tix-tracker 0.8.0

use ratatui::Frame;
use ratatui::buffer::{Buffer, CellDiffOption};
use ratatui::layout::Rect;
use ratatui::style::{Color, Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Borders, Paragraph};

use crate::model::Issue;

use std::num::NonZeroU16;

#[derive(Clone)]
pub struct DetailState {
    pub issue: Issue,
    /// The issue's column usage against its WIP limit, from the shared snapshot
    /// (WP05 T025): `3/2 max_items 2, block` or similar, or `None` for a column with
    /// no limit. Filled in by the caller, so the detail pane cannot count a column
    /// differently from the board's header.
    pub wip: Option<String>,
    /// The issue's resolved category label and color hint, from the service
    /// (WP05 T023, FR-004).
    ///
    /// `None` for a column the board does not configure, which the chip renders as
    /// `(unmapped)` — a statement about the file rather than a silent default. Filled
    /// in by the caller from the service, so the detail view cannot spell a category
    /// differently from the board card (T024).
    pub category: Option<(String, Option<crate::workflow::ColorHint>)>,
    /// The issue's relationships as the **service** resolves them, not
    /// `issue.relationships`.
    ///
    /// An edge is stored once in its canonical source's file, so the issue's own
    /// field holds only the edges it happens to own — for `2 related 1` it is
    /// empty, so rendering it showed a related issue with no relationships. The
    /// retired symmetric model mirrored the link on both sides by construction,
    /// so reading the raw field here was a regression, not a simplification.
    /// Populated by the caller from [`crate::storage::Store::relationships_for`].
    pub relationships: Vec<crate::relationships::Relationship>,
    /// The issue's dependency chain, exactly as the service ordered it, and
    /// whether a traversal bound truncated it.
    ///
    /// Taken from the service rather than derived here: re-deriving the walk in
    /// the renderer is how a detail pane ends up disagreeing with `tix chain`
    /// about the same snapshot (`contracts/surface-parity.md` §3).
    pub chain: crate::relationships::DependencyChain,
    /// The service's blocked reason, or `None` when the issue is not blocked.
    pub blocked: Option<String>,
    /// The issue's hierarchy facts, from the shared
    /// [`crate::commands::parent::HierarchyFacts`].
    ///
    /// Taken whole rather than as pre-rendered strings, so the detail pane and
    /// `tix parent show` are guaranteed to describe the same snapshot and the
    /// pane can lay them out its own way — which the parity contract allows:
    /// same facts, same order, presentation may differ.
    pub hierarchy: crate::commands::parent::HierarchyFacts,
    /// The scope's health, exactly as the shared document describes it (WP06 T031):
    /// the state, its layer, the policy version, the History entries, and — when the
    /// scope has contributors — the derived rollup with them.
    ///
    /// Taken whole from [`crate::health::PortableHealth`] rather than as a rendered
    /// string, so the detail view and the CLI describe the same snapshot and the pane
    /// can lay it out its own way. `None` when the issue is not in the document.
    pub health: Option<crate::health::PortableScopeHealth>,
    /// The health diagnostics about this scope (WP06 T033): a legacy `unknown`, a
    /// missing reference, a value this build cannot read. Rendered with their remedy,
    /// so a reader is told what to do rather than only that something is wrong.
    pub health_diagnostics: Vec<crate::health::HealthDiagnostic>,
    pub scroll_offset: u16,
    /// The pane's last-rendered viewport height, in rows (tix #1442).
    ///
    /// Recorded during the draw because the *key* handler is what needs it: "scroll
    /// one page" has to mean the page the reader is looking at, and only the renderer
    /// knows how tall that is. A `Cell` for the same reason `App::frame_hit_regions`
    /// is a `RefCell` — the renderer holds this state immutably.
    pub viewport: std::cell::Cell<u16>,
    /// The largest `scroll_offset` that still shows content (tix #1442).
    ///
    /// Scroll steps used to be unclamped, so paging past the end of a long issue left
    /// a blank pane with no way back except scrolling up the same distance. A page
    /// step makes that much easier to hit, so the bound travels with the step.
    pub max_scroll: std::cell::Cell<u16>,
    /// Which relationship `E` (re-kind) and `d` (remove) act on, as an index into
    /// `relationships` (#1359).
    ///
    /// An index and not an id, because the pane does not display ids — it shows
    /// `r.display`, which carries the kind and the target but not the stable
    /// `rel_…` token. A user picks an edge by looking at it.
    ///
    /// Always within `0..relationships.len()`; [`DetailState::clamp_rel_cursor`] is
    /// the only thing that writes it, so a removal that shrinks the list cannot leave
    /// the cursor pointing past the end.
    pub rel_cursor: usize,
    /// The issue's classified `related_issues` entries (tix #1513).
    ///
    /// Classified by [`crate::related::classify_all`] at open/refresh time, not at
    /// render time: the classification is stable for a given string and doing it once
    /// keeps the renderer a pure function of the pane's state. The list is empty for
    /// an issue with no `related_issues:` field, and the block is then not drawn.
    pub related: Vec<crate::related::RelatedRef>,
    /// Which related entry `o` follows, as an index into `related` (tix #1513).
    ///
    /// Moved only by the related picker (`r`), never by `j`/`k` — those keep moving
    /// the **relationship** cursor, which is a different list with a different
    /// meaning. Always within `0..related.len()`; [`DetailState::clamp_related_cursor`]
    /// is the only thing that writes it, so indexing cannot panic.
    pub related_cursor: usize,
    /// Whether the pane shows an issue it must not offer to mutate (tix #1513).
    ///
    /// `true` only for a `related_issues` *path* reference that parsed as an issue
    /// outside the store — the file is readable but its writes have no store to route
    /// through, so the pane refuses `e`/`c`/`a` and the relationship operations rather
    /// than failing with a lookup error.
    pub read_only: bool,
    /// The issue's referenced epics, exactly as the service resolved them (WP04 T019,
    /// FR-003, C-005).
    ///
    /// The same canonical rows `tix show` prints
    /// ([`crate::commands::view::EpicBlockEntry`]), so the pane and the CLI cannot
    /// word the same epic differently: the pane adds styling, never facts. Built by
    /// the caller from the one service read
    /// ([`crate::commands::view::epic_entries`]) because the renderer holds no store.
    pub epics: Vec<crate::commands::view::EpicBlockEntry>,
    /// The capacity scopes this issue contributes to, as the shared calculation
    /// describes them (WP06 T031).
    ///
    /// One entry per cycle the issue's own `cycles` field names, plus its assignee
    /// when it states one — the issue's **own** explicit scope references, folded by
    /// the library's [`crate::capacity::calculate::CapacityScope`] adapter rather than
    /// re-resolved here. Empty for an issue in no scope, which draws no block.
    pub capacity: Vec<IssueCapacityView>,
}

