Merge branch 'codex/overlay-runtime'

Author: Roy Lin

README.md

@@ -23,12 +23,13 @@ object graph at the host boundary.
   stable-key selection with native aggregate snapshots, independent
   `onAction(key)` item activation, select-all/clear keyboard commands,
   touch/pen long-press selection entry, collection keyboard navigation,
-  hierarchical tree expansion, inherited locale/direction, versioned capability
-  reporting, shared native event-source state machines, and accessibility
-  conformance checks.
+  hierarchical tree expansion, activation-ordered overlay dismissal, modal
+  background inertness, nested focus containment/restoration, inherited
+  locale/direction, versioned capability reporting, shared native event-source
+  state machines, and accessibility conformance checks.
   Role-edge input parity, layout-aware collection page movement, IME/dead-key
-  conformance, remaining native focus conformance, and locale formatting are
-  still in progress.
+  conformance, native overlay positioning/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

@@ -487,6 +487,42 @@ escape an active contained scope, and records the pre-mount focus owner for
 each restore-enabled scope. When nested scopes unmount, valid restoration
 targets unwind from the innermost scope outward through the same imperative
 host capability.
+
+## Mounted Overlay Runtime
+
+`MountedOverlayRegistry` is the platform-independent source of truth for open
+managed overlays. After keyed reconciliation, `GuiRuntime` synchronizes the
+registry from `data-overlay` contracts, preserves already-open overlays in
+activation order, and appends newly opened overlays. Persistent sibling nodes
+therefore stack by when they became visible rather than by source order.
+
+While any overlay is active, the runtime projects an internal capture marker
+to mounted native nodes. The shared native interaction profile translates that
+marker into pointer-lifecycle and key-down subscriptions on AppKit, GTK4, and
+WinUI. Escape is claimed only by the topmost overlay unless
+`isKeyboardDismissDisabled` is set. Outside dismissal records the topmost
+overlay on press start and closes it only when release is also outside that
+same overlay; intercepted background events do not reach application actions.
+Close-on-blur requires a known `relatedTarget` outside the overlay subtree.
+All successful dismissal paths synthesize a target-scoped native `Close`
+event, which routes to the overlay's `onClose` action without closing an
+ancestor layer.
+
+For the topmost active modal, branches outside the modal and any overlays
+opened after it are projected inert. Inert projection also removes those
+branches from portable accessibility output. Ancestors needed to retain the
+native hierarchy stay enabled, but the registry still suppresses interactions
+targeted outside the modal foreground. Later portaled overlays are treated as
+foreground and may receive focus through an earlier contained scope.
+
+Overlay focus uses the existing `FocusManager` contracts. A newly opened
+overlay with `autoFocus` focuses its first tabbable or focusable descendant;
+contained focus remains inside the active scope; and unmounting a
+restore-enabled overlay returns focus to its valid trigger. `UiDialog`,
+`UiModal`, and the default `UiPopover` opt into these behaviors. A nonmodal
+popover keeps background branches interactive and does not contain focus,
+while still supporting autofocus, restoration, close-on-blur, and Escape.
+
 Non-focus interaction state is
 revision-scoped: after a successful rerender, controlled values from the new
 blueprint supersede stale local event state while focus remains preserved until

docs/react-aria-native.md

@@ -124,6 +124,22 @@ The first shared interaction milestone is available in the portable runtime:
   descendant instead of the scope wrapper. Restore-enabled scopes retain the
   focus owner that preceded their mount and unwind nested restoration targets
   when they unmount.
+- `MountedOverlayRegistry` discovers open managed overlays from the reconciled
+  native tree and retains activation order independently of document order.
+  Only the topmost overlay handles Escape or outside-press dismissal. Escape
+  remains available to the focused control when keyboard dismissal is
+  disabled, and outside dismissal requires both press start and release to
+  occur outside the same topmost overlay.
+- Modal overlays project `inert` onto background branches, which also removes
+  them from the portable accessibility tree. Structural ancestors stay
+  available for event routing, and overlays opened later through a separate
+  portal branch remain interactive foreground layers.
+- Overlay autofocus, contained focus, and restoration reuse `FocusManager`.
+  Dismissal emits a target-scoped native `Close` event, so it invokes only the
+  topmost overlay's `onClose`. `UiDialog` and `UiModal` expose
+  `isDismissable` and `isKeyboardDismissDisabled`; `UiPopover` additionally
+  exposes `isNonModal`, closes on focus leaving its subtree, and defaults to a
+  modal dismissable popover.
 - `GuiRuntime` exposes `request_focus`, `focus_first`, `focus_last`,
   `focus_next`, and `focus_previous`. These methods validate mounted
   focusability, apply active-scope containment, and send a typed platform
