Skip to content

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.zig
index 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.zig
index 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) catch
return 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.zig
index 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 {