tix-tracker 0.6.0

use std::collections::HashMap;
use std::fmt;

use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize, Serializer};

use crate::error::{Result, TixError};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum InputContext {
    Board,
    /// The batch modal (WP07). Its own context so a key means one thing there and
    /// is not borrowed from the board's — `space` marks a card in a batch and is not
    /// a board action, and `y` confirms in a batch and is not a board action either.
    BulkModal,
    /// The triage inbox and its decision modal (WP06, T029/T031).
    ///
    /// Its own context for the reason `BulkModal`'s doc gives:
    /// `a`/`d`/`u`/`f` decide here and would be board actions there, and the
    /// inbox is keyboard-driven all the way down. It carries **free text** (a
    /// decline reason, a duplicate target), so `cancel` is `esc` and *only*
    /// `esc` — `q` stays a typeable letter for the same reason `LinkPrompt`
    /// keeps it.
    Triage,
    /// The F3 Cycle mode (tui-cycle-mode).
    ///
    /// Its own context for the reason `Triage`'s doc gives: `m` opens planning
    /// management here and would be a board action there, `j`/`k` walk the cycle
    /// rows, and the mode carries no free text, so `q`/`esc` may close it.
    Cycle,
    /// The F5 Milestones mode.
    ///
    /// Its own context for the reason `Cycle`'s doc gives: `m` opens planning
    /// management here, `j`/`k` walk the rows, and it carries no free text, so
    /// `q`/`esc` may close it.
    Milestones,
    Rollover,
    Detail,
    Form,
    FormPicker,
    ConfirmDelete,
    MoveIntoDone,
    /// The blocked-move acknowledgement prompt (WP04). Its own context so the
    /// command bar can advertise `y`/`esc` and nothing else.
    ConfirmBlockedMove,
    Help,
    /// The keybindings overlay's `/` input line (tix #1496).
    ///
    /// Its own context for the reason [`InputContext::Filter`] is one: it reads **free
    /// text**. Keeping the list mode's `q`/`?` bound to cancel here would rewrite them
    /// to `esc` before the handler saw them, and a query could never contain a `q` —
    /// the same trap the free-text modes below document.
    HelpSearch,
    ContextMenu,
    /// The detail pane's `related_issues` picker (#1513).
    ///
    /// Its own context so the picker's `Enter` selects a related entry and does
    /// not borrow any detail-pane key. It carries no free text, so `cancel` is
    /// `Esc`; an unbound letter is a no-op rather than a filter character.
    RelatedPicker,
    Filter,
    FilterModal,
    Settings,
    SettingsPrompt,
    PlanningManagement,
    PlanningConfirm,
    PlanningForm,
    DatePicker,
    Comment,
    Asset,
    /// The editor round trip's repair prompt (tix #1506).
    ///
    /// Its own context: every key here is a decision about a file the editor just
    /// produced — apply the proposed fix, declare the key, reopen the editor on
    /// the retained copy, acknowledge and keep it, or discard it behind a second
    /// confirmation. It is the successor to #1506's `edit_warning` context, which
    /// the same prompt grew out of; there is deliberately only one such prompt.
    EditRepair,
    /// The edit-conflict prompt (tix #1510).
    ///
    /// Its own context for the reason [`InputContext::EditRepair`] has one: it is
    /// a modal decision with three distinct outcomes, and one of them — *compare* —
    /// reopens the editor, which no board key does. It carries no free text, so a
    /// letter could close it — but only `Esc` (bound to `ignore`) does, because the
    /// prompt closes through a decision and nothing else. `q` stays unbound.
    EditConflict,
    /// The two-step create/edit relationship prompt (#1359).
    ///
    /// Free text, so `cancel` is `Esc` and **only** `Esc` — see the note on the
    /// `Asset`/`Comment`/`Filter` group for why binding `q` here would be a real
    /// defect rather than a preference: a title fragment containing `q` is ordinary.
    LinkPrompt,
    /// The top-level mode shell (tui-mode-navigation).
    ///
    /// It binds only the five mode switches and the navigation toggle. It is
    /// consulted **after** the active top-level context (Board, Triage,
    /// PlanningManagement, Settings, Form) declines the pressed key, so a
    /// context that binds the key locally always wins — which is what keeps
    /// `F2` as `open_picker` inside a form and the `F(12)` sentinel untouched
    /// for a truly unbound key.
    Shell,
}

impl InputContext {
    pub const ALL: &'static [Self] = &[
        Self::Board,
        Self::Rollover,
        Self::Detail,
        Self::Form,
        Self::FormPicker,
        Self::ConfirmDelete,
        Self::MoveIntoDone,
        Self::ConfirmBlockedMove,
        Self::Help,
        Self::HelpSearch,
        Self::ContextMenu,
        // Walked like every other context so the overlay's completeness guard
        // sees the related picker's keys too (#1513).
        Self::RelatedPicker,
        Self::Filter,
        Self::FilterModal,
        Self::BulkModal,
        Self::Triage,
        Self::Cycle,
        Self::Milestones,
        Self::Settings,
        Self::SettingsPrompt,
        Self::PlanningManagement,
        Self::PlanningConfirm,
        Self::PlanningForm,
        Self::DatePicker,
        Self::Comment,
        Self::Asset,
        Self::EditRepair,
        // Walked like every other context so the overlay's completeness guard
        // sees the conflict prompt's keys too (tix #1510).
        Self::EditConflict,
        // Free text like the others, and missing from this list until the overlay's
        // completeness guard needed it: a context the guard does not walk is a context
        // whose keys can go undocumented.
        Self::LinkPrompt,
        // The mode shell's switches, walked like every other context so the
        // completeness guard can see them.
        Self::Shell,
    ];

    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Board => "board",
            Self::Rollover => "rollover",
            Self::Detail => "detail",
            Self::Form => "form",
            Self::FormPicker => "form_picker",
            Self::ConfirmDelete => "confirm_delete",
            Self::ConfirmBlockedMove => "confirm_blocked_move",
            Self::MoveIntoDone => "move_into_done",
            Self::Help => "help",
            Self::HelpSearch => "help_search",
            Self::ContextMenu => "context_menu",
            Self::RelatedPicker => "related_picker",
            Self::Filter => "filter",
            Self::FilterModal => "filter_modal",
            Self::BulkModal => "bulk_modal",
            Self::Settings => "settings",
            Self::SettingsPrompt => "settings_prompt",
            Self::PlanningManagement => "planning_management",
            Self::PlanningConfirm => "planning_confirm",
            Self::PlanningForm => "planning_form",
            Self::DatePicker => "date_picker",
            Self::Comment => "comment",
            Self::Asset => "asset",
            Self::EditRepair => "edit_repair",
            Self::EditConflict => "edit_conflict",
            Self::LinkPrompt => "link_prompt",
            Self::Triage => "triage",
            Self::Cycle => "cycle",
            Self::Milestones => "milestones",
            Self::Shell => "shell",
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TuiAction {
    MoveUp,
    MoveDown,
    MoveLeft,
    MoveRight,
    NextBoard,
    PreviousBoard,
    Open,
    Edit,
    Agent,
    /// Open the selected issue in a read-only viewer (tix #1507).
    ///
    /// `v` was free on both the board and the detail pane. Read-only by
    /// construction: the viewer runs on the issue file and never writes back.
    View,
    ToggleColumn,
    FilterModal,
    BulkModal,
    /// Open the triage inbox (WP06, T029). Its own action rather than a chord
    /// bolted onto another one, so `t` can be rebound from `keybindings.board`
    /// like every other board key and the help overlay can name it.
    Triage,
    Mark,
    Unmark,
    MovePrevious,
    MoveNext,
    NewIssue,
    /// Duplicate the selected issue into the create-issue form, prefilled from it
    /// (tix #1484).
    ///
    /// `C`, the capital of `c` (toggle column): a pair that reads together without
    /// changing what any existing key means, which is the same rule `B`/`A` follow.
    CloneIssue,
    /// Show the archived issues on the board, or hide them again (tix #1492).
    ///
    /// `a` was unbound on the board. The toggle is a *reload*, not a display
    /// filter: the archived files are not read until it is on.
    ToggleArchived,
    /// Show each issue's sub-issues beneath it on the board, or hide them again
    /// (tix #1399).
    ///
    /// `u` was unbound on the board. Unlike the archive toggle this is display-only:
    /// the children are already in the board state, so flipping it **reorders** the
    /// column (one level deep) rather than re-reading the store.
    ToggleChildren,
    Delete,
    Refresh,
    Settings,
    Planning,
    NewBoard,
    Help,
    Quit,
    TextFilter,
    ReorderUp,
    ReorderDown,
    Close,
    ScrollUp,
    ScrollDown,
    Comment,
    Asset,
    /// Open the create-relationship prompt from the detail view (#1359).
    NewRelationship,
    /// Re-kind or retarget the relationship under the detail pane's cursor.
    EditRelationship,
    /// Remove the relationship under the cursor, after confirmation.
    RemoveRelationship,
    /// Move the detail pane's relationship cursor.
    NextRelationship,
    PreviousRelationship,
    /// Open the picker listing the detail pane's `related_issues` entries
    /// (tix #1513).
    ///
    /// `r` was free in the detail pane — the board's `r` is `refresh`, a
    /// different context, so the two never collide.
    RelatedPicker,
    /// Follow the detail pane's selected `related_issues` entry (tix #1513).
    ///
    /// `o` was free in the detail pane and reads as "open".
    FollowRelated,
    /// Pop the detail pane's navigation stack and restore the previous issue
    /// (tix #1513).
    ///
    /// `Backspace` was free in the detail pane and reads as "back".
    NavBack,
    Submit,
    Cancel,
    Next,
    Previous,
    OpenPicker,
    Reset,
    Toggle,
    AddColumn,
    NewPlanningItem,
    EditPlanningItem,
    DeletePlanningItem,
    Confirm,
    Create,
    PreviousYear,
    NextYear,
    PreviousMonth,
    NextMonth,
    Reedit,
    Ignore,
    /// Declare the repair prompt's undeclared frontmatter key in `tix.toml`
    /// (tix #1506).
    ///
    /// Its own action, not `confirm`: `confirm` applies whatever fix the prompt
    /// proposes, which *happens* to be the declaration for an unknown key, while
    /// `declare_key` always means "write it into `[custom_attributes]`" and says
    /// so when there is no key to declare.
    DeclareKey,
    /// Discard the repair prompt's retained copy, after a second confirmation
    /// (tix #1506).
    ///
    /// The **only** action that removes the editor's copy. The first press arms
    /// the prompt; a second press is the decision. `Esc` deliberately
    /// acknowledges and keeps the copy instead, so a stray key cannot destroy a
    /// user's edit.
    Discard,
    /// Switch the top-level shell to the Board mode (F1 by default).
    SwitchToBoard,
    /// Switch the top-level shell to the Triage mode (F2 by default).
    SwitchToTriage,
    /// Switch the top-level shell to the Cycle mode (F4 by default).
    SwitchToCycle,
    /// Switch the top-level shell to the Milestones mode (F5 by default).
    SwitchToMilestones,
    /// Switch the top-level shell to the New Issue mode (F1 by default).
    SwitchToNewIssue,
    /// Switch the top-level shell to the Config mode (F12 by default).
    SwitchToConfig,
    /// Cycle the vertical navigation display state `Off`/`Small`/`Default`.
    ToggleNavigation,
}

