@tryinget/pi-activity-strip 0.9.0 → 0.10.0

package/native/panel/src/app.rs

@@ -2,6 +2,12 @@ use crate::card_view::CardView;
 use crate::directory_view::{
     DirectoryView, JumpChoice, is_query_char, jump_choice, push_query_char,
 };
+use crate::hints;
+use crate::hover_keyboard::{HoverKeyboard, monotonic_ms};
+use crate::interaction::{
+    HideAnchor, InteractionLifetime, PointerAnchor, accepts_pointer, is_stationary_reentry,
+    surface_state,
+};
 use crate::protocol::{Card, ViewMessage, WindowEntry, demo_view, emit, emit_error, emit_ready};
 use crate::runtime::{apply_theme, duplicate_labels, install_css, now_ms, start_input_reader};
 use gtk4_layer_shell::{Edge, KeyboardMode, Layer, LayerShell};
@@ -12,7 +18,7 @@ use relm4::gtk::prelude::*;
 use relm4::{Component, ComponentParts, ComponentSender};
 use serde_json::json;
 use std::cell::Cell;
-use std::collections::{HashMap, HashSet};
+use std::collections::HashMap;
 use std::rc::Rc;
 use std::time::Duration;
 
@@ -20,16 +26,8 @@ const COMPACT_HEIGHT: i32 = 84;
 /// The ribbon sits on the same rhythm as tiled windows, so it reads as one of them rather than as
 /// a bar bolted to the top edge. Matches `gaps` in the compositor's layout.
 const OUTER_MARGIN: i32 = 8;
-const EXPANDED_HEIGHT: i32 = 276;
 const ORDER_REFRESH_MS: i64 = 15_000;
 const BRAND_WIDTH: i32 = 196;
