@desklink/host 0.5.9 → 0.5.10

package/engine/src/input_mac.rs

@@ -299,3 +299,436 @@ impl InputDevices {
         }
     }
 }
+
+/// Whether the engine may listen to the desktop's input. Listening needs Input
+/// Monitoring, a separate grant from the Accessibility one that posting needs.
+pub fn observe_probe() -> Result<(), InputUnavailable> {
+    if unsafe { crate::mac::CGPreflightListenEventAccess() } {
+        Ok(())
+    } else {
+        let app = crate::mac::tcc_responsible_app_name();
+        Err(InputUnavailable {
+            reason: format!("Input Monitoring permission has not been granted to {app}."),
+            remedy: format!("Allow {app} in System Settings › Privacy & Security › Input Monitoring, then reconnect."),
+        })
+    }
+}
+
+/// Shows the system's Input Monitoring prompt, once, and lists the app there.
+pub fn request_observe_access() -> bool {
+    unsafe { crate::mac::CGRequestListenEventAccess() }
+}
+
+#[cfg(desklink_vpx)]
+pub use observer::observe;
+
+#[cfg(desklink_vpx)]
+mod observer {
+    use super::*;
+    use crate::observe::{Observation, Sink, Tap, Unavailable};
+    use crate::protocol::{timestamp_us, ObservedInput, PointerPhase};
+    use std::sync::atomic::{AtomicBool, Ordering};
+    use std::sync::Arc;
+    use std::time::Instant;
+
+    type TapCallback = extern "C" fn(EventRef, u32, EventRef, *mut c_void) -> EventRef;
+
+    #[link(name = "ApplicationServices", kind = "framework")]
+    unsafe extern "C" {
+        fn CGEventTapCreate(tap: u32, place: u32, options: u32, events_of_interest: u64, callback: TapCallback, user_info: *mut c_void) -> CfTypeRef;
+        fn CGEventTapEnable(tap: CfTypeRef, enable: bool);
+        fn CGEventCreate(source: SourceRef) -> EventRef;
+        fn CGEventGetLocation(event: EventRef) -> Point;
+        fn CGEventGetFlags(event: EventRef) -> u64;
+        fn CGEventGetIntegerValueField(event: EventRef, field: u32) -> i64;
+        fn CGEventKeyboardGetUnicodeString(event: EventRef, max_length: usize, actual_length: *mut usize, buffer: *mut u16);
+    }
+
+    #[link(name = "CoreFoundation", kind = "framework")]
+    unsafe extern "C" {
+        fn CFMachPortCreateRunLoopSource(allocator: CfTypeRef, port: CfTypeRef, order: isize) -> CfTypeRef;
+        fn CFMachPortInvalidate(port: CfTypeRef);
+        fn CFRunLoopGetCurrent() -> CfTypeRef;
+        fn CFRunLoopAddSource(run_loop: CfTypeRef, source: CfTypeRef, mode: CfTypeRef);
+        fn CFRunLoopRunInMode(mode: CfTypeRef, seconds: f64, return_after_source: u8) -> i32;
+        static kCFRunLoopCommonModes: CfTypeRef;
+        static kCFRunLoopDefaultMode: CfTypeRef;
+    }
+
+    // CGEventType values this tap listens for.
+    const LEFT_DOWN: u32 = 1; const LEFT_UP: u32 = 2; const RIGHT_DOWN: u32 = 3; const RIGHT_UP: u32 = 4;
+    const MOVED: u32 = 5; const LEFT_DRAGGED: u32 = 6; const RIGHT_DRAGGED: u32 = 7; const KEY_DOWN: u32 = 10;
+    const KEY_UP: u32 = 11; const FLAGS_CHANGED: u32 = 12; const OTHER_DOWN: u32 = 25; const OTHER_UP: u32 = 26;
+    const OTHER_DRAGGED: u32 = 27;
+    // The system switches a tap off when its callback is slow or on its own
+    // say-so; these arrive in its place.
+    const DISABLED_BY_TIMEOUT: u32 = 0xFFFF_FFFE;
+    const DISABLED_BY_USER_INPUT: u32 = 0xFFFF_FFFF;
+
+    const BUTTON_NUMBER: u32 = 3;
+    const KEYCODE: u32 = 9;
+    const AUTOREPEAT: u32 = 8;
+
+    /// Where the selected display is on the desktop, so a point the system
+    /// reports (global, in points) becomes the source's own pixel.
+    #[derive(Debug, Clone, Copy, PartialEq)]
+    pub struct Geometry {
+        origin: (f64, f64),
+        points_per_pixel: (f64, f64),
+        pixels: (i64, i64),
+    }
+
+    impl Geometry {
+        pub fn new(origin: (f64, f64), points: (f64, f64), pixels: (i64, i64)) -> Self {
+            Self {
+                origin,
+                points_per_pixel: (points.0 / pixels.0 as f64, points.1 / pixels.1 as f64),
+                pixels,
+            }
+        }
+
+        /// `None` when the point is on another display.
+        pub fn to_source(&self, x: f64, y: f64) -> Option<(i64, i64)> {
+            let px = ((x - self.origin.0) / self.points_per_pixel.0).floor() as i64;
+            let py = ((y - self.origin.1) / self.points_per_pixel.1).floor() as i64;
+            ((0..self.pixels.0).contains(&px) && (0..self.pixels.1).contains(&py))
+                .then_some((px, py))
+        }
+    }
+
+    /// The control channel's pointer button numbers: 1 left, 2 middle, 3 right,
+    /// and 4 and up for the extra buttons.
+    pub fn observed_button(event_type: u32, button_number: i64) -> Option<(PointerPhase, i64)> {
+        let extra = |down| match button_number {
+            2 => Some((down, 2)),
+            n if n > 2 => Some((down, n + 1)),
+            _ => None,
+        };
+        match event_type {
+            LEFT_DOWN => Some((PointerPhase::Down, 1)),
+            LEFT_UP => Some((PointerPhase::Up, 1)),
+            RIGHT_DOWN => Some((PointerPhase::Down, 3)),
+            RIGHT_UP => Some((PointerPhase::Up, 3)),
+            OTHER_DOWN => extra(PointerPhase::Down),
+            OTHER_UP => extra(PointerPhase::Up),
+            _ => None,
+        }
+    }
+
+    struct Observer {
+        geometry: Geometry,
+        sink: Sink,
+        cursor: crate::cursor::Reporter,
+        last_inside: (i64, i64),
+        port: CfTypeRef,
+    }
+
+    impl Observer {
+        fn handle(&mut self, event_type: u32, event: EventRef) {
+            match event_type {
+                DISABLED_BY_TIMEOUT | DISABLED_BY_USER_INPUT => {
+                    log::warn!("the input event tap was switched off by the system; re-enabling it");
+                    unsafe { CGEventTapEnable(self.port, true) };
+                }
+                MOVED | LEFT_DRAGGED | RIGHT_DRAGGED | OTHER_DRAGGED => {
+                    let at = unsafe { CGEventGetLocation(event) };
+                    self.report_pointer(at);
+                }
+                LEFT_DOWN | LEFT_UP | RIGHT_DOWN | RIGHT_UP | OTHER_DOWN | OTHER_UP => {
+                    let number = unsafe { CGEventGetIntegerValueField(event, BUTTON_NUMBER) };
+                    let Some((phase, button)) = observed_button(event_type, number) else {
+                        return;
+                    };
+                    let at = unsafe { CGEventGetLocation(event) };
+                    // A click on another display is not on this source.
+                    let Some((x, y)) = self.geometry.to_source(at.x, at.y) else {
+                        return;
+                    };
+                    self.last_inside = (x, y);
+                    self.send(ObservedInput::Pointer { phase, x, y, button });
+                }
+                KEY_DOWN | KEY_UP | FLAGS_CHANGED => {
+                    let code = unsafe { CGEventGetIntegerValueField(event, KEYCODE) } as i16;
+                    let flags = unsafe { CGEventGetFlags(event) };
+                    let repeat = unsafe { CGEventGetIntegerValueField(event, AUTOREPEAT) } != 0;
+                    let text = if event_type == FLAGS_CHANGED {
+                        String::new()
+                    } else {
+                        let mut buffer = [0u16; 8];
+                        let mut length = 0usize;
+                        unsafe {
+                            CGEventKeyboardGetUnicodeString(
+                                event,
+                                buffer.len(),
+                                &mut length,
+                                buffer.as_mut_ptr(),
+                            )
+                        };
+                        String::from_utf16_lossy(&buffer[..length.min(buffer.len())])
+                    };
+                    if let Some(input) =
+                        crate::keymap::observed_key(event_type, code, flags, repeat, &text)
+                    {
+                        self.send(input);
+                    }
+                }
+                _ => {}
+            }
+        }
+
+        /// Reports where the pointer is now, whether or not it moves.
+        fn report_pointer(&mut self, at: Point) {
+            match self.geometry.to_source(at.x, at.y) {
+                Some(inside) => {
+                    self.last_inside = inside;
+                    self.cursor.update(inside.0 as i32, inside.1 as i32, true);
+                }
+                None => self.cursor.update(
+                    self.last_inside.0 as i32,
+                    self.last_inside.1 as i32,
+                    false,
+                ),
+            }
+        }
+
+        fn send(&self, input: ObservedInput) {
+            (self.sink)(Observation::Input {
+                timestamp_us: timestamp_us(Instant::now()),
+                input,
+            });
+        }
+    }
+
+    extern "C" fn tap_callback(
+        _proxy: EventRef,
+        event_type: u32,
+        event: EventRef,
+        user_info: *mut c_void,
+    ) -> EventRef {
+        // The run loop of the tap's own thread is the only caller.
+        let observer = unsafe { &mut *(user_info as *mut Observer) };
+        observer.handle(event_type, event);
+        event
+    }
+
+    /// The observer thread and the flag that ends it.
+    struct Running {
+        stop: Arc<AtomicBool>,
+        thread: Option<std::thread::JoinHandle<()>>,
+    }
+
+    impl Drop for Running {
+        fn drop(&mut self) {
+            self.stop.store(true, Ordering::Release);
+            if let Some(thread) = self.thread.take() {
+                let _ = thread.join();
+            }
+        }
+    }
+
+    fn unavailable(code: &'static str, reason: String, remedy: String) -> Unavailable {
+        Unavailable {
+            code,
+            reason,
+            remedy,
+        }
+    }
+
+    /// Listens to the pointer and keyboard of the display `display_id` with a
+    /// listen-only event tap: it sees events, it cannot change or block them.
+    pub fn observe(
+        display_id: u32,
+        pixels: (usize, usize),
+        sink: Sink,
+    ) -> Result<Tap, Unavailable> {
+        let app = crate::mac::tcc_responsible_app_name();
+        // Preflight never prompts; the owner grants with `setup-input` or by
+        // adding the app in System Settings.
+        if let Err(missing) = observe_probe() {
+            return Err(unavailable(
+                "missing-input-monitoring",
+                missing.reason,
+                missing.remedy,
+            ));
+        }
+        let (origin_x, origin_y, width, height) = crate::mac::display_geometry(display_id)
+            .ok_or_else(|| {
+                unavailable(
+                    "display-unavailable",
+                    String::from("the selected display is no longer active"),
+                    String::from("select an active display and reconnect"),
+                )
+            })?;
+        let geometry = Geometry::new(
+            (origin_x, origin_y),
+            (width, height),
+            (pixels.0 as i64, pixels.1 as i64),
+        );
+        let (started_tx, started_rx) = std::sync::mpsc::channel();
+        let stop = Arc::new(AtomicBool::new(false));
+        let stopped = stop.clone();
+        let thread = std::thread::Builder::new()
+            .name(String::from("input-observer"))
+            .spawn(move || {
+                let cursor_sink = sink.clone();
+                let observer = Box::into_raw(Box::new(Observer {
+                    geometry,
+                    sink,
+                    cursor: crate::cursor::Reporter::new(Box::new(move |position| {
+                        cursor_sink(Observation::Cursor(position))
+                    })),
+                    last_inside: (0, 0),
+                    port: std::ptr::null(),
+                }));
+                let mask: u64 = [
+                    LEFT_DOWN,
+                    LEFT_UP,
+                    RIGHT_DOWN,
+                    RIGHT_UP,
+                    MOVED,
+                    LEFT_DRAGGED,
+                    RIGHT_DRAGGED,
+                    KEY_DOWN,
+                    KEY_UP,
+                    FLAGS_CHANGED,
+                    OTHER_DOWN,
+                    OTHER_UP,
+                    OTHER_DRAGGED,
+                ]
+                .iter()
+                .fold(0u64, |mask, event| mask | (1u64 << *event));
+                // kCGSessionEventTap, kCGHeadInsertEventTap, kCGEventTapOptionListenOnly.
+                let port =
+                    unsafe { CGEventTapCreate(1, 0, 1, mask, tap_callback, observer.cast()) };
+                if port.is_null() {
+                    drop(unsafe { Box::from_raw(observer) });
+                    let _ = started_tx.send(Err(()));
+                    return;
+                }
+                unsafe { (*observer).port = port };
+                let source = unsafe { CFMachPortCreateRunLoopSource(std::ptr::null(), port, 0) };
+                let run_loop = unsafe { CFRunLoopGetCurrent() };
+                unsafe {
+                    CFRunLoopAddSource(run_loop, source, kCFRunLoopCommonModes);
+                    CGEventTapEnable(port, true);
+                    // Where the pointer already is, so a consumer does not wait for it to move.
+                    let here = CGEventCreate(std::ptr::null());
+                    if !here.is_null() {
+                        (*observer).report_pointer(CGEventGetLocation(here));
+                        CFRelease(here);
+                    }
+                }
+                let _ = started_tx.send(Ok(()));
+                // Polled rather than stopped from outside: stopping a run loop
+                // that has not started yet is lost, and Drop would wait forever.
+                while !stopped.load(Ordering::Acquire) {
+                    unsafe { CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0.1, 0) };
+                }
+                unsafe {
+                    CGEventTapEnable(port, false);
+                    CFMachPortInvalidate(port);
+                    CFRelease(source);
+                    CFRelease(port);
+                    drop(Box::from_raw(observer));
+                }
+            })
+            .map_err(|error| {
+                unavailable(
+                    "event-tap-failed",
+                    format!("could not start the input observer thread: {error}"),
+                    String::from("retry; if it persists, restart the engine"),
+                )
+            })?;
+        match started_rx.recv() {
+            Ok(Ok(())) => Ok(Tap {
+                mechanism: "cgeventtap",
+                guard: Box::new(Running {
+                    stop,
+                    thread: Some(thread),
+                }),
+            }),
+            _ => {
+                let _ = thread.join();
+                Err(unavailable(
+                    "event-tap-failed",
+                    format!("macOS refused to create the input event tap for {app}."),
+                    format!("Remove {app} from System Settings › Privacy & Security › Input Monitoring, add it again, then reconnect."),
+                ))
+            }
+        }
+    }
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+
+        // A 3420x2224 pixel panel shown as 1710x1112 points, with a second
+        // display to its right.
+        fn geometry() -> Geometry {
+            Geometry::new((0.0, 0.0), (1710.0, 1112.0), (3420, 2224))
+        }
+
+        #[test]
+        fn a_point_becomes_the_source_pixel_under_it() {
+            assert_eq!(geometry().to_source(100.5, 50.0), Some((201, 100)));
+            assert_eq!(geometry().to_source(0.0, 0.0), Some((0, 0)));
+            assert_eq!(geometry().to_source(1709.9, 1111.9), Some((3419, 2223)));
+        }
+
+        #[test]
+        fn a_point_on_another_display_is_not_on_this_source() {
+            assert_eq!(geometry().to_source(1710.0, 10.0), None);
+            assert_eq!(geometry().to_source(-1.0, 10.0), None);
+            assert_eq!(geometry().to_source(10.0, 1112.0), None);
+        }
+
+        #[test]
+        fn a_display_left_of_the_main_one_maps_from_its_own_origin() {
+            let left = Geometry::new((-1920.0, 0.0), (1920.0, 1080.0), (1920, 1080));
+            assert_eq!(left.to_source(-1920.0, 0.0), Some((0, 0)));
+            assert_eq!(left.to_source(-1.0, 1.0), Some((1919, 1)));
+            assert_eq!(left.to_source(0.0, 1.0), None);
+        }
+
+        #[test]
+        fn buttons_use_the_control_channels_numbers() {
+            assert_eq!(observed_button(LEFT_DOWN, 0), Some((PointerPhase::Down, 1)));
+            assert_eq!(observed_button(LEFT_UP, 0), Some((PointerPhase::Up, 1)));
+            assert_eq!(observed_button(RIGHT_DOWN, 1), Some((PointerPhase::Down, 3)));
+            assert_eq!(observed_button(RIGHT_UP, 1), Some((PointerPhase::Up, 3)));
+            assert_eq!(observed_button(OTHER_DOWN, 2), Some((PointerPhase::Down, 2)));
+            assert_eq!(observed_button(OTHER_UP, 3), Some((PointerPhase::Up, 4)));
+        }
+
+        #[test]
+        fn a_motion_or_a_key_is_not_a_button() {
+            assert_eq!(observed_button(MOVED, 0), None);
+            assert_eq!(observed_button(KEY_DOWN, 0), None);
+            assert_eq!(observed_button(OTHER_DOWN, 1), None);
+        }
+
+        #[test]
+        fn without_input_monitoring_the_tap_is_typed_unavailable_and_silent() {
+            // The CI and lab Macs this runs on have not granted Input Monitoring
+            // to the test binary; where one has, there is nothing to refuse.
+            if observe_probe().is_ok() {
+                return;
+            }
+            let delivered = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
+            let counted = delivered.clone();
+            let refused = observe(
+                1,
+                (1920, 1080),
+                std::sync::Arc::new(move |_| {
+                    counted.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                }),
+            );
+            let Err(refused) = refused else {
+                panic!("a tap was created without the grant");
+            };
+            assert_eq!(refused.code, "missing-input-monitoring");
+            assert!(refused.remedy.contains("Input Monitoring"));
+            assert_eq!(delivered.load(std::sync::atomic::Ordering::SeqCst), 0);
+        }
+    }
+}

