tix-tracker 0.10.0

use std::fmt::Write;

use crate::keybindings::{EffectiveBindings, InputContext, KeyBindings, TuiAction};
use crate::ui::nav::TopMode;

pub const MODE_BOARD: &str = "board";
pub const MODE_DETAIL: &str = "detail";
pub const MODE_HELP: &str = "help";
pub const MODE_COMMENT: &str = "comment";
pub const MODE_ASSET: &str = "asset";
pub const MODE_FILTER: &str = "filter";

const MAX_HINT_CHARS: usize = 80;

pub struct Cmd {
    pub key: &'static str,
    pub desc: &'static str,
    pub modes: &'static [&'static str],
    pub mode: &'static str,
}

pub const COMMANDS: &[Cmd] = &[
    Cmd {
        key: "j/k",
        desc: "move up/down",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "n",
        desc: "new issue",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "?",
        desc: "help",
        modes: &[MODE_BOARD, MODE_DETAIL],
        mode: "board/detail",
    },
    Cmd {
        key: "h/l",
        desc: "column",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "enter",
        desc: "open",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "d",
        desc: "delete",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "< / >",
        desc: "move",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "r",
        desc: "refresh",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "/",
        desc: "search",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "f",
        desc: "criteria",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "c",
        desc: "comment",
        modes: &[MODE_DETAIL],
        mode: MODE_DETAIL,
    },
    Cmd {
        key: "a",
        desc: "asset",
        modes: &[MODE_DETAIL],
        mode: MODE_DETAIL,
    },
];

fn actions(context: InputContext) -> &'static [TuiAction] {
    match context {
        InputContext::Board => &[
            TuiAction::Open,
            TuiAction::NewIssue,
            TuiAction::Help,
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Planning,
            // #1399: the sub-issue toggle, so the key is discoverable from the
            // footer rather than only from the help overlay.
            TuiAction::ToggleChildren,
            TuiAction::Quit,
        ],
        InputContext::Detail => &[
            TuiAction::Comment,
            TuiAction::Asset,
            // #1513: the related-issues keys, placed early because the hint bar
            // truncates at 80 columns — a key listed after the relationship group
            // would never be drawn.
            TuiAction::RelatedPicker,
            TuiAction::FollowRelated,
            TuiAction::NavBack,
            // #1359: the three mutating relationship operations and the cursor that
            // names which edge `E` and `d` act on. A binding that exists but is not
            // in the footer is a binding nobody finds.
            TuiAction::NewRelationship,
            TuiAction::NextRelationship,
            TuiAction::PreviousRelationship,
            TuiAction::EditRelationship,
            TuiAction::RemoveRelationship,
            // #1384: set/change/clear the parent. A binding that exists but is not
            // in the footer is a binding nobody finds.
            TuiAction::EditParent,
            // Mission `project-issue-health-status-01M3C8HX` (WP06): the form that
            // records this issue's health.
            TuiAction::HealthForm,
            TuiAction::Edit,
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Help,
        ],
        // The remaining top-level modes' footers. Each names a handful of the
        // bindings effective in that mode, so the hint bar follows the active mode
        // (tui-mode-navigation) instead of always describing the board.
        InputContext::Triage => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::Submit,
            TuiAction::Cancel,
        ],
        // The F3 Cycle mode's own keys: the cycle listing, the group jump, the
        // way into planning management, help, and the way out.
        InputContext::Cycle => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Planning,
            TuiAction::Help,
            TuiAction::Close,
        ],
        // The F5 Milestones mode's footer: the registry cursor and the planning
        // commands, whose labels come from the Milestones context.
        InputContext::Milestones => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Planning,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Help,
            TuiAction::Close,
        ],
        InputContext::Form | InputContext::PlanningForm => &[
            TuiAction::Submit,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::OpenPicker,
            TuiAction::Cancel,
        ],
        InputContext::FormPicker => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::Create,
            TuiAction::Cancel,
        ],
        InputContext::PlanningManagement => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Next,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Close,
        ],
        InputContext::Settings => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::AddColumn,
            TuiAction::MoveColumnUp,
            TuiAction::MoveColumnDown,
            TuiAction::Submit,
            TuiAction::NewBoard,
            TuiAction::EditPlanningItem,
            TuiAction::Delete,
            TuiAction::NextBoard,
            TuiAction::PreviousBoard,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Close,
        ],
        // The shell's own switches, so the mode navigation is discoverable from the
        // footer too.
        InputContext::Shell => &[
            TuiAction::SwitchToBoard,
            TuiAction::SwitchToTriage,
            TuiAction::SwitchToCycle,
            TuiAction::SwitchToMilestones,
            TuiAction::SwitchToRepos,
            TuiAction::SwitchToStats,
            TuiAction::SwitchToSchedule,
            TuiAction::SwitchToLibrary,
            TuiAction::SwitchToPortfolio,
            TuiAction::SwitchToNewIssue,
            TuiAction::SwitchToConfig,
            TuiAction::ToggleNavigation,
        ],
        // The F6 Repos mode's footer (tix #1529).
        InputContext::Repos => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Submit,
            TuiAction::Close,
        ],
        // The F7 Stats page (mission `project-issue-health-status-01M3C8HX`; WP05 adds
        // the Time tab): the row cursor, the two tabs, the Time tab's own commands and
        // the way out. The tabs are advertised because there are two now.
        InputContext::Stats => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::TimeAdd,
            TuiAction::TimeEdit,
            TuiAction::TimeDelete,
            TuiAction::TimeFilter,
            TuiAction::TimeBreakdown,
            TuiAction::TimeHistory,
            TuiAction::Submit,
            TuiAction::Help,
            TuiAction::Close,
        ],
        _ => &[],
    }
}

