← Files egoARCHIVED FILE
skills/ego-browser/references/api.md
50.7 KB · Oct 4, 2026 · 12:34 UTC
# ego-browser v2 API reference
Generated from `package/ego-browser/src/public-api-schema.ts`.
High-level Page actions return a receipt that may contain `popups` or a synchronous `dialog`. Handle a returned dialog with `page.acceptDialog(promptText?)` or `page.dismissDialog()` before continuing.
For an explicit popup wait, arm it before the action: `const popupPromise = page.waitForEvent("popup"); await page.click(selector); const popup = await popupPromise;`. Action receipts instead expose `{ label, targetId }` entries in `receipt.popups`; resolve one with `task.page(label)`.
For a download, arm the event before the action and save the returned artifact explicitly: `const downloadPromise = page.waitForEvent("download"); await page.click(selector); const download = await downloadPromise; await download.saveAs(absolutePath);`.
Selectors accept refs, Ego locators, XPath, and raw CSS. A small compatibility subset also accepts `css=...`, terminal `:has-text("...")` and `:text-is("...")`, `>> nth=N` after CSS/text/href selectors (`N` is `-1` or non-negative), and `loc=role:...[name*="..."]`.
## Entry points
| API | Options | Purpose |
| ------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `await profiles()` | — | List browser profiles available for new task spaces. |
| `await listTaskSpaces()` | — | List Agent-owned and user-owned spaces available to reuse or claim. |
| `await taskSpace(nameOrId, { profileId? })` | `profileId` — Browser profile id returned by profiles(); new spaces only. | Reuse or create an Agent-owned task space; a new space starts with managed Page p1, and profileId applies only when creating it. |
| `await claimTaskSpace(spaceId)` | — | Claim a user-owned or inactive space after user approval and return TaskSpace. |
| `await takeOverTaskSpace(spaceId)` | — | Resume an Agent-owned space after user approval and return TaskSpace. |
| `fileChooser.isMultiple()` | — | Report whether the chooser accepts multiple files. |
| `await fileChooser.setFiles(pathOrPaths)` | — | Set files on an intercepted chooser and return any JavaScript dialog opened by the upload. |
## TaskSpace
| API | Options | Purpose |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `task.spaceId` | — | Stable numeric identifier for this task space. |
| `task.name` | — | Human-readable task-space name. |
| `task.ownership` | — | Ownership state captured when this TaskSpace was created. |
| `task.page(label)` | — | Create a lazy Page handle for a durable page label. |
| `task.userPage()` | — | Return the tab active at the claim/takeover boundary, when one was captured. |
| `await task.pages()` | — | List the managed Page handles in this space. |
| `await task.tabs()` | — | List managed Pages and unmanaged tabs in this space. |
| `await task.newPage()` | — | Create and durably label a blank Page. |
| `await task.adopt(unmanagedPage, { as? })` | `as` — Permanent Page label. | Bring an unmanaged tab under the Page lifecycle. |
| `await task.release(label)` | — | Stop managing an unknown-origin Page without closing it. |
| `await task.waitForControl({ interval?, timeout? })` | `interval` — Polling interval in milliseconds.<br>`timeout` — Maximum duration in milliseconds. | Wait for Agent control without taking it from the user. |
| `await task.handOff()` | — | Give control of this space to the user. |
| `await task.finish({ keep })` | `keep` — Required Page retention policy: "all" or an array of managed Page labels. | Finish the task and return a receipt with retained and closed managed Page labels; an empty list closes the space when no protected tabs remain. |
| `await task.cdp(method, params?, { timeout? })` | `timeout` — Maximum duration in milliseconds. | Send a Target or Browser domain CDP command. |
## Page
| API | Options | Purpose |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page.label` | — | Durable Page label used to restore the tab across rounds. |
| `page.spaceId` | — | Numeric identifier of the Page's task space. |
| `page.openedBy` | — | Conservative origin attribution for this Page. |
| `page.targetId` | — | Internal browser target identifier for advanced Target-domain CDP only. |
| `await page.goto(url, { referer?, timeout?, waitUntil? })` | `referer` — HTTP Referer header for the navigation.<br>`timeout` — Maximum duration in milliseconds.<br>`waitUntil` (commit, domcontentloaded, load, networkidle) — Completion state; defaults to load. networkidle requires 500ms without network activity. | Navigate this Page in place. Timeout errors report whether the new document committed, plus its URL and readyState when available. |
| `await page.reload({ timeout?, waitUntil? })` | `timeout` — Maximum duration in milliseconds.<br>`waitUntil` (commit, domcontentloaded, load, networkidle) — Completion state; defaults to load. networkidle requires 500ms without network activity. | Reload this Page and wait for the selected navigation state. |
| `await page.snapshot({ scope?, root?, includeActionMarks?, includeStableLocator? })` | `scope` (full_page, only_within_viewport, subtree) — Snapshot scope; defaults to only_within_viewport, including visible iframe content returned by the browser. Use subtree with an iframe root ref to focus on that frame.<br>`root` — Valid Page snapshot ref such as @21; required only when scope is subtree. Partial snapshots preserve existing node identities.<br>`includeActionMarks` — Include action marks.<br>`includeStableLocator` — Include stable locators. | Return a semantic snapshot of the current viewport, full Page, or one snapshot-ref subtree with Page provenance. |
| `await page.screenshot({ path?, fullPage?, clip?, scale?, raw? })` | `path` — Output path; missing parent directories are created.<br>`fullPage` — Capture the full scrollable page.<br>`clip` — CSS-pixel clipping rectangle.<br>`scale` (css) — Output scale mode; css uses CSS-pixel sizing and is the default.<br>`raw` — Bypass device-pixel-ratio correction. | Capture this Page to a PNG file. |
| `await page.url()` | — | Read this Page's current URL. |
| `await page.waitForURL(urlMatcher, { timeout? })` | `timeout` — Maximum duration in milliseconds. | Wait for an exact URL, Playwright-style glob, RegExp, or synchronous predicate receiving a URL object. |
| `await page.waitForEvent(event, { timeout? })` | `timeout` — Maximum duration in milliseconds. | Wait for this Page's next "popup" or "download"; arm the promise before the triggering action. |
| `await page.waitForTimeout(timeout)` | — | Wait a fixed number of milliseconds without activating this Page. |
| `await page.title()` | — | Read this Page's current title. |
| `await page.info()` | — | Read URL, title, viewport, scroll, and dialog state. |
| `await page.acceptDialog(promptText?)` | — | Accept this Page's JavaScript dialog, optionally supplying prompt text; return false when none is open. |
| `await page.dismissDialog()` | — | Dismiss this Page's JavaScript dialog; return false when none is open. |
| `await page.evaluate(fnOrString, argument?)` | — | Run JavaScript in this Page; callbacks receive JSON data but cannot capture Node.js variables. Safety-timeout errors report executionStopped, pageResponsive, and mayHaveLateEffects. |
| `await page.waitForFunction(fnOrString, argument?, { timeout?, polling? })` | `timeout` — Maximum duration in milliseconds.<br>`polling` — Polling interval in milliseconds; defaults to 100. | Wait until a Page function or expression returns a truthy value. |
| `await page.fetch(url, options?)` | `timeout` — Maximum duration in milliseconds.<br>`saveAs` — Write the response body to this path without text conversion.<br>`method` — HTTP method.<br>`headers` — Request headers.<br>`body` — Request body.<br>`cache` (default, no-store, reload, no-cache, force-cache, only-if-cached) — Fetch cache mode.<br>`credentials` (omit, same-origin, include) — Fetch credentials mode.<br>`integrity` — Subresource integrity value.<br>`keepalive` — Allow the request to outlive the page.<br>`mode` (cors, no-cors, same-origin) — Fetch request mode.<br>`redirect` (follow, error, manual) — Redirect handling mode.<br>`referrer` — Request referrer.<br>`referrerPolicy` — Request referrer policy. | Run window.fetch in this Page, obey browser CORS, and return a structured response. |
| `await page.cdp(method, params?, { timeout? })` | `timeout` — Maximum duration in milliseconds. | Send a CDP command through this Page's target session. |
| `await page.waitForSelector(selector, { timeout?, state? })` | `timeout` — Maximum duration in milliseconds.<br>`state` (attached, detached, visible, hidden) — Required element state. | Wait for an element state in this Page. |
| `await page.waitForLoadState(state?, { timeout?, idleMs? })` | `timeout` — Maximum duration in milliseconds.<br>`idleMs` — Required network-idle window in milliseconds. | Wait for DOM content, load, or network-idle state; no state defaults to load. |
| `await page.events()` | — | Read and clear CDP events buffered for this Page. |
| `await page.click(selector, { button?, clickCount?, delay?, position?, force?, timeout?, label? })` | `button` (left, middle, right) — Mouse button.<br>`clickCount` — Number of clicks.<br>`delay` — Input delay in milliseconds.<br>`position` — CSS-pixel offset from the element's top-left corner.<br>`force` — Bypass pointer interception checks.<br>`timeout` — Maximum wait for the element to become usable in milliseconds; defaults to 3000.<br>`label` — Concise user-visible action description shown with the native mouse highlight. | Click an element with native CDP input. |
| `await page.dblclick(selector, { button?, delay?, position?, force?, timeout?, label? })` | `button` (left, middle, right) — Mouse button.<br>`delay` — Input delay in milliseconds.<br>`position` — CSS-pixel offset from the element's top-left corner.<br>`force` — Bypass pointer interception checks.<br>`timeout` — Maximum wait for the element to become usable in milliseconds; defaults to 3000.<br>`label` — Concise user-visible action description shown with the native mouse highlight. | Double-click an element with native CDP input. |
| `await page.hover(selector, { position?, force?, timeout?, label? })` | `position` — CSS-pixel offset from the element's top-left corner.<br>`force` — Bypass pointer interception checks.<br>`timeout` — Maximum wait for the element to become usable in milliseconds; defaults to 3000.<br>`label` — Concise user-visible action description shown with the native mouse highlight. | Move the mouse over an element. |
| `await page.dragAndDrop(source, target, { button?, sourcePosition?, targetPosition?, force?, timeout?, label? })` | `button` (left, middle, right) — Mouse button.<br>`sourcePosition` — CSS-pixel offset from the element's top-left corner.<br>`targetPosition` — CSS-pixel offset from the element's top-left corner.<br>`force` — Bypass pointer interception checks.<br>`timeout` — Maximum wait for the element to become usable in milliseconds; defaults to 3000.<br>`label` — Concise user-visible action description shown with the native mouse highlight. | Drag from one element to another. |
| `await page.fill(selector, value, { clearFirst?, timeout? })` | `clearFirst` — Clear the current value before filling.<br>`timeout` — Maximum wait for the element to become usable in milliseconds; defaults to 3000. | Fill the selected field, its editing host, or its unique fillable descendant, then confirm editing took effect. |
| `await page.selectOption(selector, valueOrValues, { timeout? })` | `timeout` — Maximum wait for the element to become usable in milliseconds; defaults to 3000. | Select by a value-or-label string or { value?, label?, index? }; arrays select multiple options, while null or [] clears the selection. The select must be enabled, but disabled options remain programmatically selectable. |
| `await page.focus(selector, { timeout? })` | `timeout` — Maximum wait for the element to become usable in milliseconds; defaults to 3000. | Focus the element, its nearest interactive ancestor, or its unique editable descendant. |
| `await page.press(selector, chord, { delay?, timeout? })` | `delay` — Input delay in milliseconds.<br>`timeout` — Maximum wait for the element to become usable in milliseconds; defaults to 3000. | Focus one element and press a key or shortcut chord. Named keys are case-insensitive; single-character keys preserve case. |
| `await page.setInputFiles(selector, pathOrPaths)` | — | Set files on a file input resolved from the input, its label, or a unique descendant. |
| `page.waitForFileChooser({ timeout? })` | `timeout` — Maximum duration in milliseconds. | Wait for a dynamically created file chooser. |
| `await page.close()` | — | Close this Page after confirming its tab disappeared. |
## Download
| API | Options | Purpose |
| ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `download.page()` | — | Return the Page that started this download. |
| `download.url()` | — | Return the download URL. |
| `download.suggestedFilename()` | — | Return Chromium's suggested file name. |
| `await download.saveAs(absolutePath)` | — | Wait for completion and copy the download to an absolute path, creating missing parent directories. |
| `await download.path()` | — | Wait for completion and return the round-local temporary file path. |
| `await download.failure()` | — | Wait for completion and return null or the failure reason. |
| `await download.cancel()` | — | Cancel this download by its Chromium download identifier. |
| `await download.delete()` | — | Delete this download's round-local temporary files. |
## Page.mouse
| API | Options | Purpose |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `await page.mouse.click(x, y, { button?, clickCount?, delay?, label? })` | `button` (left, middle, right) — Mouse button.<br>`clickCount` — Number of clicks.<br>`delay` — Input delay in milliseconds.<br>`label` — Concise user-visible action description shown with the native mouse highlight. | Click CSS-pixel coordinates with native CDP input. |
| `await page.mouse.move(x, y, { steps?, label? })` | `steps` — Number of movement steps.<br>`label` — Concise user-visible action description shown with the native mouse highlight. | Move the mouse to CSS-pixel coordinates. |
| `await page.mouse.down({ button?, clickCount? })` | `button` (left, middle, right) — Mouse button.<br>`clickCount` — Click count reported to the page. | Press a mouse button at the current Page position. |
| `await page.mouse.up({ button?, clickCount? })` | `button` (left, middle, right) — Mouse button.<br>`clickCount` — Click count reported to the page. | Release a mouse button at the current Page position. |
| `await page.mouse.wheel(deltaX, deltaY, { label? })` | `label` — Concise user-visible action description shown with the native mouse highlight. | Perform a short wheel-input motion at the current Page position; move or click over the intended scroll container first in each process. |
## Page.keyboard
| API | Options | Purpose |
| ---------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `await page.keyboard.down(key)` | — | Press and hold a keyboard key. |
| `await page.keyboard.up(key)` | — | Release a keyboard key. |
| `await page.keyboard.press(chord, { delay? })` | `delay` — Input delay in milliseconds. | Press and release a key or portable shortcut chord. Named keys are case-insensitive; single-character keys preserve case. |
| `await page.keyboard.type(text, { delay? })` | `delay` — Input delay in milliseconds. | Type text using physical keys where possible. |
| `await page.keyboard.insertText(text)` | — | Insert text without synthesizing key presses. |
| `await page.keyboard.paste(textOrContent)` | — | Send native paste with a string or { text, html? }, then restore the clipboard. |
SHA-256: 3e42eeee2ad8f14cd6784f7bf03e81bd52e4cc01ecb7835cac7246402d21f8ec