impl TuiAction {
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::MoveUp => "move_up",
            Self::MoveDown => "move_down",
            Self::MoveLeft => "move_left",
            Self::MoveRight => "move_right",
            Self::NextBoard => "next_board",
            Self::PreviousBoard => "previous_board",
            Self::Open => "open",
            Self::Edit => "edit",
            Self::Agent => "agent",
            Self::View => "view",
            Self::ToggleColumn => "toggle_column",
            Self::FilterModal => "filter_modal",
            Self::BulkModal => "bulk_modal",
            Self::Triage => "triage",
            Self::Mark => "mark",
            Self::Unmark => "unmark",
            Self::MovePrevious => "move_previous",
            Self::MoveNext => "move_next",
            Self::NewIssue => "new_issue",
            Self::CloneIssue => "clone_issue",
            Self::ToggleArchived => "toggle_archived",
            Self::ToggleChildren => "toggle_children",
            Self::Delete => "delete",
            Self::Refresh => "refresh",
            Self::Settings => "settings",
            Self::Planning => "planning",
            Self::NewBoard => "new_board",
            Self::Help => "help",
            Self::Quit => "quit",
            Self::TextFilter => "text_filter",
            Self::ReorderUp => "reorder_up",
            Self::ReorderDown => "reorder_down",
            Self::Close => "close",
            Self::ScrollUp => "scroll_up",
            Self::ScrollDown => "scroll_down",
            Self::Comment => "comment",
            Self::Asset => "asset",
            Self::NewRelationship => "new_relationship",
            Self::EditRelationship => "edit_relationship",
            Self::RemoveRelationship => "remove_relationship",
            Self::NextRelationship => "next_relationship",
            Self::PreviousRelationship => "previous_relationship",
            Self::RelatedPicker => "related_picker",
            Self::FollowRelated => "follow_related",
            Self::NavBack => "nav_back",
            Self::Submit => "submit",
            Self::Cancel => "cancel",
            Self::Next => "next",
            Self::Previous => "previous",
            Self::OpenPicker => "open_picker",
            Self::Reset => "reset",
            Self::Toggle => "toggle",
            Self::AddColumn => "add_column",
            Self::NewPlanningItem => "new_planning_item",
            Self::EditPlanningItem => "edit_planning_item",
            Self::DeletePlanningItem => "delete_planning_item",
            Self::Confirm => "confirm",
            Self::Create => "create",
            Self::PreviousYear => "previous_year",
            Self::NextYear => "next_year",
            Self::PreviousMonth => "previous_month",
            Self::NextMonth => "next_month",
            Self::Reedit => "reedit",
            Self::Ignore => "ignore",
            Self::DeclareKey => "declare_key",
            Self::Discard => "discard",
            Self::SwitchToBoard => "switch_to_board",
            Self::SwitchToTriage => "switch_to_triage",
            Self::SwitchToCycle => "switch_to_cycle",
            Self::SwitchToMilestones => "switch_to_milestones",
            Self::SwitchToNewIssue => "switch_to_new_issue",
            Self::SwitchToConfig => "switch_to_config",
            Self::ToggleNavigation => "toggle_navigation",
        }
    }

    pub const fn description(self) -> &'static str {
        match self {
            Self::MoveUp => "move up",
            Self::MoveDown => "move down",
            Self::MoveLeft => "previous column",
            Self::MoveRight => "next column",
            Self::NextBoard => "next board",
            Self::PreviousBoard => "previous board",
            Self::Open => "open detail",
            Self::Edit => "edit",
            Self::Agent => "open agent",
            Self::View => "view issue",
            Self::ToggleColumn => "toggle column",
            Self::FilterModal => "filter criteria",
            Self::BulkModal => "batch select",
            Self::Triage => "triage inbox",
            Self::Mark => "mark for batch",
            Self::Unmark => "unmark for batch",
            Self::MovePrevious => "move to previous column",
            Self::MoveNext => "move to next column",
            Self::NewIssue => "new issue",
            Self::CloneIssue => "clone issue",
            Self::ToggleArchived => "show archived issues",
            Self::ToggleChildren => "toggle sub-issues",
            Self::Delete => "delete",
            Self::Refresh => "refresh",
            Self::Settings => "settings",
            Self::Planning => "planning",
            Self::NewBoard => "new board",
            Self::Help => "help",
            Self::Quit => "quit",
            Self::TextFilter => "search",
            Self::ReorderUp => "reorder up",
            Self::ReorderDown => "reorder down",
            Self::Close => "close",
            Self::ScrollUp => "scroll up one page",
            Self::ScrollDown => "scroll down one page",
            Self::Comment => "comment",
            Self::Asset => "asset",
            Self::NewRelationship => "new relationship",
            Self::EditRelationship => "edit relationship",
            Self::RemoveRelationship => "remove relationship",
            Self::NextRelationship => "next relationship",
            Self::PreviousRelationship => "previous relationship",
            Self::RelatedPicker => "related issues",
            Self::FollowRelated => "follow related issue",
            Self::NavBack => "back",
            Self::Submit => "submit",
            Self::Cancel => "cancel",
            Self::Next => "next",
            Self::Previous => "previous",
            Self::OpenPicker => "open picker",
            Self::Reset => "reset",
            Self::Toggle => "toggle",
            Self::AddColumn => "add column",
            Self::NewPlanningItem => "new",
            Self::EditPlanningItem => "edit",
            Self::DeletePlanningItem => "delete",
            Self::Confirm => "confirm",
            Self::Create => "create",
            Self::PreviousYear => "previous year",
            Self::NextYear => "next year",
            Self::PreviousMonth => "previous month",
            Self::NextMonth => "next month",
            Self::Reedit => "re-edit",
            Self::Ignore => "ignore",
            Self::DeclareKey => "declare the key in tix.toml",
            Self::Discard => "discard the edit",
            Self::SwitchToBoard => "board mode",
            Self::SwitchToTriage => "triage mode",
            Self::SwitchToCycle => "cycle mode",
            Self::SwitchToMilestones => "milestones mode",
            Self::SwitchToNewIssue => "new issue mode",
            Self::SwitchToConfig => "config mode",
            Self::ToggleNavigation => "toggle navigation",
        }
    }

    /// The wording this action gets in `context`'s help.
    ///
    /// `move_left`/`move_right` walk a **column** on the board, the Config
    /// mode's two **panes** (rail ⇄ body), and a **group** in the Cycle
    /// listing; `submit` steps into the body and then activates the row there.
    /// The action — and the key — is the same event, so only the noun the help
    /// shows changes. Every other action keeps its single description.
    pub const fn description_in(self, context: InputContext) -> &'static str {
        match (context, self) {
            (InputContext::Cycle, Self::MoveLeft) => "previous group",
            (InputContext::Cycle, Self::MoveRight) => "next group",
            (InputContext::Settings, Self::MoveLeft) => "previous pane",
            (InputContext::Settings, Self::MoveRight) => "next pane",
            (InputContext::Settings, Self::Submit) => "step into the body / activate row",
            // #1506. Every key in the repair prompt is a decision about the file
            // the editor just produced, and "confirm"/"ignore" say nothing about
            // which one — the overlay has to spell out each.
            (InputContext::EditRepair, Self::Confirm) => "apply the proposed fix",
            (InputContext::EditRepair, Self::DeclareKey) => "declare the key in tix.toml",
            (InputContext::EditRepair, Self::Reedit) => "reopen the editor on the retained copy",
            (InputContext::EditRepair, Self::Ignore) => "acknowledge (keeps the copy)",
            (InputContext::EditRepair, Self::Discard) => "discard the edit (asks again)",
            // #1510. The conflict prompt reuses the edit warning's three actions:
            // each is the same *kind* of decision, so what the key means here is
            // what the wording has to spell out.
            (InputContext::EditConflict, Self::Confirm) => "overwrite the file with this edit",
            (InputContext::EditConflict, Self::Ignore) => "keep the on-disk version",
            (InputContext::EditConflict, Self::Reedit) => "compare in the editor",
            _ => self.description(),
        }
    }
}

pub type Binding = Vec<String>;

macro_rules! partial_bindings {
    ($($field:ident),+ $(,)?) => {
        #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
        #[serde(default, deny_unknown_fields)]
        pub struct ActionBindings {
            $(
                #[serde(skip_serializing_if = "Option::is_none")]
                pub $field: Option<Binding>,
            )+
        }
    };
}

partial_bindings!(
    move_up,
    move_down,
    move_left,
    move_right,
    next_board,
    previous_board,
    open,
    edit,
    agent,
    view,
    toggle_column,
    filter_modal,
    bulk_modal,
    triage,
    mark,
    unmark,
    move_previous,
    move_next,
    new_issue,
    clone_issue,
    toggle_archived,
    toggle_children,
    delete,
    refresh,
    settings,
    planning,
    new_board,
    help,
    quit,
    text_filter,
    reorder_up,
    reorder_down,
    close,
    scroll_up,
    scroll_down,
    comment,
    asset,
    submit,
    cancel,
    next,
    previous,
    open_picker,
    reset,
    toggle,
    add_column,
    new_planning_item,
    edit_planning_item,
    delete_planning_item,
    confirm,
    create,
    previous_year,
    next_year,
    previous_month,
    next_month,
    reedit,
    ignore,
    declare_key,
    discard,
    switch_to_board,
    switch_to_triage,
    switch_to_cycle,
    switch_to_milestones,
    switch_to_new_issue,
    switch_to_config,
    toggle_navigation,
);

macro_rules! keybindings_config {
    ($($field:ident => $context:ident),+ $(,)?) => {
        #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
        #[serde(default, deny_unknown_fields)]
        pub struct KeyBindings {
            $(
                #[serde(skip_serializing_if = "ActionBindings::is_empty")]
                pub $field: ActionBindings,
            )+
        }

        impl KeyBindings {
            pub fn is_empty(&self) -> bool {
                self == &Self::default()
            }

            fn overrides(&self, context: InputContext) -> &ActionBindings {
                match context {
                    $(InputContext::$context => &self.$field,)+
                }
            }
        }
    };
}

keybindings_config!(
    board => Board,
    rollover => Rollover,
    detail => Detail,
    form => Form,
    form_picker => FormPicker,
    confirm_delete => ConfirmDelete,
    confirm_blocked_move => ConfirmBlockedMove,
    help_search => HelpSearch,
    move_into_done => MoveIntoDone,
    help => Help,
    context_menu => ContextMenu,
    // #1513: the related-issues picker's own section, so its keys are rebindable
    // through `[keybindings.related_picker]` like every other context's.
    related_picker => RelatedPicker,
    filter => Filter,
    filter_modal => FilterModal,
    bulk_modal => BulkModal,
    triage => Triage,
    cycle => Cycle,
    milestones => Milestones,
    settings => Settings,
    settings_prompt => SettingsPrompt,
    planning_management => PlanningManagement,
    planning_confirm => PlanningConfirm,
    planning_form => PlanningForm,
    date_picker => DatePicker,
    comment => Comment,
    asset => Asset,
    edit_repair => EditRepair,
    edit_conflict => EditConflict,
    link_prompt => LinkPrompt,
    shell => Shell,
);

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct KeyChord {
    pub code: KeyCode,
    pub modifiers: KeyModifiers,
}

impl KeyChord {
    pub fn parse(value: &str) -> std::result::Result<Self, String> {
        let value = value.trim();
        if value.is_empty() {
            return Err("key chord must not be empty".into());
        }
        if value.chars().count() == 1 {
            let ch = value.chars().next().expect("value has one character");
            if ch.is_control() {
                return Err(format!("unsupported key name `{value}`"));
            }
            let modifiers = if ch.is_ascii_uppercase() {
                KeyModifiers::SHIFT
            } else {
                KeyModifiers::NONE
            };
            return Ok(Self {
                code: KeyCode::Char(ch),
                modifiers,
            });
        }
        let mut parts = value.split('+');
        let key = parts.next_back().ok_or("missing key name")?.trim();
        let mut modifiers = KeyModifiers::NONE;
        for part in parts {
            match part.trim().to_ascii_lowercase().as_str() {
                "ctrl" | "control" => modifiers |= KeyModifiers::CONTROL,
                "alt" | "option" => modifiers |= KeyModifiers::ALT,
                "shift" => modifiers |= KeyModifiers::SHIFT,
                "super" | "cmd" | "command" => modifiers |= KeyModifiers::SUPER,
                other => return Err(format!("unsupported modifier `{other}`")),
            }
        }
        if key.is_empty() {
            return Err("missing key name".into());
        }
        let mut code = match key.to_ascii_lowercase().as_str() {
            "backtab" => return Err("use shift+tab instead of `backtab`".into()),
            "shift+tab" => KeyCode::BackTab,
            "backspace" => KeyCode::Backspace,
            "tab" => KeyCode::Tab,
            "enter" | "return" => KeyCode::Enter,
            "esc" | "escape" => KeyCode::Esc,
            "space" => KeyCode::Char(' '),
            "left" => KeyCode::Left,
            "right" => KeyCode::Right,
            "up" => KeyCode::Up,
            "down" => KeyCode::Down,
            "home" => KeyCode::Home,
            "end" => KeyCode::End,
            "pageup" | "pgup" => KeyCode::PageUp,
            "pagedown" | "pgdn" | "pgdown" => KeyCode::PageDown,
            "delete" | "del" => KeyCode::Delete,
            "insert" | "ins" => KeyCode::Insert,
            _ => {
                if let Some(number) = key
                    .to_ascii_lowercase()
                    .strip_prefix('f')
                    .and_then(|n| n.parse::<u8>().ok())
                {
                    if (1..=12).contains(&number) {
                        KeyCode::F(number)
                    } else {
                        return Err(format!("unsupported function key `{key}`"));
                    }
                } else {
                    let mut chars = key.chars();
                    let Some(ch) = chars.next().filter(|_| chars.next().is_none()) else {
                        return Err(format!("unsupported key name `{key}`"));
                    };
                    if ch.is_control() {
                        return Err(format!("unsupported key name `{key}`"));
                    }
                    if ch.is_ascii_uppercase() {
                        modifiers |= KeyModifiers::SHIFT;
                    }
                    KeyCode::Char(ch)
                }
            }
        };
        if code == KeyCode::Tab && modifiers.contains(KeyModifiers::SHIFT) {
            code = KeyCode::BackTab;
            modifiers.remove(KeyModifiers::SHIFT);
        }
        if code == KeyCode::BackTab {
            modifiers |= KeyModifiers::SHIFT;
        }
        Ok(Self { code, modifiers })
    }

    pub fn matches(&self, event: KeyEvent) -> bool {
        if self.code != event.code {
            return false;
        }
        if self.modifiers.is_empty() {
            return event.modifiers.is_empty();
        }
        if self.code == KeyCode::BackTab {
            return event.modifiers.contains(KeyModifiers::SHIFT) || event.code == KeyCode::BackTab;
        }
        if let (KeyCode::Char(expected), KeyCode::Char(actual)) = (self.code, event.code) {
            let shift_expected = self.modifiers.contains(KeyModifiers::SHIFT);
            let normalized_expected = if shift_expected {
                expected.to_ascii_lowercase()
            } else {
                expected
            };
            let shift_actual =
                actual.is_uppercase() || event.modifiers.contains(KeyModifiers::SHIFT);
            let expected_other = self.modifiers.difference(KeyModifiers::SHIFT);
            let actual_other = event.modifiers.difference(KeyModifiers::SHIFT);
            return expected_other == actual_other
                && normalized_expected == actual.to_ascii_lowercase()
                && shift_expected == shift_actual;
        }
        event.modifiers == self.modifiers
    }

    pub fn display(&self) -> String {
        let mut out = String::new();
        if self.modifiers.contains(KeyModifiers::CONTROL) {
            out.push_str("Ctrl+");
        }
        if self.modifiers.contains(KeyModifiers::ALT) {
            out.push_str("Alt+");
        }
        if self.modifiers.contains(KeyModifiers::SUPER) {
            out.push_str("Super+");
        }
        if self.modifiers.contains(KeyModifiers::SHIFT) && self.code != KeyCode::BackTab {
            out.push_str("Shift+");
        }
        out.push_str(&match self.code {
            KeyCode::BackTab => "Shift+Tab".into(),
            KeyCode::Char(' ') => "Space".into(),
            KeyCode::Char(ch) => ch.to_string(),
            KeyCode::Enter => "Enter".into(),
            KeyCode::Esc => "Esc".into(),
            KeyCode::Left => "Left".into(),
            KeyCode::Right => "Right".into(),
            KeyCode::Up => "Up".into(),
            KeyCode::Down => "Down".into(),
            KeyCode::PageUp => "PgUp".into(),
            KeyCode::PageDown => "PgDn".into(),
            KeyCode::Delete => "Delete".into(),
            KeyCode::Insert => "Insert".into(),
            KeyCode::Home => "Home".into(),
            KeyCode::End => "End".into(),
            KeyCode::F(n) => format!("F{n}"),
            other => format!("{other:?}"),
        });
        out
    }
}

impl Serialize for KeyChord {
    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(&self.display())
    }
}

impl<'de> Deserialize<'de> for KeyChord {
    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let value = String::deserialize(deserializer)?;
        Self::parse(&value).map_err(D::Error::custom)
    }
}

impl fmt::Display for KeyChord {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(&self.display())
    }
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct EffectiveBindings {
    modes: HashMap<InputContext, HashMap<TuiAction, Vec<KeyChord>>>,
}

fn chord(value: &str) -> KeyChord {
    KeyChord::parse(value).expect("built-in key chord must parse")
}

fn set(map: &mut HashMap<TuiAction, Vec<KeyChord>>, action: TuiAction, values: &[&str]) {
    map.insert(action, values.iter().map(|value| chord(value)).collect());
}

impl KeyBindings {
    pub fn resolve(overrides: &KeyBindings) -> Result<EffectiveBindings> {
        let mut effective = EffectiveBindings::default();
        for context in InputContext::ALL {
            let mut mode = default_mode(*context);
            overlay(&mut mode, overrides.overrides(*context), *context)?;
            effective.modes.insert(*context, mode);
        }
        Ok(effective)
    }
}

impl EffectiveBindings {
    pub fn action(&self, context: InputContext, event: KeyEvent) -> Option<TuiAction> {
        self.modes
            .get(&context)?
            .iter()
            .find_map(|(action, chords)| {
                chords
                    .iter()
                    .any(|key| key.matches(event))
                    .then_some(*action)
            })
    }

    /// Every action this context binds, sorted by name so the order is stable.
    ///
    /// For the help overlay's completeness guard: that overlay's per-context action
    /// list is written by hand, and a binding it does not name is a key that works and
    /// that nobody can discover.
    pub fn bound_actions(&self, context: InputContext) -> Vec<TuiAction> {
        let mut actions: Vec<TuiAction> = self
            .modes
            .get(&context)
            .map(|mode| mode.keys().copied().collect())
            .unwrap_or_default();
        actions.sort_by_key(|action| action.as_str());
        actions
    }

    pub fn chords(&self, context: InputContext, action: TuiAction) -> &[KeyChord] {
        self.modes
            .get(&context)
            .and_then(|mode| mode.get(&action))
            .map(Vec::as_slice)
            .unwrap_or_default()
    }

    pub fn label(&self, context: InputContext, action: TuiAction) -> String {
        let labels: Vec<String> = self
            .chords(context, action)
            .iter()
            .map(ToString::to_string)
            .collect();
        if labels.is_empty() {
            "—".into()
        } else {
            labels.join(" / ")
        }
    }