/// The context whose bindings the hint bar advertises for a top-level mode.
///
/// Hints follow the active mode (tui-mode-navigation). `Detail` is handled by the
/// caller: it is a board-mode surface, so it keeps its own context.
pub const fn hint_context_for_mode(mode: TopMode) -> InputContext {
    match mode {
        TopMode::Board => InputContext::Board,
        TopMode::Triage => InputContext::Triage,
        TopMode::Cycle => InputContext::Cycle,
        TopMode::Milestones => InputContext::Milestones,
        TopMode::Repos => InputContext::Repos,
        TopMode::Stats => InputContext::Stats,
        TopMode::Schedule => InputContext::Schedule,
        TopMode::Library => InputContext::Library,
        TopMode::Portfolio => InputContext::Portfolio,
        TopMode::NewIssue => InputContext::Form,
        TopMode::Config => InputContext::Settings,
    }
}

pub fn hint_bar(active_modes: &[&str]) -> String {
    let bindings =
        KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
    for mode in active_modes {
        if let Some(context) = match *mode {
            MODE_BOARD => Some(InputContext::Board),
            MODE_DETAIL => Some(InputContext::Detail),
            _ => None,
        } {
            return hint_bar_for(&bindings, context);
        }
    }
    String::new()
}

pub fn hint_bar_for(bindings: &EffectiveBindings, context: InputContext) -> String {
    hint_bar_for_with(bindings, context, None)
}

/// The hint bar for `context`, with the `F7` Stats page's rows scoped to `stats_tab`
/// (WP05).
///
/// The hint bar is generated from the binding **context**, which cannot see a tab, so
/// an unscoped bar advertised the Time tab's six commands on the Health tab, where
/// none of them fires — the same defect the help overlay's tab scoping fixed, found in
/// the footer by a reviewer. `Some(tab)` names the tab's own rows; `None` names the
/// context's in full, which is what a caller that does not know the tab (and the
/// completeness guards) gets.
pub fn hint_bar_for_with(
    bindings: &EffectiveBindings,
    context: InputContext,
    stats_tab: Option<crate::app::StatsTab>,
) -> String {
    if context == InputContext::Board
        && bindings.label(context, TuiAction::MoveUp) == "Up / k"
        && bindings.label(context, TuiAction::MoveDown) == "Down / j"
    {
        return truncate(
            &format!(
                "j/k nav · {} new issue · {} help",
                bindings.label(context, TuiAction::NewIssue),
                bindings.label(context, TuiAction::Help),
            ),
            MAX_HINT_CHARS,
        );
    }
    let scoped: Option<&'static [TuiAction]> = if context == InputContext::Stats {
        stats_tab.map(stats_footer_actions)
    } else {
        None
    };
    let rows: &'static [TuiAction] = scoped.unwrap_or_else(|| actions(context));
    let mut text = String::new();
    for action in rows {
        let _ = write!(
            text,
            "{} {} · ",
            bindings.label(context, *action),
            action.description_in(context)
        );
    }
    truncate(text.trim_end_matches(" · "), MAX_HINT_CHARS)
}

