jevrun/README.md

Run natural-language browser tasks on a Playwright page using Jev decisions.

# jevrun

A TypeScript npm package with one runtime export: `run(page, prompt)`. Developed and tested with Bun; built JavaScript runs on Node.js 22+ or Bun.

```sh
npm install jevrun playwright
npx playwright install chromium
export TYPESAFE_API_KEY="your-key"
```

```ts
import { chromium } from "playwright";
import { run } from "jevrun";

const browser = await chromium.launch();
try {
  const page = await browser.newPage();
  await page.goto("https://your-app.example/profile");
  const result = await run(page, 'Fill Name with "Ada Lovelace" and click Save');
  console.log(result.steps);
} finally {
  await browser.close();
}
```

## How it works

1. Capture `page.locator("body").ariaSnapshot({ mode: "ai" })`.
2. Send the snapshot, prompt, and successful action history to Jev. Each snapshot element reference becomes an option in a **Choice** question, alongside `done` and `blocked`.
3. Resolve the chosen element with `page.locator("aria-ref=e…")` and ask a second Choice question about the available actions on it.
4. Execute the selected Playwright action, capture a fresh snapshot, and repeat until Jev selects `done` or a limit/error stops the run.

The integration uses the official `@typesafe-ai/sdk` client (`TypeSafeClient.systemOne` and `choice`). SDK authentication, transport, timeouts, and API errors are used directly. Automatic retries are disabled to keep each decision within its configured timeout.

Jev makes typed decisions; it does not generate Playwright code or free-form text. Put exact values to enter in straight or curly quotes in your prompt. Native select options come from the page. Supported actions: click, fill, press Enter on editable fields, check, uncheck, and select an option.

## Options and result

```ts
await run(page, 'Enter "Ada" in Name', {
  apiKey: process.env.TYPESAFE_API_KEY,
  model: "jev-latest",
  maxSteps: 10,
  minConfidence: 0.7,
  timeoutMs: 30_000,
});
```

All options are optional; values above are the defaults. Returns `{ status: "completed", steps: [{ action, confidence }] }`. Step confidence is the minimum of target and action confidence. Completion is Jev's judgment; use your own Playwright assertions for critical postconditions.

Throws on missing credentials, invalid/low-confidence decisions, blocked tasks, HTTP failures, Playwright failures, or step exhaustion. Already executed actions are not rolled back. `timeoutMs` applies per API request and browser operation, not to the entire run. The caller owns navigation, page, and browser lifecycle. Concurrent runs on the same page are rejected; do not manipulate that page concurrently.

## Initial scope

Requires Playwright 1.59+ for AI snapshots. Operates on the current page's main frame and its open shadow DOM. Iframes, new tabs, dialogs, uploads, arbitrary navigation, generated text, and long-running background transitions need additional support. Detached/stale references fail through Playwright rather than falling back to a different target.

There are at most 253 element choices, 254 actions per element, 40,000 snapshot characters, and 10,000 prompt characters. Larger inputs fail explicitly. This is an initial implementation, not a general-purpose browser agent.

Prompts, snapshots, selected-element metadata, and action history are sent to TypeSafe's hosted API. Action history may contain entered values. Use only pages and data you intend to send to that service.

## Development

```sh
bun install
bunx playwright install chromium
bun run typecheck
bun test
bun run build
bun run test:package
bun run examples/basic.ts # requires TYPESAFE_API_KEY
```

Tests use a real Chromium browser and mocked Jev responses, without API credentials. The build emits ESM, CommonJS, and matching TypeScript declarations into `dist`; Bun is not a runtime dependency. `test:package` verifies Node.js can load both package entry points. CommonJS Playwright projects can use `import { run } from "jevrun"` in TypeScript or `const { run } = require("jevrun")` in JavaScript.

References: [Jev introduction](https://docs.typesafe.ai/introduction), [Choice API](https://docs.typesafe.ai/primitives/choice), [HTTP quick start](https://docs.typesafe.ai/introduction/quickstart), [Playwright AI snapshots](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).