Skip to content

Lightpanda: the headless browser designed for AI and automation

mcp: expose Chrome-matched ARIA states in semantic tree

Robert McConnell725ff74861e5
diff --git a/src/SemanticTree.zig b/src/SemanticTree.zig
index 2b5a50def..5b5d20894 100644
--- a/src/SemanticTree.zig
+++ b/src/SemanticTree.zig
@@ -254,7 +254,7 @@ fn linePriority(node: *Node, data: *const NodeData, focused: ?*Node) Priority {
if (node.is(Element)) |el| {
if (std.mem.eql(u8, el.getAttributeSafe(comptime .wrap("aria-invalid")) orelse "", "true")) return .critical;
}
- if (data.value != null or data.options != null or data.checked != null) return .named;
+ if (data.value != null or data.options != null or data.checked != null or data.aria.expanded != null or data.aria.checked != null) return .named;
const named = data.name != null and data.name.?.len > 0;
// Headings outline the page, and a record's title is often one.
if (named and std.mem.eql(u8, data.role, "heading")) return .heading;
@@ -420,6 +420,7 @@ const NodeData = struct {
value: ?[]const u8,
options: ?[]OptionData = null,
checked: ?bool = null,
+ aria: AXNode.Writer.AriaProperties = .{},
xpath: []const u8,
interactive: bool,
disabled: bool,
@@ -633,6 +634,7 @@ fn visitNode(
.value = value,
.options = options,
.checked = checked,
+ .aria = if (!invisible and node.is(Element) != null) AXNode.Writer.ariaProperties(node.is(Element).?, role) else .{},
.xpath = xpath,
.interactive = is_interactive,
.disabled = is_disabled,
@@ -764,6 +766,14 @@ const JsonVisitor = struct {
try self.jw.objectField("checked");
try self.jw.write(checked);
}
+ if (data.aria.expanded) |expanded| {
+ try self.jw.objectField("ariaExpanded");
+ try self.jw.write(expanded);
+ }
+ if (data.aria.checked) |checked| {
+ try self.jw.objectField("ariaChecked");
+ try self.jw.write(@tagName(checked));
+ }
if (data.options) |options| {
try self.jw.objectField("options");
@@ -886,6 +896,17 @@ fn writeTextLine(writer: *std.Io.Writer, node: *Node, data: *NodeData) !TextLine
}
}
+ if (data.aria.expanded) |expanded| {
+ try writer.writeAll(if (expanded) " [expanded]" else " [collapsed]");
+ }
+ if (data.aria.checked) |checked| {
+ try writer.writeAll(switch (checked) {
+ .true => " [checked]",
+ .false => " [unchecked]",
+ .mixed => " [mixed]",
+ });
+ }
+
if (data.options) |options| {
try writer.writeAll(" options=[");
for (options, 0..) |opt, i| {
@@ -900,7 +921,7 @@ fn writeTextLine(writer: *std.Io.Writer, node: *Node, data: *NodeData) !TextLine
try writer.writeAll("]");
return .{ .children = .none, .contentful = true }; // Native handling complete, do not walk children
}
- const contentful = name_to_print != null or (if (data.value) |v| v.len > 0 else false) or data.checked != null;
+ const contentful = name_to_print != null or (if (data.value) |v| v.len > 0 else false) or data.checked != null or data.aria.expanded != null or data.aria.checked != null;
// A named one already says what its children say, but a heading or
// code can still wrap a link.
@@ -1139,6 +1160,52 @@ test "SemanticTree backendDOMNodeId" {
try testing.expect(std.mem.find(u8, json_str, "\"backendDOMNodeId\":") != null);
}
+test "SemanticTree: JSON exposes custom ARIA states without changing native checked" {
+ var registry: NodeRegistry = .init(testing.allocator);
+ defer registry.deinit();
+
+ var page = try testing.pageTest("cdp/ax_aria_states.html", .{});
+ defer page.close();
+ const frame = page.frame().?;
+ const st: Self = try .init(testing.arena_allocator, frame.window._document.asNode(), &registry, frame, .{ .prune = false });
+
+ const json = try std.json.Stringify.valueAlloc(testing.allocator, st, .{});
+ defer testing.allocator.free(json);
+ const parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{});
+ defer parsed.deinit();
+
+ const find = struct {
+ fn named(node: std.json.Value, name: []const u8) ?std.json.Value {
+ if (node != .object) return null;
+ if (node.object.get("name")) |n| {
+ if (n == .string and std.mem.eql(u8, n.string, name)) return node;
+ }
+ if (node.object.get("children")) |children| {
+ for (children.array.items) |child| {
+ if (named(child, name)) |found| return found;
+ }
+ }
+ return null;
+ }
+ }.named;
+
+ const expanded = find(parsed.value, "Uppercase expanded") orelse return error.NodeNotFound;
+ try testing.expect(expanded.object.get("ariaExpanded").?.bool);
+ const collapsed = find(parsed.value, "Collapsed details") orelse return error.NodeNotFound;
+ try testing.expect(!collapsed.object.get("ariaExpanded").?.bool);
+ const generic = find(parsed.value, "Generic expanded") orelse return error.NodeNotFound;
+ try testing.expect(generic.object.get("ariaExpanded") == null);
+ const mixed = find(parsed.value, "Uppercase mixed") orelse return error.NodeNotFound;
+ try std.testing.expectEqualStrings("mixed", mixed.object.get("ariaChecked").?.string);
+ const switch_mixed = find(parsed.value, "Switch mixed") orelse return error.NodeNotFound;
+ try std.testing.expectEqualStrings("false", switch_mixed.object.get("ariaChecked").?.string);
+ const invalid = find(parsed.value, "Invalid details") orelse return error.NodeNotFound;
+ try testing.expect(invalid.object.get("ariaExpanded") == null);
+ const native = find(parsed.value, "Native terms") orelse return error.NodeNotFound;
+ try testing.expect(native.object.get("checked").?.bool);
+ try testing.expect(native.object.get("ariaChecked") == null);
+}
+
test "SemanticTree max_depth" {
var registry: NodeRegistry = .init(testing.allocator);
defer registry.deinit();
diff --git a/src/browser/tools.zig b/src/browser/tools.zig
index 937b64853..e0dc8ff9c 100644
--- a/src/browser/tools.zig
+++ b/src/browser/tools.zig
@@ -3055,6 +3055,46 @@ test "goto: a navigation stuck waiting for a connection is an error" {
try std.testing.expectEqualStrings("Navigated. HTTP 200 OK.", r.text);
}
+test "tools: tree exposes Chrome-matched custom ARIA states" {
+ var registry: NodeRegistry = .init(std.testing.allocator);
+ defer registry.deinit();
+
+ var page = try testing.pageTest("cdp/ax_aria_states.html", .{});
+ defer page.close();
+
+ const result = try call(testing.arena_allocator, page.session, &registry, "tree", null, .{ .source = .user });
+ const expected = [_][]const u8{
+ "button 'Expanded details' [expanded]",
+ "button 'Collapsed details' [collapsed]",
+ "button 'Uppercase expanded' [expanded]",
+ "checkbox 'Uppercase mixed' [mixed]",
+ "checkbox 'Absent checked' [unchecked]",
+ "switch 'Switch mixed' [unchecked]",
+ "menuitemcheckbox 'Menu checkbox mixed' [mixed]",
+ "button 'Custom anchor' [expanded]",
+ "checkbox 'Checked terms' [checked]",
+ };
+ for (expected) |fragment| {
+ if (std.mem.find(u8, result.text, fragment) == null) return error.MissingExpectedAriaState;
+ }
+
+ // Unsupported roles and invalid tokens must not manufacture state.
+ const ignored = [_][]const u8{ "'Generic expanded'", "'Invalid details'", "'Invalid state'" };
+ for (ignored) |name| {
+ var lines = std.mem.splitScalar(u8, result.text, '\n');
+ var found = false;
+ while (lines.next()) |line| {
+ if (std.mem.find(u8, line, name) == null) continue;
+ found = true;
+ if (std.mem.find(u8, line, " [expanded]") != null) return error.UnexpectedExpanded;
+ if (std.mem.find(u8, line, " [checked]") != null) return error.UnexpectedChecked;
+ if (std.mem.find(u8, line, " [unchecked]") != null) return error.UnexpectedUnchecked;
+ }
+ if (!found) return error.IgnoredNodeMissing;
+ }
+ try std.testing.expect(std.mem.find(u8, result.text, "'Hidden terms'") == null);
+}
+
test "tools: goto flags an error status instead of reporting success" {
var registry: NodeRegistry = .init(std.testing.allocator);
defer registry.deinit();
diff --git a/src/server/cdp/AXNode.zig b/src/server/cdp/AXNode.zig
index 391e0ffef..50fe5e19a 100644
--- a/src/server/cdp/AXNode.zig
+++ b/src/server/cdp/AXNode.zig
@@ -319,7 +319,7 @@ pub const Writer = struct {
value: AXValue,
};
- const AriaState = enum { true, false, mixed };
+ pub const AriaState = enum { true, false, mixed };
fn parseAriaState(value: []const u8) ?AriaState {
inline for (comptime std.meta.tags(AriaState)) |state| {
@@ -360,6 +360,33 @@ pub const Writer = struct {
return roles.get(std.ascii.lowerString(&buf, role)) orelse .{};
}
+ // Share Chrome-matched role and token rules with the MCP semantic tree.
+ // Native input checked state remains owned by the input serializer.
+ pub const AriaProperties = struct {
+ expanded: ?bool = null,
+ checked: ?AriaState = null,
+ };
+
+ pub fn ariaProperties(el: *DOMNode.Element, role: []const u8) AriaProperties {
+ const states = roleStates(role);
+ var props: AriaProperties = .{};
+ if (states.expanded and el.getTag() != .select) {
+ if (parseAriaState(el.getAttributeInterned("aria-expanded") orelse "")) |state| {
+ switch (state) {
+ .true => props.expanded = true,
+ .false => props.expanded = false,
+ .mixed => {},
+ }
+ }
+ }
+ if (states.checked != null and el.getTag() != .input) {
+ if (parseAriaState(el.getAttributeSafe(.wrap("aria-checked")) orelse "false")) |state| {
+ props.checked = if (state == .mixed and states.checked == .binary) .false else state;
+ }
+ }
+ return props;
+ }
+
fn writeAXProperties(self: *const Writer, axnode: AXNode, w: anytype) !void {
const frame = self.frame;
const dom_node = axnode.dom;
@@ -524,20 +551,13 @@ pub const Writer = struct {
else => {},
}
- // The resolved role, not the attribute, so generic nodes get no states.
- const states = roleStates(try axnode.getRole());
- if (states.expanded and el.getTag() != .select) {
- if (parseAriaState(el.getAttributeInterned("aria-expanded") orelse "")) |state| switch (state) {
- .true, .false => try self.writeAXProperty(.{ .name = .expanded, .value = .{ .booleanOrUndefined = state == .true } }, w),
- .mixed => {},
- };
+ // Resolved roles gate states. Native select/input states are handled above.
+ const aria = ariaProperties(el, try axnode.getRole());
+ if (aria.expanded) |expanded| {
+ try self.writeAXProperty(.{ .name = .expanded, .value = .{ .booleanOrUndefined = expanded } }, w);
}
- // Inputs already emitted their native checked property above.
- if (states.checked != null and el.getTag() != .input) {
- if (parseAriaState(el.getAttributeSafe(.wrap("aria-checked")) orelse "false")) |parsed| {
- const state: AriaState = if (parsed == .mixed and states.checked == .binary) .false else parsed;
- try self.writeAXProperty(.{ .name = .checked, .value = .{ .token = @tagName(state) } }, w);
- }
+ if (aria.checked) |checked| {
+ try self.writeAXProperty(.{ .name = .checked, .value = .{ .token = @tagName(checked) } }, w);
}
// Hidden and inert nodes never reach here, so tabindex alone decides.