/// The contexts the keybindings overlay documents, in reading order.
///
/// One list, shared with the completeness guard in this module's tests: a context
/// added to the overlay but not to the guard (or the reverse) is how a whole surface
/// becomes invisible in the help without anyone noticing. The overlay itself now
/// scopes its rows with [`contexts_for_mode`], so this list is the test-only record
/// of what must stay covered.
#[cfg(test)]
const HELP_CONTEXTS: [InputContext; 36] = [
    InputContext::Detail,
    InputContext::Board,
    InputContext::Rollover,
    InputContext::Form,
    InputContext::FormPicker,
    InputContext::ConfirmDelete,
    InputContext::MoveIntoDone,
    // WP04: the blocked-move prompt's keys belong in the help overlay too, or
    // a user who never guessed `y` has no way to learn it.
    InputContext::ConfirmBlockedMove,
    InputContext::Help,
    InputContext::HelpSearch,
    InputContext::ContextMenu,
    // #1513: the related-issues picker's keys. Listed here for the same reason
    // the other pickers are — a key nobody can discover is a key nobody uses.
    InputContext::RelatedPicker,
    InputContext::Filter,
    InputContext::FilterModal,
    InputContext::Settings,
    InputContext::SettingsPrompt,
    InputContext::PlanningManagement,
    InputContext::PlanningConfirm,
    InputContext::PlanningForm,
    InputContext::DatePicker,
    InputContext::Comment,
    InputContext::Asset,
    InputContext::LinkPrompt,
    InputContext::EditRepair,
    // #1510: the conflict prompt's keys, for the same reason the edit repair's
    // are listed — a key nobody can discover is a key nobody uses, and every one
    // of the three decisions is reachable only from this prompt.
    InputContext::EditConflict,
    // WP07: the batch surface's keys, for the same reason WP04 put the
    // blocked-move prompt's there — a key nobody can discover is a key nobody
    // uses, and the batch surface is entirely keyboard-driven.
    InputContext::BulkModal,
    // WP06: the triage inbox's keys, same reason. The `t` that opens it is
    // listed by the `board` rows below.
    InputContext::Triage,
    // The F3 Cycle mode's listing keys.
    InputContext::Cycle,
    // The F5 Milestones mode's listing keys.
    InputContext::Milestones,
    // The F6 Repos mode's listing keys (tix #1529).
    InputContext::Repos,
    // The F8 Schedule page's keys (tix #1593).
    InputContext::Schedule,
    // The F11 Library page's keys (tix #1593).
    InputContext::Library,
    // The F10 Portfolio page's keys (WP06), for the same reason: a key nobody can
    // discover is a key nobody uses, and the page is entirely keyboard-driven.
    InputContext::Portfolio,
    // The mode shell's switches and the navigation toggle (tui-mode-navigation).
    InputContext::Shell,
    // WP05: the saved-views modal's keys.
    InputContext::Views,
    InputContext::ViewsPrompt,
];

/// The contexts whose bindings the help overlay shows for a top-level mode.
///
/// Each top-level mode owns the contexts reachable from it, so `?` in the Cycle
/// mode lists cycle keys and not the board's. The shell's switches appear in every
/// mode, so the way out of a mode is always listed.
pub const fn contexts_for_mode(mode: TopMode) -> &'static [InputContext] {
    match mode {
        // The board and every overlay reachable from it: the detail pane, the
        // delete/rollover/blocked prompts, filter and search, the batch and triage
        // decision surfaces, and the two text prompts. They are the board's keys
        // because the board is where they are opened from.
        TopMode::Board => &[
            InputContext::Shell,
            InputContext::Board,
            InputContext::Detail,
            InputContext::Rollover,
            InputContext::ConfirmDelete,
            InputContext::MoveIntoDone,
            InputContext::ConfirmBlockedMove,
            InputContext::Help,
            InputContext::HelpSearch,
            InputContext::ContextMenu,
            // #1513: the related picker is a detail-pane overlay, so its keys are
            // documented among the board's.
            InputContext::RelatedPicker,
            InputContext::Filter,
            InputContext::FilterModal,
            InputContext::Comment,
            InputContext::Asset,
            InputContext::LinkPrompt,
            InputContext::EditRepair,
            // #1510: the conflict prompt is reachable from the board (an editor
            // round trip) and from nothing else, so its keys are documented there.
            InputContext::EditConflict,
            InputContext::BulkModal,
            // WP05: the saved-views modal's keys. The `v` that opens it is listed
            // by the `board` rows below, and the modal's own footer names the same
            // keys.
            InputContext::Views,
            InputContext::ViewsPrompt,
        ],
        TopMode::Triage => &[InputContext::Shell, InputContext::Triage],
        TopMode::Cycle => &[
            InputContext::Shell,
            InputContext::Cycle,
            InputContext::PlanningManagement,
            InputContext::PlanningConfirm,
            InputContext::PlanningForm,
            InputContext::DatePicker,
        ],
        // The Milestones mode is the Config surface pinned to the milestones
        // section: its own keys, the planning surfaces `m` opens, and the
        // settings-confirm prompt a milestone delete raises.
        TopMode::Milestones => &[
            InputContext::Shell,
            InputContext::Milestones,
            InputContext::PlanningManagement,
            InputContext::PlanningConfirm,
            InputContext::PlanningForm,
            InputContext::DatePicker,
            InputContext::SettingsPrompt,
        ],
        // The Repos mode's listing keys, plus the shell switches every mode shows
        // (tix #1529).
        TopMode::Repos => &[InputContext::Shell, InputContext::Repos],
        // The F7 Stats page's Health tab, and the form it opens (mission
        // `project-issue-health-status-01M3C8HX`).
        TopMode::Stats => &[
            InputContext::Shell,
            InputContext::Stats,
            InputContext::Comment,
        ],
        // The Schedule page's own keys, plus the shell switches every mode shows
        // (tix #1593).
        TopMode::Schedule => &[InputContext::Shell, InputContext::Schedule],
        // The Library page's own keys, plus the shell switches every mode shows
        // (tix #1593).
        TopMode::Library => &[InputContext::Shell, InputContext::Library],
        // The Portfolio page's own keys, plus the shell switches every mode shows
        // (WP06).
        TopMode::Portfolio => &[InputContext::Shell, InputContext::Portfolio],
        TopMode::NewIssue => &[
            InputContext::Shell,
            InputContext::Form,
            InputContext::FormPicker,
        ],
        TopMode::Config => &[
            InputContext::Shell,
            InputContext::Settings,
            InputContext::SettingsPrompt,
        ],
    }
}

