feat: add layout-aware collection page navigation

Author: Roy Lin

README.md

@@ -38,10 +38,10 @@ object graph at the host boundary.
   cases of each `Button`, `DisclosureSummary`, `Link`, `ImageMapArea`,
   `MenuItem`, `ListBoxItem`, and `TreeItem` role (98 of 98 WinUI cases).
   Populating the AppKit and GTK4 manifests with real platform automation,
-  role-edge input parity, layout-aware collection page movement, IME/dead-key
-  conformance, measured overlay collision/arrow conformance and scroll locking,
-  remaining native focus conformance, and locale formatting are still in
-  progress.
+  role-edge input parity, real-platform layout-aware page-navigation fixtures,
+  IME/dead-key conformance, measured overlay collision/arrow conformance and
+  scroll locking, remaining native focus conformance, and locale formatting
+  are still in progress.
 - `.rsx` component source modules with imports, local Rust types, hook
   registrations, Rust selector/reducer expressions, and a final `rsx!(...)`
   view.

docs/architecture.md

@@ -381,11 +381,18 @@ listbox items or tabs.
 Before that activation fallback, the mounted selection registry resolves
 collection navigation for ListBox, Menu, Tree, Tabs/TabList, and RadioGroup.
 Arrow keys follow the collection orientation and inherited text direction;
-Home and PageUp move to the first focusable item, while End and PageDown move to
-the last. Fully disabled items are skipped, items disabled only for selection
-remain focusable, and `shouldFocusWrap` controls end-to-start navigation except
-for Tabs and RadioGroup, which wrap by default. Focus movement is issued through
-the same constrained `RequestFocus` capability as imperative navigation.
+Home and End move to the first and last focusable item. PageUp and PageDown
+request a fresh `CollectionLayoutSnapshot` from the host and move by one
+visible width or height using stable-key item rectangles, including
+variable-size rows. AppKit reads the list document and row frames, GTK4 reads
+list allocations and ancestor scroll adjustments, and WinUI reads actual
+list/item layout. Custom or headless hosts can install the same typed snapshot
+through `GuiRuntime::set_collection_layout`; missing measurement falls back to
+the corresponding collection boundary. Fully disabled items are skipped, items
+disabled only for selection remain focusable, and `shouldFocusWrap` controls
+end-to-start navigation except for Tabs and RadioGroup, which wrap by default.
+Focus movement is issued through the same constrained `RequestFocus` capability
+as imperative navigation.
 Replace-selection ListBox and Tree collections select as focus moves, toggle
 collections move focus only, radio navigation selects, and Menu navigation is
 focus-only. Tabs select on focus unless `keyboardActivation="manual"` is set.
@@ -396,8 +403,7 @@ that clear behavior, can be released with `escapeKeyBehavior="none"`, and still
 honors `disallowEmptySelection`. These commands route through the collection
 root as complete stable-key snapshots, including normal action failure rollback.
 Explicit `onKeyDown` bindings on the target route take precedence over all
-built-in collection handling. Page movement deliberately uses collection
-boundaries until portable native layout geometry is available.
+built-in collection handling.
 Collection `onAction` is a separate semantic channel from selection. The
 mounted registry projects an internal action marker onto owned ListBoxItem and
 TreeItem rows so native adapters capture a press lifecycle without copying the

docs/react-aria-native.md

@@ -218,9 +218,14 @@ The first shared interaction milestone is available in the portable runtime:
   selection unless `escapeKeyBehavior="none"` is configured, and
   `disallowEmptySelection` still prevents the clear. Both shortcuts emit the
   same complete stable-key payload as pointer selection. An explicit
-  `onKeyDown` on the target route retains ownership of the key. Until native
-  layout geometry is available to the portable layer, PageUp and PageDown use
-  deterministic collection-boundary behavior.
+  `onKeyDown` on the target route retains ownership of the key. PageUp and
+  PageDown use a `CollectionLayoutSnapshot` containing the visible rectangle,
+  content size, and stable-key item rectangles. Command hosts measure that
+  snapshot from AppKit, GTK4, or WinUI immediately before navigation; custom
+  and headless hosts can inject it through `GuiRuntime::set_collection_layout`.
+  Variable-size rows move by one visible extent and fully disabled rows remain
+  excluded. A host that cannot measure layout retains deterministic
+  collection-boundary behavior.
 - Tree owns controlled `expandedKeys` or uncontrolled `defaultExpandedKeys`
   independently from selection. Nested semantic `TreeItem` nodes lower to
   stable, same-level native rows with parent-key, level, position, and set-size
