@tryinget/pi-activity-strip 0.8.0 → 0.10.0

package/native/panel/src/app.rs

@@ -1,20 +1,31 @@
 use crate::card_view::CardView;
-use crate::protocol::{Card, ViewMessage, demo_view, emit, emit_error, emit_ready};
+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};
 use relm4::gtk;
+use relm4::gtk::gdk;
 use relm4::gtk::glib;
 use relm4::gtk::prelude::*;
 use relm4::{Component, ComponentParts, ComponentSender};
 use serde_json::json;
-use std::collections::{HashMap, HashSet};
+use std::cell::Cell;
+use std::collections::HashMap;
+use std::rc::Rc;
 use std::time::Duration;
 
 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;
 
@@ -28,15 +39,85 @@ 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,
     next_order_refresh_at: i64,
     collapse_generation: u64,
     interactive: bool,
+    directory: DirectoryView,
+    windows: Vec<WindowEntry>,
+    directory_open: bool,
+    directory_hovered: bool,
+    /// The pointer is over the brand column: it expands the ribbon like a card does, showing the
+    /// list at full height.
+    brand_hovered: bool,
+    /// 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,
+    /// Counts list openings, so a jump or activation result only acts on the list that asked.
+    directory_session: u64,
+    pending_request: Option<PendingRequest>,
+    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>>,
+}
+
+/// Keys the window list takes before any card sees them.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum KeyCapture {
+    None,
+    /// Keyboard mode on the cards: a typed name or number character opens the list; Enter and
+    /// Escape stay with the cards.
+    Digits,
+    /// The list is open with nothing typed: digits, Backspace and Escape are its own; Enter still
+    /// reaches the focused card.
+    List,
+    /// The list is open with digits typed: Enter jumps.
+    ListTyped,
+}
+
+/// What the open list asked the controller for, so only that answer acts on it.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct PendingRequest {
+    session: u64,
+    target: RequestTarget,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum RequestTarget {
+    Card(String),
+    Window(i64),
+}
+
+#[derive(Debug)]
+pub enum DirectoryKey {
+    /// A letter, digit, `-`, `_` or `.` of a name or window number.
+    Char(char),
+    Backspace,
+    Enter,
+    Escape,
 }
 
 #[derive(Debug)]
@@ -49,12 +130,22 @@ 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),
-    WindowInactive,
+    WindowActive(bool),
     ParentGone,
     InputError(String),
+    DirectoryHover(bool),
+    BrandHover(bool),
+    BrandSettle(u64),
+    DirectoryKey(DirectoryKey),
+    DirectoryActivate(String),
+    JumpResult(i64, bool, String),
 }
 
 #[relm4::component(pub)]
@@ -85,6 +176,9 @@ impl Component for App {
                     add_css_class: "brand",
                     set_orientation: gtk::Orientation::Vertical,
                     set_width_request: BRAND_WIDTH,
+                    // Set explicitly so the window list's expanding rows cannot widen the brand
+                    // and push the cards aside.
+                    set_hexpand: false,
                     set_valign: gtk::Align::Center,
 
                     #[name = "eyebrow"]
@@ -156,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| {
@@ -168,34 +262,124 @@ impl Component for App {
 
         let tx = sender.input_sender().clone();
         root.connect_is_active_notify(move |window| {
-            if !window.is_active() {
-                let _ = tx.send(AppMsg::WindowInactive);
-            }
+            let _ = tx.send(AppMsg::WindowActive(window.is_active()));
         });
 
+        let directory = DirectoryView::new(sender.input_sender());
+        let key_capture = Rc::new(Cell::new(KeyCapture::None));
+        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,
             next_order_refresh_at: 0,
             collapse_generation: 0,
             interactive: !init.click_through,
+            directory,
+            windows: Vec::new(),
+            directory_open: false,
+            directory_hovered: false,
+            brand_hovered: false,
+            brand_generation: 0,
+            directory_session: 0,
+            pending_request: None,
+            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),
         };
         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);
+
+        // 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));
+        });
+        let tx = sender.input_sender().clone();
+        hover.connect_leave(move |_| {
+            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 tx = sender.input_sender().clone();
+        brand_hover.connect_enter(move |_, _, _| {
+            let _ = tx.send(AppMsg::BrandHover(true));
+        });
+        let tx = sender.input_sender().clone();
+        brand_hover.connect_leave(move |_| {
+            let _ = tx.send(AppMsg::BrandHover(false));
+        });
+        widgets.brand.add_controller(brand_hover);
+
+        // Captured before any card sees it, and only while the list (or keyboard mode) is live:
+        // see `directory_key` for which keys belong to the list in which state.
+        let keys = gtk::EventControllerKey::new();
+        keys.set_propagation_phase(gtk::PropagationPhase::Capture);
+        let tx = sender.input_sender().clone();
+        keys.connect_key_pressed(move |_, key, _, modifiers| {
+            let chord = is_chord(modifiers);
+            let message = match directory_key(key_capture.get(), key, chord) {
+                Some(message) => message,
+                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
+        });
+        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()));
@@ -213,13 +397,55 @@ 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.follow_focus(widgets);
+                    }
                     self.next_order_refresh_at = now_ms() + ORDER_REFRESH_MS;
                 }
                 self.refresh_cards();
@@ -227,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;
@@ -247,28 +486,34 @@ impl Component for App {
                 }
             }
             AppMsg::Activate(id) => {
-                emit(json!({ "protocol": 1, "type": "activate", "cardId": id }));
-                if self.keyboard_active {
-                    self.end_engagement();
-                    root.set_keyboard_mode(KeyboardMode::None);
-                    self.apply_expansion(widgets, root, None);
-                }
+                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) {
                     card.set_activation(ok, &message);
                 }
+                if self.take_own_request(&RequestTarget::Card(id)) {
+                    if ok {
+                        self.finish_directory_jump(widgets, root);
+                    } else {
+                        self.directory.set_status(&message);
+                    }
+                }
             }
-            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.end_engagement();
-                        root.set_keyboard_mode(KeyboardMode::None);
-                        self.apply_expansion(widgets, root, None);
+                        self.leave_keyboard_mode(widgets, root);
                     } else {
                         self.keyboard_active = true;
-                        self.hovered.clear();
-                        self.keyboard_focused = self.order.first().cloned();
+                        self.sync_key_capture();
+                        self.keyboard_focused = self.keyboard_entry_card(widgets);
                         root.set_keyboard_mode(KeyboardMode::Exclusive);
                         root.present();
                         let focus_grabbed = self
@@ -278,36 +523,289 @@ 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.end_engagement();
-                            root.set_keyboard_mode(KeyboardMode::None);
-                            self.apply_expansion(widgets, root, None);
+                            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 {
+                    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.
+                self.refresh_cards();
+                if entered {
+                    self.resize(root);
+                    self.sync_directory_layout(widgets);
+                } else {
+                    // Collapse only after the same grace as a card, so crossing from the brand to
+                    // a card does not flicker the ribbon down and up again.
+                    self.reconcile_engagement(widgets, root, &sender);
+                    let generation = self.brand_generation;
+                    let tx = sender.input_sender().clone();
+                    glib::timeout_add_local_once(Duration::from_millis(120), move || {
+                        let _ = tx.send(AppMsg::BrandSettle(generation));
+                    });
                 }
             }
-            AppMsg::Collapse | AppMsg::WindowInactive => {
-                self.end_engagement();
-                root.set_keyboard_mode(KeyboardMode::None);
-                self.apply_expansion(widgets, root, None);
+            AppMsg::BrandSettle(generation) => {
+                if generation == self.brand_generation {
+                    self.resize(root);
+                    self.sync_directory_layout(widgets);
+                }
             }
             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())
                 {
                     self.apply_expansion(widgets, root, None);
                 }
             }
             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;
+                if entered {
+                    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 {
+                    self.pointer_anchor = None;
+                    self.hover_keyboard.inside = false;
+                    if !self.keyboard_active {
+                        self.leave_keyboard_mode(widgets, root);
+                    }
+                }
+            }
+            AppMsg::DirectoryKey(key) => {
+                if self.owns_keyboard() {
+                    self.hover_keyboard.touch(monotonic_ms());
+                    self.observe_keyboard("activity");
+                    self.handle_directory_key(widgets, root, key);
+                }
+            }
+            AppMsg::DirectoryActivate(card_id) => {
+                self.pending_request = Some(PendingRequest {
+                    session: self.directory_session,
+                    target: RequestTarget::Card(card_id.clone()),
+                });
+                self.directory.set_status("Opening…");
+                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)) {
+                    if ok {
+                        // The jumped-to window must get the keyboard back at once.
+                        self.finish_directory_jump(widgets, root);
+                    } else {
+                        self.directory.set_status(&message);
+                    }
+                }
+            }
             AppMsg::ParentGone => root.close(),
         }
     }
 }
 
+/// The scroll offset that shows the span `start..end` with the least movement: unchanged when it
+/// is already fully visible, otherwise just far enough to bring its nearer edge into view.
+fn scroll_to_show(value: f64, page: f64, start: f64, end: f64) -> f64 {
+    if start < value {
+        start
+    } else if end > value + page {
+        (end - page).min(start)
+    } else {
+        value
+    }
+}
+
+/// Whether a result for `target` answers the request the list opened as `session` is waiting on.
+fn answers_request(pending: Option<&PendingRequest>, session: u64, target: &RequestTarget) -> bool {
+    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(
+        gdk::ModifierType::CONTROL_MASK
+            | gdk::ModifierType::ALT_MASK
+            | gdk::ModifierType::SUPER_MASK
+            | gdk::ModifierType::META_MASK,
+    )
+}
+
+/// 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.
+    if chord {
+        return None;
+    }
+    let typed = key
+        .to_unicode()
+        .filter(|character| is_query_char(*character));
+    match capture {
+        KeyCapture::None => None,
+        KeyCapture::Digits => typed.map(DirectoryKey::Char),
+        KeyCapture::List | KeyCapture::ListTyped => match key {
+            gdk::Key::BackSpace => Some(DirectoryKey::Backspace),
+            gdk::Key::Return | gdk::Key::KP_Enter if capture == KeyCapture::ListTyped => {
+                Some(DirectoryKey::Enter)
+            }
+            gdk::Key::Escape => Some(DirectoryKey::Escape),
+            _ => typed.map(DirectoryKey::Char),
+        },
+    }
+}
+
 fn navigation_target(index: usize, direction: i32, len: usize) -> Option<usize> {
     if len == 0 {
         return None;
@@ -372,27 +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(
@@ -402,11 +959,45 @@ 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;
+            self.render_directory();
+        }
         let incoming_order: Vec<_> = view
             .sessions
             .iter()
@@ -423,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
@@ -450,9 +1047,7 @@ impl App {
             if focus_grabbed {
                 self.reconcile_engagement(widgets, root, sender);
             } else {
-                self.end_engagement();
-                root.set_keyboard_mode(KeyboardMode::None);
-                self.apply_expansion(widgets, root, None);
+                self.leave_keyboard_mode(widgets, root);
             }
         }
         if open_card_removed {
@@ -461,22 +1056,20 @@ impl App {
         self.reorder_widgets(&widgets.cards_box);
         self.refresh_cards();
         self.update_brand(widgets);
+        if focus_moved {
+            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.end_engagement();
-                root.set_keyboard_mode(KeyboardMode::None);
-                self.apply_expansion(widgets, root, None);
                 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 }),
             );
         }
     }