/// The rows the help overlay shows for `mode`.
///
/// A caller that knows the `F8` Schedule page's active tab passes it to
/// [`help_overlay_for`]; this is the tab-agnostic form, which shows the page's
/// original Series rows.
pub fn help_overlay(bindings: &EffectiveBindings, mode: TopMode) -> Vec<(String, String, String)> {
    help_overlay_for(bindings, mode, None, None)
}

/// The `F7` Stats page's **Health** tab keys (WP05): the page's own cursor, the two
/// tabs, opening a row's issue, help and the way out.
///
/// The Time tab's six commands act on nothing here, so they are not advertised — the
/// tab's own hint row names the keys it does have.
const STATS_HEALTH_HELP_ACTIONS: &[TuiAction] = &[
    TuiAction::MoveUp,
    TuiAction::MoveDown,
    TuiAction::Next,
    TuiAction::Previous,
    TuiAction::Submit,
    TuiAction::Help,
    TuiAction::Close,
];

/// The `F7` Stats page's **Time** tab keys (WP05): the same cursor and strip keys,
/// the three mutations, the filter, the breakdown and the audit view.
///
/// `Submit` is here because `Enter` **works** on this tab (it opens the selected row's
/// issue), and an overlay that omitted a working key is the defect the completeness
/// guard exists to prevent — a reviewer found `Enter` missing from this list, which is
/// why the test that covers it now asserts every action the context binds is listed.
const STATS_TIME_HELP_ACTIONS: &[TuiAction] = &[
    TuiAction::MoveUp,
    TuiAction::MoveDown,
    TuiAction::Next,
    TuiAction::Previous,
    TuiAction::Submit,
    TuiAction::TimeAdd,
    TuiAction::TimeEdit,
    TuiAction::TimeDelete,
    TuiAction::TimeFilter,
    TuiAction::TimeBreakdown,
    TuiAction::TimeHistory,
    TuiAction::Help,
    TuiAction::Close,
];

/// The `F7` Stats page's footer rows for its **Health** tab (WP05): the cursor, the
/// two tabs, opening a row's issue, help and the way out.
const STATS_HEALTH_FOOTER: &[TuiAction] = &[
    TuiAction::MoveUp,
    TuiAction::MoveDown,
    TuiAction::Next,
    TuiAction::Previous,
    TuiAction::Submit,
    TuiAction::Help,
    TuiAction::Close,
];

/// The `F7` Stats page's footer rows for its **Time** tab (WP05).
///
/// The tab's own commands lead, because the bar truncates at
/// [`MAX_HINT_CHARS`] and the keys that exist *only* on this tab are the ones a reader
/// cannot find anywhere else; the page's in-body hint row spells the whole set.
const STATS_TIME_FOOTER: &[TuiAction] = &[
    TuiAction::TimeAdd,
    TuiAction::TimeEdit,
    TuiAction::TimeDelete,
    TuiAction::TimeFilter,
    TuiAction::TimeBreakdown,
    TuiAction::TimeHistory,
    TuiAction::MoveUp,
    TuiAction::MoveDown,
    TuiAction::Next,
    TuiAction::Previous,
    TuiAction::Submit,
    TuiAction::Help,
    TuiAction::Close,
];

/// The `F7` Stats page's overlay rows for one tab, so the overlay and the footer
/// cannot disagree about which keys the tab has.
fn stats_help_actions(tab: crate::app::StatsTab) -> &'static [TuiAction] {
    match tab {
        crate::app::StatsTab::Health => STATS_HEALTH_HELP_ACTIONS,
        crate::app::StatsTab::Time => STATS_TIME_HELP_ACTIONS,
        // WP06: the Burndown tab's rows are the tab's own — the module that reads its
        // controls is the module that names them, exactly as the `F8` Schedule page's
        // tabs keep theirs beside their tabs.
        crate::app::StatsTab::Burndown => crate::ui::analytics::HELP_ACTIONS,
    }
}

/// The `F7` Stats page's footer rows for one tab.
fn stats_footer_actions(tab: crate::app::StatsTab) -> &'static [TuiAction] {
    match tab {
        crate::app::StatsTab::Health => STATS_HEALTH_FOOTER,
        crate::app::StatsTab::Time => STATS_TIME_FOOTER,
        crate::app::StatsTab::Burndown => crate::ui::analytics::FOOTER_ACTIONS,
    }
}

/// The keys a tab of the `F7` Stats page reads **raw**, with what each one does
/// (WP06).
///
/// A raw key is one no [`TuiAction`] names: the tab's handler reads it ahead of the
/// binding layer, so the overlay has to spell it beside the bound rows or the key
/// works and cannot be discovered. Only the Burndown tab has any — the Health and Time
/// tabs act entirely through bound actions.
fn stats_raw_rows(tab: crate::app::StatsTab) -> &'static [(&'static str, &'static str)] {
    match tab {
        crate::app::StatsTab::Burndown => crate::ui::analytics::HELP_RAW,
        crate::app::StatsTab::Health | crate::app::StatsTab::Time => &[],
    }
}

