tix/ui/

board.rs

use ratatui::Frame;
use ratatui::layout::{Constraint, Direction, Layout, Position, Rect};
use ratatui::style::{Color, Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Borders, List, ListItem, ListState, Paragraph};
use std::collections::BTreeMap;
use std::collections::HashMap;
use std::collections::HashSet;

use crate::config::BoardConfiguration;
use crate::model::{Issue, Priority};
use crate::search::{Corpus, StructuredFilter};
use crate::storage::Store;

use super::widgets;

#[derive(Debug, Clone)]
struct GroupSection {
    name: String,
    start: usize,
    end: usize,
    done: usize,
    total: usize,
}

/// The grouped board's direct-navigation affordance (WP06 T030 step 5, FR-004).
///
/// A grouped board must still open an issue's own detail and edit without passing
/// through the epic layer, so the footer states it rather than leaving it implied by
/// the card text. One constant, so the render and any test that names it cannot
/// drift.
const GROUP_OPEN_AFFORDANCE: &str = "Enter: open issue";

/// One badge per issue that records health, keyed by number (WP06 T030).
///
/// Built once per board build, like `blocked_reasons` and `child_markers`: the badge
/// comes from the shared index and rollup, and an issue with neither a recorded value
/// nor contributors gets no entry at all.
fn health_badges(issues: &[Issue]) -> BTreeMap<u32, String> {
    let policy = crate::health::HealthPolicy::v1();
    let index = crate::health::HealthIndex::build(issues, &[], &[], &policy);
    let mut out = BTreeMap::new();
    for issue in issues {
        let scope = crate::health::HealthScope::of_issue(issue.number);
        let Some((state, recorded)) = index.state_of(issue.number) else {
            continue;
        };
        let derived = crate::health::rollup(&index, &scope, &policy);
        // Nothing recorded and nobody contributing: nothing to say. A legacy issue is
        // reported as `unknown` by the detail view and by the CLI, which is where a
        // reader who asked about it is looking.
        if recorded.is_none() && derived.contributions.is_empty() {
            continue;
        }
        let current = state.as_str();
        let badge = if derived.is_derived() && derived.state.as_str() != current {
            format!("{current}\u{2192}{}", derived.state.as_str())
        } else {
            current.to_string()
        };
        out.insert(issue.number, badge);
    }
    out
}

#[derive(Debug, Clone)]
pub struct Card {
    pub number: u32,
    pub title: String,
    pub priority: Priority,
    pub labels: Vec<String>,
    pub assignee: Option<String>,
    pub filename: String,
    pub commit: Option<String>,
    pub created: String,
    pub due_date: Option<String>,
    pub status: String,
    /// The issue's resolved category label, from the service's own `label()`
    /// (WP05 T022, FR-004).
    ///
    /// `Some` for a column the board configures, `None` for one it does not — a
    /// configuration error the user should be able to *see*, rather than a
    /// transition-policy default silently applied to a display. The renderer shows
    /// `(unmapped)` for `None`.
    ///
    /// **The label carries the meaning, not the color.** A board or terminal with no
    /// color must still convey the category, so the label is always rendered and the
    /// `color_hint` only ever tints it (T022 step 3, research R6).
    pub category: Option<String>,
    /// The category's color hint, for tinting. Advisory only: dropping it changes
    /// the display's color and nothing else.
    pub category_color: Option<crate::workflow::ColorHint>,
    /// Whether the service considers this issue **complete** (WP05, C-004).
    ///
    /// Was `issue.status.is(done_column)` — a column-*name* comparison. On a board
    /// whose `category_map` puts `completed` somewhere other than its `done_column`
    /// that is a different question from the one the service answers, and this flag
    /// drives the card's completion styling and the group's rollup.
    pub done: bool,
    pub cycle: Option<String>,
    pub milestone: Option<String>,
    /// The issue's blocked reason, from the relationship service, or `None`.
    ///
    /// Derived, never stored (data-model §4, C-003): recomputed from the graph
    /// on every board build, so a card cannot show a stale blocked state after
    /// its blocker moved.
    pub blocked: Option<String>,
    /// The issue's hierarchy marker: `3` for three children, `3 1/3` when one is
    /// complete, or `None` for a leaf.
    ///
    /// `None` for a leaf rather than `Some("0")`, so a card cannot show a child
    /// count for an issue that is not a parent. Built from the service's
    /// [`crate::commands::parent::HierarchyFacts`] on every board build, so it
    /// cannot go stale when a child is created or moved — the same discipline
    /// `blocked` follows.
    pub children: Option<String>,
    /// The issue's decomposition parent, when it has one (tix #1399).
    ///
    /// Carried on the card rather than looked up at render time, so the board can
    /// place a sub-issue beneath its parent without a second pass over the issues.
    pub parent: Option<u32>,
    /// How deeply the card is nested in the board's tree rendering (tix #1399).
    ///
    /// `0` for a top-level card, `1` for a sub-issue shown directly under its
    /// parent. Never above `1`: only one level is rendered, so a grandchild stays
    /// at `0` and is drawn as a normal top-level card.
    pub depth: u8,
    /// Whether this issue is **archived** — its file is dot-prefixed (issue #1492).
    ///
    /// A card only ever carries `true` on a board built with archived issues
    /// included (the TUI's archive toggle); the default board is enumerated from
    /// the active set and never sees one. Rendered as the `[archived]` token, in the
    /// same bracketed language as `[~]` and `[N]`.
    pub archived: bool,

    /// The issue's compact health badge (mission `project-issue-health-status-01M3C8HX`,
    /// WP06 T030): the state the issue records, and the derived value beside it when
    /// the two differ (`at_risk->needs_attention`).
    ///
    /// Built from the **shared** index and rollup — never from a surface-local reading
    /// of the `health:` block, and never from a comparison of statuses (C-006). The
    /// spelling is the state's stable `as_str()`, the same word the CLI's
    /// `--columns health` cell prints, so the two surfaces cannot diverge. `None` when
    /// the issue records no health at all: a legacy card carries no badge, exactly as
    /// a leaf carries no child marker, so the board stays scannable.
    pub health: Option<String>,
    /// How many `related_issues` entries the issue carries (tix #1513).
    ///
    /// A plain count, computed from the issue set the board was built over, so the
    /// card cannot go stale when the field is edited — the same discipline `blocked`
    /// and `children` follow. `0` means no marker at all, which keeps a column of
    /// cards scannable.
    pub related: usize,
    /// The issue's **resolved project ids**, in registry declaration order
    /// (WP06 T028).
    ///
    /// Resolved once per board build from the shared membership index
    /// ([`crate::projects::ProjectIndex::build`]), so the board cannot disagree with
    /// `tix project list` about who is a member, and an association the registry does
    /// not know is not a project here either. Empty means the issue is in no project,
    /// which is the bucket the partition labels `(no project)`.
    ///
    /// Carried on the card rather than looked up at render time for the same reason
    /// `blocked`, `children` and `related` are: the renderer has no store, and a
    /// second read of the issue set per frame is work the build already did.
    pub projects: Vec<String>,
    /// The issue's **resolved epic ids**, in registry declaration order (WP06
    /// T030).
    ///
    /// Resolved once per board build from the shared membership index
    /// ([`crate::epics::EpicIndex::build`]) — only references the registry can
    /// resolve — so the board cannot disagree with `tix epic list` about who is a
    /// member, and a reference the registry does not know is not an epic here
    /// either. Empty means the issue is in no epic, which is the bucket the
    /// partition labels `(no epic)`.
    ///
    /// Carried on the card rather than looked up at render time for the same reason
    /// `projects` is: the renderer has no store, and a second read of the issue set
    /// per frame is work the build already did.
    pub epics: Vec<String>,
}

/// The project partition of one board build (WP06 T028).
///
/// Built once from the **shared** membership index
/// ([`crate::projects::ProjectIndex::build`]), so the board cannot disagree with
/// `tix project list` about who is a member: the resolved ids are the registry's,
/// and an association the registry does not know is not a project here either — it
/// is reported by `tix lint` instead, and its issue is bucketed `(no project)`.
///
/// That last point is a **chosen asymmetry** with the criterion rather than a
/// disagreement to be papered over: `StructuredFilter::project_matches` matches a
/// stored association **verbatim**, so `project:<stale-id>` still *finds* the issues
/// carrying a deleted project's id (the repair affordance `tix project remove`
/// needs), while this partition — which answers "which project owns this issue?" —
/// has no bucket for an id nothing resolves to. See `project_matches`'s doc.
///
/// The bucket rules are the design decision T027 step 4 records:
///
/// - an issue in **no** project is its own clearly labelled `(no project)` bucket;
/// - an issue in exactly **one** project sits in that project's bucket;
/// - an issue in **several** projects sits in a single `(multiple projects)`
///   bucket rather than being duplicated into each project's section.
///
/// Duplication is the road not taken, and deliberately: one issue would become two
/// cards, and the board's cursor, hit-testing and per-column counts are all
/// index-into-one-list arithmetic — a card that appeared twice would need a second
/// identity the renderer does not have. The **filter** still matches an issue in
/// two projects under either id (that is [`crate::search::StructuredFilter::project_matches`]),
/// so the union semantics are not lost where they matter.
struct ProjectPartition {
    /// Issue number -> its resolved project ids, registry declaration order.
    memberships: HashMap<u32, Vec<String>>,
    /// Project id -> its declaration index, for the sort rank.
    order: HashMap<String, usize>,
}

impl ProjectPartition {
    fn build(config: &crate::config::Config, issues: &[Issue]) -> Self {
        // Both halves come from the **service**, so the board cannot disagree with
        // `tix list --group project` / `tix status --group project` about who is a
        // member or which bucket labels them (WP09 item D): the memberships are
        // [`crate::projects::ProjectIndex::resolved_memberships`], and the label is
        // [`crate::projects::project_bucket_label`].
        let index = crate::projects::ProjectIndex::build(config, issues);
        let order: HashMap<String, usize> = index
            .projects()
            .iter()
            .enumerate()
            .map(|(position, project)| (project.id.to_string(), position))
            .collect();
        Self {
            memberships: index.resolved_memberships(),
            order,
        }
    }

    /// The issue's resolved project ids, in declaration order.
    fn memberships(&self, number: u32) -> Vec<String> {
        self.memberships.get(&number).cloned().unwrap_or_default()
    }

    /// The partition rank of one issue: a single membership sorts by its project's
    /// declaration index, several sort after every declared project (and before
    /// the no-project bucket), and none sorts last so `(no project)` is the final
    /// section.
    fn rank(&self, number: u32) -> usize {
        match self.memberships.get(&number).map(Vec::as_slice) {
            None | Some([]) => usize::MAX,
            Some([only]) => self.order.get(only).copied().unwrap_or(usize::MAX),
            Some(_) => usize::MAX - 1,
        }
    }
}

/// The group-section label for one card's project membership (WP06 T028).
///
/// `(no project)` is the clearly labelled bucket T028 step 2 requires, and
/// `(multiple projects)` is the bucket an issue in several projects lands in (see
/// [`ProjectPartition`] for why it is one bucket rather than a duplicate per
/// project). A single membership is labelled with the project **id**, because the
/// id is what selects a project, so a reader can act on the header.
fn project_bucket_label(projects: &[String]) -> String {
    // The service owns the bucket rule (WP09 item D); this delegates rather than
    // spelling the three labels a second time.
    crate::projects::project_bucket_label(projects)
}

/// The epic partition of one board build (WP06 T030).
///
/// The exact analogue of [`ProjectPartition`] for the epic registry. Built once from
/// the **shared** membership index ([`crate::epics::EpicIndex::build`]), so the
/// board cannot disagree with `tix epic list` about who is a member: the resolved ids
/// are the registry's, and a reference the registry does not know is not an epic here
/// either — it is reported by `tix lint` instead, and its issue is bucketed
/// `(no epic)`.
///
/// That last point is the same **chosen asymmetry** the project partition records:
/// [`crate::search::StructuredFilter::epic_matches`] matches a stored reference
/// **verbatim**, so `epic:<stale-id>` still *finds* the issues carrying a deleted
/// epic's id (the repair affordance `tix epic remove` needs), while this partition —
/// which answers "which epic owns this issue?" — has no bucket for an id nothing
/// resolves to.
///
/// The bucket rules are the decision T029 step 4 records (one bucket per issue):
///
/// - an issue in **no** epic is its own clearly labelled `(no epic)` bucket;
/// - an issue in exactly **one** epic sits in that epic's bucket;
/// - an issue in **several** epics sits in a single `(multiple epics)` bucket rather
///   than being duplicated into each epic's section.
///
/// Duplication is the road not taken for the reason [`ProjectPartition`] gives: one
/// issue would become several cards, and the board's cursor, hit-testing and
/// per-column counts are all index-into-one-list arithmetic. The **filter** still
/// matches an issue in two epics under either id, so the union semantics are not lost
/// where they matter.
struct EpicPartition {
    /// Issue number -> its resolved epic ids, registry declaration order.
    memberships: HashMap<u32, Vec<String>>,
    /// Epic id -> its declaration index, for the sort rank.
    order: HashMap<String, usize>,
}

impl EpicPartition {
    fn build(config: &crate::config::Config, issues: &[Issue]) -> Self {
        // Both halves come from the **service**: the index owns the membership rule
        // (which references resolve), and `memberships_by_issue` is the service's own
        // inverse of its buckets, in declaration order — so a filter, the CLI's
        // `--group epic` and this partition cannot disagree about who is a member
        // (WP09 item C).
        let index = crate::epics::EpicIndex::build(config, issues);
        let order: HashMap<String, usize> = index
            .epics()
            .iter()
            .enumerate()
            .map(|(position, epic)| (epic.id.to_string(), position))
            .collect();
        let memberships = index.memberships_by_issue();
        Self { memberships, order }
    }

    /// The issue's resolved epic ids, in declaration order.
    fn memberships(&self, number: u32) -> Vec<String> {
        self.memberships.get(&number).cloned().unwrap_or_default()
    }

    /// The partition rank of one issue: a single membership sorts by its epic's
    /// declaration index, several sort after every declared epic (and before the
    /// no-epic bucket), and none sorts last so `(no epic)` is the final section.
    fn rank(&self, number: u32) -> usize {
        match self.memberships.get(&number).map(Vec::as_slice) {
            None | Some([]) => usize::MAX,
            Some([only]) => self.order.get(only).copied().unwrap_or(usize::MAX),
            Some(_) => usize::MAX - 1,
        }
    }
}

/// The group-section label for one card's epic membership (WP06 T030).
///
/// Delegates to [`crate::search::epic_bucket_label`] rather than spelling the three
/// labels a second time, so the board's header and the filter's vocabulary name the
/// same bucket.
fn epic_bucket_label(ids: &[String]) -> String {
    crate::search::epic_bucket_label(ids)
}

impl crate::config::OrderBy {
    /// Sort cards in place per the board's `order_by` setting. `none` is a
    /// no-op. `sort_by` is stable, so equal creation dates keep the
    /// underlying store order (relative filename ascending) — deterministic
    /// ties with no extra key. Dates are zero-padded `YYYY-MM-DD`, so
    /// lexicographic comparison is chronological.
    pub fn sort(&self, cards: &mut [Card]) {
        match self {
            crate::config::OrderBy::CreatedAtDesc => {
                cards.sort_by(|a, b| b.created.cmp(&a.created))
            }
            crate::config::OrderBy::CreatedAtAsc => cards.sort_by(|a, b| a.created.cmp(&b.created)),
            crate::config::OrderBy::None => {}
        }
    }
}

fn sort_by_default_order(board_config: &BoardConfiguration, cards: &mut [Card]) {
    match board_config.order_by {
        crate::config::OrderBy::CreatedAtDesc => {
            cards.sort_by(|a, b| {
                b.created
                    .cmp(&a.created)
                    .then_with(|| a.filename.cmp(&b.filename))
            });
        }
        crate::config::OrderBy::CreatedAtAsc => {
            cards.sort_by(|a, b| {
                a.created
                    .cmp(&b.created)
                    .then_with(|| a.filename.cmp(&b.filename))
            });
        }
        crate::config::OrderBy::None => {
            cards.sort_by(|a, b| a.filename.cmp(&b.filename));
        }
    }
}

fn sort_cards(board_config: &BoardConfiguration, cards: &mut [Card]) {
    if board_config.card_order.is_empty() {
        sort_by_default_order(board_config, cards);
        return;
    }

    let mut baseline = cards.to_vec();
    sort_by_default_order(board_config, &mut baseline);

    let manual_cards: Vec<Card> = board_config
        .card_order
        .iter()
        .filter_map(|filename| {
            baseline
                .iter()
                .find(|card| card.filename == *filename)
                .cloned()
        })
        .collect();
    let touched: HashSet<String> = manual_cards
        .iter()
        .map(|card| card.filename.clone())
        .collect();
    let mut manual_iter = manual_cards.into_iter();
    let mut ordered = Vec::with_capacity(baseline.len());

    for card in baseline {
        if touched.contains(card.filename.as_str()) {
            if let Some(manual_card) = manual_iter.next() {
                ordered.push(manual_card);
            } else {
                ordered.push(card);
            }
        } else {
            ordered.push(card);
        }
    }

    cards.clone_from_slice(&ordered);
}

