Skip to content

Lightpanda: the headless browser designed for AI and automation

script: introduce Page API with async goto

Adrià Arrufat21477b39c9e1
diff --git a/docs/agent-script.md b/docs/agent-script.md
index c27e22d9b..5048faf35 100644
--- a/docs/agent-script.md
+++ b/docs/agent-script.md
@@ -1,10 +1,10 @@
# Agent JavaScript scripts
`lightpanda agent <script.js>` runs a JavaScript file that drives a
-Lightpanda browser session through a small set of blocking global functions.
-The format is intentionally plain JavaScript: use normal variables, functions,
-loops, objects, arrays, `JSON.parse`, `JSON.stringify`, and other standard
-ECMAScript built-ins.
+Lightpanda browser session through a small object-oriented API. The format is
+intentionally plain JavaScript: use normal variables, functions, loops,
+objects, arrays, `JSON.parse`, `JSON.stringify`, and other standard ECMAScript
+built-ins.
```console
./lightpanda agent session.js
@@ -19,31 +19,37 @@ an LLM.
Agent scripts run in their own V8 context. That context is separate from the
web page's JavaScript context.
+- `Page` is the only global. `new Page()` makes a page object and
+ `await page.goto(url)` navigates it; every other primitive is a **method on
+ that page**: `const page = new Page(); await page.goto(url);
+ page.extract({...}); page.click(sel);`.
- It is not the browser page environment. There is no `window`, `document`,
DOM, `localStorage`, `navigator`, or page global state in the agent script.
- Read page data with `extract(...)`, or explicitly run page JavaScript with
- `evaluate(...)` when that is the right tool.
+ Read page data with `page.extract(...)`, or explicitly run page JavaScript
+ with `page.evaluate(...)` when that is the right tool.
- It is not Node.js. There is no `require`, `process`, `fs`, `path`, npm
package loading, command-line argument API, or Node network/filesystem API.
- Page scripts cannot see agent variables or Lightpanda primitives. Agent
scripts cannot directly see page variables.
-- The global `evaluate(...)` primitive runs JavaScript in the page context,
+- The `page.evaluate(...)` method runs JavaScript in the page context,
distinct from the agent context's own native `eval`.
- Agent variables persist for the lifetime of one script run, across
navigations and primitive calls. A later `lightpanda agent script.js` run
starts with a fresh agent context.
-- The installed primitives are synchronous and blocking. Do not write an
- `async`/`await` automation contract around them. Scripts compile as classic
- scripts, so top-level `await` is a `SyntaxError`; promise callbacks
- (`.then`) only run after the script body finishes, never in between
- primitive calls.
+- `page.goto(...)` is **async — always `await` it**. Every other page method
+ is **synchronous**: write `const data = page.extract({...})`, never
+ `await page.extract(...)`. The script body runs as an async function, so
+ top-level `await` is allowed.
+- **Re-navigating reuses the same page.** `await page.goto(url2)` keeps `page`
+ valid and points it at the new URL. Work through one page at a time and read
+ it before navigating away.
- Tool failures throw JavaScript `Error` exceptions and stop execution unless
you catch them.
-- The script's completion value — its last top-level expression — is printed
- automatically (objects and arrays as JSON; other values coerced). End a
- script with the bare expression you want as output, e.g. a final
- `extract({ ... });` or `results;`. `console.log(...)` is for extra or debug
- output and does not JSON-format objects.
+- **`return <value>` is the script's output**, printed automatically (objects
+ and arrays as JSON; other values coerced). End a script with the value you
+ want as output, e.g. `return page.extract({ ... });` or `return results;`. A
+ bare trailing expression is NOT printed, and neither is
+ `console.log(JSON.stringify(...))`.
The agent context includes a small `console` object:
@@ -57,16 +63,17 @@ console.error("printed to stderr");
## Values And Return Types
-Most primitives return the browser tool's result text as a JavaScript string.
-`extract(...)` is the exception: it returns extracted data as a normal
-JavaScript value, so local script logic can use it directly. The result mirrors
-your schema — an object schema returns an object keyed by your fields (even with
-a single field), and a bare array schema returns an array:
+Most page methods return the browser tool's result text as a JavaScript
+string. `page.extract(...)` is the exception: it returns extracted data as a
+normal JavaScript value, so local script logic can use it directly. The result
+mirrors your schema — an object schema returns an object keyed by your fields
+(even with a single field), and a bare array schema returns an array:
```js
-goto("https://news.ycombinator.com/");
+const page = new Page();
+await page.goto("https://news.ycombinator.com/");
-const data = extract({
+const data = page.extract({
title: "title",
stories: [{
selector: "tr.athing",
@@ -78,13 +85,13 @@ const data = extract({
}]
});
-data; // printed automatically as JSON
+return data; // printed automatically as JSON
```
Destructure when a single field is all you need:
```js
-const { stories } = extract({
+const { stories } = page.extract({
stories: [{
selector: "tr.athing",
limit: 5,
@@ -100,52 +107,56 @@ for (const story of stories) {
}
```
-`evaluate(...)` still returns the page evaluate tool result text. When page `evaluate(...)`
-returns an object or array, that text is JSON.
+`page.evaluate(...)` returns the page evaluate tool result text. When page
+`evaluate(...)` returns an object or array, that text is JSON.
Primitive arguments must be JSON-serializable. Strings, numbers, booleans,
arrays, plain objects, and `null` work. `undefined`, functions, symbols, and
cyclic objects do not.
-## Installed Primitives
-
-Only recorded browser primitives are installed globally:
-
-| Primitive | Arguments | Runs in |
-|-----------|-----------|---------|
-| `goto` | `goto(url[, { timeout }])` | Browser session |
-| `extract` | `extract(schema)` or `extract({ schema })` | Browser page via extractor; returns a JS object or array |
-| `evaluate` | `evaluate(script[, { url, timeout, save }])` | Browser page JS context |
-| `click` | `click(selector)` or `click({ selector })` | Browser page |
-| `fill` | `fill(selector, value)` or `fill({ selector, value })` | Browser page |
-| `scroll` | `scroll()` or `scroll({ x, y })` | Browser page |
-| `waitForSelector` | `waitForSelector(selector[, { timeout }])` | Browser page |
-| `waitForScript` | `waitForScript(script[, { timeout }])` | Browser page JS context |
-| `waitForState` | `waitForState(state[, { timeout }])` | Browser page |
-| `hover` | `hover(selector)` or `hover({ selector })` | Browser page |
-| `press` | `press(selector, key)` or `press({ key[, selector] })` | Browser page |
-| `selectOption` | `selectOption(selector, value)` or `selectOption({ selector, value })` | Browser page |
-| `setChecked` | `setChecked(selector[, checked])` or `setChecked({ selector, checked })` | Browser page |
-
-`goto` returns at the `load` event (a fast snapshot). When a page's content is
-still loading (rendered by post-load JS), call `waitForState("networkidle")`
-before reading. `waitForState`'s `state` accepts `"load"`,
-`"domcontentloaded"`, `"networkalmostidle"`, `"networkidle"`, or `"done"`.
-`goto`'s `timeout` defaults to 10000 ms; the `waitFor*` timeouts default to
-5000 ms.
+## The Page object
+
+`Page` is the only global. `new Page()` makes a page object; everything else is
+a method on it. Call `Page(...)` without `new` and you get
+`Page must be called with new`.
+
+| Method | Arguments | Runs in |
+|--------|-----------|---------|
+| `new Page()` | — | Makes a page object. No navigation yet — call `page.goto(url)` before any other method. |
+| `page.goto` | `goto(url[, { timeout }])` | **Async — must be `await`ed.** Navigates the page (re-navigating reuses the same object). |
+| `page.close` | `close()` | Marks the page done; later method calls on it error. The page is otherwise reclaimed at script end. |
+| `page.extract` | `extract(schema)` or `extract({ schema })` | Browser page via extractor; returns a JS object or array |
+| `page.evaluate` | `evaluate(script[, { url, timeout, save }])` | Browser page JS context |
+| `page.click` | `click(selector)` or `click({ selector })` | Browser page |
+| `page.fill` | `fill(selector, value)` or `fill({ selector, value })` | Browser page |
+| `page.scroll` | `scroll()` or `scroll({ x, y })` | Browser page |
+| `page.waitForSelector` | `waitForSelector(selector[, { timeout }])` | Browser page |
+| `page.waitForScript` | `waitForScript(script[, { timeout }])` | Browser page JS context |
+| `page.waitForState` | `waitForState(state[, { timeout }])` | Browser page |
+| `page.hover` | `hover(selector)` or `hover({ selector })` | Browser page |
+| `page.press` | `press(selector, key)` or `press({ key[, selector] })` | Browser page |
+| `page.selectOption` | `selectOption(selector, value)` or `selectOption({ selector, value })` | Browser page |
+| `page.setChecked` | `setChecked(selector[, checked])` or `setChecked({ selector, checked })` | Browser page |
+
+`page.goto` returns at the `load` event (a fast snapshot). When a page's
+content is still loading (rendered by post-load JS), call
+`page.waitForState("networkidle")` before reading. `waitForState`'s `state`
+accepts `"load"`, `"domcontentloaded"`, `"networkalmostidle"`,
+`"networkidle"`, `"done"`. `goto`'s `timeout` defaults to 10000 ms; the
+`waitFor*` timeouts default to 5000 ms.
The `[, { … }]` is an optional trailing options object: leading arguments are
-positional (`waitForSelector("#row", { timeout: 2000 })`), and the options ride
-in a final object. Passing a single object with everything
-(`waitForSelector({ selector: "#row", timeout: 2000 })`) is equivalent — that's
-the shape `/save` records into saved scripts. An option can't be a bare
-positional, though: `waitForSelector("#row", 2000)` is an error. A `null`
-positional omits that field (`press(null, "Enter")` presses on the focused
-element), and setting the same field positionally and in the options object
-(`goto(url, { url: ... })`) is an `invalid arguments` error.
-
-Script primitives address elements by CSS selector only. The tools that hand
-out `backendNodeId`s (`tree`, `findElement`, `nodeDetails`) aren't installed in
+positional (`page.waitForSelector("#row", { timeout: 2000 })`), and the
+options ride in a final object. Passing a single object with everything
+(`page.waitForSelector({ selector: "#row", timeout: 2000 })`) is equivalent —
+that's the shape `/save` records into saved scripts. An option can't be a bare
+positional, though: `page.waitForSelector("#row", 2000)` is an error. A `null`
+positional omits that field (`page.press(null, "Enter")` presses on the
+focused element), and setting the same field positionally and in the options
+object (`page.goto(url, { url: ... })`) is an `invalid arguments` error.
+
+Page methods address elements by CSS selector only. The tools that hand out
+`backendNodeId`s (`tree`, `findElement`, `nodeDetails`) aren't installed in
the script context, and a raw node ID wouldn't survive replay anyway. When
you're exploring in the REPL and have a `backendNodeId` — e.g. the leading
number on a `/tree` line, or a `/findElement` hit — run `/nodeDetails
@@ -154,31 +165,37 @@ script.
## Navigation
-Use `goto(...)` to open a page:
+Use `page.goto(...)` to open a page. It is the only async method, so always
+`await` it:
```js
-goto("https://example.com");
+const page = new Page();
+await page.goto("https://example.com");
-goto({
+await page.goto({
url: "https://example.com/app",
timeout: 15000
});
```
+Re-navigating reuses the same page object: a later `await page.goto(url2)`
+keeps `page` valid and points it at the new URL. Read a page before navigating
+away from it.
+
The call returns a status string and throws if navigation fails. A timeout
does **not** throw: the call returns `"Navigation started but the page did not
finish loading before the timeout."` and the page stays in whatever state it
-reached. Check the return value — or follow with `waitForState(...)` /
-`waitForSelector(...)` — when completeness matters.
+reached. Check the return value — or follow with `page.waitForState(...)` /
+`page.waitForSelector(...)` — when completeness matters.
## Structured Extraction
-Use `extract(...)` to read data from the current page without writing page-side
-JavaScript. This is the preferred bridge from page content into local agent
-logic.
+Use `page.extract(...)` to read data from the current page without writing
+page-side JavaScript. This is the preferred bridge from page content into
+local agent logic.
```js
-const result = extract({
+const result = page.extract({
heading: "h1",
links: [{
selector: "a",
@@ -205,55 +222,58 @@ The schema forms are:
Return shape follows the top-level schema:
-- `extract({ title: "h1" })` returns `{ title: "..." }`.
-- `extract({ title: "h1", links: [{ selector: "a" }] })` returns an object
- with both fields.
-- `extract({ links: [{ selector: "a" }] })` returns `{ links: [...] }` — an
- object schema always returns an object, even with a single field.
-- `extract([{ selector: "a" }])` is shorthand for a single anonymous array
- extraction and returns the array directly.
+- `page.extract({ title: "h1" })` returns `{ title: "..." }`.
+- `page.extract({ title: "h1", links: [{ selector: "a" }] })` returns an
+ object with both fields.
+- `page.extract({ links: [{ selector: "a" }] })` returns `{ links: [...] }` —
+ an object schema always returns an object, even with a single field.
+- `page.extract([{ selector: "a" }])` is shorthand for a single anonymous
+ array extraction and returns the array directly.
Every value is a string (trimmed text or a raw attribute) or `null` — parse
numbers in script logic. An array field that matches nothing yields `[]`
without complaint (a page with zero comments is a valid result), but if
-*every* field in the schema misses, `extract(...)` throws
+*every* field in the schema misses, `page.extract(...)` throws
`no schema selector matched any element` — treat that as "my selectors are
wrong", not "the page is empty".
-`extract(...)` reads only the current page. For list-to-detail scraping —
+`page.extract(...)` reads only the current page. For list-to-detail scraping —
capture a list, then visit each row for more — capture the list, then loop in
-the script: `goto` each row's URL and `extract` the detail. The local agent
+the script: `await page.goto` each row's URL and `page.extract` the detail,
+reading each detail page before navigating to the next. The local agent
context keeps the data across navigations, so the assembly happens in plain
JavaScript. See the [complete example](#complete-example) below.
-When passing an object directly to `extract(...)`, the runtime serializes it as
-the extractor schema. These forms are equivalent:
+When passing an object directly to `page.extract(...)`, the runtime serializes
+it as the extractor schema. These forms are equivalent:
```js
-extract({ title: "h1" });
-extract({ schema: { title: "h1" } });
-extract('{ "title": "h1" }');
+page.extract({ title: "h1" });
+page.extract({ schema: { title: "h1" } });
+page.extract('{ "title": "h1" }');
```
The wrapped form accepts only `schema`: the REPL's `save=` option does not
-exist in scripts (`extract({ schema: ..., save: ... })` is rejected). Keep
-results in local variables instead.
+exist in scripts (`page.extract({ schema: ..., save: ... })` is rejected).
+Keep results in local variables instead.
Use local variables to keep extracted data available to later script logic:
```js
-const page = extract({ title: "title" });
+const head = page.extract({ title: "title" });
```
## Page JavaScript
-`evaluate(...)` is the explicit escape hatch into the current page's JavaScript
-context. Its script string runs where `window` and `document` exist.
+`page.evaluate(...)` is the explicit escape hatch into the current page's
+JavaScript context. Its script string runs where `window` and `document`
+exist.
```js
-goto("https://example.com");
+const page = new Page();
+await page.goto("https://example.com");
-const title = evaluate("document.title");
+const title = page.evaluate("document.title");
console.log(title);
```
@@ -263,52 +283,54 @@ Keep the boundary clear:
const selector = "h1";
// Good: local agent logic builds an extract schema.
-const data = extract({ heading: selector });
+const data = page.extract({ heading: selector });
// Bad: page evaluate cannot see local agent variables.
-evaluate("document.querySelector(selector).textContent");
+page.evaluate("document.querySelector(selector).textContent");
```
-Page `evaluate(...)` cannot call `goto`, `extract`, or other agent primitives.
+`page.evaluate(...)` cannot call `goto`, `extract`, or other agent primitives.
Agent scripts cannot access `document` directly. If you need page DOM data,
-prefer `extract(...)`; use `evaluate(...)` only for page behavior that extraction
-cannot express.
+prefer `page.extract(...)`; use `page.evaluate(...)` only for page behavior
+that extraction cannot express, and remember its state dies on every
+navigation/reload, while script variables persist.
-`waitForScript(...)` also evaluates in the page context, repeatedly, until the
-expression is truthy or the timeout expires:
+`page.waitForScript(...)` also evaluates in the page context, repeatedly,
+until the expression is truthy or the timeout expires:
```js
-waitForScript("document.querySelectorAll('.row').length >= 5");
+page.waitForScript("document.querySelectorAll('.row').length >= 5");
```
## Interaction Primitives
-The action primitives operate on the current page. Most take one object whose
+The action methods operate on the current page. Most take one object whose
fields match the browser tool schema:
```js
-click({ selector: "a.login" });
-fill({ selector: "input[name='acct']", value: "$LP_HN_USERNAME" });
-fill({ selector: "input[name='pw']", value: "$LP_HN_PASSWORD" });
-press({ key: "Enter" });
+page.click({ selector: "a.login" });
+page.fill({ selector: "input[name='acct']", value: "$LP_HN_USERNAME" });
+page.fill({ selector: "input[name='pw']", value: "$LP_HN_PASSWORD" });
+page.press({ key: "Enter" });
-waitForSelector("#logout");
+page.waitForSelector("#logout");
-hover({ selector: "#menu" });
-selectOption({ selector: "select[name='country']", value: "FR" });
-setChecked({ selector: "input[name='terms']", checked: true });
-setChecked({ selector: "input[name='newsletter']", checked: false });
+page.hover({ selector: "#menu" });
+page.selectOption({ selector: "select[name='country']", value: "FR" });
+page.setChecked({ selector: "input[name='terms']", checked: true });
+page.setChecked({ selector: "input[name='newsletter']", checked: false });
-scroll({ y: 600 });
-scroll();
+page.scroll({ y: 600 });
+page.scroll();
```
-`setChecked` defaults `checked` to `true` when the field is omitted
-(`setChecked("#chk")` checks the box). `press`'s leading positional is the
-optional `selector`, not `key`: a bare `press("Enter")` binds `"Enter"` to
-`selector` and fails. Press on the focused element with
-`press({ key: "Enter" })` or `press(null, "Enter")`; target an element with
-`press("#search", "Enter")` or `press({ key: "Enter", selector: "#search" })`.
+`page.setChecked` defaults `checked` to `true` when the field is omitted
+(`page.setChecked("#chk")` checks the box). `page.press`'s leading positional
+is the optional `selector`, not `key`: a bare `page.press("Enter")` binds
+`"Enter"` to `selector` and fails. Press on the focused element with
+`page.press({ key: "Enter" })` or `page.press(null, "Enter")`; target an
+element with `page.press("#search", "Enter")` or
+`page.press({ key: "Enter", selector: "#search" })`.
`$LP_*` placeholders in string arguments are resolved inside the Lightpanda
process. This keeps credentials out of recorded scripts and LLM prompts. In
@@ -327,16 +349,17 @@ The REPL remains slash-command based:
`/save` writes JavaScript by default:
```js
-goto("https://example.com");
-click({ selector: "a.login" });
+const page = new Page();
+await page.goto("https://example.com");
+page.click({ selector: "a.login" });
```
Only replayable browser actions are recorded:
- Recorded: `goto`, `click`, `fill`, `scroll`, `hover`, `press`,
`selectOption`, `setChecked`, `waitForSelector`, `waitForScript`,
- `waitForState`, `evaluate`, and `extract` — the same set installed as script
- primitives.
+ `waitForState`, `evaluate`, and `extract` — the same set installed as page
+ methods.
- Not recorded: read-only exploration tools such as `tree`, `markdown`, `html`,
`links`, `findElement`, `consoleLogs`, `getUrl`, `getCookies`, and `getEnv`.
- Natural-language prompts are written as `//` comments above the actions they
@@ -352,7 +375,7 @@ Primitive failures throw JavaScript exceptions:
```js
try {
- waitForSelector({ selector: "#dashboard", timeout: 1000 });
+ page.waitForSelector({ selector: "#dashboard", timeout: 1000 });
} catch (err) {
console.error("dashboard did not appear:", err.message);
throw err;
@@ -363,24 +386,30 @@ Common failures:
| Error | Meaning |
|-------|---------|
-| `ReferenceError: document is not defined` | You tried to use browser DOM APIs in the agent context. Use `extract(...)` or page `evaluate(...)`. |
+| `extract is not defined` (or `click`/`fill`/…) | These are methods on the page object, not globals. Use `const page = new Page(); await page.goto(url); page.extract(...)`. |
+| `Page must be called with new` | `Page(...)` was called without `new`. Use `const page = new Page();`. |
+| `page is not navigated or has been closed; call page.goto(url) first` | A method ran on a fresh `new Page()` (or a closed page). `await page.goto(url)` first. |
+| `page handle is no longer valid` | A page was used after a later `goto` replaced it. Read a page before navigating away. |
+| `ReferenceError: document is not defined` | You tried to use browser DOM APIs in the agent context. Use `page.extract(...)` or `page.evaluate(...)`. |
| `ReferenceError: require is not defined` | Agent scripts are not Node.js scripts. |
| `no page loaded - run goto(url) first` | A page-dependent primitive ran before navigation. |
-| `invalid arguments` | A primitive received the wrong number or shape of arguments, or a non-JSON-serializable value. |
+| `invalid arguments` | A method received the wrong number or shape of arguments, or a non-JSON-serializable value. |
| `extract: no schema selector matched any element` | Every field in the schema missed. Fix the selectors; an empty page section yields `null`/`[]` per field, not this error. |
## Complete Example
This script opens Hacker News, extracts five stories, visits each comments
-page, and prints one JSON object. The looping and object assembly happen in
-the local agent script, not in the page.
+page, and prints one JSON object. A single reusable `page` walks the list
+sequentially — read each detail page before navigating to the next. The
+looping and object assembly happen in the local agent script, not in the page.
```js
const HN = "https://news.ycombinator.com";
-goto(HN);
+const page = new Page();
+await page.goto(HN);
-const { stories } = extract({
+const { stories } = page.extract({
stories: [{
selector: "tr.athing",
limit: 5,
@@ -396,8 +425,8 @@ for (const story of stories) {
story.comments = [];
if (!story.id) continue;
- goto(`${HN}/item?id=${story.id}`);
- const { comments } = extract({
+ await page.goto(`${HN}/item?id=${story.id}`);
+ const { comments } = page.extract({
comments: [{
selector: "tr.athing.comtr:has(.commtext)",
limit: 3,
@@ -410,5 +439,5 @@ for (const story of stories) {
story.comments = comments;
}
-stories; // printed automatically as JSON
+return stories; // printed automatically as JSON
```
diff --git a/docs/agent-tutorial.md b/docs/agent-tutorial.md
index b5f0ba1b1..0cd1500d0 100644
--- a/docs/agent-tutorial.md
+++ b/docs/agent-tutorial.md
@@ -165,13 +165,14 @@ With an LLM, it synthesizes an idiomatic script. The result is
JavaScript:
```js
-goto("https://news.ycombinator.com/login");
-fill({ selector: "form[action=\"login\"] input[name=\"acct\"]", value: "$LP_HN_USERNAME" });
-fill({ selector: "form[action=\"login\"] input[name=\"pw\"]", value: "$LP_HN_PASSWORD" });
-click({ selector: "form[action=\"login\"] input[type=\"submit\"][value=\"login\"]" });
-waitForSelector("#logout");
-goto("https://news.ycombinator.com");
-extract({ topStories: [{ selector: ".athing", fields: { rank: ".rank", title: ".titleline > a", url: { selector: ".titleline > a", attr: "href" } } }] });
+const page = new Page();
+await page.goto("https://news.ycombinator.com/login");
+page.fill({ selector: "form[action=\"login\"] input[name=\"acct\"]", value: "$LP_HN_USERNAME" });
+page.fill({ selector: "form[action=\"login\"] input[name=\"pw\"]", value: "$LP_HN_PASSWORD" });
+page.click({ selector: "form[action=\"login\"] input[type=\"submit\"][value=\"login\"]" });
+page.waitForSelector("#logout");
+await page.goto("https://news.ycombinator.com");
+return page.extract({ topStories: [{ selector: ".athing", fields: { rank: ".rank", title: ".titleline > a", url: { selector: ".titleline > a", attr: "href" } } }] });
```
Only state-mutating commands are recorded; read-only ones (`/tree`,
@@ -184,9 +185,9 @@ what the script returns.
./lightpanda agent hn_login.js
```
-No `--provider`, no API key, no token spend. The script's last
-expression is printed automatically as JSON. Because the saved script
-ends with `extract(...)`, you get clean JSON on stdout:
+No `--provider`, no API key, no token spend. Whatever the script
+`return`s is printed automatically as JSON. Because the saved script
+ends with `return page.extract(...)`, you get clean JSON on stdout:
```console
./lightpanda agent hn_login.js > stories.json
@@ -195,11 +196,14 @@ ends with `extract(...)`, you get clean JSON on stdout:
From inside the REPL, `/load hn_login.js` runs the same script against
the current session.
-To reshape the output, assign the result and end with a bare expression
-(the final value is what prints):
+To reshape the output, assign the result and end with `return <value>`
+(what you return is what prints):
```js
-const topStories = extract({
+const page = new Page();
+await page.goto("https://news.ycombinator.com");
+
+const topStories = page.extract({
topStories: [{
selector: ".athing",
fields: {
@@ -210,22 +214,25 @@ const topStories = extract({
}]
});
-topStories;
+return topStories;
```
## 6. Add your own JavaScript logic
Agent scripts run in a separate JavaScript context from the page. No
`window`, `document`, DOM API, `require`, or `process`. Browser
-interaction happens through the installed primitives.
+interaction happens through the `Page` object: `new Page()` makes a
+page, `await page.goto(url)` navigates it, and every other primitive is
+a synchronous method on it.
-Use `extract(...)` to move page data into local logic, then process it
-with normal JavaScript:
+Use `page.extract(...)` to move page data into local logic, then
+process it with normal JavaScript:
```js
-goto("https://news.ycombinator.com");
+const page = new Page();
+await page.goto("https://news.ycombinator.com");
-const topStories = extract({
+const topStories = page.extract({
topStories: [{
selector: ".athing",
limit: 5,
@@ -237,11 +244,11 @@ const topStories = extract({
}]
});
-topStories.map((s) => ({ rank: s.rank, title: s.title, url: s.url }));
+return topStories.map((s) => ({ rank: s.rank, title: s.title, url: s.url }));
```
-Use `evaluate(...)` only when you intentionally want a string to run in
-the page's JavaScript context. Page evaluate cannot see agent
+Use `page.evaluate(...)` only when you intentionally want a string to
+run in the page's JavaScript context. Page evaluate cannot see agent
variables or call agent primitives.
## 7. Use Lightpanda from another agent (MCP)
@@ -269,7 +276,7 @@ Drive the browser with the usual tools (`goto`, `fill`, `click`,
"tool": "save",
"args": {
"path": "hn_login.js",
- "script": "goto(\"...\");\n..."
+ "script": "const page = new Page();\nawait page.goto(\"...\");\n..."
}
}
```
diff --git a/docs/agent.md b/docs/agent.md
index c6147bc49..c8bda8b62 100644
--- a/docs/agent.md
+++ b/docs/agent.md
@@ -353,27 +353,34 @@ session).
## JavaScript scripts
`./lightpanda agent script.js` runs a script without any LLM call. Scripts
-are plain synchronous JavaScript plus the installed Lightpanda primitives:
+are plain JavaScript plus the `Page` object — the only global. `new Page()`
+makes a page, `await page.goto(url)` navigates it, and every other primitive
+is a synchronous method on it:
```js
-goto("https://example.com");
-click({ selector: "a.login" });
-evaluate("document.title");
+const page = new Page();
+await page.goto("https://example.com");
+page.click({ selector: "a.login" });
+page.evaluate("document.title");
```
-The primitives are **synchronous and blocking**: each returns its
-result directly, so write `const data = extract(…)`, not
-`await extract(…)`. (`evaluate(...)` can run async JS inside the page,
-but the `evaluate(...)` call itself still returns synchronously.)
+`page.goto(...)` is **async — always `await` it**. Every other page method is
+**synchronous**: write `const data = page.extract(…)`, not
+`await page.extract(…)`. (`page.evaluate(...)` can run async JS inside the
+page, but the call itself still returns synchronously.) The script body runs
+as an async function, so top-level `await` is allowed. Re-navigating reuses
+the same page object: a later `await page.goto(url2)` keeps `page` valid and
+points it at the new URL.
It's not Node.js. There's no `require`, `process`, `fs`, npm package
-loading, or Node standard library. The `evaluate(...)` primitive runs its
+loading, or Node standard library. The `page.evaluate(...)` method runs its
string in the current page context; page scripts can't see agent variables
or agent primitives.
-The last expression in the script is printed automatically, so a script
-that ends with `extract({...})` will print the extraction result to stdout.
-Tool errors throw JavaScript exceptions and stop execution.
+Whatever the script `return`s is printed automatically, so a script that ends
+with `return page.extract({...})` will print the extraction result to stdout.
+A bare trailing expression is not printed. Tool errors throw JavaScript
+exceptions and stop execution.
See [agent-script.md](agent-script.md) for the full script format reference.
@@ -404,8 +411,8 @@ no resolved provider) you get the deterministic transcription:
- **With an LLM** it synthesizes an idiomatic script from the whole
session. The synthesis prompt asks for JavaScript only ("no commentary"),
so the result generally has no such comments: the model folds intent
- into the code and drops dead-ends. Returned data is the last expression,
- which prints automatically on replay.
+ into the code and drops dead-ends. Returned data is whatever the script
+ `return`s, which prints automatically on replay.
## One-shot mode (`--task`)
@@ -471,8 +478,9 @@ calling client holds the conversation and synthesizes the script itself.
| `save` | `{ path: string, script: string }` | Write `script` to `path` (relative, no `..`; created or overwritten) and return the absolute location and line count. |
The tool's description carries the same synthesis guidance the agent's
-`/save` gives its LLM: prefer the builtins (`goto`, `click`, `fill`,
-`extract`, ...) as JavaScript calls, drop dead-ends, keep `$LP_*`
+`/save` gives its LLM: drive a `Page` object (`await page.goto(...)`,
+`page.click(...)`, `page.fill(...)`, `page.extract(...)`, ...) as JavaScript
+calls, drop dead-ends, keep `$LP_*`
placeholders. Any literal `LP_*` value is scrubbed back to its placeholder
before the file is written. The result runs without an LLM via
`./lightpanda agent session.js`.
diff --git a/src/agent/Agent.zig b/src/agent/Agent.zig
index b36073bc6..6e1fdc66c 100644
--- a/src/agent/Agent.zig
+++ b/src/agent/Agent.zig
@@ -92,30 +92,36 @@ const script_skill =
\\
\\The script runs in its **own V8 context** — neither the page nor Node.js:
\\
- \\- No `window`, `document`, DOM, `localStorage` — read pages with `extract(...)`, run page-side JS only via `evaluate("...")`.
+ \\- `Page` is the only global. `new Page()` makes a page and `await page.goto(url)` navigates it; every other primitive is a **method on that page**: `const page = new Page(); await page.goto(url); page.extract({...}); page.click(sel);`.
+ \\- No `window`, `document`, DOM, `localStorage` — read pages with `page.extract(...)`, run page-side JS only via `page.evaluate("...")`.
\\- No `require`, `process`, `fs`, npm. Standard ECMAScript built-ins only (`JSON`, `Map`, template literals, …).
- \\- All primitives are **synchronous and blocking**. Never wrap them in `async`/`await`/`.then` — `const data = extract({...})`, not `await extract(...)`. Top-level `await` is a `SyntaxError` (classic script); promise callbacks only run after the script body ends.
+ \\- `page.goto(...)` is **async — always `await` it**. Page methods are **synchronous**: `const data = page.extract({...})`, never `await page.extract(...)`. The script body runs as an async function, so top-level `await` is allowed.
+ \\- **Re-navigating reuses the same page**: `await page.goto(url2)` keeps `page` valid and points it at the new URL. Work through one page at a time and read it before navigating away.
\\- Page `evaluate("...")` cannot see script variables — interpolate values into the string. Script code cannot see page variables.
\\- Variables persist across navigations within one run, so cross-page aggregation is plain JS.
- \\- The **last top-level expression is the script's output**, printed automatically (objects/arrays as JSON). End with the bare result: `extract({...});` or `results;`. No `console.log(JSON.stringify(...))`, no top-level `return` (illegal).
+ \\- **`return <value>` is the script's output**, printed automatically (objects/arrays as JSON). End with `return page.extract({...});` or `return results;`. A bare trailing expression is NOT printed; neither is `console.log(JSON.stringify(...))`.
\\
\\## Primitives
\\
+ \\`Page` is the only global; `new Page()` makes a page and everything else is a method on it.
+ \\
\\| Call | Notes |
\\|------|-------|
- \\| `goto(url[, { timeout }])` | Returns at `load`. Default timeout 10000 ms. Throws on failure; a **timeout does NOT throw** — it returns a "did not finish loading" status string. |
- \\| `extract(schema)` | The only primitive returning a real JS value (object/array). See schema below. |
- \\| `evaluate(script[, { url, timeout, save }])` | Page-side JS escape hatch; returns text (JSON for objects/arrays). |
- \\| `click(sel)` / `hover(sel)` | |
- \\| `fill(sel, value)` / `selectOption(sel, value)` | |
- \\| `setChecked(sel[, checked])` | `checked` defaults to `true`. |
- \\| `press(sel, key)` / `press(null, key)` / `press({ key })` | Selector first! `press("Enter")` binds "Enter" to `selector` and fails. |
- \\| `scroll()` / `scroll({ x, y })` | |
- \\| `waitForSelector(sel[, { timeout }])` | `waitFor*` default timeout 5000 ms. |
- \\| `waitForScript(js[, { timeout }])` | Re-evaluates page JS until truthy. |
- \\| `waitForState(state[, { timeout }])` | `"load"`, `"domcontentloaded"`, `"networkalmostidle"`, `"networkidle"`, `"done"`. |
+ \\| `new Page()` | Makes a page object. No navigation yet — call `page.goto(url)` before any other method. |
+ \\| `await page.goto(url[, { timeout }])` | **Async — must be `await`ed.** Navigates the page (re-navigating reuses the same object). Waits for `load`. Default timeout 10000 ms. Rejects on navigation failure; a **timeout does NOT reject** (the page may still be usable). |
+ \\| `page.close()` | Marks the page done; later method calls on it error. The page is otherwise reclaimed at script end. |
+ \\| `page.extract(schema)` | The only primitive returning a real JS value (object/array). See schema below. |
+ \\| `page.evaluate(script[, { url, timeout, save }])` | Page-side JS escape hatch; returns text (JSON for objects/arrays). |
+ \\| `page.click(sel)` / `page.hover(sel)` | |
+ \\| `page.fill(sel, value)` / `page.selectOption(sel, value)` | |
+ \\| `page.setChecked(sel[, checked])` | `checked` defaults to `true`. |
+ \\| `page.press(sel, key)` / `page.press(null, key)` / `page.press({ key })` | Selector first! `page.press("Enter")` binds "Enter" to `selector` and fails. |
+ \\| `page.scroll()` / `page.scroll({ x, y })` | |
+ \\| `page.waitForSelector(sel[, { timeout }])` | `waitFor*` default timeout 5000 ms. |
+ \\| `page.waitForScript(js[, { timeout }])` | Re-evaluates page JS until truthy. |
+ \\| `page.waitForState(state[, { timeout }])` | `"load"`, `"domcontentloaded"`, `"networkalmostidle"`, `"networkidle"`, `"done"`. |
\\
- \\Calling convention: leading positionals + optional trailing options object, or one object with everything (`waitForSelector("#row", { timeout: 2000 })` ≡ `waitForSelector({ selector: "#row", timeout: 2000 })`). A bare option positional (`waitForSelector("#row", 2000)`) and a field passed both ways are `invalid arguments`. `null` skips a positional. Arguments must be JSON-serializable.
+ \\Calling convention: leading positionals + optional trailing options object, or one object with everything (`page.waitForSelector("#row", { timeout: 2000 })` ≡ `page.waitForSelector({ selector: "#row", timeout: 2000 })`). A bare option positional (`page.waitForSelector("#row", 2000)`) and a field passed both ways are `invalid arguments`. `null` skips a positional. Arguments must be JSON-serializable.
\\
\\CSS selectors only — `backendNodeId`s don't exist here. Standard CSS only: no jQuery `:contains()` or Playwright `:has-text()`.
\\
@@ -124,7 +130,7 @@ const script_skill =
\\Keys = output field names; values pick what to lift (not a JSON Schema):
\\
\\```js
- \\const { stories } = extract({
+ \\const { stories } = page.extract({
\\ stories: [{
\\ selector: "tr.athing", // one record per match
\\ limit: 5,
@@ -145,26 +151,40 @@ const script_skill =
\\
\\## Best practices
\\
- \\1. **Navigate, settle, read.** After `goto` on a dynamic page (feeds, search results, comment threads), call `waitForState("networkidle")` or `waitForSelector(...)` before extracting. Most static pages are complete at `load` — don't wait blindly.
- \\2. **Check `goto` when completeness matters** — it returns a status string instead of throwing on timeout.
- \\3. **Aggregate in the script, not the page.** List-to-detail: extract the list, then loop `goto`/`extract` per item, assembling plain JS objects.
- \\4. **`evaluate` is a last resort, not a reading tool.** A `querySelectorAll`-and-parse `evaluate` block is always wrong: lift the raw strings with `extract`, then trim/split/parse them in top-level JS. Reserve `evaluate` for behavior that must run inside the page and no builtin covers — and remember its state dies on every `goto`/reload, while script variables persist.
- \\5. **Credentials via `$LP_*` placeholders** in any string argument (`fill("#pw", "$LP_HN_PASSWORD")`). Never inline a real secret; placeholders resolve inside the Lightpanda process.
- \\6. **Unique selectors.** Disambiguate with attributes/position: `input[type="submit"][value="login"]`, not `input[type="submit"]`.
- \\7. **Let failures fail.** Primitives throw on error and stop the script — only `try/catch` where you have a real fallback (e.g. optional cookie banner: `try { click("#accept") } catch {}`).
- \\8. **End with the bare result expression.** `console.log` is for debug output only and doesn't JSON-format objects.
- \\9. Modern, readable JS: `const`/`let`, `for (const x of xs)`, template literals, destructuring, 2-space indent.
+ \\1. **Navigate, settle, read.** After `await page.goto` on a dynamic page (feeds, search results, comment threads), call `page.waitForState("networkidle")` or `page.waitForSelector(...)` before extracting. Most static pages are complete at `load` — don't wait blindly.
+ \\2. **List-to-detail: read the list, then walk it.** Extract the list of links, then for each item `await page.goto(item.url)` and `page.extract(...)`, assembling plain JS objects — read each detail page before navigating to the next:
+ \\ ```js
+ \\ const page = new Page();
+ \\ await page.goto(listUrl);
+ \\ const { items } = page.extract({ items: [{ selector: "a.row", fields: { url: { attr: "href" } } }] });
+ \\ const details = [];
+ \\ for (const it of items) {
+ \\ await page.goto(it.url);
+ \\ details.push({ ...it, ...page.extract({ /* schema */ }) });
+ \\ }
+ \\ return details;
+ \\ ```
+ \\3. **`evaluate` is a last resort, not a reading tool.** A `querySelectorAll`-and-parse `page.evaluate` block is always wrong: lift the raw strings with `page.extract`, then trim/split/parse them in top-level JS. Reserve `page.evaluate` for behavior that must run inside the page and no builtin covers — and remember its state dies on every navigation/reload, while script variables persist.
+ \\4. **Credentials via `$LP_*` placeholders** in any string argument (`page.fill("#pw", "$LP_HN_PASSWORD")`). Never inline a real secret; placeholders resolve inside the Lightpanda process.
+ \\5. **Unique selectors.** Disambiguate with attributes/position: `input[type="submit"][value="login"]`, not `input[type="submit"]`.
+ \\6. **Let failures fail.** Primitives throw on error and stop the script — only `try/catch` where you have a real fallback (e.g. optional cookie banner: `try { page.click("#accept") } catch {}`).
+ \\7. **End with `return <result>`.** `console.log` is for debug output only and doesn't JSON-format objects.
+ \\8. Modern, readable JS: `const`/`let`, `for (const x of xs)`, template literals, destructuring, 2-space indent.
\\
\\## Common errors
\\
\\| Error | Cause / fix |
\\|-------|-------------|
- \\| `document is not defined` | DOM API in script context → use `extract` or `evaluate` |
+ \\| `extract is not defined` (or click/fill/…) | These are methods on the page object, not globals → `const page = new Page(); await page.goto(url); page.extract(...)` |
+ \\| `Page must be called with new` | `Page(...)` called without `new` → `const page = new Page();` |
+ \\| `page is not navigated or has been closed` | A method on a fresh `new Page()` (or a closed page) → `await page.goto(url)` first |
+ \\| `page handle is no longer valid` | Used a page after a later `goto` replaced it → read a page before navigating away |
+ \\| `document is not defined` | DOM API in script context → use `page.extract` or `page.evaluate` |
\\| `require is not defined` | Not Node.js |
\\| `no page loaded - run goto(url) first` | Page primitive before navigation |
\\| `invalid arguments` | Wrong arity/shape, non-JSON value, or a field set both positionally and in options |
\\| `extract: no schema selector matched any element` | All schema fields missed → fix selectors |
- \\| `press` fails with one string arg | Selector-first: use `press(null, "Enter")` or `press({ key: "Enter" })` |
+ \\| `press` fails with one string arg | Selector-first: use `page.press(null, "Enter")` or `page.press({ key: "Enter" })` |
;
// Sytem prompt of the `/save` command
diff --git a/src/browser/tools.zig b/src/browser/tools.zig
index 35d7ab806..6f0b6dd89 100644
--- a/src/browser/tools.zig
+++ b/src/browser/tools.zig
@@ -253,6 +253,17 @@ pub const Tool = enum {
};
}
+ /// Whether the tool's script form returns a Promise and so is recorded with
+ /// `await`. Only `goto` (navigation) is async; every other page method is
+ /// synchronous. Exhaustive like the sibling predicates so adding an async
+ /// tool is a compile error until it makes an explicit choice here.
+ pub fn isAsync(self: Tool) bool {
+ return switch (self) {
+ .goto => true,
+ .evaluate, .extract, .click, .fill, .scroll, .waitForSelector, .waitForScript, .waitForState, .hover, .press, .selectOption, .setChecked, .search, .markdown, .html, .links, .tree, .nodeDetails, .interactiveElements, .structuredData, .detectForms, .findElement, .consoleLogs, .getUrl, .getCookies, .getEnv => false,
+ };
+ }
+
/// Tool requires a target element (selector or backendNodeId) at
/// runtime even though the JSON schema marks both as optional. Used by
/// the recorder to skip lines that can't be replayed.
diff --git a/src/mcp/tools.zig b/src/mcp/tools.zig
index 31764c1ea..a49580eb9 100644
--- a/src/mcp/tools.zig
+++ b/src/mcp/tools.zig
@@ -815,13 +815,13 @@ test "MCP - save writes the script to disk" {
defer std.fs.cwd().deleteFile(path) catch {};
const msg =
- \\{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"save","arguments":{"path":"mcp-save-test-script.js","script":"goto(\"https://example.com\");"}}}
+ \\{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"save","arguments":{"path":"mcp-save-test-script.js","script":"const page = new Page();\nawait page.goto(\"https://example.com\");"}}}
;
try router.handleMessage(server, testing.arena_allocator, msg);
- try testing.expect(std.mem.indexOf(u8, out.written(), "saved 1 line") != null);
+ try testing.expect(std.mem.indexOf(u8, out.written(), "saved 2 line") != null);
const written = try std.fs.cwd().readFileAlloc(testing.arena_allocator, path, 4096);
- try std.testing.expectEqualStrings("goto(\"https://example.com\");\n", written);
+ try std.testing.expectEqualStrings("const page = new Page();\nawait page.goto(\"https://example.com\");\n", written);
}
test "MCP - tree rejects stale backendNodeId instead of dumping whole document" {
diff --git a/src/script/Recorder.zig b/src/script/Recorder.zig
index 85948fc69..2ab8b381b 100644
--- a/src/script/Recorder.zig
+++ b/src/script/Recorder.zig
@@ -29,6 +29,9 @@ const Recorder = @This();
allocator: std.mem.Allocator,
/// Number of lines appended since the last reset. Bumped only on success.
lines: u32,
+/// Whether `const page = new Page();` has been emitted yet. The first recorded
+/// command emits it, then every call is a method on `page`.
+page_declared: bool,
/// Accumulated JavaScript, returned verbatim by `bytes()`.
content: std.Io.Writer.Allocating,
/// Reused between writes so each line doesn't alloc/free.
@@ -40,6 +43,7 @@ pub fn init(allocator: std.mem.Allocator) Recorder {
return .{
.allocator = allocator,
.lines = 0,
+ .page_declared = false,
.content = .init(allocator),
.buf = .init(allocator),
.arena = .init(allocator),
@@ -58,6 +62,7 @@ pub fn bytes(self: *Recorder) []const u8 {
pub fn reset(self: *Recorder) void {
self.lines = 0;
+ self.page_declared = false;
self.content.clearRetainingCapacity();
self.buf.clearRetainingCapacity();
_ = self.arena.reset(.retain_capacity);
@@ -67,6 +72,14 @@ pub fn record(self: *Recorder, cmd: Command) !void {
if (!cmd.isRecorded()) return;
self.buf.clearRetainingCapacity();
_ = self.arena.reset(.retain_capacity);
+ // `isRecorded` guarantees `.tool_call`. The page is born once, up front; every
+ // recorded call is then a method on it — `goto` async, the rest sync.
+ if (!self.page_declared) {
+ try self.buf.writer.writeAll("const page = new Page();\n");
+ self.page_declared = true;
+ }
+ if (cmd.tool_call.tool.isAsync()) try self.buf.writer.writeAll("await ");
+ try self.buf.writer.writeAll("page.");
try cmd.formatJs(self.arena.allocator(), &self.buf.writer);
try self.buf.writer.writeByte('\n');
try self.appendScrubbed();
@@ -130,18 +143,18 @@ test "record filters state-mutating commands and comments" {
try recorder.recordComment("search for login");
try std.testing.expectEqualStrings(
- "goto(\"https://example.com\");\nclick({ selector: \"Login\" });\n// search for login\n",
+ "const page = new Page();\nawait page.goto(\"https://example.com\");\npage.click({ selector: \"Login\" });\n// search for login\n",
recorder.bytes(),
);
- try std.testing.expectEqual(@as(u32, 3), recorder.lines);
+ try std.testing.expectEqual(@as(u32, 4), recorder.lines);
recorder.reset();
try std.testing.expectEqualStrings("", recorder.bytes());
try std.testing.expectEqual(@as(u32, 0), recorder.lines);
try recorder.record(parseLine(aa, "/scroll y=200"));
- try std.testing.expectEqualStrings("scroll({ y: 200 });\n", recorder.bytes());
- try std.testing.expectEqual(@as(u32, 1), recorder.lines);
+ try std.testing.expectEqualStrings("const page = new Page();\npage.scroll({ y: 200 });\n", recorder.bytes());
+ try std.testing.expectEqual(@as(u32, 2), recorder.lines);
}
test "recordRaw writes the JS line verbatim" {
@@ -166,7 +179,7 @@ test "record emits multi-line extract as JavaScript" {
try recorder.record(parseLine(aa, cmd_str));
try std.testing.expectEqualStrings(
- "extract({ title: \"span.title\", desc: \"p.description\" });\n",
+ "const page = new Page();\npage.extract({ title: \"span.title\", desc: \"p.description\" });\n",
recorder.bytes(),
);
}
@@ -217,7 +230,7 @@ test "record scrubs literal LP_* values in JavaScript calls" {
try recorder.record(parseLine(aa, "/fill selector='#user' value='secret-user'"));
try std.testing.expectEqualStrings(
- "fill({ selector: \"#user\", value: \"$LP_RECORDER_COMMAND_TEST\" });\n",
+ "const page = new Page();\npage.fill({ selector: \"#user\", value: \"$LP_RECORDER_COMMAND_TEST\" });\n",
recorder.bytes(),
);
}
diff --git a/src/script/Runtime.zig b/src/script/Runtime.zig
index 3d8841fc0..ff667b09e 100644
--- a/src/script/Runtime.zig
+++ b/src/script/Runtime.zig
@@ -158,14 +158,23 @@ fn createContext(self: *Runtime) InitError!void {
v8.v8__Context__Enter(context);
defer v8.v8__Context__Exit(context);
+ // The promise-reject callback every `Env` installs reads a browser `Context`
+ // from embedder slot 1; this bare context has none. Pin the slot to null so
+ // the callback no-ops instead of aligncasting garbage — the script body runs
+ // inside an async wrapper, so unhandled rejections happen routinely.
+ v8.v8__Context__SetAlignedPointerInEmbedderData(context, 1, null);
+
const global = v8.v8__Context__Global(context) orelse return error.RuntimeInitFailed;
+
+ // `Page` is the only global verb; `new Page()` attaches a method for each
+ // recorded tool, reusing these `primitive_data` entries — so fill them here.
var i: usize = 0;
for (std.enums.values(BrowserTool)) |t| {
if (!t.isRecorded()) continue;
self.primitive_data[i] = .{ .runtime = self, .tool = t };
- try self.installPrimitive(context, global, @tagName(t), &self.primitive_data[i]);
i += 1;
}
+ try self.installFunction(context, global, "Page", pageConstructor, self);
try self.installConsole(context, global);
}
@@ -176,25 +185,21 @@ fn resetContext(self: *Runtime) void {
self.has_context = false;
}
-fn installPrimitive(
+const Callback = *const fn (?*const v8.FunctionCallbackInfo) callconv(.c) void;
+
+/// Install `callback` (carrying `data` as its `External`) under `name` on `object`.
+fn installFunction(
self: *Runtime,
context: *const v8.Context,
- global: *const v8.Object,
+ object: *const v8.Object,
name: []const u8,
- data: *PrimitiveData,
+ callback: Callback,
+ data: *anyopaque,
) InitError!void {
const external = self.env.isolate.createExternal(data);
- const func = v8.v8__Function__New__DEFAULT2(context, primitiveCallback, external) orelse
+ const func = v8.v8__Function__New__DEFAULT2(context, callback, external) orelse
return error.RuntimeInitFailed;
- var out: v8.MaybeBool = undefined;
- v8.v8__Object__Set(
- global,
- context,
- @ptrCast(self.env.isolate.initStringHandle(name)),
- @ptrCast(func),
- &out,
- );
- if (!out.has_value or !out.value) return error.RuntimeInitFailed;
+ try self.setObjectProperty(context, object, name, @ptrCast(func));
}
fn installConsole(
@@ -207,10 +212,7 @@ fn installConsole(
for (std.enums.values(ConsoleMethod), 0..) |method, i| {
self.console_data[i] = .{ .runtime = self, .method = method };
- const external = self.env.isolate.createExternal(&self.console_data[i]);
- const func = v8.v8__Function__New__DEFAULT2(context, consoleCallback, external) orelse
- return error.RuntimeInitFailed;
- try setObjectProperty(self, context, console, @tagName(method), @ptrCast(func));
+ try self.installFunction(context, console, @tagName(method), consoleCallback, &self.console_data[i]);
}
try setObjectProperty(self, context, global, "console", @ptrCast(console));
@@ -254,7 +256,14 @@ pub fn runSource(self: *Runtime, source: []const u8, name: []const u8) RunError!
defer v8.v8__TryCatch__DESTRUCT(&try_catch);
const script_name = self.env.isolate.initStringHandle(name);
- const script_source = self.env.isolate.initStringHandle(source);
+ // Wrap in an async IIFE so the source can use top-level `await` (e.g.
+ // `await page.goto(...)`). The wrapper evaluates to a Promise; a top-level
+ // `return <expr>` becomes that Promise's value, which we echo. (A bare
+ // trailing expression no longer auto-prints — `await` and a script
+ // completion value are mutually exclusive in JS.)
+ const wrapped = std.fmt.allocPrint(self.call_arena.allocator(), "(async () => {{\n{s}\n}})()", .{source}) catch
+ return try self.dupeError("out of memory");
+ const script_source = self.env.isolate.initStringHandle(wrapped);
var origin: v8.ScriptOrigin = undefined;
v8.v8__ScriptOrigin__CONSTRUCT(&origin, script_name);
@@ -273,19 +282,53 @@ pub fn runSource(self: *Runtime, source: []const u8, name: []const u8) RunError!
const completion = v8.v8__Script__Run(script, context) orelse
return try self.formatCaught(context, &try_catch, "script failed");
- // Explicit microtask policy: promise continuations only run once drained.
+ // `goto` runs synchronously and resolves its Promise before returning, so a
+ // single microtask drain settles the whole `await` chain — no event-loop
+ // driver. (Truly-async navigation is a later change.)
+ const root: *const v8.Promise = @ptrCast(completion);
self.env.performIsolateMicrotasks();
if (v8.v8__TryCatch__HasCaught(&try_catch)) {
return try self.formatCaught(context, &try_catch, "script failed");
}
- self.printCompletion(context, completion);
+ // A still-pending root means the script awaited something we can't settle
+ // (no async navigation is in flight) — stay silent.
+ const state = promiseState(root);
+ if (state != v8.kFulfilled and state != v8.kRejected) return null;
+ const completion_value = v8.v8__Promise__Result(root) orelse return null;
+ if (state == v8.kRejected) return try self.formatRejection(context, completion_value);
+ self.printCompletion(context, completion_value);
return null;
}
-/// Echo a script's completion value (its last-evaluated expression) so a script
-/// ending in `extract(...)` or a bare `results;` prints without `console.log`.
-/// `undefined` — declarations, assignments, control flow — stays silent.
+/// `v8__Promise__State` returns the `c_uint` `PromiseState`, but the `k*`
+/// constants are `c_int`; normalize so comparisons and switches type-check.
+fn promiseState(promise: *const v8.Promise) c_int {
+ return @intCast(v8.v8__Promise__State(promise));
+}
+
+/// Format a script's rejection reason into a run-arena message. Prefers a thrown
+/// Error's `.message` so the caller's own "Error:" label isn't doubled
+/// (`Value.toString` on an Error yields "Error: <message>").
+fn formatRejection(self: *Runtime, context: *const v8.Context, reason: *const v8.Value) RunError![]const u8 {
+ const value = self.errorMessage(context, reason) orelse reason;
+ const text = self.valueToString(self.call_arena.allocator(), context, value) catch
+ return try self.dupeError("script failed");
+ return try self.dupeError(text);
+}
+
+/// The `.message` of a thrown Error (a string), or null when `reason` is not an
+/// Error-like object — in which case the caller stringifies the value itself.
+fn errorMessage(self: *Runtime, context: *const v8.Context, reason: *const v8.Value) ?*const v8.Value {
+ if (!v8.v8__Value__IsObject(reason)) return null;
+ const key: *const v8.Value = @ptrCast(self.env.isolate.initStringHandle("message"));
+ const message = v8.v8__Object__Get(@ptrCast(reason), context, key) orelse return null;
+ return if (v8.v8__Value__IsString(message)) message else null;
+}
+
+/// Echo a script's output — the value it `return`s from the async wrapper, so a
+/// script ending in `return page.extract(...)` prints without `console.log`.
+/// `undefined` — no `return`, or a bare trailing expression — stays silent.
fn printCompletion(self: *Runtime, context: *const v8.Context, value: *const v8.Value) void {
if (v8.v8__Value__IsUndefined(value)) return;
@@ -295,20 +338,68 @@ fn printCompletion(self: *Runtime, context: *const v8.Context, value: *const v8.
self.writeConsoleLine(.log, text);
}
+/// Unwrap a callback's info handle and its `External` payload (the `*T` passed
+/// to `installFunction`). Returns null — so the callback no-ops — if either is
+/// missing.
+fn callbackData(comptime T: type, info_handle: ?*const v8.FunctionCallbackInfo) ?struct { *const v8.FunctionCallbackInfo, *T } {
+ const info = info_handle orelse return null;
+ const raw_data = v8.v8__FunctionCallbackInfo__Data(info) orelse return null;
+ const data: *T = @ptrCast(@alignCast(v8.v8__External__Value(@ptrCast(raw_data)) orelse return null));
+ return .{ info, data };
+}
+
fn primitiveCallback(info_handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
- const info = info_handle orelse return;
- const raw_data = v8.v8__FunctionCallbackInfo__Data(info) orelse return;
- const data: *PrimitiveData = @ptrCast(@alignCast(v8.v8__External__Value(@ptrCast(raw_data)) orelse return));
+ const info, const data = callbackData(PrimitiveData, info_handle) orelse return;
data.runtime.invoke(data.tool, info);
}
fn consoleCallback(info_handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
- const info = info_handle orelse return;
- const raw_data = v8.v8__FunctionCallbackInfo__Data(info) orelse return;
- const data: *ConsoleData = @ptrCast(@alignCast(v8.v8__External__Value(@ptrCast(raw_data)) orelse return));
+ const info, const data = callbackData(ConsoleData, info_handle) orelse return;
data.runtime.invokeConsole(data.method, info);
}
+fn pageConstructor(info_handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+ const info, const self = callbackData(Runtime, info_handle) orelse return;
+ self.construct(info);
+}
+
+fn closeCallback(info_handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+ const info, const self = callbackData(Runtime, info_handle) orelse return;
+ self.invokeClose(info);
+}
+
+/// `new Page()`: attach a method for every recorded tool (including `goto`) plus
+/// `close`. `__lpFrameId` is left unset until the first `goto` navigates the page.
+fn construct(self: *Runtime, info: *const v8.FunctionCallbackInfo) void {
+ if (!v8.v8__FunctionCallbackInfo__IsConstructCall(info)) {
+ return self.throwTypeError("Page must be called with new");
+ }
+ const context = v8.v8__Isolate__GetCurrentContext(self.env.isolate.handle) orelse
+ return self.throwError("internal: missing callback context");
+ const this = v8.v8__FunctionCallbackInfo__This(info) orelse
+ return self.throwError("internal: missing receiver");
+
+ for (&self.primitive_data) |*data| {
+ self.installFunction(context, this, @tagName(data.tool), primitiveCallback, data) catch
+ return self.throwError("failed to construct page");
+ }
+ self.installFunction(context, this, "close", closeCallback, self) catch
+ return self.throwError("failed to construct page");
+}
+
+/// Property carrying a page handle's claim on a live frame. Numeric while the
+/// page is navigated; absent/undefined once never-navigated or closed.
+const frame_id_key = "__lpFrameId";
+
+/// `page.close()`: stale the wrapper so later method calls error. A single
+/// synchronous page has no popups to free; the active page is reclaimed on the
+/// next `goto` or at script end.
+fn invokeClose(self: *Runtime, info: *const v8.FunctionCallbackInfo) void {
+ const context = v8.v8__Isolate__GetCurrentContext(self.env.isolate.handle) orelse return;
+ const this = v8.v8__FunctionCallbackInfo__This(info) orelse return;
+ self.setObjectProperty(context, this, frame_id_key, self.env.isolate.initUndefined()) catch {};
+}
+
fn invoke(self: *Runtime, tool: BrowserTool, info: *const v8.FunctionCallbackInfo) void {
// Owned, not shared: marshalling runs JS (`toJSON`) that can re-enter a
// primitive; a shared arena would let the nested call reset ours mid-flight.
@@ -327,6 +418,21 @@ fn invoke(self: *Runtime, tool: BrowserTool, info: *const v8.FunctionCallbackInf
error.InvalidArguments => return self.throwTypeError("invalid arguments"),
};
+ // `goto` is the one async-shaped primitive: it returns a Promise (resolved
+ // synchronously once the blocking navigation settles).
+ if (tool == .goto) return self.invokeGoto(arena, context, info, args);
+
+ // Other primitives are page methods. The receiver must be navigated, and —
+ // since a single synchronous page has only one live frame — still be the
+ // current one; a later `goto` (on any handle) replaces the page and stales
+ // every other handle.
+ const frame_id = self.receiverFrameId(context, info) orelse
+ return self.throwError("page is not navigated or has been closed; call page.goto(url) first");
+ const live = self.session.currentFrame();
+ if (live == null or live.?._frame_id != frame_id) {
+ return self.throwError("page handle is no longer valid; the page was closed or replaced");
+ }
+
const result = self.callTool(arena, tool, args) catch |err| switch (err) {
error.OutOfMemory => return self.throwError("out of memory"),
};
@@ -345,6 +451,71 @@ fn invoke(self: *Runtime, tool: BrowserTool, info: *const v8.FunctionCallbackInf
}
}
+/// Navigate the receiver Page synchronously and hand back a resolved Promise of
+/// the page object, so `await page.goto(url)` yields the page. The blocking
+/// `goto` tool runs the navigation to completion before this returns; on success
+/// the receiver's `__lpFrameId` is (re)bound to the freshly-loaded frame.
+fn invokeGoto(
+ self: *Runtime,
+ arena: std.mem.Allocator,
+ context: *const v8.Context,
+ info: *const v8.FunctionCallbackInfo,
+ args: ?std.json.Value,
+) void {
+ const resolver = v8.v8__Promise__Resolver__New(context) orelse
+ return self.throwError("internal: resolver alloc failed");
+ const promise = v8.v8__Promise__Resolver__GetPromise(resolver) orelse
+ return self.throwError("internal: promise alloc failed");
+ self.setReturnValue(info, @ptrCast(promise));
+
+ const result = self.callTool(arena, .goto, args) catch |err| switch (err) {
+ error.OutOfMemory => return self.rejectResolver(context, resolver, "out of memory"),
+ };
+
+ switch (result) {
+ .ok => {
+ const this = v8.v8__FunctionCallbackInfo__This(info) orelse
+ return self.rejectResolver(context, resolver, "navigation failed");
+ const frame = self.session.currentFrame() orelse
+ return self.rejectResolver(context, resolver, "navigation failed");
+ self.bindFrameId(context, this, frame._frame_id) catch
+ return self.rejectResolver(context, resolver, "internal: page bind failed");
+ self.resolveResolver(context, resolver, @ptrCast(this));
+ },
+ .fail => |message| self.rejectResolver(context, resolver, message),
+ }
+}
+
+fn resolveResolver(_: *Runtime, context: *const v8.Context, resolver: *const v8.PromiseResolver, value: *const v8.Value) void {
+ var out: v8.MaybeBool = undefined;
+ v8.v8__Promise__Resolver__Resolve(resolver, context, value, &out);
+}
+
+fn rejectResolver(self: *Runtime, context: *const v8.Context, resolver: *const v8.PromiseResolver, message: []const u8) void {
+ var out: v8.MaybeBool = undefined;
+ v8.v8__Promise__Resolver__Reject(resolver, context, self.env.isolate.createError(message), &out);
+}
+
+/// Bind `__lpFrameId` on a page object to `frame_id` — the handle's claim on the
+/// live frame, checked by `invoke` on every later method call.
+fn bindFrameId(self: *Runtime, context: *const v8.Context, this: *const v8.Object, frame_id: u32) InitError!void {
+ const value = v8.v8__Integer__NewFromUnsigned(self.env.isolate.handle, frame_id) orelse
+ return error.RuntimeInitFailed;
+ return self.setObjectProperty(context, this, frame_id_key, @ptrCast(value));
+}
+
+/// Frame id a method's receiver was bound to (`this.__lpFrameId`), or null when
+/// the page was never navigated or has been closed.
+fn receiverFrameId(self: *Runtime, context: *const v8.Context, info: *const v8.FunctionCallbackInfo) ?u32 {
+ const this = v8.v8__FunctionCallbackInfo__This(info) orelse return null;
+ const key: *const v8.Value = @ptrCast(self.env.isolate.initStringHandle(frame_id_key));
+ const prop = v8.v8__Object__Get(this, context, key) orelse return null;
+ if (!v8.v8__Value__IsNumber(prop)) return null;
+ var out: v8.MaybeU32 = undefined;
+ v8.v8__Value__Uint32Value(prop, context, &out);
+ return if (out.has_value) out.value else null;
+}
+
fn invokeConsole(self: *Runtime, method: ConsoleMethod, info: *const v8.FunctionCallbackInfo) void {
// Owned arena (see `invoke`): an argument's `toString` can re-enter a
// primitive mid-loop and must not reset the buffer we're accumulating.
@@ -684,9 +855,10 @@ test "agent script runtime: goto and evaluate dispatch through browser tools" {
defer runtime.deinit();
try runTestScript(runtime,
- \\const nav = goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
- \\if (!nav.includes("Navigated")) throw new Error("unexpected goto result: " + nav);
- \\const text = evaluate("document.getElementById('btn').textContent");
+ \\const page = new Page();
+ \\const same = await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\if (same !== page) throw new Error("page.goto should resolve the same page object");
+ \\const text = page.evaluate("document.getElementById('btn').textContent");
\\if (text !== "Click Me") throw new Error("evaluate ran in the wrong context: " + text);
);
@@ -694,6 +866,78 @@ test "agent script runtime: goto and evaluate dispatch through browser tools" {
try testing.expect(std.mem.indexOf(u8, frame.url, "/src/browser/tests/mcp_actions.html") != null);
}
+test "agent script runtime: Page must be called with new" {
+ defer testing.reset();
+
+ var registry = CDPNode.Registry.init(testing.allocator);
+ defer registry.deinit();
+
+ const runtime = try Runtime.init(testing.allocator, testing.test_app, testing.test_session, &registry);
+ defer runtime.deinit();
+
+ const message = (try runtime.runSource("Page();", "agent-runtime-page-no-new.js")).?;
+ try testing.expect(std.mem.indexOf(u8, message, "must be called with new") != null);
+}
+
+test "agent script runtime: a method on an un-navigated page errors" {
+ defer testing.reset();
+
+ var registry = CDPNode.Registry.init(testing.allocator);
+ defer registry.deinit();
+
+ const runtime = try Runtime.init(testing.allocator, testing.test_app, testing.test_session, &registry);
+ defer runtime.deinit();
+
+ const message = (try runtime.runSource(
+ \\const page = new Page();
+ \\page.extract({ btn: "#btn" });
+ , "agent-runtime-not-navigated.js")).?;
+ try testing.expect(std.mem.indexOf(u8, message, "not navigated") != null);
+}
+
+test "agent script runtime: page.close stales the handle" {
+ defer testing.reset();
+ defer if (testing.test_session.hasPage()) testing.test_session.removePage();
+
+ var registry = CDPNode.Registry.init(testing.allocator);
+ defer registry.deinit();
+
+ const runtime = try Runtime.init(testing.allocator, testing.test_app, testing.test_session, &registry);
+ defer runtime.deinit();
+
+ // After close() the wrapper is stale; a later method call must error rather
+ // than silently hit whatever page happens to be current.
+ const message = (try runtime.runSource(
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\page.close();
+ \\page.extract({ btn: "#btn" });
+ , "agent-runtime-close.js")).?;
+ try testing.expect(std.mem.indexOf(u8, message, "closed") != null);
+}
+
+test "agent script runtime: a stale page handle is a hard error" {
+ defer testing.reset();
+ defer if (testing.test_session.hasPage()) testing.test_session.removePage();
+
+ var registry = CDPNode.Registry.init(testing.allocator);
+ defer registry.deinit();
+
+ const runtime = try Runtime.init(testing.allocator, testing.test_app, testing.test_session, &registry);
+ defer runtime.deinit();
+
+ // The first page goes stale once a second goto replaces the page; reading
+ // through it must throw, not silently hit the current page.
+ const message = (try runtime.runSource(
+ \\const a = new Page();
+ \\await a.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\await new Page().goto("http://localhost:9582/src/browser/tests/runner/runner1.html");
+ \\a.extract({ btn: "#btn" });
+ , "agent-runtime-stale-handle.js")).?;
+
+ try testing.expect(std.mem.indexOf(u8, message, "no longer valid") != null);
+}
+
test "agent script runtime: extract returns a JavaScript object" {
defer testing.reset();
defer if (testing.test_session.hasPage()) testing.test_session.removePage();
@@ -705,8 +949,9 @@ test "agent script runtime: extract returns a JavaScript object" {
defer runtime.deinit();
try runTestScript(runtime,
- \\goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
- \\const data = extract({
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\const data = page.extract({
\\ button: "#btn",
\\ options: [{
\\ selector: "#sel option",
@@ -721,7 +966,7 @@ test "agent script runtime: extract returns a JavaScript object" {
\\if (data.button !== "Click Me") throw new Error("unexpected button text: " + data.button);
\\if (data.options.length !== 2) throw new Error("unexpected option count: " + data.options.length);
\\if (data.options[1].value !== "opt2") throw new Error("unexpected option value: " + data.options[1].value);
- \\const options = extract({
+ \\const options = page.extract({
\\ options: [{
\\ selector: "#sel option",
\\ limit: 2,
@@ -733,14 +978,14 @@ test "agent script runtime: extract returns a JavaScript object" {
\\});
\\if (typeof options !== "object" || options === null || Array.isArray(options)) throw new Error("single object field should stay an object");
\\if (options.options[0].text !== "Option 1") throw new Error("unexpected option text: " + options.options[0].text);
- \\const direct = extract([{ selector: "#sel option", limit: 1 }]);
+ \\const direct = page.extract([{ selector: "#sel option", limit: 1 }]);
\\if (!Array.isArray(direct)) throw new Error("array schema should return an array");
\\if (direct[0] !== "Option 1") throw new Error("unexpected direct array extract: " + direct[0]);
- \\const saveField = extract({ save: "#btn" });
+ \\const saveField = page.extract({ save: "#btn" });
\\if (saveField.save !== "Click Me") throw new Error("top-level save field should be schema data");
\\let rejectedSaveOption = false;
\\try {
- \\ extract({ schema: { button: "#btn" }, save: "snap" });
+ \\ page.extract({ schema: { button: "#btn" }, save: "snap" });
\\} catch (err) {
\\ rejectedSaveOption = true;
\\}
@@ -759,16 +1004,17 @@ test "agent script runtime: extract tolerates list selectors that match nothing"
defer runtime.deinit();
try runTestScript(runtime,
- \\goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
- \\const empty = extract({ comments: [{ selector: ".no-such-element", fields: { text: "" } }] });
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\const empty = page.extract({ comments: [{ selector: ".no-such-element", fields: { text: "" } }] });
\\if (!Array.isArray(empty.comments) || empty.comments.length !== 0) throw new Error("empty list selector should yield an empty array, not throw");
- \\const bare = extract([".no-such-element"]);
+ \\const bare = page.extract([".no-such-element"]);
\\if (!Array.isArray(bare) || bare.length !== 0) throw new Error("bare empty array schema should yield an empty array");
- \\const mixed = extract({ button: "#btn", comments: [".no-such-element"] });
+ \\const mixed = page.extract({ button: "#btn", comments: [".no-such-element"] });
\\if (mixed.button !== "Click Me" || mixed.comments.length !== 0) throw new Error("a matched scalar beside an empty list should still resolve");
\\let threwOnAllNull = false;
\\try {
- \\ extract({ missing: "#does-not-exist" });
+ \\ page.extract({ missing: "#does-not-exist" });
\\} catch (err) {
\\ threwOnAllNull = true;
\\}
@@ -788,9 +1034,9 @@ test "agent script runtime: strict-mode scripts can call primitives" {
try runTestScript(runtime,
\\"use strict";
- \\const nav = goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
- \\if (!nav.includes("Navigated")) throw new Error("strict-mode goto failed: " + nav);
- \\const text = evaluate("document.getElementById('btn').textContent");
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\const text = page.evaluate("document.getElementById('btn').textContent");
\\if (text !== "Click Me") throw new Error("strict-mode evaluate failed: " + text);
);
}
@@ -805,13 +1051,13 @@ test "agent script runtime: promise microtasks run to completion" {
defer runtime.deinit();
try runTestScript(runtime,
- \\let microtaskRan = false;
- \\Promise.resolve().then(() => { microtaskRan = true; });
- \\if (microtaskRan) throw new Error("microtask ran before the checkpoint");
+ \\globalThis.microtaskRan = false;
+ \\Promise.resolve().then(() => { globalThis.microtaskRan = true; });
+ \\if (globalThis.microtaskRan) throw new Error("microtask ran before the checkpoint");
);
try runTestScript(runtime,
- \\if (!microtaskRan) throw new Error("microtask did not run after the script");
+ \\if (!globalThis.microtaskRan) throw new Error("microtask did not run after the script");
);
}
@@ -826,13 +1072,14 @@ test "agent script runtime: primitives re-entered from argument callbacks stay i
defer runtime.deinit();
try runTestScript(runtime,
- \\goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
\\// toJSON re-enters evaluate mid-marshal; the outer extract must still see "#btn".
- \\const data = extract({ button: { toJSON() { return evaluate("'#btn'"); } } });
+ \\const data = page.extract({ button: { toJSON() { return page.evaluate("'#btn'"); } } });
\\if (data.button !== "Click Me") throw new Error("re-entrant extract corrupted: " + JSON.stringify(data));
\\// toString re-enters a primitive mid-loop; the console buffer must survive.
\\let probed = 0;
- \\console.log("value", { toString() { probed += 1; return evaluate("'ok'"); } }, "tail");
+ \\console.log("value", { toString() { probed += 1; return page.evaluate("'ok'"); } }, "tail");
\\if (probed !== 1) throw new Error("console toString re-entry not exercised");
);
}
@@ -866,17 +1113,17 @@ test "agent script runtime: agent variables persist and page globals are isolate
defer runtime.deinit();
try runTestScript(runtime,
- \\let counter = 1;
+ \\globalThis.counter = 1;
\\if (typeof window !== "undefined") throw new Error("window leaked into agent runtime");
\\if (typeof document !== "undefined") throw new Error("document leaked into agent runtime");
- \\goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
- \\counter += 1;
- \\if (counter !== 2) throw new Error("agent global state did not persist");
+ \\await new Page().goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\globalThis.counter += 1;
+ \\if (globalThis.counter !== 2) throw new Error("agent global state did not persist");
);
try runTestScript(runtime,
- \\counter += 1;
- \\if (counter !== 3) throw new Error("agent global state was reset between scripts");
+ \\globalThis.counter += 1;
+ \\if (globalThis.counter !== 3) throw new Error("agent global state was reset between scripts");
);
}
@@ -892,10 +1139,11 @@ test "agent script runtime: page evaluate cannot see agent primitives or binding
try runTestScript(runtime,
\\const agentOnly = "secret";
- \\goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
- \\if (evaluate("typeof goto") !== "undefined") throw new Error("agent primitive leaked to page evaluate");
- \\if (evaluate("typeof agentOnly") !== "undefined") throw new Error("agent binding leaked to page evaluate");
- \\if (evaluate("typeof document") !== "object") throw new Error("page evaluate did not run in the page context");
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\if (page.evaluate("typeof Page") !== "undefined") throw new Error("agent primitive leaked to page evaluate");
+ \\if (page.evaluate("typeof agentOnly") !== "undefined") throw new Error("agent binding leaked to page evaluate");
+ \\if (page.evaluate("typeof document") !== "object") throw new Error("page evaluate did not run in the page context");
);
}
@@ -926,10 +1174,11 @@ test "agent script runtime: tool errors throw and stop execution" {
defer runtime.deinit();
const message = (try runtime.runSource(
- \\let marker = "before";
- \\goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
- \\click({ selector: "#does-not-exist" });
- \\marker = "after";
+ \\globalThis.marker = "before";
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\page.click({ selector: "#does-not-exist" });
+ \\globalThis.marker = "after";
, "agent-runtime-failure.js")).?;
try testing.expect(std.mem.indexOf(u8, message, "click") != null or
@@ -937,7 +1186,7 @@ test "agent script runtime: tool errors throw and stop execution" {
std.mem.indexOf(u8, message, "#does-not-exist") != null);
try runTestScript(runtime,
- \\if (marker !== "before") throw new Error("script continued after tool failure");
+ \\if (globalThis.marker !== "before") throw new Error("script continued after tool failure");
);
}
@@ -953,35 +1202,35 @@ test "agent script runtime: builtin argument marshalling (positional + options)"
try runTestScript(runtime,
\\// The reported bug: Playwright-style goto(url, options) must merge, not throw.
- \\const nav = goto("http://localhost:9582/src/browser/tests/mcp_actions.html", { timeout: 5000 });
- \\if (!nav.includes("Navigated")) throw new Error("two-arg goto failed: " + nav);
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html", { timeout: 5000 });
\\// waitForState: single required param, positional like waitForSelector.
- \\if (!waitForState("load").includes("reached")) throw new Error("waitForState positional failed");
- \\// Object form still works.
- \\goto({ url: "http://localhost:9582/src/browser/tests/mcp_actions.html", timeout: 5000 });
+ \\if (!page.waitForState("load").includes("reached")) throw new Error("waitForState positional failed");
+ \\// Object form still works; re-navigation rebinds the same page object.
+ \\await page.goto({ url: "http://localhost:9582/src/browser/tests/mcp_actions.html", timeout: 5000 });
\\// Single selector positional.
- \\click("#btn");
- \\if (evaluate("String(window.clicked)") !== "true") throw new Error("click positional failed");
+ \\page.click("#btn");
+ \\if (page.evaluate("String(window.clicked)") !== "true") throw new Error("click positional failed");
\\// Two positionals: selector, value.
- \\fill("#inp", "hello");
- \\if (evaluate("window.inputVal") !== "hello") throw new Error("fill two-positional failed");
- \\selectOption("#sel", "opt2");
- \\if (evaluate("window.selChanged") !== "opt2") throw new Error("selectOption two-positional failed");
+ \\page.fill("#inp", "hello");
+ \\if (page.evaluate("window.inputVal") !== "hello") throw new Error("fill two-positional failed");
+ \\page.selectOption("#sel", "opt2");
+ \\if (page.evaluate("window.selChanged") !== "opt2") throw new Error("selectOption two-positional failed");
\\// Bool positional, and the default-true shorthand when omitted. Assert via the
\\// tool's own report (the synthetic click toggles the DOM state, so .checked is
\\// not a reliable observation of the `checked` argument).
- \\if (!setChecked("#chk").includes("to checked")) throw new Error("setChecked default-true failed");
- \\if (!setChecked("#chk", false).includes("to unchecked")) throw new Error("setChecked bool positional failed");
+ \\if (!page.setChecked("#chk").includes("to checked")) throw new Error("setChecked default-true failed");
+ \\if (!page.setChecked("#chk", false).includes("to unchecked")) throw new Error("setChecked bool positional failed");
\\// Selector-first press, and a null selector for a page/focused key press.
- \\press("#keyTarget", "Enter");
- \\if (evaluate("window.keyPressed") !== "Enter") throw new Error("selector-first press failed");
- \\press(null, "a");
+ \\page.press("#keyTarget", "Enter");
+ \\if (page.evaluate("window.keyPressed") !== "Enter") throw new Error("selector-first press failed");
+ \\page.press(null, "a");
);
// A field set by both a positional and the options object is a conflict.
{
const message = (try runtime.runSource(
- \\goto("http://localhost:9582/src/browser/tests/mcp_actions.html", { url: "http://other" });
+ \\await new Page().goto("http://localhost:9582/src/browser/tests/mcp_actions.html", { url: "http://other" });
, "agent-runtime-conflict.js")).?;
try testing.expect(std.mem.indexOf(u8, message, "invalid arguments") != null);
}
@@ -989,8 +1238,28 @@ test "agent script runtime: builtin argument marshalling (positional + options)"
// More positionals than the tool has fields throws.
{
const message = (try runtime.runSource(
- \\click("#btn", "#extra");
+ \\const page = new Page();
+ \\await page.goto("http://localhost:9582/src/browser/tests/mcp_actions.html");
+ \\page.click("#btn", "#extra");
, "agent-runtime-arity.js")).?;
try testing.expect(std.mem.indexOf(u8, message, "invalid arguments") != null);
}
}
+
+test "agent script runtime: top-level await runs in an async wrapper" {
+ defer testing.reset();
+
+ var registry = CDPNode.Registry.init(testing.allocator);
+ defer registry.deinit();
+
+ const runtime = try Runtime.init(testing.allocator, testing.test_app, testing.test_session, &registry);
+ defer runtime.deinit();
+
+ // `await` on a non-goto promise resolves without touching the browser, and
+ // a top-level `return` surfaces as the (otherwise un-echoed) result.
+ try runTestScript(runtime,
+ \\const x = await Promise.resolve(40);
+ \\if (x + 2 !== 42) throw new Error("top-level await did not resolve: " + x);
+ \\return x + 2;
+ );
+}
diff --git a/src/script/command.zig b/src/script/command.zig
index e76d67409..0902a3b77 100644
--- a/src/script/command.zig
+++ b/src/script/command.zig
@@ -191,6 +191,7 @@ pub const Command = union(enum) {
fn formatJsToolCall(tc: Command.ToolCall, arena: std.mem.Allocator, writer: *std.Io.Writer) (std.Io.Writer.Error || error{OutOfMemory})!void {
const s = tc.schema();
+ // The bare call only; the recorder adds the `page.` receiver and any `await`.
const args_val = tc.args orelse {
try writer.print("{s}();", .{s.tool_name});
return;