/// The rows the help overlay shows for `mode`, with the **tabbed** pages' rows
/// scoped to their active tab: the `F8` Schedule page by `schedule_tab` (mission
/// `repeating-cycle-schedules-01M3C7W1`, WP07 review) and the `F7` Stats page by
/// `stats_tab` (WP05).
///
/// A tabbed page is a mode whose **tab** decides which keys are live: the Schedule
/// page's Series tab's keys and its Cycle schedules tab's are different sets, and the
/// Stats page's Health tab has no mutation keys at all while its Time tab's six
/// commands act on nothing on Health. The overlay is generated from the binding
/// *context*, which cannot see a tab, so drawing it unscoped advertised `x end` and
/// `d defer` on the Cycle schedules tab — an instruction that contradicted the page's
/// own hint row — and would advertise `a add a time entry` on the Health tab where
/// the key does nothing. With `Some(tab)` the tab's own rows replace the context's;
/// every other mode, and a caller that does not know the tab, is unchanged (which is
/// what the completeness guards, which walk every context's bindings, rely on).
pub fn help_overlay_for(
    bindings: &EffectiveBindings,
    mode: TopMode,
    schedule_tab: Option<crate::ui::schedule::ScheduleTab>,
    stats_tab: Option<crate::app::StatsTab>,
) -> Vec<(String, String, String)> {
    use crate::ui::schedule::{
        CAPACITY_HELP_ACTIONS, CAPACITY_HELP_RAW, CYCLE_HELP_ACTIONS, CYCLE_HELP_RAW, ScheduleTab,
    };

    let tab_rows = (mode == TopMode::Schedule)
        .then_some(schedule_tab)
        .flatten()
        .and_then(|tab| match tab {
            ScheduleTab::Cycles => Some((CYCLE_HELP_ACTIONS, CYCLE_HELP_RAW)),
            ScheduleTab::Capacity => Some((CAPACITY_HELP_ACTIONS, CAPACITY_HELP_RAW)),
            // The Series tab keeps the keybinding table's own rows, which name the
            // Series actions it is bound to.
            ScheduleTab::Series => None,
        });
    // WP05: the `F7` Stats page's two tabs are two different key sets, so the rows
    // are scoped to the tab the overlay was opened from — exactly the fix the
    // Schedule page's tab scoping made. On the Health tab the Time tab's six
    // commands act on nothing (and the reverse: `Enter` has no row to open), so
    // leaving them in would print an instruction the page contradicts.
    let stats_rows = if mode == TopMode::Stats {
        stats_tab.map(stats_help_actions)
    } else {
        None
    };
    // WP06: the raw keys beside them — the Burndown tab's controls have no `TuiAction`
    // to be listed through, so the overlay would otherwise omit keys that work.
    let stats_raw = if mode == TopMode::Stats {
        stats_tab.map(stats_raw_rows)
    } else {
        None
    };
    let mut rows = Vec::new();
    // The pointer rows describe the board's mouse affordances; a non-board mode has
    // none to advertise, so they are scoped to the Board mode like every other row.
    if mode == TopMode::Board {
        rows.extend([
            (
                "mouse click".to_string(),
                "click".to_string(),
                "board".to_string(),
            ),
            (
                "mouse double".to_string(),
                "double-click".to_string(),
                "board".to_string(),
            ),
            (
                "mouse right".to_string(),
                "right-click".to_string(),
                "board".to_string(),
            ),
            (
                "mouse drag".to_string(),
                "drag".to_string(),
                "board".to_string(),
            ),
        ]);
    }
    for context in contexts_for_mode(mode) {
        let schedule_context = *context == InputContext::Schedule;
        if let Some((actions, raw)) = tab_rows
            && schedule_context
        {
            // The tab's own rows: the bound letters carry this tab's meanings (so a
            // rebind still renames the row), and the keys the page reads raw are
            // spelled beside them, because no `TuiAction` names them.
            rows.extend(actions.iter().map(|(action, description)| {
                (
                    bindings.label(*context, *action),
                    (*description).to_string(),
                    context.as_str().to_string(),
                )
            }));
            rows.extend(raw.iter().map(|(key, description)| {
                (
                    (*key).to_string(),
                    (*description).to_string(),
                    context.as_str().to_string(),
                )
            }));
            continue;
        }
        if let Some(actions) = stats_rows
            && *context == InputContext::Stats
        {
            // WP05: the Stats page's tab's live keys, with the bound letters read
            // back so a rebind renames the row like every other row.
            rows.extend(actions.iter().map(|action| {
                (
                    bindings.label(*context, *action),
                    action.description_in(*context).to_string(),
                    context.as_str().to_string(),
                )
            }));
            // WP06: and the tab's raw keys, in the tab's own words.
            for (key, description) in stats_raw.unwrap_or(&[]) {
                rows.push((
                    (*key).to_string(),
                    (*description).to_string(),
                    context.as_str().to_string(),
                ));
            }
            continue;
        }
        for action in all_actions(*context) {
            rows.push((
                bindings.label(*context, *action),
                action.description_in(*context).to_string(),
                context.as_str().to_string(),
            ));
        }
    }
    rows
}

fn all_actions(context: InputContext) -> &'static [TuiAction] {
    match context {
        InputContext::Board => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::NextBoard,
            TuiAction::PreviousBoard,
            TuiAction::Open,
            TuiAction::Edit,
            TuiAction::View,
            TuiAction::Agent,
            TuiAction::ToggleColumn,
            TuiAction::FilterModal,
            TuiAction::BulkModal,
            TuiAction::Triage,
            // The mentions view (OpenSpec change `issue-mentions`): `i`, and the
            // key the bottom indicator row advertises. The overlay's list is
            // hand-written, so a binding it does not name is a key that works and
            // cannot be discovered.
            TuiAction::OpenMentions,
            // WP05: the `v` that opens the saved-views modal.
            TuiAction::Views,
            TuiAction::Mark,
            TuiAction::Unmark,
            TuiAction::MovePrevious,
            TuiAction::MoveNext,
            // The page keys (#1442): bound on the board, and until this guard existed
            // they were the only way to reach a card the column had scrolled past —
            // documented nowhere.
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::NewIssue,
            // The two board keys added after this list was written: the overlay's list
            // is hand-written, so a binding it does not name is a key that works and
            // cannot be discovered. `every_bound_action_appears_in_the_overlay` is the
            // guard, and it is what found these.
            TuiAction::CloneIssue,
            TuiAction::ToggleArchived,
            // #1399: sub-issue visibility. The overlay's list is hand-written, so a
            // binding it does not name is a key that works and cannot be discovered;
            // `every_bound_action_appears_in_the_overlay` is the guard.
            TuiAction::ToggleChildren,
            TuiAction::Delete,
            TuiAction::Refresh,
            TuiAction::Settings,
            TuiAction::Planning,
            TuiAction::NewBoard,
            TuiAction::Help,
            TuiAction::Quit,
            TuiAction::TextFilter,
            TuiAction::ReorderUp,
            TuiAction::ReorderDown,
        ],
        InputContext::Detail => &[
            // The pane's own list, not the footer's: `close` is how you get back, and a
            // key that returns you is not one to leave out of the reference.
            TuiAction::Close,
            TuiAction::Edit,
            TuiAction::View,
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Help,
            TuiAction::Comment,
            TuiAction::Asset,
            TuiAction::NewRelationship,
            TuiAction::NextRelationship,
            TuiAction::PreviousRelationship,
            TuiAction::EditRelationship,
            TuiAction::RemoveRelationship,
            // #1384: set/change/clear the parent.
            TuiAction::EditParent,
            // Mission `project-issue-health-status-01M3C8HX` (WP06): the form that
            // records this issue's health.
            TuiAction::HealthForm,
            // #1513: the related-issues surface. The overlay's list is hand-written,
            // so a binding it does not name is a key that works and cannot be
            // discovered; `every_bound_action_appears_in_the_overlay` is the guard.
            TuiAction::RelatedPicker,
            TuiAction::FollowRelated,
            TuiAction::NavBack,
        ],
        InputContext::RelatedPicker => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
        ],
        InputContext::Rollover => &[TuiAction::Submit, TuiAction::Previous, TuiAction::Cancel],
        InputContext::Form | InputContext::PlanningForm => &[
            TuiAction::Submit,
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::OpenPicker,
        ],
        InputContext::FormPicker => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::Create,
        ],
        InputContext::ConfirmDelete
        | InputContext::PlanningConfirm
        | InputContext::ConfirmBlockedMove => &[TuiAction::Confirm, TuiAction::Cancel],
        InputContext::MoveIntoDone
        | InputContext::Filter
        | InputContext::Comment
        | InputContext::Asset
        | InputContext::LinkPrompt => &[TuiAction::Submit, TuiAction::Cancel],
        InputContext::Help => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            // #1496: the search key, so the overlay names the way to search it.
            TuiAction::TextFilter,
            // #1441/#1442: the overlay's page keys. These are the overlay's *rows*, not
            // a footer — the footer for this context is the hint bar `render_help` draws
            // underneath, which is the board's or the pane's.
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Submit,
        ],
        InputContext::ContextMenu => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
        ],
        // Free text: `Esc` leaves the line (and clears it), `Enter` keeps the query.
        InputContext::HelpSearch => &[TuiAction::Cancel, TuiAction::Submit],
        InputContext::BulkModal => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::Cancel,
        ],
        // WP06: only what the context actually binds. The inbox's decision keys
        // (`a`, `d`, `u`, `f`, `p`, `y`) are deliberately unbound so they stay
        // typeable in a reason field, so they cannot appear here as chords —
        // they are named by the modal's own footer instead, which is how the
        // batch surface names its unbound keys too.
        InputContext::Triage => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::Submit,
            TuiAction::Cancel,
        ],
        InputContext::Cycle => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Planning,
            TuiAction::Help,
            TuiAction::Close,
        ],
        InputContext::FilterModal => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Reset,
            TuiAction::Submit,
            TuiAction::Cancel,
            TuiAction::OpenPicker,
        ],
        // The F5 Milestones mode: the same registry keys the Cycle listing uses,
        // plus the create/edit/delete commands the planning rows support.
        InputContext::Milestones => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Submit,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Planning,
            TuiAction::Help,
            TuiAction::Close,
        ],
        // The F7 Stats page (mission `project-issue-health-status-01M3C8HX`; WP05 adds
        // the Time tab): walk the active tab's rows, switch tabs, open the selected
        // Health row's issue, and — on the Time tab — add, correct, delete, filter,
        // break down and audit. The overlay is where a key nobody guessed becomes
        // discoverable, so every bound Stats action appears here.
        InputContext::Stats => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::TimeAdd,
            TuiAction::TimeEdit,
            TuiAction::TimeDelete,
            TuiAction::TimeFilter,
            TuiAction::TimeBreakdown,
            TuiAction::TimeHistory,
            TuiAction::Help,
            TuiAction::Close,
        ],
        // The F6 Repos mode (tix #1529): walk the list and run tix in the
        // selected repository.
        InputContext::Repos => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Submit,
            TuiAction::Help,
            TuiAction::Close,
        ],
        // The F8 Schedule page (tix #1593): walk the series rows, then act. The
        // action keys are the page's own (`handle_schedule_key` reads them raw).
        InputContext::Schedule => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::SeriesNew,
            TuiAction::SeriesGenerate,
            TuiAction::SeriesPause,
            TuiAction::SeriesResume,
            TuiAction::SeriesEnd,
            TuiAction::SeriesSkip,
            TuiAction::SeriesDefer,
            TuiAction::SeriesIgnore,
            TuiAction::Help,
            TuiAction::Close,
        ],
        // The F11 Library page (tix #1593): switch registry, walk rows, and
        // apply the selected view.
        InputContext::Library => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Submit,
            TuiAction::Help,
            TuiAction::Close,
        ],
        // The F10 Portfolio page (WP06): switch tab, walk the active tab's rows,
        // step into the selected epic's members, open the selected member issue
        // directly (FR-004), and leave. There is no mutating key — the page is a
        // reader.
        InputContext::Portfolio => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Submit,
            TuiAction::Help,
            TuiAction::Close,
        ],
        // WP05: exactly what each context binds. The list is a menu, so an
        // unbound letter there is inert rather than typeable; the prompt is the
        // free-text side of the same modal and binds only submit/cancel.
        InputContext::Views => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::ApplyView,
            TuiAction::NewView,
            TuiAction::RenameView,
            TuiAction::UpdateView,
            TuiAction::DuplicateView,
            TuiAction::DeleteView,
            TuiAction::Close,
        ],
        InputContext::ViewsPrompt => &[TuiAction::Submit, TuiAction::Cancel],
        InputContext::Settings => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::AddColumn,
            TuiAction::MoveColumnUp,
            TuiAction::MoveColumnDown,
            TuiAction::Submit,
            TuiAction::NewBoard,
            TuiAction::EditPlanningItem,
            TuiAction::Delete,
            TuiAction::NextBoard,
            TuiAction::PreviousBoard,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Close,
        ],
        InputContext::SettingsPrompt => &[TuiAction::Submit, TuiAction::Cancel],
        InputContext::PlanningManagement => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::Next,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Close,
        ],
        InputContext::DatePicker => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::PreviousMonth,
            TuiAction::NextMonth,
            TuiAction::PreviousYear,
            TuiAction::NextYear,
            TuiAction::Submit,
            TuiAction::Reset,
            TuiAction::Cancel,
        ],
        // #1506: the repair prompt's five decisions. `confirm` applies the
        // proposed fix (which for an unknown key is the declaration), `declare_key`
        // writes `[custom_attributes]` explicitly, `reedit` reopens the editor on
        // the retained copy, `ignore` acknowledges and keeps it, and `discard`
        // removes it behind a second confirmation. The modal's own footer
        // advertises them too, but the overlay is where a key nobody guessed
        // becomes discoverable.
        InputContext::EditRepair => &[
            TuiAction::Confirm,
            TuiAction::DeclareKey,
            TuiAction::Reedit,
            TuiAction::Ignore,
            TuiAction::Discard,
        ],
        // #1510: the conflict prompt's three decisions. Same actions as the edit
        // warning because they are the same kinds of decision, different words
        // because they do different things here (see `description_in`).
        InputContext::EditConflict => &[TuiAction::Reedit, TuiAction::Ignore, TuiAction::Confirm],
        InputContext::Shell => &[
            TuiAction::SwitchToBoard,
            TuiAction::SwitchToTriage,
            TuiAction::SwitchToCycle,
            TuiAction::SwitchToMilestones,
            TuiAction::SwitchToRepos,
            TuiAction::SwitchToStats,
            TuiAction::SwitchToSchedule,
            TuiAction::SwitchToLibrary,
            TuiAction::SwitchToPortfolio,
            TuiAction::SwitchToNewIssue,
            TuiAction::SwitchToConfig,
            TuiAction::ToggleNavigation,
        ],
    }
}

