crcbl-shell 0.17.1

//! Win32 keyboard numbering → engine vocabulary, the two things `WM_CHAR` needs
//! done to it, and an input method's composition string.
//!
//! Everything here is pure — functions over integers, and one small set of
//! windows that needs no system call — for the reason
//! [`geometry`](super::geometry) gives at length: it is the part of the backend
//! that can be wrong in a way Windows would never complain about, so it is the
//! part that is unit-tested without Windows.
//!
//! # The scan code is in `lParam`, and the extended bit is part of it
//!
//! A `WM_KEYDOWN`'s `lParam` is a bit field, and this module reads three of its
//! fields:
//!
//! | Bits | Meaning |
//! | --- | --- |
//! | 16–23 | the **scan code**, as the keyboard sent it |
//! | 24 | the **extended** flag: the key's make code was prefixed with `E0` |
//! | 30 | the previous key state — `1` means the key was already down |
//!
//! Bit 24 is not decoration. PS/2 set 1 reuses one byte for two keys and tells
//! them apart with an `E0` prefix, so scan code `0x1C` is Enter *or* the
//! numeric keypad's Enter, `0x38` is left Alt *or* right Alt, and `0x47` is
//! Numpad 7 *or* Home. [`scancode`] folds the prefix back in as `0xE000`, which
//! is the numbering `MapVirtualKeyExW`'s `MAPVK_VK_TO_VSC_EX` also produces, and
//! [`key_code`] matches on the folded value. A backend that drops the bit binds
//! Home and Numpad 7 to the same action.
//!
//! # This is a different table from evdev, and the resemblance is the trap
//!
//! The two Linux backends share `linux::keymap`, because X11 keycodes really
//! are evdev codes plus eight. **Win32 scan codes are PS/2 set 1**, and the
//! tempting observation is that the main block *coincides*: evdev's numbering
//! was defined from set 1, so `KEY_A` is 30 and set 1's A is `0x1E`, which is
//! the same number.
//!
//! That coincidence is exactly what makes reusing the table a trap, because it
//! stops at `0x53`. Above it the two diverge completely — evdev continues flat
//! (`KEY_UP` is 103, `KEY_KPENTER` is 96), while set 1 leaves `0x60`–`0x6F`
//! unassigned and puts every one of those keys in an `E0`-prefixed second range
//! (`ArrowUp` is `0xE048`, `NumpadEnter` is `0xE01C`). A shared table would be
//! right for the letters and silently wrong for every arrow, navigation key,
//! right-hand modifier and keypad Enter. So this is a second table, written from
//! the set-1 assignment, and the tests below check the same two properties the
//! evdev one does: every [`KeyCode`] is reachable, and no two scan codes name
//! the same key.
//!
//! # Why the virtual key is carried as well
//!
//! [`KeyCode`] is a *position*, so it comes from the scan code and never from
//! the virtual key — `VK_A` is the key labelled A, which on AZERTY is a
//! different position. The virtual key is still needed for one thing:
//! [`crcbl_core::input::Keysym`], which is by definition layout-dependent. [`named_keysym`] answers
//! for the keys whose symbol does not depend on the layout, and everything it
//! returns `None` for is asked of `MapVirtualKeyW` — see
//! [`input`](super::input).

use crcbl_core::KeyCode;
use crcbl_core::input::Modifiers;

use super::ffi::value;

/// The bit in a key message's `lParam` that marks an `E0`-prefixed key.
const EXTENDED_BIT: isize = 1 << 24;
/// The bit that says the key was already down — an auto-repeat.
const PREVIOUS_STATE_BIT: isize = 1 << 30;
/// What [`scancode`] ORs into an extended key's code.
const EXTENDED_PREFIX: u32 = 0xE000;

/// The scan code a key message's `lParam` carries, with the `E0` prefix folded
/// back in.
///
/// See the [module docs](self): the extended bit is part of the key's identity,
/// not a flag beside it.
#[must_use]
pub const fn scancode(l_param: isize) -> u32 {
    let code = ((l_param >> 16) & 0xFF) as u32;
    if l_param & EXTENDED_BIT == 0 {
        code
    } else {
        EXTENDED_PREFIX | code
    }
}

/// Whether a key-**down** message says the key was already held.
///
/// Bit 30 is the previous key state, and it is meaningful only on the way down:
/// on a `WM_KEYUP` the key was of course down a moment ago, so the bit is always
/// set and reading it there would report every release as a repeat. The caller
/// is what knows which message this is, so the check is left there and stated
/// here.
#[must_use]
pub const fn was_already_down(l_param: isize) -> bool {
    l_param & PREVIOUS_STATE_BIT != 0
}

