PandaScript Reference

A PandaScript is a plain JavaScript automation script that Lightpanda runs directly, with no LLM call. Learn the execution model and see complete examples in the PandaScript usage page.

lightpanda run <my_script>.js

The script context installs two globals, Page and console, and nothing else from the browser toolset. A script creates a page with new Page(), then calls every primitive below as a method on that page. Every timeout is in milliseconds.

Navigation

Extraction and page scripting

evaluate runs a JavaScript string inside the page, where window and document exist, and extract resolves its schema selectors there too. That code runs in the page, so it cannot see the variables of your agent script.

Extraction schema

page.extract(...) takes a schema object mapping output field names to CSS-selector specs. The schema forms are:

Passing the schema. These three calls are equivalent:

page.extract({ title: "h1" });
page.extract({ schema: { title: "h1" } });
page.extract('{ "title": "h1" }');

The object form accepts only the schema key, so the REPL’s save option is rejected in scripts.

What you get back. Every extracted value is a string (trimmed text or a raw attribute) or null; parse numbers yourself. The result mirrors the top-level schema:

Interaction

Every interaction below reports the page URL and title reached after the action, so a script can tell whether it triggered a navigation. A click returns, in full:

Clicked element (selector: a.login). Page url: https://example.com/app, title: Dashboard

scroll is the exception and reports only its position.

Waiting

The states waitForState accepts:

Console

console is the second and last global. It carries five methods, split across the two output streams:

They print for you to read. A script’s own output is whatever it returns from the top level, which is where objects and arrays get JSON-formatted.

Calling conventions

Positional and options arguments. Each primitive takes its leading arguments positionally, with an optional trailing options object for the rest:

• Mix a positional with an options object: waitForSelector("#row", { timeout: 2000 }).
• Or pass one object with everything: waitForSelector({ selector: "#row", timeout: 2000 }). This is equivalent, and it’s the shape /save records into saved scripts.
• An option can never be passed as a bare positional: waitForSelector("#row", 2000) is an error.
• A null positional omits that argument: press(null, "Enter") presses on the document, not necessarily the focused element.
• Setting the same field both positionally and in the options object is an error: goto(url, { url: ... }) throws invalid arguments.
• Arguments must be JSON-serializable. undefined, functions, and symbols throw invalid arguments; a cyclic object throws V8’s own TypeError: Converting circular structure to JSON instead, since it fails before Lightpanda’s own check runs.

Selectors, not node IDs. Script primitives address elements by CSS selector only. tree, findElement, and nodeDetails hand out backendNodeIds but 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 (the leading number on a /tree line, or a /findElement hit), run /nodeDetails backendNodeId=<id> to get a durable CSS selector, then paste that into your script.

Secrets via $LP_* placeholders. String arguments can contain $LP_* placeholders, resolved inside the Lightpanda process. This keeps credentials out of recorded scripts and LLM prompts. Recordings scrub resolved LP_* values back to placeholders.

Errors

Primitive failures throw JavaScript exceptions. The complete list: