> ## Documentation Index
> Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK resources reference

> Reference browser-scoped SDK resources for files, downloads, dialogs, permissions, recordings, events, pages, and CAPTCHA.

Browser handles expose resource helpers for the things a real browser session produces: files, downloads, dialogs, permissions, recordings, events, pages, and blockers.

```ts theme={null}
const browser = await web.browser.create({ recording: true });

const downloads = await browser.downloads.list();
const events = await browser.events({ limit: 50 });
```

## Files

Use files to stage host-provided bytes for browser-side upload workflows.

```ts theme={null}
const file = await browser.files.createFromPath("./invoice.csv", {
  mimeType: "text/csv",
});
```

When browser code or an agent run needs the staged file, resolve it inside browser execution with `files.path(fileId)` before calling an upload control such as `locator.setInputFiles(...)`. For agent runs against an existing browser, use an agent without `browser.policy`; the browser owns policy.

```ts theme={null}
const resourceAgent = web.agent({
  model,
  approval: "ask",
});

await resourceAgent.run({
  browserId: browser.id,
  startUrl: "https://portal.example/upload",
  goal: `Upload the staged CSV file. The staged file id is ${file.id}; use files.path("${file.id}") to resolve the browser-side upload path.`,
});
```

| Method                         | Signature                                                                                   | Description                     |
| ------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------- |
| `browser.files.create`         | `(input: CreateBrowserFileOptions) => Promise<BrowserFileSummary>`                          | Stage a file from memory.       |
| `browser.files.createFromPath` | `(path: string, options?: CreateBrowserFileFromPathOptions) => Promise<BrowserFileSummary>` | Stage a file from a local path. |
| `browser.files.list`           | `(options?: BrowserArtifactListOptions) => Promise<ListBrowserFilesResponse>`               | List staged files.              |
| `browser.files.get`            | `(fileId: FileId, options?: { signal?: AbortSignal }) => Promise<BrowserFileSummary>`       | Fetch staged file metadata.     |
| `browser.files.content`        | `(fileId: FileId, options?: { signal?: AbortSignal }) => Promise<Uint8Array>`               | Download staged file bytes.     |
| `browser.files.delete`         | `(fileId: FileId, options?: { signal?: AbortSignal }) => Promise<void>`                     | Delete a staged file.           |

`CreateBrowserFileOptions` fields:

| Field      | Description              |
| ---------- | ------------------------ |
| `name`     | File name. Required.     |
| `mimeType` | Optional MIME type.      |
| `base64`   | Base64-encoded contents. |
| `bytes`    | Raw bytes.               |
| `signal`   | Abort signal.            |

## Downloads

```ts theme={null}
const list = await browser.downloads.list();
const [first] = list.data;

if (first) {
  await browser.downloads.save(first.id, "./downloads/report.pdf", {
    overwrite: true,
    maxBytes: 25_000_000,
  });
}
```

| Method                      | Signature                                                                                                                  | Description                                            |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `browser.downloads.list`    | `(options?: BrowserArtifactListOptions) => Promise<ListBrowserDownloadsResponse>`                                          | List browser downloads.                                |
| `browser.downloads.get`     | `(downloadId: DownloadId, options?: { signal?: AbortSignal }) => Promise<BrowserDownloadSummary>`                          | Fetch download metadata.                               |
| `browser.downloads.content` | `(downloadId: DownloadId, options?: { signal?: AbortSignal; maxBytes?: number }) => Promise<Uint8Array>`                   | Fetch download bytes, optionally capped by `maxBytes`. |
| `browser.downloads.save`    | `(downloadId: DownloadId, outputPath: string, options?: BrowserDownloadSaveOptions) => Promise<BrowserDownloadSaveResult>` | Save download bytes to a local file.                   |

`BrowserDownloadSaveOptions`:

| Field       | Description                                         |
| ----------- | --------------------------------------------------- |
| `overwrite` | Replace an existing output file. Defaults to false. |
| `maxBytes`  | Maximum bytes to save.                              |
| `signal`    | Abort signal.                                       |

## Dialogs

```ts theme={null}
const dialogs = await browser.dialogs.list({ status: "open" });

for (const dialog of dialogs.data) {
  await browser.dialogs.dismiss(dialog.id);
}
```

| Method                    | Signature                                                                                                                                                                                                    | Description                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `browser.dialogs.list`    | `(options?: { pageId?: PageId; status?: "open" \| "recent"; cursor?: string; limit?: number; signal?: AbortSignal }) => Promise<ListBrowserDialogsResponse>`                                                 | List JavaScript dialogs.                                 |
| `browser.dialogs.accept`  | `(dialogId: DialogId, options?: { promptText?: string; includeState?: "auto" \| "never" \| "none" \| "compact" \| "full"; maxStateChars?: number; signal?: AbortSignal }) => Promise<BrowserDialogResponse>` | Accept a dialog. `promptText` applies to prompt dialogs. |
| `browser.dialogs.dismiss` | `(dialogId: DialogId, options?: { includeState?: "auto" \| "never" \| "none" \| "compact" \| "full"; maxStateChars?: number; signal?: AbortSignal }) => Promise<BrowserDialogResponse>`                      | Dismiss a dialog.                                        |

