@tryinget/pi-activity-strip 0.8.0 → 0.10.0

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());
+    }
+}

package/native/panel/src/interaction.rs

@@ -0,0 +1,156 @@
+use std::cell::Cell;
+use std::rc::Rc;
+
+/// Shared with delayed GTK callbacks. Revocation survives a hide/show cycle, unlike `is_mapped`.
+#[derive(Clone, Default)]
+pub struct InteractionLifetime(Rc<Cell<u64>>);
+
+impl InteractionLifetime {
+    pub fn invalidate(&self) {
+        self.0.set(self.0.get().wrapping_add(1));
+    }
+
+    pub fn ticket(&self) -> u64 {
+        self.0.get()
+    }
+
+    pub fn accepts(&self, ticket: u64, visible: bool, interactive: bool) -> bool {
+        visible && interactive && ticket == self.ticket()
+    }
+}
+
+/// A real mapped pointer is necessary for hover intent, but controller permission is ALSO required.
+pub fn accepts_pointer(visible: bool, interactive: bool, mapped: bool, contains: bool) -> bool {
+    visible && interactive && mapped && contains
+}
+
+/// Where a pointer that was inside the body sat when the panel hid. A Wayland pointer enter carries
+/// no cause, so the compositor re-entering that unmoved pointer (remap, workspace return) looks like
+/// a genuine return, except that it reproduces this exact surface position.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum PointerAnchor {
+    At(f64, f64),
+    /// GDK had no position at hide: fail safe, the next entry is not taken as intent.
+    Unknown,
+}
+
+/// Whether an entry is the anchored pointer coming back rather than a new arrival. An entry whose
+/// position GDK cannot report is not evidence of movement either.
+pub fn is_stationary_reentry(
+    anchor: Option<PointerAnchor>,
+    entered_at: Option<(f64, f64)>,
+) -> bool {
+    match anchor {
+        Some(PointerAnchor::At(x, y)) => entered_at.is_none_or(|at| at == (x, y)),
+        Some(PointerAnchor::Unknown) => true,
+        None => false,
+    }
+}
+
+/// A pointer anchor plus the mapped absences it has outlived. Only the first mapped/body-absent
+/// Tick after a remap can fall before the compositor re-enters a stationary pointer; a second one,
+/// a full Tick later, means the pointer is elsewhere, and the anchor stops applying.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct HideAnchor {
+    pub at: PointerAnchor,
+    mapped_absences: u8,
+}
+
+impl HideAnchor {
+    pub fn new(at: PointerAnchor) -> Self {
+        Self {
+            at,
+            mapped_absences: 0,
+        }
+    }
+
+    pub fn after_mapped_absence(self) -> Option<Self> {
+        (self.mapped_absences == 0).then_some(Self {
+            mapped_absences: 1,
+            ..self
+        })
+    }
+}
+
+pub fn surface_state(visible: bool, expanded: bool) -> (i32, i32) {
+    (
+        if visible && expanded { 276 } else { 84 },
+        if visible { 84 } else { -1 },
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn hide_and_return_revoke_old_scroll_and_timer_tickets() {
+        let lifetime = InteractionLifetime::default();
+        let callback = lifetime.clone();
+        let ticket = lifetime.ticket();
+        assert!(callback.accepts(ticket, true, true));
+        lifetime.invalidate();
+        assert!(!callback.accepts(ticket, false, true));
+        assert!(!callback.accepts(ticket, true, true));
+        assert!(!callback.accepts(lifetime.ticket(), true, false));
+    }
+
+    #[test]
+    fn invisible_surface_cannot_expand_or_reclaim_zone() {
+        assert_eq!(surface_state(false, true), (84, -1));
+        assert_eq!(surface_state(false, false), (84, -1));
+        assert_eq!(surface_state(true, false), (84, 84));
+        assert_eq!(surface_state(true, true), (276, 84));
+    }
+
+    #[test]
+    fn pending_hover_requires_actual_pointer_on_an_interactive_mapped_surface() {
+        for facts in [
+            (false, true, true, true),
+            (true, false, true, true),
+            (true, true, false, true),
+            (true, true, true, false),
+        ] {
+            assert!(!accepts_pointer(facts.0, facts.1, facts.2, facts.3));
+        }
+        assert!(accepts_pointer(true, true, true, true));
+    }
+
+    #[test]
+    fn given_a_pointer_anchored_at_hide_when_an_entry_arrives_then_only_movement_is_intent() {
+        let anchor = Some(PointerAnchor::At(52.0, 32.0));
+        // Then: the exact pre-hide position is the stationary pointer, not a new arrival.
+        assert!(is_stationary_reentry(anchor, Some((52.0, 32.0))));
+        assert!(
+            is_stationary_reentry(anchor, None),
+            "unknown entry position is not movement"
+        );
+        assert!(is_stationary_reentry(
+            Some(PointerAnchor::Unknown),
+            Some((1.0, 1.0))
+        ));
+        // Then: any other position, or no anchor at all, is a genuine entry.
+        assert!(!is_stationary_reentry(anchor, Some((52.0, 32.5))));
+        assert!(!is_stationary_reentry(anchor, Some((53.0, 32.0))));
+        assert!(!is_stationary_reentry(None, Some((52.0, 32.0))));
+        assert!(!is_stationary_reentry(None, None));
+    }
+
+    #[test]
+    fn given_a_hide_anchor_when_mapped_absences_pass_then_only_the_first_is_survived() {
+        let anchor = HideAnchor::new(PointerAnchor::At(52.0, 32.0));
+        // Then: the remap-phase Tick (F02/F03) keeps the anchor.
+        let survived = anchor.after_mapped_absence().expect("first mapped absence");
+        assert_eq!(survived.at, PointerAnchor::At(52.0, 32.0));
+        // Then: a second mapped absence a full Tick later ends it, Unknown included.
+        assert_eq!(survived.after_mapped_absence(), None);
+        let unknown = HideAnchor::new(PointerAnchor::Unknown);
+        assert_eq!(
+            unknown
+                .after_mapped_absence()
+                .unwrap()
+                .after_mapped_absence(),
+            None
+        );
+    }
+}

package/native/panel/src/keyboard-observation-fixtures.json

@@ -0,0 +1,241 @@
+[
+  {
+    "name": "hover actual acquisition before native deadline",
+    "valid": true,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 1,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": 1000,
+      "deadlineMs": 4000,
+      "captured": true
+    }
+  },
+  {
+    "name": "typing activity renews observed hover deadline",
+    "valid": true,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 1,
+      "origin": "hover",
+      "reason": "activity",
+      "nativeMs": 1200,
+      "deadlineMs": 4200,
+      "captured": true
+    }
+  },
+  {
+    "name": "source revocation before expiry",
+    "valid": true,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 1,
+      "origin": "hover",
+      "reason": "source-revoked",
+      "nativeMs": 1200,
+      "deadlineMs": 4000,
+      "captured": true
+    }
+  },
+  {
+    "name": "native idle expiry at boundary",
+    "valid": true,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 2,
+      "origin": "hover",
+      "reason": "idle-expired",
+      "nativeMs": 4000,
+      "deadlineMs": 4000,
+      "captured": true
+    }
+  },
+  {
+    "name": "explicit capture has no hover deadline",
+    "valid": true,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 3,
+      "origin": "explicit",
+      "reason": "acquired",
+      "nativeMs": 5000,
+      "deadlineMs": null,
+      "captured": true
+    }
+  },
+  {
+    "name": "explicit source revocation",
+    "valid": true,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 3,
+      "origin": "explicit",
+      "reason": "source-revoked",
+      "nativeMs": 5100,
+      "deadlineMs": null,
+      "captured": true
+    }
+  },
+  {
+    "name": "unknown text is never projected",
+    "valid": true,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": 6000,
+      "deadlineMs": 9000,
+      "captured": true,
+      "query": "SECRET_QUERY",
+      "credential": "SECRET_CREDENTIAL"
+    }
+  },
+  {
+    "name": "grant is not capture",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": 6000,
+      "deadlineMs": 9000,
+      "captured": false
+    }
+  },
+  {
+    "name": "early idle cause is rejected",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "hover",
+      "reason": "idle-expired",
+      "nativeMs": 8999,
+      "deadlineMs": 9000,
+      "captured": true
+    }
+  },
+  {
+    "name": "expired acquisition is rejected",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": 9000,
+      "deadlineMs": 9000,
+      "captured": true
+    }
+  },
+  {
+    "name": "explicit never expires by hover idle",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "explicit",
+      "reason": "idle-expired",
+      "nativeMs": 9000,
+      "deadlineMs": null,
+      "captured": true
+    }
+  },
+  {
+    "name": "no missing native deadline",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": 6000,
+      "captured": true
+    }
+  },
+  {
+    "name": "no untyped origin",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "SECRET",
+      "reason": "acquired",
+      "nativeMs": 6000,
+      "deadlineMs": 9000,
+      "captured": true
+    }
+  },
+  {
+    "name": "no negative clock",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": -1,
+      "deadlineMs": 9000,
+      "captured": true
+    }
+  },
+  {
+    "name": "no string clock coercion",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": "6000",
+      "deadlineMs": 9000,
+      "captured": true
+    }
+  },
+  {
+    "name": "no unsafe request integer",
+    "valid": false,
+    "event": {
+      "protocol": 2,
+      "type": "keyboard-observation",
+      "request": 9007199254740992,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": 6000,
+      "deadlineMs": 9000,
+      "captured": true
+    }
+  },
+  {
+    "name": "legacy ABI still rejected",
+    "valid": false,
+    "event": {
+      "protocol": 1,
+      "type": "keyboard-observation",
+      "request": 4,
+      "origin": "hover",
+      "reason": "acquired",
+      "nativeMs": 6000,
+      "deadlineMs": 9000,
+      "captured": true
+    }
+  }
+]