@@ -369,7 +374,7 @@ props:
 | P0 | Native input conformance | WinUI's complete 98-case V1 manifest passes real OS automation. Populate the AppKit and GTK4 manifests with platform-run mouse, pen, touch where applicable, keyboard, assistive activation, disabled, cancellation, and keyed-rerender fixtures for every role currently marked native; then close or retain evidence-backed menu/item exceptions. |
 | P1 | Event propagation | Add platform-run conformance fixtures for conditional `Stop`/`Continue` across nested native controls. |
 | P1 | Focus management | Add platform-run conformance fixtures for post-mount `autoFocus`, nested containment, and restoration. |
-| P1 | Collections and selection | Add layout-aware page navigation and complete IME/dead-key typeahead conformance. |
+| P1 | Collections and selection | Complete IME/dead-key typeahead conformance and add real-platform fixtures for layout-aware page navigation. |
 | P1 | Internationalization | Add message formatting, number/date formatting, locale-aware collation, and localized interaction behavior on top of inherited locale/direction. |
 | P1 | Accessibility conformance | Complete OS accessibility API projection, relationships, live regions, value announcements, and role-specific native adapter coverage. |
 | P2 | Overlays | Complete measured boundary-driven collision and arrow projection, native scroll locking, configurable outside-interaction filters, multi-window layer coordination, and real-platform positioning conformance fixtures. |

src/appkit_native/mod.rs

@@ -43,7 +43,7 @@ use crate::backend::{
 };
 use crate::error::{GuiError, GuiResult};
 use crate::event::{virtual_press_events, NativeEvent, NativeEventKind};
-use crate::geometry::Orientation;
+use crate::geometry::{Orientation, Rect, Size};
 use crate::host::HostNodeId;
 use crate::html::HTML_TAG_METADATA_KEY;
 use crate::native_backends::appkit::menu::AppKitMenuRegistry;
@@ -55,6 +55,7 @@ use crate::platform::{
     NativeWidgetConfig, NativeWidgetSetter,
 };
 use crate::protocol::UiFrame;
+use crate::selection::{CollectionKey, CollectionLayoutSnapshot};
 use crate::style::{
     EdgeInsets, FontWeight, OverflowMode, PortableStyle, StyleColor, StyleLength, TextAlign,
 };

src/appkit_native/surface.rs

@@ -123,6 +123,56 @@ impl NativeWidgetSurface for AppKitNativeSurface {
         Ok(())
     }
 
