codewhale-tui 0.9.3

//! Documentation-only catalog of every user-facing keybinding.
//!
//! This module is the *single source of truth* for what shortcuts the help
//! overlay renders. The actual key handlers live in `tui/ui.rs` (and a few
//! sibling modules); they read keys directly off the crossterm event stream
//! and intentionally do **not** consult this catalog. The catalog exists so
//! that:
//!
//! 1. The help overlay (`tui/views/help.rs`) does not have to maintain a
//!    parallel list that silently rots when a handler is added or moved.
//! 2. New contributors have one place to look when answering "which keys are
//!    bound, and where do they go?"
//!
//! When you add or change a binding in `ui.rs`, **add or update the matching
//! entry here**. The compile-only side-effect of forgetting is a stale help
//! screen; there is no runtime crash, so the discipline lives in code review.
//!
//! Entries are grouped by `KeybindingSection`. The `chord` field is a
//! human-readable string formatted exactly the way it should appear in help —
//! we avoid storing `KeyBinding` values directly because many shortcuts are
//! pairs (`↑/↓`) or families (`1-8`) that don't map cleanly to a single
//! chord.

use std::borrow::Cow;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum KeybindingSection {
    Navigation,
    Editing,
    Submission,
    Modes,
    Sessions,
    Clipboard,
    Help,
}

impl KeybindingSection {
    pub fn label(self, locale: crate::localization::Locale) -> Cow<'static, str> {
        use crate::localization::{MessageId, tr};
        let id = match self {
            Self::Navigation => MessageId::HelpSectionNavigation,
            Self::Editing => MessageId::HelpSectionEditing,
            Self::Submission => MessageId::HelpSectionActions,
            Self::Modes => MessageId::HelpSectionModes,
            Self::Sessions => MessageId::HelpSectionSessions,
            Self::Clipboard => MessageId::HelpSectionClipboard,
            Self::Help => MessageId::HelpSectionHelp,
        };
        tr(locale, id)
    }

    /// Stable ordering for help rendering — matches the variant declaration
    /// order; explicit so adding a section forces a deliberate placement.
    pub fn rank(self) -> u8 {
        match self {
            Self::Navigation => 0,
            Self::Editing => 1,
            Self::Submission => 2,
            Self::Modes => 3,
            Self::Sessions => 4,
            Self::Clipboard => 5,
            Self::Help => 6,
        }
    }
}

#[derive(Debug, Clone, Copy)]
pub struct KeybindingEntry {
    pub chord: &'static str,
    pub description_id: crate::localization::MessageId,
    pub section: KeybindingSection,
}