package/native/panel/src/keyboard_observation.rs

@@ -0,0 +1,70 @@
+//! Optional private-v2 observation, never authorization or a cross-clock countdown.
+use serde_json::{Value, json};
+
+const MAX_SAFE: u64 = 9_007_199_254_740_991;
+
+/// Validate/allowlist the exact same executable protocol fixtures as the Node observer.
+/// Unknown fields are discarded, including all application/query text.
+pub(crate) fn normalize(value: &Value) -> Option<Value> {
+    if value["protocol"] != 2 || value["type"] != "keyboard-observation" {
+        return None;
+    }
+    let request = value["request"]
+        .as_u64()
+        .filter(|v| *v > 0 && *v <= MAX_SAFE)?;
+    let native_ms = value["nativeMs"].as_u64().filter(|v| *v <= MAX_SAFE)?;
+    let captured = value["captured"].as_bool()?;
+    let origin = value["origin"].as_str()?;
+    let reason = value["reason"].as_str()?;
+    if !captured
+        || !matches!(
+            reason,
+            "acquired" | "activity" | "idle-expired" | "source-revoked"
+        )
+    {
+        return None;
+    }
+    let deadline = value.get("deadlineMs")?;
+    match origin {
+        "hover" => {
+            let limit = deadline.as_u64().filter(|v| *v <= MAX_SAFE)?;
+            if (reason == "idle-expired" && native_ms < limit)
+                || (matches!(reason, "acquired" | "activity") && native_ms >= limit)
+            {
+                return None;
+            }
+        }
+        "explicit" if deadline.is_null() && reason != "idle-expired" => {}
+        _ => return None,
+    }
+    Some(
+        json!({"protocol":2, "type":"keyboard-observation", "request":request,
+        "origin":origin, "reason":reason, "nativeMs":native_ms,
+        "deadlineMs":deadline, "captured":captured}),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn shared_node_rust_protocol_transitions_are_observations_only() {
+        let cases: Value =
+            serde_json::from_str(include_str!("keyboard-observation-fixtures.json")).unwrap();
+        for case in cases.as_array().unwrap() {
+            let got = normalize(&case["event"]);
+            assert_eq!(
+                got.is_some(),
+                case["valid"].as_bool().unwrap(),
+                "{}",
+                case["name"]
+            );
+            if let Some(got) = got {
+                assert!(got.get("query").is_none());
+                assert!(got.get("credential").is_none());
+                assert_eq!(got.as_object().unwrap().len(), 8);
+            }
+        }
+    }
+}