/// Reorder one column so each card's sub-issues sit **immediately after it**,
/// marking them `depth = 1` (tix #1399).
///
/// Only **one** level is ever nested. A card is placed under its parent only when
/// that parent is itself a *top-level* card of this column — meaning the parent has
/// no parent of its own present here. A grandchild (a card whose parent is itself a
/// sub-issue) therefore stays `depth = 0` in its normal position rather than
/// stacking under the child, so the tree cannot grow past one indent.
///
/// The ordering is settled **here, at build time**, not in the renderer: the
/// selection index and the pointer hit-test both address cards by their index in
/// the column, so a reorder only the renderer knew about would make a click or a
/// `j` land on the wrong card.
///
/// Every card is emitted exactly once: a nested card is dropped from the top-level
/// sequence and re-emitted under its parent, and nothing else moves.
fn nest_children(cards: &mut Vec<Card>) {
    let count = cards.len();
    if count == 0 {
        return;
    }
    let position: std::collections::HashMap<u32, usize> = cards
        .iter()
        .enumerate()
        .map(|(i, card)| (card.number, i))
        .collect();
    // A card is a root of *this* column when it has no parent here: no parent at
    // all, or a parent living in another column.
    let is_root = |index: usize| match cards[index].parent {
        None => true,
        Some(parent) => !position.contains_key(&parent),
    };

    let mut adopted: Vec<Vec<usize>> = vec![Vec::new(); count];
    let mut top_level: Vec<usize> = Vec::with_capacity(count);
    for (index, card) in cards.iter().enumerate() {
        match card
            .parent
            .and_then(|parent| position.get(&parent).copied())
        {
            Some(parent) if is_root(parent) => adopted[parent].push(index),
            _ => top_level.push(index),
        }
    }

    let mut ordered: Vec<Card> = Vec::with_capacity(count);
    for index in top_level {
        let mut card = cards[index].clone();
        card.depth = 0;
        ordered.push(card);
        for &child in &adopted[index] {
            let mut child_card = cards[child].clone();
            child_card.depth = 1;
            ordered.push(child_card);
        }
    }
    *cards = ordered;
}

pub(crate) fn sparse_card_order(board_config: &BoardConfiguration, cards: &[Card]) -> Vec<String> {
    let mut baseline = cards.to_vec();
    sort_by_default_order(board_config, &mut baseline);
    baseline
        .iter()
        .zip(cards.iter())
        .filter(|(baseline_card, current_card)| baseline_card.filename != current_card.filename)
        .map(|(_, current_card)| current_card.filename.clone())
        .collect()
}

#[derive(Debug, Clone)]
pub struct BoardColumn {
    pub name: String,
    pub cards: Vec<Card>,
}

/// What a pointer position over the board resolves to (D3). `row` is the
/// card's index inside its column — the same index [`BoardState::selected`]
/// uses — so the caller can compare it directly against the selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HitTarget {
    Card { col: usize, row: usize },
    Column { col: usize },
}

/// Compact capacity cells the board's cycle group headers append (WP06 T032).
///
/// One already-rendered cell per configured cycle scope, keyed by **both** the cycle
/// reference a card names and the scope's resolved display label, so either spelling
/// of one scope finds it. Built by [`crate::app::App`] from the shared calculation —
/// never here, and never from a second pass over the issues.
pub type CapacitySummaries = std::collections::BTreeMap<String, String>;

#[derive(Debug, Clone)]
pub struct BoardState {
    /// Visible columns only — configured columns not listed in the active
    pub columns: Vec<BoardColumn>,
    /// Columns hidden from the active board configuration. Their cards stay
    /// in board state (keyed by column name) and remain reachable via
    /// filters/search (DM-01M2MHJB884WCTVCDHPD2T3GE7); they never render.
    pub hidden: Vec<BoardColumn>,
    pub mismatch: BoardColumn,
    /// Whether the computed "Mismatched" pseudo-column is part of the
    /// navigation/render surface (C-002 / FR-003). Cards in unknown statuses
    /// are always collected into [`BoardState::mismatch`]; the column is only
    /// shown when the effective configuration sets `show_mismatch`.
    pub show_mismatch: bool,
    pub active_col: usize,
    pub selected: usize,
    /// The `(col, card index)` the pointer is hovering (D8), set by `Moved`
    /// events and cleared on `Up` / when the pointer leaves the board.
    /// Rendered as a highlight only — it never changes the selection.
    pub hover: Option<(usize, usize)>,
    /// The column the pointer is over, set for **any** position inside a column —
    /// including empty space below the last card, where `hover` is `None`. The
    /// renderer marks the hovered column from this, so an empty column lights up
    /// too. Cleared with `hover`.
    pub hover_col: Option<usize>,
    pub filter: Option<String>,
}

/// Shorten `msg` to at most `budget` **display cells**, appending an ellipsis
/// when anything was dropped.
///
/// The marker is appended *within* the budget rather than after it, so the result
/// is never wider than the area it is rendered into. A combining mark or a
/// zero-width control contributes no width, so it is kept without consuming
/// budget rather than being dropped.
pub fn truncate_to_cells(msg: &str, budget: usize) -> String {
    use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};

    const ELLIPSIS: char = '\u{2026}';
    if budget == 0 {
        return String::new();
    }
    if UnicodeWidthStr::width(msg) <= budget {
        return msg.to_string();
    }

    // Reserve one cell for the marker. A double-width character cannot fit in
    // the last cell, so the loop stops on a width overflow rather than on a
    // character count.
    let marker_width = UnicodeWidthChar::width(ELLIPSIS).unwrap_or(1);
    let mut out = String::new();
    let mut used = 0usize;
    for ch in msg.chars() {
        let w = UnicodeWidthChar::width(ch).unwrap_or(0);
        if used + w + marker_width > budget {
            break;
        }
        out.push(ch);
        used += w;
    }
    out.push(ELLIPSIS);
    out
}

/// The blocked reason for every issue, read from the relationship service.
///
/// One graph over the **whole** set, so the answer does not depend on which
/// issues the board happens to be showing (see [`BoardState::blocked`]).
fn blocked_reasons(
    issues: &[crate::model::Issue],
    done_column: &str,
) -> std::collections::BTreeMap<u32, String> {
    let views: Vec<crate::relationships::IssueView<'_>> =
        issues.iter().map(crate::model::Issue::issue_view).collect();
    let graph = crate::relationships::RelationshipGraph::new(&views, done_column);
    issues
        .iter()
        .filter_map(|issue| {
            crate::commands::blocked_note(&graph.blocked_state(issue.number))
                .map(|note| (issue.number, note))
        })
        .collect()
}

/// The child-count marker for every issue that has children, keyed by number.
///
/// One index over the whole set, so the marker does not depend on which issues the
/// board is showing. The text comes from the shared `HierarchyFacts`, which is what
/// `tix parent show`, `tix show` and `tix list --show progress` read, so the four
/// surfaces cannot report different figures.
fn child_markers(
    issues: &[crate::model::Issue],
    done_column: &str,
) -> std::collections::BTreeMap<u32, String> {
    let views: Vec<crate::relationships::IssueView<'_>> =
        issues.iter().map(crate::model::Issue::issue_view).collect();
    let index = crate::hierarchy::HierarchyIndex::build(&views);
    issues
        .iter()
        .filter_map(|issue| {
            let facts =
                crate::commands::parent::facts_for(&index, issues, issue.number, done_column);
            facts.has_children().then(|| {
                (
                    issue.number,
                    format!(
                        "{} {}/{}",
                        facts.rollup.direct_children,
                        facts.rollup.completed_children,
                        facts.rollup.progress.total
                    ),
                )
            })
        })
        .collect()
}

impl BoardState {
    /// WP05: the resolution must be for the board this call is building, not for
    /// whichever board happens to be `default`.
    ///
    /// `board_config` can be any of the configured boards, and a board selected in
    /// the TUI is not necessarily the default one. Resolving against the default
    /// would give a card on the `staging` board the categories configured for
    /// `default` — a wrong answer rather than a missing one, which is worse.
    ///
    /// The board is identified by **pointer identity** against the config's boards,
    /// because `build` receives a `&BoardConfiguration` and not a name. That is exact
    /// and needs no name plumbing; a board not found in the config falls back to its
    /// own columns with the global vocabulary, which is the honest reading of a
    /// configuration `tix` did not load.
    /// Public so the startup path can build a board from a single shared
    /// enumeration (tix #1518) instead of each caller re-deriving it.
    pub fn resolution_for(
        store: &Store,
        board_config: &BoardConfiguration,
    ) -> crate::workflow::CategoryResolution {
        let name = store
            .config
            .configs()
            .find(|(_, board)| std::ptr::eq(*board, board_config))
            .map(|(name, _)| name)
            .unwrap_or("default");
        crate::workflow::resolution(&store.config, board_config, name)
    }

    pub fn build(store: &Store, board_config: &BoardConfiguration) -> Self {
        Self::build_with(store, board_config, false, false)
    }

    /// [`BoardState::build`], optionally including **archived** issues (issue #1492).
    ///
    /// `include_archived == false` is the default and the fast path: enumeration reads
    /// [`Store::list`], which drops a dot-prefixed filename from the directory entry
    /// without opening the file. `true` reads [`Store::list_all`], which is what the
    /// TUI's archive toggle asks for *on demand* — the point being that a repository
    /// with thousands of archived issues is never walked for a board that does not
    /// show them.
    pub fn build_with_archived(
        store: &Store,
        board_config: &BoardConfiguration,
        include_archived: bool,
    ) -> Self {
        Self::build_with(store, board_config, include_archived, false)
    }

    /// [`BoardState::build_with_archived`], optionally rendering sub-issues under
    /// their parents (tix #1399).
    ///
    /// `show_children == true` reorders every column so a card's direct sub-issues
    /// follow it, marked `depth = 1` (see [`nest_children`]). The reorder happens at
    /// **build** time, not at draw time, because the selection index and the pointer
    /// hit-test both address cards by their index inside a column — a tree only the
    /// renderer knew about would make a click or a `j` land on the wrong card.
    pub fn build_with(
        store: &Store,
        board_config: &BoardConfiguration,
        include_archived: bool,
        show_children: bool,
    ) -> Self {
        let issues = if include_archived {
            store.list_all()
        } else {
            store.list()
        }
        .unwrap_or_default();
        let resolution = Self::resolution_for(store, board_config);
        Self::build_from_issues(
            &issues,
            board_config,
            &store.config,
            &resolution,
            show_children,
        )
    }

    /// Build a board from an in-memory slice of issues (issue #10 follow-up).
    ///
    /// The single build path: [`BoardState::build_with`] reads the store and
    /// delegates here, and the TUI's incremental refresh rebuilds from its
    /// in-memory corpus without re-reading the tree. `config` supplies the
    /// completion column; `resolution` is the category resolution of the board
    /// being built (see [`BoardState::resolution_for`]).
    pub fn build_from_issues(
        issues: &[Issue],
        board_config: &BoardConfiguration,
        config: &crate::config::Config,
        resolution: &crate::workflow::CategoryResolution,
        show_children: bool,
    ) -> Self {
        // WP09: the **service's** completion column, not `done_column`. The
        // `blocked_reasons` and `child_markers` helpers take a column *name* — that is
        // their existing signature and it is not what makes them wrong. What was
        // wrong is which name they were handed: on a board whose `category_map` puts
        // `completed` on `shipped` while `done_column` is `done`, the TUI's blocked
        // marker was computed against `done_column` while `tix list`'s was computed
        // against the service, so the same issue read as blocked in the TUI and clear
        // in the CLI. The name is now resolved once, by the service.
        let done_column = crate::workflow::completion_column_or_default(board_config, config);
        let done_column = done_column.as_str();
        let blocked = blocked_reasons(issues, done_column);
        let children = child_markers(issues, done_column);
        let show_mismatch = board_config.show_mismatch;
        let hidden_names: Vec<&str> = board_config
            .hidden_columns
            .iter()
            .map(String::as_str)
            .collect();
        let mut column_map: Vec<Vec<Card>> =
            board_config.columns.iter().map(|_| Vec::new()).collect();
        let mut mismatch_cards = Vec::new();

        let health_badges = health_badges(issues);
        // The same partition the filtered build uses, from the same shared index:
        // an unfiltered board and a project-filtered one must label a card's
        // project identically (WP06 T028).
        let projects = ProjectPartition::build(config, issues);
        // The epic partition, from the same shared membership index, so an
        // unfiltered board and an epic-filtered one label a card's epic identically
        // (WP06 T030).
        let epics = EpicPartition::build(config, issues);
        for issue in issues {
            let card = Card {
                number: issue.number,
                title: issue.title.clone(),
                priority: issue.priority.clone(),
                labels: issue.labels.clone(),
                assignee: issue.assignee.clone(),
                filename: issue.filename.clone(),
                commit: issue.commit.clone(),
                created: issue.created.clone(),
                due_date: issue.due_date.clone(),
                status: issue.status.display().to_string(),
                category: crate::workflow::category_of(issue, resolution)
                    .map(|c| c.label().to_string()),
                category_color: crate::workflow::category_of(issue, resolution)
                    .and_then(|c| c.color_hint()),
                done: crate::workflow::is_completed(issue, resolution),
                cycle: issue.cycles.as_ref().and_then(|v| v.first().cloned()),
                milestone: issue.milestones.as_ref().and_then(|v| v.first().cloned()),
                blocked: blocked.get(&issue.number).cloned(),
                children: children.get(&issue.number).cloned(),
                parent: issue.parent,
                depth: 0,
                archived: issue.archived,
                related: issue.related_issues.len(),
                health: health_badges.get(&issue.number).cloned(),
                projects: projects.memberships(issue.number),
                epics: epics.memberships(issue.number),
            };
            if let Some(idx) = board_config
                .columns
                .iter()
                .position(|c| c == issue.status.display())
            {
                column_map[idx].push(card);
            } else {
                mismatch_cards.push(card);
            }
        }

        for cards in column_map.iter_mut() {
            sort_cards(board_config, cards);
        }
        sort_cards(board_config, &mut mismatch_cards);

        let mut columns: Vec<BoardColumn> = Vec::new();
        let mut hidden: Vec<BoardColumn> = Vec::new();
        for (cards, name) in column_map.into_iter().zip(board_config.columns.iter()) {
            let col = BoardColumn {
                name: name.clone(),
                cards,
            };
            if hidden_names.contains(&name.as_str()) {
                hidden.push(col);
            } else {
                columns.push(col);
            }
        }

        let mismatch = BoardColumn {
            name: "Mismatched".to_string(),
            cards: mismatch_cards,
        };

        let mut state = BoardState {
            columns,
            hidden,
            mismatch,
            show_mismatch,
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
        };
        state.apply_child_order(show_children);
        state
    }

    /// Nest each column's sub-issues beneath their parents when `show_children` is
    /// on (tix #1399). A no-op when it is off, so the default build is untouched.
    ///
    /// Applied to the visible columns and the "Mismatched" pseudo-column — every
    /// surface `render` and `hit_test` actually address. Hidden columns have no
    /// rendered presence, so they are left in their flat order.
    fn apply_child_order(&mut self, show_children: bool) {
        if !show_children {
            return;
        }
        for column in &mut self.columns {
            nest_children(&mut column.cards);
        }
        nest_children(&mut self.mismatch.cards);
    }

    /// Build a board from the search corpus, keeping only cards whose full
    /// serialized text matches **both** the fuzzy `query` layer and the
    /// structured `filter` layer (FR-012/FR-013). Both predicates run in a
    /// single pass over the corpus via [`crate::search::matches`] (NFR-001).
    ///
    /// When a filter is active (non-empty query or structured criteria set),
    /// hidden columns' matching cards are **revealed** in the rendered surface
    /// (DM-01M2MHJB884WCTVCDHPD2T3GE7: hidden-column cards reachable via
    /// filters/search). When no filter is active, matching cards from hidden
    /// columns are stashed in [`BoardState::hidden`] (no visual presence).
    pub fn build_filtered(
        board_config: &BoardConfiguration,
        config: &crate::config::Config,
        corpus: &Corpus,
        query: &str,
        filter: &StructuredFilter,
        resolution: &crate::workflow::CategoryResolution,
    ) -> Self {
        Self::build_filtered_with(
            board_config,
            config,
            corpus,
            query,
            filter,
            resolution,
            false,
        )
    }

