Cdp

CDP — browser-harness-js skill

Custom codegen'd CDP SDK (every method from browser_protocol.json + js_protocol.json gets a typed wrapper) plus a tiny HTTP server that holds one persistent CDP Session. The browser-harness-js CLI auto-starts the server on first use and forwards JS snippets to it.

The SDK lives in the skill's sdk/ directory. In the rest of this doc, <skill-dir> refers to wherever npx skills add installed the skill (Claude Code: ~/.claude/skills/cdp; Cursor: ~/.cursor/skills/cdp; other agents vary). The CLI should be on PATH as browser-harness-js.

Setup (once, first use)

npx skills add drops the skill into your agent's skills directory but does NOT put the CLI on PATH. Before the first call, verify it's reachable and symlink it into any directory on your PATH if not:

# macOS (Apple Silicon + Homebrew)
command -v browser-harness-js >/dev/null || ln -sf <skill-dir>/sdk/browser-harness-js /opt/homebrew/bin/browser-harness-js

# macOS (Intel) / most Linux — may need sudo
command -v browser-harness-js >/dev/null || ln -sf <skill-dir>/sdk/browser-harness-js /usr/local/bin/browser-harness-js

# Linux without sudo (ensure ~/.local/bin is on PATH)
command -v browser-harness-js >/dev/null || { mkdir -p ~/.local/bin && ln -sf <skill-dir>/sdk/browser-harness-js ~/.local/bin/browser-harness-js; }

The CLI auto-installs bun on first run if it's missing (the server is Bun-native). Set BROWSER_HARNESS_SKIP_BUN_INSTALL=1 to opt out.

How to use

Just run browser-harness-js '<JS>'. The first call spawns the server in the background; subsequent calls hit the same process and so reuse the same session, the same WebSocket to Chrome, and any globals you set.

browser-harness-js 'await session.connect()'
browser-harness-js 'await session.Page.navigate({url:"https://example.com"})'
browser-harness-js '(await session.Runtime.evaluate({expression:"document.title",returnByValue:true})).result.value'

Output is the raw result content — no {ok,result} envelope.

Errors go to stderr, exit code 1. The CDP error message and JS stack are printed verbatim, e.g.:

Error: CDP -32602: invalid params
    at _call (.../session.ts:117:33)
    ...

Detect failure with if browser-harness-js '...'; then ...; else handle_error; fi or by checking $?.

Multi-line snippets via stdin (heredoc). Important: a multi-statement snippet does NOT auto-return the last expression — write return X explicitly. Single-expression snippets passed as the first argument DO auto-return.

browser-harness-js <<'EOF'
const tabs = await listPageTargets();
globalThis.tid = tabs[0].targetId;
await session.use(globalThis.tid);
return globalThis.tid;
EOF

CLI commands

Env vars: CDP_REPL_PORT (default 9876), CDP_REPL_LOG (default /tmp/browser-harness-js.log).

API surface inside snippets

These globals are pre-loaded — no imports needed:

• session — the persistent Session. Has every CDP domain mounted: session.Page, session.DOM, session.Runtime, session.Network, … 56 domains, 652 methods total.
• listPageTargets() — list real page targets via CDP's Target.getTargets (works on Chrome 144+ too), with chrome:// and devtools:// URLs filtered out. No args — uses the connected session.
• detectBrowsers() — scan OS-specific profile dirs for running Chromium-based browsers with remote debugging on. Returns [{name, profileDir, port, wsPath, wsUrl, mtimeMs}], sorted by most recently launched.
• resolveWsUrl(opts) — resolve a WS URL from {wsUrl} | {port, host?} | {profileDir}. For the no-args auto-detect flow, call session.connect() directly instead.
• CDP — the generated namespaces (CDP.Page, CDP.Runtime, …) for type-name reference.

Calling a CDP method

Every method takes a single object argument matching the CDP wire params; it resolves to the typed return value (no result envelope, no id correlation — handled for you).

// no params
await session.DOM.enable()

// required params
await session.Page.navigate({ url: 'https://example.com' })

// all-optional params (object also optional)
await session.Page.captureScreenshot()
await session.Page.captureScreenshot({ format: 'png', quality: 80 })

// returns are stripped to the typed shape
const { root } = await session.DOM.getDocument()
const { nodeId } = await session.DOM.querySelector({ nodeId: root.nodeId, selector: 'h1' })

Connecting

Default: just call `session.connect()` with no args. It auto-detects running Chromium-based browsers (Chrome, Chromium, Edge, Brave, Arc, Vivaldi, Opera, Comet, Canary) by scanning OS-specific profile dirs for a DevToolsActivePort file, ordered by most-recently-launched, and picks the first one whose WebSocket accepts. OS-agnostic — works on macOS, Linux, Windows.

await session.connect()   // auto-detect

Use detectBrowsers() first if you want to see what's available (or let the user pick) before connecting:

const found = await detectBrowsers()
// [{ name: 'Google Chrome', profileDir, port, wsPath, wsUrl, mtimeMs }, ...]

Explicit forms — use these only when auto-detect picks the wrong browser, or when you already know where to connect:

await session.connect({ profileDir: '/Users/<you>/Library/Application Support/Google/Chrome' })
await session.connect({ wsUrl: 'ws://127.0.0.1:9222/devtools/browser/<uuid>' })

Profile paths by OS — use these with { profileDir }:

• macOS: ~/Library/Application Support/<Browser> (e.g. Google/Chrome, Comet, BraveSoftware/Brave-Browser, Arc/User Data)
• Linux: ~/.config/<browser> (e.g. google-chrome, chromium, BraveSoftware/Brave-Browser)
• Windows: %LOCALAPPDATA%\<Browser>\User Data (e.g. Google\Chrome, Microsoft\Edge, BraveSoftware\Brave-Browser)

Per-candidate WS-open timeout defaults to 5s — live browsers answer with open/close within ~100ms, so 5s is already generous. The only case where 5s is too short is when Chrome is showing the Allow popup and waiting on the user to click. If you expect that, pass timeoutMs: 30000:

await session.connect({ profileDir: '/Users/<you>/Library/Application Support/Google/Chrome', timeoutMs: 30_000 })

If you see `No detected browser accepted a connection` — the browsers have DevToolsActivePort files but none are currently serving WS. Most common cause: remote-debugging is enabled but the user hasn't clicked Allow on the prompt yet. Tell them to click Allow, then retry (or bump timeoutMs).

Picking a target (tab)

After connect(), call session.use(targetId) once; subsequent page-level calls (Page/DOM/Runtime/Network/etc.) auto-route to that target's sessionId. Browser.* and Target.* calls always hit the browser endpoint.

const tabs = await listPageTargets()                     // no args; uses the connected session
const sid  = await session.use(tabs[0].targetId)
await session.Page.enable()
await session.Page.navigate({ url: 'https://example.com' })

listPageTargets() uses CDP's Target.getTargets (not /json), so it works on Chrome 144+ too. It already filters out chrome:// and devtools:// URLs. Equivalent raw call:

const { targetInfos } = await session.Target.getTargets({})
const tabs = targetInfos.filter(t => t.type === 'page' && !t.url.startsWith('chrome://') && !t.url.startsWith('devtools://'))

To switch tabs: session.use(otherTargetId). To detach: session.setActiveSession(undefined).

Events

// Subscribe (returns an unsubscribe fn)
const off = session.onEvent((method, params, sessionId) => { ... })