@@ -274,6 +290,7 @@ existence of a platform object:
 | Focus within | Portable runtime routing on AppKit, GTK4, WinUI, and headless hosts. Native blur/focus batches are linked with `relatedTarget`; direct focus callbacks remain target-only while focus-within callbacks run only when a subtree boundary is crossed. |
 | Interaction style projection | Runtime-resolved hover, press, long-press, move, focus, focus-visible, focus-within, selected, checked, expanded, disabled, validation, read-only, direction, and matching `data-*`/`aria-*` variants use the same transactional `SetPortableStyle` path on all three planning adapters. |
 | Focus events, scopes, and `autoFocus` | Native focusable control roles listed in the capability manifest. Runtime navigation, restoration, and post-mount `autoFocus` all emit typed `requestFocus` commands; contained scopes redirect escaping native focus. AppKit uses `makeFirstResponder`, GTK4 uses `grab_focus`, and WinUI calls the fixed `IUIElement::Focus(Programmatic)` ABI through an isolated adapter because the generated binding leaves that method unwrapped. |
+| Overlay stack | Activation ordering, topmost Escape and outside-press dismissal, modal background inertness/accessibility suppression, close-on-blur, portaled child overlays, containment, autofocus, and restoration run in the shared mounted runtime. AppKit, GTK4, and WinUI planning adapters receive the same projected props and event subscriptions. |
 | Selection and item action | Select/combo box, list box/tree, and tabs/tab list. GTK4 and WinUI ListBox callbacks provide complete native selection snapshots; AppKit modifier-aware row activation and all stable-key aggregation remain in the portable keyed-runtime layer. ListBox/Tree item `onAction(key)` separation and collection keyboard navigation are shared across adapters. |
 
 `NativeCapabilities` is the executable source of truth. Global entries are
@@ -294,7 +311,7 @@ props:
 | P1 | Collections and selection | Add layout-aware page navigation and complete IME/dead-key typeahead conformance. |
 | 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 | Add dismissal, focus restoration, modal containment, outside interaction, and nested overlay ordering. |
+| P2 | Overlays | Add anchored positioning/flipping, native scroll locking, configurable outside-interaction filters, multi-window layer coordination, and real-platform conformance fixtures. |
 | P2 | Capability enforcement | Turn reported capability gaps into adapter policy and conformance gates where portable fallback is not sufficient. |
 | P2 | Environment style variants | Add native environment and ancestry evaluators for responsive/container, theme, group, peer, and structural selector variants. These remain preserved in the style IR but inactive at runtime today. |
 

docs/roadmap.md

@@ -75,6 +75,9 @@ The following foundations are implemented and are not roadmap placeholders:
 - a component playground that checks registry coverage
 - normalized portable style, Tailwind-compatible variant metadata, and
   transactional runtime projection for interaction and typed state variants
+- an activation-ordered mounted overlay stack with topmost Escape/outside
+  dismissal, modal background inertness, portaled foreground layers, and
+  shared focus containment, autofocus, and restoration
 - AppKit, GTK4, and WinUI build/test matrices with real native dogfood surfaces
 
 ## Delivery Dependency

docs/rsx.md

@@ -1633,6 +1633,36 @@ card parts are under `src/rsx_ui/components/card/`, checkbox parts are under
 - `UiCalendarMonthPicker`
 - `UiCalendarYearPicker`
 
+Open `UiDialog`, `UiModal`, and `UiPopover` nodes participate in the mounted
+overlay stack. Only the most recently opened overlay handles Escape and
+outside interaction. `UiDialog` and `UiModal` accept `isDismissable` (default
+`false`) and `isKeyboardDismissDisabled` (default `false`). Escape invokes
+`onClose` independently of `isDismissable`; set
+`isKeyboardDismissDisabled={true}` to leave Escape for the focused control.
+Outside dismissal requires `isDismissable={true}` and suppresses the
+corresponding background press lifecycle.
+
+`UiPopover` accepts `onClose`, `isNonModal`, and
+`isKeyboardDismissDisabled`. A normal popover is modal and dismissable,
+contains focus, closes when focus moves outside, and makes background branches
+inert. `isNonModal={true}` keeps the background interactive and disables
+outside-press dismissal and focus containment; close-on-blur, Escape,
+autofocus, and focus restoration remain enabled. `UiModalOverlay` is a
+structural underlay and `UiTooltip` is informational, so neither independently
+joins the managed stack. Dismissal is controlled: the `onClose` action should
+rerender the overlay with `isOpen={false}`.
+
+```rsx
+<UiModal
+  key="settings-modal"
+  isOpen={settings_open}
+  isDismissable={true}
+  onClose={close_settings}
+>
+  <UiButton key="save" onPress={save_settings}>Save</UiButton>
+</UiModal>
+```
+
 Collection selection components accept React Aria-style `selectedKeys`,
 `defaultSelectedKeys`, `selectionMode`, `selectionBehavior`, `disabledKeys`,
 `disabledBehavior`, `disallowEmptySelection`, and `shouldFocusWrap` props.