@@ -505,6 +1098,9 @@ impl App {
     fn refresh_cards(&self) {
         let duplicates = duplicate_labels(self.data.values());
         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(
@@ -512,8 +1108,9 @@ impl App {
                     self.focused_card_id.as_deref() == Some(id),
                     duplicates.contains(&card.repo_label),
                     now,
+                    key_hint.as_deref(),
                 );
-                view.set_expanded(self.open_card_id.as_deref() == Some(id));
+                view.set_expanded(all_open || self.open_card_id.as_deref() == Some(id));
             }
         }
     }
@@ -530,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) {
@@ -579,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) {
@@ -593,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)
         {
@@ -610,38 +1218,380 @@ impl App {
 
     fn apply_expansion(
         &mut self,
-        _widgets: &mut AppWidgets,
+        widgets: &mut AppWidgets,
         root: &gtk::Window,
         card_id: Option<String>,
     ) {
         if self.open_card_id == card_id {
             return;
         }
-        self.open_card_id = card_id;
-        let expanded = self.open_card_id.is_some();
-        root.set_default_size(
-            1,
-            if expanded {
-                EXPANDED_HEIGHT
+        self.open_card_id = if self.visible && self.interactive {
+            card_id
+        } else {
+            None
+        };
+        self.refresh_cards();
+        self.resize(root);
+        self.sync_directory_layout(widgets);
+    }
+
+    /// 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) {
+        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();
+        let scroller = widgets.scroller.clone();
+        // Measured on the second frame after the change: the first one lays the row out, so the
+        // 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;
+            }
+            if let Some(origin) = card.compute_point(&row, &gtk::graphene::Point::new(0.0, 0.0)) {
+                let start = f64::from(origin.x());
+                let end = start + f64::from(card.width());
+                let adjustment = scroller.hadjustment();
+                adjustment.set_value(scroll_to_show(
+                    adjustment.value(),
+                    adjustment.page_size(),
+                    start,
+                    end,
+                ));
+            }
+            glib::ControlFlow::Break
+        });
+    }
+
+    fn focused_position(&self) -> Option<usize> {
+        let id = self.focused_card_id.as_ref()?;
+        self.order.iter().position(|candidate| candidate == id)
+    }
+
+    /// 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.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,
+    /// it is hidden.
+    fn sync_directory_layout(&self, widgets: &AppWidgets) {
+        let shown = self.directory_open && self.expanded();
+        self.directory.set_visible(shown);
+        widgets.brand.set_valign(if shown {
+            gtk::Align::Fill
+        } else {
+            gtk::Align::Center
+        });
+    }
+
+    fn resize(&self, root: &gtk::Window) {
+        let expanded = self.expanded();
+        let (height, zone) = surface_state(self.visible, expanded);
+        root.set_default_size(1, height);
+        root.set_exclusive_zone(zone);
+        emit(
+            json!({ "protocol": 2, "type": "expanded", "expanded": expanded, "cardId": self.open_card_id, "queryLength": self.query.chars().count() }),
+        );
+    }
+
+    fn sync_key_capture(&self) {
+        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.owns_keyboard() {
+                KeyCapture::Digits
             } else {
-                COMPACT_HEIGHT
+                KeyCapture::None
             },
         );