// Or wait for a single matching event with optional predicate + timeout
await session.Network.enable()
const ev = await session.waitFor(
  'Page.frameNavigated',
  (p) => p.frame.url.includes('example.com'),
  10_000
)

Persisting state across calls

Each snippet runs inside its own async wrapper, so its let/const declarations vanish when it returns. To carry data forward, attach to globalThis:

browser-harness-js '(await listPageTargets()).forEach((t,i)=>globalThis["tab"+i]=t.targetId)'
browser-harness-js 'await session.use(globalThis.tab0)'
browser-harness-js 'await session.Page.navigate({url:"https://example.com"})'

session itself, the active sessionId, and event subscribers are already preserved by the server — globals are only needed for ad-hoc data.

Connecting to a running Chrome (chrome://inspect flow)

When attaching to the user's already-running browser:

1. Try `await session.connect()` first (no args) — auto-detect handles every Chromium-based browser via DevToolsActivePort. If it returns, you're done. 2. If auto-detect fails with No running browser with remote debugging detected, the user needs to turn it on. Open the inspect page:

   # macOS — prefer AppleScript over `open -a` (reuses current profile, avoids the profile picker)
   osascript -e 'open location "chrome://inspect/#remote-debugging"'

   # Linux
   google-chrome 'chrome://inspect/#remote-debugging'     # or: chromium, google-chrome-stable

   # Windows (PowerShell)
   Start-Process chrome 'chrome://inspect/#remote-debugging'

Only macOS's AppleScript path avoids the profile picker; Linux/Windows may prompt the user to pick a profile first. 3. Tick "Discover network targets" in chrome://inspect, then click Allow when Chrome prompts. 4. If auto-detect picks the wrong browser (multiple running, you want a specific one): list them with await detectBrowsers(), then await session.connect({ profileDir: <the one you want> }). 5. If `session.connect()` returns `No detected browser accepted a connection`, the user has remote-debugging on but hasn't clicked Allow yet. Tell them to click it and retry, or pass timeoutMs: 30000 to wait for the click.

Working with targets (tabs)

• Filter Chrome internals. listPageTargets() already drops chrome:// and devtools:// URLs. If you call Target.getTargets() directly, filter manually.
• CDP target order ≠ visible tab-strip order. When the user says "the first tab I can see", use a screenshot or page title to identify it — Target.activateTarget only switches to a known targetId.

Looking up a method

The full typed surface is in <skill-dir>/sdk/generated.ts (~655 KB, only loaded if you read it). Each method has its CDP description as a JSDoc comment plus typed *Params / *Return interfaces in per-domain namespaces.

grep -n "navigate" <skill-dir>/sdk/generated.ts | head

Regenerating the SDK

When the upstream protocol JSONs change, replace sdk/browser_protocol.json and/or sdk/js_protocol.json and re-run:

cd <skill-dir>/sdk && bun gen.ts
browser-harness-js --restart   # pick up the new bindings

Files

All paths are relative to <skill-dir> (the install path — see top of this doc).

• /usr/local/bin/browser-harness-js → <skill-dir>/sdk/browser-harness-js (the CLI)
• sdk/repl.ts — HTTP server (Bun.serve on 127.0.0.1:9876)
• sdk/session.ts — Session class (transport, connect, target routing, events)
• sdk/generated.ts — codegen output: every CDP method as a typed wrapper
• sdk/gen.ts — codegen script
• sdk/{browser,js}_protocol.json — upstream protocol (vendored)

Connection & Tab Visibility

Just call session.connect()

No args required. It scans OS-specific profile dirs for every running Chromium-based browser (Chrome, Chromium, Edge, Brave, Arc, Vivaldi, Opera, Comet, Canary), picks the most-recently-launched one whose WebSocket accepts, and attaches. Dead ports and permission-denied (403) candidates fall through in <100ms each, so the loop is fast.

await session.connect()

Inspect what's available (e.g. to let the user choose) with detectBrowsers():

const browsers = await detectBrowsers()
// [{ name: 'Google Chrome', profileDir, port, wsPath, wsUrl, mtimeMs }, ...]

Explicit forms (override auto-detect)

Use only when auto-detect picks the wrong browser or you already know the destination.

await session.connect({ profileDir: '/Users/<you>/Library/Application Support/Google/Chrome' })
await session.connect({ wsUrl: 'ws://127.0.0.1:9222/devtools/browser/<uuid>' })

Timeouts and the Allow popup

Per-candidate WS-open timeout defaults to 5s. A live browser either opens or closes the connection within ~100ms, so 5s is always enough — unless the user has to click Allow on Chrome's remote-debugging popup. In that case, pass timeoutMs: 30000 to give them time:

await session.connect({ profileDir, timeoutMs: 30_000 })

If session.connect() reports No detected browser accepted a connection, it means every browser with DevToolsActivePort answered 403 or closed without opening — most likely the user hasn't clicked Allow yet. Ask them to, then retry.

The omnibox popup problem

When Chrome opens fresh, the only CDP type: "page" targets may be chrome://inspect and chrome://omnibox-popup.top-chrome/ (a 1px invisible viewport). If you attach to the omnibox popup, every subsequent action happens on a tab the user cannot see.

listPageTargets() already filters chrome:// and devtools:// URLs. If you call Target.getTargets directly, filter these manually:

const { targetInfos } = await session.Target.getTargets({})
const realTabs = targetInfos.filter(t =>
  t.type === 'page' &&
  !t.url.startsWith('chrome://') &&
  !t.url.startsWith('devtools://')
)

If no real pages exist yet, create one instead of attaching to nothing:

const tabs = await listPageTargets()
let targetId = tabs[0]?.targetId
if (!targetId) {
  ({ targetId } = await session.Target.createTarget({ url: 'about:blank' }))
}
await session.use(targetId)

Startup sequence

1. await session.connect() — auto-detect the running browser. 2. const tabs = await listPageTargets() — see what real pages exist. 3. await session.use(tabs[0].targetId) — route Page/DOM/Runtime/Network calls to that target. 4. await session.Target.activateTarget({ targetId: tabs[0].targetId }) — bring the tab visually to front. 5. Enable the domains you need: await session.Page.enable(), await session.Network.enable({}), etc.

CDP target order ≠ visible tab-strip order

When the user says "the first tab I can see", do NOT trust the order of Target.getTargets. Use:

• A screenshot (session.Page.captureScreenshot()) to identify visually.
• Page title / URL heuristics.
• Or platform UI automation (macOS: AppleScript; Linux: xdotool/wmctrl).

Target.activateTarget only switches to a targetId you already know — it cannot resolve "leftmost tab".

Bringing Chrome to front

# macOS — prefer AppleScript over `open -a` (reuses current profile, avoids the profile picker)
osascript -e 'tell application "Google Chrome" to activate'

# Linux (X11) — use wmctrl or xdotool
wmctrl -a 'Google Chrome'
xdotool search --name 'Google Chrome' windowactivate

# Windows (PowerShell)
powershell -NoProfile -Command "(New-Object -ComObject WScript.Shell).AppActivate('Google Chrome')"

Cookies

Use Network.* for cookies scoped to the attached page/context; use Storage.getCookies / Storage.setCookies for every cookie in the browser.

Read

await session.Network.enable({})

// All cookies visible to the attached page (current origin + its frames)
const { cookies } = await session.Network.getCookies({})

// Cookies for specific URLs
const { cookies: github } = await session.Network.getCookies({
  urls: ['https://github.com/'],
})

// Every cookie across the whole browser (requires Storage domain)
const { cookies: all } = await session.Storage.getCookies({})

Shape: { name, value, domain, path, expires, size, httpOnly, secure, session, sameSite?, sourceScheme?, priority? }.

Write

// Single cookie on the attached page
await session.Network.setCookie({
  name: 'session',
  value: 'abc123',
  domain: '.example.com',
  path: '/',
  secure: true,
  httpOnly: true,
  sameSite: 'Lax',
  expires: Date.now() / 1000 + 86400,   // seconds since epoch
})

// Bulk import (e.g. to preload an auth session)
await session.Network.setCookies({
  cookies: [
    { name: 'a', value: '1', domain: '.example.com', path: '/' },
    { name: 'b', value: '2', domain: '.example.com', path: '/' },
  ],
})

Delete / clear

await session.Network.deleteCookies({ name: 'session', domain: '.example.com' })
await session.Network.clearBrowserCookies()   // nukes everything in the default context

Gotchas

• Network.setCookie silently fails with no error if domain doesn't match any origin in the current profile — you'll get { success: true } and the cookie just won't be there. Verify with getCookies after.
• expires is seconds (float), not milliseconds. A common mistake.
• Session cookies: pass no expires and Chrome treats them as session-scoped. Setting expires: 0 also works.
• sameSite values are 'Strict' | 'Lax' | 'None'. For 'None', Chrome also requires secure: true.
• Clearing cookies does NOT clear localStorage/IndexedDB. For a full logout, also call Storage.clearDataForOrigin({ origin, storageTypes: 'all' }).

Cross-Origin Iframes (OOPIFs)

Cross-origin iframes (stripe.com checkout, recaptcha, Salesforce Lightning, Azure blades) run in out-of-process iframes (OOPIFs) with their own CDP target. You cannot reach them via contentDocument from the parent.

First try: coordinate clicks

Compositor-level input passes through OOPIFs transparently. If the thing you want is a button you can see in a screenshot, try this first — it's simpler, undetectable, and doesn't need attaching to anything:

// Click a "Pay" button inside a Stripe iframe by page coordinates
await session.Input.dispatchMouseEvent({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 })
await session.Input.dispatchMouseEvent({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 })

Coordinate-based typing also works if you click first, then Input.insertText/Input.dispatchKeyEvent.

When you need DOM inside the OOPIF

Find the iframe target and route Runtime/DOM calls to it:

const { targetInfos } = await session.Target.getTargets({})
const iframe = targetInfos.find(t => t.type === 'iframe' && t.url.includes('stripe.com'))

// Route subsequent calls to the iframe target
await session.use(iframe.targetId)

await session.Runtime.enable()
const { result } = await session.Runtime.evaluate({
  expression: 'document.querySelector("[name=cardnumber]").value',
  returnByValue: true,
})

// Switch back to the parent page when done
await session.use(parentTargetId)

session.use(iframe.targetId) auto-attaches if not already attached, and routes Page/DOM/Runtime/Network to it. Target.* and Browser.* always hit the browser endpoint regardless of use.

Which target is which?

Target.getTargets returns all OOPIFs in the page, flat. If multiple iframes share an origin (e.g. multiple Stripe Elements), you need more than URL to disambiguate:

• Filter by URL path (cardNumber vs cardExpiry vs cvc in Stripe).
• Enumerate in DOM order from the parent: find all <iframe> elements, map their src to target URLs.
• Inspect title via Target.getTargetInfo({ targetId }).

Listening to events from an OOPIF

After session.use(iframe.targetId), events for that target arrive via the same session.onEvent / session.waitFor:

await session.use(iframe.targetId)
await session.Network.enable({})
const ev = await session.waitFor(
  'Network.responseReceived',
  (p) => p.response.url.includes('/confirm_payment'),
  10_000
)

Traps

• An OOPIF is not always present until interaction. Stripe's card iframe is lazy-mounted after you focus the outer input. Screenshot + coordinate-click the outer input first, then re-query Target.getTargets.
• OOPIF targets disappear when the parent navigates. A cached iframe.targetId from before a navigation is dead.
• CSP / sandbox may block `Runtime.evaluate` side effects even when you've attached. Read-only calls usually work; writes may silently no-op.
• Don't `use(iframe.targetId)` and forget to switch back. Your next Page.navigate goes to the iframe instead of the main frame. Always pair with a session.use(parentTargetId).

Dialogs

alert, confirm, prompt, beforeunload freeze the JS thread. Two approaches depending on timing.

Reactive: dismiss via CDP (preferred)

Works even when JS is frozen. Handles all four dialog types.

await session.Page.enable()

// Dismiss / accept
await session.Page.handleJavaScriptDialog({ accept: true })               // "OK"
await session.Page.handleJavaScriptDialog({ accept: false })              // "Cancel"
await session.Page.handleJavaScriptDialog({ accept: true, promptText: 'hi' })  // for prompt()

// Wait for a dialog to open (and read its text)
const ev = await session.waitFor('Page.javascriptDialogOpening', undefined, 10_000)
console.log(ev.type, ev.message)  // "alert"|"confirm"|"prompt"|"beforeunload"

Undetectable by antibot — no JS runs in the page.

Subscribe to every dialog while a flow runs:

await session.Page.enable()
const off = session.onEvent(async (method, params) => {
  if (method === 'Page.javascriptDialogOpening') {
    await session.Page.handleJavaScriptDialog({ accept: true })
  }
})
// ...do actions that may trigger dialogs...
off()

Proactive: stub via JS

Prevents dialogs from ever appearing. Good when you expect many alert()/confirm() calls.

await session.Runtime.evaluate({ expression: `
  window.__dialogs__ = [];
  window.alert = m => window.__dialogs__.push(String(m));
  window.confirm = m => { window.__dialogs__.push(String(m)); return true; };
  window.prompt = (m, d) => { window.__dialogs__.push(String(m)); return d || ''; };
` })
// ...actions...
const { result } = await session.Runtime.evaluate({
  expression: 'window.__dialogs__ || []',
  returnByValue: true,
})

Tradeoffs:

• Stubs are lost on page navigation — re-inject after every navigate.
• confirm() always returns true.
• Detectable by antibot (window.alert.toString() reveals non-native code).
• Does not handle beforeunload.

beforeunload specifically

Fires when navigating away from a page with unsaved changes (forms, editors). The page freezes until the user clicks Leave/Stay.

// Option A: dismiss after navigating (CDP, safe, undetectable)
await session.Page.navigate({ url: 'https://new-url.com' })
try {
  await session.Page.handleJavaScriptDialog({ accept: true })  // "Leave"
} catch { /* no dialog — normal */ }

// Option B: prevent before navigating (JS, detectable)
await session.Runtime.evaluate({ expression: 'window.onbeforeunload = null' })
await session.Page.navigate({ url: 'https://new-url.com' })

Downloads

Two modes: let Chrome write the file to a directory you control, or intercept the download response in CDP and save it yourself.

Route downloads to a directory you own

// Cross-platform temp dir: /tmp on Linux, /var/folders/… on macOS, %TEMP% on Windows
const { tmpdir } = await import('node:os')
const downloadDir = `${tmpdir()}/cdp-downloads`
await Bun.write(`${downloadDir}/.keep`, '')  // ensure dir exists

await session.Browser.setDownloadBehavior({
  behavior: 'allow',
  downloadPath: downloadDir,
  eventsEnabled: true,   // emit Browser.downloadWillBegin / downloadProgress
})

Now any download — whether triggered by a link (<a download>), a window.location to a binary, or a form POST that returns Content-Disposition: attachment — saves to that directory.

Signal that a download actually started

const ev = await session.waitFor(
  'Browser.downloadWillBegin',
  (p) => p.suggestedFilename.endsWith('.pdf'),
  10_000
)
console.log(ev.guid, ev.suggestedFilename, ev.url)

Signal that it finished

const done = await session.waitFor(
  'Browser.downloadProgress',
  (p) => p.state === 'completed',
  60_000
)
console.log(done.receivedBytes, done.totalBytes)

Browser.downloadProgress.state is one of 'inProgress' | 'completed' | 'canceled'.

Skip the browser entirely for plain HTTP downloads

If the download URL is a plain HTTP GET with no auth/cookie state the browser added, fetch directly from the Bun snippet:

const { tmpdir } = await import('node:os')
const res = await fetch('https://example.com/report.pdf')
await Bun.write(`${tmpdir()}/report.pdf`, await res.arrayBuffer())

This is often 10× faster than driving the browser. But it loses cookie-based auth — for logged-in downloads, either: 1. Use the browser path (Browser.setDownloadBehavior), or 2. Copy cookies out first (Network.getCookies) and include them in the fetch.

When the only trigger is a click

If the site exposes only a "Download" button and no obvious URL:

// Pre-arm Browser.setDownloadBehavior, then click
await session.Input.dispatchMouseEvent({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 })
await session.Input.dispatchMouseEvent({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 })
const ev = await session.waitFor('Browser.downloadWillBegin', undefined, 10_000)

Traps

• `Browser.setDownloadBehavior` is browser-scoped, not page-scoped. Set it once per browser session.
• `downloadPath` must exist. Chrome silently drops the file otherwise — always mkdir -p first.
• Files arrive with the suggested filename, not a name you choose. Rename after state === 'completed' if you need a specific name.
• `beforeunload` on the triggering page can block the download. Some sites open a confirm dialog before navigating to the PDF endpoint — handle the dialog first (see dialogs.md).
• If the "download" is actually just inline navigation (PDF viewer opens in-page), there's no downloadWillBegin — you'll need Page.printToPDF or direct fetch instead.

Drag and Drop

Three kinds hide behind "drag and drop" — each wants a different CDP call.

Kind 1: HTML5 DnD (dragstart / drop events)

React DnD, pragmatic-drag-and-drop, native <div draggable> — all listen to DOM DragEvent. CDP's Input.dispatchMouseEvent with mousePressed/moved/released does not fire these, because the browser synthesizes DragEvents from a native OS drag that CDP doesn't trigger. Use Input.dispatchDragEvent instead:

// Chrome needs to be told we're about to handle drags via CDP
await session.Input.setInterceptDrags({ enabled: true })

// Press at the source
await session.Input.dispatchMouseEvent({ type: 'mousePressed', x: srcX, y: srcY, button: 'left', clickCount: 1 })

// Wait for CDP to deliver the initial drag intent (via Input.dragIntercepted)
const di = await session.waitFor('Input.dragIntercepted', undefined, 2_000)

// Simulate the move + drop via dispatchDragEvent
await session.Input.dispatchDragEvent({ type: 'dragEnter', x: dstX, y: dstY, data: di.data })
await session.Input.dispatchDragEvent({ type: 'dragOver',  x: dstX, y: dstY, data: di.data })
await session.Input.dispatchDragEvent({ type: 'drop',      x: dstX, y: dstY, data: di.data })

await session.Input.dispatchMouseEvent({ type: 'mouseReleased', x: dstX, y: dstY, button: 'left', clickCount: 1 })
await session.Input.setInterceptDrags({ enabled: false })

This covers most real-world DnD on React/Vue apps (Trello cards, Notion blocks, Linear tickets, Figma layers).

Kind 2: Pointer-based drag (canvas, SVG, custom handlers)

Games, map panning, Figma/Excalidraw canvases, range sliders — these listen for mousedown / mousemove / mouseup (or pointer events) and do their own coordinate math. For these, a plain mouse-event sequence is enough:

await session.Input.dispatchMouseEvent({ type: 'mousePressed', x: x1, y: y1, button: 'left', clickCount: 1 })
// Intermediate moves matter — many sites track velocity / only trigger on movement delta
for (let i = 1; i <= 10; i++) {
  const x = x1 + (x2 - x1) * (i / 10)
  const y = y1 + (y2 - y1) * (i / 10)
  await session.Input.dispatchMouseEvent({ type: 'mouseMoved', x, y, button: 'left' })
}
await session.Input.dispatchMouseEvent({ type: 'mouseReleased', x: x2, y: y2, button: 'left', clickCount: 1 })

Add intermediate mouseMoved events — sites tracking velocity won't fire on a single jump.

Kind 3: "Drag a file onto this zone" = actually upload

Most drop zones that accept files have a hidden <input type="file"> under them. Use DOM.setFileInputFiles — see uploads.md. Don't fight the DnD path if an input exists.

Traps

• Don't use `Input.dispatchMouseEvent` alone for HTML5 DnD — no dragstart fires. The site just sees a click that went nowhere. Use setInterceptDrags + dispatchDragEvent.
• Don't use `Input.dispatchDragEvent` without `setInterceptDrags({ enabled: true })` — Chrome routes the drag to the native OS otherwise.
• Snap / animation: after drop, re-screenshot after ~300ms. Some libraries animate the card into place and a too-fast follow-up action lands on the wrong coordinates.
• Pointer Events vs Mouse Events: if mousedown doesn't work, try dispatchMouseEvent with pointerType: 'mouse' and also include the same sequence as dispatchPointerEvent (some new SPAs only listen to pointer events).

Dropdowns

The right approach depends on what kind of dropdown the site actually rendered.

Native <select>

Don't click options — set the value directly and fire change. Keyboard/mouse on a native select opens an OS menu CDP can't close.

await session.Runtime.evaluate({ expression: `
  (() => {
    const s = document.querySelector('select#country')
    s.value = 'DE'
    s.dispatchEvent(new Event('change', { bubbles: true }))
  })()
`})

Verify: await session.Runtime.evaluate({ expression: 'document.querySelector("select#country").value', returnByValue: true }).

Custom overlay (div-based menu under a trigger)

1. Click the trigger with Input.dispatchMouseEvent. 2. Re-measure — options appear late, sometimes inside a portal attached to <body>. 3. Click the option by visible text.

// Click the trigger
await session.Input.dispatchMouseEvent({ type: 'mousePressed', x: triggerX, y: triggerY, button: 'left', clickCount: 1 })
await session.Input.dispatchMouseEvent({ type: 'mouseReleased', x: triggerX, y: triggerY, button: 'left', clickCount: 1 })

// Wait one frame, then find the option by text and coordinate-click it
const { result } = await session.Runtime.evaluate({
  returnByValue: true,
  expression: `
    (() => {
      const t = [...document.querySelectorAll('[role="option"], li, .menu-item')]
        .find(el => el.textContent.trim() === 'Germany')
      if (!t) return null
      const r = t.getBoundingClientRect()
      return { x: r.x + r.width/2, y: r.y + r.height/2 }
    })()
  `,
})
if (result.value) {
  const { x, y } = result.value
  await session.Input.dispatchMouseEvent({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 })
  await session.Input.dispatchMouseEvent({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 })
}

Searchable combobox (React / Downshift / Radix / MUI Autocomplete)

Most comboboxes commit on the keyboard, not the click:

1. Click the input to focus + open. 2. Input.insertText the search string. 3. Wait for options to render. 4. Input.dispatchKeyEvent ArrowDown → Enter to commit.

await session.Input.dispatchKeyEvent({ type: 'keyDown', key: 'ArrowDown', code: 'ArrowDown', windowsVirtualKeyCode: 40 })
await session.Input.dispatchKeyEvent({ type: 'keyUp',   key: 'ArrowDown', code: 'ArrowDown', windowsVirtualKeyCode: 40 })
await session.Input.dispatchKeyEvent({ type: 'keyDown', key: 'Enter',     code: 'Enter',     windowsVirtualKeyCode: 13, text: '\r' })
await session.Input.dispatchKeyEvent({ type: 'keyUp',   key: 'Enter',     code: 'Enter',     windowsVirtualKeyCode: 13 })

Some libraries (notably Radix) require Escape to close without committing. Clicking outside may keep stale input.

Virtualized menus

Long option lists (react-window, TanStack Virtual) only render the visible slice. If your option isn't in the DOM, scroll the menu container with a mouseWheel at its coordinates (see scrolling.md) until it mounts, then coordinate-click.

Traps

• Always re-measure after opening — the trigger's on-screen position may shift when the menu appears (dropdowns that push content).
• Portals: the option DOM may not be a descendant of the trigger. Search document.querySelectorAll, not trigger.querySelectorAll.
• MUI Autocomplete: blur commits the text value, not the selected option. Always use Enter.
• CSS pointer-events: none on the option means the click passes through — check for an inner <span> or the option container a level up.

Iframes (same-origin)

Same-origin iframes are just part of the parent DOM — you can walk into them via contentDocument. For cross-origin (OOPIFs), see cross-origin-iframes.md.

Reading / writing through contentDocument

await session.Runtime.evaluate({
  returnByValue: true,
  expression: `
    (() => {
      const doc = document.querySelector('iframe#inner').contentDocument
      return doc.querySelector('h1').textContent
    })()
  `,
})

• Throws DOMException: Blocked a frame with origin … if the frame is actually cross-origin. That's your signal to switch to OOPIF routing.
• contentWindow.postMessage works from the parent if you need to send data in.

Coordinate clicks pass through iframes

The compositor-level input path (Input.dispatchMouseEvent) doesn't care about frame boundaries. If you can see a button in a screenshot, you can click its page coordinates regardless of how many iframes it's nested in:

await session.Input.dispatchMouseEvent({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 })
await session.Input.dispatchMouseEvent({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 })

This is usually the lowest-friction approach. Only drop to contentDocument / OOPIF attach when you need to read DOM or dispatch DOM events on elements that are hard to target by coordinate.

Frame-local vs page coordinates

getBoundingClientRect() inside an iframe returns iframe-local coordinates. To coordinate-click, you need page coordinates:

await session.Runtime.evaluate({
  returnByValue: true,
  expression: `
    (() => {
      const iframe = document.querySelector('iframe#inner')
      const inner = iframe.contentDocument.querySelector('.target')
      const iRect = iframe.getBoundingClientRect()
      const tRect = inner.getBoundingClientRect()
      return { x: iRect.x + tRect.x + tRect.width/2, y: iRect.y + tRect.y + tRect.height/2 }
    })()
  `,
})

Nested iframes

Recurse through contentDocument:

let doc = document
for (const sel of ['iframe#outer', 'iframe#middle', 'iframe#inner']) {
  doc = doc.querySelector(sel).contentDocument
  if (!doc) throw new Error('cross-origin boundary')
}
return doc.querySelector('h1').textContent

Traps

• A frame that was same-origin can become cross-origin after navigation inside it (e.g. OAuth redirect). Re-check with contentDocument truthiness.
• iframe.contentDocument === null right after insertion — wait for load on the iframe before reading.
• CSP frame-ancestors/sandbox="allow-same-origin" can block contentDocument access even when origins match.

Network Requests

Use Network.* events when the DOM doesn't tell you whether a request happened, what it sent, or what came back. Use Fetch.* when you need to intercept, modify, or mock.

Watching requests

await session.Network.enable({})

// React to every request
const off = session.onEvent((method, params) => {
  if (method === 'Network.requestWillBeSent') {
    console.log(params.request.method, params.request.url)
  }
  if (method === 'Network.responseReceived') {
    console.log(params.response.status, params.response.url)
  }
})

// ...do the action that should trigger the request...
off()

Wait for a specific request

session.waitFor returns just the first matching event's params:

await session.Network.enable({})
// (Trigger the action before awaiting, or trigger concurrently.)
const ev = await session.waitFor(
  'Network.responseReceived',
  (p) => p.response.url.includes('/api/submit') && p.response.status === 200,
  10_000
)
console.log(ev.response.status, ev.requestId)

Read a response body

Network.getResponseBody needs the requestId — grab it from the matching event:

const ev = await session.waitFor(
  'Network.responseReceived',
  (p) => p.response.url.endsWith('/me'),
  10_000
)
const { body, base64Encoded } = await session.Network.getResponseBody({ requestId: ev.requestId })
const text = base64Encoded ? Buffer.from(body, 'base64').toString('utf-8') : body

Bodies aren't always available — if the response was a redirect, was cached, or Chrome discarded it, getResponseBody throws. Read it immediately after Network.loadingFinished.

Capture request bodies

Network.requestWillBeSent gives you params.request.postData (for small bodies); use Network.getRequestPostData({ requestId }) for large ones.

Intercept / modify / mock (Fetch domain)

When you need to change what's sent or returned:

await session.Fetch.enable({
  patterns: [{ urlPattern: '*/api/flag*', requestStage: 'Response' }],
})

session.onEvent(async (method, params) => {
  if (method === 'Fetch.requestPaused') {
    // Mock the response
    await session.Fetch.fulfillRequest({
      requestId: params.requestId,
      responseCode: 200,
      responseHeaders: [{ name: 'content-type', value: 'application/json' }],
      body: Buffer.from(JSON.stringify({ enabled: true })).toString('base64'),
    })
  }
})

Alternatives per request:

• session.Fetch.continueRequest({ requestId }) — pass through untouched.
• session.Fetch.continueRequest({ requestId, url, method, postData, headers }) — modify in flight.
• session.Fetch.failRequest({ requestId, errorReason: 'Failed' }) — simulate an error.

Fetch.enable disables the HTTP cache for matching URLs. Disable Fetch as soon as you're done.

Cheap SPA "did the action succeed?" signal

Many SPAs mutate state without a visible DOM change. A request-based wait is the cleanest signal:

await session.Network.enable({})
// click Save
await session.Input.dispatchMouseEvent({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 })
await session.Input.dispatchMouseEvent({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 })
await session.waitFor(
  'Network.responseReceived',
  (p) => p.response.url.includes('/save') && p.response.status === 200,
  10_000
)

Traps

• `Network.enable` must be called before the request fires. If you enable after the click, you'll miss the event. Enable once at session start and leave it.
• `Network.enable` is per-target. After session.use(iframe.targetId), call Network.enable({}) again inside that target.
• Request IDs are unique per target, not global. Don't pass an iframe requestId to a main-frame getResponseBody call.
• `waitFor` will reject on timeout, not return null. Wrap in try/catch if you don't want the whole snippet to fail when the request doesn't happen.

Print as PDF

Two completely different things the user may mean by "print to PDF":

1. Render the current page to a PDF (what you usually want)

const { data } = await session.Page.printToPDF({
  printBackground: true,
  paperWidth: 8.5,           // inches
  paperHeight: 11,
  marginTop: 0.4,
  marginBottom: 0.4,
  marginLeft: 0.4,
  marginRight: 0.4,
  preferCSSPageSize: true,   // respect @page in the site's CSS if set
})
// Cross-platform temp dir: /tmp on Linux, /var/folders/… on macOS, %TEMP% on Windows
const { tmpdir } = await import('node:os')
await Bun.write(`${tmpdir()}/page.pdf`, Buffer.from(data, 'base64'))

Works without any visible print dialog — Chrome renders the PDF server-side in the process. Undetectable by the page.

Options worth knowing:

• landscape: true — flip orientation
• displayHeaderFooter: true + headerTemplate / footerTemplate — printed HTML (mustache-style variables: {{pageNumber}}, {{totalPages}}, {{title}}, {{url}})
• scale: 0.8 — shrink to fit
• pageRanges: '1-3,7' — subset of pages
• transferMode: 'ReturnAsStream' — for very large PDFs, returns a stream handle instead of a giant base64 blob

2. The site has a "Print" button that opens a real print dialog

Some sites call window.print() and rely on the user picking "Save as PDF" in the OS dialog. CDP cannot interact with the OS print dialog.

Two ways around it:

A. Intercept window.print before the click

await session.Runtime.evaluate({ expression: `
  window.print = () => {
    window.dispatchEvent(new Event('beforeprint'))
    window.__printed__ = true
  }
`})
// Click the site's Print button — the call is now a no-op
// Then generate the PDF yourself:

Follow with session.Page.printToPDF(...) from option 1.

Detectable by window.print.toString() — fine for most sites, risky for antibot.

B. Use the underlying URL

Often the Print button just navigates to a print-friendly URL like /invoice/123?print=1. Find it with DevTools, then:

await session.Page.navigate({ url: 'https://example.com/invoice/123?print=1' })
// ...wait for load...
await session.Page.printToPDF({ printBackground: true })

Traps

• `printBackground: false` (default) skips background colors and images. Invoices, receipts, and anything design-heavy look empty without it — turn it on unless you specifically want the "clean print" look.
• `Page.printToPDF` uses its own print-media CSS (@media print). If the page hides elements with display: none under @media print, they'll be missing from your PDF. Override with Emulation.setEmulatedMedia({ media: 'screen' }) first.
• Very large pages (long reports, data tables) can hit Chrome's internal PDF size limits and fail silently. Split by pageRanges or reduce scale.
• Fonts may substitute. Chrome uses system fonts for PDF rendering — if the site uses a webfont that isn't loaded at capture time, your PDF gets the fallback.

Screenshots

session.Page.captureScreenshot is your default discovery and verification tool.

Core calls

// Viewport only (default) — fastest, matches what the user sees
const { data } = await session.Page.captureScreenshot({ format: 'png' })
// Cross-platform temp dir: /tmp on Linux, /var/folders/… on macOS, %TEMP% on Windows
const { tmpdir } = await import('node:os')
await Bun.write(`${tmpdir()}/shot.png`, Buffer.from(data, 'base64'))

// Full page — stitched beyond the viewport
await session.Page.captureScreenshot({ format: 'png', captureBeyondViewport: true })

// JPEG is ~5× smaller — good when you only need to eyeball
await session.Page.captureScreenshot({ format: 'jpeg', quality: 70 })

// A specific region (page coordinates)
await session.Page.captureScreenshot({
  format: 'png',
  clip: { x: 0, y: 0, width: 800, height: 600, scale: 1 },
})

When to screenshot

• Discovery: after navigating, before inventing a selector. A screenshot answers "is the thing I need visible and where?" faster than a DOM walk.
• Verification: after every meaningful action. The DOM can lie about state; pixels cannot.
• Debugging coordinate clicks: shot → read → Input.dispatchMouseEvent at (x, y) → shot again.

Element screenshots via DOM.getBoxModel

When you want just one element:

await session.DOM.enable()
const { root } = await session.DOM.getDocument({})
const { nodeId } = await session.DOM.querySelector({ nodeId: root.nodeId, selector: '.card' })
const { model } = await session.DOM.getBoxModel({ nodeId })
const [x, y] = model.border        // top-left
const width = model.width
const height = model.height
await session.Page.captureScreenshot({ clip: { x, y, width, height, scale: 1 } })

model.border is [x1,y1, x2,y1, x2,y2, x1,y2] — 8 numbers, 4 corners. Take the first two for origin.

Traps

• captureBeyondViewport: true re-layouts the page (fires resize). Don't use it in the middle of a user-driven flow — use viewport shots.
• On high-DPI, captureScreenshot returns the device-pixel image. If you plan to coordinate-click on values read from the image, remember the CSS-pixel / device-pixel scale (see viewport.md).
• Pages with fixed/sticky headers over captureBeyondViewport can produce duplicated headers down the stitched image.

Scrolling

Three levels, in order of how often they work:

1. Wheel event at a point — Input.dispatchMouseEvent { type: 'mouseWheel' }. Scrolls whichever element is under (x, y) and consumes wheel. 2. `scrollIntoView` on the element — Runtime.evaluate with a short JS snippet. Works for anything in the DOM you can querySelector. 3. Set `scrollTop` directly on the container — bypasses animations and snap.

Wheel (coordinate-based, closest to a real user)

// scroll down 300px at the center of the viewport
await session.Input.dispatchMouseEvent({
  type: 'mouseWheel',
  x: 600, y: 400,
  deltaX: 0, deltaY: 300,
})

// scroll up
await session.Input.dispatchMouseEvent({ type: 'mouseWheel', x: 600, y: 400, deltaX: 0, deltaY: -300 })

• Pick (x, y) over the element you want to scroll. If you wheel over a sticky header or a pinned sidebar, nothing happens.
• Virtualized lists (react-window, TanStack Virtual): wheeling the container is the only reliable scroll; scrollIntoView on a child row often no-ops because the row isn't yet mounted.

scrollIntoView (DOM-based)

await session.Runtime.evaluate({ expression: `
  document.querySelector('[data-row-id="42"]')?.scrollIntoView({ block: 'center', behavior: 'instant' })
`})

• behavior: 'instant' avoids the animation round-trip and your next action landing on old coordinates.
• Fails silently if the selector doesn't match — always verify with a screenshot.

scrollTop / scrollLeft (blunt but reliable)

await session.Runtime.evaluate({ expression: `
  const el = document.querySelector('.list-scroll-container')
  if (el) el.scrollTop = el.scrollHeight
`})

Use when:

• The container has custom overflow: auto and wheel events aren't reaching it.
• You need to jump to absolute offsets (top, bottom, "row N × rowHeight").

Which container is consuming wheel events?

Sites with multiple nested scrollers (modals inside pages, lists inside cards) make "scroll the page" ambiguous. Find the actual scroller:

await session.Runtime.evaluate({
  returnByValue: true,
  expression: `
    (() => {
      const out = []
      document.querySelectorAll('*').forEach(el => {
        const s = getComputedStyle(el)
        if ((s.overflowY === 'auto' || s.overflowY === 'scroll') && el.scrollHeight > el.clientHeight)
          out.push({ tag: el.tagName, cls: el.className, h: el.clientHeight, scroll: el.scrollHeight })
      })
      return out
    })()
  `,
})

Traps

• `scroll-behavior: smooth` in CSS makes everything animate — your Input.dispatchMouseEvent fires immediately, but the next coordinate click lands before the scroll finishes. Either set behavior: 'instant' on scrollIntoView, or await new Promise(r => setTimeout(r, 400)) after wheeling.
• Re-read element rects after opening a dropdown / modal before coordinate-clicking. Layout shifts invalidate cached coords.
• Wheel on a trackpad fires dozens of small delta events. If a site's infinite-scroll sentinel requires momentum, a single deltaY: 300 call may not trigger it — send several smaller wheels in a loop.

Shadow DOM

Closed shadow roots are rare on the sites you're likely to automate. Most web components use open shadow roots — you can walk them from JS or use CDP's pierceShadow flag.

First try: coordinate clicks

Compositor-level clicks don't care about shadow roots. If you can see it in a screenshot, Input.dispatchMouseEvent can click it. This avoids all shadow-piercing entirely — reach for it first for buttons, links, and form triggers.

CDP path: pierceShadow

DOM.querySelector / DOM.querySelectorAll accept pierceShadow: true — one call crosses every open shadow boundary:

await session.DOM.enable()
const { root } = await session.DOM.getDocument({})
const { nodeId } = await session.DOM.querySelector({
  nodeId: root.nodeId,
  selector: 'my-button >>> .inner-label',
  // Chrome has also historically accepted `pierceShadow: true`; on recent
  // Chrome the `>>>` combinator in the selector pierces shadow roots directly.
})

JS path: recursive walk through shadowRoot

More portable, works in any Chrome:

await session.Runtime.evaluate({
  returnByValue: true,
  expression: `
    (() => {
      function* walk(root) {
        const stack = [root]
        while (stack.length) {
          const node = stack.pop()
          if (!node) continue
          yield node
          if (node.shadowRoot) stack.push(...node.shadowRoot.children)
          stack.push(...(node.children || []))
        }
      }
      for (const el of walk(document.body)) {
        if (el.matches?.('.target-class')) {
          const r = el.getBoundingClientRect()
          return { x: r.x + r.width/2, y: r.y + r.height/2 }
        }
      }
      return null
    })()
  `,
})

Use the returned {x, y} for Input.dispatchMouseEvent.

Setting a value inside a shadow-DOM input

Reaching the input is the hard part — setting the value is the same as any input:

await session.Runtime.evaluate({ expression: `
  (() => {
    const host = document.querySelector('my-form')
    const input = host.shadowRoot.querySelector('input[name=email]')
    input.focus()
    input.value = 'hi@example.com'
    input.dispatchEvent(new Event('input', { bubbles: true, composed: true }))
  })()
`})

composed: true on the event lets it cross shadow boundaries — many web components listen on the host, not the internal input.

Traps

• Closed shadow roots ({ mode: 'closed' }) cannot be walked from JS. Fall back to coordinate clicks + Input.insertText. Closed roots are rare — usually only password managers and some Google components.
• `slot` content lives in the light DOM, not the shadow root. If your element has <slot>…</slot>, the children you're looking for are host.children, not host.shadowRoot.children.
• `::part()` / `::slotted()` CSS affects styling but has no DOM-query equivalent — you still traverse shadowRoot.
• Element screenshots via DOM.getBoxModel work even for shadow-DOM elements once you have the nodeId.

Tabs

Use CDP for control (attach, activate known targets, inspect). Use UI automation for visible order.

Pure CDP

// List page targets (filtered; chrome:// / devtools:// dropped)
const tabs = await listPageTargets()

// Create a new tab and route subsequent calls to it
const { targetId } = await session.Target.createTarget({ url: 'https://example.com' })
await session.use(targetId)

// Switch: route calls to another existing tab
await session.use(otherTargetId)

// Show this tab visibly in Chrome (different from `session.use` — which is CDP routing only)
await session.Target.activateTarget({ targetId })

// Close a tab
await session.Target.closeTarget({ targetId })

// What tab is session.use currently pointing at?
const { targetInfo } = await session.Target.getTargetInfo({ targetId })

`session.use` is CDP-side routing; `Target.activateTarget` is Chrome-side focus. They are independent. If the user expects Chrome to visibly change, call activateTarget too.

Two things Target.createTarget quietly gets wrong

1. Race: `{ url }` in `createTarget` can resolve before navigation starts. If you then poll document.readyState, you'll see 'complete' for about:blank and move on. Safer:

   const { targetId } = await session.Target.createTarget({ url: 'about:blank' })
   await session.use(targetId)
   await session.Page.enable()
   await session.Page.navigate({ url: 'https://example.com' })
   // now wait for Page.loadEventFired via session.waitFor

2. New tab may open behind the active one. Add Target.activateTarget if the user needs to see it.

Visible tab-strip order (platform UI)

CDP's Target.getTargets returns an arbitrary order — not left-to-right.

macOS

tell application "Google Chrome"
  set out to {}
  set i to 1
  repeat with t in every tab of front window
    set end of out to {tab_index:i, tab_title:(title of t), tab_url:(URL of t)}
    set i to i + 1
  end repeat
  return out
end tell

tell application "Google Chrome"
  set active tab index of front window to 2
  activate
end tell

Linux

No AppleScript. Use xdotool, wmctrl, or desktop-environment scripting. The split is the same — CDP for attach/activate-by-id, window manager for visible ordering.

Traps

• listPageTargets() already drops chrome:// and devtools://. If you call Target.getTargets raw, you must filter yourself, or you'll attach to a 1px omnibox popup.
• If a page reports innerWidth=0 innerHeight=0, you're probably attached to a non-window surface (omnibox popup, background tab that never rendered).

Uploads

Never simulate clicks on <input type="file"> — it opens the OS file picker, which CDP cannot dismiss. Set files directly via CDP instead.

The canonical path

await session.DOM.enable()
const { root } = await session.DOM.getDocument({ depth: -1 })
const { nodeId } = await session.DOM.querySelector({
  nodeId: root.nodeId,
  selector: 'input[type="file"]',
})
if (!nodeId) throw new Error('no file input found')

await session.DOM.setFileInputFiles({
  nodeId,
  files: ['/absolute/path/to/file.png'],
})

• Paths must be absolute.
• Multiple files: pass an array — only works if the input has multiple.
• Fires change on the input just like a real selection would.

Hidden / off-screen file inputs

Sites commonly hide <input type="file"> (display:none, visibility:hidden, positioned off-screen) and expose a styled button that calls input.click(). DOM.setFileInputFiles works regardless of visibility — find the input directly, don't click the button:

// Works even for display:none / opacity:0 inputs
const { nodeIds } = await session.DOM.querySelectorAll({
  nodeId: root.nodeId,
  selector: 'input[type="file"]',
})

If querySelector returns nodeId: 0, the input is inside a shadow root or iframe — see shadow-dom.md / iframes.md.

Drag-and-drop upload zones

React/Vue dropzones (react-dropzone, etc.) often only react to drop events and have no <input>. Two paths:

1. Find the hidden input — most dropzones still include one for accessibility. Inspect with document.querySelectorAll('input[type=file]') first. 2. Synthesize a DOM drop event with a DataTransfer containing your File:

   await session.Runtime.evaluate({ awaitPromise: true, expression: `
     (async () => {
       const resp = await fetch('https://example.com/file.png')
       const blob = await resp.blob()
       const file = new File([blob], 'file.png', { type: 'image/png' })
       const dt = new DataTransfer()
       dt.items.add(file)
       const target = document.querySelector('.dropzone')
       for (const type of ['dragenter','dragover','drop']) {
         target.dispatchEvent(new DragEvent(type, { bubbles: true, cancelable: true, dataTransfer: dt }))
       }
     })()
   `})

Detectable by antibot — prefer path 1 if a hidden input exists.

Verifying the upload fired

Listen for the change on the input, or watch the network via Network.requestWillBeSent for the upload POST. A screenshot alone often won't show that the file attached — use the network trace.

Viewport

Coordinate clicks depend on viewport size; layouts depend on viewport size; a lot of flaky automation traces to a viewport that silently changed.

Read the current viewport

const { result } = await session.Runtime.evaluate({
  returnByValue: true,
  expression: `
    JSON.stringify({
      w: innerWidth, h: innerHeight,
      sx: scrollX, sy: scrollY,
      pw: document.documentElement.scrollWidth,
      ph: document.documentElement.scrollHeight,
      dpr: devicePixelRatio,
    })
  `,
})
const vp = JSON.parse(result.value)

innerWidth/innerHeight is the CSS-pixel viewport — what coordinate clicks use. devicePixelRatio multiplies for actual screen pixels (captureScreenshot output dimensions).

Force a specific size (CSS pixels)

await session.Emulation.setDeviceMetricsOverride({
  width: 1280,
  height: 800,
  deviceScaleFactor: 1,   // 0 = use real DPR; set to 2 for retina-like
  mobile: false,
})

All subsequent Input.dispatchMouseEvent coordinates are in this 1280×800 space — pin it at the start of a session so coordinates stay stable.

Clear it back to the actual window size:

await session.Emulation.clearDeviceMetricsOverride()

Mobile emulation

await session.Emulation.setDeviceMetricsOverride({
  width: 390, height: 844,
  deviceScaleFactor: 3,
  mobile: true,
})
await session.Emulation.setTouchEmulationEnabled({ enabled: true })
await session.Network.setUserAgentOverride({
  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
})

Mobile triggers responsive breakpoints and enables touch events. Sites with @media (hover: hover) also flip their hover affordances off.

w=0 h=0 is a target problem, not a viewport problem

If Runtime.evaluate('innerWidth') returns 0, you're attached to a non-window surface (omnibox popup, a DevTools target). See connection.md / tabs.md — use listPageTargets() and re-route with session.use(...).

Traps

• Coordinate clicks become wrong as soon as the viewport changes. Re-read rects with getBoundingClientRect() after any resize, not just after scrolling.
• `captureScreenshot` returns device pixels, not CSS pixels. If devicePixelRatio = 2 and you eyeball an element at (400, 300) in the screenshot, click at (200, 150) in CSS pixels.
• `setDeviceMetricsOverride` persists across navigations within the session — remember to clear it at the end if the user is going to keep using the browser.
• Some sites guard against resize storms (e.g. window.addEventListener('resize', debounce)). After setDeviceMetricsOverride, wait ~300ms before reading rects or clicking.
• Responsive sites that use `matchMedia` at page load may not re-evaluate breakpoints after override. Apply setDeviceMetricsOverride before Page.navigate, not after.

<img src="https://r2.browser-use.com/github/asbfgihsbfbaosfjla.png" alt="Browser Harness" width="100%" />

Browser Harness JS ♞

The thinnest possible bridge from the LLM to Chrome. No harness, no recipes, no rails — just every CDP method as a typed JS call.

One persistent WebSocket, 56 domains, 652 typed wrappers, zero wrapping of what Chrome already does.

  ● agent: wants to click a button
  │
  ● no click() helper, no upload_file(), no goto()
  │
  ● agent writes the CDP call itself        await session.Input.dispatchMouseEvent({...})
  │                                          await session.DOM.setFileInputFiles({...})
  ✓ done — same pattern for all 652 methods

The protocol is the API. If Chrome can do it, you can call it.

Installation

npx skills add https://github.com/browser-use/browser-harness-js --skill cdp

Or paste this into your agent — it'll install the skill, put the CLI on your PATH, and run a first task:

Run `npx skills add https://github.com/browser-use/browser-harness-js --skill cdp`, then
symlink `browser-harness-js` into a directory on my PATH, then use the cdp skill to drive
my browser: look at all the tabs I have open, group them by topic, and screenshot the most
interesting one.

(The CLI auto-installs `bun` on first run if it's missing. Set BROWSER_HARNESS_SKIP_BUN_INSTALL=1 to opt out.)

If Chrome asks you to tick a remote-debugging checkbox, do it — that's how the agent attaches:

<img src="docs/setup-remote-debugging.png" alt="Remote debugging setup" width="520" style="border-radius: 12px;" />

See interaction-skills/ for recipes on the mechanics that are not obvious from the CDP method list alone.

Files

• SKILL.md — day-to-day usage; how to connect, pick a tab, call methods, persist state
• sdk/browser-harness-js — tiny CLI that auto-spawns the server and forwards snippets
• sdk/repl.ts — Bun HTTP server holding one persistent Session
• sdk/session.ts — the Session class: transport, connect, target routing, events
• sdk/gen.ts — codegen: reads browser_protocol.json + js_protocol.json → typed wrappers
• sdk/generated.ts — every CDP method as session.<Domain>.<method>(params) (generated)

No helpers file. No click(), no goto(), no upload_file() — just the protocol, typed.

Why no pre-baked helpers?

Every helper is a lie about what CDP already gives you. click(x, y) hides Input.dispatchMouseEvent — which has 14 parameters the LLM might need (button, clickCount, modifiers, pointerType, force, tangentialPressure, …). A harness that exposes three of them quietly limits what the agent can do.

• Types are the docs. session.Page.navigate( triggers autocomplete with the exact params — same JSDoc as the CDP reference.
• No version drift. The SDK is regenerated from the upstream protocol JSON; new Chrome methods appear as soon as you swap the JSON.
• No "helper doesn't handle my case" detours. If CDP can do it, the agent can call it — directly, typed, today.

The only "helpers" you'll find are things CDP itself is missing:

• listPageTargets() — filters chrome:// / devtools:// out of Target.getTargets
• resolveWsUrl({wsUrl|port|profileDir}) — reads DevToolsActivePort for Chrome 144+
• session.use(targetId) / session.waitFor(method, pred, timeout) — the two routing primitives you genuinely need

Contributing

PRs welcome. The best way to help: contribute a new interaction skill under interaction-skills/ when you figure out the CDP recipe for something non-obvious (a dropdown framework, a shadow-DOM trap, a network-wait pattern).

• Keep recipes in pure CDP — session.Domain.method(...), not wrapped helpers.
• Lead with the shortest method call that works; add the workaround or trap afterwards.
• Small and focused beats comprehensive. One mechanic per file.
• Bug fixes, codegen improvements, and session.ts refinements are equally welcome.

---

Bitter lesson · Skills