/// The engine key a PS/2 set 1 scan code names, layout-independently.
///
/// `None` for a key this engine has no name for — a laptop's brightness key, a
/// keyboard's media block. That is not data loss:
/// [`ShellEvent::Key`](crate::ShellEvent::Key) still carries the raw
/// [`Scancode`](crcbl_core::input::Scancode), so the key stays bindable and
/// round-trippable through a profile.
///
/// A `match` rather than a lookup table, for the reason the evdev table gives:
/// the extended codes are a second, sparse range and a table with a hole in it
/// invites an off-by-one a `match` cannot express.
#[must_use]
pub const fn key_code(scancode: u32) -> Option<KeyCode> {
    // PS/2 scan code set 1, in numeric order, with the extended block after it.
    Some(match scancode {
        0x0001 => KeyCode::Escape,
        0x0002 => KeyCode::Digit1,
        0x0003 => KeyCode::Digit2,
        0x0004 => KeyCode::Digit3,
        0x0005 => KeyCode::Digit4,
        0x0006 => KeyCode::Digit5,
        0x0007 => KeyCode::Digit6,
        0x0008 => KeyCode::Digit7,
        0x0009 => KeyCode::Digit8,
        0x000A => KeyCode::Digit9,
        0x000B => KeyCode::Digit0,
        0x000C => KeyCode::Minus,
        0x000D => KeyCode::Equal,
        0x000E => KeyCode::Backspace,
        0x000F => KeyCode::Tab,
        0x0010 => KeyCode::KeyQ,
        0x0011 => KeyCode::KeyW,
        0x0012 => KeyCode::KeyE,
        0x0013 => KeyCode::KeyR,
        0x0014 => KeyCode::KeyT,
        0x0015 => KeyCode::KeyY,
        0x0016 => KeyCode::KeyU,
        0x0017 => KeyCode::KeyI,
        0x0018 => KeyCode::KeyO,
        0x0019 => KeyCode::KeyP,
        0x001A => KeyCode::BracketLeft,
        0x001B => KeyCode::BracketRight,
        0x001C => KeyCode::Enter,
        0x001D => KeyCode::ControlLeft,
        0x001E => KeyCode::KeyA,
        0x001F => KeyCode::KeyS,
        0x0020 => KeyCode::KeyD,
        0x0021 => KeyCode::KeyF,
        0x0022 => KeyCode::KeyG,
        0x0023 => KeyCode::KeyH,
        0x0024 => KeyCode::KeyJ,
        0x0025 => KeyCode::KeyK,
        0x0026 => KeyCode::KeyL,
        0x0027 => KeyCode::Semicolon,
        0x0028 => KeyCode::Quote,
        0x0029 => KeyCode::Backquote,
        0x002A => KeyCode::ShiftLeft,
        0x002B => KeyCode::Backslash,
        0x002C => KeyCode::KeyZ,
        0x002D => KeyCode::KeyX,
        0x002E => KeyCode::KeyC,
        0x002F => KeyCode::KeyV,
        0x0030 => KeyCode::KeyB,
        0x0031 => KeyCode::KeyN,
        0x0032 => KeyCode::KeyM,
        0x0033 => KeyCode::Comma,
        0x0034 => KeyCode::Period,
        0x0035 => KeyCode::Slash,
        0x0036 => KeyCode::ShiftRight,
        0x0037 => KeyCode::NumpadMultiply,
        0x0038 => KeyCode::AltLeft,
        0x0039 => KeyCode::Space,
        0x003A => KeyCode::CapsLock,
        0x003B => KeyCode::F1,
        0x003C => KeyCode::F2,
        0x003D => KeyCode::F3,
        0x003E => KeyCode::F4,
        0x003F => KeyCode::F5,
        0x0040 => KeyCode::F6,
        0x0041 => KeyCode::F7,
        0x0042 => KeyCode::F8,
        0x0043 => KeyCode::F9,
        0x0044 => KeyCode::F10,
        // **Not** Num Lock. Pause's make code is the `E1`-prefixed sequence
        // `E1 1D 45`, which the keyboard driver reports as a bare `0x45`;
        // Num Lock is the *extended* `0xE045`, because MSDN's list of extended
        // keys names it. Swapping the two is the classic Win32 mistake here.
        0x0045 => KeyCode::Pause,
        0x0046 => KeyCode::ScrollLock,
        0x0047 => KeyCode::Numpad7,
        0x0048 => KeyCode::Numpad8,
        0x0049 => KeyCode::Numpad9,
        0x004A => KeyCode::NumpadSubtract,
        0x004B => KeyCode::Numpad4,
        0x004C => KeyCode::Numpad5,
        0x004D => KeyCode::Numpad6,
        0x004E => KeyCode::NumpadAdd,
        0x004F => KeyCode::Numpad1,
        0x0050 => KeyCode::Numpad2,
        0x0051 => KeyCode::Numpad3,
        0x0052 => KeyCode::Numpad0,
        0x0053 => KeyCode::NumpadDecimal,
        // SysRq: Alt+Print Screen reports this instead of `0xE037`, because the
        // Alt makes the keyboard send the unprefixed code. Both are the Print
        // Screen key and both map to it — the one place this table is not
        // injective, and the test below names it.
        0x0054 => KeyCode::PrintScreen,
        0x0056 => KeyCode::IntlBackslash,
        0x0057 => KeyCode::F11,
        0x0058 => KeyCode::F12,
        // The JIS keys. `0x0070` (Kana), `0x0079` (Henkan) and `0x007B`
        // (Muhenkan) are the neighbours this engine has no name for.
        0x0073 => KeyCode::IntlRo,
        0x007D => KeyCode::IntlYen,

        // The `E0`-prefixed block.
        0xE01C => KeyCode::NumpadEnter,
        0xE01D => KeyCode::ControlRight,
        0xE035 => KeyCode::NumpadDivide,
        0xE037 => KeyCode::PrintScreen,
        0xE038 => KeyCode::AltRight,
        0xE045 => KeyCode::NumLock,
        0xE047 => KeyCode::Home,
        0xE048 => KeyCode::ArrowUp,
        0xE049 => KeyCode::PageUp,
        0xE04B => KeyCode::ArrowLeft,
        0xE04D => KeyCode::ArrowRight,
        0xE04F => KeyCode::End,
        0xE050 => KeyCode::ArrowDown,
        0xE051 => KeyCode::PageDown,
        0xE052 => KeyCode::Insert,
        0xE053 => KeyCode::Delete,
        0xE05B => KeyCode::SuperLeft,
        0xE05C => KeyCode::SuperRight,
        0xE05D => KeyCode::ContextMenu,
        _ => return None,
    })
}

/// What `MAPVK_VK_TO_VSC_EX` answers for Pause: its `E1 1D 45` make code's
/// first two bytes, where a key message carries the bare `0x45`.
const PAUSE_E1: u32 = 0xE11D;
/// The scan code a key message carries for Pause; see [`key_code`].
const PAUSE: u32 = 0x0045;

