pandascript

Writing Lightpanda agent scripts

Run with:

./lightpanda agent 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.

Call	Notes
new Page()	Makes a page object. No navigation yet — call page.goto(url) before any other method. Make several to navigate in parallel (fan-out, best practice 2).
page.close()	Marks the page done; later method calls on it error. The page is otherwise reclaimed at script end.
await page.goto(url[, { timeout }])	Async — must be awaited. Navigates the page (re-navigating reuses the same object). Waits for load. Rejects on navigation failure; a timeout does NOT reject (the page may still be usable). Default timeout 10000 ms.
page.evaluate(script[, { url, timeout, save }])	Page-side JS escape hatch; returns text (JSON for objects/arrays).
page.extract(schema)	The only primitive returning a real JS value (object/array). The schema is its only argument. See schema below.
page.click(selector)
page.fill(selector, value)
page.scroll([{ x, y }])
page.waitForSelector(selector[, { timeout }])	waitFor* default timeout 5000 ms.
page.waitForScript(script[, { timeout }])	Re-evaluates page JS until truthy.
page.waitForState(state[, { timeout }])	state: one of "load", "domcontentloaded", "networkalmostidle", "networkidle", "done".
page.hover(selector)
page.press(selector, key)	Selector first! page.press("Enter") binds "Enter" to selector and fails — use page.press(null, "Enter") or page.press({ key: "Enter" }).
page.selectOption(selector, value)
page.setChecked(selector[, checked])	checked defaults to true.