Skip to content

Add Reference section for PandaScript - #78

Open
cdebled wants to merge 3 commits into
mainfrom
pandascript-reference
Open

Add Reference section for PandaScript#78
cdebled wants to merge 3 commits into
mainfrom
pandascript-reference

Conversation

@cdebled

@cdebled cdebled commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add a new reference/pandascript page documenting the primitives, calling conventions, extraction schema and full error list of the PandaScript runtime, sourced from the browser's src/script/Runtime.zig (execution semantics and error strings), src/script/Schema.zig (positional argument order), src/browser/tools.zig (recorded tool list, return values, timeout defaults) and src/Config.zig (the waitForState states)
  • Slim usage/pandascript.mdx down to a practical guide (execution model, worked examples), linking to the new reference for exhaustive detail
  • Fix several correctness issues found while writing the reference, checked against browser @ 33763f70 (origin/main):
    • Top-level await and goto are asynchronous, not synchronous
    • A script's output comes from a return statement, not its last bare expression
    • goto's resolve/reject behavior
    • press's target-element behavior
    • page handle is no longer valid doesn't actually happen on every same-object re-goto; a successful re-goto rebinds the handle and keeps working. The real trigger is a re-goto that fails or times out: the old frame is torn down before the new navigation's outcome is known, so a rejected navigation leaves the handle bound to an already-removed frame
    • Added the missing generic <tool> failed: <ZigErrorName> fallback error, arguably the most common one in practice (e.g. click failed: NodeNotFound for a bad selector)

⚠️ Two bugs found in browser, not in these docs — both in src/script/skill.zig (the LLM-facing prompt used by /save), worth fixing upstream:

  • skill.zig:195's .goto note claims "a timeout does NOT reject"; Runtime.zig's settlePending (.timed_out branch) rejects with "navigation timed out". The opposite is true.
  • skill.zig:313's "Common errors" table has the same wrong page handle is no longer valid explanation described above.

This PR is part of a series splitting the new Reference section (CLI, MCP tools, HTTP API, PandaScript) into smaller pieces so each can be reviewed and merged on its own: #76 (CLI reference), #77 (MCP tools reference).

Two related cross-references belong to #76's files — reference/cli/agent.mdx's /save command row and usage/agent.mdx's extraction-schema link, both pointing at /reference/pandascript — and aren't included here to keep this PR scoped to its own files. Add them to #76 once this PR merges.

@arrufat arrufat left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really nice work on this one. I checked everything against browser main (f55aa1a66): the error strings, positional orders, extract forms, wait semantics and return strings all match the source, and both skill.zig bugs you flagged are real and still unfixed. Two small drifts from changes merged after your snapshot, plus one broken anchor, in the inline comments below.

Comment thread src/content/reference/pandascript.mdx Outdated
Comment thread src/content/reference/pandascript.mdx Outdated
Comment thread src/content/usage/pandascript.mdx Outdated
…tForScript's state-dependent timeout, fix broken #primitives anchor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants