tix-tracker 0.6.0

use std::cell::{Cell, RefCell};
use std::io;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};

use crossterm::event::{
    self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEvent, KeyEventKind,
    KeyModifiers, MouseButton, MouseEvent, MouseEventKind,
};
use crossterm::execute;
use crossterm::terminal::{
    EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode,
};
use ratatui::Terminal;
use ratatui::backend::CrosstermBackend;
use ratatui::layout::{Position, Rect};
use ratatui::style::{Color, Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Borders, Clear, Paragraph, Wrap};

use crate::assignee::{git_identity, resolve_me};
use crate::commands::{self, mv};
use crate::config::{BoardConfiguration, Config};
use crate::error::{Result, TixError};
use crate::keybindings::{EffectiveBindings, InputContext, TuiAction};
use crate::model::{Issue, Priority, Status, today};
use crate::planning::Planner;
use crate::search::{self, Corpus, FilterField};
use crate::storage::{IssueSelector, Store};

use crate::edit_problems::{self, EditFix, EditProblem};
use crate::editor;
use crate::ui::board::{self, BoardState, HitTarget};
use crate::ui::commandbar;
use crate::ui::context_menu::{ContextMenu, MenuEvent, MenuItem, MenuItemKind};
use crate::ui::date_picker::{DatePicker, DatePickerEvent, DatePickerHit};
use crate::ui::detail::{self, DetailState};
use crate::ui::dialog::{DialogEvent, RolloverDialog};
use crate::ui::form::{self, FormState, NewIssueTarget};
use crate::ui::nav::{NavDisplay, TopMode};
use crate::ui::pickers::{DropdownState, PickerEvent, PickerItem, PickerMode, SelectionModel};
use crate::ui::planning::{
    PlanningForm, PlanningKind, PlanningModal, PlanningPrompt, PlanningRow, PlanningSegment,
};
use crate::ui::settings::{
    ConfigPane, ConfigSection, SettingsModal, SettingsPrompt, board_rows_len,
};
use crate::ui::tabs::BoardTabs;
use crate::ui::triage::{TriageControl, TriageDropdownKind};
use crate::watcher::FsDelta;

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Action {
    None,
    Quit,
    OpenEditor(String),
    /// Open the issue file in the resolved read-only viewer (tix #1507).
    OpenViewer(String),
    /// Open an **arbitrary** file in the resolved read-only viewer (tix #1513).
    ///
    /// Distinct from [`Action::OpenViewer`], which resolves a store-relative
    /// filename through the store: a `related_issues` *path* entry may point
    /// anywhere, including outside the store, and there is no store entry to look
    /// up. The path is absolute — it comes from [`crate::related::resolve_path`].
    OpenViewerAt(PathBuf),
    /// Re-open the editor on the conflict prompt's temp copy so the user can
    /// compare it with the newer on-disk version (tix #1510). Handled in the
    /// event loop because it hands the terminal to the child, exactly as
    /// [`Action::OpenEditor`] does.
    CompareEdit,
    /// Re-open the editor on the repair prompt's retained copy (tix #1506), so a
    /// problem with no automatic fix can be corrected by hand. Handled in the
    /// event loop for the same reason [`Action::CompareEdit`] is: the child needs
    /// the terminal.
    ReeditRepair,
    OpenAgent(String),
    /// Switch to a named board by tab index (mouse click on a tab, D5/D6).
    SwitchBoard(usize),
    /// Confirm-delete dialog Yes/No button clicked; maps to the `y` /
    /// any-other-key branch of [`App::handle_confirm_delete_key`] (D6).
    ConfirmDeleteYes,
    ConfirmDeleteNo,
    /// A filter-modal criterion row was clicked; jump focus there (D6).
    FilterModalFocus(FilterField),
    /// A settings-modal row was clicked; select it and run the Enter action.
    SettingsRow(usize),
    /// A date-picker day cell or control was clicked; maps to the equivalent
    /// key branch (D6): day → select that date, Prev/Next → page the month,
    /// Submit → Enter.
    DatePickerHit(DatePickerHit),
    /// The help overlay was clicked; close it like the `?`/`q`/Esc branch.
    HelpClose,
    /// A vertical mode-navigation entry was clicked; switch the shell to that
    /// top-level mode (tui-mode-navigation).
    SwitchMode(TopMode),
    /// The Triage mode's status control was clicked; open the status picker
    /// (tui-triage-mode).
    TriageOpenStatus,
    /// The Triage mode's assignee control was clicked; open the assignee picker.
    TriageOpenAssignee,
    /// The Triage mode's create control was clicked; start the inline prompt.
    TriageCreate,
    /// The Triage mode's queue control was clicked; move the focus there. The
    /// queue has no action of its own, so this focuses and stops.
    TriageFocusQueue,
    /// A visible option row of the open Triage picker was clicked; choose it by
    /// its position in the filtered option list.
    TriagePickOption(usize),
    /// A click landed outside the open Triage picker; close it.
    TriageDropdownClose,
    /// A Cycle-mode row was clicked; select that cycle (tui-cycle-mode).
    CycleSelect(usize),
    /// A row of the shared flat issue table was clicked; open that issue's
    /// detail pane. The filename is store-relative, exactly what
    /// [`crate::storage::IssueSelector::Filename`] takes. Raised by both the
    /// Cycle mode's and the Milestones mode's issue table
    /// ([`crate::ui::issue_table`]).
    OpenIssue(String),
    /// The New Issue mode's Template row was clicked; open the template picker
    /// (tui-new-issue-mode).
    TemplateOpen,
    /// A visible option row of the open template picker was clicked; choose that
    /// template by its position in the filtered option list.
    TemplatePickOption(usize),
    /// A Config-mode section-rail entry was clicked; switch the section
    /// (tui-config-mode).
    ConfigSection(ConfigSection),
    /// A Config-mode cycle/milestone row was clicked; select that row's index
    /// in the planning cursor (tui-config-mode).
    ConfigPlanningRow(usize),
    /// A Config-mode Types/custom-attributes row was clicked; select that row's
    /// index in the section's list cursor (tui-config-mode).
    ConfigListRow(usize),
    /// A rail **branch** under the Board trunk was clicked; switch the active
    /// board to the named configuration (tui-mode-navigation).
    SelectBoard(String),
    /// A rail branch under the Cycles trunk was clicked; enter the Cycle mode
    /// focused on the named cycle (tui-mode-navigation).
    SelectCycle(String),
    /// A rail branch under the Milestones trunk was clicked; enter the
    /// Milestones mode focused on the named milestone (tui-mode-navigation).
    SelectMilestone(String),
    /// A rail branch under the New Issue trunk was clicked; open the New Issue
    /// form seeded from the named `[templates.<name>]` record.
    NewFromTemplate(String),
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Mode {
    Board,
    /// The batch modal (WP07). The modal's state is in [`App::bulk`]; the mode says
    /// only that it is open, exactly as `Mode::FilterModal` does.
    BulkModal,
    /// The triage inbox (WP06, T029). A modal over the board like settings and
    /// the batch modal, so the board, its tabs and its card cursor are all
    /// still there underneath and unchanged when it closes.
    ///
    /// The inbox's own cursor and selection live in [`App::triage`] rather than
    /// in [`BoardState`], which is what makes "the normal board/detail
    /// selection is unchanged when the inbox is not active" a property of
    /// which struct each cursor is in rather than something a test has to
    /// remember to restore.
    TriageInbox,
    /// The F3 Cycle mode (tui-cycle-mode): cycles grouped current / future /
    /// archived with statistics for the selected one. Like the triage inbox it
    /// is the mode's content, not a modal over the board; the
    /// planning-management surface is reached from it with `m`.
    Cycle,
    RolloverDialog,
    Detail,
    Form,
    ConfirmDelete,
    MoveIntoDone {
        target_col: usize,
        buffer: String,
    },
    /// The blocked-move acknowledgement prompt (WP04, FR-004).
    ///
    /// Reached instead of applying a move toward the board's completion column
    /// when the issue has open blockers. `warning` is the **shared** text from
    /// `commands::blocked_note`, so the TUI says exactly what the CLI says.
    ConfirmBlockedMove {
        target_col: usize,
        warning: String,
    },
    /// The reasoned-override prompt (WP05, FR-002, contract §3.3).
    ///
    /// Reached instead of applying a move that leaves a **terminal** category
    /// when the board declares a `category_map`. `reason` is the **shared**
    /// diagnostic from the service, so the TUI says exactly what the CLI says —
    /// parity includes the message, not only the accept/refuse decision.
    ///
    /// This prompt is the whole reason WP05 exists on this path. Until it, a
    /// terminal-exit transition was refused by the seam with a message naming
    /// `tix move … --reason`, and the TUI had **no way to supply one** — the flag
    /// is a CLI spelling and the TUI has no flags. So a user who moved an issue to
    /// `done` in the TUI could not move it back, in the TUI, at all.
    TransitionReason {
        target_col: usize,
        /// The refusal being overridden, rendered verbatim.
        reason: String,
        /// What the user has typed so far.
        buffer: String,
    },
    Help {
        return_to: Box<Mode>,
    },
    /// Issue context menu opened by right-clicking a card (D5); `return_to` is
    /// the mode it was opened from (the board). Activation runs the exact
    /// action the equivalent key binding would.
    ContextMenu {
        return_to: Box<Mode>,
    },
    Filter {
        buffer: String,
    },
    FilterModal,
    /// The F12 Config mode (tui-config-mode): the sectioned surface over
    /// dashboards, cycles, and milestones. Like the triage inbox and the cycle
    /// listing it is the mode's content, not a modal over the board. Its state
    /// is [`App::settings`], and its cycles/milestones sections drive
    /// [`App::planning`] too.
    Settings,
    PlanningManagement,
    PlanningForm,
    /// Calendar date picker popup; `return_to` is the modal it overlays.
    DatePicker {
        return_to: Box<Mode>,
    },
    Comment {
        buffer: String,
    },
    Asset {
        buffer: String,
    },
    /// The editor round trip left a file with a problem (tix #1506).
    ///
    /// One prompt for every post-edit problem: a file that will not parse, a
    /// file `tix lint` is unhappy about, or an edit that lost its title. It
    /// lists each problem with its diagnostic and a proposal, and offers the fix
    /// tix can apply, the editor again on the retained copy, an explicit
    /// declaration of an undeclared key, acknowledgement, and a discard that
    /// needs a second confirmation.
    ///
    /// Nothing is discarded automatically: the retained copy (`temp`) survives
    /// acknowledgement and is only removed by the confirmed discard. When
    /// `written` is true the edited content is already on disk (`tix lint`
    /// findings arrive after the write, tix #1510's #1506 behaviour), so the
    /// prompt is a report; when it is false nothing has been written and the fix
    /// writes the repaired file for the first time.
    ///
    /// `key` is the undeclared top-level frontmatter key the prompt can declare,
    /// `Some` only for an `unknown_key` problem with a non-empty value. It is what
    /// `confirm`/`declare_key` write into `tix.toml`; every other problem leaves
    /// it `None`, so those chords say there is nothing to declare.
    EditRepair {
        filename: String,
        /// `kind: message` of the first problem, for the status line and the
        /// prompt's heading.
        message: String,
        key: Option<String>,
        /// Every classified problem, in the order the diagnostics arrived.
        problems: Vec<EditProblem>,
        /// The retained edited copy — the editor's temp file when one exists.
        /// The only thing a confirmed discard removes.
        temp: Option<PathBuf>,
        /// Whether the edited content is already on disk.
        written: bool,
        /// A discard has been asked for once; the second keypress is the
        /// decision. `Esc` never sets it.
        discard_armed: bool,
    },
    /// The issue file changed on disk while the editor had it open (tix #1510).
    ///
    /// Entered **instead of** the write, so nothing about the raced edit is on
    /// disk: the newer file is untouched and the editor's version is still the
    /// temp copy. The three keys the prompt names are the only way out, and two of
    /// them — `a`/`Esc` (keep the on-disk version) and `c` (compare in the
    /// editor) — never write the editor's version at all. Only `o`/`y` overrides.
    EditConflict {
        /// The issue file, relative to the store's `issues_dir`.
        filename: String,
        /// The edited temp copy — the editor's version, kept until the user
        /// decides (abandoning removes it, overriding writes it, comparing
        /// reopens it).
        temp: PathBuf,
        /// The newer on-disk file, shown so the user can open it by hand.
        disk_path: PathBuf,
    },
    /// Create a relationship from the detail view (#1359), in two steps.
    ///
    /// `Step::Target` asks for the other issue as a **selector** — the same string
    /// `tix link <from> <to>` takes, so `#4`, `4`, or a title fragment all work and
    /// an unresolvable one produces the CLI's own error rather than a TUI-specific
    /// one. `Step::Kind` then asks for the kind, and it is **required**: C-001 forbids
    /// an untypeable relationship, so there is no default to fall back to and an
    /// empty or unrecognised answer is a refusal, not a guess.
    LinkCreate {
        buffer: String,
        step: LinkStep,
        /// The target resolved by the `Target` step, carried forward to `Kind`.
        ///
        /// Carried rather than re-resolved: the first step already applied the CLI's
        /// selector rules and reported its errors, and re-reading the buffer's
        /// meaning a second time would be a second place for the two to disagree. A
        /// `Kind` step with no target cannot happen — the mode is only entered in
        /// that state with one.
        target: Option<u32>,
    },
    /// Re-kind or retarget the relationship under the detail pane's cursor.
    ///
    /// Carries the target it was opened with so the kind step can submit an edit
    /// rather than a create: `tix link edit <id>` is an edit precisely because the
    /// stable id survives a re-kind, and a create-then-remove pair would lose it.
    LinkEdit {
        index: usize,
        buffer: String,
        step: LinkStep,
        /// The new target, when the user supplied one. `None` means **keep the
        /// existing target** and change only the kind — the same as `tix link edit
        /// <id> --type …` with no `--to`.
        target: Option<u32>,
        /// The new kind, when the user supplied one. `None` likewise means keep.
        kind: Option<crate::relationships::RelationKind>,
    },
    /// Confirm removing the relationship under the cursor.
    ///
    /// A relationship is stored in exactly one issue's file, so removing it is a
    /// write to another issue from the one on screen. It gets a confirmation for the
    /// same reason `ConfirmDelete` does, and the confirmation names the edge.
    ConfirmRemoveRelationship {
        index: usize,
    },
}

/// Which half of a two-step relationship prompt is being answered.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LinkStep {
    /// The other issue, as a selector.
    Target,
    /// The relationship kind. **Required** (C-001).
    Kind,
}

/// A rectangular click target recorded by a widget during drawing (D3), so the
/// same frame's pointer position can be resolved to an [`Action`] without the
/// widget knowing anything about mouse handling.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HitRegion {
    pub rect: Rect,
    pub action: Action,
}

/// Origin of a mouse press (D4): which column and (when the press landed on a
/// card) which card it started on, plus a timestamp used for the double-click
/// window. Kept by [`MouseState::last_down`] until a second press on the same
/// card, a drag, or the next distinct target replaces it.
#[derive(Debug)]
struct MouseDown {
    col: usize,
    card: Option<usize>,
    at: Instant,
}

/// An in-flight drag (D4): the pressed card's origin, so an `Up` can compare
/// the drop target against it and no-op for same-column / non-card drops.
#[derive(Debug)]
struct Drag {
    col: usize,
    card: Option<usize>,
}

/// Mouse interaction state driven by `handle_board_mouse` (D4). A `Down`
/// records the press origin, `Drag` frames promote it into an active drag (no
/// board mutation while dragging), and the resolving `Up` decides between a
/// plain click / double-click / drag-drop.
#[derive(Debug)]
pub struct MouseState {
    last_down: Option<MouseDown>,
    drag: Option<Drag>,
    pub double_click_window: Duration,
}

impl Default for MouseState {
    fn default() -> Self {
        MouseState {
            last_down: None,
            drag: None,
            double_click_window: Duration::from_millis(500),
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum FormPickerField {
    Labels,
    Assignee,
    Cycles,
    Milestones,
    Reviewer,
    /// The issue's board column (tix #1508). Single-select, options are the
    /// active board's columns plus the field's current value. No inline create:
    /// a column the board does not configure renders in the Mismatched column, and
    /// inventing one from a form is not something the dropdown should do.
    Status,
    /// The issue's priority (tix #1508). Single-select, options are the built-in
    /// `low`/`medium`/`high` plus every priority the store already uses, plus the
    /// current value. Inline `+` create is kept: a custom priority is a preserved
    /// concept in the model (`Priority::Other`), so a genuinely new one must
    /// remain expressible.
    Priority,
    /// The new-issue templates configured in `[templates.<name>]`
    /// (tui-new-issue-mode). Single-select: choosing one names a record to
    /// pre-fill the form from.
    Template,
    /// The parent issue (WP06 / T026). Single-select, per C-001: one parent,
    /// never a list, so this is `DropdownState::single` below and never `multi`.
    Parent,
}

#[derive(Debug, Clone)]
struct FormPicker {
    field: FormPickerField,
    state: DropdownState,
}

impl FormPickerField {
    /// Whether the picker's `+` inline create is offered on this field.
    ///
    /// Every field but Status keeps the keystroke it had: cycles, milestones and
    /// team members become configuration records, labels and priorities are
    /// preserved values, and parent/template simply no-op downstream. A board
    /// column cannot be created from the form (tix #1508) — a status the board
    /// does not configure renders in the Mismatched column, so the dropdown must
    /// not pretend to add one.
    fn allows_inline_create(self) -> bool {
        self != FormPickerField::Status
    }
}

/// Rows a mouse-wheel notch scrolls, in every surface that scrolls.
///
/// One constant rather than a number per handler: the detail pane and the keybindings
/// overlay (and anything else that scrolls later) move by the same amount, or the
/// wheel means something different depending on where the pointer happens to be.
const WHEEL_ROWS: u16 = 5;

/// How many detail panes the back stack keeps (tix #1513).
///
/// Following related links is unbounded, so the stack is not; the oldest pane is
/// dropped once the cap is reached, which keeps `Backspace` walking back toward
/// what the reader saw most recently.
const MAX_DETAIL_NAV: usize = 32;

/// How much of the keybindings overlay fits, and how far it can scroll (tix #1441).
///
/// Recorded by the overlay's own draw: its *handlers* need what only the renderer
/// knows, which is why the two numbers travel back through a `Cell` rather than being
/// recomputed from the key that was pressed.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
struct HelpMetrics {
    /// Binding rows the overlay can show at once.
    visible: u16,
    /// The largest `help_scroll` that still shows the last row.
    max_scroll: u16,
}

/// The editor round trip in flight (tix #1510).
///
/// Recorded when the editor is launched and consumed when it exits. `snapshot` is
/// the issue file's raw bytes at launch, and re-reading the same path after the
/// child exits is what makes a concurrent write — an agent editing through MCP,
/// a watcher, another session — detectable at all.
struct PendingEdit {
    /// The issue file, relative to the store's `issues_dir`.
    filename: String,
    /// The temp copy the editor writes to.
    temp: PathBuf,
    /// Raw bytes of the issue file when the editor was launched.
    snapshot: Vec<u8>,
}

/// Independent toggles are what a TUI session's state *is* — the mode lives in `Mode`,
/// and the flags beside it (archived shown, help line open, one-shot exit) are not
/// states a machine would model, they are switches the user throws. Four is not a
/// design smell here; a struct with a mode enum and a handful of toggles is the shape.
#[allow(clippy::struct_excessive_bools)]
pub struct App {
    pub mode: Mode,
    /// The active top-level mode of the shell (tui-mode-navigation). Session-only:
    /// it is derived from the current [`Mode`] by [`App::sync_top_mode`] and never
    /// persisted.
    pub top_mode: TopMode,
    /// How the vertical mode navigation is displayed (`Off`/`Small`/`Default`).
    /// Session-only, cycled by `toggle_navigation`; never persisted.
    pub nav_display: NavDisplay,
    /// Which rail row owns the keyboard, as an index into [`App::nav_rows`]
    /// (trunks and their limbs in draw order); `None` means the mode's content
    /// owns it. Session-only. Entered with `h`/`Left` when the active mode has
    /// no leftward target, left with `l`/`Right`/`Esc` (see
    /// [`App::handle_nav_key`]).
    nav_focus: Option<usize>,
    /// Whether the Config surface is currently standing in for the F5
    /// **Milestones** mode. The Milestones mode reuses the Config surface pinned
    /// to [`ConfigSection::Milestones`] rather than growing a second view; this
    /// flag is what makes the rail highlight Milestones (not Config), gives the
    /// mode its own [`InputContext::Milestones`] keys, and hides the Config
    /// section rail. Session-only, never persisted.
    pub milestone_mode: bool,
    pub board: BoardState,
    pub detail: Option<DetailState>,
    pub form: Option<FormState>,
    pub confirm_delete_target: Option<String>,
    pub store: Store,
    pub status_msg: Option<String>,
    pub quit: bool,
    pub bindings: EffectiveBindings,
    /// The raw bytes of `tix.toml` as last read, so a hand-edit during the
    /// session is adopted instead of linted against a stale configuration.
    config_snapshot: Option<Vec<u8>>,
    /// The active named board configuration index into `Config::configs()`
    /// (session state only — never persisted). `rebuild_board`/`apply_filter`
    /// must not reset it.
    pub active_config: usize,
    /// Persistent tabs bar of all named boards (DM-01M2MH8J01DZHV3JMT76XX38KX).
    pub tabs: BoardTabs,
    filter: Option<String>,
    corpus: Corpus,
    /// A second corpus snapshot that **includes archived** issues, built
    /// lazily the first time a `/` search runs and reused keystroke to
    /// keystroke (tix #1498).
    ///
    /// `corpus` above is the active set, built from [`crate::storage::Store::list`]
    /// so a repository full of archived files opens cheaply (tix #1492). Search
    /// must still find an archived issue — the whole point of "always search
    /// archived" — so it reads this snapshot instead, and only once a query is
    /// non-empty. [`App::refresh_corpus`] drops it, so the next search rebuilds
    /// it from whatever is on disk now. `None` also means "not yet built"; a
    /// build error leaves it `None` and the caller falls back to `corpus`, so a
    /// transient read failure degrades to an archived-blind search rather than
    /// no search at all.
    search_corpus: Option<Corpus>,
    /// Whether the board is showing **archived** issues too (tix #1492).
    ///
    /// Off by default, and that default is the point: the board and the corpus are
    /// built from [`crate::storage::Store::list`], which drops a dot-prefixed file
    /// from the directory entry without opening it, so a repository with thousands of
    /// archived issues costs nothing to open. Toggling this on is the "reload them on
    /// demand" half — `refresh_corpus` re-reads the issue set with the archived files
    /// included and rebuilds the board around it.
    pub show_archived: bool,
    /// Whether the board draws each issue's sub-issues beneath it (tix #1399).
    ///
    /// Off by default. Session-only, like [`App::show_archived`] — it is a view
    /// preference, not a setting written back to `tix.toml`. The `u` toggle flips it
    /// and rebuilds the board, which reorders each column so a sub-issue follows its
    /// parent indented one level (see `BoardState::build_with`); no store re-read is
    /// needed because the children are already in the issue set.
    pub show_children: bool,
    /// How many rows the keybindings overlay is scrolled down (tix #1441).
    ///
    /// Reset when the overlay opens, so `?` always starts at the top: a help screen
    /// that reappears halfway down, from a scroll three sessions ago, would hide the
    /// first bindings from exactly the person who needed them.
    help_scroll: u16,
    /// The keybindings overlay's `/` query, and whether the input line has the
    /// keyboard (tix #1496).
    ///
    /// Cleared when the overlay opens, like the scroll offset and for the same reason:
    /// a help screen that reappeared filtered by a query from ten minutes ago would
    /// hide the binding the reader opened it to find.
    help_query: String,
    help_searching: bool,
    /// The overlay's last-rendered geometry, recorded by its own draw (tix #1441).
    ///
    /// A `Cell` for the same reason `frame_hit_regions` is a `RefCell`: the renderer
    /// takes `&App`, and it is the only thing that knows how many rows fit.
    help_metrics: std::cell::Cell<HelpMetrics>,
    /// Cards one screen of the active board column holds, as of the last draw
    /// (tix #1442 follow-up).
    ///
    /// Reported by the board renderer, which is the only thing that knows the column's
    /// height and each card's rendered height; a `Cell` for the same reason
    /// `help_metrics` is one — the renderer holds `&App`.
    board_page: std::cell::Cell<usize>,
    pub filter_modal: Option<crate::ui::filter_modal::FilterModal>,
    /// Config mode state (F12, `s`, `b`): the active section and the dashboards
    /// row cursor. `Some` exactly while [`Mode::Settings`] (and its planning
    /// sub-forms) is active.
    pub settings: Option<SettingsModal>,
    /// Planning cursor: the `m` management surface's list state, and the same
    /// cursor the Config mode's cycles/milestones sections drive (one state, not
    /// two).
    pub planning: Option<PlanningModal>,
    /// Create/edit form for a planning item.
    pub planning_form: Option<PlanningForm>,
    /// Open calendar date picker (overlaid on the form that opened it).
    pub date_picker: Option<DatePicker>,
    /// Committed structured filter (kept when the modal is closed). The live
    /// in-progress criteria come from `filter_modal` while it is open.
    structured: search::StructuredFilter,
    rollover_dialog: Option<RolloverDialog>,
    form_picker: Option<FormPicker>,
    /// One-shot render (`tix render`): suppresses the keyboard hint bar.
    one_shot: bool,
    /// Click targets recorded by widgets during the current draw; cleared at
    /// the start of every draw and resolved by [`App::resolve_region`] when a
    /// pointer event arrives (D3). `RefCell` lets the &-borrowing render pass
    /// record regions while `handle_mouse` resolves them later (D6).
    frame_hit_regions: RefCell<Vec<HitRegion>>,
    /// Mouse click/drag state (D4).
    mouse: MouseState,
    /// Open issue context menu (D5): `Some` exactly while `mode` is
    /// [`Mode::ContextMenu`].
    context_menu: Option<ContextMenu>,
    /// The batch modal (WP07), `Some` exactly while `mode` is
    /// [`Mode::BulkModal`].
    pub bulk: Option<crate::ui::bulk::BulkModal>,
    /// The triage inbox (WP06), `Some` exactly while `mode` is
    /// [`Mode::TriageInbox`]. Its cursor and selection are its own — see the
    /// note on that mode.
    pub triage: Option<crate::ui::triage::TriageState>,
    /// The F3 Cycle mode's cursor (tui-cycle-mode), `Some` exactly while `mode`
    /// is [`Mode::Cycle`]. Its selection is its own, like the triage inbox's.
    pub cycle_state: Option<crate::ui::cycle::CycleState>,
    /// The mode the planning-management modal returns to when it closes: the
    /// board when opened with `m` there, the F3 Cycle mode when opened from it
    /// (tui-cycle-mode / planning-management). Session-only.
    planning_return: Mode,
    /// Column currently shown as the drag-drop target while a card is held.
    drag_preview_col: Option<usize>,
    /// The action of the innermost hit region under the pointer as of the last
    /// `Moved` event, so any widget can style itself when hovered (the vertical
    /// mode navigation in every mode, the Config section rail, dropdown rows).
    /// `None` when the pointer is not over a recorded region.
    hover_action: Option<Action>,
    /// The terminal size of the most recent draw, remembered so pointer
    /// coordinates can be mapped onto the board render area (D3).
    frame_size: Cell<Rect>,
    /// The editor round trip currently in flight, if any (tix #1510). `Some` only
    /// between the snapshot taken before the editor is launched and the decision
    /// [`App::after_editor`] makes when it exits, so it is also the signal that a
    /// pre-edit snapshot exists to compare against.
    pending_edit: Option<PendingEdit>,
    /// The detail pane's back stack, bounded (tix #1513).
    ///
    /// A pane is pushed when the reader opens a **related** entry from an open
    /// pane, so `Backspace` can return to where the jump started. Snapshotting the
    /// whole [`DetailState`] rather than a filename is what keeps the stack honest
    /// for a `Path` entry: the previous pane may itself have been an external,
    /// read-only file with no store entry to re-open.
    ///
    /// Bounded because following links is unbounded by nature — a chain of
    /// cross-repo references can be arbitrarily long, and a session that walks a
    /// thousand of them must not grow the stack without limit. The **oldest** entry
    /// is dropped, so the back key always walks back toward what the reader saw
    /// most recently.
    nav_stack: Vec<DetailState>,
    /// The open related-issues picker, `Some` exactly while it overlays the detail
    /// pane (tix #1513). `input_context` reports [`InputContext::RelatedPicker`]
    /// while it is `Some`, exactly as `form_picker` does for the form.
    related_picker: Option<DropdownState>,
}

impl App {
    /// Record a disclosure raised by a write, alongside whatever confirmation the
    /// action already produced.
    ///
    /// Cycle-4 F4. The event loop drains at the *top* of the loop body, so a
    /// disclosure raised by `handle_key` at the bottom would overwrite that
    /// action's confirmation message before any frame ever drew it — the user
    /// moved an issue and never saw "Moved #1 to in progress". Composing is the
    /// fix: both facts are true, and both are worth showing.
    ///
    /// The disclosure is appended rather than prepended so the confirmation reads
    /// first, which is the order the user caused them in. The existing message
    /// is left untouched, so this cannot swallow anything either.
    pub fn note_disclosure(&mut self, disclosure: String) {
        // Disclosure first, then the confirmation. Order alone does **not** make
        // it fit: the status area is a single unwrapped row, so at 80 columns a
        // disclosure plus a long filename is cut regardless of order. Cycle 6
        // measured this and found the claim previously recorded here — that
        // reordering made the actionable tail survive — to be false at 80, 100
        // and 120 columns.
        //
        // What actually helps is that the disclosure now *leads with the action*
        // ("remove `links:` by hand to silence"), so the instruction is the part
        // that survives a long filename, plus an ellipsis at the render site so a
        // cut is visible rather than silent. The full text remains in
        // `tix lint`, which is the durable channel for it.
        self.status_msg = Some(match self.status_msg.take() {
            Some(existing) if !existing.is_empty() => format!("{disclosure} — {existing}"),
            _ => disclosure,
        });
    }

    pub fn new(config: &Config) -> Result<Self> {
        let store = Store::open(config)?;
        // The bytes `tix.toml` had at startup, so a hand-edit made while the TUI
        // is open can be noticed and adopted (see `reload_config_if_changed`).
        let config_snapshot = store
            .config_path()
            .ok()
            .and_then(|path| std::fs::read(path).ok());
        let tabs = BoardTabs::new(config.configs().map(|(name, _)| name.to_string()).collect());
        // One enumeration for the whole startup (tix #1518). Before this, the
        // board, the corpus and the rollover plan each walked the tree — the
        // board and corpus once each, the rollover plan once per expired cycle
        // — so a cold start read and parsed every issue file three or four
        // times over. All three now build from this single slice.
        let issues = store.list()?;
        let board_config = config.default_config();
        let resolution = BoardState::resolution_for(&store, board_config);
        let board =
            BoardState::build_from_issues(&issues, board_config, &store.config, &resolution, false);
        let planner = Planner::from_config(config.clone(), std::path::PathBuf::from("."));
        let rollover_plan = planner.rollover_plan_from(&issues, &today());
        let corpus = Corpus::from_issues(issues);
        let rollover_dialog = if rollover_plan.is_empty() {
            None
        } else {
            Some(RolloverDialog::new(
                rollover_plan
                    .into_iter()
                    .map(|p| (p.from_cycle, p.to_cycle, p.issues.len()))
                    .collect(),
            ))
        };
        Ok(App {
            mode: if rollover_dialog.is_some() {
                Mode::RolloverDialog
            } else {
                Mode::Board
            },
            top_mode: TopMode::default(),
            nav_display: NavDisplay::default(),
            nav_focus: None,
            milestone_mode: false,
            board,
            // The default board is the active set; archived issues are read only
            // when the toggle asks for them (tix #1492).
            show_archived: false,
            show_children: false,
            help_scroll: 0,
            help_query: String::new(),
            help_searching: false,
            help_metrics: std::cell::Cell::new(HelpMetrics::default()),
            board_page: std::cell::Cell::new(0),
            detail: None,
            form: None,
            confirm_delete_target: None,
            store,
            status_msg: None,
            quit: false,
            bindings: config.effective_keybindings()?,
            config_snapshot,
            active_config: 0,
            tabs,
            filter: None,
            corpus,
            search_corpus: None,
            filter_modal: None,
            settings: None,
            planning: None,
            planning_form: None,
            date_picker: None,
            structured: search::StructuredFilter::default(),
            rollover_dialog,
            form_picker: None,
            one_shot: false,
            frame_hit_regions: RefCell::new(Vec::new()),
            mouse: MouseState::default(),
            hover_action: None,
            context_menu: None,
            bulk: None,
            triage: None,
            cycle_state: None,
            planning_return: Mode::Board,
            drag_preview_col: None,
            frame_size: Cell::new(Rect::new(0, 0, 0, 0)),
            pending_edit: None,
            nav_stack: Vec::new(),
            related_picker: None,
        })
    }

    /// The active `BoardConfiguration` indexed by [`App::active_config`].
    fn active_board_config(&self) -> &BoardConfiguration {
        self.store
            .config
            .configs()
            .nth(self.active_config)
            .map(|(_, board)| board)
            .unwrap_or_else(|| self.store.config.default_config())
    }

    /// The navigation tree: each trunk mode with the limbs drawn under it
    /// (tui-mode-navigation).
    ///
    /// Built from the live config and registry, so the rail cannot disagree with
    /// the surfaces a branch activates. Boards, cycles and templates come from
    /// `Config`; only the milestone names touch the filesystem (a directory
    /// listing of tiny records), and an empty group renders no rows.
    pub fn nav_tree(&self) -> Vec<crate::ui::nav::NavNode> {
        use crate::ui::nav::{BranchKind, NavBranch, NavNode};

        let active_board = self.active_board_name().to_string();
        let active_cycle = self.active_cycle_name();
        let active_milestone = self.active_milestone_name();
        let planner = || Planner::from_config(self.store.config.clone(), self.project_root());
        TopMode::ALL
            .iter()
            .map(|mode| {
                let branches = match mode {
                    // Every configured board is a limb; the active one is marked
                    // so the rail bolds it. The horizontal board tab bar stays as
                    // the always-visible active-board indicator on Board mode.
                    TopMode::Board => self
                        .store
                        .config
                        .configs()
                        .map(|(name, _)| NavBranch {
                            label: name.to_string(),
                            action: Action::SelectBoard(name.to_string()),
                            kind: BranchKind::Board,
                            active: name == active_board,
                        })
                        .collect(),
                    TopMode::Cycle => planner()
                        .cycle_names()
                        .into_iter()
                        .map(|name| NavBranch {
                            label: name.clone(),
                            active: active_cycle.as_deref() == Some(name.as_str()),
                            action: Action::SelectCycle(name),
                            kind: BranchKind::Cycle,
                        })
                        .collect(),
                    TopMode::Milestones => planner()
                        .list_milestones()
                        .unwrap_or_default()
                        .into_iter()
                        .map(|milestone| NavBranch {
                            active: active_milestone.as_deref() == Some(milestone.name.as_str()),
                            label: milestone.name.clone(),
                            action: Action::SelectMilestone(milestone.name),
                            kind: BranchKind::Milestone,
                        })
                        .collect(),
                    TopMode::NewIssue => self
                        .store
                        .config
                        .templates
                        .keys()
                        .map(|name| NavBranch {
                            label: name.clone(),
                            action: Action::NewFromTemplate(name.clone()),
                            kind: BranchKind::Template,
                            active: false,
                        })
                        .collect(),
                    TopMode::Triage | TopMode::Config => Vec::new(),
                };
                NavNode {
                    mode: *mode,
                    branches,
                }
            })
            .collect()
    }

    /// The column width the rail needs for its current content.
    ///
    /// Grown past [`NavDisplay::width`] so the widest trunk or branch line is
    /// drawn whole (one space of separation from the content area) rather than
    /// clipped — that is what lets `Default` show a full branch name.
    pub fn nav_width(&self) -> u16 {
        if self.nav_display == NavDisplay::Off {
            return 0;
        }
        let mut width = self.nav_display.width();
        for node in self.nav_tree() {
            let chord = self.bindings.label(InputContext::Shell, node.mode.action());
            let trunk = if self.nav_display == NavDisplay::Small {
                chord.chars().count()
            } else {
                chord.chars().count() + 1 + self.mode_label(node.mode).chars().count()
            };
            width = width.max(trunk as u16 + 1);
            if self.nav_display != NavDisplay::Small {
                for branch in &node.branches {
                    width = width.max(2 + branch.label.chars().count() as u16 + 1);
                }
            }
        }
        width
    }

    /// The trunk label for `mode`: the singular name, or the plural when the
    /// mode owns **more than one** record — boards by configured count, cycles
    /// by [`Planner::cycle_names`], milestones by [`Planner::list_milestones`].
    /// The chord is never affected; only the noun moves.
    pub fn mode_label(&self, mode: TopMode) -> &'static str {
        let planner = || Planner::from_config(self.store.config.clone(), self.project_root());
        let plural = match mode {
            TopMode::Board => self.store.config.configs().count() > 1,
            TopMode::Cycle => planner().cycle_names().len() > 1,
            TopMode::Milestones => planner().list_milestones().unwrap_or_default().len() > 1,
            TopMode::NewIssue | TopMode::Triage | TopMode::Config => false,
        };
        mode.label(plural)
    }

    /// The rail's rows in draw order — each trunk followed by its limbs, exactly
    /// as [`crate::ui::nav::render`] paints them. The keyboard cursor indexes
    /// this list; the pointer's hit regions come from the same tree.
    pub fn nav_rows(&self) -> Vec<Action> {
        let mut rows = Vec::new();
        for node in self.nav_tree() {
            rows.push(Action::SwitchMode(node.mode));
            rows.extend(node.branches.iter().map(|branch| branch.action.clone()));
        }
        rows
    }

    /// The index of the rail row holding the keyboard cursor, `None` when the
    /// mode content owns the keyboard.
    pub fn nav_focus_index(&self) -> Option<usize> {
        self.nav_focus
    }

    /// Whether rail row `index` holds the keyboard cursor. The rail draws such a
    /// row exactly like a hovered one.
    pub fn nav_row_focused(&self, index: usize) -> bool {
        self.nav_focus == Some(index)
    }

    /// Whether the active mode has **no leftward target**, so `h`/`Left` means
    /// "enter the rail" rather than "move left".
    ///
    /// The board answers with its left edge, the Cycle mode with its first
    /// entry, the Config surface with its section rail already focused, and the
    /// Milestones mode (which draws no rail of its own) always. Every other
    /// mode answers `false`, so no existing key changes meaning where a target
    /// exists.
    fn rail_entry_available(&self) -> bool {
        if self.nav_display == NavDisplay::Off {
            return false;
        }
        match &self.mode {
            Mode::Board => self.board.real_cols() == 0 || self.board.active_col == 0,
            Mode::Cycle => self.cycle_state.as_ref().map_or(0, |state| state.selected) == 0,
            Mode::Settings => {
                self.milestone_mode
                    || self
                        .settings
                        .as_ref()
                        .is_some_and(|modal| modal.pane == ConfigPane::Sections)
            }
            _ => false,
        }
    }

    /// Put the keyboard cursor on the rail, at the current top mode's trunk row
    /// (or the first row when that mode has no trunk). Idempotent.
    fn focus_rail(&mut self) {
        if self.nav_focus.is_some() {
            return;
        }
        let rows = self.nav_rows();
        let index = rows
            .iter()
            .position(|action| *action == Action::SwitchMode(self.top_mode))
            .unwrap_or(0);
        self.nav_focus = Some(index);
    }

    /// The rail's keys while it owns the keyboard.
    ///
    /// `j`/`k` and the arrows walk the flattened trunk+limb rows; `Enter`, `l`
    /// and `→` activate the focused row — a trunk switches modes, a limb runs
    /// exactly the action a click on it runs — and hand the keyboard to the
    /// opened content on the right, the same result a click has; `Esc` (and `←`)
    /// leave the rail without activating. Anything else is swallowed: the rail
    /// has focus, and a half-applied board key would act on a surface the user is
    /// not looking at.
    fn handle_nav_key(&mut self, key: KeyEvent) -> Result<Action> {
        let rows = self.nav_rows();
        let last = rows.len().saturating_sub(1);
        match key.code {
            KeyCode::Up | KeyCode::Char('k') => {
                if let Some(index) = self.nav_focus.as_mut() {
                    *index = index.saturating_sub(1);
                }
            }
            KeyCode::Down | KeyCode::Char('j') => {
                if let Some(index) = self.nav_focus.as_mut() {
                    *index = usize::min(index.saturating_add(1), last);
                }
            }
            KeyCode::Enter | KeyCode::Right | KeyCode::Char('l') => {
                self.activate_focused_rail_row()?;
                // Opening a row hands the keyboard to the surface on the right,
                // exactly like a click; the rail keeps the cursor only while the
                // user is walking it.
                self.nav_focus = None;
            }
            KeyCode::Left | KeyCode::Esc => self.nav_focus = None,
            _ => {}
        }
        Ok(Action::None)
    }

    /// Run the rail row under the keyboard cursor: a trunk switches modes, a limb
    /// runs exactly the action a click on it runs. A missing cursor (or one that
    /// drifted past the end) does nothing.
    fn activate_focused_rail_row(&mut self) -> Result<()> {
        let action = self
            .nav_focus
            .and_then(|index| self.nav_rows().get(index).cloned());
        match action {
            Some(Action::SwitchMode(mode)) => {
                self.switch_top_mode(mode)?;
            }
            // Branch limbs: the same transition their click runs.
            Some(other) => {
                self.activate_branch(&other)?;
            }
            None => {}
        }
        Ok(())
    }

    /// The category resolution for the board the TUI is currently showing.
    ///
    /// WP05. Derived from [`Self::active_board_config`], so it is the resolution of
    /// the board on screen rather than of whichever board is `default` — the TUI can
    /// display any configured board, and a card showing another board's categories is
    /// a wrong answer rather than a missing one.
    fn workflow_resolution(&self) -> crate::workflow::CategoryResolution {
        let name = self
            .store
            .config
            .configs()
            .nth(self.active_config)
            .map(|(name, _)| name)
            .unwrap_or("default");
        crate::workflow::resolution(&self.store.config, self.active_board_config(), name)
    }

    /// The category label and color hint for `issue`, as the detail view shows them.
    ///
    /// WP05 T023. Resolved through the service against the board on screen, and
    /// derived rather than stored — an issue's category changes when its column
    /// changes or when the board's `category_map` is edited, and a value captured
    /// when the detail was opened would be stale for exactly as long as the view
    /// stayed open.
    fn category_of_issue(
        &self,
        issue: &crate::model::Issue,
    ) -> Option<(String, Option<crate::workflow::ColorHint>)> {
        let resolution = self.workflow_resolution();
        crate::workflow::category_of(issue, &resolution)
            .map(|c| (c.label().to_string(), c.color_hint()))
    }

    pub fn handle_key(&mut self, key: KeyEvent) -> Result<Action> {
        if key.kind != KeyEventKind::Press {
            return Ok(Action::None);
        }
        let context = self.input_context();
        // The mode shell is consulted **before** the `F(12)` sentinel rewrite
        // (tui-mode-navigation, D2). A shell chord (F1–F4/F12, ctrl+n) switches
        // modes only when the active top-level context does not bind the key
        // itself — so `F2` inside a form is still `open_picker`, and a genuinely
        // unbound key still becomes the sentinel.
        if let Some(action) = self.shell_action(context, key) {
            let result = self.run_shell_action(action);
            self.sync_top_mode();
            return result;
        }
        // The rail owns the keyboard while it is focused, and is entered with
        // `h`/`Left` when the active mode has no leftward target of its own
        // (see `rail_entry_available`). Both checks sit after the shell chords,
        // so a mode switch still works from inside the rail, and before the
        // binding resolution, so the rail's `j`/`k`/`Enter` are read raw rather
        // than rewritten to the mode's own bindings. A text-entry context is
        // never intercepted: `h` there is a letter.
        if self.nav_focus.is_some() {
            return self.handle_nav_key(key);
        }
        if !Self::allows_text_fallback(context)
            && matches!(key.code, KeyCode::Left | KeyCode::Char('h'))
            && self.rail_entry_available()
        {
            self.focus_rail();
            return Ok(Action::None);
        }
        let key = self
            .bindings
            .action(context, key)
            .map(|action| self.bindings.canonical_event(context, action))
            .unwrap_or_else(|| {
                if Self::allows_text_fallback(context) {
                    key
                } else {
                    KeyEvent::new(KeyCode::F(12), KeyModifiers::NONE)
                }
            });
        let result = self.handle_resolved_key(context, key);
        self.sync_top_mode();
        result
    }

    /// The shell action a key resolves to in `context`, if any.
    ///
    /// `None` unless the context is one of the five top-level modes, the context
    /// does **not** bind the key, and the shell context does. The local binding
    /// always wins: this is the single rule that keeps `F2`-in-form as the picker.
    fn shell_action(&self, context: InputContext, key: KeyEvent) -> Option<TuiAction> {
        if !matches!(
            context,
            InputContext::Board
                | InputContext::Triage
                | InputContext::Cycle
                | InputContext::Milestones
                | InputContext::PlanningManagement
                | InputContext::Settings
                | InputContext::Form
        ) {
            return None;
        }
        if self.bindings.action(context, key).is_some() {
            return None;
        }
        self.bindings.action(InputContext::Shell, key)
    }

    /// Run a shell action: switch modes or cycle the navigation display.
    fn run_shell_action(&mut self, action: TuiAction) -> Result<Action> {
        match action {
            TuiAction::SwitchToBoard => self.switch_top_mode(TopMode::Board),
            TuiAction::SwitchToTriage => self.switch_top_mode(TopMode::Triage),
            TuiAction::SwitchToCycle => self.switch_top_mode(TopMode::Cycle),
            TuiAction::SwitchToMilestones => self.switch_top_mode(TopMode::Milestones),
            TuiAction::SwitchToNewIssue => self.switch_top_mode(TopMode::NewIssue),
            TuiAction::SwitchToConfig => self.switch_top_mode(TopMode::Config),
            TuiAction::ToggleNavigation => {
                self.nav_display = self.nav_display.next();
                if self.nav_display == NavDisplay::Off {
                    // A cursor on a rail nobody can see is a keyboard trap.
                    self.nav_focus = None;
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Switch the shell to `target`, reusing each mode's existing open path.
    ///
    /// The sibling top-level state is dropped first so a switch does not leave a
    /// stale modal behind to reappear when the mode is left again; the *openers*
    /// are the same methods the letter keys call.
    pub fn switch_top_mode(&mut self, target: TopMode) -> Result<Action> {
        // Released by default; only the Milestones arm re-arms it after opening
        // the Config surface. Keeping this here (not derived from the target in
        // `open_settings`) means every other entry point — `s`, `b` — is Config.
        self.milestone_mode = false;
        match target {
            TopMode::Board => {
                self.close_top_level_state();
                self.mode = Mode::Board;
                self.rebuild_board();
            }
            TopMode::Triage => {
                self.close_top_level_state();
                self.mode = Mode::Board;
                let result = self.open_triage_inbox();
                self.sync_top_mode();
                return result;
            }
            TopMode::Cycle => {
                self.close_top_level_state();
                self.cycle_state = Some(crate::ui::cycle::CycleState::default());
                self.mode = Mode::Cycle;
            }
            TopMode::NewIssue => {
                self.close_top_level_state();
                self.open_new_issue_form();
            }
            TopMode::Config => {
                self.close_top_level_state();
                self.open_settings(None);
            }
            TopMode::Milestones => {
                // The Milestones mode is the Config surface pinned to the
                // milestones section, with the section rail hidden (`render_config`
                // checks `milestone_mode`). Pinning the planning segment here means
                // the body's row cursor is already the milestones list.
                self.close_top_level_state();
                self.open_settings(None);
                self.milestone_mode = true;
                if let Some(settings) = self.settings.as_mut() {
                    settings.section = ConfigSection::Milestones;
                    // No rail is drawn; the body owns the keys.
                    settings.focus(ConfigPane::Body);
                }
                let modal = self.planning.get_or_insert_with(PlanningModal::new);
                modal.segment = PlanningSegment::Milestones;
                modal.prompt = None;
                modal.selected = 0;
            }
        }
        self.sync_top_mode();
        Ok(Action::None)
    }

    /// Drop the state of any top-level mode, so a switch starts clean.
    fn close_top_level_state(&mut self) {
        self.triage = None;
        self.cycle_state = None;
        self.settings = None;
        self.planning = None;
        self.planning_form = None;
        self.date_picker = None;
        self.form = None;
        self.form_picker = None;
        self.filter_modal = None;
        // A message about the mode being left would be stale over the mode being
        // entered; a refusal raised by the new mode's opener sets its own afterwards.
        self.status_msg = None;
    }

    /// Record the top-level mode implied by the current [`Mode`].
    ///
    /// Derived rather than assigned at every entry point: `t`, `m`, `n`, `s`, and
    /// every close path already move `mode`, so reading it back keeps the
    /// navigation highlight in step without a second place to update.
    ///
    /// A planning form or date picker opened **from the Config mode** belongs to
    /// Config, not to the Cycle mode its input context would otherwise imply:
    /// `settings` is `Some` exactly while the Config mode's state is present, and
    /// its sub-surfaces keep it.
    fn sync_top_mode(&mut self) {
        if self.settings.is_some() {
            // The Config surface hosts two top-level modes: F12 Config, and the
            // F5 Milestones mode that borrows it (`milestone_mode`). The flag,
            // not the `InputContext`, decides which — `Milestones` is only one of
            // the contexts this surface can be in.
            self.top_mode = if self.milestone_mode {
                TopMode::Milestones
            } else {
                TopMode::Config
            };
            return;
        }
        if let Some(mode) = Self::top_mode_for_context(self.input_context()) {
            self.top_mode = mode;
        }
    }

    fn top_mode_for_context(context: InputContext) -> Option<TopMode> {
        match context {
            InputContext::Board => Some(TopMode::Board),
            InputContext::Triage => Some(TopMode::Triage),
            InputContext::Cycle => Some(TopMode::Cycle),
            InputContext::PlanningManagement
            | InputContext::PlanningConfirm
            | InputContext::PlanningForm
            | InputContext::DatePicker => Some(TopMode::Cycle),
            InputContext::Settings | InputContext::SettingsPrompt => Some(TopMode::Config),
            InputContext::Milestones => Some(TopMode::Milestones),
            InputContext::Form | InputContext::FormPicker => Some(TopMode::NewIssue),
            _ => None,
        }
    }

    fn allows_text_fallback(context: InputContext) -> bool {
        matches!(
            context,
            InputContext::Form
                | InputContext::FormPicker
                | InputContext::Filter
                | InputContext::FilterModal
                // #1496: the overlay's `/` line takes free text. Without this, every
                // letter arrives as `F(12)` — the rewrite happens before the handler sees
                // the key — and the search line would be untypeable. The *list* mode is
                // deliberately not listed here: it has no text entry, so an unbound key
                // there is a no-op either way.
                | InputContext::HelpSearch
                | InputContext::PlanningForm
                | InputContext::Comment
                | InputContext::Asset
                | InputContext::MoveIntoDone
                | InputContext::LinkPrompt
                | InputContext::SettingsPrompt
                | InputContext::BulkModal
                | InputContext::Triage
        )
    }

    fn input_context(&self) -> InputContext {
        match &self.mode {
            Mode::Board => InputContext::Board,
            Mode::RolloverDialog => InputContext::Rollover,
            Mode::Detail if self.related_picker.is_some() => InputContext::RelatedPicker,
            Mode::Detail => InputContext::Detail,
            Mode::Form if self.form_picker.is_some() => InputContext::FormPicker,
            Mode::Form => InputContext::Form,
            Mode::ConfirmDelete => InputContext::ConfirmDelete,
            Mode::MoveIntoDone { .. } => InputContext::MoveIntoDone,
            Mode::TransitionReason { .. } => InputContext::MoveIntoDone,
            Mode::ConfirmBlockedMove { .. } => InputContext::ConfirmBlockedMove,
            Mode::Help { .. } if self.help_searching => InputContext::HelpSearch,
            Mode::Help { .. } => InputContext::Help,
            Mode::ContextMenu { .. } => InputContext::ContextMenu,
            Mode::Filter { .. } => InputContext::Filter,
            Mode::FilterModal => InputContext::FilterModal,
            Mode::Settings
                if self
                    .settings
                    .as_ref()
                    .is_some_and(|modal| modal.prompt.is_some())
                    // A planning delete confirmation raised from the Config
                    // mode's cycles/milestones sections is answered with the
                    // same `y`/`esc` keys, so it uses the same context.
                    || self
                        .planning
                        .as_ref()
                        .is_some_and(|modal| modal.prompt.is_some()) =>
            {
                InputContext::SettingsPrompt
            }
            Mode::Settings if self.milestone_mode => InputContext::Milestones,
            Mode::Settings => InputContext::Settings,
            Mode::PlanningManagement
                if self
                    .planning
                    .as_ref()
                    .is_some_and(|modal| modal.prompt.is_some()) =>
            {
                InputContext::PlanningConfirm
            }
            Mode::PlanningManagement => InputContext::PlanningManagement,
            Mode::PlanningForm => InputContext::PlanningForm,
            Mode::DatePicker { .. } => InputContext::DatePicker,
            Mode::Comment { .. } => InputContext::Comment,
            Mode::Asset { .. } => InputContext::Asset,
            Mode::EditRepair { .. } => InputContext::EditRepair,
            Mode::EditConflict { .. } => InputContext::EditConflict,
            Mode::LinkCreate { .. } | Mode::LinkEdit { .. } => InputContext::LinkPrompt,
            Mode::ConfirmRemoveRelationship { .. } => InputContext::ConfirmDelete,
            Mode::BulkModal => InputContext::BulkModal,
            Mode::TriageInbox => InputContext::Triage,
            Mode::Cycle => InputContext::Cycle,
        }
    }

    /// The batch modal's keys (WP07 T032/T033).
    ///
    /// Every branch here either changes the modal's **own** state or calls a shared
    /// service. There is no `IssuePatch` built here and no `store.update` here: the
    /// modal holds `PatchFlags` and the plan/apply live in `bulk::plan`/`bulk::apply`,
    /// which is what "reject TUI-local patch construction or direct writes" asks for.
    ///
    /// `p` previews, `y` **arms** and then `y` again confirms, and `esc` cancels from
    /// any state. Two `y` presses because "I saw it" and "I approved it" are two
    /// decisions, and one `y` conflates them.
    /// Open the batch modal, optionally marking the card under the cursor first.
    ///
    /// `mark` is what makes `space` on a card the first press rather than two. It
    /// marks **only if** the selection is not already refused — a duplicate or a
    /// full selection is reported on the modal's note, not silently swallowed, so
    /// the second `space` on the same card tells the user why nothing changed.
    ///
    /// The board's `(active_col, selected)` cursor is never written here, so opening
    /// and cancelling the modal restores the board exactly (T031).
    fn open_bulk_modal(&mut self, action: crate::ui::bulk::BatchAction, mark: bool) {
        if mark {
            let number = self.board.get_selected_card().map(|c| c.number);
            let mut modal = self
                .bulk
                .take()
                .unwrap_or_else(|| crate::ui::bulk::BulkModal::new(action));
            if let Some(number) = number {
                if let Err(problem) = modal.selection.toggle(number) {
                    modal.note = Some(problem.to_string());
                }
            }
            self.bulk = Some(modal);
        } else if self.bulk.is_none() {
            self.bulk = Some(crate::ui::bulk::BulkModal::new(action));
        }
        self.mode = Mode::BulkModal;
    }

    /// Open the triage inbox (`t`).
    ///
    /// A refusal — no `[triage]` section in this project, or an I/O failure —
    /// is reported on the status line and **nothing else changes**: a project
    /// that does not use triage leaves the board exactly where it was, which is
    /// T029's "navigation is unchanged when the tab is not active" from the
    /// other side.
    fn open_triage_inbox(&mut self) -> Result<Action> {
        match crate::ui::triage::TriageState::open(&self.store) {
            Ok(state) => {
                self.triage = Some(state);
                self.mode = Mode::TriageInbox;
            }
            Err(e) => self.status_msg = Some(e.to_string()),
        }
        Ok(Action::None)
    }

    /// The inbox's keys (WP06, T029–T032).
    ///
    /// Two layers, exactly as the batch modal has one: an open decision modal
    /// takes the key first, and the list has it otherwise. Every branch here
    /// either moves a cursor that belongs to *this* view or calls a shared
    /// service — no `IssuePatch`, no `store.update`, and no status compared
    /// against a literal. Cancellation drops the modal and changes nothing else;
    /// the queue is re-read only after an apply has actually run.
    fn handle_triage_key(&mut self, key: KeyEvent) -> Result<Action> {
        use crate::ui::triage::ModalState;

        let Some(mut state) = self.triage.take() else {
            self.mode = Mode::Board;
            return Ok(Action::None);
        };

        let editing = state.modal.as_ref().is_some_and(|m| m.editing);
        let armed = state.modal.as_ref().is_some_and(|m| m.is_armed());
        let previewed = matches!(
            state.modal.as_ref().map(|m| &m.state),
            Some(ModalState::Preview(_))
        );
        let mut closed = false;
        let mut wrote = false;
        let mut chosen: Option<(TriageDropdownKind, String)> = None;
        let mut create_title: Option<String> = None;
        let mut activate: Option<TriageControl> = None;

        // Priority: picker, then create prompt, then decision modal, then list.
        // A picker and the create prompt can never coexist with a modal, so a
        // letter typed into a decline reason is never stolen (tui-triage-mode).
        if state.dropdown.is_some() {
            if let Some(choice) = state.handle_dropdown_key(key.code) {
                chosen = Some(choice);
            }
        } else if state.creating {
            match key.code {
                KeyCode::Esc => {
                    state.creating = false;
                    state.create_buffer.clear();
                }
                KeyCode::Enter => {
                    let title = state.create_buffer.trim().to_string();
                    state.creating = false;
                    state.create_buffer.clear();
                    if title.is_empty() {
                        state.note = Some("a title is required".to_string());
                    } else {
                        create_title = Some(title);
                    }
                }
                KeyCode::Backspace => {
                    state.create_buffer.pop();
                }
                KeyCode::Char(c) => state.create_buffer.push(c),
                _ => {}
            }
        } else if state.modal.is_some() {
            match key.code {
                // `esc` while a field is being typed reverts the draft rather
                // than closing — the footer says "esc revert", and a revert
                // that closed the modal would take the row it reverted with it.
                KeyCode::Esc if editing => {
                    if let Some(modal) = state.modal.as_mut() {
                        modal.abort_edit();
                    }
                }
                // Cancels from every state: the plan and the draft go, the
                // committed fields stay, and no file moved (T032). The report
                // goes with the user when it is a refusal — a refusal nobody
                // can re-read after pressing `esc` is not a report.
                KeyCode::Esc => {
                    let carried = match state.modal.as_ref().map(|m| &m.state) {
                        Some(ModalState::Done(text)) | Some(ModalState::Refused(text)) => {
                            Some(text.lines().next().unwrap_or(text.as_str()).to_string())
                        }
                        _ => None,
                    };
                    state.close_modal();
                    if carried.is_some() {
                        state.note = carried;
                    }
                }
                KeyCode::Enter if editing => {
                    if let Some(modal) = state.modal.as_mut() {
                        modal.commit_edit();
                    }
                }
                KeyCode::Enter => {
                    if let Some(modal) = state.modal.as_mut() {
                        modal.begin_edit();
                    }
                }
                KeyCode::Backspace if editing => {
                    if let Some(modal) = state.modal.as_mut() {
                        modal.pop_char();
                    }
                }
                KeyCode::Char(c) if editing => {
                    if let Some(modal) = state.modal.as_mut() {
                        modal.push_char(c);
                    }
                }
                // The cursor does not move while a field is being typed:
                // `commit_edit` writes the draft to the row the cursor is on,
                // so a cursor that could travel mid-edit would file half a
                // reason under the wrong label.
                KeyCode::Tab | KeyCode::Down | KeyCode::Char('j') if !editing => {
                    if let Some(modal) = state.modal.as_mut() {
                        modal.move_cursor(1);
                    }
                }
                KeyCode::BackTab | KeyCode::Up | KeyCode::Char('k') if !editing => {
                    if let Some(modal) = state.modal.as_mut() {
                        modal.move_cursor(-1);
                    }
                }
                // The target row, when the decision has one — the same `t` the
                // batch modal gives its pair target.
                KeyCode::Char('t') if !editing => {
                    if let Some(modal) = state.modal.as_mut() {
                        let wanted = if modal.kind == crate::triage::DecisionKind::Accept {
                            crate::ui::triage::DecisionField::Target
                        } else {
                            crate::ui::triage::DecisionField::DuplicateOf
                        };
                        if let Some(index) = modal.fields.iter().position(|f| *f == wanted) {
                            modal.cursor = index;
                        }
                    }
                }
                // Cycle the verb. The selection and the already-typed fields
                // survive it, for the reason the batch modal's `a` keeps the
                // selection: a user who marked ten does not re-mark them to
                // change their mind about what to do with them.
                KeyCode::Char('a') => {
                    if let Some(modal) = state.modal.as_mut() {
                        modal.cycle_kind();
                    }
                }
                KeyCode::Char('p') => state.preview(&self.store)?,
                KeyCode::Char('y') => {
                    if armed {
                        state.confirm(&self.store)?;
                        wrote = state.modal_finished();
                    } else if previewed {
                        state.confirm(&self.store)?;
                    } else {
                        state.note = Some("press `p` to preview first".to_string());
                    }
                }
                _ => {}
            }
            if wrote {
                // The plan ran, so the counts behind the modal are stale. Re-read
                // them now; the board underneath is refreshed when the inbox
                // closes.
                state.refresh(&self.store)?;
            }
        } else {
            match key.code {
                KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => closed = true,
                KeyCode::Up | KeyCode::Char('k') => state.move_cursor(-1),
                KeyCode::Down | KeyCode::Char('j') => state.move_cursor(1),
                KeyCode::Char(' ') => state.toggle_current(),
                KeyCode::Char('X') => state.clear_selection(),
                // Oldest first, the TUI's `--age`. Toggling re-reads the queue
                // rather than re-sorting a snapshot, so the ages cannot be
                // computed against two different `today`s.
                KeyCode::Char('A') => {
                    state.by_age = !state.by_age;
                    state.refresh(&self.store)?;
                }
                KeyCode::Char('a') => {
                    state.open_single(crate::triage::DecisionKind::Accept);
                }
                KeyCode::Char('d') => {
                    state.open_single(crate::triage::DecisionKind::Decline);
                }
                KeyCode::Char('u') => {
                    state.open_single(crate::triage::DecisionKind::Duplicate);
                }
                KeyCode::Char('f') => {
                    state.open_single(crate::triage::DecisionKind::Defer);
                }
                // The batch modal over everything marked; `a` inside it picks
                // the decision, exactly as the batch modal's `a` picks its
                // action.
                KeyCode::Char('p') => {
                    state.open_batch(crate::triage::DecisionKind::Accept);
                }
                // The status picker: exactly the active board's columns. The
                // direct key moves the focus onto the control it opened, the
                // same as a click or `enter` does.
                KeyCode::Char('s') => {
                    let columns = self.active_board_config().columns.clone();
                    let options = crate::ui::triage::status_options(&columns);
                    let current = state
                        .current()
                        .map(|row| row.issue.status.display().to_string());
                    state.focus = TriageControl::Status;
                    state.open_dropdown(TriageDropdownKind::Status, options, current.as_deref());
                }
                // The assignee picker: storage folders + team members + current.
                KeyCode::Char('@') => {
                    let current = state.current().and_then(|row| row.issue.assignee.clone());
                    let options =
                        crate::ui::triage::assignee_options(&self.store, current.as_deref());
                    state.focus = TriageControl::Assignee;
                    state.open_dropdown(TriageDropdownKind::Assignee, options, current.as_deref());
                }
                // Create an issue straight into the inbox's entry column.
                KeyCode::Char('n') => {
                    state.focus = TriageControl::New;
                    state.creating = true;
                    state.create_buffer.clear();
                }
                // The control bar's own axis (tui-triage-mode). `h`/`l` are
                // **raw** keys, never bindings in this context: the inbox is a
                // text-entry context (`allows_text_fallback`), so a binding
                // would rewrite those letters while a decline reason or a
                // duplicate target is being typed. This branch is reached only
                // with no modal, picker, or prompt open — the same "nothing is
                // being typed" state `!editing` names in the modal branch.
                KeyCode::Left | KeyCode::Char('h') => state.move_focus(-1),
                KeyCode::Right | KeyCode::Char('l') => state.move_focus(1),
                // `enter` activates the focused control. On `queue` it is the
                // no-op it has always been: the queue's keys act on the list
                // directly and need no activation step.
                KeyCode::Enter => activate = Some(state.focus),
                _ => {}
            }
        }

        if let Some(title) = create_title {
            self.triage = Some(state);
            self.create_triage_issue(&title)?;
            return Ok(Action::None);
        }
        if let Some((kind, id)) = chosen {
            self.triage = Some(state);
            match kind {
                TriageDropdownKind::Status => self.move_focused_triage_issue(&id)?,
                TriageDropdownKind::Assignee => self.assign_focused_triage_issue(&id)?,
            }
            return Ok(Action::None);
        }

        if closed {
            // The note goes to the status line rather than being dropped with
            // the view — the batch modal's handler does the same thing for the
            // same reason.
            let note = state.note.clone();
            self.triage = None;
            self.mode = Mode::Board;
            self.refresh_corpus()?;
            if note.is_some() {
                self.status_msg = note;
            }
            return Ok(Action::None);
        }

        self.triage = Some(state);
        self.mode = Mode::TriageInbox;
        // `enter` on the focused control runs the very same path a click on it
        // does, so the two can never drift.
        if let Some(control) = activate {
            match control {
                TriageControl::Queue => {}
                TriageControl::Status => self.open_triage_status_dropdown(),
                TriageControl::Assignee => self.open_triage_assignee_dropdown(),
                TriageControl::New => {
                    self.apply_triage_action(Action::TriageCreate)?;
                }
            }
            return Ok(Action::None);
        }
        Ok(Action::None)
    }

    /// Open the status picker: exactly the active board's columns, in board
    /// order, with the focused issue's current column preselected. The status
    /// control becomes the focused one, so `enter` reopens what a click opened
    /// (tui-triage-mode).
    fn open_triage_status_dropdown(&mut self) {
        let columns = self.active_board_config().columns.clone();
        let options = crate::ui::triage::status_options(&columns);
        if let Some(state) = self.triage.as_mut() {
            state.focus = TriageControl::Status;
            let current = state
                .current()
                .map(|row| row.issue.status.display().to_string());
            state.open_dropdown(TriageDropdownKind::Status, options, current.as_deref());
        }
    }

    /// Open the assignee picker: `docs/issues/<username>/` folders, configured
    /// team members, and the focused issue's current value (design D6). The
    /// assignee control becomes the focused one.
    fn open_triage_assignee_dropdown(&mut self) {
        let current = self
            .triage
            .as_ref()
            .and_then(|state| state.current())
            .and_then(|row| row.issue.assignee.clone());
        let options = crate::ui::triage::assignee_options(&self.store, current.as_deref());
        if let Some(state) = self.triage.as_mut() {
            state.focus = TriageControl::Assignee;
            state.open_dropdown(TriageDropdownKind::Assignee, options, current.as_deref());
        }
    }

    /// Move the focused triage issue to `target` through the **shared** move
    /// path, so the blocked-move and terminal-transition guards still apply. A
    /// refusal (an unacknowledged blocked move, a terminal exit without a
    /// reason) is reported on the mode's note rather than bypassed.
    fn move_focused_triage_issue(&mut self, target: &str) -> Result<()> {
        let Some(number) = self
            .triage
            .as_ref()
            .and_then(|state| state.current())
            .map(|row| row.issue.number)
        else {
            return Ok(());
        };
        match crate::commands::mv::apply_guarded(
            &self.store.config,
            &self.store,
            &number.to_string(),
            target,
            None,
            None,
            // No acknowledgement is offered inline: a blocked move stays blocked
            // rather than being written without the decision it requires.
            false,
        ) {
            Ok(moved) => {
                if let Some(state) = self.triage.as_mut() {
                    state.refresh(&self.store)?;
                    state.note = Some(format!("Moved #{} to {target}", moved.issue.number));
                }
                self.refresh_corpus()?;
            }
            Err(e) => {
                if let Some(state) = self.triage.as_mut() {
                    state.note = Some(e.to_string());
                }
            }
        }
        Ok(())
    }

    /// Set the focused triage issue's assignee through `tix edit --assignee`'s
    /// own core, so the field and the file relocation are exactly the CLI's.
    fn assign_focused_triage_issue(&mut self, assignee: &str) -> Result<()> {
        let Some(number) = self
            .triage
            .as_ref()
            .and_then(|state| state.current())
            .map(|row| row.issue.number)
        else {
            return Ok(());
        };
        match crate::commands::edit::apply(
            &self.store.config,
            &self.store,
            &number.to_string(),
            None,
            None,
            None,
            None,
            Some(assignee),
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
        ) {
            Ok(issue) => {
                if let Some(state) = self.triage.as_mut() {
                    state.refresh(&self.store)?;
                    state.note = Some(format!("Assigned #{} to {assignee}", issue.number));
                }
                self.refresh_corpus()?;
            }
            Err(e) => {
                if let Some(state) = self.triage.as_mut() {
                    state.note = Some(e.to_string());
                }
            }
        }
        Ok(())
    }

    /// Create an issue from inside the Triage mode, straight into the
    /// configured entry column, through the shared create core (so the entry
    /// stamp is recorded and it appears in the queue).
    fn create_triage_issue(&mut self, title: &str) -> Result<()> {
        let entry = self
            .store
            .config
            .triage
            .as_ref()
            .and_then(|triage| triage.entry_status.clone())
            .ok_or_else(|| {
                TixError::InvalidInput(
                    "the triage inbox needs a `[triage]` section in tix.toml, and this project \
                     has none"
                        .to_string(),
                )
            })?;
        let issue = crate::commands::create::create(
            &self.store.config,
            &self.store,
            title,
            None,
            Some(crate::model::Status::new(entry.clone())),
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
        )?;
        if let Some(state) = self.triage.as_mut() {
            state.refresh(&self.store)?;
            state.note = Some(format!("Created #{} in {entry}", issue.number));
        }
        self.refresh_corpus()?;
        Ok(())
    }

    /// Run a Triage-mode pointer action recorded during the draw. Public so the
    /// hit-region tests drive the same path the run loop does.
    pub fn apply_triage_action(&mut self, action: Action) -> Result<Action> {
        match action {
            Action::TriageOpenStatus => self.open_triage_status_dropdown(),
            Action::TriageOpenAssignee => self.open_triage_assignee_dropdown(),
            Action::TriageCreate => {
                if let Some(state) = self.triage.as_mut() {
                    state.dropdown = None;
                    state.focus = TriageControl::New;
                    state.creating = true;
                    state.create_buffer.clear();
                }
            }
            Action::TriageFocusQueue => {
                if let Some(state) = self.triage.as_mut() {
                    state.focus = TriageControl::Queue;
                }
            }
            Action::TriageDropdownClose => {
                if let Some(state) = self.triage.as_mut() {
                    state.close_dropdown();
                }
            }
            Action::TriagePickOption(row) => {
                let chosen = self.triage.as_mut().and_then(|state| {
                    let (kind, id) = {
                        let dropdown = state.dropdown.as_ref()?;
                        let index = *dropdown.state.visible_indices().get(row)?;
                        (dropdown.kind, dropdown.state.options.get(index)?.id.clone())
                    };
                    state.dropdown = None;
                    Some((kind, id))
                });
                if let Some((kind, id)) = chosen {
                    match kind {
                        TriageDropdownKind::Status => self.move_focused_triage_issue(&id)?,
                        TriageDropdownKind::Assignee => self.assign_focused_triage_issue(&id)?,
                    }
                }
            }
            _ => {}
        }
        Ok(Action::None)
    }

    fn handle_bulk_modal_key(&mut self, key: KeyEvent) -> Result<Action> {
        use crate::ui::bulk::{BulkFocus, BulkState};
        let Some(mut modal) = self.bulk.take() else {
            self.mode = Mode::Board;
            return Ok(Action::None);
        };
        // The board's cards, in board order — what the user can see, which is what
        // they can have marked.
        let issues = crate::ui::bulk::visible_issues(&self.board, &self.store)?;
        let result = if modal.focus == BulkFocus::Edit {
            // Editing: every key is text. No command is reachable here, and that is
            // the point — one channel cannot be both a command set and a text field.
            match key.code {
                KeyCode::Esc => {
                    modal.abort_edit();
                    Ok(())
                }
                KeyCode::Enter => modal.commit_edit(),
                KeyCode::Backspace => {
                    modal.draft.pop();
                    Ok(())
                }
                KeyCode::Char(c) => {
                    modal.draft.push(c);
                    Ok(())
                }
                _ => Ok(()),
            }
        } else {
            match key.code {
                KeyCode::Esc => {
                    // Closes the modal, as every other modal here does on `esc`. The
                    // selection goes with it: `esc` is a cancel, and a cancel that
                    // leaves a half-built selection behind has not cancelled.
                    self.bulk = None;
                    self.mode = Mode::Board;
                    self.rebuild_board();
                    return Ok(Action::None);
                }
                KeyCode::Tab | KeyCode::Down => {
                    modal.move_cursor(1);
                    Ok(())
                }
                KeyCode::BackTab | KeyCode::Up => {
                    modal.move_cursor(-1);
                    Ok(())
                }
                KeyCode::Enter => {
                    if modal.row_names().is_empty() {
                        // An archive has no rows, so `enter` previews rather than
                        // entering nothing.
                        modal.preview(&self.store, &issues)
                    } else {
                        modal.begin_edit();
                        Ok(())
                    }
                }
                KeyCode::Char('p') => modal.preview(&self.store, &issues),
                KeyCode::Char('y') => {
                    if modal.is_armed() {
                        modal.confirm(&self.store)
                    } else {
                        modal.arm();
                        Ok(())
                    }
                }
                // The card under the **board** cursor, which is visible underneath
                // the modal. `X` empties the whole selection; `space` and `x` act on
                // one card. The board arms are the same three keys, so there is one
                // vocabulary and not two.
                KeyCode::Char('X') => {
                    modal.selection.clear();
                    modal.mark_stale();
                    Ok(())
                }
                KeyCode::Char(' ') | KeyCode::Char('x') => {
                    match self.board.get_selected_card().map(|c| c.number) {
                        None => Ok(()),
                        Some(card) => {
                            let outcome = if key.code == KeyCode::Char(' ') {
                                modal.selection.toggle(card).map(|_| true)
                            } else if modal.selection.remove(card) {
                                Ok(true)
                            } else {
                                Err(crate::ui::bulk::SelectionProblem::AlreadySelected)
                            };
                            match outcome {
                                Ok(_) => {
                                    modal.mark_stale();
                                    Ok(())
                                }
                                Err(problem) => {
                                    modal.note = Some(if key.code == KeyCode::Char('x') {
                                        // Unmarking something not marked is the
                                        // *desired* end state, so it reports rather
                                        // than errors.
                                        format!("#{card} was not selected")
                                    } else {
                                        problem.to_string()
                                    });
                                    Ok(())
                                }
                            }
                        }
                    }
                }
                KeyCode::Char('a') => {
                    // Cycle the action. The selection and the flags survive it: a user
                    // who marked ten cards does not re-mark them to change their mind
                    // about the verb.
                    modal.action = modal.action.next();
                    modal.state = BulkState::Selecting;
                    modal.plan_stale = true;
                    modal.cursor = 0;
                    Ok(())
                }
                KeyCode::Char('t') => {
                    // A pair's target defaults to the card the user is standing on,
                    // which is the other end of a link nine times in ten. It is a
                    // **default**, not a commitment: the `target` row is editable.
                    if let Some(card) = self.board.get_selected_card() {
                        modal.target = Some(card.number.to_string());
                        modal.mark_stale();
                    }
                    Ok(())
                }
                KeyCode::Char('c') => {
                    // `--clear` on the row under the cursor: the **`clear` row** is
                    // the one that carries the flag, never the cursor's own row. On
                    // the `clear` row it re-applies what is already named
                    // (idempotent); on any other row it names that row. `set_row`
                    // validates, so a non-clearable field (`status`) is a refusal
                    // rather than a flag the apply would ignore.
                    //
                    // The first version of this arm passed `modal.cursor` where the
                    // clear row's index belongs, so `c` on `priority` stored the
                    // word "priority" as the priority, left `flags.clear` empty, and
                    // made the next preview refuse with `invalid priority
                    // 'priority'`. It was the only key of this keymap with no test.
                    let names = modal.row_names();
                    match names.iter().position(|row| *row == "clear") {
                        None => {
                            // A pair has a target and a kind, an archive has no rows
                            // at all: there is no field to empty, and inventing one
                            // would offer a flag the apply cannot carry.
                            modal.note = Some(format!(
                                "a {} has no clearable fields — nothing to clear",
                                modal.action.as_str()
                            ));
                            Ok(())
                        }
                        Some(clear_row) => {
                            let name = modal.row_name(modal.cursor);
                            if name == "clear" {
                                let current = modal.row_value(clear_row);
                                if current == "—" {
                                    // Nothing is named, so there is nothing to
                                    // re-apply. The em dash the renderer shows for an
                                    // absent value is not a field name and must not
                                    // reach `set_row` as one.
                                    modal.note = Some(
                                        "no field is named — press c on the field you \
                                         want to empty"
                                            .to_string(),
                                    );
                                    Ok(())
                                } else {
                                    modal.set_row(clear_row, current)
                                }
                            } else {
                                modal.set_row(clear_row, name.to_string())
                            }
                        }
                    }
                }
                _ => Ok(()),
            }
        };
        if let Err(e) = &result {
            modal.note = Some(e.to_string());
        }
        // The modal closes on a **completed** apply, and on nothing else. A refusal
        // stays on screen with its reasons, because a refusal the user cannot read is
        // not a report — and WP06 already froze the rule that a refusal is a completed
        // command that reports non-zero, not an `Err`.
        let finished = matches!(modal.state, BulkState::Done(..)) && result.is_ok();
        self.bulk = Some(modal);
        if finished {
            // The modal is about to be dropped, so its note would be dropped with it.
            // The board's status line is where a result has to land.
            if let Some(note) = self.bulk.as_ref().and_then(|m| m.note.clone()) {
                self.status_msg = Some(note);
            }
            self.mode = Mode::Board;
            self.refresh_corpus()?;
        } else {
            self.mode = Mode::BulkModal;
        }
        // …and the same rule one level up. `run` propagates an `Err` out of
        // `handle_key` with `?`, so returning one here ends the session and takes the
        // note this function just recorded with it. Every other dispatch in this file
        // reports a user's refusal through `status_msg` and returns `Ok`; this one
        // used to return it, so `c` on the `status` row — or, with no `c` involved at
        // all, `enter` on the `clear` row with `title` typed in — printed
        // `cannot clear …` and quit the TUI. `visible_issues` above still returns
        // `Err`: that is an I/O failure behind the keyboard, not a request the user
        // made and was refused.
        //
        // Read by `finished` above, and deliberately not consumed: a refusal is a
        // completed command that reports.
        let _ = result;
        Ok(Action::None)
    }

    fn handle_resolved_key(&mut self, _context: InputContext, key: KeyEvent) -> Result<Action> {
        match self.mode.clone() {
            Mode::Board => self.handle_board_key(key),
            Mode::RolloverDialog => self.handle_rollover_dialog_key(key),
            Mode::Detail => self.handle_detail_key(key),
            Mode::Form => self.handle_form_key(key),
            Mode::ConfirmDelete => self.handle_confirm_delete_key(key),
            Mode::MoveIntoDone { target_col, .. } => {
                self.handle_move_into_done_key(key, target_col)
            }
            Mode::TransitionReason { target_col, .. } => {
                self.handle_transition_reason_key(key, target_col)
            }
            Mode::ConfirmBlockedMove {
                target_col,
                warning,
            } => self.handle_confirm_blocked_move_key(key, target_col, &warning),
            Mode::Help { .. } => self.handle_help_key(key),
            Mode::ContextMenu { .. } => self.handle_context_menu_key(key),
            Mode::Filter { .. } => self.handle_filter_key(key),
            Mode::FilterModal => self.handle_filter_modal_key(key),
            Mode::BulkModal => self.handle_bulk_modal_key(key),
            Mode::TriageInbox => self.handle_triage_key(key),
            Mode::Cycle => self.handle_cycle_key(key),
            Mode::Settings => self.handle_settings_key(key),
            Mode::PlanningManagement => self.handle_planning_key(key),
            Mode::PlanningForm => self.handle_planning_form_key(key),
            Mode::DatePicker { .. } => self.handle_date_picker_key(key),
            Mode::Comment { .. } => self.handle_comment_key(key),
            Mode::Asset { .. } => self.handle_asset_key(key),
            Mode::EditRepair { .. } => self.handle_edit_repair_key(key),
            Mode::EditConflict { .. } => self.handle_edit_conflict_key(key),
            Mode::LinkCreate { .. } => self.handle_link_prompt_key(key),
            Mode::LinkEdit { .. } => self.handle_link_prompt_key(key),
            Mode::ConfirmRemoveRelationship { .. } => self.handle_remove_relationship_key(key),
        }
    }

    /// Route a [`MouseEvent`] into the active mode's pointer handler (D2),
    /// mirroring [`App::handle_key`]: one dispatch trunk per mode, so mouse and
    /// keyboard share the same single-mode mental model. Modes that declare no
    /// mouse behavior fall through to a no-op. Per-mode handlers land with the
    /// click/hover/dialog tasks.
    pub fn handle_mouse(&mut self, mouse: MouseEvent) -> Result<Action> {
        // The pointer's hovered region is tracked for **every** mode, before the
        // per-mode dispatch, so widgets shared across modes (the vertical mode
        // navigation) highlight wherever they are drawn. Regions come from the
        // previous frame, which is the frame the pointer is actually over.
        if matches!(mouse.kind, MouseEventKind::Moved) {
            self.hover_action = self.resolve_region(mouse.column, mouse.row);
        }
        let mut action = match self.mode.clone() {
            Mode::Board => self.handle_board_mouse(mouse),
            Mode::Detail => self.handle_detail_mouse(mouse),
            Mode::ConfirmDelete => self.handle_confirm_delete_mouse(mouse),
            Mode::Help { .. } => self.handle_help_mouse(mouse),
            Mode::ContextMenu { .. } => self.handle_context_menu_mouse(mouse),
            Mode::FilterModal => self.handle_filter_modal_mouse(mouse),
            Mode::Settings => self.handle_settings_mouse(mouse),
            Mode::DatePicker { .. } => self.handle_date_picker_mouse(mouse),
            _ => Ok(Action::None),
        }?;
        if action == Action::None
            && matches!(mouse.kind, MouseEventKind::Down(_))
            && !matches!(
                self.mode,
                Mode::ContextMenu { .. }
                    // #1510: the conflict prompt's three decisions are the only way
                    // out. A click that fell through to the board drawn underneath
                    // would leave the prompt — and the temp copy it holds — without
                    // a decision ever being made.
                    | Mode::EditConflict { .. }
                    // #1506: the repair prompt's decisions are the only way out for
                    // the same reason, and its retained copy must not be abandoned
                    // by a stray click on the board.
                    | Mode::EditRepair { .. }
            )
        {
            // Fall back to widget-recorded hit regions (D3/D6): a click on a
            // region a widget declared during draw runs its associated action,
            // regardless of which mode did not handle the event. The context
            // menu owns every click while it is open (inside = item, outside =
            // dismiss), so underlying board regions must not resolve through
            // the fallback.
            if let Some(region_action) = self.resolve_region(mouse.column, mouse.row) {
                action = region_action;
            }
        }
        Ok(action)
    }

    /// Record a click target bounding `rect` for the current draw (D3).
    /// Widgets call this while rendering; `handle_mouse` resolves the region
    /// under a pointer via [`App::resolve_region`]. Regions are cleared at the
    /// start of every frame, so stale targets from previous frames never fire.
    pub fn record_region(&self, rect: Rect, action: Action) {
        self.frame_hit_regions
            .borrow_mut()
            .push(HitRegion { rect, action });
    }

    /// Whether `action`'s hit region is the one the pointer is currently over.
    /// Widgets use this to style themselves on hover without owning any pointer
    /// state; the value is refreshed by each `Moved` event (see `handle_mouse`).
    pub fn is_hovered(&self, action: &Action) -> bool {
        self.hover_action.as_ref() == Some(action)
    }

    /// The innermost (last-recorded) region under `(x, y)`, if any (D3).
    fn resolve_region(&self, x: u16, y: u16) -> Option<Action> {
        self.frame_hit_regions
            .borrow()
            .iter()
            .rev()
            .find(|region| region.rect.contains(Position::new(x, y)))
            .map(|region| region.action.clone())
    }

    // The pointer handlers below are filled in by their mouse tasks
    // (dialog click targets 5.x); until then they are honest stubs that
    // return a no-op so the dispatch trunk stays live.

    /// Board-mode pointer handling (D4): `Down` selects a card/column and
    /// records the press origin, `Drag` frames promote an active drag without
    /// touching the board, and a resolving `Up` decides between a plain click,
    /// a double-click (opens the card's detail) and a drag-move to another
    /// real column. Right-click opens the context menu (task 4.2); scroll
    /// wheel behavior lands with task 6.1.
    fn handle_board_mouse(&mut self, mouse: MouseEvent) -> Result<Action> {
        match mouse.kind {
            MouseEventKind::Down(MouseButton::Left) => {
                self.drag_preview_col = None;
                let hit = self.board_hit_at(mouse.column, mouse.row);
                self.mouse_down_left(hit)
            }
            MouseEventKind::Down(MouseButton::Right) => {
                self.drag_preview_col = None;
                let hit = self.board_hit_at(mouse.column, mouse.row);
                self.open_context_menu(hit)
            }
            MouseEventKind::Up(MouseButton::Left) => {
                self.drag_preview_col = None;
                self.mouse_up_left(mouse.column, mouse.row)
            }
            MouseEventKind::Drag(_) => {
                self.mouse_drag();
                self.update_drag_preview(mouse.column, mouse.row);
                Ok(Action::None)
            }
            MouseEventKind::ScrollUp => {
                self.board.move_up();
                Ok(Action::None)
            }
            MouseEventKind::ScrollDown => {
                self.board.move_down();
                Ok(Action::None)
            }
            MouseEventKind::Moved => {
                self.drag_preview_col = None;
                if let Some(tab) = self.tab_hover_at(mouse.column, mouse.row) {
                    self.tabs.hovered = Some(tab);
                    self.board.hover = None;
                    self.board.hover_col = None;
                } else {
                    self.tabs.hovered = None;
                    self.mouse_hover(mouse.column, mouse.row);
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Track which tab, if any, the pointer is hovering. This mirrors the tab
    /// bar geometry so the hover highlight stays aligned with the rendered row.
    fn tab_hover_at(&self, x: u16, y: u16) -> Option<usize> {
        if !self.tabs.needs_bar() {
            return None;
        }
        let area = self.frame_size.get();
        if y < area.y || y >= area.y + TAB_HEIGHT {
            return None;
        }
        let tabs_area = Rect {
            y: area.y,
            height: TAB_HEIGHT,
            ..area
        };
        (0..self.tabs.len()).find(|&index| {
            self.tabs
                .tab_rect(index, tabs_area)
                .is_some_and(|rect| rect.contains(Position::new(x, y)))
        })
    }

    /// Track the pointer for the hover highlight (D8): `Moved` records the
    /// card under the pointer on `board.hover` and the column on
    /// `board.hover_col` (never touching the selection). The column is recorded
    /// for empty columns too, so hovering anywhere inside one marks it; both are
    /// cleared over the board chrome or outside the board.
    fn mouse_hover(&mut self, x: u16, y: u16) {
        match self.board_hit_at(x, y) {
            Some(HitTarget::Card { col, row }) => {
                self.board.hover = Some((col, row));
                self.board.hover_col = Some(col);
            }
            Some(HitTarget::Column { col }) => {
                self.board.hover = None;
                self.board.hover_col = Some(col);
            }
            None => {
                self.board.hover = None;
                self.board.hover_col = None;
            }
        }
    }

    /// Update the current drag preview target while a card is held down.
    fn update_drag_preview(&mut self, x: u16, y: u16) {
        match self.board_hit_at(x, y) {
            Some(HitTarget::Card { col, row }) => {
                self.drag_preview_col = Some(col);
                self.board.hover = Some((col, row));
                self.board.hover_col = Some(col);
            }
            Some(HitTarget::Column { col }) if col < self.board.real_cols() => {
                self.drag_preview_col = Some(col);
                self.board.hover = None;
                self.board.hover_col = Some(col);
            }
            _ => {
                self.drag_preview_col = None;
                self.board.hover = None;
                self.board.hover_col = None;
            }
        }
    }

    /// Board-detail mouse handling: only the wheel changes scroll offset.
    fn handle_detail_mouse(&mut self, mouse: MouseEvent) -> Result<Action> {
        match mouse.kind {
            MouseEventKind::ScrollUp => {
                if let Some(d) = self.detail.as_mut() {
                    d.scroll_by(-i32::from(WHEEL_ROWS));
                }
            }
            MouseEventKind::ScrollDown => {
                if let Some(d) = self.detail.as_mut() {
                    d.scroll_by(i32::from(WHEEL_ROWS));
                }
            }
            _ => {}
        }
        Ok(Action::None)
    }

    /// The rect the board widget draws into within the frame `area`, mirroring
    /// `render_board`: tabs bar and hover line on top, filter row (when
    /// active), board, then the hint bar at the bottom. `None` when the frame
    /// is too small to contain a board at all.
    fn board_mouse_area(&self, area: Rect) -> Option<Rect> {
        let tab_h: u16 = if self.tabs.needs_bar() { TAB_HEIGHT } else { 0 };
        let filter_h: u16 = if self.filter.is_some() || self.structured.has_active_criteria() {
            FILTER_HEIGHT
        } else {
            0
        };
        let hint_h: u16 = if self.one_shot { 0 } else { HINT_HEIGHT };
        if area.height <= hint_h + tab_h + HOVER_HEIGHT + filter_h {
            return None;
        }
        Some(Rect {
            y: area.y + tab_h + HOVER_HEIGHT + filter_h,
            height: area.height - tab_h - HOVER_HEIGHT - filter_h - hint_h,
            ..area
        })
    }

    /// Resolve a terminal pointer against the board using the geometry of the
    /// most recent draw (D3), or `None` outside the board / when unframed.
    fn board_hit_at(&self, x: u16, y: u16) -> Option<HitTarget> {
        let frame = self.frame_size.get();
        let board_area = self.board_mouse_area(frame)?;
        self.board.hit_test(
            board_area,
            board::BoardDisplay::from(self.active_board_config()),
            self.status_msg.is_some(),
            x,
            y,
        )
    }

    /// Move the cursor to the card or column the pointer resolved to (D4:
    /// selection changes only on `Down`).
    fn select_at(&mut self, hit: HitTarget) {
        match hit {
            HitTarget::Card { col, row } => {
                self.board.active_col = col;
                self.board.selected = row;
            }
            HitTarget::Column { col } => {
                self.board.active_col = col;
                self.board.clamp_selection();
            }
        }
    }

    fn mouse_down_left(&mut self, hit: Option<HitTarget>) -> Result<Action> {
        let Some(target) = hit else {
            return Ok(Action::None);
        };
        self.select_at(target);
        let (col, card) = match target {
            HitTarget::Card { col, row } => (col, Some(row)),
            HitTarget::Column { col } => (col, None),
        };

        let double_click = match target {
            HitTarget::Card { col, row } => match self.mouse.last_down.as_ref() {
                // A second press on the same card within the window is a
                // double-click; the press consuming it re-records the origin.
                Some(prev) => {
                    prev.at.elapsed() < self.mouse.double_click_window
                        && prev.col == col
                        && prev.card == Some(row)
                }
                None => false,
            },
            HitTarget::Column { .. } => false,
        };

        self.mouse.last_down = Some(MouseDown {
            col,
            card,
            at: Instant::now(),
        });

        if double_click {
            return self.open_detail_for(target);
        }
        Ok(Action::None)
    }

    /// Open the detail view for the card at the hit target (mirrors the board
    /// `Enter` branch) — the resolving half of a double-click.
    fn open_detail_for(&mut self, hit: HitTarget) -> Result<Action> {
        if let HitTarget::Card { col, row } = hit {
            if let Some(card) = self.board.column_cards(col).get(row).cloned() {
                let issue = self.store.get(IssueSelector::Filename(card.filename))?;
                self.open_detail_root(issue)?;
            }
        }
        Ok(Action::None)
    }

    /// Open the detail pane on the issue a shared issue-table row names
    /// ([`Action::OpenIssue`]).
    ///
    /// The row's filename is store-relative, exactly what
    /// [`IssueSelector::Filename`] takes; a file that has vanished since the
    /// draw surfaces as an `Err` the caller reports through the status line
    /// rather than opening an empty detail.
    pub fn open_issue_by_filename(&mut self, filename: &str) -> Result<()> {
        let issue = self
            .store
            .get(IssueSelector::Filename(filename.to_string()))?;
        self.open_detail_root(issue)
    }

    /// Open `issue`'s detail pane as a **fresh root**: the back stack is cleared,
    /// because the navigation began at the board rather than from another pane
    /// (tix #1513).
    fn open_detail_root(&mut self, issue: Issue) -> Result<()> {
        self.nav_stack.clear();
        self.related_picker = None;
        self.detail = Some(self.detail_state_for(issue)?);
        self.mode = Mode::Detail;
        Ok(())
    }

    /// Build a detail pane for a **store** issue, service-resolved.
    ///
    /// One builder for every path that opens a store issue (the board's Enter, a
    /// double-click, and following a local related entry), so the `related` list can
    /// never be populated on one path and forgotten on another. The pane is
    /// writable: a store issue has a file to route writes through.
    fn detail_state_for(&self, issue: Issue) -> Result<DetailState> {
        // Service-resolved, so the pane shows the relationships that touch this
        // issue rather than the ones it happens to own.
        let relationships = self.store.relationships_for(issue.number)?;
        // One graph for the chain and the blocked note, so the two rows cannot
        // describe different snapshots of the same issue.
        let (all, done_column) = self.store.graph_source()?;
        let graph = commands::graph_over(&all, &done_column);
        let number = issue.number;
        // WP05: the resolved category, for the detail row (T023).
        let category = self.category_of_issue(&issue);
        // #1513: classified once, here, so the renderer stays a pure function of
        // the pane's state.
        let related = crate::related::classify_all(&issue.related_issues);
        let mut state = DetailState {
            issue,
            category,
            relationships,
            chain: graph.dependency_chain(number),
            blocked: commands::blocked_note(&graph.blocked_state(number)),
            // From the **same** `all` snapshot the graph was built over, so the
            // hierarchy rows and the relationship rows cannot describe different
            // states of the same issue.
            hierarchy: commands::parent::facts_over(&all, &done_column, number),
            scroll_offset: 0,
            viewport: std::cell::Cell::new(0),
            max_scroll: std::cell::Cell::new(0),
            rel_cursor: 0,
            related,
            related_cursor: 0,
            read_only: false,
        };
        state.clamp_related_cursor();
        Ok(state)
    }

    /// Open an issue parsed from a file **outside** the store in the pane,
    /// read-only (tix #1513).
    ///
    /// There is no store entry to resolve relationships or a dependency graph
    /// against, so the pane carries the issue and its `related` list and nothing
    /// derived from the graph. `read_only` makes `e`/`c`/`a` and the relationship
    /// operations refuse rather than fail with a lookup error.
    fn open_external_detail(&mut self, issue: Issue) {
        let number = issue.number;
        let related = crate::related::classify_all(&issue.related_issues);
        // No store snapshot to compute hierarchy over beyond the issue itself.
        let hierarchy = commands::parent::facts_over(std::slice::from_ref(&issue), "done", number);
        let mut state = DetailState {
            issue,
            category: None,
            relationships: Vec::new(),
            chain: crate::relationships::DependencyChain::default(),
            blocked: None,
            hierarchy,
            scroll_offset: 0,
            viewport: std::cell::Cell::new(0),
            max_scroll: std::cell::Cell::new(0),
            rel_cursor: 0,
            related,
            related_cursor: 0,
            read_only: true,
        };
        state.clamp_related_cursor();
        self.detail = Some(state);
        self.mode = Mode::Detail;
    }

    /// Right-click on a card opens the issue context menu (D5, Spec: 6). The
    /// clicked card is selected first so every activated item — which runs the
    /// exact path its key binding would — operates on the expected issue. The
    /// menu is a widget overlay; activation/dismissal happen in
    /// [`App::handle_context_menu_key`] / [`App::handle_context_menu_mouse`].
    fn open_context_menu(&mut self, hit: Option<HitTarget>) -> Result<Action> {
        let target = match hit {
            Some(target @ HitTarget::Card { .. }) => target,
            // Right-click without a card target is a no-op.
            _ => return Ok(Action::None),
        };
        self.select_at(target);
        let mut items = vec![
            MenuItem {
                kind: MenuItemKind::OpenDetail,
                label: "Open detail".to_string(),
            },
            MenuItem {
                kind: MenuItemKind::EditInEditor,
                label: "Edit in editor".to_string(),
            },
            MenuItem {
                kind: MenuItemKind::ViewIssue,
                label: "View issue".to_string(),
            },
        ];
        for col in 0..self.board.real_cols() {
            if col != self.board.active_col {
                let name = self.board.column_name(col);
                items.push(MenuItem {
                    kind: MenuItemKind::MoveTo { column: col },
                    label: format!("Move to {name}"),
                });
            }
        }
        items.push(MenuItem {
            kind: MenuItemKind::Delete,
            label: "Delete".to_string(),
        });
        items.push(MenuItem {
            kind: MenuItemKind::RefreshBoard,
            label: "Refresh board".to_string(),
        });
        self.context_menu = Some(ContextMenu::new(items));
        self.mode = Mode::ContextMenu {
            return_to: Box::new(Mode::Board),
        };
        Ok(Action::None)
    }

    /// Restore `return_to` and drop the open menu (mirrors `handle_help_key`).
    fn close_context_menu(&mut self) {
        if let Mode::ContextMenu { return_to } = std::mem::replace(&mut self.mode, Mode::Board) {
            self.mode = *return_to;
        }
        self.context_menu = None;
    }

    /// Keyboard routing for the open context menu (D5): Up/Down move the
    /// selection, Enter activates the highlighted item (via the shared action
    /// path), Esc dismisses. Mirrors the Help overlay's single-trunk routing.
    fn handle_context_menu_key(&mut self, key: KeyEvent) -> Result<Action> {
        let Some(menu) = self.context_menu.as_mut() else {
            self.close_context_menu();
            return Ok(Action::None);
        };
        match menu.handle_key(key.code) {
            MenuEvent::None => Ok(Action::None),
            MenuEvent::Dismissed => {
                self.close_context_menu();
                Ok(Action::None)
            }
            MenuEvent::Selected(index) => {
                let kind = menu.item(index).map(|item| item.kind.clone());
                let Some(kind) = kind else {
                    return Ok(Action::None);
                };
                self.activate_context_item(kind)
            }
        }
    }

    /// Pointer routing for the open context menu (D5): a `Down` on an item row
    /// activates it; a `Down` outside the popup dismisses; anything else is
    /// ignored. Because this handler owns every click, it bypasses the D3
    /// region fallback (`handle_mouse` skips it while this mode is active).
    fn handle_context_menu_mouse(&mut self, mouse: MouseEvent) -> Result<Action> {
        match mouse.kind {
            MouseEventKind::ScrollUp => {
                if let Some(menu) = self.context_menu.as_mut() {
                    let _ = menu.handle_key(KeyCode::Up);
                }
                Ok(Action::None)
            }
            MouseEventKind::ScrollDown => {
                if let Some(menu) = self.context_menu.as_mut() {
                    let _ = menu.handle_key(KeyCode::Down);
                }
                Ok(Action::None)
            }
            MouseEventKind::Down(_) => {
                let Some(menu) = self.context_menu.take() else {
                    self.close_context_menu();
                    return Ok(Action::None);
                };
                let bounds = menu.bounds(self.frame_size.get());
                let in_popup = mouse.column >= bounds.x
                    && mouse.column < bounds.x + bounds.width
                    && mouse.row >= bounds.y
                    && mouse.row < bounds.y + bounds.height;
                if !in_popup {
                    self.close_context_menu();
                    return Ok(Action::None);
                }
                // Item rows sit between the popup's borders (top border at `bounds.y`,
                // content starts one row down; bottom border excluded from the hit).
                let row_hit = mouse.row.checked_sub(bounds.y + 1);
                let index = match row_hit {
                    Some(offset) => usize::from(offset),
                    None => return Ok(Action::None),
                };
                let kind = menu.item(index).map(|item| item.kind.clone());
                self.context_menu = Some(menu);
                match kind {
                    Some(kind) => self.activate_context_item(kind),
                    None => Ok(Action::None),
                }
            }
            _ => Ok(Action::None),
        }
    }

    /// Run the action a context menu item represents — the exact path the
    /// equivalent key binding would take (Spec: 6). The menu is closed first,
    /// restoring `return_to`, so the shared board/detail/handler state is
    /// current when the action runs.
    fn activate_context_item(&mut self, kind: MenuItemKind) -> Result<Action> {
        self.close_context_menu();
        match kind {
            MenuItemKind::OpenDetail => {
                let hit = HitTarget::Card {
                    col: self.board.active_col,
                    row: self.board.selected,
                };
                self.open_detail_for(hit)
            }
            MenuItemKind::EditInEditor => {
                if let Some(card) = self.board.get_selected_card() {
                    return Ok(Action::OpenEditor(card.filename.clone()));
                }
                Ok(Action::None)
            }
            MenuItemKind::ViewIssue => {
                if let Some(card) = self.board.get_selected_card() {
                    return Ok(Action::OpenViewer(card.filename.clone()));
                }
                Ok(Action::None)
            }
            MenuItemKind::MoveTo { column } => self.move_selected_to(column),
            MenuItemKind::Delete => {
                if let Some(card) = self.board.get_selected_card().cloned() {
                    self.confirm_delete_target = Some(card.filename);
                    self.mode = Mode::ConfirmDelete;
                }
                Ok(Action::None)
            }
            MenuItemKind::RefreshBoard => {
                self.refresh_corpus()?;
                self.status_msg = Some("Refreshed".to_string());
                Ok(Action::None)
            }
        }
    }

    /// A press followed by `Drag` frames promotes the recorded press into an
    /// active drag (D4). The board is not mutated during drag frames; the
    /// eventual `Up` decides the outcome. Dragging requires a card origin —
    /// grabbing empty column space never moves anything.
    fn mouse_drag(&mut self) {
        if self.mouse.drag.is_none() {
            if let Some(down) = &self.mouse.last_down {
                if down.card.is_some() {
                    self.mouse.drag = Some(Drag {
                        col: down.col,
                        card: down.card,
                    });
                }
            }
        }
    }

    /// Resolve a left-button release (D4): an active drag becomes a drop —
    /// moved to a different real column via `move_selected_to`, no-op on the
    /// source column, the mismatched column, or outside the board — while a
    /// plain click keeps the press recorded so a fast second press on the same
    /// card registers as a double-click.
    fn mouse_up_left(&mut self, x: u16, y: u16) -> Result<Action> {
        self.board.hover = None;
        self.board.hover_col = None;
        if let Some(drag) = self.mouse.drag.take() {
            self.mouse.last_down = None;
            if drag.card.is_none() {
                return Ok(Action::None);
            }
            let target = match self.board_hit_at(x, y) {
                Some(target) => target,
                None => return Ok(Action::None),
            };
            match target {
                HitTarget::Card { col, row } if col == drag.col => {
                    if Some(row) == drag.card {
                        return Ok(Action::None);
                    }
                    return self.reorder_selected_within_column(col, drag.card.unwrap(), row);
                }
                HitTarget::Column { col } if col == drag.col => {
                    return self.reorder_selected_within_column(
                        col,
                        drag.card.unwrap(),
                        self.board.column_cards(col).len().saturating_sub(1),
                    );
                }
                HitTarget::Card { col, .. } | HitTarget::Column { col }
                    if col < self.board.real_cols() && col != drag.col =>
                {
                    return self.move_selected_to(col);
                }
                _ => return Ok(Action::None),
            }
        }
        Ok(Action::None)
    }

    /// Persist the cards whose positions differ from the automatic ordering so
    /// a drag-reordered column survives rebuilds/restarts without storing a
    /// full column snapshot.
    fn persist_card_order(&mut self) -> bool {
        let board_name = self.active_board_name().to_string();
        let mut order = Vec::new();
        let active_config = self.active_board_config().clone();
        order.extend(
            self.board
                .columns
                .iter()
                .flat_map(|col| board::sparse_card_order(&active_config, &col.cards)),
        );
        order.extend(
            self.board
                .hidden
                .iter()
                .flat_map(|col| board::sparse_card_order(&active_config, &col.cards)),
        );
        order.extend(board::sparse_card_order(
            &active_config,
            &self.board.mismatch.cards,
        ));
        let Some(board_config) = self.store.config.kanban.configurations.get_mut(&board_name)
        else {
            return false;
        };
        board_config.card_order = order;
        self.persist_config()
    }

    fn reorder_selected_within_column(
        &mut self,
        col: usize,
        from_row: usize,
        to_row: usize,
    ) -> Result<Action> {
        let (filename, number, column_name) = {
            let Some(column) = self.board.columns.get_mut(col) else {
                return Ok(Action::None);
            };
            if from_row >= column.cards.len() || to_row >= column.cards.len() || from_row == to_row
            {
                return Ok(Action::None);
            }
            let card = column.cards.remove(from_row);
            let filename = card.filename.clone();
            let number = card.number;
            let insert_at = to_row;
            column.cards.insert(insert_at, card);
            (filename, number, column.name.clone())
        };

        if !self.persist_card_order() {
            return Ok(Action::None);
        }
        self.rebuild_board();
        self.select_card_by_filename(&filename);
        self.status_msg = Some(format!("Reordered #{} in {}", number, column_name));
        Ok(Action::None)
    }

    /// Move the selected card within the active column by `delta` slots.
    fn move_selected_within_column(&mut self, delta: isize) -> Result<Action> {
        let col = self.board.active_col;
        let column_name = if col < self.board.columns.len() {
            self.board.columns[col].name.clone()
        } else if col == self.board.columns.len() && self.board.show_mismatch {
            self.board.mismatch.name.clone()
        } else {
            return Ok(Action::None);
        };
        let (filename, number) = {
            let cards = if col < self.board.columns.len() {
                &mut self.board.columns[col].cards
            } else {
                &mut self.board.mismatch.cards
            };
            let len = cards.len();
            if len < 2 {
                return Ok(Action::None);
            }
            let from_row = self.board.selected;
            if from_row >= len {
                return Ok(Action::None);
            }
            let to_row = if delta < 0 {
                from_row.saturating_sub(delta.unsigned_abs())
            } else {
                usize::min(from_row + delta as usize, len - 1)
            };
            if to_row == from_row {
                return Ok(Action::None);
            }
            let card = cards.remove(from_row);
            let filename = card.filename.clone();
            let number = card.number;
            let insert_at = to_row;
            cards.insert(insert_at, card);
            (filename, number)
        };
        if !self.persist_card_order() {
            return Ok(Action::None);
        }
        self.rebuild_board();
        self.select_card_by_filename(&filename);
        self.status_msg = Some(format!(
            "Moved #{} {} in {}",
            number,
            if delta < 0 { "up" } else { "down" },
            column_name
        ));
        Ok(Action::None)
    }

    #[allow(clippy::unused_self, clippy::unnecessary_wraps)]
    fn handle_confirm_delete_mouse(&mut self, _mouse: MouseEvent) -> Result<Action> {
        Ok(Action::None)
    }

    #[allow(clippy::unnecessary_wraps)]
    fn handle_help_mouse(&mut self, mouse: MouseEvent) -> Result<Action> {
        // tix #1441: the wheel scrolls the overlay, like the board and the detail
        // pane already did. It used to resolve to a click-anywhere-closes region,
        // which is still true for clicks — a wheel event is not a click.
        match mouse.kind {
            MouseEventKind::ScrollUp => self.scroll_help(-i32::from(WHEEL_ROWS)),
            MouseEventKind::ScrollDown => self.scroll_help(i32::from(WHEEL_ROWS)),
            _ => {}
        }
        Ok(Action::None)
    }

    #[allow(clippy::unused_self, clippy::unnecessary_wraps)]
    fn handle_filter_modal_mouse(&mut self, _mouse: MouseEvent) -> Result<Action> {
        Ok(Action::None)
    }

    #[allow(clippy::unused_self, clippy::unnecessary_wraps)]
    fn handle_settings_mouse(&mut self, _mouse: MouseEvent) -> Result<Action> {
        Ok(Action::None)
    }

    #[allow(clippy::unused_self, clippy::unnecessary_wraps)]
    fn handle_date_picker_mouse(&mut self, _mouse: MouseEvent) -> Result<Action> {
        Ok(Action::None)
    }

    fn handle_board_key(&mut self, key: KeyEvent) -> Result<Action> {
        if key
            .modifiers
            .contains(crossterm::event::KeyModifiers::CONTROL)
        {
            match key.code {
                KeyCode::Up => return self.move_selected_within_column(-1),
                KeyCode::Down => return self.move_selected_within_column(1),
                _ => {}
            }
        }
        match key.code {
            KeyCode::Char('q') | KeyCode::Char('Q') | KeyCode::Esc => {
                self.quit = true;
                Ok(Action::Quit)
            }
            KeyCode::Tab => {
                self.tabs.next();
                self.active_config = self.tabs.selected;
                self.switch_config();
                Ok(Action::None)
            }
            KeyCode::BackTab => {
                self.tabs.previous();
                self.active_config = self.tabs.selected;
                self.switch_config();
                Ok(Action::None)
            }
            KeyCode::Left | KeyCode::Char('h') => {
                self.board.move_left();
                Ok(Action::None)
            }
            KeyCode::Right | KeyCode::Char('l') => {
                self.board.move_right();
                Ok(Action::None)
            }
            KeyCode::Up | KeyCode::Char('k') => {
                self.board.move_up();
                Ok(Action::None)
            }
            KeyCode::Down | KeyCode::Char('j') => {
                self.board.move_down();
                Ok(Action::None)
            }
            KeyCode::Enter => {
                if let Some(card) = self.board.get_selected_card().cloned() {
                    let issue = self.store.get(IssueSelector::Filename(card.filename))?;
                    self.open_detail_root(issue)?;
                }
                Ok(Action::None)
            }
            KeyCode::Char('e') => {
                if let Some(card) = self.board.get_selected_card() {
                    Ok(Action::OpenEditor(card.filename.clone()))
                } else {
                    Ok(Action::None)
                }
            }
            KeyCode::Char('v') => {
                if let Some(card) = self.board.get_selected_card() {
                    Ok(Action::OpenViewer(card.filename.clone()))
                } else {
                    Ok(Action::None)
                }
            }
            KeyCode::Char('A') => {
                if let Some(card) = self.board.get_selected_card() {
                    Ok(Action::OpenAgent(card.filename.clone()))
                } else {
                    Ok(Action::None)
                }
            }
            KeyCode::Char('c') => {
                self.toggle_column_visibility();
                Ok(Action::None)
            }
            KeyCode::Char('f') => {
                self.open_filter_modal();
                Ok(Action::None)
            }
            // WP07 T031: `space` marks a card and `x` unmarks it. The **board**
            // owns these, not the modal, because the selection is made by standing
            // on cards — a modal that swallowed the board's keys would break every
            // existing binding, which T031 forbids. Marking also opens the modal on
            // the first mark, so the first `space` is not silent: the user sees
            // "1 selected" without having to find the `B` key.
            KeyCode::Char(' ') => {
                self.open_bulk_modal(crate::ui::bulk::BatchAction::Edit, true);
                Ok(Action::None)
            }
            KeyCode::Char('x') | KeyCode::Char('X') => {
                if self.bulk.is_some() {
                    let Some(card) = self.board.get_selected_card().map(|c| c.number) else {
                        return Ok(Action::None);
                    };
                    if let Some(modal) = self.bulk.as_mut() {
                        if !modal.selection.remove(card) {
                            modal.note = Some(format!("#{card} was not selected"));
                        }
                    }
                } else {
                    self.open_bulk_modal(crate::ui::bulk::BatchAction::Edit, true);
                }
                Ok(Action::None)
            }
            KeyCode::Char('B') => {
                let action = self
                    .bulk
                    .as_ref()
                    .map(|m| m.action)
                    .unwrap_or(crate::ui::bulk::BatchAction::Edit);
                self.open_bulk_modal(action, false);
                Ok(Action::None)
            }
            KeyCode::Char('<') => {
                let real_cols = self.board.real_cols();
                if real_cols > 0 {
                    let target = if self.board.active_col == 0 || self.board.active_col >= real_cols
                    {
                        real_cols - 1
                    } else {
                        self.board.active_col - 1
                    };
                    self.move_selected_to(target)
                } else {
                    Ok(Action::None)
                }
            }
            KeyCode::Char('>') => {
                let real_cols = self.board.real_cols();
                if real_cols > 0 {
                    let target = if self.board.active_col >= real_cols {
                        0
                    } else {
                        (self.board.active_col + 1) % real_cols
                    };
                    self.move_selected_to(target)
                } else {
                    Ok(Action::None)
                }
            }
            KeyCode::Char('n') => {
                self.open_new_issue_form();
                Ok(Action::None)
            }
            KeyCode::Char('C') => {
                // #1484. The source is resolved through the same selector path the
                // CLI uses (`view::get`, by the card's filename) rather than read
                // off the card: a `Card` is the *display* projection, and it
                // carries no estimate, reviewer, start date or parent — a clone
                // that silently dropped those would be a partial copy wearing a
                // whole one's name.
                if let Some(card) = self.board.get_selected_card().cloned() {
                    match crate::commands::view::get(&self.store, &card.filename) {
                        Ok(issue) => {
                            self.status_msg = Some(format!("Cloning #{}", issue.number));
                            // The clone keeps the source's status verbatim; the
                            // Target row is set to whichever side that status is,
                            // so it does not name a destination the form is not
                            // using.
                            let entry = self.new_issue_target_status(NewIssueTarget::Triage);
                            let mut form = FormState::from_issue(&issue);
                            if issue.status.to_string().trim() == entry {
                                form.target = NewIssueTarget::Triage;
                            }
                            self.enter_form(form);
                        }
                        Err(err) => self.status_msg = Some(format!("Cannot clone: {err}")),
                    }
                } else {
                    self.status_msg = Some("No issue selected to clone".to_string());
                }
                Ok(Action::None)
            }
            // #1492: show the archived issues too, or hide them again. Off by
            // default and *reloaded* rather than filtered on demand: the archived
            // files are not in the corpus until this is on, which is what keeps
            // opening a board in a repository full of them cheap.
            KeyCode::Char('a') => {
                self.show_archived = !self.show_archived;
                self.refresh_corpus()?;
                self.status_msg = Some(
                    if self.show_archived {
                        "Showing archived issues"
                    } else {
                        "Hiding archived issues"
                    }
                    .to_string(),
                );
                Ok(Action::None)
            }
            // #1399: show each issue's sub-issues beneath it, or hide them again.
            // Display-only: the children are already in the board state, so this
            // reorders the columns (one level deep) on a rebuild rather than
            // re-reading the store — the archive toggle's reload would be wasted work.
            KeyCode::Char('u') => {
                self.show_children = !self.show_children;
                self.rebuild_board();
                self.status_msg = Some(
                    if self.show_children {
                        "Showing sub-issues"
                    } else {
                        "Hiding sub-issues"
                    }
                    .to_string(),
                );
                Ok(Action::None)
            }
            // tix #1442 (follow-up): a page of cards. The column scrolls itself to keep
            // the selection visible — the `List` does that — so a page step is a
            // selection jump by one screen, measured by the renderer.
            //
            // These keys were **unbound** on the board until now, and an unbound key in
            // a non-text context is rewritten to `F(12)` before the handler sees it, so
            // `PgUp`/`PgDn` did nothing at all while the wheel next to them worked. A
            // key that silently disappears is worse than one that is not advertised.
            KeyCode::PageDown => {
                self.move_selection_by_page(1);
                Ok(Action::None)
            }
            KeyCode::PageUp => {
                self.move_selection_by_page(-1);
                Ok(Action::None)
            }
            KeyCode::Char('d') => {
                if let Some(card) = self.board.get_selected_card().cloned() {
                    self.confirm_delete_target = Some(card.filename);
                    self.mode = Mode::ConfirmDelete;
                }
                Ok(Action::None)
            }
            KeyCode::Char('r') => {
                self.refresh_corpus()?;
                self.status_msg = Some("Refreshed".to_string());
                Ok(Action::None)
            }
            KeyCode::Char('s') => {
                self.open_settings(None);
                Ok(Action::None)
            }
            // WP06, T029. `t` was unbound, so this adds a key rather than
            // changing what an existing one means — the escalation this
            // mission is told to avoid is an *unrelated* navigation change,
            // and this one is the triage surface's own entry point.
            KeyCode::Char('t') => self.open_triage_inbox(),
            KeyCode::Char('m') | KeyCode::Char('M') => {
                self.open_planning_modal();
                Ok(Action::None)
            }
            KeyCode::Char('b') => {
                self.open_settings(Some(SettingsPrompt::NewBoard(String::new())));
                Ok(Action::None)
            }
            KeyCode::Char('?') => {
                self.open_help(Mode::Board);
                Ok(Action::None)
            }
            KeyCode::Char('/') => {
                let buffer = self.filter.clone().unwrap_or_default();
                self.mode = Mode::Filter { buffer };
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// The single entry point for a TUI move, with no reason yet.
    ///
    /// WP05 T021: all three TUI move paths — the board's `<`/`>` keys, the detail
    /// view's move action, and the context menu's — now come through here, so the
    /// enumeration NFR-002 is checked against is three call sites rather than three
    /// hand-copied sequences that can drift.
    ///
    /// The order is deliberate and load-bearing:
    ///
    /// 1. **Blocked-move guard.** A move that will need an acknowledgement must not
    ///    first ask the user for a reason or a commit hash.
    /// 2. **Transition policy.** A terminal-exit refusal raises the reason prompt.
    /// 3. **Commit prompt**, only if the move actually reaches completion.
    /// 4. **The seam.**
    fn move_selected_to(&mut self, target_col: usize) -> Result<Action> {
        self.move_selected_to_impl(target_col, None, false)
    }

    /// [`Self::move_selected_to`], carrying a reason and/or a prior acknowledgement.
    ///
    /// Called with `(None, false)` to start a move, `(Some(reason), false)` from the
    /// reason prompt's accept path, and `(None, true)` from the blocked-move
    /// confirmation. The call re-runs the guard and the policy check rather than
    /// resuming mid-sequence, so the three entry points cannot drift apart.
    ///
    /// **Why `acknowledged` has to be threaded rather than the prompt resuming.**
    /// The acknowledgement exists to suppress the guard's refusal. Re-entering with
    /// `false` would raise the confirmation dialog again and loop forever, so the
    /// flag is the only thing that distinguishes "the user has not decided" from
    /// "the user has decided".
    fn move_selected_to_impl(
        &mut self,
        target_col: usize,
        override_reason: Option<String>,
        acknowledged: bool,
    ) -> Result<Action> {
        let card = match self.board.get_selected_card().cloned() {
            Some(c) => c,
            None => return Ok(Action::None),
        };

        let target_name = self.board.column_name(target_col).to_string();
        // WP05: completion is the **service's** decision, not a column-name
        // comparison (C-004). This is the same class of defect WP04 fixed in the
        // CLI: on a board whose `category_map` puts `completed` somewhere other than
        // its `done_column`, comparing names asks the wrong question, and the TUI
        // would skip the commit prompt for a move the seam records as reaching
        // completion.
        let (_, resolution) = crate::workflow::active_resolution(&self.store.config);
        let is_done_target = resolution
            .resolve(&target_name)
            .is_some_and(crate::workflow::WorkflowCategory::is_complete);
        let current_col_name = self.board.column_name(self.board.active_col);
        let was_done = resolution
            .resolve(current_col_name)
            .is_some_and(crate::workflow::WorkflowCategory::is_complete);

        // The shared guard runs **here**, before the commit prompt, so a move that
        // will need an acknowledgement does not first ask for a commit hash.
        //
        // This call is mandatory, not an optimisation: writing `issue.status`
        // directly below would let the TUI move blocked work to done with no
        // warning, no confirmation, and no History entry, while the CLI refused
        // the same move. That divergence is the parity defect
        // `contracts/surface-parity.md` §3 exists to prevent.
        let issue = self
            .store
            .get(IssueSelector::Filename(card.filename.clone()))?;

        // WP05 T021 step 3: when the policy refuses and no reason has been supplied,
        // raise the **shared** diagnostic as the prompt's text. Parity includes the
        // message, not only the accept/refuse decision
        // (`contracts/surface-parity.md` §2), and reusing the service's own string is
        // what guarantees that without a second copy to reword.
        if override_reason.is_none()
            && let crate::workflow::TransitionOutcome::Rejected(diagnostic) =
                crate::workflow::validate_transition(
                    &issue,
                    &target_name,
                    &resolution,
                    &self.store.config,
                    None,
                )
        {
            self.mode = Mode::TransitionReason {
                target_col,
                reason: diagnostic.to_string(),
                buffer: String::new(),
            };
            return Ok(Action::None);
        }

        let guard = mv::blocked_move_guard(&self.store.config, &self.store, &issue, &target_name)?;
        if guard.needs_acknowledgement() && !acknowledged {
            self.mode = Mode::ConfirmBlockedMove {
                target_col,
                warning: guard.warning().unwrap_or_default(),
            };
            return Ok(Action::None);
        }

        if is_done_target && card.commit.is_none() {
            self.mode = Mode::MoveIntoDone {
                target_col,
                buffer: String::new(),
            };
            return Ok(Action::None);
        }

        // Through the shared path, so the move's rules — including any
        // acknowledgement event — are identical on every surface. `was_done`
        // clearing the commit stays in the command layer, which owns it.
        //
        // **This call is mandatory, not an optimisation.** `Status` is a tuple struct
        // with a public field (research R7), so writing `issue.status` here would
        // compile, would be shorter, and would silently skip the transition policy
        // and the `TransitionDecision` — the TUI would then accept a move the CLI
        // refuses. The comment is here so the next reader does not "simplify" it.
        let commit = if was_done { None } else { card.commit.clone() };
        mv::apply_guarded(
            &self.store.config,
            &self.store,
            &card.filename,
            &target_name,
            commit.as_deref(),
            override_reason.as_deref(),
            acknowledged,
        )?;

        self.refresh_corpus()?;
        self.board.select_column(target_col);
        self.status_msg = Some(format!("Moved #{} to {target_name}", card.number));
        Ok(Action::None)
    }

    /// The reasoned-override prompt's key handler.
    ///
    /// Enter accepts a **non-blank** reason; Esc cancels. A blank reason is refused
    /// rather than accepted, because a whitespace-only string is not a reason and the
    /// service trims it away — accepting it here would show the user a move that
    /// then fails at the seam, having already closed the prompt.
    ///
    /// Cancelling returns to the board with **nothing** written: no file, no
    /// `updated` bump, no History entry. The move was never applied, so there is
    /// nothing to undo.
    fn handle_transition_reason_key(&mut self, key: KeyEvent, target_col: usize) -> Result<Action> {
        match key.code {
            KeyCode::Enter => {
                let reason = match &self.mode {
                    Mode::TransitionReason { buffer, .. } => buffer.clone(),
                    _ => String::new(),
                };
                if reason.trim().is_empty() {
                    self.status_msg = Some(
                        "A reason is required: the decision is recorded in the issue's \
                         history and has to say why"
                            .to_string(),
                    );
                    return Ok(Action::None);
                }
                // Re-enter the shared move with the reason, so the guard, the policy
                // check, the commit prompt and the write all run once more in the
                // same order as an unprompted move.
                self.mode = Mode::Board;
                self.move_selected_to_impl(target_col, Some(reason), false)
            }
            KeyCode::Esc => {
                self.mode = Mode::Board;
                Ok(Action::None)
            }
            KeyCode::Char(c) => {
                if let Mode::TransitionReason { ref mut buffer, .. } = self.mode {
                    buffer.push(c);
                }
                Ok(Action::None)
            }
            KeyCode::Backspace => {
                if let Mode::TransitionReason { ref mut buffer, .. } = self.mode {
                    buffer.pop();
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    fn handle_detail_key(&mut self, key: KeyEvent) -> Result<Action> {
        // The related picker overlays the pane (#1513), exactly as `form_picker`
        // overlays the form: while it is open it owns the keyboard.
        if self.related_picker.is_some() {
            return self.handle_related_picker_key(key);
        }
        // An external, read-only issue has no store to route a write through, so
        // the mutating keys refuse up front rather than failing with a lookup
        // error from the store (#1513).
        if self.detail.as_ref().is_some_and(|detail| detail.read_only)
            && matches!(key.code, KeyCode::Char('e' | 'c' | 'a' | 'n' | 'E' | 'd'))
        {
            self.status_msg = Some("read-only: the issue is outside the store".to_string());
            return Ok(Action::None);
        }
        match key.code {
            KeyCode::Char('q') | KeyCode::Char('Q') | KeyCode::Esc => {
                self.mode = Mode::Board;
                self.detail = None;
                // The navigation that ended here is over with it; a back stack left
                // behind would let a later pane `Backspace` into a screen the reader
                // had already closed (#1513).
                self.nav_stack.clear();
                self.related_picker = None;
                Ok(Action::None)
            }
            KeyCode::Char('e') => {
                if let Some(ref d) = self.detail {
                    let filename = d.issue.filename.clone();
                    Ok(Action::OpenEditor(filename))
                } else {
                    Ok(Action::None)
                }
            }
            KeyCode::Char('v') => {
                if let Some(d) = &self.detail {
                    Ok(Action::OpenViewer(d.issue.filename.clone()))
                } else {
                    Ok(Action::None)
                }
            }
            KeyCode::PageUp => {
                if let Some(d) = self.detail.as_mut() {
                    let page = d.page();
                    d.scroll_by(-i32::from(page));
                }
                Ok(Action::None)
            }
            KeyCode::PageDown => {
                if let Some(d) = self.detail.as_mut() {
                    let page = d.page();
                    d.scroll_by(i32::from(page));
                }
                Ok(Action::None)
            }
            KeyCode::Char('?') => {
                self.open_help(Mode::Detail);
                Ok(Action::None)
            }
            KeyCode::Char('c') => {
                self.mode = Mode::Comment {
                    buffer: String::new(),
                };
                Ok(Action::None)
            }
            KeyCode::Char('a') => {
                self.mode = Mode::Asset {
                    buffer: String::new(),
                };
                Ok(Action::None)
            }
            // #1359: the three mutating relationship operations, plus the cursor
            // naming which edge `E` and `d` act on.
            KeyCode::Char('n') => {
                self.mode = Mode::LinkCreate {
                    buffer: String::new(),
                    step: LinkStep::Target,
                    target: None,
                };
                Ok(Action::None)
            }
            KeyCode::Char('E') => {
                // Only meaningful with an edge under the cursor; with none selected
                // the key says so rather than doing nothing, because a silently
                // ignored key is indistinguishable from a missing binding.
                match self.selected_relationship_id() {
                    Some(id) => {
                        let index = self.detail.as_ref().map(|d| d.rel_cursor).unwrap_or(0);
                        self.mode = Mode::LinkEdit {
                            index,
                            buffer: String::new(),
                            step: LinkStep::Target,
                            target: None,
                            kind: None,
                        };
                        self.status_msg = Some(format!("Re-kind {id}"));
                    }
                    None => {
                        self.status_msg =
                            Some("no relationship selected — press j or k first".to_string())
                    }
                }
                Ok(Action::None)
            }
            KeyCode::Char('d') => {
                match self.selected_relationship().cloned() {
                    Some(rel) => {
                        let line = crate::commands::link::relationship_line(&rel);
                        let index = self.detail.as_ref().map(|d| d.rel_cursor).unwrap_or(0);
                        self.status_msg = Some(format!("Remove {line}? (y to confirm)"));
                        self.mode = Mode::ConfirmRemoveRelationship { index };
                    }
                    None => {
                        self.status_msg =
                            Some("no relationship selected — press j or k first".to_string())
                    }
                }
                Ok(Action::None)
            }
            KeyCode::Char('j') | KeyCode::Down => {
                self.move_rel_cursor(1);
                Ok(Action::None)
            }
            KeyCode::Char('k') | KeyCode::Up => {
                self.move_rel_cursor(-1);
                Ok(Action::None)
            }
            // #1513: the related-issues surface. `r` lists them, `o` follows the
            // selected one, `Backspace` returns to the previous pane. `j`/`k` are
            // deliberately **not** reused: they move the relationship cursor, and
            // the picker is the selection surface for related entries.
            KeyCode::Char('r') => {
                self.open_related_picker();
                Ok(Action::None)
            }
            KeyCode::Char('o') => self.follow_related(),
            KeyCode::Backspace => {
                self.nav_back();
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Open the related-issues picker over the detail pane (tix #1513).
    ///
    /// A no-op with nothing to pick, so `r` on an issue with no `related_issues`
    /// does not open an empty box.
    fn open_related_picker(&mut self) {
        let Some(detail) = self.detail.as_ref() else {
            return;
        };
        if detail.related.is_empty() {
            self.status_msg = Some("no related issues".to_string());
            return;
        }
        let options: Vec<PickerItem> = detail
            .related
            .iter()
            .enumerate()
            .map(|(index, entry)| PickerItem {
                id: index.to_string(),
                label: entry.display(),
            })
            .collect();
        let mut state = DropdownState::single(options);
        // Start on the entry `o` would follow, so the picker opens where the
        // reader already is.
        state.cursor = detail
            .related_cursor
            .min(state.visible_indices().len().saturating_sub(1));
        self.related_picker = Some(state);
    }

    /// Keyboard routing for the open related picker (tix #1513): the picker owns
    /// the keys while it is open, exactly as `handle_form_picker_key` does for a
    /// form dropdown. Canonical events arrive (`Up`/`Down`/`Enter`/`Esc`) because
    /// `InputContext::RelatedPicker` binds `next`/`previous`/`submit`/`cancel`.
    fn handle_related_picker_key(&mut self, key: KeyEvent) -> Result<Action> {
        let event = match self.related_picker.as_mut() {
            Some(picker) => picker.handle_key(key.code),
            None => return Ok(Action::None),
        };
        match event {
            PickerEvent::None => {}
            PickerEvent::Cancelled => {
                self.related_picker = None;
            }
            PickerEvent::Selected(ids) => {
                self.related_picker = None;
                if let Some(id) = ids.first().and_then(|id| id.parse::<usize>().ok()) {
                    if let Some(detail) = self.detail.as_mut() {
                        detail.related_cursor = id;
                        detail.clamp_related_cursor();
                    }
                    // Selecting an entry means "go there", so the picker is a
                    // navigation surface rather than a second selection step.
                    return self.follow_related();
                }
            }
            // The picker has no inline create; a `Created` event cannot arise from
            // the keys bound in its context, and ignoring it is honest.
            PickerEvent::Created(_) => {}
        }
        Ok(Action::None)
    }

    /// Follow the detail pane's selected related entry (tix #1513).
    ///
    /// Three shapes, matching [`crate::related::RelatedRef`]:
    /// - `Local` resolves through the store and opens the issue in the pane;
    /// - `Path` opens the parsed file read-only (it may be outside the store), or
    ///   hands the path to the resolved viewer when it does not parse as an issue;
    /// - `Url` launches the system browser, and falls back to showing the URL so it
    ///   can be copied.
    ///
    /// Every failure is a status message, never an `Err`: a broken link in one issue
    /// must not end the session.
    fn follow_related(&mut self) -> Result<Action> {
        let Some(detail) = self.detail.as_ref() else {
            return Ok(Action::None);
        };
        let Some(entry) = detail.related.get(detail.related_cursor).cloned() else {
            // Nothing to follow, and saying so is better than a key that silently
            // does nothing (#1513).
            self.status_msg = Some("no related issues".to_string());
            return Ok(Action::None);
        };
        let base = crate::related::base_dir(&self.store.issues_dir, &detail.issue.filename);
        match entry {
            crate::related::RelatedRef::Local(raw) => {
                match crate::related::resolve_local(&self.store, &raw) {
                    // Built **before** the snapshot is pushed, so a store failure
                    // leaves the stack and the pane untouched and reports instead of
                    // ending the session — the same rule the path and URL branches
                    // follow.
                    Ok(issue) => match self.detail_state_for(issue) {
                        Ok(state) => {
                            self.push_detail_snapshot();
                            self.detail = Some(state);
                            self.mode = Mode::Detail;
                        }
                        Err(e) => self.status_msg = Some(format!("related {raw}: {e}")),
                    },
                    Err(e) => self.status_msg = Some(format!("related {raw}: {e}")),
                }
            }
            crate::related::RelatedRef::Path { .. } => return self.follow_path(&base, &entry),
            crate::related::RelatedRef::Url { .. } => {
                let url = entry.display();
                match open_in_browser(&url) {
                    Ok(()) => self.status_msg = Some(format!("opened {url}")),
                    // Not an error the app can act on: the URL is shown so it can
                    // be copied into a browser by hand.
                    Err(e) => self.status_msg = Some(format!("{url} (could not open: {e})")),
                }
            }
        }
        Ok(Action::None)
    }

    /// Follow a `Path` entry (tix #1513).
    ///
    /// A path that lands **inside** the store is opened as an ordinary issue
    /// through the service (it is not "external" just because it was written as a
    /// path); anything else is opened read-only when it parses as an issue, or
    /// handed to the read-only viewer when it does not — the viewer needs the
    /// terminal, so it travels back as an [`Action`].
    fn follow_path(&mut self, base: &Path, entry: &crate::related::RelatedRef) -> Result<Action> {
        let Some(path) = crate::related::resolve_path(base, entry) else {
            return Ok(Action::None);
        };
        if let Ok(relative) = path.strip_prefix(&self.store.issues_dir) {
            let name = relative.to_string_lossy().to_string();
            if let Ok(issue) = self.store.get(IssueSelector::Filename(name)) {
                match self.detail_state_for(issue) {
                    Ok(state) => {
                        self.push_detail_snapshot();
                        self.detail = Some(state);
                        self.mode = Mode::Detail;
                    }
                    // A store failure is reported, not propagated: a link must not be
                    // able to end the session (#1513).
                    Err(e) => self.status_msg = Some(format!("related: {e}")),
                }
                return Ok(Action::None);
            }
        }
        match crate::related::read_issue_file(&path) {
            Ok(issue) => {
                self.push_detail_snapshot();
                self.open_external_detail(issue);
                Ok(Action::None)
            }
            // Not an issue file: hand it to the read-only viewer, which can page
            // anything. A viewer that cannot be resolved is a status message, not a
            // failed key.
            Err(_) => match crate::editor::resolve_viewer(self.store.config.viewer.as_deref()) {
                Ok(_viewer) => Ok(Action::OpenViewerAt(path)),
                Err(e) => {
                    self.status_msg = Some(format!("viewer: {e}"));
                    Ok(Action::None)
                }
            },
        }
    }

    /// Push the current pane onto the back stack, bounded (tix #1513).
    fn push_detail_snapshot(&mut self) {
        let Some(current) = self.detail.as_ref() else {
            return;
        };
        if self.nav_stack.len() >= MAX_DETAIL_NAV {
            self.nav_stack.remove(0);
        }
        self.nav_stack.push(current.clone());
    }

    /// Pop the back stack and restore the previous pane (tix #1513).
    fn nav_back(&mut self) {
        match self.nav_stack.pop() {
            Some(previous) => {
                self.detail = Some(previous);
                self.mode = Mode::Detail;
                self.related_picker = None;
            }
            // Said rather than swallowed: a back key that does nothing and says
            // nothing is indistinguishable from a missing binding.
            None => self.status_msg = Some("no previous issue".to_string()),
        }
    }

    fn handle_form_key(&mut self, key: KeyEvent) -> Result<Action> {
        if self.form_picker.is_some() {
            return self.handle_form_picker_key(key);
        }
        let form = match self.form.as_mut() {
            Some(f) => f,
            None => return Ok(Action::None),
        };
        match key.code {
            KeyCode::Esc => {
                self.form = None;
                self.mode = Mode::Board;
                Ok(Action::None)
            }
            KeyCode::Enter => {
                // The Target row is a toggle, not a submit: Enter flips Triage /
                // Todo and writes the matching status, which is what determines
                // the created issue's column. It has to be handled before the
                // submit path, or choosing a target would create the issue.
                if form.focus.is_target() {
                    let next = form.target.next();
                    self.set_form_target(next);
                    return Ok(Action::None);
                }
                // Likewise the Template row: Enter opens the picker rather than
                // submitting a form whose template the user was reaching for.
                if form.focus.is_template() {
                    self.open_template_picker();
                    return Ok(Action::None);
                }
                if form.is_date_focus() && !form.focused_date_is_complete() {
                    self.open_date_picker(Mode::Form);
                    return Ok(Action::None);
                }
                // A parent is chosen, never typed, so an **empty** Parent row has
                // nothing to submit and Enter means "choose". This is the same rule
                // the date fields follow one branch above — Enter opens the picker
                // only while the value is missing, and submits once it is there.
                //
                // Not "always open the picker", which was the first attempt: that
                // makes Parent a field the form can never be submitted from, because
                // Enter there never submits and the only way out is to tab away. A
                // chosen field that traps the submit key is worse than a plain text
                // field.
                if form.focus.is_parent() && form.parent.trim().is_empty() {
                    self.open_form_picker();
                    return Ok(Action::None);
                }
                // Status and Priority are chosen from their dropdowns and refuse
                // typing (tix #1508), so Enter on either row means "choose" and
                // never submits — the same way a Parent row keeps Enter for the
                // picker. The user submits from another row.
                if form.focus.is_status() || form.focus.is_priority() {
                    self.open_form_picker();
                    return Ok(Action::None);
                }
                if form.title.trim().is_empty() {
                    self.status_msg = Some("Title is required".to_string());
                    return Ok(Action::None);
                }
                let start_date = if form.start_date.trim().is_empty() {
                    None
                } else {
                    Some(form.start_date.trim().to_string())
                };
                let due_date = if form.due_date.trim().is_empty() {
                    None
                } else {
                    Some(form.due_date.trim().to_string())
                };
                if let Some(start) = start_date.as_deref()
                    && !crate::model::validate_date(start)
                {
                    self.status_msg = Some("Start date must be YYYY-MM-DD".to_string());
                    return Ok(Action::None);
                }
                if let Some(due) = due_date.as_deref()
                    && !crate::model::validate_date(due)
                {
                    self.status_msg = Some("Due date must be YYYY-MM-DD".to_string());
                    return Ok(Action::None);
                }
                if let (Some(start), Some(due)) = (start_date.as_deref(), due_date.as_deref())
                    && due < start
                {
                    self.status_msg = Some("Due date must be >= start date".to_string());
                    return Ok(Action::None);
                }
                let title = form.title.trim().to_string();
                // The body is submitted verbatim — not trimmed, because leading or
                // trailing blank lines in Markdown are content, and a template
                // writes them on purpose.
                let body = form.body.clone();
                let status_str = if form.status.trim().is_empty() {
                    self.store
                        .config
                        .default_config()
                        .columns
                        .first()
                        .cloned()
                        .unwrap_or_else(|| "todo".to_string())
                } else {
                    form.status.trim().to_string()
                };
                let priority: Priority = form.priority.parse().unwrap_or_default();
                let identity = git_identity();
                let assignee = if form.assignee.trim().is_empty() {
                    None
                } else {
                    resolve_me(form.assignee.trim(), identity.as_ref())
                };
                let labels: Vec<String> = form
                    .labels
                    .split(',')
                    .map(|s| s.trim().to_string())
                    .filter(|s| !s.is_empty())
                    .collect();
                let estimate = if form.estimate.trim().is_empty() {
                    None
                } else {
                    Some(form.estimate.trim().to_string())
                };
                let cycles = {
                    let values: Vec<String> = form
                        .cycles
                        .split(',')
                        .map(str::trim)
                        .filter(|s| !s.is_empty())
                        .map(str::to_string)
                        .collect();
                    if values.is_empty() {
                        // No explicit selection joins the default cycle, the
                        // same answer the CLI create core gives (tui-cycle-mode).
                        Some(vec![crate::commands::create::default_cycle_name(
                            &self.store.config,
                        )])
                    } else {
                        Some(values)
                    }
                };
                let milestones = {
                    let values: Vec<String> = form
                        .milestones
                        .split(',')
                        .map(str::trim)
                        .filter(|s| !s.is_empty())
                        .map(str::to_string)
                        .collect();
                    (!values.is_empty()).then_some(values)
                };
                let reviewer = if form.reviewer.trim().is_empty() {
                    None
                } else {
                    Some(form.reviewer.trim().to_string())
                };

                // The parent is resolved and validated through the hierarchy
                // service **before** anything is written, exactly as
                // `commands::create` does it — same resolution, same
                // `validate_new_parent`, so a bad parent creates no file, no
                // number, and no History entry. The service's own diagnostic is
                // what reaches `status_msg`, so the TUI says what the CLI says
                // rather than a second wording of the same rule.
                //
                // `validate_new_parent`, not `set_parent`: the child does not exist
                // yet, so it cannot be its own parent and cannot close a cycle. A
                // self-parent and a cycle are both *unrepresentable* here, not merely
                // rejected.
                //
                // **This call is not test-covered, and the reason is worth stating
                // rather than leaving implied.** The picker's options come from the
                // store, so every value the user can choose is a live issue; and
                // `unknown_parent` needs a selector that *resolves* to a number the
                // index does not hold. `resolve_issue` and `hierarchy_index` each
                // re-read the store, so that state exists only for a delete landing
                // between the two reads — a window no single-threaded test can enter,
                // since deleting first makes `resolve_issue` fail instead (which is
                // the refusal `t027_a_rejected_parent_keeps_the_form_open...` does
                // assert). Reverting the line leaves the suite green, so this is
                // defence in depth against a concurrent delete, kept because the CLI
                // has the identical line and the charter's parity boundary is about
                // what both surfaces *do*, not about which of them is covered.
                //
                // A rejection returns to the form with the field untouched, so the
                // user keeps everything they typed and can pick again.
                let parent_number = match form.parent.trim() {
                    "" => None,
                    raw => match self.store.resolve_issue(raw).and_then(|target| {
                        let (index, _) = self.store.hierarchy_index()?;
                        crate::hierarchy::validate_new_parent(&index, target.number)?;
                        Ok(target.number)
                    }) {
                        Ok(number) => Some(number),
                        Err(e) => {
                            self.status_msg = Some(e.to_string());
                            return Ok(Action::None);
                        }
                    },
                };

                let mut issue = Issue {
                    number: 0,
                    type_: None,
                    title,
                    status: Status::new(status_str),
                    labels,
                    priority,
                    assignee,
                    estimate,
                    commit: None,
                    gitlab_id: None,
                    linear_id: None,
                    mission: None,
                    task: None,
                    relationships: vec![],
                    related_issues: vec![],
                    files: vec![],
                    cycles,
                    milestones,
                    reviewer,
                    start_date,
                    due_date,
                    created: today(),
                    updated: today(),
                    filename: String::new(),
                    body: String::new(),
                    history: crate::model::History::new(),
                    has_retired_links_key: false,
                    parent: parent_number,
                    extra_frontmatter: std::collections::BTreeMap::new(),
                    archived: false,
                    entered_at: None,
                    source: None,
                };
                // Exactly one History entry, naming the parent (C-004). Appended to
                // the in-memory issue so `store.create` writes it with the first
                // content — an entry that only appeared on a later edit would
                // describe a create that did not happen this way. This is the step
                // the TUI's hand-built `Issue` was silently skipping (tix #1385).
                if let Some(number) = parent_number {
                    issue.history.append_now(
                        &crate::storage::actor_identity(),
                        crate::model::HistoryEventKind::ParentSet,
                        &crate::hierarchy::change_detail(None, Some(number)),
                    );
                }
                // The entry stamp, through the **same** rule the CLI's create core
                // uses: without it this form was the one create path that entered the
                // inbox without recording when, so the queue reported an `unknown` age
                // for an issue the TUI had just created. (The form still builds its own
                // `Issue` rather than calling `commands::create::create` — see tix #1385
                // for the parent/History line that cost once already; what must not be
                // duplicated is the *rule*, and it no longer is.) Applied **before** the
                // write, so the file and the stamp cannot disagree.
                crate::triage::record_entry_if_inbox(&self.store.config, &mut issue, "new")?;
                self.store.create(&mut issue, &body, None)?;
                // `issue.filename` is the store-relative path (including the
                // assignee segment); the board's cards key on that, so select
                // with it — the basename would never match and the wrong card
                // would stay selected.
                let filename = issue.filename.clone();
                let basename = filename.rsplit('/').next().unwrap_or(&filename).to_string();
                self.status_msg = Some(format!("Created {basename}"));
                self.form = None;
                self.mode = Mode::Board;
                self.refresh_corpus()?;
                self.select_card_by_filename(&filename);
                Ok(Action::None)
            }
            KeyCode::Tab | KeyCode::Down => {
                form.move_focus_next();
                Ok(Action::None)
            }
            KeyCode::BackTab | KeyCode::Up => {
                form.move_focus_prev();
                Ok(Action::None)
            }
            // On the Target row, Left/Right pick a side directly (Enter above
            // toggles). Everywhere else they are unbound and mean nothing, which
            // is why the branch is a no-op off the row rather than a navigation.
            KeyCode::Left => {
                if form.focus.is_target() {
                    self.set_form_target(crate::ui::form::NewIssueTarget::Triage);
                }
                Ok(Action::None)
            }
            KeyCode::Right => {
                if form.focus.is_target() {
                    self.set_form_target(crate::ui::form::NewIssueTarget::Todo);
                }
                Ok(Action::None)
            }
            KeyCode::F(2) => {
                if form.is_date_focus() {
                    self.open_date_picker(Mode::Form);
                } else {
                    self.open_form_picker();
                }
                Ok(Action::None)
            }
            KeyCode::Char(c) => {
                form.insert_char(c);
                Ok(Action::None)
            }
            KeyCode::Backspace => {
                form.delete_char();
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Open the calendar picker, seeded from the focused date field of the
    /// modal identified by `return_to`.
    fn open_date_picker(&mut self, return_to: Mode) {
        let current = match return_to {
            Mode::Form => self.form.as_ref().map(|f| f.focused_value().to_string()),
            Mode::PlanningForm => self
                .planning_form
                .as_ref()
                .map(|f| f.focused_value().to_string()),
            Mode::FilterModal => self.filter_modal.as_ref().map(|m| m.focused_value()),
            _ => None,
        };
        self.date_picker = Some(DatePicker::new(current.as_deref().unwrap_or("")));
        self.mode = Mode::DatePicker {
            return_to: Box::new(return_to),
        };
    }

    fn handle_date_picker_key(&mut self, key: KeyEvent) -> Result<Action> {
        let Some(picker) = self.date_picker.as_mut() else {
            self.mode = Mode::Board;
            return Ok(Action::None);
        };
        match picker.handle_key(key.code) {
            DatePickerEvent::None => {}
            DatePickerEvent::Cancelled => self.close_date_picker(),
            DatePickerEvent::Selected(value) => {
                self.apply_date_selection(&value);
                self.close_date_picker();
            }
            DatePickerEvent::Cleared => {
                self.apply_date_selection("");
                self.close_date_picker();
            }
        }
        Ok(Action::None)
    }

    /// Close the picker and restore the modal that opened it.
    fn close_date_picker(&mut self) {
        let return_to = match std::mem::replace(&mut self.mode, Mode::Board) {
            Mode::DatePicker { return_to } => *return_to,
            _ => Mode::Board,
        };
        self.date_picker = None;
        self.mode = return_to;
    }

    /// Write the picked `value` (empty clears) into the modal the picker was
    /// opened from.
    fn apply_date_selection(&mut self, value: &str) {
        let return_to = match &self.mode {
            Mode::DatePicker { return_to } => (**return_to).clone(),
            _ => return,
        };
        match return_to {
            Mode::Form => {
                if let Some(form) = self.form.as_mut() {
                    form.set_focused_date(value);
                }
            }
            Mode::PlanningForm => {
                if let Some(form) = self.planning_form.as_mut() {
                    form.set_focused_date(value);
                }
            }
            Mode::FilterModal => {
                if let Some(modal) = self.filter_modal.as_mut() {
                    modal.set_focused_date(value);
                }
                self.rebuild_board();
            }
            _ => {}
        }
    }

    fn handle_form_picker_key(&mut self, key: KeyEvent) -> Result<Action> {
        if matches!(key.code, KeyCode::Esc | KeyCode::F(2)) {
            self.form_picker = None;
            return Ok(Action::None);
        }
        // The Status dropdown refuses inline create (tix #1508): a board column the
        // form invents is not a column the board has, and it would render in the
        // Mismatched column rather than somewhere real. Swallow the create keys
        // before `DropdownState::handle_key` turns them into an InlineCreate prompt.
        if let Some(picker) = self.form_picker.as_ref()
            && !picker.field.allows_inline_create()
            && picker.state.mode != PickerMode::InlineCreate
            && matches!(key.code, KeyCode::Char('+') | KeyCode::Insert)
        {
            return Ok(Action::None);
        }
        let event = match self.form_picker.as_mut() {
            Some(picker) => picker.state.handle_key(key.code),
            None => return Ok(Action::None),
        };
        match event {
            PickerEvent::None => {}
            PickerEvent::Cancelled => {
                self.form_picker = None;
            }
            PickerEvent::Selected(ids) => {
                self.apply_picker_selection(ids);
            }
            PickerEvent::Created(value) => {
                self.apply_picker_created(value)?;
            }
        }
        Ok(Action::None)
    }

    fn open_form_picker(&mut self) {
        let Some(form) = self.form.as_ref() else {
            return;
        };
        let field = match form.focus {
            form::FormFocus::Status => FormPickerField::Status,
            form::FormFocus::Priority => FormPickerField::Priority,
            form::FormFocus::Labels => FormPickerField::Labels,
            form::FormFocus::Assignee => FormPickerField::Assignee,
            form::FormFocus::Cycles => FormPickerField::Cycles,
            form::FormFocus::Milestones => FormPickerField::Milestones,
            form::FormFocus::Reviewer => FormPickerField::Reviewer,
            form::FormFocus::Parent => FormPickerField::Parent,
            form::FormFocus::Template => FormPickerField::Template,
            _ => return,
        };
        // The template picker has its own opener (`open_template_picker`), which
        // seeds the `(none)` option and refuses when nothing is configured; F2 on
        // the row routes there rather than duplicating the fallback here.
        if field == FormPickerField::Template {
            self.open_template_picker();
            return;
        }
        let options = self.picker_options(field);
        let mut state = match field {
            FormPickerField::Labels | FormPickerField::Cycles | FormPickerField::Milestones => {
                DropdownState::multi(options)
            }
            FormPickerField::Assignee
            | FormPickerField::Reviewer
            | FormPickerField::Parent
            | FormPickerField::Status
            | FormPickerField::Priority
            | FormPickerField::Template => DropdownState::single(options),
        };
        self.seed_picker_selection(field, &mut state);
        self.form_picker = Some(FormPicker { field, state });
    }

    fn picker_options(&self, field: FormPickerField) -> Vec<PickerItem> {
        match field {
            FormPickerField::Cycles => {
                let root = self.project_root();
                let planner = Planner::from_config(self.store.config.clone(), root);
                planner
                    .cycle_names()
                    .into_iter()
                    .map(|name| PickerItem {
                        id: name.clone(),
                        label: name,
                    })
                    .collect()
            }
            FormPickerField::Milestones => {
                let root = self.project_root();
                let planner = Planner::from_config(self.store.config.clone(), root);
                planner
                    .milestone_names()
                    .unwrap_or_default()
                    .into_iter()
                    .map(|name| PickerItem {
                        id: name.clone(),
                        label: name,
                    })
                    .collect()
            }
            FormPickerField::Labels => {
                let mut out = std::collections::BTreeSet::new();
                for issue in self.store.list().unwrap_or_default() {
                    for label in issue.labels {
                        if !label.trim().is_empty() {
                            out.insert(label);
                        }
                    }
                }
                out.into_iter()
                    .map(|label| PickerItem {
                        id: label.clone(),
                        label,
                    })
                    .collect()
            }
            // The board's columns, in board order, plus the field's current value
            // when the board no longer configures it. A status the board has
            // dropped must not become unselectable from a form that still holds
            // it (tix #1508) — the same "keep the current value" rule the assignee
            // and reviewer pickers follow.
            FormPickerField::Status => {
                let columns = self.active_board_config().columns.clone();
                let mut options = crate::ui::triage::status_options(&columns);
                if let Some(form) = self.form.as_ref() {
                    let current = form.status.trim();
                    if !current.is_empty() && !columns.iter().any(|c| c == current) {
                        options.push(PickerItem {
                            id: current.to_string(),
                            label: current.to_string(),
                        });
                    }
                }
                options
            }
            // The built-in set first, then every priority the store already uses,
            // then the field's current value — the same "defaults plus what the
            // project actually uses" rule Labels follows. A custom priority is a
            // preserved model value (`Priority::Other`), so it must be listed once
            // an issue carries it rather than being re-typed from memory.
            FormPickerField::Priority => {
                const BUILT_INS: [&str; 3] = ["low", "medium", "high"];
                let mut out: Vec<String> = BUILT_INS.iter().map(|p| (*p).to_string()).collect();
                for issue in self.store.list().unwrap_or_default() {
                    let priority = issue.priority.to_string();
                    if !priority.trim().is_empty() && !out.contains(&priority) {
                        out.push(priority);
                    }
                }
                if let Some(form) = self.form.as_ref() {
                    let current = form.priority.trim().to_string();
                    if !current.is_empty() && !out.contains(&current) {
                        out.push(current);
                    }
                }
                out.into_iter()
                    .map(|priority| PickerItem {
                        id: priority.clone(),
                        label: priority,
                    })
                    .collect()
            }
            FormPickerField::Parent => {
                // Every issue in the store is a candidate parent.
                //
                // T026's note asks for the issue itself to be excluded from the
                // list, as "the first line of defense against a self-parent". The
                // form is **create-only** — `Mode::Form` has one entry point and it
                // always builds a fresh `FormState` — so there is no issue-under-edit
                // to exclude: the child does not exist yet and cannot be among its
                // own ancestors. The list is therefore unfiltered here, and the
                // defense is `hierarchy::validate_new_parent`, which runs at submit.
                // (Tracked as tix #1384: once an edit form exists, this arm must
                // exclude the edited issue, and `set_parent` becomes the write.)
                self.store
                    .list()
                    .unwrap_or_default()
                    .into_iter()
                    .map(|issue| PickerItem {
                        id: issue.number.to_string(),
                        label: format!("#{} {}", issue.number, issue.title),
                    })
                    .collect()
            }
            // Unreachable in practice: `open_form_picker` routes the Template row
            // to `open_template_picker`, which owns the `(none)` option. Kept
            // exhaustive and honest — the options *are* the configured names.
            FormPickerField::Template => self
                .template_names()
                .into_iter()
                .map(|name| PickerItem {
                    id: name.clone(),
                    label: name,
                })
                .collect(),
            FormPickerField::Assignee | FormPickerField::Reviewer => {
                let mut out = std::collections::BTreeSet::new();
                for team in self.store.config.teams.values() {
                    for member in &team.members {
                        if !member.trim().is_empty() {
                            out.insert(member.trim().to_string());
                        }
                    }
                }
                if let Some(id) = git_identity() {
                    out.insert(id.to_string());
                }
                if let Some(form) = self.form.as_ref() {
                    let current = match field {
                        FormPickerField::Assignee => form.assignee.trim(),
                        FormPickerField::Reviewer => form.reviewer.trim(),
                        _ => "",
                    };
                    if !current.is_empty() {
                        out.insert(current.to_string());
                    }
                }
                out.into_iter()
                    .map(|member| PickerItem {
                        id: member.clone(),
                        label: member,
                    })
                    .collect()
            }
        }
    }

    fn seed_picker_selection(&self, field: FormPickerField, picker: &mut DropdownState) {
        let Some(form) = self.form.as_ref() else {
            return;
        };
        let values: Vec<String> = match field {
            FormPickerField::Labels => form
                .labels
                .split(',')
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_string)
                .collect(),
            FormPickerField::Cycles => form
                .cycles
                .split(',')
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_string)
                .collect(),
            FormPickerField::Milestones => form
                .milestones
                .split(',')
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_string)
                .collect(),
            FormPickerField::Assignee => form
                .assignee
                .trim()
                .split(',')
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_string)
                .take(1)
                .collect(),
            FormPickerField::Reviewer => form
                .reviewer
                .trim()
                .split(',')
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_string)
                .take(1)
                .collect(),
            // Status and Priority are single values, held whole (a status can
            // contain spaces, so splitting on commas would be wrong), and an
            // empty field simply starts the dropdown with nothing selected.
            FormPickerField::Status => (!form.status.trim().is_empty())
                .then(|| form.status.trim().to_string())
                .into_iter()
                .collect(),
            FormPickerField::Priority => (!form.priority.trim().is_empty())
                .then(|| form.priority.trim().to_string())
                .into_iter()
                .collect(),
            // Already a resolved number, so no comma-splitting: there is exactly
            // one parent, and splitting it would corrupt a value that is legal.
            FormPickerField::Parent => (!form.parent.trim().is_empty())
                .then(|| form.parent.trim().to_string())
                .into_iter()
                .collect(),
            // Empty is `(none)`, which matches the option's empty id, so the
            // picker opens on the current selection rather than at the top.
            FormPickerField::Template => (!form.template.trim().is_empty())
                .then(|| form.template.trim().to_string())
                .into_iter()
                .collect(),
        };
        match &mut picker.selection {
            SelectionModel::Single(current) => {
                *current = values.first().cloned();
            }
            SelectionModel::Multi(current) => {
                current.clear();
                current.extend(values);
            }
        }
    }

    fn apply_picker_selection(&mut self, values: Vec<String>) {
        let Some(field) = self.form_picker.as_ref().map(|p| p.field) else {
            return;
        };
        // Templates are single-select *and* choosing one ends the interaction: the
        // picker closes and the form is pre-filled. The multi-select fields below
        // stay open on purpose, so several labels/cycles can be picked in one go.
        if field == FormPickerField::Template {
            let name = values.first().cloned().unwrap_or_default();
            self.form_picker = None;
            self.select_template(&name);
            return;
        }
        let Some(form) = self.form.as_mut() else {
            return;
        };
        match field {
            FormPickerField::Labels => form.labels = values.join(","),
            FormPickerField::Assignee => {
                form.assignee = values.first().cloned().unwrap_or_default()
            }
            FormPickerField::Cycles => form.cycles = values.join(","),
            FormPickerField::Milestones => form.milestones = values.join(","),
            // Single-select: a Status/Priority dropdown writes the one chosen
            // value, and no selection clears the row, which is the same "empty
            // means unset" the CLI accepts.
            FormPickerField::Status => form.status = values.first().cloned().unwrap_or_default(),
            FormPickerField::Priority => {
                form.priority = values.first().cloned().unwrap_or_default()
            }
            FormPickerField::Reviewer => {
                form.reviewer = values.first().cloned().unwrap_or_default()
            }
            // Single-select: at most one value, and no selection clears the field,
            // which is the same "empty means none" the CLI's `--parent ""` means.
            FormPickerField::Parent => form.parent = values.first().cloned().unwrap_or_default(),
            // Handled before the `form` borrow above: choosing a template closes
            // the picker and re-fills the form through `select_template`.
            FormPickerField::Template => {}
        }
    }

    fn apply_picker_created(&mut self, value: String) -> Result<()> {
        let value = value.trim().to_string();
        if value.is_empty() {
            return Ok(());
        }
        let Some(field) = self.form_picker.as_ref().map(|p| p.field) else {
            return Ok(());
        };
        match field {
            FormPickerField::Cycles => {
                let root = self.project_root();
                let mut planner = Planner::from_config(self.store.config.clone(), root.clone());
                match planner.add_cycle(Some(value.clone())) {
                    Ok(_) => {
                        self.reload_config_from(root.as_path())?;
                    }
                    Err(e) => {
                        self.status_msg = Some(e.to_string());
                        return Ok(());
                    }
                }
            }
            FormPickerField::Milestones => {
                let root = self.project_root();
                let planner = Planner::from_config(self.store.config.clone(), root.clone());
                match planner.create_milestone_file(&value, None, None) {
                    Ok(_) => {
                        self.reload_config_from(root.as_path())?;
                    }
                    Err(e) => {
                        self.status_msg = Some(e.to_string());
                        return Ok(());
                    }
                }
            }
            FormPickerField::Assignee | FormPickerField::Reviewer => {
                let root = self.project_root();
                let mut planner = Planner::from_config(self.store.config.clone(), root.clone());
                let team = self
                    .store
                    .config
                    .planning
                    .default_team
                    .clone()
                    .unwrap_or_else(|| "default".to_string());
                match planner.add_team_member(&team, &value) {
                    Ok(()) => {
                        self.reload_config_from(root.as_path())?;
                    }
                    Err(e) => {
                        self.status_msg = Some(e.to_string());
                        return Ok(());
                    }
                }
            }
            // `+` is inline-create: it makes a *new* cycle, milestone, or team
            // member, and appends it to the list. A parent is not something you
            // make from inside another issue's form — it is an issue that already
            // exists — so the keystroke does nothing here, exactly as it does for
            // Labels. Creating an empty issue to stand in for a parent would be
            // worse than nothing: it would write a file the user never asked for.
            // Templates are configuration, not form values: `+` cannot invent one
            // any more than it can invent a parent. It is edited in `tix.toml`.
            // A priority has no configuration record to write either — the custom
            // value *is* the form value, and it is applied through the selection
            // below like any picked option. Status never reaches here: its dropdown
            // refuses `+`, because a column the board does not configure would
            // render in the Mismatched column rather than becoming a choice.
            FormPickerField::Labels
            | FormPickerField::Parent
            | FormPickerField::Template
            | FormPickerField::Status
            | FormPickerField::Priority => {}
        }

        let next_options = self.picker_options(field);
        if let Some(picker) = self.form_picker.as_mut() {
            picker.state.options = next_options;
            picker.state.filter.clear();
            picker.state.cursor = 0;
            picker.state.mode = PickerMode::Idle;
            picker.state.create_buffer.clear();
            match &mut picker.state.selection {
                SelectionModel::Single(current) => *current = Some(value.clone()),
                SelectionModel::Multi(current) => {
                    current.insert(value.clone());
                }
            }
            let values = match &picker.state.selection {
                SelectionModel::Single(current) => current.iter().cloned().collect(),
                SelectionModel::Multi(current) => current.iter().cloned().collect(),
            };
            self.apply_picker_selection(values);
        }
        Ok(())
    }

    /// The configured new-issue template names, in declaration order
    /// (`tui-new-issue-mode`).
    fn template_names(&self) -> Vec<String> {
        self.store.config.templates.keys().cloned().collect()
    }

    /// The status a New Issue target lands the created issue in.
    ///
    /// Derived from configuration rather than hard-coded so a renamed column still
    /// works: `Triage` is the inbox's `entry_status` when the project has one, and
    /// `Todo` is a literal `todo` column when the board names one. The `Todo`
    /// fallbacks keep a project whose columns are not named `todo` creating
    /// *somewhere real* — its accepted status, then its first column — rather than
    /// writing a status the board cannot show.
    fn new_issue_target_status(&self, target: NewIssueTarget) -> String {
        let triage = self.store.config.triage.as_ref();
        match target {
            NewIssueTarget::Triage => triage
                .and_then(|t| t.entry_status.as_deref())
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .unwrap_or("triage")
                .to_string(),
            NewIssueTarget::Todo => {
                let columns = &self.store.config.default_config().columns;
                if columns.iter().any(|c| c == "todo") {
                    return "todo".to_string();
                }
                triage
                    .and_then(|t| t.accepted_status.as_deref())
                    .map(str::trim)
                    .filter(|s| !s.is_empty())
                    .map(str::to_string)
                    .or_else(|| columns.first().cloned())
                    .unwrap_or_else(|| "todo".to_string())
            }
        }
    }

    /// Choose a New Issue target and write its status into the Status row.
    ///
    /// Writing the status is what makes the choice *determine* the created issue's
    /// column: submit reads `form.status`, so the Target row cannot disagree with
    /// what is created. The Status row stays editable afterwards, which is how a
    /// column the two targets do not name is still reachable.
    fn set_form_target(&mut self, target: NewIssueTarget) {
        let status = self.new_issue_target_status(target);
        if let Some(form) = self.form.as_mut() {
            form.target = target;
            form.status = status;
        }
    }

    /// Open the template picker over the configured `[templates.<name>]` names.
    ///
    /// A `(none)` option comes first so the selection is clearable; choosing it
    /// only drops the label, leaving whatever the template pre-filled in place,
    /// because the user's typed values are the form's, not the template's.
    fn open_template_picker(&mut self) {
        if self.store.config.templates.is_empty() {
            self.status_msg = Some(
                "No new-issue templates configured; add [templates.<name>] to tix.toml".to_string(),
            );
            return;
        }
        let mut options = vec![PickerItem {
            id: String::new(),
            label: "(none)".to_string(),
        }];
        options.extend(self.template_names().into_iter().map(|name| PickerItem {
            id: name.clone(),
            label: name,
        }));
        let mut state = DropdownState::single(options);
        self.seed_picker_selection(FormPickerField::Template, &mut state);
        self.form_picker = Some(FormPicker {
            field: FormPickerField::Template,
            state,
        });
    }

    /// Pre-fill the form from a named template, or clear the selection for an
    /// empty/unknown name.
    fn select_template(&mut self, name: &str) {
        let template = self.store.config.templates.get(name).cloned();
        if let Some(form) = self.form.as_mut() {
            match template {
                Some(template) => form.apply_template(name, &template),
                None => form.template.clear(),
            }
        }
    }

    /// Run a New Issue-mode pointer action recorded during the draw. Public so the
    /// hit-region tests drive the same path the run loop does.
    pub fn apply_new_issue_action(&mut self, action: Action) -> Result<Action> {
        match action {
            Action::TemplateOpen => self.open_template_picker(),
            Action::TemplatePickOption(row) => {
                let chosen = self.form_picker.as_ref().and_then(|picker| {
                    if picker.field != FormPickerField::Template {
                        return None;
                    }
                    let index = *picker.state.visible_indices().get(row)?;
                    Some(picker.state.options.get(index)?.id.clone())
                });
                if let Some(name) = chosen {
                    self.form_picker = None;
                    self.select_template(&name);
                }
            }
            _ => {}
        }
        Ok(Action::None)
    }

    fn project_root(&self) -> PathBuf {
        Config::project_root(&self.store.issues_dir).unwrap_or_else(|| PathBuf::from("."))
    }

    fn reload_config_from(&mut self, root: &std::path::Path) -> Result<()> {
        let cfg = Config::load_with_warning(&root.join("tix.toml"), |_| {})?;
        self.bindings = cfg.effective_keybindings()?;
        self.store.config = cfg;
        Ok(())
    }

    /// Re-read `tix.toml` **when it changed on disk**, so a hand-edit made while
    /// the session is open is honoured without a restart.
    ///
    /// Called before linting an editor round trip, because the lint's job is to
    /// report the project's *current* rules: warning `unknown_key` for a key the
    /// user has just declared in `[custom_attributes]` is a false positive, and a
    /// false positive is what teaches someone to ignore the warning. It also
    /// prevents the declare-fix from rewriting `tix.toml` from a stale in-memory
    /// copy.
    ///
    /// A `tix.toml` that does not load is reported and the previous configuration
    /// is kept, and the snapshot is **not** advanced — a half-saved file is
    /// retried on the next call rather than latched.
    fn reload_config_if_changed(&mut self) -> bool {
        let Ok(path) = self.store.config_path() else {
            return false;
        };
        let Ok(bytes) = std::fs::read(&path) else {
            return false;
        };
        if self.config_snapshot.as_deref() == Some(bytes.as_slice()) {
            return false;
        }
        let root = path
            .parent()
            .map(std::path::Path::to_path_buf)
            .unwrap_or_else(|| std::path::PathBuf::from("."));
        match self.reload_config_from(&root) {
            Ok(()) => {
                self.config_snapshot = Some(bytes);
                self.reload_tabs();
                self.rebuild_board();
                true
            }
            Err(e) => {
                self.status_msg = Some(format!("tix.toml: {e} — kept the previous configuration"));
                false
            }
        }
    }

    fn handle_confirm_delete_key(&mut self, key: KeyEvent) -> Result<Action> {
        match key.code {
            KeyCode::Char('y') | KeyCode::Char('Y') => self.confirm_delete_yes(),
            _ => self.confirm_delete_no(),
        }
    }

    /// Yes branch of the confirm-delete dialog — shared by the `y` key, the
    /// `Action::ConfirmDeleteYes` mouse hit (D6), and the run loop.
    fn confirm_delete_yes(&mut self) -> Result<Action> {
        if let Some(filename) = self.confirm_delete_target.take() {
            self.store.delete(&filename)?;
            self.status_msg = Some(format!("Deleted {filename}"));
        }
        self.mode = Mode::Board;
        self.refresh_corpus()?;
        Ok(Action::None)
    }

    /// Cancel branch of the confirm-delete dialog — shared by every other key,
    /// `Action::ConfirmDeleteNo`, and the run loop.
    fn confirm_delete_no(&mut self) -> Result<Action> {
        self.confirm_delete_target = None;
        self.mode = Mode::Board;
        Ok(Action::None)
    }

    /// The blocked-move acknowledgement prompt (WP04, FR-004).
    ///
    /// Both branches go through [`mv::apply_guarded`], so the TUI's accept/reject
    /// decision, its diagnostic, and its History event are the *same code* the
    /// CLI runs. An unconfirmed move is not applied at all — the cancel branch
    /// changes nothing and returns to the board.
    fn handle_confirm_blocked_move_key(
        &mut self,
        key: KeyEvent,
        target_col: usize,
        warning: &str,
    ) -> Result<Action> {
        let confirmed = matches!(
            key.code,
            KeyCode::Char('y') | KeyCode::Char('Y') | KeyCode::Enter
        );
        if !confirmed {
            // Anything else cancels. Leaving the move unapplied is the safe
            // default: a prompt that guesses on an unrecognised key is a prompt
            // that can close blocked work by accident.
            self.mode = Mode::Board;
            self.status_msg = Some(format!("Move cancelled; {warning}"));
            return Ok(Action::None);
        }

        // WP05: the confirmation **defers** to the shared move rather than
        // re-implementing it. This branch used to carry its own copy of the
        // completion check, the commit-prompt decision, and the `apply_guarded`
        // call — a third place to keep in step with the other two move paths, and
        // the one WP04's C-004 work had to be duplicated into by hand.
        //
        // `acknowledged = true` is the whole point of the re-entry: it is what
        // suppresses the guard's refusal, so re-entering with `false` would raise
        // this same dialog again.
        self.mode = Mode::Board;
        self.move_selected_to_impl(target_col, None, true)
    }

    fn handle_move_into_done_key(&mut self, key: KeyEvent, target_col: usize) -> Result<Action> {
        match key.code {
            KeyCode::Enter => {
                let buffer = match &self.mode {
                    Mode::MoveIntoDone { buffer, .. } => buffer.clone(),
                    _ => unreachable!(),
                };

                let card = match self.board.get_selected_card().cloned() {
                    Some(c) => c,
                    None => {
                        self.mode = Mode::Board;
                        return Ok(Action::None);
                    }
                };

                let target_name = self.board.column_name(target_col).to_string();
                let trimmed = buffer.trim();
                // Through the shared path, not a local `issue.status =` write — the
                // TUI must not write History itself, or the audit trail would be
                // surface-specific.
                //
                // **This is the one move site that does not re-enter
                // `move_selected_to_impl`,** and the reason is that it carries a
                // value the card does not hold: the hash the user just typed. Re-
                // entering would see `card.commit.is_none()` again and raise the very
                // prompt the user has just answered. So the enumeration NFR-002 is
                // checked against is *two* move writers — this one and
                // `move_selected_to_impl` — plus the create form, which is a column
                // check and not a transition.
                let moved = mv::apply_guarded(
                    &self.store.config,
                    &self.store,
                    &card.filename,
                    &target_name,
                    if trimmed.is_empty() {
                        None
                    } else {
                        Some(trimmed)
                    },
                    /* override_reason */ None,
                    true,
                )?;

                self.refresh_corpus()?;
                self.board.select_column(target_col);
                // Derived from the move's own outcome, not from how this prompt
                // was reached, so a move that was confirmed as blocked says so
                // here too rather than reporting itself as an ordinary move.
                let ack = if moved.acknowledged {
                    ", blocked move acknowledged"
                } else {
                    ""
                };
                self.status_msg = Some(match trimmed {
                    "" => format!(
                        "Moved #{} to {target_name} (no commit recorded{ack})",
                        moved.issue.number
                    ),
                    _ => format!(
                        "Moved #{} to {target_name} (commit: {}{ack})",
                        moved.issue.number, trimmed
                    ),
                });
                self.mode = Mode::Board;
                Ok(Action::None)
            }
            KeyCode::Esc => {
                self.mode = Mode::Board;
                Ok(Action::None)
            }
            KeyCode::Char(c) => {
                if let Mode::MoveIntoDone { ref mut buffer, .. } = self.mode {
                    buffer.push(c);
                }
                Ok(Action::None)
            }
            KeyCode::Backspace => {
                if let Mode::MoveIntoDone { ref mut buffer, .. } = self.mode {
                    buffer.pop();
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    fn handle_help_key(&mut self, key: KeyEvent) -> Result<Action> {
        // tix #1496: while the `/` line has the keyboard, every key belongs to the
        // query. The list underneath filters as you type, so Enter only *commits* the
        // input (the query stays and the list keeps its filter) and Esc clears it — the
        // same bargain `/` makes on the board, so one gesture does not mean two things
        // in the same tool. Closing the overlay is one Esc away in both states.
        if self.help_searching {
            match key.code {
                KeyCode::Enter => self.help_searching = false,
                KeyCode::Esc => {
                    self.help_query.clear();
                    self.help_searching = false;
                }
                KeyCode::Backspace => {
                    self.help_query.pop();
                }
                KeyCode::Char(c) => self.help_query.push(c),
                _ => {}
            }
            // A narrower list starts at the top: keeping an offset from the wider list
            // would scroll the matches away before the reader saw them.
            self.help_scroll = 0;
            return Ok(Action::None);
        }
        match key.code {
            KeyCode::Char('?') | KeyCode::Char('q') | KeyCode::Char('Q') | KeyCode::Esc => {
                self.close_help();
            }
            // Not a toggle: `/` starts the input line, and the query it leaves behind is
            // what filters the list. Reopening it with the query still there is how you
            // extend a search, and Esc inside it is how you clear one.
            KeyCode::Char('/') => self.help_searching = true,
            // tix #1441/#1442: the overlay scrolls — one row for the cursor keys its
            // context already binds (`next`/`previous`, which until now the help
            // advertised and this handler ignored), one page for PgUp/PgDn, one wheel
            // notch for the wheel. The same three steps the detail pane uses, because
            // "scroll" meaning something different per surface is how a keyboard stops
            // being learnable.
            KeyCode::Down | KeyCode::Char('j') => self.scroll_help(1),
            KeyCode::Up | KeyCode::Char('k') => self.scroll_help(-1),
            KeyCode::PageDown => self.scroll_help(i32::from(self.help_page())),
            KeyCode::PageUp => self.scroll_help(-i32::from(self.help_page())),
            _ => {}
        }
        Ok(Action::None)
    }

    /// Rows one page step moves in the overlay: what fits, less a row of overlap.
    fn help_page(&self) -> u16 {
        self.help_metrics.get().visible.saturating_sub(1).max(1)
    }

    /// Open the keybindings overlay, always at the top and unfiltered (tix #1441).
    ///
    /// A help screen that reappeared halfway down — from a scroll the user made some
    /// minutes ago — would hide the first bindings from exactly the person who opened
    /// it to look them up. The same goes for a `/` query left over from last time
    /// (tix #1496).
    fn open_help(&mut self, return_to: Mode) {
        self.help_scroll = 0;
        self.help_query.clear();
        self.help_searching = false;
        self.mode = Mode::Help {
            return_to: Box::new(return_to),
        };
    }

    /// Scroll the overlay by `rows` (negative scrolls up), clamped to the list.
    ///
    /// The clamp is what makes the last row reachable *and* keeps the list from being
    /// scrolled into emptiness — a bound the old truncating overlay did not need
    /// because it could not move at all.
    fn scroll_help(&mut self, rows: i32) {
        let max = i32::from(self.help_metrics.get().max_scroll);
        let next = i32::from(self.help_scroll) + rows;
        self.help_scroll = next.clamp(0, max) as u16;
    }

    fn close_help(&mut self) {
        if let Mode::Help { return_to } = std::mem::replace(&mut self.mode, Mode::Board) {
            self.mode = *return_to;
        }
    }

    fn handle_filter_key(&mut self, key: KeyEvent) -> Result<Action> {
        match key.code {
            KeyCode::Char('q') | KeyCode::Char('Q') | KeyCode::Esc => {
                self.filter = None;
                self.board = BoardState::build_with(
                    &self.store,
                    self.active_board_config(),
                    false,
                    self.show_children,
                );
                self.status_msg = None;
                self.mode = Mode::Board;
            }
            KeyCode::Enter => {
                self.mode = Mode::Board;
            }
            KeyCode::Char(c) => {
                let mut next = match &self.mode {
                    Mode::Filter { buffer } => buffer.clone(),
                    _ => String::new(),
                };
                next.push(c);
                self.mode = Mode::Filter {
                    buffer: next.clone(),
                };
                self.apply_filter(&next);
            }
            KeyCode::Backspace => {
                let mut next = match &self.mode {
                    Mode::Filter { buffer } => buffer.clone(),
                    _ => String::new(),
                };
                next.pop();
                self.mode = Mode::Filter {
                    buffer: next.clone(),
                };
                self.apply_filter(&next);
            }
            _ => {}
        }
        Ok(Action::None)
    }

    /// The structured filter to apply right now: the live in-progress criteria
    /// while the modal is open, otherwise the committed one.
    fn active_structured_filter(&self) -> &search::StructuredFilter {
        self.filter_modal
            .as_ref()
            .map(|m| m.active_filter())
            .unwrap_or(&self.structured)
    }

    /// Open the structured filter modal seeded from the committed filter.
    fn open_filter_modal(&mut self) {
        self.filter_modal = Some(crate::ui::filter_modal::FilterModal::with_filter(
            self.structured.clone(),
        ));
        self.mode = Mode::FilterModal;
    }

    /// FilterModal keys: Tab/Shift+Tab navigate criterion rows; `r` resets all
    /// criteria (FR-014); Esc cancels; Enter normalizes + commits. Free-text
    /// typing edits the focused field and re-renders live (FR-013). All
    /// criteria run over the corpus in the same single pass as the query
    /// (NFR-001) via [`BoardState::build_filtered`].
    fn handle_filter_modal_key(&mut self, key: KeyEvent) -> Result<Action> {
        let Some(modal) = self.filter_modal.as_mut() else {
            self.mode = Mode::Board;
            return Ok(Action::None);
        };
        match key.code {
            KeyCode::Esc => {
                self.filter_modal = None;
                self.mode = Mode::Board;
                self.rebuild_board();
            }
            KeyCode::Tab | KeyCode::Down => modal.focus_next(),
            KeyCode::BackTab | KeyCode::Up => modal.focus_prev(),
            KeyCode::Char('r') | KeyCode::Char('R') => modal.clear(),
            KeyCode::Enter => {
                if modal.is_date_focus() && !modal.focused_date_is_complete() {
                    self.open_date_picker(Mode::FilterModal);
                } else {
                    let mut filter = modal.active_filter().clone();
                    filter.normalize();
                    self.structured = filter;
                    self.filter_modal = None;
                    self.mode = Mode::Board;
                    self.rebuild_board();
                }
            }
            KeyCode::Backspace => {
                modal.backspace();
                self.rebuild_board();
            }
            KeyCode::Char(c) => {
                modal.type_char(c);
                self.rebuild_board();
            }
            KeyCode::F(2) => {
                if modal.is_date_focus() {
                    self.open_date_picker(Mode::FilterModal);
                }
            }
            _ => {}
        }
        Ok(Action::None)
    }

    fn handle_comment_key(&mut self, key: KeyEvent) -> Result<Action> {
        match key.code {
            KeyCode::Esc => {
                self.mode = Mode::Detail;
                Ok(Action::None)
            }
            KeyCode::Enter => self.submit_comment(),
            KeyCode::Char(c) => {
                if let Mode::Comment { ref mut buffer } = self.mode {
                    buffer.push(c);
                }
                Ok(Action::None)
            }
            KeyCode::Backspace => {
                if let Mode::Comment { ref mut buffer } = self.mode {
                    buffer.pop();
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Move the board selection by one screen of cards (tix #1442 follow-up).
    ///
    /// A no-op before the first draw (nothing has reported a page yet) and in an empty
    /// column (the renderer reports zero, because there is nothing to page).
    fn move_selection_by_page(&mut self, direction: i32) {
        let page = self.board_page.get();
        if page == 0 {
            return;
        }
        let step = i32::try_from(page).unwrap_or(i32::MAX);
        self.board.move_selection_by(step * direction);
    }

    /// Open the F4 New Issue mode — `n` on the board, the F4 shell chord, and
    /// where `tix new` starts the session (#1398, tui-new-issue-mode).
    ///
    /// Seeds the default target's status and the git identity (FR-028, best effort:
    /// empty when git is absent, never an error). One method rather than copies,
    /// because the key, the shell switch, and the command must produce the *same*
    /// form — entry points into one mode that default differently is how a bug is
    /// born.
    pub fn open_new_issue_form(&mut self) {
        let default_assignee = crate::assignee::git_identity()
            .map(|id| id.to_string())
            .unwrap_or_default();
        let target = NewIssueTarget::default();
        let default_status = self.new_issue_target_status(target);
        let mut form = FormState::with_default_assignee(&default_status, &default_assignee);
        form.target = target;
        self.enter_form(form);
    }

    /// Put `form` on screen as the New Issue mode and record the shell mode.
    fn enter_form(&mut self, form: FormState) {
        self.form = Some(form);
        self.mode = Mode::Form;
        // `sync_top_mode` would derive this on the next key, but the direct entry
        // points (`tix new`, the F4 switch) draw the navigation highlight before any
        // key arrives, so the mode must be recorded here rather than a frame later.
        self.top_mode = TopMode::NewIssue;
    }

    /// Open the Config mode (F12, `s`, `b`), optionally seeding an inline
    /// prompt (e.g. `b` starts a new-board prompt). A seeded prompt belongs to
    /// the dashboards section, so that is the section it opens on.
    fn open_settings(&mut self, prompt: Option<SettingsPrompt>) {
        self.settings = Some(SettingsModal {
            selected: 0,
            prompt,
            section: ConfigSection::Dashboards,
            ..SettingsModal::default()
        });
        self.mode = Mode::Settings;
    }

    /// Config mode keys, dispatched by the active section (tui-config-mode).
    ///
    /// The dashboards section reuses the settings rows (column checkboxes,
    /// display toggles, editor); the cycles and milestones sections reuse the
    /// planning cursor and its create/edit/delete commands. Within either
    /// section the mode is the standard two-pane shape: `h`/`l` move the focus
    /// between the section rail and the body, `j`/`k` move inside the focused
    /// pane. An inline prompt takes every text key it is given.
    fn handle_settings_key(&mut self, key: KeyEvent) -> Result<Action> {
        let Some(section) = self.settings.as_ref().map(|m| m.section) else {
            self.mode = Mode::Board;
            return Ok(Action::None);
        };
        match section {
            ConfigSection::Dashboards => self.handle_settings_dashboards_key(key),
            ConfigSection::Cycles | ConfigSection::Milestones => {
                self.handle_settings_planning_key(key)
            }
            ConfigSection::Types | ConfigSection::CustomAttributes => {
                self.handle_settings_list_key(key)
            }
        }
    }

    /// Keys of the dashboards section: an active inline prompt takes text
    /// (`Enter` submits, `Esc` cancels); otherwise the row cursor and the
    /// column/board commands.
    fn handle_settings_dashboards_key(&mut self, key: KeyEvent) -> Result<Action> {
        let prompt_active = self.settings.as_ref().and_then(|m| m.prompt.clone());
        let Some(p) = prompt_active else {
            return self.handle_settings_browse(key);
        };
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => {
                if let Some(m) = self.settings.as_mut() {
                    m.prompt = None;
                }
                Ok(Action::None)
            }
            KeyCode::Enter | KeyCode::Char('y') | KeyCode::Char('Y') => {
                match p {
                    SettingsPrompt::AddColumn(name) => self.settings_commit_add_column(name),
                    SettingsPrompt::NewBoard(name) => self.settings_commit_new_board(name),
                    SettingsPrompt::RenameBoard { old, buffer } => {
                        self.settings_commit_rename_board(old, buffer)
                    }
                    SettingsPrompt::ConfirmDeleteBoard { name, .. } => {
                        self.settings_commit_delete_board(name)
                    }
                    SettingsPrompt::SetEditor(value) => self.settings_commit_editor(value),
                    SettingsPrompt::SetViewer(value) => self.settings_commit_viewer(value),
                    // These belong to the Types / Attributes sections and
                    // are never seeded here; submitting one is a no-op.
                    SettingsPrompt::AddType(_) | SettingsPrompt::AddAttribute(_) => {}
                }
                Ok(Action::None)
            }
            KeyCode::Char(c) => {
                self.settings_prompt_push(c);
                Ok(Action::None)
            }
            KeyCode::Backspace => {
                self.settings_prompt_pop();
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Type into the active text prompt. Prompts that only confirm
    /// (`ConfirmDeleteBoard`) ignore text.
    fn settings_prompt_push(&mut self, c: char) {
        if let Some(m) = self.settings.as_mut()
            && let Some(prompt) = m.prompt.as_mut()
        {
            match prompt {
                SettingsPrompt::AddColumn(b)
                | SettingsPrompt::NewBoard(b)
                | SettingsPrompt::RenameBoard { buffer: b, .. }
                | SettingsPrompt::SetEditor(b)
                | SettingsPrompt::SetViewer(b)
                | SettingsPrompt::AddType(b)
                | SettingsPrompt::AddAttribute(b) => b.push(c),
                SettingsPrompt::ConfirmDeleteBoard { .. } => {}
            }
        }
    }

    fn settings_prompt_pop(&mut self) {
        if let Some(m) = self.settings.as_mut()
            && let Some(prompt) = m.prompt.as_mut()
        {
            match prompt {
                SettingsPrompt::AddColumn(b)
                | SettingsPrompt::NewBoard(b)
                | SettingsPrompt::RenameBoard { buffer: b, .. }
                | SettingsPrompt::SetEditor(b)
                | SettingsPrompt::SetViewer(b)
                | SettingsPrompt::AddType(b)
                | SettingsPrompt::AddAttribute(b) => {
                    b.pop();
                }
                SettingsPrompt::ConfirmDeleteBoard { .. } => {}
            }
        }
    }

    /// Browsing the dashboards rows: no inline prompt is active.
    ///
    /// The two-pane model: `h`/`l` (or `←`/`→`) move the focus between the
    /// section rail and the body, clamped at the ends; `j`/`k` (or `↓`/`↑`)
    /// move inside the focused pane — the selected section in the rail, the row
    /// cursor in the body. `Enter` steps from the rail into the body and
    /// activates the selected row from the body; `Space` still toggles the row
    /// directly. The mode-level commands (`a`, `n`, `e`, `x`, `Tab`) are
    /// available from either pane.
    fn handle_settings_browse(&mut self, key: KeyEvent) -> Result<Action> {
        let pane = self.settings.as_ref().map(|m| m.pane).unwrap_or_default();
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => {
                self.close_config_mode();
                Ok(Action::None)
            }
            KeyCode::Left | KeyCode::Char('h') => {
                self.config_move_pane(-1);
                Ok(Action::None)
            }
            KeyCode::Right | KeyCode::Char('l') => {
                self.config_move_pane(1);
                Ok(Action::None)
            }
            KeyCode::Up | KeyCode::Char('k') => {
                match pane {
                    ConfigPane::Sections => self.config_prev_section(),
                    ConfigPane::Body => {
                        let count = board_rows_len(self.active_board_config());
                        if let Some(m) = self.settings.as_mut() {
                            m.move_selected(-1, count);
                        }
                    }
                }
                Ok(Action::None)
            }
            KeyCode::Down | KeyCode::Char('j') => {
                match pane {
                    ConfigPane::Sections => self.config_next_section(),
                    ConfigPane::Body => {
                        let count = board_rows_len(self.active_board_config());
                        if let Some(m) = self.settings.as_mut() {
                            m.move_selected(1, count);
                        }
                    }
                }
                Ok(Action::None)
            }
            KeyCode::Tab => {
                self.settings_next_board();
                Ok(Action::None)
            }
            KeyCode::BackTab => {
                self.settings_prev_board();
                Ok(Action::None)
            }
            KeyCode::Enter => match pane {
                ConfigPane::Sections => {
                    self.config_move_pane(1);
                    Ok(Action::None)
                }
                ConfigPane::Body => self.settings_toggle_selected(),
            },
            KeyCode::Char(' ') => self.settings_toggle_selected(),
            KeyCode::Char('a') => {
                if let Some(m) = self.settings.as_mut() {
                    m.prompt = Some(SettingsPrompt::AddColumn(String::new()));
                }
                Ok(Action::None)
            }
            KeyCode::Char('n') => {
                if let Some(m) = self.settings.as_mut() {
                    m.prompt = Some(SettingsPrompt::NewBoard(String::new()));
                }
                Ok(Action::None)
            }
            KeyCode::Char('e') => {
                let old = self.active_board_name().to_string();
                if let Some(m) = self.settings.as_mut() {
                    m.prompt = Some(SettingsPrompt::RenameBoard {
                        old: old.clone(),
                        buffer: old,
                    });
                }
                Ok(Action::None)
            }
            KeyCode::Char('x') | KeyCode::Char('X') => {
                if self.store.config.configs().count() <= 1 {
                    self.status_msg = Some("Cannot delete the last board".to_string());
                    return Ok(Action::None);
                }
                let name = self.active_board_name().to_string();
                let referencing = Self::board_reference_count(&name);
                if let Some(m) = self.settings.as_mut() {
                    m.prompt = Some(SettingsPrompt::ConfirmDeleteBoard { name, referencing });
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Keys of the cycles/milestones sections: the planning cursor and its
    /// create/edit/delete commands, plus the pane model and close.
    ///
    /// Same two panes as the dashboards section: `h`/`l` move the focus between
    /// the rail and the body, `j`/`k` move the section (rail) or the row (body),
    /// and `Enter` steps into the body from the rail then edits the selected
    /// cycle or milestone from the body.
    fn handle_settings_planning_key(&mut self, key: KeyEvent) -> Result<Action> {
        if self.planning.is_none() {
            let mut modal = PlanningModal::new();
            modal.segment = match self.settings.as_ref().map(|m| m.section) {
                Some(ConfigSection::Milestones) => PlanningSegment::Milestones,
                _ => PlanningSegment::Cycles,
            };
            self.planning = Some(modal);
        }
        // A delete confirmation is answered before anything else, through the
        // same handler the planning surface uses.
        if let Some(prompt) = self.planning.as_ref().and_then(|m| m.prompt.clone()) {
            return self.handle_planning_confirm_key(key, prompt);
        }
        // The Milestones mode hides the section rail, so its vertical keys always
        // walk the milestone rows — the rail's `Sections` pane does not exist there.
        let pane = if self.milestone_mode {
            ConfigPane::Body
        } else {
            self.settings.as_ref().map(|m| m.pane).unwrap_or_default()
        };
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => {
                self.close_config_mode();
                Ok(Action::None)
            }
            KeyCode::Left | KeyCode::Char('h') => {
                self.config_move_pane(-1);
                Ok(Action::None)
            }
            KeyCode::Right | KeyCode::Char('l') => {
                self.config_move_pane(1);
                Ok(Action::None)
            }
            KeyCode::Up | KeyCode::Char('k') => {
                match pane {
                    ConfigPane::Sections => self.config_prev_section(),
                    ConfigPane::Body => {
                        let len = self.planning_rows_len();
                        if let Some(m) = self.planning.as_mut() {
                            m.move_selected(-1, len);
                        }
                    }
                }
                Ok(Action::None)
            }
            KeyCode::Down | KeyCode::Char('j') => {
                match pane {
                    ConfigPane::Sections => self.config_next_section(),
                    ConfigPane::Body => {
                        let len = self.planning_rows_len();
                        if let Some(m) = self.planning.as_mut() {
                            m.move_selected(1, len);
                        }
                    }
                }
                Ok(Action::None)
            }
            KeyCode::Enter => match pane {
                ConfigPane::Sections => {
                    self.config_move_pane(1);
                    Ok(Action::None)
                }
                ConfigPane::Body => self.planning_open_edit(),
            },
            KeyCode::Char('n') => {
                self.planning_open_create();
                Ok(Action::None)
            }
            KeyCode::Char('e') => self.planning_open_edit(),
            KeyCode::Char('x') | KeyCode::Char('X') => self.planning_confirm_delete(),
            // `m` opens the planning-management surface for the section on
            // screen (the Cycle mode's `m` does the same). It is bound in the
            // Milestones context; a user who rebinds it into `settings` reaches
            // the same place.
            KeyCode::Char('m') | KeyCode::Char('M') => {
                let segment = if self.milestone_mode
                    || self.settings.as_ref().map(|m| m.section) == Some(ConfigSection::Milestones)
                {
                    PlanningSegment::Milestones
                } else {
                    PlanningSegment::Cycles
                };
                self.open_planning_modal();
                if let Some(modal) = self.planning.as_mut() {
                    modal.segment = segment;
                    modal.selected = 0;
                    modal.prompt = None;
                }
                Ok(Action::None)
            }
            // `?` opens the overlay from the Milestones mode (bound there). The
            // Config mode's `settings` context does not bind `help`, so this arm
            // is reached only when a user binds `?` into that context.
            KeyCode::Char('?') => {
                self.open_help(Mode::Settings);
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Keys of the Types / Attributes sections: an active inline prompt
    /// takes text (`Enter` submits, `Esc` cancels); otherwise the row cursor plus
    /// add (`n`) and remove (`x`). The two panes mirror the other sections —
    /// `h`/`l` move focus, `j`/`k` move the section (rail) or the row (body).
    fn handle_settings_list_key(&mut self, key: KeyEvent) -> Result<Action> {
        if let Some(prompt) = self.settings.as_ref().and_then(|m| m.prompt.clone()) {
            match key.code {
                KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => {
                    if let Some(m) = self.settings.as_mut() {
                        m.prompt = None;
                    }
                }
                KeyCode::Enter | KeyCode::Char('y') | KeyCode::Char('Y') => match prompt {
                    SettingsPrompt::AddType(value) => self.settings_commit_add_type(value),
                    SettingsPrompt::AddAttribute(value) => {
                        self.settings_commit_add_attribute(value)
                    }
                    _ => {}
                },
                KeyCode::Char(c) => self.settings_prompt_push(c),
                KeyCode::Backspace => self.settings_prompt_pop(),
                _ => {}
            }
            return Ok(Action::None);
        }
        let section = self
            .settings
            .as_ref()
            .map(|m| m.section)
            .unwrap_or_default();
        let pane = self.settings.as_ref().map(|m| m.pane).unwrap_or_default();
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => {
                self.close_config_mode();
                Ok(Action::None)
            }
            KeyCode::Left | KeyCode::Char('h') => {
                self.config_move_pane(-1);
                Ok(Action::None)
            }
            KeyCode::Right | KeyCode::Char('l') => {
                self.config_move_pane(1);
                Ok(Action::None)
            }
            KeyCode::Up | KeyCode::Char('k') => {
                match pane {
                    ConfigPane::Sections => self.config_prev_section(),
                    ConfigPane::Body => {
                        let len = self.settings_list_len(section);
                        if let Some(m) = self.settings.as_mut() {
                            m.move_selected(-1, len);
                        }
                    }
                }
                Ok(Action::None)
            }
            KeyCode::Down | KeyCode::Char('j') => {
                match pane {
                    ConfigPane::Sections => self.config_next_section(),
                    ConfigPane::Body => {
                        let len = self.settings_list_len(section);
                        if let Some(m) = self.settings.as_mut() {
                            m.move_selected(1, len);
                        }
                    }
                }
                Ok(Action::None)
            }
            KeyCode::Enter => {
                // Enter steps from the rail into the body, matching the other
                // sections; the body's rows have no Enter action (add/remove are
                // the `n`/`x` commands).
                if pane == ConfigPane::Sections {
                    self.config_move_pane(1);
                }
                Ok(Action::None)
            }
            KeyCode::Char('n') => {
                let prompt = match section {
                    ConfigSection::CustomAttributes => SettingsPrompt::AddAttribute(String::new()),
                    _ => SettingsPrompt::AddType(String::new()),
                };
                if let Some(m) = self.settings.as_mut() {
                    m.prompt = Some(prompt);
                }
                Ok(Action::None)
            }
            KeyCode::Char('x') | KeyCode::Char('X') => {
                self.settings_remove_selected(section);
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// The number of rows in a Types / Attributes section.
    fn settings_list_len(&self, section: ConfigSection) -> usize {
        match section {
            ConfigSection::Types => self.store.config.custom_types().len(),
            ConfigSection::CustomAttributes => self.store.config.attributes().len(),
            _ => 0,
        }
    }

    /// Remove the selected entry of a list section and persist. The cursor moves
    /// to the entry that took its place (the previous one at the end of the list).
    fn settings_remove_selected(&mut self, section: ConfigSection) {
        let selected = self.settings.as_ref().map(|m| m.selected).unwrap_or(0);
        let removed = match section {
            ConfigSection::Types => {
                let mut types = self.store.config.custom_types();
                if selected >= types.len() {
                    return;
                }
                let removed = types.remove(selected);
                self.store.config.custom_types = Some(types);
                removed
            }
            ConfigSection::CustomAttributes => {
                let mut attrs = self.store.config.attributes();
                if selected >= attrs.len() {
                    return;
                }
                let removed = attrs.remove(selected);
                self.store.config.custom_attributes.keys = attrs;
                removed
            }
            _ => return,
        };
        if !self.persist_config() {
            return;
        }
        let len = self.settings_list_len(section);
        if let Some(m) = self.settings.as_mut() {
            let target = selected.saturating_sub(1).min(len.saturating_sub(1));
            m.move_selected_to(target, len);
        }
        self.status_msg = Some(match section {
            ConfigSection::Types => format!("Removed type '{removed}'"),
            _ => format!("Removed attribute '{removed}'"),
        });
    }

    /// Add a `custom_types` entry and persist. An empty name is refused; a
    /// duplicate (case-insensitively) is refused with a message rather than
    /// silently ignored.
    fn settings_commit_add_type(&mut self, value: String) {
        let value = value.trim().to_string();
        if value.is_empty() {
            self.status_msg = Some("Type name is required".to_string());
            return;
        }
        // `custom_types()` falls back to the default set when unset, so adding to
        // a project that never declared the key materializes the defaults plus
        // the new name — the same list `tix init` would have written.
        let mut types = self.store.config.custom_types();
        if types.iter().any(|t| t.eq_ignore_ascii_case(&value)) {
            self.status_msg = Some(format!("Type '{value}' already exists"));
            return;
        }
        types.push(value.clone());
        self.store.config.custom_types = Some(types);
        if !self.persist_config() {
            return;
        }
        if let Some(m) = self.settings.as_mut() {
            m.prompt = None;
        }
        self.status_msg = Some(format!("Added type '{value}'"));
    }

    /// Add an attribute entry and persist, refusing a blank or duplicate name.
    /// When no `[custom_attributes]` are declared, the built-in attributes are
    /// materialized first, mirroring the Types section.
    fn settings_commit_add_attribute(&mut self, value: String) {
        let value = value.trim().to_string();
        if value.is_empty() {
            self.status_msg = Some("Attribute name is required".to_string());
            return;
        }
        let mut attrs = self.store.config.attributes();
        if attrs.iter().any(|key| key.eq_ignore_ascii_case(&value)) {
            self.status_msg = Some(format!("Attribute '{value}' already exists"));
            return;
        }
        attrs.push(value.clone());
        self.store.config.custom_attributes.keys = attrs;
        if !self.persist_config() {
            return;
        }
        if let Some(m) = self.settings.as_mut() {
            m.prompt = None;
        }
        self.status_msg = Some(format!("Added attribute '{value}'"));
    }

    /// Leave the Config mode back to the board, dropping every section's state.
    fn close_config_mode(&mut self) {
        self.settings = None;
        self.planning = None;
        self.planning_form = None;
        // The Milestones mode borrowed this surface; release the flag so a later
        // `s`/F12 opens Config rather than Milestones.
        self.milestone_mode = false;
        self.mode = Mode::Board;
        self.rebuild_board();
    }

    /// Switch the Config mode's active section, keeping the planning cursor in
    /// step with the cycles/milestones sections. Selecting a section also puts
    /// the focus on the rail (that is where the selection was made — a rail
    /// click, or `j`/`k` while the rail is focused).
    fn config_set_section(&mut self, section: ConfigSection) {
        // The Milestones mode has no rail: its section is pinned, so nothing may
        // move it.
        if self.milestone_mode {
            return;
        }
        if let Some(m) = self.settings.as_mut() {
            m.set_section(section);
            m.focus(ConfigPane::Sections);
        }
        let segment = match section {
            ConfigSection::Dashboards | ConfigSection::Types | ConfigSection::CustomAttributes => {
                return;
            }
            ConfigSection::Cycles => PlanningSegment::Cycles,
            ConfigSection::Milestones => PlanningSegment::Milestones,
        };
        let modal = self.planning.get_or_insert_with(PlanningModal::new);
        if modal.segment != segment {
            modal.segment = segment;
            modal.selected = 0;
            modal.prompt = None;
        }
    }

    fn config_next_section(&mut self) {
        if self.milestone_mode {
            return;
        }
        if let Some(next) = self.settings.as_ref().map(|m| m.section.next()) {
            self.config_set_section(next);
        }
    }

    fn config_prev_section(&mut self) {
        if self.milestone_mode {
            return;
        }
        if let Some(prev) = self.settings.as_ref().map(|m| m.section.prev()) {
            self.config_set_section(prev);
        }
    }

    /// Move the Config mode's pane focus along the horizontal axis (`h`/`l`,
    /// `←`/`→`), clamped to the two panes — `Sections` on the left, `Body` on
    /// the right — rather than wrapping.
    fn config_move_pane(&mut self, delta: isize) {
        // The Milestones mode hides the rail, so there is no pane to move to.
        if self.milestone_mode {
            return;
        }
        if let Some(m) = self.settings.as_mut() {
            m.move_pane(delta);
        }
    }

    /// Apply a click that landed on the Config mode's surface. A rail entry
    /// focuses the rail (and switches section); a body row focuses the body and
    /// moves that section's row cursor — the caller runs the row's own action.
    /// This is the one place pane focus follows the pointer (D3/D6).
    fn apply_config_click(&mut self, action: Action) {
        match action {
            Action::ConfigSection(section) => self.config_set_section(section),
            Action::SettingsRow(row) => {
                let count = board_rows_len(self.active_board_config());
                if let Some(modal) = self.settings.as_mut() {
                    modal.focus(ConfigPane::Body);
                    modal.move_selected_to(row, count);
                }
            }
            Action::ConfigPlanningRow(row) => {
                let len = self.planning_rows_len();
                if let Some(modal) = self.settings.as_mut() {
                    modal.focus(ConfigPane::Body);
                }
                if let Some(modal) = self.planning.as_mut() {
                    modal.move_selected_to(row, len);
                }
            }
            Action::ConfigListRow(row) => {
                let section = self
                    .settings
                    .as_ref()
                    .map(|modal| modal.section)
                    .unwrap_or_default();
                let len = self.settings_list_len(section);
                if let Some(modal) = self.settings.as_mut() {
                    modal.focus(ConfigPane::Body);
                    modal.move_selected_to(row, len);
                }
            }
            _ => {}
        }
    }

    /// How many issues reference `name` as a board. **Zero today**: nothing in
    /// issue frontmatter names a board (only `status`/`cycles`/`milestones`),
    /// so a board rename needs no issue cascade and a board delete has no
    /// references to report beyond the count. The count is still computed so
    /// the confirmation states a number rather than assuming one.
    fn board_reference_count(_name: &str) -> usize {
        0
    }

    fn settings_next_board(&mut self) {
        self.tabs.next();
        self.active_config = self.tabs.selected;
        self.switch_config();
        if let Some(ref mut m) = self.settings {
            m.selected = 0;
        }
    }

    fn settings_prev_board(&mut self) {
        self.tabs.previous();
        self.active_config = self.tabs.selected;
        self.switch_config();
        if let Some(ref mut m) = self.settings {
            m.selected = 0;
        }
    }

    /// The cycles the F3 mode lists, in the order `Planner` knows them.
    ///
    /// Every name comes through `Planner` — the same read path the planning
    /// surface and the CLI use — and the implicit `Default` cycle is always
    /// present even when no file backs it, so a fresh project shows the cycle
    /// its new issues join. Progress comes from [`Planner::cycle_progress`],
    /// which counts by cycle membership and the board's completion rule, so the
    /// mode cannot disagree with `tix cycle list`.
    fn cycle_entries(&self) -> Vec<crate::ui::cycle::CycleEntry> {
        let root = self.project_root();
        let planner = Planner::from_config(self.store.config.clone(), root);
        let mut names = planner.cycle_names();
        if !names
            .iter()
            .any(|name| name == crate::cycle_store::DEFAULT_CYCLE_NAME)
        {
            names.push(crate::cycle_store::DEFAULT_CYCLE_NAME.to_string());
        }
        names
            .into_iter()
            .map(|name| {
                let cycle = planner.cycle(&name);
                crate::ui::cycle::CycleEntry {
                    progress: planner.cycle_progress(&self.store, &name),
                    description: cycle
                        .and_then(|c| c.description.clone())
                        .unwrap_or_default(),
                    start_date: cycle.and_then(|c| c.start_date.clone()),
                    due_date: cycle.and_then(|c| c.due_date.clone()),
                    name,
                }
            })
            .collect()
    }

    /// The mode's rows grouped current / future / archived on today's date.
    fn cycle_groups(&self) -> Vec<crate::ui::cycle::CycleGrouping> {
        crate::ui::cycle::group_entries(self.cycle_entries(), &today())
    }

    /// The name of the cycle the rail should mark active: the F3 Cycle mode's
    /// cursor target, or `None` when that mode is not the shell's top mode.
    ///
    /// Read from the **rendered** flat order ([`crate::ui::cycle::flat_entries`])
    /// — the same order the listing highlights and the issue table lists — so
    /// the bold limb names the cycle the mode is actually showing. Gated on the
    /// top mode so a cycle does not stay bold after the user has moved to
    /// another surface, and bounds-guarded so a stale cursor past the last entry
    /// names no cycle rather than panicking.
    pub fn active_cycle_name(&self) -> Option<String> {
        if self.top_mode != TopMode::Cycle {
            return None;
        }
        let selected = self.cycle_state.as_ref()?.selected;
        let groups = self.cycle_groups();
        crate::ui::cycle::flat_entries(&groups)
            .get(selected)
            .map(|entry| entry.name.clone())
    }

    /// The name of the milestone the rail should mark active: the F5 Milestones
    /// mode's cursor target, or `None` otherwise.
    ///
    /// Gated on `milestone_mode` **and** the top mode, so the Config mode's own
    /// milestones section never bolds a row through this path (its cursor is the
    /// same `planning.selected`, but the F12 surface is not the F5 mode).
    pub fn active_milestone_name(&self) -> Option<String> {
        if !self.milestone_mode || self.top_mode != TopMode::Milestones {
            return None;
        }
        let selected = self.planning.as_ref()?.selected;
        let (_cycles, milestones) = self.planning_rows();
        milestones.get(selected).map(|row| row.name.clone())
    }

    fn cycle_entry_count(&self) -> usize {
        self.cycle_entries().len()
    }

    /// Select the cycle row a click landed on — mouse parity with `j`/`k`.
    pub fn select_cycle_row(&mut self, index: usize) {
        let len = self.cycle_entry_count();
        if len == 0 {
            return;
        }
        self.cycle_state
            .get_or_insert_with(crate::ui::cycle::CycleState::default)
            .selected = usize::min(index, len - 1);
    }

    /// The F3 Cycle mode's keys: move the cursor, jump between the group
    /// sections, open planning management (create/rename/delete cycles and
    /// milestones), open help, or close.
    fn handle_cycle_key(&mut self, key: KeyEvent) -> Result<Action> {
        if !matches!(self.mode, Mode::Cycle) {
            self.mode = Mode::Board;
            return Ok(Action::None);
        }
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => {
                self.cycle_state = None;
                self.mode = Mode::Board;
            }
            KeyCode::Up | KeyCode::Char('k') => {
                let len = self.cycle_entry_count();
                if let Some(state) = self.cycle_state.as_mut() {
                    state.move_selected(-1, len);
                }
            }
            KeyCode::Down | KeyCode::Char('j') => {
                let len = self.cycle_entry_count();
                if let Some(state) = self.cycle_state.as_mut() {
                    state.move_selected(1, len);
                }
            }
            // The listing's horizontal axis is its group sections
            // (tui-cycle-mode): `h`/`l` land on the first entry of the previous
            // / next **rendered** group and clamp at the ends. The letters are
            // listed beside the arrows because the bound keys canonicalize to
            // them; both spellings reach here.
            KeyCode::Left | KeyCode::Char('h') => {
                let groups = self.cycle_groups();
                if let Some(state) = self.cycle_state.as_mut() {
                    state.move_group(&groups, -1);
                }
            }
            KeyCode::Right | KeyCode::Char('l') => {
                let groups = self.cycle_groups();
                if let Some(state) = self.cycle_state.as_mut() {
                    state.move_group(&groups, 1);
                }
            }
            KeyCode::Char('m') | KeyCode::Char('M') => self.open_planning_modal(),
            KeyCode::Char('?') => self.open_help(Mode::Cycle),
            _ => {}
        }
        Ok(Action::None)
    }

    fn open_planning_modal(&mut self) {
        // Remember where the surface was opened from so Esc/q returns there:
        // the board's `m` comes back to the board, the Cycle mode's `m` comes
        // back to the Cycle mode it was showing (tui-cycle-mode).
        self.planning_return = self.mode.clone();
        let modal = self.planning.get_or_insert_with(PlanningModal::new);
        modal.prompt = None;
        modal.selected = 0;
        self.mode = Mode::PlanningManagement;
    }

    /// The rows the planning modal renders, read straight from the registry:
    /// cycles from `cycle_names()` + `cycle()`, milestones from
    /// `list_milestones()`, referencing issue counts from `store.list()`
    /// (same computation as `tix cycle list` / `milestone list`).
    fn planning_rows(&self) -> (Vec<PlanningRow>, Vec<PlanningRow>) {
        let root = self.project_root();
        let planner = Planner::from_config(self.store.config.clone(), root);
        let issues = self.store.list().unwrap_or_default();

        let mut cycles = Vec::new();
        for name in planner.cycle_names() {
            let cycle = planner.cycle(&name);
            let issues = issues
                .iter()
                .filter(|issue| {
                    issue
                        .cycles
                        .as_ref()
                        .is_some_and(|cs| cs.iter().any(|c| c == &name))
                })
                .count();
            cycles.push(PlanningRow {
                name,
                description: cycle
                    .and_then(|c| c.description.clone())
                    .unwrap_or_default(),
                date_a: cycle.and_then(|c| c.start_date.clone()).unwrap_or_default(),
                date_b: Some(cycle.and_then(|c| c.due_date.clone()).unwrap_or_default()),
                issues,
            });
        }

        let mut milestones = Vec::new();
        if let Ok(list) = planner.list_milestones() {
            for ms in list {
                let issues = issues
                    .iter()
                    .filter(|issue| {
                        issue
                            .milestones
                            .as_ref()
                            .is_some_and(|ml| ml.iter().any(|x| x == &ms.name))
                    })
                    .count();
                milestones.push(PlanningRow {
                    name: ms.name,
                    description: ms.description,
                    date_a: ms.target_date,
                    date_b: None,
                    issues,
                });
            }
        }
        (cycles, milestones)
    }

    /// The number of rows in the modal's active segment (for cursor clamping).
    fn planning_rows_len(&self) -> usize {
        let (cycles, milestones) = self.planning_rows();
        match self.planning.as_ref().map(|m| m.segment) {
            Some(PlanningSegment::Cycles) => cycles.len(),
            Some(PlanningSegment::Milestones) => milestones.len(),
            None => 0,
        }
    }

    /// Planning modal keys: browse the list (`j/k`/arrows, Tab segment switch,
    /// `n` create, `e` edit, `x` delete confirm); a `ConfirmDelete` prompt
    /// accepts `y`/Enter or cancels on `n`/Esc.
    fn handle_planning_key(&mut self, key: KeyEvent) -> Result<Action> {
        if self.planning.is_none() {
            self.mode = self.planning_return.clone();
            return Ok(Action::None);
        }
        if let Some(prompt) = self.planning.as_ref().and_then(|m| m.prompt.clone()) {
            return self.handle_planning_confirm_key(key, prompt);
        }
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => {
                self.planning = None;
                self.mode = self.planning_return.clone();
                Ok(Action::None)
            }
            KeyCode::Up | KeyCode::Char('k') => {
                let len = self.planning_rows_len();
                if let Some(ref mut m) = self.planning {
                    m.move_selected(-1, len);
                }
                Ok(Action::None)
            }
            KeyCode::Down | KeyCode::Char('j') => {
                let len = self.planning_rows_len();
                if let Some(ref mut m) = self.planning {
                    m.move_selected(1, len);
                }
                Ok(Action::None)
            }
            KeyCode::Tab | KeyCode::BackTab => {
                if let Some(ref mut m) = self.planning {
                    m.switch_segment();
                }
                Ok(Action::None)
            }
            // The segments are the surface's horizontal axis; the movement keys
            // switch them, matching the Config section rail (h/j/k/l + arrows in
            // every mode where the axis exists).
            KeyCode::Left | KeyCode::Char('h') | KeyCode::Right | KeyCode::Char('l') => {
                if let Some(m) = &mut self.planning {
                    m.switch_segment();
                }
                Ok(Action::None)
            }
            KeyCode::Char('n') => {
                self.planning_open_create();
                Ok(Action::None)
            }
            KeyCode::Char('e') => self.planning_open_edit(),
            KeyCode::Char('x') | KeyCode::Char('X') => self.planning_confirm_delete(),
            _ => Ok(Action::None),
        }
    }

    /// Keys while a delete confirmation prompt is up inside the modal.
    fn handle_planning_confirm_key(
        &mut self,
        key: KeyEvent,
        prompt: PlanningPrompt,
    ) -> Result<Action> {
        let PlanningPrompt::ConfirmDelete { name, .. } = prompt;
        match key.code {
            KeyCode::Char('y') | KeyCode::Char('Y') | KeyCode::Enter => {
                match self.planning_delete(&name) {
                    Ok(()) => {
                        self.status_msg = Some(format!("Deleted {name}"));
                    }
                    Err(e) => {
                        self.status_msg = Some(format!("Cannot delete {name}: {e}"));
                    }
                }
                if let Some(ref mut m) = self.planning {
                    m.prompt = None;
                }
                Ok(Action::None)
            }
            _ => {
                if let Some(ref mut m) = self.planning {
                    m.prompt = None;
                }
                Ok(Action::None)
            }
        }
    }

    /// `n`: open a blank create form for the active segment.
    fn planning_open_create(&mut self) {
        let kind = match self.planning.as_ref().map(|m| m.segment) {
            Some(PlanningSegment::Milestones) => PlanningKind::Milestone,
            _ => PlanningKind::Cycle,
        };
        self.planning_form = Some(PlanningForm::new(kind));
        self.mode = Mode::PlanningForm;
    }

    /// `e`: open an edit form pre-filled from the selected item.
    fn planning_open_edit(&mut self) -> Result<Action> {
        let Some(modal) = self.planning.as_ref() else {
            return Ok(Action::None);
        };
        let root = self.project_root();
        let planner = Planner::from_config(self.store.config.clone(), root);
        let form = match modal.segment {
            PlanningSegment::Cycles => {
                let name = match planner.cycle_names().into_iter().nth(modal.selected) {
                    Some(name) => name,
                    None => return Ok(Action::None),
                };
                let Some(cycle) = planner.cycle(&name) else {
                    return Ok(Action::None);
                };
                PlanningForm::from_cycle(&name, cycle)
            }
            PlanningSegment::Milestones => {
                let list = planner.list_milestones().unwrap_or_default();
                let Some(ms) = list.into_iter().nth(modal.selected) else {
                    return Ok(Action::None);
                };
                PlanningForm::from_milestone(&ms)
            }
        };
        self.planning_form = Some(form);
        self.mode = Mode::PlanningForm;
        Ok(Action::None)
    }

    /// `x`: compute the delete impact for the selected item and raise the
    /// inline confirm prompt (spec: reference count shown, issues untouched).
    fn planning_confirm_delete(&mut self) -> Result<Action> {
        let Some(modal) = self.planning.as_ref() else {
            return Ok(Action::None);
        };
        if modal.prompt.is_some() {
            return Ok(Action::None);
        }
        let root = self.project_root();
        let planner = Planner::from_config(self.store.config.clone(), root);
        let (name, referencing) = match modal.segment {
            PlanningSegment::Cycles => {
                let Some(name) = planner.cycle_names().into_iter().nth(modal.selected) else {
                    return Ok(Action::None);
                };
                let referencing = planner
                    .delete_impact(&self.store, &name)
                    .map(|i| i.referencing_issues.len())
                    .unwrap_or(0);
                (name, referencing)
            }
            PlanningSegment::Milestones => {
                let list = planner.list_milestones().unwrap_or_default();
                let Some(name) = list.into_iter().nth(modal.selected).map(|m| m.name) else {
                    return Ok(Action::None);
                };
                let referencing = planner
                    .milestone_delete_impact(&self.store, &name)
                    .map(|i| i.referencing_issues.len())
                    .unwrap_or(0);
                (name, referencing)
            }
        };
        if let Some(ref mut m) = self.planning {
            m.prompt = Some(PlanningPrompt::ConfirmDelete { name, referencing });
        }
        Ok(Action::None)
    }

    /// Confirm-delete an item, leaving referencing issues unchanged. Cycle
    /// deletion mutates `tix.toml`, so the store config is reloaded for
    /// pickers built from it.
    fn planning_delete(&mut self, name: &str) -> Result<()> {
        let root = self.project_root();
        let mut planner = Planner::from_config(self.store.config.clone(), root.clone());
        match self.planning.as_ref().map(|m| m.segment) {
            Some(PlanningSegment::Cycles) => {
                planner.delete_cycle(name)?;
                self.reload_config_from(&root)?;
            }
            Some(PlanningSegment::Milestones) => {
                planner.delete_milestone(name)?;
            }
            None => {}
        }
        self.refresh_corpus()?;
        Ok(())
    }

    /// Where a planning form returns when it closes. A form opened from the
    /// Config mode's cycles/milestones sections returns there — the Config mode
    /// owns the surface — while the `m` planning surface keeps the modal behind
    /// the form, as before.
    fn planning_form_return(&self) -> Mode {
        if self.settings.is_some() {
            Mode::Settings
        } else {
            Mode::PlanningManagement
        }
    }

    /// Planning form keys. Cancel closes the form back to the modal; the
    /// remaining keys (field navigation, typing, Enter/apply) live in
    /// `handle_planning_form_edit_key`.
    fn handle_planning_form_key(&mut self, key: KeyEvent) -> Result<Action> {
        if self.planning_form.is_none() {
            self.mode = self.planning_form_return();
            return Ok(Action::None);
        }
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('Q') => {
                self.planning_form = None;
                self.mode = self.planning_form_return();
                Ok(Action::None)
            }
            _ => self.handle_planning_form_edit_key(key),
        }
    }

    /// Form field navigation and editing, plus Enter to apply (task groups
    /// 3/4 fill in the mutations).
    fn handle_planning_form_edit_key(&mut self, key: KeyEvent) -> Result<Action> {
        if self.planning_form.is_none() {
            return Ok(Action::None);
        }
        match key.code {
            KeyCode::Enter => {
                if self
                    .planning_form
                    .as_ref()
                    .is_some_and(|f| f.focused_is_date() && !f.focused_date_is_complete())
                {
                    self.open_date_picker(Mode::PlanningForm);
                    Ok(Action::None)
                } else {
                    self.planning_form_apply()
                }
            }
            KeyCode::Tab | KeyCode::Down => {
                if let Some(ref mut f) = self.planning_form {
                    f.focus_next();
                }
                Ok(Action::None)
            }
            KeyCode::BackTab | KeyCode::Up => {
                if let Some(ref mut f) = self.planning_form {
                    f.focus_prev();
                }
                Ok(Action::None)
            }
            KeyCode::Backspace => {
                if let Some(ref mut f) = self.planning_form {
                    f.delete_char();
                }
                Ok(Action::None)
            }
            KeyCode::Char(c) => {
                if let Some(ref mut f) = self.planning_form {
                    f.insert_char(c);
                }
                Ok(Action::None)
            }
            KeyCode::F(2) => {
                if self
                    .planning_form
                    .as_ref()
                    .is_some_and(|f| f.focused_is_date())
                {
                    self.open_date_picker(Mode::PlanningForm);
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Apply the open form (create or edit). Filled in by task group 3
    /// (create) and 4 (edit/rename cascades).
    fn planning_form_apply(&mut self) -> Result<Action> {
        let Some(form) = self.planning_form.clone() else {
            self.mode = self.planning_form_return();
            return Ok(Action::None);
        };
        let result = self.planning_form_commit(&form);
        match result {
            Ok(()) => {
                self.planning_form = None;
                self.mode = self.planning_form_return();
                Ok(Action::None)
            }
            Err(e) => {
                self.status_msg = Some(format!("Cannot save {}: {e}", form.kind.noun()));
                Ok(Action::None)
            }
        }
    }

    fn planning_form_commit(&mut self, form: &PlanningForm) -> Result<()> {
        let root = self.project_root();
        let mut planner = Planner::from_config(self.store.config.clone(), root.clone());
        let name = form.name().trim().to_string();
        if name.is_empty() {
            return Err(TixError::InvalidInput("a name is required".to_string()));
        }
        match form.kind {
            PlanningKind::Cycle => {
                let overlaps = if let Some(old) = form.editing.as_deref() {
                    if old != name {
                        planner.rename_cycle_cascade(&self.store, old, &name)?;
                    }
                    planner.set_cycle_fields(
                        &name,
                        Some(form.description()),
                        Some(form.date_a()),
                        Some(form.date_b()),
                    )?;
                    Vec::new()
                } else {
                    planner.add_cycle(Some(name.clone()))?;
                    planner.set_cycle_fields(
                        &name,
                        Some(form.description()),
                        Some(form.date_a()),
                        Some(form.date_b()),
                    )?;
                    // A new cycle whose window intersects an existing one is
                    // created anyway; the overlap is surfaced as a status note,
                    // the TUI's counterpart to the CLI's stderr warning
                    // (tix #1509). A start-less cycle has no window and never
                    // warns.
                    planner.overlapping_cycles(&name)
                };
                self.reload_config_from(&root)?;
                if !overlaps.is_empty() {
                    self.status_msg = Some(format!(
                        "cycle `{name}` overlaps existing cycle(s): {}",
                        overlaps.join(", ")
                    ));
                }
            }
            PlanningKind::Milestone => {
                let target = if form.date_a().trim().is_empty() {
                    None
                } else {
                    Some(form.date_a())
                };
                if let Some(old) = form.editing.as_deref() {
                    if old != name {
                        let old_milestone = planner.milestone(old)?;
                        planner.rename_milestone_cascade(&self.store, &old_milestone, &name)?;
                    }
                    planner.update_milestone(&name, target, Some(form.description()))?;
                } else {
                    planner.create_milestone_file(&name, target, Some(form.description()))?;
                }
            }
        }
        self.refresh_corpus()?;
        Ok(())
    }

    fn settings_toggle_selected(&mut self) -> Result<Action> {
        let col_count = self.active_board_config().columns.len();
        let selected = self.settings.as_ref().map(|m| m.selected).unwrap_or(0);
        if selected >= col_count {
            return self.settings_toggle_display_row(selected - col_count);
        }
        let col = self
            .settings
            .as_ref()
            .and_then(|m| self.active_board_config().columns.get(m.selected))
            .cloned();
        let Some(col) = col else {
            return Ok(Action::None);
        };
        let board_name = self.active_board_name().to_string();
        let now_hidden = {
            let board_config = self.store.config.kanban.configurations.get_mut(&board_name);
            match board_config {
                Some(bc) => {
                    if let Some(pos) = bc.hidden_columns.iter().position(|h| h == &col) {
                        bc.hidden_columns.remove(pos);
                        false
                    } else {
                        bc.hidden_columns.push(col.clone());
                        true
                    }
                }
                None => return Ok(Action::None),
            }
        };
        if !self.persist_config() {
            return Ok(Action::None);
        }
        self.rebuild_board();
        let last = self.active_board_config().columns.len().saturating_sub(1);
        if let Some(ref mut m) = self.settings
            && m.selected > last
        {
            m.selected = last;
        }
        self.status_msg = Some(match now_hidden {
            true => format!("'{col}' hidden"),
            false => format!("'{col}' shown"),
        });
        Ok(Action::None)
    }

    /// Toggle/cycle one of the display rows (after the column checkboxes).
    /// Row 0 flips title wrapping, row 1 cycles the line limit through 1-5,
    /// row 2 cycles the ordering; every change persists and rebuilds the board.
    /// The general rows after those open the `$EDITOR` override prompt.
    fn settings_toggle_display_row(&mut self, row: usize) -> Result<Action> {
        if row >= crate::ui::settings::DISPLAY_ROWS {
            // The general rows, in order: the `$EDITOR` override, then the
            // read-only viewer (tix #1507). Both are `tix.toml` settings rather
            // than per-record metadata files, and both open an inline prompt.
            let general = row - crate::ui::settings::DISPLAY_ROWS;
            let prompt = match general {
                0 => {
                    SettingsPrompt::SetEditor(self.store.config.editor.clone().unwrap_or_default())
                }
                _ => {
                    SettingsPrompt::SetViewer(self.store.config.viewer.clone().unwrap_or_default())
                }
            };
            if let Some(m) = self.settings.as_mut() {
                m.prompt = Some(prompt);
            }
            return Ok(Action::None);
        }
        let board_name = self.active_board_name().to_string();
        let action_msg = {
            let board_config = self.store.config.kanban.configurations.get_mut(&board_name);
            let Some(board_config) = board_config else {
                return Ok(Action::None);
            };
            match row {
                0 => {
                    board_config.wrap_titles = !board_config.wrap_titles;
                    if board_config.wrap_titles {
                        "Wrap titles: on".to_string()
                    } else {
                        "Wrap titles: off".to_string()
                    }
                }
                1 => {
                    board_config.title_lines = board_config.title_lines % 5 + 1;
                    format!("Title lines: {}", board_config.title_lines)
                }
                2 => {
                    board_config.order_by = board_config.order_by.next();
                    format!("Order by: {}", board_config.order_by.as_str())
                }
                _ => return Ok(Action::None),
            }
        };
        if !self.persist_config() {
            return Ok(Action::None);
        }
        self.rebuild_board();
        self.status_msg = Some(action_msg);
        Ok(Action::None)
    }

    fn settings_commit_add_column(&mut self, name: String) {
        let name = name.trim().to_string();
        if name.is_empty() {
            self.status_msg = Some("Column name is required".to_string());
            return;
        }
        let board_name = self.active_board_name().to_string();
        let board_config = self.store.config.kanban.configurations.get_mut(&board_name);
        let Some(board_config) = board_config else {
            self.status_msg = Some("board not found".to_string());
            return;
        };
        if board_config.columns.iter().any(|c| c == &name) {
            self.status_msg = Some(format!("Column '{name}' already exists"));
            return;
        }
        board_config.columns.push(name.clone());
        if !self.persist_config() {
            return;
        }
        self.rebuild_board();
        let last = self.active_board_config().columns.len().saturating_sub(1);
        if let Some(ref mut m) = self.settings {
            m.prompt = None;
            m.selected = last;
        }
        self.status_msg = Some(format!("Added column '{name}'"));
    }

    fn settings_commit_new_board(&mut self, name: String) {
        let name = name.trim().to_string();
        if name.is_empty() {
            self.status_msg = Some("Board name is required".to_string());
            return;
        }
        if self.store.config.kanban.configurations.contains_key(&name) {
            self.status_msg = Some(format!("Board '{name}' already exists"));
            return;
        }
        // Lazy store creation (docs-metadata-stores): a board beyond the seeded
        // set is the point the project becomes file-backed, so `docs/boards/`
        // is created here and the next save writes every board into it — the
        // one-time write-back; `tix.toml` keeps everything else.
        if let Err(e) = self.ensure_board_store() {
            self.status_msg = Some(format!("Cannot create docs/boards/: {e}"));
            return;
        }
        self.store
            .config
            .kanban
            .configurations
            .insert(name.clone(), crate::config::BoardConfiguration::default());
        if !self.persist_config() {
            return;
        }
        self.reload_tabs();
        let idx = self
            .store
            .config
            .configs()
            .position(|(n, _)| n == name.as_str())
            .unwrap_or(0);
        self.active_config = idx;
        self.tabs.selected = idx;
        self.switch_config();
        if let Some(m) = self.settings.as_mut() {
            m.prompt = None;
            m.selected = 0;
        }
        self.status_msg = Some(format!("Added board '{name}'"));
    }

    /// Make `docs/boards/` exist, materializing the file store for a project
    /// that only had legacy `tix.toml` boards. Reading never creates it; only
    /// adding a board does (`docs-metadata-stores`, lazy directory creation).
    fn ensure_board_store(&self) -> Result<()> {
        let store = crate::board_store::BoardStore::new(&self.project_root());
        if store.exists() {
            return Ok(());
        }
        std::fs::create_dir_all(store.dir())?;
        Ok(())
    }

    /// Rename the active board: the map entry moves in place (keeping its tab
    /// position), the board file is renamed when the file store is active, and
    /// the tabs are rebuilt. Nothing in issue frontmatter names a board — only
    /// `status`/`cycles`/`milestones` — so there is **no issue cascade** to run.
    fn settings_commit_rename_board(&mut self, old: String, new: String) {
        let new = new.trim().to_string();
        if new.is_empty() {
            self.status_msg = Some("Board name is required".to_string());
            return;
        }
        if new == old {
            if let Some(m) = self.settings.as_mut() {
                m.prompt = None;
            }
            return;
        }
        if self.store.config.kanban.configurations.contains_key(&new) {
            self.status_msg = Some(format!("Board '{new}' already exists"));
            return;
        }
        let board_store = crate::board_store::BoardStore::new(&self.project_root());
        if board_store.exists()
            && board_store.get(&old).is_ok()
            && let Err(e) = board_store.rename(&old, &new)
        {
            self.status_msg = Some(format!("Cannot rename board '{old}': {e}"));
            return;
        }
        let Some(idx) = self.store.config.kanban.configurations.get_index_of(&old) else {
            self.status_msg = Some(format!("Board '{old}' not found"));
            return;
        };
        if let Some(board) = self.store.config.kanban.configurations.shift_remove(&old) {
            self.store
                .config
                .kanban
                .configurations
                .shift_insert(idx, new.clone(), board);
        }
        if !self.persist_config() {
            return;
        }
        self.reload_tabs();
        self.active_config = idx.min(self.tabs.names.len().saturating_sub(1));
        self.tabs.selected = self.active_config;
        self.switch_config();
        if let Some(m) = self.settings.as_mut() {
            m.prompt = None;
            m.selected = 0;
        }
        self.status_msg = Some(format!("Renamed board '{old}' to '{new}'"));
    }

    /// Commit the `$EDITOR` override to `tix.toml` (a blank value clears it).
    fn settings_commit_editor(&mut self, value: String) {
        let value = value.trim().to_string();
        self.store.config.editor = if value.is_empty() {
            None
        } else {
            Some(value.clone())
        };
        if !self.persist_config() {
            return;
        }
        if let Some(m) = self.settings.as_mut() {
            m.prompt = None;
        }
        self.status_msg = Some(match value.is_empty() {
            true => "Editor: (default)".to_string(),
            false => format!("Editor: {value}"),
        });
    }

    /// The Viewer row's label (tix #1507): the configured override, or the
    /// viewer the auto chain resolves to, or a note naming the chain when none
    /// of it is installed.
    ///
    /// Never panics and never blocks the frame: the auto probe is cached per
    /// process in [`editor::resolve_viewer`], so this is a string build on the
    /// hot path rather than a `which` walk.
    fn viewer_label(&self) -> String {
        match self.store.config.viewer.as_deref().map(str::trim) {
            Some(name) if !name.is_empty() && name != "auto" => name.to_string(),
            _ => match editor::resolve_viewer(None) {
                Ok(name) => format!("{name} (auto)"),
                Err(_) => format!(
                    "(none — install one of {})",
                    editor::VIEWER_CANDIDATES.join(", ")
                ),
            },
        }
    }

    /// Commit the `viewer` override to `tix.toml` (a blank value clears it back
    /// to the auto chain, tix #1507).
    fn settings_commit_viewer(&mut self, value: String) {
        let value = value.trim().to_string();
        self.store.config.viewer = if value.is_empty() {
            None
        } else {
            Some(value.clone())
        };
        if !self.persist_config() {
            return;
        }
        if let Some(m) = self.settings.as_mut() {
            m.prompt = None;
        }
        self.status_msg = Some(match value.is_empty() {
            true => "Viewer: (auto)".to_string(),
            false => format!("Viewer: {value}"),
        });
    }

    fn settings_commit_delete_board(&mut self, name: String) {
        if self.store.config.kanban.configurations.len() <= 1 {
            self.status_msg = Some("Cannot delete the last board".to_string());
            return;
        }
        if !self.store.config.kanban.configurations.contains_key(&name) {
            self.status_msg = Some(format!("Board '{name}' not found"));
            return;
        }
        let idx = self.active_config;
        // A file store that exists is authoritative, so the file goes too: a
        // save that only dropped the map entry would leave the file behind to
        // resurrect the board on the next load.
        let board_store = crate::board_store::BoardStore::new(&self.project_root());
        if board_store.exists() {
            match board_store.delete(&name) {
                Ok(()) | Err(TixError::NotFound(_)) => {}
                Err(e) => {
                    self.status_msg = Some(format!("Cannot delete board '{name}': {e}"));
                    return;
                }
            }
        }
        self.store.config.kanban.configurations.shift_remove(&name);
        if !self.persist_config() {
            return;
        }
        self.reload_tabs();
        let count = self.store.config.kanban.configurations.len();
        let target = idx.min(count.saturating_sub(1));
        self.active_config = target;
        self.tabs.selected = target;
        self.switch_config();
        if let Some(m) = self.settings.as_mut() {
            m.prompt = None;
            m.selected = 0;
        }
        self.status_msg = Some(format!("Deleted board '{name}'"));
    }

    fn persist_config(&mut self) -> bool {
        match self.store.config_path() {
            Ok(path) => match self.store.config.save(&path) {
                Ok(()) => true,
                Err(e) => {
                    self.status_msg = Some(format!("settings save: {e}"));
                    false
                }
            },
            Err(e) => {
                self.status_msg = Some(format!("settings path: {e}"));
                false
            }
        }
    }

    fn reload_tabs(&mut self) {
        let names: Vec<String> = self
            .store
            .config
            .configs()
            .map(|(name, _)| name.to_string())
            .collect();
        self.tabs = BoardTabs::new(names);
    }

    fn active_board_name(&self) -> &str {
        self.store
            .config
            .configs()
            .nth(self.active_config)
            .map(|(name, _)| name)
            .unwrap_or("default")
    }

    fn submit_comment(&mut self) -> Result<Action> {
        let buffer = match &self.mode {
            Mode::Comment { buffer } => buffer.clone(),
            _ => return Ok(Action::None),
        };
        let text = buffer.trim().to_string();
        if text.is_empty() {
            self.status_msg = Some("Comment discarded (empty)".to_string());
            self.mode = Mode::Detail;
            return Ok(Action::None);
        }
        let filename = match self.detail.as_ref() {
            Some(d) => d.issue.filename.clone(),
            None => {
                self.mode = Mode::Detail;
                return Ok(Action::None);
            }
        };
        let author = crate::assignee::git_identity()
            .map(|id| id.to_string())
            .unwrap_or_else(|| "anonymous".to_string());
        let mut issue = self.store.get(IssueSelector::Filename(filename.clone()))?;
        issue.add_comment(&author, &text);
        issue.filename = self.store.update(&filename, &issue)?;
        if let Some(ref mut d) = self.detail {
            d.issue = issue;
            d.scroll_offset = 0;
        }
        self.refresh_corpus()?;
        self.status_msg = Some(format!("Commented by {author}"));
        self.mode = Mode::Detail;
        Ok(Action::None)
    }

    /// The relationship under the detail pane's cursor, if any.
    fn selected_relationship(&self) -> Option<&crate::relationships::Relationship> {
        self.detail
            .as_ref()
            .and_then(|d| d.relationships.get(d.rel_cursor))
    }

    /// The **stable id** of the selected relationship, which is what `tix link edit`
    /// and `tix link remove` name.
    ///
    /// Taken from the id rather than from `(from, to)`, because the id survives a
    /// re-kind: `2 related 1` and `1 blocks 2` are different edges that can share an
    /// endpoint pair, and addressing one by its endpoints would be ambiguous.
    fn selected_relationship_id(&self) -> Option<String> {
        self.selected_relationship().map(|r| r.id.clone())
    }

    /// Move the relationship cursor by `delta`, clamped to the list.
    fn move_rel_cursor(&mut self, delta: isize) {
        let Some(d) = self.detail.as_mut() else {
            return;
        };
        if d.relationships.is_empty() {
            return;
        }
        let last = d.relationships.len() as isize - 1;
        let next = (d.rel_cursor as isize + delta).clamp(0, last);
        d.rel_cursor = next as usize;
    }

    /// The two-step create/edit relationship prompt (#1359).
    ///
    /// Shares one handler for `LinkCreate` and `LinkEdit` because the two differ only
    /// in what they do at the end: a create needs both a target and a kind, an edit
    /// keeps the target it already has unless the user changes it. Sharing it means
    /// the two cannot drift in how they read a selector or report a bad kind — which
    /// is the class of bug `surface-parity.md` §2 is about.
    fn handle_link_prompt_key(&mut self, key: KeyEvent) -> Result<Action> {
        match key.code {
            KeyCode::Esc => {
                // Cancel the whole flow, not just this step: `Esc` in step 2 returns
                // to the detail pane rather than to step 1, because a two-step
                // cancel that needs two presses is a trap.
                self.mode = Mode::Detail;
                self.status_msg = Some("relationship: cancelled".to_string());
                Ok(Action::None)
            }
            KeyCode::Enter => {
                let prompt = match self.mode.clone() {
                    Mode::LinkCreate { buffer, step, .. } => Some((buffer, step)),
                    Mode::LinkEdit { buffer, step, .. } => Some((buffer, step)),
                    _ => None,
                };
                match prompt {
                    Some((buffer, step)) => self.submit_link_prompt(buffer, step),
                    None => Ok(Action::None),
                }
            }
            KeyCode::Backspace => {
                if let Mode::LinkCreate { ref mut buffer, .. } = self.mode {
                    buffer.pop();
                } else if let Mode::LinkEdit { ref mut buffer, .. } = self.mode {
                    buffer.pop();
                }
                Ok(Action::None)
            }
            KeyCode::Char(c) => {
                if let Mode::LinkCreate { ref mut buffer, .. } = self.mode {
                    buffer.push(c);
                } else if let Mode::LinkEdit { ref mut buffer, .. } = self.mode {
                    buffer.push(c);
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// One prompt step: resolve a target, or apply the kind.
    fn submit_link_prompt(&mut self, buffer: String, step: LinkStep) -> Result<Action> {
        let trimmed = buffer.trim().to_string();
        let subject = self.detail.as_ref().map(|d| d.issue.number).unwrap_or(0);
        let (is_edit, index) = match &self.mode {
            Mode::LinkEdit { index, .. } => (true, *index),
            _ => (false, 0),
        };

        match step {
            LinkStep::Target => {
                if trimmed.is_empty() {
                    self.status_msg = Some("relationship: cancelled (no issue given)".into());
                    self.mode = Mode::Detail;
                    return Ok(Action::None);
                }
                // **The CLI's own resolver**, so `#4`, `4` and a title fragment all
                // work and an unresolvable selector produces the CLI's message. A
                // TUI-specific resolver would be a second place for the two surfaces
                // to disagree about what a selector means.
                let selector = match crate::commands::parse_selector(&self.store, &trimmed) {
                    Ok(selector) => selector,
                    Err(e) => {
                        self.status_msg = Some(e.to_string());
                        return Ok(Action::None);
                    }
                };
                let target = match self.store.get(selector) {
                    Ok(issue) => issue.number,
                    Err(e) => {
                        self.status_msg = Some(e.to_string());
                        return Ok(Action::None);
                    }
                };
                if target == subject {
                    // The service rejects a self-link; saying so here is friendlier
                    // and the service's check still stands as the guarantee.
                    self.status_msg =
                        Some("relationship: an issue cannot be related to itself".into());
                    return Ok(Action::None);
                }
                self.mode = if is_edit {
                    Mode::LinkEdit {
                        index,
                        buffer: String::new(),
                        step: LinkStep::Kind,
                        target: Some(target),
                        kind: None,
                    }
                } else {
                    Mode::LinkCreate {
                        buffer: String::new(),
                        step: LinkStep::Kind,
                        target: Some(target),
                    }
                };
                Ok(Action::None)
            }
            LinkStep::Kind => {
                // **Required** (C-001). An untypeable relationship must never be
                // creatable by omission, so there is no default kind and an empty
                // answer is a refusal carrying the CLI's own message — which names
                // the valid set rather than just failing.
                let kind = match crate::commands::link::parse_kind(&trimmed) {
                    Ok(kind) => kind,
                    Err(e) => {
                        self.status_msg = Some(e.to_string());
                        return Ok(Action::None);
                    }
                };
                if is_edit {
                    self.apply_relationship_edit(kind)
                } else {
                    self.apply_relationship_create(subject, kind)
                }
            }
        }
    }

    /// `tix link <subject> <target> --type <kind>`, through the service.
    ///
    /// The **shared** message (`link::link_message`), so the TUI reports the same
    /// sentence as the CLI and MCP for the same edge.
    fn apply_relationship_create(
        &mut self,
        subject: u32,
        kind: crate::relationships::RelationKind,
    ) -> Result<Action> {
        let Some(target) = (match &self.mode {
            Mode::LinkCreate { target, .. } => *target,
            _ => None,
        }) else {
            // Unreachable: `Kind` is only entered from a resolved `Target` step. Left
            // as a refusal rather than an `expect` so a request handler never panics.
            self.status_msg = Some("relationship: no target resolved".into());
            self.mode = Mode::Detail;
            return Ok(Action::None);
        };
        // `Store::link` takes the same **selector strings** the CLI takes, so the
        // numbers resolved in the prompt go through the one resolver rather than a
        // second path that happens to agree today.
        match self
            .store
            .link(&subject.to_string(), &target.to_string(), kind)
        {
            Ok(outcome) => {
                self.status_msg = Some(crate::commands::link::link_message(&outcome));
                self.mode = Mode::Detail;
                self.refresh_detail()?;
            }
            Err(e) => {
                self.status_msg = Some(e.to_string());
                self.mode = Mode::Detail;
            }
        }
        Ok(Action::None)
    }

    /// `tix link edit <id> --to <target> --type <kind>`, through the service.
    ///
    /// Reached by the **stable id**, not by an endpoint pair: `2 related 1` and
    /// `1 blocks 2` can share a pair, so an endpoint-addressed edit would be
    /// ambiguous. The id survives a re-kind, which is the whole reason an edit
    /// exists rather than a remove-then-create pair.
    fn apply_relationship_edit(
        &mut self,
        kind: crate::relationships::RelationKind,
    ) -> Result<Action> {
        // The index is read from the mode rather than passed in, so there is one
        // source for "which edge" instead of a parameter and a field that can
        // disagree. (It did disagree in the first draft: the parameter was carried
        // and never used, and the field was read instead.)
        let (id, to) = match &self.mode {
            Mode::LinkEdit { index, target, .. } => (
                self.detail
                    .as_ref()
                    .and_then(|d| d.relationships.get(*index))
                    .map(|r| r.id.clone()),
                *target,
            ),
            _ => (None, None),
        };
        let Some(id) = id else {
            self.status_msg = Some("relationship: nothing selected to edit".into());
            self.mode = Mode::Detail;
            return Ok(Action::None);
        };
        match self.store.edit_relation(&id, to, Some(kind)) {
            Ok(outcome) => {
                self.status_msg = Some(crate::commands::link::edit_message(&outcome));
                self.mode = Mode::Detail;
                self.refresh_detail()?;
            }
            Err(e) => {
                self.status_msg = Some(e.to_string());
                self.mode = Mode::Detail;
            }
        }
        Ok(Action::None)
    }

    fn handle_remove_relationship_key(&mut self, key: KeyEvent) -> Result<Action> {
        match key.code {
            KeyCode::Char('y') | KeyCode::Char('Y') => {
                let index = match &self.mode {
                    Mode::ConfirmRemoveRelationship { index } => *index,
                    _ => return Ok(Action::None),
                };
                let id = match self
                    .detail
                    .as_ref()
                    .and_then(|d| d.relationships.get(index))
                {
                    Some(rel) => rel.id.clone(),
                    None => {
                        self.mode = Mode::Detail;
                        return Ok(Action::None);
                    }
                };
                match self.store.remove_relation(&id) {
                    Ok(outcome) => {
                        // **The shared wording** — `link::remove_message` — so the TUI
                        // and the CLI cannot drift on what a removal reports.
                        self.status_msg = Some(crate::commands::link::remove_message(&outcome));
                        self.mode = Mode::Detail;
                        self.refresh_detail()?;
                    }
                    Err(e) => {
                        self.status_msg = Some(e.to_string());
                        self.mode = Mode::Detail;
                    }
                }
                Ok(Action::None)
            }
            _ => {
                self.mode = Mode::Detail;
                self.status_msg = Some("relationship: removal cancelled".to_string());
                Ok(Action::None)
            }
        }
    }

    fn handle_asset_key(&mut self, key: KeyEvent) -> Result<Action> {
        match key.code {
            KeyCode::Esc => {
                self.mode = Mode::Detail;
                Ok(Action::None)
            }
            KeyCode::Enter => self.submit_asset(),
            KeyCode::Char(c) => {
                if let Mode::Asset { ref mut buffer } = self.mode {
                    buffer.push(c);
                }
                Ok(Action::None)
            }
            KeyCode::Backspace => {
                if let Mode::Asset { ref mut buffer } = self.mode {
                    buffer.pop();
                }
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    fn submit_asset(&mut self) -> Result<Action> {
        let buffer = match &self.mode {
            Mode::Asset { buffer } => buffer.clone(),
            _ => return Ok(Action::None),
        };
        let path = std::path::PathBuf::from(buffer.trim());
        let filename = match self.detail.as_ref() {
            Some(d) => d.issue.filename.clone(),
            None => {
                self.mode = Mode::Detail;
                return Ok(Action::None);
            }
        };
        match self.store.add_asset(&filename, &path) {
            Ok(added) => {
                if let Ok(issue) = self.store.get(IssueSelector::Filename(filename))
                    && let Some(ref mut d) = self.detail
                {
                    d.issue = issue;
                    d.scroll_offset = 0;
                }
                self.status_msg = Some(format!("Asset added: {}", added.link));
                self.refresh_corpus()?;
                self.mode = Mode::Detail;
                Ok(Action::None)
            }
            Err(e) => {
                self.status_msg = Some(format!("asset: {e}"));
                Ok(Action::None)
            }
        }
    }

    /// Toggle column visibility on the active column (FR-005/FR-006/NFR-004/
    /// SC-003). Updates the in-memory config and persists atomically.
    fn toggle_column_visibility(&mut self) {
        let col_name = self.board.active_column_name().to_string();
        let config_name = self.tabs.names[self.active_config].clone();
        let board_config = self
            .store
            .config
            .kanban
            .configurations
            .get_mut(&config_name);
        let board_config = match board_config {
            Some(bc) => bc,
            None => {
                self.status_msg = Some("toggle: config not found".into());
                return;
            }
        };
        let now_hidden = if let Some(pos) = board_config
            .hidden_columns
            .iter()
            .position(|h| h == &col_name)
        {
            board_config.hidden_columns.remove(pos);
            false
        } else {
            board_config.hidden_columns.push(col_name.clone());
            true
        };
        match self.store.config_path() {
            Ok(path) => {
                if let Err(e) = self.store.config.save(&path) {
                    self.status_msg = Some(format!("toggle save: {e}"));
                    return;
                }
            }
            Err(e) => {
                self.status_msg = Some(format!("toggle path: {e}"));
                return;
            }
        }
        self.rebuild_board();
        // Keep the cursor logically on the toggled column so a second `c`
        // press re-shows it: visible index when shown, hidden-region index
        // while hidden. Navigation keys still skip hidden columns (T014).
        let visible = self.board.columns.len();
        self.board.active_col = if now_hidden {
            visible
                + self
                    .board
                    .hidden
                    .iter()
                    .position(|c| c.name == col_name)
                    .unwrap_or_default()
        } else {
            self.board
                .columns
                .iter()
                .position(|c| c.name == col_name)
                .unwrap_or_default()
        };
        self.board.clamp_selection();
        self.status_msg = Some(format!("Toggled '{col_name}' visibility"));
    }

    /// Switch the active board configuration (Tab/BackTab). Rebuilds the
    /// board through the same path as `rebuild_board` so filters re-apply to
    /// the new config's visible columns, resetting `active_col` to the first
    /// visible column while keeping the selected card if it is still visible.
    /// Switch to the named board at tab index `i` — the exact Tab/BackTab
    /// path (set `selected`, then `active_config`, then rebuild via
    /// [`App::switch_config`]). Used by the mouse-hit `Action::SwitchBoard`
    /// and the run loop; tabs need a single shared transition.
    fn switch_board(&mut self, index: usize) {
        if index < self.tabs.len() {
            self.tabs.selected = index;
            self.tabs.hovered = None;
            self.active_config = index;
            self.switch_config();
        }
    }

    fn switch_config(&mut self) {
        let selected_filename = self.board.get_selected_card().map(|c| c.filename.clone());
        self.rebuild_board();
        self.board.active_col = 0;
        if let Some(filename) = selected_filename
            && self
                .board
                .column_cards(0)
                .iter()
                .any(|c| c.filename == filename)
        {
            self.board.selected = self
                .board
                .column_cards(0)
                .iter()
                .position(|c| c.filename == filename)
                .unwrap_or(0);
        } else {
            self.board.selected = 0;
        }
        self.board.clamp_selection();
        self.status_msg = Some("Switched board".to_string());
    }

    /// Activate a rail **branch**: switch the shell to the branch's target,
    /// resolved by the same paths the mode's own controls use.
    ///
    /// One method per [`Action`] arm, so a branch click and a branch-only
    /// keyboard activation (there is none today; branches are pointer-only per
    /// the open-question-3 decision) share a single transition.
    pub fn activate_branch(&mut self, action: &Action) -> Result<Action> {
        match action {
            Action::SelectBoard(name) => self.select_board_branch(name),
            Action::SelectCycle(name) => self.select_cycle_branch(name),
            Action::SelectMilestone(name) => self.select_milestone_branch(name),
            Action::NewFromTemplate(name) => self.new_from_template(name),
            _ => Ok(Action::None),
        }
    }

    /// Switch the active board to the named configuration and show the Board
    /// mode (open question 2: the branch switches the mode too, so the result of
    /// the switch is what the user sees rather than a board changing off-screen).
    fn select_board_branch(&mut self, name: &str) -> Result<Action> {
        let index = self
            .store
            .config
            .configs()
            .position(|(candidate, _)| candidate == name);
        let Some(index) = index else {
            self.status_msg = Some(format!("Board '{name}' not found"));
            return Ok(Action::None);
        };
        self.switch_top_mode(TopMode::Board)?;
        self.switch_board(index);
        Ok(Action::None)
    }

    /// Enter the Cycle mode with its cursor on the named cycle.
    ///
    /// The index is a position in the mode's **rendered** flat order, the same
    /// space [`crate::ui::cycle::flat_entries`] and every other cursor write
    /// use; a position in the config's insertion order would land on a
    /// different cycle whenever the two disagree, which is most of the time.
    fn select_cycle_branch(&mut self, name: &str) -> Result<Action> {
        self.switch_top_mode(TopMode::Cycle)?;
        let groups = self.cycle_groups();
        let index = crate::ui::cycle::flat_entries(&groups)
            .iter()
            .position(|entry| entry.name == name);
        if let (Some(index), Some(state)) = (index, self.cycle_state.as_mut()) {
            state.selected = index;
        }
        Ok(Action::None)
    }

    /// Enter the Milestones mode with its cursor on the named milestone.
    fn select_milestone_branch(&mut self, name: &str) -> Result<Action> {
        self.switch_top_mode(TopMode::Milestones)?;
        let (_cycles, milestones) = self.planning_rows();
        let index = milestones
            .iter()
            .position(|row| row.name == name)
            .unwrap_or(0);
        if let Some(modal) = self.planning.as_mut() {
            modal.segment = PlanningSegment::Milestones;
            modal.selected = index;
            modal.prompt = None;
        }
        Ok(Action::None)
    }

    /// Open the New Issue form seeded from the named `[templates.<name>]`
    /// record, entering the New Issue mode first (the form is that mode's
    /// content).
    fn new_from_template(&mut self, name: &str) -> Result<Action> {
        self.switch_top_mode(TopMode::NewIssue)?;
        self.select_template(name);
        Ok(Action::None)
    }

    /// Build the archived-inclusive search corpus on first use (tix #1498).
    ///
    /// A build error leaves `search_corpus` as `None`; the callers fall back to
    /// the active corpus, so a transient read failure degrades the search to
    /// "archived issues are excluded" instead of "no search at all".
    fn ensure_search_corpus(&mut self) {
        if self.search_corpus.is_none() {
            if let Ok(c) = Corpus::build_with(&self.store, true) {
                self.search_corpus = Some(c);
            }
        }
    }

    /// Re-read the store and rebuild the board while preserving the current
    /// filter, active column, and selection.
    fn rebuild_board(&mut self) {
        let active_col = self.board.active_col;
        let selected = self.board.selected;
        let board_config = self.active_board_config().clone();
        let active_filter = self.active_structured_filter().clone();
        let q = self.filter.clone().unwrap_or_default();
        if !q.is_empty() || active_filter.has_active_criteria() {
            if !q.is_empty() {
                self.ensure_search_corpus();
            }
            let corpus = if q.is_empty() {
                &self.corpus
            } else {
                self.search_corpus.as_ref().unwrap_or(&self.corpus)
            };
            self.board = BoardState::build_filtered_with(
                &board_config,
                &self.store.config,
                corpus,
                &q,
                &active_filter,
                &self.workflow_resolution(),
                self.show_children,
            );
        } else {
            // The corpus is the single in-memory source (issue #10 follow-up):
            // every write through the store refreshes it, so the unfiltered
            // board can be rebuilt from memory instead of re-reading the tree.
            let resolution = self.workflow_resolution();
            self.board = BoardState::build_from_issues(
                &self.corpus.issues,
                &board_config,
                &self.store.config,
                &resolution,
                self.show_children,
            );
        }
        self.board.active_col = active_col;
        self.board.selected = selected;
        self.board.clamp_selection();
    }

    fn select_card_by_filename(&mut self, filename: &str) {
        let mut columns: Vec<&[crate::ui::board::Card]> = self
            .board
            .columns
            .iter()
            .map(|c| c.cards.as_slice())
            .collect();
        if self.board.show_mismatch {
            columns.push(self.board.mismatch.cards.as_slice());
        }
        if let Some((col_idx, card_idx)) =
            columns.iter().enumerate().find_map(|(col_idx, cards)| {
                cards
                    .iter()
                    .position(|card| card.filename == filename)
                    .map(|card_idx| (col_idx, card_idx))
            })
        {
            self.board.active_col = col_idx;
            self.board.selected = card_idx;
        }
    }

    /// Live filter: update the applied `filter` and re-render the board from
    /// the corpus. An empty buffer clears the query (FR-013: an active
    /// structured filter alone still filters).
    fn apply_filter(&mut self, buffer: &str) {
        if buffer.trim().is_empty() {
            self.filter = None;
        } else {
            self.filter = Some(buffer.trim().to_string());
        }
        let board_config = self.active_board_config().clone();
        let active_filter = self.active_structured_filter().clone();
        let q = self.filter.clone().unwrap_or_default();
        if !q.is_empty() || active_filter.has_active_criteria() {
            if !q.is_empty() {
                self.ensure_search_corpus();
            }
            let corpus = if q.is_empty() {
                &self.corpus
            } else {
                self.search_corpus.as_ref().unwrap_or(&self.corpus)
            };
            self.board = BoardState::build_filtered_with(
                &board_config,
                &self.store.config,
                corpus,
                &q,
                &active_filter,
                &self.workflow_resolution(),
                self.show_children,
            );
            self.status_msg = if self.board.is_empty() {
                Some("No matches for current search".to_string())
            } else {
                None
            };
        } else {
            self.board =
                BoardState::build_with(&self.store, &board_config, false, self.show_children);
            self.status_msg = None;
        }
    }

    /// Re-read the corpus after comment/asset writes so the active filter
    /// stays fresh, then rebuilds the board.
    /// Re-read the open detail pane from the service after a write.
    ///
    /// **Everything** the pane shows is re-derived, not just the issue: the
    /// relationships come from `Store::relationships_for` and the chain and blocked
    /// note from a fresh graph. A pane that refreshed only `issue` would keep showing
    /// the edge list and blocked state from *before* the mutation, which is the
    /// failure that makes a TUI feel like it is lying to you.
    ///
    /// The relationship cursor is clamped rather than reset, so editing the third of
    /// five relationships leaves it on the third — which after a re-kind is the same
    /// edge, since the list is ordered by `(kind, target, from)` and a re-kind can
    /// move it. Clamping is the honest minimum: it never points past the end.
    fn refresh_detail(&mut self) -> Result<()> {
        let Some(detail) = self.detail.as_ref() else {
            return Ok(());
        };
        let number = detail.issue.number;
        let filename = detail.issue.filename.clone();
        let Some(mut next) = self.store.get(IssueSelector::Filename(filename)).ok() else {
            return Ok(());
        };
        let relationships = self.store.relationships_for(number)?;
        let (all, done_column) = self.store.graph_source()?;
        let graph = commands::graph_over(&all, &done_column);
        let cursor = detail.rel_cursor;
        let related_cursor = detail.related_cursor;
        if let Some(d) = self.detail.as_mut() {
            d.issue = std::mem::replace(&mut next, d.issue.clone());
            d.relationships = relationships;
            d.chain = graph.dependency_chain(number);
            d.blocked = commands::blocked_note(&graph.blocked_state(number));
            d.rel_cursor = cursor;
            d.clamp_rel_cursor();
            // #1513: the `related_issues` field may have been edited, so the
            // classified list is re-derived with everything else. The cursor is
            // clamped rather than reset, the same rule the relationship cursor
            // follows.
            d.related = crate::related::classify_all(&d.issue.related_issues);
            d.related_cursor = related_cursor;
            d.clamp_related_cursor();
        }
        self.refresh_corpus()
    }

    fn refresh_corpus(&mut self) -> Result<()> {
        let c = Corpus::build_with(&self.store, self.show_archived)?;
        self.corpus = c;
        // The archived-inclusive search snapshot is stale now; the next search
        // rebuilds it from disk (tix #1498).
        self.search_corpus = None;
        self.rebuild_board();
        Ok(())
    }

    /// Apply an external change to the in-memory corpus and rebuild the board,
    /// **without re-reading the issues tree** (issue #10 follow-up).
    ///
    /// `delta` comes from [`crate::watcher::FsWatcher::poll`] with paths
    /// relative to the issues directory; [`Corpus::apply`] re-reads only those
    /// files and drops the removed ones. A read error (e.g. a partially written
    /// file) leaves the current corpus and board in place.
    ///
    /// The delta is narrowed to the current view first: with the archived
    /// toggle off, an archived path is dropped rather than read, so an issue
    /// archived outside `tix` leaves the active board instead of appearing on
    /// it (the archived-inclusive [`App::ensure_search_corpus`] snapshot is
    /// dropped and rebuilt from disk on the next search, as after any refresh).
    pub fn refresh_from_disk(&mut self, delta: &FsDelta) -> Result<()> {
        let delta = self.delta_for_view(delta);
        self.corpus.apply(&self.store, &delta)?;
        self.search_corpus = None;
        self.rebuild_board();
        Ok(())
    }

    /// Narrow `delta` to the paths the current view indexes (issue #10
    /// follow-up).
    ///
    /// With the archived toggle off, a dot-prefixed file is not part of the
    /// corpus, so a change to one is not a change to this view. With it on,
    /// every path passes through and [`Corpus::apply`] judges `.md`/segment
    /// rules.
    fn delta_for_view(&self, delta: &FsDelta) -> FsDelta {
        if self.show_archived {
            return delta.clone();
        }
        let visible = |path: &PathBuf| {
            !path
                .file_name()
                .and_then(|name| name.to_str())
                .is_some_and(|name| name.starts_with('.'))
        };
        FsDelta {
            changed: delta
                .changed
                .iter()
                .filter(|p| visible(p))
                .cloned()
                .collect(),
            removed: delta
                .removed
                .iter()
                .filter(|p| visible(p))
                .cloned()
                .collect(),
        }
    }

    /// Launch the editor on a temp copy of `filename` and settle the result
    /// (tix #1510).
    ///
    /// The issue file's raw bytes are snapshotted **before** the child runs, and
    /// the edited temp copy is compared against that snapshot **after** it exits
    /// by [`App::after_editor`] — the one place the conflict decision is made.
    /// Splitting the round trip this way is what lets the live
    /// `Action::OpenEditor` shell-out and the programmatic entry point be the same
    /// code path: the only difference between them is who suspends the terminal
    /// around the child.
    pub fn open_editor_round_trip(&mut self, filename: &str) -> Result<()> {
        let name = editor::resolve_editor(self.store.config.editor.as_deref())?;
        let original = self
            .store
            .get(IssueSelector::Filename(filename.to_string()))?;
        let disk_path = self.store.issues_dir.join(&original.filename);
        let snapshot = std::fs::read(&disk_path).map_err(TixError::Io)?;
        let temp = std::env::temp_dir().join(format!(
            "tix-edit-{}-{}.md",
            std::process::id(),
            original.number
        ));
        std::fs::write(&temp, original.to_file_contents()).map_err(TixError::Io)?;
        self.pending_edit = Some(PendingEdit {
            filename: original.filename.clone(),
            temp: temp.clone(),
            snapshot,
        });
        if let Err(e) = editor::run_editor(&name, &temp, &self.store.config) {
            // The child failed to launch or exited non-zero, so nothing was
            // written — and the copy is **kept**. Deleting it here (as the old
            // flow did) is the automatic discard tix #1506 exists to remove; the
            // temp copy is the only copy of anything the editor might have
            // managed to save before it failed.
            self.pending_edit = None;
            self.status_msg = Some(format!(
                "editor: {e}; your copy is kept at {}",
                temp.display()
            ));
            return Ok(());
        }
        self.after_editor(&original.filename);
        Ok(())
    }

    /// Finish an editor round trip: commit the edit, or refuse to because the file
    /// changed underneath it (tix #1510).
    ///
    /// Both entry points arrive here — [`App::open_editor_round_trip`] for the live
    /// shell-out, and direct callers that write the file themselves before calling
    /// this. A round trip that recorded a pending edit is compared against its
    /// pre-edit snapshot and may enter [`Mode::EditConflict`] **writing nothing**;
    /// one with no pending edit has no pre-edit bytes to compare against, so it
    /// keeps the pre-#1510 behaviour of persisting the file it is asked to read.
    pub fn after_editor(&mut self, filename: &str) {
        // The lint below reports the project's current rules, and the user may
        // have declared a custom attribute in `tix.toml` since this session
        // started (tix #1506): adopt the file before judging the edit.
        self.reload_config_if_changed();
        if let Some(pending) = self
            .pending_edit
            .take_if(|pending| pending.filename == filename)
        {
            self.settle_pending_edit(pending);
            return;
        }
        match self
            .store
            .get(IssueSelector::Filename(filename.to_string()))
        {
            // No pending edit means this caller wrote the file itself, so there
            // is no retained temp copy: the issue file is the working copy.
            Ok(issue) => self.commit_edited_issue(filename, issue, "Edited", None),
            Err(e) => {
                self.status_msg = Some(format!("editor: {e}"));
            }
        }
    }

    /// Detect a concurrent write and decide what a finished round trip does
    /// (tix #1510).
    ///
    /// The comparison is on the file's **raw bytes**: anything that rewrote the
    /// file — an agent editing through MCP, another session, a watcher's repair —
    /// leaves different bytes, and at this point nothing has been written yet.
    /// Identical bytes mean the file is the one the editor was handed, so the edit
    /// is committed exactly as it was before #1510 existed.
    fn settle_pending_edit(&mut self, pending: PendingEdit) {
        let disk_path = self.store.issues_dir.join(&pending.filename);
        let edited = match std::fs::read_to_string(&pending.temp) {
            Ok(text) => text,
            Err(e) => {
                self.status_msg = Some(format!("editor: {e}"));
                return;
            }
        };
        // A read failure counts as a change: the bytes cannot be shown to be the
        // ones the editor saw, and assuming "unchanged" would write over a file
        // this process cannot even read.
        let unchanged = std::fs::read(&disk_path)
            .map(|bytes| bytes == pending.snapshot)
            .unwrap_or(false);
        if !unchanged {
            // Nothing is written and the temp copy is deliberately kept: it *is*
            // the editor's version, and the prompt may still write it or reopen it.
            self.mode = Mode::EditConflict {
                filename: pending.filename,
                temp: pending.temp,
                disk_path,
            };
            self.status_msg =
                Some("the issue changed on disk while you were editing it".to_string());
            return;
        }
        let issue = match Issue::parse(&edited) {
            Ok(issue) => issue,
            Err(e) => {
                // The reported bug (tix #1506). The old flow returned the generic
                // `file not valid after edit` from `run_editor` and then deleted
                // the temp copy, destroying the user's work. Now the real
                // diagnostic is classified, nothing is written, the round trip
                // stays in flight, and the retained copy is kept for the repair
                // prompt to reopen.
                let filename = pending.filename.clone();
                let previous = self.previous_issue(&filename);
                let problems =
                    edit_problems::for_parse_error(&error_message(&e), &edited, previous.as_ref());
                let temp = pending.temp.clone();
                self.pending_edit = Some(pending);
                self.enter_repair(&filename, Some(temp), false, problems);
                return;
            }
        };
        let temp = pending.temp.clone();
        self.commit_edited_issue(&pending.filename, issue, "Edited", Some(temp));
    }

    /// Persist an issue an editor round trip produced and settle it (#1506/#1510).
    ///
    /// The one write both entry points and the conflict prompt's override share,
    /// so an override cannot land somewhere an ordinary save would not: it refuses
    /// a titleless issue (no slug, no stable filename), reassigns the segment when
    /// the edit changed the assignee (FR-031), updates the detail pane when it is
    /// showing this issue, rebuilds the board, and reports through
    /// [`App::report_or_repair`].
    ///
    /// `temp` is the retained edited copy when there is one. It is **not** removed
    /// here: `report_or_repair` keeps it if the written file still has problems,
    /// so the repair prompt has something to reopen, and removes it only once the
    /// edit is clean.
    fn commit_edited_issue(
        &mut self,
        original_filename: &str,
        issue: Issue,
        message: &str,
        temp: Option<PathBuf>,
    ) {
        if issue.title.trim().is_empty() {
            let previous = self.previous_issue(original_filename);
            // A titleless issue has no slug and no stable filename. Nothing is
            // written; the prompt offers the pre-edit title back.
            let problems = vec![edit_problems::missing_title(previous.as_ref())];
            self.enter_repair(original_filename, temp, false, problems);
            return;
        }
        // Back up the version this write is about to replace, so even a clean
        // save leaves the previous content recoverable and names where.
        let backup = self.backup_previous_content(original_filename);
        match self.persist_issue(original_filename, issue) {
            Ok(location) => self.report_or_repair(&location, temp, message, backup),
            Err(e) => {
                self.status_msg = Some(format!("editor: {e}"));
            }
        }
    }

    /// Write `issue` over `original_filename`, reassigning the segment when the
    /// edit changed the assignee, and refresh what the shell shows.
    ///
    /// Returns the relative path actually written (the assignee segment may have
    /// changed, FR-031).
    fn persist_issue(&mut self, original_filename: &str, mut issue: Issue) -> Result<String> {
        issue.bump_updated();
        // FR-031: when the editor assigned the issue, physically move it into the
        // new assignee segment before writing content. An unassigned edit keeps the
        // current file location.
        let mut location = match &issue.assignee {
            Some(a) => self
                .store
                .reassign(original_filename, Some(a))?
                .to_string_lossy()
                .to_string(),
            None => original_filename.to_string(),
        };
        location = self.store.update(&location, &issue)?;
        issue.filename = location.clone();
        if let Some(d) = &mut self.detail
            && (d.issue.filename == original_filename || d.issue.filename == location)
        {
            d.issue = issue;
            d.scroll_offset = 0;
        }
        let _ = self.refresh_corpus();
        Ok(location)
    }

    /// Lint the written file and either report `message` or enter the repair
    /// prompt (#1506).
    ///
    /// The edit is already on disk here, so a finding is a *report*: the custom
    /// keys the edit added are preserved either way ([`App::report_or_repair`]
    /// never deletes the file). `backup` is the pre-write copy, named in the
    /// status so the previous version stays findable.
    fn report_or_repair(
        &mut self,
        filename: &str,
        temp: Option<PathBuf>,
        message: &str,
        backup: Option<PathBuf>,
    ) {
        match self.classify_file_problems(filename) {
            Ok(problems) if !problems.is_empty() => {
                // The edit is on disk now, so the round trip is over: only the
                // *unwritten* path keeps `pending_edit` in flight.
                self.pending_edit = None;
                self.enter_repair(filename, temp, true, problems);
            }
            Ok(_) => {
                if let Some(temp) = &temp {
                    let _ = std::fs::remove_file(temp);
                }
                // The round trip is resolved: `reedit_repair` arrives here with
                // the repair prompt still up, so the board is set explicitly
                // rather than assumed.
                self.mode = Mode::Board;
                self.pending_edit = None;
                self.status_msg = Some(names_backup(message, backup.as_ref()));
            }
            Err(e) => {
                if let Some(temp) = &temp {
                    let _ = std::fs::remove_file(temp);
                }
                self.mode = Mode::Board;
                self.pending_edit = None;
                self.status_msg = Some(format!("editor: {e}"));
            }
        }
    }

    /// Every problem `tix lint` reports for `filename`, classified.
    fn classify_file_problems(&self, filename: &str) -> Result<Vec<EditProblem>> {
        let findings =
            crate::commands::lint::collect_file(&self.store.config, &self.store, filename)?;
        if findings.is_empty() {
            return Ok(Vec::new());
        }
        let previous = self.previous_issue(filename);
        Ok(edit_problems::for_lint_findings(
            &findings,
            previous.as_ref(),
        ))
    }

    /// The issue as it is on disk, used for the pre-edit title and as the
    /// fallback previous version. `None` when it cannot be read or parsed.
    fn previous_issue(&self, filename: &str) -> Option<Issue> {
        let path = self.store.issues_dir.join(filename);
        let contents = std::fs::read_to_string(path).ok()?;
        Issue::parse(&contents).ok()
    }

    /// Write a recoverable copy of `filename`'s current content beside it.
    ///
    /// Every write that replaces the on-disk issue from the editor, repair, or
    /// conflict path goes through this first, so a change tix made is always
    /// recoverable. The name ends in `.tixbak`, which the corpus walker ignores
    /// (it only reads `.md`), and it is returned so the status line can name it.
    fn backup_previous_content(&self, filename: &str) -> Option<PathBuf> {
        let path = self.store.issues_dir.join(filename);
        let bytes = std::fs::read(&path).ok()?;
        let name = std::path::Path::new(filename)
            .file_name()
            .map(|n| n.to_string_lossy().to_string())?;
        let backup = path.with_file_name(format!("{name}.tixbak"));
        std::fs::write(&backup, bytes).ok()?;
        Some(backup)
    }

    /// Enter the repair prompt with `problems` (#1506).
    ///
    /// Does nothing when there is nothing to report — every caller guards on a
    /// non-empty list, but an empty prompt would be worse than no prompt.
    fn enter_repair(
        &mut self,
        filename: &str,
        temp: Option<PathBuf>,
        written: bool,
        problems: Vec<EditProblem>,
    ) {
        let Some(first) = problems.first() else {
            return;
        };
        let key = problems.iter().find_map(|problem| match problem.fix() {
            Some(EditFix::DeclareCustomAttribute { key }) => Some(key.clone()),
            _ => None,
        });
        let message = first.summary();
        self.mode = Mode::EditRepair {
            filename: filename.to_string(),
            message: message.clone(),
            key,
            problems,
            temp,
            written,
            discard_armed: false,
        };
        self.status_msg = Some(message);
    }

    /// Override the newer on-disk version with the editor's version (#1510).
    ///
    /// The **only** conflict outcome that writes, and it writes the temp copy's
    /// content rather than the on-disk one: the prompt has already said which file
    /// changed and the user chose their own edit. A temp copy that cannot be read
    /// or parsed leaves the prompt in place instead of closing it, so the user
    /// still has the abandon and compare keys.
    fn override_conflicting_edit(&mut self, filename: &str, temp: &std::path::Path) {
        let edited = match std::fs::read_to_string(temp) {
            Ok(edited) => edited,
            Err(e) => {
                self.status_msg = Some(format!("editor: {e}"));
                return;
            }
        };
        let issue = match Issue::parse(&edited) {
            Ok(issue) => issue,
            Err(e) => {
                // The temp copy cannot be parsed, so nothing can be written over
                // the newer file. The prompt stays up with both versions intact.
                self.status_msg = Some(format!("editor: {e}"));
                return;
            }
        };
        self.mode = Mode::Board;
        // The temp copy is handed to the commit, which keeps it if the written
        // file still has problems and removes it once the edit is clean.
        self.commit_edited_issue(
            filename,
            issue,
            "Overrode the version that changed on disk with your edit",
            Some(temp.to_path_buf()),
        );
    }

    /// Abandon the editor's version and keep the newer on-disk one (#1510).
    ///
    /// The safe default, and the reason `Esc` is bound to it: the temp copy is
    /// removed and nothing is written, so a write that arrived while the editor was
    /// open is never clobbered by a keypress the user did not mean as a decision.
    fn abandon_conflicting_edit(&mut self, temp: &std::path::Path) {
        let _ = std::fs::remove_file(temp);
        self.mode = Mode::Board;
        self.status_msg =
            Some("kept the version that changed on disk; your edit was discarded".to_string());
    }

    /// Re-open the editor on the conflict prompt's temp copy so the user can
    /// compare the two versions (#1510), then land back on the prompt.
    ///
    /// The disk file's bytes are read **before** and **after** the second editor
    /// run, so a change made while the user compares is detected too — that is the
    /// "re-reading the disk state" the prompt promises. It needs the child and the
    /// child needs the terminal, which is why the keypress returns
    /// [`Action::CompareEdit`] instead of doing this where the key is handled.
    /// Nothing is written either way: the editor opens the temp copy, never the
    /// issue file.
    pub fn compare_conflicting_edit(&mut self) -> Result<()> {
        let (filename, temp, disk_path) = match &self.mode {
            Mode::EditConflict {
                filename,
                temp,
                disk_path,
            } => (filename.clone(), temp.clone(), disk_path.clone()),
            _ => return Ok(()),
        };
        let name = editor::resolve_editor(self.store.config.editor.as_deref())?;
        let before = std::fs::read(&disk_path).map_err(TixError::Io)?;
        editor::run_editor(&name, &temp, &self.store.config)?;
        let after = std::fs::read(&disk_path).map_err(TixError::Io)?;
        // Back to the same prompt: a second look is not a decision, and the three
        // choices have to still be there once the user has looked.
        self.mode = Mode::EditConflict {
            filename,
            temp,
            disk_path,
        };
        self.status_msg = Some(if after == before {
            "the issue changed on disk while you were editing it".to_string()
        } else {
            "the issue changed on disk again while you were comparing it".to_string()
        });
        Ok(())
    }

    /// The edit-conflict prompt's keys (tix #1510).
    ///
    /// The arms read the keys' **canonical** events, like every other modal: the
    /// prompt binds `o`/`y` to `confirm` (canonical `y`), `a`/`Esc` to `ignore`
    /// (canonical `Enter`), and `c`/`r` to `reedit` (canonical `r`), so what arrives
    /// here is `y`, `Enter` and `r` whatever chords the keymap names. `Esc`
    /// therefore abandons exactly as the prompt promises, and no key that is not one
    /// of the three does anything.
    fn handle_edit_conflict_key(&mut self, key: KeyEvent) -> Result<Action> {
        let (filename, temp) = match &self.mode {
            Mode::EditConflict { filename, temp, .. } => (filename.clone(), temp.clone()),
            _ => return Ok(Action::None),
        };
        match key.code {
            KeyCode::Char('y') => {
                self.override_conflicting_edit(&filename, &temp);
                Ok(Action::None)
            }
            // The child needs the terminal, so the event loop runs this and not
            // the handler (see `compare_conflicting_edit`).
            KeyCode::Char('r') => Ok(Action::CompareEdit),
            KeyCode::Enter | KeyCode::Esc => {
                self.abandon_conflicting_edit(&temp);
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Declare `key` in `tix.toml`'s `[custom_attributes]` (#1506) — the one fix
    /// the repair prompt applies by writing config rather than the issue, and the
    /// reason the prompt is not just a nag.
    ///
    /// The entry is appended and `tix.toml` is written through
    /// [`Config::save`](crate::config::Config::save), the same atomic temp-file
    /// path the Config mode uses. An entry that is already declared — compared
    /// case-insensitively, the rule [`Config::custom_attributes`] itself applies —
    /// is not appended again: a second `a` on an open warning is an idempotent
    /// re-run, not a duplicate row.
    ///
    /// `key == None` is a finding that is not an undeclared key, so `a` has
    /// nothing to declare and says so rather than writing an entry that would
    /// silence nothing.
    fn declare_custom_attribute(&mut self, key: Option<&str>) {
        let Some(key) = key.map(str::trim).filter(|k| !k.is_empty()) else {
            self.status_msg = Some(
                "nothing to declare: this finding is not an undeclared frontmatter key".into(),
            );
            return;
        };
        let declared = self.store.config.custom_attributes();
        let already_declared = declared.iter().any(|d| d == &key.to_ascii_lowercase());
        if !already_declared {
            self.store
                .config
                .custom_attributes
                .keys
                .push(key.to_string());
        }
        match self
            .store
            .config_path()
            .and_then(|path| self.store.config.save(&path))
        {
            Ok(()) => {
                self.status_msg = Some(format!(
                    "declared `{key}` in [custom_attributes] in tix.toml"
                ));
            }
            Err(e) => {
                // The warning closed either way, so the status line is the only
                // place this can be reported. Roll the in-memory entry back, so
                // it never claims a declaration that is not on disk.
                if !already_declared {
                    self.store.config.custom_attributes.keys.pop();
                }
                self.status_msg = Some(format!("declare `{key}`: {e}"));
            }
        }
    }

    /// The repair prompt's keys (tix #1506).
    ///
    /// The arms read the keys' **canonical** events, like every other modal:
    /// `handle_key` rewrites a bound key to its action's canonical event before
    /// this runs, so `a`/`y` arrive as `y` (`confirm`), `d` as `d`
    /// (`declare_key`), `r` as `r` (`reedit`), `i`/`Esc` as `Enter` (`ignore`),
    /// and `x` as `x` (`discard`).
    ///
    /// `reedit` hands back [`Action::ReeditRepair`] because the child needs the
    /// terminal; everything else is decided here. **No key discards silently**:
    /// `Esc` acknowledges and keeps the copy, and only a second `x` removes it.
    fn handle_edit_repair_key(&mut self, key: KeyEvent) -> Result<Action> {
        match key.code {
            KeyCode::Char('y') => {
                self.apply_repair_fix();
                Ok(Action::None)
            }
            KeyCode::Char('d') => {
                self.declare_repair_key();
                Ok(Action::None)
            }
            KeyCode::Char('r') => Ok(Action::ReeditRepair),
            KeyCode::Char('x') => {
                self.arm_or_discard_repair();
                Ok(Action::None)
            }
            KeyCode::Enter | KeyCode::Esc => {
                self.acknowledge_repair();
                Ok(Action::None)
            }
            _ => Ok(Action::None),
        }
    }

    /// Apply the first fix the prompt proposes (#1506).
    ///
    /// An undeclared key's fix *is* the declaration, so `confirm` keeps #1506's
    /// behaviour there. The fix operates on the retained copy (or the issue file
    /// when the edit is already written) and the result is re-parsed: a fix that
    /// does not make the file valid leaves it untouched and re-reports, and one
    /// that does is written with the previous version backed up.
    fn apply_repair_fix(&mut self) {
        let (filename, temp, problems) = match &self.mode {
            Mode::EditRepair {
                filename,
                temp,
                problems,
                ..
            } => (filename.clone(), temp.clone(), problems.clone()),
            _ => return,
        };
        let Some(problem) = problems.iter().find(|problem| problem.fix().is_some()) else {
            // #1506: `confirm` on a prompt whose problem is the undeclared key is
            // the declaration itself, whether or not the key was carried as a fix.
            if let Mode::EditRepair { key: Some(key), .. } = &self.mode {
                let key = key.clone();
                self.declare_custom_attribute(Some(&key));
                self.mode = Mode::Board;
                self.pending_edit = None;
                return;
            }
            // A finding that is not an undeclared key has nothing to declare, and
            // the wording is the one the old warning used. `confirm` closes the
            // prompt, exactly as the old warning did (the reported problem stays
            // on disk and in `tix lint`; there is nothing to decide here).
            self.status_msg = Some(
                "nothing to declare: this finding is not an undeclared frontmatter key".into(),
            );
            self.mode = Mode::Board;
            self.pending_edit = None;
            return;
        };
        let Some(fix) = problem.fix().cloned() else {
            return;
        };
        if let EditFix::DeclareCustomAttribute { key } = &fix {
            self.declare_custom_attribute(Some(key));
            self.mode = Mode::Board;
            self.pending_edit = None;
            return;
        }
        let source = match &temp {
            Some(temp) => temp.clone(),
            None => self.store.issues_dir.join(&filename),
        };
        let contents = match std::fs::read_to_string(&source) {
            Ok(contents) => contents,
            Err(e) => {
                self.status_msg = Some(format!("editor: {e}"));
                return;
            }
        };
        let Some(fixed) = fix.apply(&contents) else {
            self.status_msg = Some(format!(
                "could not apply `{}`; the file is untouched",
                fix.label()
            ));
            return;
        };
        let label = fix.label();
        match Issue::parse(&fixed) {
            Ok(issue) => {
                let backup = self.backup_previous_content(&filename);
                match self.persist_issue(&filename, issue) {
                    Ok(location) => {
                        if let Some(temp) = &temp {
                            let _ = std::fs::remove_file(temp);
                        }
                        self.pending_edit = None;
                        self.mode = Mode::Board;
                        self.status_msg = Some(names_backup(
                            &format!("applied `{label}` to {location}"),
                            backup.as_ref(),
                        ));
                    }
                    Err(e) => self.status_msg = Some(format!("editor: {e}")),
                }
            }
            Err(e) => {
                // The fix did not make the file valid. Nothing was written — the
                // repaired text only ever existed as a local string — so the
                // retained copy is untouched and the remaining problems are what
                // the prompt now lists.
                let previous = self.previous_issue(&filename);
                let problems =
                    edit_problems::for_parse_error(&error_message(&e), &fixed, previous.as_ref());
                if let Mode::EditRepair {
                    problems: current, ..
                } = &mut self.mode
                {
                    *current = problems;
                }
                self.status_msg = Some(format!(
                    "the fix did not make the file valid: {e}; the file is untouched"
                ));
            }
        }
    }

    /// Declare the prompt's undeclared key (#1506), or say there is none.
    ///
    /// Closes to the board either way, as the old warning did: the declaration is
    /// what silences the finding, and the custom key is already on disk.
    fn declare_repair_key(&mut self) {
        let key = match &self.mode {
            Mode::EditRepair { key, .. } => key.clone(),
            _ => None,
        };
        self.declare_custom_attribute(key.as_deref());
        self.mode = Mode::Board;
        self.pending_edit = None;
    }

    /// Acknowledge the prompt and **keep** the retained copy (#1506).
    ///
    /// `Esc` lands here, which is why it can never destroy an edit: the worst a
    /// stray key does is leave the copy where the status line names it.
    fn acknowledge_repair(&mut self) {
        let temp = match &self.mode {
            Mode::EditRepair { temp, .. } => temp.clone(),
            _ => None,
        };
        self.mode = Mode::Board;
        self.pending_edit = None;
        self.status_msg = Some(match &temp {
            Some(temp) => format!("kept your edited copy at {}", temp.display()),
            None => "kept your edit".to_string(),
        });
    }

    /// Arm a discard, or perform it on the second press (#1506).
    ///
    /// Two presses because "I saw it" and "throw it away" are two decisions, and
    /// this is the **only** action in the whole flow that removes the retained
    /// copy.
    fn arm_or_discard_repair(&mut self) {
        if let Mode::EditRepair {
            discard_armed,
            temp,
            ..
        } = &mut self.mode
        {
            if !*discard_armed {
                *discard_armed = true;
                self.status_msg = Some(
                    "press the discard key again to remove the retained copy — this cannot be \
                     undone"
                        .to_string(),
                );
                return;
            }
            let temp = temp.clone();
            self.mode = Mode::Board;
            self.pending_edit = None;
            match temp {
                Some(temp) => {
                    let _ = std::fs::remove_file(&temp);
                    self.status_msg = Some(format!("discarded your edit ({})", temp.display()));
                }
                None => {
                    self.status_msg =
                        Some("nothing to discard: the edit is already on disk".to_string())
                }
            }
        }
    }

    /// Re-open the editor on the repair prompt's retained copy (#1506).
    ///
    /// Called from the event loop because the child needs the terminal, exactly
    /// as [`App::compare_conflicting_edit`] is. The edited copy is re-parsed when
    /// it comes back: a valid file is committed (with the previous version backed
    /// up), an invalid one re-enters the same prompt with fresh problems, and
    /// either way the copy survives.
    pub fn reedit_repair(&mut self) -> Result<()> {
        let (filename, temp) = match &self.mode {
            Mode::EditRepair { filename, temp, .. } => (filename.clone(), temp.clone()),
            _ => return Ok(()),
        };
        let name = editor::resolve_editor(self.store.config.editor.as_deref())?;
        // No retained copy means the edit is already on disk (the #1506
        // warn-after-write path): materialise one so the re-edit has a copy to
        // work on and the prompt keeps the guarantee that its copy only goes away
        // by discard.
        let temp = match temp {
            Some(temp) => temp,
            None => {
                let contents = std::fs::read_to_string(self.store.issues_dir.join(&filename))
                    .map_err(TixError::Io)?;
                let temp = std::env::temp_dir().join(format!(
                    "tix-edit-repair-{}-{}.md",
                    std::process::id(),
                    filename.replace('/', "-")
                ));
                std::fs::write(&temp, contents).map_err(TixError::Io)?;
                temp
            }
        };
        editor::run_editor(&name, &temp, &self.store.config)?;
        let edited = std::fs::read_to_string(&temp).map_err(TixError::Io)?;
        match Issue::parse(&edited) {
            Ok(issue) => {
                self.commit_edited_issue(&filename, issue, "Edited", Some(temp));
            }
            Err(e) => {
                let previous = self.previous_issue(&filename);
                let problems =
                    edit_problems::for_parse_error(&error_message(&e), &edited, previous.as_ref());
                let message = problems
                    .first()
                    .map(EditProblem::summary)
                    .unwrap_or_else(|| error_message(&e));
                if let Mode::EditRepair {
                    problems: current,
                    temp: kept,
                    written,
                    discard_armed,
                    ..
                } = &mut self.mode
                {
                    *current = problems;
                    *kept = Some(temp);
                    // The revised copy is not on disk, whatever the prompt said
                    // about the version that was.
                    *written = false;
                    *discard_armed = false;
                }
                self.status_msg = Some(message);
            }
        }
        Ok(())
    }

    fn handle_rollover_dialog_key(&mut self, key: KeyEvent) -> Result<Action> {
        let Some(dialog) = self.rollover_dialog.as_mut() else {
            self.mode = Mode::Board;
            return Ok(Action::None);
        };
        match dialog.handle_key(key.code) {
            DialogEvent::ConfirmDo => {
                crate::commands::rollover::run(&self.store.config, &self.store, None, true)?;
                self.refresh_corpus()?;
                self.status_msg = Some("Rollover applied".to_string());
                self.rollover_dialog = None;
                self.mode = Mode::Board;
            }
            DialogEvent::ConfirmIgnore | DialogEvent::Dismiss => {
                self.rollover_dialog = None;
                self.mode = Mode::Board;
            }
            DialogEvent::None => {}
        }
        Ok(Action::None)
    }
}

/// The parse diagnostic inside a [`TixError`], without the `parse error:` prefix
/// the prompt's message already implies.
fn error_message(error: &TixError) -> String {
    match error {
        TixError::Parse(message) => message.clone(),
        other => other.to_string(),
    }
}

/// `message`, with the recoverable copy of the previous version appended when
/// one was made (tix #1506).
fn names_backup(message: &str, backup: Option<&PathBuf>) -> String {
    match backup {
        Some(path) => format!("{message}; previous version saved at {}", path.display()),
        None => message.to_string(),
    }
}

const HINT_HEIGHT: u16 = 1;
/// Two rows: one for the tab labels, one for the tab bar's bottom border
/// (`BoardTabs` renders a `Block` with `Borders::BOTTOM`, which consumes the
/// last row). With height 1 the labels would never render.
const TAB_HEIGHT: u16 = 2;
/// Single-row active-filter indicator shown directly beneath the tab bar
/// (board-filtering FR-01); zero rows when no filter is active (D-05).
const FILTER_HEIGHT: u16 = 1;
/// Full-width row directly beneath the tab bar showing the currently hovered
/// issue's title (hovered-issue title line FR).
const HOVER_HEIGHT: u16 = 1;
const RENDER_FALLBACK_WIDTH: u16 = 80;
const RENDER_FALLBACK_HEIGHT: u16 = 24;
/// Spare rows kept blank below a one-shot render so the board fits on screen
/// instead of consuming the full terminal height.
const RENDER_BOTTOM_MARGIN: u16 = 4;

pub fn render(app: &App, f: &mut ratatui::Frame, area: Rect) {
    app.frame_hit_regions.borrow_mut().clear();
    // The vertical mode navigation takes the left column, and the active mode's
    // content is everything to its right (tui-mode-navigation). `frame_size`
    // tracks the *content* rect so board/tab hit-testing stays aligned with what
    // was drawn. One-shot `tix render` never shows the navigation, so its
    // contract is unchanged.
    let content = if !app.one_shot && app.nav_display != NavDisplay::Off {
        let nav_width = app.nav_width();
        if area.width > nav_width {
            let nav_area = Rect {
                width: nav_width,
                ..area
            };
            crate::ui::nav::render(app, f, nav_area);
            Rect {
                x: area.x + nav_width,
                width: area.width - nav_width,
                ..area
            }
        } else {
            area
        }
    } else {
        area
    };
    app.frame_size.set(content);
    // Every arm below draws into the content rect, so the geometry it records for
    // mouse hit-testing matches `frame_size`.
    let area = content;
    match &app.mode {
        Mode::Board => render_board(app, f, area, commandbar::MODE_BOARD),
        Mode::BulkModal => {
            // The board renders underneath, as it does under every other modal, so
            // the user can see the cards they marked and the columns they are in.
            render_board(app, f, area, commandbar::MODE_BOARD);
            if let Some(modal) = app.bulk.as_ref() {
                crate::ui::bulk::render(f, area, modal);
            }
        }
        Mode::TriageInbox => {
            // The inbox is the mode's content, not a card floating over the
            // board (tui-mode-navigation): the vertical navigation highlights
            // Triage and the mode occupies the whole content area.
            if let Some(state) = app.triage.as_ref() {
                crate::ui::triage::render(app, f, area, state);
            } else {
                render_board(app, f, area, commandbar::MODE_BOARD);
            }
        }
        Mode::Cycle => {
            // The cycle listing is the mode's content (tui-cycle-mode): the
            // vertical navigation highlights Cycle and the mode owns the area,
            // as the triage inbox does.
            if let Some(state) = app.cycle_state.as_ref() {
                let groups = app.cycle_groups();
                crate::ui::cycle::render(app, f, area, state, &groups);
            } else {
                render_board(app, f, area, commandbar::MODE_BOARD);
            }
        }
        Mode::RolloverDialog => {
            render_board(app, f, area, commandbar::MODE_BOARD);
            if let Some(dialog) = app.rollover_dialog.as_ref() {
                let rect = crate::ui::modal::modal_rect(area);
                f.render_widget(Clear, rect);
                let mut lines = Vec::new();
                lines.push(Line::from(Span::styled(
                    "Rollover needed",
                    Style::default()
                        .fg(Color::Yellow)
                        .add_modifier(Modifier::BOLD),
                )));
                for (from, to, count) in &dialog.plans {
                    lines.push(Line::from(format!(
                        "{count} issue(s): \"{from}\" -> \"{to}\""
                    )));
                }
                lines.push(Line::from(""));
                lines.push(Line::from(format!(
                    "{}: Do rollover | {}: Toggle choice | {}: Ignore",
                    app.bindings.label(
                        InputContext::Rollover,
                        crate::keybindings::TuiAction::Submit
                    ),
                    app.bindings.label(
                        InputContext::Rollover,
                        crate::keybindings::TuiAction::Previous
                    ),
                    app.bindings.label(
                        InputContext::Rollover,
                        crate::keybindings::TuiAction::Cancel
                    ),
                )));
                lines.push(Line::from(match dialog.choice {
                    crate::ui::dialog::DialogChoice::DoRollover => "> Do rollover | Ignore",
                    crate::ui::dialog::DialogChoice::Ignore => "Do rollover | > Ignore",
                }));
                let para = Paragraph::new(lines).block(
                    Block::default()
                        .borders(Borders::ALL)
                        .title("Rollover needed")
                        .style(Style::default().fg(Color::Yellow)),
                );
                f.render_widget(para, rect);
            }
        }
        Mode::Detail => render_detail(app, f, area, commandbar::MODE_DETAIL),
        Mode::Form => {
            // The form is the New Issue **mode's content**, not a modal floating
            // over the board (tui-new-issue-mode): it fills the area beside the
            // navigation, exactly as Triage and Cycle do.
            if let Some(fr) = &app.form {
                form::render_with_bindings(fr, f, area, &app.bindings, InputContext::Form);
                // Record the Template row so a click opens the picker. The row rect
                // comes from `form`, the same arithmetic the renderer and the caret
                // use, rather than a second copy of "border plus ring index".
                if let Some(row) = form::field_row_rect(area, form::FormFocus::Template) {
                    app.record_region(row, Action::TemplateOpen);
                }
                if let Some(picker) = &app.form_picker {
                    render_form_picker(app, picker, f, area, &app.bindings);
                } else {
                    // With nothing drawn over the form, the form owns the caret
                    // (#1486). Under a picker the overlay owns it instead, and a
                    // caret on the row behind it would point at the wrong surface.
                    form::place_caret(fr, f, area);
                }
            }
        }
        Mode::ConfirmDelete => {
            if area.height < 2 {
                return;
            }
            board::render(
                &app.board,
                f,
                area,
                &None,
                app.drag_preview_col,
                board::BoardDisplay::from(app.active_board_config()),
            );
            let title = app.confirm_delete_target.as_deref().unwrap_or("?");
            let prompt_area = confirm_delete_prompt(area);
            let prompt = Paragraph::new(vec![
                Line::from(Span::styled(
                    format!("Delete '{title}'? [y/N]"),
                    Style::default().fg(Color::Red).add_modifier(Modifier::BOLD),
                )),
                Line::from(""),
                Line::from("  [Yes]   [No]  "),
            ])
            .block(
                Block::default()
                    .borders(Borders::ALL)
                    .title("Confirm")
                    .style(Style::default().fg(Color::Red)),
            );
            f.render_widget(prompt, prompt_area);
            // Record the Yes / No button cells as click regions (D6): the run
            // loop maps them to the same `y` / cancel branches as the keys.
            let (yes, no) = confirm_delete_buttons(prompt_area);
            app.record_region(yes, Action::ConfirmDeleteYes);
            app.record_region(no, Action::ConfirmDeleteNo);
        }
        Mode::ConfirmBlockedMove { warning, .. } => {
            if area.height < 3 {
                return;
            }
            board::render(
                &app.board,
                f,
                area,
                &None,
                app.drag_preview_col,
                board::BoardDisplay::from(app.active_board_config()),
            );
            let prompt_area = Rect {
                y: area.y + area.height - 2,
                height: 2,
                ..area
            };
            // The warning is the shared text, so this prompt and the CLI's
            // `tix move` refusal cannot describe the same situation differently.
            let prompt = Paragraph::new(vec![
                Line::from(Span::styled(
                    format!("{warning} — move anyway? [y/N]"),
                    Style::default().fg(Color::Red).add_modifier(Modifier::BOLD),
                )),
                Line::from("  The decision is recorded in the issue's History."),
            ])
            .block(
                Block::default()
                    .borders(Borders::ALL)
                    .title("Blocked move")
                    .style(Style::default().fg(Color::Red)),
            );
            f.render_widget(prompt, prompt_area);
        }
        Mode::MoveIntoDone { buffer, .. } => {
            if area.height < 3 {
                return;
            }
            let prompt_area = Rect {
                y: area.y + area.height - 1,
                height: 1,
                ..area
            };
            let block_area = Rect {
                height: area.height - 1,
                ..area
            };
            board::render(
                &app.board,
                f,
                block_area,
                &app.status_msg,
                app.drag_preview_col,
                board::BoardDisplay::from(app.active_board_config()),
            );
            let prompt_text = format!("Commit hash: {buffer}_");
            let prompt = Paragraph::new(Line::from(Span::styled(
                prompt_text,
                Style::default().fg(Color::Yellow),
            )));
            f.render_widget(prompt, prompt_area);
        }
        // WP05: the reasoned-override prompt. `reason` is the **shared** service
        // diagnostic, rendered verbatim, so this prompt and the CLI's refusal
        // describe the same situation in the same words
        // (`contracts/surface-parity.md` §2 — parity includes the message).
        Mode::TransitionReason { buffer, reason, .. } => {
            if area.height < 3 {
                return;
            }
            let block_area = Rect {
                height: area.height - 1,
                ..area
            };
            board::render(
                &app.board,
                f,
                block_area,
                &app.status_msg,
                app.drag_preview_col,
                board::BoardDisplay::from(app.active_board_config()),
            );
            let prompt_area = Rect {
                y: area.y + area.height - 1,
                height: 1,
                ..area
            };
            let prompt = Paragraph::new(Line::from(Span::styled(
                format!("Reason (required): {buffer}_"),
                Style::default().fg(Color::Yellow),
            )));
            f.render_widget(prompt, prompt_area);
            // The refusal is shown above the board rather than in the one-line
            // prompt, because it is a full sentence with a backtick-quoted column
            // and a command spelling, and truncating it would leave the user with a
            // rule and no route.
            if area.height >= 5 {
                let notice = Rect {
                    y: area.y,
                    height: 3,
                    ..area
                };
                let text = Paragraph::new(vec![
                    Line::from(Span::styled(
                        "Blocked by the transition policy",
                        Style::default().fg(Color::Red).add_modifier(Modifier::BOLD),
                    )),
                    Line::from(reason.clone()),
                ])
                .block(
                    Block::default()
                        .borders(Borders::ALL)
                        .title("Override required"),
                );
                f.render_widget(text, notice);
            }
        }
        Mode::Help { return_to } => render_help(app, f, area, return_to),
        Mode::ContextMenu { return_to } => render_context_menu(app, f, area, return_to),
        Mode::Filter { buffer } => render_board_input(app, f, area, "Search", buffer),
        Mode::FilterModal => {
            render_board(app, f, area, commandbar::MODE_BOARD);
            if let Some(m) = app.filter_modal.as_ref() {
                m.render_with_bindings(f, area, &app.bindings, InputContext::FilterModal);
                // Record a hit region per criterion row; the run loop jumps
                // focus there (D6) exactly as Tab/arrow cycling would place it.
                let rect = crate::ui::modal::modal_rect(area);
                for (row, field) in FilterField::ALL.iter().enumerate() {
                    let hit = Rect {
                        x: rect.x + 1,
                        y: rect.y + 1 + row as u16,
                        width: rect.width.saturating_sub(2),
                        height: 1,
                    };
                    app.record_region(hit, Action::FilterModalFocus(*field));
                }
            }
        }
        Mode::Settings => {
            // The Config mode is the mode's content, not a modal over the board
            // (tui-config-mode): the section rail and the active section own the
            // area, as the triage inbox and the cycle listing do. Its planner
            // rows come from the same `planning_rows` the `m` surface uses.
            let (cycles, milestones) = app.planning_rows();
            let viewer = app.viewer_label();
            crate::ui::settings::render_config(
                app,
                f,
                area,
                crate::ui::settings::DashboardView {
                    name: app.active_board_name(),
                    board: app.active_board_config(),
                    editor: app.store.config.editor.as_deref(),
                    viewer: &viewer,
                },
                &cycles,
                &milestones,
            );
        }
        Mode::PlanningManagement => {
            render_board(app, f, area, commandbar::MODE_BOARD);
            if let Some(m) = app.planning.as_ref() {
                let (cycles, milestones) = app.planning_rows();
                m.render_with_bindings(
                    f,
                    area,
                    &cycles,
                    &milestones,
                    &app.bindings,
                    InputContext::PlanningManagement,
                );
            }
        }
        Mode::PlanningForm => {
            render_config_or_board(app, f, area);
            if let Some(fm) = app.planning_form.as_ref() {
                fm.render_with_bindings(f, area, &app.bindings, InputContext::PlanningForm);
            }
        }
        Mode::DatePicker { return_to } => {
            render_config_or_board(app, f, area);
            match return_to.as_ref() {
                Mode::Form => {
                    // The mode's content, so the picker overlays the form where it
                    // was actually drawn rather than a smaller modal rect.
                    if let Some(fr) = app.form.as_ref() {
                        form::render_with_bindings(fr, f, area, &app.bindings, InputContext::Form);
                    }
                }
                Mode::PlanningForm => {
                    if let Some(fm) = app.planning_form.as_ref() {
                        fm.render_with_bindings(f, area, &app.bindings, InputContext::PlanningForm);
                    }
                }
                Mode::FilterModal => {
                    if let Some(m) = app.filter_modal.as_ref() {
                        m.render_with_bindings(f, area, &app.bindings, InputContext::FilterModal);
                    }
                }
                _ => {}
            }
            if let Some(picker) = app.date_picker.as_ref() {
                picker.render_with_bindings(f, area, &app.bindings, InputContext::DatePicker);
                // Record the calendar grid and chrome so pointer clicks route
                // through the same key branches as keyboard input (D6).
                let rect = picker.popup_rect(area);
                let days_y = rect.y + 3;
                let weeks = rect.height.saturating_sub(6);
                for row in 0..weeks {
                    for col in 0..7u16 {
                        let x = rect.x + 1 + col * 3;
                        let y = days_y + row;
                        if let Some(date) = picker.date_at(area, x + 1, y) {
                            let hit = Rect {
                                x,
                                y,
                                width: 3,
                                height: 1,
                            };
                            app.record_region(
                                hit,
                                Action::DatePickerHit(DatePickerHit::Day(
                                    crate::ui::date_picker::format_date(date),
                                )),
                            );
                        }
                    }
                }
                let header_y = rect.y + 1;
                let header_w = rect.width.saturating_sub(2);
                let split = header_w / 2;
                if split > 0 {
                    app.record_region(
                        Rect {
                            x: rect.x + 1,
                            y: header_y,
                            width: split,
                            height: 1,
                        },
                        Action::DatePickerHit(DatePickerHit::PrevMonth),
                    );
                    app.record_region(
                        Rect {
                            x: rect.x + 1 + split,
                            y: header_y,
                            width: header_w - split,
                            height: 1,
                        },
                        Action::DatePickerHit(DatePickerHit::NextMonth),
                    );
                }
                app.record_region(
                    Rect {
                        x: rect.x,
                        y: rect.y + rect.height.saturating_sub(1),
                        width: rect.width,
                        height: 1,
                    },
                    Action::DatePickerHit(DatePickerHit::Submit),
                );
            }
        }
        Mode::Comment { buffer } => render_detail_input(app, f, area, "Comment", buffer),
        Mode::Asset { buffer } => render_detail_input(app, f, area, "Asset", buffer),
        Mode::EditRepair {
            filename,
            message,
            key,
            problems,
            temp,
            discard_armed,
            ..
        } => render_edit_repair(
            app,
            f,
            area,
            filename,
            message,
            key.as_deref(),
            problems,
            temp.as_deref(),
            *discard_armed,
        ),
        // #1510. The prompt names both files — the temp copy and the newer
        // on-disk one — so "compare" is something the user can do by hand even
        // outside the editor the key offers.
        Mode::EditConflict {
            filename,
            temp,
            disk_path,
        } => render_edit_conflict(app, f, area, filename, temp, disk_path),
        // #1359. The prompt is labelled by which step it is asking, so "enter
        // something" is never the whole instruction — and the kind step says it is
        // **required**, which is the one thing a user needs to know before typing.
        Mode::LinkCreate { buffer, step, .. } | Mode::LinkEdit { buffer, step, .. } => {
            let label = match (step, matches!(app.mode, Mode::LinkEdit { .. })) {
                (LinkStep::Target, false) => "Link to issue",
                (LinkStep::Target, true) => "Re-target to issue (blank keeps)",
                (LinkStep::Kind, false) => "Kind (required)",
                (LinkStep::Kind, true) => "Kind (required)",
            };
            render_detail_input(app, f, area, label, buffer)
        }
        Mode::ConfirmRemoveRelationship { .. } => {
            if let Some(ref d) = app.detail {
                detail::render(d, f, area);
            }
            render_input_line(
                f,
                Rect {
                    y: area.y + area.height.saturating_sub(1),
                    height: 1,
                    ..area
                },
                "Remove relationship (y to confirm)",
                "",
            );
        }
    }
}

fn render_form_picker(
    app: &App,
    picker: &FormPicker,
    f: &mut ratatui::Frame,
    area: Rect,
    bindings: &EffectiveBindings,
) {
    let rect = crate::ui::modal::modal_rect(area);
    let picker_rect = Rect::new(
        rect.x.saturating_add(2),
        rect.y.saturating_add(2),
        rect.width.saturating_sub(4).max(10),
        rect.height.saturating_sub(4).max(5),
    );
    f.render_widget(Clear, picker_rect);

    let mut lines = Vec::new();
    lines.push(Line::from(format!("Filter: {}", picker.state.filter)));
    lines.push(Line::from(""));

    if picker.state.mode == PickerMode::InlineCreate {
        lines.push(Line::from(Span::styled(
            format!("Create: {}_", picker.state.create_buffer),
            Style::default().fg(Color::Yellow),
        )));
    } else {
        let visible = picker.state.visible_indices();
        for (pos, idx) in visible.into_iter().take(8).enumerate() {
            let item = &picker.state.options[idx];
            let selected = match &picker.state.selection {
                SelectionModel::Single(current) => current.as_deref() == Some(item.id.as_str()),
                SelectionModel::Multi(current) => current.contains(&item.id),
            };
            let cursor = if pos == picker.state.cursor { ">" } else { " " };
            let mark = if selected { "[x]" } else { "[ ]" };
            lines.push(Line::from(format!("{cursor} {mark} {}", item.label)));
        }
    }

    lines.push(Line::from(""));
    // The create key is only advertised where it does something: the Status
    // dropdown refuses `+` (tix #1508), so its footer must not offer it.
    let create_hint = if picker.field.allows_inline_create() {
        format!(
            " | {} create",
            bindings.label(
                InputContext::FormPicker,
                crate::keybindings::TuiAction::Create
            )
        )
    } else {
        String::new()
    };
    lines.push(Line::from(Span::styled(
        format!(
            "{}/{} close | {} select{create_hint}",
            bindings.label(
                InputContext::FormPicker,
                crate::keybindings::TuiAction::OpenPicker
            ),
            bindings.label(
                InputContext::FormPicker,
                crate::keybindings::TuiAction::Cancel
            ),
            bindings.label(
                InputContext::FormPicker,
                crate::keybindings::TuiAction::Submit
            ),
        ),
        Style::default().fg(Color::DarkGray),
    )));

    let title = match picker.field {
        FormPickerField::Status => "Status picker",
        FormPickerField::Priority => "Priority picker",
        FormPickerField::Labels => "Labels picker",
        FormPickerField::Assignee => "Assignee picker",
        FormPickerField::Cycles => "Cycles picker",
        FormPickerField::Milestones => "Milestones picker",
        FormPickerField::Reviewer => "Reviewer picker",
        FormPickerField::Parent => "Parent picker",
        FormPickerField::Template => "Template picker",
    };
    let para = Paragraph::new(lines).block(Block::default().borders(Borders::ALL).title(title));
    f.render_widget(para, picker_rect);

    // The template selector is clickable as well as keyboard-navigable
    // (tui-new-issue-mode, requirement 4). Only the template picker records
    // regions: the multi-select pickers stay selections the user closes
    // deliberately, and a click that silently closed one would drop the rest.
    if picker.field == FormPickerField::Template && picker.state.mode != PickerMode::InlineCreate {
        // Below the top border the panel is `Filter:` (row 0), a blank (row 1),
        // then the option rows — so the first option sits three rows down.
        for (pos, _idx) in picker
            .state
            .visible_indices()
            .into_iter()
            .take(8)
            .enumerate()
        {
            let row = Rect {
                x: picker_rect.x.saturating_add(1),
                y: picker_rect
                    .y
                    .saturating_add(3)
                    .saturating_add(u16::try_from(pos).unwrap_or(0)),
                width: picker_rect.width.saturating_sub(2),
                height: 1,
            };
            app.record_region(row, Action::TemplatePickOption(pos));
        }
    }
}

/// The repair prompt (tix #1506): the editor round trip left a file with one or
/// more problems, and this lists each with its diagnostic and a proposal.
///
/// Every key is named with the chord the effective keymap binds: `confirm`
/// applies the proposed fix, `declare_key` writes an undeclared key into
/// `tix.toml`, `reedit` reopens the editor on the retained copy, `ignore`
/// acknowledges and keeps it, and `discard` removes it behind a second press.
/// The retained copy's path is named so a problem with no automatic fix can be
/// fixed by hand even outside the editor the key offers.
///
/// Wrapped, not clipped: the diagnostics are long (this is the message tix #1506
/// was filed about), and an offer to fix a problem must not be the line that
/// falls off the right edge on an 80-column terminal.
#[allow(clippy::too_many_arguments)]
fn render_edit_repair(
    app: &App,
    f: &mut ratatui::Frame,
    area: Rect,
    filename: &str,
    message: &str,
    key: Option<&str>,
    problems: &[EditProblem],
    temp: Option<&std::path::Path>,
    discard_armed: bool,
) {
    let label = |action| app.bindings.label(InputContext::EditRepair, action);
    render_board(app, f, area, commandbar::MODE_BOARD);
    let rect = crate::ui::modal::modal_rect(area);
    f.render_widget(Clear, rect);
    let mut lines = vec![
        Line::from(Span::styled("Edit Repair", Style::default().fg(Color::Red))),
        Line::from(Span::raw(filename.to_string())),
    ];
    if problems.is_empty() {
        lines.push(Line::from(Span::styled(
            message.to_string(),
            Style::default().fg(Color::Yellow),
        )));
    } else {
        for problem in problems {
            lines.push(Line::from(Span::styled(
                problem.message.clone(),
                Style::default().fg(Color::Yellow),
            )));
            lines.push(Line::from(Span::styled(
                format!("\u{2192} {}", problem.proposal_text()),
                Style::default().fg(Color::Green),
            )));
        }
    }
    // #1506. Offered only when the problem *is* an undeclared key — the one case
    // where accepting has something to declare. The chord is the context's own
    // `confirm` binding, so a customised keymap is what the hint shows.
    if let Some(key) = key {
        lines.push(Line::from(Span::styled(
            format!(
                "{}: declare `{key}` in [custom_attributes] in tix.toml",
                label(crate::keybindings::TuiAction::Confirm)
            ),
            Style::default().fg(Color::Green),
        )));
    }
    lines.push(Line::from(""));
    lines.push(Line::from(Span::styled(
        format!(
            "{}: apply the fix · {}: re-edit · {}: ignore",
            label(crate::keybindings::TuiAction::Confirm),
            label(crate::keybindings::TuiAction::Reedit),
            label(crate::keybindings::TuiAction::Ignore),
        ),
        Style::default().fg(Color::DarkGray),
    )));
    let discard = if discard_armed {
        format!(
            "{}: press again to discard the retained copy",
            label(crate::keybindings::TuiAction::Discard)
        )
    } else {
        format!(
            "{}: discard the edit (asks again)",
            label(crate::keybindings::TuiAction::Discard)
        )
    };
    let retained = match temp {
        Some(path) => format!("retained copy: {}", path.display()),
        None => "the edit is already on disk".to_string(),
    };
    lines.push(Line::from(Span::styled(
        format!("{discard} · {retained}"),
        Style::default().fg(Color::Red),
    )));
    let para = Paragraph::new(lines).wrap(Wrap { trim: true }).block(
        Block::default()
            .borders(Borders::ALL)
            .title("Edit Repair")
            .style(Style::default().fg(Color::Red)),
    );
    f.render_widget(para, rect);
}

/// The edit-conflict prompt (tix #1510): the issue file changed on disk while the
/// editor had it open, so nothing has been written and both versions still exist.
///
/// It states that fact, names **both** files — the edited temp copy and the newer
/// on-disk one — so the user can compare them by hand, and offers the three
/// decisions with the chords the effective keymap binds. Wrapped, not clipped: the
/// temp and store paths are long, and a prompt that hides where the two versions
/// are is a prompt that cannot be acted on at 80 columns.
fn render_edit_conflict(
    app: &App,
    f: &mut ratatui::Frame,
    area: Rect,
    filename: &str,
    temp: &std::path::Path,
    disk_path: &std::path::Path,
) {
    render_board(app, f, area, commandbar::MODE_BOARD);
    let rect = crate::ui::modal::modal_rect(area);
    f.render_widget(Clear, rect);
    let mut lines = vec![
        Line::from(Span::styled(
            "The issue changed on disk while the editor was open",
            Style::default().fg(Color::Red),
        )),
        Line::from(Span::raw(filename.to_string())),
        Line::from(Span::styled(
            format!("your edit:     {}", temp.display()),
            Style::default().fg(Color::Yellow),
        )),
        Line::from(Span::styled(
            format!("on disk (new): {}", disk_path.display()),
            Style::default().fg(Color::Yellow),
        )),
        Line::from(Span::styled(
            "nothing has been written yet".to_string(),
            Style::default().fg(Color::DarkGray),
        )),
        Line::from(""),
    ];
    // The three decisions, each with the chord the effective keymap binds and the
    // wording the *action* carries (`description_in`), so the prompt, the help
    // overlay and the docs say the same thing and a rebound key reads correctly
    // here without a second place to keep in step.
    for action in [TuiAction::Confirm, TuiAction::Ignore, TuiAction::Reedit] {
        lines.push(Line::from(format!(
            "{}: {}",
            app.bindings.label(InputContext::EditConflict, action),
            action.description_in(InputContext::EditConflict)
        )));
    }
    let para = Paragraph::new(lines).wrap(Wrap { trim: true }).block(
        Block::default()
            .borders(Borders::ALL)
            .title("Edit Conflict")
            .style(Style::default().fg(Color::Red)),
    );
    f.render_widget(para, rect);
}

/// Full-width row that always shows the title of the currently hovered
/// (selected) issue — `#<number> <title>` — or a dim placeholder when no card
/// is selected. Renders regardless of filter state. Sits directly beneath the
/// tab bar, or at the very top when a single board makes the bar redundant.
fn render_hover_line(app: &App, f: &mut ratatui::Frame, area: Rect) {
    let tab_h: u16 = if app.tabs.needs_bar() { TAB_HEIGHT } else { 0 };
    let hover_area = Rect {
        y: area.y + tab_h,
        height: HOVER_HEIGHT,
        ..area
    };
    let line = match app.board.get_selected_card() {
        Some(card) => Line::from(vec![
            Span::styled(
                format!("#{}", card.number),
                Style::default().fg(Color::Cyan),
            ),
            Span::raw(" "),
            Span::styled(card.title.clone(), Style::default()),
        ]),
        None => Line::from(Span::styled("—", Style::default().fg(Color::DarkGray))),
    };
    f.render_widget(Paragraph::new(line), hover_area);
}

/// The surface beneath a planning form or date picker: the Config mode's
/// sectioned view when the sub-surface was opened from it — the Config mode
/// owns the cycles/milestones sections, so its surface must stay visible — and
/// the board otherwise.
fn render_config_or_board(app: &App, f: &mut ratatui::Frame, area: Rect) {
    if app.settings.is_some() {
        let (cycles, milestones) = app.planning_rows();
        let viewer = app.viewer_label();
        crate::ui::settings::render_config(
            app,
            f,
            area,
            crate::ui::settings::DashboardView {
                name: app.active_board_name(),
                board: app.active_board_config(),
                editor: app.store.config.editor.as_deref(),
                viewer: &viewer,
            },
            &cycles,
            &milestones,
        );
    } else {
        render_board(app, f, area, commandbar::MODE_BOARD);
    }
}

/// Launch the system browser for `url` (tix #1513).
///
/// Spawned and **not waited on**: a browser is a long-lived process, and a TUI
/// that blocked on it would freeze until the browser closed. `stdout`/`stderr` are
/// nulled so a launcher's chatter cannot corrupt the alternate screen. `xdg-open`
/// first (the Linux convention), then `open` (macOS, and a fallback wherever a
/// user has it), which also covers the macOS case without a compile-time `cfg`.
fn open_in_browser(url: &str) -> std::io::Result<()> {
    let mut last = None;
    for opener in ["xdg-open", "open"] {
        match std::process::Command::new(opener)
            .arg(url)
            .stdin(std::process::Stdio::null())
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .spawn()
        {
            Ok(_child) => return Ok(()),
            Err(e) => last = Some(e),
        }
    }
    Err(last.unwrap_or_else(|| {
        std::io::Error::new(std::io::ErrorKind::NotFound, "no browser launcher found")
    }))
}

/// Board view: a persistent tabs bar at the top (omitted when only one board
/// is configured), the hovered-issue title line beneath it, then the board
/// (with its own status line), and the hint bar at the very bottom
/// (FR-009/FR-010).
fn render_board(app: &App, f: &mut ratatui::Frame, area: Rect, tag: &str) {
    let tab_h: u16 = if app.tabs.needs_bar() { TAB_HEIGHT } else { 0 };
    let filter_h: u16 = if app.filter.is_some() || app.structured.has_active_criteria() {
        FILTER_HEIGHT
    } else {
        0
    };
    let hint_h: u16 = if app.one_shot { 0 } else { HINT_HEIGHT };
    if area.height <= hint_h + tab_h + HOVER_HEIGHT + filter_h {
        return;
    }
    let hint_area = Rect {
        y: area.y + area.height - hint_h,
        height: hint_h,
        ..area
    };
    let tabs_area = Rect {
        y: area.y,
        height: tab_h,
        ..area
    };
    let filter_area = Rect {
        y: area.y + tab_h + HOVER_HEIGHT,
        height: filter_h,
        ..area
    };
    let content = Rect {
        y: area.y + tab_h + HOVER_HEIGHT + filter_h,
        height: area.height - tab_h - HOVER_HEIGHT - filter_h - hint_h,
        ..area
    };
    if tab_h > 0 {
        app.tabs.render(f, tabs_area);
        for index in 0..app.tabs.len() {
            if let Some(rect) = app.tabs.tab_rect(index, tabs_area) {
                app.record_region(rect, Action::SwitchBoard(index));
            }
        }
    }
    render_hover_line(app, f, area);
    if filter_h > 0 {
        filter_row(app).render(f, filter_area);
    }
    let page_cards = board::render(
        &app.board,
        f,
        content,
        &app.status_msg,
        app.drag_preview_col,
        board::BoardDisplay::from(app.active_board_config()),
    );
    // The renderer reports what one screen of the active column holds; the page keys
    // read it back. Set through `&App` because the field is a `Cell` — the same reason
    // the help overlay's geometry is one (tix #1442 follow-up).
    app.board_page.set(page_cards);
    if hint_h > 0 {
        render_hint(f, hint_area, app, tag);
    }
}

/// Detail view: detail content, optional status line, then the hint bar.
fn render_detail(app: &App, f: &mut ratatui::Frame, area: Rect, tag: &str) {
    let status_h: u16 = if app.status_msg.is_some() { 1 } else { 0 };
    if area.height <= HINT_HEIGHT + status_h {
        return;
    }
    let hint_area = Rect {
        y: area.y + area.height - HINT_HEIGHT,
        height: HINT_HEIGHT,
        ..area
    };
    let content = Rect {
        height: area.height - status_h - HINT_HEIGHT,
        ..area
    };
    if let Some(ref d) = app.detail {
        detail::render(d, f, content);
    }
    if let Some(msg) = &app.status_msg {
        let status_area = Rect {
            y: area.y + area.height - status_h - HINT_HEIGHT,
            height: status_h,
            ..area
        };
        let para = Paragraph::new(Line::from(Span::raw(msg.clone())))
            .style(Style::default().fg(Color::Yellow));
        f.render_widget(para, status_area);
    }
    if let Some(picker) = &app.related_picker {
        render_related_picker(app, picker, f, area);
    }
    render_hint(f, hint_area, app, tag);
}

/// The related-issues picker, drawn over the detail pane (tix #1513).
///
/// A centered modal like the form's picker; `related_picker` is the state, so the
/// rows come straight from it. There is no filter line: `InputContext::RelatedPicker`
/// binds only navigation, select, and cancel, so a filter the user could not type
/// would be a lie.
fn render_related_picker(app: &App, picker: &DropdownState, f: &mut ratatui::Frame, area: Rect) {
    let rect = crate::ui::modal::modal_rect(area);
    let picker_rect = Rect::new(
        rect.x.saturating_add(2),
        rect.y.saturating_add(2),
        rect.width.saturating_sub(4).max(10),
        rect.height.saturating_sub(4).max(5),
    );
    f.render_widget(Clear, picker_rect);

    const WINDOW: usize = 10;
    let visible = picker.visible_indices();
    let start = picker.cursor.saturating_sub(WINDOW.saturating_sub(1));
    let mut lines: Vec<Line<'static>> = Vec::new();
    for (pos, idx) in visible.iter().enumerate().skip(start).take(WINDOW) {
        let Some(item) = picker.options.get(*idx) else {
            continue;
        };
        let marker = if pos == picker.cursor { "> " } else { "  " };
        lines.push(Line::from(format!("{marker}{}", item.label)));
    }
    if lines.is_empty() {
        lines.push(Line::from("(no related issues)"));
    }
    lines.push(Line::from(""));
    lines.push(Line::from(Span::styled(
        format!(
            "{} select | {} close",
            app.bindings
                .label(InputContext::RelatedPicker, TuiAction::Submit),
            app.bindings
                .label(InputContext::RelatedPicker, TuiAction::Cancel),
        ),
        Style::default().fg(Color::DarkGray),
    )));

    let para = Paragraph::new(lines).block(
        Block::default()
            .borders(Borders::ALL)
            .title("Related issues"),
    );
    f.render_widget(para, picker_rect);
}

/// Board-underneath input modes (filter): the tab bar is omitted for a single
/// board; otherwise the layout is tab bar, hovered-issue title line, optional
/// filter row, board, and a one-line prompt at the bottom.
fn render_board_input(app: &App, f: &mut ratatui::Frame, area: Rect, label: &str, buffer: &str) {
    let tab_h: u16 = if app.tabs.needs_bar() { TAB_HEIGHT } else { 0 };
    if area.height < tab_h + HOVER_HEIGHT + 1 {
        return;
    }
    let filter_h: u16 = if app.filter.is_some() || app.structured.has_active_criteria() {
        FILTER_HEIGHT
    } else {
        0
    };
    let input_area = Rect {
        y: area.y + area.height - 1,
        height: 1,
        ..area
    };
    let tabs_area = Rect {
        y: area.y,
        height: tab_h,
        ..area
    };
    let filter_area = Rect {
        y: area.y + tab_h + HOVER_HEIGHT,
        height: filter_h,
        ..area
    };
    let content = Rect {
        y: area.y + tab_h + HOVER_HEIGHT + filter_h,
        height: area
            .height
            .saturating_sub(tab_h + HOVER_HEIGHT + filter_h + 1),
        ..area
    };
    if tab_h > 0 {
        app.tabs.render(f, tabs_area);
        for index in 0..app.tabs.len() {
            if let Some(rect) = app.tabs.tab_rect(index, tabs_area) {
                app.record_region(rect, Action::SwitchBoard(index));
            }
        }
    }
    render_hover_line(app, f, area);
    if filter_h > 0 {
        filter_row(app).render(f, filter_area);
    }
    let page_cards = board::render(
        &app.board,
        f,
        content,
        &app.status_msg,
        app.drag_preview_col,
        board::BoardDisplay::from(app.active_board_config()),
    );
    // The renderer reports what one screen of the active column holds; the page keys
    // read it back. Set through `&App` because the field is a `Cell` — the same reason
    // the help overlay's geometry is one (tix #1442 follow-up).
    app.board_page.set(page_cards);
    render_input_line(f, input_area, label, buffer);
}

/// Detail-underneath input modes (comment, asset): detail content + prompt.
fn render_detail_input(app: &App, f: &mut ratatui::Frame, area: Rect, label: &str, buffer: &str) {
    if area.height < 2 {
        return;
    }
    let input_area = Rect {
        y: area.y + area.height - 1,
        height: 1,
        ..area
    };
    let content = Rect {
        height: area.height - 1,
        ..area
    };
    if let Some(ref d) = app.detail {
        detail::render(d, f, content);
    }
    render_input_line(f, input_area, label, buffer);
}

fn render_input_line(f: &mut ratatui::Frame, area: Rect, label: &str, buffer: &str) {
    let text = format!("{label}: {buffer}_");
    let prompt = Paragraph::new(Line::from(Span::styled(
        text,
        Style::default().fg(Color::Yellow),
    )));
    f.render_widget(prompt, area);
}

fn filter_row(app: &App) -> crate::ui::filter_row::FilterRow {
    crate::ui::filter_row::FilterRow {
        query: app.filter.clone(),
        structured: app.structured.clone(),
    }
}

fn render_hint(f: &mut ratatui::Frame, area: Rect, app: &App, tag: &str) {
    let context = if tag == commandbar::MODE_DETAIL {
        // The related picker overlays the detail pane (#1513), so its own keys
        // are the ones to advertise while it is open. When it is not, the pane's
        // keys are — never `app.input_context()`, which would report the *help*
        // context while the overlay is drawn over a detail pane.
        if app.related_picker.is_some() {
            InputContext::RelatedPicker
        } else {
            InputContext::Detail
        }
    } else {
        commandbar::hint_context_for_mode(app.top_mode)
    };
    let bar = commandbar::hint_bar_for(&app.bindings, context);
    let para = Paragraph::new(Line::from(Span::styled(
        bar,
        Style::default().fg(Color::Gray),
    )));
    f.render_widget(para, area);
}

/// Help as a centered modal (FR-010): the screen the user came from stays
/// visible underneath (rendered per `return_to`), and the command list floats
/// above it in a bordered box. `?`/`q`/Esc close it (see `handle_help_key`).
fn render_help(app: &App, f: &mut ratatui::Frame, area: Rect, return_to: &Mode) {
    match return_to {
        Mode::Board => render_board(app, f, area, commandbar::MODE_BOARD),
        Mode::Detail => render_detail(app, f, area, commandbar::MODE_DETAIL),
        _ => render_board(app, f, area, commandbar::MODE_BOARD),
    }

    let help_entries = commandbar::help_overlay(&app.bindings, app.top_mode);
    // tix #1496: `/` filters the list, best match first. `fuzzy_score` is the same
    // subsequence scorer `tix search` and the board's `/` use, so "clon" finds
    // `clone issue` and "nwiss" finds it too — one notion of "fuzzy" in the tool, not
    // a second one that behaves almost the same.
    let query = app.help_query.trim().to_string();
    // Contiguous matches first; the fuzzy scorer is the **fallback**, not the first
    // pass. A bare subsequence is far too permissive over a hundred short rows —
    // `clone` is a subsequence of `Esc / q / ? cancel context_menu`, so a pure fuzzy
    // filter would keep most of the list and rank the binding you asked for somewhere
    // inside it. The literal search is what actually narrows; when it finds nothing
    // (`nwiss` has no literal home) the scorer takes over, which is the case that makes
    // the search *fuzzy* rather than a second substring filter.
    let mut fuzzy_fallback = false;
    let matches: Vec<(String, String, String)> = if query.is_empty() {
        help_entries.clone()
    } else {
        let needle = query.to_lowercase();
        let haystack = |entry: &(String, String, String)| {
            format!("{} {} {}", entry.0, entry.1, entry.2).to_lowercase()
        };
        let literal: Vec<(String, String, String)> = help_entries
            .iter()
            .filter(|entry| haystack(entry).contains(&needle))
            .cloned()
            .collect();
        if literal.is_empty() {
            fuzzy_fallback = true;
            // Best first; `sort_by` is stable, so equal scores keep the declared order —
            // which is the order the overlay is normally read in.
            let mut scored: Vec<(u32, (String, String, String))> = help_entries
                .iter()
                .filter_map(|entry| {
                    crate::search::fuzzy_score(&query, &haystack(entry))
                        .map(|score| (score, entry.clone()))
                })
                .collect();
            scored.sort_by(|a, b| b.0.cmp(&a.0));
            scored.into_iter().map(|(_, entry)| entry).collect()
        } else {
            literal
        }
    };
    let total = help_entries.len();
    // How many entry rows fit, once the border and this line are accounted for.
    // Computed **before** the rows so the notice can be counted against the same
    // budget rather than pushed off the bottom itself.
    let frame_rows = area.height.saturating_sub(2);
    let visible = (matches.len() as u16).min(frame_rows.saturating_sub(1));
    let hidden = matches.len().saturating_sub(visible as usize);
    // tix #1441: record what only the renderer knows, so the handlers can clamp a
    // step without re-deriving the frame.
    app.help_metrics.set(HelpMetrics {
        visible,
        max_scroll: u16::try_from(hidden).unwrap_or(u16::MAX),
    });
    let offset = usize::from(app.help_scroll).min(hidden);
    let mut rows: Vec<Line<'static>> = matches
        .iter()
        .skip(offset)
        .take(visible as usize)
        .map(|(key, desc, scope)| {
            Line::from(vec![
                Span::styled(format!("{key:<20}"), Style::default().fg(Color::Cyan)),
                Span::styled(format!("{desc:<28}"), Style::default().fg(Color::White)),
                Span::styled(scope.clone(), Style::default().fg(Color::DarkGray)),
            ])
        })
        .collect();
    // Returns the column the terminal caret belongs at, when the input line is up.
    let caret = if app.help_searching {
        let mut spans = vec![
            Span::styled("/", Style::default().fg(Color::Yellow)),
            Span::styled(app.help_query.clone(), Style::default().fg(Color::White)),
        ];
        // The count belongs on this line too: while typing is exactly when the reader
        // wants to know whether the filter found anything, and the rows below say it
        // only by being short. It sits after the caret, dim, so it reads as status
        // rather than as more input.
        if !query.is_empty() {
            spans.push(Span::styled(
                format!(
                    "  — {} of {total} bindings{}",
                    matches.len(),
                    if fuzzy_fallback { " (fuzzy)" } else { "" },
                ),
                Style::default().fg(Color::DarkGray),
            ));
        }
        rows.push(Line::from(spans));
        Some(Line::from(format!("/{}", app.help_query)).width())
    } else if !query.is_empty() {
        // What the filter did, and where in the *matches* the reader is — the same two
        // facts the unfiltered line carries, because a filtered list that does not say
        // how much it is hiding reads as the whole list.
        // Says which search answered, so a fallback that matched rows the reader did not
        // type is explained rather than mysterious.
        let mode = if fuzzy_fallback { " (fuzzy)" } else { "" };
        rows.push(Line::from(Span::styled(
            match hidden {
                0 => format!(
                    "match \"{query}\" — {} of {total} bindings{mode}",
                    matches.len()
                ),
                _ => format!(
                    "match \"{query}\" — {} of {total} bindings, rows {}-{}{mode}",
                    matches.len(),
                    offset + 1,
                    offset + visible as usize,
                ),
            },
            Style::default().fg(Color::DarkGray),
        )));
        None
    } else if hidden > 0 {
        // **Say what is missing — and where you are.** The overlay used to be
        // silently truncated at the frame height, so a short terminal showed a
        // complete-looking list that was quietly missing bindings, and a binding
        // absent from the help is a binding nobody can find. Now that it scrolls, the
        // same line has to answer "is there more?" *and* "am I at the top?", or a
        // scrolled reader cannot tell the difference between the first page and the
        // last.
        //
        // One row of the budget, so it stays short enough not to wrap.
        rows.push(Line::from(Span::styled(
            format!(
                "rows {}-{} of {} — {} above, {} below",
                offset + 1,
                offset + visible as usize,
                matches.len(),
                offset,
                hidden - offset,
            ),
            Style::default().fg(Color::DarkGray),
        )));
        None
    } else {
        None
    };
    let block = Block::default()
        .borders(Borders::ALL)
        .title("Help [? close]")
        .style(Style::default().fg(Color::Cyan));
    let para = Paragraph::new(rows).block(block);
    // The match rows plus the one line that carries the input prompt, the filter
    // summary or the scroll position — whichever of those is showing.
    let notice_rows = u16::from(caret.is_some() || !query.is_empty() || hidden > 0);
    let drawn_rows = visible + notice_rows;

    let modal_w = 60.min(area.width).max(30);
    // Sized to what is actually drawn, so a filter that narrows the list to three
    // bindings gives a three-row box rather than leaving a tall empty one.
    let modal_h = (drawn_rows + 2).min(area.height).max(4);
    let modal_x = area.x + (area.width.saturating_sub(modal_w)) / 2;
    let modal_y = area.y + (area.height.saturating_sub(modal_h)) / 2;
    let modal_area = Rect::new(modal_x, modal_y, modal_w, modal_h);

    if area.height >= modal_h && area.width >= modal_w {
        f.render_widget(Clear, modal_area);
        f.render_widget(para, modal_area);
    }
    // The input line has the keyboard, so the caret goes where the next character will
    // land — the same rule the create form follows (tix #1486), and the reason the
    // prompt is drawn as a row rather than only described in the footer.
    if let Some(column) = caret
        && area.height >= modal_h
        && area.width >= modal_w
    {
        let inner = Block::default().borders(Borders::ALL).inner(modal_area);
        let row = inner.y + visible.min(inner.height.saturating_sub(1));
        let x = inner.x
            + u16::try_from(column)
                .unwrap_or(u16::MAX)
                .min(inner.width.saturating_sub(1));
        f.set_cursor_position(ratatui::layout::Position::new(x, row));
    }
    // Any click on the help screen closes it, so the whole overlay resolves to
    // the same branch as `?`/`q`/Esc.
    app.record_region(area, Action::HelpClose);
}

/// The centered prompt box of the confirm-delete dialog, sized to the frame.
/// Shared by `render` (drawing) and `confirm_delete_buttons` (hit regions) so
/// the pointer geometry cannot drift from what is drawn.
fn confirm_delete_prompt(area: Rect) -> Rect {
    let prompt_w = 40.min(area.width);
    let prompt_h = 4;
    let prompt_x = area.x + (area.width.saturating_sub(prompt_w)) / 2;
    let prompt_y = area.y + (area.height.saturating_sub(prompt_h)) / 2;
    Rect::new(prompt_x, prompt_y, prompt_w, prompt_h)
}

/// The matched cell rectangles of the Yes and No buttons inside a
/// confirm-delete prompt, matching the `"  [Yes]   [No]  "` row's columns.
/// `(yes, no)`.
fn confirm_delete_buttons(prompt: Rect) -> (Rect, Rect) {
    let yes = Rect::new(prompt.x + 3, prompt.y + 3, 5, 1);
    let no = Rect::new(prompt.x + 10, prompt.y + 3, 4, 1);
    (yes, no)
}

/// The issue context menu as an overlay (D5): the board stays visible
/// underneath and the menu floats at a clamped popup position. See
/// [`App::handle_context_menu_key`] for routing.
fn render_context_menu(app: &App, f: &mut ratatui::Frame, area: Rect, return_to: &Mode) {
    match return_to {
        Mode::Board => render_board(app, f, area, commandbar::MODE_BOARD),
        _ => render_board(app, f, area, commandbar::MODE_BOARD),
    }
    if let Some(menu) = app.context_menu.as_ref() {
        menu.render(f, area);
    }
}

/// Drain disclosures raised by a TUI action into the status line.
///
/// Extracted from the event loop so the wiring is reachable from a test. Cycle 5
/// deleted the inlined loop and all 1012 tests stayed green: the unit test for
/// `note_disclosure` calls it directly, so it could not fail for the regression it
/// is named for. `run` needs a real terminal, so this function is the only seam
/// available. The call site inside `run` is still not covered; it says so.
pub fn drain_disclosures(app: &mut App) {
    for disclosure in crate::storage::take_disclosures() {
        app.note_disclosure(disclosure);
    }
}

pub fn run(config: &Config) -> Result<()> {
    run_session(config, false)
}

/// `tix new` (#1398): the same session, opened on the create-issue form.
///
/// The form wins over the pending-rollover dialog an expired cycle would normally
/// raise at startup. That is deliberate: `tix new` was asked to file an issue, the
/// rollover is a prompt rather than a task, and it is still pending — the next
/// session and the one-line hint every other command prints both raise it again.
pub fn run_new_issue(config: &Config) -> Result<()> {
    run_session(config, true)
}

fn run_session(config: &Config, new_issue_form: bool) -> Result<()> {
    let mut app = App::new(config)?;
    if new_issue_form {
        app.open_new_issue_form();
    }
    let mut watcher = crate::watcher::FsWatcher::new(app.store.issues_dir.clone());
    let mut coalescer = crate::watcher::DeltaCoalescer::default();
    enable_raw_mode().map_err(io_err)?;
    execute!(io::stdout(), EnterAlternateScreen).map_err(io_err)?;
    mouse_capture_on(io::stdout()).map_err(io_err)?;
    let guard = RestoreGuard;
    let backend = CrosstermBackend::new(io::stdout());
    let mut terminal = Terminal::new(backend).map_err(io_err)?;

    let result = loop {
        // A write performed by any TUI action can raise a disclosure; surface
        // it rather than letting it sit in the queue for the rest of the session.
        //
        // Uncovered: `run` needs a real terminal, so no test reaches this line.
        // `drain_disclosures` itself is tested; this call site is not, and saying
        // so here is the point — a reader must not infer that deleting it would be
        // caught. Cycle-6 F5: the function's own comment used to promise a
        // statement here that was never written.
        drain_disclosures(&mut app);
        terminal
            .draw(|f| render(&app, f, f.area()))
            .map_err(io_err)?;

        // The idle tick is 1 Hz (tix #1518): one redraw per second is enough for
        // this TUI, and the loop draws unconditionally at the top of each
        // iteration, so the tick *is* the idle redraw rate. A key or mouse event
        // wakes `poll` immediately and is handled at once — the cap applies to
        // idle redraws, not to input latency. The tree walk in `watcher.poll`
        // below runs on the same 1 Hz beat, so an external edit surfaces within
        // about a second.
        if event::poll(Duration::from_secs(1)).map_err(io_err)? {
            let action = match event::read().map_err(io_err)? {
                Event::Key(key) => app.handle_key(key)?,
                Event::Mouse(mouse) => app.handle_mouse(mouse)?,
                // Resize (and any unknown event) is a no-op: the loop redraws
                // on the 1 Hz tick anyway (D2).
                _ => Action::None,
            };
            match action {
                Action::None => {}
                Action::Quit => break Ok(()),
                Action::SwitchBoard(index) => {
                    app.switch_board(index);
                }
                Action::ConfirmDeleteYes => {
                    let _ = app.confirm_delete_yes();
                }
                Action::ConfirmDeleteNo => {
                    let _ = app.confirm_delete_no();
                }
                Action::FilterModalFocus(field) => {
                    if let Some(modal) = app.filter_modal.as_mut() {
                        modal.focus_field(field);
                    }
                }
                Action::SettingsRow(row) => {
                    app.apply_config_click(Action::SettingsRow(row));
                    let _ = app.settings_toggle_selected();
                }
                Action::ConfigSection(section) => {
                    app.apply_config_click(Action::ConfigSection(section));
                }
                Action::ConfigPlanningRow(row) => {
                    app.apply_config_click(Action::ConfigPlanningRow(row));
                }
                Action::ConfigListRow(row) => {
                    app.apply_config_click(Action::ConfigListRow(row));
                }
                Action::SelectBoard(_)
                | Action::SelectCycle(_)
                | Action::SelectMilestone(_)
                | Action::NewFromTemplate(_) => {
                    let _ = app.activate_branch(&action);
                }
                Action::DatePickerHit(hit) => match hit {
                    DatePickerHit::Day(date) => {
                        if let Some(picker) = app.date_picker.as_mut() {
                            picker.select_date_str(&date);
                        }
                    }
                    DatePickerHit::PrevMonth => {
                        if let Some(picker) = app.date_picker.as_mut() {
                            picker.shift_month(-1);
                        }
                    }
                    DatePickerHit::NextMonth => {
                        if let Some(picker) = app.date_picker.as_mut() {
                            picker.shift_month(1);
                        }
                    }
                    DatePickerHit::Submit => {
                        let _ = app.handle_date_picker_key(KeyEvent::new(
                            KeyCode::Enter,
                            crossterm::event::KeyModifiers::NONE,
                        ));
                    }
                },
                Action::HelpClose => {
                    app.close_help();
                }
                Action::SwitchMode(mode) => {
                    let _ = app.switch_top_mode(mode);
                }
                Action::TriageOpenStatus
                | Action::TriageOpenAssignee
                | Action::TriageCreate
                | Action::TriageFocusQueue
                | Action::TriagePickOption(_)
                | Action::TriageDropdownClose => {
                    let _ = app.apply_triage_action(action);
                }
                Action::CycleSelect(index) => app.select_cycle_row(index),
                Action::OpenIssue(filename) => {
                    if let Err(e) = app.open_issue_by_filename(&filename) {
                        app.status_msg = Some(format!("open: {e}"));
                    }
                }
                Action::TemplateOpen | Action::TemplatePickOption(_) => {
                    let _ = app.apply_new_issue_action(action);
                }
                Action::OpenEditor(filename) => {
                    drop(terminal);
                    let _ = disable_raw_mode();
                    let _ = mouse_capture_off(io::stdout());
                    let _ = execute!(io::stdout(), LeaveAlternateScreen);

                    // #1510. The whole round trip — snapshot, temp copy, editor,
                    // read-back, conflict decision, write and lint report — is
                    // `open_editor_round_trip`; the terminal handover around it is
                    // all this arm adds, which is the one thing a test cannot
                    // provide and the one thing that has nothing to do with what
                    // the edit means.
                    if let Err(e) = app.open_editor_round_trip(&filename) {
                        app.status_msg = Some(format!("editor: {e}"));
                    }

                    enable_raw_mode().map_err(io_err)?;
                    execute!(io::stdout(), EnterAlternateScreen).map_err(io_err)?;
                    mouse_capture_on(io::stdout()).map_err(io_err)?;
                    let backend = CrosstermBackend::new(io::stdout());
                    terminal = Terminal::new(backend).map_err(io_err)?;
                }
                Action::CompareEdit => {
                    drop(terminal);
                    let _ = disable_raw_mode();
                    let _ = mouse_capture_off(io::stdout());
                    let _ = execute!(io::stdout(), LeaveAlternateScreen);

                    // The conflict prompt's `c`: reopen the editor on the temp
                    // copy and come back to the prompt (#1510). An error leaves the
                    // prompt exactly as it was — the temp copy and the newer file
                    // are both still there — so the failure cannot strand the user
                    // with nothing to press.
                    if let Err(e) = app.compare_conflicting_edit() {
                        app.status_msg = Some(format!("editor: {e}"));
                    }

                    enable_raw_mode().map_err(io_err)?;
                    execute!(io::stdout(), EnterAlternateScreen).map_err(io_err)?;
                    mouse_capture_on(io::stdout()).map_err(io_err)?;
                    let backend = CrosstermBackend::new(io::stdout());
                    terminal = Terminal::new(backend).map_err(io_err)?;
                }
                Action::ReeditRepair => {
                    drop(terminal);
                    let _ = disable_raw_mode();
                    let _ = mouse_capture_off(io::stdout());
                    let _ = execute!(io::stdout(), LeaveAlternateScreen);

                    // The repair prompt's `r`: the editor reopens on the retained
                    // copy (#1506). An error leaves the prompt — and the copy —
                    // exactly as they were, so a failed launch cannot strand the
                    // user with nothing to press.
                    if let Err(e) = app.reedit_repair() {
                        app.status_msg = Some(format!("editor: {e}"));
                    }

                    enable_raw_mode().map_err(io_err)?;
                    execute!(io::stdout(), EnterAlternateScreen).map_err(io_err)?;
                    mouse_capture_on(io::stdout()).map_err(io_err)?;
                    let backend = CrosstermBackend::new(io::stdout());
                    terminal = Terminal::new(backend).map_err(io_err)?;
                }
                Action::OpenAgent(filename) => {
                    drop(terminal);
                    let _ = disable_raw_mode();
                    let _ = mouse_capture_off(io::stdout());
                    let _ = execute!(io::stdout(), LeaveAlternateScreen);

                    let edit_result = (|| -> Result<()> {
                        let agent = editor::resolve_agent(app.store.config.agent.as_deref())?;
                        let issue = app.store.get(IssueSelector::Filename(filename.clone()))?;
                        let temp = std::env::temp_dir().join(format!(
                            "tix-agent-{}-{}.md",
                            std::process::id(),
                            issue.number
                        ));
                        std::fs::write(&temp, issue.body.as_bytes()).map_err(io_err)?;
                        let result = std::process::Command::new(&agent)
                            .arg(&temp)
                            .status()
                            .map_err(|e| {
                                crate::error::TixError::Editor(format!(
                                    "failed to launch {agent}: {e}"
                                ))
                            });
                        let _ = std::fs::remove_file(&temp);
                        result?;
                        Ok(())
                    })();
                    if let Err(e) = edit_result {
                        app.status_msg = Some(format!("agent: {e}"));
                    }

                    enable_raw_mode().map_err(io_err)?;
                    execute!(io::stdout(), EnterAlternateScreen).map_err(io_err)?;
                    mouse_capture_on(io::stdout()).map_err(io_err)?;
                    let backend = CrosstermBackend::new(io::stdout());
                    terminal = Terminal::new(backend).map_err(io_err)?;
                }
                Action::OpenViewer(filename) => {
                    drop(terminal);
                    let _ = disable_raw_mode();
                    let _ = mouse_capture_off(io::stdout());
                    let _ = execute!(io::stdout(), LeaveAlternateScreen);

                    // Read-only: no temp file, no read-back, no write. The shell-out
                    // mechanics match `OpenEditor` — the terminal is handed over and
                    // restored around the child — but nothing after the child runs
                    // sees the file.
                    let view_result = (|| -> Result<()> {
                        let viewer = editor::resolve_viewer(app.store.config.viewer.as_deref())?;
                        let issue = app.store.get(IssueSelector::Filename(filename.clone()))?;
                        let path = app.store.issues_dir.join(&issue.filename);
                        editor::run_viewer(&viewer, &path)?;
                        app.status_msg = Some(format!("Viewed with {viewer}"));
                        Ok(())
                    })();
                    if let Err(e) = view_result {
                        app.status_msg = Some(format!("viewer: {e}"));
                    }

                    enable_raw_mode().map_err(io_err)?;
                    execute!(io::stdout(), EnterAlternateScreen).map_err(io_err)?;
                    mouse_capture_on(io::stdout()).map_err(io_err)?;
                    let backend = CrosstermBackend::new(io::stdout());
                    terminal = Terminal::new(backend).map_err(io_err)?;
                }
                Action::OpenViewerAt(path) => {
                    drop(terminal);
                    let _ = disable_raw_mode();
                    let _ = mouse_capture_off(io::stdout());
                    let _ = execute!(io::stdout(), LeaveAlternateScreen);

                    // The same read-only handover as `OpenViewer`, but the path is
                    // already resolved: a `related_issues` path entry may point
                    // outside the store, so there is no store lookup to do (#1513).
                    let view_result = (|| -> Result<()> {
                        let viewer = editor::resolve_viewer(app.store.config.viewer.as_deref())?;
                        editor::run_viewer(&viewer, &path)?;
                        app.status_msg = Some(format!("Viewed with {viewer}"));
                        Ok(())
                    })();
                    if let Err(e) = view_result {
                        app.status_msg = Some(format!("viewer: {e}"));
                    }

                    enable_raw_mode().map_err(io_err)?;
                    execute!(io::stdout(), EnterAlternateScreen).map_err(io_err)?;
                    mouse_capture_on(io::stdout()).map_err(io_err)?;
                    let backend = CrosstermBackend::new(io::stdout());
                    terminal = Terminal::new(backend).map_err(io_err)?;
                }
            }
        }

        // Issue #10: reflect edits made outside `tix` (another editor, `tix`
        // CLI, git checkout). A burst of writes is coalesced into **one**
        // rebuild: `DeltaCoalescer` buffers deltas and hands back the merged
        // one only on the first quiet tick (a poll that reports nothing while a
        // delta is pending), so N writes cost one `refresh_from_disk`. The cost
        // is at most one extra idle tick (~1s, tix #1518) of latency before an external
        // edit shows. A failed apply — a file caught mid-write is a parse error
        // now and a good read once the writer finishes — stays pending and is
        // retried, so its sibling changes are not lost.
        if let Some(delta) = coalescer.observe(watcher.poll()) {
            if let Err(e) = app.refresh_from_disk(&delta) {
                app.status_msg = Some(format!("watch: {e}"));
                coalescer.retry(delta);
            }
        }
    };
    drop(guard);
    result
}

/// Render the board once using startup state and return the plain-text frame.
pub fn render_once(config: &Config) -> Result<String> {
    let size = resolve_render_size(crossterm::terminal::size().ok());
    render_once_at(config, size.0, size.1)
}

fn resolve_render_size(measured: Option<(u16, u16)>) -> (u16, u16) {
    let (width, height) = measured.unwrap_or((RENDER_FALLBACK_WIDTH, RENDER_FALLBACK_HEIGHT));
    (width.max(1), height.max(1))
}

fn render_once_at(config: &Config, width: u16, height: u16) -> Result<String> {
    let render_h = height.max(1).saturating_sub(RENDER_BOTTOM_MARGIN).max(1);
    let mut app = App::new(config)?;
    app.mode = Mode::Board;
    app.rollover_dialog = None;
    app.one_shot = true;
    let cells = render_to_cells(&app, width, render_h)?;
    Ok(cells_to_text(&cells, width, render_h))
}

fn render_to_cells(app: &App, width: u16, height: u16) -> Result<Vec<String>> {
    let backend = ratatui::backend::TestBackend::new(width.max(1), height.max(1));
    let mut terminal = ratatui::Terminal::new(backend).map_err(io_err)?;
    terminal
        .draw(|f| render(app, f, f.area()))
        .map_err(io_err)?;
    let buffer = terminal.backend().buffer();
    Ok(buffer
        .content
        .iter()
        .map(|cell| cell.symbol().to_string())
        .collect())
}

fn cells_to_text(cells: &[String], width: u16, height: u16) -> String {
    let mut lines = Vec::new();
    for row in 0..height as usize {
        let start = row * width as usize;
        let end = start + width as usize;
        let line = cells[start..end].concat();
        lines.push(line.trim_end().to_string());
    }
    while matches!(lines.last(), Some(last) if last.is_empty()) {
        let _ = lines.pop();
    }
    if lines.is_empty() {
        String::new()
    } else {
        format!("{}\n", lines.join("\n"))
    }
}

/// Enable terminal mouse capture on `stream` (D1): one command pair shared by
/// the startup, editor/agent shell-out re-entry, and restore paths so capture
/// toggling can never drift between call sites.
fn mouse_capture_on(mut stream: io::Stdout) -> Result<()> {
    execute!(stream, EnableMouseCapture).map_err(io_err)
}

/// Disable terminal mouse capture on `stream` (D1): mirror of
/// [`mouse_capture_on`]. Must run while the alternate screen is still active,
/// so the terminal leaves a clean state on quit/error.
fn mouse_capture_off(mut stream: io::Stdout) -> Result<()> {
    execute!(stream, DisableMouseCapture).map_err(io_err)
}

struct RestoreGuard;

impl Drop for RestoreGuard {
    fn drop(&mut self) {
        let _ = disable_raw_mode();
        let _ = mouse_capture_off(io::stdout());
        let _ = execute!(io::stdout(), LeaveAlternateScreen);
    }
}

fn io_err<E: std::fmt::Display>(e: E) -> TixError {
    TixError::Io(io::Error::other(e.to_string()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs;
    use tempfile::TempDir;

    /// A test config with auto-migration off, so tests that use bare/legacy
    /// fixtures stay about their own concern. Auto-migration is covered by
    /// dedicated tests (`tests/cli.rs`, `tests/mcp.rs`, and storage).
    fn test_config() -> Config {
        let mut config = Config::default();
        config.layout.move_on_change = false;
        config
    }

    fn make_app() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let config_path = tmp.path().join("tix.toml");
        let config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        let app = App::new(&config).unwrap();
        (tmp, app)
    }

    fn write_issue(
        dir: &std::path::Path,
        name: &str,
        number: u32,
        title: &str,
        status: &str,
        commit: Option<&str>,
    ) {
        let commit_line = match commit {
            Some(h) => format!("commit: \"{h}\""),
            None => String::new(),
        };
        let contents = format!(
            "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"{status}\"\nlabels: []\npriority: \"medium\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n{commit_line}\n---\n\nBody text."
        );
        fs::write(dir.join(name), contents).unwrap();
    }

    /// Temp fixture with `n` issues for the throughput harness, ~10% `todo` and
    /// the rest `done` so the board resembles a real one.
    fn perf_fixture(n: u32) -> (TempDir, Config) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let config_path = tmp.path().join("tix.toml");
        let config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        config.save(&config_path).unwrap();
        for i in 1..=n {
            let status = if i % 10 == 0 { "todo" } else { "done" };
            write_issue(
                &dir,
                &format!("perf-{i:05}.md"),
                i,
                &format!("Card {i:05}"),
                status,
                None,
            );
        }
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        (tmp, config)
    }

    /// Throughput harness for tix #1518. Ignored by default (it is a benchmark,
    /// not an assertion); run it against a release build:
    ///
    /// ```text
    /// cargo test --release -- --ignored --nocapture perf_startup_and_render
    /// ```
    ///
    /// It reports, per issue count, the time to construct an `App` (one tree walk
    /// plus board/corpus/rollover build since #1518) and the time for one full
    /// board frame. Both are printed; the test asserts nothing, so a regression is
    /// visible in the numbers rather than as a flaky wall-clock bound.
    #[test]
    #[ignore = "throughput harness (tix #1518); run with --release --ignored --nocapture"]
    fn perf_startup_and_render() {
        use std::time::Instant;
        for n in [10u32, 100, 1000, 5000] {
            let (_tmp, config) = perf_fixture(n);
            let iters: u32 = if n >= 1000 { 3 } else { 10 };
            // Warm the page cache, then measure `App::new`.
            let mut app = App::new(&config).unwrap();
            let start = Instant::now();
            for _ in 0..iters {
                app = App::new(&config).unwrap();
            }
            let startup = start.elapsed() / iters;
            // One full frame over the built board.
            let start = Instant::now();
            for _ in 0..iters {
                render_to_cells(&app, 120, 40).unwrap();
            }
            let frame = start.elapsed() / iters;
            println!("n={n:5}  startup={startup:>10?}  frame={frame:>10?}");
        }
    }

    /// Where startup time actually goes, per phase (tix #1518). Run:
    ///
    /// ```text
    /// cargo test --release -- --ignored --nocapture perf_startup_breakdown
    /// ```
    ///
    /// Prints, per issue count: the tree scan (`store.list`), the board build
    /// (blocked/children/related over the whole set), corpus serialization, the
    /// rollover plan, and one steady-state filesystem-watcher poll.
    #[test]
    #[ignore = "throughput harness (tix #1518); run with --release --ignored --nocapture"]
    fn perf_startup_breakdown() {
        use std::time::Instant;
        for n in [1000u32, 5000] {
            let (_tmp, config) = perf_fixture(n);
            let store = Store::open(&config).unwrap();
            let board_config = config.default_config().clone();

            let start = Instant::now();
            let issues = store.list().unwrap();
            let scan = start.elapsed();

            let resolution = BoardState::resolution_for(&store, &board_config);
            let start = Instant::now();
            let _board = BoardState::build_from_issues(
                &issues,
                &board_config,
                &store.config,
                &resolution,
                false,
            );
            let board = start.elapsed();

            let start = Instant::now();
            let corpus = Corpus::from_issues(issues);
            let corpus_ser = start.elapsed();

            let planner = Planner::from_config(config.clone(), std::path::PathBuf::from("."));
            let start = Instant::now();
            let _plan = planner.rollover_plan_from(&corpus.issues, &today());
            let rollover = start.elapsed();

            let mut watcher = crate::watcher::FsWatcher::new(store.issues_dir.clone());
            let _ = watcher.poll();
            let start = Instant::now();
            for _ in 0..5 {
                let _ = watcher.poll();
            }
            let watch = start.elapsed() / 5;

            println!(
                "n={n:5} scan={scan:>10?} board={board:>10?} corpus_ser={corpus_ser:>10?} \
                 rollover={rollover:>10?} watch_poll={watch:>10?}"
            );
        }
    }

    fn press(code: KeyCode) -> KeyEvent {
        KeyEvent::new(code, crossterm::event::KeyModifiers::NONE)
    }

    fn press_with_modifiers(code: KeyCode, modifiers: crossterm::event::KeyModifiers) -> KeyEvent {
        KeyEvent::new(code, modifiers)
    }

    /// A temp store seeded with two cycles (one referencing a stored issue), a
    /// milestone file, and one issue referencing both. Cycles carry
    /// far-future dates so no rollover dialog steals the initial mode.
    fn make_app_with_planning() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let mut config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        config.cycles.insert(
            "Cycle 1".into(),
            crate::config::PlanningCycle {
                description: Some("kickoff".into()),
                start_date: Some("2026-10-01".into()),
                due_date: Some("2999-12-31".into()),
            },
        );
        config.cycles.insert(
            "Cycle 2".into(),
            crate::config::PlanningCycle {
                description: Some("next".into()),
                start_date: Some("2999-01-01".into()),
                due_date: Some("2999-01-15".into()),
            },
        );
        let issue = "---\nnumber: 1\ntitle: \"A\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\ncycles: [\"Cycle 1\"]\nmilestones: [\"GA\"]\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody text.";
        fs::create_dir_all(dir.join("alice")).unwrap();
        fs::write(dir.join("alice/2026-01-01-a.md"), issue).unwrap();
        let milestones_dir = tmp.path().join("docs/milestones");
        fs::create_dir_all(&milestones_dir).unwrap();
        fs::write(
            milestones_dir.join("2026-01-01-ga.md"),
            "---\nname: \"GA\"\ntarget_date: \"2026-12-31\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nship it\n",
        )
        .unwrap();
        let config_path = tmp.path().join("tix.toml");
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        let app = App::new(&config).unwrap();
        (tmp, app)
    }

    fn make_app_with_rollover_dialog() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let mut config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        config.cycles.clear();
        config.cycles.insert(
            "Cycle 1".into(),
            crate::config::PlanningCycle {
                description: Some("expired".into()),
                start_date: Some("2000-01-01".into()),
                due_date: Some("2000-01-02".into()),
            },
        );
        config.cycles.insert(
            "Cycle 2".into(),
            crate::config::PlanningCycle {
                description: Some("next".into()),
                start_date: Some("2999-01-01".into()),
                due_date: Some("2999-01-15".into()),
            },
        );
        let issue = "---\nnumber: 1\ntitle: \"A\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\ncycles: [\"Cycle 1\"]\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody text.";
        fs::create_dir_all(dir.join("alice")).unwrap();
        fs::write(dir.join("alice/2026-01-01-a.md"), issue).unwrap();
        let config_path = tmp.path().join("tix.toml");
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        let app = App::new(&config).unwrap();
        (tmp, app)
    }

    #[test]
    fn quit_on_q() {
        let (_tmp, mut app) = make_app();
        let action = app.handle_key(press(KeyCode::Char('q'))).unwrap();
        assert!(app.quit);
        assert!(matches!(action, Action::Quit));
    }

    #[test]
    fn m_opens_planning_modal_from_board() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        assert!(
            matches!(app.mode, Mode::PlanningManagement),
            "m flips board mode to planning management"
        );
        assert!(app.planning.is_some(), "planning modal state is opened");
    }

    #[test]
    fn q_and_esc_close_planning_modal() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('q'))).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert!(app.planning.is_none());

        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Board), "Esc closes the modal");
        assert!(app.planning.is_none());
    }

    #[test]
    fn esc_cancels_planning_form_back_to_modal() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(matches!(app.mode, Mode::PlanningForm));
        assert!(app.planning_form.is_some());
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(
            matches!(app.mode, Mode::PlanningManagement),
            "Esc in the form returns to the modal"
        );
        assert!(app.planning_form.is_none());
        assert!(app.planning.is_some(), "the modal stays open underneath");
    }

    #[test]
    fn planning_browse_navigates_and_switches_segments() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();

        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(app.planning.as_ref().unwrap().selected, 1);
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(
            app.planning.as_ref().unwrap().selected,
            1,
            "cursor clamps at the last cycle"
        );
        let _ = app.handle_key(press(KeyCode::Char('k'))).unwrap();
        assert_eq!(app.planning.as_ref().unwrap().selected, 0);

        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let modal = app.planning.as_ref().unwrap();
        assert_eq!(
            modal.segment,
            crate::ui::planning::PlanningSegment::Milestones,
            "Tab switches to the milestones segment"
        );
        assert_eq!(modal.selected, 0, "segment switch resets the row cursor");
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(
            app.planning.as_ref().unwrap().selected,
            0,
            "a single milestone clamps the cursor"
        );

        let _ = app.handle_key(press(KeyCode::BackTab)).unwrap();
        assert_eq!(
            app.planning.as_ref().unwrap().segment,
            crate::ui::planning::PlanningSegment::Cycles,
            "BackTab switches back to the cycles segment"
        );

        let _ = app.handle_key(press(KeyCode::Char('q'))).unwrap();
        assert!(
            matches!(app.mode, Mode::Board),
            "q cancels out of the modal"
        );
        assert!(app.planning.is_none());
    }

    #[test]
    fn planning_h_l_and_arrows_switch_segments() {
        use crate::ui::planning::PlanningSegment;
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();

        let segment = |app: &App| app.planning.as_ref().unwrap().segment;
        assert_eq!(segment(&app), PlanningSegment::Cycles);

        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(
            segment(&app),
            PlanningSegment::Milestones,
            "`l` moves right"
        );
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        assert_eq!(segment(&app), PlanningSegment::Cycles, "`h` moves left");
        let _ = app.handle_key(press(KeyCode::Right)).unwrap();
        assert_eq!(segment(&app), PlanningSegment::Milestones, "→ moves right");
        let _ = app.handle_key(press(KeyCode::Left)).unwrap();
        assert_eq!(segment(&app), PlanningSegment::Cycles, "← moves left");
    }

    #[test]
    fn planning_n_opens_create_form_for_active_segment() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(matches!(app.mode, Mode::PlanningForm));
        assert_eq!(
            app.planning_form.as_ref().unwrap().kind,
            crate::ui::planning::PlanningKind::Cycle,
            "n on the cycles segment opens a cycle form"
        );

        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert_eq!(
            app.planning_form.as_ref().unwrap().kind,
            crate::ui::planning::PlanningKind::Milestone,
            "n on the milestones segment opens a milestone form"
        );
    }

    #[test]
    fn planning_e_opens_edit_form_prefilled() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('e'))).unwrap();
        let form = app.planning_form.as_ref().unwrap().clone();
        assert_eq!(form.kind, crate::ui::planning::PlanningKind::Cycle);
        assert_eq!(form.name(), "Cycle 1");
        assert_eq!(form.editing.as_deref(), Some("Cycle 1"));
        assert_eq!(form.description(), "kickoff");
        assert_eq!(form.date_a(), "2026-10-01");

        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('e'))).unwrap();
        let form = app.planning_form.as_ref().unwrap().clone();
        assert_eq!(form.kind, crate::ui::planning::PlanningKind::Milestone);
        assert_eq!(form.name(), "GA");
        assert_eq!(form.editing.as_deref(), Some("GA"));
        assert_eq!(form.date_a(), "2026-12-31");
    }

    #[test]
    fn planning_x_shows_referencing_count_and_cancel_keeps_item() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
        match &app.planning.as_ref().unwrap().prompt {
            Some(crate::ui::planning::PlanningPrompt::ConfirmDelete { name, referencing }) => {
                assert_eq!(name, "Cycle 1");
                assert_eq!(*referencing, 1, "one issue references Cycle 1");
            }
            other => panic!("x raises a confirm prompt, got {other:?}"),
        }

        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(
            app.planning.as_ref().unwrap().prompt.is_none(),
            "n dismisses the prompt"
        );
        assert!(
            matches!(app.mode, Mode::PlanningManagement),
            "cancelling stays in the modal"
        );
        assert_eq!(
            app.planning_rows_len(),
            2,
            "the cancelled delete leaves the cycle in the registry"
        );
    }

    #[test]
    /// #1307: a double-width character must not defeat the cut marker.
    ///
    /// The previous truncation took `chars().take(budget)` — scalar values, not
    /// display cells — so a CJK filename produced a string up to twice as wide as
    /// the status area. ratatui's `Paragraph` then hard-cut it at the right edge
    /// and discarded the ellipsis appended at the end of the overflowed string,
    /// which is the silent cut the truncation was added to prevent.
    ///
    /// Driven through the real renderer rather than the helper, because the bug
    /// lived in the interaction between the two: the helper "worked" and the
    /// widget threw the marker away.
    fn the_cut_marker_survives_a_double_width_filename() {
        let (_tmp, mut app) = make_app();
        app.note_disclosure(
            "remove `links:` by hand to silence \u{2014} \
             alice/2026-09-14-\u{65e5}\u{672c}\u{8a9e}\u{306e}\u{3068}\u{3066}\u{3082}\u{3044}\u{3044}\u{30d5}\u{30a1}\u{30a4}\u{30eb}\u{540d}_tests.md \
             (retired by C-001; never read as typed data, no migration)"
                .to_string(),
        );
        // 60 is included: the review noted the existing test omitted it, and
        // omitted widths are where this class of bug hides.
        for width in [60u16, 80, 100, 120, 200] {
            let cells = render_to_cells(&app, width, 40).unwrap();
            let rendered: Vec<String> = (0..40).map(|y| flush_line(&cells, width, y)).collect();
            let status = rendered
                .iter()
                .find(|l| l.contains("remove `links:`"))
                .unwrap_or_else(|| panic!("width {width}: no status row: {rendered:?}"));
            assert!(
                status.contains("remove `links:` by hand"),
                "width {width}: the action must stay visible, got {status:?}"
            );
            if width < 200 {
                assert!(
                    status.contains('\u{2026}'),
                    "width {width}: a cut must be marked, not silent, got {status:?}"
                );
            }
        }
    }

    /// #1307: the rendered row must never exceed the area, in cells.
    ///
    /// This is the invariant the widget silently broke: a string handed to a
    /// one-row area that is wider than the area gets hard-cut, and whatever sat
    /// at the end of it — the marker — is lost.
    #[test]
    #[allow(clippy::unicode_not_nfc)] // the CJK literals are deliberately un-normalised
    fn a_truncated_status_row_never_exceeds_its_width_in_cells() {
        use unicode_width::UnicodeWidthStr;
        for msg in [
            "remove `links:` by hand to silence \u{2014} plain-ascii-file.md",
            "remove `links:` by hand to silence \u{2014} \u{65e5}\u{672c}\u{8a9e}.md",
            "short",
            "",
        ] {
            for budget in [1usize, 2, 3, 5, 10, 20] {
                let text = crate::ui::board::truncate_to_cells(msg, budget);
                assert!(
                    text.width() <= budget,
                    "budget {budget}, msg {msg:?}: produced {text:?} at width {}",
                    text.width()
                );
                if msg.width() > budget {
                    assert!(
                        text.ends_with('\u{2026}'),
                        "budget {budget}, msg {msg:?}: a cut must be marked, got {text:?}"
                    );
                }
            }
        }
    }

    #[test]
    fn the_retired_key_warning_stays_actionable_at_every_terminal_width() {
        // Cycle-5 Major 6 claimed reordering the composed message was enough; cycle
        // 6 drove the real renderer and found the actionable instruction still
        // off-screen at 80, 100 and 120 columns, because the status area is one
        // unwrapped row and a long filename fills it whatever the order. This
        // pins what actually makes it work: the disclosure leads with the action,
        // and the render marks the cut.
        let (_tmp, mut app) = make_app();
        app.note_disclosure(
            "remove `links:` by hand to silence \u{2014} \
             alice/2026-09-14-add-the-ability-to-hide-and-show-kanban-columns.md \
             (retired by C-001; never read as typed data, no migration)"
                .to_string(),
        );
        for width in [80u16, 100, 120] {
            let cells = render_to_cells(&app, width, 40).unwrap();
            let rendered: Vec<String> = (0..40).map(|y| flush_line(&cells, width, y)).collect();
            let status = rendered
                .iter()
                .find(|l| l.contains("remove `links:`"))
                .unwrap_or_else(|| panic!("width {width}: no status row rendered: {rendered:?}"));
            assert!(
                status.contains("remove `links:` by hand to silence"),
                "width {width}: the action must be visible, got {status:?}"
            );
            assert!(
                status.contains('\u{2026}'),
                "width {width}: a cut is marked rather than silent, got {status:?}"
            );
        }
    }

    #[test]
    fn planning_renders_rows_with_fields_and_counts() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let cells = render_to_cells(&app, 120, 40).unwrap();
        let lines: Vec<String> = (0..40).map(|y| flush_line(&cells, 120, y)).collect();

        assert!(
            lines
                .iter()
                .any(|l| l.contains("Cycle 1 | kickoff | 2026-10-01 | 2999-12-31 | 1 issue")),
            "cycle rows show fields and count: {lines:?}"
        );
        assert!(
            lines
                .iter()
                .any(|l| l.contains("Cycle 2 | next | 2999-01-01 | 2999-01-15 | 0 issues")),
            "unreferenced cycles render a zero count"
        );

        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let cells = render_to_cells(&app, 120, 40).unwrap();
        let lines: Vec<String> = (0..40).map(|y| flush_line(&cells, 120, y)).collect();
        assert!(
            lines
                .iter()
                .any(|l| l.contains("GA | ship it | 2026-12-31 | 1 issue")),
            "milestone rows show fields and count: {lines:?}"
        );
    }

    #[test]
    fn planning_form_creates_cycle_with_blank_fields_rejected() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();

        // Blank name is rejected; the form stays open with an error status.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            matches!(app.mode, Mode::PlanningForm),
            "blank-name submit keeps the form open"
        );
        let status = app.status_msg.as_deref().unwrap_or("");
        assert!(
            status.contains("a name is required"),
            "blank names surface an error status: {status:?}"
        );
        assert_eq!(app.planning_rows_len(), 2, "nothing was created");

        // Type a name and submit.
        for c in "Cycle 9".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            matches!(app.mode, Mode::PlanningManagement),
            "a valid create returns to the modal"
        );
        assert!(app.planning_form.is_none());
        assert!(
            app.store.config.cycles.contains_key("Cycle 9"),
            "the new cycle is persisted to tix.toml and reloaded into the store"
        );
        let (cycles, _) = app.planning_rows();
        assert!(
            cycles.iter().any(|r| r.name == "Cycle 9"),
            "the modal re-query shows the new cycle"
        );
    }

    #[test]
    fn planning_form_creates_milestone_and_refreshes_pickers() {
        let (tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Beta".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        let milestones_dir = tmp.path().join("docs/milestones");
        let created = milestones_dir
            .read_dir()
            .unwrap()
            .filter_map(|e| e.ok())
            .filter(|e| e.file_name().to_string_lossy().contains("beta.md"))
            .count();
        assert_eq!(created, 1, "a milestone registry file is written");

        let (_, milestones) = app.planning_rows();
        assert!(
            milestones
                .iter()
                .any(|r| { r.name == "Beta" && r.date_a == today() }),
            "the modal re-query shows the milestone with its target date"
        );

        let options = app.picker_options(FormPickerField::Milestones);
        assert!(
            options.iter().any(|o| o.id == "Beta"),
            "a freshly built picker lists the new milestone (no restart)"
        );
    }

    #[test]
    fn planning_form_date_row_masked_typing_and_picker() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Gamma".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();

        // Enter on an empty date row opens the picker.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::PlanningForm));

        // Typing digits edits the date in place with the mask.
        for c in "20261130".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(app.planning_form.as_ref().unwrap().date_a(), "2026-11-30");

        // Backspace removes the last digit, then typing restores it.
        let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        assert_eq!(app.planning_form.as_ref().unwrap().date_a(), "2026-11-3");
        let _ = app.handle_key(press(KeyCode::Char('0'))).unwrap();
        assert_eq!(app.planning_form.as_ref().unwrap().date_a(), "2026-11-30");

        // F2 opens the picker seeded from the field.
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(app.planning_form.as_ref().unwrap().date_a(), "2026-11-30");
    }

    #[test]
    fn planning_form_creates_cycle_visible_to_pickers() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Cycle 9".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        let options = app.picker_options(crate::app::FormPickerField::Cycles);
        assert!(
            options.iter().any(|o| o.id == "Cycle 9"),
            "a freshly built cycle picker lists the new cycle"
        );
    }

    #[test]
    fn new_issue_form_without_a_cycle_joins_the_single_running_cycle() {
        let (_tmp, mut app) = make_app();
        // One cycle whose window certainly contains today; no configured default.
        app.store.config.cycles.insert(
            "October 2026".into(),
            crate::config::PlanningCycle {
                description: None,
                start_date: Some("2020-01-01".into()),
                due_date: Some("2999-12-31".into()),
            },
        );
        app.store.config.planning.default_cycle = None;

        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Automatic".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        // Enter on the (non-empty) Title row submits; no cycle was chosen, so
        // the form takes the same `default_cycle_name` path the CLI core does.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Board), "the form submitted");

        let issue = app
            .store
            .list()
            .unwrap()
            .into_iter()
            .find(|issue| issue.title == "Automatic")
            .expect("created issue");
        assert_eq!(
            issue.cycles,
            Some(vec!["October 2026".to_string()]),
            "the TUI form assigns the single running cycle"
        );
    }

    #[test]
    fn planning_form_create_surfaces_an_overlap_in_the_status() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "October".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        // Name → description → start date, then type a date that falls inside
        // the fixture's `Cycle 1` window.
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        for c in "20261020".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        // Enter on a complete date row submits the form.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(
            app.store.config.cycles.contains_key("October"),
            "the overlapping cycle is still created"
        );
        let status = app.status_msg.clone().unwrap_or_default();
        assert!(
            status.contains("overlaps existing cycle(s)") && status.contains("Cycle 1"),
            "the overlap is surfaced as a status note: {status:?}"
        );
    }

    #[test]
    fn planning_form_edits_cycle_fields() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('e'))).unwrap();

        // Focus the description field and rewrite it.
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        for _ in 0..7 {
            let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        }
        for c in "sprint".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        let cycle = &app.store.config.cycles["Cycle 1"];
        assert_eq!(cycle.description.as_deref(), Some("sprint"));
        assert_eq!(cycle.start_date.as_deref(), Some("2026-10-01"));
        assert_eq!(cycle.due_date.as_deref(), Some("2999-12-31"));
        assert!(
            app.store.config.cycles.contains_key("Cycle 1")
                && !app.store.config.cycles.contains_key("sprint"),
            "field edits never rename the cycle"
        );
    }

    #[test]
    fn planning_form_renames_cycle_cascade_rewrites_issues_and_refreshes() {
        let (tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('e'))).unwrap();
        for _ in 0..7 {
            let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        }
        for c in "Cycle One".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(
            !app.store.config.cycles.contains_key("Cycle 1"),
            "old name gone"
        );
        assert!(
            app.store.config.cycles.contains_key("Cycle One"),
            "new name persisted"
        );

        let issue = app.store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(issue.cycles.unwrap(), vec!["Cycle One".to_string()]);

        let (cycles, _) = app.planning_rows();
        assert!(
            cycles.iter().any(|r| r.name == "Cycle One"),
            "the modal re-query shows the renamed cycle"
        );

        let options = app.picker_options(crate::app::FormPickerField::Cycles);
        assert!(options.iter().any(|o| o.id == "Cycle One"));
        assert!(!options.iter().any(|o| o.id == "Cycle 1"));

        // The corpus is rebuilt from the rewritten files: the renamed cycle
        // matches a board query and the stale spelling no longer does.
        app.apply_filter("cycle:One");
        let hit: usize = (0..app.board.total_cols())
            .map(|c| app.board.column_cards(c).len())
            .sum();
        assert_eq!(hit, 1, "the board corpus picks up the renamed cycle");
        let raw = std::fs::read_to_string(tmp.path().join("issues/alice/2026-01-01-a.md")).unwrap();
        assert!(
            raw.contains("Cycle One"),
            "issue file carries the new spelling"
        );
        assert!(!raw.contains("Cycle 1"), "stale spelling fully rewritten");
    }

    #[test]
    fn planning_form_duplicate_name_surfaces_error_keeps_form() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('e'))).unwrap();
        for _ in 0..7 {
            let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        }
        for c in "Cycle 2".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(matches!(app.mode, Mode::PlanningForm));
        let status = app.status_msg.as_deref().unwrap_or("");
        assert!(
            status.contains("already exists"),
            "duplicate names surface an error status: {status:?}"
        );
        assert!(app.store.config.cycles.contains_key("Cycle 1"));
        assert!(app.store.config.cycles.contains_key("Cycle 2"));
        assert_eq!(
            app.store.config.cycles.len(),
            2,
            "the rejected rename changed nothing"
        );
    }

    #[test]
    fn planning_form_renames_milestone_cascade_edge_to_edge() {
        let (tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('e'))).unwrap();
        for _ in 0..2 {
            let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        }
        for c in "GAX".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        for _ in 0..7 {
            let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        }
        for c in "beta".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));
        let _ = app.handle_key(press(KeyCode::PageDown)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        let milestones_dir = tmp.path().join("docs/milestones");
        let files: Vec<String> = milestones_dir
            .read_dir()
            .unwrap()
            .filter_map(|e| e.ok())
            .map(|e| e.file_name().to_string_lossy().to_string())
            .collect();
        assert!(
            files.iter().any(|f| f.ends_with("-gax.md")),
            "the milestone registry file is renamed: {files:?}"
        );
        assert!(
            !files.iter().any(|f| f.ends_with("-ga.md")),
            "the old registry file is gone: {files:?}"
        );

        let issue = app.store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(issue.milestones.unwrap(), vec!["GAX".to_string()]);

        let planner = Planner::load_from(&tmp.path().join("tix.toml")).unwrap();
        let ms = planner.milestone("GAX").unwrap();
        assert_eq!(ms.target_date.as_str(), "2027-01-31");
        assert!(ms.description.contains("beta"), "description was edited");
    }

    #[test]
    fn planning_delete_confirm_removes_cycle_and_refreshes_grouping() {
        let (_tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
        match &app.planning.as_ref().unwrap().prompt {
            Some(crate::ui::planning::PlanningPrompt::ConfirmDelete { name, referencing }) => {
                assert_eq!(name, "Cycle 1");
                assert_eq!(*referencing, 1, "the confirm prompt reports the count");
            }
            other => panic!("x raises a confirm prompt, got {other:?}"),
        }

        // Cancelling with Esc keeps everything.
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(
            app.store.config.cycles.contains_key("Cycle 1"),
            "cancelling keeps the item"
        );
        let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        // Confirming deletes the cycle but leaves referencing issues unchanged.
        assert!(!app.store.config.cycles.contains_key("Cycle 1"));
        assert!(app.store.config.cycles.contains_key("Cycle 2"));
        let (cycles, _) = app.planning_rows();
        assert!(
            cycles.iter().all(|r| r.name != "Cycle 1"),
            "the modal re-query drops the deleted cycle"
        );
        let issue = app.store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(
            issue.cycles.unwrap(),
            vec!["Cycle 1".to_string()],
            "references preserved"
        );

        let options = app.picker_options(crate::app::FormPickerField::Cycles);
        assert!(
            !options.iter().any(|o| o.id == "Cycle 1"),
            "no stale picker entry"
        );
        app.apply_filter("cycle:Cycle");
        let hit: usize = (0..app.board.total_cols())
            .map(|c| app.board.column_cards(c).len())
            .sum();
        assert_eq!(hit, 1, "the referencing issue stays grouped on the board");
    }

    #[test]
    fn planning_delete_confirm_removes_milestone_file_preserves_issues() {
        let (tmp, mut app) = make_app_with_planning();
        let _ = app.handle_key(press(KeyCode::Char('m'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
        match &app.planning.as_ref().unwrap().prompt {
            Some(crate::ui::planning::PlanningPrompt::ConfirmDelete { name, referencing }) => {
                assert_eq!(name, "GA");
                assert_eq!(*referencing, 1);
            }
            other => panic!("x raises a confirm prompt, got {other:?}"),
        }
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        let milestones_dir = tmp.path().join("docs/milestones");
        assert!(
            milestones_dir.join("2026-01-01-ga.md").exists(),
            "cancel keeps the milestone file"
        );

        let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('y'))).unwrap();
        assert!(
            !milestones_dir.join("2026-01-01-ga.md").exists(),
            "confirm removes the registry file"
        );
        let (_, milestones) = app.planning_rows();
        assert!(milestones.is_empty(), "the milestone segment is now empty");
        let issue = app.store.get(IssueSelector::Number(1)).unwrap();
        assert_eq!(issue.milestones.unwrap(), vec!["GA".to_string()]);
        let options = app.picker_options(FormPickerField::Milestones);
        assert!(
            !options.iter().any(|o| o.id == "GA"),
            "no stale picker entry"
        );
    }

    #[test]
    fn startup_shows_rollover_dialog_when_plan_exists() {
        let (_tmp, app) = make_app_with_rollover_dialog();
        assert!(matches!(app.mode, Mode::RolloverDialog));
        assert!(app.rollover_dialog.is_some());
    }

    #[test]
    fn rollover_dialog_enter_applies_rollover() {
        let (_tmp, mut app) = make_app_with_rollover_dialog();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        let issue = app.store.list().unwrap().into_iter().next().unwrap();
        let cycles = issue.cycles.unwrap_or_default();
        assert!(cycles.iter().any(|c| c == "Cycle 2"));
        assert!(!cycles.iter().any(|c| c == "Cycle 1"));
    }

    #[test]
    fn quit_on_esc() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(app.quit);
    }

    #[test]
    fn cursor_clamp_empty_column() {
        let (_tmp, mut app) = make_app();
        app.board.move_left();
        assert_eq!(app.board.active_col, app.board.total_cols() - 1);
        app.board.move_right();
        assert_eq!(app.board.active_col, 0);
    }

    #[test]
    fn cursor_clamp_single_card() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        assert_eq!(app.board.column_cards(0).len(), 1);
        app.board.move_down();
        assert_eq!(app.board.selected, 0);
        app.board.move_up();
        assert_eq!(app.board.selected, 0);
    }

    #[test]
    fn wrap_around_columns() {
        let (_tmp, mut app) = make_app();
        let total = app.board.total_cols();
        for _ in 0..total + 2 {
            app.board.move_right();
        }
        assert_eq!(app.board.active_col, 2 % total);
        for _ in 0..total + 2 {
            app.board.move_left();
        }
    }

    #[test]
    fn refresh_from_disk_picks_up_new_file() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        assert_eq!(app.board.column_cards(0).len(), 0);
        let mut watcher = crate::watcher::FsWatcher::new(&dir);
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let delta = watcher.poll().expect("the new file is reported");
        app.refresh_from_disk(&delta).unwrap();
        assert_eq!(app.board.column_cards(0).len(), 1);
    }

    #[test]
    fn refresh_from_disk_reflects_external_status_move() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        let mut watcher = crate::watcher::FsWatcher::new(&dir);
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let delta = watcher.poll().unwrap();
        app.refresh_from_disk(&delta).unwrap();
        assert_eq!(app.board.column_cards(0).len(), 1);

        write_issue(&dir, "2026-01-01-a.md", 1, "A", "done", None);
        let delta = watcher.poll().expect("the rewrite is reported");
        app.refresh_from_disk(&delta).unwrap();
        assert_eq!(app.board.column_cards(0).len(), 0);
        assert_eq!(app.board.column_cards(3).len(), 1);
    }

    #[test]
    fn refresh_from_disk_keeps_board_on_bad_file() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        let mut watcher = crate::watcher::FsWatcher::new(&dir);
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let delta = watcher.poll().unwrap();
        app.refresh_from_disk(&delta).unwrap();
        assert_eq!(app.board.column_cards(0).len(), 1);

        fs::write(dir.join("2026-01-01-bad.md"), "not frontmatter").unwrap();
        let delta = watcher.poll().expect("the malformed file is reported");
        assert!(app.refresh_from_disk(&delta).is_err());
        assert_eq!(
            app.board.column_cards(0).len(),
            1,
            "a malformed file must not wipe the board"
        );
    }

    /// An external edit of one issue must not re-read the whole tree: after a
    /// delta, the corpus is exactly a rebuild over the files on disk.
    #[test]
    fn incremental_refresh_matches_a_full_corpus_rebuild() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(dir.join("alice")).unwrap();
        write_issue(&dir, "alice/2026-01-01-a.md", 1, "A", "todo", None);
        write_issue(&dir, "2026-01-02-b.md", 2, "B", "todo", None);
        app.refresh_corpus().unwrap();
        let mut watcher = crate::watcher::FsWatcher::new(&dir);

        write_issue(&dir, "alice/2026-01-01-a.md", 1, "A changed", "done", None);
        write_issue(&dir, "2026-01-03-c.md", 3, "C", "in progress", None);
        fs::remove_file(dir.join("2026-01-02-b.md")).unwrap();
        let delta = watcher.poll().expect("the burst is reported");
        app.refresh_from_disk(&delta).unwrap();

        let rebuilt = crate::search::Corpus::build(&app.store).unwrap();
        let incremental: Vec<(u32, String)> = app
            .corpus
            .issues
            .iter()
            .map(|i| (i.number, i.title.clone()))
            .collect();
        let expected: Vec<(u32, String)> = rebuilt
            .issues
            .iter()
            .map(|i| (i.number, i.title.clone()))
            .collect();
        assert_eq!(incremental, expected);
        assert_eq!(app.corpus.texts, rebuilt.texts);
    }

    /// With the archived toggle off, an external archive leaves the active
    /// board instead of adding the archived file to it.
    #[test]
    fn external_archive_leaves_the_active_board() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(dir.join("alice")).unwrap();
        write_issue(&dir, "alice/2026-01-01-a.md", 1, "A", "todo", None);
        app.refresh_corpus().unwrap();
        assert_eq!(app.board.column_cards(0).len(), 1);
        let mut watcher = crate::watcher::FsWatcher::new(&dir);

        // The archived marker is the leading dot of the file name (#1492).
        fs::rename(
            dir.join("alice/2026-01-01-a.md"),
            dir.join("alice/.2026-01-01-a.md"),
        )
        .unwrap();
        let delta = watcher.poll().expect("the rename is reported");
        app.refresh_from_disk(&delta).unwrap();
        assert_eq!(
            app.board.column_cards(0).len(),
            0,
            "an issue archived outside `tix` leaves the active board"
        );
        assert!(
            app.corpus.issues.is_empty(),
            "the active corpus does not gain the archived file"
        );
    }

    /// A burst of writes is applied through the coalescer as **one** rebuild.
    #[test]
    fn a_coalesced_burst_rebuilds_once() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        let mut watcher = crate::watcher::FsWatcher::new(&dir);
        let mut coalescer = crate::watcher::DeltaCoalescer::default();

        let mut applies = 0;
        // Three writes, a poll after each, then a quiet poll: each distinct
        // file is a separate delta, and the first quiet tick coalesces them.
        for (i, name) in ["a.md", "b.md", "c.md"].iter().enumerate() {
            write_issue(&dir, name, i as u32 + 1, "T", "todo", None);
            assert!(
                coalescer.observe(watcher.poll()).is_none(),
                "a pending delta is not applied until the tree settles"
            );
        }
        if let Some(delta) = coalescer.observe(None) {
            applies += 1;
            app.refresh_from_disk(&delta).unwrap();
        }
        assert_eq!(applies, 1, "a burst costs exactly one rebuild");
        assert_eq!(app.board.column_cards(0).len(), 3);
        assert!(coalescer.observe(None).is_none(), "nothing is left pending");
    }

    #[test]
    fn enter_opens_detail() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
        assert!(app.detail.is_some());
    }

    #[test]
    fn n_opens_form() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert!(app.form.is_some());
    }

    fn filter_modal_focus(app: &App) -> crate::search::FilterField {
        app.filter_modal
            .as_ref()
            .expect("filter modal open")
            .focus()
    }

    #[test]
    fn filter_modal_arrows_navigate_rows() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('f'))).unwrap();
        assert!(matches!(app.mode, Mode::FilterModal));
        use crate::search::FilterField::*;
        assert_eq!(filter_modal_focus(&app), Assignee);
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        assert_eq!(filter_modal_focus(&app), Label);
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        assert_eq!(filter_modal_focus(&app), Assignee);
        // `FilterField::ALL` has **ten** rows since `Parent` was appended (WP06
        // T024), so a full lap is ten presses. Hard-coded rather than derived from
        // `ALL.len()` on purpose: a test that reads the length it is testing cannot
        // notice the length changing, which is exactly what happened here — the
        // loop was `0..9` and the wrap assertion then failed.
        for _ in 0..crate::search::FilterField::ALL.len() {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        assert_eq!(filter_modal_focus(&app), Assignee, "Down wraps forward");
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        assert_eq!(
            filter_modal_focus(&app),
            Category,
            "Up wraps backward, to the last row — which is now `Category` (WP08 \
             appended it after `Parent`)"
        );
    }

    #[test]
    fn filter_modal_arrow_press_keeps_criterion_value() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('f'))).unwrap();
        for c in "alice".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let before = app
            .filter_modal
            .as_ref()
            .unwrap()
            .active_filter()
            .assignee
            .clone();
        assert_eq!(before.as_deref(), Some("alice"));
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let after = app
            .filter_modal
            .as_ref()
            .unwrap()
            .active_filter()
            .assignee
            .clone();
        assert_eq!(after, before, "arrow press must not alter the value");
        use crate::search::FilterField::*;
        assert_eq!(filter_modal_focus(&app), Label);
    }

    #[test]
    fn filter_modal_j_and_k_type_their_letters() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('f'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('k'))).unwrap();
        let modal = app.filter_modal.as_ref().unwrap();
        assert_eq!(
            modal.active_filter().assignee.as_deref(),
            Some("jk"),
            "j and k must type into the focused criterion, not navigate"
        );
        use crate::search::FilterField::*;
        assert_eq!(modal.focus(), Assignee);
    }

    #[test]
    fn filter_modal_date_field_masked_typing_and_picker() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('f'))).unwrap();
        use crate::search::FilterField::*;
        for _ in 0..7 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        assert_eq!(filter_modal_focus(&app), StartDate);

        // Enter on an empty date criterion opens the picker.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::FilterModal));

        // Typing digits edits the criterion in place with the mask.
        for c in "20260910".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(
            app.filter_modal
                .as_ref()
                .unwrap()
                .active_filter()
                .start_date
                .as_deref(),
            Some("2026-09-10")
        );

        // Enter on a complete date commits the filter.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert_eq!(app.structured.start_date.as_deref(), Some("2026-09-10"));
    }

    #[test]
    fn d_opens_confirm_delete() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        let _ = app.handle_key(press(KeyCode::Char('d'))).unwrap();
        assert!(matches!(app.mode, Mode::ConfirmDelete));
        assert!(app.confirm_delete_target.is_some());
    }

    #[test]
    fn move_to_done_triggers_commit_prompt() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        // issue sits in "in review" (0-indexed column 2), target is "done" (3)
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "in review", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.board.select_column(2);
        app.board.selected = 0;

        let _ = app.handle_key(press(KeyCode::Char('>'))).unwrap();
        // Moving to done without a commit opens the hash prompt
        assert!(
            matches!(
                &app.mode,
                Mode::MoveIntoDone { target_col: 3, buffer } if buffer.is_empty()
            ),
            "expected MoveIntoDone, got {:?}",
            app.mode
        );

        // Esc cancels the prompt and keeps the status unchanged
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        let issue = app
            .store
            .get(crate::storage::IssueSelector::Filename(
                "2026-01-01-a.md".into(),
            ))
            .unwrap();
        assert_eq!(issue.status.display(), "in review");
        assert!(issue.commit.is_none());
    }

    #[test]
    fn move_into_done_with_commit_applies() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "in review", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.board.select_column(2);
        app.board.selected = 0;

        let _ = app.handle_key(press(KeyCode::Char('>'))).unwrap();
        assert!(matches!(&app.mode, Mode::MoveIntoDone { .. }));

        for c in "abc123".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(matches!(app.mode, Mode::Board));
        let issue = app
            .store
            .get(crate::storage::IssueSelector::Filename(
                "2026-01-01-a.md".into(),
            ))
            .unwrap();
        assert_eq!(issue.status.display(), "done");
        assert_eq!(issue.commit.as_deref(), Some("abc123"));
    }

    #[test]
    fn move_into_done_with_empty_commit_moves_without_hash() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "in review", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.board.select_column(2);
        app.board.selected = 0;

        let _ = app.handle_key(press(KeyCode::Char('>'))).unwrap();
        assert!(matches!(&app.mode, Mode::MoveIntoDone { .. }));
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(matches!(app.mode, Mode::Board));
        let issue = app
            .store
            .get(crate::storage::IssueSelector::Filename(
                "2026-01-01-a.md".into(),
            ))
            .unwrap();
        assert_eq!(issue.status.display(), "done");
        assert!(
            issue.commit.is_none(),
            "no commit recorded when moving to done without a hash"
        );
    }

    #[test]
    fn move_out_of_done_clears_commit() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "done", Some("abc123"));
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.board.select_column(3);
        app.board.selected = 0;

        let _ = app.handle_key(press(KeyCode::Char('<'))).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        let issue = app
            .store
            .get(crate::storage::IssueSelector::Filename(
                "2026-01-01-a.md".into(),
            ))
            .unwrap();
        assert_eq!(issue.status.display(), "in review");
        assert!(issue.commit.is_none());
    }

    #[test]
    fn move_right_wraps_across_real_columns_skipping_mismatch() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "done", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.board.select_column(3); // done (last real column)
        app.board.selected = 0;
        let _ = app.handle_key(press(KeyCode::Char('>'))).unwrap();
        assert_eq!(app.board.active_col, 0);
        let issue = app
            .store
            .get(crate::storage::IssueSelector::Filename(
                "2026-01-01-a.md".into(),
            ))
            .unwrap();
        assert_eq!(issue.status.display(), "todo");
    }

    #[test]
    fn move_left_wraps_across_real_columns_skipping_mismatch() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", Some("abc"));
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.board.select_column(0);
        app.board.selected = 0;
        let _ = app.handle_key(press(KeyCode::Char('<'))).unwrap();
        assert_eq!(app.board.active_col, 3);
        let issue = app
            .store
            .get(crate::storage::IssueSelector::Filename(
                "2026-01-01-a.md".into(),
            ))
            .unwrap();
        assert_eq!(issue.status.display(), "done");
    }

    #[test]
    fn move_left_right_board() {
        let (_tmp, mut app) = make_app();
        let initial = app.board.active_col;
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(app.board.active_col, initial + 1);
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        assert_eq!(app.board.active_col, initial);
    }

    #[test]
    fn refresh_rebuilds_board() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let _ = app.handle_key(press(KeyCode::Char('r'))).unwrap();
        assert_eq!(app.board.column_cards(0).len(), 1);
        assert_eq!(app.status_msg, Some("Refreshed".to_string()));
    }

    #[test]
    fn detail_esc_back_to_board() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert!(app.detail.is_none());
    }

    #[test]
    fn confirm_delete_y_removes_issue() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        let _ = app.handle_key(press(KeyCode::Char('d'))).unwrap();
        assert!(matches!(app.mode, Mode::ConfirmDelete));
        let _ = app.handle_key(press(KeyCode::Char('y'))).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        assert_eq!(app.board.column_cards(0).len(), 0);
    }

    #[test]
    fn confirm_delete_n_cancels() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        let _ = app.handle_key(press(KeyCode::Char('d'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert!(app.confirm_delete_target.is_none());
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        assert_eq!(app.board.column_cards(0).len(), 1);
    }

    #[test]
    fn form_submit_creates_issue() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        if let Mode::Form = &app.mode {
            // Type title
            for c in "My Issue".chars() {
                let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
            }
            // Submit
            let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        }
        assert!(matches!(app.mode, Mode::Board));
        assert!(
            app.status_msg
                .as_deref()
                .is_some_and(|m| m.starts_with("Created ")),
            "got {:?}",
            app.status_msg
        );
    }

    #[test]
    fn form_submit_selects_created_issue() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        if let Mode::Form = &app.mode {
            for c in "Selected Issue".chars() {
                let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
            }
            let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        }
        assert!(matches!(app.mode, Mode::Board));
        let card = app.board.get_selected_card().expect("selected card");
        assert_eq!(card.title, "Selected Issue");
        assert_eq!(app.board.active_col, 0);
    }

    #[test]
    fn form_submit_selects_created_issue_in_assignee_segment() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "Old", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());

        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        if let Mode::Form = &app.mode {
            for c in "New".chars() {
                let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
            }
        }
        app.form.as_mut().unwrap().assignee = "alice".to_string();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(matches!(app.mode, Mode::Board));
        let card = app.board.get_selected_card().expect("selected card");
        assert_eq!(
            card.title, "New",
            "the just-created issue is selected, not the previously selected one"
        );
        assert!(card.filename.starts_with("alice/"), "got {}", card.filename);
    }

    #[test]
    fn editor_return_warns_on_invalid_issue() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        if let Mode::Form = &app.mode {
            for c in "Lint Warn".chars() {
                let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
            }
            let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        }
        let issue = app
            .board
            .get_selected_card()
            .cloned()
            .expect("selected issue");
        let path = app.store.issues_dir.join(&issue.filename);
        let mut text = std::fs::read_to_string(&path).unwrap();
        // Rewrite whatever the form actually wrote, rather than assuming it is
        // `medium`. The form seeds `priority: String::new()`, so the previous
        // `replace("priority: medium", …)` was a no-op, the issue was never made
        // invalid, and the test asserted a warning that had nothing to warn
        // about. It passed for the wrong reason and would have kept passing after
        // the form changed again.
        let before = text.clone();
        text = text
            .lines()
            .map(|l| {
                if l.starts_with("priority:") {
                    "priority: strange"
                } else {
                    l
                }
            })
            .collect::<Vec<_>>()
            .join("\n");
        assert_ne!(
            text, before,
            "the fixture must actually change the priority"
        );
        std::fs::write(&path, text).unwrap();

        app.after_editor(&issue.filename);

        assert!(matches!(app.mode, Mode::EditRepair { .. }));
        assert!(
            matches!(&app.mode, Mode::EditRepair { key: None, .. }),
            "an invalid priority is not an undeclared key: {:?}",
            app.mode
        );
    }

    /// An issue whose frontmatter carries a top-level key tix does not know — the
    /// shape an editor leaves behind when a user adds their own metadata (#1506).
    fn write_issue_with_custom_key(dir: &std::path::Path, name: &str, key: &str) {
        write_issue(dir, name, 1, "A", "todo", None);
        let path = dir.join(name);
        let text = std::fs::read_to_string(&path).unwrap();
        let text = text.replace("labels: []\n", &format!("labels: []\n{key}: \"ci-4471\"\n"));
        std::fs::write(&path, text).unwrap();
    }

    /// A hand-built repair prompt, for the tests that exercise the *view* rather
    /// than a round trip: no classified problems, no retained copy.
    fn repair_mode(message: &str, key: Option<&str>) -> Mode {
        Mode::EditRepair {
            filename: "2026-01-01-a.md".to_string(),
            message: message.to_string(),
            key: key.map(str::to_string),
            problems: Vec::new(),
            temp: None,
            written: true,
            discard_armed: false,
        }
    }

    /// #1506, the "discard" half: the warning is a **report**, so the editor's
    /// custom key is on disk before the warning is even computed — and must still
    /// be there afterwards.
    #[test]
    fn editor_return_preserves_an_unknown_key_and_warns_with_it() {
        let (_tmp, mut app) = make_app();
        let dir = app.store.issues_dir.clone();
        write_issue_with_custom_key(&dir, "2026-01-01-a.md", "build_id");

        app.after_editor("2026-01-01-a.md");

        let on_disk = std::fs::read_to_string(dir.join("2026-01-01-a.md")).unwrap();
        assert!(
            on_disk.contains("build_id: \"ci-4471\""),
            "the edit warning must not discard the custom key it warns about:\n{on_disk}"
        );
        match &app.mode {
            Mode::EditRepair { key, .. } => assert_eq!(
                key.as_deref(),
                Some("build_id"),
                "the warning carries the key `a` can declare"
            ),
            other => panic!("expected the edit warning, got {other:?}"),
        }
    }

    /// #1506, the "offer" half: `a` declares the key in `tix.toml`, and the file
    /// stops warning about it.
    #[test]
    fn accepting_the_edit_warning_declares_the_key_and_the_file_lints_clean() {
        let (tmp, mut app) = make_app();
        let dir = app.store.issues_dir.clone();
        write_issue_with_custom_key(&dir, "2026-01-01-a.md", "build_id");
        app.after_editor("2026-01-01-a.md");
        assert!(matches!(app.mode, Mode::EditRepair { .. }));

        let action = app.handle_key(press(KeyCode::Char('a'))).unwrap();

        assert_eq!(action, Action::None);
        assert!(
            matches!(app.mode, Mode::Board),
            "accepting closes the warning: {:?}",
            app.mode
        );
        assert_eq!(
            app.status_msg.as_deref(),
            Some("declared `build_id` in [custom_attributes] in tix.toml")
        );
        // The write left a config that loads, with exactly the new entry in it.
        let reloaded = Config::load_with_warning(&tmp.path().join("tix.toml"), |_| {}).unwrap();
        assert_eq!(
            reloaded.custom_attributes.keys,
            vec!["build_id".to_string()]
        );
        // …and re-linting the file no longer reports the key.
        let findings =
            crate::commands::lint::collect_file(&app.store.config, &app.store, "2026-01-01-a.md")
                .unwrap();
        assert!(
            findings.iter().all(|f| f.kind != "unknown_key"),
            "the declared key must stop warning: {findings:?}"
        );
    }

    /// `y` is `confirm`'s chord everywhere else, so it accepts here too — a key
    /// that says yes on every other prompt must not do nothing on this one.
    #[test]
    fn the_confirm_chord_also_accepts_the_edit_warning() {
        let (_tmp, mut app) = make_app();
        let dir = app.store.issues_dir.clone();
        write_issue_with_custom_key(&dir, "2026-01-01-a.md", "build_id");
        app.after_editor("2026-01-01-a.md");

        let _ = app.handle_key(press(KeyCode::Char('y'))).unwrap();

        assert!(matches!(app.mode, Mode::Board));
        assert_eq!(app.store.config.custom_attributes.keys, vec!["build_id"]);
    }

    /// The declaration is idempotent: re-accepting an already-declared key — and
    /// the same key in another case, which `custom_attributes()` folds — adds no
    /// second row.
    #[test]
    fn declaring_the_same_key_again_does_not_duplicate_it() {
        let (tmp, mut app) = make_app();
        let dir = app.store.issues_dir.clone();
        write_issue_with_custom_key(&dir, "2026-01-01-a.md", "build_id");
        app.after_editor("2026-01-01-a.md");
        let _ = app.handle_key(press(KeyCode::Char('a'))).unwrap();

        for key in ["build_id", "BUILD_ID"] {
            app.mode = repair_mode("unknown_key: already handled", Some(key));
            let _ = app.handle_key(press(KeyCode::Char('a'))).unwrap();
        }

        let reloaded = Config::load_with_warning(&tmp.path().join("tix.toml"), |_| {}).unwrap();
        assert_eq!(
            reloaded.custom_attributes.keys,
            vec!["build_id".to_string()]
        );
    }

    /// Only an undeclared key is declarable. Every other finding leaves `key`
    /// `None`, and `a` says there is nothing to declare instead of writing an
    /// entry that would silence nothing.
    #[test]
    fn a_finding_that_is_not_an_unknown_key_has_nothing_to_declare() {
        let (tmp, mut app) = make_app();
        let dir = app.store.issues_dir.clone();
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let path = dir.join("2026-01-01-a.md");
        let text = std::fs::read_to_string(&path)
            .unwrap()
            .replace("priority: \"medium\"", "priority: \"strange\"");
        std::fs::write(&path, text).unwrap();

        app.after_editor("2026-01-01-a.md");
        match &app.mode {
            Mode::EditRepair { key, .. } => assert!(
                key.is_none(),
                "only an undeclared frontmatter key is declarable, got {key:?}"
            ),
            other => panic!("expected the edit warning, got {other:?}"),
        }

        let action = app.handle_key(press(KeyCode::Char('a'))).unwrap();

        assert_eq!(action, Action::None);
        assert!(matches!(app.mode, Mode::Board));
        assert!(
            app.status_msg
                .as_deref()
                .is_some_and(|m| m.contains("nothing to declare")),
            "got {:?}",
            app.status_msg
        );
        let reloaded = Config::load_with_warning(&tmp.path().join("tix.toml"), |_| {}).unwrap();
        assert!(
            reloaded.custom_attributes.keys.is_empty(),
            "a finding that is not an unknown key must not write a declaration"
        );
    }

    /// The warning view advertises the fix only where there is one, and names the
    /// chord the effective keymap actually binds.
    #[test]
    fn the_edit_warning_offers_to_declare_only_when_there_is_a_key() {
        let (_tmp, mut app) = make_app();
        app.mode = repair_mode(
            "unknown_key: unknown top-level frontmatter key `build_id`",
            Some("build_id"),
        );
        let chord = app
            .bindings
            .label(InputContext::EditRepair, TuiAction::Confirm);
        // A roomy terminal and a minimum-size one: an offer only the largest
        // terminal can show is an offer most users never see, so the modal must
        // not push it off the bottom — or clip it off the right edge — at 80x24.
        for (w, h) in [(100u16, 30u16), (80, 24)] {
            let text = cells_to_text(&draw_board(&app, w, h), w, h);
            assert!(
                text.contains(&chord),
                "the offer names the effective chord `{chord}` at {w}x{h}:\n{text}"
            );
            assert!(
                text.contains("declare `build_id`") && text.contains("[custom_attributes]"),
                "the warning must offer the fix it can apply, at {w}x{h}:\n{text}"
            );
        }

        app.mode = repair_mode(
            "priority: valid options: '' (unset), low, medium, high",
            None,
        );
        let text = cells_to_text(&draw_board(&app, 100, 30), 100, 30);
        assert!(
            !text.contains("declare"),
            "a finding with no key must not offer a declaration:\n{text}"
        );
        assert!(
            text.contains("re-edit") && text.contains("ignore"),
            "the other keys stay exactly as they were:\n{text}"
        );
    }

    /// #1510 — the editor round trip against a write that lands while the editor
    /// is open.
    ///
    /// The editor is a real `/bin/sh` script pointed at by the config's `editor`
    /// setting, as the CLI's editor test does: the temp copy, the pre-edit
    /// snapshot, and the concurrency this ticket is about all live *outside* the
    /// key handler, so only a real round trip can exercise them.
    #[cfg(unix)]
    mod edit_conflict {
        use super::*;
        use std::os::unix::fs::PermissionsExt;

        /// The edit the "user" makes in the editor: the temp copy `$1` goes from the
        /// fixture's `medium` to `high`.
        ///
        /// The pattern is **unquoted** on purpose: the temp copy is not the raw
        /// fixture — it is `Issue::to_file_contents`, tix's own canonical form, which
        /// writes `priority: medium`. The concurrent writer edits the raw issue file
        /// instead, and that one *is* the fixture's quoted text.
        const USER_EDIT: &str = r#"sed -i 's/priority: medium/priority: high/' "$1""#;

        /// Point the app's editor at a fresh `sh` script and return the script's
        /// path. `$1` is the temp copy the round trip hands the editor.
        ///
        /// The script is written by a **child** `sh`, not by this process. A write
        /// descriptor this process holds — even briefly, even if `fs::write` has
        /// already returned — is inherited by any child another test thread forks,
        /// and the next `exec` of that file then fails with `ETXTBSY` ("Text file
        /// busy"). That is a real flake in a parallel test binary, and never holding
        /// the descriptor here is the fix.
        pub(super) fn script(
            app: &mut App,
            tmp: &TempDir,
            name: &str,
            body: &str,
        ) -> std::path::PathBuf {
            use std::io::Write as _;

            let path = tmp.path().join(name);
            let full = format!("#!/bin/sh\n{body}\n");
            let mut writer = std::process::Command::new("sh")
                .args(["-c", "cat > \"$1\"", "sh"])
                .arg(&path)
                .stdin(std::process::Stdio::piped())
                .spawn()
                .expect("spawn the script writer");
            writer
                .stdin
                .take()
                .expect("the writer's stdin is piped")
                .write_all(full.as_bytes())
                .expect("write the script body");
            assert!(
                writer.wait().expect("wait for the script writer").success(),
                "the script writer failed"
            );
            fs::set_permissions(&path, fs::Permissions::from_mode(0o755)).unwrap();
            app.store.config.editor = Some(path.to_string_lossy().to_string());
            path
        }

        /// The temp copy issue `number` gets, with any stale file removed first.
        /// Every test in this binary shares one process id, so the issue number is
        /// what keeps two tests off each other's path.
        pub(super) fn temp_for(number: u32) -> std::path::PathBuf {
            let path =
                std::env::temp_dir().join(format!("tix-edit-{}-{number}.md", std::process::id()));
            let _ = fs::remove_file(&path);
            path
        }

        /// The fixture every decision test starts from: an editor that makes the
        /// user's edit *and* a concurrent writer that rewrites the issue file, then
        /// the round trip run to completion. Returns the app already sitting in the
        /// conflict prompt, so the test is about what a decision does.
        fn raced_round_trip(number: u32, name: &str) -> (TempDir, App, std::path::PathBuf) {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, name, number, "Raced", "todo", None);
            let disk = dir.join(name);
            script(
                &mut app,
                &tmp,
                "editor.sh",
                &format!(
                    "{USER_EDIT}\nsed -i 's/priority: \"medium\"/priority: \"low\"/' '{}'",
                    disk.display()
                ),
            );
            let temp = temp_for(number);
            app.open_editor_round_trip(name).unwrap();
            assert!(
                matches!(app.mode, Mode::EditConflict { .. }),
                "the fixture must actually produce a conflict, got {:?}",
                app.mode
            );
            (tmp, app, temp)
        }

        /// No concurrent write: the bytes are the ones the editor was handed, so
        /// the edit is written and no conflict prompt appears.
        #[test]
        fn an_unchanged_file_writes_normally_and_never_enters_the_conflict_prompt() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
            script(&mut app, &tmp, "editor.sh", USER_EDIT);
            let temp = temp_for(1);

            app.open_editor_round_trip("2026-01-01-a.md").unwrap();

            assert!(
                matches!(app.mode, Mode::Board),
                "an unchanged file is not a conflict: {:?}",
                app.mode
            );
            // The status names the recoverable copy of the previous version
            // (#1506), so it starts with the outcome rather than being it.
            assert!(
                app.status_msg
                    .as_deref()
                    .is_some_and(|m| m.contains("Edited")),
                "got {:?}",
                app.status_msg
            );
            let on_disk = fs::read_to_string(dir.join("2026-01-01-a.md")).unwrap();
            assert!(
                on_disk.contains("priority: high"),
                "the edit is on disk:\n{on_disk}"
            );
            assert!(!temp.exists(), "the temp copy is cleaned up");
            assert!(app.pending_edit.is_none(), "the round trip is finished");
        }

        /// A concurrent write is detected and **nothing** is written: the newer
        /// file is intact, the editor's version is still the temp copy, and the
        /// prompt carries all three paths it promises.
        #[test]
        fn a_concurrent_write_enters_the_conflict_prompt_and_writes_nothing() {
            let (_tmp, app, temp) = raced_round_trip(2, "2026-01-01-b.md");
            let disk = app.store.issues_dir.join("2026-01-01-b.md");

            match &app.mode {
                Mode::EditConflict {
                    filename,
                    temp: kept,
                    disk_path,
                } => {
                    assert_eq!(filename, "2026-01-01-b.md");
                    assert_eq!(kept, &temp);
                    assert_eq!(disk_path, &disk);
                }
                other => panic!("expected the conflict prompt, got {other:?}"),
            }
            assert!(
                temp.is_file(),
                "the editor's version must survive for the prompt to decide about"
            );
            let on_disk = fs::read_to_string(&disk).unwrap();
            assert!(
                on_disk.contains(r#"priority: "low""#),
                "the concurrent write must not be clobbered:\n{on_disk}"
            );
            assert!(
                !on_disk.contains(r#"priority: "high""#),
                "nothing of the editor's version may be written:\n{on_disk}"
            );
            assert!(
                app.status_msg
                    .as_deref()
                    .is_some_and(|m| m.contains("changed on disk")),
                "got {:?}",
                app.status_msg
            );
            // The prompt deliberately keeps the editor's copy — that is the point of
            // it — so a test that stops here owns the cleanup.
            let _ = fs::remove_file(&temp);
        }

        /// Override is the one outcome that writes, and it writes the editor's
        /// version — the user has already been told which file changed.
        #[test]
        fn overriding_writes_the_editors_version_and_removes_the_temp_copy() {
            let (_tmp, mut app, temp) = raced_round_trip(3, "2026-01-01-c.md");
            let disk = app.store.issues_dir.join("2026-01-01-c.md");

            let action = app.handle_key(press(KeyCode::Char('o'))).unwrap();

            assert_eq!(action, Action::None);
            assert!(
                matches!(app.mode, Mode::Board),
                "override returns to the board: {:?}",
                app.mode
            );
            assert!(
                app.status_msg
                    .as_deref()
                    .is_some_and(|m| m.contains("Overrode")),
                "the status says what happened: {:?}",
                app.status_msg
            );
            let on_disk = fs::read_to_string(&disk).unwrap();
            assert!(
                on_disk.contains("priority: high"),
                "the editor's version wins:\n{on_disk}"
            );
            assert!(!temp.exists(), "the temp copy is consumed by the write");
        }

        /// `Esc` is the safe default the prompt promises, and `a` is its spelled
        /// out chord; both keep the newer on-disk version and discard the edit.
        #[test]
        fn abandoning_keeps_the_on_disk_version_and_removes_the_temp_copy() {
            for (number, key) in [(4u32, KeyCode::Esc), (5, KeyCode::Char('a'))] {
                let name = format!("2026-01-01-{number}.md");
                let (_tmp, mut app, temp) = raced_round_trip(number, &name);
                let disk = app.store.issues_dir.join(&name);

                let action = app.handle_key(press(key)).unwrap();

                assert_eq!(action, Action::None, "{key:?}");
                assert!(matches!(app.mode, Mode::Board), "{key:?}: {:?}", app.mode);
                let on_disk = fs::read_to_string(&disk).unwrap();
                assert!(
                    on_disk.contains(r#"priority: "low""#),
                    "{key:?} keeps the concurrent write:\n{on_disk}"
                );
                assert!(!temp.exists(), "{key:?}: the temp copy is discarded");
                assert!(
                    app.status_msg
                        .as_deref()
                        .is_some_and(|m| m.contains("kept the version")),
                    "{key:?}: got {:?}",
                    app.status_msg
                );
            }
        }

        /// Compare opens the editor again **on the temp copy** and comes back to
        /// the same prompt — the second look is not a decision.
        #[test]
        fn comparing_reopens_the_editor_on_the_temp_copy_and_keeps_it() {
            let (tmp, mut app, temp) = raced_round_trip(6, "2026-01-01-f.md");
            let runs = tmp.path().join("runs.txt");
            // The second look edits the temp copy only and records that it ran.
            script(
                &mut app,
                &tmp,
                "compare.sh",
                &format!(
                    "printf 'run\\n' >> '{}'\nprintf 'compared\\n' >> \"$1\"",
                    runs.display()
                ),
            );

            let action = app.handle_key(press(KeyCode::Char('c'))).unwrap();
            assert_eq!(
                action,
                Action::CompareEdit,
                "the editor needs the terminal, so the key hands it to the event loop"
            );

            app.compare_conflicting_edit().unwrap();

            assert!(
                matches!(app.mode, Mode::EditConflict { .. }),
                "compare returns to the same prompt: {:?}",
                app.mode
            );
            assert!(temp.is_file(), "the temp copy survives a look");
            let temp_text = fs::read_to_string(&temp).unwrap();
            assert!(
                temp_text.contains("compared"),
                "the editor ran on the temp copy:\n{temp_text}"
            );
            assert_eq!(
                fs::read_to_string(&runs).unwrap().lines().count(),
                1,
                "and it ran exactly once"
            );
            // Same again: the prompt is still open and still holds the copy.
            let _ = fs::remove_file(&temp);
        }

        /// The disk state is re-read around the compare run, so a write that lands
        /// *while* the user compares is detected too.
        #[test]
        fn a_second_change_while_comparing_is_detected_too() {
            let (tmp, mut app, temp) = raced_round_trip(7, "2026-01-01-g.md");
            let disk = app.store.issues_dir.join("2026-01-01-g.md");
            // The concurrent writer is busy too: the compare run rewrites the file
            // again, as `raced_round_trip` left it at `low`.
            script(
                &mut app,
                &tmp,
                "compare.sh",
                &format!(
                    "sed -i 's/priority: \"low\"/priority: \"medium\"/' '{}'",
                    disk.display()
                ),
            );

            app.compare_conflicting_edit().unwrap();

            assert!(matches!(app.mode, Mode::EditConflict { .. }));
            assert!(
                app.status_msg
                    .as_deref()
                    .is_some_and(|m| m.contains("again")),
                "the second change must be named: {:?}",
                app.status_msg
            );
            // The prompt is still open, so its copy is the test's to remove.
            let _ = fs::remove_file(&temp);
        }

        /// The rendered rows with runs of whitespace collapsed, so an assertion is
        /// about the text rather than about where the wrap happened to fall: the
        /// modal is three quarters of the *board* area (the mode navigation takes a
        /// column), which is narrower than the terminal. The box-drawing characters
        /// between panes are spaces for the same reason — a wrapped line has a
        /// border in the middle of it in the cell grid.
        fn flattened(text: &str) -> String {
            text.replace(['│', '─', '┌', '┐', '└', '┘'], " ")
                .split_whitespace()
                .collect::<Vec<_>>()
                .join(" ")
        }

        /// The prompt states what happened, names both files, and offers the three
        /// decisions with the chords the effective keymap binds.
        #[test]
        fn the_conflict_prompt_names_its_three_choices_and_both_files() {
            let (_tmp, mut app) = make_app();
            let temp = std::path::PathBuf::from("/tmp/tix-edit-1-42.md");
            let disk_path = std::path::PathBuf::from("/tmp/store/issues/2026-01-01-prompt.md");
            app.mode = Mode::EditConflict {
                filename: "2026-01-01-prompt.md".to_string(),
                temp: temp.clone(),
                disk_path: disk_path.clone(),
            };
            let hints = [
                "overwrite the file with this edit",
                "keep the on-disk version",
                "compare in the editor",
            ];
            let actions = [TuiAction::Confirm, TuiAction::Ignore, TuiAction::Reedit];

            // Roomy: the full chord label and both paths are visible.
            let text = flattened(&cells_to_text(&draw_board(&app, 100, 30), 100, 30));
            assert!(text.contains("Edit Conflict"), "{text}");
            assert!(text.contains("2026-01-01-prompt.md"), "{text}");
            assert!(
                text.contains(&temp.display().to_string()),
                "the editor's copy must be named where the user can open it:\n{text}"
            );
            assert!(
                text.contains(&disk_path.display().to_string()),
                "and so must the newer file:\n{text}"
            );
            for (action, hint) in actions.iter().zip(hints) {
                let chord = app.bindings.label(InputContext::EditConflict, *action);
                assert!(
                    text.contains(&chord),
                    "the prompt names the effective chord `{chord}`:\n{text}"
                );
                assert!(text.contains(hint), "`{chord}` says what it does:\n{text}");
            }

            // Minimum size: the offers must survive it, or the prompt is a prompt
            // most users never see.
            let text = flattened(&cells_to_text(&draw_board(&app, 80, 24), 80, 24));
            assert!(text.contains("2026-01-01-prompt.md"), "{text}");
            assert!(text.contains(&temp.display().to_string()), "{text}");
            for hint in hints {
                assert!(
                    text.contains(hint),
                    "`{hint}` must survive an 80x24 terminal:\n{text}"
                );
            }
        }
    }

    /// The repair prompt (tix #1506): the data-loss bug, the never-discard
    /// guarantee, and each classified fix.
    #[cfg(unix)]
    mod edit_repair {
        use super::edit_conflict::{script, temp_for};
        use super::*;
        use crate::edit_problems::EditProblemKind;

        /// An editor script that leaves the temp copy unparsable.
        const BREAK: &str = r#"sed -i 's/priority: medium/priority: [broken/' "$1""#;

        /// An issue with a `## History` section in the middle of its body, where
        /// the parser treats it as prose (the dangerous shape #1506 quotes).
        fn write_issue_with_misplaced_history(dir: &std::path::Path, name: &str, number: u32) {
            let contents = format!(
                "---\nnumber: {number}\ntitle: \"Hist\"\nstatus: \"todo\"\nlabels: []\n\
                 priority: \"medium\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\n\
                 Some prose.\n\n## History\n\n\
                 - 2026-01-01T00:00:00Z \u{2014} alice \u{2014} created \u{2014} did it\n\
                 - 2026-01-02T00:00:00Z \u{2014} bob \u{2014} edited \u{2014} then this\n"
            );
            fs::write(dir.join(name), contents).unwrap();
        }

        /// tix #1506: a `[custom_attributes]` added to `tix.toml` while the TUI is
        /// open must be honoured by the very next editor return. Linting against
        /// the startup copy reports a false `unknown_key` for a key the user has
        /// just declared — and the declare-fix would then rewrite `tix.toml` from
        /// that stale copy.
        #[test]
        fn an_editor_return_adopts_a_tix_toml_that_gained_custom_attributes() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-t.md", 31, "T", "todo", None);

            // Declare the key the way a user would: edit `tix.toml` by hand while
            // the session is running.
            let config_path = app.store.config_path().unwrap();
            let mut text = fs::read_to_string(&config_path).unwrap();
            text.push_str("\n[custom_attributes]\nkeys = [\"build_id\"]\n");
            fs::write(&config_path, text).unwrap();

            // The edit introduces exactly that key.
            script(
                &mut app,
                &tmp,
                "add-type.sh",
                r#"cat > "$1" <<'ISSUE'
---
number: 31
title: "T"
status: todo
build_id: story
labels: []
priority: medium
created: 2026-01-01
updated: 2026-01-01
---
ISSUE"#,
            );
            app.open_editor_round_trip("2026-01-01-t.md").unwrap();

            assert!(
                !matches!(app.mode, Mode::EditRepair { .. }),
                "a declared key must not raise the repair prompt, got {:?}",
                app.mode
            );
            let written = fs::read_to_string(dir.join("2026-01-01-t.md")).unwrap();
            assert!(written.contains("build_id: story"), "{written}");
            assert!(
                app.store
                    .config
                    .custom_attributes()
                    .contains(&"build_id".to_string()),
                "the reloaded configuration declares the key"
            );
            assert!(app.config_snapshot.is_some(), "the snapshot advanced");
        }

        /// A `tix.toml` that does not load is reported, the previous configuration
        /// stands, and the snapshot is **not** advanced, so a half-saved file is
        /// retried rather than latched.
        #[test]
        fn a_broken_tix_toml_is_reported_and_the_previous_config_is_kept() {
            let (_tmp, mut app) = make_app();
            let config_path = app.store.config_path().unwrap();
            let before = app.store.config.clone();
            let startup_bytes = app.config_snapshot.clone();
            fs::write(&config_path, "this is not = = toml\n").unwrap();

            assert!(
                !app.reload_config_if_changed(),
                "a broken file is not adopted"
            );
            assert_eq!(
                app.store.config, before,
                "the previous configuration stands"
            );
            assert!(
                app.status_msg
                    .as_deref()
                    .unwrap_or_default()
                    .contains("tix.toml"),
                "and it says so: {:?}",
                app.status_msg
            );
            assert_eq!(
                app.config_snapshot, startup_bytes,
                "the snapshot did not advance, so a fixed file is picked up later"
            );
        }

        /// The reported bug: an edit that makes the file unparsable enters the
        /// prompt with the **real** diagnostic, writes nothing, and leaves the
        /// temp copy in place.
        #[test]
        fn an_unparsable_edit_enters_repair_with_the_real_diagnostic_and_writes_nothing() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-h.md", 21, "H", "todo", None);
            script(&mut app, &tmp, "break.sh", BREAK);
            let temp = temp_for(21);
            let before = fs::read_to_string(dir.join("2026-01-01-h.md")).unwrap();

            app.open_editor_round_trip("2026-01-01-h.md").unwrap();

            let problems = match &app.mode {
                Mode::EditRepair {
                    problems,
                    temp: kept,
                    written,
                    ..
                } => {
                    assert_eq!(
                        kept.as_deref(),
                        Some(temp.as_path()),
                        "the copy is retained"
                    );
                    assert!(!written, "nothing has been written yet");
                    problems.clone()
                }
                other => panic!("expected the repair prompt, got {other:?}"),
            };
            assert!(temp.is_file(), "the editor's copy must survive");
            assert!(
                problems
                    .iter()
                    .any(|p| p.kind == EditProblemKind::Unparsable),
                "{problems:?}"
            );
            let summary: String = problems
                .iter()
                .map(|p| p.message.clone())
                .collect::<Vec<_>>()
                .join(" | ");
            assert!(
                !summary.contains("file not valid after edit"),
                "the generic message is the bug: {summary}"
            );
            assert!(
                summary.contains("priority") && summary.contains("invalid type"),
                "the real parse diagnostic must reach the user: {summary}"
            );
            assert_eq!(
                fs::read_to_string(dir.join("2026-01-01-h.md")).unwrap(),
                before,
                "an unparsable edit must write nothing"
            );
            assert!(
                app.pending_edit.is_some(),
                "the round trip stays in flight until a decision is made"
            );
            let _ = fs::remove_file(&temp);
        }

        /// `Esc` acknowledges and keeps the copy; the copy is the one thing a
        /// stray key must not destroy.
        #[test]
        fn escape_acknowledges_and_keeps_the_retained_copy() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-e.md", 22, "E", "todo", None);
            script(&mut app, &tmp, "break.sh", BREAK);
            let temp = temp_for(22);
            app.open_editor_round_trip("2026-01-01-e.md").unwrap();

            let action = app.handle_key(press(KeyCode::Esc)).unwrap();

            assert_eq!(action, Action::None);
            assert!(matches!(app.mode, Mode::Board), "{:?}", app.mode);
            assert!(
                temp.is_file(),
                "Esc acknowledges; it never removes the retained copy"
            );
            let _ = fs::remove_file(&temp);
        }

        /// Discard needs two presses, and it is the **only** thing that removes
        /// the copy.
        #[test]
        fn discard_requires_a_second_press_and_is_the_only_removal() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-d.md", 23, "D", "todo", None);
            script(&mut app, &tmp, "break.sh", BREAK);
            let temp = temp_for(23);
            app.open_editor_round_trip("2026-01-01-d.md").unwrap();

            let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
            assert!(
                matches!(
                    app.mode,
                    Mode::EditRepair {
                        discard_armed: true,
                        ..
                    }
                ),
                "{:?}",
                app.mode
            );
            assert!(temp.is_file(), "the first press only arms the discard");
            assert!(
                app.status_msg
                    .as_deref()
                    .is_some_and(|m| m.contains("again")),
                "got {:?}",
                app.status_msg
            );

            let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
            assert!(matches!(app.mode, Mode::Board), "{:?}", app.mode);
            assert!(!temp.exists(), "the confirmed discard removes the copy");
        }

        /// The history fix moves the section to the front and keeps every entry.
        #[test]
        fn the_history_fix_moves_every_entry_to_the_front_and_the_file_parses() {
            let (_tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue_with_misplaced_history(&dir, "2026-01-01-hist.md", 24);

            app.after_editor("2026-01-01-hist.md");
            assert!(
                matches!(app.mode, Mode::EditRepair { .. }),
                "{:?}",
                app.mode
            );

            let action = app.handle_key(press(KeyCode::Char('a'))).unwrap();

            assert_eq!(action, Action::None);
            assert!(matches!(app.mode, Mode::Board), "{:?}", app.mode);
            let on_disk = fs::read_to_string(dir.join("2026-01-01-hist.md")).unwrap();
            let issue = Issue::parse(&on_disk).unwrap();
            assert_eq!(
                issue.history.entries.len(),
                2,
                "both entries are recognised after the move:\n{on_disk}"
            );
            for entry in ["did it", "then this"] {
                assert!(
                    on_disk.contains(entry),
                    "`{entry}` must survive:\n{on_disk}"
                );
            }
            assert!(
                !on_disk.contains("Some prose.\n\n## History"),
                "the section is no longer body text:\n{on_disk}"
            );
            assert!(on_disk.contains("Some prose"), "{on_disk}");
        }

        /// `r` reopens the editor on the retained copy; a valid result is
        /// committed, and the copy is consumed only then.
        #[test]
        fn reedit_reopens_the_editor_on_the_retained_copy_and_commits_a_valid_file() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-r.md", 29, "R", "todo", None);
            script(&mut app, &tmp, "break.sh", BREAK);
            let temp = temp_for(29);
            app.open_editor_round_trip("2026-01-01-r.md").unwrap();
            // The second look repairs what the first broke.
            script(
                &mut app,
                &tmp,
                "fix.sh",
                r#"sed -i 's/priority: \[broken/priority: high/' "$1""#,
            );
            assert_eq!(
                app.handle_key(press(KeyCode::Char('r'))).unwrap(),
                Action::ReeditRepair
            );
            app.reedit_repair().unwrap();

            assert!(matches!(app.mode, Mode::Board), "{:?}", app.mode);
            let on_disk = fs::read_to_string(dir.join("2026-01-01-r.md")).unwrap();
            let issue = Issue::parse(&on_disk).unwrap();
            assert_eq!(issue.priority, crate::model::Priority::High);
            assert!(!temp.exists(), "the copy is consumed once the edit lands");
            assert!(app.pending_edit.is_none());
        }

        /// A lost title is reported, not written over, and the fix restores the
        /// pre-edit title.
        #[test]
        fn the_missing_title_fix_restores_the_pre_edit_title() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-t.md", 28, "Original", "todo", None);
            script(
                &mut app,
                &tmp,
                "untitle.sh",
                r#"sed -i 's/^title: .*/title: ""/' "$1""#,
            );
            let temp = temp_for(28);
            app.open_editor_round_trip("2026-01-01-t.md").unwrap();
            match &app.mode {
                Mode::EditRepair { problems, .. } => assert!(
                    problems
                        .iter()
                        .any(|p| p.kind == EditProblemKind::MissingTitle),
                    "{problems:?}"
                ),
                other => panic!("expected the repair prompt, got {other:?}"),
            }

            let _ = app.handle_key(press(KeyCode::Char('a'))).unwrap();

            assert!(matches!(app.mode, Mode::Board), "{:?}", app.mode);
            let on_disk = fs::read_to_string(dir.join("2026-01-01-t.md")).unwrap();
            assert_eq!(Issue::parse(&on_disk).unwrap().title, "Original");
            assert!(
                !temp.exists(),
                "a successful fix consumes the retained copy"
            );
        }

        /// The duplicate-key fix keeps the first value.
        #[test]
        fn the_duplicate_key_fix_keeps_the_first_value() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-dup.md", 25, "Kept", "todo", None);
            script(
                &mut app,
                &tmp,
                "dup.sh",
                r#"sed -i 's/^title: .*/&\ntitle: "Second"/' "$1""#,
            );
            let temp = temp_for(25);
            app.open_editor_round_trip("2026-01-01-dup.md").unwrap();
            match &app.mode {
                Mode::EditRepair { problems, .. } => assert!(
                    problems
                        .iter()
                        .any(|p| p.kind == EditProblemKind::DuplicateKey),
                    "{problems:?}"
                ),
                other => panic!("expected the repair prompt, got {other:?}"),
            }

            let _ = app.handle_key(press(KeyCode::Char('a'))).unwrap();

            assert!(matches!(app.mode, Mode::Board), "{:?}", app.mode);
            let on_disk = fs::read_to_string(dir.join("2026-01-01-dup.md")).unwrap();
            assert_eq!(Issue::parse(&on_disk).unwrap().title, "Kept");
            assert!(
                !temp.exists(),
                "a successful fix consumes the retained copy"
            );
        }

        /// A fix that still does not parse leaves the file and the copy
        /// untouched, and re-reports.
        #[test]
        fn a_fix_that_still_does_not_parse_leaves_the_file_untouched() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-broken.md", 27, "Broken", "todo", None);
            script(
                &mut app,
                &tmp,
                "triple.sh",
                r#"sed -i 's/^title: .*/&\ntitle: "B"\ntitle: "C"/' "$1""#,
            );
            let temp = temp_for(27);
            let disk_before = fs::read_to_string(dir.join("2026-01-01-broken.md")).unwrap();
            app.open_editor_round_trip("2026-01-01-broken.md").unwrap();
            assert!(
                matches!(app.mode, Mode::EditRepair { .. }),
                "{:?}",
                app.mode
            );
            let temp_before = fs::read_to_string(&temp).unwrap();

            let _ = app.handle_key(press(KeyCode::Char('a'))).unwrap();

            assert!(
                matches!(app.mode, Mode::EditRepair { .. }),
                "the prompt stays up: {:?}",
                app.mode
            );
            assert_eq!(
                fs::read_to_string(dir.join("2026-01-01-broken.md")).unwrap(),
                disk_before,
                "nothing is written when the fix does not repair the file"
            );
            assert_eq!(
                fs::read_to_string(&temp).unwrap(),
                temp_before,
                "the retained copy is untouched"
            );
            assert!(
                app.status_msg
                    .as_deref()
                    .is_some_and(|m| m.contains("did not make the file valid")),
                "got {:?}",
                app.status_msg
            );
            let _ = fs::remove_file(&temp);
        }

        /// Overwriting the issue leaves the previous version recoverable beside
        /// it, and the status names where.
        #[test]
        fn an_overwrite_stores_a_recoverable_copy_of_the_previous_version() {
            let (tmp, mut app) = make_app();
            let dir = app.store.issues_dir.clone();
            write_issue(&dir, "2026-01-01-b.md", 26, "B", "todo", None);
            script(
                &mut app,
                &tmp,
                "edit.sh",
                r#"sed -i 's/priority: medium/priority: high/' "$1""#,
            );
            let _ = temp_for(26);

            app.open_editor_round_trip("2026-01-01-b.md").unwrap();

            assert!(matches!(app.mode, Mode::Board), "{:?}", app.mode);
            let backup = dir.join("2026-01-01-b.md.tixbak");
            assert!(backup.is_file(), "the previous version must be recoverable");
            let previous = fs::read_to_string(&backup).unwrap();
            assert!(
                previous.contains("priority: \"medium\""),
                "the backup holds the pre-edit bytes:\n{previous}"
            );
            assert!(
                app.status_msg
                    .as_deref()
                    .is_some_and(|m| m.contains(&backup.display().to_string())),
                "the status names the backup: {:?}",
                app.status_msg
            );
        }
    }

    #[test]
    fn form_empty_title_rejected() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert_eq!(app.status_msg.as_deref(), Some("Title is required"));
    }

    #[test]
    fn form_esc_cancels() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
    }

    fn form_focus(app: &App) -> crate::ui::form::FormFocus {
        app.form.as_ref().expect("form open").focus
    }

    #[test]
    fn form_arrows_navigate_fields() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        use crate::ui::form::FormFocus::*;
        assert_eq!(form_focus(&app), Title);
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        assert_eq!(form_focus(&app), Status);
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        assert_eq!(form_focus(&app), Title);
        for _ in 0..crate::ui::form::FormFocus::RING.len() {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        assert_eq!(form_focus(&app), Title, "Down wraps forward");
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        assert_eq!(
            form_focus(&app),
            *crate::ui::form::FormFocus::RING
                .last()
                .expect("RING is non-empty"),
            "Up wraps backward, from the last field in the ring"
        );
    }

    #[test]
    fn form_j_and_k_type_their_letters() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('k'))).unwrap();
        let form = app.form.as_ref().unwrap();
        assert_eq!(form.title, "jk", "j and k must type, not navigate");
        assert_eq!(form.focus, crate::ui::form::FormFocus::Title);
    }

    #[test]
    fn form_invalid_date_order_is_rejected() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Date check".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        for _ in 0..9 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));
        let _ = app.handle_key(press(KeyCode::PageDown)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert_eq!(
            app.status_msg.as_deref(),
            Some("Due date must be >= start date")
        );
    }

    #[test]
    fn form_persists_planning_fields() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Planning fields".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        for c in "Cycle 1,Cycle 2".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        for c in "Backlog".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        for c in "alice".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        let issues = app.store.list().unwrap();
        assert_eq!(issues.len(), 1);
        let issue = &issues[0];
        assert_eq!(
            issue.cycles.as_deref(),
            Some(&["Cycle 1".to_string(), "Cycle 2".to_string()][..])
        );
        assert_eq!(
            issue.milestones.as_deref(),
            Some(&["Backlog".to_string()][..])
        );
        assert_eq!(issue.reviewer.as_deref(), Some("alice"));
        assert_eq!(issue.start_date.as_deref(), Some(today().as_str()));
        assert_eq!(issue.due_date.as_deref(), Some(today().as_str()));
    }

    #[test]
    fn form_date_field_masked_typing_and_picker() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Dated".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        for _ in 0..9 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        assert!(app.form.as_ref().unwrap().is_date_focus());

        // Enter on an empty date field opens the picker.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Form));

        // Typing digits edits the date in place with the mask.
        for c in "20260910".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(app.form.as_ref().unwrap().start_date, "2026-09-10");

        // Enter on a complete date submits the form.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        let issues = app.store.list().unwrap();
        let issue = issues
            .iter()
            .find(|i| i.title == "Dated")
            .expect("the form created the issue");
        assert_eq!(issue.start_date.as_deref(), Some("2026-09-10"));
    }

    #[test]
    fn form_date_picker_select_and_clear() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Dated".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        for _ in 0..9 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }

        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert_eq!(app.form.as_ref().unwrap().start_date, today());

        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert_eq!(
            app.form.as_ref().unwrap().start_date,
            today(),
            "Esc leaves the date unchanged"
        );

        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('c'))).unwrap();
        assert_eq!(
            app.form.as_ref().unwrap().start_date,
            "",
            "c clears the date field"
        );
    }

    /// Render the date picker once and return the center point of the day cell
    /// matching `target` (`YYYY-MM-DD`).
    fn drawn_date_picker_day(app: &App, target: &str) -> (u16, u16) {
        use ratatui::backend::TestBackend;

        let backend = TestBackend::new(app.frame_size.get().width, app.frame_size.get().height);
        let mut terminal = ratatui::Terminal::new(backend).unwrap();
        terminal
            .draw(|f| crate::app::render(app, f, f.area()))
            .unwrap();

        let picker = app.date_picker.as_ref().expect("picker open");
        let rect = picker.popup_rect(app.frame_size.get());
        let days_y = rect.y + 3;
        let weeks = rect.height.saturating_sub(6);
        for row in 0..weeks {
            for col in 0..7u16 {
                let x = rect.x + 1 + col * 3 + 1;
                let y = days_y + row;
                if picker
                    .date_at(app.frame_size.get(), x, y)
                    .map(crate::ui::date_picker::format_date)
                    .as_deref()
                    == Some(target)
                {
                    return (x, y);
                }
            }
        }
        panic!("no day cell found for {target}");
    }

    #[test]
    fn date_picker_day_click_changes_selected_date() {
        let (_tmp, mut app) = make_app();
        app.frame_size.set(Rect::new(0, 0, 80, 24));
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for _ in 0..9 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        app.form.as_mut().unwrap().start_date = "2026-03-15".into();
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(matches!(app.mode, Mode::DatePicker { .. }));

        let (x, y) = drawn_date_picker_day(&app, "2026-03-16");
        let action = app.handle_mouse(down_left(x, y)).unwrap();
        assert_eq!(
            action,
            Action::DatePickerHit(DatePickerHit::Day("2026-03-16".into()))
        );
        if let Action::DatePickerHit(DatePickerHit::Day(date)) = action {
            app.date_picker.as_mut().unwrap().select_date_str(&date);
        }
        assert_eq!(app.date_picker.as_ref().unwrap().selected(), "2026-03-16");
    }

    #[test]
    fn date_picker_ok_click_submits_selected_date() {
        let (_tmp, mut app) = make_app();
        app.frame_size.set(Rect::new(0, 0, 80, 24));
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for _ in 0..9 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        app.form.as_mut().unwrap().start_date = "2026-03-15".into();
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();

        let (x, y) = drawn_date_picker_day(&app, "2026-03-16");
        let _ = app.handle_mouse(down_left(x, y)).unwrap();
        app.date_picker
            .as_mut()
            .unwrap()
            .select_date_str("2026-03-16");

        let picker = app.date_picker.as_ref().unwrap();
        let rect = picker.popup_rect(app.frame_size.get());
        let ok_x = rect.x + rect.width / 2;
        let ok_y = rect.y + rect.height.saturating_sub(1);
        let action = app.handle_mouse(down_left(ok_x, ok_y)).unwrap();
        assert_eq!(action, Action::DatePickerHit(DatePickerHit::Submit));

        let _ = app.handle_date_picker_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert_eq!(app.form.as_ref().unwrap().start_date, "2026-03-16");
    }

    #[test]
    fn form_non_date_field_still_opens_list_picker() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for _ in 0..6 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(
            app.form_picker.is_some(),
            "cycles field opens the list picker"
        );
        assert!(!matches!(app.mode, Mode::DatePicker { .. }));
    }

    #[test]
    fn form_picker_inline_create_cycle_persists_and_populates_field() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Picker cycle".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        for _ in 0..6 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }

        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(app.form_picker.is_some(), "picker should open on cycles");
        let _ = app.handle_key(press(KeyCode::Char('+'))).unwrap();
        for c in "Cycle 42".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        let form = app.form.as_ref().unwrap();
        assert!(
            form.cycles.split(',').any(|c| c.trim() == "Cycle 42"),
            "created cycle should populate form field, got {:?}",
            form.cycles
        );
        assert!(
            app.store.config.cycles.contains_key("Cycle 42"),
            "new cycle should be persisted in config"
        );

        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        let issue = app.store.list().unwrap().into_iter().next().unwrap();
        assert!(
            issue
                .cycles
                .unwrap_or_default()
                .iter()
                .any(|c| c == "Cycle 42")
        );
    }

    #[test]
    fn form_picker_selects_existing_label() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        let seed = "---\nnumber: 1\ntitle: \"Seed\"\nstatus: \"todo\"\nlabels: [\"bug\"]\npriority: \"medium\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody text.";
        fs::write(dir.join("2026-01-01-seed.md"), seed).unwrap();
        app.refresh_corpus().unwrap();

        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Picker labels".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        for _ in 0..3 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::F(2))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(matches!(app.mode, Mode::Board));
        let issues = app.store.list().unwrap();
        let created = issues
            .into_iter()
            .find(|i| i.title == "Picker labels")
            .expect("created issue");
        assert!(created.labels.iter().any(|l| l == "bug"));
    }

    #[test]
    fn key_release_ignored() {
        let (_tmp, mut app) = make_app();
        let key = KeyEvent {
            code: KeyCode::Char('q'),
            modifiers: crossterm::event::KeyModifiers::NONE,
            kind: KeyEventKind::Release,
            state: crossterm::event::KeyEventState::NONE,
        };
        let _ = app.handle_key(key).unwrap();
        assert!(!app.quit);
    }

    #[test]
    fn handle_mouse_in_mode_without_mouse_support_is_noop() {
        let (_tmp, mut app) = make_app();
        app.mode = Mode::Filter {
            buffer: "query".into(),
        };
        let before = app.mode.clone();
        let ev = MouseEvent {
            kind: crossterm::event::MouseEventKind::Down(crossterm::event::MouseButton::Left),
            column: 1,
            row: 1,
            modifiers: crossterm::event::KeyModifiers::NONE,
        };
        let action = app.handle_mouse(ev).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.mode, before);
    }

    #[test]
    fn frame_hit_regions_are_empty_until_recorded_and_resolve_to_actions() {
        let (_tmp, app) = make_app();
        assert!(
            app.frame_hit_regions.borrow().is_empty(),
            "no regions before a draw"
        );

        let rect_a = Rect::new(0, 0, 10, 5);
        let rect_b = Rect::new(2, 1, 2, 2);
        app.record_region(rect_a, Action::OpenEditor("a.md".into()));
        app.record_region(rect_b, Action::Quit);
        assert_eq!(app.frame_hit_regions.borrow().len(), 2);

        // Recorded rects resolve to their action...
        assert_eq!(
            app.resolve_region(0, 0),
            Some(Action::OpenEditor("a.md".into()))
        );
        // ...innermost (last-recorded) regions win on overlap...
        assert_eq!(app.resolve_region(3, 2), Some(Action::Quit));
        // ...and positions outside every region resolve to nothing.
        assert_eq!(app.resolve_region(11, 2), None);
        assert_eq!(app.resolve_region(3, 6), None);
    }

    #[test]
    fn draw_clears_regions_so_stale_targets_never_fire() {
        use ratatui::backend::TestBackend;
        let (_tmp, app) = make_app();
        app.record_region(Rect::new(0, 0, 10, 5), Action::Quit);
        app.record_region(Rect::new(0, 0, 10, 5), Action::Quit);
        let mut terminal = Terminal::new(TestBackend::new(80, 40)).unwrap();
        terminal.draw(|f| render(&app, f, f.area())).unwrap();
        assert!(
            !app.frame_hit_regions
                .borrow()
                .iter()
                .any(|region| region.action == Action::Quit),
            "a draw clears regions recorded before it"
        );
    }

    // ------------------------------------------------------------------
    // Mouse board selection / click / drag (task 3.1)
    // ------------------------------------------------------------------

    /// A board with `n` cards in the first column, for the page-step tests.
    fn make_app_with_cards(n: u32) -> (TempDir, App) {
        let (tmp, mut app) = make_app();
        let dir = app.store.config.issues_dir.clone();
        for i in 1..=n {
            write_issue(
                &dir,
                &format!("card-{i:02}.md"),
                i,
                &format!("Card {i:02}"),
                "todo",
                None,
            );
        }
        app.refresh_corpus().unwrap();
        (tmp, app)
    }

    /// Four-column board (todo / in progress / in review / done) seeded with
    /// one short title per column, framed at 80x40 so every card renders on a
    /// single line. `double_click_window` is padded so tests never race the
    /// wall clock.
    fn make_mouse_app() -> (TempDir, App) {
        let (tmp, mut app) = make_app();
        app.mouse.double_click_window = Duration::from_secs(60);
        let dir = app.store.config.issues_dir.clone();
        write_issue(&dir, "a.md", 1, "Alpha", "todo", None);
        write_issue(&dir, "b.md", 2, "Beta", "todo", None);
        write_issue(&dir, "c.md", 3, "Gamma", "in progress", None);
        write_issue(&dir, "d.md", 4, "Delta", "in review", None);
        write_issue(&dir, "e.md", 5, "Epsilon", "done", Some("abc123"));
        app.refresh_corpus().unwrap();
        app.frame_size.set(Rect::new(0, 0, 80, 40));
        (tmp, app)
    }

    fn make_sparse_order_mouse_app() -> (TempDir, App) {
        let (tmp, mut app) = make_app();
        app.mouse.double_click_window = Duration::from_secs(60);
        let dir = app.store.config.issues_dir.clone();
        write_issue(&dir, "a.md", 1, "Alpha", "todo", None);
        write_issue(&dir, "b.md", 2, "Beta", "todo", None);
        write_issue(&dir, "c.md", 3, "Gamma", "todo", None);
        write_issue(&dir, "d.md", 4, "Delta", "todo", None);
        app.refresh_corpus().unwrap();
        app.frame_size.set(Rect::new(0, 0, 80, 40));
        (tmp, app)
    }

    /// The pointer fixtures, plus one **blocked** card: #1 blocks #2, so dragging
    /// or menu-moving #2 into `done` has to raise the acknowledgement prompt.
    ///
    /// WP04's TUI coverage went through the keyboard `>` binding only. A drag-drop
    /// and a context-menu item are two more doors into `move_selected_to`, and a
    /// door with no test is a door nobody checked.
    fn make_blocked_mouse_app() -> (TempDir, App) {
        let (tmp, mut app) = make_mouse_app();
        app.store
            .link("1", "2", crate::relationships::RelationKind::Blocks)
            .unwrap();
        app.refresh_corpus().unwrap();
        (tmp, app)
    }

    /// The index of the `done` column, resolved from the board rather than
    /// hard-coded, so a column-order change does not silently retarget the test.
    fn done_col(app: &App) -> usize {
        let name = app
            .store
            .config
            .default_config()
            .effective_done_column()
            .expect("the fixture board has a done column");
        (0..app.board.total_cols())
            .find(|c| app.board.column_name(*c) == name)
            .unwrap_or_else(|| panic!("no column named {name}"))
    }

    fn down_left(x: u16, y: u16) -> MouseEvent {
        MouseEvent {
            kind: MouseEventKind::Down(MouseButton::Left),
            column: x,
            row: y,
            modifiers: crossterm::event::KeyModifiers::NONE,
        }
    }

    fn down_right(x: u16, y: u16) -> MouseEvent {
        MouseEvent {
            kind: MouseEventKind::Down(MouseButton::Right),
            column: x,
            row: y,
            modifiers: crossterm::event::KeyModifiers::NONE,
        }
    }

    fn up_left(x: u16, y: u16) -> MouseEvent {
        MouseEvent {
            kind: MouseEventKind::Up(MouseButton::Left),
            column: x,
            row: y,
            modifiers: crossterm::event::KeyModifiers::NONE,
        }
    }

    fn drag_event(x: u16, y: u16) -> MouseEvent {
        MouseEvent {
            kind: MouseEventKind::Drag(MouseButton::Left),
            column: x,
            row: y,
            modifiers: crossterm::event::KeyModifiers::NONE,
        }
    }

    /// A pointer position on `row`-th card of column `col`, using the shared
    /// board geometry so tests stay in lock-step with `hit_test`.
    fn card_cell(app: &App, col: usize, row: usize) -> (u16, u16) {
        let board_area = app.board_mouse_area(app.frame_size.get()).unwrap();
        let rect = board::compute_column_rects(board_area, app.board.total_cols())[col];
        let mut y = rect.y + 1;
        for before in 0..row {
            y += crate::ui::widgets::card_line_count(
                &app.board.columns[col].cards[before],
                rect.width as usize,
                true,
                3,
            );
        }
        (rect.x + 2, y)
    }

    /// A pointer position on empty space inside column `col` (below its cards).
    fn column_cell(app: &App, col: usize) -> (u16, u16) {
        let board_area = app.board_mouse_area(app.frame_size.get()).unwrap();
        let rect = board::compute_column_rects(board_area, app.board.total_cols())[col];
        (rect.x + 2, rect.y + rect.height - 2)
    }

    /// Dragging a blocked card into `done` is a **move**, so it asks before it
    /// writes — the same prompt the `>` binding raises.
    ///
    /// WP04 covered the keyboard path only. A drag-drop is a second door into
    /// `move_selected_to`, and the review flagged that no test drove it.
    #[test]
    fn a_drag_of_a_blocked_card_into_done_asks_before_it_writes() {
        let (_tmp, mut app) = make_blocked_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 1); // #2 Beta, blocked by #1
        let (tx, ty) = column_cell(&app, done_col(&app));

        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(tx, ty)).unwrap();
        app.handle_mouse(up_left(tx, ty)).unwrap();

        assert!(
            matches!(app.mode, Mode::ConfirmBlockedMove { .. }),
            "a drag into done must raise the acknowledgement prompt, got {:?}",
            app.mode
        );
        // Cancelling leaves the card where it was.
        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(
            app.board.column_cards(0).iter().any(|c| c.number == 2),
            "a cancelled drag must not move the card"
        );
    }

    /// The same drag, confirmed: the prompt **defers** to the commit prompt
    /// rather than applying with no commit, so a confirmed blocked move is
    /// recorded exactly like a clear one.
    #[test]
    fn a_confirmed_blocked_drag_into_done_records_its_commit() {
        let (_tmp, mut app) = make_blocked_mouse_app();
        let dir = app.store.config.issues_dir.clone();
        let (sx, sy) = card_cell(&app, 0, 1);
        let (tx, ty) = column_cell(&app, done_col(&app));

        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(tx, ty)).unwrap();
        app.handle_mouse(up_left(tx, ty)).unwrap();
        app.handle_key(press(KeyCode::Char('y'))).unwrap();

        assert!(
            matches!(app.mode, Mode::MoveIntoDone { .. }),
            "confirming must still ask for the commit hash, got {:?}",
            app.mode
        );
        for c in "deadbee".chars() {
            app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        app.handle_key(press(KeyCode::Enter)).unwrap();

        let file = fs::read_to_string(dir.join("b.md")).unwrap();
        assert!(file.contains("commit: deadbee"), "commit recorded:\n{file}");
        assert!(
            file.contains("blocked_move_acknowledged"),
            "and the acknowledgement is in the same record:\n{file}"
        );
    }

    /// The context menu's `Move to <column>` is a third door into
    /// `move_selected_to`, and it was the only one with no test at all.
    #[test]
    fn a_context_menu_move_of_a_blocked_card_asks_before_it_writes() {
        let (_tmp, mut app) = make_blocked_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 1); // #2 Beta, blocked by #1
        let target = done_col(&app);

        app.handle_mouse(down_right(sx, sy)).unwrap();
        assert!(
            matches!(app.mode, Mode::ContextMenu { .. }),
            "right-click opens the menu, got {:?}",
            app.mode
        );
        // Navigate to `Move to <done>` by index, not by counting Down presses.
        let index = app
            .context_menu
            .as_ref()
            .unwrap()
            .items()
            .iter()
            .position(|i| i.kind == MenuItemKind::MoveTo { column: target })
            .expect("the menu offers a move into the done column");
        for _ in 0..index {
            app.handle_key(press(KeyCode::Down)).unwrap();
        }
        app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(
            matches!(app.mode, Mode::ConfirmBlockedMove { .. }),
            "a menu move into done must raise the acknowledgement prompt, got {:?}",
            app.mode
        );
        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(
            app.board.column_cards(0).iter().any(|c| c.number == 2),
            "a cancelled menu move must not move the card"
        );
    }

    #[test]
    fn mouse_click_selects_card() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        let action = app.handle_mouse(down_left(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!((app.board.active_col, app.board.selected), (0, 1));
        assert_eq!(
            app.board.get_selected_card().map(|c| c.number),
            Some(2),
            "second todo card selected"
        );
    }

    #[test]
    fn mouse_click_on_empty_column_space_selects_column() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = column_cell(&app, 1);
        let action = app.handle_mouse(down_left(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.board.active_col, 1);
    }

    #[test]
    fn mouse_double_click_opens_detail() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 0);
        app.handle_mouse(down_left(x, y)).unwrap();
        app.handle_mouse(up_left(x, y)).unwrap();
        app.handle_mouse(down_left(x, y)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
        assert_eq!(
            app.detail.as_ref().map(|d| d.issue.number),
            Some(1),
            "double-clicked card detail is open"
        );
    }

    #[test]
    fn mouse_single_click_does_not_open_detail() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 0);
        app.handle_mouse(down_left(x, y)).unwrap();
        app.handle_mouse(up_left(x, y)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert!(app.detail.is_none());
    }

    #[test]
    fn mouse_drag_moves_issue_to_another_real_column() {
        let (_tmp, mut app) = make_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 1);
        let target = column_cell(&app, 1);
        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(target.0, target.1)).unwrap();
        let action = app.handle_mouse(up_left(target.0, target.1)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.board.active_col, 1);
        assert!(
            app.board.columns[1].cards.iter().any(|c| c.number == 2),
            "Beta landed in 'in progress'"
        );
        assert!(
            app.board.columns[0].cards.iter().all(|c| c.number != 2),
            "Beta left 'todo'"
        );
        assert_eq!(app.status_msg.as_deref(), Some("Moved #2 to in progress"));
    }

    #[test]
    fn mouse_drag_updates_preview_column_while_held() {
        let (_tmp, mut app) = make_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 1);
        let target = column_cell(&app, 1);
        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(target.0, target.1)).unwrap();
        assert_eq!(app.drag_preview_col, Some(1));
        assert_eq!(app.board.hover, None);
        app.handle_mouse(up_left(target.0, target.1)).unwrap();
        assert_eq!(app.drag_preview_col, None);
    }

    #[test]
    fn ctrl_up_and_down_reorder_the_selected_card() {
        let (_tmp, mut app) = make_mouse_app();
        app.board.active_col = 0;
        app.board.selected = 1;
        let up = app
            .handle_key(press_with_modifiers(
                KeyCode::Up,
                crossterm::event::KeyModifiers::CONTROL,
            ))
            .unwrap();
        assert_eq!(up, Action::None);
        assert_eq!(
            app.board
                .column_cards(0)
                .iter()
                .map(|c| c.title.as_str())
                .collect::<Vec<_>>(),
            ["Beta", "Alpha"],
            "ctrl-up moves the selected card one slot earlier"
        );
        assert_eq!(app.board.selected, 0);
        let down = app
            .handle_key(press_with_modifiers(
                KeyCode::Down,
                crossterm::event::KeyModifiers::CONTROL,
            ))
            .unwrap();
        assert_eq!(down, Action::None);
        assert_eq!(
            app.board
                .column_cards(0)
                .iter()
                .map(|c| c.title.as_str())
                .collect::<Vec<_>>(),
            ["Alpha", "Beta"],
            "ctrl-down restores the original order"
        );
    }

    #[test]
    fn mouse_drop_on_source_column_is_noop() {
        let (_tmp, mut app) = make_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 1);
        let target = column_cell(&app, 0);
        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(target.0, target.1)).unwrap();
        app.handle_mouse(up_left(target.0, target.1)).unwrap();
        assert!(
            app.board.columns[0].cards.iter().any(|c| c.number == 2),
            "Beta stayed in 'todo'"
        );
    }

    #[test]
    fn mouse_drag_reorders_cards_within_same_column_and_persists_order() {
        let (_tmp, mut app) = make_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 1);
        let (tx, ty) = card_cell(&app, 0, 0);
        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(tx, ty)).unwrap();
        let action = app.handle_mouse(up_left(tx, ty)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(
            app.board
                .column_cards(0)
                .iter()
                .map(|c| c.title.as_str())
                .collect::<Vec<_>>(),
            ["Beta", "Alpha"],
            "dropping on another card in the same column reorders it"
        );
        let board_name = app.active_board_name().to_string();
        let board_cfg = app
            .store
            .config
            .kanban
            .configurations
            .get(&board_name)
            .unwrap();
        assert_eq!(
            board_cfg.card_order,
            vec!["b.md".to_string(), "a.md".to_string()],
            "same-column drag persists the custom order in config"
        );
    }

    #[test]
    fn mouse_drag_persists_only_cards_that_differ_from_default_order() {
        let (_tmp, mut app) = make_sparse_order_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 3);
        let (tx, ty) = card_cell(&app, 0, 1);
        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(tx, ty)).unwrap();
        app.handle_mouse(up_left(tx, ty)).unwrap();
        assert_eq!(
            app.board
                .column_cards(0)
                .iter()
                .map(|c| c.title.as_str())
                .collect::<Vec<_>>(),
            ["Alpha", "Delta", "Beta", "Gamma"],
            "dragging the last card into the middle updates the visible order"
        );
        let board_name = app.active_board_name().to_string();
        let board_cfg = app
            .store
            .config
            .kanban
            .configurations
            .get(&board_name)
            .unwrap();
        assert_eq!(
            board_cfg.card_order,
            vec!["d.md".to_string(), "b.md".to_string(), "c.md".to_string()],
            "only the cards whose positions changed are persisted"
        );
    }

    #[test]
    fn mouse_drop_on_no_column_area_is_noop() {
        let (_tmp, mut app) = make_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 0);
        app.handle_mouse(down_left(sx, sy)).unwrap();
        let outside = (sx, 0u16); // the hover line, above the board area
        app.handle_mouse(drag_event(outside.0, outside.1)).unwrap();
        app.handle_mouse(up_left(outside.0, outside.1)).unwrap();
        assert!(
            app.board.columns[0].cards.iter().any(|c| c.number == 1),
            "Alpha stayed in 'todo'"
        );
        assert_eq!(app.status_msg, None);
    }

    #[test]
    fn mouse_drop_on_mismatch_column_is_noop() {
        let (_tmp, mut app) = make_app();
        app.mouse.double_click_window = Duration::from_secs(60);
        let dir = app.store.config.issues_dir.clone();
        write_issue(&dir, "x.md", 1, "Alpha", "todo", None);
        write_issue(&dir, "w.md", 9, "Oddball", "weird", None);
        app.refresh_corpus().unwrap();
        app.board.show_mismatch = true;
        app.frame_size.set(Rect::new(0, 0, 80, 40));

        let (sx, sy) = card_cell(&app, 0, 0);
        let mismatch_col = app.board.columns.len();
        let target = column_cell(&app, mismatch_col);
        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(target.0, target.1)).unwrap();
        app.handle_mouse(up_left(target.0, target.1)).unwrap();
        assert!(
            app.board.columns[0].cards.iter().any(|c| c.number == 1),
            "Alpha stayed in 'todo' (mismatched column is not a move target)"
        );
    }

    #[test]
    fn mouse_drag_into_done_without_commit_opens_prompt() {
        let (_tmp, mut app) = make_mouse_app();
        let (sx, sy) = card_cell(&app, 0, 0);
        let target = column_cell(&app, 3); // "done"
        app.handle_mouse(down_left(sx, sy)).unwrap();
        app.handle_mouse(drag_event(target.0, target.1)).unwrap();
        app.handle_mouse(up_left(target.0, target.1)).unwrap();
        assert!(
            matches!(&app.mode, Mode::MoveIntoDone { target_col: 3, buffer } if buffer.is_empty()),
            "drag into done without a commit opens the MoveIntoDone prompt, got {:?}",
            app.mode
        );
    }

    fn moved_to(x: u16, y: u16) -> MouseEvent {
        MouseEvent {
            kind: MouseEventKind::Moved,
            column: x,
            row: y,
            modifiers: crossterm::event::KeyModifiers::NONE,
        }
    }

    fn scroll_up(x: u16, y: u16) -> MouseEvent {
        MouseEvent {
            kind: MouseEventKind::ScrollUp,
            column: x,
            row: y,
            modifiers: crossterm::event::KeyModifiers::NONE,
        }
    }

    fn scroll_down(x: u16, y: u16) -> MouseEvent {
        MouseEvent {
            kind: MouseEventKind::ScrollDown,
            column: x,
            row: y,
            modifiers: crossterm::event::KeyModifiers::NONE,
        }
    }

    #[test]
    fn mouse_hover_updates_without_selection_change() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        let before = (app.board.active_col, app.board.selected);
        let action = app.handle_mouse(moved_to(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.board.hover, Some((0, 1)));
        assert_eq!((app.board.active_col, app.board.selected), before);
    }

    #[test]
    fn mouse_hover_marks_an_empty_column_without_a_card() {
        let (_tmp, mut app) = make_app();
        let dir = app.store.config.issues_dir.clone();
        // Only `todo` has a card, so `in progress` (column 1) is empty.
        write_issue(&dir, "a.md", 1, "Alpha", "todo", None);
        app.refresh_corpus().unwrap();
        app.frame_size.set(Rect::new(0, 0, 80, 40));

        let (x, y) = column_cell(&app, 1);
        app.handle_mouse(moved_to(x, y)).unwrap();
        assert_eq!(app.board.hover, None, "no card under the pointer");
        assert_eq!(
            app.board.hover_col,
            Some(1),
            "an empty column is still marked as hovered"
        );

        // Leaving the column clears both.
        let (ox, oy) = column_cell(&app, 0);
        app.handle_mouse(moved_to(ox, oy)).unwrap();
        assert_eq!(app.board.hover_col, Some(0));

        // Off the board entirely clears it.
        app.handle_mouse(moved_to(0, 0)).unwrap();
        assert_eq!(app.board.hover_col, None);
    }

    #[test]
    fn mouse_hover_cleared_on_up_or_pointer_leaving_board() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 0);
        app.handle_mouse(moved_to(x, y)).unwrap();
        assert_eq!(app.board.hover, Some((0, 0)));

        // Leaving the board clears the hover.
        app.handle_mouse(moved_to(x, 0)).unwrap();
        assert_eq!(app.board.hover, None);

        // Hovering a card again then releasing the button also clears it.
        app.handle_mouse(moved_to(x, y)).unwrap();
        assert!(app.board.hover.is_some());
        app.handle_mouse(up_left(x, y)).unwrap();
        assert_eq!(app.board.hover, None);
    }

    #[test]
    fn mouse_scroll_moves_board_selection_within_active_column() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        app.handle_mouse(down_left(x, y)).unwrap();
        assert_eq!(app.board.selected, 1);

        let action = app.handle_mouse(scroll_up(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.board.selected, 0);

        let action = app.handle_mouse(scroll_down(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.board.selected, 1);
    }

    #[test]
    fn mouse_scroll_scrolls_detail_and_context_menu() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 0);

        app.handle_mouse(down_left(x, y)).unwrap();
        app.handle_mouse(up_left(x, y)).unwrap();
        app.handle_mouse(down_left(x, y)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
        // The pane's geometry is normally recorded by its own draw; a test that drives
        // the handler supplies it, which is also what makes the clamping visible.
        if let Some(d) = app.detail.as_mut() {
            d.viewport.set(20);
            d.max_scroll.set(8);
        }
        let action = app.handle_mouse(scroll_down(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.detail.as_ref().unwrap().scroll_offset, 5);
        // One more notch would be 10, past the last page: it stops at 8 rather than
        // scrolling the pane into emptiness (tix #1442).
        app.handle_mouse(scroll_down(x, y)).unwrap();
        assert_eq!(app.detail.as_ref().unwrap().scroll_offset, 8);
        let action = app.handle_mouse(scroll_up(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.detail.as_ref().unwrap().scroll_offset, 3);
        for _ in 0..5 {
            app.handle_mouse(scroll_up(x, y)).unwrap();
        }
        assert_eq!(app.detail.as_ref().unwrap().scroll_offset, 0);

        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 0);
        app.handle_mouse(down_right(x, y)).unwrap();
        assert!(matches!(app.mode, Mode::ContextMenu { .. }));
        let action = app.handle_mouse(scroll_down(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.context_menu.as_ref().unwrap().selected(), Some(1));
        let action = app.handle_mouse(scroll_up(x, y)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.context_menu.as_ref().unwrap().selected(), Some(0));
    }

    // ------------------------------------------------------------------
    // #1398 / #1441 / #1442 — the new-issue entry point, and scrolling
    // ------------------------------------------------------------------

    /// `tix new` starts the session on the create form (#1398). This is the state
    /// `app::run_new_issue` opens, and it must be the *same* form `n` produces — both
    /// go through [`App::open_new_issue_form`], and this pins the outcome so a future
    /// second implementation of "prefill the form" shows up as a difference.
    #[test]
    fn new_issue_form_is_the_form_the_board_key_opens() {
        let (_tmp, mut by_key) = make_app();
        by_key.mode = Mode::Board;
        let _ = by_key.handle_key(press(KeyCode::Char('n'))).unwrap();

        let (_tmp2, mut by_command) = make_app();
        by_command.open_new_issue_form();

        assert!(matches!(by_command.mode, Mode::Form));
        assert!(matches!(by_key.mode, Mode::Form));
        let key_form = by_key.form.as_ref().expect("n opens a form");
        let cmd_form = by_command.form.as_ref().expect("the command opens a form");
        assert_eq!(cmd_form.title, key_form.title);
        assert_eq!(cmd_form.status, key_form.status);
        assert_eq!(cmd_form.assignee, key_form.assignee);
        assert_eq!(cmd_form.focus, key_form.focus);
    }

    /// The pane's page keys move a **page**, not a handful of lines, and stop at the
    /// end of the content instead of scrolling past it (#1442).
    #[test]
    fn detail_page_keys_scroll_one_page_and_stop_at_the_end() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 0);
        app.handle_mouse(down_left(x, y)).unwrap();
        app.handle_mouse(up_left(x, y)).unwrap();
        app.handle_mouse(down_left(x, y)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));

        if let Some(d) = app.detail.as_mut() {
            d.viewport.set(20);
            d.max_scroll.set(45);
        }
        // A page keeps one row of the previous page, so the reader has an anchor.
        let page = app.detail.as_ref().unwrap().page();
        assert_eq!(page, 19);

        app.handle_key(press(KeyCode::PageDown)).unwrap();
        assert_eq!(app.detail.as_ref().unwrap().scroll_offset, 19);
        app.handle_key(press(KeyCode::PageDown)).unwrap();
        assert_eq!(app.detail.as_ref().unwrap().scroll_offset, 38);
        // 38 + 19 = 57 > 45, so this one lands on the last page rather than past it.
        app.handle_key(press(KeyCode::PageDown)).unwrap();
        assert_eq!(app.detail.as_ref().unwrap().scroll_offset, 45);
        app.handle_key(press(KeyCode::PageUp)).unwrap();
        assert_eq!(app.detail.as_ref().unwrap().scroll_offset, 26);
    }

    /// The keybindings overlay scrolls — one row, one page, one wheel notch — and
    /// clamps at both ends (#1441, #1442).
    #[test]
    fn help_overlay_scrolls_by_row_page_and_wheel() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let (_tmp, mut app) = make_app();
        app.open_help(Mode::Board);
        // The overlay records its geometry while it draws, so it has to draw once
        // before its handlers know how far they can go — which is also what a real
        // session does before it reads a key.
        let mut terminal = Terminal::new(TestBackend::new(80, 12)).unwrap();
        terminal.draw(|f| render(&app, f, f.area())).unwrap();
        let metrics = app.help_metrics.get();
        assert!(
            metrics.max_scroll > 0,
            "the test frame is meant to hide rows: {metrics:?}"
        );

        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(app.help_scroll, 1, "one row down");
        app.handle_key(press(KeyCode::Char('k'))).unwrap();
        assert_eq!(app.help_scroll, 0, "and back");

        app.handle_key(press(KeyCode::PageDown)).unwrap();
        assert_eq!(app.help_scroll, app.help_page(), "one page down");
        app.handle_key(press(KeyCode::PageUp)).unwrap();
        assert_eq!(app.help_scroll, 0, "and back");

        app.handle_mouse(scroll_down(1, 1)).unwrap();
        assert_eq!(app.help_scroll, WHEEL_ROWS, "one wheel notch");
        app.handle_mouse(scroll_up(1, 1)).unwrap();
        assert_eq!(app.help_scroll, 0);

        for _ in 0..50 {
            app.handle_key(press(KeyCode::PageDown)).unwrap();
        }
        assert_eq!(
            app.help_scroll, metrics.max_scroll,
            "the last row is reachable"
        );
        for _ in 0..50 {
            app.handle_key(press(KeyCode::PageUp)).unwrap();
        }
        assert_eq!(app.help_scroll, 0, "and the first row stays the first");
    }

    /// Scrolling the overlay moves the **rendered** rows, and reopening starts at the
    /// top again (#1441).
    #[test]
    fn help_overlay_scrolls_its_rows_and_reopens_at_the_top() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let (_tmp, mut app) = make_app();
        let entries = crate::ui::commandbar::help_overlay(&app.bindings, app.top_mode);
        assert!(
            entries.len() > 12,
            "the overlay must be longer than the frame"
        );

        let draw = |app: &App| {
            let mut terminal = Terminal::new(TestBackend::new(80, 12)).unwrap();
            terminal.draw(|f| render(app, f, f.area())).unwrap();
            let buf = terminal.backend().buffer();
            let mut text = String::new();
            for y in 0..buf.area.height {
                for x in 0..buf.area.width {
                    text.push_str(buf[(x, y)].symbol());
                }
                text.push('\n');
            }
            text
        };

        app.open_help(Mode::Board);
        let first = draw(&app);
        assert!(
            first.contains(&entries[0].0),
            "the top of the list is on screen: {first}"
        );

        app.handle_key(press(KeyCode::PageDown)).unwrap();
        let second = draw(&app);
        assert_ne!(
            second, first,
            "scrolling a page must change what is drawn, not just a counter"
        );
        let page = app.help_page() as usize;
        assert!(
            second.contains(&entries[page].0),
            "the row one page down is now visible: {second}"
        );
        assert!(
            !second.contains(&entries[0].0),
            "and the first page scrolled away"
        );

        // Reopening resets: a help screen that reappeared halfway down would hide the
        // first bindings from the person who opened it to find them.
        app.close_help();
        app.open_help(Mode::Board);
        assert_eq!(app.help_scroll, 0);
        assert!(draw(&app).contains(&entries[0].0));
    }

    /// `PgUp`/`PgDn` move the board selection by one screen of cards — and they move
    /// it **at all**, which they did not before (tix #1442 follow-up): the keys were
    /// unbound on the board, and an unbound key in a non-text context is rewritten to
    /// `F(12)` before the handler sees it, so the key did nothing while the wheel next
    /// to it worked.
    #[test]
    fn board_page_keys_move_the_selection_by_a_screen() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let (_tmp, mut app) = make_app_with_cards(30);
        // The page size is reported by the draw, exactly as in a session.
        let mut terminal = Terminal::new(TestBackend::new(70, 20)).unwrap();
        terminal.draw(|f| render(&app, f, f.area())).unwrap();
        let page = app.board_page.get();
        assert!(
            page > 1,
            "a 20-row column must hold more than one card, got {page}"
        );

        assert_eq!(app.board.selected, 0);
        app.handle_key(press(KeyCode::PageDown)).unwrap();
        assert_eq!(app.board.selected, page, "one screen down");
        app.handle_key(press(KeyCode::PageDown)).unwrap();
        assert_eq!(app.board.selected, page * 2, "two screens down");
        app.handle_key(press(KeyCode::PageUp)).unwrap();
        assert_eq!(app.board.selected, page, "and back one");

        for _ in 0..20 {
            app.handle_key(press(KeyCode::PageDown)).unwrap();
        }
        assert_eq!(
            app.board.selected, 29,
            "paging past the end lands on the last card"
        );
        for _ in 0..20 {
            app.handle_key(press(KeyCode::PageUp)).unwrap();
        }
        assert_eq!(app.board.selected, 0, "and paging up lands on the first");
    }

    /// An empty column has nothing to page, and the key says nothing rather than
    /// moving a selection that is not there.
    #[test]
    fn board_page_keys_do_nothing_in_an_empty_column() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let (_tmp, mut app) = make_app();
        let mut terminal = Terminal::new(TestBackend::new(70, 20)).unwrap();
        terminal.draw(|f| render(&app, f, f.area())).unwrap();

        assert_eq!(app.board_page.get(), 0, "nothing to page");
        app.handle_key(press(KeyCode::PageDown)).unwrap();
        assert_eq!(app.board.selected, 0);
        assert!(matches!(app.mode, Mode::Board));
    }

    /// The overlay's rendered text at `w`x`h`.
    ///
    /// For the tests that care about what is *on screen* rather than what the state
    /// says: a filter that changes a counter but not a row would pass a state test.
    fn draw_help(app: &App, w: u16, h: u16) -> String {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let mut terminal = Terminal::new(TestBackend::new(w, h)).unwrap();
        terminal.draw(|f| render(app, f, f.area())).unwrap();
        let buf = terminal.backend().buffer();
        let mut text = String::new();
        for y in 0..buf.area.height {
            for x in 0..buf.area.width {
                text.push_str(buf[(x, y)].symbol());
            }
            text.push('\n');
        }
        text
    }

    /// tix #1496: `/` searches the keybindings. The query filters the list as it is
    /// typed, in the same fuzzy sense `tix search` uses, and the overlay says how much
    /// it is hiding.
    #[test]
    fn help_overlay_search_filters_the_list() {
        let (_tmp, mut app) = make_app();
        let entries = crate::ui::commandbar::help_overlay(&app.bindings, app.top_mode);
        let first_key = entries[0].0.clone();

        app.open_help(Mode::Board);
        assert!(
            draw_help(&app, 80, 24).contains(&first_key),
            "the unfiltered list starts at the top"
        );

        app.handle_key(press(KeyCode::Char('/'))).unwrap();
        assert!(app.help_searching, "the input line has the keyboard");
        for c in "clone".chars() {
            app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(app.help_query, "clone");

        let filtered = draw_help(&app, 80, 24);
        assert!(
            filtered.contains("clone issue"),
            "the match is listed: {filtered}"
        );
        assert!(
            filtered.contains("of") && filtered.contains("bindings"),
            "and the summary says how many rows the filter kept: {filtered}"
        );
        assert!(
            !filtered.contains("open detail"),
            "an unrelated binding is filtered out: {filtered}"
        );

        // Enter commits the search: the input closes, the filter stays.
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(!app.help_searching);
        assert_eq!(app.help_query, "clone");
        assert!(draw_help(&app, 80, 24).contains("clone issue"));

        // Backspace while the input is open widens it again.
        app.handle_key(press(KeyCode::Char('/'))).unwrap();
        app.handle_key(press(KeyCode::Backspace)).unwrap();
        app.handle_key(press(KeyCode::Backspace)).unwrap();
        assert_eq!(app.help_query, "clo");
        assert!(
            draw_help(&app, 80, 24).contains("clone issue"),
            "still a match"
        );

        // Esc **inside** the input clears the query and does not close the overlay —
        // the same bargain `/` makes on the board.
        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(!app.help_searching);
        assert!(app.help_query.is_empty());
        assert!(
            matches!(app.mode, Mode::Help { .. }),
            "clearing a search is not closing the help"
        );
        assert!(
            draw_help(&app, 80, 24).contains(&first_key),
            "the whole list is back"
        );

        // And Esc outside it closes, as it always did.
        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(!matches!(app.mode, Mode::Help { .. }));
    }

    /// The search is *fuzzy*, not a substring test: `nwiss` finds `new issue`, which is
    /// the whole point of asking for a fuzzy search rather than a second `/`.
    #[test]
    fn help_overlay_search_is_fuzzy() {
        let (_tmp, mut app) = make_app();
        app.open_help(Mode::Board);
        app.handle_key(press(KeyCode::Char('/'))).unwrap();
        for c in "nwiss".chars() {
            app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let text = draw_help(&app, 80, 24);
        assert!(
            text.contains("new issue"),
            "a non-contiguous query still matches: {text}"
        );
    }

    /// Reopening the overlay starts from a clean slate: a query left over from last
    /// time would hide the binding the reader opened the help to find.
    #[test]
    fn help_overlay_search_resets_when_reopened() {
        let (_tmp, mut app) = make_app();
        app.open_help(Mode::Board);
        app.handle_key(press(KeyCode::Char('/'))).unwrap();
        app.handle_key(press(KeyCode::Char('x'))).unwrap();
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(app.help_query, "x");

        app.close_help();
        app.open_help(Mode::Board);
        assert!(app.help_query.is_empty(), "the query did not survive");
        assert!(!app.help_searching);
    }

    /// While the input line is up, the caret sits at the end of what has been typed —
    /// the text has to land somewhere visible.
    #[test]
    fn help_overlay_search_puts_the_caret_on_the_input_line() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let (_tmp, mut app) = make_app();
        app.open_help(Mode::Board);
        app.handle_key(press(KeyCode::Char('/'))).unwrap();
        for c in "clone".chars() {
            app.handle_key(press(KeyCode::Char(c))).unwrap();
        }

        let mut terminal = Terminal::new(TestBackend::new(80, 24)).unwrap();
        terminal.draw(|f| render(&app, f, f.area())).unwrap();
        let cursor = terminal.backend().cursor_position();

        // Find the row the prompt is drawn on, and the column just past its text: the
        // caret must be exactly there, which is the claim — not a re-derivation of the
        // modal's geometry.
        let buf = terminal.backend().buffer();
        let mut found = None;
        for y in 0..buf.area.height {
            let mut row = String::new();
            for x in 0..buf.area.width {
                row.push_str(buf[(x, y)].symbol());
            }
            // `find` returns a *byte* index and the box borders are three bytes each, so
            // the column is the number of characters before the match, not the offset.
            if let Some(byte) = row.find("/clone") {
                let column = row[..byte].chars().count() as u16 + "/clone".chars().count() as u16;
                found = Some((y, column));
            }
        }
        let (row, column) = found.expect("the prompt is drawn");
        assert_eq!(
            cursor,
            ratatui::layout::Position::new(column, row),
            "the prompt row was: {:?}",
            {
                let mut text = String::new();
                for x in 0..buf.area.width {
                    text.push_str(buf[(x, row)].symbol());
                }
                text
            }
        );
    }

    /// The search line is **free text**: `q` and `?` are characters there, not the keys
    /// that close the overlay. They *are* bound to cancel in the list mode, and
    /// `App::handle_key` rewrites a bound key to its action's canonical chord before the
    /// handler sees it — so without a context of its own, `q` would arrive as `Esc` and
    /// no query could contain one.
    #[test]
    fn help_overlay_search_accepts_the_keys_that_close_the_overlay() {
        let (_tmp, mut app) = make_app();
        app.open_help(Mode::Board);
        app.handle_key(press(KeyCode::Char('/'))).unwrap();
        for c in "quit?".chars() {
            app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(app.help_query, "quit?");
        assert!(app.help_searching, "still typing");
        assert!(
            matches!(app.mode, Mode::Help { .. }),
            "neither `q` nor `?` closed the overlay"
        );

        // Committing it and pressing `q` in the *list* mode still closes, as before.
        app.handle_key(press(KeyCode::Enter)).unwrap();
        app.handle_key(press(KeyCode::Char('q'))).unwrap();
        assert!(!matches!(app.mode, Mode::Help { .. }));
    }

    // ------------------------------------------------------------------
    // WP05 — help overlay, `/` filter, comment and asset entry
    // ------------------------------------------------------------------

    fn open_detail(app: &mut App) {
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
        assert!(app.detail.is_some());
    }

    #[test]
    fn help_opens_from_board_and_closes() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('?'))).unwrap();
        assert!(
            matches!(&app.mode, Mode::Help { return_to } if **return_to == Mode::Board),
            "got {:?}",
            app.mode
        );
        let _ = app.handle_key(press(KeyCode::Char('q'))).unwrap();
        assert!(matches!(app.mode, Mode::Board));
    }

    #[test]
    fn help_from_detail_returns_to_detail() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        open_detail(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('?'))).unwrap();
        assert!(
            matches!(&app.mode, Mode::Help { return_to } if **return_to == Mode::Detail),
            "got {:?}",
            app.mode
        );
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
    }

    #[test]
    fn help_overlay_click_closes_via_recorded_region() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('?'))).unwrap();
        assert!(matches!(app.mode, Mode::Help { .. }));

        let _ = draw_board(&app, 80, 24);

        // A click inside the overlay's content closes it; the mode-navigation
        // column to its left is its own click target and stays a mode switch.
        let action = app.handle_mouse(down_left(20, 5)).unwrap();
        assert_eq!(action, Action::HelpClose);
        app.close_help();

        assert!(matches!(app.mode, Mode::Board));
    }

    #[test]
    fn help_overlay_lists_mouse_bindings() {
        let (_tmp, mut app) = make_app();
        let _ = app.handle_key(press(KeyCode::Char('?'))).unwrap();
        let cells = draw_board(&app, 80, 24);
        let text: String = cells.concat();
        assert!(text.contains("click"), "got {text:?}");
        assert!(text.contains("double-click"), "got {text:?}");
        assert!(text.contains("right-click"), "got {text:?}");
        assert!(text.contains("drag"), "got {text:?}");
    }

    #[test]
    fn filter_narrows_board_live() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "Target", "todo", None);
        write_issue(&dir, "2026-01-01-b.md", 2, "Other", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.refresh_corpus().unwrap();
        assert_eq!(app.board.column_cards(0).len(), 2);

        let _ = app.handle_key(press(KeyCode::Char('/'))).unwrap();
        assert!(matches!(app.mode, Mode::Filter { .. }));
        for c in "arget".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(app.filter, Some("arget".into()));
        assert_eq!(app.board.column_cards(0).len(), 1);
        assert_eq!(app.board.column_cards(0)[0].title, "Target");
        assert!(matches!(app.mode, Mode::Filter { .. }));
    }

    #[test]
    fn filter_esc_clears_and_returns_to_board() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "Target", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.refresh_corpus().unwrap();
        let _ = app.handle_key(press(KeyCode::Char('/'))).unwrap();
        for c in "zzw".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(app.board.column_cards(0).len(), 0);
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert_eq!(app.filter, None);
        assert_eq!(app.board.column_cards(0).len(), 1);
    }

    #[test]
    fn filter_enter_commits_and_stays_filtered() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "Target", "todo", None);
        write_issue(&dir, "2026-01-01-b.md", 2, "Other", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.refresh_corpus().unwrap();
        let _ = app.handle_key(press(KeyCode::Char('/'))).unwrap();
        for c in "arget".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert_eq!(app.filter, Some("arget".into()));
        assert_eq!(app.board.column_cards(0).len(), 1);
    }

    #[test]
    fn filter_zero_match_reports_status() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "Target", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.refresh_corpus().unwrap();
        let _ = app.handle_key(press(KeyCode::Char('/'))).unwrap();
        for c in "zzw".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(app.board.column_cards(0).len(), 0);
        assert!(
            app.status_msg
                .as_deref()
                .is_some_and(|m| m.contains("No matches")),
            "got {:?}",
            app.status_msg
        );
    }

    #[test]
    fn filter_zero_match_number_reports_status() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 7, "Target", "todo", None);
        // Issue 7's title contains the digit sequence "999"? No: a miss still
        // must surface the no-matches status because the bare number gate
        // bypasses fuzzy text matching.
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.refresh_corpus().unwrap();
        let _ = app.handle_key(press(KeyCode::Char('/'))).unwrap();
        for c in "999".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert_eq!(app.filter, Some("999".into()));
        assert_eq!(app.board.column_cards(0).len(), 0);
        assert!(
            app.status_msg
                .as_deref()
                .is_some_and(|m| m.contains("No matches")),
            "got {:?}",
            app.status_msg
        );
    }

    #[test]
    fn comment_round_trip_via_detail() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        open_detail(&mut app);

        let _ = app.handle_key(press(KeyCode::Char('c'))).unwrap();
        assert!(matches!(app.mode, Mode::Comment { .. }));
        for c in "hello world".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));

        let issue = app
            .store
            .get(IssueSelector::Filename("2026-01-01-a.md".into()))
            .unwrap();
        let comments = issue.comments();
        assert_eq!(comments.len(), 1);
        assert_eq!(comments[0].text.trim(), "hello world");
    }

    #[test]
    fn comment_esc_cancels() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        open_detail(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('c'))).unwrap();
        for c in "partial".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
        let issue = app
            .store
            .get(IssueSelector::Filename("2026-01-01-a.md".into()))
            .unwrap();
        assert!(issue.comments().is_empty());
    }

    #[test]
    fn comment_empty_discarded() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        open_detail(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('c'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
        let issue = app
            .store
            .get(IssueSelector::Filename("2026-01-01-a.md".into()))
            .unwrap();
        assert!(issue.comments().is_empty());
        assert!(
            app.status_msg
                .as_deref()
                .is_some_and(|m| m.contains("empty"))
        );
    }

    #[test]
    fn f4_a_disclosure_is_composed_with_the_confirmation_not_substituted() {
        // Cycle-4 F4. The event loop drains at the top of the loop body, so a
        // disclosure raised by `handle_key` at the bottom overwrote that action's
        // confirmation before any frame drew it. Reproduced with a real keypress:
        // on a `links:`-bearing issue, "Moved #1 to in progress" was assigned and
        // then never rendered.
        //
        // The loop itself needs a real terminal, so it is not covered here; this
        // asserts the composition rule the loop delegates to, and the drain
        // topology is covered end-to-end in `tests/mcp.rs` for `main` and the
        // MCP server.
        let (_tmp, mut app) = make_app();
        app.status_msg = Some("Moved #1 to in progress".to_string());
        app.note_disclosure("legacy-1.md: this write removed the retired `links:` key.".into());
        let status = app.status_msg.as_deref().unwrap();
        assert!(
            status.contains("Moved #1 to in progress"),
            "the confirmation must survive: {status}"
        );
        assert!(
            status.contains("retired `links:` key"),
            "and the disclosure must be shown: {status}"
        );
        // Disclosure first, because the actionable instruction is at the *end* of
        // a ~160-character string and the status area is a single unwrapped row.
        // At 80 columns the tail is what gets cut.
        let disclosure_at = status.find("retired").expect("disclosure is present");
        let confirmation_at = status.find("Moved #1").expect("confirmation is present");
        assert!(
            disclosure_at < confirmation_at,
            "the disclosure leads, so its actionable tail survives truncation: {status}"
        );

        // With no prior message the disclosure is shown on its own.
        let (_tmp2, mut app2) = make_app();
        app2.note_disclosure("alone".into());
        assert_eq!(app2.status_msg.as_deref(), Some("alone"));
    }

    #[test]
    fn f4_the_loop_drain_moves_a_raised_disclosure_into_the_status_line() {
        // Cycle-5 Major 4. The previous test called `App::note_disclosure`
        // directly, so deleting the drain from the event loop left every test
        // green — the unit test could not fail for the regression it was named
        // for. This goes through `drain_disclosures`, the function the loop
        // itself calls, so emptying that function fails here.
        let (_tmp, mut app) = make_app();
        app.status_msg = Some("Moved #1 to in progress".to_string());

        crate::storage::retired_key_disclosure("alice/2026-01-01-x.md");
        assert_eq!(
            crate::storage::take_disclosures().len(),
            1,
            "precondition: a disclosure is queued and nothing has drained it"
        );
        // Re-raise it: the line above consumed the queue.
        crate::storage::retired_key_disclosure("alice/2026-01-01-x.md");

        super::drain_disclosures(&mut app);
        let status = app.status_msg.as_deref().unwrap_or_default();
        assert!(
            status.contains("Moved #1 to in progress"),
            "the confirmation survives: {status:?}"
        );
        assert!(
            status.contains("retired"),
            "and the loop's drain moved the disclosure in: {status:?}"
        );
        assert!(
            crate::storage::take_disclosures().is_empty(),
            "the queue is empty, so the next frame does not repeat it"
        );
    }

    /// Every printable ASCII character can be typed into a free-text prompt.
    ///
    /// All four of `Comment`, `Asset`, `Filter` and `MoveIntoDone` read arbitrary
    /// text into a buffer — a comment body, a **filesystem path**, a filter string, a
    /// commit message. `q` used to be bound to `cancel` in all four, copied in from
    /// the list-navigation contexts. That is not a style wart: the binding resolves
    /// to the action's canonical event (`esc`), so pressing `q` **left the mode**,
    /// and every character typed after it was then applied as a command in the mode
    /// underneath.
    ///
    /// For `Asset` the input is a path, so this is reachable from ordinary use: attach
    /// an asset from `~/Pictures/q-report.png` and the prompt closes on the `q`, and
    /// whatever you type next is executed as detail-view commands. This was found by
    /// the `asset_round_trip_via_detail` flake (#1305): that test types the source
    /// path through `handle_key`, and the path came from a `tempfile` directory whose
    /// six random characters are `[A-Za-z0-9]`, so about one run in forty hit a `q` —
    /// and one failure reported `status = "Commented by …"` with no asset written.
    ///
    /// The test is deliberately **deterministic**: it enumerates the printable ASCII
    /// range rather than depending on a random name, so it can never miss the bug it
    /// exists to prevent. `esc` is the cancel key, which is already this codebase's
    /// convention for text entry (`FilterModal` and `ConfirmDelete` bind `esc` only).
    #[test]
    fn every_printable_character_is_typeable_in_a_free_text_prompt() {
        let (_tmp, app) = make_app();
        let free_text = [
            InputContext::Comment,
            InputContext::Asset,
            InputContext::Filter,
            InputContext::MoveIntoDone,
        ];

        // `q` and `Q` are the two that used to be stolen. Asserted by name as well
        // as by the sweep below, so a future reader does not have to diff the binding
        // table to see what this test is about.
        for context in free_text {
            for ch in ['q', 'Q'] {
                let event = KeyEvent::new(KeyCode::Char(ch), crossterm::event::KeyModifiers::NONE);
                assert_ne!(
                    app.bindings.action(context, event),
                    Some(crate::keybindings::TuiAction::Cancel),
                    "{context:?} must be able to type `{ch}`: it is bound to cancel, so \
                     pressing it leaves the mode and the rest of the input is applied as \
                     commands underneath"
                );
            }
        }

        // The sweep: no printable ASCII character may resolve to a binding at all in a
        // free-text context. `Esc` and `Enter` are control keys rather than
        // characters, so they are out of scope here — `Enter` submits, which is right.
        for context in free_text {
            let mut stolen: Vec<char> = Vec::new();
            for code in 0x20u8..0x7f {
                let ch = code as char;
                let event = KeyEvent::new(KeyCode::Char(ch), crossterm::event::KeyModifiers::NONE);
                if app.bindings.action(context, event).is_some() {
                    stolen.push(ch);
                }
            }
            assert!(
                stolen.is_empty(),
                "{context:?} steals these printable characters, so they cannot be \
                 typed: {stolen:?}"
            );
        }

        // `esc` still cancels — the fix moved `q` out, it did not remove the escape
        // hatch. Asserted on the real handler, not just the binding table.
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        app.board = BoardState::build(&app.store, app.store.config.default_config());
        open_detail(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('c'))).unwrap();
        assert!(
            matches!(app.mode, Mode::Comment { .. }),
            "enter the comment prompt"
        );
        for c in "has a q in it".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        if let Mode::Comment { ref buffer, .. } = app.mode {
            assert_eq!(
                buffer, "has a q in it",
                "every character reached the buffer"
            );
        } else {
            panic!("the prompt must still be open, got {:?}", app.mode);
        }
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(
            !matches!(app.mode, Mode::Comment { .. }),
            "esc must still cancel, got {:?}",
            app.mode
        );
    }

    #[test]
    fn asset_round_trip_via_detail() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        open_detail(&mut app);

        let asset = tmp.path().join("pic.png");
        fs::write(&asset, b"fake-png").unwrap();

        let _ = app.handle_key(press(KeyCode::Char('a'))).unwrap();
        assert!(matches!(app.mode, Mode::Asset { .. }));
        for c in asset.to_string_lossy().chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Detail));

        assert!(
            dir.join("a-assets").join("pic.png").is_file(),
            "asset must be copied into the issue asset dir"
        );
        let issue = app
            .store
            .get(IssueSelector::Filename("2026-01-01-a.md".into()))
            .unwrap();
        assert!(
            issue.body.contains("pic.png"),
            "body must reference the asset, got {:?}",
            issue.body
        );
    }

    #[test]
    fn asset_error_stays_in_mode() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 1, "A", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        open_detail(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('a'))).unwrap();
        for c in "/no/such/file.png".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            matches!(app.mode, Mode::Asset { .. }),
            "asset error must stay in entry mode, got {:?}",
            app.mode
        );
        assert!(app.status_msg.is_some());
    }

    #[test]
    fn u_toggles_sub_issue_visibility_and_rebuilds_the_board() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-parent.md", 1, "Parent", "todo", None);
        fs::write(
            dir.join("2026-01-02-child.md"),
            "---\nnumber: 2\ntitle: \"Child\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\ncreated: \"2026-01-02\"\nupdated: \"2026-01-02\"\nparent: 1\n---\n\nBody text.",
        )
        .unwrap();
        app.refresh_corpus().unwrap();

        let shape = |app: &App| -> Vec<(u32, u8)> {
            app.board
                .column_cards(0)
                .iter()
                .map(|c| (c.number, c.depth))
                .collect()
        };
        assert!(!app.show_children, "sub-issues are off by default");
        assert_eq!(shape(&app), vec![(2, 0), (1, 0)]);

        let _ = app.handle_key(press(KeyCode::Char('u'))).unwrap();
        assert!(app.show_children);
        assert_eq!(app.status_msg.as_deref(), Some("Showing sub-issues"));
        assert_eq!(
            shape(&app),
            vec![(1, 0), (2, 1)],
            "the rebuild nests the sub-issue beneath its parent"
        );

        let _ = app.handle_key(press(KeyCode::Char('u'))).unwrap();
        assert!(!app.show_children);
        assert_eq!(app.status_msg.as_deref(), Some("Hiding sub-issues"));
        assert_eq!(
            shape(&app),
            vec![(2, 0), (1, 0)],
            "toggling back restores the flat order"
        );
    }

    fn draw_board(app: &App, w: u16, h: u16) -> Vec<String> {
        render_to_cells(app, w, h).unwrap()
    }

    fn flush_line(cells: &[String], width: u16, row: u16) -> String {
        let start = (row as usize) * (width as usize);
        cells[start..start + width as usize].concat()
    }

    #[test]
    fn render_board_unfiltered_has_no_filter_row() {
        let (_tmp, app) = make_app();
        let cells = draw_board(&app, 80, 24);
        assert!(
            !cells.iter().any(|s| s.contains("Search:")),
            "no filter row expected"
        );
    }

    #[test]
    fn render_board_filtered_shows_filter_row_beneath_tabs() {
        let (_tmp, mut app) = make_app();
        app.filter = Some("55".into());
        app.board = BoardState::build(&app.store, app.store.config.default_config());
        let cells = draw_board(&app, 80, 24);
        // Single board: no tab bar. Row 0 = hovered-issue title line; row 1 =
        // the filter indicator.
        assert!(
            flush_line(&cells, 80, 1).contains("Search: #55"),
            "row 1 should read the filter, got {}",
            flush_line(&cells, 80, 1)
        );
    }

    #[test]
    fn render_board_structured_filter_shows_row() {
        let (_tmp, mut app) = make_app();
        app.filter = None;
        app.structured = search::StructuredFilter {
            status: Some("todo".into()),
            ..Default::default()
        };
        app.board = BoardState::build(&app.store, app.store.config.default_config());
        let cells = draw_board(&app, 80, 24);
        assert!(
            flush_line(&cells, 80, 1).contains("Search:"),
            "got {}",
            flush_line(&cells, 80, 1)
        );
    }

    #[test]
    fn render_board_filter_input_draws_row_and_prompt() {
        let (_tmp, mut app) = make_app();
        app.mode = Mode::Filter {
            buffer: "55".to_string(),
        };
        app.filter = Some("55".into());
        app.board = BoardState::build(&app.store, app.store.config.default_config());
        let cells = draw_board(&app, 80, 24);
        assert!(
            flush_line(&cells, 80, 1).contains("Search: #55"),
            "row 1 should read the filter while typing"
        );
        assert!(
            flush_line(&cells, 80, 23).contains("Search: 55"),
            "bottom row should hold the input prompt"
        );
    }

    #[test]
    fn render_board_tiny_terminal_filtered_does_not_panic() {
        let (_tmp, mut app) = make_app();
        app.filter = Some("55".into());
        app.board = BoardState::build(&app.store, app.store.config.default_config());
        app.mode = Mode::Filter {
            buffer: "55".to_string(),
        };
        for h in [2_u16, 3, 4, 5] {
            let _ = draw_board(&app, 80, h);
        }
    }

    #[test]
    fn filter_esc_clears_row_and_resolves_to_board() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        write_issue(&dir, "2026-01-01-a.md", 55, "Target", "todo", None);
        let config = app.store.config.clone();
        app.board = BoardState::build(&app.store, config.default_config());
        app.refresh_corpus().unwrap();
        let _ = app.handle_key(press(KeyCode::Char('/'))).unwrap();
        for c in "55".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let cells = draw_board(&app, 80, 24);
        assert!(
            cells.concat().contains("Search:"),
            "filtered board must show the row; filter={:?} cells_row1={}",
            app.filter,
            flush_line(&cells, 80, 1)
        );
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert_eq!(app.filter, None);
        let after = draw_board(&app, 80, 24).concat();
        assert!(
            !after.contains("Search:"),
            "esc cleared the filter, row must disappear, got {after:?}"
        );
    }

    #[test]
    fn render_once_uses_default_board_configuration() {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();

        let config_path = tmp.path().join("tix.toml");
        let config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        config.save(&config_path).unwrap();
        let mut config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        config.kanban.configurations.clear();
        config.kanban.configurations.insert(
            "release".to_string(),
            crate::config::BoardConfiguration {
                columns: vec!["todo".to_string(), "done".to_string()],
                done_column: Some("done".to_string()),
                category_map: indexmap::IndexMap::new(),
                hidden_columns: vec![],
                show_mismatch: false,
                wrap_titles: true,
                title_lines: 2,
                card_order: vec![],
                order_by: crate::config::OrderBy::CreatedAtDesc,
            },
        );
        config.kanban.configurations.insert(
            "default".to_string(),
            crate::config::BoardConfiguration {
                columns: vec!["backlog".to_string(), "done".to_string()],
                done_column: Some("done".to_string()),
                category_map: indexmap::IndexMap::new(),
                hidden_columns: vec![],
                show_mismatch: false,
                wrap_titles: true,
                title_lines: 2,
                card_order: vec![],
                order_by: crate::config::OrderBy::CreatedAtDesc,
            },
        );
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();

        write_issue(&dir, "2026-01-01-a.md", 1, "A", "backlog", None);
        let rendered = render_once_at(&config, 80, 24).unwrap();
        assert!(
            rendered.contains("backlog"),
            "rendered board should include default board columns, got:\n{rendered}"
        );
    }

    #[test]
    fn render_once_tiny_terminal_is_stable() {
        let (tmp, _app) = make_app();
        let config_path = tmp.path().join("tix.toml");
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        write_issue(
            &tmp.path().join("issues"),
            "2026-01-01-a.md",
            1,
            "Alpha",
            "todo",
            None,
        );
        let first = render_once_at(&config, 20, 4).unwrap();
        let second = render_once_at(&config, 20, 4).unwrap();
        assert_eq!(first, second, "tiny render should be deterministic");
    }

    #[test]
    fn render_once_omits_keyboard_hints() {
        let (tmp, _app) = make_app();
        let config_path = tmp.path().join("tix.toml");
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        write_issue(
            &tmp.path().join("issues"),
            "2026-01-01-a.md",
            1,
            "Alpha",
            "todo",
            None,
        );
        let rendered = render_once_at(&config, 80, 24).unwrap();
        for hint in [
            "j/k nav",
            "n new",
            "? help",
            "h/l column",
            "enter open",
            "d delete",
        ] {
            assert!(
                !rendered.contains(hint),
                "one-shot output must not contain the keyboard hint {hint:?}:\n{rendered}"
            );
        }
    }

    #[test]
    fn render_once_reserves_bottom_margin_lines() {
        let (tmp, _app) = make_app();
        let config_path = tmp.path().join("tix.toml");
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        write_issue(
            &tmp.path().join("issues"),
            "2026-01-01-a.md",
            1,
            "Alpha",
            "todo",
            None,
        );
        let height = 24u16;
        let rendered = render_once_at(&config, 80, height).unwrap();
        let line_count = rendered.lines().count();
        assert!(
            line_count <= (height - RENDER_BOTTOM_MARGIN) as usize,
            "one-shot render must leave {RENDER_BOTTOM_MARGIN} spare lines, \
             got {line_count} lines for a {height}-row terminal:\n{rendered}"
        );
        assert!(
            rendered.lines().any(|l| l.chars().count() == 80),
            "one-shot render should still span the full width:\n{rendered}"
        );
    }

    #[test]
    fn resolve_render_size_falls_back_for_non_tty() {
        assert_eq!(
            resolve_render_size(None),
            (RENDER_FALLBACK_WIDTH, RENDER_FALLBACK_HEIGHT)
        );
        assert_eq!(resolve_render_size(Some((0, 0))), (1, 1));
    }

    // --- Right-click context menu (D5, Spec: 6) ---

    /// A two-board config (`default` + `release`) so the tab bar renders.
    fn make_multi_board_app() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let config_path = tmp.path().join("tix.toml");
        let mut config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        config.kanban.configurations.insert(
            "release".into(),
            crate::config::BoardConfiguration::default(),
        );
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        let app = App::new(&config).unwrap();
        app.frame_size.set(Rect::new(0, 0, 80, 24));
        (tmp, app)
    }

    #[test]
    fn tab_click_switches_board_via_recorded_region() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let (_tmp, mut app) = make_multi_board_app();
        assert!(app.tabs.needs_bar());
        assert_eq!(app.active_config, 0);

        let backend = TestBackend::new(80, 24);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| crate::app::render(&app, f, f.area()))
            .unwrap();

        // The tab bar is the top TAB_HEIGHT rows of the drawn content (the mode
        // navigation takes the left column, so this is not the full frame width).
        let content = app.frame_size.get();
        let tabs_area = Rect::new(content.x, content.y, content.width, 2);
        let second = app.tabs.tab_rect(1, tabs_area).unwrap();
        let action = app.handle_mouse(down_left(second.x + 1, 1)).unwrap();
        assert_eq!(
            action,
            Action::SwitchBoard(1),
            "tab click resolves the region"
        );

        // Replay the run loop's consumption of the action (the loop arm calls
        // the same switch_board, so the transition is shared).
        if let Action::SwitchBoard(index) = action {
            app.switch_board(index);
        }
        assert_eq!(app.active_config, 1);
        assert_eq!(app.tabs.selected, 1);
        assert_eq!(app.status_msg.as_deref(), Some("Switched board"));
    }

    #[test]
    fn tab_hover_updates_hover_state_without_switching_board() {
        let (_tmp, mut app) = make_multi_board_app();
        let tabs_area = Rect::new(0, 0, 80, 2);
        let second = app.tabs.tab_rect(1, tabs_area).unwrap();

        let action = app.handle_mouse(moved_to(second.x + 1, 0)).unwrap();
        assert_eq!(action, Action::None);
        assert_eq!(app.active_config, 0);
        assert_eq!(app.tabs.selected, 0);
        assert_eq!(app.tabs.hovered, Some(1));
        assert_eq!(app.board.hover, None);
    }

    // --- Confirm-delete dialog click targets (D6, Spec: 8) ---

    /// Render the app once so recorded hit regions are populated, then return
    /// the Yes / No button cell coordinates for the drawn prompt.
    fn drawn_confirm_buttons(app: &App) -> ((u16, u16), (u16, u16)) {
        let backend = ratatui::backend::TestBackend::new(
            app.frame_size.get().width,
            app.frame_size.get().height,
        );
        let mut terminal = ratatui::Terminal::new(backend).unwrap();
        terminal
            .draw(|f| crate::app::render(app, f, f.area()))
            .unwrap();
        let prompt = confirm_delete_prompt(app.frame_size.get());
        let (yes, no) = confirm_delete_buttons(prompt);
        ((yes.x + 2, yes.y), (no.x + 1, no.y))
    }

    #[test]
    fn confirm_delete_yes_click_deletes_issue() {
        let (_tmp, mut app) = make_app();
        let dir = app.store.config.issues_dir.clone();
        write_issue(&dir, "a.md", 1, "Alpha", "todo", None);
        app.refresh_corpus().unwrap();
        app.frame_size.set(Rect::new(0, 0, 80, 24));
        app.confirm_delete_target = Some("a.md".into());
        app.mode = Mode::ConfirmDelete;

        let ((yes_x, yes_y), _) = drawn_confirm_buttons(&app);
        let action = app.handle_mouse(down_left(yes_x, yes_y)).unwrap();
        assert_eq!(action, Action::ConfirmDeleteYes);

        let _ = app.confirm_delete_yes();
        assert_eq!(app.mode, Mode::Board);
        assert_eq!(app.confirm_delete_target, None);
        assert_eq!(
            app.status_msg.as_deref(),
            Some("Deleted a.md"),
            "Yes click deletes the issue (same branch as the y key)"
        );
        assert!(
            !dir.join("a.md").exists(),
            "the target file is actually removed"
        );
    }

    #[test]
    fn confirm_delete_no_click_cancels() {
        let (_tmp, mut app) = make_app();
        let dir = app.store.config.issues_dir.clone();
        write_issue(&dir, "a.md", 1, "Alpha", "todo", None);
        app.refresh_corpus().unwrap();
        app.frame_size.set(Rect::new(0, 0, 80, 24));
        app.confirm_delete_target = Some("a.md".into());
        app.mode = Mode::ConfirmDelete;

        let (_, (no_x, no_y)) = drawn_confirm_buttons(&app);
        let action = app.handle_mouse(down_left(no_x, no_y)).unwrap();
        assert_eq!(action, Action::ConfirmDeleteNo);

        let _ = app.confirm_delete_no();
        assert_eq!(app.mode, Mode::Board);
        assert_eq!(app.confirm_delete_target, None);
        assert!(
            dir.join("a.md").exists(),
            "No click cancels: the issue is left in place (same branch as Esc)"
        );
    }

    // --- Filter-modal row clicks (D6, Spec: 8) ---

    #[test]
    fn filter_modal_row_click_moves_focus_to_that_criterion() {
        let (_tmp, mut app) = make_app();
        app.frame_size.set(Rect::new(0, 0, 80, 24));
        app.filter_modal = Some(crate::ui::filter_modal::FilterModal::new());
        app.mode = Mode::FilterModal;

        let backend = ratatui::backend::TestBackend::new(80, 24);
        let mut terminal = ratatui::Terminal::new(backend).unwrap();
        terminal
            .draw(|f| crate::app::render(&app, f, f.area()))
            .unwrap();

        // Rows mirror FilterField::ALL in order; click the Status row (index 2).
        // The modal is centered in the drawn content, which excludes the mode
        // navigation column.
        let rect = crate::ui::modal::modal_rect(app.frame_size.get());
        let status_row = rect.y + 1 + 2;
        let status_field = FilterField::ALL[2];
        assert_eq!(status_field, FilterField::Status);

        assert_ne!(
            app.filter_modal.as_ref().unwrap().focus(),
            FilterField::Status
        );
        let action = app.handle_mouse(down_left(rect.x + 2, status_row)).unwrap();
        assert_eq!(
            action,
            Action::FilterModalFocus(FilterField::Status),
            "row click resolves the criterion region"
        );
        if let Action::FilterModalFocus(field) = action {
            app.filter_modal.as_mut().unwrap().focus_field(field);
        }
        assert_eq!(
            app.filter_modal.as_ref().unwrap().focus(),
            FilterField::Status,
            "clicked row becomes the focused criterion"
        );
    }

    // --- Config-mode row clicks (D6, Spec: 8) ---

    /// A point inside the dashboards section's row `row`. The Config mode draws
    /// the rows into the body to the right of the section rail, so the click
    /// target follows `config_body_rect` rather than the old centered modal.
    fn drawn_settings_row(app: &App, row: usize) -> (u16, u16) {
        let backend = ratatui::backend::TestBackend::new(
            app.frame_size.get().width,
            app.frame_size.get().height,
        );
        let mut terminal = ratatui::Terminal::new(backend).unwrap();
        terminal
            .draw(|f| crate::app::render(app, f, f.area()))
            .unwrap();
        let rect = crate::ui::settings::config_body_rect(app.frame_size.get());
        (rect.x + 2, rect.y + 1 + row as u16)
    }

    #[test]
    fn settings_row_click_selects_and_toggles_the_row() {
        let (_tmp, mut app) = make_app();
        app.frame_size.set(Rect::new(0, 0, 80, 24));
        let board_name = app.active_board_name().to_string();
        let col = "in progress".to_string();
        app.settings = Some(crate::ui::settings::SettingsModal::new());
        app.mode = Mode::Settings;

        // Row 1 is the "in progress" column row (columns in order, then the
        // DISPLAY_ROWS display rows). Clicking it must select it and run the
        // row's own activation (the body's Enter, or `Space`): hide the column.
        let (x, y) = drawn_settings_row(&app, 1);
        let action = app.handle_mouse(down_left(x, y)).unwrap();
        assert_eq!(action, Action::SettingsRow(1), "settings row resolves");

        if let Action::SettingsRow(row) = action {
            let count = board_rows_len(app.active_board_config());
            app.settings.as_mut().unwrap().move_selected_to(row, count);
            let _ = app.settings_toggle_selected();
        }
        assert_eq!(app.settings.as_ref().unwrap().selected, 1);
        assert!(
            app.store
                .config
                .kanban
                .configurations
                .get(&board_name)
                .unwrap()
                .hidden_columns
                .contains(&col),
            "clicking the column row runs the Enter toggle (hides the column)"
        );
    }

    #[test]
    fn settings_display_row_click_mirrors_entering_browse() {
        let (_tmp, mut app) = make_app();
        app.frame_size.set(Rect::new(0, 0, 80, 24));
        let board_name = app.active_board_name().to_string();
        app.settings = Some(crate::ui::settings::SettingsModal::new());
        app.mode = Mode::Settings;

        // The first display row sits right after the board's columns (index 4).
        let display_row = app.active_board_config().columns.len();
        let (x, y) = drawn_settings_row(&app, display_row);
        let action = app.handle_mouse(down_left(x, y)).unwrap();
        assert_eq!(action, Action::SettingsRow(display_row));

        if let Action::SettingsRow(row) = action {
            let count = board_rows_len(app.active_board_config());
            app.settings.as_mut().unwrap().move_selected_to(row, count);
            let _ = app.settings_toggle_selected();
        }
        assert_eq!(app.settings.as_ref().unwrap().selected, display_row);
        assert_eq!(
            app.status_msg.as_deref(),
            Some("Wrap titles: off"),
            "display row click runs the same edit as Enter on that row"
        );
        assert!(
            !app.store
                .config
                .kanban
                .configurations
                .get(&board_name)
                .unwrap()
                .wrap_titles
        );
    }

    /// The menu items offered for a card in the given column.
    fn menu_kinds(app: &App) -> Vec<MenuItemKind> {
        app.context_menu
            .as_ref()
            .expect("menu open")
            .items()
            .iter()
            .map(|item| item.kind.clone())
            .collect()
    }

    #[test]
    fn right_click_card_opens_menu_with_all_actions() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        app.handle_mouse(down_right(x, y)).unwrap();

        assert_eq!((app.board.active_col, app.board.selected), (0, 1));
        let Some(menu) = app.context_menu.as_ref() else {
            panic!("menu not open");
        };
        assert_eq!(menu.len(), 8, "open, edit, view, 3 moves, delete, refresh");
        let kinds = menu_kinds(&app);
        assert_eq!(kinds[0], MenuItemKind::OpenDetail);
        assert_eq!(kinds[1], MenuItemKind::EditInEditor);
        assert_eq!(kinds[2], MenuItemKind::ViewIssue);
        assert!(matches!(kinds[3], MenuItemKind::MoveTo { column: 1 }));
        assert!(matches!(kinds[4], MenuItemKind::MoveTo { column: 2 }));
        assert!(matches!(kinds[5], MenuItemKind::MoveTo { column: 3 }));
        assert_eq!(kinds[6], MenuItemKind::Delete);
        assert_eq!(kinds[7], MenuItemKind::RefreshBoard);
        assert!(
            menu.item(3).unwrap().label.contains("in progress"),
            "move entries are labeled with the target column"
        );
        assert!(
            !kinds
                .iter()
                .any(|k| matches!(k, MenuItemKind::MoveTo { column: 0 })),
            "current column is not offered as a move target"
        );
        assert!(matches!(app.mode, Mode::ContextMenu { .. }));
    }

    #[test]
    fn right_click_empty_column_space_is_a_noop() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = column_cell(&app, 1);
        app.handle_mouse(down_right(x, y)).unwrap();
        assert!(
            !matches!(app.mode, Mode::ContextMenu { .. }),
            "no menu on empty column space"
        );
        assert!(app.context_menu.is_none());
    }

    #[test]
    fn context_menu_open_detail_matches_enter_key() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        let issue_before = app.board.column_cards(0)[1].number;
        app.handle_mouse(down_right(x, y)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(!matches!(app.mode, Mode::ContextMenu { .. }));
        assert!(app.context_menu.is_none());
        let Some(detail) = &app.detail else {
            panic!("menu Open detail should open the detail view");
        };
        assert_eq!(detail.issue.number, issue_before);

        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        let _ = app.handle_mouse(down_left(x, y)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(
            app.detail.as_ref().map(|d| d.issue.number),
            Some(issue_before),
            "menu Open detail and board Enter open the same issue"
        );
    }

    #[test]
    fn context_menu_edit_in_editor_matches_e_key() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        app.handle_mouse(down_right(x, y)).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap(); // select "Edit in editor"
        let action = app.handle_key(press(KeyCode::Enter)).unwrap();

        let selected = app.board.get_selected_card().cloned().unwrap().filename;
        assert_eq!(
            action,
            Action::OpenEditor(selected.clone()),
            "menu Edit in editor returns OpenEditor for the selected card"
        );

        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        let _ = app.handle_mouse(down_left(x, y)).unwrap();
        let key_action = app.handle_key(press(KeyCode::Char('e'))).unwrap();
        let key_filename = match app.board.get_selected_card() {
            Some(card) => card.filename.clone(),
            None => String::new(),
        };
        assert_eq!(
            key_action,
            Action::OpenEditor(key_filename),
            "board 'e' returns OpenEditor for the same card"
        );
    }

    #[test]
    fn context_menu_view_issue_matches_v_key() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        app.handle_mouse(down_right(x, y)).unwrap();
        // Items: [Open detail, Edit, View issue, ...] -> two Downs reach View.
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap();
        let action = app.handle_key(press(KeyCode::Enter)).unwrap();

        let selected = app.board.get_selected_card().cloned().unwrap().filename;
        assert_eq!(
            action,
            Action::OpenViewer(selected.clone()),
            "menu View issue returns OpenViewer for the selected card"
        );

        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        let _ = app.handle_mouse(down_left(x, y)).unwrap();
        let key_action = app.handle_key(press(KeyCode::Char('v'))).unwrap();
        let key_filename = match app.board.get_selected_card() {
            Some(card) => card.filename.clone(),
            None => String::new(),
        };
        assert_eq!(
            key_action,
            Action::OpenViewer(key_filename),
            "board 'v' returns OpenViewer for the same card"
        );
    }

    #[test]
    fn detail_v_returns_open_viewer_for_the_open_issue() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        let _ = app.handle_mouse(down_left(x, y)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let number = app.detail.as_ref().unwrap().issue.number;

        let action = app.handle_key(press(KeyCode::Char('v'))).unwrap();
        let Action::OpenViewer(filename) = action else {
            panic!("detail 'v' must return OpenViewer");
        };
        let issue = app.store.get(IssueSelector::Filename(filename)).unwrap();
        assert_eq!(issue.number, number, "the viewer opens the detail's issue");
    }

    #[test]
    fn context_menu_move_to_matches_cardinal_move_key() {
        // Menu MoveTo { column: 2 } on the first card must produce the same
        // file state as '>' twice (0 -> 1 -> 2) on a matching board.
        fn moved_via_menu() -> Status {
            let (_tmp, mut app) = make_mouse_app();
            let (x, y) = card_cell(&app, 0, 0);
            app.handle_mouse(down_right(x, y)).unwrap();
            // Select the "Move to in review" (column 2) entry: items are
            // [Open detail, Edit in editor, View issue, Move to in progress (1),
            //  Move to in review (2), Move to done (3), Delete, Refresh].
            app.handle_key(press(KeyCode::Down)).unwrap();
            app.handle_key(press(KeyCode::Down)).unwrap();
            app.handle_key(press(KeyCode::Down)).unwrap();
            app.handle_key(press(KeyCode::Down)).unwrap();
            app.handle_key(press(KeyCode::Enter)).unwrap();
            app.store
                .get(IssueSelector::Filename("a.md".to_string()))
                .unwrap()
                .status
        }

        fn moved_via_keys() -> Status {
            let (_tmp, mut app) = make_mouse_app();
            let (x, y) = card_cell(&app, 0, 0);
            let _ = app.handle_mouse(down_left(x, y)).unwrap();
            let _ = app.handle_key(press(KeyCode::Char('>'))).unwrap();
            let _ = app.handle_key(press(KeyCode::Char('>'))).unwrap();
            app.store
                .get(IssueSelector::Filename("a.md".to_string()))
                .unwrap()
                .status
        }

        assert_eq!(moved_via_menu(), moved_via_keys());
    }

    #[test]
    fn context_menu_delete_sets_up_confirm() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 1);
        app.handle_mouse(down_right(x, y)).unwrap();
        // Items: [Open detail, Edit, View, 3x Move, Delete, Refresh] -> Delete is 6.
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert_eq!(app.mode, Mode::ConfirmDelete);
        assert_eq!(
            app.confirm_delete_target.as_deref(),
            Some("b.md"),
            "delete targets the right-clicked card"
        );
        assert!(!matches!(&app.mode, Mode::ContextMenu { .. }));
    }

    #[test]
    fn context_menu_refresh_rebuilds_board() {
        let (_tmp, mut app) = make_mouse_app();
        let (x, y) = card_cell(&app, 0, 0);
        app.handle_mouse(down_right(x, y)).unwrap();
        // Refresh Board is the last item (index 6).
        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert_eq!(app.mode, Mode::Board);
        assert_eq!(app.status_msg.as_deref(), Some("Refreshed"));
        assert!(app.context_menu.is_none());
    }

    #[test]
    fn context_menu_esc_closes_without_side_effects() {
        let (_tmp, mut app) = make_mouse_app();
        let (card_x, card_y) = card_cell(&app, 0, 1);
        app.handle_mouse(down_right(card_x, card_y)).unwrap();
        let status_before = app
            .store
            .get(IssueSelector::Filename("b.md".to_string()))
            .unwrap()
            .status
            .clone();

        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();

        assert_eq!(app.mode, Mode::Board);
        assert!(app.context_menu.is_none());
        assert_eq!((app.board.active_col, app.board.selected), (0, 1));
        assert!(app.confirm_delete_target.is_none());
        assert_eq!(
            app.store
                .get(IssueSelector::Filename("b.md".to_string()))
                .unwrap()
                .status,
            status_before,
            "Esc closes the menu without mutating any issue"
        );
    }

    #[test]
    fn context_menu_outside_click_closes_menu() {
        let (_tmp, mut app) = make_mouse_app();
        let (card_x, card_y) = card_cell(&app, 0, 1);
        app.handle_mouse(down_right(card_x, card_y)).unwrap();

        // Click far below the board area (outside the popup).
        let action = app.handle_mouse(down_left(40, 39)).unwrap();
        assert_eq!(action, Action::None);
        assert!(app.context_menu.is_none());
        assert_eq!(app.mode, Mode::Board);
        assert!(
            app.mouse.drag.is_none(),
            "the dismissing click must not start a drag"
        );
    }

    #[test]
    fn context_menu_item_click_activates() {
        let (_tmp, mut app) = make_mouse_app();
        let (card_x, card_y) = card_cell(&app, 0, 1);
        app.handle_mouse(down_right(card_x, card_y)).unwrap();
        let menu = app.context_menu.as_ref().unwrap();
        let bounds = menu.bounds(app.frame_size.get());
        let item_x = bounds.x + 2;
        // Row 6 is Delete: [Open, Edit, View, 3x Move, Delete, Refresh].
        let item_y = bounds.y + 1 + 6;
        let _ = app.handle_mouse(down_left(item_x, item_y)).unwrap();

        assert_eq!(app.mode, Mode::ConfirmDelete);
        assert_eq!(app.confirm_delete_target.as_deref(), Some("b.md"));
        assert!(app.context_menu.is_none());
    }

    #[test]
    fn custom_board_binding_replaces_default() {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let mut config = Config {
            issues_dir: dir,
            ..test_config()
        };
        config.keybindings.board.new_issue = Some(vec!["ctrl+n".into()]);
        let mut app = App::new(&config).unwrap();
        app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        app.handle_key(press_with_modifiers(
            KeyCode::Char('n'),
            crossterm::event::KeyModifiers::CONTROL,
        ))
        .unwrap();
        assert!(matches!(app.mode, Mode::Form));
    }

    /// An app whose config has a `[triage]` section, so the Triage mode can open.
    fn make_shell_app() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let mut config = Config::starter();
        config.layout.move_on_change = false;
        config.issues_dir = dir;
        let app = App::new(&config).unwrap();
        (tmp, app)
    }

    #[test]
    fn function_keys_switch_top_level_modes() {
        let (_tmp, mut app) = make_shell_app();
        assert_eq!(app.top_mode, TopMode::Board);

        // F1 New Issue, F2 Triage, F3 Board, F4 Cycles, F5 Milestones, F12 Config.
        app.handle_key(press(KeyCode::F(1))).unwrap();
        assert!(
            matches!(app.mode, Mode::Form),
            "F1 opens the New Issue mode's own content, got {:?}",
            app.mode
        );
        assert_eq!(app.top_mode, TopMode::NewIssue);

        app.handle_key(press(KeyCode::F(4))).unwrap();
        assert!(
            matches!(app.mode, Mode::Cycle),
            "F4 opens the Cycles mode, got {:?}",
            app.mode
        );
        assert_eq!(app.top_mode, TopMode::Cycle);

        app.handle_key(press(KeyCode::F(5))).unwrap();
        assert!(
            matches!(app.mode, Mode::Settings),
            "F5 opens the Milestones mode on the borrowed Config surface, got {:?}",
            app.mode
        );
        assert_eq!(app.top_mode, TopMode::Milestones);
        assert!(app.milestone_mode);
        assert_eq!(
            app.settings.as_ref().map(|s| s.section),
            Some(ConfigSection::Milestones)
        );

        app.handle_key(press(KeyCode::F(12))).unwrap();
        assert!(matches!(app.mode, Mode::Settings));
        assert_eq!(app.top_mode, TopMode::Config);
        assert!(!app.milestone_mode, "F12 is Config, not Milestones");

        app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(
            matches!(app.mode, Mode::TriageInbox),
            "F2 must open the triage inbox, got {:?}",
            app.mode
        );
        assert_eq!(app.top_mode, TopMode::Triage);

        app.handle_key(press(KeyCode::F(3))).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert_eq!(app.top_mode, TopMode::Board);
    }

    /// Leaving the Milestones mode and opening Config by its own key gives the
    /// Config surface, not a Milestones mode that leaked through the borrowed
    /// surface (`s`/`b` call `open_settings` directly, not `switch_top_mode`).
    #[test]
    fn config_opened_after_milestones_is_not_milestone_mode() {
        let (_tmp, mut app) = make_shell_app();
        app.handle_key(press(KeyCode::F(5))).unwrap();
        assert!(app.milestone_mode, "F5 is the Milestones mode");

        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Board));

        app.handle_key(press(KeyCode::Char('s'))).unwrap();
        assert!(matches!(app.mode, Mode::Settings));
        assert!(!app.milestone_mode, "`s` opens Config, not Milestones");
        assert_eq!(app.top_mode, TopMode::Config);
        assert_eq!(
            app.settings.as_ref().map(|s| s.section),
            Some(ConfigSection::Dashboards)
        );
    }

    /// `F2` inside the form keeps its local picker meaning: a context that binds the
    /// key wins over the shell (tui-mode-navigation, D2).
    #[test]
    fn f2_inside_form_opens_the_picker_instead_of_triage() {
        let (_tmp, mut app) = make_shell_app();
        app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert_eq!(app.top_mode, TopMode::NewIssue);

        // Focus a field that has a picker (`Title` has none), so opening the picker
        // is observable.
        app.form.as_mut().unwrap().focus = crate::ui::form::FormFocus::Labels;
        app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(matches!(app.mode, Mode::Form), "the form stays focused");
        assert!(
            app.form_picker.is_some(),
            "F2 must still open the form picker"
        );
        assert_eq!(
            app.top_mode,
            TopMode::NewIssue,
            "F2 must not have switched the shell to Triage"
        );
    }

    #[test]
    fn unbound_key_takes_the_f12_sentinel_path_unchanged() {
        let (_tmp, mut app) = make_shell_app();
        // F6..F11 are reserved and bound nowhere, so they fall through to the
        // sentinel rewrite and do nothing rather than switching modes.
        app.handle_key(press(KeyCode::F(7))).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert_eq!(app.top_mode, TopMode::Board);
        // An F-key the shell does not bind resolves to no action in the shell.
        assert_eq!(
            app.bindings.action(
                InputContext::Shell,
                KeyEvent::new(KeyCode::F(7), KeyModifiers::NONE)
            ),
            None
        );
    }

    #[test]
    fn navigation_toggle_cycles_display_states() {
        let (_tmp, mut app) = make_app();
        assert_eq!(app.nav_display, NavDisplay::Default);
        let toggle = |app: &mut App| {
            app.handle_key(press_with_modifiers(
                KeyCode::Char('n'),
                crossterm::event::KeyModifiers::CONTROL,
            ))
        };
        toggle(&mut app).unwrap();
        assert_eq!(app.nav_display, NavDisplay::Off);
        toggle(&mut app).unwrap();
        assert_eq!(app.nav_display, NavDisplay::Small);
        toggle(&mut app).unwrap();
        assert_eq!(app.nav_display, NavDisplay::Default);
    }

    #[test]
    fn navigation_renders_in_all_three_display_states() {
        let (_tmp, mut app) = make_app();

        app.nav_display = NavDisplay::Default;
        let cells = draw_board(&app, 80, 24);
        assert!(
            flush_line(&cells, 80, 0).starts_with("F1 New Issue"),
            "default navigation shows the full label, got {:?}",
            flush_line(&cells, 80, 0)
        );

        app.nav_display = NavDisplay::Small;
        let cells = draw_board(&app, 80, 24);
        let row = flush_line(&cells, 80, 0);
        assert!(
            row.starts_with("F1 ") && !row.starts_with("F1 New Issue"),
            "small navigation shows only the chord, got {row:?}"
        );

        app.nav_display = NavDisplay::Off;
        let cells = draw_board(&app, 80, 24);
        assert!(
            !flush_line(&cells, 80, 0).starts_with("F1"),
            "off navigation draws nothing in the left column"
        );
    }

    #[test]
    fn hovering_a_navigation_entry_highlights_it_without_switching() {
        let (_tmp, mut app) = make_app();
        // Draw first: the entry rects are recorded by the renderer.
        let _ = draw_board(&app, 80, 24);
        assert!(!app.is_hovered(&Action::SwitchMode(TopMode::Cycle)));

        // Row 4 is `F4 Cycles`: row 3 is the single-board limb (`default`).
        let action = app.handle_mouse(moved_to(0, 4)).unwrap();
        assert_eq!(action, Action::None, "hover never acts");
        assert!(
            app.is_hovered(&Action::SwitchMode(TopMode::Cycle)),
            "the F4 entry must read as hovered"
        );
        assert_eq!(app.top_mode, TopMode::Board, "hover never switches mode");

        // And the hover is drawn: the rail row carries the hover background.
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;
        let backend = TestBackend::new(80, 24);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| crate::app::render(&app, f, f.area()))
            .unwrap();
        let buffer = terminal.backend().buffer();
        assert_eq!(
            buffer[(0, 4)].style().bg,
            Some(ratatui::style::Color::DarkGray),
            "the hovered Cycles entry is highlighted in the rail"
        );
        // The active mode's row (Board, row 2) keeps its own colour.
        assert_eq!(
            buffer[(0, 2)].style().bg,
            Some(ratatui::style::Color::Cyan),
            "the active entry is not overwritten by the hover"
        );

        // Leaving the rail clears it.
        app.handle_mouse(moved_to(60, 20)).unwrap();
        assert!(!app.is_hovered(&Action::SwitchMode(TopMode::Cycle)));
    }

    #[test]
    fn clicking_a_navigation_entry_switches_mode() {
        let (_tmp, mut app) = make_app();
        app.nav_display = NavDisplay::Default;
        // Draw first: the entry rects are recorded by the renderer.
        let _ = draw_board(&app, 80, 24);
        // Row 4 is `F4 Cycles` (row 3 is the board limb).
        let action = app.handle_mouse(down_left(0, 4)).unwrap();
        assert_eq!(action, Action::SwitchMode(TopMode::Cycle));
        app.switch_top_mode(TopMode::Cycle).unwrap();
        assert!(matches!(app.mode, Mode::Cycle));
        assert_eq!(app.top_mode, TopMode::Cycle);
    }

    #[test]
    fn letter_keys_still_open_each_mode() {
        // The F-keys are additive: the existing letters keep working.
        let (_tmp, mut app) = make_shell_app();
        app.handle_key(press(KeyCode::Char('m'))).unwrap();
        assert!(matches!(app.mode, Mode::PlanningManagement));
        assert_eq!(app.top_mode, TopMode::Cycle);
        app.handle_key(press(KeyCode::Esc)).unwrap();
        app.handle_key(press(KeyCode::Char('t'))).unwrap();
        assert!(matches!(app.mode, Mode::TriageInbox));
        assert_eq!(app.top_mode, TopMode::Triage);
    }

    // -----------------------------------------------------------------------
    // Navigation tree (tui-mode-navigation, tasks 2/3)
    // -----------------------------------------------------------------------

    /// An app with two boards and two templates, so both the Boards and the
    /// New Issue limbs have rows. Written through `tix.toml` and re-read, so the
    /// limb comes from the same config the surfaces read.
    fn make_branchy_app() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let mut config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        config.kanban.configurations.insert(
            "release".into(),
            crate::config::BoardConfiguration::default(),
        );
        config.templates.insert(
            "bug".into(),
            crate::config::IssueTemplate {
                body: Some("## Steps\n".into()),
                labels: vec!["bug".into()],
                ..crate::config::IssueTemplate::default()
            },
        );
        config.templates.insert(
            "feature".into(),
            crate::config::IssueTemplate {
                body: Some("## Motivation\n".into()),
                labels: vec!["enhancement".into()],
                ..crate::config::IssueTemplate::default()
            },
        );
        let path = tmp.path().join("tix.toml");
        config.save(&path).unwrap();
        let config = Config::load_with_warning(&path, |_| {}).unwrap();
        let app = App::new(&config).unwrap();
        (tmp, app)
    }

    /// Every configured board is listed under the Board trunk, and the active one
    /// is marked (`NavBranch::active`) so the rail draws it bold.
    #[test]
    fn boards_limb_lists_every_board_and_marks_the_active_one() {
        // A single board is still listed (and is the active one).
        let (_tmp, app) = make_app();
        let board = app
            .nav_tree()
            .into_iter()
            .find(|node| node.mode == TopMode::Board)
            .expect("the Board trunk exists");
        assert_eq!(
            board
                .branches
                .iter()
                .map(|b| b.label.as_str())
                .collect::<Vec<_>>(),
            vec!["default"]
        );
        assert_eq!(board.branches[0].kind, crate::ui::nav::BranchKind::Board);
        assert!(board.branches[0].active, "the only board is active");

        // Two boards: both listed, only the active one marked.
        let (_tmp, app) = make_branchy_app();
        let board = app
            .nav_tree()
            .into_iter()
            .find(|node| node.mode == TopMode::Board)
            .expect("the Board trunk exists");
        assert_eq!(
            board
                .branches
                .iter()
                .map(|b| b.label.as_str())
                .collect::<Vec<_>>(),
            vec!["default", "release"]
        );
        assert_eq!(
            board
                .branches
                .iter()
                .filter(|b| b.active)
                .map(|b| b.label.as_str())
                .collect::<Vec<_>>(),
            vec!["default"],
            "exactly the active board is marked"
        );
    }

    /// The active board's limb row is drawn in bold; the others are not.
    #[test]
    fn active_board_limb_is_drawn_bold() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;
        let (_tmp, mut app) = make_branchy_app();
        app.nav_display = NavDisplay::Default;
        let backend = TestBackend::new(80, 24);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| crate::app::render(&app, f, f.area()))
            .unwrap();
        let buffer = terminal.backend().buffer();
        // Rows: 0 F1 New Issue, 1 bug, 2 feature, 3 F2 Triage, 4 F3 Board,
        // 5 `default` (active board), 6 `release`. Branch text starts at col 2.
        assert!(
            buffer[(2, 5)].style().add_modifier.contains(Modifier::BOLD),
            "the active board limb is bold: {:?}",
            buffer[(2, 5)].style()
        );
        assert!(
            !buffer[(2, 6)].style().add_modifier.contains(Modifier::BOLD),
            "a non-active board limb is not bold: {:?}",
            buffer[(2, 6)].style()
        );
    }

    /// Templates, cycles and milestones each become a limb under their trunk,
    /// with the action that activates them (acceptance 3).
    #[test]
    fn template_cycle_and_milestone_limbs_carry_their_actions() {
        let (_tmp, app) = make_branchy_app();
        let templates = app
            .nav_tree()
            .into_iter()
            .find(|node| node.mode == TopMode::NewIssue)
            .expect("the New Issue trunk exists");
        assert_eq!(
            templates
                .branches
                .iter()
                .map(|b| b.action.clone())
                .collect::<Vec<_>>(),
            vec![
                Action::NewFromTemplate("bug".into()),
                Action::NewFromTemplate("feature".into()),
            ]
        );

        let (_tmp, app) = make_cycle_app();
        let cycles = app
            .nav_tree()
            .into_iter()
            .find(|node| node.mode == TopMode::Cycle)
            .expect("the Cycles trunk exists");
        assert_eq!(
            cycles
                .branches
                .iter()
                .map(|b| b.label.as_str())
                .collect::<Vec<_>>(),
            vec!["Historical", "Ongoing", "Later"]
        );

        // A milestone registry file becomes a Milestones limb.
        let planner =
            crate::planning::Planner::from_config(app.store.config.clone(), app.project_root());
        planner
            .create_milestone_file("Backlog", None, None)
            .expect("milestone file is created");
        let milestones = app
            .nav_tree()
            .into_iter()
            .find(|node| node.mode == TopMode::Milestones)
            .expect("the Milestones trunk exists");
        assert_eq!(
            milestones
                .branches
                .iter()
                .map(|b| b.action.clone())
                .collect::<Vec<_>>(),
            vec![Action::SelectMilestone("Backlog".into())]
        );
    }

    /// The rail draws one indented row per trunk and per limb, and each limb row
    /// records its own click target (acceptance 2/3).
    #[test]
    fn rail_draws_indented_limbs_with_click_regions() {
        let (_tmp, mut app) = make_branchy_app();
        app.nav_display = NavDisplay::Default;
        let cells = draw_board(&app, 80, 24);
        assert!(
            flush_line(&cells, 80, 0).starts_with("F1 New Issue"),
            "the New Issue trunk is the first row: {:?}",
            flush_line(&cells, 80, 0)
        );
        assert!(
            flush_line(&cells, 80, 1).starts_with("  bug"),
            "the first template limb is indented: {:?}",
            flush_line(&cells, 80, 1)
        );
        assert!(flush_line(&cells, 80, 2).starts_with("  feature"));

        // The limb row resolves to its own action, not the trunk's.
        let hovered = app.handle_mouse(moved_to(0, 1)).unwrap();
        assert_eq!(hovered, Action::None, "hover never acts");
        assert!(
            app.is_hovered(&Action::NewFromTemplate("bug".into())),
            "the template row must read as hovered"
        );
        let clicked = app.handle_mouse(down_left(0, 1)).unwrap();
        assert_eq!(clicked, Action::NewFromTemplate("bug".into()));
    }

    /// `Small` abbreviates each limb row to two characters while trunk rows keep
    /// their chord (acceptance 4).
    #[test]
    fn small_navigation_abbreviates_limb_labels() {
        let (_tmp, mut app) = make_branchy_app();
        app.nav_display = NavDisplay::Small;
        let cells = draw_board(&app, 80, 24);
        let row0 = flush_line(&cells, 80, 0);
        assert!(
            row0.starts_with("F1") && !row0.starts_with("F1 New Issue"),
            "small trunk shows only the chord: {row0:?}"
        );
        assert!(
            flush_line(&cells, 80, 1).starts_with("  bu"),
            "the template limb is abbreviated: {:?}",
            flush_line(&cells, 80, 1)
        );
        assert!(flush_line(&cells, 80, 2).starts_with("  fe"));
    }

    /// Activating a branch reaches the same target its own surface does: the
    /// board switches, the cycle cursor lands on the named cycle, the template
    /// seeds the New Issue form.
    #[test]
    fn activating_a_branch_reaches_its_target() {
        // Board: switch to the non-active board and show the Board mode.
        let (_tmp, mut app) = make_branchy_app();
        app.activate_branch(&Action::SelectBoard("release".into()))
            .unwrap();
        assert!(matches!(app.mode, Mode::Board));
        assert_eq!(app.active_board_name(), "release");
        assert_eq!(app.top_mode, TopMode::Board);

        // Cycle: enter the mode with the cursor on the named cycle.
        let (_tmp, mut app) = make_cycle_app();
        app.activate_branch(&Action::SelectCycle("Ongoing".into()))
            .unwrap();
        assert!(matches!(app.mode, Mode::Cycle));
        assert_eq!(app.top_mode, TopMode::Cycle);
        assert_eq!(
            app.cycle_state.as_ref().map(|s| s.selected),
            Some(1),
            "the cursor lands on Ongoing"
        );

        // Template: open the New Issue form seeded from the record.
        let (_tmp, mut app) = make_templated_app();
        app.activate_branch(&Action::NewFromTemplate("bug".into()))
            .unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert_eq!(app.top_mode, TopMode::NewIssue);
        assert_eq!(app.form.as_ref().map(|f| f.template.as_str()), Some("bug"));
    }

    /// The F5 Milestones mode is the Config surface pinned to the milestones
    /// section, focused on the branch's milestone; its registry renders the same
    /// rows the Config section draws (task 5).
    #[test]
    fn milestone_branch_focuses_and_renders_the_registry() {
        let (_tmp, mut app) = make_app();
        let planner =
            crate::planning::Planner::from_config(app.store.config.clone(), app.project_root());
        planner
            .create_milestone_file("Backlog", None, Some("first things first"))
            .unwrap();
        planner.create_milestone_file("Q4", None, None).unwrap();

        app.activate_branch(&Action::SelectMilestone("Q4".into()))
            .unwrap();
        assert!(matches!(app.mode, Mode::Settings));
        assert_eq!(app.top_mode, TopMode::Milestones);
        assert!(app.milestone_mode);
        assert_eq!(
            app.settings.as_ref().map(|s| s.section),
            Some(ConfigSection::Milestones)
        );
        assert_eq!(app.planning.as_ref().map(|m| m.selected), Some(1));

        let cells = draw_board(&app, 80, 24);
        let text = cells.concat();
        assert!(
            text.contains("Backlog") && text.contains("Q4"),
            "both milestones render: {text:?}"
        );
        assert!(
            !text.contains(" Dashboards — "),
            "the Milestones mode draws no section rail"
        );
    }

    /// The Config mode's Types and Attributes sections add and remove entries,
    /// and both round-trip through `tix.toml` (acceptance 5).
    #[test]
    fn config_types_and_attributes_round_trip() {
        let (tmp, mut app) = make_app();
        let path = tmp.path().join("tix.toml");

        app.open_settings(None);
        app.config_set_section(ConfigSection::Types);
        app.settings.as_mut().unwrap().focus(ConfigPane::Body);

        app.handle_key(press(KeyCode::Char('n'))).unwrap();
        type_text(&mut app, "epic");
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            app.store.config.custom_types().iter().any(|t| t == "epic"),
            "the type is added in memory"
        );
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert!(
            reloaded.custom_types().iter().any(|t| t == "epic"),
            "the type is persisted to tix.toml"
        );

        let index = app
            .store
            .config
            .custom_types()
            .iter()
            .position(|t| t == "epic")
            .unwrap();
        app.settings.as_mut().unwrap().selected = index;
        app.handle_key(press(KeyCode::Char('x'))).unwrap();
        assert!(!app.store.config.custom_types().iter().any(|t| t == "epic"));
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert!(!reloaded.custom_types().iter().any(|t| t == "epic"));

        // Attributes: with no `[custom_attributes]` declared, the section lists
        // the built-in attributes; adding one materializes them plus the new key
        // (mirrors the Types section).
        app.config_set_section(ConfigSection::CustomAttributes);
        app.settings.as_mut().unwrap().focus(ConfigPane::Body);
        assert!(
            app.store.config.attributes().iter().any(|a| a == "type"),
            "the built-in attributes are listed when none are declared: {:?}",
            app.store.config.attributes()
        );
        app.handle_key(press(KeyCode::Char('n'))).unwrap();
        type_text(&mut app, "build_id");
        app.handle_key(press(KeyCode::Enter)).unwrap();
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert!(
            reloaded
                .custom_attributes
                .keys
                .iter()
                .any(|k| k == "build_id"),
            "the attribute round-trips: {:?}",
            reloaded.custom_attributes.keys
        );

        let index = app
            .store
            .config
            .attributes()
            .iter()
            .position(|a| a == "build_id")
            .unwrap();
        app.settings.as_mut().unwrap().selected = index;
        app.handle_key(press(KeyCode::Char('x'))).unwrap();
        let reloaded = Config::load_with_warning(&path, |_| {}).unwrap();
        assert!(
            !reloaded
                .custom_attributes
                .keys
                .iter()
                .any(|k| k == "build_id"),
            "the attribute is removed: {:?}",
            reloaded.custom_attributes.keys
        );
    }

    // -----------------------------------------------------------------------
    // F3 Cycle mode (tui-cycle-mode, tasks 5.1/5.2)
    // -----------------------------------------------------------------------

    /// An app with an archived, a current (no end date), and a future cycle,
    /// plus one issue done and one open in the current cycle. The pending
    /// rollover the expired cycle would raise is cleared so the tests start on
    /// the board.
    fn make_cycle_app() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(dir.join("alice")).unwrap();
        let mut config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        let cycle =
            |description: &str, start: &str, due: Option<&str>| crate::config::PlanningCycle {
                description: Some(description.to_string()),
                start_date: Some(start.to_string()),
                due_date: due.map(str::to_string),
            };
        config.cycles.insert(
            "Historical".into(),
            cycle("old", "2000-01-01", Some("2000-02-01")),
        );
        config
            .cycles
            .insert("Ongoing".into(), cycle("open", "2026-01-01", None));
        config.cycles.insert(
            "Later".into(),
            cycle("future", "2999-01-01", Some("2999-02-01")),
        );
        for (name, number, status, cycle) in [
            ("2026-01-01-done.md", 1, "done", "Ongoing"),
            ("2026-01-02-open.md", 2, "todo", "Ongoing"),
            ("2026-01-03-old.md", 3, "todo", "Historical"),
        ] {
            fs::write(
                dir.join("alice").join(name),
                format!(
                    "---\nnumber: {number}\ntitle: \"Issue {number}\"\nstatus: \"{status}\"\n\
                     labels: []\npriority: \"medium\"\ncycles: [\"{cycle}\"]\n\
                     created: 2026-01-01\nupdated: 2026-01-01\n---\n\nBody."
                ),
            )
            .unwrap();
        }
        let config_path = tmp.path().join("tix.toml");
        config.save(&config_path).unwrap();
        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        let mut app = App::new(&config).unwrap();
        // The expired `Historical` cycle would otherwise raise the startup
        // rollover dialog; the mode tests want the board.
        app.rollover_dialog = None;
        app.mode = Mode::Board;
        (tmp, app)
    }

    #[test]
    fn f4_opens_the_cycle_mode_and_highlights_it() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        assert!(matches!(app.mode, Mode::Cycle));
        assert_eq!(
            app.top_mode,
            TopMode::Cycle,
            "the navigation highlights Cycle"
        );
        assert!(app.cycle_state.is_some(), "the mode owns its cursor");
    }

    #[test]
    fn cycle_mode_groups_cycles_chronologically() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        let groups = app.cycle_groups();
        let group_of = |name: &str| {
            groups
                .iter()
                .find(|group| group.entries.iter().any(|entry| entry.name == name))
                .map(|group| group.group)
        };
        assert_eq!(
            group_of("Ongoing"),
            Some(crate::ui::cycle::CycleGroup::Current),
            "a start date with no end date is the current cycle"
        );
        assert_eq!(
            group_of("Default"),
            Some(crate::ui::cycle::CycleGroup::Current),
            "the implicit Default cycle is current"
        );
        assert_eq!(
            group_of("Later"),
            Some(crate::ui::cycle::CycleGroup::Future)
        );
        assert_eq!(
            group_of("Historical"),
            Some(crate::ui::cycle::CycleGroup::Archived)
        );
        let order: Vec<&str> = crate::ui::cycle::flat_entries(&groups)
            .into_iter()
            .map(|entry| entry.name.as_str())
            .collect();
        assert_eq!(
            order,
            vec!["Default", "Ongoing", "Later", "Historical"],
            "current first, then future, then archived"
        );
    }

    #[test]
    fn cycle_mode_statistics_are_progress_and_zero_for_an_empty_cycle() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        let entries = app.cycle_entries();
        let progress = |name: &str| {
            entries
                .iter()
                .find(|entry| entry.name == name)
                .map(|entry| (entry.progress.done, entry.progress.total))
                .unwrap()
        };
        assert_eq!(progress("Ongoing"), (1, 2), "one of two issues complete");
        assert_eq!(
            progress("Later"),
            (0, 0),
            "an empty cycle renders zeros, not an error"
        );
    }

    #[test]
    fn cycle_mode_renders_group_headings_and_selected_statistics() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        // Ordinal 1 is `Ongoing` (Default is ordinal 0), so its stats show.
        app.select_cycle_row(1);
        let text = draw_board(&app, 80, 24).concat();
        assert!(text.contains("Ongoing"), "the cycle row is listed: {text}");
        assert!(
            text.contains("Completed: 1/2"),
            "the selected cycle's progress renders: {text}"
        );
        assert!(text.contains("Current"), "current heading: {text}");
        assert!(text.contains("Future"), "future heading: {text}");
        assert!(text.contains("Archived"), "archived heading: {text}");
    }

    #[test]
    fn cycle_mode_cursor_moves_with_keys() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(app.cycle_state.unwrap().selected, 1);
        app.handle_key(press(KeyCode::Char('k'))).unwrap();
        assert_eq!(app.cycle_state.unwrap().selected, 0);
        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(matches!(app.mode, Mode::Board), "Esc leaves the mode");
    }

    #[test]
    fn cycle_mode_h_and_l_jump_between_groups_and_clamp() {
        // Flat order: Default, Ongoing | Later | Historical. `l` lands on the
        // first entry of the next rendered group, `h` on the previous one, and
        // neither end wraps.
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        let selected = |app: &App| app.cycle_state.unwrap().selected;
        assert_eq!(selected(&app), 0);

        app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(selected(&app), 2, "`l` jumps to the first Future entry");
        app.handle_key(press(KeyCode::Right)).unwrap();
        assert_eq!(selected(&app), 3, "the arrow jumps to Archived");
        app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(selected(&app), 3, "the last group clamps");

        app.handle_key(press(KeyCode::Char('h'))).unwrap();
        assert_eq!(selected(&app), 2, "`h` jumps back to Future");
        app.handle_key(press(KeyCode::Left)).unwrap();
        assert_eq!(selected(&app), 0, "the arrow jumps back to Current");
        app.handle_key(press(KeyCode::Char('h'))).unwrap();
        assert_eq!(selected(&app), 0, "the first group clamps");
    }

    #[test]
    fn cycle_mode_h_from_inside_a_group_lands_on_its_first_entry() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        // Ordinal 1 is `Ongoing`, the second Current entry.
        app.select_cycle_row(1);
        app.handle_key(press(KeyCode::Char('h'))).unwrap();
        assert_eq!(
            app.cycle_state.unwrap().selected,
            0,
            "the previous group is clamped to Current, whose first entry is ordinal 0"
        );
        app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(
            app.cycle_state.unwrap().selected,
            2,
            "and `l` still reaches the next rendered group"
        );
    }

    #[test]
    fn clicking_a_cycle_row_selects_it() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        // Draw first: the row rects are recorded by the renderer. The default
        // navigation takes 14 columns, the group heading is row 1, so the
        // second entry (`Ongoing`) is row 3.
        let _ = draw_board(&app, 80, 24);
        let action = app.handle_mouse(down_left(20, 3)).unwrap();
        assert_eq!(
            action,
            Action::CycleSelect(1),
            "a click on the second row maps to the second cycle"
        );
        app.select_cycle_row(1);
        assert_eq!(app.cycle_state.unwrap().selected, 1);
        assert!(matches!(app.mode, Mode::Cycle));
    }

    #[test]
    fn planning_management_opens_from_cycle_mode_and_returns_to_it() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        app.select_cycle_row(1);
        app.handle_key(press(KeyCode::Char('m'))).unwrap();
        assert!(
            matches!(app.mode, Mode::PlanningManagement),
            "m opens the planning surface from the Cycle mode"
        );
        assert!(app.planning.is_some());
        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(
            matches!(app.mode, Mode::Cycle),
            "Esc returns to the Cycle mode, got {:?}",
            app.mode
        );
        assert!(app.planning.is_none());
        assert_eq!(
            app.cycle_state.unwrap().selected,
            1,
            "the mode is shown again in its previous state"
        );
    }

    #[test]
    fn cycle_mode_renders_on_a_tiny_terminal() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        for (width, height) in [(20_u16, 5_u16), (1, 1), (80, 3), (15, 24)] {
            let _ = draw_board(&app, width, height);
        }
    }

    #[test]
    fn help_in_cycle_mode_returns_to_the_cycle_mode() {
        let (_tmp, mut app) = make_cycle_app();
        app.handle_key(press(KeyCode::F(4))).unwrap();
        app.handle_key(press(KeyCode::Char('?'))).unwrap();
        assert!(matches!(app.mode, Mode::Help { .. }));
        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(
            matches!(app.mode, Mode::Cycle),
            "closing help returns to the Cycle mode, got {:?}",
            app.mode
        );
    }

    #[test]
    fn form_creation_without_a_cycle_selection_joins_the_default_cycle() {
        let (_tmp, mut app) = make_app();
        app.handle_key(press(KeyCode::Char('n'))).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        app.form.as_mut().unwrap().title = "Fresh".into();
        app.handle_key(press(KeyCode::Enter)).unwrap();
        let issue = app
            .store
            .list()
            .unwrap()
            .into_iter()
            .find(|issue| issue.title == "Fresh")
            .expect("the form created the issue");
        assert_eq!(issue.cycles, Some(vec!["Default".to_string()]));
    }

    // -----------------------------------------------------------------------
    // F4 New Issue mode (tui-new-issue-mode, tasks 6.1/6.2)
    // -----------------------------------------------------------------------

    /// An app whose `[templates.<name>]` holds two records. Written through
    /// `tix.toml` and re-read, so the test depends on the config round trip the
    /// feature promises rather than on a hand-set field.
    fn make_templated_app() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let mut config = Config::starter();
        config.layout.move_on_change = false;
        config.issues_dir = dir;
        config.templates.insert(
            "bug".into(),
            crate::config::IssueTemplate {
                body: Some("## Steps to reproduce\n\n## Expected\n".into()),
                labels: vec!["bug".into()],
                ..crate::config::IssueTemplate::default()
            },
        );
        config.templates.insert(
            "feature".into(),
            crate::config::IssueTemplate {
                body: Some("## Motivation\n".into()),
                labels: vec!["enhancement".into()],
                ..crate::config::IssueTemplate::default()
            },
        );
        let path = tmp.path().join("tix.toml");
        config.save(&path).unwrap();
        let config = Config::load_with_warning(&path, |_| {}).unwrap();
        assert!(
            config.templates.contains_key("bug"),
            "templates must survive the tix.toml round trip"
        );
        let app = App::new(&config).unwrap();
        (tmp, app)
    }

    fn type_text(app: &mut App, text: &str) {
        for c in text.chars() {
            app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
    }

    #[test]
    fn f1_opens_the_new_issue_mode_as_content() {
        let (_tmp, mut app) = make_shell_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert_eq!(app.top_mode, TopMode::NewIssue);

        // The form is the mode content beside the navigation, not a modal: the
        // block's `New Issue` title shares row 0 with the nav column.
        let cells = draw_board(&app, 80, 24);
        let row0 = flush_line(&cells, 80, 0);
        assert!(
            row0.starts_with("F1"),
            "navigation still occupies the left column: {row0:?}"
        );
        assert!(
            row0.contains("New Issue"),
            "the form block is the mode content: {row0:?}"
        );
    }

    #[test]
    fn new_issue_defaults_to_todo_and_creates_there() {
        let (_tmp, mut app) = make_shell_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        let form = app.form.as_ref().unwrap();
        assert_eq!(form.target, crate::ui::form::NewIssueTarget::Todo);
        assert_eq!(
            form.status, "todo",
            "the default target seeds the status row"
        );

        type_text(&mut app, "Todo bound");
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Board));
        let issue = app
            .store
            .list()
            .unwrap()
            .into_iter()
            .find(|i| i.title == "Todo bound")
            .expect("the mode created the issue");
        assert_eq!(issue.status.to_string(), "todo");
    }

    #[test]
    fn new_issue_target_triage_creates_into_the_entry_status() {
        let (_tmp, mut app) = make_shell_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        type_text(&mut app, "Inbox bound");

        // Walk to the Target row (last three rows of the ring) and flip it.
        for _ in 0..12 {
            app.handle_key(press(KeyCode::Down)).unwrap();
        }
        assert_eq!(
            app.form.as_ref().unwrap().focus,
            crate::ui::form::FormFocus::Target
        );
        app.handle_key(press(KeyCode::Enter)).unwrap();
        let form = app.form.as_ref().unwrap();
        assert_eq!(form.target, crate::ui::form::NewIssueTarget::Triage);
        assert_eq!(
            form.status, "triage",
            "choosing Triage writes the inbox entry status"
        );

        // Off the toggle and onto the body row, so Enter submits rather than
        // flipping the target back.
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap();
        assert_eq!(
            app.form.as_ref().unwrap().focus,
            crate::ui::form::FormFocus::Body
        );
        app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(matches!(app.mode, Mode::Board));
        let issue = app
            .store
            .list()
            .unwrap()
            .into_iter()
            .find(|i| i.title == "Inbox bound")
            .expect("the mode created the issue");
        assert_eq!(issue.status.to_string(), "triage");
        assert!(
            issue.entered_at.is_some(),
            "an issue created into the inbox carries the entry stamp the queue ages from"
        );
    }

    #[test]
    fn new_issue_mode_rejects_an_empty_title() {
        let (_tmp, mut app) = make_shell_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Form), "the mode stays open");
        assert_eq!(app.status_msg.as_deref(), Some("Title is required"));
        assert!(app.store.list().unwrap().is_empty(), "nothing was written");
    }

    /// The Status dropdown offers exactly the board's columns, in board order
    /// (tix #1508), plus the field's current value when the board no longer
    /// configures it — a status the board dropped must stay selectable.
    #[test]
    fn status_picker_options_are_the_board_columns_plus_an_off_board_current_value() {
        let (_tmp, mut app) = make_app();
        let columns = app.active_board_config().columns.clone();
        assert_eq!(columns, vec!["todo", "in progress", "in review", "done"]);

        app.handle_key(press(KeyCode::F(1))).unwrap();
        let ids = |app: &App| -> Vec<String> {
            app.picker_options(FormPickerField::Status)
                .into_iter()
                .map(|item| item.id)
                .collect()
        };
        assert_eq!(
            ids(&app),
            columns,
            "the options are the board's columns, in board order"
        );

        // A status the board does not configure is appended, once.
        app.form.as_mut().unwrap().status = "legacy".to_string();
        let mut expected = columns.clone();
        expected.push("legacy".to_string());
        assert_eq!(ids(&app), expected);
        assert_eq!(
            ids(&app)
                .iter()
                .filter(|id| id.as_str() == "legacy")
                .count(),
            1,
            "the current value is appended once, not duplicated"
        );

        // A current value that *is* a column is not repeated.
        app.form.as_mut().unwrap().status = "done".to_string();
        assert_eq!(ids(&app), columns);
    }

    /// The Priority dropdown is the built-in `low`/`medium`/`high` (tix #1508),
    /// then every priority the store already uses, then the current value —
    /// de-duplicated, built-ins first.
    #[test]
    fn priority_picker_options_are_built_ins_then_priorities_in_use() {
        let (tmp, mut app) = make_app();
        let dir = tmp.path().join("issues");
        fs::write(
            dir.join("2026-01-01-urgent.md"),
            "---\nnumber: 1\ntitle: \"Urgent\"\nstatus: \"todo\"\nlabels: []\n\
             priority: \"urgent\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\n\
             Body.",
        )
        .unwrap();
        app.refresh_corpus().unwrap();
        app.handle_key(press(KeyCode::F(1))).unwrap();

        let ids = |app: &App| -> Vec<String> {
            app.picker_options(FormPickerField::Priority)
                .into_iter()
                .map(|item| item.id)
                .collect()
        };
        assert_eq!(
            ids(&app),
            vec!["low", "medium", "high", "urgent"],
            "built-ins first, then a priority the store uses"
        );

        // The default `medium` is already a built-in, so it is not repeated.
        app.form.as_mut().unwrap().priority = "medium".to_string();
        assert_eq!(ids(&app), vec!["low", "medium", "high", "urgent"]);

        // A custom current value the store does not carry yet is appended.
        app.form.as_mut().unwrap().priority = "blocker".to_string();
        assert_eq!(
            ids(&app),
            vec!["low", "medium", "high", "urgent", "blocker"]
        );
    }

    /// Status and Priority are reachable from the keyboard (tix #1508): `Enter`
    /// and `F2` both open their dropdown, and `Enter` on those rows never submits.
    #[test]
    fn enter_and_f2_open_the_status_and_priority_dropdowns() {
        let (_tmp, mut app) = make_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap(); // Title -> Status
        assert_eq!(
            app.form.as_ref().unwrap().focus,
            crate::ui::form::FormFocus::Status
        );

        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            app.form_picker
                .as_ref()
                .is_some_and(|p| p.field == FormPickerField::Status),
            "Enter on Status opens its dropdown"
        );
        assert!(
            matches!(app.mode, Mode::Form),
            "Enter on Status must not submit the form"
        );
        assert!(app.store.list().unwrap().is_empty(), "nothing was written");
        let picker = app.form_picker.as_ref().unwrap();
        assert_eq!(
            match &picker.state.selection {
                SelectionModel::Single(current) => current.clone(),
                SelectionModel::Multi(_) => panic!("Status must be single-select"),
            },
            Some("todo".to_string()),
            "the dropdown opens on the row's current value"
        );
        app.handle_key(press(KeyCode::Esc)).unwrap();
        assert!(app.form_picker.is_none(), "Esc closes the dropdown");

        app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(
            app.form_picker
                .as_ref()
                .is_some_and(|p| p.field == FormPickerField::Status),
            "F2 opens the Status dropdown too"
        );
        app.handle_key(press(KeyCode::Esc)).unwrap();

        app.handle_key(press(KeyCode::Down)).unwrap(); // Status -> Priority
        assert_eq!(
            app.form.as_ref().unwrap().focus,
            crate::ui::form::FormFocus::Priority
        );
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            app.form_picker
                .as_ref()
                .is_some_and(|p| p.field == FormPickerField::Priority),
            "Enter on Priority opens its dropdown"
        );
        assert!(
            matches!(app.mode, Mode::Form),
            "Enter on Priority must not submit"
        );
        app.handle_key(press(KeyCode::Esc)).unwrap();
        app.handle_key(press(KeyCode::F(2))).unwrap();
        assert!(
            app.form_picker
                .as_ref()
                .is_some_and(|p| p.field == FormPickerField::Priority),
            "F2 opens the Priority dropdown too"
        );
    }

    /// Choosing an option writes the row, and the created issue lands in that
    /// column (tix #1508).
    #[test]
    fn choosing_a_status_creates_the_issue_in_that_column() {
        let (_tmp, mut app) = make_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        type_text(&mut app, "Placed");

        app.handle_key(press(KeyCode::Down)).unwrap(); // Title -> Status
        app.handle_key(press(KeyCode::Enter)).unwrap(); // open the dropdown
        // The options are the board's columns; the cursor starts on the first
        // (`todo`), so one `Down` lands on `in progress`.
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(app.form.as_ref().unwrap().status, "in progress");

        app.handle_key(press(KeyCode::Esc)).unwrap(); // close the dropdown
        // Submit from a row Enter still submits from.
        app.form.as_mut().unwrap().focus = crate::ui::form::FormFocus::Body;
        app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(matches!(app.mode, Mode::Board));
        let issue = app
            .store
            .list()
            .unwrap()
            .into_iter()
            .find(|i| i.title == "Placed")
            .expect("the mode created the issue");
        assert_eq!(issue.status.to_string(), "in progress");

        // And the card really sits in that column on the board, not just in the
        // file: the chosen status is the created issue's column.
        let names: Vec<String> = (0..app.board.total_cols())
            .map(|i| app.board.column_name(i).to_string())
            .collect();
        let idx = names
            .iter()
            .position(|n| n == "in progress")
            .expect("in progress column exists");
        assert_eq!(
            app.board.column_cards(idx).len(),
            1,
            "the chosen status lands the issue in 'in progress'"
        );
    }

    /// Choosing a Priority writes that row, and inline `+` still reaches a
    /// genuinely new custom priority — a preserved model value (tix #1508).
    #[test]
    fn choosing_a_priority_writes_the_row_and_inline_create_still_works() {
        let (_tmp, mut app) = make_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap(); // Title -> Status
        app.handle_key(press(KeyCode::Down)).unwrap(); // Status -> Priority

        // Pick the built-in `high` (the third option).
        app.handle_key(press(KeyCode::Enter)).unwrap();
        for _ in 0..2 {
            app.handle_key(press(KeyCode::Down)).unwrap();
        }
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(app.form.as_ref().unwrap().priority, "high");

        // `+` invents a custom priority the options do not list.
        app.handle_key(press(KeyCode::Char('+'))).unwrap();
        for c in "blocker".chars() {
            app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(app.form.as_ref().unwrap().priority, "blocker");
    }

    /// Status refuses `+` inline create (tix #1508): a column the board does not
    /// configure is not a column the form can add.
    #[test]
    fn the_status_dropdown_refuses_inline_create() {
        let (_tmp, mut app) = make_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap(); // Title -> Status
        app.handle_key(press(KeyCode::Enter)).unwrap();
        app.handle_key(press(KeyCode::Char('+'))).unwrap();
        assert_eq!(
            app.form_picker.as_ref().unwrap().state.mode,
            PickerMode::Idle,
            "Status refuses the inline-create prompt"
        );
        for c in "legacy".chars() {
            app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        assert!(
            app.form_picker
                .as_ref()
                .unwrap()
                .state
                .create_buffer
                .is_empty(),
            "the swallowed create keys never reach a buffer"
        );
    }

    /// The change is scoped to Status and Priority (tix #1508): the other picker
    /// rows still accept typing, and Enter still submits from a text row.
    #[test]
    fn the_other_form_rows_keep_their_behaviour() {
        let (_tmp, mut app) = make_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        type_text(&mut app, "Scoped");
        app.handle_key(press(KeyCode::Down)).unwrap(); // Status
        app.handle_key(press(KeyCode::Down)).unwrap(); // Priority
        app.handle_key(press(KeyCode::Down)).unwrap(); // Labels
        assert_eq!(
            app.form.as_ref().unwrap().focus,
            crate::ui::form::FormFocus::Labels
        );
        type_text(&mut app, "bug");
        assert_eq!(
            app.form.as_ref().unwrap().labels,
            "bug",
            "Labels still accepts typed text"
        );

        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            matches!(app.mode, Mode::Board),
            "Enter still submits from a plain text row"
        );
        let issue = app
            .store
            .list()
            .unwrap()
            .into_iter()
            .find(|i| i.title == "Scoped")
            .expect("the mode created the issue");
        assert_eq!(issue.labels, vec!["bug".to_string()]);
    }

    /// The dropdown is a real surface (tix #1508): its title and footer render,
    /// and the Status footer does not advertise the inline-create key it refuses
    /// while the Priority footer does.
    #[test]
    fn the_status_and_priority_dropdowns_render_their_footers() {
        let (_tmp, mut app) = make_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        app.handle_key(press(KeyCode::Down)).unwrap(); // Title -> Status
        app.handle_key(press(KeyCode::Enter)).unwrap();
        // Wide enough that the picker footer is not clipped mid-word.
        let text = cells_to_text(&draw_board(&app, 120, 30), 120, 30);
        assert!(
            text.contains("Status picker"),
            "the Status dropdown renders:\n{text}"
        );
        let footer = text
            .lines()
            .find(|line| line.contains("close |"))
            .expect("the picker footer renders");
        assert!(
            footer.contains("select"),
            "the footer names select: {footer:?}"
        );
        assert!(
            !footer.contains("create"),
            "Status must not offer the create key it refuses: {footer:?}"
        );
        app.handle_key(press(KeyCode::Esc)).unwrap();

        app.handle_key(press(KeyCode::Down)).unwrap(); // Status -> Priority
        app.handle_key(press(KeyCode::Enter)).unwrap();
        let text = cells_to_text(&draw_board(&app, 120, 30), 120, 30);
        assert!(
            text.contains("Priority picker"),
            "the Priority dropdown renders:\n{text}"
        );
        let footer = text
            .lines()
            .find(|line| line.contains("close |"))
            .expect("the picker footer renders");
        assert!(
            footer.contains("create"),
            "Priority keeps inline create: {footer:?}"
        );
    }

    #[test]
    fn clone_opens_the_new_issue_mode_and_creates_a_distinct_issue() {
        let (tmp, mut app) = make_shell_app();
        let dir = tmp.path().join("issues");
        fs::write(
            dir.join("2026-01-01-source.md"),
            "---\nnumber: 7\ntitle: \"Source issue\"\nstatus: \"todo\"\nlabels: [\"bug\"]\n\
             priority: \"high\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\n\
             Original body.",
        )
        .unwrap();
        app.refresh_corpus().unwrap();
        // The starter board's first column is `triage`; select the seeded card in
        // `todo` so `C` has a source.
        app.select_card_by_filename("2026-01-01-source.md");

        app.handle_key(press(KeyCode::Char('C'))).unwrap();
        assert!(
            matches!(app.mode, Mode::Form),
            "clone lands in the New Issue mode, got {:?}",
            app.mode
        );
        assert_eq!(app.top_mode, TopMode::NewIssue);
        let form = app.form.as_ref().unwrap();
        assert_eq!(form.title, "Source issue");
        assert_eq!(form.labels, "bug");
        assert_eq!(form.priority, "high");
        assert_eq!(form.body, "Original body.", "the body is copied too");

        // Submit unchanged: the copy is a new issue, not an edit of the source.
        app.handle_key(press(KeyCode::Enter)).unwrap();
        let issues = app.store.list().unwrap();
        assert_eq!(issues.len(), 2, "clone creates a second file");
        let created = issues
            .iter()
            .find(|i| i.title == "Source issue" && i.number != 7)
            .expect("a distinct issue was created");
        assert_eq!(created.labels, vec!["bug".to_string()]);
        assert_eq!(created.body, "Original body.");
        let source = issues.iter().find(|i| i.number == 7).unwrap();
        assert_eq!(
            source.body, "Original body.",
            "the source is untouched by the clone"
        );
    }

    #[test]
    fn template_prefills_body_and_labels_before_submission() {
        let (_tmp, mut app) = make_templated_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        type_text(&mut app, "Templated");

        for _ in 0..13 {
            app.handle_key(press(KeyCode::Down)).unwrap();
        }
        assert_eq!(
            app.form.as_ref().unwrap().focus,
            crate::ui::form::FormFocus::Template
        );
        app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            app.form_picker.is_some(),
            "Enter on Template opens the picker"
        );
        // Options are `(none)`, `bug`, `feature`: step onto `bug` and choose it.
        app.handle_key(press(KeyCode::Down)).unwrap();
        app.handle_key(press(KeyCode::Enter)).unwrap();

        let form = app.form.as_ref().unwrap();
        assert_eq!(form.template, "bug");
        assert_eq!(form.labels, "bug", "the template pre-fills labels");
        assert!(
            form.body.contains("Steps to reproduce"),
            "the template pre-fills the body, got {:?}",
            form.body
        );
        assert!(
            app.form_picker.is_none(),
            "choosing closes the template picker"
        );

        app.form.as_mut().unwrap().focus = crate::ui::form::FormFocus::Title;
        app.handle_key(press(KeyCode::Enter)).unwrap();
        let issue = app
            .store
            .list()
            .unwrap()
            .into_iter()
            .find(|i| i.title == "Templated")
            .expect("the mode created the issue");
        assert_eq!(issue.labels, vec!["bug".to_string()]);
        assert!(issue.body.contains("Steps to reproduce"));
    }

    #[test]
    fn new_issue_submits_without_a_template() {
        let (_tmp, mut app) = make_shell_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        assert!(app.store.config.templates.is_empty());
        assert_eq!(
            app.form.as_ref().unwrap().template,
            "",
            "no template is selected by default"
        );

        type_text(&mut app, "No template");
        app.handle_key(press(KeyCode::Enter)).unwrap();
        let issue = app
            .store
            .list()
            .unwrap()
            .into_iter()
            .find(|i| i.title == "No template")
            .expect("submitting without a template works");
        assert!(issue.labels.is_empty());
        assert!(issue.body.is_empty());
    }

    #[test]
    fn template_selector_is_mouse_operable() {
        let (_tmp, mut app) = make_templated_app();
        app.handle_key(press(KeyCode::F(1))).unwrap();
        let _ = draw_board(&app, 80, 24);

        // Click the Template row to open the picker.
        let row = crate::ui::form::field_row_rect(
            app.frame_size.get(),
            crate::ui::form::FormFocus::Template,
        )
        .expect("the Template row is visible");
        let action = app.handle_mouse(down_left(row.x + 3, row.y)).unwrap();
        assert_eq!(action, Action::TemplateOpen);
        app.apply_new_issue_action(action).unwrap();
        assert!(
            app.form_picker
                .as_ref()
                .is_some_and(|p| p.field == FormPickerField::Template),
            "the click opened the template picker"
        );

        // Draw again so the picker's option rows record their regions, then click
        // the `bug` option (position 1, after `(none)`).
        let _ = draw_board(&app, 80, 24);
        let option = {
            let regions = app.frame_hit_regions.borrow();
            regions
                .iter()
                .find(|r| r.action == Action::TemplatePickOption(1))
                .map(|r| r.rect)
                .expect("the bug option recorded a click region")
        };
        let action = app.handle_mouse(down_left(option.x + 1, option.y)).unwrap();
        assert_eq!(action, Action::TemplatePickOption(1));
        app.apply_new_issue_action(action).unwrap();

        let form = app.form.as_ref().unwrap();
        assert_eq!(form.template, "bug");
        assert_eq!(form.labels, "bug");
        assert!(form.body.contains("Steps to reproduce"));
        assert!(app.form_picker.is_none(), "the click closed the picker");
    }

    // --- Config mode (tui-config-mode) ---

    /// A project whose board and cycle **file stores** both exist:
    /// `docs/boards/default.md` and `docs/cycles/sprint-7.md`, with one issue
    /// that references `Sprint 7` and one milestone.
    fn make_app_with_config_stores() -> (TempDir, App) {
        let tmp = TempDir::new().unwrap();
        let root = tmp.path();
        let dir = root.join("issues");
        fs::create_dir_all(&dir).unwrap();

        // A stored cycle the issue references.
        crate::cycle_store::CycleStore::new(root)
            .save(
                "Sprint 7",
                &crate::config::PlanningCycle {
                    description: Some("kickoff".into()),
                    start_date: Some("2026-10-01".into()),
                    due_date: Some("2999-12-31".into()),
                },
                None,
            )
            .unwrap();

        let issue = "---\nnumber: 1\ntitle: \"A\"\nstatus: \"todo\"\nlabels: []\npriority: \"medium\"\ncycles: [\"Sprint 7\"]\nmilestones: [\"GA\"]\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody text.";
        fs::create_dir_all(dir.join("alice")).unwrap();
        fs::write(dir.join("alice/2026-01-01-a.md"), issue).unwrap();

        let milestones_dir = root.join("docs/milestones");
        fs::create_dir_all(&milestones_dir).unwrap();
        fs::write(
            milestones_dir.join("2026-01-01-ga.md"),
            "---\nname: \"GA\"\ntarget_date: \"2026-12-31\"\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nship it\n",
        )
        .unwrap();

        // The board store is authoritative once `docs/boards/` exists, so the
        // board is written there and `tix.toml` carries no `[kanban.*]` copy.
        fs::create_dir_all(root.join("docs/boards")).unwrap();
        let mut config = Config {
            issues_dir: dir.clone(),
            ..test_config()
        };
        config
            .kanban
            .configurations
            .insert("default".into(), crate::config::starter_board());
        let config_path = root.join("tix.toml");
        config.save(&config_path).unwrap();

        let config = Config::load_with_warning(&config_path, |_| {}).unwrap();
        let app = App::new(&config).unwrap();
        (tmp, app)
    }

    fn open_config(app: &mut App) {
        let _ = app.handle_key(press(KeyCode::F(12))).unwrap();
        assert!(
            matches!(app.mode, Mode::Settings),
            "F12 opens the Config mode"
        );
    }

    #[test]
    fn config_mode_shows_the_three_sections() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let cells = draw_board(&app, 100, 30);
        let text = cells_to_text(&cells, 100, 30);
        for label in ["Sections", "Dashboards", "Cycles", "Milestones"] {
            assert!(text.contains(label), "Config mode shows `{label}`:\n{text}");
        }
        assert!(
            text.contains("Wrap titles:"),
            "the dashboards section is the active one:\n{text}"
        );
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Dashboards
        );
    }

    #[test]
    fn config_board_edit_persists_to_the_board_file() {
        let (tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let col = app.active_board_config().columns[0].clone();
        assert!(
            !app.active_board_config().hidden_columns.contains(&col),
            "the column starts visible"
        );
        // Row 0 is the first column checkbox; Space toggles it, exactly as the
        // old settings modal did.
        app.settings.as_mut().unwrap().selected = 0;
        let _ = app.handle_key(press(KeyCode::Char(' '))).unwrap();

        let raw = fs::read_to_string(tmp.path().join("docs/boards/default.md")).unwrap();
        assert!(
            raw.contains("hidden_columns:") && raw.contains(&col),
            "the board file records the hidden column:\n{raw}"
        );
        let toml = fs::read_to_string(tmp.path().join("tix.toml")).unwrap();
        assert!(
            !toml.contains("[kanban"),
            "a board edit must not write a second copy into tix.toml:\n{toml}"
        );
    }

    #[test]
    fn config_cycle_edit_persists_to_the_cycle_file() {
        let (tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        // `j` on the focused rail moves down to the Cycles section …
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Cycles
        );
        // … then `l` moves the focus into the body, where `j` moves the row.
        let _ = app.handle_key(press(KeyCode::Right)).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Body);
        // The rows are `Default` then `Sprint 7`; move to `Sprint 7` and edit it.
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('e'))).unwrap();
        assert!(matches!(app.mode, Mode::PlanningForm));
        // Focus the description field and rewrite it.
        let _ = app.handle_key(press(KeyCode::Tab)).unwrap();
        for _ in 0.."kickoff".len() {
            let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        }
        for c in "renamed".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(
            matches!(app.mode, Mode::Settings),
            "a form opened from Config returns to Config"
        );
        assert_eq!(app.top_mode, TopMode::Config);
        let raw = fs::read_to_string(tmp.path().join("docs/cycles/sprint-7.md")).unwrap();
        assert!(
            raw.contains("renamed"),
            "the cycle file carries the edit:\n{raw}"
        );
    }

    #[test]
    fn config_non_record_setting_persists_to_tix_toml() {
        let (tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        // The editor row is the general row after the display rows.
        let editor_row =
            app.active_board_config().columns.len() + crate::ui::settings::DISPLAY_ROWS;
        app.settings.as_mut().unwrap().selected = editor_row;
        // The rail starts focused, so `l` steps into the body before `Enter`
        // activates the row.
        let _ = app.handle_key(press(KeyCode::Right)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            matches!(
                app.settings.as_ref().unwrap().prompt,
                Some(SettingsPrompt::SetEditor(_))
            ),
            "Enter on the editor row opens the prompt"
        );
        for c in "nvim".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert_eq!(app.store.config.editor.as_deref(), Some("nvim"));
        let toml = fs::read_to_string(tmp.path().join("tix.toml")).unwrap();
        assert!(
            toml.contains(r#"editor = "nvim""#),
            "a non-record setting persists to tix.toml:\n{toml}"
        );
        // Still no board copy in tix.toml: the two stores stay separate.
        assert!(!toml.contains("[kanban"), "{toml}");
    }

    #[test]
    fn config_viewer_row_persists_and_clears_back_to_auto() {
        let (tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        // The viewer row is the second general row: after the display rows and
        // the editor row.
        let viewer_row =
            app.active_board_config().columns.len() + crate::ui::settings::DISPLAY_ROWS + 1;
        app.settings.as_mut().unwrap().selected = viewer_row;
        // The rail starts focused, so `l` steps into the body before `Enter`
        // activates the row.
        let _ = app.handle_key(press(KeyCode::Right)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            matches!(
                app.settings.as_ref().unwrap().prompt,
                Some(SettingsPrompt::SetViewer(_))
            ),
            "Enter on the viewer row opens the prompt"
        );
        for c in "mdterm".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert_eq!(app.store.config.viewer.as_deref(), Some("mdterm"));
        let toml = fs::read_to_string(tmp.path().join("tix.toml")).unwrap();
        assert!(
            toml.contains(r#"viewer = "mdterm""#),
            "the viewer persists to tix.toml:\n{toml}"
        );

        // Reopen the row (still selected, body still focused) and clear the
        // seeded value: a blank submission returns the key to the auto chain.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        for _ in 0.."mdterm".len() {
            let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(app.store.config.viewer, None);
        let toml = fs::read_to_string(tmp.path().join("tix.toml")).unwrap();
        assert!(
            !toml.contains("viewer"),
            "a blank value clears back to auto:\n{toml}"
        );
    }

    #[test]
    fn config_rename_cycle_cascades_to_referencing_issues() {
        let (tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Right)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('e'))).unwrap();
        // Rewrite the name field ("Sprint 7").
        for _ in 0.."Sprint 7".len() {
            let _ = app.handle_key(press(KeyCode::Backspace)).unwrap();
        }
        for c in "Sprint 8".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        let root = tmp.path();
        assert!(
            !root.join("docs/cycles/sprint-7.md").exists(),
            "the old cycle file is gone"
        );
        assert!(root.join("docs/cycles/sprint-8.md").exists());
        let issue = fs::read_to_string(root.join("issues/alice/2026-01-01-a.md")).unwrap();
        assert!(
            issue.contains("Sprint 8") && !issue.contains("Sprint 7"),
            "the referencing issue was rewritten:\n{issue}"
        );
    }

    #[test]
    fn config_delete_reports_the_reference_count() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Right)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();

        assert_eq!(
            app.planning.as_ref().unwrap().prompt,
            Some(PlanningPrompt::ConfirmDelete {
                name: "Sprint 7".into(),
                referencing: 1,
            }),
            "the confirmation names the one referencing issue"
        );
        // Confirming deletes the cycle; the issue keeps its orphaned reference.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(app.planning.as_ref().unwrap().prompt.is_none());
        assert!(
            !app.store.config.cycles.contains_key("Sprint 7"),
            "the cycle is gone"
        );
    }

    #[test]
    fn config_delete_board_reports_zero_references() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        // Add a second board so the last-board guard allows a delete.
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "ops".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().prompt,
            Some(SettingsPrompt::ConfirmDeleteBoard {
                name: "ops".into(),
                referencing: 0,
            }),
            "nothing in issue frontmatter names a board"
        );
    }

    #[test]
    fn config_add_second_board_creates_the_store_directory() {
        let (tmp, mut app) = make_app();
        let root = tmp.path();
        assert!(
            !root.join("docs/boards").exists(),
            "the fixture starts without a board store"
        );
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "ops".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(
            root.join("docs/boards/ops.md").exists(),
            "adding a board past the seeded default creates docs/boards/"
        );
        assert!(root.join("docs/boards/default.md").exists());
        // The whole set migrated: the next load reads both boards from files.
        let reloaded = Config::load_with_warning(&root.join("tix.toml"), |_| {}).unwrap();
        let names: Vec<&str> = reloaded.configs().map(|(name, _)| name).collect();
        assert!(
            names.contains(&"ops") && names.contains(&"default"),
            "{names:?}"
        );
    }

    #[test]
    fn config_add_second_cycle_creates_the_store_directory() {
        let (tmp, mut app) = make_app();
        let root = tmp.path();
        assert!(!root.join("docs/cycles").exists());
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('n'))).unwrap();
        for c in "Sprint 9".chars() {
            let _ = app.handle_key(press(KeyCode::Char(c))).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();

        assert!(
            root.join("docs/cycles/sprint-9.md").exists(),
            "adding a cycle past the implicit Default creates docs/cycles/"
        );
    }

    #[test]
    fn config_milestone_section_reuses_the_planning_surface() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Milestones
        );
        assert_eq!(
            app.planning.as_ref().unwrap().segment,
            PlanningSegment::Milestones
        );
        // `x` reports the reference count through the same planner impact the
        // planning surface uses.
        let _ = app.handle_key(press(KeyCode::Char('x'))).unwrap();
        assert_eq!(
            app.planning.as_ref().unwrap().prompt,
            Some(PlanningPrompt::ConfirmDelete {
                name: "GA".into(),
                referencing: 1,
            })
        );
    }

    // --- Config mode's two-pane focus model (h/l between panes, j/k within) ---

    #[test]
    fn config_starts_with_the_section_rail_focused() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Sections);
    }

    #[test]
    fn config_h_and_l_move_the_pane_focus_and_clamp() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        // `l` steps right into the body; another `l` clamps there.
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Body);
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().pane,
            ConfigPane::Body,
            "the right end clamps"
        );
        // The arrows are the same event: `←` steps back and clamps on the rail.
        let _ = app.handle_key(press(KeyCode::Left)).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Sections);
        let _ = app.handle_key(press(KeyCode::Left)).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().pane,
            ConfigPane::Sections,
            "the left end clamps"
        );
        // And `h` mirrors `l`.
        let _ = app.handle_key(press(KeyCode::Right)).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Sections);
    }

    #[test]
    fn config_j_k_change_the_section_while_the_rail_is_focused() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Cycles
        );
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Sections);
        let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Milestones
        );
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Cycles
        );
        let _ = app.handle_key(press(KeyCode::Char('k'))).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Dashboards
        );
    }

    #[test]
    fn config_changing_section_from_the_rail_resets_the_row_cursor() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        app.settings.as_mut().unwrap().selected = 2;
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Cycles
        );
        assert_eq!(
            app.settings.as_ref().unwrap().selected,
            0,
            "the per-section cursor resets on a change"
        );
    }

    #[test]
    fn config_j_k_move_the_body_row_only_when_the_body_is_focused() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let row_count = board_rows_len(app.active_board_config());
        // With the rail focused, `j` moves the section and never the row.
        app.settings.as_mut().unwrap().selected = 1;
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Body);
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().selected, 2);
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Dashboards,
            "a body row move never switches section"
        );
        let _ = app.handle_key(press(KeyCode::Char('k'))).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().selected, 1);
        // Clamped at the top …
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().selected, 0);
        // … and at the bottom.
        for _ in 0..row_count + 3 {
            let _ = app.handle_key(press(KeyCode::Down)).unwrap();
        }
        assert_eq!(app.settings.as_ref().unwrap().selected, row_count - 1);
    }

    #[test]
    fn config_j_k_move_the_planning_body_row_when_the_body_is_focused() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(app.planning.as_ref().unwrap().selected, 1);
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Cycles,
            "moving a row does not switch section"
        );
        let _ = app.handle_key(press(KeyCode::Char('k'))).unwrap();
        assert_eq!(app.planning.as_ref().unwrap().selected, 0);
    }

    #[test]
    fn config_enter_from_the_rail_focuses_the_body() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Body);
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Dashboards,
            "stepping into the body does not switch section"
        );
    }

    #[test]
    fn config_enter_in_the_body_activates_the_row() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let board_name = app.active_board_name().to_string();
        let col = app.active_board_config().columns[0].clone();
        assert!(!app.active_board_config().hidden_columns.contains(&col));
        // Rail → body, then Enter toggles the selected column.
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            app.store
                .config
                .kanban
                .configurations
                .get(&board_name)
                .unwrap()
                .hidden_columns
                .contains(&col),
            "Enter in the body runs the row's activate action"
        );
    }

    #[test]
    fn config_enter_in_the_planning_body_edits_the_selected_item() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            matches!(app.mode, Mode::PlanningForm),
            "Enter edits the selected cycle from the body"
        );
    }

    #[test]
    fn config_body_row_click_focuses_the_body() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let board_name = app.active_board_name().to_string();
        let col = app.active_board_config().columns[1].clone();
        let _ = draw_board(&app, 100, 30);
        assert_eq!(
            app.settings.as_ref().unwrap().pane,
            ConfigPane::Sections,
            "the rail starts focused"
        );

        let row = {
            let regions = app.frame_hit_regions.borrow();
            regions
                .iter()
                .find(|r| r.action == Action::SettingsRow(1))
                .map(|r| r.rect)
                .expect("the second dashboards row recorded a click region")
        };
        let action = app.handle_mouse(down_left(row.x + 1, row.y)).unwrap();
        assert_eq!(action, Action::SettingsRow(1));

        // The click's own action: focus the body, move the cursor, toggle.
        app.apply_config_click(Action::SettingsRow(1));
        let _ = app.settings_toggle_selected();
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Body);
        assert_eq!(app.settings.as_ref().unwrap().selected, 1);
        assert!(
            app.store
                .config
                .kanban
                .configurations
                .get(&board_name)
                .unwrap()
                .hidden_columns
                .contains(&col),
            "the click activates the row it landed on, as it did before the panes"
        );
    }

    #[test]
    fn config_section_entries_are_hoverable() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = draw_board(&app, 100, 30);

        let rail = {
            let regions = app.frame_hit_regions.borrow();
            regions
                .iter()
                .find(|r| r.action == Action::ConfigSection(ConfigSection::Milestones))
                .map(|r| r.rect)
                .expect("the Milestones rail entry recorded a click region")
        };
        let action = app.handle_mouse(moved_to(rail.x + 1, rail.y)).unwrap();
        assert_eq!(action, Action::None, "hover never acts");
        assert!(app.is_hovered(&Action::ConfigSection(ConfigSection::Milestones)));
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Dashboards,
            "hover never changes the section"
        );

        // Leaving the rail clears it.
        app.handle_mouse(moved_to(rail.x + rail.width + 20, rail.y))
            .unwrap();
        assert!(!app.is_hovered(&Action::ConfigSection(ConfigSection::Milestones)));
    }

    #[test]
    fn config_sections_are_mouse_navigable() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);
        let _ = draw_board(&app, 100, 30);

        // Start with the body focused so the rail click has a focus to move.
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(app.settings.as_ref().unwrap().pane, ConfigPane::Body);

        let rail = {
            let regions = app.frame_hit_regions.borrow();
            regions
                .iter()
                .find(|r| r.action == Action::ConfigSection(ConfigSection::Cycles))
                .map(|r| r.rect)
                .expect("the Cycles rail entry recorded a click region")
        };
        let action = app.handle_mouse(down_left(rail.x + 1, rail.y)).unwrap();
        assert_eq!(action, Action::ConfigSection(ConfigSection::Cycles));
        app.apply_config_click(action);
        assert_eq!(
            app.settings.as_ref().unwrap().section,
            ConfigSection::Cycles
        );
        assert_eq!(
            app.settings.as_ref().unwrap().pane,
            ConfigPane::Sections,
            "a rail click focuses the rail"
        );

        // Re-draw so the cycle rows record their regions, then click row 1.
        let _ = draw_board(&app, 100, 30);
        let row = {
            let regions = app.frame_hit_regions.borrow();
            regions
                .iter()
                .find(|r| r.action == Action::ConfigPlanningRow(1))
                .map(|r| r.rect)
                .expect("the cycle row recorded a click region")
        };
        let action = app.handle_mouse(down_left(row.x + 1, row.y)).unwrap();
        assert_eq!(action, Action::ConfigPlanningRow(1));
        app.apply_config_click(action);
        assert_eq!(app.planning.as_ref().unwrap().selected, 1);
        assert_eq!(
            app.settings.as_ref().unwrap().pane,
            ConfigPane::Body,
            "a body-row click focuses the body"
        );

        // And a dashboards row click still runs the same toggle the key does.
        app.config_set_section(ConfigSection::Dashboards);
        let _ = draw_board(&app, 100, 30);
        let board_row = {
            let regions = app.frame_hit_regions.borrow();
            regions
                .iter()
                .find(|r| r.action == Action::SettingsRow(0))
                .map(|r| r.rect)
                .expect("the first dashboards row recorded a click region")
        };
        let action = app
            .handle_mouse(down_left(board_row.x + 1, board_row.y))
            .unwrap();
        assert_eq!(action, Action::SettingsRow(0));
    }

    #[test]
    fn config_focused_pane_is_rendered_distinctly() {
        let (_tmp, mut app) = make_app_with_config_stores();
        open_config(&mut app);

        // The accent of each pane's border corner: the rail's top-left and the
        // body's top-left, both read from the frame the app just drew.
        let borders = |app: &App| {
            let backend = ratatui::backend::TestBackend::new(100, 30);
            let mut terminal = ratatui::Terminal::new(backend).unwrap();
            terminal
                .draw(|f| crate::app::render(app, f, f.area()))
                .unwrap();
            let content = app.frame_size.get();
            let body = crate::ui::settings::config_body_rect(content);
            let buffer = terminal.backend().buffer();
            (
                buffer[(content.x, content.y)].fg,
                buffer[(body.x, body.y)].fg,
            )
        };

        let (rail, body) = borders(&app);
        assert_eq!(rail, Color::Yellow, "the focused rail is accented");
        assert_eq!(body, Color::DarkGray, "the unfocused body is dimmed");

        // Moving the focus into the body swaps the two accents.
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        let (rail, body) = borders(&app);
        assert_eq!(rail, Color::DarkGray, "the unfocused rail is dimmed");
        assert_eq!(body, Color::Yellow, "the focused body is accented");
    }

    /// Draw `app` into a `TestBackend` and hand back the buffer, so a test can
    /// read cell styles (the `draw_board`/`flush_line` helpers keep text only).
    fn draw_buffer(app: &App, w: u16, h: u16) -> ratatui::buffer::Buffer {
        let backend = ratatui::backend::TestBackend::new(w, h);
        let mut terminal = ratatui::Terminal::new(backend).unwrap();
        terminal
            .draw(|f| crate::app::render(app, f, f.area()))
            .unwrap();
        terminal.backend().buffer().clone()
    }

    /// Write an issue carrying the given cycle and milestone memberships, so the
    /// flat issue tables have something to list.
    fn write_planning_issue(
        dir: &std::path::Path,
        name: &str,
        number: u32,
        title: &str,
        status: &str,
        cycles: &[&str],
        milestones: &[&str],
    ) {
        let list = |values: &[&str]| {
            values
                .iter()
                .map(|v| format!("\"{v}\""))
                .collect::<Vec<_>>()
                .join(", ")
        };
        let cycles_line = if cycles.is_empty() {
            String::new()
        } else {
            format!("cycles: [{}]\n", list(cycles))
        };
        let milestones_line = if milestones.is_empty() {
            String::new()
        } else {
            format!("milestones: [{}]\n", list(milestones))
        };
        fs::write(
            dir.join(name),
            format!(
                "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"{status}\"\nlabels: []\n\
                 priority: \"medium\"\n{cycles_line}{milestones_line}\
                 created: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody."
            ),
        )
        .unwrap();
    }

    /// The filenames of every recorded `OpenIssue` region, sorted.
    fn open_issue_regions(app: &App) -> Vec<String> {
        let mut names: Vec<String> = app
            .frame_hit_regions
            .borrow()
            .iter()
            .filter_map(|region| match &region.action {
                Action::OpenIssue(filename) => Some(filename.clone()),
                _ => None,
            })
            .collect();
        names.sort();
        names
    }

    /// The cycle the rail marks active is exactly the focused cycle, and only
    /// while the Cycle mode is the top mode; the row is drawn bold.
    #[test]
    fn active_cycle_limb_is_marked_and_drawn_bold() {
        // Off the Cycle mode nothing is active, even with a cursor present.
        let (_tmp, app) = make_cycle_app();
        assert_eq!(app.active_cycle_name(), None);
        let cycle_node = |app: &App| {
            app.nav_tree()
                .into_iter()
                .find(|node| node.mode == TopMode::Cycle)
                .expect("the Cycles trunk exists")
        };
        assert!(
            cycle_node(&app)
                .branches
                .iter()
                .all(|branch| !branch.active)
        );

        let (_tmp, mut app) = make_cycle_app();
        app.activate_branch(&Action::SelectCycle("Ongoing".into()))
            .unwrap();
        assert_eq!(app.active_cycle_name().as_deref(), Some("Ongoing"));
        let marked: Vec<String> = cycle_node(&app)
            .branches
            .iter()
            .filter(|branch| branch.active)
            .map(|branch| branch.label.clone())
            .collect();
        assert_eq!(marked, vec!["Ongoing".to_string()]);

        let cells = draw_board(&app, 80, 24);
        let row_of = |prefix: &str| {
            (0..24u16)
                .find(|row| flush_line(&cells, 80, *row).starts_with(prefix))
                .unwrap_or_else(|| panic!("no rail row starts with {prefix:?}"))
        };
        let ongoing = row_of("  Ongoing");
        let later = row_of("  Later");
        let buffer = draw_buffer(&app, 80, 24);
        assert!(
            buffer[(2, ongoing)]
                .style()
                .add_modifier
                .contains(Modifier::BOLD),
            "the focused cycle limb is bold"
        );
        assert!(
            !buffer[(2, later)]
                .style()
                .add_modifier
                .contains(Modifier::BOLD),
            "a non-focused cycle limb is not bold"
        );
    }

    /// The milestone the rail marks active is the focused one, only in the
    /// Milestones mode, and the row is drawn bold.
    #[test]
    fn active_milestone_limb_is_marked_and_drawn_bold() {
        let (_tmp, mut app) = make_app();
        let planner =
            crate::planning::Planner::from_config(app.store.config.clone(), app.project_root());
        planner
            .create_milestone_file("Backlog", None, None)
            .unwrap();
        planner.create_milestone_file("Q4", None, None).unwrap();

        // Config's milestones section shares the cursor but is not the F5 mode.
        app.open_settings(None);
        app.config_set_section(ConfigSection::Milestones);
        assert_eq!(app.active_milestone_name(), None);

        app.switch_top_mode(TopMode::Milestones).unwrap();
        assert_eq!(app.active_milestone_name().as_deref(), Some("Backlog"));
        let milestone_node = |app: &App| {
            app.nav_tree()
                .into_iter()
                .find(|node| node.mode == TopMode::Milestones)
                .expect("the Milestones trunk exists")
        };
        let marked: Vec<String> = milestone_node(&app)
            .branches
            .iter()
            .filter(|branch| branch.active)
            .map(|branch| branch.label.clone())
            .collect();
        assert_eq!(marked, vec!["Backlog".to_string()]);

        let cells = draw_board(&app, 80, 24);
        let row_of = |prefix: &str| {
            (0..24u16)
                .find(|row| flush_line(&cells, 80, *row).starts_with(prefix))
                .unwrap_or_else(|| panic!("no rail row starts with {prefix:?}"))
        };
        let backlog = row_of("  Backlog");
        let q4 = row_of("  Q4");
        let buffer = draw_buffer(&app, 80, 24);
        assert!(
            buffer[(2, backlog)]
                .style()
                .add_modifier
                .contains(Modifier::BOLD),
            "the focused milestone limb is bold"
        );
        assert!(
            !buffer[(2, q4)]
                .style()
                .add_modifier
                .contains(Modifier::BOLD),
            "a non-focused milestone limb is not bold"
        );

        // Moving the cursor moves the bold row with it.
        app.handle_key(press(KeyCode::Down)).unwrap();
        assert_eq!(app.active_milestone_name().as_deref(), Some("Q4"));
    }

    /// The Cycle mode's flat table lists exactly the focused cycle's issues
    /// (and no others), each row a click target that opens the issue.
    #[test]
    fn cycle_mode_lists_the_focused_cycles_issues_and_opens_them() {
        let (_tmp, mut app) = make_cycle_app();
        app.activate_branch(&Action::SelectCycle("Historical".into()))
            .unwrap();
        let _ = draw_board(&app, 100, 30);
        assert_eq!(open_issue_regions(&app), vec!["alice/2026-01-03-old.md"]);

        // A cycle with no issues says so rather than drawing an empty box: the
        // fixture's `Later` cycle has none.
        let (_tmp, mut app) = make_cycle_app();
        app.activate_branch(&Action::SelectCycle("Later".into()))
            .unwrap();
        let cells = draw_board(&app, 100, 30);
        assert!(open_issue_regions(&app).is_empty());
        assert!(
            cells.concat().contains("No issues."),
            "an empty cycle says so"
        );

        let (_tmp, mut app) = make_cycle_app();
        app.activate_branch(&Action::SelectCycle("Ongoing".into()))
            .unwrap();
        let cells = draw_board(&app, 100, 30);
        assert_eq!(
            open_issue_regions(&app),
            vec![
                "alice/2026-01-01-done.md".to_string(),
                "alice/2026-01-02-open.md".to_string(),
            ],
            "exactly the Ongoing issues, and not Historical's"
        );
        let text = cells.concat();
        assert!(
            text.contains("issues — Ongoing"),
            "the table is titled: {text:?}"
        );
        assert!(text.contains("Issue 1") && text.contains("Issue 2"));
        assert!(
            !text.contains("Issue 3"),
            "another cycle's issue is not listed"
        );

        // A row is a click region resolving to its `OpenIssue`, hovers, and opens.
        let (region, filename) = {
            let regions = app.frame_hit_regions.borrow();
            let region = regions
                .iter()
                .find(|region| {
                    region.action == Action::OpenIssue("alice/2026-01-02-open.md".into())
                })
                .expect("the open issue recorded a click region");
            (region.rect, "alice/2026-01-02-open.md".to_string())
        };
        let _ = app.handle_mouse(moved_to(region.x + 1, region.y)).unwrap();
        assert!(
            app.is_hovered(&Action::OpenIssue(filename.clone())),
            "the hovered table row reads as hovered"
        );

        let action = app.handle_mouse(down_left(region.x + 1, region.y)).unwrap();
        assert_eq!(action, Action::OpenIssue(filename.clone()));
        app.open_issue_by_filename(&filename).unwrap();
        assert!(matches!(app.mode, Mode::Detail), "the row opens the issue");
        assert_eq!(app.detail.as_ref().unwrap().issue.number, 2);
    }

    /// The Milestones mode reuses the same table for the focused milestone.
    #[test]
    fn milestones_mode_lists_the_focused_milestones_issues_and_opens_them() {
        let (tmp, mut app) = make_app();
        let planner =
            crate::planning::Planner::from_config(app.store.config.clone(), app.project_root());
        planner
            .create_milestone_file("Backlog", None, None)
            .unwrap();
        planner.create_milestone_file("Q4", None, None).unwrap();
        let dir = tmp.path().join("issues");
        write_planning_issue(
            &dir,
            "2026-01-01-backlog.md",
            1,
            "Backlog work",
            "todo",
            &[],
            &["Backlog"],
        );
        write_planning_issue(&dir, "2026-01-02-q4.md", 2, "Q4 work", "todo", &[], &["Q4"]);
        app.handle_key(press(KeyCode::F(5))).unwrap();

        let cells = draw_board(&app, 100, 30);
        assert_eq!(open_issue_regions(&app), vec!["2026-01-01-backlog.md"]);
        let text = cells.concat();
        assert!(
            text.contains("issues — Backlog"),
            "the table is titled: {text:?}"
        );
        assert!(text.contains("Backlog work") && !text.contains("Q4 work"));

        // Moving to the next milestone re-points the table.
        app.handle_key(press(KeyCode::Down)).unwrap();
        let _ = draw_board(&app, 100, 30);
        assert_eq!(open_issue_regions(&app), vec!["2026-01-02-q4.md"]);

        let (region, filename) = {
            let regions = app.frame_hit_regions.borrow();
            let region = regions
                .iter()
                .find(|region| region.action == Action::OpenIssue("2026-01-02-q4.md".into()))
                .expect("the Q4 issue recorded a click region");
            (region.rect, "2026-01-02-q4.md".to_string())
        };
        let _ = app.handle_mouse(moved_to(region.x + 1, region.y)).unwrap();
        assert!(app.is_hovered(&Action::OpenIssue(filename.clone())));

        let action = app.handle_mouse(down_left(region.x + 1, region.y)).unwrap();
        assert_eq!(action, Action::OpenIssue(filename.clone()));
        app.open_issue_by_filename(&filename).unwrap();
        assert!(matches!(app.mode, Mode::Detail));
        assert_eq!(app.detail.as_ref().unwrap().issue.number, 2);
    }

    /// The rail is reachable and operable by keyboard: `h`/`Left` focus it when
    /// the mode has no leftward target, `j`/`k` walk trunk and limb rows, and
    /// `Enter` activates the focused row.
    #[test]
    fn rail_focus_walks_rows_and_activates_trunks_and_limbs() {
        let (_tmp, mut app) = make_branchy_app();
        let rows = app.nav_rows();
        let board_trunk = rows
            .iter()
            .position(|action| *action == Action::SwitchMode(TopMode::Board))
            .expect("the Board trunk is a rail row");

        // The board starts at its left edge, so `h` has no leftward target and
        // enters the rail on the Board trunk.
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        assert_eq!(app.nav_focus_index(), Some(board_trunk));

        // `j`/`k` walk trunk and limb rows.
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(app.nav_focus_index(), Some(board_trunk + 1));
        assert_eq!(
            app.nav_rows()[board_trunk + 1],
            Action::SelectBoard("default".into())
        );
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        assert_eq!(app.nav_focus_index(), Some(board_trunk));

        // Enter on a limb runs the limb's action (switch to `release`) and hands
        // the keyboard to the opened content.
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(
            app.nav_rows()[board_trunk + 2],
            Action::SelectBoard("release".into())
        );
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert_eq!(app.active_board_name(), "release");
        assert_eq!(app.top_mode, TopMode::Board);
        assert_eq!(
            app.nav_focus_index(),
            None,
            "Enter opens the row and moves the keyboard right"
        );
    }

    /// `l` and `→` open the focused row exactly like `Enter`/a click and move the
    /// keyboard into the opened content; `Esc` leaves the rail without opening.
    #[test]
    fn rail_right_and_l_activate_the_focused_row() {
        // `l` on the `release` limb switches to that board and returns.
        let (_tmp, mut app) = make_branchy_app();
        let board_trunk = app
            .nav_rows()
            .iter()
            .position(|action| *action == Action::SwitchMode(TopMode::Board))
            .expect("the Board trunk is a rail row");
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(
            app.nav_rows()[board_trunk + 2],
            Action::SelectBoard("release".into())
        );
        let _ = app.handle_key(press(KeyCode::Char('l'))).unwrap();
        assert_eq!(app.active_board_name(), "release");
        assert_eq!(
            app.nav_focus_index(),
            None,
            "`l` opens the row and hands the keyboard to the content"
        );

        // `→` runs the same transition (here the already-active `default` board).
        let (_tmp, mut app) = make_branchy_app();
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Right)).unwrap();
        assert_eq!(app.active_board_name(), "default");
        assert_eq!(app.nav_focus_index(), None, "`→` opens the row too");

        // `Esc` leaves the rail without activating anything.
        let (_tmp, mut app) = make_branchy_app();
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        let _ = app.handle_key(press(KeyCode::Esc)).unwrap();
        assert_eq!(app.nav_focus_index(), None);
    }

    /// Enter on a trunk switches modes, and Enter on a template limb opens the
    /// seeded New Issue form.
    #[test]
    fn rail_enter_switches_modes_and_opens_a_template() {
        let (_tmp, mut app) = make_branchy_app();
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        // Board trunk (index 4) up to the New Issue trunk (index 0): Triage
        // trunk, the `feature` limb, the `bug` limb, then the trunk.
        for _ in 0..4 {
            let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        }
        assert_eq!(app.nav_focus_index(), Some(0));
        assert_eq!(
            app.nav_rows()[0],
            Action::SwitchMode(TopMode::NewIssue),
            "the New Issue trunk is the first rail row"
        );
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(
            matches!(app.mode, Mode::Form),
            "a trunk Enter switches modes"
        );
        assert_eq!(app.top_mode, TopMode::NewIssue);
        assert_eq!(
            app.nav_focus_index(),
            None,
            "Enter hands the keyboard to the opened form"
        );

        let (_tmp, mut app) = make_branchy_app();
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        for _ in 0..4 {
            let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        }
        let _ = app.handle_key(press(KeyCode::Char('j'))).unwrap();
        assert_eq!(
            app.nav_rows()[app.nav_focus_index().unwrap()],
            Action::NewFromTemplate("bug".into())
        );
        let _ = app.handle_key(press(KeyCode::Enter)).unwrap();
        assert!(matches!(app.mode, Mode::Form));
        assert_eq!(app.top_mode, TopMode::NewIssue);
        assert_eq!(app.form.as_ref().map(|f| f.template.as_str()), Some("bug"));
        assert_eq!(app.nav_focus_index(), None);
    }

    /// Every rail row — trunk and limb — highlights under the pointer.
    #[test]
    fn hovering_a_trunk_and_a_limb_row_highlights_each() {
        let (_tmp, mut app) = make_branchy_app();
        app.nav_display = NavDisplay::Default;
        let _ = draw_board(&app, 80, 24);

        // Row 0 is the New Issue trunk.
        let _ = app.handle_mouse(moved_to(0, 0)).unwrap();
        assert!(app.is_hovered(&Action::SwitchMode(TopMode::NewIssue)));
        let buffer = draw_buffer(&app, 80, 24);
        assert_eq!(
            buffer[(0, 0)].style().bg,
            Some(Color::DarkGray),
            "the hovered trunk is highlighted"
        );

        // Row 1 is the `bug` template limb.
        let _ = app.handle_mouse(moved_to(2, 1)).unwrap();
        assert!(app.is_hovered(&Action::NewFromTemplate("bug".into())));
        let buffer = draw_buffer(&app, 80, 24);
        assert_eq!(
            buffer[(2, 1)].style().bg,
            Some(Color::DarkGray),
            "the hovered limb is highlighted"
        );
    }

    /// The keyboard-focused rail row is highlighted exactly like a hovered one.
    #[test]
    fn the_keyboard_focused_rail_row_is_highlighted_like_hover() {
        let (_tmp, mut app) = make_branchy_app();
        app.nav_display = NavDisplay::Default;
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        // Board trunk -> Triage trunk, which is not the active mode, so the
        // background is the focus highlight rather than the active-mode cyan.
        let _ = app.handle_key(press(KeyCode::Up)).unwrap();
        assert_eq!(
            app.nav_focus_index().map(|i| app.nav_rows()[i].clone()),
            Some(Action::SwitchMode(TopMode::Triage))
        );
        let buffer = draw_buffer(&app, 80, 24);
        assert_eq!(buffer[(0, 3)].style().bg, Some(Color::DarkGray));
    }

    /// Entering the rail with `h`/`Left` lands the cursor on the active mode's
    /// trunk; the cursor highlight must outrank the active-mode colour so the
    /// position is always visible.
    #[test]
    fn the_rail_cursor_is_visible_on_the_active_trunk() {
        let (_tmp, mut app) = make_branchy_app();
        app.nav_display = NavDisplay::Default;
        let board_trunk = app
            .nav_rows()
            .iter()
            .position(|action| *action == Action::SwitchMode(TopMode::Board))
            .expect("the Board trunk is a rail row");
        // Board is the active mode and starts at its left edge, so `h` enters the
        // rail on the Board trunk — the row that would otherwise draw active-cyan.
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        assert_eq!(app.nav_focus_index(), Some(board_trunk));
        let buffer = draw_buffer(&app, 80, 24);
        assert_eq!(
            buffer[(0, board_trunk as u16)].style().bg,
            Some(Color::DarkGray),
            "the cursor on the active trunk is highlighted, not left as active-cyan"
        );
    }

    /// A focused rail draws a right-edge focus accent; the unfocused rail does not.
    #[test]
    fn the_focused_rail_draws_a_focus_accent() {
        let (_tmp, mut app) = make_branchy_app();
        app.nav_display = NavDisplay::Default;
        let edge = app.nav_width() - 1;
        let unfocused = draw_buffer(&app, 80, 24);
        assert_ne!(
            unfocused[(edge, 0)].style().fg,
            Some(Color::Yellow),
            "the unfocused rail draws no focus accent"
        );
        let _ = app.handle_key(press(KeyCode::Char('h'))).unwrap();
        let focused = draw_buffer(&app, 80, 24);
        assert_eq!(
            focused[(edge, 0)].style().fg,
            Some(Color::Yellow),
            "the focused rail's right edge is accented"
        );
    }

    /// Trunk labels pluralize by configured count; the chord never changes.
    #[test]
    fn mode_labels_pluralize_by_configured_count() {
        let (_tmp, mut app) = make_app();
        assert_eq!(app.mode_label(TopMode::Board), "Board");
        assert_eq!(app.mode_label(TopMode::Cycle), "Cycle");
        assert_eq!(app.mode_label(TopMode::Milestones), "Milestone");
        let cells = draw_board(&app, 80, 24);
        assert!(
            flush_line(&cells, 80, 2).starts_with("F3 Board"),
            "{:?}",
            flush_line(&cells, 80, 2)
        );
        assert!(
            flush_line(&cells, 80, 4).starts_with("F4 Cycle"),
            "{:?}",
            flush_line(&cells, 80, 4)
        );
        assert!(
            flush_line(&cells, 80, 5).starts_with("F5 Milestone"),
            "{:?}",
            flush_line(&cells, 80, 5)
        );

        // The boundary is `count > 1`: one cycle stays singular, two pluralize.
        app.store
            .config
            .cycles
            .insert("Solo".into(), crate::config::PlanningCycle::default());
        assert_eq!(app.mode_label(TopMode::Cycle), "Cycle");
        app.store
            .config
            .cycles
            .insert("Pair".into(), crate::config::PlanningCycle::default());
        assert_eq!(app.mode_label(TopMode::Cycle), "Cycles");

        // Two boards pluralize the Board trunk.
        let (_tmp, app) = make_branchy_app();
        assert_eq!(app.mode_label(TopMode::Board), "Boards");
        let cells = draw_board(&app, 80, 24);
        let board_row = (0..24u16)
            .find(|row| flush_line(&cells, 80, *row).starts_with("F3 "))
            .expect("the Board trunk is drawn");
        assert!(
            flush_line(&cells, 80, board_row).starts_with("F3 Boards"),
            "{:?}",
            flush_line(&cells, 80, board_row)
        );

        // Milestones follow the same rule.
        let (_tmp, app) = make_app();
        let planner =
            crate::planning::Planner::from_config(app.store.config.clone(), app.project_root());
        planner
            .create_milestone_file("Backlog", None, None)
            .unwrap();
        assert_eq!(app.mode_label(TopMode::Milestones), "Milestone");
        planner.create_milestone_file("Q4", None, None).unwrap();
        assert_eq!(app.mode_label(TopMode::Milestones), "Milestones");
    }
}