// Copyright (C) 2023-2026 Lightpanda (Selecy SAS) // // Francis Bouvier // Pierre Tachoire // // This program is free software: you can redistribute it and/or modify // it under the terms of the GNU Affero General Public License as // published by the Free Software Foundation, either version 3 of the // License, or (at your option) any later version. // // This program is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU Affero General Public License for more details. // // You should have received a copy of the GNU Affero General Public License // along with this program. If not, see . //! 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, the //! PandaScript builtins) so the reference can't drift from the code. const std = @import("std"); const lp = @import("lightpanda"); const Schema = lp.Schema; const SlashCommand = @import("agent/SlashCommand.zig"); const mcp_tools = @import("mcp/tools.zig"); const mcp_resources = @import("mcp/resources.zig"); const protocol = @import("mcp/protocol.zig"); const Tool = lp.tools.Tool; const Writer = std.Io.Writer; pub const Partial = struct { name: []const u8, write: *const fn (w: *Writer) Writer.Error!void, }; 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"; const browser_tools_page = "/reference/browser-tools"; /// Every browser tool, grouped, with its full description and parameters. /// The MCP and agent partials link here instead of repeating it. fn writeBrowserTools(w: *Writer) Writer.Error!void { try w.writeAll(banner); for (std.enums.values(Tool.Group)) |g| { 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 } }); } try w.writeAll("\n"); for (Schema.all()) |*s| { if (s.tool.group() != g) continue; try w.print("### {s}\n\n", .{s.tool_name}); try writeText(w, s.description); try w.writeAll("\n\n"); try writeParams(w, s.parameters); const traits = [_]Flag{ .{ s.tool.isRecorded(), "Recorded in saved scripts." }, .{ s.tool.navigatesToUrl(), "Navigates first when given `url`." }, .{ s.tool.reportsPageState(), "Reports the resulting page state (`url`, `httpStatus`, `title`)." }, }; if (try writeFlags(w, &traits, " ")) try w.writeAll("\n\n"); } } } /// The MCP view: titles and hints per browser tool, plus the MCP-only tools /// and resources in full. fn writeMcpTools(w: *Writer) Writer.Error!void { try w.writeAll(banner); for (std.enums.values(Tool.Group)) |g| { 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 "" } }); try writeHints(w, mt); try w.writeAll(" |\n"); } try w.writeAll("\n"); } var arena: std.heap.ArenaAllocator = .init(std.heap.page_allocator); defer arena.deinit(); try w.writeAll( \\## MCP-only tools \\ \\These tools exist only in the MCP server, not in the agent or in scripts. Over the [HTTP transport](/usage/mcp#http-transport), every tool call runs in the session the `Mcp-Session-Id` header names, falling back to the always-present `default` session; the `session_*` tools create, list and close those sessions. \\ \\ ); for (mcp_tools.extra_tools) |mt| { try w.print("### {s}\n\n", .{mt.name}); if (mt.title) |title| { try w.writeAll("**"); try writeText(w, title); try w.writeAll(".** "); } try writeText(w, mt.description orelse ""); try w.writeAll("\n\n"); const schema = std.json.parseFromSliceLeaky(std.json.Value, arena.allocator(), mt.inputSchema, .{}) catch |err| { std.debug.panic("invalid input schema for MCP tool '{s}': {s}", .{ mt.name, @errorName(err) }); }; try writeParams(w, schema); try w.writeAll("Hints: "); try writeHints(w, mt); try w.writeAll("\n\n"); } try w.writeAll( \\## Resources \\ \\The host application reads these with `resources/read`. The page resources need a loaded page; the skill resources don't. \\ \\| URI | MIME type | Description | \\|---|---|---| \\ ); for (mcp_resources.resource_list) |r| { try w.print("| `{s}` | `{s}` | {f} |\n", .{ r.uri, r.mimeType orelse "", Cell{ .s = r.description orelse r.name } }); } try w.writeAll( \\ \\```json copy \\{"jsonrpc":"2.0","id":2,"method":"resources/read", \\ "params":{"uri":"mcp://page/markdown"}} \\``` \\ \\The `markdown` tool and the `mcp://page/markdown` resource return the same content; the difference is who initiates. The agent calls **tools** during its workflow, while the host application reads **resources**, e.g. an IDE displaying page state in the background. \\ ); } /// The agent REPL's slash commands: meta, LLM-prompt, and one per browser /// tool in the `key=value` syntax the REPL parses. fn writeAgentCommands(w: *Writer) Writer.Error!void { try w.writeAll(banner); try w.writeAll("### Meta commands\n\nThese commands configure the REPL and never reach the model.\n\n| Command | Description |\n|---|---|\n"); for (SlashCommand.meta_commands) |m| { try w.print("| `/{s}", .{m.name}); if (m.hint.len > 0) try w.print(" {f}", .{Cell{ .s = m.hint, .in_code = true }}); try w.print("` | {f} |\n", .{Cell{ .s = m.description }}); } try w.writeAll("\n### LLM commands\n\nThese commands send a prebuilt prompt to the model, so they need a provider.\n\n| Command | Description |\n|---|---|\n"); for (SlashCommand.llm_commands) |row| { try w.print("| `/{s}` | {f} |\n", .{ row.name, Cell{ .s = row.description } }); } try w.writeAll("\n### Browser commands\n\nGiven its fields, every browser tool runs directly as a slash command, with no model call. A lone required argument can be passed positionally; the rest take `key=value` or a JSON object.\n\n"); try w.writeAll("These take only `key=value`, and also accept a prompt in place of their fields:"); var first = true; for (Schema.all()) |*s| { if (!Schema.takesPrompt(s.tool)) continue; try w.print("{s} `/{s}`", .{ if (first) "" else ",", s.tool_name }); first = false; } try w.writeAll(". `/click the sign in button` asks the model for the selector, and the call it makes is what `/save` records.\n\n| Command | Description |\n|---|---|\n"); for (std.enums.values(Tool.Group)) |g| { for (Schema.all()) |*s| { if (s.tool.group() != g) continue; try w.print("| [`/{s}", .{s.tool_name}); for (s.hints) |h| try w.print(" {f}", .{Cell{ .s = h.fragment, .in_code = true }}); try w.print("`]({f}) | {f} |\n", .{ Anchor{ .page = browser_tools_page, .name = s.tool_name }, Cell{ .s = s.summary } }); } } } /// The methods `new Page()` carries in a PandaScript, i.e. the scriptable tools /// plus the runtime's own page methods, and the `console` global. fn writePandascriptBuiltins(w: *Writer) Writer.Error!void { const table_head = "| Method | Call | Returns | Summary |\n|---|---|---|---|\n"; try w.writeAll(banner); for (std.enums.values(Tool.Group)) |g| { if (!hasScriptable(g)) continue; try writeGroupHeading(w, g, "methods", table_head); for (Schema.all()) |*s| { if (s.tool.group() != g or !s.tool.isScriptable()) continue; try w.print("| [`{s}`]({f}) | `", .{ s.tool_name, Anchor{ .page = browser_tools_page, .name = s.tool_name } }); try lp.skill.writeSignature(w, s); // Non-null: `scriptReturns` covers every scriptable tool. try w.print("` | {f} | {f} |\n", .{ Cell{ .s = Schema.scriptReturns(s.tool).? }, Cell{ .s = s.summary } }); } try w.writeAll("\n"); } try w.writeAll("## Page lifecycle\n\n" ++ table_head); for (lp.Runtime.page_methods) |m| { try w.print("| `{s}` | `page.{s}()` | {f} | {f} |\n", .{ m.name, m.name, Cell{ .s = m.returns }, Cell{ .s = m.summary } }); } 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" }); } } fn hasScriptable(g: Tool.Group) bool { for (std.enums.values(Tool)) |t| { if (t.group() == g and t.isScriptable()) 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, or save a URL to a file" }, .reading => .{ "Reading the page", "read the loaded page without modifying it" }, .extraction => .{ "Data extraction and scripting", "return structured results from the loaded page" }, .interaction => .{ "Interacting with the page", "dispatch real DOM events on the page" }, .waiting => .{ "Waiting", "block until the page reaches a condition" }, .state => .{ "State and debugging", "inspect browser state outside the DOM" }, .page_tools => .{ "Page tools (WebMCP)", "list and call the tools a page registers for agents through WebMCP" }, }; 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 /// object. fn writeParams(w: *Writer, schema: std.json.Value) Writer.Error!void { const props = schema.object.get("properties") orelse return w.writeAll("No arguments.\n\n"); if (props.object.count() == 0) return w.writeAll("No arguments.\n\n"); const required: []const std.json.Value = if (schema.object.get("required")) |r| r.array.items else &.{}; try w.writeAll("| Argument | Type | Required | Description |\n|---|---|---|---|\n"); var it = props.object.iterator(); while (it.next()) |entry| { const name = entry.key_ptr.*; const prop = entry.value_ptr.*.object; try w.print("| `{s}` | ", .{name}); try writeType(w, prop); try w.print(" | {s} | ", .{if (isRequired(required, name)) "yes" else "no"}); var sep: []const u8 = ""; if (prop.get("description")) |d| { try w.print("{f}", .{Cell{ .s = d.string }}); sep = " "; } if (prop.get("enum")) |values| { try w.print("{s}One of ", .{sep}); for (values.array.items, 0..) |v, i| { if (i > 0) try w.writeAll(", "); try w.print("`{s}`", .{v.string}); } try w.writeAll("."); sep = " "; } if (prop.get("default")) |d| { try w.print("{s}Defaults to `", .{sep}); try std.json.Stringify.value(d, .{}, w); try w.writeAll("`."); sep = " "; } if (prop.get("properties")) |sub| { try w.print("{s}Keys:", .{sep}); var sub_it = sub.object.iterator(); var first = true; while (sub_it.next()) |s| : (first = false) { try w.print("{s} `{s}`", .{ if (first) "" else ",", s.key_ptr.* }); } try w.writeAll("."); } try w.writeAll(" |\n"); } try w.writeAll("\n"); } fn writeType(w: *Writer, prop: std.json.ObjectMap) Writer.Error!void { const ty = prop.get("type") orelse return w.writeAll("any"); if (std.mem.eql(u8, ty.string, "array")) { const item_ty = if (prop.get("items")) |items| if (items.object.get("type")) |t| t.string else "any" else "any"; return w.print("{s}[]", .{item_ty}); } try w.writeAll(ty.string); } fn isRequired(required: []const std.json.Value, name: []const u8) bool { for (required) |r| { if (std.mem.eql(u8, r.string, name)) return true; } return false; } fn writeHints(w: *Writer, mt: protocol.Tool) Writer.Error!void { const a = mt.annotations orelse protocol.ToolAnnotations{}; const hints = [_]Flag{ .{ a.readOnlyHint, "read-only" }, .{ a.destructiveHint, "destructive" }, .{ a.idempotentHint, "idempotent" }, .{ a.openWorldHint, "open-world" }, .{ mt.outputSchema != null, "page state" }, }; if (!try writeFlags(w, &hints, ", ")) try w.writeAll("—"); } const Flag = struct { bool, []const u8 }; /// Writes the labels of the set flags, separated by `sep`. Returns whether /// any was set. fn writeFlags(w: *Writer, flags: []const Flag, sep: []const u8) Writer.Error!bool { var wrote = false; for (flags) |flag| { if (!flag[0]) continue; if (wrote) try w.writeAll(sep); try w.writeAll(flag[1]); wrote = true; } return wrote; } /// A link target to a tool's heading. Nextra slugs headings in lowercase, so /// `### nodeDetails` is `#nodedetails`. const Anchor = struct { page: []const u8 = "", name: []const u8, pub fn format(self: Anchor, w: *Writer) Writer.Error!void { try w.print("{s}#", .{self.page}); for (self.name) |c| try w.writeByte(std.ascii.toLower(c)); } }; /// Text for a GFM table cell: `|` ends the cell even inside a code span, and /// a newline ends the row. `in_code` is for text already inside a code span. const Cell = struct { s: []const u8, in_code: bool = false, pub fn format(self: Cell, w: *Writer) Writer.Error!void { if (self.in_code) return writeCode(w, self.s, true); try writeEscaped(w, self.s, true); } }; /// Prose for MDX: outside code spans and fences, `<` would open JSX and `{` /// an expression. fn writeText(w: *Writer, s: []const u8) Writer.Error!void { try writeEscaped(w, s, false); } fn writeCode(w: *Writer, s: []const u8, cell: bool) Writer.Error!void { if (!cell) return w.writeAll(s); for (s) |c| switch (c) { '|' => try w.writeAll("\\|"), else => try w.writeByte(c), }; } fn writeEscaped(w: *Writer, s: []const u8, cell: bool) Writer.Error!void { var i: usize = 0; while (i < s.len) { if (s[i] == '`') { const run_end = std.mem.findNonePos(u8, s, i, "`") orelse s.len; const fence = s[i..run_end]; try w.writeAll(fence); i = run_end; if (std.mem.findPos(u8, s, run_end, fence)) |close| { try writeCode(w, s[run_end..close], cell); try w.writeAll(fence); i = close + fence.len; } continue; } switch (s[i]) { '<' => try w.writeAll("<"), '{' => try w.writeAll("\\{"), '}' => try w.writeAll("\\}"), '|' => try w.writeAll(if (cell) "\\|" else "|"), '\n' => try w.writeAll(if (cell) " " else "\n"), else => try w.writeByte(s[i]), } i += 1; } } const testing = std.testing; fn render(write: *const fn (w: *Writer) Writer.Error!void) ![]u8 { var aw: Writer.Allocating = .init(testing.allocator); errdefer aw.deinit(); try write(&aw.writer); return aw.toOwnedSlice(); } test "docs: browser-tools documents every tool exactly once" { const out = try render(writeBrowserTools); defer testing.allocator.free(out); for (std.enums.values(Tool)) |t| { var buf: [64]u8 = undefined; const heading = try std.mem.print(&buf, "\n### {s}\n", .{@tagName(t)}); try testing.expectEqual(1, std.mem.count(u8, out, heading)); } } test "docs: mcp-tools lists every MCP tool and resource" { const out = try render(writeMcpTools); defer testing.allocator.free(out); for (mcp_tools.browser_tool_list ++ mcp_tools.extra_tools) |mt| { var row_buf: [64]u8 = undefined; var heading_buf: [64]u8 = undefined; const row = try std.mem.print(&row_buf, "| [`{s}`]", .{mt.name}); const heading = try std.mem.print(&heading_buf, "\n### {s}\n", .{mt.name}); try testing.expectEqual(1, std.mem.count(u8, out, row) + std.mem.count(u8, out, heading)); } for (mcp_resources.resource_list) |r| { try testing.expect(std.mem.find(u8, out, r.uri) != null); } } test "docs: agent-commands covers every slash command" { const out = try render(writeAgentCommands); defer testing.allocator.free(out); for (SlashCommand.all_names) |name| { var buf: [64]u8 = undefined; const cmd = try std.mem.print(&buf, "`/{s}", .{name}); try testing.expect(std.mem.find(u8, out, cmd) != null); } try testing.expect(std.mem.find(u8, out, "[`/goto [timeout=…]") != null); } test "docs: pandascript-builtins lists exactly the scriptable 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.isScriptable()), std.mem.count(u8, out, call)); try testing.expectEqual(t.isScriptable(), Schema.scriptReturns(t) != null); } try testing.expect(std.mem.find(u8, out, "`page.extract(schema)`") != null); try testing.expect(std.mem.find(u8, out, "| A status line starting `Clicked element ()`, ") != null); // No signature takes a node id; the one mention is what `waitForSelector` returns. try testing.expectEqual(1, std.mem.count(u8, out, "backendNodeId")); 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); } test "docs: escaping leaves code spans alone" { var aw: Writer.Allocating = .init(testing.allocator); defer aw.deinit(); try aw.writer.print("{f}", .{Cell{ .s = "a {c} `x|{}` d|e\nf `open" }}); try testing.expectEqualStrings("a <b> \\{c\\} `x\\|{}` d\\|e f `open", aw.written()); } test "docs: prose keeps fenced blocks verbatim" { var aw: Writer.Allocating = .init(testing.allocator); defer aw.deinit(); try writeText(&aw.writer, "Shapes:\n```text\n\"\" → {a}\n```\nAfter ."); try testing.expectEqualStrings("Shapes:\n```text\n\"\" → {a}\n```\nAfter <x>.", aw.written()); }