pandascript

Writing Lightpanda agent scripts

Run with:

./lightpanda run script.js

Mental model (get this right first)

The script runs in its own V8 context — neither the page nor Node.js:

• 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, …).
• 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, discarding the old page — read it before navigating away. Independent URLs don't share a page: make a new Page() for each and load them in parallel (fan-out, best practice 2).
• 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.
• 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.