Skip to main content

kernel/
host_event.rs

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