## Permissions

Use permission helpers when a workflow needs explicit browser permissions such as geolocation.

| Method                      | Signature                                                                                                                               | Description                              |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `browser.permissions.grant` | `(request: BrowserPermissionGrant & { geolocation?: BrowserGeolocation; signal?: AbortSignal }) => Promise<BrowserPermissionsResponse>` | Grant permissions.                       |
| `browser.permissions.deny`  | `(request: BrowserPermissionGrant & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse>`                                   | Deny permissions.                        |
| `browser.permissions.clear` | `(request?: BrowserClearPermissionsRequest & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse>`                          | Clear permission overrides.              |
| `browser.permissions.reset` | `(request?: BrowserClearPermissionsRequest & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse>`                          | Alias for clearing permission overrides. |

## Recordings

Recording methods are useful only for browsers created with `recording: true`.

```ts theme={null}
const recording = await browser.recordings.get();
const segments = await browser.recordings.segments();
await browser.recordings.download("wc_rec_...", "./recordings", { overwrite: true });
```

| Method                        | Signature                                                                                                                    | Description                                           |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `browser.recordings.get`      | `(options?: { signal?: AbortSignal }) => Promise<BrowserRecordingResponse>`                                                  | Fetch recording summary.                              |
| `browser.recordings.segments` | `(options?: RecordingListOptions) => Promise<ListRecordingSegmentsResponse>`                                                 | List recording segments.                              |
| `browser.recordings.segment`  | `(segmentId: RecordingSegmentId, options?: { signal?: AbortSignal }) => Promise<RecordingSegmentManifestResponse>`           | Fetch a segment manifest.                             |
| `browser.recordings.events`   | `(segmentId: RecordingSegmentId, options?: RecordingEventsOptions) => Promise<ListRecordingEventsResponse>`                  | List events for one segment.                          |
| `browser.recordings.frame`    | `(segmentId: RecordingSegmentId, frameKey: string, options?: { signal?: AbortSignal }) => Promise<Uint8Array>`               | Fetch a recorded frame.                               |
| `browser.recordings.download` | `(segmentId: RecordingSegmentId, outputDir: string, options?: RecordingDownloadOptions) => Promise<RecordingDownloadResult>` | Download manifest, events, and frames to local files. |

`RecordingDownloadResult` contains `segmentId`, `outputDir`, `manifestPath`, `eventsPath`, and `framePaths`.

## Events

```ts theme={null}
for await (const event of browser.streamEvents({ pollIntervalMs: 1000 })) {
  console.log(event.type, event.severity);
}
```

| Method                 | Signature                                                                | Description                     |
| ---------------------- | ------------------------------------------------------------------------ | ------------------------------- |
| `browser.events`       | `(options?: BrowserEventsOptions) => Promise<ListBrowserEventsResponse>` | Fetch browser events.           |
| `browser.streamEvents` | `(options?: BrowserEventStreamOptions) => AsyncIterable<BrowserEvent>`   | Poll events as an async stream. |

`BrowserEventsOptions` fields:

| Field        | Description              |
| ------------ | ------------------------ |
| `cursor`     | Pagination cursor.       |
| `limit`      | Results per page.        |
| `since`      | Lower time bound.        |
| `until`      | Upper time bound.        |
| `type`       | Event type filter.       |
| `category`   | Event category filter.   |
| `pageId`     | Page filter.             |
| `severity`   | Event severity filter.   |
| `visibility` | Event visibility filter. |
| `signal`     | Abort signal.            |

`BrowserEventStreamOptions` also accepts `pollIntervalMs`.

## Pages

```ts theme={null}
const pages = await browser.pages();
const active = pages.find((page) => page.active);
```

`browser.pages(options?)` returns page summaries with:

| Field       | Description                           |
| ----------- | ------------------------------------- |
| `id`        | Page ID.                              |
| `browserId` | Browser ID.                           |
| `url`       | Current page URL.                     |
| `title`     | Current page title.                   |
| `active`    | Whether this page is the active page. |

## CAPTCHA and blockers

| Method                    | Signature                                                                     | Description                                            |
| ------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ |
| `browser.captcha.status`  | `(options?: { signal?: AbortSignal }) => Promise<BrowserStatusResponse>`      | Fetch compact blocker status.                          |
| `browser.captcha.resolve` | `(options?: BrowserCaptchaResolveOptions) => Promise<ResolveCaptchaResponse>` | Ask the runtime to resolve a detected CAPTCHA blocker. |

`BrowserCaptchaResolveOptions` accepts resolver options plus `signal`.