    /// [`BoardState::build_filtered`], optionally rendering sub-issues under their
    /// parents (tix #1399).
    ///
    /// The `u` toggle is global, so it must keep working while a search or
    /// structured filter is active: `build_filtered` delegates here with
    /// `show_children == false` and the TUI passes its flag through.
    pub fn build_filtered_with(
        board_config: &BoardConfiguration,
        config: &crate::config::Config,
        corpus: &Corpus,
        query: &str,
        filter: &StructuredFilter,
        resolution: &crate::workflow::CategoryResolution,
        show_children: bool,
    ) -> Self {
        let show_mismatch = board_config.show_mismatch;
        // WP09, as in `build`: the service's completion column, so the filtered and
        // unfiltered boards agree on which column is blocked and which is complete.
        let done_column = crate::workflow::completion_column_or_default(board_config, config);
        let done_column = done_column.as_str();
        // Built from the corpus, not from the filtered slice below: a blocker the
        // query happens to exclude must still count as a blocker.
        let blocked = blocked_reasons(&corpus.issues, done_column);
        // Same reason, same discipline: a child the query excludes is still a
        // child, so a parent's marker must not shrink because the board is
        // filtered.
        let children = child_markers(&corpus.issues, done_column);
        let filtering = !query.is_empty() || filter.has_active_criteria();
        // A `group:<key>` with no explicit `sort:<key>` sorts by that key
        // (WP06 T028). A partition is only contiguous — and only in the key's own
        // order — when the cards are ordered by the same key, and the contract for
        // the project partition names the order explicitly ("declaration order,
        // no-project bucket last"). Without this, `group:project` alone would emit
        // one section per created-date run and the order would depend on the user
        // remembering to type `sort:project` as well.
        //
        // An explicit `sort:` still wins, so `group:cycle sort:due` keeps meaning
        // what it meant.
        let sort_key = crate::search::control_token(query, "sort")
            .or_else(|| crate::search::control_token(query, "group"));
        // The project partition, resolved once from the shared membership index
        // (NFR-001): the sorter and the renderer both read this, so there is no
        // second membership read and no scan per criterion.
        let projects = ProjectPartition::build(config, &corpus.issues);
        // The epic partition, read once from the same shared index as `projects`
        // (WP06 T030): the sorter and the renderer both read this, so there is no
        // second membership read.
        let epics = EpicPartition::build(config, &corpus.issues);
        // A bare-number query (all-ASCII-digit after trim) is an exact issue
        // number match, not a fuzzy digit search: only the issue whose
        // `number` equals it survives, still ANDed with the structured
        // filter (board-filtering FR-02 / FR-03). Any other query keeps the
        // fuzzy-text path.
        let number = crate::search::number_query(query);
        let hidden_names: Vec<&str> = board_config
            .hidden_columns
            .iter()
            .map(String::as_str)
            .collect();
        let mut column_map: Vec<Vec<Card>> =
            board_config.columns.iter().map(|_| Vec::new()).collect();
        let mut mismatch_cards = Vec::new();
        let mut matched_issues: Vec<&crate::model::Issue> = Vec::new();

        for (issue, text) in corpus.issues.iter().zip(corpus.texts().iter()) {
            // Bare-number query: exact issue-number match replaces the fuzzy
            // text layer (board-filtering FR-02); the structured filter still
            // runs (FR-03). Otherwise the composite fuzzy+structured
            // predicate applies unchanged.
            // `matches_issue`, not `matches` (WP08 T035): the TUI filter modal can
            // set a `category` criterion, and `matches` cannot judge it — it would
            // silently drop the criterion and show the **unfiltered** board while
            // the modal showed `category: completed` as active. The board already
            // holds the `resolution` (it is a parameter, because WP05 needed it for
            // the card labels), so the criterion costs one hash lookup per issue.
            let keep = if let Some(n) = number {
                issue.number == n && filter.evaluate_issue(issue, text, resolution)
            } else {
                crate::search::matches_issue(query, filter, issue, text, resolution)
            };
            if !keep {
                continue;
            }
            matched_issues.push(issue);
        }

        Self::sort_filtered_issues(&mut matched_issues, sort_key.as_deref(), &projects, &epics);

        let health_badges = health_badges(&corpus.issues);
        for issue in matched_issues {
            let card = Card {
                number: issue.number,
                title: issue.title.clone(),
                priority: issue.priority.clone(),
                labels: issue.labels.clone(),
                assignee: issue.assignee.clone(),
                filename: issue.filename.clone(),
                commit: issue.commit.clone(),
                created: issue.created.clone(),
                due_date: issue.due_date.clone(),
                status: issue.status.display().to_string(),
                category: crate::workflow::category_of(issue, resolution)
                    .map(|c| c.label().to_string()),
                category_color: crate::workflow::category_of(issue, resolution)
                    .and_then(|c| c.color_hint()),
                done: crate::workflow::is_completed(issue, resolution),
                cycle: issue.cycles.as_ref().and_then(|v| v.first().cloned()),
                milestone: issue.milestones.as_ref().and_then(|v| v.first().cloned()),
                blocked: blocked.get(&issue.number).cloned(),
                children: children.get(&issue.number).cloned(),
                parent: issue.parent,
                depth: 0,
                archived: issue.archived,
                related: issue.related_issues.len(),
                health: health_badges.get(&issue.number).cloned(),
                projects: projects.memberships(issue.number),
                epics: epics.memberships(issue.number),
            };
            if let Some(idx) = board_config
                .columns
                .iter()
                .position(|c| c == issue.status.display())
            {
                column_map[idx].push(card);
            } else {
                mismatch_cards.push(card);
            }
        }

        if sort_key.is_none() {
            for cards in column_map.iter_mut() {
                sort_cards(board_config, cards);
            }
            sort_cards(board_config, &mut mismatch_cards);
        }

        let mut columns: Vec<BoardColumn> = Vec::new();
        let mut hidden: Vec<BoardColumn> = Vec::new();
        for (cards, name) in column_map.into_iter().zip(board_config.columns.iter()) {
            let col = BoardColumn {
                name: name.clone(),
                cards,
            };
            if hidden_names.contains(&name.as_str()) {
                if filtering {
                    // Reveal hidden column when a filter is active so
                    // matching cards appear in the rendered surface
                    // (DM-01M2MHJB884WCTVCDHPD2T3GE7).
                    columns.push(col);
                } else {
                    hidden.push(col);
                }
            } else {
                columns.push(col);
            }
        }

        let mut state = BoardState {
            columns,
            hidden,
            mismatch: BoardColumn {
                name: "Mismatched".to_string(),
                cards: mismatch_cards,
            },
            show_mismatch,
            active_col: 0,
            selected: 0,
            filter: Some(query.to_string()),
            hover: None,
            hover_col: None,
        };
        state.apply_child_order(show_children);
        state
    }

    fn sort_filtered_issues(
        issues: &mut [&crate::model::Issue],
        sort: Option<&str>,
        projects: &ProjectPartition,
        epics: &EpicPartition,
    ) {
        match sort.unwrap_or("created") {
            // The project partition order (WP06 T028): registry declaration order
            // for a single membership, after every declared project for an issue in
            // several, and last of all for an issue in none — which is exactly the
            // order the buckets are rendered in, so the sections come out
            // contiguous and the `(no project)` bucket is last.
            "project" => issues.sort_by(|a, b| {
                projects
                    .rank(a.number)
                    .cmp(&projects.rank(b.number))
                    .then(a.number.cmp(&b.number))
            }),
            // The epic partition order (WP06 T030): the exact analogue of `project`
            // above, so `group:epic` alone emits one contiguous section per epic in
            // declaration order, then `(multiple epics)`, then `(no epic)` last.
            "epic" => issues.sort_by(|a, b| {
                epics
                    .rank(a.number)
                    .cmp(&epics.rank(b.number))
                    .then(a.number.cmp(&b.number))
            }),
            "due" => {
                issues.sort_by(|a, b| a.due_date.cmp(&b.due_date).then(a.number.cmp(&b.number)))
            }
            "start" => issues.sort_by(|a, b| {
                a.start_date
                    .cmp(&b.start_date)
                    .then(a.number.cmp(&b.number))
            }),
            "reviewer" => {
                issues.sort_by(|a, b| a.reviewer.cmp(&b.reviewer).then(a.number.cmp(&b.number)))
            }
            "cycle" => issues.sort_by(|a, b| {
                a.cycles
                    .as_ref()
                    .and_then(|v| v.first())
                    .cmp(&b.cycles.as_ref().and_then(|v| v.first()))
                    .then(a.number.cmp(&b.number))
            }),
            "milestone" => issues.sort_by(|a, b| {
                a.milestones
                    .as_ref()
                    .and_then(|v| v.first())
                    .cmp(&b.milestones.as_ref().and_then(|v| v.first()))
                    .then(a.number.cmp(&b.number))
            }),
            "status" => issues.sort_by(|a, b| {
                a.status
                    .display()
                    .cmp(b.status.display())
                    .then(a.number.cmp(&b.number))
            }),
            "priority" => issues.sort_by(|a, b| {
                a.priority
                    .to_string()
                    .cmp(&b.priority.to_string())
                    .then(a.number.cmp(&b.number))
            }),
            _ => issues.sort_by(|a, b| a.created.cmp(&b.created).then(a.number.cmp(&b.number))),
        }
    }

    /// True when no card anywhere is visible (used for zero-match feedback).
    pub fn is_empty(&self) -> bool {
        self.columns.iter().all(|c| c.cards.is_empty())
            && (!self.show_mismatch || self.mismatch.cards.is_empty())
    }

    pub fn total_cols(&self) -> usize {
        if self.show_mismatch {
            self.columns.len() + 1
        } else {
            self.columns.len()
        }
    }

    /// Map a terminal pointer `(x, y)` — given against the same `area` passed
    /// to [`render`] — to the card or column underneath. `status` mirrors
    /// whether [`render`] is drawing a status message, so the status row (not
    /// part of any column) never resolves to a target. Returns `None` for
    /// positions outside the board area (`y` above the columns or beyond the
    /// board) or when nothing is drawn. Uses [`compute_column_rects`] and
    /// [`super::widgets::card_line_count`] — the geometry `render` draws with —
    /// so the hit-tested layout matches the rendered one by construction (D3).
    pub fn hit_test(
        &self,
        area: Rect,
        display: BoardDisplay,
        status: bool,
        x: u16,
        y: u16,
    ) -> Option<HitTarget> {
        if area.height < 2 || area.width < 4 || self.total_cols() == 0 {
            return None;
        }
        let board_height = area.height.saturating_sub(u16::from(status));
        if y >= area.y + board_height {
            return None;
        }
        let board_area = Rect {
            height: board_height,
            ..area
        };

        let rects = compute_column_rects(board_area, self.total_cols());
        let (col, col_rect) = rects
            .iter()
            .enumerate()
            .find(|(_, r)| r.contains(Position::new(x, y)))?;

        let cards: &[Card] = if col < self.columns.len() {
            &self.columns[col].cards
        } else {
            &self.mismatch.cards
        };

        let group_mode = self
            .filter
            .as_deref()
            .and_then(|q| crate::search::control_token(q, "group"));

        // Items stack top-down exactly as `render` pushes them: group headers
        // occupy one row each, cards occupy `card_line_count` rows.
        let mut items: Vec<Option<usize>> = Vec::new();
        if let Some(mode) = group_mode.as_deref() {
            if let Some(sections) = Self::group_sections(cards, Some(mode)) {
                for section in sections {
                    items.push(None);
                    for (j, card) in cards
                        .iter()
                        .enumerate()
                        .take(section.end)
                        .skip(section.start)
                    {
                        let count = widgets::card_line_count(
                            card,
                            col_rect.width as usize,
                            display.wrap_titles,
                            display.title_lines,
                        );
                        for _ in 0..count {
                            items.push(Some(j));
                        }
                    }
                }
            }
        } else {
            for (j, card) in cards.iter().enumerate() {
                let count = widgets::card_line_count(
                    card,
                    col_rect.width as usize,
                    display.wrap_titles,
                    display.title_lines,
                );
                for _ in 0..count {
                    items.push(Some(j));
                }
            }
        }

        let has_footer = BoardState::group_footer(cards, group_mode.as_deref()).is_some();
        let list_height = col_rect.height.saturating_sub(u16::from(has_footer));
        // Content rows live between the block's top border and bottom border.
        let content_top = col_rect.y + 1;
        let content_end = col_rect.y + list_height.saturating_sub(1);
        if y >= content_top && y < content_end {
            let offset = usize::from(y - content_top);
            if let Some(Some(row)) = items.get(offset) {
                return Some(HitTarget::Card { col, row: *row });
            }
        }
        Some(HitTarget::Column { col })
    }

    /// Columns a card can be moved into: the configured columns plus (when
    /// shown) the "Mismatched" sentinel, which is never a move target. The
    /// `</>` move keys navigate *among movable columns* only.
    pub fn real_cols(&self) -> usize {
        self.columns.len()
    }

    pub fn column_name(&self, idx: usize) -> &str {
        if idx < self.columns.len() {
            &self.columns[idx].name
        } else if idx == self.columns.len() && self.show_mismatch {
            &self.mismatch.name
        } else {
            "Unknown"
        }
    }

    /// The name under the active cursor, resolving **hidden** columns too
    /// (visible region first, then hidden, then Unknown). Lets `toggle` keep a
    /// logical cursor on a just-hidden column so a second press re-shows it
    /// (T017: "a second press on the same column re-shows it").
    pub fn active_column_name(&self) -> &str {
        let visible = self.columns.len();
        if self.active_col < visible {
            &self.columns[self.active_col].name
        } else {
            let hidden_idx = self.active_col - visible;
            if hidden_idx < self.hidden.len() {
                &self.hidden[hidden_idx].name
            } else {
                "Unknown"
            }
        }
    }

    pub fn column_cards(&self, idx: usize) -> &[Card] {
        if idx < self.columns.len() {
            &self.columns[idx].cards
        } else if idx == self.columns.len() && self.show_mismatch {
            &self.mismatch.cards
        } else {
            &[]
        }
    }

    pub fn get_selected_card(&self) -> Option<&Card> {
        self.column_cards(self.active_col).get(self.selected)
    }

    pub fn move_left(&mut self) {
        let total = self.real_cols();
        self.active_col = if total == 0 {
            0
        } else if self.active_col >= total {
            total - 1
        } else {
            (self.active_col + total - 1) % total
        };
        self.clamp_selection();
    }

    pub fn move_right(&mut self) {
        let total = self.real_cols();
        self.active_col = if total == 0 || self.active_col >= total {
            0
        } else {
            (self.active_col + 1) % total
        };
        self.clamp_selection();
    }

    pub fn move_up(&mut self) {
        if self.selected > 0 {
            self.selected -= 1;
        }
    }

    pub fn move_down(&mut self) {
        let cards = self.column_cards(self.active_col);
        if self.selected + 1 < cards.len() {
            self.selected += 1;
        }
    }

    /// Move the selection by `cards` (negative moves up), clamped to the column
    /// (tix #1442 follow-up).
    ///
    /// The page step: `move_up`/`move_down` are the one-card steps, this is the same
    /// move by a screenful. It clamps for the reason the detail pane's scroll does — a
    /// jump past the end should land on the last card, not walk off it.
    pub fn move_selection_by(&mut self, cards: i32) {
        let len = self.column_cards(self.active_col).len();
        if len == 0 {
            self.selected = 0;
            return;
        }
        let next = i32::try_from(self.selected)
            .unwrap_or(i32::MAX)
            .saturating_add(cards);
        self.selected = next.clamp(0, i32::try_from(len).unwrap_or(i32::MAX) - 1) as usize;
    }

    pub fn clamp_selection(&mut self) {
        let cards = self.column_cards(self.active_col);
        if cards.is_empty() {
            self.selected = 0;
        } else if self.selected >= cards.len() {
            self.selected = cards.len() - 1;
        }
    }

    pub fn select_column(&mut self, col: usize) {
        let total = self.real_cols();
        if total > 0 {
            self.active_col = col % total;
        }
        self.clamp_selection();
    }

    fn group_footer(cards: &[Card], mode: Option<&str>) -> Option<String> {
        let sections = Self::group_sections(cards, mode)?;
        let text = sections
            .into_iter()
            .map(|section| {
                let pct = (section.done * 100).checked_div(section.total).unwrap_or(0);
                format!("{} {}/{} {pct}%", section.name, section.done, section.total)
            })
            .collect::<Vec<_>>()
            .join(" | ");
        // The grouped board keeps **direct issue navigation** (FR-004): the card
        // cursor and `Enter` open the issue's own detail and edit, with the group
        // label only as the section above it. The route is stated beside the
        // partition rather than implied by the card text.
        Some(format!("{text}  ·  {GROUP_OPEN_AFFORDANCE}"))
    }

    fn card_group(card: &Card, key: &str) -> String {
        match key {
            "cycle" => card.cycle.clone().unwrap_or_else(|| "(none)".to_string()),
            "milestone" => card
                .milestone
                .clone()
                .unwrap_or_else(|| "(none)".to_string()),
            // WP06 T028: the project bucket is read off the card's resolved
            // memberships, so a `group:project` board shows one section per project
            // in declaration order, then `(multiple projects)`, then the labelled
            // `(no project)` bucket last.
            "project" => project_bucket_label(&card.projects),
            // WP06 T030: the epic bucket, read off the card's resolved references
            // — one section per epic in declaration order, then `(multiple epics)`,
            // then the labelled `(no epic)` bucket last.
            "epic" => epic_bucket_label(&card.epics),
            _ => "(none)".to_string(),
        }
    }