/// One capacity scope an issue contributes to, as the detail pane draws it (WP06
/// T031).
///
/// Every figure is a field of the shared DTOs
/// ([`crate::capacity::calculate::CapacityCalculation`] and
/// [`crate::capacity::snapshot::CapacitySnapshot`]); the pane adds styling, never a
/// fact, and an absent value is `-` rather than `0`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct IssueCapacityView {
    /// The scope the figures belong to, `cycle `Cycle 1`` — the library's own
    /// resolution, so the name and its stable id are one scope.
    pub scope: String,
    /// The issue's own contribution: its raw estimate, the value it contributes in
    /// the scope's unit, or an explicit statement that it states no estimate.
    pub issue_line: String,
    /// The shared calculation's fields, in `tix capacity calculate`'s spelling.
    pub fields: Vec<(String, String)>,
    /// The findings that name this issue, or the scope's own, each with its remedy.
    pub diagnostics: Vec<String>,
}

impl DetailState {
    /// Keep the relationship cursor inside the list.
    ///
    /// Called after every mutation that can change the list's length — a removal, and
    /// a refresh after a create. A cursor that survived a removal as `3` into a
    /// two-element list would make `E` and `d` act on nothing while still reporting
    /// a selection.
    pub fn clamp_rel_cursor(&mut self) {
        if self.relationships.is_empty() {
            self.rel_cursor = 0;
        } else if self.rel_cursor >= self.relationships.len() {
            self.rel_cursor = self.relationships.len() - 1;
        }
    }

    /// Keep the related-entry cursor inside the list (tix #1513).
    ///
    /// The same rule [`DetailState::clamp_rel_cursor`] follows: `o` indexes
    /// `related` and the picker writes the index, so the list shrinking (a refresh
    /// after the `related_issues` field was edited) must not leave it past the end.
    pub fn clamp_related_cursor(&mut self) {
        if self.related.is_empty() {
            self.related_cursor = 0;
        } else if self.related_cursor >= self.related.len() {
            self.related_cursor = self.related.len() - 1;
        }
    }

    /// Rows a **page** step moves: the last-rendered viewport, less one row of
    /// overlap (tix #1442).
    ///
    /// The overlap is the point. A step that moves exactly the height of the pane
    /// leaves no line on screen that was there before, so a reader paging through a
    /// long body has nothing to anchor the new page to. One row of context costs
    /// nothing and removes that.
    pub fn page(&self) -> u16 {
        self.viewport.get().saturating_sub(1).max(1)
    }

    /// Scroll by `rows` (negative scrolls up), clamped to the content.
    ///
    /// The clamp is what keeps a page step usable: without it, one `PgDn` past the
    /// end of an issue left a blank pane, and the only way back was to scroll up the
    /// same distance — which, on a page step, is the whole screen.
    /// Scroll so `body_line` is the first visible row of the body.
    ///
    /// Used by the mention jump (OpenSpec change `issue-mentions`). The offset is a
    /// **body line**, and the pane wraps long lines, so the target can land a row or
    /// two off on a narrow terminal — close enough to see the mention, which is what
    /// the jump is for; exact row arithmetic would need the wrapped layout, which
    /// only the renderer knows.
    pub fn focus_body_line(&mut self, body_line: usize) {
        self.scroll_offset = u16::try_from(body_line)
            .unwrap_or(u16::MAX)
            .min(self.max_scroll.get());
    }

    pub fn scroll_by(&mut self, rows: i32) {
        let next = i32::from(self.scroll_offset) + rows;
        self.scroll_offset = next.clamp(0, i32::from(self.max_scroll.get())) as u16;
    }
}

/// An empty chain, for tests with no graph to hand.
#[cfg(test)]
fn no_chain() -> crate::relationships::DependencyChain {
    crate::relationships::DependencyChain {
        root: 0,
        paths: vec![],
        truncated: false,
    }
}

/// One `label: value` line in the detail pane, in the pane's own field style.
fn health_line(label: &str, value: &str) -> Line<'static> {
    Line::from(vec![
        Span::styled(format!("{label}: "), Style::default().fg(Color::DarkGray)),
        Span::raw(value.to_string()),
    ])
}

// ---------------------------------------------------------------------------
// The time table (WP05 T024), shared by the two surfaces that draw one
// ---------------------------------------------------------------------------
//
// Both the pane's time block and the `F7` Stats page's Time tab list the same
// entries in the same columns, so the row and the dash rule are written once, here,
// and imported by the tab. They live beside the pane because the pane's block is
// where the table is introduced; nothing here computes a figure — every cell is a
// field of WP03's [`crate::time_tracking::TimeEntry`], and the *total* those rows
// belong to is the shared [`crate::time_tracking::aggregate::TimeTotal`]'s.

/// An absent number as `-`, the crate's convention for "no value".
///
/// The rendering `commands::time`'s own private `number` performs, restated here
/// because that helper belongs to the command adapter and the TUI must not reach
/// into it: a zero total and a scope with nothing to total never print the same
/// bytes (C-005, [`crate::time_tracking::aggregate::TimeTotalState`]).
pub(crate) fn dash_number<T: std::fmt::Display>(value: Option<T>) -> String {
    value.map_or_else(|| "-".to_string(), |value| value.to_string())
}

/// One table cell: `-` when the value is absent or blank, on one line whatever the
/// file holds.
///
/// The collapse is the renderer's own guarantee, not the caller's: a hand-edited
/// note that is a YAML literal block round-trips a line break, and a table row that
/// broke across two lines would misread as a field nobody wrote.
pub(crate) fn dash_cell(value: Option<&str>) -> String {
    let value = value.unwrap_or_default().trim();
    if value.is_empty() {
        return "-".to_string();
    }
    value
        .chars()
        .map(|ch| if ch == '\n' || ch == '\r' { ' ' } else { ch })
        .collect()
}

/// The columns of the shared time table, in the order `tix time show` prints them.
///
/// The one difference from that table's header casing is typographic: both surfaces
/// label the same five fields in the same order, so a reader comparing the pane with
/// the CLI is comparing values, not columns.
const TIME_COLUMNS: [&str; 5] = ["ENTRY", "MINUTES", "DATE", "AUTHOR", "NOTE"];

/// The column widths, one per [`TIME_COLUMNS`] entry.
const TIME_WIDTHS: [usize; 5] = [18, 7, 10, 14, 0];

/// The table's heading line, for a surface that draws one.
pub(crate) fn time_entry_heading() -> String {
    format!(
        "{:<18} {:>7}  {:<10}  {:<14}  {}",
        TIME_COLUMNS[0], TIME_COLUMNS[1], TIME_COLUMNS[2], TIME_COLUMNS[3], TIME_COLUMNS[4]
    )
}