package/engine/src/keymap_mac.rs

@@ -1,4 +1,6 @@
 use anyhow::Result;
+#[cfg(desklink_vpx)]
+use crate::protocol::ObservedInput;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Keystroke {
@@ -182,3 +184,258 @@ fn us_ansi_key(character: char) -> Option<(i16, bool)> {
         _ => return None,
     })
 }
+
+/// Event types of a CGEventTap that carry a key.
+#[cfg(desklink_vpx)]
+pub mod key_event {
+    pub const DOWN: u32 = 10;
+    pub const UP: u32 = 11;
+    pub const FLAGS_CHANGED: u32 = 12;
+}
+
+/// Generic modifier bits of a CGEvent's flags.
+#[cfg(desklink_vpx)]
+const SHIFT: u64 = 0x2_0000;
+#[cfg(desklink_vpx)]
+const CONTROL: u64 = 0x4_0000;
+#[cfg(desklink_vpx)]
+const ALT: u64 = 0x8_0000;
+#[cfg(desklink_vpx)]
+const META: u64 = 0x10_0000;
+
+/// A modifier key: its name, and the bit of the event flags that is set while
+/// this key (not just its twin on the other side) is held. Caps Lock and Fn have
+/// no per-side bit, so theirs is the generic one.
+#[cfg(desklink_vpx)]
+const MODIFIER_KEYS: [(i16, &str, u64); 10] = [
+    (59, "Control", 0x1), (62, "ControlRight", 0x2000), (56, "Shift", 0x2),
+    (60, "ShiftRight", 0x4), (58, "Alt", 0x20), (61, "AltRight", 0x40),
+    (55, "Meta", 0x8), (54, "MetaRight", 0x10), (57, "CapsLock", 0x1_0000),
+    (63, "Fn", 0x80_0000),
+];
+
+/// Keys that have a name rather than a character, following `KeyboardEvent.key`.
+/// Every name here that the control channel accepts maps to the same virtual key
+/// code through `named_key`.
+#[cfg(desklink_vpx)]
+const NAMED_KEYS: [(i16, &str); 36] = [
+    (36, "Enter"), (76, "Enter"), (48, "Tab"), (53, "Escape"),
+    (51, "Backspace"), (117, "Delete"), (126, "ArrowUp"), (125, "ArrowDown"),
+    (123, "ArrowLeft"), (124, "ArrowRight"), (115, "Home"), (119, "End"),
+    (116, "PageUp"), (121, "PageDown"), (122, "F1"), (120, "F2"),
+    (99, "F3"), (118, "F4"), (96, "F5"), (97, "F6"),
+    (98, "F7"), (100, "F8"), (101, "F9"), (109, "F10"),
+    (103, "F11"), (111, "F12"), (105, "F13"), (107, "F14"),
+    (113, "F15"), (106, "F16"), (64, "F17"), (79, "F18"),
+    (80, "F19"), (90, "F20"), (114, "Help"), (110, "ContextMenu"),
+];
+
+/// Names of the modifiers held in `flags`, in the order the control channel's
+/// own examples use.
+#[cfg(desklink_vpx)]
+pub fn modifier_names(flags: u64) -> Vec<String> {
+    [
+        (CONTROL, "Control"),
+        (ALT, "Alt"),
+        (SHIFT, "Shift"),
+        (META, "Meta"),
+    ]
+    .into_iter()
+    .filter(|(bit, _)| flags & bit != 0)
+    .map(|(_, name)| name.to_owned())
+    .collect()
+}
+
+/// The character a key makes on the US ANSI map this engine injects with. Only
+/// a fallback: a control chord, or an event the system gave no text, has none.
+#[cfg(desklink_vpx)]
+fn base_character(code: i16, shift: bool) -> Option<char> {
+    (' '..='~').find(|character| us_ansi_key(*character) == Some((code, shift)))
+}
+
+/// The single printable character a key produced on the layout in use.
+#[cfg(desklink_vpx)]
+fn printable(text: &str) -> Option<char> {
+    let mut characters = text.chars();
+    let character = characters.next()?;
+    // U+F700..U+F8FF is where AppKit puts the function and arrow keys.
+    (characters.next().is_none() && !character.is_control() && !('\u{f700}'..='\u{f8ff}').contains(&character))
+        .then_some(character)
+}
+
+/// What a CGEventTap key event means, in the control channel's `key` vocabulary.
+///
+/// `text` is what the event types on the active layout. Auto-repeat is not an
+/// event: a held key is one down and one up. A modifier arrives as a flags
+/// change, whose direction is its own bit being set.
+#[cfg(desklink_vpx)]
+pub fn observed_key(
+    event_type: u32,
+    code: i16,
+    flags: u64,
+    autorepeat: bool,
+    text: &str,
+) -> Option<ObservedInput> {
+    let modifiers = modifier_names(flags);
+    if event_type == key_event::FLAGS_CHANGED {
+        let (_, name, bit) = MODIFIER_KEYS.iter().find(|(key, _, _)| *key == code)?;
+        return Some(ObservedInput::Key {
+            name: Some((*name).to_owned()),
+            character: None,
+            down: flags & bit != 0,
+            modifiers,
+        });
+    }
+    let down = match event_type {
+        key_event::DOWN if autorepeat => return None,
+        key_event::DOWN => true,
+        key_event::UP => false,
+        _ => return None,
+    };
+    let named = NAMED_KEYS.iter().find(|(key, _)| *key == code);
+    let character = if named.is_some() {
+        None
+    } else {
+        printable(text).or_else(|| base_character(code, flags & SHIFT != 0))
+    };
+    let name = match (named, character) {
+        (Some((_, name)), _) => Some((*name).to_owned()),
+        (None, Some(_)) => None,
+        (None, None) => Some(String::from("Unidentified")),
+    };
+    Some(ObservedInput::Key {
+        name,
+        character: character.map(String::from),
+        down,
+        modifiers,
+    })
+}
+
+#[cfg(all(test, desklink_vpx))]
+mod tests {
+    use super::*;
+
+    fn key(
+        event_type: u32,
+        code: i16,
+        flags: u64,
+        autorepeat: bool,
+        text: &str,
+    ) -> Option<ObservedInput> {
+        observed_key(event_type, code, flags, autorepeat, text)
+    }
+
+    #[test]
+    fn a_letter_is_a_character_with_the_modifier_state_after_the_event() {
+        assert_eq!(
+            key(key_event::DOWN, 0, SHIFT, false, "A"),
+            Some(ObservedInput::Key {
+                name: None,
+                character: Some(String::from("A")),
+                down: true,
+                modifiers: vec![String::from("Shift")],
+            })
+        );
+    }
+
+    #[test]
+    fn a_named_key_carries_no_character() {
+        assert_eq!(
+            key(key_event::UP, 36, 0, false, "\r"),
+            Some(ObservedInput::Key {
+                name: Some(String::from("Enter")),
+                character: None,
+                down: false,
+                modifiers: Vec::new(),
+            })
+        );
+    }
+
+    #[test]
+    fn a_chord_with_no_text_falls_back_to_the_key_it_is() {
+        // Control-C types U+0003, which is not a character a keycap can show.
+        let Some(ObservedInput::Key {
+            character,
+            modifiers,
+            ..
+        }) = key(key_event::DOWN, 8, CONTROL, false, "\u{3}")
+        else {
+            panic!("a chord is a key");
+        };
+        assert_eq!(character.as_deref(), Some("c"));
+        assert_eq!(modifiers, vec![String::from("Control")]);
+    }
+
+    #[test]
+    fn an_event_with_no_text_is_still_the_shifted_character() {
+        let Some(ObservedInput::Key { character, .. }) =
+            key(key_event::DOWN, 4, SHIFT, false, "")
+        else {
+            panic!("a letter is a key");
+        };
+        assert_eq!(character.as_deref(), Some("H"));
+    }
+
+    #[test]
+    fn a_held_key_is_one_down_and_one_up() {
+        assert_eq!(key(key_event::DOWN, 0, 0, true, "a"), None);
+        assert!(key(key_event::UP, 0, 0, false, "a").is_some());
+    }
+
+    #[test]
+    fn releasing_one_shift_while_the_other_is_held_is_an_up() {
+        // Left shift went up; right shift (bit 0x4) and the generic bit remain.
+        let Some(ObservedInput::Key {
+            name,
+            down,
+            modifiers,
+            ..
+        }) = key(key_event::FLAGS_CHANGED, 56, SHIFT | 0x4, false, "")
+        else {
+            panic!("a modifier change is a key");
+        };
+        assert_eq!(name.as_deref(), Some("Shift"));
+        assert!(!down);
+        assert_eq!(modifiers, vec![String::from("Shift")]);
+        let Some(ObservedInput::Key { down, .. }) =
+            key(key_event::FLAGS_CHANGED, 56, SHIFT | 0x2 | 0x4, false, "")
+        else {
+            panic!("a modifier change is a key");
+        };
+        assert!(down);
+    }
+
+    #[test]
+    fn a_key_with_no_name_and_no_text_is_unidentified_not_empty() {
+        let Some(ObservedInput::Key {
+            name, character, ..
+        }) = key(key_event::DOWN, 127, 0, false, "")
+        else {
+            panic!("an unknown key is still a key");
+        };
+        assert_eq!(name.as_deref(), Some("Unidentified"));
+        assert_eq!(character, None);
+    }
+
+    #[test]
+    fn the_private_use_characters_appkit_gives_arrows_are_not_text() {
+        assert_eq!(printable("\u{f702}"), None);
+        assert_eq!(printable("é"), Some('é'));
+        assert_eq!(printable("ab"), None);
+    }
+
+    #[test]
+    fn what_is_observed_is_what_the_control_channel_would_inject() {
+        for (code, name) in NAMED_KEYS {
+            if let Some(stroke) = named_key(name) {
+                // Keypad Enter (76) shares its name with Return (36).
+                assert!(stroke.code == code || name == "Enter", "{name}");
+            }
+        }
+        for (code, name, _) in MODIFIER_KEYS {
+            if let Some(injected) = modifier_key(name) {
+                assert_eq!(injected, code, "{name}");
+            }
+        }
+    }
+}