Compare commits

...

9 Commits

Author SHA1 Message Date
Sean McGuire
d7103c28ac fix double log 2026-05-28 18:05:30 -07:00
Sean McGuire
95bbec6152 wire up flowlogger 2026-05-28 17:58:12 -07:00
Sean McGuire
dfe0e0760f add try catch in example 2026-05-28 17:57:40 -07:00
Sean McGuire
0cf3797b62 update example 2026-05-28 17:52:22 -07:00
Sean McGuire
97976fbd16 changeset 2026-05-28 17:43:11 -07:00
Sean McGuire
ef73d9d461 add test 2026-05-28 17:41:52 -07:00
Sean McGuire
bda575069f rename copySelection to copy 2026-05-28 17:16:15 -07:00
Sean McGuire
74d41f010e example 2026-05-28 16:44:52 -07:00
Sean McGuire
f46cc2b4bb wip 2026-05-28 16:44:46 -07:00
7 changed files with 350 additions and 0 deletions

View File

@ -0,0 +1,5 @@
---
"@browserbasehq/stagehand": minor
---
add native clipboard API

View File

@ -0,0 +1,37 @@
import { Stagehand } from "../lib/v3/index.js";
async function example(stagehand: Stagehand) {
const page = stagehand.context.pages()[0];
await page.goto("https://example.com");
await new Promise((resolve) => setTimeout(resolve, 3000));
await page.evaluate(() => {
document.body.innerHTML =
"<textarea autofocus style='width:400px;height:120px'></textarea>";
document.querySelector("textarea")?.focus();
});
await stagehand.context.clipboard.writeText("Hello from Stagehand");
await stagehand.context.clipboard.paste();
await page.keyPress("ControlOrMeta+A");
await stagehand.context.clipboard.copy();
const copied = await stagehand.context.clipboard.readText();
console.log(copied);
await stagehand.context.clipboard.clear();
}
(async () => {
const stagehand = new Stagehand({
env: "BROWSERBASE",
model: "openai/gpt-5",
verbose: 2,
});
try {
await stagehand.init();
await example(stagehand);
} finally {
await stagehand.close();
}
})();

View File

@ -0,0 +1,19 @@
import type { Page } from "../../understudy/page.js";
export interface ClipboardOptions {
page?: Page;
timeout?: number;
}
export interface ClipboardPasteOptions extends ClipboardOptions {
shortcut?: "ControlOrMeta+V" | "Meta+V" | "Control+V";
}
export interface BrowserClipboard {
readText(options?: ClipboardOptions): Promise<string>;
writeText(text: string, options?: ClipboardOptions): Promise<void>;
clear(options?: ClipboardOptions): Promise<void>;
paste(options?: ClipboardPasteOptions): Promise<void>;
copy(options?: ClipboardOptions): Promise<void>;
cut(options?: ClipboardOptions): Promise<void>;
}

View File

@ -5,6 +5,7 @@ export * as Api from "./api.js";
// Also export BrowserbaseRegion directly for convenience
export type { BrowserbaseRegion } from "./api.js";
export * from "./apiErrors.js";
export * from "./clipboard.js";
export * from "./logs.js";
export * from "./methods.js";
export * from "./metrics.js";

View File