/// One current entry as one line of the shared time table (WP05 T024).
///
/// The columns are the entry's own fields — the stable id, the minutes, the optional
/// date, the author and the optional note — each rendered through the dash rule, so
/// a malformed entry reads as *absent* rather than as zero and its finding (which
/// the caller draws beside the total) explains why. The id is the one field the
/// service's one-line `entry_summary` does not carry, which is why this table is
/// built from the fields rather than reusing that summary.
pub(crate) fn time_entry_row(entry: &crate::time_tracking::TimeEntry) -> String {
    let cells = [
        dash_cell(Some(entry.id.as_str())),
        dash_number(entry.minutes()),
        dash_cell(entry.date.as_deref()),
        dash_cell(Some(entry.author.as_str())),
        dash_cell(entry.note.as_deref()),
    ];
    let mut row = String::new();
    for (index, cell) in cells.iter().enumerate() {
        if index > 0 {
            row.push_str("  ");
        }
        let width = TIME_WIDTHS[index];
        if index == 1 {
            row.push_str(&format!("{cell:>width$}"));
        } else if width == 0 {
            row.push_str(cell);
        } else {
            row.push_str(&format!("{cell:<width$}"));
        }
    }
    row
}

pub fn render(detail: &DetailState, f: &mut Frame, area: Rect, theme: &crate::ui::color::Theme) {
    let mut lines: Vec<Line<'static>> = Vec::new();
    let mut files_line_index: Option<usize> = None;

    let fields: Vec<(&str, String)> = vec![
        ("number", detail.issue.number.to_string()),
        ("title", detail.issue.title.clone()),
        ("status", detail.issue.status.to_string()),
        // The category label, from the service's own `label()` — never reworded
        // here (T023 step 1). Rendered as a plain field so it is greppable in the
        // detail view exactly as the other frontmatter fields are.
        // The WIP row appears only when the board configures a limit for this
        // issue's column: a limit-free board's detail view is byte-identical to what
        // it rendered before this mission.
        ("wip", detail.wip.clone().unwrap_or_default()),
        (
            "category",
            detail
                .category
                .as_ref()
                .map(|(label, _)| label.clone())
                .unwrap_or_else(|| "(unmapped)".to_string()),
        ),
        ("priority", detail.issue.priority.to_string()),
        ("created", detail.issue.created.clone()),
        ("updated", detail.issue.updated.clone()),
    ];

    for (key, value) in &fields {
        lines.push(Line::from(vec![
            Span::styled(format!("{key}: "), Style::default().fg(Color::DarkGray)),
            Span::raw(value.clone()),
        ]));
    }

    // The health block (WP06 T031/T033): the same facts the CLI prints — the state,
    // its layer, the policy version, the contributors, the audit entries — plus every
    // diagnostic with its remedy. Rendered from the shared DTO, so a reader comparing
    // this pane with `tix health show` sees one set of facts rather than two.
    if let Some(health) = &detail.health {
        let mut layer = format!(
            "{} ({}, {})",
            health.state,
            health.source,
            health
                .recorded_policy_version
                .as_deref()
                .unwrap_or("no policy version recorded")
        );
        if let Some(recorded) = &health.recorded {
            if recorded != &health.state {
                layer.push_str(&format!(" recorded `{recorded}`"));
            }
        }
        lines.push(health_line("health", &layer));
        if let Some(derived) = &health.rollup {
            let contributors: Vec<String> = derived
                .contributors
                .iter()
                .map(|contributor| format!("#{} {}", contributor.number, contributor.state))
                .collect();
            lines.push(health_line(
                "health derived",
                &format!(
                    "{} ({}, {} contributor{}: {})",
                    derived.state,
                    derived.policy_version,
                    derived.contributors.len(),
                    if derived.contributors.len() == 1 {
                        ""
                    } else {
                        "s"
                    },
                    if contributors.is_empty() {
                        "nothing contributes yet".to_string()
                    } else {
                        contributors.join(", ")
                    }
                ),
            ));
        }
        lines.push(health_line(
            "health history",
            &format!(
                "{} entr{}",
                health.events.len(),
                if health.events.len() == 1 { "y" } else { "ies" }
            ),
        ));
    }
    for diagnostic in &detail.health_diagnostics {
        lines.push(health_line(
            "health diagnostic",
            &format!("{}: {}", diagnostic.kind.as_str(), diagnostic.message),
        ));
        if let Some(remedy) = &diagnostic.remedy {
            lines.push(health_line("  remedy", remedy));
        }
    }

    if let Some(rendered) = render_assignee(detail.issue.assignee.as_deref()) {
        lines.push(Line::from(vec![
            Span::styled("assignee: ", Style::default().fg(Color::DarkGray)),
            Span::raw(rendered),
        ]));
    }

    if let Some(estimate) = &detail.issue.estimate {
        lines.push(Line::from(vec![
            Span::styled("estimate: ", Style::default().fg(Color::DarkGray)),
            Span::raw(estimate.clone()),
        ]));
    }

    // The capacity block (WP06 T031): the issue's own contributing estimate and the
    // scope context it is counted in, from the shared calculation. Read-only — the
    // pane renders the DTO's values and never offers to change one — and an issue in
    // no scope draws no block at all rather than an empty heading.
    if !detail.capacity.is_empty() {
        lines.push(Line::from(Span::styled("", Style::default())));
        lines.push(Line::from(Span::styled(
            "capacity:",
            Style::default()
                .fg(Color::DarkGray)
                .add_modifier(Modifier::BOLD),
        )));
        for view in &detail.capacity {
            lines.push(Line::from(vec![
                Span::styled("  ", Style::default()),
                Span::styled(
                    view.scope.clone(),
                    Style::default().add_modifier(Modifier::BOLD),
                ),
            ]));
            lines.push(health_line("    this issue", &view.issue_line));
            for (key, value) in &view.fields {
                lines.push(health_line(&format!("    {key}"), value));
            }
            if !view.diagnostics.is_empty() {
                lines.push(health_line(
                    "    findings",
                    &view.diagnostics.len().to_string(),
                ));
                for diagnostic in &view.diagnostics {
                    for line in diagnostic.lines() {
                        lines.push(health_line("      ", line));
                    }
                }
            }
        }
    }

    // The time block (WP05 T024): the issue's current entries and their total, from
    // the shared aggregation DTO — the same rows and the same total the CLI's
    // `tix time show` and this page's Time tab render, so the pane cannot count a
    // minute the CLI would not. Read-only: the pane draws the DTO's values and never
    // offers to change one, and the mutations live on the Stats page's Time tab,
    // which routes them through the same service.
    //
    // The block is drawn even for an issue with no entry, because the total's typed
    // state is the answer: `nothing` ("this issue recorded nothing") and `recorded
    // 0` ("an entry recorded zero minutes") are different facts, and a pane that drew
    // nothing would leave the reader to guess which one this is (C-005).
    {
        let filter =
            crate::time_tracking::filters::TimeFilter::new().for_issue(detail.issue.number);
        let snapshot =
            crate::time_tracking::aggregate::TimeSnapshot::of(std::slice::from_ref(&detail.issue));
        let total = snapshot.total(&filter);
        lines.push(Line::from(Span::styled("", Style::default())));
        lines.push(Line::from(Span::styled(
            "time:",
            Style::default()
                .fg(Color::DarkGray)
                .add_modifier(Modifier::BOLD),
        )));
        lines.push(health_line("  state", total.state().as_str()));
        lines.push(health_line("  total", &dash_number(total.total_minutes)));
        lines.push(health_line("  entries", &total.entry_count.to_string()));
        if total.is_partial() {
            // Only when the total is not the whole story: the counts say why the
            // number above must be read with the findings below (C-005).
            lines.push(health_line(
                "  malformed",
                &total.malformed_count.to_string(),
            ));
            lines.push(health_line("  undated", &total.undated_count.to_string()));
        }
        let deleted = snapshot.deletions_on(detail.issue.number).len();
        let corrected = snapshot.corrections_on(detail.issue.number);
        if deleted > 0 || corrected > 0 {
            // The History side, shown beside the current one: a correction and a
            // deletion keep their prior value in History, which is what makes them
            // auditable rather than silent (C-003, C-004).
            lines.push(health_line("  history deleted", &deleted.to_string()));
            lines.push(health_line("  history corrected", &corrected.to_string()));
        }
        let rows: Vec<&crate::time_tracking::aggregate::IndexedEntry> = snapshot
            .entries()
            .iter()
            .filter(|indexed| filter.selects(indexed.issue, &indexed.entry))
            .collect();
        if !rows.is_empty() {
            // The table's own heading and rows, indented like the fields above: the
            // heading is a label line rather than a `label: value` pair, because the
            // five column names are not a value of the pane's.
            lines.push(Line::from(Span::styled(
                format!("  {}", time_entry_heading()),
                Style::default().fg(Color::DarkGray),
            )));
            for indexed in rows {
                lines.push(Line::from(vec![
                    Span::styled("  ", Style::default()),
                    Span::raw(time_entry_row(&indexed.entry)),
                ]));
            }
        }
        for finding in &total.diagnostics {
            lines.push(health_line(
                "  finding",
                &format!("{}: {}", finding.kind.as_str(), finding.reason),
            ));
            // The remedy is what the reader does about it, so it travels with the
            // finding rather than being left to the CLI's refusal block.
            lines.push(health_line("    remedy", &finding.remedy));
        }
    }

    if let Some(commit) = &detail.issue.commit {
        lines.push(Line::from(vec![
            Span::styled("commit: ", Style::default().fg(Color::DarkGray)),
            Span::raw(commit.clone()),
        ]));
    }

    if !detail.issue.labels.is_empty() {
        // Each label renders in its tag color when `docs/tags` configures one
        // (tix #1530); an unconfigured label keeps the default foreground.
        let mut spans = vec![Span::styled(
            "labels: ",
            Style::default().fg(Color::DarkGray),
        )];
        for (index, label) in detail.issue.labels.iter().enumerate() {
            if index > 0 {
                spans.push(Span::raw(", "));
            }
            let style = theme
                .tag(label)
                .map_or_else(Style::default, |color| Style::default().fg(color));
            spans.push(Span::styled(label.clone(), style));
        }
        lines.push(Line::from(spans));
    }

    // The `related:` block (tix #1513). Prominent and **near the top**, above the
    // relationship rows: `related_issues` is the cross-repository surface the user
    // came to this pane for, and a block below the dependency graph would be below
    // the fold on a long issue. Non-empty only — an issue with no `related_issues:`
    // field draws nothing, because an empty heading would be noise on every issue.
    //
    // The selected entry carries a `>` marker exactly like the relationship row, so
    // `o` (follow) acts on something the reader can see. `related_cursor` is clamped
    // on every mutation, so indexing here cannot panic.
    if !detail.related.is_empty() {
        let accent = Style::default()
            .fg(Color::Magenta)
            .add_modifier(Modifier::BOLD);
        lines.push(Line::from(vec![
            Span::styled("related: ", accent),
            // The count, so a long list is legible at a glance. Stated rather than
            // implied by the number of following lines, which the viewport may clip.
            Span::styled(detail.related.len().to_string(), accent),
        ]));
        let cursor = detail.related_cursor;
        for (index, entry) in detail.related.iter().enumerate() {
            let marker = if index == cursor {
                Span::styled("  > ", Style::default().fg(Color::Cyan))
            } else {
                Span::styled("    ", Style::default())
            };
            lines.push(Line::from(vec![
                marker,
                Span::styled(entry.display(), Style::default().fg(Color::Magenta)),
            ]));
        }
    }

    if !detail.relationships.is_empty() {
        // The selected edge is marked, because `E` and `d` act on it and a key that
        // acts on an invisible selection is a key the user cannot use. The marker is
        // `>` on the row itself rather than a separate "selected: …" line, so the
        // row's text is unchanged and stays byte-comparable with `tix view`'s.
        //
        // `rel_cursor` is clamped by `DetailState::clamp_rel_cursor` on every
        // mutation, so indexing here cannot panic even if a future caller forgets.
        let cursor = detail.rel_cursor;
        // Owned strings, because `lines` is `Vec<Line<'static>>` — the pane builds
        // every row that way, and borrowing `rel.display` here would pin the whole
        // vector to the detail's lifetime.
        let mut spans: Vec<Span<'static>> = vec![Span::styled(
            "links: ",
            Style::default().fg(Color::DarkGray),
        )];
        for (index, rel) in detail.relationships.iter().enumerate() {
            if index > 0 {
                spans.push(Span::raw(", "));
            }
            if index == cursor {
                spans.push(Span::styled("> ", Style::default().fg(Color::Cyan)));
            }
            spans.push(Span::raw(rel.display.clone()));
        }
        lines.push(Line::from(spans));
    }

    // Field order matches `tix view --show relationships` exactly:
    // relationships, then chain, then blocked (`surface-parity.md` §2 requires the
    // *outcome* to match and permits presentation to differ **if documented**;
    // WP06 T027 asks for the same order outright, and one order for both surfaces
    // is one fewer thing to explain).
    //
    // WP04 deliberately put the blocked reason first, on the grounds that it is
    // "the fact that changes what the reader should do next". That is a
    // presentation preference rather than a correctness claim — the row is on the
    // same screen either way — so it yields to the shared order. The reasoning is
    // recorded rather than deleted, because if this ever moves back the reason
    // should come with it.
    if detail.chain.paths.is_empty() {
        // The empty state is **stated**, not omitted. `tix view` prints
        // "No dependency chain for #N", and a detail pane that prints nothing
        // cannot distinguish "there is no chain" from "the chain was not
        // computed" — two very different facts about the same issue.
        lines.push(Line::from(vec![
            Span::styled("chain: ", Style::default().fg(Color::DarkGray)),
            Span::styled("none", Style::default().fg(Color::DarkGray)),
        ]));
    } else {
        for (depth, path) in detail.chain.paths.iter().enumerate() {
            let rendered: Vec<String> = path
                .iter()
                .map(|node| {
                    let title = node.title.trim();
                    if title.is_empty() {
                        format!("#{}", node.number)
                    } else {
                        format!("#{} {}", node.number, title)
                    }
                })
                .collect();
            let label = if depth == 0 { "chain: " } else { "        " };
            lines.push(Line::from(vec![
                Span::styled(label, Style::default().fg(Color::DarkGray)),
                Span::raw(rendered.join(" -> ")),
            ]));
        }
    }

    // Likewise the blocked state. An unblocked issue says so. Silently omitting
    // the row would make "not blocked" and "not looked at" the same picture.
    match &detail.blocked {
        Some(reason) => lines.push(Line::from(vec![
            Span::styled("blocked: ", Style::default().fg(Color::Red)),
            Span::styled(
                reason.clone(),
                Style::default().fg(Color::Red).add_modifier(Modifier::BOLD),
            ),
        ])),
        None => lines.push(Line::from(vec![
            Span::styled("blocked: ", Style::default().fg(Color::DarkGray)),
            Span::styled("not blocked", Style::default().fg(Color::DarkGray)),
        ])),
    }

    // The hierarchy block. **Same facts, same order as the CLI block** (parent,
    // child count, rollup, children) — the parity contract requires the content
    // to match even though the presentation does not.
    lines.push(Line::from(Span::styled("", Style::default())));
    lines.push(Line::from(Span::styled(
        "hierarchy:",
        Style::default()
            .fg(Color::DarkGray)
            .add_modifier(Modifier::BOLD),
    )));
    lines.push(Line::from(vec![
        Span::styled("  parent: ", Style::default().fg(Color::DarkGray)),
        Span::raw(crate::commands::parent::parent_text(&detail.hierarchy)),
    ]));
    lines.push(Line::from(vec![
        Span::styled("  ", Style::default()),
        Span::raw(detail.hierarchy.child_count_line()),
    ]));
    lines.push(Line::from(vec![
        Span::styled("  ", Style::default()),
        Span::raw(detail.hierarchy.completion_line()),
    ]));
    for child in &detail.hierarchy.children {
        lines.push(Line::from(vec![
            Span::styled("    ", Style::default()),
            Span::raw(child.display.clone()),
        ]));
    }
    // An explicit empty state, not a bare heading — the CLI block says
    // "No children for #N" and a silent omission would read as "not looked at".
    if !detail.hierarchy.has_children() {
        lines.push(Line::from(vec![
            Span::styled("    ", Style::default()),
            Span::raw(crate::commands::parent::no_children_text(
                detail.hierarchy.number,
            )),
        ]));
    }

    // The epic block (WP04 T019, FR-003, C-005): the same facts `tix show` prints —
    // the id, the name, the hierarchy summary, and the rollup figures — because both
    // render the service's canonical rows ([`crate::commands::view::EpicBlockEntry`]).
    // The pane adds styling, never a fact. An issue in no epic draws nothing at all,
    // not an empty heading.
    if !detail.epics.is_empty() {
        lines.push(Line::from(Span::styled("", Style::default())));
        lines.push(Line::from(Span::styled(
            "epics:",
            Style::default()
                .fg(Color::DarkGray)
                .add_modifier(Modifier::BOLD),
        )));
        for entry in &detail.epics {
            lines.push(Line::from(vec![
                Span::styled("  ", Style::default()),
                Span::raw(entry.heading.clone()),
            ]));
            for line in &entry.detail {
                lines.push(Line::from(vec![
                    Span::styled("    ", Style::default()),
                    Span::raw(line.clone()),
                ]));
            }
        }
        // FR-004: the pane never becomes the only way to reach an issue. The epic
        // layer is a presentation, and a member's detail opens from the epic view's
        // member list directly — stated here so the affordance is explicit rather
        // than implied by the absence of a trap.
        lines.push(Line::from(vec![
            Span::styled("  ", Style::default()),
            Span::styled(
                "members open directly from the epic view — no epic layer",
                Style::default().fg(Color::DarkGray),
            ),
        ]));
    }

    if detail.chain.truncated {
        // Said, not silently dropped: a partial chain shown as a whole one is a
        // false statement about the graph.
        lines.push(Line::from(Span::styled(
            format!(
                "note: chain display truncated at {} nodes; the chain may continue",
                crate::relationships::MAX_CHAIN_NODES
            ),
            Style::default().fg(Color::Yellow),
        )));
    }

    if !detail.issue.files.is_empty() {
        lines.push(Line::from(vec![
            Span::styled("files: ", Style::default().fg(Color::DarkGray)),
            Span::raw(detail.issue.files.join(", ")),
        ]));
        files_line_index = Some(lines.len() - 1);
    }

    lines.push(Line::from(""));
    lines.push(Line::from(Span::styled(
        "---",
        Style::default().fg(Color::DarkGray),
    )));
    lines.push(Line::from(""));

    for line_text in detail.issue.body.lines() {
        lines.push(Line::from(Span::raw(line_text.to_string())));
    }

    let content_lines = lines.len();
    let title = if detail.read_only {
        // An external file has no store to write through, so the pane says so
        // rather than offering an `e` that would fail (#1513).
        "Detail [read-only] [Esc=back]"
    } else {
        "Detail [Esc=back e=edit A=agent]"
    };
    let para = Paragraph::new(lines)
        .scroll((detail.scroll_offset, 0))
        .block(Block::default().borders(Borders::ALL).title(title));

    // tix #1442: the pane records its own geometry, so a page step means the page
    // the reader is looking at and no step can scroll past the last line into a
    // blank pane. Recorded here because only the renderer knows either number.
    let viewport = area.height.saturating_sub(2); // the block's two border rows
    detail.viewport.set(viewport);
    detail.max_scroll.set(
        u16::try_from(content_lines)
            .unwrap_or(u16::MAX)
            .saturating_sub(viewport),
    );

    f.render_widget(para, area);

    if let Some(idx) = files_line_index {
        inject_files_hyperlinks(
            f.buffer_mut(),
            area,
            idx,
            detail.scroll_offset,
            &detail.issue.files,
        );
    }
}

