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.mdindex 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 theweb 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`, npmpackage loading, command-line argument API, or Node network/filesystem API.- Page scripts cannot see agent variables or Lightpanda primitives. Agentscripts 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, acrossnavigations and primitive calls. A later `lightpanda agent script.js` runstarts 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 unlessyou 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, andcyclic 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 inthe script context, and a raw node ID wouldn't survive replay anyway. Whenyou're exploring in the REPL and have a `backendNodeId` — e.g. the leadingnumber 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 timeoutdoes **not** throw: the call returns `"Navigation started but the page did notfinish 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` — parsenumbers 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 arewrong", 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 agentcontext keeps the data across navigations, so the assembly happens in plainJavaScript. 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 whosefields 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 Lightpandaprocess. 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:```jstry {- 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 ExampleThis 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.```jsconst 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.mdindex 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 isJavaScript:```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 againstthe 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 logicAgent 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 agentvariables 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.mdindex 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 itsstring in the current page context; page scripts can't see agent variablesor 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 wholesession. 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 placeholderbefore 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.zigindex 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` commanddiff --git a/src/browser/tools.zig b/src/browser/tools.zigindex 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.zigindex 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.zigindex 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.zigindex 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) orelsereturn 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) orelsereturn 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.FunctionCallbackInferror.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, ®istry);+ 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, ®istry);+ 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, ®istry);+ 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, ®istry);+ 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 idefer 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 isolatedefer 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 bindingtry 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, ®istry);+ 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.zigindex 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;