/// Whether a virtual key names an `E0`-prefixed key that `MAPVK_VK_TO_VSC_EX`
/// answers **without** the prefix.
///
/// The navigation block and Num Lock share their scan code bytes with the
/// numeric keypad, and the mapping call answers the shared byte: `VK_UP` and
/// `VK_NUMPAD8` both come back as `0x48`, and `VK_HOME` and `VK_NUMPAD7` as
/// `0x47`, observed on Windows 11. The virtual key is what tells them apart,
/// so these are the keys whose prefix the caller puts back: `VK_PRIOR`
/// through `VK_DOWN`, `VK_INSERT`, `VK_DELETE` and `VK_NUMLOCK`.
const fn maps_without_its_prefix(virtual_key: u16) -> bool {
    matches!(virtual_key, 0x21..=0x28 | 0x2D | 0x2E) || virtual_key as usize == value::VK_NUM_LOCK
}

/// The scan code a key message should have carried, from what
/// `MAPVK_VK_TO_VSC_EX` answered for its virtual key, in [`scancode`]'s
/// numbering. The call answers `0` for a key the layout cannot place, which
/// this keeps a scan code no key is named by, prefixed or not.
///
/// `extended` is the message's own `E0` flag, which an injector that sets
/// `KEYEVENTF_EXTENDEDKEY` without a scan code still sends: it is the only
/// thing that makes the generic `VK_CONTROL` the right-hand Control.
#[must_use]
pub const fn recovered_scancode(virtual_key: u16, extended: bool, mapped: u32) -> u32 {
    if mapped == PAUSE_E1 {
        return PAUSE;
    }
    if extended || maps_without_its_prefix(virtual_key) {
        return EXTENDED_PREFIX | mapped;
    }
    mapped
}

/// The engine key for a key message, falling back to its virtual key when the
/// message carried no scan code at all.
///
/// Input injected by virtual key alone — `SendInput` with a zero `wScan`,
/// which is what SendKeys, remote desktop clients, on-screen keyboards and
/// AutoHotkey send — arrives with scan code `0`, or `0xE000` with the
/// extended flag, and [`key_code`] names no key for either. Only then is
/// `map` asked for the virtual key's scan code (`MAPVK_VK_TO_VSC_EX`, which
/// is a system call and so the caller's), and the answer goes through the
/// same table. A scan code that is real but unnamed is left `None`: the key
/// is still bindable by its scan code, and its virtual key is a layout's
/// guess, not a position.
///
/// The reported [`Scancode`](crcbl_core::input::Scancode) stays the one the
/// message carried, so a binding made from it matches the next identical
/// message rather than a scan code the keyboard never sent.
pub fn key_code_or_recovered(
    scancode: u32,
    virtual_key: u16,
    map: impl FnOnce(u16) -> u32,
) -> Option<KeyCode> {
    if let Some(key) = key_code(scancode) {
        return Some(key);
    }
    if scancode & !EXTENDED_PREFIX != 0 {
        return None;
    }
    let extended = scancode & EXTENDED_PREFIX != 0;
    key_code(recovered_scancode(virtual_key, extended, map(virtual_key)))
}

/// The keysym for a key whose symbol does not depend on the keyboard layout.
///
/// The table itself lives in [`crate::keysym`], shared with the AppKit
/// backend: it is a pure function of the engine's own [`KeyCode`] with no
/// platform in it, and two copies of one fact were exactly the drift the
/// codebase's rules warn about. Re-exported here so `keys::named_keysym` keeps
/// reading the same at every call site.
pub use crate::keysym::named_keysym;

/// Whether a virtual key is down, in a `GetKeyboardState` snapshot.
///
/// The high bit is the held state and the low bit is the *toggle* state, which
/// is the distinction Caps Lock depends on: a Caps Lock that is on but not
/// physically held has bit 0 set and bit 7 clear.
const fn is_down(keys: &[u8; 256], key: usize) -> bool {
    keys[key] & 0x80 != 0
}

/// Whether a virtual key is latched on. See [`is_down`].
const fn is_toggled(keys: &[u8; 256], key: usize) -> bool {
    keys[key] & 0x01 != 0
}

