V3Context — browser context API reference

V3Context is the object that wires CDP target events into Page instances and exposes context-level APIs for cookies, init scripts, and extra HTTP headers. You receive a V3Context from browser.context (the default context) or from browser.create() / context.createBrowserContext() (an isolated context). Every V3Context has a browserContextId that scopes all storage and network operations. Default contexts and dedicated (incognito-style) contexts behave identically from the API surface.

Page management

`context.newPage`

Open a new browser tab. The method creates a CDP target, waits for it to attach, and returns the resulting Page once ready.

const page = await context.newPage("https://example.com")

url

string

default:"about:blank"

URL to navigate to after the tab opens. Navigation is fire-and-forget after attach, so the page may still be loading when the method returns.

Returns Promise<Page>

`context.pages`

Return all top-level pages (tabs) in this context, ordered from oldest to newest. Out-of-process iframes are not included.

const pages = context.pages()
for (const page of pages) {
  console.log(page.url())
}

Returns Page[]

`context.activePage`

Return the most recently activated page, or undefined if no pages exist.

const page = context.activePage()
if (page) {
  await page.goto("https://example.com")
}

Returns Page | undefined

`context.setActivePage`

Mark a specific page as the active one and bring it to the foreground in headed Chrome.

context.setActivePage(page)

page

Page

required

A Page instance that belongs to this context.

Returns void

`context.awaitActivePage`

Like activePage(), but waits briefly if a popup or new tab was just opened. Useful when clicking a link that opens a new window.

// After clicking a link that opens a new tab:
const newPage = await context.awaitActivePage(2000)

timeoutMs

number

default:"2000"

Maximum time to wait for a new page to appear, in milliseconds.

Returns Promise<Page> Throws PageNotFoundError if no page is available within the timeout.

`context.cookies`

Return all cookies in this browser context. When one or more URLs are supplied, only cookies whose domain, path, and secure attributes match are returned.

// All cookies
const all = await context.cookies()

// Cookies for a specific URL
const filtered = await context.cookies("https://example.com")

// Cookies for multiple URLs
const multi = await context.cookies(["https://a.com", "https://b.com"])

urls

string | string[]

Optional URL or list of URLs to filter by.

Returns Promise<Cookie[]>

name

string

required

Cookie name.

value

string

required

Cookie value.

domain

string

required

Cookie domain (e.g., ".example.com").

path

string

required

Cookie path.

expires

number

required

Unix timestamp in seconds. -1 means session cookie.

httpOnly

boolean

required

Whether the cookie is HTTP-only.

secure

boolean

required

Whether the cookie is secure.

sameSite

"Strict" | "Lax" | "None"

required

SameSite attribute value.

`context.addCookies`

Set one or more cookies in this browser context. Each cookie must specify either a url (from which domain, path, and secure are derived) or an explicit domain + path pair.

await context.addCookies([
  {
    name: "session",
    value: "abc123",
    url: "https://example.com",
    httpOnly: true,
    secure: true,
  },
])

CookieParam[]

required

Array of cookie descriptors to set.

Returns Promise<void> Throws CookieSetError if the browser rejects the batch.

`CookieParam` type

name

string

required

Cookie name.

value

string

required

Cookie value.

url

string

Convenience field: derive domain, path, and secure from this URL. Provide url or domain+path, not both.

domain

string

Cookie domain.

path

string

Cookie path.

expires

number

Unix timestamp in seconds. Omit or pass -1 for a session cookie.

httpOnly

boolean

HTTP-only flag.

secure

boolean

Secure flag.

sameSite

"Strict" | "Lax" | "None"

SameSite attribute.

`context.clearCookies`

Clear cookies from this browser context. Called with no arguments, all cookies are removed atomically. Called with filter options, matching cookies are removed while non-matching ones are preserved.

// Clear all cookies
await context.clearCookies()

// Clear cookies matching a name
await context.clearCookies({ name: "session" })

// Clear cookies matching a domain pattern
await context.clearCookies({ domain: /example\.com$/ })

options

ClearCookieOptions