src/compiler.rs

@@ -2862,6 +2862,28 @@ fn i18n_scope_value(props: &CompiledProps) -> GuiResult<JsonValue> {
 }
 
 fn overlay_scope_value(props: &CompiledProps) -> GuiResult<JsonValue> {
+    let overlay_type = non_empty_attribute(props, &["overlayType", "data-overlay-type"]);
+    let is_non_modal =
+        bool_attribute_value(props, &["isNonModal", "data-overlay-non-modal"]).unwrap_or(false);
+    let managed_by_default = !matches!(overlay_type.as_deref(), Some("tooltip" | "underlay"));
+    let modal_by_default = match overlay_type.as_deref() {
+        Some("modal" | "dialog") => true,
+        Some("popover") => !is_non_modal,
+        _ => false,
+    };
+    let underlay_by_default = matches!(overlay_type.as_deref(), Some("modal"));
+    let dismissable_by_default =
+        matches!(overlay_type.as_deref(), Some("popover")) && !is_non_modal;
+    let close_on_blur_by_default = matches!(overlay_type.as_deref(), Some("popover"));
+    let contain_by_default = match overlay_type.as_deref() {
+        Some("modal" | "dialog") => true,
+        Some("popover") => !is_non_modal,
+        _ => false,
+    };
+    let manages_focus_by_default = matches!(
+        overlay_type.as_deref(),
+        Some("modal" | "dialog" | "popover")
+    );
     use_overlay_value(
         UseOverlayProps::new()
             .open(bool_attribute_value(props, &["isOpen", "open", "data-open"]).unwrap_or(false))
@@ -2874,7 +2896,49 @@ fn overlay_scope_value(props: &CompiledProps) -> GuiResult<JsonValue> {
             .trigger_kind(non_empty_attribute(
                 props,
                 &["overlayTriggerKind", "triggerKind", "aria-haspopup"],
-            )),
+            ))
+            .managed(
+                bool_attribute_value(props, &["isManagedOverlay", "data-overlay-managed"])
+                    .unwrap_or(managed_by_default),
+            )
+            .modal(
+                bool_attribute_value(props, &["isModal", "aria-modal", "data-overlay-modal"])
+                    .unwrap_or(modal_by_default),
+            )
+            .underlay(
+                bool_attribute_value(props, &["isUnderlay", "data-overlay-underlay"])
+                    .unwrap_or(underlay_by_default),
+            )
+            .dismissable(
+                bool_attribute_value(props, &["isDismissable", "data-overlay-dismissable"])
+                    .unwrap_or(dismissable_by_default),
+            )
+            .keyboard_dismiss_disabled(
+                bool_attribute_value(
+                    props,
+                    &[
+                        "isKeyboardDismissDisabled",
+                        "data-overlay-keyboard-dismiss-disabled",
+                    ],
+                )
+                .unwrap_or(false),
+            )
+            .close_on_blur(
+                bool_attribute_value(props, &["shouldCloseOnBlur", "data-overlay-close-on-blur"])
+                    .unwrap_or(close_on_blur_by_default),
+            )
+            .contain_focus(
+                bool_attribute_value(props, &["shouldContainFocus", "contain", "data-contain"])
+                    .unwrap_or(contain_by_default),
+            )
+            .restore_focus(
+                bool_attribute_value(props, &["restoreFocus", "data-restore-focus"])
+                    .unwrap_or(manages_focus_by_default),
+            )
+            .auto_focus(
+                bool_attribute_value(props, &["autoFocus", "data-auto-focus"])
+                    .unwrap_or(manages_focus_by_default),
+            ),
     )
 }
 

src/event/press.rs

@@ -32,6 +32,7 @@ impl NativeInteractionSubscriptions {
                 .is_some_and(|action| !action.is_empty()),
         );
         subscriptions.merge(Self::from_style(&blueprint.portable_style));
+        subscriptions.merge(Self::from_metadata(&blueprint.metadata));
         subscriptions.terminal_press |= has_collection_action(blueprint);
         subscriptions.long_press |= has_collection_action(blueprint);
         subscriptions