    pub fn canonical_event(&self, context: InputContext, action: TuiAction) -> KeyEvent {
        let (code, modifiers) = match (context, action) {
            (_, TuiAction::ReorderUp) => (KeyCode::Up, KeyModifiers::CONTROL),
            (_, TuiAction::ReorderDown) => (KeyCode::Down, KeyModifiers::CONTROL),
            (InputContext::Rollover, TuiAction::Previous) => (KeyCode::Tab, KeyModifiers::NONE),
            (InputContext::PlanningManagement, TuiAction::Next) => {
                (KeyCode::Tab, KeyModifiers::NONE)
            }
            (InputContext::FormPicker, TuiAction::Next) => (KeyCode::Up, KeyModifiers::NONE),
            (InputContext::FormPicker, TuiAction::Previous) => (KeyCode::Down, KeyModifiers::NONE),
            (InputContext::DatePicker, TuiAction::PreviousYear) => {
                (KeyCode::Char('['), KeyModifiers::NONE)
            }
            (InputContext::DatePicker, TuiAction::NextYear) => {
                (KeyCode::Char(']'), KeyModifiers::NONE)
            }
            (InputContext::DatePicker, TuiAction::PreviousMonth) => {
                (KeyCode::PageUp, KeyModifiers::NONE)
            }
            (InputContext::DatePicker, TuiAction::NextMonth) => {
                (KeyCode::PageDown, KeyModifiers::NONE)
            }
            (InputContext::DatePicker, TuiAction::Reset) => (KeyCode::Delete, KeyModifiers::NONE),
            (InputContext::Settings, TuiAction::NewBoard) => {
                (KeyCode::Char('n'), KeyModifiers::NONE)
            }
            (InputContext::Settings, TuiAction::Delete) => (KeyCode::Char('x'), KeyModifiers::NONE),
            // #1441/#1442: `scroll_up`/`scroll_down` are **page** steps and must
            // canonicalize to themselves. The generic arms below fold them into
            // Up/Down, which is what made the detail pane's `PgUp`/`PgDn` arms dead
            // code: the key arrived canonicalized as `Down` and moved the
            // relationship cursor instead of scrolling, so a bound key did something
            // other than what it was bound to. These arms sit above the generics
            // because the match is top-down.
            (_, TuiAction::ScrollUp) => (KeyCode::PageUp, KeyModifiers::NONE),
            (_, TuiAction::ScrollDown) => (KeyCode::PageDown, KeyModifiers::NONE),
            (_, TuiAction::MoveUp | TuiAction::Previous) => (KeyCode::Up, KeyModifiers::NONE),
            (_, TuiAction::MoveDown | TuiAction::Next) => (KeyCode::Down, KeyModifiers::NONE),
            (_, TuiAction::MoveLeft) => (KeyCode::Left, KeyModifiers::NONE),
            (_, TuiAction::MoveRight) => (KeyCode::Right, KeyModifiers::NONE),
            (_, TuiAction::PreviousBoard) => (KeyCode::BackTab, KeyModifiers::NONE),
            (_, TuiAction::NextBoard) => (KeyCode::Tab, KeyModifiers::NONE),
            (_, TuiAction::Submit | TuiAction::Open | TuiAction::Ignore) => {
                (KeyCode::Enter, KeyModifiers::NONE)
            }
            (_, TuiAction::NewIssue) => (KeyCode::Char('n'), KeyModifiers::NONE),
            (_, TuiAction::CloneIssue) => (KeyCode::Char('C'), KeyModifiers::NONE),
            (_, TuiAction::ToggleArchived) => (KeyCode::Char('a'), KeyModifiers::NONE),
            (_, TuiAction::ToggleChildren) => (KeyCode::Char('u'), KeyModifiers::NONE),
            (_, TuiAction::Edit | TuiAction::EditPlanningItem) => {
                (KeyCode::Char('e'), KeyModifiers::NONE)
            }
            (_, TuiAction::Agent) => (KeyCode::Char('A'), KeyModifiers::NONE),
            (_, TuiAction::View) => (KeyCode::Char('v'), KeyModifiers::NONE),
            (_, TuiAction::ToggleColumn | TuiAction::Comment) => {
                (KeyCode::Char('c'), KeyModifiers::NONE)
            }
            (_, TuiAction::FilterModal) => (KeyCode::Char('f'), KeyModifiers::NONE),
            (_, TuiAction::BulkModal) => (KeyCode::Char('B'), KeyModifiers::NONE),
            (_, TuiAction::Triage) => (KeyCode::Char('t'), KeyModifiers::NONE),
            (_, TuiAction::Mark) => (KeyCode::Char(' '), KeyModifiers::NONE),
            (_, TuiAction::Unmark) => (KeyCode::Char('x'), KeyModifiers::NONE),
            (_, TuiAction::MovePrevious) => (KeyCode::Char('<'), KeyModifiers::NONE),
            (_, TuiAction::MoveNext) => (KeyCode::Char('>'), KeyModifiers::NONE),
            (_, TuiAction::Delete) => (KeyCode::Char('d'), KeyModifiers::NONE),
            (_, TuiAction::DeletePlanningItem) => (KeyCode::Char('x'), KeyModifiers::NONE),
            (_, TuiAction::Refresh | TuiAction::Reset | TuiAction::Reedit) => {
                (KeyCode::Char('r'), KeyModifiers::NONE)
            }
            (_, TuiAction::Settings) => (KeyCode::Char('s'), KeyModifiers::NONE),
            (_, TuiAction::Planning) => (KeyCode::Char('m'), KeyModifiers::NONE),
            (_, TuiAction::NewPlanningItem) => (KeyCode::Char('n'), KeyModifiers::NONE),
            (_, TuiAction::NewBoard) => (KeyCode::Char('b'), KeyModifiers::NONE),
            (_, TuiAction::AddColumn) => (KeyCode::Char('a'), KeyModifiers::NONE),
            (_, TuiAction::Help) => (KeyCode::Char('?'), KeyModifiers::NONE),
            (_, TuiAction::Quit) => (KeyCode::Char('q'), KeyModifiers::NONE),
            (_, TuiAction::TextFilter) => (KeyCode::Char('/'), KeyModifiers::NONE),
            (_, TuiAction::Close | TuiAction::Cancel) => (KeyCode::Esc, KeyModifiers::NONE),
            (_, TuiAction::Asset) => (KeyCode::Char('a'), KeyModifiers::NONE),
            // #1359. `e` is the editor in the detail view, so re-kind is `E` — the
            // same relationship the CLI's `tix link edit <id>` changes.
            (_, TuiAction::NewRelationship) => (KeyCode::Char('n'), KeyModifiers::NONE),
            (_, TuiAction::EditRelationship) => (KeyCode::Char('E'), KeyModifiers::SHIFT),
            (_, TuiAction::RemoveRelationship) => (KeyCode::Char('d'), KeyModifiers::NONE),
            (_, TuiAction::NextRelationship) => (KeyCode::Char('j'), KeyModifiers::NONE),
            (_, TuiAction::PreviousRelationship) => (KeyCode::Char('k'), KeyModifiers::NONE),
            // #1513. The three related-navigation actions hand the handler the
            // key they advertise — without these arms the generic catch-all
            // would fold them into `Esc`, and `o` on a related entry would close
            // the pane instead of following the link.
            (_, TuiAction::RelatedPicker) => (KeyCode::Char('r'), KeyModifiers::NONE),
            (_, TuiAction::FollowRelated) => (KeyCode::Char('o'), KeyModifiers::NONE),
            (_, TuiAction::NavBack) => (KeyCode::Backspace, KeyModifiers::NONE),
            (_, TuiAction::OpenPicker) => (KeyCode::F(2), KeyModifiers::NONE),
            // The shell's mode switches. `F(2)` is also `open_picker`'s canonical
            // event — they are different actions in different contexts, which is
            // exactly why mode switching is scoped to the shell context and a form's
            // `F2` keeps its picker meaning.
            (_, TuiAction::SwitchToBoard) => (KeyCode::F(3), KeyModifiers::NONE),
            (_, TuiAction::SwitchToTriage) => (KeyCode::F(2), KeyModifiers::NONE),
            (_, TuiAction::SwitchToCycle) => (KeyCode::F(4), KeyModifiers::NONE),
            (_, TuiAction::SwitchToMilestones) => (KeyCode::F(5), KeyModifiers::NONE),
            (_, TuiAction::SwitchToNewIssue) => (KeyCode::F(1), KeyModifiers::NONE),
            (_, TuiAction::SwitchToConfig) => (KeyCode::F(12), KeyModifiers::NONE),
            (_, TuiAction::ToggleNavigation) => (KeyCode::Char('n'), KeyModifiers::CONTROL),
            (_, TuiAction::Toggle) => (KeyCode::Char(' '), KeyModifiers::NONE),
            (_, TuiAction::Confirm) => (KeyCode::Char('y'), KeyModifiers::NONE),
            // #1506. The repair prompt's own two decisions canonicalize to the
            // keys the prompt advertises, so `handle_edit_repair_key` reads a
            // canonical `d`/`x` however the user reached the action.
            (_, TuiAction::DeclareKey) => (KeyCode::Char('d'), KeyModifiers::NONE),
            (_, TuiAction::Discard) => (KeyCode::Char('x'), KeyModifiers::NONE),
            (_, TuiAction::Create) => (KeyCode::Char('+'), KeyModifiers::NONE),
            _ => (KeyCode::Esc, KeyModifiers::NONE),
        };
        KeyEvent::new(code, modifiers)
    }
}

fn defaults(values: &[(&str, &[&str])]) -> HashMap<TuiAction, Vec<KeyChord>> {
    let mut map = HashMap::new();
    for (action, keys) in values {
        let action = match *action {
            "move_up" => TuiAction::MoveUp,
            "move_down" => TuiAction::MoveDown,
            "move_left" => TuiAction::MoveLeft,
            "move_right" => TuiAction::MoveRight,
            "next_board" => TuiAction::NextBoard,
            "previous_board" => TuiAction::PreviousBoard,
            "open" => TuiAction::Open,
            "edit" => TuiAction::Edit,
            "agent" => TuiAction::Agent,
            "view" => TuiAction::View,
            "toggle_column" => TuiAction::ToggleColumn,
            "filter_modal" => TuiAction::FilterModal,
            "bulk_modal" => TuiAction::BulkModal,
            "triage" => TuiAction::Triage,
            "mark" => TuiAction::Mark,
            "unmark" => TuiAction::Unmark,
            "move_previous" => TuiAction::MovePrevious,
            "move_next" => TuiAction::MoveNext,
            "new_issue" => TuiAction::NewIssue,
            "clone_issue" => TuiAction::CloneIssue,
            "toggle_archived" => TuiAction::ToggleArchived,
            "toggle_children" => TuiAction::ToggleChildren,
            "delete" => TuiAction::Delete,
            "refresh" => TuiAction::Refresh,
            "settings" => TuiAction::Settings,
            "planning" => TuiAction::Planning,
            "new_board" => TuiAction::NewBoard,
            "help" => TuiAction::Help,
            "quit" => TuiAction::Quit,
            "text_filter" => TuiAction::TextFilter,
            "reorder_up" => TuiAction::ReorderUp,
            "reorder_down" => TuiAction::ReorderDown,
            "close" => TuiAction::Close,
            "scroll_up" => TuiAction::ScrollUp,
            "scroll_down" => TuiAction::ScrollDown,
            "comment" => TuiAction::Comment,
            "asset" => TuiAction::Asset,
            "new_relationship" => TuiAction::NewRelationship,
            "edit_relationship" => TuiAction::EditRelationship,
            "remove_relationship" => TuiAction::RemoveRelationship,
            "next_relationship" => TuiAction::NextRelationship,
            "previous_relationship" => TuiAction::PreviousRelationship,
            "related_picker" => TuiAction::RelatedPicker,
            "follow_related" => TuiAction::FollowRelated,
            "nav_back" => TuiAction::NavBack,
            "submit" => TuiAction::Submit,
            "cancel" => TuiAction::Cancel,
            "next" => TuiAction::Next,
            "previous" => TuiAction::Previous,
            "open_picker" => TuiAction::OpenPicker,
            "reset" => TuiAction::Reset,
            "toggle" => TuiAction::Toggle,
            "add_column" => TuiAction::AddColumn,
            "new_planning_item" => TuiAction::NewPlanningItem,
            "edit_planning_item" => TuiAction::EditPlanningItem,
            "delete_planning_item" => TuiAction::DeletePlanningItem,
            "confirm" => TuiAction::Confirm,
            "create" => TuiAction::Create,
            "previous_year" => TuiAction::PreviousYear,
            "next_year" => TuiAction::NextYear,
            "previous_month" => TuiAction::PreviousMonth,
            "next_month" => TuiAction::NextMonth,
            "reedit" => TuiAction::Reedit,
            "ignore" => TuiAction::Ignore,
            "declare_key" => TuiAction::DeclareKey,
            "discard" => TuiAction::Discard,
            "switch_to_board" => TuiAction::SwitchToBoard,
            "switch_to_triage" => TuiAction::SwitchToTriage,
            "switch_to_cycle" => TuiAction::SwitchToCycle,
            "switch_to_milestones" => TuiAction::SwitchToMilestones,
            "switch_to_new_issue" => TuiAction::SwitchToNewIssue,
            "switch_to_config" => TuiAction::SwitchToConfig,
            "toggle_navigation" => TuiAction::ToggleNavigation,
            _ => unreachable!(),
        };
        set(&mut map, action, keys);
    }
    map
}

fn default_mode(context: InputContext) -> HashMap<TuiAction, Vec<KeyChord>> {
    match context {
        InputContext::Board => defaults(&[
            ("move_up", &["up", "k"]),
            ("move_down", &["down", "j"]),
            // tix #1442 (follow-up): a screen of cards. They have to be *bound* for the
            // board to see them at all: `App::handle_key` routes an unbound key in a
            // non-text context to `F(12)` rather than passing it through, which is why
            // `PgUp`/`PgDn` did nothing here while the wheel next to them worked. They
            // canonicalize to `PageUp`/`PageDown`, so the handler can tell a page from
            // a row.
            ("scroll_up", &["pgup"]),
            ("scroll_down", &["pgdn"]),
            ("move_left", &["left", "h"]),
            ("move_right", &["right", "l"]),
            ("next_board", &["tab"]),
            ("previous_board", &["shift+tab"]),
            ("open", &["enter"]),
            ("edit", &["e"]),
            // #1507: read the selected card in the resolved viewer, read-only.
            ("view", &["v"]),
            ("agent", &["A"]),
            ("toggle_column", &["c"]),
            ("filter_modal", &["f"]),
            ("bulk_modal", &["B"]),
            // WP06: the triage inbox. `t` was unbound, so this adds a key
            // rather than changing what any existing one means.
            ("triage", &["t"]),
            // The chord is spelled `space`, not a literal blank: `KeyChord::parse`
            // trims its input, so a bare `" "` is the empty chord and every
            // built-in binding panics at startup.
            ("mark", &["space"]),
            ("unmark", &["x"]),
            ("move_previous", &["<"]),
            ("move_next", &[">"]),
            ("new_issue", &["n"]),
            // #1484: the capital of `c` (toggle column), not a new letter — the
            // board's free letters are its navigation, and `C` keeps "clone" beside
            // the toggle it is the second half of.
            ("clone_issue", &["C"]),
            // #1492: `a` was free on the board, and "archived" is what it means.
            ("toggle_archived", &["a"]),
            // #1399: `u` was free on the board; "sub-issues" is what it shows.
            ("toggle_children", &["u"]),
            ("delete", &["d"]),
            ("refresh", &["r"]),
            ("settings", &["s"]),
            ("planning", &["m", "M"]),
            ("new_board", &["b"]),
            ("help", &["?"]),
            ("quit", &["q", "Q", "esc"]),
            ("text_filter", &["/"]),
            ("reorder_up", &["ctrl+up"]),
            ("reorder_down", &["ctrl+down"]),
        ]),
        InputContext::Rollover => defaults(&[
            ("submit", &["enter"]),
            ("previous", &["left", "right", "tab"]),
            ("cancel", &["esc"]),
        ]),
        InputContext::Detail => defaults(&[
            ("close", &["q", "Q", "esc"]),
            ("edit", &["e"]),
            // #1507: view the open issue in the resolved read-only viewer.
            ("view", &["v"]),
            ("scroll_up", &["pgup"]),
            ("scroll_down", &["pgdn"]),
            ("help", &["?"]),
            ("comment", &["c"]),
            ("asset", &["a"]),
            // #1359: the three mutating relationship operations, plus the cursor
            // that names which edge `E` and `d` act on. `e` stays the editor, so
            // re-kind is `E`.
            ("new_relationship", &["n"]),
            ("edit_relationship", &["E"]),
            ("remove_relationship", &["d"]),
            ("next_relationship", &["j", "down"]),
            ("previous_relationship", &["k", "up"]),
            // #1513: the related-issues surface. `r` lists them, `o` follows the
            // selected one, `Backspace` returns to the previous pane. `j`/`k`
            // keep moving the **relationship** cursor; the picker is the
            // selection surface for related entries.
            ("related_picker", &["r"]),
            ("follow_related", &["o"]),
            ("nav_back", &["backspace"]),
        ]),
        InputContext::RelatedPicker => defaults(&[
            ("cancel", &["esc"]),
            ("next", &["down"]),
            ("previous", &["up"]),
            ("submit", &["enter"]),
        ]),
        InputContext::Form | InputContext::PlanningForm => defaults(&[
            ("cancel", &["esc"]),
            ("submit", &["enter"]),
            ("next", &["tab", "down"]),
            ("previous", &["shift+tab", "up"]),
            ("open_picker", &["f2"]),
        ]),
        InputContext::FormPicker => defaults(&[
            ("cancel", &["esc", "f2"]),
            ("next", &["up"]),
            ("previous", &["down"]),
            ("submit", &["enter"]),
            ("create", &["+", "insert"]),
        ]),
        InputContext::ConfirmDelete => defaults(&[("confirm", &["y", "Y"]), ("cancel", &["esc"])]),
        // `n` cancels as well as `esc`: a yes/no prompt whose only "no" is a
        // non-printing key is a trap for anyone who does not know it.
        InputContext::ConfirmBlockedMove => defaults(&[
            ("confirm", &["y", "Y", "enter"]),
            ("cancel", &["n", "N", "esc"]),
        ]),
        // Free-text entry. `cancel` is **`esc` only**, and that is load-bearing
        // rather than a style choice.
        //
        // All four of these read arbitrary text into a buffer — a commit message, a
        // comment body, a **filesystem path**, a filter string. Binding `q` to cancel
        // means the letter `q` cannot be typed, and it is worse than that: the
        // binding resolves to the action's canonical event (`esc`), so `q` does not
        // merely fail to type, it **leaves the mode**, and every character after it
        // is then interpreted as a command in the mode underneath.
        //
        // This was found by a test flake (#1305), not by inspection. The asset
        // round-trip test types the source path through `handle_key`, and the path
        // came from a `tempfile` temp directory whose six random characters are drawn
        // from `[A-Za-z0-9]`. Roughly one run in forty produced a name containing a
        // `q`; the prompt closed mid-path and the rest of the string was applied as
        // Detail-mode keys — which is how a run came to report
        // `status = "Commented by …"` and no asset at all. A user attaching an asset
        // from a path containing `q` gets the same thing, and it silently creates a
        // comment on the issue.
        //
        // The test was at fault for depending on a random name, but the behaviour is
        // a real defect, so the binding moves rather than the fixture. `esc` remains
        // the cancel key, which is already this codebase's convention for text entry
        // — `FilterModal` and `ConfirmDelete` both bind `esc` and nothing else.
        //
        // `q`-to-close is kept where there is no text to type: `Help`,
        // `ContextMenu`, `Settings`, `PlanningManagement`, `DatePicker`, and the
        // yes/no `ConfirmBlockedMove` keep it.
        InputContext::MoveIntoDone
        | InputContext::Comment
        | InputContext::Asset
        | InputContext::Filter => defaults(&[("cancel", &["esc"]), ("submit", &["enter"])]),
        // The overlay and the context menu are *not* the same surface, and sharing a
        // context made them one: a binding added for the overlay (`pgup`/`pgdn`, tix
        // #1441) would silently become a context-menu key too. They share a key set
        // today only by coincidence, so they get their own arms.
        InputContext::Help => defaults(&[
            ("cancel", &["esc", "q", "?"]),
            ("next", &["down", "j"]),
            ("previous", &["up", "k"]),
            ("submit", &["enter"]),
            // #1496: `/` filters the list. Bound rather than handled as a raw key so it
            // is rebindable like everything else — and so the overlay's own rows name
            // it, since a search nobody knows about is a search nobody uses.
            ("text_filter", &["/"]),
            // #1441/#1442: one page at a time. These have to be *bound* for the
            // overlay to see them at all — `App::handle_key` routes an unbound key in
            // a non-text context to `F(12)` rather than passing it through — and they
            // canonicalize to themselves so the handler can tell a page from a row.
            ("scroll_up", &["pgup"]),
            ("scroll_down", &["pgdn"]),
        ]),
        InputContext::ContextMenu => defaults(&[
            ("cancel", &["esc", "q", "?"]),
            ("next", &["down", "j"]),
            ("previous", &["up", "k"]),
            ("submit", &["enter"]),
        ]),
        // The overlay's `/` input (tix #1496): free text, so `cancel` is `Esc` and only
        // `Esc`. `q` and `?` stay ordinary characters here — binding them to cancel
        // would rewrite them to `esc` inside `App::handle_key`, before the handler saw
        // them, and a query could never contain a `q`.
        InputContext::HelpSearch => defaults(&[("cancel", &["esc"]), ("submit", &["enter"])]),
        InputContext::BulkModal => defaults(&[
            ("cancel", &["esc"]),
            ("next", &["tab", "down"]),
            ("previous", &["shift+tab", "up"]),
            ("submit", &["enter"]),
        ]),
        // WP06. Five bindings and nothing else, because every remaining inbox
        // key (`q`, `j`, `k`, `a`, `d`, `u`, `f`, `p`, `y`, `?`) has to arrive
        // **raw**: a decline reason containing `q` and a duplicate target
        // containing `a` are ordinary, and `allows_text_fallback` is what keeps
        // them letters instead of turning them into a close or an accept.
        InputContext::Triage => defaults(&[
            ("cancel", &["esc"]),
            ("submit", &["enter"]),
            ("move_up", &["up"]),
            ("move_down", &["down"]),
            ("toggle", &["space"]),
        ]),
        // The F3 Cycle mode (tui-cycle-mode). `m` opens the planning-management
        // surface for the same reason the board binds it: it is where cycles and
        // milestones are created, renamed, and deleted. Nothing here collides with
        // the surface's own keys, so opening it from this mode is unambiguous.
        InputContext::Cycle => defaults(&[
            ("close", &["q", "Q", "esc"]),
            ("move_up", &["up", "k"]),
            ("move_down", &["down", "j"]),
            // The listing's horizontal axis: `h`/`l` and the arrows land on the
            // first entry of the previous / next rendered group.
            ("move_left", &["left", "h"]),
            ("move_right", &["right", "l"]),
            ("planning", &["m"]),
            ("help", &["?"]),
        ]),
        // The F5 Milestones mode. `m`, `j`/`k`, `q`/`esc` mirror the Cycle
        // listing: it is the same kind of registry view. The planning commands
        // (`n`/`e`/`x`, `Enter` to edit) are bound here too, so the milestone
        // registry is editable from its own mode and not only from F12.
        InputContext::Milestones => defaults(&[
            ("close", &["q", "Q", "esc"]),
            ("move_up", &["up", "k"]),
            ("move_down", &["down", "j"]),
            ("submit", &["enter"]),
            ("new_planning_item", &["n"]),
            ("edit_planning_item", &["e"]),
            ("delete_planning_item", &["x", "X"]),
            ("planning", &["m"]),
            ("help", &["?"]),
        ]),
        InputContext::FilterModal => defaults(&[
            ("cancel", &["esc"]),
            ("next", &["tab", "down"]),
            ("previous", &["shift+tab", "up"]),
            ("reset", &["r", "R"]),
            ("submit", &["enter"]),
            ("open_picker", &["f2"]),
        ]),
        // The F12 Config mode's sections (tui-config-mode). The dashboards
        // section edits the active board, so `tab`/`shift+tab` switch boards
        // (`next_board`/`previous_board`, whose canonical events are Tab and
        // BackTab). `left`/`right` move the pane focus between the section rail
        // and the body, and `up`/`down` move inside the focused pane — the
        // section when the rail is focused, the row when the body is. `n`/`e`/`x`
        // are the new/rename/delete keys in both the dashboards section and the
        // cycles/milestones sections — the section decides what they act on.
        //
        // `enter` is `submit`, not a second `toggle` chord: it steps from the
        // rail into the body and then activates the row, while `space` keeps
        // toggling wherever the cursor is. Both bound to `toggle` would
        // canonicalize to the same event and there would be no Enter behaviour
        // to implement.
        InputContext::Settings => defaults(&[
            ("close", &["q", "Q", "esc"]),
            ("next_board", &["tab", "]"]),
            ("previous_board", &["shift+tab", "["]),
            ("move_left", &["left", "h"]),
            ("move_right", &["right", "l"]),
            ("move_up", &["up", "k"]),
            ("move_down", &["down", "j"]),
            ("toggle", &["space"]),
            ("submit", &["enter"]),
            ("add_column", &["a"]),
            ("new_board", &["n"]),
            ("edit_planning_item", &["e"]),
            ("delete", &["x", "X"]),
        ]),
        InputContext::SettingsPrompt => defaults(&[
            ("cancel", &["esc", "q", "Q"]),
            ("submit", &["enter", "y", "Y"]),
        ]),
        InputContext::PlanningManagement => defaults(&[
            ("close", &["q", "Q", "esc"]),
            ("move_up", &["up", "k"]),
            ("move_down", &["down", "j"]),
            // The segments (Cycles / Milestones) are a horizontal axis, so the
            // horizontal movement keys switch them — the same rule the Config
            // rail's vertical section list deliberately does not follow: there
            // `h`/`l` are the pane axis and `j`/`k` walk the sections.
            ("move_left", &["left", "h"]),
            ("move_right", &["right", "l"]),
            ("next", &["tab", "shift+tab"]),
            ("new_planning_item", &["n"]),
            ("edit_planning_item", &["e"]),
            ("delete_planning_item", &["x", "X"]),
        ]),
        InputContext::PlanningConfirm => {
            defaults(&[("confirm", &["y", "Y", "enter"]), ("cancel", &["esc"])])
        }
        InputContext::DatePicker => defaults(&[
            ("cancel", &["esc", "q"]),
            ("submit", &["enter"]),
            ("move_up", &["up", "k"]),
            ("move_down", &["down", "j"]),
            ("move_left", &["left", "h"]),
            ("move_right", &["right", "l"]),
            ("previous_month", &["pgup"]),
            ("next_month", &["pgdn"]),
            ("previous_year", &["["]),
            ("next_year", &["]"]),
            ("reset", &["delete", "c", "C"]),
        ]),
        // #1506/#1510. The repair prompt the editor round trip raises when the
        // saved file has a problem: apply the proposed fix, declare the key,
        // reopen the editor on the retained copy, acknowledge, or discard.
        // `confirm` keeps `a`/`y` — the chord #1506's warning advertised — and
        // every other key is a decision, never a stray exit. `discard` is `x`
        // and requires a second press; `Esc` acknowledges and **keeps** the copy.
        InputContext::EditRepair => defaults(&[
            ("confirm", &["a", "y"]),
            ("declare_key", &["d", "D"]),
            ("reedit", &["r", "R"]),
            ("ignore", &["i", "I", "enter", "esc"]),
            ("discard", &["x", "X"]),
        ]),
        // #1510. The conflict prompt: overwrite, abandon, compare. The chords are
        // the ones the handler's arms key on — `handle_key` rewrites a bound key to
        // its action's canonical event, which is `y` for `confirm`, `Enter` for
        // `ignore`, and `r` for `reedit` — so every chord listed here arrives as
        // that canonical code. `Esc` is bound to `ignore`, which is what makes it
        // the safe default the prompt promises. `q` is deliberately *not* bound:
        // the prompt closes only through a decision it names.
        InputContext::EditConflict => defaults(&[
            ("confirm", &["o", "O", "y", "Y"]),
            ("ignore", &["a", "A", "esc"]),
            ("reedit", &["c", "C", "r", "R"]),
        ]),
        // The mode shell (tui-mode-navigation). Five switches and a display-state
        // toggle, nothing else: every other key belongs to the active mode, and this
        // context is consulted only when that mode declines the key.
        InputContext::Shell => defaults(&[
            ("switch_to_new_issue", &["f1"]),
            ("switch_to_triage", &["f2"]),
            ("switch_to_board", &["f3"]),
            ("switch_to_cycle", &["f4"]),
            ("switch_to_milestones", &["f5"]),
            ("switch_to_config", &["f12"]),
            ("toggle_navigation", &["ctrl+n"]),
        ]),
        // #1359. Free text, so `q` must be typeable: a title fragment or a path
        // containing `q` is unremarkable, and binding it to cancel closes the prompt
        // and applies the rest of the input as commands underneath. See the note on
        // the `Asset`/`Comment`/`Filter` group for the full reasoning.
        InputContext::LinkPrompt => defaults(&[("cancel", &["esc"]), ("submit", &["enter"])]),
    }
}