/// The modifiers a `GetKeyboardState` snapshot describes.
///
/// # AltGr is a Control that was never pressed
///
/// On every layout that has an AltGr — which is most of Europe — Windows
/// synthesizes a **left Control down** alongside the right Alt, because that is
/// how the original IBM AltGr was encoded. Reported literally, a French user
/// typing `€` (AltGr+E) sends `Ctrl+Alt+E`, and every `Ctrl+E` shortcut in the
/// application fires while they are writing a price.
///
/// So the pair is recognized and unpicked: right Alt held **together with** left
/// Control is AltGr, which sets [`ALT_GR`](Modifiers::ALT_GR) and contributes
/// neither [`CTRL`](Modifiers::CTRL) nor [`ALT`](Modifiers::ALT). The test is
/// the pair rather than right-Alt alone because on a US layout right Alt really
/// is a plain Alt and sends no Control with it — and a US user's `RAlt+E` must
/// still be `Alt+E`.
///
/// Real `Ctrl+AltGr+E` — left Control genuinely held while AltGr is pressed — is
/// indistinguishable from AltGr alone at this layer, on Windows, by
/// construction. Every toolkit has this limitation and none of them can fix it;
/// it is recorded here rather than discovered.
///
/// # An unsided key counts where no sided one is down
///
/// Windows sets the unsided `VK_CONTROL`, `VK_MENU` and `VK_SHIFT` alongside
/// whichever sided key is down, and a key injected by the unsided virtual key
/// with no scan code — what some automation tools and remote-input stacks send
/// — can set the unsided one alone, and reading only the sided keys turned
/// that `Ctrl+V` into a plain `v`. So the unsided key adds its modifier as a
/// left key would — except where the sided key that would decide is already down: an
/// unsided Control beside a left Control is that Control, AltGr's synthesized
/// one included, and an unsided Alt beside a right Alt is that Alt, which may
/// be AltGr's. It never makes AltGr: that pair is Windows' sided synthesis,
/// and an injected Control beside a US right Alt is still `Ctrl+Alt`.
#[must_use]
pub fn modifiers(keys: &[u8; 256]) -> Modifiers {
    let left_control = is_down(keys, value::VK_L_CONTROL);
    let right_control = is_down(keys, value::VK_R_CONTROL);
    let left_alt = is_down(keys, value::VK_L_MENU);
    let right_alt = is_down(keys, value::VK_R_MENU);
    let alt_gr = right_alt && left_control;
    let unsided_control = is_down(keys, value::VK_CONTROL) && !left_control;
    let unsided_alt = is_down(keys, value::VK_MENU) && !right_alt;

    let mut modifiers = Modifiers::empty();
    modifiers.set(
        Modifiers::SHIFT,
        is_down(keys, value::VK_L_SHIFT)
            || is_down(keys, value::VK_R_SHIFT)
            || is_down(keys, value::VK_SHIFT),
    );
    modifiers.set(
        Modifiers::CTRL,
        right_control || unsided_control || (left_control && !alt_gr),
    );
    modifiers.set(
        Modifiers::ALT,
        left_alt || unsided_alt || (right_alt && !alt_gr),
    );
    modifiers.set(
        Modifiers::SUPER,
        is_down(keys, value::VK_L_WIN) || is_down(keys, value::VK_R_WIN),
    );
    modifiers.set(Modifiers::ALT_GR, alt_gr);
    modifiers.set(Modifiers::CAPS_LOCK, is_toggled(keys, value::VK_CAPITAL));
    modifiers.set(Modifiers::NUM_LOCK, is_toggled(keys, value::VK_NUM_LOCK));
    modifiers
}

/// Reassembles the UTF-16 code units `WM_CHAR` delivers one at a time.
///
/// # Why this is a state machine and not a cast
///
/// `WM_CHAR`'s `wParam` is a UTF-16 **code unit**, not a character. A codepoint
/// above the BMP — an emoji, a rare CJK ideograph, anything a modern IME can
/// commit — arrives as *two* messages carrying a surrogate pair, and casting
/// either half on its own produces nothing valid: `char::from_u32` rejects the
/// surrogate range outright, so a backend that ignores this silently drops every
/// astral character rather than mangling it.
///
/// The pair is held across exactly one message. A high surrogate followed by
/// something that is not a low surrogate is a malformed stream — dropped, and
/// the new unit is then interpreted on its own, so one bad message costs one
/// character rather than desynchronising everything after it.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct Utf16 {
    /// The high half of a surrogate pair, waiting for its low half.
    pending: Option<u16>,
}

/// The first UTF-16 high surrogate.
const HIGH_SURROGATE_START: u16 = 0xD800;
/// The first UTF-16 low surrogate, which is also one past the last high one.
const LOW_SURROGATE_START: u16 = 0xDC00;
/// One past the last UTF-16 surrogate.
const SURROGATE_END: u16 = 0xE000;
/// The first codepoint outside the BMP, which is what a pair encodes.
const ASTRAL_START: u32 = 0x1_0000;

impl Utf16 {
    /// Feeds one code unit, and yields a character when one is complete.
    ///
    /// Control characters are **not** filtered here — see [`is_text`], which is
    /// the separate question of whether a complete character is worth
    /// committing.
    pub fn push(&mut self, unit: u16) -> Option<char> {
        let high = self.pending.take();
        if let Some(high) = high
            && (LOW_SURROGATE_START..SURROGATE_END).contains(&unit)
        {
            let codepoint = ASTRAL_START
                + (((high - HIGH_SURROGATE_START) as u32) << 10)
                + (unit - LOW_SURROGATE_START) as u32;
            return char::from_u32(codepoint);
        }
        if (HIGH_SURROGATE_START..LOW_SURROGATE_START).contains(&unit) {
            self.pending = Some(unit);
            return None;
        }
        char::from_u32(unit as u32)
    }
}

/// Whether a committed character is text rather than a control code.
///
/// `WM_CHAR` is the system's translation of a key press, so it delivers `\u{8}`
/// for Backspace, `\r` for Enter and `\u{1b}` for Escape — every one of which
/// would be inserted verbatim by a text field that trusted the stream.
/// [`ShellEvent::TextCommit`](crate::ShellEvent::TextCommit) means *text*, and
/// this is the same filter the two Linux backends apply to what XKB hands them,
/// so the three agree about what typing Enter commits: nothing.
#[must_use]
pub fn is_text(character: char) -> bool {
    !character.is_control()
}

/// A `WM_IME_SETCONTEXT`'s `lParam` with the input method's own composition
/// window turned off, and its candidate windows left as they were.
///
/// The field draws the pre-edit itself, from
/// [`TextPreedit`](crate::ShellEvent::TextPreedit), so the system's window
/// would show the reading a second time beside it; the candidate list has no
/// counterpart in the field and stays.
#[must_use]
pub const fn without_composition_window(l_param: isize) -> isize {
    // The `ISC_*` flags are a `DWORD` in the low half, zero-extended here.
    l_param & !(value::ISC_SHOW_UI_COMPOSITION_WINDOW as isize)
}

/// Whether a `WM_IME_COMPOSITION`'s `lParam` says the composition string
/// changed, which is what makes it a pre-edit.
///
/// The message also arrives for a result alone (`GCS_RESULTSTR`), which is the
/// commit, never a pre-edit; see [`composition_committed`].
#[must_use]
pub const fn composition_changed(l_param: isize) -> bool {
    // The `GCS_*` flags are a `DWORD` in the low half; truncating is the read.
    (l_param as u32) & value::GCS_COMP_STR != 0
}