@ -0,0 +1,144 @@
import type { Protocol } from "devtools-protocol";
import type { V3Context } from "./context.js";
import type { Page } from "./page.js";
import type {
BrowserClipboard,
ClipboardOptions,
ClipboardPasteOptions,
} from "../types/public/clipboard.js";
import { StagehandEvalError } from "../types/public/sdkErrors.js";
import { FlowLogger } from "../flowlogger/FlowLogger.js";
type ContextClipboardParams = {
context: V3Context;
resolvePage: (page?: Page) => Promise<Page>;
};
export class ContextClipboard implements BrowserClipboard {
constructor(private readonly params: ContextClipboardParams) {}
@FlowLogger.wrapWithLogging({ eventType: "ClipboardWriteText" })
async writeText(text: string, options?: ClipboardOptions): Promise<void> {
await this.writeTextInternal(text, options);
}
private async writeTextInternal(
text: string,
options?: ClipboardOptions,
): Promise<void> {
const page = await this.resolvePage(options?.page);
await this.ensurePageFocused(page);
await this.grantClipboardPermissions(page);
await page.sendCDP("Runtime.enable").catch(() => {});
const response = await page.sendCDP<Protocol.Runtime.EvaluateResponse>(
"Runtime.evaluate",
{
expression: `navigator.clipboard.writeText(${JSON.stringify(text)})`,
awaitPromise: true,
returnByValue: true,
userGesture: true,
},
);
this.throwIfEvaluationFailed("write clipboard text", response);
}
@FlowLogger.wrapWithLogging({ eventType: "ClipboardReadText" })
async readText(options?: ClipboardOptions): Promise<string> {
const page = await this.resolvePage(options?.page);
await this.ensurePageFocused(page);
await this.grantClipboardPermissions(page);
await page.sendCDP("Runtime.enable").catch(() => {});
const response = await page.sendCDP<Protocol.Runtime.EvaluateResponse>(
"Runtime.evaluate",
{
expression: "navigator.clipboard.readText()",
awaitPromise: true,
returnByValue: true,
userGesture: true,
},
);
this.throwIfEvaluationFailed("read clipboard text", response);
return String(response.result?.value ?? "");
}
@FlowLogger.wrapWithLogging({ eventType: "ClipboardClear" })
async clear(options?: ClipboardOptions): Promise<void> {
await this.writeTextInternal("", options);
}
@FlowLogger.wrapWithLogging({ eventType: "ClipboardPaste" })
async paste(options?: ClipboardPasteOptions): Promise<void> {
const page = await this.resolvePage(options?.page);
await this.ensurePageFocused(page);
await page.keyPress(options?.shortcut ?? "ControlOrMeta+V");
}
@FlowLogger.wrapWithLogging({ eventType: "ClipboardCopy" })
async copy(options?: ClipboardOptions): Promise<void> {
const page = await this.resolvePage(options?.page);
await this.ensurePageFocused(page);
await page.keyPress("ControlOrMeta+C");
}
@FlowLogger.wrapWithLogging({ eventType: "ClipboardCut" })
async cut(options?: ClipboardOptions): Promise<void> {
const page = await this.resolvePage(options?.page);
await this.ensurePageFocused(page);
await page.keyPress("ControlOrMeta+X");
}
private async resolvePage(page?: Page): Promise<Page> {
return await this.params.resolvePage(page);
}
private async grantClipboardPermissions(page: Page): Promise<void> {
const origin = this.originForPage(page);
if (!origin) return;
await this.params.context.conn
.send("Browser.grantPermissions", {
origin,
permissions: ["clipboardReadWrite", "clipboardSanitizedWrite"],
})
.catch(() => {});
}
private async ensurePageFocused(page: Page): Promise<void> {
this.params.context.setActivePage(page);
await page.sendCDP("Page.bringToFront").catch(() => {});
await page.sendCDP("Runtime.enable").catch(() => {});
await page
.sendCDP("Runtime.evaluate", {
expression: "window.focus()",
awaitPromise: true,
userGesture: true,
})
.catch(() => {});
}
private originForPage(page: Page): string | undefined {
try {
const parsed = new URL(page.url());
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
return undefined;
}
return parsed.origin;
} catch {
return undefined;
}
}
private throwIfEvaluationFailed(
operation: string,
response: Protocol.Runtime.EvaluateResponse,
): void {
if (!response.exceptionDetails) return;
const message =
response.exceptionDetails.exception?.description ??
response.exceptionDetails.text ??
"Runtime.evaluate failed";
throw new StagehandEvalError(`Failed to ${operation}: ${message}`);
}
}

View File