macro_rules! overlay_fields {
    ($map:ident, $overrides:ident, $context:expr, $($field:ident => $action:ident),+ $(,)?) => {
        $(
            if let Some(values) = &$overrides.$field {
                let mut chords = Vec::with_capacity(values.len());
                for value in values {
                    chords.push(KeyChord::parse(value).map_err(|message| TixError::Config(format!(
                        "`keybindings.{}.{}`: {message}", $context.as_str(), stringify!($field)
                    )))?);
                }
                if chords.is_empty() {
                    return Err(TixError::Config(format!(
                        "`keybindings.{}.{}` must not be empty", $context.as_str(), stringify!($field)
                    )));
                }
                $map.insert(TuiAction::$action, chords);
            }
        )+
    };
}

fn overlay(
    map: &mut HashMap<TuiAction, Vec<KeyChord>>,
    overrides: &ActionBindings,
    context: InputContext,
) -> Result<()> {
    overlay_fields!(map, overrides, context,
        move_up => MoveUp, move_down => MoveDown, move_left => MoveLeft, move_right => MoveRight,
        next_board => NextBoard, previous_board => PreviousBoard, open => Open, edit => Edit,
        agent => Agent, view => View, toggle_column => ToggleColumn, filter_modal => FilterModal,
        bulk_modal => BulkModal, mark => Mark, unmark => Unmark, triage => Triage,
        move_previous => MovePrevious, move_next => MoveNext, new_issue => NewIssue,
        clone_issue => CloneIssue,
        toggle_archived => ToggleArchived,
        toggle_children => ToggleChildren,
        delete => Delete, refresh => Refresh, settings => Settings, planning => Planning,
        new_board => NewBoard, help => Help, quit => Quit, text_filter => TextFilter, reorder_up => ReorderUp,
        reorder_down => ReorderDown, close => Close, scroll_up => ScrollUp, scroll_down => ScrollDown,
        comment => Comment, asset => Asset, submit => Submit, cancel => Cancel, next => Next,
        previous => Previous, open_picker => OpenPicker, reset => Reset, toggle => Toggle,
        add_column => AddColumn, new_planning_item => NewPlanningItem,
        edit_planning_item => EditPlanningItem, delete_planning_item => DeletePlanningItem,
        confirm => Confirm, create => Create, previous_year => PreviousYear, next_year => NextYear,
        previous_month => PreviousMonth, next_month => NextMonth, reedit => Reedit, ignore => Ignore,
        declare_key => DeclareKey, discard => Discard,
        switch_to_board => SwitchToBoard, switch_to_triage => SwitchToTriage,
        switch_to_cycle => SwitchToCycle, switch_to_milestones => SwitchToMilestones,
        switch_to_new_issue => SwitchToNewIssue,
        switch_to_config => SwitchToConfig, toggle_navigation => ToggleNavigation,
    );
    let mut seen: HashMap<KeyChord, TuiAction> = HashMap::new();
    for (action, chords) in map {
        for key in chords {
            if let Some(previous) = seen.insert(*key, *action) {
                return Err(TixError::Config(format!(
                    "`keybindings.{}`: `{}` is assigned to both `{}` and `{}`",
                    context.as_str(),
                    key,
                    previous.as_str(),
                    action.as_str()
                )));
            }
        }
    }
    Ok(())
}

