Lightpanda: the headless browser designed for AI and automation
docs: share the skill's script signature, list page methods from the runtime
Adrià Arrufat4eb68ffc2ef8
diff --git a/src/docs.zig b/src/docs.zigindex be3f50bc3..9ef1248d5 100644--- a/src/docs.zig+++ b/src/docs.zig@@ -170,81 +170,36 @@ fn writeAgentCommands(w: *Writer) Writer.Error!void {}/// The methods `new Page()` carries in a PandaScript, i.e. the recorded tools-/// plus `close`, and the `console` global.+/// plus the runtime's own page methods, and the `console` global.fn writePandascriptBuiltins(w: *Writer) Writer.Error!void {+ const table_head = "| Method | Call | Summary |\n|---|---|---|\n";try w.writeAll(banner);for (std.enums.values(Tool.Group)) |g| {- var heading = false;+ if (!hasRecorded(g)) continue;+ try writeGroupHeading(w, g, "methods", table_head);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 lp.skill.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);+ try w.writeAll("\n");}- 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("## Page lifecycle\n\n" ++ table_head);+ for (lp.Runtime.page_methods) |m| {+ try w.print("| `{s}` | `page.{s}()` | {f} |\n", .{ m.name, m.name, Cell{ .s = m.summary } });}- 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;+ try w.writeAll("\n## 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" });}- return true;}-fn isRequiredField(s: *const Schema, name: []const u8) bool {- for (s.required) |r| {- if (std.mem.eql(u8, r, name)) return true;+fn hasRecorded(g: Tool.Group) bool {+ for (std.enums.values(Tool)) |t| {+ if (t.group() == g and t.isRecorded()) return true;}return false;}@@ -472,9 +427,12 @@ test "docs: pandascript-builtins lists exactly the recorded tools" {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, "`page.extract(schema)`") != null);try testing.expect(std.mem.find(u8, out, "backendNodeId") == null);+ for (lp.Runtime.page_methods) |m| {+ var buf: [64]u8 = undefined;+ try testing.expect(std.mem.find(u8, out, try std.mem.print(&buf, "`page.{s}()`", .{m.name})) != null);+ }try testing.expect(std.mem.find(u8, out, "| `console.warn` | stderr |") != null);}diff --git a/src/script/Runtime.zig b/src/script/Runtime.zigindex b93e2eff6..c394e6eac 100644--- a/src/script/Runtime.zig+++ b/src/script/Runtime.zig@@ -415,10 +415,24 @@ fn construct(self: *Runtime, info: *const v8.FunctionCallbackInfo) void {self.installFunction(context, this, @tagName(data.tool), primitiveCallback, data) catchreturn self.throwError("failed to construct page");}- self.installFunction(context, this, "close", closeCallback, self) catch- return self.throwError("failed to construct page");+ for (page_methods) |m| {+ self.installFunction(context, this, m.name, m.callback, self) catch+ return self.throwError("failed to construct page");+ }}+pub const PageMethod = struct {+ name: []const u8,+ callback: Callback,+ /// Rendered by `zig build docs`.+ summary: []const u8,+};++/// The page methods besides the recorded tools.+pub const page_methods = [_]PageMethod{+ .{ .name = "close", .callback = closeCallback, .summary = "Stales the handle, so later calls on it fail. The page itself is reclaimed on the next `goto` or at script end." },+};+/// Property carrying a page handle's claim on a live frame. Numeric while the/// page is navigated; absent/undefined once never-navigated or closed.const frame_id_key = "__lpFrameId";diff --git a/src/script/skill.zig b/src/script/skill.zigindex 590719344..43264c92c 100644--- a/src/script/skill.zig+++ b/src/script/skill.zig@@ -100,30 +100,8 @@ fn writeReference(w: *std.Io.Writer) std.Io.Writer.Error!void {fn writeRow(w: *std.Io.Writer, s: *const Schema) std.Io.Writer.Error!void {try w.writeAll("| `");- if (s.tool.isAsync()) try w.writeAll("await ");- try w.print("page.{s}(", .{s.tool_name});- for (s.positional, 0..) |p, i| {- const optional = positionalOptional(s, p);- // A trailing optional positional is bracketed; a leading one- // (press's selector) renders plain and its note explains `null`.- if (i > 0) try w.writeAll(if (optional) "[, " else ", ");- try w.writeAll(p);- if (i > 0 and optional) try w.writeAll("]");- }- // The script form of extract takes the schema as its only argument- // (`Runtime.extractArgs`); every other tool accepts the options object.- if (s.tool != .extract and hasOptions(s)) {- try w.writeAll(if (s.positional.len > 0) "[, { " else "[{ ");- var i: usize = 0;- for (s.fields) |f| {- if (!isOption(s, f.name)) continue;- if (i > 0) try w.writeAll(", ");- try w.writeAll(f.name);- i += 1;- }- try w.writeAll(" }]");- }- try w.writeAll(")` | ");+ try writeSignature(w, s);+ try w.writeAll("` | ");var wrote = false;if (s.tool.isAsync()) {@@ -156,6 +134,35 @@ fn writeRow(w: *std.Io.Writer, s: *const Schema) std.Io.Writer.Error!void {try w.writeAll(" |\n");}+/// The script call `await page.tool(positional…[, { option… }])`, as the+/// runtime marshals it.+pub fn writeSignature(w: *std.Io.Writer, s: *const Schema) std.Io.Writer.Error!void {+ if (s.tool.isAsync()) try w.writeAll("await ");+ try w.print("page.{s}(", .{s.tool_name});+ for (s.positional, 0..) |p, i| {+ const optional = positionalOptional(s, p);+ // A trailing optional positional is bracketed; a leading one+ // (press's selector) renders plain and its note explains `null`.+ if (i > 0) try w.writeAll(if (optional) "[, " else ", ");+ try w.writeAll(p);+ if (i > 0 and optional) try w.writeAll("]");+ }+ // The script form of extract takes the schema as its only argument+ // (`Runtime.extractArgs`); every other tool accepts the options object.+ if (s.tool != .extract and hasOptions(s)) {+ try w.writeAll(if (s.positional.len > 0) "[, { " else "[{ ");+ var i: usize = 0;+ for (s.fields) |f| {+ if (!isOption(s, f.name)) continue;+ if (i > 0) try w.writeAll(", ");+ try w.writeAll(f.name);+ i += 1;+ }+ try w.writeAll(" }]");+ }+ try w.writeAll(")");+}+/// Non-positional schema fields surfacing in the script signature./// `backendNodeId` is ephemeral and has no script form.fn isOption(s: *const Schema, field_name: []const u8) bool {