@ -8,8 +8,10 @@ import { v3ScriptContent } from "../dom/build/scriptV3Content.js";
import { executionContexts } from "./executionContextRegistry.js";
import type { StagehandAPIClient } from "../api.js";
import { LocalBrowserLaunchOptions } from "../types/public/index.js";
import type { BrowserClipboard } from "../types/public/clipboard.js";
import { InitScriptSource } from "../types/private/index.js";
import { normalizeInitScriptSource } from "./initScripts.js";
import { ContextClipboard } from "./clipboard.js";
import {
TimeoutError,
CookieSetError,
@ -124,6 +126,7 @@ export class V3Context {
private pendingCreatedTargetUrl = new Map<TargetId, string>();
private readonly initScripts: string[] = [];
private extraHttpHeaders: Record<string, string> | null = null;
private _clipboard?: ContextClipboard;
private installTargetSessionListeners(session: CDPSessionLike): void {
const sessionId = session.id;
@ -422,6 +425,18 @@ export class V3Context {
}
}
public get clipboard(): BrowserClipboard {
return (this._clipboard ??= new ContextClipboard({
context: this,
resolvePage: async (page) => {
if (page) return page;
const active = this.activePage();
if (!active) throw new PageNotFoundError("active page");
return active;
},
}));
}
/**
* Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
*/

View File

@ -0,0 +1,129 @@
import { test, expect } from "@playwright/test";
import { V3 } from "../../lib/v3/v3.js";
import type { Page } from "../../lib/v3/types/public/page.js";
import { v3DynamicTestConfig } from "./v3.dynamic.config.js";
import { closeV3 } from "./testUtils.js";
const TEST_URL =
"https://browserbase.github.io/stagehand-eval-sites/sites/example/";
async function setupTextarea(
page: Page,
options: { id: string; value?: string },
): Promise<void> {
await page.goto(TEST_URL, {
waitUntil: "domcontentloaded",
timeoutMs: 15000,
});
await page.evaluate(({ id, value }) => {
document.body.innerHTML = `<textarea id="${id}" style="width:400px;height:120px"></textarea>`;
const el = document.getElementById(id) as HTMLTextAreaElement;
el.value = value ?? "";
el.focus();
}, options);
}
async function textareaValue(page: Page, id: string): Promise<string> {
return await page.evaluate(
(selector) =>
(document.querySelector(selector) as HTMLTextAreaElement).value,
`#${id}`,
);
}
async function selectTextareaContents(page: Page, id: string): Promise<void> {
await page.evaluate((selector) => {
const el = document.querySelector(selector) as HTMLTextAreaElement;
el.focus();
el.setSelectionRange(0, el.value.length);
}, `#${id}`);
}
test.describe("context.clipboard", () => {
let v3: V3;
test.beforeEach(async () => {
v3 = new V3(v3DynamicTestConfig);
await v3.init();
});
test.afterEach(async () => {
await closeV3(v3);
});
test("writeText() then readText()", async () => {
const page = await v3.context.awaitActivePage();
await setupTextarea(page, { id: "target" });
await v3.context.clipboard.writeText("hello");
await expect(v3.context.clipboard.readText()).resolves.toBe("hello");
});
test("paste() inserts clipboard text into the focused textarea", async () => {
const page = await v3.context.awaitActivePage();
await setupTextarea(page, { id: "target" });
await v3.context.clipboard.writeText("hello");
await v3.context.clipboard.paste();
await expect(textareaValue(page, "target")).resolves.toBe("hello");
});
test("copy() copies selected textarea text", async () => {
const page = await v3.context.awaitActivePage();
await setupTextarea(page, { id: "target", value: "copy me" });
await selectTextareaContents(page, "target");
await v3.context.clipboard.copy();
await expect(v3.context.clipboard.readText()).resolves.toBe("copy me");
});
test("cut() cuts selected textarea text and updates clipboard", async () => {
const page = await v3.context.awaitActivePage();
await setupTextarea(page, { id: "target", value: "cut me" });
await selectTextareaContents(page, "target");
await v3.context.clipboard.cut();
await expect(v3.context.clipboard.readText()).resolves.toBe("cut me");
await expect(textareaValue(page, "target")).resolves.toBe("");
});
test("defaults actions to the active page", async () => {
const page1 = await v3.context.awaitActivePage();
await setupTextarea(page1, { id: "first" });
const page2 = await v3.context.newPage();
await setupTextarea(page2, { id: "second" });
v3.context.setActivePage(page2);
await v3.context.clipboard.writeText("active page text");
await v3.context.clipboard.paste();
await expect(textareaValue(page1, "first")).resolves.toBe("");
await expect(textareaValue(page2, "second")).resolves.toBe(
"active page text",
);
});
test("accepts an explicit page option for page-targeted actions", async () => {
const page1 = await v3.context.awaitActivePage();
await setupTextarea(page1, { id: "first" });
const page2 = await v3.context.newPage();
await setupTextarea(page2, { id: "second" });
await v3.context.clipboard.writeText("explicit page text", {
page: page1,
});
v3.context.setActivePage(page2);
await v3.context.clipboard.paste({ page: page1 });
await expect(textareaValue(page1, "first")).resolves.toBe(
"explicit page text",
);
await expect(textareaValue(page2, "second")).resolves.toBe("");
});
});