Optional filter. Cookies matching all provided criteria are removed.

Returns Promise<void>

`ClearCookieOptions` type

name

string | RegExp

Match cookies by exact name or regular expression.

domain

string | RegExp

Match cookies by exact domain or regular expression.

path

string | RegExp

Match cookies by exact path or regular expression.

Scripts and headers

`context.addInitScript`

Register a script to run at document start on every page in this context, including pages that open in the future. Scripts are not inherited by child contexts created via createBrowserContext.

// Inline function with an argument
await context.addInitScript((token: string) => {
  window.__authToken = token
}, "my-secret-token")

// Inline expression string
await context.addInitScript("window.__env = 'test'")

script

string | Function

required

A JavaScript expression string or a serializable function. Functions are stringified and invoked with the optional arg.

arg

any

JSON-serializable argument passed to the script function.

Returns Promise<void>

`context.setExtraHTTPHeaders`

Attach additional HTTP headers to every request made by any page in this context. Headers set here apply to all sessions, including those of out-of-process iframes.

await context.setExtraHTTPHeaders({
  "X-Custom-Header": "value",
  Authorization: "Bearer token",
})

headers

Record<string, string>

required

Key–value pairs of header names and values.

Returns Promise<void> Throws HandstagesSetExtraHTTPHeadersError if one or more CDP sessions fail to apply the headers.

Context lifecycle

`context.createBrowserContext`

Create a new isolated browser context that shares the underlying CDP connection but has its own cookies, storage, and pages. The returned context is tracked weakly so the parent can close it during cleanup if needed.

const isolated = await context.createBrowserContext({ disposeOnDetach: true })
const page = await isolated.newPage("https://example.com")
await isolated.close()

options

CreateContextOptions

Options for the new context.

Returns Promise<V3Context>

`CreateContextOptions` type

disposeOnDetach

boolean

default:"true"

When true, Chrome automatically disposes the context if the CDP connection drops unexpectedly.

proxyServer

string

Proxy server URL to use for requests from this context (e.g., "http://proxy.example.com:8080").

proxyBypassList

string

Comma-separated list of hosts that bypass the proxy.

originsWithUniversalNetworkAccess

string[]

Origins granted unrestricted network access regardless of CORS or mixed-content policies.

`context.close`

Tear down this context. Closes all child contexts, removes all event listeners, closes every page, and disposes the browser context on the CDP side. For the default context, the underlying CDP connection is also closed.

await context.close()

Returns Promise<void> Calling close() more than once is safe — subsequent calls are no-ops.

@handstage/core

@handstage/agent

V3Context — browser context API reference

Page management

`context.newPage`

`context.pages`

`context.activePage`

`context.setActivePage`

`context.awaitActivePage`

`context.cookies`

`context.addCookies`

`CookieParam` type

`context.clearCookies`

`ClearCookieOptions` type

Scripts and headers

`context.addInitScript`

`context.setExtraHTTPHeaders`

Context lifecycle

`context.createBrowserContext`

`CreateContextOptions` type

`context.close`

Build docs developers (and LLMs) love

@handstage/core

@handstage/agent

Documentation Index

​Page management

​context.newPage

​context.pages

​context.activePage

​context.setActivePage

​context.awaitActivePage

​Cookie management

​context.cookies

​Cookie type

​context.addCookies

​CookieParam type

​context.clearCookies

​ClearCookieOptions type

​Scripts and headers

​context.addInitScript

​context.setExtraHTTPHeaders

​Context lifecycle

​context.createBrowserContext

​CreateContextOptions type

​context.close

Build docs developers (and LLMs) love

Page management

`context.newPage`

`context.pages`

`context.activePage`

`context.setActivePage`

`context.awaitActivePage`

Cookie management

`context.cookies`

`Cookie` type

`context.addCookies`

`CookieParam` type

`context.clearCookies`

`ClearCookieOptions` type

Scripts and headers

`context.addInitScript`

`context.setExtraHTTPHeaders`

Context lifecycle

`context.createBrowserContext`

`CreateContextOptions` type

`context.close`