/// Whether a `WM_IME_COMPOSITION`'s `lParam` carries a result, which is the
/// commit. One message can carry both a result and a new composition, when the
/// input method commits part of what was typed and keeps composing the rest.
#[must_use]
pub const fn composition_committed(l_param: isize) -> bool {
    (l_param as u32) & value::GCS_RESULT_STR != 0
}

/// The keys an input method consumed, so neither edge of one is reported.
///
/// A key the input method takes while composing reaches the window as a
/// `WM_KEYDOWN` whose virtual key is `VK_PROCESSKEY` rather than the key's own,
/// and [`ShellEvent::Key`](crate::ShellEvent::Key) promises that such a key is
/// not reported: a Backspace that deletes a kana from the composition must not
/// also delete a character from the field. The *release* is the awkward half —
/// Windows sends it with the real virtual key as often as with
/// `VK_PROCESSKEY` — so the press's scan code is remembered and the release is
/// matched by that instead.
#[derive(Debug, Default)]
pub struct Consumed {
    scancodes: Vec<u32>,
}

impl Consumed {
    /// Records one key message, answering whether the consumer is owed it as a
    /// [`ShellEvent::Key`](crate::ShellEvent::Key).
    ///
    /// A press the input method consumed is not, and neither is the release of
    /// a key whose press was consumed, whatever virtual key the release
    /// carries. A press it did *not* consume — a repeat after the composition
    /// ended — is reported, and so is its release, so the consumer never sees
    /// a key go down that does not come back up.
    pub fn report(&mut self, virtual_key: u16, scancode: u32, pressed: bool) -> bool {
        let known = self.scancodes.iter().position(|&code| code == scancode);
        if pressed && virtual_key == value::VK_PROCESS_KEY {
            if known.is_none() {
                self.scancodes.push(scancode);
            }
            return false;
        }
        let Some(known) = known else { return true };
        self.scancodes.swap_remove(known);
        pressed
    }