@@ -50,6 +51,17 @@ impl NativeInteractionSubscriptions {
         }
     }
 
+    fn from_metadata(metadata: &BTreeMap<String, String>) -> Self {
+        let captures_overlay_events = metadata
+            .get(crate::overlay::OVERLAY_CAPTURE_METADATA_KEY)
+            .is_some_and(|value| value.eq_ignore_ascii_case("true"));
+        Self {
+            press_lifecycle: captures_overlay_events,
+            key_down: captures_overlay_events,
+            ..Self::default()
+        }
+    }
+
     fn from_events(events: &BTreeMap<String, String>, has_action: bool) -> Self {
         Self {
             terminal_press: has_action || has_event(events, &["onPress", "onClick"]),
@@ -210,6 +222,7 @@ pub(crate) struct NativeInteractionProfile {
     pub(crate) subscriptions: NativeInteractionSubscriptions,
     event_subscriptions: NativeInteractionSubscriptions,
     style_subscriptions: NativeInteractionSubscriptions,
+    overlay_subscriptions: NativeInteractionSubscriptions,
     has_action: bool,
     has_terminal_event: bool,
     has_long_press_event: bool,
@@ -236,11 +249,14 @@ impl NativeInteractionProfile {
         );
         let style_subscriptions =
             NativeInteractionSubscriptions::from_style(&blueprint.portable_style);
+        let overlay_subscriptions =
+            NativeInteractionSubscriptions::from_metadata(&blueprint.metadata);
         let mut profile = Self {
             role: blueprint.role,
             subscriptions: NativeInteractionSubscriptions::default(),
             event_subscriptions,
             style_subscriptions,
+            overlay_subscriptions,
             has_action,
             has_terminal_event,
             has_long_press_event,
@@ -277,6 +293,8 @@ impl NativeInteractionProfile {
                     .get(crate::selection::COLLECTION_ACTION_METADATA_KEY)
                     .is_some_and(|value| value.eq_ignore_ascii_case("true"));
                 self.long_press_threshold = long_press_threshold(metadata);
+                self.overlay_subscriptions =
+                    NativeInteractionSubscriptions::from_metadata(metadata);
                 self.refresh_subscriptions();
             }
             NativeWidgetSetter::SetPortableStyle(style) => {
@@ -329,6 +347,7 @@ impl NativeInteractionProfile {
             self.has_long_press_event || self.has_collection_action;
         self.subscriptions = self.event_subscriptions;
         self.subscriptions.merge(self.style_subscriptions);
+        self.subscriptions.merge(self.overlay_subscriptions);
     }
 }
 
@@ -1171,6 +1190,23 @@ mod tests {
         assert!(!profile.subscriptions.terminal_press);
     }
 
+    #[test]
+    fn overlay_capture_marker_subscribes_pointer_lifecycle_and_escape_delivery() {
+        let element = NativeElement::new("overlay-capture", NativeRole::View).with_props(
+            NativeProps::new().metadata(crate::overlay::OVERLAY_CAPTURE_METADATA_KEY, "true"),
+        );
+        let blueprint = AppKitAdapter.blueprint(&element);
+        let mut profile = NativeInteractionProfile::from_blueprint(&blueprint);
+
+        assert!(profile.subscriptions.press_lifecycle);
+        assert!(profile.subscriptions.key_down);
+        assert!(!profile.subscriptions.terminal_press);
+
+        profile.apply_setter(&NativeWidgetSetter::SetMetadata(BTreeMap::new()));
+        assert!(!profile.subscriptions.press_lifecycle);
+        assert!(!profile.subscriptions.key_down);
+    }
+
     #[test]
     fn explicit_long_press_profile_honors_a_bounded_threshold() {
         let element = NativeElement::new("target", NativeRole::Button).with_props(

src/lib.rs

@@ -41,6 +41,7 @@ pub mod native;
     all(feature = "winui-native", target_os = "windows")
 ))]
 mod native_backends;
+pub mod overlay;
 pub mod platform;
 pub mod protocol;
 pub mod renderer;
@@ -137,6 +138,7 @@ pub use interaction::{
     DEFAULT_INTERACTION_CHANGE_HISTORY_LIMIT,
 };
 pub use native::{ElementKey, NativeElement, NativeProps, NativeRole, ValueSensitivity};
+pub use overlay::{MountedOverlayRegistry, NativeOverlay};
 pub use platform::{
     native_widget_kind, native_widget_name, widget_blueprint, AppKitAdapter, BlueprintHost,
     Gtk4Adapter, NativeBackendKind, NativeConfigValueChange, NativeContainerKind,