Skip to main content

kernel/
host_event.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Host-neutral input events flowing from platform adapters into the
5//! runtime.
6//!
7//! [`HostEvent`] is a serialisable, platform-agnostic UI event that
8//! gets fed into either the egui or iced hosts for parity verification
9//! and golden replay. Pre-M4 slice 8 (2026-04-22) these types lived in
10//! `shell/desktop/workbench/ux_replay.rs` next to the replay session
11//! driver; the session itself (`UxReplaySession`) carries a
12//! `UxTreeSnapshot` that stays shell-side, but the event vocabulary
13//! is portable and moves here so `FrameHostInput.events: Vec<HostEvent>`
14//! can live in kernel.
15//!
16//! The shell crate re-exports these types from `ux_replay.rs` so
17//! existing import paths resolve unchanged.
18
19use serde::{Deserialize, Serialize};
20
21/// Represents a platform-agnostic UI event that can be serialized,
22/// deserialized, and fed into either the egui or expected iced hosts
23/// for parity verification and golden testing.
24#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
25pub enum HostEvent {
26    PointerMoved {
27        x: f32,
28        y: f32,
29    },
30    PointerDown {
31        x: f32,
32        y: f32,
33        button: PointerButton,
34    },
35    PointerUp {
36        x: f32,
37        y: f32,
38        button: PointerButton,
39    },
40    Scroll {
41        dx: f32,
42        dy: f32,
43    },
44    Zoom {
45        delta: f32,
46    },
47    Text(String),
48    Key {
49        key: String,
50        pressed: bool,
51        modifiers: ModifiersState,
52    },
53    Focus(bool),
54    WindowResized {
55        width: f32,
56        height: f32,
57    },
58    /// Synthesized command-surface events (e.g. from tests invoking
59    /// Command Palette directly).
60    CommandSurface {
61        surface_id: String,
62        action: String,
63        payload: Option<serde_json::Value>,
64    },
65}
66
67#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
68pub enum PointerButton {
69    Primary,
70    Secondary,
71    Middle,
72    Back,
73    Forward,
74    Other(u16),
75}
76
77#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
78pub struct ModifiersState {
79    pub alt: bool,
80    pub ctrl: bool,
81    pub shift: bool,
82    pub mac_cmd: bool,
83    pub command: bool,
84}
85
86#[cfg(test)]
87mod tests {
88    use super::*;
89
90    #[test]
91    fn modifiers_default_is_all_false() {
92        let m = ModifiersState::default();
93        assert!(!m.alt && !m.ctrl && !m.shift && !m.mac_cmd && !m.command);
94    }
95
96    #[test]
97    fn host_event_serde_round_trip() {
98        // Replay golden tests depend on the serde wire shape being
99        // stable across the runtime. Pin a representative sample.
100        let event = HostEvent::Key {
101            key: "Enter".to_string(),
102            pressed: true,
103            modifiers: ModifiersState {
104                ctrl: true,
105                ..ModifiersState::default()
106            },
107        };
108        let json = serde_json::to_string(&event).expect("serialize");
109        let decoded: HostEvent = serde_json::from_str(&json).expect("deserialize");
110        assert_eq!(decoded, event);
111    }
112
113    #[test]
114    fn command_surface_event_round_trips_with_payload() {
115        let payload = serde_json::json!({"arg": 42, "label": "submit"});
116        let event = HostEvent::CommandSurface {
117            surface_id: "command_palette".into(),
118            action: "invoke".into(),
119            payload: Some(payload.clone()),
120        };
121        let json = serde_json::to_string(&event).unwrap();
122        let decoded: HostEvent = serde_json::from_str(&json).unwrap();
123        assert_eq!(decoded, event);
124    }
125
126    #[test]
127    fn pointer_button_other_preserves_value() {
128        let b = PointerButton::Other(42);
129        let json = serde_json::to_string(&b).unwrap();
130        let back: PointerButton = serde_json::from_str(&json).unwrap();
131        assert_eq!(b, back);
132    }
133}