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.zigindex 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.zigindex 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,