page

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto(url: string, options?: GotoOptions): Promise<Response | null>

await page.reload(options?: ReloadOptions): Promise<Response | null>

await page.goBack(options?: NavigationOptions): Promise<Response | null>

await page.goForward(options?: NavigationOptions): Promise<Response | null>

page.url(): string

await page.title(): Promise<string>

await page.click(x: number, y: number, options?: ClickOptions): Promise<string>

await page.hover(x: number, y: number, options?: HoverOptions): Promise<string>

await page.scroll(x: number, y: number, deltaX: number, deltaY: number, options?: ScrollOptions): Promise<string>

const [fromXpath, toXpath] = await page.dragAndDrop(fromX, fromY, toX, toY, options?)

await page.type(text: string, options?: TypeOptions): Promise<void>

await page.keyPress(key: string, options?: KeyPressOptions): Promise<void>

page.locator(selector: string): Locator

await page.evaluate<R, Arg>(
  pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>),
  arg?: Arg
): Promise<R>

await page.addInitScript<Arg>(
  script: string | { path?: string; content?: string } | ((arg: Arg) => unknown),
  arg?: Arg,
): Promise<void>

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const context = stagehand.context;
const page = await context.awaitActivePage();

await page.addInitScript(() => {
  window.Math.random = () => 42;
});

await page.goto("https://example.com", { waitUntil: "load" });

const result = await page.evaluate(() => Math.random());
console.log("Math.random() returned:", result);

// Math.random() returned: 42

await page.setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = stagehand.context.pages()[0];

// Set custom headers for all requests from this page
await page.setExtraHTTPHeaders({
  "X-Custom-Token": "my-secret-token",
  "Accept-Language": "en-US",
});

// All subsequent requests from this page will include these headers
await page.goto("https://example.com");

await page.screenshot(options?: ScreenshotOptions): Promise<Buffer>

await page.snapshot(options?: PageSnapshotOptions): Promise<SnapshotResult>

[0-1] RootWebArea: Example Domain
  [0-3] heading: Example Domain
  [0-5] paragraph: This domain is for use in illustrative examples in documents.
  [0-8] link: More information...

const page = stagehand.context.pages()[0];
await page.goto("https://example.com");

const { formattedTree, xpathMap, urlMap } = await page.snapshot();

// Print the accessibility tree
console.log(formattedTree);

// Look up a specific element's XPath by encoded ID
const linkId = "0-8";
console.log(xpathMap[linkId]); // e.g., "/html/body/div/p[2]/a"

// Resolve a link's URL via the urlMap
console.log(urlMap[linkId]); // e.g., "https://www.example.com"

// Exclude iframe content when you only need the main document
const mainDocumentSnapshot = await page.snapshot({ includeIframes: false });

await page.listWebMCPTools(options?: WebMCPListToolsOptions): Promise<WebMCPTool[]>

await page.invokeWebMCPTool(
  toolName: string,
  input: Record<string, unknown>,
  options?: WebMCPToolInvocationOptions,
): Promise<WebMCPToolInvocation>

const tools = await page.listWebMCPTools();
const calculateSum = tools.find((tool) => tool.name === "calculateSum");

if (!calculateSum) {
  throw new Error("calculateSum was not registered on this page");
}

const invocation = await page.invokeWebMCPTool(
  "calculateSum",
  { a: 19, b: 23 },
  { frameId: calculateSum.frameId, timeoutMs: 5_000 },
);

const result = await invocation.result;
console.log(result.status); // "Completed"
console.log(result.output); // { a: 19, b: 23, sum: 42 }

const invocation = await page.invokeWebMCPTool(
  "longRunningTool",
  {},
  { frameId: tool.frameId },
);

await invocation.cancel();
const result = await invocation.result;
console.log(result.status); // "Canceled"

await page.setViewportSize(
  width: number,
  height: number,
  options?: ViewportOptions
): Promise<void>

await page.waitForLoadState(state: LoadState, timeoutMs?: number): Promise<void>

await page.waitForSelector(
  selector: string,
  options?: {
    state?: "attached" | "detached" | "visible" | "hidden";
    timeout?: number;
    pierceShadow?: boolean;
  }
): Promise<boolean>

import type { ConsoleMessage } from "@browserbasehq/stagehand";

const handleConsole = (message: ConsoleMessage) => {
  console.log(`[${message.type()}] ${message.text()}`);
  console.log("Arguments:", message.args());
  const location = message.location();
  if (location?.url) {
    console.log(`Emitted from ${location.url}:${location.lineNumber ?? 0}`);
  }
};

page.on("console", handleConsole);

page.once("console", (message) => {
  console.log("First console message:", message.text());
});

page.off("console", handleConsole);

type LoadState = "load" | "domcontentloaded" | "networkidle";

type AnyPage = PlaywrightPage | PuppeteerPage | PatchrightPage | Page;

interface ScreenshotClip {
  x: number;
  y: number;
  width: number;
  height: number;
}

interface ScreenshotOptions {
  fullPage?: boolean;
  clip?: ScreenshotClip;
  type?: "png" | "jpeg";
  quality?: number;
  scale?: "css" | "device";
  animations?: "allow" | "disabled";
  caret?: "hide" | "initial";
  mask?: Locator[];
  maskColor?: string;
  style?: string;
  omitBackground?: boolean;
  timeout?: number;
  path?: string;
}

type PageSnapshotOptions = {
  includeIframes?: boolean;
};

type SnapshotResult = {
  formattedTree: string;
  xpathMap: Record<string, string>;
  urlMap: Record<string, string>;
};

type WebMCPTool = {
  name: string;
  description?: string;
  inputSchema?: string | Record<string, unknown>;
  annotations?: Record<string, unknown>;
  frameId: string;
};

type WebMCPToolInvocationStatus = "Completed" | "Canceled" | "Error";

type WebMCPToolResult = {
  invocationId: string;
  status: WebMCPToolInvocationStatus;
  output?: unknown;
  errorText?: string;
  exception?: unknown;
};

type WebMCPToolInvocation = {
  invocationId: string;
  toolName: string;
  frameId: string;
  result: Promise<WebMCPToolResult>;
  cancel: () => Promise<void>;
};

type WebMCPListToolsOptions = {
  timeoutMs?: number;
};

type WebMCPToolInvocationOptions = {
  frameId?: string;
  timeoutMs?: number;
};

try {
  await page.goto("https://example.com");
} catch (error) {
  console.error("Navigation failed:", error.message);
}