-/// Grace before a hovered-away window list closes, so crossing the brand's own padding does not
-/// close and reopen it.
-const DIRECTORY_CLOSE_MS: u64 = 200;
-/// Hovering the ribbon takes the keyboard so a window number can be typed at once. Without a digit
-/// within this time it is handed back, so a pointer resting on the ribbon cannot keep swallowing
-/// what is typed into the window below; a click on the ribbon still takes it again.
-const HOVER_GRAB_MS: u64 = 3_000;
 
 pub struct AppInit {
     pub demo: bool,
@@ -41,9 +39,21 @@ pub struct App {
     data: HashMap<String, Card>,
     order: Vec<String>,
     focused_card_id: Option<String>,
-    hovered: HashSet<String>,
+    /// The card under the pointer. One at most: a pointer is in one place, and the card it
+    /// entered last is the one it is on, whatever order GTK delivers the old card's leave in.
+    hovered: Option<String>,
+    /// The compositor shortcut that enters keyboard mode, for the progressive hints.
+    hotkey: Option<String>,
+    /// Niri focus moved while the operator's hand was on the ribbon; follow it once they leave.
+    scroll_deferred: bool,
     keyboard_focused: Option<String>,
+    /// Explicit/manual keyboard mode; hover must NOT inherit its arrow or unlisted-window powers.
     keyboard_active: bool,
+    hover_keyboard: HoverKeyboard,
+    /// Set when the panel hides with the pointer inside; consumed by the next body entry.
+    pointer_anchor: Option<HideAnchor>,
+    hover_capture: Rc<Cell<bool>>,
+    interaction_epoch: u64,
     open_card_id: Option<String>,
     revision: u64,
     visible: bool,
@@ -60,29 +70,18 @@ pub struct App {
     /// Counts brand hover changes, so a leave only collapses if the pointer did not come back
     /// (or land on a card) within the collapse grace.
     brand_generation: u64,
-    directory_generation: u64,
-    /// Opened by hovering the brand, so leaving it closes the list; a list opened by a typed
-    /// digit in keyboard mode stays open until it jumps or is dismissed.
-    directory_opened_by_hover: bool,
     /// Counts list openings, so a jump or activation result only acts on the list that asked.
     directory_session: u64,
     pending_request: Option<PendingRequest>,
-    /// The list changed the keyboard mode and must set it back when it closes.
-    directory_owns_keyboard: bool,
-    /// The keyboard was taken on hover and is still held. Released when the pointer leaves, and
-    /// after HOVER_GRAB_MS without a key while nothing is typed.
-    hover_grab: bool,
-    /// Counts grab timers, so only the latest one (re-armed on every key) can release the grab.
-    grab_generation: u64,
-    /// Whether the ribbon has keyboard focus right now: after a click on the list, or in
-    /// keyboard mode. Hovering alone never takes the keyboard from the window being typed into.
+    lifetime: InteractionLifetime,
+    pointer: gtk::EventControllerMotion,
+    brand_pointer: gtk::EventControllerMotion,
+    keyboard_request: u64,
+    /// GTK activity alone is never permission to expand or capture keys.
     window_active: bool,
     query: String,
     /// Read by the window's key controller: which keys belong to the window list right now.
     key_capture: Rc<Cell<KeyCapture>>,
-    /// Read by the key controller: the keyboard is held only because of hover, so any key that is
-    /// not part of a search means the typing was meant for the window below.
-    hover_guard: Rc<Cell<bool>>,
 }
 
 /// Keys the window list takes before any card sees them.
@@ -119,8 +118,6 @@ pub enum DirectoryKey {
     Backspace,
     Enter,
     Escape,
-    /// A key that cannot be part of a search, pressed while only hover holds the keyboard.
-    Interrupt,
 }
 
 #[derive(Debug)]
@@ -133,7 +130,11 @@ pub enum AppMsg {
     Navigate(String, i32, bool),
     Activate(String),
     ActivationResult(String, bool, String),
-    FocusStrip,
+    FocusStrip(u64, u64),
+    HoverGrant(u64, u64, u64),
+    HoverDenied(u64),
+    HoverInterrupt,
+    PointerIntent,
     Collapse,
     CollapseIf(u64),
     WindowActive(bool),
@@ -142,8 +143,6 @@ pub enum AppMsg {
     DirectoryHover(bool),
     BrandHover(bool),
     BrandSettle(u64),
-    DirectoryCloseIf(u64),
-    DirectoryGrabExpired(u64),
     DirectoryKey(DirectoryKey),
     DirectoryActivate(String),
     JumpResult(i64, bool, String),
@@ -251,7 +250,7 @@ impl Component for App {
         root.set_margin(Edge::Top, OUTER_MARGIN);
         root.set_margin(Edge::Left, OUTER_MARGIN);
         root.set_margin(Edge::Right, OUTER_MARGIN);
-        root.set_exclusive_zone(COMPACT_HEIGHT);
+        root.set_exclusive_zone(-1);
         root.set_keyboard_mode(KeyboardMode::None);
         if init.click_through {
             root.connect_realize(|window| {
@@ -268,15 +267,23 @@ impl Component for App {
 
         let directory = DirectoryView::new(sender.input_sender());
         let key_capture = Rc::new(Cell::new(KeyCapture::None));
-        let hover_guard = Rc::new(Cell::new(false));
+        let hover_capture = Rc::new(Cell::new(false));
+        let hover = gtk::EventControllerMotion::new();
+        let brand_hover = gtk::EventControllerMotion::new();
         let model = App {
             cards: HashMap::new(),
             data: HashMap::new(),
             order: Vec::new(),
             focused_card_id: None,
-            hovered: HashSet::new(),
+            hovered: None,
+            hotkey: None,
+            scroll_deferred: false,
             keyboard_focused: None,
             keyboard_active: false,
+            hover_keyboard: HoverKeyboard::default(),
+            pointer_anchor: None,
+            hover_capture: Rc::clone(&hover_capture),
+            interaction_epoch: 0,
             open_card_id: None,
             revision: 0,
             visible: false,
@@ -289,24 +296,32 @@ impl Component for App {
             directory_hovered: false,
             brand_hovered: false,
             brand_generation: 0,
-            directory_generation: 0,
-            directory_opened_by_hover: false,
             directory_session: 0,
             pending_request: None,
-            directory_owns_keyboard: false,
-            hover_grab: false,
-            grab_generation: 0,
+            lifetime: InteractionLifetime::default(),
+            pointer: hover.clone(),
+            brand_pointer: brand_hover.clone(),
+            keyboard_request: 0,
             window_active: false,
             query: String::new(),
             key_capture: Rc::clone(&key_capture),
-            hover_guard: Rc::clone(&hover_guard),
         };
         let widgets = view_output!();
         widgets.body.set_can_target(!init.click_through);
+        // GTK's viewport scrolls whatever takes focus into view. Focus on this panel only routes
+        // keys, so a hover grab must never move the row under a stationary pointer; the row
+        // scrolls only where the code below asks it to.
+        if let Some(viewport) = widgets.scroller.child().and_downcast::<gtk::Viewport>() {
+            viewport.set_scroll_to_focus(false);
+        }
+        // A key-routing focus target that is not a card, for a hover grab with no card under the
+        // pointer: focusing a card there would draw its focus ring on a card nobody pointed at.
+        widgets.body.set_focusable(true);
+        widgets.body.set_focus_on_click(false);
         widgets.brand.append(&model.directory.root);
 
-        // Hovering anywhere on the ribbon opens the window list in the brand column.
-        let hover = gtk::EventControllerMotion::new();
+        // The body is ONE region (including brand, cards and directory). Entry requests controller
+        // permission; child crossings do not drop/regrab ownership.
         let tx = sender.input_sender().clone();
         hover.connect_enter(move |_, _, _| {
             let _ = tx.send(AppMsg::DirectoryHover(true));
@@ -316,8 +331,14 @@ impl Component for App {
             let _ = tx.send(AppMsg::DirectoryHover(false));
         });
         widgets.body.add_controller(hover);
+        let click = gtk::GestureClick::new();
+        click.set_propagation_phase(gtk::PropagationPhase::Capture);
+        let tx = sender.input_sender().clone();
+        click.connect_pressed(move |_, _, _, _| {
+            let _ = tx.send(AppMsg::PointerIntent);
+        });
+        widgets.body.add_controller(click);
 
-        let brand_hover = gtk::EventControllerMotion::new();
         let tx = sender.input_sender().clone();
         brand_hover.connect_enter(move |_, _, _| {
             let _ = tx.send(AppMsg::BrandHover(true));
@@ -337,8 +358,15 @@ impl Component for App {
             let chord = is_chord(modifiers);
             let message = match directory_key(key_capture.get(), key, chord) {
                 Some(message) => message,
-                None if hover_guard.get() && !is_modifier_key(key) => DirectoryKey::Interrupt,
-                None => return glib::Propagation::Proceed,
+                None => {
+                    if hover_capture.get() && !is_typing_modifier(key) {
+                        // Interrupting keys release hover; they are NOT replayed or injected into
+                        // the underlying application. Subsequent typing belongs to that app.
+                        let _ = tx.send(AppMsg::HoverInterrupt);
+                        return glib::Propagation::Stop;
+                    }
+                    return glib::Propagation::Proceed;
+                }
             };
             let _ = tx.send(AppMsg::DirectoryKey(message));
             glib::Propagation::Stop
@@ -346,10 +374,12 @@ impl Component for App {
         widgets.root.add_controller(keys);
 
         let tick_tx = sender.input_sender().clone();
-        glib::timeout_add_seconds_local(1, move || {
+        let _tick_source = glib::timeout_add_seconds_local(1, move || {
             let _ = tick_tx.send(AppMsg::Tick);
             glib::ControlFlow::Continue
         });
+        #[cfg(test)]
+        gui_tests::configure_tick_source(_tick_source);
 
         if init.demo {
             let _ = sender.input_sender().send(AppMsg::View(demo_view()));
@@ -367,18 +397,54 @@ impl Component for App {
         sender: ComponentSender<Self>,
         root: &Self::Root,
     ) {
+        #[cfg(test)]
+        let _dispatch_observation = gui_tests::observe_dispatch(&message, self, root);
+        if !self.visible || !self.interactive {
+            match &message {
+                AppMsg::Hover(..)
+                | AppMsg::Focus(..)
+                | AppMsg::Navigate(..)
+                | AppMsg::Activate(..)
+                | AppMsg::DirectoryHover(..)
+                | AppMsg::BrandHover(..)
+                | AppMsg::BrandSettle(..)
+                | AppMsg::CollapseIf(..)
+                | AppMsg::DirectoryKey(..)
+                | AppMsg::DirectoryActivate(..) => return,
+                _ => {}
+            }
+        }
         match message {
             AppMsg::View(view) => self.apply_view(widgets, root, &sender, view),
             AppMsg::Theme(definitions) => apply_theme(&definitions),
             AppMsg::Tick => {
-                if now_ms() >= self.next_order_refresh_at {
+                // Mapping a surface beneath a stationary pointer is not a fresh keyboard intent.
+                // Observe an actual mapped absence before rearming after release/hide.
+                if root.is_mapped() && !self.pointer.contains_pointer() {
+                    self.hover_keyboard.inside = false;
+                    self.pointer_anchor = self
+                        .pointer_anchor
+                        .and_then(HideAnchor::after_mapped_absence);
+                }
+                if self.hover_keyboard.expired(monotonic_ms()) {
+                    // Idle typing time ends the keyboard grab, not the hover: the card under a
+                    // stationary pointer stays open.
+                    self.observe_keyboard("idle-expired");
+                    self.release_keyboard(widgets, root);
+                }
+                // Regrouping moves cards. Never under the pointer or the keyboard selection; the
+                // next tick after the operator leaves catches up.
+                if now_ms() >= self.next_order_refresh_at
+                    && !self.pointer.contains_pointer()
+                    && !self.owns_keyboard()
+                {
                     let focused_at = self.focused_position();
                     self.regroup();
                     self.reorder_widgets(&widgets.cards_box);
                     // Only when regrouping moved the focused card: a row the operator scrolled
                     // by hand stays where they left it.
                     if self.focused_position() != focused_at {
-                        self.scroll_focused_into_view(widgets);
+                        self.follow_focus(widgets);
                     }
                     self.next_order_refresh_at = now_ms() + ORDER_REFRESH_MS;
                 }
@@ -387,14 +453,27 @@ impl Component for App {
             }
             AppMsg::Hover(id, entered) => {
                 if entered {
-                    self.hovered.insert(id);
-                } else {
-                    self.hovered.remove(&id);
+                    if !self.cards.get(&id).is_some_and(|card| {
+                        accepts_pointer(
+                            self.visible,
+                            self.interactive,
+                            card.root.is_mapped(),
+                            card.motion.contains_pointer(),
+                        )
+                    }) {
+                        return;
+                    }
+                    self.hovered = Some(id);
+                } else if self.hovered.as_deref() == Some(id.as_str()) {
+                    self.hovered = None;
                 }
                 self.reconcile_engagement(widgets, root, &sender);
             }
             AppMsg::Focus(id, entered) => {
                 if entered && self.keyboard_active {
+                    // Keyboard selection is the one thing that may move the row: it is where the
+                    // operator is looking. Pointer focus never scrolls (see init).
+                    self.scroll_card_into_view(widgets, &id);
                     self.keyboard_focused = Some(id);
                 } else if !entered && self.keyboard_focused.as_deref() == Some(id.as_str()) {
                     self.keyboard_focused = None;
@@ -407,14 +486,9 @@ impl Component for App {
                 }
             }
             AppMsg::Activate(id) => {
-                emit(json!({ "protocol": 1, "type": "activate", "cardId": id }));
-                // Focus is moving to that card's window, so the ribbon must hold nothing: not
-                // keyboard mode, and not the hover grab that clicking inside the ribbon implies.
-                if self.keyboard_active {
-                    self.leave_keyboard_mode(widgets, root);
-                } else {
-                    self.close_directory(widgets, root);
-                }
+                emit(json!({ "protocol": 2, "type": "activate", "cardId": id }));
+                // Activation returns the keyboard to the exact target, never to a hover grab.
+                self.leave_keyboard_mode(widgets, root);
             }
             AppMsg::ActivationResult(id, ok, message) => {
                 if let Some(card) = self.cards.get(&id) {
@@ -428,19 +502,18 @@ impl Component for App {
                     }
                 }
             }
-            AppMsg::FocusStrip => {
-                if self.visible && self.interactive {
+            AppMsg::FocusStrip(request, epoch) => {
+                if epoch == self.interaction_epoch && self.visible && self.interactive {
+                    // A shortcut upgrades hover first; only a second explicit shortcut exits.
+                    self.cancel_pending_hover();
+                    self.hover_keyboard.clear();
+                    self.keyboard_request = request;
                     if self.keyboard_active {
                         self.leave_keyboard_mode(widgets, root);
                     } else {
                         self.keyboard_active = true;
-                        // Keyboard mode now holds the keyboard, whoever opened the list, and no
-                        // hover timeout may hand it back.
-                        self.directory_owns_keyboard = false;
-                        self.hover_grab = false;
                         self.sync_key_capture();
-                        self.hovered.clear();
-                        self.keyboard_focused = self.order.first().cloned();
+                        self.keyboard_focused = self.keyboard_entry_card(widgets);
                         root.set_keyboard_mode(KeyboardMode::Exclusive);
                         root.present();
                         let focus_grabbed = self
@@ -450,37 +523,129 @@ impl Component for App {
                             .is_some_and(|first| first.root.grab_focus());
                         if focus_grabbed {
                             self.reconcile_engagement(widgets, root, &sender);
+                            self.update_brand(widgets);
+                            self.observe_keyboard("acquired");
                             emit(
-                                json!({ "protocol": 1, "type": "keyboard-active", "active": true }),
+                                json!({ "protocol": 2, "type": "keyboard-active", "active": true, "revision": self.keyboard_request }),
                             );
                         } else {
                             self.leave_keyboard_mode(widgets, root);
                         }
                     }
+                } else {
+                    emit(
+                        json!({ "protocol": 2, "type": "keyboard-active", "active": false, "revision": request }),
+                    );
                 }
             }
+            AppMsg::HoverGrant(token, epoch, request) => {
+                let pointer_valid = accepts_pointer(
+                    self.visible,
+                    self.interactive,
+                    root.is_mapped(),
+                    self.pointer.contains_pointer(),
+                );
+                if !self.keyboard_active
+                    && self.hover_keyboard.grant(
+                        token,
+                        epoch,
+                        self.interaction_epoch,
+                        pointer_valid,
+                        monotonic_ms(),
+                    )
+                {
+                    self.keyboard_request = request;
+                    self.sync_key_capture();
+                    root.set_keyboard_mode(KeyboardMode::Exclusive);
+                    root.present();
+                    // GTK still needs a focus widget to route real key events through the root
+                    // capture controller. This is NOT explicit/manual card-selection permission.
+                    // The card under the pointer if there is one (so Enter opens it), else the
+                    // body: never a card the pointer is not on. Neither scrolls the row.
+                    let focus_grabbed =
+                        match self.hovered.as_ref().and_then(|id| self.cards.get(id)) {
+                            Some(card) => card.root.grab_focus(),
+                            None => widgets.body.grab_focus(),
+                        };
+                    if focus_grabbed {
+                        self.refresh_directory_status();
+                        self.update_brand(widgets);
+                        // Capability confirmation comes from the applied compositor focus, not
+                        // grab_focus() (which merely selects a GTK widget before Wayland commits).
+                        if root.is_active() {
+                            self.acknowledge_hover_keyboard();
+                        }
+                    } else {
+                        self.leave_keyboard_mode(widgets, root);
+                    }
+                } else {
+                    emit(json!({ "protocol": 2, "type": "hover-cancel", "token": token }));
+                }
+            }
+            AppMsg::HoverDenied(token) => {
+                if self
+                    .hover_keyboard
+                    .pending
+                    .is_some_and(|(pending, _)| pending == token)
+                {
+                    self.hover_keyboard.clear();
+                }
+            }
+            AppMsg::HoverInterrupt => {
+                if self.hover_keyboard.active {
+                    // The key belongs to the app below; the pointer is still where it was.
+                    self.release_keyboard(widgets, root);
+                }
+            }
+            AppMsg::PointerIntent => self.request_hover_keyboard(root),
             AppMsg::Collapse => {
                 self.leave_keyboard_mode(widgets, root);
             }
             AppMsg::WindowActive(active) => {
+                if active != root.is_active() {
+                    return;
+                }
                 self.window_active = active;
                 if active {
-                    // Only the hint changes. Rebuilding the rows here would replace the very row
-                    // whose click just handed over the keyboard, and swallow that click.
-                    self.refresh_directory_status();
-                } else if self.keyboard_active {
-                    // Keyboard mode lost the keyboard to another window: leave it entirely.
-                    self.leave_keyboard_mode(widgets, root);
-                } else if !self.directory_hovered {
-                    // A click elsewhere dismisses a clicked-into list. Hover expansion of cards is
-                    // pointer business and is left alone.
-                    self.close_directory(widgets, root);
-                } else {
-                    // Still hovered but no longer typing (the hover grab ran out): say so.
+                    if self.keyboard_active {
+                        self.observe_keyboard("acquired");
+                    }
+                    if self.hover_keyboard.active {
+                        if accepts_pointer(
+                            self.visible,
+                            self.interactive,
+                            root.is_mapped(),
+                            self.pointer.contains_pointer(),
+                        ) {
+                            self.acknowledge_hover_keyboard();
+                        } else {
+                            self.leave_keyboard_mode(widgets, root);
+                        }
+                    }
                     self.refresh_directory_status();
+                } else if !self.hover_keyboard.active || self.hover_keyboard.captured {
+                    // Explicit mode ends with the keyboard; a hover grab only gives it back.
+                    if self.keyboard_active {
+                        self.leave_keyboard_mode(widgets, root);
+                    } else {
+                        self.release_keyboard(widgets, root);
+                    }
+                    emit(
+                        json!({ "protocol": 2, "type": "keyboard-active", "active": false, "revision": self.keyboard_request }),
+                    );
                 }
             }
             AppMsg::BrandHover(entered) => {
+                if entered
+                    && !accepts_pointer(
+                        self.visible,
+                        self.interactive,
+                        root.is_mapped(),
+                        self.brand_pointer.contains_pointer(),
+                    )
+                {
+                    return;
+                }
                 self.brand_hovered = entered;
                 self.brand_generation += 1;
                 // Every card opens (entered) or falls back to the hovered one (left) at once.
@@ -507,7 +672,7 @@ impl Component for App {
             }
             AppMsg::CollapseIf(generation) => {
                 if generation == self.collapse_generation
-                    && self.hovered.is_empty()
+                    && self.hovered.is_none()
                     && !self.brand_hovered
                     && (!self.keyboard_active || self.keyboard_focused.is_none())
                 {
@@ -516,47 +681,43 @@ impl Component for App {
             }
             AppMsg::InputError(message) => emit_error(message),
             AppMsg::DirectoryHover(entered) => {
+                let contains = self.pointer.contains_pointer();
+                if entered
+                    && !accepts_pointer(self.visible, self.interactive, root.is_mapped(), contains)
+                {
+                    return;
+                }
+                if !entered && contains {
+                    return;
+                } // Not a real region leave.
                 self.directory_hovered = entered;
-                self.directory_generation += 1;
                 if entered {
-                    self.open_directory(widgets, root, true);
-                    // Also on re-entry within the close grace: the grab and its timer start over.
-                    if self.take_hover_grab(root) {
-                        self.arm_grab_timer(&sender);
+                    let fresh_entry = !self.hover_keyboard.inside;
+                    // The compositor re-entering the pointer that sat here at hide is not intent,
+                    // even after a mapped Tick cleared `inside`.
+                    let stationary = is_stationary_reentry(
+                        self.pointer_anchor.take().map(|anchor| anchor.at),
+                        pointer_surface_position(root),
+                    );
+                    self.hover_keyboard.inside = true;
+                    self.open_directory(widgets, root);
+                    if fresh_entry && !stationary {
+                        self.request_hover_keyboard(root);
                     }
                 } else {
-                    // Hovering is the only reason the ribbon holds the keyboard: leaving returns it.
-                    self.release_hover_grab(root);
-                    let generation = self.directory_generation;
-                    let tx = sender.input_sender().clone();
-                    glib::timeout_add_local_once(
-                        Duration::from_millis(DIRECTORY_CLOSE_MS),
-                        move || {
-                            let _ = tx.send(AppMsg::DirectoryCloseIf(generation));
-                        },
-                    );
-                }
-            }
-            AppMsg::DirectoryGrabExpired(generation) => {
-                if generation == self.grab_generation && self.query.is_empty() {
-                    self.release_hover_grab(root);
-                }
-            }
-            AppMsg::DirectoryCloseIf(generation) => {
-                if generation == self.directory_generation
-                    && !self.directory_hovered
-                    && self.directory_opened_by_hover
-                {
-                    self.close_directory(widgets, root);
+                    self.pointer_anchor = None;
+                    self.hover_keyboard.inside = false;
+                    if !self.keyboard_active {
+                        self.leave_keyboard_mode(widgets, root);
+                    }
                 }
             }
             AppMsg::DirectoryKey(key) => {
-                // Every key keeps a hover grab alive for another HOVER_GRAB_MS; the grab is only
-                // released idle and empty, never mid-number.
-                if self.hover_grab {
-                    self.arm_grab_timer(&sender);
+                if self.owns_keyboard() {
+                    self.hover_keyboard.touch(monotonic_ms());
+                    self.observe_keyboard("activity");
+                    self.handle_directory_key(widgets, root, key);
                 }
-                self.handle_directory_key(widgets, root, key);
             }
             AppMsg::DirectoryActivate(card_id) => {
                 self.pending_request = Some(PendingRequest {
@@ -564,7 +725,8 @@ impl Component for App {
                     target: RequestTarget::Card(card_id.clone()),
                 });
                 self.directory.set_status("Opening…");
-                emit(json!({ "protocol": 1, "type": "activate", "cardId": card_id }));
+                emit(json!({ "protocol": 2, "type": "activate", "cardId": card_id }));
+                self.leave_keyboard_mode(widgets, root);
             }
             AppMsg::JumpResult(window_id, ok, message) => {
                 if self.take_own_request(&RequestTarget::Window(window_id)) {
@@ -598,6 +760,19 @@ fn answers_request(pending: Option<&PendingRequest>, session: u64, target: &Requ
     pending.is_some_and(|request| request.session == session && &request.target == target)
 }
 
+/// GDK's own surface-local pointer position, while this surface has pointer focus.
+fn pointer_surface_position(root: &gtk::Window) -> Option<(f64, f64)> {
+    let pointer = WidgetExt::display(root).default_seat()?.pointer()?;
+    let (x, y, _) = root.surface()?.device_position(&pointer)?;
+    Some((x, y))
+}
+
+/// A physical Shift press prepares a capital query character; it is not an interrupt or an idle
+/// extension by itself. Ctrl/Alt/Super remain interrupting shortcut intent in hover mode.
+fn is_typing_modifier(key: gdk::Key) -> bool {
+    matches!(key, gdk::Key::Shift_L | gdk::Key::Shift_R)
+}
+
 /// Ctrl, Alt, Super or Meta held: a shortcut, not typing. Shift is typing (capital letters).
 fn is_chord(modifiers: gdk::ModifierType) -> bool {
     modifiers.intersects(
@@ -608,26 +783,6 @@ fn is_chord(modifiers: gdk::ModifierType) -> bool {
     )
 }
 
-/// A modifier pressed on its own, on the way to a capital letter or a chord: neither search input
-/// nor a sign that the typing is meant elsewhere.
-fn is_modifier_key(key: gdk::Key) -> bool {
-    matches!(
-        key,
-        gdk::Key::Shift_L
-            | gdk::Key::Shift_R
-            | gdk::Key::Control_L
-            | gdk::Key::Control_R
-            | gdk::Key::Alt_L
-            | gdk::Key::Alt_R
-            | gdk::Key::Super_L
-            | gdk::Key::Super_R
-            | gdk::Key::Meta_L
-            | gdk::Key::Meta_R
-            | gdk::Key::ISO_Level3_Shift
-            | gdk::Key::Caps_Lock
-    )
-}
-
 /// The window-list key a press means under the current capture, if it belongs to the list at all.
 fn directory_key(capture: KeyCapture, key: gdk::Key, chord: bool) -> Option<DirectoryKey> {
     // Ctrl, Alt and Super combinations are shortcuts, never search characters.
@@ -715,28 +870,86 @@ fn short_path(path: &str, home: &str) -> String {
 }
 
 fn engaged_card_id(
-    hovered: &HashSet<String>,
+    hovered: &Option<String>,
     keyboard_active: bool,
     keyboard_focused: &Option<String>,
 ) -> Option<String> {
     if keyboard_active {
         keyboard_focused.clone()
     } else {
-        hovered.iter().next().cloned()
+        hovered.clone()
     }
 }
 
 impl App {
+    fn owns_keyboard(&self) -> bool {
+        self.keyboard_active || self.hover_keyboard.active
+    }
+
+    /// Allowlisted native facts only. This message never authorizes input or changes timers.
+    fn observe_keyboard(&self, reason: &str) {
+        if let Some(event) = crate::keyboard_observation::normalize(&json!({
+            "protocol": 2, "type": "keyboard-observation", "request": self.keyboard_request,
+            "origin": if self.keyboard_active { "explicit" } else { "hover" },
+            "reason": reason, "nativeMs": monotonic_ms(),
+            "deadlineMs": self.hover_keyboard.captured_deadline_ms(),
+            "captured": self.hover_keyboard.captured || (self.keyboard_active && self.window_active),
+        })) {
+            emit(event);
+        }
+    }
+
+    fn acknowledge_hover_keyboard(&mut self) {
+        if self.hover_keyboard.acquired(monotonic_ms()) {
+            self.observe_keyboard("acquired");
+            emit(
+                json!({ "protocol": 2, "type": "keyboard-active", "active": true, "revision": self.keyboard_request }),
+            );
+        }
+    }
+
+    fn cancel_pending_hover(&mut self) {
+        if let Some((token, _)) = self.hover_keyboard.pending.take() {
+            emit(json!({ "protocol": 2, "type": "hover-cancel", "token": token }));
+        }
+    }
+
+    fn request_hover_keyboard(&mut self, root: &gtk::Window) {
+        if self.keyboard_active
+            || !accepts_pointer(
+                self.visible,
+                self.interactive,
+                root.is_mapped(),
+                self.pointer.contains_pointer(),
+            )
+        {
+            return;
+        }
+        if let Some(token) = self
+            .hover_keyboard
+            .request(self.interaction_epoch, monotonic_ms())
+        {
+            emit(
+                json!({ "protocol": 2, "type": "hover-request", "token": token, "epoch": self.interaction_epoch }),
+            );
+        }
+    }
+
     fn end_engagement(&mut self) {
-        let was_keyboard_active = self.keyboard_active;
-        self.hovered.clear();
+        self.hovered = None;
+        self.brand_hovered = false;
+        self.directory_hovered = false;
         self.keyboard_focused = None;
         self.keyboard_active = false;
+        self.cancel_pending_hover();
+        self.hover_keyboard.clear();
+        self.window_active = false;
+        self.pending_request = None;
+        self.query.clear();
         self.sync_key_capture();
         self.collapse_generation += 1;
-        if was_keyboard_active {
-            emit(json!({ "protocol": 1, "type": "keyboard-active", "active": false }));
-        }
+        self.brand_generation += 1;
+        self.lifetime.invalidate();
     }
 
     fn apply_view(
@@ -746,11 +959,40 @@ impl App {
         sender: &ComponentSender<Self>,
         view: ViewMessage,
     ) {
-        if view.protocol != 1 || view.message_type != "view" || view.revision <= self.revision {
+        if view.protocol != 2 || view.message_type != "view" || view.revision <= self.revision {
             return;
         }
         self.revision = view.revision;
+        // Data changes revoke two-frame scroll callbacks, NOT keyboard ownership attempts. The
+        // latter are bound to the controller's exact admission epoch and a unique pointer token.
+        self.lifetime.invalidate();
+        // Visibility is controller policy; an empty workspace still has a compact ribbon.
+        let should_show = view.visible;
+        let visibility_changed = should_show != self.visible;
+        if self.visible && !should_show && self.hover_keyboard.inside {
+            self.pointer_anchor = Some(HideAnchor::new(
+                pointer_surface_position(root)
+                    .map_or(PointerAnchor::Unknown, |(x, y)| PointerAnchor::At(x, y)),
+            ));
+        }
+        self.visible = should_show;
         let focus_moved = self.focused_card_id != view.focused_card_id;
+        let hotkey_changed = self.hotkey != view.hotkey;
+        self.hotkey = view.hotkey.clone();
+        // Identity loss or hiding ends everything. A focus move inside the same identity (the
+        // controller's own activation echo) is not an app switch: it must not collapse the card
+        // under the pointer, only drop a hover request that has not been answered yet.
+        if !should_show || view.interaction_epoch != self.interaction_epoch || visibility_changed {
+            self.observe_keyboard("source-revoked");
+            self.leave_keyboard_mode(widgets, root);
+        } else if focus_moved && !self.owns_keyboard() {
+            self.cancel_pending_hover();
+            self.hover_keyboard.clear();
+        }
+        if hotkey_changed {
+            self.render_directory();
+        }
+        self.interaction_epoch = view.interaction_epoch;
         self.focused_card_id = view.focused_card_id;
         if self.windows != view.windows {
             self.windows = view.windows;
@@ -772,7 +1014,13 @@ impl App {
                 self.order.push(id);
             }
         }
-        self.hovered.retain(|id| self.data.contains_key(id));
+        if self
+            .hovered
+            .as_ref()
+            .is_some_and(|id| !self.data.contains_key(id))
+        {
+            self.hovered = None;
+        }
         let keyboard_card_removed = self.keyboard_active
             && self
                 .keyboard_focused
@@ -809,22 +1057,19 @@ impl App {
         self.refresh_cards();
         self.update_brand(widgets);
         if focus_moved {
-            self.scroll_focused_into_view(widgets);
+            self.follow_focus(widgets);
         }
 
-        let should_show = view.visible && !self.data.is_empty();
-        if should_show != self.visible {
-            self.visible = should_show;
+        if visibility_changed {
             if should_show {
                 root.set_exclusive_zone(COMPACT_HEIGHT);
                 root.present();
             } else {
-                self.leave_keyboard_mode(widgets, root);
                 root.set_exclusive_zone(-1);
                 root.set_visible(false);
             }
             emit(
-                json!({ "protocol": 1, "type": "visibility-applied", "revision": self.revision, "visible": should_show }),
+                json!({ "protocol": 2, "type": "visibility-applied", "revision": self.revision, "visible": should_show }),
             );
         }
     }
@@ -855,6 +1100,7 @@ impl App {
         let now = now_ms();
         // Hovering the brand column is an overview: every card shows its details at once.
         let all_open = self.brand_hovered && self.expanded();
+        let key_hint = hints::card_hint(self.hotkey.as_deref());
         for (id, view) in &self.cards {
             if let Some(card) = self.data.get(id) {
                 view.update(
@@ -862,6 +1108,7 @@ impl App {
                     self.focused_card_id.as_deref() == Some(id),
                     duplicates.contains(&card.repo_label),
                     now,
+                    key_hint.as_deref(),
                 );
                 view.set_expanded(all_open || self.open_card_id.as_deref() == Some(id));
             }
@@ -880,14 +1127,22 @@ impl App {
             .and_then(|id| self.data.get(id));
         let home = std::env::var("HOME").unwrap_or_default();
         let brand = brand_text(focused, &counts, &home);
-        widgets.eyebrow.set_text(&brand.eyebrow);
         widgets.title.set_text(&brand.title);
-        widgets.meta.set_text(&brand.meta);
-        widgets.brand.set_tooltip_text(
-            focused
-                .map(|card| card.cwd.as_str())
-                .filter(|cwd| !cwd.is_empty()),
-        );
+        // The last rung of the keyboard hints: in keyboard mode the key map replaces the folder,
+        // ellipsized at its end so the first keys always show.
+        if self.keyboard_active {
+            widgets.eyebrow.set_text(hints::KEYBOARD_EYEBROW);
+            widgets.meta.set_text(hints::KEYBOARD_META);
+            widgets.meta.set_ellipsize(gtk::pango::EllipsizeMode::End);
+        } else {
+            widgets.eyebrow.set_text(&brand.eyebrow);
+            widgets.meta.set_text(&brand.meta);
+            widgets.meta.set_ellipsize(gtk::pango::EllipsizeMode::Start);
+        }
+        widgets.brand.set_tooltip_text(Some(&hints::brand_tooltip(
+            focused.map(|card| card.cwd.as_str()),
+            self.hotkey.as_deref(),
+        )));
     }
 
     fn regroup(&mut self) {
@@ -929,7 +1184,7 @@ impl App {
             move_order_item(&mut self.order, index, target);
             self.reorder_widgets(parent);
             self.next_order_refresh_at = now_ms() + ORDER_REFRESH_MS;
-            emit(json!({ "protocol": 1, "type": "moved", "cardId": id, "direction": direction }));
+            emit(json!({ "protocol": 2, "type": "moved", "cardId": id, "direction": direction }));
         }
         let focus_id = if manual { id } else { &self.order[target] };
         if let Some(card) = self.cards.get(focus_id) {
@@ -943,6 +1198,9 @@ impl App {
         root: &gtk::Window,
         sender: &ComponentSender<Self>,
     ) {
+        if !self.visible || !self.interactive {
+            return;
+        }
         if let Some(id) =
             engaged_card_id(&self.hovered, self.keyboard_active, &self.keyboard_focused)
         {
@@ -967,7 +1225,11 @@ impl App {
         if self.open_card_id == card_id {
             return;
         }
-        self.open_card_id = card_id;
+        self.open_card_id = if self.visible && self.interactive {
+            card_id
+        } else {
+            None
+        };
         self.refresh_cards();
         self.resize(root);
         self.sync_directory_layout(widgets);
@@ -976,11 +1238,62 @@ impl App {
     /// Scroll the card row so the focused window's card is fully in view, as Niri focus moves
     /// between windows. Runs once layout has placed the card, so its position in the row is known.
     fn scroll_focused_into_view(&self, widgets: &AppWidgets) {
-        let Some(card) = self
-            .focused_card_id
-            .as_ref()
-            .and_then(|id| self.cards.get(id))
-        else {
+        if let Some(id) = self.focused_card_id.clone() {
+            self.scroll_card_into_view(widgets, &id);
+        }
+    }
+
+    /// Follow Niri focus along the row, but never under the operator's hand: while the pointer is
+    /// on the ribbon or it holds the keyboard the scroll waits, and runs once they leave.
+    fn follow_focus(&mut self, widgets: &AppWidgets) {
+        if self.pointer.contains_pointer() || self.owns_keyboard() {
+            self.scroll_deferred = true;
+        } else {
+            self.scroll_deferred = false;
+            self.scroll_focused_into_view(widgets);
+        }
+    }
+
+    /// Where explicit keyboard mode starts: the card under the pointer, else the focused window's
+    /// card, else the first card already on screen, so entering never jumps the row to its start.
+    fn keyboard_entry_card(&self, widgets: &AppWidgets) -> Option<String> {
+        let present = |id: &&String| self.cards.contains_key(*id);
+        if let Some(id) = self.hovered.as_ref().filter(present) {
+            return Some(id.clone());
+        }
+        if let Some(id) = self.focused_card_id.as_ref().filter(present) {
+            return Some(id.clone());
+        }
+        let adjustment = widgets.scroller.hadjustment();
+        let (left, right) = (
+            adjustment.value(),
+            adjustment.value() + adjustment.page_size(),
+        );
+        self.order
+            .iter()
+            .find(|id| {
+                self.cards.get(*id).is_some_and(|card| {
+                    card.root
+                        .compute_point(&widgets.cards_box, &gtk::graphene::Point::new(0.0, 0.0))
+                        .is_some_and(|origin| {
+                            let start = f64::from(origin.x());
+                            start >= left - 1.0
+                                && start + f64::from(card.root.width()) <= right + 1.0
+                        })
+                })
+            })
+            .or(self.order.first())
+            .cloned()
+    }
+
+    /// Bring one card fully into view with the least movement, once layout has placed it.
+    fn scroll_card_into_view(&self, widgets: &AppWidgets, id: &str) {
+        if !self.visible || !self.interactive {
+            return;
+        }
+        let lifetime = self.lifetime.clone();
+        let ticket = lifetime.ticket();
+        let Some(card) = self.cards.get(id) else {
             return;
         };
         let row = widgets.cards_box.clone();
@@ -989,6 +1302,9 @@ impl App {
         // card's position is final, and a panel that is not shown yet simply waits until it is.
         let frames = Cell::new(0u8);
         card.root.add_tick_callback(move |card, _clock| {
+            if !lifetime.accepts(ticket, card.is_mapped(), card.is_sensitive()) {
+                return glib::ControlFlow::Break;
+            }
             frames.set(frames.get() + 1);
             if frames.get() < 2 {
                 return glib::ControlFlow::Continue;
@@ -1016,8 +1332,11 @@ impl App {
     /// The ribbon is tall while a card is open (hovered or in keyboard mode), while the pointer is
     /// on the brand column with the list open, or while a typed number needs the list shown.
     fn expanded(&self) -> bool {
-        self.open_card_id.is_some()
-            || (self.directory_open && (self.brand_hovered || !self.query.is_empty()))
+        self.visible
+            && self.interactive
+            && (self.open_card_id.is_some()
+                || (self.directory_open
+                    && (self.brand_hovered || (self.owns_keyboard() && !self.query.is_empty()))))
     }
 
     /// The list fills the brand column, top to bottom, whenever the ribbon is expanded; compact,
@@ -1034,33 +1353,30 @@ impl App {
 
     fn resize(&self, root: &gtk::Window) {
         let expanded = self.expanded();
-        root.set_default_size(
-            1,
-            if expanded {
-                EXPANDED_HEIGHT
-            } else {
-                COMPACT_HEIGHT
-            },
-        );
-        root.set_exclusive_zone(COMPACT_HEIGHT);
+        let (height, zone) = surface_state(self.visible, expanded);
+        root.set_default_size(1, height);
+        root.set_exclusive_zone(zone);
         emit(
-            json!({ "protocol": 1, "type": "expanded", "expanded": expanded, "cardId": self.open_card_id }),
+            json!({ "protocol": 2, "type": "expanded", "expanded": expanded, "cardId": self.open_card_id, "queryLength": self.query.chars().count() }),
         );
     }
 
     fn sync_key_capture(&self) {
-        self.hover_guard
-            .set(self.directory_open && self.hover_grab && !self.keyboard_active);
-        self.key_capture
-            .set(if self.directory_open && !self.query.is_empty() {
+        self.hover_capture
+            .set(self.visible && self.interactive && self.hover_keyboard.active);
+        self.key_capture.set(
+            if !self.visible || !self.interactive || !self.owns_keyboard() {
+                KeyCapture::None
+            } else if self.directory_open && !self.query.is_empty() {
                 KeyCapture::ListTyped
             } else if self.directory_open {
                 KeyCapture::List
-            } else if self.keyboard_active {
+            } else if self.owns_keyboard() {
                 KeyCapture::Digits
             } else {
                 KeyCapture::None
-            });
+            },
+        );
     }
 
     fn handle_directory_key(
@@ -1071,7 +1387,7 @@ impl App {
     ) {
         match key {
             DirectoryKey::Char(digit) => {
-                self.open_directory(widgets, root, false);
+                self.open_directory(widgets, root);
                 if push_query_char(&mut self.query, digit) {
                     self.render_directory();
                     self.sync_key_capture();
@@ -1095,7 +1411,10 @@ impl App {
                         });
                         self.directory
                             .set_status(&format!("Jumping to #{window_id}…"));
-                        emit(json!({ "protocol": 1, "type": "jump", "windowId": window_id }));
+                        emit(
+                            json!({ "protocol": 2, "type": "jump", "windowId": window_id, "request": self.keyboard_request, "epoch": self.interaction_epoch }),
+                        );
+                        self.leave_keyboard_mode(widgets, root);
                     }
                     Some(JumpChoice::Card(card_id)) => {
                         self.pending_request = Some(PendingRequest {
@@ -1103,16 +1422,13 @@ impl App {
                             target: RequestTarget::Card(card_id.clone()),
                         });
                         self.directory.set_status("Opening…");
-                        emit(json!({ "protocol": 1, "type": "activate", "cardId": card_id }));
+                        emit(json!({ "protocol": 2, "type": "activate", "cardId": card_id }));
+                        self.leave_keyboard_mode(widgets, root);
                     }
-                    // Enter leading nowhere while only hover holds the keyboard: the typing was meant
-                    // for the window below, so hand the keyboard back.
-                    None if self.hover_guard.get() => self.cancel_hover_search(widgets, root),
                     None => {}
                 }
             }
-            DirectoryKey::Escape => self.dismiss_directory(widgets, root),
-            DirectoryKey::Interrupt => self.cancel_hover_search(widgets, root),
+            DirectoryKey::Escape => self.leave_keyboard_mode(widgets, root),
         }
     }
 
@@ -1138,8 +1454,9 @@ impl App {
             self.directory.set_prompt(
                 &self.windows,
                 &self.query,
-                self.window_active || self.keyboard_active,
+                self.owns_keyboard(),
                 self.allow_unlisted(),
+                self.hotkey.as_deref(),
             );
         }
     }
@@ -1149,79 +1466,24 @@ impl App {
             self.directory.render(
                 &self.windows,
                 &self.query,
-                self.window_active || self.keyboard_active,
+                self.owns_keyboard(),
                 self.allow_unlisted(),
+                self.hotkey.as_deref(),
             );
         }
     }
 
-    /// Take the keyboard for a hover-opened list, so a number can be typed at once. Clears the
-    /// window's focus widget first: Enter with nothing typed must not press a card or row that
-    /// kept focus from an earlier keyboard mode or click.
-    fn take_hover_grab(&mut self, root: &gtk::Window) -> bool {
-        if !self.directory_open || !self.directory_opened_by_hover || self.keyboard_active {
-            return false;
-        }
-        if !self.hover_grab {
-            GtkWindowExt::set_focus(root, None::<&gtk::Widget>);
-            root.set_keyboard_mode(KeyboardMode::Exclusive);
-            self.hover_grab = true;
-            self.directory_owns_keyboard = true;
-            self.sync_key_capture();
-        }
-        true
-    }
-
-    /// Typing held only by hover turned out to be meant for the window below: drop it, hand the
-    /// keyboard back and close the list, so keys still in flight find nothing to type into. The
-    /// list reopens when the pointer re-enters the ribbon.
-    fn cancel_hover_search(&mut self, widgets: &mut AppWidgets, root: &gtk::Window) {
-        self.query.clear();
-        self.release_hover_grab(root);
-        self.dismiss_directory(widgets, root);
-    }
-
-    /// Unlisted window numbers are reachable only when the keyboard was given on purpose (a
-    /// click or keyboard mode), not merely held by hover.
     fn allow_unlisted(&self) -> bool {
-        !(self.hover_grab && !self.keyboard_active)
-    }
-
-    fn release_hover_grab(&mut self, root: &gtk::Window) {
-        if self.hover_grab {
-            self.hover_grab = false;
-            self.grab_generation += 1;
-            if !self.keyboard_active {
-                root.set_keyboard_mode(KeyboardMode::OnDemand);
-            }
-            self.sync_key_capture();
-            self.refresh_directory_status();
-        }
+        self.keyboard_active
     }
 
-    fn arm_grab_timer(&mut self, sender: &ComponentSender<Self>) {
-        self.grab_generation += 1;
-        let generation = self.grab_generation;
-        let tx = sender.input_sender().clone();
-        glib::timeout_add_local_once(Duration::from_millis(HOVER_GRAB_MS), move || {
-            let _ = tx.send(AppMsg::DirectoryGrabExpired(generation));
-        });
-    }
-
-    fn open_directory(&mut self, widgets: &AppWidgets, root: &gtk::Window, by_hover: bool) {
+    fn open_directory(&mut self, widgets: &AppWidgets, root: &gtk::Window) {
         if self.directory_open || !self.visible || !self.interactive {
             return;
         }
         self.directory_open = true;
-        self.directory_opened_by_hover = by_hover;
         self.directory_session += 1;
         self.query.clear();
-        // On-demand until a hover grab (take_hover_grab) upgrades it; a click can always take the
-        // keyboard. Keyboard mode already holds it.
-        if !self.keyboard_active {
-            root.set_keyboard_mode(KeyboardMode::OnDemand);
-            self.directory_owns_keyboard = true;
-        }
         self.render_directory();
         self.sync_key_capture();
         self.resize(root);
@@ -1242,7 +1504,7 @@ impl App {
     /// pointer: the card kept open while the pointer crossed to the list has done its job.
     fn dismiss_directory(&mut self, widgets: &mut AppWidgets, root: &gtk::Window) {
         self.close_directory(widgets, root);
-        if self.hovered.is_empty() && !self.keyboard_active {
+        if self.hovered.is_none() && !self.keyboard_active {
             self.apply_expansion(widgets, root, None);
         }
     }
@@ -1250,10 +1512,58 @@ impl App {
     /// The one way out of keyboard mode. The list closes with it: once the ribbon gives up the
     /// keyboard nothing could type into or dismiss a list left open.
     fn leave_keyboard_mode(&mut self, widgets: &mut AppWidgets, root: &gtk::Window) {
+        let was_keyboard_active = self.owns_keyboard();
         self.close_directory(widgets, root);
         self.end_engagement();
+        self.refresh_cards();
         root.set_keyboard_mode(KeyboardMode::None);
+        GtkWindowExt::set_focus(root, None::<&gtk::Widget>);
+        // If GTK still owns focus, acknowledge release only on WindowActive(false), after Niri
+        // applies None. Otherwise the controller could mistake the in-flight NULL for lost identity.
+        if was_keyboard_active && !root.is_active() {
+            emit(
+                json!({ "protocol": 2, "type": "keyboard-active", "active": false, "revision": self.keyboard_request }),
+            );
+        }
         self.apply_expansion(widgets, root, None);
+        self.resize(root);
+        self.sync_directory_layout(widgets);
+        self.update_brand(widgets);
+        self.flush_deferred_scroll(widgets);
+    }
+
+    /// Give the keyboard back without ending what the pointer is doing. An idle or interrupted
+    /// hover grab must not collapse the card still under a stationary pointer, nor move the row:
+    /// only the typing state goes, and the list's prompt says how to take the keyboard again.
+    /// Explicit keyboard mode has no partial release; it leaves through `leave_keyboard_mode`.
+    fn release_keyboard(&mut self, widgets: &mut AppWidgets, root: &gtk::Window) {
+        if self.keyboard_active {
+            self.leave_keyboard_mode(widgets, root);
+            return;
+        }
+        let was_owning = self.owns_keyboard();
+        self.cancel_pending_hover();
+        self.hover_keyboard.clear();
+        self.query.clear();
+        self.sync_key_capture();
+        root.set_keyboard_mode(KeyboardMode::None);
+        GtkWindowExt::set_focus(root, None::<&gtk::Widget>);
+        if was_owning && !root.is_active() {
+            emit(
+                json!({ "protocol": 2, "type": "keyboard-active", "active": false, "revision": self.keyboard_request }),
+            );
+        }
+        self.render_directory();
+        self.resize(root);
+        self.sync_directory_layout(widgets);
+        self.update_brand(widgets);
+    }
+
+    fn flush_deferred_scroll(&mut self, widgets: &AppWidgets) {
+        if self.scroll_deferred && !self.pointer.contains_pointer() && !self.owns_keyboard() {
+            self.scroll_deferred = false;
+            self.scroll_focused_into_view(widgets);
+        }
     }
 
     fn close_directory(&mut self, widgets: &AppWidgets, root: &gtk::Window) {
@@ -1261,22 +1571,18 @@ impl App {
             return;
         }
         self.directory_open = false;
-        self.directory_opened_by_hover = false;
-        self.hover_grab = false;
         self.pending_request = None;
         self.query.clear();
-        if self.directory_owns_keyboard {
-            self.directory_owns_keyboard = false;
-            if !self.keyboard_active {
-                root.set_keyboard_mode(KeyboardMode::None);
-            }
-        }
         self.sync_key_capture();
         self.resize(root);
         self.sync_directory_layout(widgets);
     }
 }
 
+#[cfg(test)]
+#[path = "app_gui_tests.rs"]
+mod gui_tests;
+
 #[cfg(test)]
 mod tests {
     use super::{
@@ -1286,7 +1592,6 @@ mod tests {
     };
     use crate::protocol::Card;
     use relm4::gtk::gdk;
-    use std::collections::HashSet;
 
     fn counts() -> BrandCounts {
         BrandCounts {
@@ -1348,14 +1653,15 @@ mod tests {
 
     #[test]
     fn only_ctrl_alt_super_make_a_chord_and_bare_modifiers_are_not_typing() {
+        assert!(super::is_typing_modifier(gdk::Key::Shift_L));
+        assert!(super::is_typing_modifier(gdk::Key::Shift_R));
+        assert!(!super::is_typing_modifier(gdk::Key::Control_L));
         assert!(super::is_chord(gdk::ModifierType::CONTROL_MASK));
         assert!(super::is_chord(gdk::ModifierType::SUPER_MASK));
         assert!(
             !super::is_chord(gdk::ModifierType::SHIFT_MASK),
             "Shift types capitals"
         );
-        assert!(super::is_modifier_key(gdk::Key::Shift_L));
-        assert!(!super::is_modifier_key(gdk::Key::space));
     }
 
     #[test]
@@ -1444,13 +1750,13 @@ mod tests {
     #[test]
     fn stale_gtk_focus_does_not_retain_expansion_outside_keyboard_mode() {
         let focused = Some("card-a".to_owned());
-        assert_eq!(engaged_card_id(&HashSet::new(), false, &focused), None);
-        assert_eq!(engaged_card_id(&HashSet::new(), true, &focused), focused);
+        assert_eq!(engaged_card_id(&None, false, &focused), None);
+        assert_eq!(engaged_card_id(&None, true, &focused), focused);
     }
 
     #[test]
     fn pointer_hover_retains_expansion_without_keyboard_mode() {
-        let hovered = HashSet::from(["card-a".to_owned()]);
+        let hovered = Some("card-a".to_owned());
         assert_eq!(
             engaged_card_id(&hovered, false, &Some("card-b".to_owned())),
             Some("card-a".to_owned())
@@ -1459,7 +1765,7 @@ mod tests {
 
     #[test]
     fn explicit_keyboard_mode_takes_precedence_over_pointer_hover() {
-        let hovered = HashSet::from(["card-a".to_owned()]);
+        let hovered = Some("card-a".to_owned());
         assert_eq!(
             engaged_card_id(&hovered, true, &Some("card-b".to_owned())),
             Some("card-b".to_owned())