+    fn measure_native_collection_layout(
+        &mut self,
+        collection: HostNodeId,
+        collection_handle: &Self::Handle,
+        items: &[(HostNodeId, CollectionKey, Self::Handle)],
+    ) -> GuiResult<Option<CollectionLayoutSnapshot>> {
+        if collection_handle.id != collection {
+            return Err(GuiError::host(format!(
+                "AppKit handle id does not match collection {}",
+                collection.get()
+            )));
+        }
+        let AppKitOsWidget::ListView(scroll_view) = &collection_handle.widget else {
+            return Ok(None);
+        };
+        let Some(state) = self.list_views.get(&collection) else {
+            return Ok(None);
+        };
+        state.stack_view.layoutSubtreeIfNeeded();
+        let visible = scroll_view.documentVisibleRect();
+        let content = state.stack_view.frame().size;
+        let rows = state.rows.borrow();
+        let mut layout = CollectionLayoutSnapshot::new(
+            Rect::new(
+                visible.origin.x,
+                visible.origin.y,
+                visible.size.width.max(0.0),
+                visible.size.height.max(0.0),
+            ),
+            Size::new(content.width.max(0.0), content.height.max(0.0)),
+        );
+        for (node, key, _) in items {
+            let Some(row) = rows.iter().find(|row| row.node == *node) else {
+                continue;
+            };
+            let frame = row.button_view().frame();
+            layout.insert_item_rect(
+                key.clone(),
+                Rect::new(
+                    frame.origin.x,
+                    frame.origin.y,
+                    frame.size.width.max(0.0),
+                    frame.size.height.max(0.0),
+                ),
+            );
+        }
+        layout.validate()?;
+        Ok(Some(layout))
+    }
+
     fn position_native_overlay(
         &mut self,
         overlay: HostNodeId,

src/backend/command_host.rs

@@ -10,6 +10,7 @@ use crate::overlay_position::OverlayPositionRequest;
 use crate::platform::{
     BlueprintHost, NativeWidgetBlueprint, PlatformAdapter, PlatformPlanningHost,
 };
+use crate::selection::{CollectionKey, CollectionLayoutSnapshot};
 use crate::style::PortableStyle;
 
 use super::traits::{
@@ -379,6 +380,15 @@ impl<A: PlatformAdapter, E: PlatformCommandExecutor> NativeHost for CommandExecu
     fn overlay_position_host(&mut self) -> Option<&mut dyn OverlayPositionHost> {
         Some(self)
     }
+
+    fn measure_collection_layout(
+        &mut self,
+        collection: HostNodeId,
+        items: &[(HostNodeId, CollectionKey)],
+    ) -> GuiResult<Option<CollectionLayoutSnapshot>> {
+        self.ensure_healthy()?;
+        self.executor.measure_collection_layout(collection, items)
+    }
 }
 
 impl<A: PlatformAdapter, E: PlatformCommandExecutor> ProgrammaticFocusHost

src/backend/driver.rs

@@ -6,6 +6,7 @@ use crate::event::NativeEvent;
 use crate::host::HostNodeId;
 use crate::overlay_position::OverlayPositionRequest;
 use crate::platform::{NativeBackendKind, NativeWidgetBlueprint, NativeWidgetConfig};
+use crate::selection::{CollectionKey, CollectionLayoutSnapshot};
 
 use super::traits::{NativeEventSource, NativeHandleAdapter, NativeWidgetDriver};
 
@@ -337,4 +338,18 @@ impl<A: NativeHandleAdapter> NativeWidgetDriver for HandleWidgetDriver<A> {
             request,
         )
     }
+
+    fn measure_collection_layout(
+        &mut self,
+        collection: HostNodeId,
+        items: &[(HostNodeId, CollectionKey)],
+    ) -> GuiResult<Option<CollectionLayoutSnapshot>> {
+        let collection_handle = self.cloned_handle(collection)?;
+        let items = items
+            .iter()
+            .map(|(id, key)| Ok((*id, key.clone(), self.cloned_handle(*id)?)))
+            .collect::<GuiResult<Vec<_>>>()?;
+        self.adapter
+            .measure_collection_layout_handles(collection, &collection_handle, &items)
+    }
 }

src/backend/executor.rs

@@ -1,6 +1,8 @@
 use crate::error::{GuiError, GuiResult};
 use crate::event::NativeEvent;
+use crate::host::HostNodeId;
 use crate::platform::{NativeWidgetBlueprint, PlatformCommand};