fn truncate(value: &str, max_chars: usize) -> String {
    if max_chars == 0 || value.chars().count() <= max_chars {
        return value.to_string();
    }
    let take = max_chars.saturating_sub(1);
    let head: String = value.chars().take(take).collect();
    format!("{}…", head.trim_end())
}

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

    /// Every action a documented context binds must appear in the overlay.
    ///
    /// `all_actions` is written by hand per context, so a binding can be added to the
    /// keymap and never appear in the help — the worst of both worlds, because the key
    /// works and nobody can discover it. It had already happened twice before this
    /// guard existed (`clone_issue` and `toggle_archived`, both added while this list
    /// was not).
    #[test]
    fn every_bound_action_appears_in_the_overlay() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        let mut missing: Vec<String> = Vec::new();
        for context in HELP_CONTEXTS {
            let listed = all_actions(context);
            for action in bindings.bound_actions(context) {
                if !listed.contains(&action) {
                    missing.push(format!("{} — {}", context.as_str(), action.as_str()));
                }
            }
        }
        assert!(
            missing.is_empty(),
            "the overlay does not list these bound actions, so nothing in the help \
             would tell a user they exist:\n  {}",
            missing.join("\n  ")
        );
    }

    /// Every row a mode's help draws comes from a context that mode owns, and the
    /// union over all modes still covers every documented context.
    #[test]
    fn the_overlay_and_its_guard_cover_the_same_contexts() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        let drawn: Vec<(String, String, String)> = TopMode::ALL
            .iter()
            .flat_map(|mode| help_overlay(&bindings, *mode))
            .collect();
        for context in HELP_CONTEXTS {
            let scope = context.as_str();
            assert!(
                drawn.iter().any(|(_, _, listed)| listed == scope),
                "`{scope}` is in HELP_CONTEXTS but contributes no rows to any mode's overlay"
            );
        }
    }

    /// Help is scoped to the active mode: every row's scope belongs to that mode's
    /// contexts, and a binding only the board has is absent elsewhere.
    #[test]
    fn help_is_scoped_to_the_active_mode() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        for mode in TopMode::ALL {
            let allowed: Vec<&str> = contexts_for_mode(mode).iter().map(|c| c.as_str()).collect();
            for (key, description, scope) in help_overlay(&bindings, mode) {
                assert!(
                    allowed.contains(&scope.as_str()),
                    "{mode:?} help shows `{key} {description}` from out-of-scope `{scope}`"
                );
            }
        }
        // `toggle column` is a board-only action; the cycle mode's help must not
        // offer it.
        let cycle = help_overlay(&bindings, TopMode::Cycle);
        assert!(
            !cycle
                .iter()
                .any(|(_, description, _)| description == "toggle column"),
            "cycle help must not list board bindings: {cycle:?}"
        );
        // …while the board's own help does list it.
        let board = help_overlay(&bindings, TopMode::Board);
        assert!(
            board
                .iter()
                .any(|(_, description, _)| description == "toggle column")
        );
        // The navigation switch is part of every mode's help.
        for mode in TopMode::ALL {
            let rows = help_overlay(&bindings, mode);
            assert!(
                rows.iter()
                    .any(|(_, description, _)| description == "toggle navigation"),
                "{mode:?} help must list the navigation control"
            );
        }
    }

    #[test]
    fn dynamic_hint_uses_effective_aliases() {
        let mut overrides = KeyBindings::default();
        overrides.board.new_issue = Some(vec!["ctrl+n".into(), "f4".into()]);
        overrides.board.help = Some(vec!["f1".into()]);
        let bindings = KeyBindings::resolve(&overrides).unwrap();
        let hint = hint_bar_for(&bindings, InputContext::Board);
        assert!(hint.contains("Ctrl+n / F4 new issue"), "got {hint:?}");
        assert!(hint.contains("F1 help"), "got {hint:?}");
    }

    /// The hint bar follows the active mode rather than always describing the board.
    #[test]
    fn hints_follow_the_active_mode() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        let board = hint_bar_for(&bindings, hint_context_for_mode(TopMode::Board));
        let triage = hint_bar_for(&bindings, hint_context_for_mode(TopMode::Triage));
        let config = hint_bar_for(&bindings, hint_context_for_mode(TopMode::Config));
        assert!(board.contains("new issue"), "got {board:?}");
        assert!(
            triage.contains("toggle") && !triage.contains("new issue"),
            "triage hint should describe triage, got {triage:?}"
        );
        assert!(
            config.contains("add column") && !config.contains("new issue"),
            "config hint should describe settings, got {config:?}"
        );
    }

    #[test]
    fn help_covers_every_configured_action() {
        let bindings = KeyBindings::resolve(&KeyBindings::default()).unwrap();
        let rows: Vec<(String, String, String)> = TopMode::ALL
            .iter()
            .flat_map(|mode| help_overlay(&bindings, *mode))
            .collect();
        for context in InputContext::ALL {
            for action in all_actions(*context) {
                assert!(
                    rows.iter().any(|(_, description, mode)| description
                        == action.description_in(*context)
                        && mode == context.as_str()),
                    "{} / {} is not listed by any mode's help",
                    context.as_str(),
                    action.as_str()
                );
            }
        }
    }
}