/// Render an assignee for the detail view (FR-030):
/// - a full git identity (`Name <email>`) is shown verbatim (identity form
///   sniffed on the `<>` pair),
/// - a bare handle gets the cosmetic `@` prefix,
/// - an already `@`-prefixed value passes through unchanged,
/// - unassigned renders no line at all.
pub fn render_assignee(assignee: Option<&str>) -> Option<String> {
    let raw = assignee?;
    if raw.contains('<') && raw.contains('>') {
        return Some(raw.to_string());
    }
    if raw.starts_with('@') {
        return Some(raw.to_string());
    }
    Some(format!("@{raw}"))
}

/// A zero-width OSC 8 terminal hyperlink wrapping `label` around `uri`, so a
/// `files:` entry renders as a clickable link in supporting terminals. The
/// sequence is invisible and only has an effect when emitted verbatim.
pub fn hyperlink(uri: &str, label: &str) -> String {
    format!("{}{}{}", osc8_start(uri), label, osc8_end())
}

fn osc8_start(uri: &str) -> String {
    format!("\u{1b}]8;;{uri}\u{1b}\\")
}

fn osc8_end() -> String {
    "\u{1b}]8;;\u{1b}\\".to_string()
}

/// Best-effort `file://` URI for a repo-relative path, resolved against the
/// current working directory (the repo root when tix runs from it). No path
/// validation — a missing file still gets a clickable entry (D3 non-goal).
fn file_uri(path: &str) -> String {
    if path.starts_with("file://") {
        return path.to_string();
    }
    let abs = std::path::absolute(path).unwrap_or_else(|_| path.into());
    format!("file://{}", abs.to_string_lossy())
}

