Skip to content

Lightpanda: the headless browser designed for AI and automation

docs: generate the PandaScript builtins partial

Adrià Arrufata5e656fce8cf
diff --git a/src/docs.zig b/src/docs.zig
index 43af87553..be3f50bc3 100644
--- a/src/docs.zig
+++ b/src/docs.zig
@@ -19,8 +19,8 @@
//! Reference partials for the docs site (lightpanda.io/docs), written by
//! `zig build docs`. Each is an MDX fragment with no frontmatter that a
//! handwritten docs page imports, rendered from the registries the runtime
-//! serves (`lp.tools`, the MCP tool list, the REPL slash commands) so the
-//! reference can't drift from the code.
+//! serves (`lp.tools`, the MCP tool list, the REPL slash commands, the
+//! PandaScript builtins) so the reference can't drift from the code.
const std = @import("std");
const lp = @import("lightpanda");
@@ -42,6 +42,7 @@ pub const partials = [_]Partial{
.{ .name = "browser-tools.mdx", .write = writeBrowserTools },
.{ .name = "mcp-tools.mdx", .write = writeMcpTools },
.{ .name = "agent-commands.mdx", .write = writeAgentCommands },
+ .{ .name = "pandascript-builtins.mdx", .write = writePandascriptBuiltins },
};
const banner = "{/* Generated by `zig build docs` from the lightpanda browser source. Do not edit. */}\n\n";
@@ -52,7 +53,7 @@ const browser_tools_page = "/reference/browser-tools";
fn writeBrowserTools(w: *Writer) Writer.Error!void {
try w.writeAll(banner);
for (std.enums.values(Tool.Group)) |g| {
- try writeGroupHeading(w, g, "| Tool | Summary |\n|---|---|\n");
+ try writeGroupHeading(w, g, "tools", "| Tool | Summary |\n|---|---|\n");
for (Schema.all()) |*s| {
if (s.tool.group() != g) continue;
try w.print("| [`{s}`]({f}) | {f} |\n", .{ s.tool_name, Anchor{ .name = s.tool_name }, Cell{ .s = s.summary } });
@@ -80,7 +81,7 @@ fn writeBrowserTools(w: *Writer) Writer.Error!void {
fn writeMcpTools(w: *Writer) Writer.Error!void {
try w.writeAll(banner);
for (std.enums.values(Tool.Group)) |g| {
- try writeGroupHeading(w, g, "| Tool | Title | Hints |\n|---|---|---|\n");
+ try writeGroupHeading(w, g, "tools", "| Tool | Title | Hints |\n|---|---|---|\n");
for (std.enums.values(Tool), mcp_tools.browser_tool_list) |t, mt| {
if (t.group() != g) continue;
try w.print("| [`{s}`]({f}) | {f} | ", .{ mt.name, Anchor{ .page = browser_tools_page, .name = mt.name }, Cell{ .s = mt.title orelse "" } });
@@ -168,7 +169,87 @@ fn writeAgentCommands(w: *Writer) Writer.Error!void {
}
}
-fn writeGroupHeading(w: *Writer, g: Tool.Group, table_head: []const u8) Writer.Error!void {
+/// The methods `new Page()` carries in a PandaScript, i.e. the recorded tools
+/// plus `close`, and the `console` global.
+fn writePandascriptBuiltins(w: *Writer) Writer.Error!void {
+ try w.writeAll(banner);
+ for (std.enums.values(Tool.Group)) |g| {
+ var heading = false;
+ for (Schema.all()) |*s| {
+ if (s.tool.group() != g or !s.tool.isRecorded()) continue;
+ if (!heading) {
+ try writeGroupHeading(w, g, "methods", "| Method | Call | Summary |\n|---|---|---|\n");
+ heading = true;
+ }
+ try w.print("| [`{s}`]({f}) | `", .{ s.tool_name, Anchor{ .page = browser_tools_page, .name = s.tool_name } });
+ try writeSignature(w, s);
+ try w.print("` | {f} |\n", .{Cell{ .s = s.summary }});
+ if (s.tool == .goto) {
+ try w.writeAll("| `close` | `page.close()` | Stales the handle, so later calls on it fail. The page itself is reclaimed on the next `goto` or at script end. |\n");
+ }
+ }
+ if (heading) try w.writeAll("\n");
+ }
+
+ try w.writeAll("## Console\n\n| Method | Writes to |\n|---|---|\n");
+ for (std.enums.values(lp.Runtime.ConsoleMethod)) |m| {
+ try w.print("| `console.{s}` | {s} |\n", .{ @tagName(m), if (m.writesStderr()) "stderr" else "stdout" });
+ }
+}
+
+/// `page.tool(positional…[, { option?… }])`, the call the runtime marshals.
+/// `backendNodeId` is left out: it never survives replay, so scripts address
+/// elements by selector only.
+fn writeSignature(w: *Writer, s: *const Schema) Writer.Error!void {
+ try w.print("{s}page.{s}(", .{ if (s.tool.isAsync()) "await " else "", s.tool_name });
+ for (s.positional, 0..) |p, i| {
+ if (i > 0) try w.writeAll(", ");
+ try w.writeAll(p);
+ }
+
+ const props = (s.parameters.object.get("properties") orelse return w.writeAll(")")).object;
+ var options: usize = 0;
+ var any_required = false;
+ for (props.keys()) |name| {
+ if (isOption(s, name)) {
+ options += 1;
+ any_required = any_required or isRequiredField(s, name);
+ }
+ }
+ if (options == 0) return w.writeAll(")");
+
+ const optional_bag = s.positional.len > 0 and !any_required;
+ if (optional_bag) try w.writeAll("[");
+ if (s.positional.len > 0) try w.writeAll(", ");
+ try w.writeAll("{ ");
+ var first = true;
+ for (props.keys()) |name| {
+ if (!isOption(s, name)) continue;
+ if (!first) try w.writeAll(", ");
+ first = false;
+ try w.print("{s}{s}", .{ name, if (isRequiredField(s, name)) "" else "?" });
+ }
+ try w.writeAll(" }");
+ if (optional_bag) try w.writeAll("]");
+ try w.writeAll(")");
+}
+
+fn isOption(s: *const Schema, name: []const u8) bool {
+ if (std.mem.eql(u8, name, "backendNodeId")) return false;
+ for (s.positional) |p| {
+ if (std.mem.eql(u8, p, name)) return false;
+ }
+ return true;
+}
+
+fn isRequiredField(s: *const Schema, name: []const u8) bool {
+ for (s.required) |r| {
+ if (std.mem.eql(u8, r, name)) return true;
+ }
+ return false;
+}
+
+fn writeGroupHeading(w: *Writer, g: Tool.Group, noun: []const u8, table_head: []const u8) Writer.Error!void {
const title, const scope = switch (g) {
.navigation => .{ "Navigation and search", "bring a page into the browser" },
.reading => .{ "Reading the page", "read the loaded page without modifying it" },
@@ -177,7 +258,7 @@ fn writeGroupHeading(w: *Writer, g: Tool.Group, table_head: []const u8) Writer.E
.waiting => .{ "Waiting", "block until the page reaches a condition" },
.state => .{ "State and debugging", "inspect browser state outside the DOM" },
};
- try w.print("## {s}\n\nThese tools {s}.\n\n{s}", .{ title, scope, table_head });
+ try w.print("## {s}\n\nThese {s} {s}.\n\n{s}", .{ title, noun, scope, table_head });
}
/// An `Argument | Type | Required | Description` table for a JSON Schema
@@ -383,6 +464,20 @@ test "docs: agent-commands covers every slash command" {
try testing.expect(std.mem.find(u8, out, "[`/goto <url> [timeout=…]") != null);
}
+test "docs: pandascript-builtins lists exactly the recorded tools" {
+ const out = try render(writePandascriptBuiltins);
+ defer testing.allocator.free(out);
+ for (std.enums.values(Tool)) |t| {
+ var buf: [64]u8 = undefined;
+ const call = try std.mem.print(&buf, "page.{s}(", .{@tagName(t)});
+ try testing.expectEqual(@intFromBool(t.isRecorded()), std.mem.count(u8, out, call));
+ }
+ try testing.expect(std.mem.find(u8, out, "`await page.goto(url[, { timeout?, waitUntil? }])`") != null);
+ try testing.expect(std.mem.find(u8, out, "`page.scroll({ selector?, x?, y? })`") != null);
+ try testing.expect(std.mem.find(u8, out, "backendNodeId") == null);
+ try testing.expect(std.mem.find(u8, out, "| `console.warn` | stderr |") != null);
+}
+
test "docs: escaping leaves code spans alone" {
var aw: Writer.Allocating = .init(testing.allocator);
defer aw.deinit();
diff --git a/src/script/Runtime.zig b/src/script/Runtime.zig
index f8d86ec94..b93e2eff6 100644
--- a/src/script/Runtime.zig
+++ b/src/script/Runtime.zig
@@ -85,14 +85,14 @@ const PendingGoto = struct {
}
};
-const ConsoleMethod = enum {
+pub const ConsoleMethod = enum {
debug,
@"error",
info,
log,
warn,
- fn writesStderr(self: ConsoleMethod) bool {
+ pub fn writesStderr(self: ConsoleMethod) bool {
return switch (self) {
.@"error", .warn => true,
.debug, .info, .log => false,