@tryinget/pi-activity-strip 0.9.0 → 0.10.0

package/native/panel/src/card_view.rs

@@ -16,6 +16,7 @@ const AK_CHIP_SLOTS: usize = 1;
 
 pub struct CardView {
     pub root: gtk::Button,
+    pub motion: gtk::EventControllerMotion,
     phase: gtk::Label,
     repo: gtk::Label,
     state: gtk::Label,
@@ -154,7 +155,7 @@ impl CardView {
         motion.connect_leave(move |_| {
             let _ = tx.send(AppMsg::Hover(card_id.clone(), false));
         });
-        root.add_controller(motion);
+        root.add_controller(motion.clone());
 
         let focus = gtk::EventControllerFocus::new();
         let card_id = id.to_owned();
@@ -193,6 +194,7 @@ impl CardView {
 
         Self {
             root,
+            motion,
             phase,
             repo,
             state,
@@ -216,7 +218,14 @@ impl CardView {
         }
     }
 
-    pub fn update(&self, card: &Card, focused: bool, duplicate_label: bool, now_ms: i64) {
+    pub fn update(
+        &self,
+        card: &Card,
+        focused: bool,
+        duplicate_label: bool,
+        now_ms: i64,
+        key_hint: Option<&str>,
+    ) {
         let hidden_tab = card.hidden_tab();
         self.repo.set_text(&display_repo(card, duplicate_label));
         self.phase.set_text(text_or(&card.phase, "Idle"));
@@ -301,7 +310,7 @@ impl CardView {
         };
         let ak_note = ak_accessible_note(&card.ak_tasks);
         let window_note = window_note(card);
-        self.root.set_tooltip_text(Some(&format!(
+        let mut tooltip = format!(
             "{} {} ({}{}{}){}",
             if hidden_tab { "Present" } else { "Focus" },
             text_or(&card.repo_label, "Pi session"),
@@ -309,7 +318,13 @@ impl CardView {
             window_note,
             if hidden_tab { ", hidden tab" } else { "" },
             ak_note
-        )));
+        );
+        // The first rung of the keyboard hints: every card names the shortcut.
+        if let Some(hint) = key_hint {
+            tooltip.push('\n');
+            tooltip.push_str(hint);
+        }
+        self.root.set_tooltip_text(Some(&tooltip));
         let accessible_label = format!(
             "{}{}, {}, {}{}",
             text_or(&card.repo_label, "Pi session"),

package/native/panel/src/directory_view.rs

@@ -3,6 +3,7 @@ use crate::protocol::WindowEntry;
 use relm4::Sender;
 use relm4::gtk;
 use relm4::gtk::prelude::*;
+use std::cell::RefCell;
 
 /// Enough digits for any Niri window id; a longer number is a typo, not a window.
 const MAX_WINDOW_DIGITS: usize = 9;
@@ -25,6 +26,8 @@ pub struct DirectoryView {
     pub root: gtk::Box,
     status: gtk::Label,
     rows: gtk::Box,
+    // Every material field (including the activation target), but not current styling.
+    rendered_rows: RefCell<Vec<WindowEntry>>,
     sender: Sender<AppMsg>,
 }
 
@@ -55,6 +58,7 @@ impl DirectoryView {
             root,
             status,
             rows,
+            rendered_rows: RefCell::new(Vec::new()),
             sender: sender.clone(),
         }
     }
@@ -63,8 +67,20 @@ impl DirectoryView {
         self.root.set_visible(visible);
     }
 
-    /// Rebuild the rows for the current list and query. Clicking a row activates its card, so a
-    /// hidden tab is presented exactly as clicking its card would. The row Enter would open is
+    /// Strong references let GTK tests distinguish retained rows from replacement widgets.
+    #[cfg(test)]
+    pub(crate) fn row_widgets(&self) -> Vec<gtk::Widget> {
+        let mut rows = Vec::new();
+        let mut child = self.rows.first_child();
+        while let Some(row) = child {
+            child = row.next_sibling();
+            rows.push(row);
+        }
+        rows
+    }
+
+    /// Retain rows when their material data and order match; update focus/choice styling in
+    /// place. Clicking a row activates its card, including hidden tabs. The row Enter opens is
     /// marked, so a typed name always shows where it leads.
     pub fn render(
         &self,
@@ -72,11 +88,25 @@ impl DirectoryView {
         query: &str,
         can_type: bool,
         allow_unlisted: bool,
+        hotkey: Option<&str>,
     ) {
-        while let Some(child) = self.rows.first_child() {
-            self.rows.remove(&child);
-        }
         let shown = filter_entries(windows, query);
+        let key: Vec<WindowEntry> = shown
+            .iter()
+            .map(|entry| {
+                let mut key = (**entry).clone();
+                key.current = false;
+                key
+            })
+            .collect();
+        // Empty states have different messages; rebuild them rather than caching a label.
+        let reuse = !shown.is_empty() && *self.rendered_rows.borrow() == key;
+        if !reuse {
+            while let Some(child) = self.rows.first_child() {
+                self.rows.remove(&child);
+            }
+        }
+        let mut retained = self.rows.first_child();
         let choice = jump_choice(windows, query, allow_unlisted);
         // Alphabetical from the controller, so workspace headings would repeat; each row names
         // its workspace instead.
@@ -86,8 +116,21 @@ impl DirectoryView {
                 Some(JumpChoice::Card(card_id)) => &entry.card_id == card_id,
                 None => false,
             };
-            self.rows.append(&self.row(entry, chosen));
+            if reuse {
+                let row = retained.take().expect("cached directory row exists");
+                retained = row.next_sibling();
+                for (class, enabled) in [("current", entry.current), ("chosen", chosen)] {
+                    if enabled {
+                        row.add_css_class(class);
+                    } else {
+                        row.remove_css_class(class);
+                    }
+                }
+            } else {
+                self.rows.append(&self.row(entry, chosen));
+            }
         }
+        *self.rendered_rows.borrow_mut() = key;
         if shown.is_empty() {
             let empty = gtk::Label::new(Some(if windows.is_empty() {
                 "No agent windows"
@@ -98,8 +141,13 @@ impl DirectoryView {
             empty.set_xalign(0.0);
             self.rows.append(&empty);
         }
-        self.status
-            .set_text(&status_text(windows, query, can_type, allow_unlisted));
+        self.status.set_text(&status_text(
+            windows,
+            query,
+            can_type,
+            allow_unlisted,
+            hotkey,
+        ));
     }
 
     /// The typing hint alone, leaving the rows (and any click in progress on them) untouched.
@@ -109,9 +157,15 @@ impl DirectoryView {
         query: &str,
         can_type: bool,
         allow_unlisted: bool,
+        hotkey: Option<&str>,
     ) {
-        self.status
-            .set_text(&status_text(windows, query, can_type, allow_unlisted));
+        self.status.set_text(&status_text(
+            windows,
+            query,
+            can_type,
+            allow_unlisted,
+            hotkey,
+        ));
     }
 
     /// A transient message after a jump or activation, until the next keystroke re-renders.
@@ -257,10 +311,11 @@ fn status_text(
     query: &str,
     can_type: bool,
     allow_unlisted: bool,
+    hotkey: Option<&str>,
 ) -> String {
     if !can_type {
-        // The keyboard was handed back (hover timeout); a click takes it again.
-        return "Click, then type a name or number".to_owned();
+        // The keyboard was handed back (hover timeout); a click or the shortcut takes it again.
+        return crate::hints::pointer_prompt(hotkey);
     }
     match jump_choice(windows, query, allow_unlisted) {
         _ if query.is_empty() => "Type a name or number · ⏎ go".to_owned(),
@@ -302,19 +357,26 @@ mod tests {
     fn the_status_line_says_what_enter_will_do() {
         let windows = vec![entry("pi-extensions", 432, 2)];
         assert_eq!(
-            status_text(&windows, "", false, true),
+            status_text(&windows, "", false, true, None),
             "Click, then type a name or number"
         );
         assert_eq!(
-            status_text(&windows, "", true, true),
+            status_text(&windows, "", false, true, Some("Super+Shift+A")),
+            "Click or Super+Shift+A to type"
+        );
+        assert_eq!(
+            status_text(&windows, "", true, true, None),
             "Type a name or number · ⏎ go"
         );
-        assert!(status_text(&windows, "43", true, true).starts_with("#43"));
+        assert!(status_text(&windows, "43", true, true, None).starts_with("#43"));
         assert_eq!(
-            status_text(&windows, "ext", true, true),
+            status_text(&windows, "ext", true, true, None),
             "ext▏ ⏎ pi-extensions"
         );
-        assert_eq!(status_text(&windows, "zzz", true, true), "zzz▏ no match");
+        assert_eq!(
+            status_text(&windows, "zzz", true, true, None),
+            "zzz▏ no match"
+        );
     }
 
     #[test]

package/native/panel/src/hints.rs

@@ -0,0 +1,65 @@
+//! Progressive keyboard hints. The ribbon teaches its shortcut in three steps, each shown only
+//! once the operator is already doing the step before it: every tooltip names the shortcut, the
+//! list's status line says what the keyboard would do right now, and keyboard mode itself shows
+//! the whole key map where the folder path normally is.
+
+/// The whole key map, for the brand tooltip and the docs.
+pub const KEY_MAP: &str =
+    "←/→ move · Shift+←/→ reorder · Enter open\nType a name or window # to jump · Esc leaves";
+
+/// Brand lines while keyboard mode is on: the key map replaces the folder path.
+pub const KEYBOARD_EYEBROW: &str = "⌨ KEYBOARD MODE";
+pub const KEYBOARD_META: &str = "←→ move · ⏎ open · Esc";
+
+/// One line under each card's tooltip: the shortcut that reaches the ribbon without the mouse.
+pub fn card_hint(hotkey: Option<&str>) -> Option<String> {
+    hotkey.map(|key| format!("{key} drives the strip from the keyboard"))
+}
+
+/// The brand tooltip: where you are, then how to get here without the mouse.
+pub fn brand_tooltip(cwd: Option<&str>, hotkey: Option<&str>) -> String {
+    let keys = match hotkey {
+        Some(key) => format!("{key} — keyboard mode\n{KEY_MAP}"),
+        None => format!("Keyboard mode\n{KEY_MAP}"),
+    };
+    match cwd.filter(|cwd| !cwd.is_empty()) {
+        Some(cwd) => format!("{cwd}\n\n{keys}"),
+        None => keys,
+    }
+}
+
+/// The list's prompt before it may type: the two ways to hand it the keyboard.
+pub fn pointer_prompt(hotkey: Option<&str>) -> String {
+    match hotkey {
+        Some(key) => format!("Click or {key} to type"),
+        None => "Click, then type a name or number".to_owned(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_level_names_the_bound_shortcut_and_none_invents_one() {
+        assert_eq!(card_hint(None), None);
+        assert!(
+            card_hint(Some("Super+Shift+A"))
+                .unwrap()
+                .starts_with("Super+Shift+A")
+        );
+        assert!(pointer_prompt(Some("Super+Shift+A")).contains("Super+Shift+A"));
+        assert_eq!(pointer_prompt(None), "Click, then type a name or number");
+        let tooltip = brand_tooltip(Some("/home/me/repo"), Some("Super+Shift+A"));
+        assert!(tooltip.starts_with("/home/me/repo\n\nSuper+Shift+A"));
+        assert!(tooltip.contains("Esc leaves"));
+        assert!(brand_tooltip(Some(""), None).starts_with("Keyboard mode"));
+    }
+
+    #[test]
+    fn the_keyboard_mode_lines_fit_the_brand_column() {
+        // BRAND_WIDTH is 196 px; the meta font fits about 26 characters before ellipsizing.
+        assert!(KEYBOARD_META.chars().count() <= 26);
+        assert!(KEYBOARD_EYEBROW.chars().count() <= 26);
+    }
+}

package/native/panel/src/hover-lifecycle-fixtures.json

@@ -0,0 +1,30 @@
+[
+  {
+    "name": "capture releases and late focus cannot revive",
+    "steps": [["grant", true], ["capture", true], ["release", false], ["capture", false]]
+  },
+  {
+    "name": "release before GTK acquisition is final",
+    "steps": [["grant", true], ["release", false], ["capture", false]]
+  },
+  {
+    "name": "old permission cannot transfer to a newer request",
+    "steps": [
+      ["grant", true],
+      ["capture", true],
+      ["release", false],
+      ["grant", true],
+      ["stale-permission", true],
+      ["capture", true],
+      ["release", false]
+    ]
+  },
+  {
+    "name": "source revocation defeats later acquisition",
+    "steps": [["grant", true], ["capture", true], ["source-revoked", false], ["capture", false]]
+  },
+  {
+    "name": "duplicate acquisition preserves one request",
+    "steps": [["grant", true], ["capture", true], ["capture", true], ["release", false]]
+  }
+]

package/native/panel/src/hover_keyboard.rs

@@ -0,0 +1,237 @@
+use std::sync::OnceLock;
+use std::time::Instant;
+
+/// Idle ownership uses monotonic time, never the wall clock used for telemetry labels.
+pub fn monotonic_ms() -> i64 {
+    static START: OnceLock<Instant> = OnceLock::new();
+    START
+        .get_or_init(Instant::now)
+        .elapsed()
+        .as_millis()
+        .try_into()
+        .unwrap_or(i64::MAX)
+}
+
+/// Pointer-entry attempts are not data revisions or callback tickets. Tokens never repeat during
+/// a panel lifetime; leaving, hiding or explicit entry invalidates the pending attempt, not the counter.
+#[derive(Default, Debug)]
+pub struct HoverKeyboard {
+    next_token: u64,
+    pub inside: bool,
+    pub pending: Option<(u64, u64)>, // token, controller identity epoch
+    pub active: bool,
+    pub captured: bool,
+    touched_at: i64,
+}
+
+impl HoverKeyboard {
+    pub fn request(&mut self, epoch: u64, now: i64) -> Option<u64> {
+        if self.pending.is_some() || self.active {
+            return None;
+        }
+        self.next_token += 1;
+        self.pending = Some((self.next_token, epoch));
+        self.touched_at = now;
+        Some(self.next_token)
+    }
+
+    pub fn grant(
+        &mut self,
+        token: u64,
+        epoch: u64,
+        current_epoch: u64,
+        pointer_valid: bool,
+        now: i64,
+    ) -> bool {
+        if self.pending != Some((token, epoch))
+            || epoch != current_epoch
+            || !pointer_valid
+            || now.saturating_sub(self.touched_at) >= 3_000
+        {
+            return false;
+        }
+        self.pending = None;
+        self.active = true;
+        self.captured = false;
+        self.touched_at = now;
+        true
+    }
+
+    /// GTK focus confirms application of an ALREADY authorized grab; it never grants permission.
+    pub fn acquired(&mut self, now: i64) -> bool {
+        if !self.active || self.captured || self.expired(now) {
+            return false;
+        }
+        self.captured = true;
+        self.touched_at = now;
+        true
+    }
+
+    pub fn touch(&mut self, now: i64) {
+        if self.captured {
+            self.touched_at = now;
+        }
+    }
+
+    /// Observation in this process's monotonic domain, never a controller deadline.
+    pub fn captured_deadline_ms(&self) -> Option<i64> {
+        (self.active && self.captured).then(|| self.touched_at.saturating_add(3_000))
+    }
+
+    pub fn expired(&self, now: i64) -> bool {
+        // A parked nested compositor can take several seconds to commit a layer-shell change.
+        // Acquisition is separately bounded; the typing idle clock starts on actual focus.
+        let limit = if self.active && !self.captured {
+            10_000
+        } else {
+            3_000
+        };
+        (self.active || self.pending.is_some()) && now.saturating_sub(self.touched_at) >= limit
+    }
+
+    /// Retain `inside` on timeout/Escape: ordinary telemetry or child crossings cannot recapture.
+    /// Only a fresh physical region entry or click may request again.
+    pub fn clear(&mut self) -> Option<u64> {
+        self.active = false;
+        self.captured = false;
+        self.pending.take().map(|(token, _)| token)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn shared_hover_lifecycle_fixtures() {
+        let cases: serde_json::Value =
+            serde_json::from_str(include_str!("hover-lifecycle-fixtures.json")).unwrap();
+        for case in cases.as_array().unwrap() {
+            let mut h = HoverKeyboard::default();
+            let mut current = 0;
+            let mut old = 0;
+            for (index, step) in case["steps"].as_array().unwrap().iter().enumerate() {
+                let now = i64::try_from(index).unwrap() * 10;
+                match step[0].as_str().unwrap() {
+                    "grant" => {
+                        old = current;
+                        current = h.request(7, now).unwrap();
+                        assert!(h.grant(current, 7, 7, true, now));
+                    }
+                    "capture" => {
+                        h.acquired(now);
+                    }
+                    "release" | "source-revoked" => {
+                        h.clear();
+                    }
+                    "stale-permission" => {
+                        assert!(!h.grant(old, 7, 7, true, now));
+                    }
+                    other => panic!("unknown fixture operation {other}"),
+                }
+                assert_eq!(
+                    h.active,
+                    step[1].as_bool().unwrap(),
+                    "{} step {index}",
+                    case["name"]
+                );
+                assert_eq!(h.captured_deadline_ms().is_some(), h.captured);
+            }
+        }
+    }
+
+    #[test]
+    fn attempts_in_one_epoch_are_unique_and_old_grants_cannot_win() {
+        let mut h = HoverKeyboard::default();
+        let first = h.request(7, 0).unwrap();
+        assert_eq!(h.clear(), Some(first));
+        let second = h.request(7, 10).unwrap();
+        assert_ne!(first, second);
+        assert!(!h.grant(first, 7, 7, true, 11));
+        assert_eq!(h.pending, Some((second, 7)));
+        assert!(!h.grant(second, 7, 8, true, 11));
+        assert!(!h.grant(second, 7, 7, false, 11));
+        assert!(h.grant(second, 7, 7, true, 11));
+    }
+
+    #[test]
+    fn hide_show_and_explicit_upgrade_revoke_pending_grants() {
+        let mut h = HoverKeyboard::default();
+        let token = h.request(1, 0).unwrap();
+        h.clear();
+        assert!(!h.grant(token, 1, 1, true, 1));
+        let next = h.request(3, 2).unwrap();
+        assert!(!h.grant(token, 1, 3, true, 3));
+        assert!(h.grant(next, 3, 3, true, 3));
+    }
+
+    #[test]
+    fn grant_expires_even_before_the_next_tick_is_dispatched() {
+        let mut h = HoverKeyboard::default();
+        let token = h.request(7, 0).unwrap();
+        assert!(!h.grant(token, 7, 7, true, 3_000));
+        h.clear();
+        let next = h.request(7, 3_001).unwrap();
+        assert!(!h.grant(token, 7, 7, true, 3_002));
+        assert!(h.grant(next, 7, 7, true, 3_002));
+    }
+
+    #[test]
+    fn pending_acquisition_and_actual_capture_have_separate_bounded_lifetimes() {
+        let mut h = HoverKeyboard::default();
+        assert!(!h.acquired(0), "GTK focus alone is not authorization");
+        let token = h.request(1, 0).unwrap();
+        assert!(h.expired(3_000), "controller handshake cannot wait forever");
+        assert!(h.grant(token, 1, 1, true, 10));
+        assert!(!h.expired(3_010), "not yet holding any keyboard input");
+        h.touch(9_999);
+        assert!(
+            h.expired(10_010),
+            "pre-focus key/GTK noise cannot prolong acquisition"
+        );
+        assert!(h.acquired(6_000));
+        assert!(
+            !h.acquired(7_000),
+            "ordinary GTK activity cannot restart idle"
+        );
+        assert!(!h.expired(8_999));
+        assert!(h.expired(9_000));
+        h.clear();
+        assert!(
+            !h.acquired(9_001),
+            "late GTK focus cannot revive a revoked claim"
+        );
+    }
+
+    #[test]
+    fn applied_focus_at_acquisition_expiry_cannot_restart_an_expired_claim() {
+        let mut h = HoverKeyboard::default();
+        let token = h.request(1, 0).unwrap();
+        assert!(h.grant(token, 1, 1, true, 1));
+        assert!(!h.acquired(10_001));
+        h.clear();
+        let next = h.request(1, 10_002).unwrap();
+        assert!(!h.grant(token, 1, 1, true, 10_003));
+        assert!(h.grant(next, 1, 1, true, 10_003));
+        assert!(h.acquired(10_004));
+    }
+
+    #[test]
+    fn idle_is_bounded_even_with_query_and_does_not_invent_new_pointer_entry() {
+        let mut h = HoverKeyboard {
+            inside: true,
+            ..Default::default()
+        };
+        let token = h.request(1, 0).unwrap();
+        assert!(h.grant(token, 1, 1, true, 10));
+        assert!(h.acquired(10));
+        assert!(!h.expired(3_009));
+        h.touch(2_500);
+        assert!(!h.expired(5_499));
+        assert!(h.expired(5_500));
+        h.clear();
+        assert!(h.inside);
+        assert!(!h.active);
+        assert!(h.pending.is_none());
+    }
+}