    fn group_sections(cards: &[Card], mode: Option<&str>) -> Option<Vec<GroupSection>> {
        let key =
            mode.filter(|m| *m == "cycle" || *m == "milestone" || *m == "project" || *m == "epic")?;
        if cards.is_empty() {
            return None;
        }
        let mut sections = Vec::new();
        let mut current = String::new();
        let mut start = 0usize;
        let mut done = 0usize;
        let mut total = 0usize;
        for (idx, card) in cards.iter().enumerate() {
            let group = Self::card_group(card, key);
            if idx == 0 {
                current = group;
            } else if group != current {
                sections.push(GroupSection {
                    name: std::mem::take(&mut current),
                    start,
                    end: idx,
                    done,
                    total,
                });
                current = group;
                start = idx;
                done = 0;
                total = 0;
            }
            total += 1;
            if card.done {
                done += 1;
            }
        }
        sections.push(GroupSection {
            name: current,
            start,
            end: cards.len(),
            done,
            total,
        });
        Some(sections)
    }
}

/// Render options carried from the active board configuration into the board
/// draw. Kept tiny and copyable so tests and call sites stay light.
#[derive(Debug, Clone, Copy)]
pub struct BoardDisplay {
    pub wrap_titles: bool,
    pub title_lines: usize,
}

impl Default for BoardDisplay {
    fn default() -> Self {
        BoardDisplay {
            wrap_titles: true,
            title_lines: 3,
        }
    }
}

impl From<&crate::config::BoardConfiguration> for BoardDisplay {
    fn from(config: &crate::config::BoardConfiguration) -> Self {
        BoardDisplay {
            wrap_titles: config.wrap_titles,
            title_lines: config.title_lines,
        }
    }
}

/// Equal-width column slices for a board of `total_cols` columns (the same
/// `Constraint::Ratio` layout `render` draws), shared so hit-testing can map a
/// pointer position back to a column without re-deriving geometry (D3).
pub fn compute_column_rects(area: Rect, total_cols: usize) -> Vec<Rect> {
    if total_cols == 0 {
        return Vec::new();
    }
    Layout::default()
        .direction(Direction::Horizontal)
        .constraints(vec![Constraint::Ratio(1, total_cols as u32); total_cols])
        .split(area)
        .to_vec()
}

// `wip` is the one derived fact the board needs beyond its own state (WP05 T025):
// the columns' usage against their limits, from the shared snapshot. It is passed
// in rather than built here so every renderer in a frame reports the same figures.
#[allow(clippy::too_many_arguments)]
pub fn render(
    board: &BoardState,
    f: &mut Frame,
    area: Rect,
    status_msg: &Option<String>,
    drag_preview_col: Option<usize>,
    display: BoardDisplay,
    theme: &crate::ui::color::Theme,
    wip: Option<&crate::wip::WipSnapshot>,
    capacity: Option<&CapacitySummaries>,
) -> usize {
    // How many cards one screen of the **active** column holds (tix #1442 follow-up).
    //
    // Returned rather than re-derived by the caller: this is the only place that knows
    // the column's inner height *and* each card's rendered height, and a page key needs
    // both. `0` when nothing was drawn, so the caller cannot page a column that is not
    // on screen.
    let mut page_cards = 0usize;

    if area.height < 2 || area.width < 4 {
        return 0;
    }

    let status_height: u16 = if status_msg.is_some() { 1 } else { 0 };
    let board_height = area.height.saturating_sub(status_height);
    let board_area = Rect {
        height: board_height,
        ..area
    };
    let status_area = Rect {
        y: area.y + board_height,
        height: status_height,
        ..area
    };

    let total = board.total_cols();
    if total == 0 {
        return 0;
    }

    let chunks = compute_column_rects(board_area, total);

    for (i, chunk) in chunks.iter().enumerate() {
        let col = if i < board.columns.len() {
            &board.columns[i]
        } else {
            &board.mismatch
        };
        let group_mode = board
            .filter
            .as_deref()
            .and_then(|q| crate::search::control_token(q, "group"));

        let is_active = i == board.active_col;
        let is_mismatch_col = i == board.columns.len();
        let is_mismatch_highlight = is_mismatch_col && !col.cards.is_empty();
        // The column the pointer sits in — set for empty columns too, so hovering
        // anywhere in a column lights the whole column up (not just a card).
        let hovered_col = board.hover_col;

        let mut selected_row: Option<usize> = None;
        let items: Vec<ListItem> = if let Some(mode) = group_mode.as_deref() {
            if let Some(sections) = BoardState::group_sections(&col.cards, Some(mode)) {
                let mut items = Vec::new();
                for section in sections {
                    let pct = (section.done * 100).checked_div(section.total).unwrap_or(0);
                    // WP06 T032: a `[cycle]`-grouped board appends the scope's compact
                    // capacity cell to its own section header — the same line, one more
                    // fact, so grouping, filtering, card order and hit-testing are all
                    // untouched. A group whose name names no configured scope (a card in
                    // no cycle, or a cycle with no ceiling) keeps exactly the header it
                    // had, because a fabricated cell would be a TUI-only number.
                    let capacity_cell = (mode == "cycle")
                        .then(|| capacity.and_then(|cells| cells.get(&section.name)))
                        .flatten();
                    let header = match capacity_cell {
                        Some(cell) => format!(
                            "-- {mode}: {} ({}/{} done, {pct}%) · {cell} --",
                            section.name, section.done, section.total
                        ),
                        None => format!(
                            "-- {mode}: {} ({}/{} done, {pct}%) --",
                            section.name, section.done, section.total
                        ),
                    };
                    items.push(ListItem::new(Line::from(Span::styled(
                        header,
                        Style::default()
                            .fg(Color::Yellow)
                            .add_modifier(Modifier::BOLD),
                    ))));
                    for j in section.start..section.end {
                        let card = &col.cards[j];
                        let lines = widgets::card_lines_themed(
                            card,
                            chunk.width as usize,
                            display.wrap_titles,
                            display.title_lines,
                            theme,
                        );
                        let style = if is_active && j == board.selected {
                            selected_row = Some(items.len());
                            Style::default()
                                .bg(Color::DarkGray)
                                .add_modifier(Modifier::BOLD)
                        } else if board.hover == Some((i, j)) {
                            // Hover highlight only — selection is untouched (D8).
                            if drag_preview_col == Some(i) {
                                Style::default()
                                    .fg(Color::Yellow)
                                    .add_modifier(Modifier::BOLD)
                            } else {
                                Style::default().fg(Color::Cyan)
                            }
                        } else if is_mismatch_highlight {
                            Style::default().fg(Color::Red)
                        } else {
                            Style::default()
                        };
                        items.push(ListItem::new(lines).style(style));
                    }
                }
                items
            } else {
                Vec::new()
            }
        } else {
            col.cards
                .iter()
                .enumerate()
                .map(|(j, card)| {
                    let lines = widgets::card_lines_themed(
                        card,
                        chunk.width as usize,
                        display.wrap_titles,
                        display.title_lines,
                        theme,
                    );
                    let style = if is_active && j == board.selected {
                        selected_row = Some(j);
                        Style::default()
                            .bg(Color::DarkGray)
                            .add_modifier(Modifier::BOLD)
                    } else if board.hover == Some((i, j)) {
                        if drag_preview_col == Some(i) {
                            Style::default()
                                .fg(Color::Yellow)
                                .add_modifier(Modifier::BOLD)
                        } else {
                            Style::default().fg(Color::Cyan)
                        }
                    } else if is_mismatch_highlight {
                        Style::default().fg(Color::Red)
                    } else {
                        Style::default()
                    };
                    ListItem::new(lines).style(style)
                })
                .collect()
        };

        // The column's own count, replaced by the usage cell when the board
        // configures a limit for it: `in progress (4/3 8/10d!)` says what the header
        // said and what the limit is, and a board with no limits keeps the plain
        // `in progress (4)` it always had (WP05 T025).
        let title = match wip
            .and_then(|snapshot| snapshot.column(&col.name))
            .filter(|usage| usage.limit.is_some())
        {
            Some(usage) => format!("{} ({})", col.name, usage.cell()),
            None => format!("{} ({})", col.name, col.cards.len()),
        };
        let border_style = if drag_preview_col == Some(i) {
            Style::default().fg(Color::Yellow)
        } else if is_active {
            Style::default().fg(Color::Cyan)
        } else if is_mismatch_highlight {
            Style::default().fg(Color::Red)
        } else if hovered_col == Some(i) {
            // The hovered column gets its own accent so the pointer's column is
            // visible even when the card itself is small.
            Style::default()
                .fg(Color::Blue)
                .add_modifier(Modifier::BOLD)
        } else {
            Style::default()
        };

        let block = Block::default()
            .borders(Borders::ALL)
            .title(title)
            .border_style(border_style);

        let col_chunks = if BoardState::group_footer(&col.cards, group_mode.as_deref()).is_some() {
            Layout::default()
                .direction(Direction::Vertical)
                .constraints([Constraint::Min(1), Constraint::Length(1)])
                .split(*chunk)
        } else {
            Layout::default()
                .direction(Direction::Vertical)
                .constraints([Constraint::Min(1), Constraint::Length(0)])
                .split(*chunk)
        };

        let list = List::new(items).block(block);

        if is_active {
            // A page is what the reader can see: the column's inner height against the
            // heights the cards actually render at.
            page_cards = cards_per_screen(
                &col.cards,
                chunk.width as usize,
                col_chunks[0].height.saturating_sub(2),
                display,
            );
            let mut state = ListState::default();
            if let Some(row) = selected_row {
                state.select(Some(row));
            }
            f.render_stateful_widget(list, col_chunks[0], &mut state);
        } else {
            f.render_widget(list, col_chunks[0]);
        }
        if let Some(footer) = BoardState::group_footer(&col.cards, group_mode.as_deref()) {
            let para = Paragraph::new(Line::from(Span::styled(
                footer,
                Style::default().fg(Color::DarkGray),
            )));
            f.render_widget(para, col_chunks[1]);
        }
    }

    if let Some(msg) = status_msg {
        // The status area is one row and does not wrap, so anything longer is cut
        // by the widget with no indication at all. Mark the cut instead: a
        // silently shortened warning reads as a complete one, and the
        // retired-`links:` disclosure runs to ~100 characters before the filename,
        // which is routinely longer still.
        //
        // `Paragraph` is handed the truncated string rather than the full one, so
        // the ellipsis cannot itself be pushed off the right edge.
        //
        // Truncation is measured in **display cells**, not scalar values. A CJK
        // character occupies two cells, so `chars().take(budget)` yields a string
        // up to twice as wide as the area; the widget then hard-cuts it at the
        // right edge and discards the marker appended at the end of the
        // overflowed string — silently reinstating the exact failure this
        // truncation exists to prevent. `unicode-width` is already a dependency,
        // so this costs no new one.
        let budget = (status_area.width as usize).saturating_sub(1);
        let text = truncate_to_cells(msg, budget);
        let para =
            Paragraph::new(Line::from(Span::raw(text))).style(Style::default().fg(Color::Yellow));
        f.render_widget(para, status_area);
    }

    page_cards
}