/// Canonical list of keybindings shown in the help overlay.
///
/// Strings are written in the same notation the existing help screen uses so
/// readers can cross-reference with documentation: `Ctrl+X`, `Alt+X`,
/// `Shift+X`, `↑/↓`, `PgUp/PgDn`, etc. Help renderers may apply per-platform
/// substitutions (e.g. `⌥` for Alt on macOS) at render time, but the catalog
/// itself stores the portable form.
pub const KEYBINDINGS: &[KeybindingEntry] = &[
    // --- Navigation ---
    KeybindingEntry {
        chord: "↑ / ↓",
        description_id: crate::localization::MessageId::KbScrollTranscript,
        section: KeybindingSection::Navigation,
    },
    KeybindingEntry {
        chord: "Alt+↑ / Alt+↓",
        description_id: crate::localization::MessageId::KbScrollTranscriptAlt,
        section: KeybindingSection::Navigation,
    },
    KeybindingEntry {
        chord: "Shift+↑ / Shift+↓",
        description_id: crate::localization::MessageId::KbBrowseHistory,
        section: KeybindingSection::Navigation,
    },
    KeybindingEntry {
        chord: "PgUp / PgDn",
        description_id: crate::localization::MessageId::KbScrollPage,
        section: KeybindingSection::Navigation,
    },
    KeybindingEntry {
        chord: "Ctrl+Home / Ctrl+End",
        description_id: crate::localization::MessageId::KbJumpTopBottom,
        section: KeybindingSection::Navigation,
    },
    KeybindingEntry {
        chord: "Alt+G / Alt+Shift+G",
        description_id: crate::localization::MessageId::KbJumpTopBottomEmpty,
        section: KeybindingSection::Navigation,
    },
    KeybindingEntry {
        chord: "Alt+[ / Alt+]",
        description_id: crate::localization::MessageId::KbJumpToolBlocks,
        section: KeybindingSection::Navigation,
    },
    // --- Editing ---
    KeybindingEntry {
        chord: "← / →",
        description_id: crate::localization::MessageId::KbMoveCursor,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Home / End",
        description_id: crate::localization::MessageId::KbJumpLineStartEnd,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Ctrl+A / Ctrl+E",
        description_id: crate::localization::MessageId::KbJumpLineStartEnd,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Backspace / Delete",
        description_id: crate::localization::MessageId::KbDeleteChar,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Shift+←/→ / Shift+Home/End",
        description_id: crate::localization::MessageId::KbSelectText,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        // Ctrl+A keeps its readline meaning (start of input); select-all is
        // the shifted chord, plus native Cmd+A on terminals that forward Cmd.
        chord: "Ctrl+Shift+A / Cmd+A",
        description_id: crate::localization::MessageId::KbSelectAllDraft,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Ctrl+U",
        description_id: crate::localization::MessageId::KbClearDraft,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Ctrl+Z",
        description_id: crate::localization::MessageId::KbRestoreClearedDraft,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Ctrl+G / Ctrl+S",
        description_id: crate::localization::MessageId::KbStashDraft,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Alt+R",
        description_id: crate::localization::MessageId::KbSearchHistory,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        chord: "Ctrl+J / Alt+Enter / Shift+Enter",
        description_id: crate::localization::MessageId::KbInsertNewline,
        section: KeybindingSection::Editing,
    },
    // --- Submission / actions ---
    KeybindingEntry {
        chord: "Enter",
        description_id: crate::localization::MessageId::KbSendDraft,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Esc",
        description_id: crate::localization::MessageId::KbCloseMenu,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+C",
        description_id: crate::localization::MessageId::KbCancelOrExit,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+B",
        description_id: crate::localization::MessageId::KbShellControls,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+D",
        description_id: crate::localization::MessageId::KbExitEmpty,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+K",
        description_id: crate::localization::MessageId::KbCommandPalette,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "F2",
        description_id: crate::localization::MessageId::KbSettings,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+X (Activity sidebar)",
        description_id: crate::localization::MessageId::KbCancelBackgroundShellJobs,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+P",
        description_id: crate::localization::MessageId::KbFuzzyFilePicker,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        // `/context` is the guaranteed path; Alt+C is an unadvertised
        // handler until proven in real terminals (TUI-DOG-003).
        chord: "/context",
        description_id: crate::localization::MessageId::KbCompactInspector,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Alt+L",
        description_id: crate::localization::MessageId::KbLastMessagePager,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        // Bare `v` always types `v`; details is Alt+V only (⌥V on macOS).
        chord: "Alt+V",
        description_id: crate::localization::MessageId::KbSelectedDetails,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+O",
        description_id: crate::localization::MessageId::KbReasoningDetail,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+Alt+O",
        description_id: crate::localization::MessageId::KbTurnInspector,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+Shift+O / F4",
        description_id: crate::localization::MessageId::KbExternalEditor,
        section: KeybindingSection::Editing,
    },
    KeybindingEntry {
        // `/transcript` is the reliable fallback when a terminal cannot
        // distinguish Ctrl+Shift+T from Ctrl+T.
        chord: "/transcript / Ctrl+Shift+T",
        description_id: crate::localization::MessageId::KbLiveTranscript,
        section: KeybindingSection::Submission,
    },
    KeybindingEntry {
        chord: "Ctrl+T",
        description_id: crate::localization::MessageId::KbCycleThinking,
        section: KeybindingSection::Modes,
    },
    KeybindingEntry {
        chord: "Esc Esc",
        description_id: crate::localization::MessageId::KbBacktrackMessage,
        section: KeybindingSection::Submission,
    },
    // --- Modes ---
    KeybindingEntry {
        chord: "Tab",
        description_id: crate::localization::MessageId::KbCompleteCycleModes,
        section: KeybindingSection::Modes,
    },
    KeybindingEntry {
        chord: "Shift+Tab",
        description_id: crate::localization::MessageId::KbCyclePermissions,
        section: KeybindingSection::Modes,
    },
    KeybindingEntry {
        chord: "Alt+1-8",
        description_id: crate::localization::MessageId::KbJumpPlanAgentYolo,
        section: KeybindingSection::Modes,
    },
    KeybindingEntry {
        chord: "Alt+P / Alt+A / Alt+Y",
        description_id: crate::localization::MessageId::KbAltJumpPlanAgentYolo,
        section: KeybindingSection::Modes,
    },
    KeybindingEntry {
        chord: "Alt+! / Alt+@ / Alt+# / Alt+$ / Alt+0 / Ctrl+Alt+0",
        description_id: crate::localization::MessageId::KbFocusSidebar,
        section: KeybindingSection::Modes,
    },
    // --- Sessions ---
    KeybindingEntry {
        chord: "Ctrl+R",
        description_id: crate::localization::MessageId::KbSessionPicker,
        section: KeybindingSection::Sessions,
    },
    // --- Clipboard ---
    KeybindingEntry {
        // Keep both terminal-client families visible: the TUI may be running
        // on Linux while the user's SSH terminal is on macOS (or vice versa).
        chord: "Cmd+V / Ctrl+Shift+V",
        description_id: crate::localization::MessageId::KbTerminalPaste,
        section: KeybindingSection::Clipboard,
    },
    KeybindingEntry {
        chord: "Ctrl+V",
        description_id: crate::localization::MessageId::KbPasteAttach,
        section: KeybindingSection::Clipboard,
    },
    KeybindingEntry {
        // Terminal-native copy chords are normally consumed by the local
        // terminal and never become Codewhale key events. Ctrl+C is the
        // reliable in-app copy path when a Codewhale selection is active.
        chord: "Ctrl+C (selection)",
        description_id: crate::localization::MessageId::KbCopySelection,
        section: KeybindingSection::Clipboard,
    },
    KeybindingEntry {
        chord: "Right click",
        description_id: crate::localization::MessageId::KbContextMenu,
        section: KeybindingSection::Clipboard,
    },
    KeybindingEntry {
        chord: "@path",
        description_id: crate::localization::MessageId::KbAttachPath,
        section: KeybindingSection::Clipboard,
    },
    // --- Help ---
    KeybindingEntry {
        // F1 is primary (with /help); Ctrl+/ is the secondary fallback.
        // Alt+? stays an unadvertised handler (TUI-DOG-003).
        chord: "F1 / Ctrl+/",
        description_id: crate::localization::MessageId::KbHelpOverlay,
        section: KeybindingSection::Help,
    },
];

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

    #[test]
    fn catalog_is_non_empty_and_sections_have_entries() {
        assert!(KEYBINDINGS.iter().any(|entry| !entry.chord.is_empty()));
        // Every declared section should appear in the catalog at least once,
        // otherwise the help overlay would render an empty heading.
        let sections = [
            KeybindingSection::Navigation,
            KeybindingSection::Editing,
            KeybindingSection::Submission,
            KeybindingSection::Modes,
            KeybindingSection::Sessions,
            KeybindingSection::Clipboard,
            KeybindingSection::Help,
        ];
        for section in sections {
            assert!(
                KEYBINDINGS.iter().any(|entry| entry.section == section),
                "no entries for section {section:?}"
            );
        }
    }

    #[test]
    fn help_advertises_f1_and_ctrl_slash_never_alt_question() {
        // TUI-DOG-003: Alt+? is not advertised anywhere; F1 (with /help) is
        // primary and Ctrl+/ is the secondary fallback.
        assert!(
            KEYBINDINGS.iter().any(|entry| {
                entry.section == KeybindingSection::Help
                    && entry.chord.contains("F1")
                    && entry.chord.contains("Ctrl+/")
            }),
            "help must document F1 with the Ctrl+/ fallback"
        );
        assert!(
            KEYBINDINGS
                .iter()
                .all(|entry| !entry.chord.contains("Alt+?")),
            "Alt+? must not be advertised in the help catalog"
        );
    }

    #[test]
    fn composer_catalog_assigns_one_stable_role_to_each_chord() {
        let chord_for = |id| {
            KEYBINDINGS
                .iter()
                .find(|entry| entry.description_id == id)
                .expect("composer binding should be documented")
                .chord
        };

        assert_eq!(
            chord_for(crate::localization::MessageId::KbInsertNewline),
            "Ctrl+J / Alt+Enter / Shift+Enter"
        );
        assert!(
            KEYBINDINGS
                .iter()
                .all(|entry| !entry.chord.contains("Ctrl+Enter")
                    && !entry.chord.contains("Cmd+Enter"))
        );
        assert_eq!(
            chord_for(crate::localization::MessageId::KbStashDraft),
            "Ctrl+G / Ctrl+S"
        );
        assert_eq!(
            chord_for(crate::localization::MessageId::KbSendDraft),
            "Enter"
        );

        let tab_copy = crate::localization::tr(
            crate::localization::Locale::En,
            crate::localization::MessageId::KbCompleteCycleModes,
        );
        assert!(!tab_copy.to_ascii_lowercase().contains("queue"));
        let stash_copy = crate::localization::tr(
            crate::localization::Locale::En,
            crate::localization::MessageId::KbStashDraft,
        );
        assert!(!stash_copy.to_ascii_lowercase().contains("send"));
    }

    #[test]
    fn clipboard_help_distinguishes_terminal_text_graphical_image_and_in_app_copy() {
        let terminal_paste = KEYBINDINGS
            .iter()
            .find(|entry| entry.description_id == crate::localization::MessageId::KbTerminalPaste)
            .expect("terminal paste binding should be documented");
        let graphical_paste = KEYBINDINGS
            .iter()
            .find(|entry| entry.description_id == crate::localization::MessageId::KbPasteAttach)
            .expect("graphical paste binding should be documented");
        let copy = KEYBINDINGS
            .iter()
            .find(|entry| entry.description_id == crate::localization::MessageId::KbCopySelection)
            .expect("copy binding should be documented");

        assert!(terminal_paste.chord.contains("Cmd+V"));
        assert!(terminal_paste.chord.contains("Ctrl+Shift+V"));
        assert_eq!(graphical_paste.chord, "Ctrl+V");
        let terminal_description = crate::localization::tr(
            crate::localization::Locale::En,
            crate::localization::MessageId::KbTerminalPaste,
        );
        let graphical_description = crate::localization::tr(
            crate::localization::Locale::En,
            crate::localization::MessageId::KbPasteAttach,
        );
        assert!(!terminal_description.to_ascii_lowercase().contains("image"));
        assert!(graphical_description.to_ascii_lowercase().contains("image"));
        assert_eq!(copy.chord, "Ctrl+C (selection)");
        assert!(!copy.chord.contains("Cmd+C"));
        assert!(!copy.chord.contains("Ctrl+Shift+C"));
    }

    #[test]
    fn transcript_navigation_catalog_does_not_advertise_bare_typing_keys() {
        for stale in [
            "g / G",
            "[ / ]",
            "l",
            "?",
            "Ctrl+↑ / Ctrl+↓",
            "v",
            "v / Alt+V",
        ] {
            assert!(
                KEYBINDINGS.iter().all(|entry| entry.chord != stale),
                "stale handler-free chord remains documented: {stale}"
            );
        }
        for wired in ["Alt+G / Alt+Shift+G", "Alt+[ / Alt+]", "Alt+L", "Alt+V"] {
            assert!(
                KEYBINDINGS.iter().any(|entry| entry.chord == wired),
                "wired transcript shortcut missing from help: {wired}"
            );
        }
    }

    #[test]
    fn live_transcript_documents_command_before_shaky_chord() {
        let transcript = KEYBINDINGS
            .iter()
            .find(|entry| entry.description_id == crate::localization::MessageId::KbLiveTranscript)
            .expect("live transcript entry should be documented");

        assert_eq!(transcript.chord, "/transcript / Ctrl+Shift+T");
    }

    #[test]
    fn shell_binding_source_matches_help_catalog_chords() {
        use crate::tui::shell_key_routing::{ShellBindingId, binding};
        assert_eq!(binding(ShellBindingId::ToolDetails).catalog_chord, "Alt+V");
        assert_eq!(
            binding(ShellBindingId::ContextInspector).catalog_chord,
            "/context"
        );
        assert_eq!(binding(ShellBindingId::Help).catalog_chord, "F1 / Ctrl+/");
        for id in [
            ShellBindingId::ToolDetails,
            ShellBindingId::ContextInspector,
            ShellBindingId::Help,
        ] {
            let chord = binding(id).catalog_chord;
            assert!(
                KEYBINDINGS
                    .iter()
                    .any(|entry| entry.chord == chord || entry.chord.contains(chord)),
                "shell binding {id:?} chord missing from help catalog: {chord}"
            );
        }
    }

    #[test]
    fn ctrl_o_and_ctrl_alt_o_help_copy_match_split_surfaces() {
        let ctrl_o = KEYBINDINGS
            .iter()
            .find(|entry| entry.chord == "Ctrl+O")
            .expect("Ctrl+O keybinding should be documented");

        // Ctrl+O now opens the full recorded Reasoning Detail; the whole-turn
        // Turn Inspector moved to Ctrl+Alt+O.
        assert_eq!(
            ctrl_o.description_id,
            crate::localization::MessageId::KbReasoningDetail
        );
        assert_eq!(
            crate::localization::tr(crate::localization::Locale::En, ctrl_o.description_id,),
            "Open reasoning detail for the selected or current turn"
        );

        let ctrl_alt_o = KEYBINDINGS
            .iter()
            .find(|entry| entry.chord == "Ctrl+Alt+O")
            .expect("Ctrl+Alt+O keybinding should be documented");
        assert_eq!(
            ctrl_alt_o.description_id,
            crate::localization::MessageId::KbTurnInspector
        );
        assert_eq!(
            crate::localization::tr(crate::localization::Locale::En, ctrl_alt_o.description_id,),
            "Open Turn Inspector"
        );

        let editor = KEYBINDINGS
            .iter()
            .find(|entry| entry.chord == "Ctrl+Shift+O / F4")
            .expect("external-editor keybinding should be documented");
        assert_eq!(
            crate::localization::tr(crate::localization::Locale::En, editor.description_id,),
            "Open composer draft in external editor"
        );
    }

    #[test]
    fn ctrl_x_activity_sidebar_cancel_all_is_documented() {
        let ctrl_x_activity = KEYBINDINGS
            .iter()
            .find(|entry| entry.chord == "Ctrl+X (Activity sidebar)")
            .expect("Ctrl+X Activity sidebar keybinding should be documented");

        assert_eq!(
            ctrl_x_activity.description_id,
            crate::localization::MessageId::KbCancelBackgroundShellJobs
        );
    }

    #[test]
    fn tool_details_documents_alt_v_only_never_bare_v() {
        let selected_details = KEYBINDINGS
            .iter()
            .filter(|entry| {
                entry.description_id == crate::localization::MessageId::KbSelectedDetails
            })
            .map(|entry| entry.chord)
            .collect::<Vec<_>>();

        // TUI-DOG-002: bare `v` always types `v`; details is Alt+V only.
        assert_eq!(selected_details, vec!["Alt+V"]);
        assert!(
            KEYBINDINGS
                .iter()
                .all(|entry| entry.chord != "v" && !entry.chord.starts_with("v /")),
            "bare `v` must not be advertised — composer typing owns it"
        );
    }

    /// #3758: a user who reads the help overlay must be able to answer "what
    /// does this key do?" with one answer. A key may appear twice only when
    /// every occurrence but one names its context in parentheses — the way
    /// `Ctrl+C` and `Ctrl+C (selection)` do — so the reader is told which
    /// reading applies. Two unqualified entries for the same key is the
    /// ambiguity this guard exists to reject.
    #[test]
    fn every_advertised_key_names_exactly_one_canonical_action() {
        struct Use {
            chord: &'static str,
            alternative: String,
            description_id: crate::localization::MessageId,
        }

        let mut uses_by_key: std::collections::BTreeMap<String, Vec<Use>> =
            std::collections::BTreeMap::new();
        for entry in KEYBINDINGS {
            for alternative in entry.chord.split(" / ") {
                let alternative = alternative.trim();
                // `Ctrl+C (selection)` → base key `Ctrl+C`, qualifier retained
                // on the alternative so the check below can see it.
                let base = alternative
                    .split_once(" (")
                    .map(|(head, _)| head)
                    .unwrap_or(alternative)
                    .trim()
                    .to_string();
                uses_by_key.entry(base).or_default().push(Use {
                    chord: entry.chord,
                    alternative: alternative.to_string(),
                    description_id: entry.description_id,
                });
            }
        }

        for (key, uses) in &uses_by_key {
            if uses.len() == 1 {
                continue;
            }
            let single_action = uses
                .iter()
                .all(|entry| entry.description_id == uses[0].description_id);
            if single_action {
                // The same action documented from two spellings is fine —
                // `Home / End` and `Ctrl+A / Ctrl+E` both jump to line edges.
                continue;
            }
            let unqualified: Vec<&str> = uses
                .iter()
                .filter(|entry| !entry.alternative.contains('('))
                .map(|entry| entry.chord)
                .collect();
            assert!(
                unqualified.len() <= 1,
                "{key} is advertised for more than one action without naming the \
                 context that selects between them: {unqualified:?}"
            );
        }
    }

    /// #440 / #3758: `Ctrl+G` and `Ctrl+S` stash the draft. They are not a
    /// send, a queue, a steer, or a file save, and a real-terminal report that
    /// says otherwise is reading ambiguous copy, not misusing the key.
    #[test]
    fn stash_chords_advertise_stashing_and_nothing_else() {
        let stash_entries: Vec<&KeybindingEntry> = KEYBINDINGS
            .iter()
            .filter(|entry| {
                entry
                    .chord
                    .split(" / ")
                    .map(str::trim)
                    .any(|chord| matches!(chord, "Ctrl+G" | "Ctrl+S"))
            })
            .collect();

        assert_eq!(
            stash_entries.len(),
            1,
            "Ctrl+G / Ctrl+S must be documented exactly once, together"
        );
        assert_eq!(stash_entries[0].chord, "Ctrl+G / Ctrl+S");
        assert_eq!(
            stash_entries[0].description_id,
            crate::localization::MessageId::KbStashDraft
        );

        let copy = crate::localization::tr(
            crate::localization::Locale::En,
            crate::localization::MessageId::KbStashDraft,
        )
        .to_ascii_lowercase();
        for forbidden in ["send", "queue", "steer", "submit", "save"] {
            assert!(
                !copy.contains(forbidden),
                "stash copy must not read as {forbidden:?}: {copy:?}"
            );
        }
        assert!(
            copy.contains("stash"),
            "stash copy must name the action it performs: {copy:?}"
        );
    }

    /// Only chords distinguishable by the baseline terminal protocol may be
    /// advertised. Enter sends or queues (then sends a queued message now),
    /// while the newline chords stay newlines.
    #[test]
    fn running_turn_verbs_belong_to_one_chord_each() {
        let entry_for = |id| {
            KEYBINDINGS
                .iter()
                .find(|entry| entry.description_id == id)
                .expect("running-turn binding should be documented")
        };

        assert_eq!(
            entry_for(crate::localization::MessageId::KbSendDraft).chord,
            "Enter"
        );
        assert!(
            KEYBINDINGS
                .iter()
                .all(|entry| !entry.chord.contains("Ctrl+Enter")
                    && !entry.chord.contains("Cmd+Enter"))
        );
        assert_eq!(
            entry_for(crate::localization::MessageId::KbInsertNewline).chord,
            "Ctrl+J / Alt+Enter / Shift+Enter"
        );

        let newline_copy = crate::localization::tr(
            crate::localization::Locale::En,
            crate::localization::MessageId::KbInsertNewline,
        )
        .to_ascii_lowercase();
        for forbidden in ["send", "steer", "queue"] {
            assert!(
                !newline_copy.contains(forbidden),
                "newline chords must not read as {forbidden:?}: {newline_copy:?}"
            );
        }
    }

    #[test]
    fn section_rank_is_a_total_order() {
        let sections = [
            KeybindingSection::Navigation,
            KeybindingSection::Editing,
            KeybindingSection::Submission,
            KeybindingSection::Modes,
            KeybindingSection::Sessions,
            KeybindingSection::Clipboard,
            KeybindingSection::Help,
        ];
        let mut ranks: Vec<u8> = sections.iter().map(|s| s.rank()).collect();
        ranks.sort_unstable();
        ranks.dedup();
        assert_eq!(ranks.len(), sections.len(), "ranks must be unique");
    }
}