-        root.set_exclusive_zone(COMPACT_HEIGHT);
+    }
+
+    fn handle_directory_key(
+        &mut self,
+        widgets: &mut AppWidgets,
+        root: &gtk::Window,
+        key: DirectoryKey,
+    ) {
+        match key {
+            DirectoryKey::Char(digit) => {
+                self.open_directory(widgets, root);
+                if push_query_char(&mut self.query, digit) {
+                    self.render_directory();
+                    self.sync_key_capture();
+                    self.resize(root);
+                    self.sync_directory_layout(widgets);
+                }
+            }
+            DirectoryKey::Backspace => {
+                self.query.pop();
+                self.render_directory();
+                self.sync_key_capture();
+                self.resize(root);
+                self.sync_directory_layout(widgets);
+            }
+            DirectoryKey::Enter => {
+                match jump_choice(&self.windows, &self.query, self.allow_unlisted()) {
+                    Some(JumpChoice::Window(window_id)) => {
+                        self.pending_request = Some(PendingRequest {
+                            session: self.directory_session,
+                            target: RequestTarget::Window(window_id),
+                        });
+                        self.directory
+                            .set_status(&format!("Jumping to #{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 {
+                            session: self.directory_session,
+                            target: RequestTarget::Card(card_id.clone()),
+                        });
+                        self.directory.set_status("Opening…");
+                        emit(json!({ "protocol": 2, "type": "activate", "cardId": card_id }));
+                        self.leave_keyboard_mode(widgets, root);
+                    }
+                    None => {}
+                }
+            }
+            DirectoryKey::Escape => self.leave_keyboard_mode(widgets, root),
+        }
+    }
+
+    /// Whether a result answers exactly what the open list asked for. Anything else (a card's own
+    /// activation, an earlier jump) leaves the pending request in place.
+    fn take_own_request(&mut self, target: &RequestTarget) -> bool {
+        if self.directory_open
+            && answers_request(
+                self.pending_request.as_ref(),
+                self.directory_session,
+                target,
+            )
+        {
+            self.pending_request = None;
+            true
+        } else {
+            false
+        }
+    }
+
+    fn refresh_directory_status(&self) {
+        if self.directory_open {
+            self.directory.set_prompt(
+                &self.windows,
+                &self.query,
+                self.owns_keyboard(),
+                self.allow_unlisted(),
+                self.hotkey.as_deref(),
+            );
+        }
+    }
+
+    fn render_directory(&self) {
+        if self.directory_open {
+            self.directory.render(
+                &self.windows,
+                &self.query,
+                self.owns_keyboard(),
+                self.allow_unlisted(),
+                self.hotkey.as_deref(),
+            );
+        }
+    }
+
+    fn allow_unlisted(&self) -> bool {
+        self.keyboard_active
+    }
+
+    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_session += 1;
+        self.query.clear();
+        self.render_directory();
+        self.sync_key_capture();
+        self.resize(root);
+        self.sync_directory_layout(widgets);
+    }
+
+    /// After the list moved focus somewhere, nothing on the ribbon may keep the keyboard: the list
+    /// closes, and keyboard mode ends exactly as activating a card ends it.
+    fn finish_directory_jump(&mut self, widgets: &mut AppWidgets, root: &gtk::Window) {
+        if self.keyboard_active {
+            self.leave_keyboard_mode(widgets, root);
+        } else {
+            self.dismiss_directory(widgets, root);
+        }
+    }
+
+    /// Close the list and let the ribbon fall back to compact unless a card is still under the
+    /// 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_none() && !self.keyboard_active {
+            self.apply_expansion(widgets, root, None);
+        }
+    }
+
+    /// 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();
-        emit(
-            json!({ "protocol": 1, "type": "expanded", "expanded": expanded, "cardId": self.open_card_id }),
-        );
+        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) {
+        if !self.directory_open {
+            return;
+        }
+        self.directory_open = false;
+        self.pending_request = None;
+        self.query.clear();
+        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::{
-        BrandCounts, brand_text, engaged_card_id, move_order_item, navigation_target, short_path,
+        BrandCounts, DirectoryKey, KeyCapture, PendingRequest, RequestTarget, answers_request,
+        brand_text, directory_key, engaged_card_id, move_order_item, navigation_target,
+        scroll_to_show, short_path,
     };
     use crate::protocol::Card;
-    use std::collections::HashSet;
+    use relm4::gtk::gdk;
 
     fn counts() -> BrandCounts {
         BrandCounts {
@@ -650,6 +1600,113 @@ mod tests {
         }
     }
 
+    #[test]
+    fn the_focused_card_scrolls_into_view_with_the_least_movement() {
+        // Row viewport 0..1000.
+        assert_eq!(
+            scroll_to_show(0.0, 1000.0, 200.0, 440.0),
+            0.0,
+            "already visible"
+        );
+        assert_eq!(
+            scroll_to_show(0.0, 1000.0, 1500.0, 1740.0),
+            740.0,
+            "right of view"
+        );
+        assert_eq!(
+            scroll_to_show(800.0, 1000.0, 300.0, 540.0),
+            300.0,
+            "left of view"
+        );
+        assert_eq!(
+            scroll_to_show(0.0, 200.0, 500.0, 740.0),
+            500.0,
+            "wider than the view: its start wins"
+        );
+    }
+
+    #[test]
+    fn only_the_answer_to_what_the_open_list_asked_acts_on_it() {
+        let pending = PendingRequest {
+            session: 3,
+            target: RequestTarget::Window(43),
+        };
+        assert!(answers_request(
+            Some(&pending),
+            3,
+            &RequestTarget::Window(43)
+        ));
+        assert!(
+            !answers_request(Some(&pending), 3, &RequestTarget::Window(44)),
+            "an earlier jump to another number"
+        );
+        assert!(
+            !answers_request(Some(&pending), 3, &RequestTarget::Card("card-a".into())),
+            "a card's own activation"
+        );
+        assert!(
+            !answers_request(Some(&pending), 4, &RequestTarget::Window(43)),
+            "a list opened again since"
+        );
+        assert!(!answers_request(None, 3, &RequestTarget::Window(43)));
+    }
+
+    #[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"
+        );
+    }
+
+    #[test]
+    fn the_window_list_takes_keys_only_while_they_belong_to_it() {
+        let key = |capture, key| format!("{:?}", directory_key(capture, key, false));
+        assert_eq!(
+            format!("{:?}", directory_key(KeyCapture::List, gdk::Key::c, true)),
+            "None",
+            "Ctrl+C is a shortcut, not a search for c"
+        );
+        assert_eq!(key(KeyCapture::None, gdk::Key::_4), "None");
+        // Keyboard mode on the cards: a digit opens the list, Enter and Escape stay with the cards.
+        assert_eq!(key(KeyCapture::Digits, gdk::Key::_4), "Some(Char('4'))");
+        assert_eq!(
+            key(KeyCapture::Digits, gdk::Key::e),
+            "Some(Char('e'))",
+            "a letter starts a name search"
+        );
+        assert_eq!(key(KeyCapture::Digits, gdk::Key::Return), "None");
+        assert_eq!(key(KeyCapture::Digits, gdk::Key::Escape), "None");
+        assert_eq!(key(KeyCapture::List, gdk::Key::KP_7), "Some(Char('7'))");
+        assert_eq!(key(KeyCapture::List, gdk::Key::minus), "Some(Char('-'))");
+        assert_eq!(
+            key(KeyCapture::List, gdk::Key::space),
+            "None",
+            "space is never taken"
+        );
+        assert_eq!(
+            key(KeyCapture::List, gdk::Key::Return),
+            "None",
+            "with nothing typed, Enter still reaches the focused card"
+        );
+        assert_eq!(key(KeyCapture::ListTyped, gdk::Key::Return), "Some(Enter)");
+        assert_eq!(
+            key(KeyCapture::List, gdk::Key::BackSpace),
+            "Some(Backspace)"
+        );
+        assert_eq!(key(KeyCapture::List, gdk::Key::Escape), "Some(Escape)");
+        assert_eq!(key(KeyCapture::None, gdk::Key::a), "None");
+        assert!(matches!(
+            directory_key(KeyCapture::ListTyped, gdk::Key::KP_Enter, false),
+            Some(DirectoryKey::Enter)
+        ));
+    }
+
     #[test]
     fn brand_names_the_focused_windows_project_and_folder() {
         let card: Card = serde_json::from_value(serde_json::json!({
@@ -693,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())
@@ -708,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())