/// How many of `cards` fit into `rows` of a column `width` cells wide.
///
/// Measured with the same [`widgets::card_lines`] the renderer draws, so the answer is
/// the height the reader actually sees rather than an estimate from a constant. Group
/// headers and the group footer are **not** counted: the result is a step size for a
/// page key, and a step that overshoots by a header or two is friendlier than one that
/// undershoots and leaves the reader pressing the key again.
///
/// Zero for an empty column — "there is nothing to page" — and at least one otherwise,
/// so a page key in a column shorter than a single card still moves somewhere.
fn cards_per_screen(cards: &[Card], width: usize, rows: u16, display: BoardDisplay) -> usize {
    if cards.is_empty() {
        return 0;
    }
    let mut used: u16 = 0;
    let mut fits = 0usize;
    for card in cards {
        let height = u16::try_from(
            widgets::card_lines(card, width, display.wrap_titles, display.title_lines).len(),
        )
        .unwrap_or(u16::MAX);
        if fits > 0 && used.saturating_add(height) > rows {
            break;
        }
        used = used.saturating_add(height);
        fits += 1;
        if used >= rows {
            break;
        }
    }
    fits.max(1)
}

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

    #[test]
    fn compute_column_rects_splits_into_equal_columns() {
        let area = Rect::new(5, 7, 90, 30);
        let rects = compute_column_rects(area, 3);
        assert_eq!(rects.len(), 3);
        assert_eq!((rects[0].x, rects[0].width), (5, 30));
        assert_eq!((rects[1].x, rects[1].width), (35, 30));
        assert_eq!((rects[2].x, rects[2].width), (65, 30));
        assert_eq!((rects[0].y, rects[0].height), (7, 30));
        assert_eq!((rects[2].y, rects[2].height), (7, 30));
    }

    #[test]
    fn compute_column_rects_zero_columns_is_empty() {
        assert_eq!(
            compute_column_rects(Rect::new(0, 0, 10, 10), 0),
            [] as [ratatui::prelude::Rect; 0]
        );
    }

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

        let wrapped = "A deliberately long card title that cannot fit on a single line inside the narrow column and must wrap over several rows";
        let cards = vec![
            Card {
                health: None,
                number: 1,
                title: "Short".into(),
                priority: crate::model::Priority::Medium,
                labels: vec![],
                assignee: None,
                filename: "1.md".into(),
                commit: None,
                created: "2026-01-01".into(),
                due_date: None,
                status: "todo".into(),
                category: None,
                category_color: None,
                done: false,
                cycle: None,
                milestone: None,
                blocked: None,
                children: None,
                parent: None,
                depth: 0,
                archived: false,
                related: 0,
                projects: vec![],
                epics: Vec::new(),
            },
            Card {
                health: None,
                number: 2,
                title: wrapped.into(),
                priority: crate::model::Priority::Medium,
                labels: vec![],
                assignee: None,
                filename: "2.md".into(),
                commit: None,
                created: "2026-01-01".into(),
                due_date: None,
                status: "todo".into(),
                category: None,
                category_color: None,
                done: false,
                cycle: None,
                milestone: None,
                blocked: None,
                children: None,
                parent: None,
                depth: 0,
                archived: false,
                related: 0,
                projects: vec![],
                epics: Vec::new(),
            },
            Card {
                health: None,
                number: 3,
                title: "Another long title card that also wraps".into(),
                priority: crate::model::Priority::Medium,
                labels: vec![],
                assignee: None,
                filename: "3.md".into(),
                commit: None,
                created: "2026-01-01".into(),
                due_date: None,
                status: "todo".into(),
                category: None,
                category_color: None,
                done: false,
                cycle: None,
                milestone: None,
                blocked: None,
                children: None,
                parent: None,
                depth: 0,
                archived: false,
                related: 0,
                projects: vec![],
                epics: Vec::new(),
            },
        ];
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards,
            }],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: false,
        };
        let display = BoardDisplay {
            wrap_titles: true,
            title_lines: 3,
        };
        let width = 80u16;
        let height = 30u16;
        let backend = TestBackend::new(width, height);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &None,
                    None,
                    display,
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
        let buffer = terminal.backend().buffer();

        let col_width = compute_column_rects(Rect::new(0, 0, width, height), 1)[0].width as usize;

        let mut starts: Vec<(u32, u16)> = Vec::new();
        for y in 0..height {
            let line: String = (1..width.min(24))
                .map(|x| buffer[(x, y)].symbol())
                .collect();
            for card in &board.columns[0].cards {
                if line.starts_with(&format!("#{} ", card.number))
                    && !starts.iter().any(|(n, _)| *n == card.number)
                {
                    starts.push((card.number, y));
                    break;
                }
            }
        }
        starts.sort_by_key(|(_, y)| *y);
        assert_eq!(
            starts.len(),
            3,
            "every card found in the buffer: {starts:?}"
        );
        for (idx, (number, y)) in starts.iter().enumerate() {
            let span: u16 = if idx + 1 < starts.len() {
                starts[idx + 1].1 - y
            } else {
                u16::try_from(
                    (*y..height)
                        .filter(|&rw| {
                            rw != height - 1
                                && (1..(width - 1)).any(|x| buffer[(x, rw)].symbol() != " ")
                        })
                        .count(),
                )
                .unwrap()
            };
            let card = board.columns[0]
                .cards
                .iter()
                .find(|c| c.number == *number)
                .expect("card on the board");
            let expected =
                widgets::card_line_count(card, col_width, display.wrap_titles, display.title_lines);
            assert_eq!(
                span, expected,
                "rendered height of card #{number} must match card_line_count"
            );
        }
    }

    #[test]
    fn hit_test_cards_and_column_fallback() {
        let tall = "A deliberately long card title that cannot fit on a single line inside the narrow column and wraps over several rows";
        let cards = vec![
            Card {
                health: None,
                number: 1,
                title: "one".into(),
                priority: Priority::Medium,
                labels: vec![],
                assignee: None,
                filename: "1.md".into(),
                commit: None,
                created: "2026-01-01".into(),
                due_date: None,
                status: "todo".into(),
                category: None,
                category_color: None,
                done: false,
                cycle: None,
                milestone: None,
                blocked: None,
                children: None,
                parent: None,
                depth: 0,
                archived: false,
                related: 0,
                projects: vec![],
                epics: Vec::new(),
            },
            Card {
                health: None,
                number: 2,
                title: tall.into(),
                priority: Priority::Medium,
                labels: vec![],
                assignee: None,
                filename: "2.md".into(),
                commit: None,
                created: "2026-01-02".into(),
                due_date: None,
                status: "todo".into(),
                category: None,
                category_color: None,
                done: false,
                cycle: None,
                milestone: None,
                blocked: None,
                children: None,
                parent: None,
                depth: 0,
                archived: false,
                related: 0,
                projects: vec![],
                epics: Vec::new(),
            },
        ];
        let board = BoardState {
            columns: vec![
                BoardColumn {
                    name: "todo".into(),
                    cards,
                },
                BoardColumn {
                    name: "done".into(),
                    cards: vec![Card {
                        health: None,
                        number: 3,
                        title: "three".into(),
                        priority: Priority::Medium,
                        labels: vec![],
                        assignee: None,
                        filename: "3.md".into(),
                        commit: None,
                        created: "2026-01-03".into(),
                        due_date: None,
                        status: "done".into(),
                        category: None,
                        category_color: None,
                        done: true,
                        cycle: None,
                        milestone: None,
                        blocked: None,
                        children: None,
                        parent: None,
                        depth: 0,
                        archived: false,
                        related: 0,
                        projects: vec![],
                        epics: Vec::new(),
                    }],
                },
            ],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: false,
        };
        let display = BoardDisplay::default();
        let area = Rect::new(0, 0, 80, 30);
        let widths = compute_column_rects(area, 2);
        let col0 = widths[0].width as usize;
        let card1_height = widgets::card_line_count(&board.columns[0].cards[0], col0, true, 3);

        // First card occupies a single row right below the top border.
        assert_eq!(
            board.hit_test(area, display, false, 3, 1),
            Some(HitTarget::Card { col: 0, row: 0 })
        );
        // Second (wrapping) card starts where the first one ends, row-wise.
        assert_eq!(
            board.hit_test(area, display, false, 3, 1 + card1_height),
            Some(HitTarget::Card { col: 0, row: 1 })
        );
        // Blank area below the stacked cards selects the column itself.
        assert_eq!(
            board.hit_test(area, display, false, 3, 10),
            Some(HitTarget::Column { col: 0 })
        );
        // The block border still resolves to its column.
        assert_eq!(
            board.hit_test(area, display, false, 0, 5),
            Some(HitTarget::Column { col: 0 })
        );
        // Second column, single card in the first content row.
        assert_eq!(
            board.hit_test(area, display, false, 55, 0),
            Some(HitTarget::Column { col: 1 })
        );
        assert_eq!(
            board.hit_test(area, display, false, 55, 1),
            Some(HitTarget::Card { col: 1, row: 0 })
        );
        // The block's bottom border still resolves to its column.
        assert_eq!(
            board.hit_test(area, display, false, 3, 29),
            Some(HitTarget::Column { col: 0 })
        );
    }

    #[test]
    fn hit_test_outside_area_is_none() {
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards: vec![Card {
                    health: None,
                    number: 1,
                    title: "one".into(),
                    priority: Priority::Medium,
                    labels: vec![],
                    assignee: None,
                    filename: "1.md".into(),
                    commit: None,
                    created: "2026-01-01".into(),
                    due_date: None,
                    status: "todo".into(),
                    category: None,
                    category_color: None,
                    done: false,
                    cycle: None,
                    milestone: None,
                    blocked: None,
                    children: None,
                    parent: None,
                    depth: 0,
                    archived: false,
                    related: 0,
                    projects: vec![],
                    epics: Vec::new(),
                }],
            }],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: false,
        };
        let display = BoardDisplay::default();
        let area = Rect::new(0, 5, 40, 12);
        // Above the area.
        assert_eq!(board.hit_test(area, display, false, 3, 3), None);
        // Inside the area on a card (content starts one row below the top border).
        assert_eq!(
            board.hit_test(area, display, false, 3, 6),
            Some(HitTarget::Card { col: 0, row: 0 })
        );
        // Beyond the right edge of the area.
        assert_eq!(board.hit_test(area, display, false, 44, 7), None);
    }

    #[test]
    fn hit_test_respects_status_row() {
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards: vec![Card {
                    health: None,
                    number: 1,
                    title: "one".into(),
                    priority: Priority::Medium,
                    labels: vec![],
                    assignee: None,
                    filename: "1.md".into(),
                    commit: None,
                    created: "2026-01-01".into(),
                    due_date: None,
                    status: "todo".into(),
                    category: None,
                    category_color: None,
                    done: false,
                    cycle: None,
                    milestone: None,
                    blocked: None,
                    children: None,
                    parent: None,
                    depth: 0,
                    archived: false,
                    related: 0,
                    projects: vec![],
                    epics: Vec::new(),
                }],
            }],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: false,
        };
        let display = BoardDisplay::default();
        let area = Rect::new(0, 0, 80, 30);
        // With a status message the last row belongs to the status line, not a
        // column, so it must not resolve.
        assert_eq!(board.hit_test(area, display, true, 3, 29), None);
        assert_eq!(
            board.hit_test(area, display, true, 3, 1),
            Some(HitTarget::Card { col: 0, row: 0 })
        );
    }

    #[test]
    fn hit_test_group_header_is_not_a_card() {
        let cycle_card = |number: u32, cycle: &str| Card {
            health: None,
            number,
            title: format!("task {number}"),
            priority: Priority::Medium,
            labels: vec![],
            assignee: None,
            filename: format!("{number}.md"),
            commit: None,
            created: format!("2026-01-{number:02}"),
            due_date: None,
            status: "todo".into(),
            category: None,
            category_color: None,
            done: false,
            cycle: Some(cycle.into()),
            milestone: None,
            blocked: None,
            children: None,
            parent: None,
            depth: 0,
            archived: false,
            related: 0,
            projects: vec![],
            epics: Vec::new(),
        };
        let board = BoardState {
            columns: vec![
                BoardColumn {
                    name: "todo".into(),
                    cards: vec![cycle_card(1, "alpha"), cycle_card(2, "beta")],
                },
                BoardColumn {
                    name: "done".into(),
                    cards: vec![],
                },
            ],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: Some("group:cycle".into()),
            hover: None,
            hover_col: None,
            show_mismatch: false,
        };
        let display = BoardDisplay::default();
        let area = Rect::new(0, 0, 80, 30);
        let col0 = area.width / 2;
        let first_height =
            widgets::card_line_count(&board.columns[0].cards[0], col0 as usize, true, 3);

        // Header row for the "alpha" section selects the column, not a card.
        assert_eq!(
            board.hit_test(area, display, false, 5, 1),
            Some(HitTarget::Column { col: 0 })
        );
        // The card below its header maps to its real column index.
        assert_eq!(
            board.hit_test(area, display, false, 5, 2),
            Some(HitTarget::Card { col: 0, row: 0 })
        );
        // Second section header sits below the first card's rows.
        assert_eq!(
            board.hit_test(area, display, false, 5, 2 + first_height),
            Some(HitTarget::Column { col: 0 })
        );
        assert_eq!(
            board.hit_test(area, display, false, 5, 3 + first_height),
            Some(HitTarget::Card { col: 0, row: 1 })
        );
    }

    #[test]
    fn hit_test_mismatch_column_resolves() {
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards: vec![],
            }],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![Card {
                    health: None,
                    number: 9,
                    title: "oddball".into(),
                    priority: Priority::Medium,
                    labels: vec![],
                    assignee: None,
                    filename: "9.md".into(),
                    commit: None,
                    created: "2026-01-09".into(),
                    due_date: None,
                    status: "weird".into(),
                    category: None,
                    category_color: None,
                    done: false,
                    cycle: None,
                    milestone: None,
                    blocked: None,
                    children: None,
                    parent: None,
                    depth: 0,
                    archived: false,
                    related: 0,
                    projects: vec![],
                    epics: Vec::new(),
                }],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: true,
        };
        let display = BoardDisplay::default();
        let area = Rect::new(0, 0, 90, 30);
        let mismatch_col = board.columns.len();
        // The mismatch column is the last (3rd) of the equal-width columns.
        assert_eq!(
            board.hit_test(area, display, false, 70, 1),
            Some(HitTarget::Card {
                col: mismatch_col,
                row: 0
            })
        );
    }

    #[test]
    fn render_highlights_hovered_card_without_selecting() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards: vec![
                    Card {
                        health: None,
                        number: 1,
                        title: "Alpha".into(),
                        priority: Priority::Medium,
                        labels: vec![],
                        assignee: None,
                        filename: "1.md".into(),
                        commit: None,
                        created: "2026-01-01".into(),
                        due_date: None,
                        status: "todo".into(),
                        category: None,
                        category_color: None,
                        done: false,
                        cycle: None,
                        milestone: None,
                        blocked: None,
                        children: None,
                        parent: None,
                        depth: 0,
                        archived: false,
                        related: 0,
                        projects: vec![],
                        epics: Vec::new(),
                    },
                    Card {
                        health: None,
                        number: 2,
                        title: "Beta".into(),
                        priority: Priority::Medium,
                        labels: vec![],
                        assignee: None,
                        filename: "2.md".into(),
                        commit: None,
                        created: "2026-01-02".into(),
                        due_date: None,
                        status: "todo".into(),
                        category: None,
                        category_color: None,
                        done: false,
                        cycle: None,
                        milestone: None,
                        blocked: None,
                        children: None,
                        parent: None,
                        depth: 0,
                        archived: false,
                        related: 0,
                        projects: vec![],
                        epics: Vec::new(),
                    },
                ],
            }],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            show_mismatch: false,
            active_col: 0,
            selected: 0,
            hover: Some((0, 1)),
            hover_col: Some(0),
            filter: None,
        };
        let display = BoardDisplay::default();
        let backend = TestBackend::new(80, 30);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &None,
                    None,
                    display,
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
        let buffer = terminal.backend().buffer();

        let mut rows = [None, None];
        for y in 0..30u16 {
            let line: String = (1..12).map(|x| buffer[(x, y)].symbol()).collect();
            if line.starts_with("#1") {
                rows[0] = Some(y);
            }
            if line.starts_with("#2") {
                rows[1] = Some(y);
            }
        }
        let y1 = rows[0].expect("first card rendered");
        let y2 = rows[1].expect("second card rendered");

        // The selected card keeps its selection style (dark-gray background)...
        assert_eq!(buffer[(3, y1)].style().bg, Some(Color::DarkGray));
        // ...while the hovered card is highlighted in cyan...
        assert_eq!(buffer[(3, y2)].style().fg, Some(Color::Cyan));
        // ...and hovering changed nothing about the selection.
        assert_eq!((board.active_col, board.selected), (0, 0));
    }

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

        let card = |number: u32, title: &str, status: &str| Card {
            health: None,
            number,
            title: title.into(),
            priority: Priority::Medium,
            labels: vec![],
            assignee: None,
            filename: format!("{number}.md"),
            commit: None,
            created: "2026-01-01".into(),
            due_date: None,
            status: status.into(),
            category: None,
            category_color: None,
            done: false,
            cycle: None,
            milestone: None,
            blocked: None,
            children: None,
            parent: None,
            depth: 0,
            archived: false,
            related: 0,
            projects: vec![],
            epics: Vec::new(),
        };
        let board = BoardState {
            columns: vec![
                BoardColumn {
                    name: "todo".into(),
                    cards: vec![card(1, "Alpha", "todo")],
                },
                BoardColumn {
                    name: "doing".into(),
                    cards: vec![card(2, "Beta", "doing")],
                },
            ],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            show_mismatch: false,
            active_col: 0,
            selected: 0,
            // Hovering the card in the *second* column.
            hover: Some((1, 0)),
            hover_col: Some(1),
            filter: None,
        };
        let display = BoardDisplay::default();
        let area = Rect::new(0, 0, 80, 30);
        let backend = TestBackend::new(80, 30);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &None,
                    None,
                    display,
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
        let buffer = terminal.backend().buffer();

        let chunks = compute_column_rects(area, board.total_cols());
        let hovered = chunks[1];
        let active = chunks[0];
        assert_eq!(
            buffer[(hovered.x, hovered.y)].style().fg,
            Some(Color::Blue),
            "the hovered column is outlined"
        );
        assert_eq!(
            buffer[(active.x, active.y)].style().fg,
            Some(Color::Cyan),
            "the active column keeps its own colour"
        );
    }

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

        let board = BoardState {
            columns: vec![
                BoardColumn {
                    name: "todo".into(),
                    cards: vec![],
                },
                BoardColumn {
                    name: "doing".into(),
                    cards: vec![],
                },
            ],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            show_mismatch: false,
            active_col: 0,
            selected: 0,
            hover: None,
            // The pointer is over the *empty* second column.
            hover_col: Some(1),
            filter: None,
        };
        let display = BoardDisplay::default();
        let area = Rect::new(0, 0, 80, 30);
        let backend = TestBackend::new(80, 30);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &None,
                    None,
                    display,
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
        let buffer = terminal.backend().buffer();

        let chunks = compute_column_rects(area, board.total_cols());
        assert_eq!(
            buffer[(chunks[1].x, chunks[1].y)].style().fg,
            Some(Color::Blue),
            "an empty column with no cards is still outlined when hovered"
        );
        assert_eq!(
            buffer[(chunks[0].x, chunks[0].y)].style().fg,
            Some(Color::Cyan),
            "the active column keeps its own colour"
        );
    }

    #[test]
    fn total_cols_includes_mismatch() {
        let board = BoardState {
            columns: vec![
                BoardColumn {
                    name: "a".into(),
                    cards: vec![],
                },
                BoardColumn {
                    name: "b".into(),
                    cards: vec![],
                },
            ],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        assert_eq!(board.total_cols(), 3);
    }

    #[test]
    fn column_name_mismatch_index() {
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards: vec![],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        assert_eq!(board.column_name(0), "todo");
        assert_eq!(board.column_name(1), "Mismatched");
    }

    #[test]
    fn move_left_wraps_around() {
        let mut board = BoardState {
            columns: vec![
                BoardColumn {
                    name: "a".into(),
                    cards: vec![],
                },
                BoardColumn {
                    name: "b".into(),
                    cards: vec![],
                },
            ],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: true,
        };
        board.move_left();
        assert_eq!(board.active_col, 1);
    }

    #[test]
    fn move_right_wraps_around() {
        let mut board = BoardState {
            columns: vec![
                BoardColumn {
                    name: "a".into(),
                    cards: vec![],
                },
                BoardColumn {
                    name: "b".into(),
                    cards: vec![],
                },
            ],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 2,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        board.move_right();
        assert_eq!(board.active_col, 0);
    }

    #[test]
    fn clamp_selection_empty_column() {
        let mut board = BoardState {
            columns: vec![BoardColumn {
                name: "a".into(),
                cards: vec![],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 5,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        board.clamp_selection();
        assert_eq!(board.selected, 0);
    }

    #[test]
    fn clamp_selection_single_card() {
        let mut board = BoardState {
            columns: vec![BoardColumn {
                name: "a".into(),
                cards: vec![Card {
                    health: None,
                    number: 1,
                    title: "X".into(),
                    priority: crate::model::Priority::Medium,
                    labels: vec![],
                    assignee: None,
                    filename: "x.md".into(),
                    commit: None,
                    created: "2026-01-01".into(),
                    due_date: None,
                    status: "todo".into(),
                    category: None,
                    category_color: None,
                    done: false,
                    cycle: None,
                    milestone: None,
                    blocked: None,
                    children: None,
                    parent: None,
                    depth: 0,
                    archived: false,
                    related: 0,
                    projects: vec![],
                    epics: Vec::new(),
                }],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 5,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        board.clamp_selection();
        assert_eq!(board.selected, 0);
    }

    #[test]
    fn move_up_clamps_at_top() {
        let mut board = BoardState {
            columns: vec![BoardColumn {
                name: "a".into(),
                cards: vec![Card {
                    health: None,
                    number: 1,
                    title: "X".into(),
                    priority: crate::model::Priority::Medium,
                    labels: vec![],
                    assignee: None,
                    filename: "x.md".into(),
                    commit: None,
                    created: "2026-01-01".into(),
                    due_date: None,
                    status: "todo".into(),
                    category: None,
                    category_color: None,
                    done: false,
                    cycle: None,
                    milestone: None,
                    blocked: None,
                    children: None,
                    parent: None,
                    depth: 0,
                    archived: false,
                    related: 0,
                    projects: vec![],
                    epics: Vec::new(),
                }],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        board.move_up();
        assert_eq!(board.selected, 0);
    }

    #[test]
    fn move_down_clamps_at_bottom() {
        let mut board = BoardState {
            columns: vec![BoardColumn {
                name: "a".into(),
                cards: vec![Card {
                    health: None,
                    number: 1,
                    title: "X".into(),
                    priority: crate::model::Priority::Medium,
                    labels: vec![],
                    assignee: None,
                    filename: "x.md".into(),
                    commit: None,
                    created: "2026-01-01".into(),
                    due_date: None,
                    status: "todo".into(),
                    category: None,
                    category_color: None,
                    done: false,
                    cycle: None,
                    milestone: None,
                    blocked: None,
                    children: None,
                    parent: None,
                    depth: 0,
                    archived: false,
                    related: 0,
                    projects: vec![],
                    epics: Vec::new(),
                }],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        board.move_down();
        assert_eq!(board.selected, 0);
    }

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

        let backend = TestBackend::new(5, 3);
        let mut terminal = Terminal::new(backend).unwrap();
        let board = BoardState {
            columns: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &None,
                    None,
                    BoardDisplay::default(),
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
    }

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

        let backend = TestBackend::new(80, 24);
        let mut terminal = Terminal::new(backend).unwrap();
        let board = BoardState {
            columns: vec![
                BoardColumn {
                    name: "todo".into(),
                    cards: vec![],
                },
                BoardColumn {
                    name: "done".into(),
                    cards: vec![],
                },
            ],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &Some("test msg".into()),
                    None,
                    BoardDisplay::default(),
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
    }

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

        let title = "This is a deliberately long card title that will not fit on a single line inside the column and must wrap more than once";
        let card = crate::ui::board::Card {
            health: None,
            number: 7,
            title: title.into(),
            priority: crate::model::Priority::Medium,
            labels: vec![],
            assignee: None,
            filename: "x.md".into(),
            commit: None,
            created: "2026-01-01".into(),
            due_date: None,
            status: "todo".into(),
            category: None,
            category_color: None,
            done: false,
            cycle: None,
            milestone: None,
            blocked: None,
            children: None,
            parent: None,
            depth: 0,
            archived: false,
            related: 0,
            projects: vec![],
            epics: Vec::new(),
        };
        let backend = TestBackend::new(80, 24);
        let mut terminal = Terminal::new(backend).unwrap();
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards: vec![card],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: false,
        };
        let display = BoardDisplay {
            wrap_titles: true,
            title_lines: 3,
        };
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &None,
                    None,
                    display,
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
        let buffer = terminal.backend().buffer();

        // The card is the only item in the only column; its block top border
        // sits on y=0, so the ListItem starts at y=1 and each wrapped line
        // must carry the selected-card highlight (DarkGray bg + BOLD).
        let mut highlighted = 0;
        for y in 1..buffer.area().height - 1 {
            let cell = &buffer[(2, y)];
            if cell.bg != Color::DarkGray {
                break;
            }
            assert!(
                cell.modifier.contains(Modifier::BOLD),
                "highlighted continuation line must stay bold: {cell:?}"
            );
            highlighted += 1;
        }
        assert!(
            highlighted >= 2,
            "wrapped card highlights every line, got {highlighted}"
        );
        assert!(
            highlighted <= display.title_lines,
            "highlight never exceeds the line limit: {highlighted}"
        );
    }

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

        let backend = TestBackend::new(80, 24);
        let mut terminal = Terminal::new(backend).unwrap();
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards: vec![
                    Card {
                        health: None,
                        number: 1,
                        title: "A".into(),
                        priority: crate::model::Priority::Medium,
                        labels: vec![],
                        assignee: None,
                        filename: "a.md".into(),
                        commit: None,
                        created: "2026-01-01".into(),
                        due_date: None,
                        status: "todo".into(),
                        category: None,
                        category_color: None,
                        done: false,
                        cycle: Some("Cycle 1".into()),
                        milestone: None,
                        blocked: None,
                        children: None,
                        parent: None,
                        depth: 0,
                        archived: false,
                        related: 0,
                        projects: vec![],
                        epics: Vec::new(),
                    },
                    Card {
                        health: None,
                        number: 2,
                        title: "B".into(),
                        priority: crate::model::Priority::Medium,
                        labels: vec![],
                        assignee: None,
                        filename: "b.md".into(),
                        commit: None,
                        created: "2026-01-01".into(),
                        due_date: None,
                        status: "todo".into(),
                        category: None,
                        category_color: None,
                        done: true,
                        cycle: Some("Cycle 1".into()),
                        milestone: None,
                        blocked: None,
                        children: None,
                        parent: None,
                        depth: 0,
                        archived: false,
                        related: 0,
                        projects: vec![],
                        epics: Vec::new(),
                    },
                    Card {
                        health: None,
                        number: 3,
                        title: "C".into(),
                        priority: crate::model::Priority::Medium,
                        labels: vec![],
                        assignee: None,
                        filename: "c.md".into(),
                        commit: None,
                        created: "2026-01-01".into(),
                        due_date: None,
                        status: "todo".into(),
                        category: None,
                        category_color: None,
                        done: false,
                        cycle: Some("Cycle 2".into()),
                        milestone: None,
                        blocked: None,
                        children: None,
                        parent: None,
                        depth: 0,
                        archived: false,
                        related: 0,
                        projects: vec![],
                        epics: Vec::new(),
                    },
                ],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: Some("group:cycle".into()),
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: false,
        };
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &None,
                    None,
                    BoardDisplay::default(),
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();

        let buffer = terminal.backend().buffer();
        let mut lines = Vec::new();
        for y in 0..buffer.area.height {
            let line = (0..buffer.area.width)
                .map(|x| buffer[(x, y)].symbol())
                .collect::<String>();
            lines.push(line);
        }
        let rendered = lines.join("\n");
        assert!(rendered.contains("-- cycle: Cycle 1 (1/2 done, 50%) --"));
        assert!(rendered.contains("-- cycle: Cycle 2 (0/1 done, 0%) --"));
    }

    #[test]
    fn build_filtered_keeps_only_fuzzy_matches() {
        use crate::model::Issue;
        use crate::search::Corpus;

        let to_issue = |number: u32, title: &str| Issue {
            projects: None,
            id: None,
            number,
            title: title.to_string(),
            status: crate::model::Status::new("todo"),
            labels: vec![],
            priority: crate::model::Priority::Medium,
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: format!("2026-01-01-{number}.md"),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            time_entries: vec![],
            parent: None,
            series: None,
            health: None,
            epics: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        let corpus = Corpus::with_texts(
            vec![to_issue(1, "Fix login bug"), to_issue(2, "Polish exports")],
            vec!["Fix login bug".to_string(), "Polish exports".to_string()],
        );
        let config = Config::default();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let board_config = config.default_config();

        let board = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "log",
            &StructuredFilter::default(),
            &resolution,
        );
        assert_eq!(board.columns.len(), board_config.columns.len());
        assert_eq!(board.column_cards(0).len(), 1);
        assert_eq!(board.column_cards(0)[0].title, "Fix login bug");
        assert_eq!(board.filter.as_deref(), Some("log"));

        let none = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "zzw",
            &StructuredFilter::default(),
            &resolution,
        );
        assert!(none.is_empty());

        let empty = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "",
            &StructuredFilter::default(),
            &resolution,
        );
        assert_eq!(empty.column_cards(0).len(), 2, "empty query keeps all");
        assert!(empty.filter.is_some());
    }

    #[test]
    fn build_filtered_group_cycle_keeps_original_titles() {
        use crate::model::Issue;
        use crate::search::Corpus;

        let issue = |number: u32, title: &str, status: &str, cycles: &[&str]| Issue {
            projects: None,
            id: None,
            number,
            title: title.to_string(),
            status: crate::model::Status::new(status),
            labels: vec![],
            priority: crate::model::Priority::Medium,
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: Some(cycles.iter().map(|c| (*c).to_string()).collect()),
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: format!("2026-01-01-{number}.md"),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            time_entries: vec![],
            parent: None,
            series: None,
            health: None,
            epics: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };

        let corpus = Corpus::with_texts(
            vec![
                issue(1, "A", "todo", &["Cycle 1"]),
                issue(2, "B", "done", &["Cycle 1"]),
                issue(3, "C", "todo", &["Cycle 2"]),
            ],
            vec![
                "cycle: Cycle 1\nstatus: todo".to_string(),
                "cycle: Cycle 1\nstatus: done".to_string(),
                "cycle: Cycle 2\nstatus: todo".to_string(),
            ],
        );

        let config = Config::default();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "group:cycle",
            &StructuredFilter::default(),
            &resolution,
        );
        let titles: Vec<String> = board
            .columns
            .iter()
            .flat_map(|col| col.cards.iter().map(|c| c.title.clone()))
            .collect();
        assert!(titles.iter().any(|t| t == "A"));
        assert!(titles.iter().any(|t| t == "B"));
        assert!(titles.iter().any(|t| t == "C"));
    }

    /// A config declaring `p-1`/`Platform` and `p-2`/`Infra`, and a corpus of four
    /// issues: one per project, one in both, one in none (WP06 T028).
    fn project_fixture() -> (Config, crate::search::Corpus) {
        use crate::config::ProjectConfiguration;
        use crate::model::Issue;
        use crate::search::Corpus;

        let issue = |number: u32, title: &str, projects: &[&str]| Issue {
            projects: if projects.is_empty() {
                None
            } else {
                Some(projects.iter().map(|p| (*p).to_string()).collect())
            },
            id: None,
            number,
            title: title.to_string(),
            status: crate::model::Status::new("todo"),
            labels: vec![],
            priority: crate::model::Priority::Medium,
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: format!("2026-01-01-{number}.md"),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            time_entries: vec![],
            parent: None,
            series: None,
            health: None,
            epics: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };

        let issues = vec![
            issue(1, "Platform work", &["p-1"]),
            issue(2, "Infra work", &["p-2"]),
            issue(3, "Spans both", &["p-1", "p-2"]),
            issue(4, "Homeless", &[]),
        ];
        let texts: Vec<String> = issues.iter().map(Issue::frontmatter).collect();
        let corpus = Corpus::with_texts(issues, texts);

        let mut config = Config::default();
        for (id, name) in [("p-1", "Platform"), ("p-2", "Infra")] {
            config.projects.insert(
                id.to_string(),
                ProjectConfiguration {
                    name: name.to_string(),
                    ..ProjectConfiguration::default()
                },
            );
        }
        (config, corpus)
    }

    /// The epic analogue of [`project_fixture`]: two registered epics and four
    /// issues spanning them, the fixture the T030 tests read. Built from parsed
    /// frontmatter so the fixture exercises the model's own reader.
    fn epic_fixture() -> (Config, crate::search::Corpus) {
        use crate::config::EpicConfiguration;
        use crate::model::Issue;
        use crate::search::Corpus;

        let make = |number: u32, title: &str, epics: &[&str]| {
            let list = if epics.is_empty() {
                String::new()
            } else {
                let ids = epics
                    .iter()
                    .map(|id| format!("\"{id}\""))
                    .collect::<Vec<_>>()
                    .join(", ");
                format!("epics: [{ids}]\n")
            };
            let text = format!(
                "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: todo\nlabels: []\n\
                 priority: medium\n{list}created: 2026-01-01\nupdated: 2026-01-01\n---\n\nBody."
            );
            (Issue::parse(&text).unwrap(), text)
        };
        let (i1, t1) = make(1, "Alpha work", &["e-aaa111"]);
        let (i2, t2) = make(2, "Beta work", &["e-bbb222"]);
        let (i3, t3) = make(3, "Spans both", &["e-aaa111", "e-bbb222"]);
        let (i4, t4) = make(4, "Homeless", &[]);
        let corpus = Corpus::with_texts(vec![i1, i2, i3, i4], vec![t1, t2, t3, t4]);

        let mut config = Config::default();
        for (id, name) in [("e-aaa111", "Alpha"), ("e-bbb222", "Beta")] {
            config.epics.insert(
                id.to_string(),
                EpicConfiguration {
                    name: name.to_string(),
                    ..EpicConfiguration::default()
                },
            );
        }
        (config, corpus)
    }

    /// Draw a board and return the frame as text, for the tests that read what the
    /// grouped board actually prints.
    fn epic_board_text(board: &BoardState, width: u16, height: u16) -> String {
        use ratatui::backend::TestBackend;
        let display = BoardDisplay {
            wrap_titles: true,
            title_lines: 3,
        };
        let backend = TestBackend::new(width, height);
        let mut terminal = ratatui::Terminal::new(backend).unwrap();
        terminal
            .draw(|f| {
                render(
                    board,
                    f,
                    f.area(),
                    &None,
                    None,
                    display,
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
        let buffer = terminal.backend().buffer();
        (0..height)
            .map(|y| {
                (0..width)
                    .map(|x| buffer[(x, y)].symbol())
                    .collect::<String>()
            })
            .collect::<Vec<_>>()
            .join("\n")
    }

    #[test]
    fn t030_the_board_partitions_by_epic_with_a_labelled_no_epic_bucket() {
        let (config, corpus) = epic_fixture();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        // `sort:epic` is what the sort derivation supplies when only `group:` is
        // typed; naming both here pins the documented spelling.
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "group:epic sort:epic",
            &StructuredFilter::default(),
            &resolution,
        );

        let cards = &board.columns[0].cards;
        let titles: Vec<&str> = cards.iter().map(|c| c.title.as_str()).collect();
        assert_eq!(
            titles,
            vec!["Alpha work", "Beta work", "Spans both", "Homeless"],
            "declaration order, then the multi-epic bucket, then no-epic last"
        );

        let sections = BoardState::group_sections(cards, Some("epic"))
            .expect("group:epic must produce sections");
        let names: Vec<&str> = sections.iter().map(|s| s.name.as_str()).collect();
        assert_eq!(
            names,
            vec!["e-aaa111", "e-bbb222", "(multiple epics)", "(no epic)"],
            "one bucket per epic in declaration order, then multi, then the \
             labelled no-epic bucket last"
        );

        // The header the renderer draws names the epic's **id**, so a user can act
        // on it from the board (T030 step 4).
        let footer = BoardState::group_footer(cards, Some("epic")).expect("a footer");
        assert!(footer.contains("e-aaa111 0/1 0%"), "got {footer:?}");
        assert!(footer.contains("(no epic) 0/1 0%"), "got {footer:?}");
    }

    #[test]
    fn t030_an_unresolved_epic_reference_is_diagnosed_not_a_bucket() {
        use crate::model::Issue;
        use crate::search::Corpus;

        // One issue whose only reference names an epic the registry does not hold
        // (`tix epic delete` removes the registry entry and retains the reference).
        let text = "---\nnumber: 1\ntitle: Stale\nstatus: todo\nlabels: []\npriority: medium\nepics:\n- e-gone\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\nBody.";
        let issue = Issue::parse(text).unwrap();
        let corpus = Corpus::with_texts(vec![issue], vec![text.to_string()]);
        let (config, _) = epic_fixture();
        let (_, resolution) = crate::workflow::active_resolution(&config);

        // The **filter** finds it: the id as stored is the handle `tix epic remove
        // <stale-id>` takes, so a dangling reference must stay reachable.
        let filter = StructuredFilter {
            epic: Some("e-gone".to_string()),
            ..StructuredFilter::default()
        };
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "",
            &filter,
            &resolution,
        );
        assert_eq!(
            board.columns[0].cards.len(),
            1,
            "a stored reference to a deleted epic must still be findable"
        );

        // The **partition** does not invent a bucket for it: this issue is in no
        // *epic*, so it lands in the labelled no-epic bucket.
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "group:epic sort:epic",
            &StructuredFilter::default(),
            &resolution,
        );
        assert_eq!(
            board.columns[0].cards[0].epics,
            [] as [std::string::String; 0]
        );
        let sections = BoardState::group_sections(&board.columns[0].cards, Some("epic"))
            .expect("group:epic must produce sections");
        let names: Vec<&str> = sections.iter().map(|s| s.name.as_str()).collect();
        assert_eq!(
            names,
            vec!["(no epic)"],
            "an unresolvable id is not a bucket"
        );
    }

    #[test]
    fn t030_the_epic_filter_narrows_the_board_to_the_members() {
        let (config, corpus) = epic_fixture();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let members = |id: &str| {
            let filter = StructuredFilter {
                epic: Some(id.to_string()),
                ..StructuredFilter::default()
            };
            let board = BoardState::build_filtered(
                config.default_config(),
                &config,
                &corpus,
                "",
                &filter,
                &resolution,
            );
            let mut titles: Vec<String> = board.columns[0]
                .cards
                .iter()
                .map(|c| c.title.clone())
                .collect();
            titles.sort();
            titles
        };
        assert_eq!(
            members("e-aaa111"),
            vec!["Alpha work", "Spans both"],
            "a member matches and an issue in two epics matches both"
        );
        assert_eq!(members("e-bbb222"), vec!["Beta work", "Spans both"]);
        // An id no reference carries matches nothing, and neither does one the
        // registry does not know.
        for unknown in ["e-ccc333", "e-does-not-exist"] {
            let filter = StructuredFilter {
                epic: Some(unknown.to_string()),
                ..StructuredFilter::default()
            };
            let board = BoardState::build_filtered(
                config.default_config(),
                &config,
                &corpus,
                "",
                &filter,
                &resolution,
            );
            assert!(board.is_empty(), "epic:{unknown} must match nothing");
        }
    }

    #[test]
    fn t030_a_grouped_board_still_opens_the_member_issue_directly() {
        // FR-004: the epic is the section label, never a layer between the cursor
        // and the issue. The selected card is a real issue, and the drawn board
        // states the direct route rather than implying it.
        let (config, corpus) = epic_fixture();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let mut board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "group:epic sort:epic",
            &StructuredFilter::default(),
            &resolution,
        );
        board.selected = 2;
        let selected = board.get_selected_card().expect("a card under the cursor");
        assert_eq!(
            selected.number, 3,
            "the cursor addresses the issue itself, not an epic"
        );
        let text = epic_board_text(&board, 140, 40);
        assert!(text.contains("-- epic: e-aaa111"), "got {text:?}");
        let footer = BoardState::group_footer(&board.columns[0].cards, Some("epic"))
            .expect("a grouped board has a footer");
        assert!(
            footer.contains(GROUP_OPEN_AFFORDANCE),
            "the grouped board advertises the direct issue route: {footer:?}"
        );
    }

    #[test]
    fn t028_the_board_partitions_by_project_with_a_labelled_no_project_bucket() {
        let (config, corpus) = project_fixture();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        // `sort:project` is what the sort derivation supplies when only `group:` is
        // typed; naming both here pins the documented spelling.
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "group:project sort:project",
            &StructuredFilter::default(),
            &resolution,
        );

        let cards = &board.columns[0].cards;
        let titles: Vec<&str> = cards.iter().map(|c| c.title.as_str()).collect();
        assert_eq!(
            titles,
            vec!["Platform work", "Infra work", "Spans both", "Homeless"],
            "declaration order, then the multi-project bucket, then no-project last"
        );

        let sections = BoardState::group_sections(cards, Some("project"))
            .expect("group:project must produce sections");
        let names: Vec<&str> = sections.iter().map(|s| s.name.as_str()).collect();
        assert_eq!(
            names,
            vec!["p-1", "p-2", "(multiple projects)", "(no project)"],
            "one bucket per project in declaration order, then multi, then the \
             labelled no-project bucket last"
        );

        // The header the renderer draws names the bucket, so the id is actionable
        // from the board (T028 step 4).
        let footer = BoardState::group_footer(cards, Some("project")).expect("a footer");
        assert!(footer.contains("p-1 0/1 0%"), "got {footer:?}");
        assert!(footer.contains("(no project) 0/1 0%"), "got {footer:?}");
    }

    #[test]
    fn t028_an_unresolved_association_is_diagnosed_not_a_bucket() {
        use crate::model::Issue;
        use crate::search::Corpus;

        // One issue whose only association names a project the registry does not hold
        // (`tix project delete` removes the registry entry and retains the reference).
        let text = "---\nnumber: 1\ntitle: Stale\nstatus: todo\nlabels: []\npriority: medium\nprojects:\n- p-gone\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\nBody.";
        let issue = Issue::parse(text).unwrap();
        let corpus = Corpus::with_texts(vec![issue], vec![text.to_string()]);
        let (config, _) = project_fixture();
        let (_, resolution) = crate::workflow::active_resolution(&config);

        // The **filter** finds it: the id as stored is the handle
        // `tix project remove <stale-id>` takes, so a dangling reference must stay
        // reachable (WP06 review item 4).
        let filter = StructuredFilter {
            project: Some("p-gone".to_string()),
            ..StructuredFilter::default()
        };
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "",
            &filter,
            &resolution,
        );
        assert_eq!(
            board.columns[0].cards.len(),
            1,
            "a stored reference to a deleted project must still be findable"
        );

        // The **partition** does not invent a bucket for it: this issue is in no
        // *project*, so it lands in the labelled no-project bucket, and the card
        // carries no resolved id.
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "group:project sort:project",
            &StructuredFilter::default(),
            &resolution,
        );
        assert_eq!(
            board.columns[0].cards[0].projects,
            [] as [std::string::String; 0]
        );
        let sections = BoardState::group_sections(&board.columns[0].cards, Some("project"))
            .expect("group:project must produce sections");
        let names: Vec<&str> = sections.iter().map(|s| s.name.as_str()).collect();
        assert_eq!(
            names,
            vec!["(no project)"],
            "an unresolvable id is diagnosed, not a bucket"
        );
    }

    #[test]
    fn t028_the_project_filter_narrows_the_board_to_the_members() {
        let (config, corpus) = project_fixture();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let filter = StructuredFilter {
            project: Some("p-1".to_string()),
            ..StructuredFilter::default()
        };
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "",
            &filter,
            &resolution,
        );
        let titles: Vec<&str> = board.columns[0]
            .cards
            .iter()
            .map(|c| c.title.as_str())
            .collect();
        assert_eq!(
            titles,
            vec!["Platform work", "Spans both"],
            "a member matches and an issue in two projects matches both — so the \
             multi-project issue is visible under either project"
        );

        // The same criterion set on the other project returns the other member.
        let other = StructuredFilter {
            project: Some("p-2".to_string()),
            ..StructuredFilter::default()
        };
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "",
            &other,
            &resolution,
        );
        let titles: Vec<&str> = board.columns[0]
            .cards
            .iter()
            .map(|c| c.title.as_str())
            .collect();
        assert_eq!(titles, vec!["Infra work", "Spans both"]);

        // An id no association carries matches nothing, and neither does one the
        // registry does not know.
        for unknown in ["p-3", "p-does-not-exist"] {
            let filter = StructuredFilter {
                project: Some(unknown.to_string()),
                ..StructuredFilter::default()
            };
            let board = BoardState::build_filtered(
                config.default_config(),
                &config,
                &corpus,
                "",
                &filter,
                &resolution,
            );
            assert!(
                board.is_empty(),
                "project:{unknown} must match nothing, got cards"
            );
        }
    }

    #[test]
    fn group_footer_reports_done_progress() {
        let cards = vec![
            Card {
                health: None,
                number: 1,
                title: "A".into(),
                priority: crate::model::Priority::Medium,
                labels: vec![],
                assignee: None,
                filename: "a.md".into(),
                commit: None,
                created: "2026-01-01".into(),
                due_date: None,
                status: "todo".into(),
                category: None,
                category_color: None,
                done: false,
                cycle: Some("Cycle 1".into()),
                milestone: None,
                blocked: None,
                children: None,
                parent: None,
                depth: 0,
                archived: false,
                related: 0,
                projects: vec![],
                epics: Vec::new(),
            },
            Card {
                health: None,
                number: 2,
                title: "B".into(),
                priority: crate::model::Priority::Medium,
                labels: vec![],
                assignee: None,
                filename: "b.md".into(),
                commit: None,
                created: "2026-01-01".into(),
                due_date: None,
                status: "done".into(),
                category: None,
                category_color: None,
                done: true,
                cycle: Some("Cycle 1".into()),
                milestone: None,
                blocked: None,
                children: None,
                parent: None,
                depth: 0,
                archived: false,
                related: 0,
                projects: vec![],
                epics: Vec::new(),
            },
        ];
        let text = BoardState::group_footer(&cards, Some("cycle")).unwrap();
        assert!(text.contains("Cycle 1 1/2 50%"));
    }

    #[test]
    fn build_filtered_bare_number_matches_exact_issue_only() {
        use crate::model::Issue;
        use crate::search::Corpus;

        let to_issue = |number: u32, title: &str, status: &str| Issue {
            projects: None,
            id: None,
            number,
            title: title.to_string(),
            status: crate::model::Status::new(status),
            labels: vec![],
            priority: crate::model::Priority::Medium,
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: format!("2026-01-01-{number}.md"),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            time_entries: vec![],
            parent: None,
            series: None,
            health: None,
            epics: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        let corpus = Corpus::with_texts(
            vec![
                to_issue(55, "Concrete target", "todo"),
                to_issue(155, "Digit-rich title", "todo"),
                to_issue(3, "Login bug", "todo"),
            ],
            vec![
                "Concrete target".to_string(),
                "Digit-rich title".to_string(),
                "Login bug".to_string(),
            ],
        );
        let config = Config::default();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let board_config = config.default_config();

        let exact = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "55",
            &StructuredFilter::default(),
            &resolution,
        );
        assert_eq!(exact.column_cards(0).len(), 1, "only issue 55 matches");
        assert_eq!(exact.column_cards(0)[0].title, "Concrete target");
        assert_eq!(
            exact.column_cards(0)[0].number,
            55,
            "issue 155's digit sequence must not qualify"
        );
        assert_eq!(exact.filter.as_deref(), Some("55"));

        // Number miss -> empty board.
        let miss = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "999",
            &StructuredFilter::default(),
            &resolution,
        );
        assert!(miss.is_empty(), "no issue 999 => zero matches");

        // Non-numeric query keeps fuzzy behavior (login finds issue 3 only).
        let fuzzy = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "login",
            &StructuredFilter::default(),
            &resolution,
        );
        assert_eq!(fuzzy.column_cards(0).len(), 1);
        assert_eq!(fuzzy.column_cards(0)[0].title, "Login bug");
    }

    #[test]
    fn build_filtered_mixed_query_keeps_fuzzy_not_number() {
        use crate::model::Issue;
        use crate::search::Corpus;

        let to_issue = |number: u32, title: &str| Issue {
            projects: None,
            id: None,
            number,
            title: title.to_string(),
            status: crate::model::Status::new("todo"),
            labels: vec![],
            priority: crate::model::Priority::Medium,
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: format!("2026-01-01-{number}.md"),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            time_entries: vec![],
            parent: None,
            series: None,
            health: None,
            epics: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        let corpus = Corpus::with_texts(
            vec![
                to_issue(55, "Concrete target"),
                to_issue(155, "Digit-rich title"),
            ],
            vec![
                "Concrete target".to_string(),
                "Digit-rich title".to_string(),
            ],
        );
        let config = Config::default();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let board_config = config.default_config();

        // "55bug" is not a bare number: fuzzy path applies (no such text, so
        // zero matches rather than exact issue 55).
        let mixed = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "55bug",
            &StructuredFilter::default(),
            &resolution,
        );
        assert!(mixed.is_empty(), "mixed query is not an exact-number query");
    }

    #[test]
    fn build_filtered_number_composes_with_structured_filter_and() {
        use crate::model::Issue;
        use crate::search::Corpus;

        let cases = [
            (55u32, "Issue 55 todo", "todo"),
            (156u32, "Issue 156 todo", "todo"),
            (57u32, "Issue 57 done", "done"),
        ];
        let corpus = Corpus::with_texts(
            cases
                .iter()
                .map(|&(number, title, status)| Issue {
                    projects: None,
                    id: None,
                    number,
                    title: title.to_string(),
                    status: crate::model::Status::new(status),
                    labels: vec![],
                    priority: crate::model::Priority::Medium,
                    assignee: None,
                    estimate: None,
                    commit: None,
                    gitlab_id: None,
                    linear_id: None,
                    mission: None,
                    task: None,
                    relationships: vec![],
                    related_issues: vec![],
                    files: vec![],
                    cycles: None,
                    milestones: None,
                    reviewer: None,
                    start_date: None,
                    due_date: None,
                    created: "2026-01-01".into(),
                    type_: None,
                    updated: "2026-01-01".into(),
                    filename: format!("2026-01-01-{}.md", number),
                    body: String::new(),
                    history: crate::model::History::new(),
                    has_retired_links_key: false,
                    time_entries: vec![],
                    parent: None,
                    series: None,
                    health: None,
                    epics: None,
                    extra_frontmatter: std::collections::BTreeMap::new(),
                    archived: false,
                    entered_at: None,
                    source: None,
                })
                .collect(),
            cases
                .iter()
                .map(|(_, title, _)| title.to_string())
                .collect(),
        );
        let config = Config::default();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let board_config = config.default_config();
        let status_todo = StructuredFilter {
            status: Some("todo".to_string()),
            ..Default::default()
        };
        let status_done = StructuredFilter {
            status: Some("done".to_string()),
            ..Default::default()
        };

        // AND holds on the positive side: 55 must match number AND todo;
        // 156 matches the criteria but is dropped by the number gate.
        let matches = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "55",
            &status_todo,
            &resolution,
        );
        assert_eq!(matches.column_cards(0).len(), 1);
        assert_eq!(matches.column_cards(0)[0].title, "Issue 55 todo");

        // Requirement scenario: number matches but the criterion fails
        // (issue 55 is "todo" here) => board shows nothing.
        let done_criteria = BoardState::build_filtered(
            board_config,
            &config,
            &corpus,
            "55",
            &status_done,
            &resolution,
        );
        assert!(done_criteria.is_empty(), "criteria failure hides issue 55");
    }

    #[test]
    fn is_empty_true_only_with_no_cards_anywhere() {
        let board = BoardState {
            columns: vec![BoardColumn {
                name: "a".into(),
                cards: vec![],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        assert!(board.is_empty());

        let populated = BoardState {
            columns: vec![BoardColumn {
                name: "a".into(),
                cards: vec![Card {
                    health: None,
                    number: 1,
                    title: "X".into(),
                    priority: crate::model::Priority::Medium,
                    labels: vec![],
                    assignee: None,
                    filename: "x.md".into(),
                    commit: None,
                    created: "2026-01-01".into(),
                    due_date: None,
                    status: "todo".into(),
                    category: None,
                    category_color: None,
                    done: false,
                    cycle: None,
                    milestone: None,
                    blocked: None,
                    children: None,
                    parent: None,
                    depth: 0,
                    archived: false,
                    related: 0,
                    projects: vec![],
                    epics: Vec::new(),
                }],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            hidden: vec![],
            show_mismatch: true,
        };
        assert!(!populated.is_empty());
    }

    #[test]
    fn build_splits_hidden_columns_out_of_visible_surface() {
        use crate::config::{BoardConfiguration, Config};

        let mut config = Config::default();
        config.kanban.configurations.insert(
            "default".to_string(),
            BoardConfiguration {
                columns: vec!["todo".into(), "done".into()],
                hidden_columns: vec!["done".into()],
                ..BoardConfiguration::default()
            },
        );
        let store = crate::storage::Store::open(&config).unwrap();
        let board = BoardState::build(&store, config.default_config());
        assert_eq!(board.columns.len(), 1);
        assert_eq!(board.columns[0].name, "todo");
        assert_eq!(board.hidden.len(), 1);
        assert_eq!(board.hidden[0].name, "done");
        assert_eq!(board.total_cols(), 1);
    }

    #[test]
    fn move_left_skips_hidden_column() {
        let mut board = BoardState {
            columns: vec![BoardColumn {
                name: "visible-a".into(),
                cards: vec![],
            }],
            hidden: vec![BoardColumn {
                name: "hidden-b".into(),
                cards: vec![],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: true,
        };
        board.move_left();
        assert_eq!(board.active_col, 0, "single visible column wraps to itself");
    }

    #[test]
    fn move_right_skips_hidden_column() {
        let mut board = BoardState {
            columns: vec![BoardColumn {
                name: "visible-a".into(),
                cards: vec![],
            }],
            hidden: vec![BoardColumn {
                name: "hidden-b".into(),
                cards: vec![],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: true,
        };
        board.move_right();
        assert_eq!(board.active_col, 0, "single visible column wraps to itself");
    }

    #[test]
    fn all_columns_hidden_board_is_displayable_and_navigation_safe() {
        let mut board = BoardState {
            columns: vec![],
            hidden: vec![BoardColumn {
                name: "only-hidden".into(),
                cards: vec![],
            }],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: false,
        };
        assert_eq!(board.total_cols(), 0);
        board.move_left();
        board.move_right();
        assert_eq!(board.active_col, 0, "zero-column board must not panic");
        let board2 = BoardState {
            columns: vec![],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: false,
        };
        assert_eq!(board2.total_cols(), 0);
    }

    fn write_issue_md(
        dir: &std::path::Path,
        name: &str,
        number: u32,
        title: &str,
        status: &str,
        created: &str,
    ) {
        let contents = format!(
            "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"{status}\"\nlabels: []\npriority: \"medium\"\ncreated: \"{created}\"\nupdated: \"{created}\"\n---\n\nBody text."
        );
        std::fs::write(dir.join(name), contents).unwrap();
    }

    #[test]
    fn order_by_sort_desc_asc_none() {
        let mk = |created: &str| Card {
            health: None,
            number: 1,
            title: created.to_string(),
            priority: crate::model::Priority::Medium,
            labels: vec![],
            assignee: None,
            filename: "x.md".into(),
            commit: None,
            created: created.to_string(),
            due_date: None,
            status: "todo".into(),
            category: None,
            category_color: None,
            done: false,
            cycle: None,
            milestone: None,
            blocked: None,
            children: None,
            parent: None,
            depth: 0,
            archived: false,
            related: 0,
            projects: vec![],
            epics: Vec::new(),
        };
        let dates =
            |cards: &[Card]| -> Vec<String> { cards.iter().map(|c| c.created.clone()).collect() };

        let mut cards = vec![mk("2026-01-01"), mk("2026-03-01"), mk("2026-02-01")];
        crate::config::OrderBy::CreatedAtDesc.sort(&mut cards);
        assert_eq!(dates(&cards), ["2026-03-01", "2026-02-01", "2026-01-01"]);

        let mut cards = vec![mk("2026-01-01"), mk("2026-03-01"), mk("2026-02-01")];
        crate::config::OrderBy::CreatedAtAsc.sort(&mut cards);
        assert_eq!(dates(&cards), ["2026-01-01", "2026-02-01", "2026-03-01"]);

        let mut cards = vec![mk("2026-03-01"), mk("2026-01-01")];
        crate::config::OrderBy::None.sort(&mut cards);
        assert_eq!(
            dates(&cards),
            ["2026-03-01", "2026-01-01"],
            "none is a no-op"
        );
    }

    #[test]
    fn build_orders_most_recent_first_by_default() {
        use crate::config::Config;
        use std::path::PathBuf;
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        std::fs::create_dir_all(&dir).unwrap();
        write_issue_md(&dir, "2026-01-01-old.md", 1, "old", "todo", "2026-01-01");
        write_issue_md(&dir, "2026-02-01-mid.md", 2, "mid", "todo", "2026-02-01");
        write_issue_md(&dir, "2026-03-01-new.md", 3, "new", "todo", "2026-03-01");
        let config = Config {
            issues_dir: PathBuf::from(&dir),
            ..Config::default()
        };
        let store = crate::storage::Store::open(&config).unwrap();
        let board = BoardState::build(&store, config.default_config());
        let titles: Vec<&str> = board
            .column_cards(0)
            .iter()
            .map(|c| c.title.as_str())
            .collect();
        assert_eq!(titles, ["new", "mid", "old"], "default desc: newest first");
    }

    #[test]
    fn build_applies_created_at_asc_and_none() {
        use crate::config::OrderBy;
        use std::path::PathBuf;
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        std::fs::create_dir_all(&dir).unwrap();
        write_issue_md(&dir, "2026-01-01-old.md", 1, "old", "todo", "2026-01-01");
        write_issue_md(&dir, "2026-02-01-mid.md", 2, "mid", "todo", "2026-02-01");
        write_issue_md(&dir, "2026-03-01-new.md", 3, "new", "todo", "2026-03-01");
        let config = crate::config::Config {
            issues_dir: PathBuf::from(&dir),
            ..crate::config::Config::default()
        };
        let store = crate::storage::Store::open(&config).unwrap();

        let mut cfg_asc = config.clone();
        cfg_asc
            .kanban
            .configurations
            .get_mut("default")
            .unwrap()
            .order_by = OrderBy::CreatedAtAsc;
        let board_asc = BoardState::build(&store, cfg_asc.default_config());
        let titles: Vec<&str> = board_asc
            .column_cards(0)
            .iter()
            .map(|c| c.title.as_str())
            .collect();
        assert_eq!(titles, ["old", "mid", "new"]);

        let mut cfg_none = config;
        cfg_none
            .kanban
            .configurations
            .get_mut("default")
            .unwrap()
            .order_by = OrderBy::None;
        let board_none = BoardState::build(&store, cfg_none.default_config());
        let titles: Vec<&str> = board_none
            .column_cards(0)
            .iter()
            .map(|c| c.title.as_str())
            .collect();
        assert_eq!(
            titles,
            ["old", "mid", "new"],
            "none keeps the store's filename-ascending order"
        );
    }

    #[test]
    fn build_applies_sparse_manual_card_order_when_present() {
        use crate::config::Config;
        use std::path::PathBuf;
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        std::fs::create_dir_all(&dir).unwrap();
        write_issue_md(&dir, "2026-01-01-old.md", 1, "old", "todo", "2026-01-01");
        write_issue_md(&dir, "2026-02-01-mid.md", 2, "mid", "todo", "2026-02-01");
        write_issue_md(&dir, "2026-03-01-new.md", 3, "new", "todo", "2026-03-01");
        let config = Config {
            issues_dir: PathBuf::from(&dir),
            ..Config::default()
        };
        let store = crate::storage::Store::open(&config).unwrap();
        let mut board_cfg = config.default_config().clone();
        board_cfg.card_order = vec!["2026-02-01-mid.md".into(), "2026-03-01-new.md".into()];
        let board = BoardState::build(&store, &board_cfg);
        let titles: Vec<&str> = board
            .column_cards(0)
            .iter()
            .map(|c| c.title.as_str())
            .collect();
        assert_eq!(titles, ["mid", "new", "old"], "manual order wins");
    }

    #[test]
    fn sparse_card_order_only_returns_changed_cards() {
        use crate::config::Config;
        use std::path::PathBuf;

        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        std::fs::create_dir_all(&dir).unwrap();
        write_issue_md(&dir, "2026-01-01-old.md", 1, "old", "todo", "2026-01-01");
        write_issue_md(&dir, "2026-02-01-mid.md", 2, "mid", "todo", "2026-02-01");
        write_issue_md(&dir, "2026-03-01-new.md", 3, "new", "todo", "2026-03-01");
        let config = Config {
            issues_dir: PathBuf::from(&dir),
            ..Config::default()
        };
        let store = crate::storage::Store::open(&config).unwrap();
        let board_cfg = config.default_config().clone();
        let mut cards = BoardState::build(&store, &board_cfg)
            .column_cards(0)
            .to_vec();
        cards.swap(0, 1);
        let sparse = sparse_card_order(&board_cfg, &cards);
        assert_eq!(sparse, ["2026-02-01-mid.md", "2026-03-01-new.md"]);
    }

    #[test]
    fn build_filtered_applies_order_by() {
        use crate::model::Issue;
        use crate::search::{Corpus, StructuredFilter};

        let to_issue = |number: u32, title: &str, created: &str| Issue {
            projects: None,
            id: None,
            number,
            title: title.to_string(),
            status: crate::model::Status::new("todo"),
            labels: vec![],
            priority: crate::model::Priority::Medium,
            assignee: None,
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            related_issues: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: created.into(),
            type_: None,
            updated: "2026-01-01".into(),
            filename: format!("2026-01-01-{number}.md"),
            body: String::new(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            time_entries: vec![],
            parent: None,
            series: None,
            health: None,
            epics: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        let corpus = Corpus::with_texts(
            vec![
                to_issue(1, "old", "2026-01-01"),
                to_issue(2, "new", "2026-03-01"),
                to_issue(3, "mid", "2026-02-01"),
            ],
            vec!["old".into(), "new".into(), "mid".into()],
        );
        let config = crate::config::Config::default();
        let (_, resolution) = crate::workflow::active_resolution(&config);
        let board = BoardState::build_filtered(
            config.default_config(),
            &config,
            &corpus,
            "",
            &StructuredFilter::default(),
            &resolution,
        );
        let titles: Vec<&str> = board
            .column_cards(0)
            .iter()
            .map(|c| c.title.as_str())
            .collect();
        assert_eq!(
            titles,
            ["new", "mid", "old"],
            "default desc applies to filtered results too"
        );
    }

    /// A card for the tree-ordering tests: only the fields the ordering and the
    /// renderer read are spelled out.
    fn tree_card(number: u32, parent: Option<u32>) -> Card {
        Card {
            health: None,
            number,
            title: format!("Issue {number}"),
            priority: Priority::Medium,
            labels: vec![],
            assignee: None,
            filename: format!("{number}.md"),
            commit: None,
            created: "2026-01-01".into(),
            due_date: None,
            status: "todo".into(),
            category: None,
            category_color: None,
            done: false,
            cycle: None,
            milestone: None,
            blocked: None,
            children: None,
            parent,
            depth: 0,
            archived: false,
            related: 0,
            projects: vec![],
            epics: Vec::new(),
        }
    }

    #[test]
    fn nest_children_places_a_child_after_its_parent() {
        let mut cards = vec![
            tree_card(2, Some(1)),
            tree_card(1, None),
            tree_card(3, None),
        ];
        nest_children(&mut cards);
        let shape: Vec<(u32, u8)> = cards.iter().map(|c| (c.number, c.depth)).collect();
        assert_eq!(
            shape,
            vec![(1, 0), (2, 1), (3, 0)],
            "the child moves up under its parent and is marked depth 1"
        );
    }

    #[test]
    fn nest_children_keeps_adopted_siblings_in_their_existing_order() {
        let mut cards = vec![
            tree_card(1, None),
            tree_card(3, Some(1)),
            tree_card(2, Some(1)),
        ];
        nest_children(&mut cards);
        let shape: Vec<(u32, u8)> = cards.iter().map(|c| (c.number, c.depth)).collect();
        assert_eq!(shape, vec![(1, 0), (3, 1), (2, 1)]);
    }

    #[test]
    fn nest_children_does_not_nest_a_grandchild() {
        // #2 is a child of #1; #3 is a child of #2. Only one level is shown, so #3
        // stays top level instead of stacking under the child.
        let mut cards = vec![
            tree_card(1, None),
            tree_card(2, Some(1)),
            tree_card(3, Some(2)),
        ];
        nest_children(&mut cards);
        let shape: Vec<(u32, u8)> = cards.iter().map(|c| (c.number, c.depth)).collect();
        assert_eq!(shape, vec![(1, 0), (2, 1), (3, 0)]);
    }

    #[test]
    fn nest_children_leaves_a_child_whose_parent_is_in_another_column() {
        // #1 is not in this column, so #2 keeps its position and `depth`.
        let mut cards = vec![tree_card(2, Some(1)), tree_card(5, None)];
        nest_children(&mut cards);
        let shape: Vec<(u32, u8)> = cards.iter().map(|c| (c.number, c.depth)).collect();
        assert_eq!(shape, vec![(2, 0), (5, 0)]);
    }

    #[test]
    fn nest_children_keeps_every_card_exactly_once() {
        let mut cards = vec![
            tree_card(4, None),
            tree_card(3, Some(1)),
            tree_card(1, None),
            tree_card(2, Some(1)),
        ];
        nest_children(&mut cards);
        let mut numbers: Vec<u32> = cards.iter().map(|c| c.number).collect();
        numbers.sort_unstable();
        assert_eq!(
            numbers,
            vec![1, 2, 3, 4],
            "no card is duplicated or dropped"
        );
    }

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

        let width = 80u16;
        let height = 30u16;
        let mut child = tree_card(2, Some(1));
        child.title = "a sub-issue whose deliberately long title wraps across more \
                       than a single rendered row inside the column"
            .into();
        child.depth = 1;
        let parent = tree_card(1, None);

        let mut flat_child = child.clone();
        flat_child.depth = 0;
        assert_eq!(
            widgets::card_line_count(&child, width as usize, true, 3),
            widgets::card_line_count(&flat_child, width as usize, true, 3),
            "the indent must not change the card's rendered line count"
        );

        let board = BoardState {
            columns: vec![BoardColumn {
                name: "todo".into(),
                cards: vec![parent, child],
            }],
            hidden: vec![],
            mismatch: BoardColumn {
                name: "Mismatched".into(),
                cards: vec![],
            },
            active_col: 0,
            selected: 0,
            filter: None,
            hover: None,
            hover_col: None,
            show_mismatch: false,
        };
        let display = BoardDisplay {
            wrap_titles: true,
            title_lines: 3,
        };
        let backend = TestBackend::new(width, height);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| {
                render(
                    &board,
                    f,
                    f.area(),
                    &None,
                    None,
                    display,
                    &crate::ui::color::Theme::default(),
                    None,
                    None,
                );
            })
            .unwrap();
        let buffer = terminal.backend().buffer();
        let row = |y: u16| -> String { (0..width).map(|x| buffer[(x, y)].symbol()).collect() };

        let symbol = |x: u16, y: u16| buffer[(x, y)].symbol().to_string();
        assert!(
            row(1).contains("#1"),
            "the parent draws first: {:?}",
            row(1)
        );
        assert_eq!(
            symbol(1, 1),
            "#",
            "a top-level card is flush with the column border: {:?}",
            row(1)
        );
        assert_eq!(
            (symbol(1, 2), symbol(2, 2)),
            (" ".to_string(), "2".to_string()),
            "the sub-issue draws a one-character ASCII whitespace margin and drops \
             the `#` (tix #1536): {:?}",
            row(2)
        );
        // The indent is exactly the `#`'s width and the sub-issue's `#` is gone,
        // so the two numbers start in the same column: `#1` and ` 2`, not `#1` and
        // ` #2`.
        assert_eq!(
            (symbol(2, 1), symbol(2, 2)),
            ("1".to_string(), "2".to_string()),
            "the parent's and sub-issue's digits align at the same column: {:?} / {:?}",
            row(1),
            row(2)
        );

        // Hit-testing resolves the rows the renderer drew to the same card
        // indices: row 1 is card 0 (the parent), row 2 is card 1 (the child).
        let area = Rect::new(0, 0, width, height);
        assert_eq!(
            board.hit_test(area, display, false, 3, 1),
            Some(HitTarget::Card { col: 0, row: 0 })
        );
        assert_eq!(
            board.hit_test(area, display, false, 3, 2),
            Some(HitTarget::Card { col: 0, row: 1 })
        );
    }

    /// Write an issue with an optional `parent:` frontmatter line, for the
    /// build-time tree tests.
    fn write_issue_with_parent_md(
        dir: &std::path::Path,
        name: &str,
        number: u32,
        title: &str,
        status: &str,
        created: &str,
        parent: Option<u32>,
    ) {
        let parent_line = parent.map(|p| format!("parent: {p}\n")).unwrap_or_default();
        let contents = format!(
            "---\nnumber: {number}\ntitle: \"{title}\"\nstatus: \"{status}\"\nlabels: []\npriority: \"medium\"\ncreated: \"{created}\"\nupdated: \"{created}\"\n{parent_line}---\n\nBody text."
        );
        std::fs::write(dir.join(name), contents).unwrap();
    }

    #[test]
    fn build_with_show_children_nests_a_sub_issue_below_its_parent() {
        use crate::config::Config;
        use std::path::PathBuf;

        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        std::fs::create_dir_all(&dir).unwrap();
        write_issue_with_parent_md(
            &dir,
            "2026-01-01-parent.md",
            1,
            "parent",
            "todo",
            "2026-01-01",
            None,
        );
        write_issue_with_parent_md(
            &dir,
            "2026-01-02-child.md",
            2,
            "child",
            "todo",
            "2026-01-02",
            Some(1),
        );
        let config = Config {
            issues_dir: PathBuf::from(&dir),
            ..Config::default()
        };
        let store = crate::storage::Store::open(&config).unwrap();
        let board_cfg = config.default_config().clone();

        // The default order puts the newer child before the older parent, so the
        // toggle has to reorder them.
        let flat = BoardState::build(&store, &board_cfg);
        let flat_shape: Vec<(u32, u8)> = flat
            .column_cards(0)
            .iter()
            .map(|c| (c.number, c.depth))
            .collect();
        assert_eq!(flat_shape, vec![(2, 0), (1, 0)]);

        let tree = BoardState::build_with(&store, &board_cfg, false, true);
        let tree_shape: Vec<(u32, u8)> = tree
            .column_cards(0)
            .iter()
            .map(|c| (c.number, c.depth))
            .collect();
        assert_eq!(
            tree_shape,
            vec![(1, 0), (2, 1)],
            "the sub-issue follows its parent, one level deep"
        );
        assert_eq!(tree.column_cards(0)[1].parent, Some(1));
    }

    /// `build_from_issues` is the single build path: for the same store it must
    /// produce exactly the board `build_with` produces (issue #10 follow-up).
    #[test]
    fn build_from_issues_matches_build_with() {
        use crate::config::Config;

        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        std::fs::create_dir_all(&dir).unwrap();
        write_issue_with_parent_md(
            &dir,
            "2026-01-01-parent.md",
            1,
            "parent",
            "todo",
            "2026-01-01",
            None,
        );
        write_issue_with_parent_md(
            &dir,
            "2026-01-02-child.md",
            2,
            "child",
            "todo",
            "2026-01-02",
            Some(1),
        );
        write_issue_md(
            &dir,
            "2026-01-03-other.md",
            3,
            "other",
            "in progress",
            "2026-01-03",
        );
        let config = Config {
            issues_dir: dir.clone(),
            ..Config::default()
        };
        let store = crate::storage::Store::open(&config).unwrap();
        let board_cfg = config.default_config().clone();

        let shape = |state: &BoardState| -> Vec<(String, Vec<(String, u8)>)> {
            state
                .columns
                .iter()
                .chain(state.hidden.iter())
                .chain(std::iter::once(&state.mismatch))
                .map(|col| {
                    (
                        col.name.clone(),
                        col.cards
                            .iter()
                            .map(|c| (c.filename.clone(), c.depth))
                            .collect(),
                    )
                })
                .collect()
        };

        for show_children in [false, true] {
            let from_store = BoardState::build_with(&store, &board_cfg, false, show_children);
            let issues = store.list().unwrap();
            let resolution = BoardState::resolution_for(&store, &board_cfg);
            let from_issues = BoardState::build_from_issues(
                &issues,
                &board_cfg,
                &config,
                &resolution,
                show_children,
            );
            assert_eq!(
                shape(&from_issues),
                shape(&from_store),
                "show_children={show_children}"
            );
        }
    }
}