/// Wrap every `files:` entry on its rendered line in an OSC 8 hyperlink.
///
/// ratatui's [`Buffer::set_stringn`] strips control characters from span
/// content, so the escape sequences are spliced into the already-rendered
/// cells instead: the opening sequence is prepended to the first cell of each
/// path and the reset sequence appended to its last cell. The text between
/// them passes through untouched, keeping the visible layout identical. Both
/// spliced cells are forced to single-cell width
/// ([`CellDiffOption::ForcedWidth`]) so the render diff treats the escape
/// sequence as zero-width and does not skip the following path cells as the
/// trailing columns of a wide glyph. Entries truncated by the block's inner
/// width are skipped best-effort.
fn inject_files_hyperlinks(
    buf: &mut Buffer,
    area: Rect,
    line_index: usize,
    scroll_offset: u16,
    files: &[String],
) {
    let inner_top = area.top() + 1;
    let scrolled = line_index as i32 - scroll_offset as i32;
    if scrolled < 0 {
        return;
    }
    let y0 = inner_top + scrolled as u16;
    if y0 >= area.bottom() {
        return;
    }
    let (x0, inner_right) = (area.left() + 1, area.right().saturating_sub(1));
    let mut x = x0 + "files: ".len() as u16;
    for entry in files {
        if entry.is_empty() {
            continue;
        }
        let len = entry.chars().count() as u16;
        if x + len > inner_right {
            break;
        }
        let uri = file_uri(entry);
        let first = &mut buf[(x, y0)];
        first.set_symbol(&format!("{}{}", osc8_start(&uri), first.symbol()));
        first.set_diff_option(CellDiffOption::ForcedWidth(
            NonZeroU16::new(1).expect("one is non-zero"),
        ));
        let last = &mut buf[(x + len - 1, y0)];
        last.set_symbol(&format!("{}{}", last.symbol(), osc8_end()));
        last.set_diff_option(CellDiffOption::ForcedWidth(
            NonZeroU16::new(1).expect("one is non-zero"),
        ));
        x += len + 2; // `, ` separator
    }
}

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

    fn sample_issue() -> Issue {
        Issue {
            projects: None,
            id: None,
            number: 1,
            title: "Test Issue".into(),
            status: Status::new("todo"),
            labels: vec!["bug".into()],
            priority: Priority::High,
            assignee: Some("alice".into()),
            estimate: Some("2".into()),
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![crate::relationships::Relationship::new(
                1,
                12,
                crate::relationships::RelationKind::Related,
                "Twelve",
            )],
            related_issues: vec![],
            history: crate::model::History::new(),
            has_retired_links_key: false,
            time_entries: vec![],
            parent: None,
            series: None,
            health: None,
            files: vec!["openspec/changes/x/proposal.md".into()],
            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: "test.md".into(),
            body: "Line one\n\nLine two".into(),
            epics: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        }
    }

    /// Render a `DetailState` and return the pane's text.
    fn render_text(detail: &DetailState) -> String {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;
        let backend = TestBackend::new(120, 40);
        let mut terminal = Terminal::new(backend).unwrap();
        terminal
            .draw(|f| render(detail, f, f.area(), &crate::ui::color::Theme::default()))
            .unwrap();
        let buf = terminal.backend().buffer();
        buf.content()
            .iter()
            .map(|c| c.symbol())
            .collect::<Vec<_>>()
            .chunks(120)
            .map(|row| {
                row.iter()
                    .copied()
                    .collect::<String>()
                    .trim_end()
                    .to_string()
            })
            .collect::<Vec<_>>()
            .join("\n")
    }

    fn detail_with(
        relationships: Vec<crate::relationships::Relationship>,
        chain: crate::relationships::DependencyChain,
        blocked: Option<String>,
    ) -> DetailState {
        let issue = sample_issue();
        DetailState {
            health: None,
            health_diagnostics: Vec::new(),
            wip: None,
            category: None,
            // `sample_issue()` has no parent and no children, so the facts are the
            // empty ones. Read through the real reader rather than hand-constructed,
            // so a fixture cannot drift from the shape the renderer consumes.
            hierarchy: crate::commands::parent::facts_over(
                std::slice::from_ref(&issue),
                "done",
                issue.number,
            ),
            issue,
            relationships,
            chain,
            blocked,
            scroll_offset: 0,
            viewport: std::cell::Cell::new(0),
            max_scroll: std::cell::Cell::new(0),
            rel_cursor: 0,
            related: Vec::new(),
            related_cursor: 0,
            read_only: false,
            epics: Vec::new(),
            capacity: Vec::new(),
        }
    }

    /// The three cases T027 step 4 names, in one test so the *order* and the
    /// empty states are asserted against each other rather than in isolation.
    #[test]
    fn the_relationship_block_covers_a_blocks_edge_a_related_only_issue_and_the_empty_state() {
        // **A `blocks` edge.** The row carries the kind, the target, and the
        // display name — the three facts T027 step 1 names — and the blocked
        // state and chain are stated, not implied.
        let blocks = detail_with(
            vec![crate::relationships::Relationship::new(
                1,
                2,
                crate::relationships::RelationKind::Blocks,
                "Refactor store",
            )],
            no_chain(),
            Some("Blocked by #1 Ship the thing".to_string()),
        );
        let text = render_text(&blocks);
        assert!(text.contains("blocks #2 Refactor store"), "got:\n{text}");
        assert!(text.contains("blocked: Blocked by #1"), "got:\n{text}");
        assert!(text.contains("chain: none"), "got:\n{text}");

        // **Only `related` edges**, and an issue that is not blocked. A
        // relationship that merely *exists* must not be presented as blocking
        // anything — the whole point of the typed model.
        let related = detail_with(
            vec![crate::relationships::Relationship::new(
                1,
                3,
                crate::relationships::RelationKind::Related,
                "Notes",
            )],
            no_chain(),
            None,
        );
        let text = render_text(&related);
        assert!(text.contains("related #3 Notes"), "got:\n{text}");
        assert!(
            text.contains("blocked: not blocked"),
            "a `related` edge must not read as blocking: got:\n{text}"
        );
        assert!(
            !text.contains("blocked: related"),
            "and nothing may present a non-blocks edge as a blocker: got:\n{text}"
        );

        // **No relationships at all.** The empty state says so, rather than
        // leaving the reader to guess between "none" and "not computed".
        let empty = detail_with(vec![], no_chain(), None);
        let text = render_text(&empty);
        assert!(text.contains("blocked: not blocked"), "got:\n{text}");
        assert!(text.contains("chain: none"), "got:\n{text}");
        assert!(
            !text.contains("links: "),
            "an issue with no relationships has no links row: got:\n{text}"
        );
    }

    /// Field order is the same as `tix view --show relationships`:
    /// relationships, then chain, then blocked.
    ///
    /// Asserted by position rather than by presence, because presence alone would
    /// pass with any order — and the order is the part T027 step 2 constrains.
    #[test]
    fn the_relationship_block_is_ordered_like_the_cli_detail() {
        let mut chain = no_chain();
        chain.paths.push(vec![crate::relationships::ChainNode {
            number: 1,
            title: "Ship it".into(),
        }]);
        let text = render_text(&detail_with(
            vec![crate::relationships::Relationship::new(
                1,
                2,
                crate::relationships::RelationKind::Blocks,
                "Refactor store",
            )],
            chain,
            Some("Blocked by #3 Something".to_string()),
        ));
        let links = text.find("links: ").expect("a links row");
        let chain_at = text.find("chain: ").expect("a chain row");
        let blocked = text.find("blocked: ").expect("a blocked row");
        assert!(
            links < chain_at && chain_at < blocked,
            "relationships, then chain, then blocked — got:\n{text}"
        );
    }

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

        let backend = TestBackend::new(120, 40);
        let mut terminal = Terminal::new(backend).unwrap();
        // `sample_issue` owns its relationship, so a store-resolved set for it
        // is exactly its own stored field.
        let detail = DetailState {
            health: None,
            health_diagnostics: Vec::new(),
            wip: None,
            category: None,
            issue: sample_issue(),
            relationships: sample_issue().relationships,
            chain: no_chain(),
            blocked: None,
            // `sample_issue()` has no parent and no children, so the facts are the
            // empty ones. Built through the real reader rather than hand-constructed,
            // so a fixture cannot drift from the shape the renderer consumes.
            hierarchy: crate::commands::parent::facts_over(
                std::slice::from_ref(&sample_issue()),
                "done",
                sample_issue().number,
            ),
            scroll_offset: 0,
            viewport: std::cell::Cell::new(0),
            max_scroll: std::cell::Cell::new(0),
            rel_cursor: 0,
            related: Vec::new(),
            related_cursor: 0,
            read_only: false,
            epics: Vec::new(),
            capacity: Vec::new(),
        };
        terminal
            .draw(|f| render(&detail, f, f.area(), &crate::ui::color::Theme::default()))
            .unwrap();

        let buf = terminal.backend().buffer();
        let text: String = buf
            .content()
            .iter()
            .map(|c| c.symbol().to_string())
            .collect::<Vec<_>>()
            .join("");
        let link = hyperlink(
            &file_uri("openspec/changes/x/proposal.md"),
            "openspec/changes/x/proposal.md",
        );
        assert!(
            text.contains(&link),
            "files must render as an OSC 8 hyperlink to the resolved file"
        );
        assert!(text.contains("related #12 Twelve"), "got:\n{text}");
    }

    #[test]
    fn hyperlink_wraps_label_and_keeps_file_uris() {
        assert_eq!(
            hyperlink("file:///a/b.md", "b.md"),
            "\u{1b}]8;;file:///a/b.md\u{1b}\\b.md\u{1b}]8;;\u{1b}\\"
        );
        assert_eq!(file_uri("file:///already/abs.md"), "file:///already/abs.md");
        assert!(file_uri("openspec/x.md").starts_with("file:///"));
    }

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

        let backend = TestBackend::new(10, 5);
        let mut terminal = Terminal::new(backend).unwrap();
        // `sample_issue` owns its relationship, so a store-resolved set for it
        // is exactly its own stored field.
        let detail = DetailState {
            health: None,
            health_diagnostics: Vec::new(),
            wip: None,
            category: None,
            issue: sample_issue(),
            relationships: sample_issue().relationships,
            chain: no_chain(),
            blocked: None,
            // `sample_issue()` has no parent and no children, so the facts are the
            // empty ones. Built through the real reader rather than hand-constructed,
            // so a fixture cannot drift from the shape the renderer consumes.
            hierarchy: crate::commands::parent::facts_over(
                std::slice::from_ref(&sample_issue()),
                "done",
                sample_issue().number,
            ),
            scroll_offset: 0,
            viewport: std::cell::Cell::new(0),
            max_scroll: std::cell::Cell::new(0),
            rel_cursor: 0,
            related: Vec::new(),
            related_cursor: 0,
            read_only: false,
            epics: Vec::new(),
            capacity: Vec::new(),
        };
        terminal
            .draw(|f| render(&detail, f, f.area(), &crate::ui::color::Theme::default()))
            .unwrap();
    }

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

        let backend = TestBackend::new(80, 40);
        let mut terminal = Terminal::new(backend).unwrap();
        // `sample_issue` owns its relationship, so a store-resolved set for it
        // is exactly its own stored field.
        let detail = DetailState {
            health: None,
            health_diagnostics: Vec::new(),
            wip: None,
            category: None,
            issue: sample_issue(),
            relationships: sample_issue().relationships,
            chain: no_chain(),
            blocked: None,
            // `sample_issue()` has no parent and no children, so the facts are the
            // empty ones. Built through the real reader rather than hand-constructed,
            // so a fixture cannot drift from the shape the renderer consumes.
            hierarchy: crate::commands::parent::facts_over(
                std::slice::from_ref(&sample_issue()),
                "done",
                sample_issue().number,
            ),
            scroll_offset: 0,
            viewport: std::cell::Cell::new(0),
            max_scroll: std::cell::Cell::new(0),
            rel_cursor: 0,
            related: Vec::new(),
            related_cursor: 0,
            read_only: false,
            epics: Vec::new(),
            capacity: Vec::new(),
        };
        terminal
            .draw(|f| render(&detail, f, f.area(), &crate::ui::color::Theme::default()))
            .unwrap();
    }

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

        let backend = TestBackend::new(80, 10);
        let mut terminal = Terminal::new(backend).unwrap();
        // `sample_issue` owns its relationship, so a store-resolved set for it
        // is exactly its own stored field.
        let issue = sample_issue();
        let relationships = issue.relationships.clone();
        let detail = DetailState {
            health: None,
            health_diagnostics: Vec::new(),
            wip: None,
            category: None,
            hierarchy: crate::commands::parent::facts_over(
                std::slice::from_ref(&issue),
                "done",
                issue.number,
            ),
            issue,
            relationships,
            chain: no_chain(),
            blocked: None,
            scroll_offset: 5,
            viewport: std::cell::Cell::new(0),
            max_scroll: std::cell::Cell::new(0),
            rel_cursor: 0,
            related: Vec::new(),
            related_cursor: 0,
            read_only: false,
            epics: Vec::new(),
            capacity: Vec::new(),
        };
        terminal
            .draw(|f| render(&detail, f, f.area(), &crate::ui::color::Theme::default()))
            .unwrap();
    }

    /// tix #1513 T007: the `related:` block is drawn near the top (above the
    /// relationship row), carries a count, styles each entry as a chip, and marks
    /// the entry `o` will follow with a `>` — and is drawn at all only when the
    /// issue has `related_issues`.
    #[test]
    fn the_related_block_renders_a_count_chips_and_the_selection_marker() {
        let mut detail = detail_with(
            vec![crate::relationships::Relationship::new(
                1,
                2,
                crate::relationships::RelationKind::Related,
                "Twelve",
            )],
            no_chain(),
            None,
        );
        detail.related = crate::related::classify_all(&[
            "12".to_string(),
            "../other-repo/issues/2026-01-01-x.md".to_string(),
            "https://gitlab.com/foo/bar#7".to_string(),
        ]);
        detail.related_cursor = 1;
        let text = render_text(&detail);

        assert!(
            text.contains("related: 3"),
            "a count is drawn: got:\n{text}"
        );
        // Rows carry the block border, so a cell's text is the row with the border
        // and padding stripped.
        let cell = |line: &str| {
            line.trim_matches(|c: char| c == '│' || c == ' ')
                .to_string()
        };
        // Chips: the local selector, the relative path, and the URL.
        assert!(
            text.lines().any(|line| cell(line) == "12"),
            "the local chip is drawn: got:\n{text}"
        );
        assert!(
            text.lines()
                .any(|line| cell(line).contains("../other-repo/issues/2026-01-01-x.md")),
            "the path chip is drawn: got:\n{text}"
        );
        assert!(
            text.lines()
                .any(|line| cell(line).contains("https://gitlab.com/foo/bar#7")),
            "the URL chip is drawn: got:\n{text}"
        );
        // The `>` marker sits on the **selected** entry, and only on it.
        let selected = text
            .lines()
            .find(|line| cell(line).contains("../other-repo"))
            .expect("the selected line");
        assert!(
            cell(selected).starts_with("> "),
            "the selected related entry needs a marker: {selected:?}"
        );
        let first = text
            .lines()
            .find(|line| cell(line) == "12")
            .expect("the first line");
        assert!(
            !cell(first).contains('>'),
            "unselected related entries carry no marker: {first:?}"
        );
        // "Near the top, before the relationship row" — asserted by position.
        let related_at = text.find("related: 3").expect("the related block");
        let links_at = text.find("links: ").expect("the relationship row");
        assert!(
            related_at < links_at,
            "the related block must precede the links row: got:\n{text}"
        );

        // Absent when there is nothing to show: no empty heading on every issue.
        let empty = detail_with(vec![], no_chain(), None);
        let empty_text = render_text(&empty);
        assert!(
            !empty_text.contains("related:"),
            "an issue with no related_issues must draw no block: got:\n{empty_text}"
        );
    }

    #[test]
    fn assignee_render_identity_verbatim_bare_gets_at() {
        assert_eq!(render_assignee(None), None);
        assert_eq!(
            render_assignee(Some("Herbert Maschke <thyseus@pm.me>")),
            Some("Herbert Maschke <thyseus@pm.me>".to_string())
        );
        assert_eq!(render_assignee(Some("alice")), Some("@alice".to_string()));
        assert_eq!(render_assignee(Some("@alice")), Some("@alice".to_string()));
    }

    // ---- WP04 T019: the epic block and direct issue navigation --------------

    /// The canonical rows the CLI prints, as `App::detail_state_for` fills them.
    fn epic_entry(heading: &str, detail: &[&str]) -> crate::commands::view::EpicBlockEntry {
        crate::commands::view::EpicBlockEntry {
            heading: heading.to_string(),
            detail: detail.iter().map(|line| (*line).to_string()).collect(),
        }
    }

    #[test]
    fn t019_the_pane_renders_the_canonical_epic_rows_and_the_navigation_affordance() {
        let mut detail = detail_with(vec![], no_chain(), None);
        detail.epics = vec![epic_entry(
            "Alpha (e-aaa111)",
            &[
                "progress: 1/2 done",
                "weighted progress: 2/2 (100%)",
                "children: 1",
                "blocked: 0",
            ],
        )];
        let text = render_text(&detail);
        assert!(text.contains("epics:"), "{text}");
        assert!(text.contains("Alpha (e-aaa111)"), "{text}");
        assert!(
            text.contains("progress: 1/2 done"),
            "the pane renders the same facts as `tix show`: {text}"
        );
        assert!(text.contains("weighted progress: 2/2 (100%)"), "{text}");
        assert!(
            text.contains("members open directly from the epic view"),
            "the direct issue navigation affordance is explicit (FR-004): {text}"
        );
    }

    #[test]
    fn t019_an_issue_in_no_epic_draws_no_epic_heading() {
        let detail = detail_with(vec![], no_chain(), None);
        let text = render_text(&detail);
        assert!(
            !text.contains("epics:"),
            "an empty reference list is the empty state, not an empty heading: {text}"
        );
    }

    #[test]
    fn t019_a_missing_epic_reference_is_rendered_with_its_id_and_reason() {
        let mut detail = detail_with(vec![], no_chain(), None);
        detail.epics = vec![epic_entry(
            "e-gone1 (missing reference)",
            &[
                "issue #5 records epic reference `e-gone1`, which is not in the registry \
               (the reference is kept so it can be repaired)",
            ],
        )];
        let text = render_text(&detail);
        assert!(
            text.contains("e-gone1 (missing reference)"),
            "a missing reference is named, not dropped (C-005): {text}"
        );
        assert!(text.contains("not in the registry"), "{text}");
    }
}