.cursorrules

# Stagehand Project

This is a project that uses Stagehand, which amplifies Playwright with `act`, `extract`, and `observe` added to the Page class.

`Stagehand` is a class that provides config, a `StagehandPage` object via `stagehand.page`, and a `StagehandContext` object via `stagehand.context`.

`Page` is a class that extends the Playwright `Page` class and adds `act`, `extract`, and `observe` methods.
`Context` is a class that extends the Playwright `BrowserContext` class.

Use the following rules to write code for this project.

- When writing Playwright code, wrap it with Stagehand `act`
- When writing code that needs to extract data from the page, use Stagehand `extract`
- When writing code that needs to observe the page, use Stagehand `observe`

## Initialize

```typescript
import { Stagehand } from "@browserbasehq/stagehand";
import StagehandConfig from "./stagehand.config";

const stagehand = new Stagehand(StagehandConfig);
await stagehand.init();

const page = stagehand.page; // Playwright Page with act, extract, and observe methods
const context = stagehand.context; // Playwright BrowserContext
```

## Act

For example, if you are writing Playwright code, wrap it with Stagehand `act` like this:

```typescript
try {
  await page.locator('button[name="Sign in"]').click();
} catch (error) {
  await page.act({
    action: "click the sign in button",
  });
}
```

Act `action` should be as atomic and specific as possible, i.e. "Click the sign in button" or "Type 'hello' into the search input". Avoid actions that are too broad, i.e. "Order me pizza" or "Send an email to Paul asking him to call me". Actions work best for Playwright code that is vulnerable to unexpected DOM changes.

When using `act`, write Playwright code FIRST, then wrap it with a try-catch block where the catch block is `act`.

## Extract

If you are writing code that needs to extract data from the page, use Stagehand `extract` like this:

```typescript
const data = await page.extract({
  instruction: "extract the sign in button text",
  schema: z.object({
    text: z.string(),
  }),
  useTextExtract: true,
});
```

`schema` is a Zod schema that describes the data you want to extract. To extract an array, make sure to pass in a single object that contains the array, as follows:

```typescript
const data = await page.extract({
  instruction: "extract the text inside all buttons",
  schema: z.object({
    text: z.array(z.string()),
  }),
});
```

Set `useTextExtract` to `true` for better results.

## Observe

If you are writing code that needs to observe the page, use Stagehand `observe` like this:

```typescript
const data = await page.observe({
  instruction: "observe the page",
});
```

This returns a list of XPaths and descriptions of the data you want to extract as `{ selector: string; description: string }[]`.