feat(a11y): Document role, and disclosure of web content the reader cannot enter (#506)

CHANGELOG.md

@@ -19,6 +19,12 @@ internal refactors, CI, or test-only changes.
 
 ## [Unreleased]
 
+### Added
+- `Document` accessibility role: a browser page or embedded web view (AT-SPI `document web`/`document frame`, `AXWebArea`, Android `WebView`) now reads as a `Document` whose children are the page's elements, on Linux, macOS, Android and iOS.
+
+### Fixed
+- A web view whose content the platform has not published is disclosed in the snapshot with its id, bounds and the pixel path, instead of arriving as an indistinguishable empty group.
+
 ## [1.5.0] - 2026-08-22
 
 ### Added

crates/glass-a11y-linux/src/mapping.rs

@@ -50,6 +50,7 @@ pub(crate) fn map_role(role: Role) -> AxRole {
         Role::ToolBar => AxRole::Toolbar,
         Role::StatusBar => AxRole::StatusBar,
         Role::Heading => AxRole::Heading,
+        Role::DocumentWeb | Role::DocumentFrame => AxRole::Document,
         _ => AxRole::Other,
     }
 }
@@ -108,6 +109,17 @@ mod tests {
         assert_eq!(map_role(Role::Calendar), AxRole::Other);
     }
 
+    #[test]
+    fn web_documents_map_to_document() {
+        // A browser's page root and an ARIA role=document region are both web documents;
+        // a text document (DocumentText) is a text area and stays one.
+        assert_eq!(map_role(Role::DocumentWeb), AxRole::Document);
+        assert_eq!(map_role(Role::DocumentFrame), AxRole::Document);
+        assert_eq!(map_role(Role::DocumentText), AxRole::TextArea);
+        // An embedded object (<embed>, <object>) is not a document.
+        assert_eq!(map_role(Role::Embedded), AxRole::Other);
+    }
+
     #[test]
     fn states_map_to_flags() {
         let s =
@@ -177,6 +189,7 @@ mod tests {
         (Role::ToolBar, AxRole::Toolbar),
         (Role::StatusBar, AxRole::StatusBar),
         (Role::Heading, AxRole::Heading),
+        (Role::DocumentWeb, AxRole::Document),
     ];
 
     #[test]

crates/glass-a11y-macos/src/mapping.rs

@@ -40,6 +40,8 @@ pub const ROLE_TOKENS: &[(&str, AxRole)] = &[
     ("AXSplitter", AxRole::Separator),
     ("AXHeading", AxRole::Heading),
     ("AXMenuButton", AxRole::Button),
+    // The root of a web engine's subtree.
+    ("AXWebArea", AxRole::Document),
 ];
 
 /// Subroles that decide a role, and the base roles that can carry one.
@@ -231,6 +233,11 @@ mod tests {
         assert_eq!(map_role("", None), AxRole::Other);
     }
 
+    #[test]
+    fn a_web_area_is_a_document() {
+        assert_eq!(map_role("AXWebArea", None), AxRole::Document);
+    }
+
     #[test]
     fn a_switch_is_a_togglebutton_whichever_base_role_carries_it() {
         // `AXToggle` is deliberately absent: AppKit documents it for on/off *buttons*, and no probe

crates/glass-a11y-windows/src/mapping.rs

@@ -329,7 +329,8 @@ mod tests {
     #[test]
     fn document_maps_from_an_observed_token() {
         // Observed on a stock text editor — see the probe test in
-        // crates/glass-windows/tests/onbox.rs.
+        // crates/glass-windows/tests/onbox.rs. What a web document reports here is unread, so
+        // the role-support matrix records the Document cell as a gap until one is read.
         assert_eq!(map_role(50030, false), AxRole::TextArea);
     }
 

crates/glass-android/src/a11y_service.rs

@@ -987,10 +987,7 @@ fn movement_candidates<'a>(tree: &'a AxTree, target: &AxTarget) -> Vec<&'a AxNod
 
 /// A rectangle as `(x,y wxh)`.
 fn rect(b: Option<AxRect>) -> String {
-    b.map_or_else(
-        || "(no bounds)".to_string(),
-        |r| format!("({},{} {}x{})", r.x, r.y, r.width, r.height),
-    )
+    b.map_or_else(|| "(no bounds)".to_string(), |r| r.to_string())
 }
 
 /// The refusal for a target more than one node now matches on everything but position, so its id

crates/glass-android/src/axmap.rs

@@ -43,7 +43,7 @@ pub const CLASS_TOKENS: &[(&str, AxRole)] = &[
     ("RecyclerView", AxRole::List),
     ("ListView", AxRole::List),
     ("GridView", AxRole::List),
-    ("WebView", AxRole::Group),
+    ("WebView", AxRole::Document),
     // Containers the leaf-suffix rule below cannot catch, each observed in a real app's
     // tree: the AndroidX card container, the AppCompat linear layout (shipped under two
     // package names), the view that hosts a Compose hierarchy, and a swipe-paged container.
@@ -629,6 +629,13 @@ mod tests {
         }
     }
 
+    #[test]
+    fn a_webview_is_a_document_not_a_group() {
+        // glass#506: as a Group, a WebView whose content the reader could not enter was
+        // indistinguishable from an empty container.
+        assert_eq!(class_to_role("android.webkit.WebView"), AxRole::Document);
+    }
+
     #[test]
     fn class_tokens_have_no_duplicates() {
         for (i, (leaf, _)) in CLASS_TOKENS.iter().enumerate() {