    /// Forgets every consumed key: the keyboard went elsewhere, and a release
    /// that arrives after it came back belongs to a press nobody here saw.
    pub fn clear(&mut self) {
        self.scancodes.clear();
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn only_a_changed_composition_string_is_a_pre_edit() {
        /// `GCS_COMPATTR`: the clause attributes, sent alongside the string.
        const GCS_COMP_ATTR: isize = 0x0010;
        let comp_str = value::GCS_COMP_STR as isize;
        let result_str = value::GCS_RESULT_STR as isize;
        assert!(composition_changed(comp_str));
        assert!(composition_changed(comp_str | GCS_COMP_ATTR));
        assert!(composition_changed(comp_str | result_str));
        assert!(!composition_changed(result_str));
        assert!(!composition_changed(0));
    }

    #[test]
    fn only_a_result_is_a_commit() {
        let comp_str = value::GCS_COMP_STR as isize;
        let result_str = value::GCS_RESULT_STR as isize;
        assert!(composition_committed(result_str));
        assert!(
            composition_committed(result_str | comp_str),
            "a partial commit carries the rest of the composition too"
        );
        assert!(!composition_committed(comp_str));
        assert!(!composition_committed(0));
    }

    #[test]
    fn the_input_methods_composition_window_is_turned_off_and_nothing_else() {
        /// `ISC_SHOWUICANDIDATEWINDOW`, one per candidate list, in the low bits.
        const ISC_SHOW_UI_CANDIDATE_WINDOWS: isize = 0x0000_000F;
        /// `ISC_SHOWUIGUIDELINE`.
        const ISC_SHOW_UI_GUIDELINE: isize = 0x4000_0000;
        let composition = value::ISC_SHOW_UI_COMPOSITION_WINDOW as isize;
        // `ISC_SHOWUIALL`, what a window gaining the context is usually sent.
        let all = composition | ISC_SHOW_UI_GUIDELINE | ISC_SHOW_UI_CANDIDATE_WINDOWS;
        assert_eq!(
            without_composition_window(all),
            ISC_SHOW_UI_GUIDELINE | ISC_SHOW_UI_CANDIDATE_WINDOWS,
            "the composition window goes, the guideline and candidates stay"
        );
        assert_eq!(without_composition_window(composition), 0);
        assert_eq!(
            without_composition_window(ISC_SHOW_UI_CANDIDATE_WINDOWS),
            ISC_SHOW_UI_CANDIDATE_WINDOWS,
            "a context with no composition window is left alone"
        );
    }

    #[test]
    fn a_message_with_no_scan_code_takes_its_key_from_the_virtual_key() {
        // What `MAPVK_VK_TO_VSC_EX` answered for each virtual key on
        // Windows 11 with a US layout, recorded so the fix-ups are tested
        // against the call's real quirks rather than against its docs.
        const ANSWERS: [(u16, u32); 12] = [
            (0x41, 0x001E), // VK_A
            (0x1B, 0x0001), // VK_ESCAPE
            (0x26, 0x0048), // VK_UP: the keypad's byte, unprefixed
            (0x24, 0x0047), // VK_HOME
            (0x67, 0x0047), // VK_NUMPAD7: the same answer, rightly
            (0x2E, 0x0053), // VK_DELETE
            (0x90, 0x0045), // VK_NUMLOCK
            (0x13, 0xE11D), // VK_PAUSE: E1-prefixed
            (0xA3, 0xE01D), // VK_RCONTROL: the one side it does prefix
            (0x11, 0x001D), // VK_CONTROL: generic, so the left one
            (0x2C, 0x0054), // VK_SNAPSHOT
            (0xE5, 0x0000), // VK_PROCESSKEY: no key at all
        ];
        let map = |virtual_key: u16| {
            ANSWERS
                .iter()
                .find(|(key, _)| *key == virtual_key)
                .map_or(0, |(_, mapped)| *mapped)
        };
        let recover = |extended: bool, virtual_key| {
            let scancode = if extended { EXTENDED_PREFIX } else { 0 };
            key_code_or_recovered(scancode, virtual_key, map)
        };
        assert_eq!(recover(false, 0x41), Some(KeyCode::KeyA));
        assert_eq!(recover(false, 0x1B), Some(KeyCode::Escape));
        assert_eq!(recover(false, 0x26), Some(KeyCode::ArrowUp), "not Numpad8");
        assert_eq!(recover(false, 0x24), Some(KeyCode::Home), "not Numpad7");
        assert_eq!(recover(false, 0x67), Some(KeyCode::Numpad7));
        assert_eq!(recover(false, 0x2E), Some(KeyCode::Delete));
        assert_eq!(recover(false, 0x90), Some(KeyCode::NumLock), "not Pause");
        assert_eq!(recover(false, 0x13), Some(KeyCode::Pause));
        assert_eq!(recover(false, 0xA3), Some(KeyCode::ControlRight));
        assert_eq!(recover(false, 0x11), Some(KeyCode::ControlLeft));
        // The message's own extended flag is what makes the generic Control
        // the right-hand one, and an answer that already has the prefix keeps
        // it.
        assert_eq!(recover(true, 0x11), Some(KeyCode::ControlRight));
        assert_eq!(recover(true, 0xA3), Some(KeyCode::ControlRight));
        assert_eq!(recover(true, 0x26), Some(KeyCode::ArrowUp));
        assert_eq!(recover(false, 0x2C), Some(KeyCode::PrintScreen));
        // A virtual key the layout cannot place is still no key.
        assert_eq!(recover(false, 0xE5), None);
        assert_eq!(recover(true, 0xE5), None);

        // A message that carried a scan code is answered by it alone: a named
        // one wins over its virtual key, and an unnamed one stays unnamed.
        let untouched = |_| panic!("the virtual key is not asked about");
        assert_eq!(
            key_code_or_recovered(0x0011, 0x41, untouched),
            Some(KeyCode::KeyW),
            "the position, not the layout's label"
        );
        assert_eq!(key_code_or_recovered(0x0059, 0x41, untouched), None);
        assert_eq!(key_code_or_recovered(0xE022, 0x41, untouched), None);
    }

    #[test]
    fn a_key_the_input_method_consumed_is_reported_on_neither_edge() {
        /// `VK_BACK`.
        const VK_BACK: u16 = 0x08;
        /// `VK_RETURN`.
        const VK_RETURN: u16 = 0x0D;
        /// `VK_W`.
        const VK_W: u16 = 0x57;
        /// `VK_A`.
        const VK_A: u16 = 0x41;
        let process = value::VK_PROCESS_KEY;
        let mut consumed = Consumed::default();

        // Backspace inside a composition: the press says VK_PROCESSKEY and
        // the release names the real key. Neither is the consumer's.
        assert!(!consumed.report(process, 0x000E, true));
        assert!(!consumed.report(process, 0x000E, true), "nor its repeat");
        assert!(!consumed.report(VK_BACK, 0x000E, false));
        // Matched once: the next Backspace, outside a composition, is a key.
        assert!(consumed.report(VK_BACK, 0x000E, true));
        assert!(consumed.report(VK_BACK, 0x000E, false));

        // Enter committing the conversion, released as VK_PROCESSKEY too.
        assert!(!consumed.report(process, 0x001C, true));
        assert!(!consumed.report(process, 0x001C, false));
        assert!(consumed.report(VK_RETURN, 0x001C, false), "already matched");

        // A key the input method stopped taking mid-hold comes back as a key,
        // and so does its release.
        assert!(!consumed.report(process, 0x0011, true));
        assert!(consumed.report(VK_W, 0x0011, true));
        assert!(consumed.report(VK_W, 0x0011, false));

        // A release with VK_PROCESSKEY whose press was reported is still a key:
        // the consumer saw it go down.
        assert!(consumed.report(VK_W, 0x0011, true));
        assert!(consumed.report(process, 0x0011, false));

        // A focus loss forgets the consumed press, so a later release of the
        // same key — pressed elsewhere — is reported rather than eaten.
        assert!(!consumed.report(process, 0x001E, true));
        consumed.clear();
        assert!(consumed.report(VK_A, 0x001E, false));
    }

    /// A key message's `lParam` for a scan code, with the flags spelled out.
    const fn l_param(code: isize, extended: bool, previous: bool) -> isize {
        let mut packed = code << 16;
        if extended {
            packed |= EXTENDED_BIT;
        }
        if previous {
            packed |= PREVIOUS_STATE_BIT;
        }
        // Bits 0-15 are the repeat count, which this backend does not read;
        // a non-zero one here proves that.
        packed | 1
    }

    /// A `GetKeyboardState` snapshot with these virtual keys held.
    fn held(keys: &[usize]) -> [u8; 256] {
        let mut state = [0u8; 256];
        for key in keys {
            state[*key] = 0x80;
        }
        state
    }

    #[test]
    fn the_extended_bit_is_folded_into_the_scan_code_rather_than_dropped() {
        // The whole reason this module reads bit 24: set 1 gives Enter and the
        // keypad's Enter the same byte, and the prefix is the only difference.
        assert_eq!(scancode(l_param(0x1C, false, false)), 0x001C);
        assert_eq!(scancode(l_param(0x1C, true, false)), 0xE01C);
        assert_eq!(key_code(0x001C), Some(KeyCode::Enter));
        assert_eq!(key_code(0xE01C), Some(KeyCode::NumpadEnter));

        // And the three other pairs a dropped bit would collapse.
        assert_eq!(key_code(0x001D), Some(KeyCode::ControlLeft));
        assert_eq!(key_code(0xE01D), Some(KeyCode::ControlRight));
        assert_eq!(key_code(0x0038), Some(KeyCode::AltLeft));
        assert_eq!(key_code(0xE038), Some(KeyCode::AltRight));
        assert_eq!(key_code(0x0047), Some(KeyCode::Numpad7));
        assert_eq!(key_code(0xE047), Some(KeyCode::Home));

        // The high byte of the scan-code field is masked off: `lParam` carries
        // a repeat count below it and context bits above it.
        assert_eq!(scancode(l_param(0x39, false, true)), 0x0039);
        assert_eq!(scancode(-1), 0xE0FF, "every bit set is still one byte");
    }

    #[test]
    fn pause_is_the_bare_forty_five_and_num_lock_is_the_extended_one() {
        // Backwards in a lot of published tables, and the failure is silent:
        // a game binds Pause and the player's Num Lock triggers it.
        assert_eq!(key_code(0x0045), Some(KeyCode::Pause));
        assert_eq!(key_code(0xE045), Some(KeyCode::NumLock));
    }

    #[test]
    fn the_previous_state_bit_is_what_marks_an_auto_repeat() {
        // Held keys repeat at the system rate; a jump button that forwards them
        // fires thirty times a second.
        assert!(!was_already_down(l_param(0x11, false, false)));
        assert!(was_already_down(l_param(0x11, false, true)));
    }

    #[test]
    fn wasd_and_the_gameplay_keys_map_to_their_set_one_codes() {
        // These are the numbers a `WM_KEYDOWN` actually carries, and they are
        // *not* the evdev ones — which is the whole reason this table is not
        // `linux::keymap`.
        assert_eq!(key_code(0x0011), Some(KeyCode::KeyW));
        assert_eq!(key_code(0x001E), Some(KeyCode::KeyA));
        assert_eq!(key_code(0x001F), Some(KeyCode::KeyS));
        assert_eq!(key_code(0x0020), Some(KeyCode::KeyD));
        assert_eq!(key_code(0x0039), Some(KeyCode::Space));
        assert_eq!(key_code(0x0001), Some(KeyCode::Escape));
        assert_eq!(key_code(0xE05B), Some(KeyCode::SuperLeft));
    }

    /// Where this table and the evdev one agree, and where they stop.
    ///
    /// Linux-only because [`linux::keymap`](crate::linux::keymap) is compiled
    /// there and only there — which is the whole point: the resemblance below
    /// `0x54` is what makes sharing one table tempting, and the divergence above
    /// it is what makes sharing wrong. Neither half is visible from one side.
    #[cfg(target_os = "linux")]
    #[test]
    fn the_two_numberings_coincide_for_the_letters_and_for_nothing_above_them() {
        assert_eq!(crate::linux::keymap::key_code(17), Some(KeyCode::KeyW));
        assert_eq!(key_code(17), Some(KeyCode::KeyW), "0x11 is W in both");
        assert_eq!(crate::linux::keymap::key_code(30), Some(KeyCode::KeyA));
        assert_eq!(key_code(30), Some(KeyCode::KeyA), "0x1E is A in both");

        assert_eq!(
            crate::linux::keymap::key_code(103),
            Some(KeyCode::ArrowUp),
            "evdev continues flat"
        );
        assert_eq!(key_code(103), None, "set 1 assigns nothing at 0x67");
        assert_eq!(key_code(0xE048), Some(KeyCode::ArrowUp), "it is prefixed");
        assert_eq!(
            crate::linux::keymap::key_code(96),
            Some(KeyCode::NumpadEnter)
        );
        assert_eq!(key_code(96), None);
        assert_eq!(key_code(0xE01C), Some(KeyCode::NumpadEnter));
    }

    /// Every scan code a `WM_KEYDOWN` can carry: one byte, and one byte with
    /// the `E0` prefix folded in.
    fn all_scancodes() -> impl Iterator<Item = u32> {
        (0..=0xFFu32).chain((0..=0xFFu32).map(|code| EXTENDED_PREFIX | code))
    }

    #[test]
    fn every_named_key_is_reachable_from_some_scan_code() {
        // A key in the vocabulary that no scan code produces is a key nobody
        // can bind on Windows — invisible in every other way.
        let reachable: Vec<KeyCode> = all_scancodes().filter_map(key_code).collect();
        let mut missing: Vec<&'static str> = Vec::new();
        for key in KeyCode::ALL {
            if !reachable.contains(key) {
                missing.push(key.as_str());
            }
        }
        assert!(missing.is_empty(), "unreachable KeyCodes: {missing:?}");
    }

    #[test]
    fn print_screen_is_the_only_key_two_scan_codes_name() {
        // The other direction: a duplicated arm silently shadows, and the
        // shadowed key simply never fires. Print Screen is the one real
        // duplicate — Alt+Print Screen sends the unprefixed `0x54` — so it is
        // named here rather than allowed by a loose assertion.
        let mut seen: Vec<KeyCode> = all_scancodes().filter_map(key_code).collect();
        let count = seen.len();
        seen.sort_unstable();
        seen.dedup();
        assert_eq!(
            count - seen.len(),
            1,
            "exactly one scan code pair may share a KeyCode"
        );
        assert_eq!(
            seen.len(),
            KeyCode::ALL.len(),
            "the table is the vocabulary"
        );
        assert_eq!(key_code(0x0054), Some(KeyCode::PrintScreen));
        assert_eq!(key_code(0xE037), Some(KeyCode::PrintScreen));
    }

    #[test]
    fn unnamed_keys_degrade_to_none_rather_than_to_a_wrong_key() {
        // Holes in set 1, the JIS neighbours this engine does not name, and the
        // extended codes the media block uses.
        for code in [
            0x0000, 0x0055, 0x0059, 0x0070, 0x0079, 0xE010, 0xE022, 0xE06F,
        ] {
            assert_eq!(key_code(code), None, "scan code {code:#06x}");
        }
    }

    #[test]
    fn alt_gr_is_reported_as_itself_and_not_as_control_plus_alt() {
        // The bug this exists to not have: a French user typing € would
        // otherwise fire every Ctrl+E shortcut in the application.
        let alt_gr = modifiers(&held(&[value::VK_R_MENU, value::VK_L_CONTROL]));
        assert!(alt_gr.contains(Modifiers::ALT_GR));
        assert!(!alt_gr.contains(Modifiers::CTRL), "{alt_gr:?}");
        assert!(!alt_gr.contains(Modifiers::ALT), "{alt_gr:?}");
        assert_eq!(alt_gr.chord(), Modifiers::empty());

        // A US keyboard's right Alt sends no Control with it, so it stays Alt.
        let plain = modifiers(&held(&[value::VK_R_MENU]));
        assert_eq!(plain, Modifiers::ALT);
        // And a real Ctrl+Alt — left Alt, not AltGr — is untouched.
        let real = modifiers(&held(&[value::VK_L_CONTROL, value::VK_L_MENU]));
        assert_eq!(real, Modifiers::CTRL | Modifiers::ALT);
        // Right Control with AltGr is still a Control: it is not the key
        // Windows synthesizes.
        let both = modifiers(&held(&[
            value::VK_R_MENU,
            value::VK_L_CONTROL,
            value::VK_R_CONTROL,
        ]));
        assert!(both.contains(Modifiers::ALT_GR | Modifiers::CTRL));
    }

    #[test]
    fn an_unsided_modifier_counts_where_no_sided_one_is_down() {
        // The bug this exists to not have: Ctrl injected as the unsided
        // `VK_CONTROL` made Ctrl+V a plain v.
        assert_eq!(modifiers(&held(&[value::VK_CONTROL])), Modifiers::CTRL);
        assert_eq!(modifiers(&held(&[value::VK_MENU])), Modifiers::ALT);
        assert_eq!(modifiers(&held(&[value::VK_SHIFT])), Modifiers::SHIFT);
        // Beside a sided key, as Windows reports a real keyboard's, it adds
        // nothing.
        let right = modifiers(&held(&[value::VK_CONTROL, value::VK_R_CONTROL]));
        assert_eq!(right, Modifiers::CTRL);
        let left = modifiers(&held(&[value::VK_CONTROL, value::VK_L_CONTROL]));
        assert_eq!(left, Modifiers::CTRL);

        // AltGr as Windows reports it, the unsided bits set with the sided
        // ones: still AltGr alone, neither a Control nor an Alt.
        let alt_gr = modifiers(&held(&[
            value::VK_L_CONTROL,
            value::VK_R_MENU,
            value::VK_CONTROL,
            value::VK_MENU,
        ]));
        assert_eq!(alt_gr, Modifiers::ALT_GR);
        // An injected Control beside a US right Alt is not AltGr's
        // synthesized one.
        let injected = modifiers(&held(&[value::VK_CONTROL, value::VK_R_MENU]));
        assert_eq!(injected, Modifiers::CTRL | Modifiers::ALT);
    }

    #[test]
    fn shift_and_super_come_from_either_side_and_the_locks_from_the_toggle_bit() {
        assert_eq!(modifiers(&held(&[value::VK_L_SHIFT])), Modifiers::SHIFT);
        assert_eq!(modifiers(&held(&[value::VK_R_SHIFT])), Modifiers::SHIFT);
        assert_eq!(modifiers(&held(&[value::VK_L_WIN])), Modifiers::SUPER);
        assert_eq!(modifiers(&held(&[value::VK_R_WIN])), Modifiers::SUPER);
        assert_eq!(modifiers(&[0u8; 256]), Modifiers::empty());

        // Caps Lock latched on is bit 0, not bit 7 — a Caps Lock that is *on*
        // is not a Caps Lock that is held, and reading the wrong bit reports
        // the modifier only during the keystroke that toggles it.
        let mut state = [0u8; 256];
        state[value::VK_CAPITAL] = 0x01;
        state[value::VK_NUM_LOCK] = 0x01;
        assert_eq!(
            modifiers(&state),
            Modifiers::CAPS_LOCK | Modifiers::NUM_LOCK
        );
        // Held but not latched: the key is on its way down and the lock is off.
        let mut pressing = [0u8; 256];
        pressing[value::VK_CAPITAL] = 0x80;
        assert_eq!(modifiers(&pressing), Modifiers::empty());
    }

    #[test]
    fn a_surrogate_pair_becomes_one_character_and_a_lone_half_becomes_none() {
        // The astral case: `WM_CHAR` delivers 🎮 as two messages, and casting
        // either half alone yields nothing valid at all.
        let mut text = Utf16::default();
        assert_eq!(text.push(0xD83C), None, "the high half commits nothing");
        assert_eq!(text.push(0xDFAE), Some('🎮'));
        assert_eq!(text, Utf16::default(), "and the pair is not held on to");

        // A BMP character is one message.
        assert_eq!(text.push(0x3042), Some('あ'));
        assert_eq!(text.push(u16::from(b'q')), Some('q'));

        // A high surrogate followed by something that is not a low one costs
        // one character, not the rest of the stream.
        assert_eq!(text.push(0xD83C), None);
        assert_eq!(text.push(u16::from(b'a')), Some('a'));
        // A lone low surrogate is not a character and is not held.
        assert_eq!(text.push(0xDFAE), None);
        assert_eq!(text.push(u16::from(b'b')), Some('b'));
    }

    #[test]
    fn control_characters_are_not_text() {
        // `WM_CHAR` really does deliver these, and a text field that trusted
        // the stream would insert a literal escape when the user pressed Esc.
        for control in ['\u{8}', '\r', '\n', '\t', '\u{1b}', '\u{7f}'] {
            assert!(!is_text(control), "{control:?}");
        }
        for text in ['a', ' ', 'é', '🎮', '日'] {
            assert!(is_text(text), "{text:?}");
        }
    }
}