+use crate::selection::{CollectionKey, CollectionLayoutSnapshot};
 
 use super::traits::{
     NativeEventSource, NativeWidgetDriver, PlatformCommandBatch, PlatformCommandExecutor,
@@ -81,6 +83,14 @@ impl<D: NativeWidgetDriver + Default> Default for DriverCommandExecutor<D> {
 }
 
 impl<D: NativeWidgetDriver> PlatformCommandExecutor for DriverCommandExecutor<D> {
+    fn measure_collection_layout(
+        &mut self,
+        collection: HostNodeId,
+        items: &[(HostNodeId, CollectionKey)],
+    ) -> GuiResult<Option<CollectionLayoutSnapshot>> {
+        self.driver.measure_collection_layout(collection, items)
+    }
+
     fn prepare_batch(&mut self, batch: &PlatformCommandBatch) -> GuiResult<()> {
         for command in &batch.commands {
             match command {

src/backend/surface.rs

@@ -5,6 +5,7 @@ use crate::overlay_position::OverlayPositionRequest;
 use crate::platform::{
     NativeBackendKind, NativeWidgetBlueprint, NativeWidgetConfigPatch, NativeWidgetSetter,
 };
+use crate::selection::{CollectionKey, CollectionLayoutSnapshot};
 
 use super::traits::{NativeHandleAdapter, NativeWidgetSurface};
 
@@ -129,6 +130,16 @@ impl<S: NativeWidgetSurface> NativeHandleAdapter for SurfaceHandleAdapter<S> {
         )
     }
 
+    fn measure_collection_layout_handles(
+        &mut self,
+        collection: HostNodeId,
+        collection_handle: &Self::Handle,
+        items: &[(HostNodeId, CollectionKey, Self::Handle)],
+    ) -> GuiResult<Option<CollectionLayoutSnapshot>> {
+        self.surface
+            .measure_native_collection_layout(collection, collection_handle, items)
+    }
+
     fn take_native_events(&mut self) -> Vec<NativeEvent> {
         self.surface.take_native_events()
     }

src/backend/tests.rs

@@ -3,13 +3,15 @@ use crate::accessibility::AccessibilityRole;
 use crate::compiler::CompiledRsxNode;
 use crate::error::{GuiError, GuiResult};
 use crate::event::{NativeEvent, NativeEventKind};
+use crate::geometry::{Rect, Size};
 use crate::host::HostNodeId;
 use crate::native::{NativeElement, NativeProps, NativeRole};
 use crate::platform::{
     Gtk4Adapter, NativeBackendKind, NativeWidgetBlueprint, NativeWidgetConfigPatch,
     NativeWidgetSetter, PlatformAdapter, PlatformCommand, WinUiAdapter,
 };
 use crate::runtime::GuiRuntime;
+use crate::selection::{CollectionKey, CollectionLayoutSnapshot};
 use std::cell::RefCell;
 use std::rc::Rc;
 
@@ -173,6 +175,31 @@ impl NativeWidgetSurface for TestNativeSurface {
         Ok(())
     }
 
+    fn measure_native_collection_layout(
+        &mut self,
+        collection: HostNodeId,
+        collection_handle: &Self::Handle,
+        items: &[(HostNodeId, CollectionKey, Self::Handle)],
+    ) -> GuiResult<Option<CollectionLayoutSnapshot>> {
+        self.calls.borrow_mut().push(format!(
+            "layout:{}:{}:{}",
+            collection.get(),
+            collection_handle.widget_class,
+            items.len()
+        ));
+        let mut layout = CollectionLayoutSnapshot::new(
+            Rect::new(0.0, 0.0, 200.0, 100.0),
+            Size::new(200.0, items.len() as f64 * 40.0),
+        );
+        for (index, (_, key, _)) in items.iter().enumerate() {
+            layout.insert_item_rect(
+                key.clone(),
+                Rect::new(0.0, index as f64 * 40.0, 200.0, 40.0),
+            );
+        }
+        Ok(Some(layout))
+    }
+
     fn take_native_events(&mut self) -> Vec<NativeEvent> {
         std::mem::take(&mut self.events.borrow_mut())
     }
@@ -1121,6 +1148,45 @@ fn surface_handle_adapter_drains_native_surface_events() {
     assert!(driver.take_native_events().is_empty());
 }
 
+#[test]
+fn page_navigation_measures_layout_through_the_native_backend_stack() {
+    let surface = TestNativeSurface::default();
+    let calls = surface.calls.clone();
+    let executor =
+        DriverCommandExecutor::new(HandleWidgetDriver::new(SurfaceHandleAdapter::new(surface)));
+    let host = CommandExecutingHost::new(Gtk4Adapter, executor);
+    let mut runtime = GuiRuntime::new(host);
+    let list = NativeElement::new("list", NativeRole::ListBox)
+        .with_props(
+            NativeProps::new()
+                .web(crate::web::WebProps::new().attribute("data-selection-mode", "none")),
+        )
+        .child(NativeElement::new("a", NativeRole::ListBoxItem))
+        .child(NativeElement::new("b", NativeRole::ListBoxItem))
+        .child(NativeElement::new("c", NativeRole::ListBoxItem))
+        .child(NativeElement::new("d", NativeRole::ListBoxItem));
+    let root = runtime.render_native(&list).unwrap();
+    let items = runtime
+        .host()
+        .planning()
+        .node(root)
+        .unwrap()
+        .children
+        .clone();
+
+    runtime
+        .handle_native_event_with_changes(
+            NativeEvent::new(items[0], NativeEventKind::KeyDown).value("PageDown"),
+        )
+        .unwrap();
+
+    assert_eq!(runtime.host().planning().focused(), Some(items[2]));
+    assert!(calls
+        .borrow()
+        .iter()
+        .any(|call| call == &format!("layout:{}:gtk::ListBox:4", root.get())));
+}
+
 #[test]
 fn recording_backend_reparents_children_and_rejects_cycles() {
     let mut backend = RecordingBackend::default();