impl ActionBindings {
    pub fn is_empty(&self) -> bool {
        self == &Self::default()
    }
}

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

    #[test]
    fn parses_and_normalizes_documented_chords() {
        assert_eq!(KeyChord::parse("ESC").unwrap(), chord("esc"));
        assert_eq!(KeyChord::parse("Enter").unwrap(), chord("enter"));
        assert_eq!(KeyChord::parse("LEFT").unwrap(), chord("left"));
        assert_eq!(KeyChord::parse("PgUp").unwrap(), chord("pgup"));
        assert_eq!(KeyChord::parse("F2").unwrap(), chord("f2"));
        assert_eq!(KeyChord::parse("Ctrl+UP").unwrap(), chord("ctrl+up"));
        assert_eq!(KeyChord::parse("A").unwrap().display(), "Shift+A");
        assert!(KeyChord::parse("ctrl+wat").is_err());
        assert!(KeyChord::parse("f99").is_err());
    }

    #[test]
    fn defaults_validate_and_cross_mode_reuse_is_allowed() {
        let defaults = KeyBindings::resolve(&KeyBindings::default()).unwrap();
        assert!(
            defaults
                .action(
                    InputContext::Board,
                    KeyEvent::new(KeyCode::Char('q'), KeyModifiers::NONE)
                )
                .is_some()
        );
        let mut overrides = KeyBindings::default();
        overrides.board.open = Some(vec!["f4".into()]);
        overrides.detail.close = Some(vec!["f4".into()]);
        assert!(KeyBindings::resolve(&overrides).is_ok());
    }

    #[test]
    fn board_and_detail_bind_v_to_view() {
        let bindings = KeyBindings::resolve(&KeyBindings::default()).unwrap();
        for context in [InputContext::Board, InputContext::Detail] {
            let event = KeyEvent::new(KeyCode::Char('v'), KeyModifiers::NONE);
            assert_eq!(
                bindings.action(context, event),
                Some(TuiAction::View),
                "{context:?} must bind `v` to view"
            );
            assert_eq!(
                bindings.canonical_event(context, TuiAction::View),
                event,
                "`view` must canonicalize to `v` so the handler sees it as typed"
            );
        }
    }

    /// The conflict prompt's three decisions (#1510): every choice is reachable by
    /// two chords, and each pair resolves to an action whose canonical event is the
    /// code the handler's arms read (`y`, `Enter`, `r`) — the indirection that makes
    /// `Esc` abandon and `c` compare without a chord name in the logic.
    #[test]
    fn the_conflict_prompt_binds_overwrite_abandon_and_compare() {
        let bindings = KeyBindings::resolve(&KeyBindings::default()).unwrap();
        let cases = [
            (KeyCode::Char('o'), TuiAction::Confirm),
            (KeyCode::Char('y'), TuiAction::Confirm),
            (KeyCode::Char('a'), TuiAction::Ignore),
            (KeyCode::Esc, TuiAction::Ignore),
            (KeyCode::Char('c'), TuiAction::Reedit),
            (KeyCode::Char('r'), TuiAction::Reedit),
        ];
        for (code, action) in cases {
            assert_eq!(
                bindings.action(
                    InputContext::EditConflict,
                    KeyEvent::new(code, KeyModifiers::NONE)
                ),
                Some(action),
                "{code:?} must be {action:?} in the conflict prompt"
            );
        }
        // …and the canonical events are what `handle_edit_conflict_key` matches on,
        // so the mapping is asserted rather than assumed.
        for (action, expected) in [
            (TuiAction::Confirm, KeyCode::Char('y')),
            (TuiAction::Ignore, KeyCode::Enter),
            (TuiAction::Reedit, KeyCode::Char('r')),
        ] {
            assert_eq!(
                bindings.canonical_event(InputContext::EditConflict, action),
                KeyEvent::new(expected, KeyModifiers::NONE),
                "{action:?} must hand the handler `{expected:?}`"
            );
        }
        // A key nobody bound does nothing: `q` must not close the prompt.
        assert_eq!(
            bindings.action(
                InputContext::EditConflict,
                KeyEvent::new(KeyCode::Char('q'), KeyModifiers::NONE)
            ),
            None
        );
    }

    #[test]
    fn conflicts_report_mode_and_actions() {
        let mut overrides = KeyBindings::default();
        overrides.board.open = Some(vec!["ctrl+n".into()]);
        overrides.board.new_issue = Some(vec!["ctrl+n".into()]);
        let error = KeyBindings::resolve(&overrides).unwrap_err().to_string();
        assert!(error.contains("board") && error.contains("open") && error.contains("new_issue"));
    }

    #[test]
    fn shell_defaults_resolve_mode_switches_and_toggle() {
        let bindings = KeyBindings::resolve(&KeyBindings::default()).unwrap();
        // F1 New Issue, F2 Triage, F3 Board, F4 Cycles, F5 Milestones, F12 Config.
        let cases = [
            (KeyCode::F(1), TuiAction::SwitchToNewIssue),
            (KeyCode::F(2), TuiAction::SwitchToTriage),
            (KeyCode::F(3), TuiAction::SwitchToBoard),
            (KeyCode::F(4), TuiAction::SwitchToCycle),
            (KeyCode::F(5), TuiAction::SwitchToMilestones),
            (KeyCode::F(12), TuiAction::SwitchToConfig),
        ];
        for (code, action) in cases {
            assert_eq!(
                bindings.action(InputContext::Shell, KeyEvent::new(code, KeyModifiers::NONE)),
                Some(action),
                "{code:?} must switch modes in the shell"
            );
            assert_eq!(
                bindings.canonical_event(InputContext::Shell, action),
                KeyEvent::new(code, KeyModifiers::NONE),
                "{action:?} must canonicalize to its default chord"
            );
        }
        assert_eq!(
            bindings.action(
                InputContext::Shell,
                KeyEvent::new(KeyCode::Char('n'), KeyModifiers::CONTROL)
            ),
            Some(TuiAction::ToggleNavigation)
        );
        // F6..F11 are reserved: the shell context binds nothing there.
        for number in 6..=11 {
            assert_eq!(
                bindings.action(
                    InputContext::Shell,
                    KeyEvent::new(KeyCode::F(number), KeyModifiers::NONE)
                ),
                None,
                "F{number} must stay unbound in the shell"
            );
        }
    }

    #[test]
    fn shell_conflict_reports_both_actions_and_mode() {
        let mut overrides = KeyBindings::default();
        overrides.shell.switch_to_board = Some(vec!["f2".into()]);
        overrides.shell.switch_to_triage = Some(vec!["f2".into()]);
        let error = KeyBindings::resolve(&overrides).unwrap_err().to_string();
        assert!(
            error.contains("shell")
                && error.contains("switch_to_board")
                && error.contains("switch_to_triage"),
            "got {error:?}"
        );
    }
}