lattice_ui_tui/

render.rs

//! Frame rendering. Pure where it can be (line composition is testable);
//! IO-bound where ratatui needs it (`draw_frame` accepting a `Frame`).
//!
//! Layout:
//!
//! +----------------------------------------------------------------+
//! | gutter | buffer text                                           |
//! | gutter | buffer text                                           |
//! | ...                                                            |
//! +----------------------------------------------------------------+
//! | mode line: NOR  path                       line:col   lang     |
//! +----------------------------------------------------------------+

use std::sync::Arc;

use ratatui::Frame;
use ratatui::layout::{Constraint, Direction, Layout, Rect};
use ratatui::style::{Color, Modifier, Style as TuiStyle};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Borders, Clear, Paragraph, Wrap};

use lattice_grammar::{ModalState, SearchDirection};
use lattice_lsp::{Diagnostic as LspDiagnostic, DiagnosticSeverity};
use lattice_protocol::position::Range as ProtoRange;
// 5.8.P: `VisualMode` reads now live host-side via
// `Editor::visual_selection_range`; this peer no longer references
// the variants directly.
use lattice_runtime::DocumentSnapshot;

use crate::app::{App, EchoLevel, Fold};

/// Per-render-chain snapshot of App state the renderer reads.
///
/// Audit slice 7 / M2. The renderer is one of multiple peer
/// renderer implementations (TUI today, GPUI as part of 1.0,
/// future WebRenderer). The architecture is renderer-agnostic:
/// no render path may depend on single-threaded discipline as
/// its safety mechanism, because GPUI runs on a separate
/// thread from the App's input loop.
///
/// `FrameView` is taken once at entry to each render chain
/// (`compose_visible_lines`, `draw_inactive_document`) and
/// threaded into the chain's helpers. Internal reads then go
/// through immutable Arc-shared / by-value snapshots; an async
/// mutator that writes the underlying App fields can no longer
/// produce a torn mid-render view, regardless of which thread
/// the renderer runs on.
///
/// Fields:
/// - `app: &App` -- stable App fields (cursor, modal,
///   command_line, picker, ...) that don't mutate during a
///   render pass even under multi-thread rendering. Read
///   directly through this borrowed reference.
/// - `folds: Arc<[Fold]>` -- frozen snapshot. Replaces direct
///   `app.editor.folds.iter()` reads.
/// - `show_line_numbers: bool` -- cached typed-options value.
///   The typed-options ArcSwap read is wait-free per call, but
///   caching once per chain keeps gutter computation
///   deterministic if the option flips mid-chain under
///   multi-thread input.
///
/// `app.editor.lsp_diagnostics` is left as a borrowed
/// `&DiagnosticsLayer` because that layer is already wait-free
/// behind its own `ArcSwap` (audit slice 2); the existing
/// `line_severity` / `diagnostics_on_line` API is structurally
/// safe to call from any thread.
pub struct FrameView<'a> {
    pub app: &'a App,
    pub folds: Arc<[Fold]>,
    // display-line B4.2: the `visible_rows` field (worker-published
    // pre-paint rows) was deleted. The TUI document body migrated to
    // the canonical `DisplayMatrix` (B2.4); markdown / help / messages
    // bodies read their own sources. Nothing in the compose chain read
    // this field any more — it was constructed but never consumed.
    pub show_line_numbers: bool,
    /// M.4: resolved per-pane in `for_buffer`; tracks the active
    /// buffer's setting in `from_app`. Reading this through the
    /// view lets per-pane render paths route consistently.
    pub relative_line_numbers: bool,
    /// Slice 3c.extension.fold-rs: cache `foldenable` at view
    /// construction. Prior to this, `view.line_inside_closed_fold`
    /// and friends called `self.app.foldenable()` per line, each
    /// triggering an actor mailbox round-trip (~µs–tens-of-µs).
    /// One pre-cached bool per frame replaces 120+ RPCs in the
    /// compose loop.
    pub foldenable: bool,
    /// Perf plan C: O(log folds) lookup index built once per frame
    /// from `folds + foldenable`. The compose loop's per-line
    /// `line_inside_closed_fold` check used to walk every fold per
    /// row (`iter().any(...)` — O(rows × folds)); via this index it
    /// becomes a partition-point binary search with a constant-time
    /// fast path for the common non-overlapping case.
    pub fold_index: lattice_host::folds::FoldIndex,
    /// Fold-bleed follow-up (2026-06-30): this pane's OWN byte-baked
    /// inlay-hint rows, resolved via `RenderState::inlay_hints_for_buffer`
    /// (active → baked `syntax.inlay_hints`; inactive → published
    /// `cells.panes` entry). One source for both focus states so the
    /// compose loop splices hints through a single path — no
    /// active-vs-inactive divergence to drift.
    pub inlay_hints: Arc<[lattice_host::render_state::InlayHintRow]>,
    /// Slice 3c.extension.fold-rs: per-frame LSP-mode gates,
    /// cached once at `FrameView::from_app` so the compose loop's
    /// per-line decoration checks don't pay actor-RPC cost. Each
    /// is one `read_editor` at frame entry; a 120-row paint that
    /// previously triggered 120× per-line RPC for
    /// `app.lsp_semantic_tokens_mode_enabled_for(...)` now reads
    /// `view.lsp_semantic_tokens_enabled` directly.
    pub lsp_mode_enabled: bool,
    pub lsp_diagnostics_enabled: bool,
    pub lsp_semantic_tokens_enabled: bool,
    pub lsp_document_highlight_enabled: bool,
    /// Slice A.2b.2: inlay-hint mode gate moved to publish-time
    /// (`Editor::build_active_inlay_hints` returns an empty list
    /// when the mode is off). The compose loop no longer reads
    /// this field; `rs.syntax.inlay_hints` is already gated, so
    /// `is_empty()` on the published list is the cheap fast-path
    /// check.
    pub lsp_progress_enabled: bool,
    /// Whether soft-wrap is enabled for this pane's buffer. Global
    /// option today (`option_cache.wrap_lines`); the seam for
    /// per-buffer options: when buffer-local options land,
    /// `for_buffer` resolves from that buffer's local value with
    /// the global default as fallback (emacs buffer-local pattern).
    /// Compose paths read `view.wrap_lines` instead of touching
    /// `app.ad().option_cache` directly so the resolver is always
    /// in one place.
    pub wrap_lines: bool,
    /// PU.1b-1a (`signcolumn`): whether to reserve this pane's gutter
    /// sign columns (diagnostics severity + diff sign). Resolved
    /// per-buffer like every other view option — `from_app` reads the
    /// active buffer's `option_cache.sign_column`; `for_buffer` reads
    /// `app.sign_column_for(buffer_id)`. The compose path reserves the
    /// two sign cells iff this is `true`, so a buffer with
    /// `signcolumn=no` (help-mode, synthetic buffers) renders
    /// gutterless without the renderer knowing it's help.
    pub sign_column: bool,
    /// DB.4: extra leading gutter cells to horizontally centre the buffer's
    /// content (dashboard). Added to the computed gutter width for both
    /// document lines and virtual rows, so content + cursor shift right. `0`
    /// for every non-centred buffer.
    pub content_left_pad: u32,
}

impl<'a> FrameView<'a> {
    /// Snapshot the App's per-render-chain state once.
    ///
    /// `Arc::from(Vec<T>)` is one alloc + a memcpy of the
    /// slice metadata; the underlying span / fold data already
    /// lives in heap-allocated vecs, so the snapshot cost is
    /// O(folds.len() + viewport_height) -- negligible at
    /// terminal sizes. GPUI-era multi-thread rendering can call
    /// this from the render thread without taking any App
    /// lock; the App's main loop owns the underlying vecs and
    /// the snapshot is consistent at the moment `from_app` runs.
    pub fn from_app(app: &'a App) -> Self {
        // display-line B4.2: the worker-published pre-paint rows the
        // `FrameView` used to snapshot here were deleted with the
        // overlay worker's span/row cache. The TUI document body reads
        // the canonical `DisplayMatrix` (B2.4) directly in the compose
        // loop; nothing on `FrameView` consumed the prepaint rows.
        let rs = app.render_state.load_full();
        // Slice 3c.extension.fold-rs: pre-cache per-frame option +
        // mode-gate reads. One `read_editor` each at frame entry
        // (~7 RPCs total per frame) replaces N actor RPCs in the
        // per-line compose loop. The active document id is needed
        // for the mode-gate checks.
        let doc_id = rs.active_document.load().document_buffer_id;
        // Perf plan C: build the index once per frame from the same
        // snapshot the renderer reads. Both peers go through this
        // path now; build cost is O(folds) (<1 µs for typical files).
        // Fold-bleed fix (2026-06-30): route through `folds_for_buffer`
        // (the active doc returns its live `self.folds`) so the active
        // and inactive (`for_buffer`) pane paths share ONE per-buffer
        // fold source — no drift between them or the GPUI peer.
        let (folds, foldenable) = rs.folds_for_buffer(doc_id);
        let fold_index = lattice_host::folds::FoldIndex::from_folds(&folds, foldenable);
        let inlay_hints = rs.inlay_hints_for_buffer(doc_id);
        // Snapshot ad() once so wrap_lines and sign_column come from
        // the same atomic snapshot as the outer RenderState.
        let ad = rs.active_document.load();
        Self {
            app,
            folds,
            inlay_hints,
            show_line_numbers: app.show_line_numbers(),
            relative_line_numbers: app.relative_line_numbers(),
            foldenable,
            fold_index,
            lsp_mode_enabled: app.lsp_mode_enabled_for(doc_id),
            lsp_diagnostics_enabled: app.lsp_diagnostics_mode_enabled_for(doc_id),
            lsp_semantic_tokens_enabled: app.lsp_semantic_tokens_mode_enabled_for(doc_id),
            lsp_document_highlight_enabled: app.lsp_document_highlight_mode_enabled_for(doc_id),
            lsp_progress_enabled: app.lsp_progress_mode_enabled_for(doc_id),
            wrap_lines: ad.option_cache.wrap_lines,
            sign_column: ad.option_cache.sign_column,
            content_left_pad: ad.option_cache.content_left_pad,
        }
    }

    /// M.4: per-pane FrameView -- resolves options for `buffer_id`
    /// instead of capturing the active buffer's settings. Used by
    /// inactive-pane render paths so each pane's mode stack drives
    /// its own gutter independently.
    /// DR.2: inactive panes now source decorations from their own
    /// per-pane `DisplayMatrix`; `pane_highlights` is retired.
    pub fn for_buffer(app: &'a App, buffer_id: crate::buffers::BufferId) -> Self {
        // display-line B4.2: same as `from_app` — the deleted
        // prepaint-rows cell is no longer snapshotted here.
        let rs = app.render_state.load_full();
        // Fold-bleed fix (2026-06-30): resolve folds from THIS pane's
        // buffer, not the active doc. Previously this snapshot was
        // doc-scoped (`active_document.folds`), so an inactive pane
        // showing a different buffer rendered with the active buffer's
        // folds and dropped its own. `folds_for_buffer` returns the
        // per-buffer list (+ its `foldenable`). Shared with the GPUI peer.
        let (folds, foldenable) = rs.folds_for_buffer(buffer_id);
        let fold_index = lattice_host::folds::FoldIndex::from_folds(&folds, foldenable);
        let inlay_hints = rs.inlay_hints_for_buffer(buffer_id);
        // PI.0: content-centring pad follows the *rendered* buffer's
        // `CenterContentWidth` local + its pane's width, not the
        // active-buffer identity — so a pane keeps its centring even when
        // `document_buffer_id` points elsewhere (e.g. during a picker
        // preview that swapped the active buffer to the previewed file).
        let content_left_pad = rs.content_left_pad_for(buffer_id);
        Self {
            app,
            folds,
            inlay_hints,
            content_left_pad,
            // PI.4: resolved from the PUBLISHED per-buffer snapshot, not
            // through `App::resolved_option` — that routes via `read_editor`,
            // so the four option reads here were four actor-seam calls per
            // pane per frame. The active path never paid them (it read the
            // hot-path `option_cache`), which is exactly why the guard on
            // `compose_visible_lines` never caught it: it only watched the
            // path that was already clean. Same seam the GPUI peer uses.
            show_line_numbers: *rs.resolved_option_for::<lattice_config::Number>(buffer_id),
            relative_line_numbers: *rs
                .resolved_option_for::<lattice_config::RelativeNumber>(buffer_id),
            // Slice 3c.extension.fold-rs: per-buffer cache. The
            // mode gates resolve against `buffer_id` (the pane's
            // buffer, possibly different from the active doc).
            foldenable,
            fold_index,
            lsp_mode_enabled: app.lsp_mode_enabled_for(buffer_id),
            lsp_diagnostics_enabled: app.lsp_diagnostics_mode_enabled_for(buffer_id),
            lsp_semantic_tokens_enabled: app.lsp_semantic_tokens_mode_enabled_for(buffer_id),
            lsp_document_highlight_enabled: app.lsp_document_highlight_mode_enabled_for(buffer_id),
            lsp_progress_enabled: app.lsp_progress_mode_enabled_for(buffer_id),
            // PU.1b-1a: wrap + signcolumn resolve per-buffer (the
            // emacs buffer-local pattern) so an inactive pane reflects
            // ITS mode stack — e.g. help-mode's `Wrap = true` /
            // `signcolumn = no` — not the active buffer's settings.
            wrap_lines: *rs.resolved_option_for::<lattice_config::Wrap>(buffer_id),
            sign_column: rs
                .resolved_option_for::<lattice_config::SignColumnOption>(buffer_id)
                .reserved(),
        }
    }

    /// Mirror of [`App::fold_start_at_any`] but reads from the
    /// frozen `view.folds` snapshot instead of `app.editor.folds`.
    /// Used by the gutter glyph provider so the renderer's view
    /// of folds can't go out of sync with the snapshot it took
    /// at chain entry.
    pub fn fold_start_at_any(&self, line: u32) -> Option<&Fold> {
        if !self.foldenable {
            return None;
        }
        self.folds.iter().find(|f| f.start_line == line)
    }

    /// Mirror of [`App::fold_start_at`] -- only matches CLOSED
    /// folds at `line`. Reads from the frozen `view.folds`
    /// snapshot.
    pub fn fold_start_at(&self, line: u32) -> Option<&Fold> {
        if !self.foldenable {
            return None;
        }
        self.folds.iter().find(|f| f.closed && f.start_line == line)
    }

    /// Mirror of [`App::line_inside_closed_fold`] reading from
    /// the snapshot.
    ///
    /// Perf plan C: routes through the per-frame
    /// [`lattice_host::folds::FoldIndex`] so the per-line cost in
    /// compose loops drops from O(folds) to O(log folds) amortized
    /// constant. The `foldenable` short-circuit is baked into the
    /// index at construction time — no extra branch here.
    pub fn line_inside_closed_fold(&self, line: u32) -> bool {
        self.fold_index.line_inside_closed_fold(line)
    }
}

// DR.2 (decoration-retention): `source_spans_from_runs` (the
// inactive-pane fallback that derived `StyledSpan`s from the worker's
// `RowPrepaint.runs`) was retired with the `pane_highlights` path.
// Inactive panes now read the per-pane `DisplayMatrix` like the active
// pane.

/// Render one terminal frame.
///
/// `snap` is the active document's snapshot, loaded once per frame
/// by the runtime via `app.editor.snapshot_cache.load_arc()` (DESIGN.md
/// §5.6.8). All active-pane render paths read through this single
/// snapshot -- inactive panes (different documents) still go
/// through `entry.handle.snapshot()` since the cache is per-cell.
///
/// ## Per-render-chain stability (audit slice 7 / M2)
///
/// The renderer is one of multiple peer renderer implementations
/// (TUI today; GPUI as part of 1.0; future WebRenderer). The
/// architecture is renderer-agnostic: render paths must NOT depend
/// on single-threaded discipline as their safety mechanism,
/// because GPUI runs on a separate thread from the App's input
/// loop. Each render chain (`compose_visible_lines`,
/// `draw_inactive_document`) takes a [`FrameView`] at entry and
/// threads it into its helpers; reads of `folds`,
/// `visible_highlights`, and `show_line_numbers` go through that
/// snapshot rather than the live App fields. `lsp_diagnostics`
/// stays wait-free behind its own `ArcSwap` (audit slice 2).
/// WK.12: how many rows the minibuffer band claims — its content, capped at
/// half the body so an advisory hint can never swallow the buffer it describes
/// (the same cap the pane-bottom popup carried). `0` when no band is open.
pub(crate) fn band_row_count(app: &crate::app::App, body_height: u16) -> u16 {
    let Some(id) = app.band().buffer_id else {
        return 0;
    };
    let Some(handle) = app.buffers().registry.document_handle(id) else {
        return 0;
    };
    let lines = handle.snapshot().buffer.content_line_count() as u16;
    lines.min((body_height / 2).max(1))
}

/// WK.12: the band's inner `(rows, cols)` for the host's cells worker — the
/// peer of [`popup_feedback_inner_dims`]. Without this hand-off
/// `build_cells_panes` never sizes `PaneId::MINIBUFFER_BAND` and the band
/// paints nothing at all.
pub fn band_feedback_inner_dims(
    app: &crate::app::App,
    terminal_width: u16,
    buffer_height: u32,
) -> Option<(u32, u32)> {
    let rows = band_row_count(app, buffer_height.min(u16::MAX as u32) as u16);
    (rows > 0).then(|| (rows as u32, terminal_width.max(1) as u32))
}

/// WK.12: paint the minibuffer band — which-key's grid today. Borderless and
/// full width: it is a strip of the frame, not a floating box, and it never
/// takes focus, so no cursor is placed inside it and no interaction overlay
/// (hlsearch, current line) applies.
fn draw_minibuffer_band(
    frame: &mut ratatui::Frame,
    area: ratatui::layout::Rect,
    app: &crate::app::App,
) {
    let Some(band_id) = app.band().buffer_id else {
        return;
    };
    let Some(handle) = app.buffers().registry.document_handle(band_id) else {
        return;
    };
    let content_snap = handle.snapshot();
    let view = FrameView::for_buffer(app, band_id);
    let ctx = PaneComposeCtx {
        is_active: false,
        pane_id: lattice_core::ui::pane::PaneId::MINIBUFFER_BAND,
        buffer_id: band_id,
        cursor_line: 0,
        cursor_line_highlight: false,
        scroll: 0,
        leftcol: 0,
        // A band shows a grid, never a file: no gutter.
        display_line_numbers: None,
    };
    let lines = compose_pane_lines(
        &view,
        &content_snap,
        area.height as u32,
        area.width as u32,
        &ctx,
    );
    frame.render_widget(ratatui::widgets::Paragraph::new(lines), area);
}

/// Returns the completion-docs side popup's inner `(rows, cols)` when it is
/// shown this frame (PU.5c) — `None` otherwise. The runtime loop feeds this
/// back via `App::set_completion_docs_viewport` so `build_cells_panes` sizes
/// the `PaneId::COMPLETION_DOCS` matrix. Computed at the exact draw site
/// (with the real `chunks[1]` buffer area) because the docs popup is
/// cursor-anchored — position-dependent, unlike the floating popup whose
/// geometry the runtime reconstructs (`popup_feedback_inner_dims`).
#[must_use]
pub fn draw_frame(frame: &mut Frame, app: &App, snap: &DocumentSnapshot) -> Option<(u32, u32)> {
    // ML.4: last frame's click regions describe a layout that is about
    // to be overwritten. Clearing here rather than in the modeline
    // painter is what makes a pane that stops painting a modeline
    // (closed split, full-screen popup) stop being clickable too.
    app.modeline_hits.borrow_mut().clear();
    // MO.2: same contract as the modeline map above — last frame's pane
    // rects describe a layout about to be overwritten, and clearing here
    // is what makes a pane that stops painting (closed split) stop taking
    // clicks.
    app.pane_hits.borrow_mut().clear();
    // Vertico-style layout (DESIGN.md §5.11.3, §5.9.7): when the
    // cmdline completion popup OR the picker is open in
    // minibuffer mode, an extra row band sits below the cmdline
    // holding the candidate list. The selected candidate sits
    // visually adjacent to the prompt (above for completion,
    // below for picker), alternatives fanning away. Without
    // either open the layout is the standard
    // buffer / mode-line / cmdline three.
    //
    // Picker takes precedence over completion when both are open
    // (only one is reachable interactively at a time, but the
    // ordering matters for layout sizing).
    //
    // `picker.display` (config) selects whether the picker uses
    // this minibuffer-anchored layout or a centred popup overlay
    // floating over the buffer. Default `"minibuffer"`. In
    // `"popup"` mode the picker does NOT claim the cmdline row
    // and does NOT allocate an extra band -- the centered
    // overlay is drawn on top of the buffer area instead.
    let picker_is_minibuffer = picker_display_is_minibuffer(app);
    // `chrome_rows` is the single source of truth for tabline + candidate-
    // band rows, shared with the runtime loop's viewport/pane-rect push
    // (see its doc comment) — this and that push can no longer diverge.
    let chrome = chrome_rows(app);
    let extra_rows = chrome.extra();

    // Issue #29 (2026-05-22): tabline row at the top. Visibility
    // is resolved by the publisher (`build_tabs_render_state`)
    // based on `tabline.show` × tabs.len().
    let tabline_rows: u16 = chrome.tabline;
    let tabline_visible = tabline_rows > 0;

    // MO.4.b / Option-A: global modeline removed. Each pane owns its
    // own 1-row status footer (drawn by draw_panes / draw_pane_status_line).
    // MB.2: the `:` line grows into a multi-row mini-buffer band when
    // expanded (`<C-x><C-e>`), pushing the panes (and their mode-lines) up.
    // MB.2e: the `command-line.expand-height` option sizes it (`half`
    // default / `full` / fixed rows), resolved against the live frame
    // height. The band claims rows from the `Min(1)` pane area above it.
    let cmdline_rows: u16 = if app.command_line_expanded() {
        let base = app.command_line_expand_height().rows(frame.area().height);
        // When the completion popup is open inside the expanded band,
        // deduct its rows from the band height so candidates sit flush
        // against the cursor instead of at the very bottom of the frame.
        let completion_rows = app
            .completion()
            .state
            .as_deref()
            .map(|s| popup_height(s.candidates.len()))
            .unwrap_or(0) as u16;
        base.saturating_sub(completion_rows).max(1)
    } else {
        1
    };
    // Layout: tabline (0/1) | panes (Min) | cmdline (1..=band) | candidates (opt).
    let constraints: Vec<Constraint> = if extra_rows > 0 {
        vec![
            Constraint::Length(tabline_rows),      // tabline (0 or 1)
            Constraint::Min(1),                    // panes (each carries its own status row)
            Constraint::Length(cmdline_rows),      // cmdline / picker query / expanded band
            Constraint::Length(extra_rows as u16), // candidate list (bottom)
        ]
    } else {
        vec![
            Constraint::Length(tabline_rows),
            Constraint::Min(1),
            Constraint::Length(cmdline_rows),
        ]
    };
    let chunks = Layout::default()
        .direction(Direction::Vertical)
        .constraints(constraints)
        .split(frame.area());

    // chunks[0] = tabline (0-height when hidden),
    // chunks[1] = pane area, chunks[2] = cmdline, chunks[3] = candidates.
    if tabline_visible {
        draw_tabline(frame, chunks[0], app);
    }
    // WK.12: the minibuffer band claims rows from the BOTTOM of the pane area —
    // below every pane, directly above the `:` line. Carved out here rather
    // than added as a layout constraint so the `chunks[N]` indices below keep
    // their meaning; everything that paints over the panes gets `body`, so the
    // band is never overdrawn and never overdraws a popup.
    let band_rows = band_row_count(app, chunks[1].height);
    let body = ratatui::layout::Rect {
        height: chunks[1].height.saturating_sub(band_rows),
        ..chunks[1]
    };
    draw_panes(frame, body, app, snap);
    if band_rows > 0 {
        let band_area = ratatui::layout::Rect {
            y: chunks[1].y + body.height,
            height: band_rows,
            ..chunks[1]
        };
        draw_minibuffer_band(frame, band_area, app);
    }
    // Picker query claims the cmdline row only in minibuffer
    // mode. In popup mode the cmdline / echo content stays
    // visible and the picker query renders inside the overlay
    // instead. Fold audit fix: a transient in minibuffer mode gets
    // its title here (the same row a regular picker's prompt uses),
    // exactly like every other picker surface — it used to force
    // the popup overlay unconditionally, ignoring `picker.display`.
    if app.picker_state().state.is_some() && picker_is_minibuffer {
        let picker = app.picker_state();
        let is_transient = picker
            .state
            .as_deref()
            .is_some_and(|p| p.transient.is_some());
        if is_transient {
            draw_transient_minibuffer_prompt(frame, chunks[2], app);
        } else {
            draw_picker_prompt(frame, chunks[2], app);
        }
    } else {
        draw_command_or_echo(frame, chunks[2], app);
    }
    // Help popup overlay -- painted whenever a popup_buffer is
    // set AND the active pane isn't already showing it as an
    // in-pane buffer (the in-pane case is handled by the Help
    // arm of `draw_panes`). Two scenarios trigger this:
    // - **State A** (active = Document, popup_buffer = Some):
    //   first `K` shown the popup, focus is still on the doc;
    //   doc paints normally below, popup floats on top, no
    //   cursor inside the popup.
    // - **State B** (active = Help via popup mode, pane.buffer =
    //   Document): second `K` moved focus into the popup; popup
    //   paints with a visible cursor at `app.editor.cursor`; doc paints
    //   as inactive (frozen at `pane.cursor`) below.
    // Slice 3c.final.B (group 1): pane-tree reads route through
    // `app.panes()` instead of `app.editor.pane_tree.X()`.
    let active_pane_kind = app.panes().tree.active().buffer;
    if app.popup().is_open() && active_pane_kind != crate::buffers::BufferKind::Help {
        draw_help_overlay(frame, body, app, snap);
    }
    // Picker candidate list (precedence over completion popup --
    // only one is interactive at a time). Only the minibuffer
    // display mode uses the bottom band; the popup mode draws
    // its own self-contained overlay below. Fold audit fix: a
    // transient's item list now uses this same band in minibuffer
    // mode (`draw_transient_minibuffer_candidates`), instead of
    // being excluded from it entirely and forced into the popup box.
    let is_transient = app
        .picker_state()
        .state
        .as_deref()
        .is_some_and(|p| p.transient.is_some());
    if chrome.picker > 0 && is_transient {
        draw_transient_minibuffer_candidates(frame, chunks[3], app);
    } else if chrome.picker > 0 {
        draw_picker_candidates(frame, chunks[3], app);
    } else if chrome.completion > 0 {
        draw_completion_popup(frame, chunks[3], app);
    }
    // Picker popup overlay -- only drawn when `picker.display` is
    // `"popup"` and a picker is open. Floats centered over the
    // buffer area (chunks[0]) so the user still sees the mode line
    // and any echo / cmdline content underneath. Fold audit fix:
    // this used to draw the transient overlay unconditionally
    // (`|| ...transient.is_some()`) regardless of `picker_is_minibuffer`
    // — a transient in minibuffer mode got BOTH the minibuffer strip
    // above AND this popup, or effectively always the popup since the
    // strip path never ran. Now it follows the exact same
    // `!picker_is_minibuffer` gate every other picker surface uses.
    let picker_state = app.picker_state();
    if picker_state.state.is_some() && !picker_is_minibuffer {
        let p = picker_state.state.as_deref().unwrap();
        if p.transient.is_some() {
            draw_transient_overlay(frame, body, app);
        } else {
            draw_picker_overlay(frame, body, app);
        }
    }
    // NOTIF.1b: painted after every other overlay so a picker or a
    // transient cannot cover it — a notification hidden exactly when
    // the user is busy is the case it exists for.
    draw_notifications(frame, body, app);
    // Slice 3c.gpui-cmdline-completion: cmdline-completion popup
    // overlay. Mutually exclusive with the picker (picker doesn't
    // open during `:` typing).
    if !picker_is_minibuffer
        && app
            .completion()
            .state
            .as_deref()
            .is_some_and(|s| !s.candidates.is_empty())
    {
        draw_completion_overlay(frame, body, app);
    }
    // Insert-mode completion popup overlay (Phase 4.2.g.1).
    // Anchored at the cursor; floats over the buffer; doesn't
    // claim the cmdline row (so echoes can still appear).
    // Painted last so it sits on top of any pane-area widgets.
    let mut completion_docs_dims: Option<(u32, u32)> = None;
    if app.completion_popup_active() {
        draw_insert_completion_popup(frame, body, app, snap);
        // Side documentation popup (Phase 4.2.g.3) -- only
        // rendered when the user has flipped it on with
        // `<C-d>`. Anchored right of the candidate popup
        // when there's room; below otherwise.
        if let Some(state) = app.completion().insert.as_deref()
            && state.doc_popup.is_some()
        {
            draw_insert_completion_docs_popup(frame, body, app, snap);
            // PU.5c: feed the docs popup's inner geometry back to the host
            // (computed here with the exact `chunks[1]` it painted into).
            completion_docs_dims = completion_docs_feedback_inner_dims(app, snap, chunks[1]);
        }
    }
    completion_docs_dims
}

/// Issue #29 (2026-05-22): paint the tabline row. Reads the
/// published `TabsRenderState` (labels + active idx) and
/// renders ` [N] {label} ` per tab, brightening the active
/// one with `cursor_background` / `cursor_foreground`. Lines
/// truncate horizontally at the area's right edge — overflow
/// disappears (real vim does the same).
fn draw_tabline(frame: &mut Frame, area: Rect, app: &App) {
    use ratatui::text::{Line, Span};
    use ratatui::widgets::Paragraph;
    let tabs = app.render_state.load().tabs.clone();
    let active_style = app.theme.pane_status_active;
    let inactive_style = app.theme.pane_status_inactive;
    let mut spans: Vec<Span<'static>> = Vec::with_capacity(tabs.items.len() * 2);
    for (idx, item) in tabs.items.iter().enumerate() {
        let label = item.tabline_text(idx);
        let style = if idx == tabs.active {
            active_style
        } else {
            inactive_style
        };
        spans.push(Span::styled(label, style));
        // Separator between tabs (only between, not trailing).
        if idx + 1 < tabs.items.len() {
            spans.push(Span::styled(" ".to_string(), inactive_style));
        }
    }
    let line = Line::from(spans);
    frame.render_widget(Paragraph::new(line), area);
}

/// Total rows the popup occupies (no borders -- vertico-style;
/// matches the picker's candidate-list shape) capped so it
/// never dominates the screen.
/// The picker / completion candidate-band budget.
///
/// A picker is *filtered* — you type to narrow — so ten rows is
/// plenty. Transients are different (see [`transient_popup_height`]).
const PICKER_MAX_ROWS: usize = 10;

fn popup_height(candidate_count: usize) -> usize {
    popup_height_capped(candidate_count, PICKER_MAX_ROWS)
}

/// MG.41b: the same clamp with a caller-supplied maximum.
fn popup_height_capped(candidate_count: usize, max_rows: usize) -> usize {
    candidate_count.min(max_rows.max(1)).max(1)
}

/// MG.41b: a transient's row budget, from `ui.transient.max-rows`.
///
/// Transients are *browsed*, not filtered: you read the menu to find
/// the key, so the picker's ten-row budget showed under half of the
/// 25-row magit dispatch. Falls back to the compiled default when the
/// registry is unpopulated (boot-before-linkme and test fixtures,
/// mirroring `command_line_expand_height`).
fn transient_max_rows(app: &App) -> usize {
    // Published options sub-state — a wait-free Arc clone, no actor
    // round-trip, same as `picker_display_is_minibuffer`. This runs in
    // the per-frame layout path, so an actor hop here would be a
    // paramount-#1 violation.
    app.options()
        .config
        .get_typed::<lattice_config::TransientMaxRows>()
        .map(|arc| *arc)
        .unwrap_or(20)
        .max(1) as usize
}

/// Rows outside the buffer area: the tabline (0/1) and the picker/
/// completion candidate band (0 when neither is open, or when
/// `picker.display = "popup"` floats it over the buffer instead of
/// claiming a strip).
pub(crate) struct ChromeRows {
    pub tabline: u16,
    pub picker: u16,
    pub completion: u16,
}

impl ChromeRows {
    /// The candidate-band height: picker takes precedence when both are
    /// open (only one is interactively reachable at a time).
    pub fn extra(&self) -> u16 {
        self.picker.max(self.completion)
    }
}

/// SINGLE source of truth for [`ChromeRows`]. Before this existed,
/// `draw_frame`'s paint layout and the runtime loop's viewport / pane-rect
/// push each computed these rows independently (the runtime loop even had
/// its own hand-synced copy of `popup_height`, `popup_height_for`,
/// explicitly commented "kept in sync by hand for now"). The tabline term
/// was missing from the runtime's copy entirely: the scroll/viewport logic
/// believed it had one more row than `draw_frame` actually painted, so the
/// last visible line (by the viewport's reckoning) was never drawn once the
/// tabline showed. `popup_feedback_inner_dims` no longer needs its own
/// local tabline recomputation either — callers pass a `buffer_height`
/// that already excludes it via this function.
pub(crate) fn chrome_rows(app: &App) -> ChromeRows {
    let tabline = if app.render_state.load().tabs.visible {
        1
    } else {
        0
    };
    let picker_is_minibuffer = picker_display_is_minibuffer(app);
    let picker_rows = if picker_is_minibuffer {
        app.picker_state()
            .state
            .as_deref()
            .map(|p| match p.transient.as_deref() {
                // Fold audit fix: a transient's row budget is its
                // group/item count, not `candidates.len()` (always 0
                // for a transient — it has no candidate list at all).
                // Using the candidate count here meant the minibuffer
                // band claimed only 1 row for a transient, regardless
                // of how many items it actually had.
                Some(spec) => {
                    popup_height_capped(transient_row_count(spec), transient_max_rows(app))
                }
                None => popup_height(p.candidates.len().max(1)),
            })
            .unwrap_or(0)
    } else {
        0
    };
    let completion_rows = if picker_is_minibuffer {
        app.completion()
            .state
            .as_deref()
            .map(|s| popup_height(s.candidates.len()))
            .unwrap_or(0)
    } else {
        0
    };
    ChromeRows {
        tabline,
        picker: picker_rows as u16,
        completion: completion_rows as u16,
    }
}

/// Vertico-style cmdline completion popup (DESIGN.md §5.11.3,
/// **Insert-mode completion popup** (Phase 4.2.g.1, design
/// in `docs/dev/architecture/insert-completion.md` §5). Multi-column layout:
/// `[kind glyph] [label]   [detail]   [src]`. Anchored below
/// the cursor at the popup's `anchor` position; falls back to
/// above when there's no room below. Selected row reverse-
/// videoed; matched byte ranges in the label are painted with
/// the match face.
///
/// Width capped at 60 cells; height capped at 12 rows. Doc-
/// popup side panel + width-aware column dropping land in
/// 4.2.g.3 / 4.2.g.5.
fn draw_insert_completion_popup(
    frame: &mut Frame,
    buffer_area: Rect,
    app: &App,
    snap: &DocumentSnapshot,
) {
    // Slice 3c.final.B (group 3): bind the substate Arc so the
    // `as_deref()` borrow lives for the function body.
    let completion = app.completion();
    let Some(state) = completion.insert.as_deref() else {
        return;
    };
    if state.rendered.is_empty() {
        return;
    }
    // Width: cap at 60 cells, fits at least 30.
    let width: u16 = 60u16.min(buffer_area.width.saturating_sub(2)).max(30);
    // Height: cap at 12, but never more than the candidate
    // count + the selected row's surrounding band.
    let max_h: u16 = 12;
    let want_h = (state.rendered.len() as u16).min(max_h).max(1);
    // Anchor screen position: the cursor's screen position
    // is what we want, since the popup sits at the user's
    // typing point. Active pane content rect computed via
    // the helper from the hover popup path.
    let pane_rect = active_pane_content_rect(app, buffer_area).unwrap_or(buffer_area);
    let view = FrameView::from_app(app);
    let anchor_screen = cursor_screen_position_at(
        &view,
        snap,
        pane_rect,
        app.ad().cursor,
        app.ad().scroll,
        app.panes().tree.active().id,
    );
    let (anchor_x, anchor_y) = anchor_screen.unwrap_or((buffer_area.x, buffer_area.y));
    // Below if there's room, else above.
    let area_bottom = buffer_area.y + buffer_area.height;
    let space_below = area_bottom.saturating_sub(anchor_y + 1);
    let space_above = anchor_y.saturating_sub(buffer_area.y);
    let height = want_h.min(space_below.max(space_above));
    if height == 0 {
        return;
    }
    let y = if space_below >= height {
        anchor_y + 1
    } else {
        anchor_y.saturating_sub(height)
    };
    let max_x = (buffer_area.x + buffer_area.width).saturating_sub(width);
    let x = anchor_x.min(max_x).max(buffer_area.x);
    let popup = Rect {
        x,
        y,
        width,
        height,
    };
    frame.render_widget(Clear, popup);
    // CSM.K2: reserve the bottom row for a filter-chord hint
    // whenever the popup has at least 2 rows. The hint surfaces
    // the per-source filter chords (unfiltered) or the active
    // source + `<C-Space>` clear (filtered).
    let footer_rows: u16 = if popup.height >= 2 { 1 } else { 0 };
    let candidate_rows = popup.height.saturating_sub(footer_rows) as usize;
    // Window the visible slice so the selected row stays on
    // screen. Selected sticks at the top band when reachable;
    // scrolls down when the selection passes the visible-row
    // count.
    let scroll = if state.selected < candidate_rows {
        0
    } else {
        state.selected + 1 - candidate_rows
    };
    let display_col_chars = state
        .rendered
        .iter()
        .skip(scroll)
        .take(candidate_rows)
        .map(|c| c.raw.display.chars().count())
        .max()
        .unwrap_or(0);
    let lines: Vec<Line> = state
        .rendered
        .iter()
        .enumerate()
        .skip(scroll)
        .take(candidate_rows)
        .map(|(i, c)| insert_candidate_line(c, i == state.selected, display_col_chars))
        .collect();
    let candidate_area = Rect {
        x: popup.x,
        y: popup.y,
        width: popup.width,
        height: candidate_rows as u16,
    };
    let para = Paragraph::new(lines);
    frame.render_widget(para, candidate_area);
    if footer_rows > 0 {
        let footer_area = Rect {
            x: popup.x,
            y: popup.y + candidate_rows as u16,
            width: popup.width,
            height: footer_rows,
        };
        let footer = insert_completion_footer_line(state, footer_area.width);
        frame.render_widget(Paragraph::new(footer), footer_area);
    }
}

/// CSM.K2: filter-chord hint rendered as the popup's bottom
/// row. Unfiltered: a compact chord menu pruned to the chords
/// that actually have candidates in `state.raw`. Filtered:
/// `source: <id>  [<C-Space> all]` so the user can tell which
/// source is active and how to clear it.
///
/// 2026-05-27: switched from `  ` separator to `│` and added
/// a compact fallback. Width adaption order:
///   1. Full form: `<C-b> buf │ <C-o> lsp │ ...`
///   2. Compact: `[b]uf │ [o]lsp │ ...` (drops the `<C-` chord
///      prefix since users know the convention from the popup-
///      layer keymap docs).
///   3. Prune chords from the right (least common source last)
///      until what's left fits.
fn insert_completion_footer_line(
    state: &lattice_completion::InsertCompletionState,
    width: u16,
) -> Line<'static> {
    use ratatui::style::{Modifier, Style};
    use ratatui::text::Span;
    if let Some(active) = state.source_filter.as_ref() {
        let label = source_display_label(active.as_str());
        let text = format!(" source: {label} │ <C-Space> all ");
        let text = clip_to_width(&text, width);
        return Line::from(Span::styled(
            text,
            Style::default().add_modifier(Modifier::DIM),
        ));
    }
    let sources_present: std::collections::BTreeSet<&str> = state
        .raw
        .iter()
        .filter_map(|r| r.source.as_ref().map(|s| s.as_str()))
        .collect();
    let entries = filter_chord_entries(&sources_present);
    if entries.is_empty() {
        return Line::from(Span::raw(""));
    }
    let text = render_filter_chord_footer(&entries, width);
    Line::from(Span::styled(
        text,
        Style::default().add_modifier(Modifier::DIM),
    ))
}

/// One filter chord entry. `key` is the bare letter (e.g.
/// `"b"`); `label` is the source's short name. Shared between
/// the full and compact renderers.
pub(crate) struct FilterChordEntry {
    pub key: &'static str,
    pub label: &'static str,
}

/// 2026-05-27: build the ordered chord list from the sources
/// actually present in this batch. Pruning order matches the
/// popup keymap (CSM.K2): buffer → lsp → path → tree-sitter →
/// snippet (most-common to least-common in normal coding use).
pub(crate) fn filter_chord_entries(
    sources_present: &std::collections::BTreeSet<&str>,
) -> Vec<FilterChordEntry> {
    let mut out: Vec<FilterChordEntry> = Vec::new();
    if sources_present.contains(lattice_completion::insert::BufferWordsSource::ID) {
        out.push(FilterChordEntry {
            key: "b",
            label: "buf",
        });
    }
    if sources_present.contains(lattice_completion::insert::LSP_COMPLETION_SOURCE_ID) {
        out.push(FilterChordEntry {
            key: "o",
            label: "lsp",
        });
    }
    if sources_present.contains(lattice_completion::insert::PATH_SOURCE_ID) {
        out.push(FilterChordEntry {
            key: "f",
            label: "path",
        });
    }
    if sources_present.contains(lattice_completion::insert::TREE_SITTER_SYMBOL_SOURCE_ID) {
        out.push(FilterChordEntry {
            key: "t",
            label: "ts",
        });
    }
    if sources_present.contains(lattice_completion::insert::SNIPPET_SOURCE_ID) {
        out.push(FilterChordEntry {
            key: "s",
            label: "snip",
        });
    }
    out
}

/// 2026-05-27: render the filter-chord footer string with
/// width adaption — full form if it fits, compact otherwise,
/// then prune from the right.
pub(crate) fn render_filter_chord_footer(entries: &[FilterChordEntry], width: u16) -> String {
    if entries.is_empty() {
        return String::new();
    }
    let w = width as usize;
    let render = |form_full: bool, take: usize| -> String {
        let parts: Vec<String> = entries
            .iter()
            .take(take)
            .map(|e| {
                if form_full {
                    format!("<C-{}> {}", e.key, e.label)
                } else {
                    // `^` is the standard Ctrl indicator (e.g. `^C` =
                    // Ctrl-C). `[^b]uf` reads as "Ctrl-b → buf" in
                    // half the chars of the full form.
                    format!("[^{}]{}", e.key, e.label)
                }
            })
            .collect();
        format!(" {} ", parts.join(" │ "))
    };
    // Try full form, all entries.
    let full = render(true, entries.len());
    if full.chars().count() <= w {
        return full;
    }
    // Try compact form, all entries.
    let compact = render(false, entries.len());
    if compact.chars().count() <= w {
        return compact;
    }
    // Prune from the right in compact form.
    for take in (1..entries.len()).rev() {
        let pruned = render(false, take);
        if pruned.chars().count() <= w {
            return pruned;
        }
    }
    // Single chord still doesn't fit — hard truncate.
    clip_to_width(&compact, width)
}

fn source_display_label(id: &str) -> &'static str {
    match id {
        "gen:buffer-words" => "buffer-words",
        "gen:lsp-completion" => "lsp",
        "gen:path" => "path",
        "gen:tree-sitter-symbol" => "tree-sitter",
        "gen:snippet" => "snippet",
        _ => "source",
    }
}

fn clip_to_width(s: &str, width: u16) -> String {
    let w = width as usize;
    if s.chars().count() <= w {
        let mut out = s.to_string();
        while out.chars().count() < w {
            out.push(' ');
        }
        out
    } else {
        s.chars().take(w).collect()
    }
}

/// **Insert-mode completion docs side popup** (Phase
/// 4.2.g.3). Anchored right of the candidate popup when
/// there's room (typical wide terminals); falls back to
/// below the candidate popup when narrow. Renders the
/// focused item's `documentation` (lazy-resolved via
/// `completionItem/resolve`) wrapped to the popup width.
/// Title bar shows "docs" + the focused candidate's label.
///
/// `<C-f>` / `<C-b>` (inside the completion-popup minor
/// mode) page through the body via `state.doc_popup.scroll`.
/// PU.5c: the OUTER rect the completion-docs side popup paints into, or
/// `None` when no docs popup is shown / there's no room. Anchored to the
/// right of (or below) the candidate popup. Shared by the renderer (paint)
/// and the runtime geometry feedback (`completion_docs_feedback_inner_dims`
/// → `App::set_completion_docs_viewport`) so the `PaneId::COMPLETION_DOCS`
/// matrix width and the painted box agree — the peer of
/// `popup_feedback_inner_dims` / `draw_help_overlay`.
fn completion_docs_popup_rect(
    app: &App,
    snap: &DocumentSnapshot,
    buffer_area: Rect,
) -> Option<Rect> {
    let completion = app.completion();
    let state = completion.insert.as_deref()?;
    let doc_popup = state.doc_popup.as_ref()?;
    // Only shown when the focused candidate resolved a non-empty body.
    if doc_popup.body.as_ref().is_none_or(|b| b.is_empty()) {
        return None;
    }
    // Anchor: same anchor as the candidate popup.
    let pane_rect = active_pane_content_rect(app, buffer_area).unwrap_or(buffer_area);
    let view = FrameView::from_app(app);
    let anchor_screen = cursor_screen_position_at(
        &view,
        snap,
        pane_rect,
        app.ad().cursor,
        app.ad().scroll,
        app.panes().tree.active().id,
    );
    let (anchor_x, anchor_y) = anchor_screen.unwrap_or((buffer_area.x, buffer_area.y));
    // Candidate popup geometry (mirrors `draw_insert_completion_popup`).
    let cand_width: u16 = 60u16.min(buffer_area.width.saturating_sub(2)).max(30);
    let cand_height: u16 = 12u16.min(state.rendered.len() as u16).max(1);
    let area_bottom = buffer_area.y + buffer_area.height;
    let space_below = area_bottom.saturating_sub(anchor_y + 1);
    let cand_y = if space_below >= cand_height {
        anchor_y + 1
    } else {
        anchor_y.saturating_sub(cand_height)
    };
    let cand_max_x = (buffer_area.x + buffer_area.width).saturating_sub(cand_width);
    let cand_x = anchor_x.min(cand_max_x).max(buffer_area.x);
    // Docs popup: try to fit right of the candidate popup; else below it.
    let cand_right = cand_x + cand_width;
    let space_right = (buffer_area.x + buffer_area.width).saturating_sub(cand_right + 1);
    let docs_width: u16 = 60u16.min(space_right);
    let (x, y, width, height) = if docs_width >= 30 {
        (cand_right + 1, cand_y, docs_width, cand_height)
    } else {
        let below_y = cand_y + cand_height;
        let below_h = area_bottom.saturating_sub(below_y).min(8);
        if below_h < 3 {
            return None;
        }
        (cand_x, below_y, cand_width, below_h)
    };
    if width < 20 || height < 3 {
        return None;
    }
    Some(Rect {
        x,
        y,
        width,
        height,
    })
}

/// PU.5c: inner `(rows, cols)` of the completion-docs popup for the host
/// geometry hand-off (`App::set_completion_docs_viewport`). Inner = outer −
/// 2 (the `Borders::ALL` block). `None` when no docs popup is shown — the
/// runtime then pushes nothing (the synthetic pane simply isn't built).
pub(crate) fn completion_docs_feedback_inner_dims(
    app: &App,
    snap: &DocumentSnapshot,
    buffer_area: Rect,
) -> Option<(u32, u32)> {
    let rect = completion_docs_popup_rect(app, snap, buffer_area)?;
    let inner_w = u32::from(rect.width.saturating_sub(2)).max(1);
    let inner_h = u32::from(rect.height.saturating_sub(2)).max(1);
    Some((inner_h, inner_w))
}

fn draw_insert_completion_docs_popup(
    frame: &mut Frame,
    buffer_area: Rect,
    app: &App,
    snap: &DocumentSnapshot,
) {
    let Some(popup) = completion_docs_popup_rect(app, snap, buffer_area) else {
        return;
    };
    frame.render_widget(Clear, popup);
    let block = Block::default()
        .borders(Borders::ALL)
        .title(" docs (<C-d>) ");
    let inner = block.inner(popup);
    frame.render_widget(block, popup);
    if inner.width == 0 || inner.height == 0 {
        return;
    }
    let completion = app.completion();
    let doc_scroll = completion
        .insert
        .as_deref()
        .and_then(|s| s.doc_popup.as_ref())
        .map(|d| d.scroll)
        .unwrap_or(0);
    // PU.5c: render the docs CONTENT through the shared compose seam reading
    // the `PaneId::COMPLETION_DOCS` `DisplayMatrix` (markdown colour + link
    // styling + soft-wrap), the SAME path the help / hover popup uses — the
    // docs buffer is a help-flavoured ephemeral Document. Before the
    // ephemeral buffer exists (the one tick between `doc_popup.body`
    // appearing and `reconcile_completion_docs_buffer` creating it) OR
    // before the renderer has fed geometry back (matrix not built yet),
    // compose falls back to plain-text from the snapshot — correct text,
    // colour catches up within a frame (UX-acceptable eventual consistency).
    if let Some(docs_id) = completion.docs_buffer_id
        && let Some(handle) = app.buffers().registry.document_handle(docs_id)
    {
        let content_snap = handle.snapshot();
        let view = FrameView::for_buffer(app, docs_id);
        let ctx = PaneComposeCtx {
            // The docs popup is never focused (State A only) — no cursor,
            // no interaction overlays.
            is_active: false,
            pane_id: lattice_core::ui::pane::PaneId::COMPLETION_DOCS,
            buffer_id: docs_id,
            cursor_line: 0,
            cursor_line_highlight: false,
            scroll: doc_scroll,
            leftcol: 0,
            display_line_numbers: handle.display_line_numbers(),
        };
        let lines = compose_pane_lines(
            &view,
            &content_snap,
            inner.height as u32,
            inner.width as u32,
            &ctx,
        );
        frame.render_widget(Paragraph::new(lines), inner);
    } else {
        // Pre-buffer fallback: plain-text body so the user sees docs
        // immediately on the first frame.
        let body_text: String = completion
            .insert
            .as_deref()
            .and_then(|s| s.doc_popup.as_ref())
            .and_then(|d| d.body.clone())
            .unwrap_or_else(|| "(loading…)".to_string());
        let visible_body: String = body_text
            .lines()
            .skip(doc_scroll as usize)
            .collect::<Vec<_>>()
            .join("\n");
        let para = Paragraph::new(visible_body)
            .wrap(Wrap { trim: false })
            .style(TuiStyle::default().fg(Color::Gray));
        frame.render_widget(para, inner);
    }
}

/// Render one Insert-mode-completion candidate row. Three
/// columns: kind glyph (3 cells) / label with match-face
/// highlighting (≤ 30 cells) / source tag right-aligned
/// (3-4 cells). Detail column lands in 4.2.g.3 once LSP
/// items carry signatures; for buffer-words there's no
/// detail to show.
/// 2026-05-27: `display_col_chars` is the widest visible
/// candidate's display width in chars. Caller computes once
/// per render so every row's annotation column starts at the
/// same x. Replaces the previous `width: u16` (popup width)
/// padding that made the annotation drift to the right edge
/// of wide popups — bounded by content, not container.
fn insert_candidate_line<'a>(
    c: &'a lattice_completion::RenderedCandidate,
    selected: bool,
    display_col_chars: usize,
) -> Line<'a> {
    let row_style = if selected {
        TuiStyle::default()
            .bg(Color::DarkGray)
            .add_modifier(Modifier::BOLD)
    } else {
        TuiStyle::default()
    };
    let match_style = TuiStyle::default()
        .fg(Color::Cyan)
        .add_modifier(Modifier::BOLD);
    let glyph = candidate_kind_glyph(c.raw.kind);
    // 3-cell kind column (selected/unselected) + leading space.
    let mut spans: Vec<Span<'a>> = vec![Span::styled(format!(" {glyph}  "), row_style)];
    // Label with match-face spans on `c.match_ranges`.
    let label = &c.raw.display;
    let mut cursor = 0usize;
    let mut sorted: Vec<_> = c.match_ranges.clone();
    sorted.sort_by_key(|r| r.start);
    for range in sorted {
        if range.start >= label.len() || range.end > label.len() || range.start >= range.end {
            continue;
        }
        if range.start > cursor {
            spans.push(Span::styled(
                label[cursor..range.start].to_string(),
                row_style,
            ));
        }
        spans.push(Span::styled(
            label[range.start..range.end].to_string(),
            if selected {
                match_style.bg(Color::DarkGray).add_modifier(Modifier::BOLD)
            } else {
                match_style
            },
        ));
        cursor = range.end;
    }
    if cursor < label.len() {
        spans.push(Span::styled(label[cursor..].to_string(), row_style));
    }
    // Source tag, column-aligned. Inferred from kind for v1 --
    // CandidateData::Plain doesn't carry a source id today.
    // 4.2.g.5 will plumb the SourceId into RenderedCandidate
    // (typed routing payload work) and this falls out.
    let source_tag = source_tag_for_kind(c.raw.kind);
    // Pad so the tag column starts `display_col_chars + 2`
    // chars into the row — same x as every other row in the
    // visible window.
    let label_len: usize = spans.iter().map(|s| s.content.chars().count()).sum();
    let target_col = display_col_chars
        .saturating_add(spans[0].content.chars().count()) // kind prefix width
        .saturating_add(2);
    let target_pad = target_col.saturating_sub(label_len);
    if target_pad > 0 {
        spans.push(Span::styled(" ".repeat(target_pad), row_style));
    }
    spans.push(Span::styled(
        format!(" {source_tag}"),
        if selected {
            row_style.fg(Color::DarkGray)
        } else {
            TuiStyle::default().fg(Color::DarkGray)
        },
    ));
    Line::from(spans)
}

/// Single-glyph icon for a candidate's `CandidateKind`.
/// Mirrors `symbol_kind_glyph` / `completion_kind_glyph` in
/// the LSP path -- once the LSP source plugs into the popup
/// (4.2.g.2) those map straight through.
fn candidate_kind_glyph(kind: lattice_completion::CandidateKind) -> &'static str {
    use lattice_completion::CandidateKind as K;
    match kind {
        K::Command => ":",
        K::Option => "⚙",
        K::File => "📄",
        K::Directory => "📁",
        K::Pattern => "/",
        K::Buffer => "▤",
        K::Register => "\"",
        K::Mark => "'",
        K::Chord => "⌘",
        K::Plain => "·",
        K::Extension(_) => "+",
    }
}

/// Source tag rendered right-aligned in the popup row. Today
/// inferred from kind; 4.2.g.5 plumbs the `SourceId` directly
/// onto the candidate so the tag matches the actual source.
fn source_tag_for_kind(kind: lattice_completion::CandidateKind) -> &'static str {
    use lattice_completion::CandidateKind as K;
    match kind {
        K::File | K::Directory => "path",
        K::Buffer => "buf",
        K::Plain => "buf",
        _ => "",
    }
}

/// §5.9.7). Sits BELOW the `:` prompt; the selected candidate is
/// the FIRST visible row (closest to the prompt above), alternatives
/// fan downward. Same visual shape as
/// [`draw_picker_candidates`] -- no border, no title bar, just the
/// candidate list. The candidate-count hint is appended to the
/// cmdline itself by [`draw_command_or_echo`] when completion is
/// open, matching the picker's prompt-inline `(n/m)` style.
fn draw_completion_popup(frame: &mut Frame, popup_area: Rect, app: &App) {
    // Slice 3c.final.B (group 3): bind substate Arc.
    let completion = app.completion();
    let Some(state) = completion.state.as_deref() else {
        return;
    };
    if state.candidates.is_empty() {
        return;
    }

    frame.render_widget(Clear, popup_area);
    let inner = popup_area;

    // Visible window. Selected stays in view as the user advances
    // with Tab; once it would scroll off the bottom, we shift the
    // window so the selected sits at the bottom row.
    let visible_count = inner.height as usize;
    if visible_count == 0 {
        return;
    }
    let scroll = if state.selected < visible_count {
        0
    } else {
        state.selected + 1 - visible_count
    };
    let display_col_chars = state
        .candidates
        .iter()
        .skip(scroll)
        .take(visible_count)
        .map(|c| c.raw.display.chars().count())
        .max()
        .unwrap_or(0);
    // MARG.5 (2026-06-03): per-category column layout across
    // the visible candidate set. Each row's annotation cells
    // render against this so columns align vertically even
    // when some rows have keybindings and others don't.
    let columns = lattice_completion::AnnotationColumns::from_visible(
        state.candidates.iter().skip(scroll).take(visible_count),
    );
    // MR.1: resolved theme + ids so annotation colors read the
    // registered `completion.annotation.*` slots (TUI/GPUI parity).
    let cells_rs = app.render_state.load().cells.load_full();
    let visible: Vec<Line> = state
        .candidates
        .iter()
        .enumerate()
        .skip(scroll)
        .take(visible_count)
        .map(|(i, c)| {
            candidate_to_line(
                c,
                i == state.selected,
                display_col_chars,
                &columns,
                &cells_rs.resolved_theme,
                &cells_rs.theme_ids,
            )
        })
        .collect();
    let para = Paragraph::new(visible);
    frame.render_widget(para, inner);
}

/// Render one candidate as a single styled line. Matched byte
/// ranges are painted with a distinct style; annotations
/// column-aligned at `display_col_chars + 2` characters in
/// (caller passes the widest visible display so every row's
/// annotation starts at the same x). 2026-05-27: previously
/// took `width: u16` and right-justified to it; replaced for
/// content-bound annotation column so wide popups don't push
/// the marginalia to the far-right edge.
fn candidate_to_line<'a>(
    c: &'a lattice_completion::RenderedCandidate,
    selected: bool,
    display_col_chars: usize,
    columns: &lattice_completion::AnnotationColumns,
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) -> Line<'a> {
    // 2026-06-03: the `▶ ` selection-glyph prefix was
    // redundant — the row-background colour on the selected
    // row already conveys focus. Dropping it both halves the
    // left-margin width and matches the GPUI peer's shape
    // (which never carried a selection-glyph). Empty prefix:
    // candidate text starts at the kind glyph.
    let prefix = "";
    let row_style = if selected {
        TuiStyle::default()
            .bg(Color::DarkGray)
            .add_modifier(Modifier::BOLD)
    } else {
        TuiStyle::default()
    };
    // Issue #35 (2026-05-22): match highlight stays cyan+bold.
    // TUI's hardcoded palette is the 16-color baseline (works
    // even on Linux ttys without true-color). Theme-driven
    // override queued — bringing the GPUI peer's
    // `picker_match_highlight` to ratatui needs the host
    // Theme abstraction wired through here (separate slice).
    let match_style = TuiStyle::default()
        .fg(Color::Cyan)
        .add_modifier(Modifier::BOLD);
    // Kind glyph style — dim grey so it doesn't compete with
    // the candidate text. On the selected row we lift it
    // slightly to stay legible.
    let kind_style = if selected {
        row_style.fg(Color::Gray)
    } else {
        row_style.fg(Color::DarkGray)
    };

    // Build spans: kind glyph (issue #35), text with match-range
    // highlighting, then padding, then annotations on the right.
    let text = &c.raw.display;
    let mut spans: Vec<Span<'a>> = Vec::new();
    spans.push(Span::styled(prefix, row_style));
    // Issue #35: left-margin kind glyph + space separator.
    spans.push(Span::styled(format!("{} ", c.raw.kind.glyph()), kind_style));

    // Walk text + match_ranges to paint runs.
    let mut cursor = 0usize;
    let mut sorted_ranges: Vec<_> = c
        .match_ranges
        .iter()
        .filter(|r| r.start < r.end && r.end <= text.len())
        .cloned()
        .collect();
    sorted_ranges.sort_by_key(|r| r.start);
    for range in sorted_ranges {
        if range.start > cursor {
            // PH.1: the non-match gap is syntax-highlighted by
            // `display_spans` when present (match runs below keep
            // the match style — composition rule: match wins on
            // overlap).
            push_preview_run(
                &mut spans,
                text,
                cursor,
                range.start,
                &c.raw.display_spans,
                row_style,
                resolved,
                ids,
            );
        }
        spans.push(Span::styled(
            text[range.start..range.end].to_string(),
            match_style,
        ));
        cursor = range.end;
    }
    if cursor < text.len() {
        push_preview_run(
            &mut spans,
            text,
            cursor,
            text.len(),
            &c.raw.display_spans,
            row_style,
            resolved,
            ids,
        );
    }

    // MARG.5 (2026-06-03): per-category column-aligned
    // annotations. Walk `columns` (pre-computed per-visible-
    // set max widths) in display order; for each column,
    // either render this candidate's matching annotation
    // (padded to column width) or render a blank cell of the
    // same column width. Keeps every row's annotation cells
    // lined up vertically even when some rows have a
    // keybinding and others don't.
    //
    // The pad-to-display_col_chars run before the first
    // column stays — it's what lifts the annotation column
    // off the variable-width candidate text. Per-variant
    // colours from `annotation_color` (MARG.1) still apply
    // per-cell; blank cells inherit the row style only.
    if !columns.is_empty() {
        let kind_prefix_len = prefix.len() + 2; // glyph + " "
        let target_col = display_col_chars
            .saturating_add(kind_prefix_len)
            .saturating_add(2);
        let used = prefix.len() + 2 + text.len(); // kind prefix + display
        let pad = target_col.saturating_sub(used);
        if pad > 0 {
            spans.push(Span::styled(" ".repeat(pad), row_style));
        }
        for (i, (category, col_width)) in columns.iter().enumerate() {
            if i > 0 {
                spans.push(Span::styled("  ", row_style));
            }
            // Find this row's annotation for the column's
            // category. None ⇒ blank cell of the full width.
            let ann_for_col = c.annotations.iter().find(|a| a.category() == category);
            match ann_for_col {
                Some(ann) => {
                    let text_chars = ann.display_text().chars().count();
                    let cell_pad = col_width.saturating_sub(text_chars);
                    match ann {
                        // MR.2: a styled cell paints one span per segment,
                        // each resolved from its own theme slot (the per-bit
                        // permission coloring). Selection is conveyed by the
                        // row background, so segments read the slot fg in both
                        // states (no per-segment brightening).
                        lattice_completion::Annotation::Styled { segments, .. } => {
                            for seg in segments {
                                let fg = resolved
                                    .get(ids.annotation_slot(&seg.slot))
                                    .fg
                                    .map(crate::theme::host_color_to_ratatui)
                                    .unwrap_or(Color::DarkGray);
                                spans.push(Span::styled(seg.text.to_string(), row_style.fg(fg)));
                            }
                        }
                        _ => {
                            let fg = annotation_color(ann, selected, resolved, ids);
                            spans.push(Span::styled(
                                ann.display_text().into_owned(),
                                row_style.fg(fg),
                            ));
                        }
                    }
                    if cell_pad > 0 {
                        spans.push(Span::styled(" ".repeat(cell_pad), row_style));
                    }
                }
                None => {
                    // Blank cell — keeps downstream columns
                    // aligned vertically across rows.
                    if col_width > 0 {
                        spans.push(Span::styled(" ".repeat(col_width), row_style));
                    }
                }
            }
        }
    }
    Line::from(spans)
}

/// PH.1: paint the `[lo, hi)` byte slice of a candidate's
/// display run, subdividing it by `display_spans` (the
/// syntax-highlight overlay) when present. Each covered sub-run
/// resolves its semantic `Style` to a theme fg via
/// `resolve_syntax_style` — so `:colorscheme` recolors picker
/// previews live, exactly like the main editor path; uncovered
/// bytes paint in `base` (today's plain preview, so no new
/// "plain" theme slot is needed). Called only for the
/// non-match gaps; fuzzy-match runs keep the match style
/// (composition: match wins on overlap, picker-preview-
/// highlight.md §5).
///
/// `display_spans` are assumed sorted by `range.start` and
/// non-overlapping (producer contract, PH.2). Ranges that don't
/// land on a char boundary are skipped rather than panicking on
/// the slice — graceful degradation over a hot-path panic.
#[allow(clippy::too_many_arguments)]
fn push_preview_run<'a>(
    spans: &mut Vec<Span<'a>>,
    text: &str,
    lo: usize,
    hi: usize,
    display_spans: &[lattice_completion::DisplaySpan],
    base: TuiStyle,
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) {
    if lo >= hi {
        return;
    }
    // Fast path: no overlay → one plain run, byte-identical to
    // the pre-PH.1 output.
    if display_spans.is_empty() {
        spans.push(Span::styled(text[lo..hi].to_string(), base));
        return;
    }
    let mut pos = lo;
    for ds in display_spans {
        let s = ds.range.start.max(lo);
        let e = ds.range.end.min(hi);
        if s >= e {
            continue; // span doesn't overlap this gap
        }
        if !text.is_char_boundary(s) || !text.is_char_boundary(e) {
            continue; // malformed range — skip, never panic
        }
        if s > pos && text.is_char_boundary(pos) {
            spans.push(Span::styled(text[pos..s].to_string(), base));
        }
        let run_style = match lattice_host::ui::theme::resolve_syntax_style(resolved, ids, ds.style)
            .fg
            .map(crate::theme::host_color_to_ratatui)
        {
            Some(c) => base.fg(c),
            None => base,
        };
        spans.push(Span::styled(text[s..e].to_string(), run_style));
        pos = e;
    }
    if pos < hi && text.is_char_boundary(pos) {
        spans.push(Span::styled(text[pos..hi].to_string(), base));
    }
}

/// MARG.1 (2026-06-03): pick a foreground colour per
/// annotation variant. `selected` flips between the dim
/// (unselected row bg) and bright (selected row's
/// `DarkGray` bg) shade so contrast holds in both states.
/// Defaults documented in
/// `docs/dev/architecture/marginalia.md` §5; will move to
/// theme-slot reads when the queued theme-through-renderer
/// slice lands.
/// Pack a `0xRRGGBB` literal into a ratatui `Color::Rgb`. Used for the
/// selected-row brightened annotation literals and the unset-slot
/// fallbacks (both shared verbatim with the GPUI peer).
fn rgb_u32_to_ratatui(v: u32) -> Color {
    Color::Rgb((v >> 16) as u8, (v >> 8) as u8, v as u8)
}

/// MR.1 (2026-06-30): resolve a completion / picker annotation's
/// foreground from the theme. Mirrors the GPUI peer's
/// `annotation_color_rgb` exactly so both renderers agree:
///
/// - the **unselected** base reads the registered
///   `completion.annotation.{kind,doc,keybinding,source,custom}`
///   element (fall back to the legacy literal if the slot is unset);
/// - the **selected-row brightening** stays renderer logic — a selected
///   row returns the brightened literal so contrast against the
///   selection background holds (the brightening is NOT a separate theme
///   element). The two-tuple literals are identical to GPUI's.
///
/// Before MR.1 this matched on the variant and returned a hardcoded
/// `Color::*` regardless of theme (the §5 "queued" note only closed on
/// the GPUI side via T.6). Now `:colorscheme` recolors marginalia on
/// both peers.
fn annotation_color(
    ann: &lattice_completion::Annotation,
    selected: bool,
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) -> Color {
    use lattice_completion::Annotation;
    let (id, base_fallback, brightened): (_, u32, u32) = match ann {
        Annotation::Kind(_) => (ids.completion_annotation_kind, 0x9399b2, 0xcdd6f4),
        Annotation::DocSnippet(_) => (ids.completion_annotation_doc, 0x89dceb, 0xbfeaf5),
        Annotation::Keybinding(_) => (ids.completion_annotation_keybinding, 0xf9e2af, 0xfff0b8),
        Annotation::Source(_) => (ids.completion_annotation_source, 0xcba6f7, 0xe2cfff),
        // A plugin's own slot, RESOLVED rather than discarded. This arm was
        // `{ .. }`, so every `Custom` annotation painted one fixed blue however
        // the producer had labelled it — org-roam marks aliases and tags with
        // different slots and both came out identical, which reads as "the
        // picker has no highlighting at all". `Styled` segments already resolve
        // per-segment through this same call; `Custom` carrying a slot and
        // ignoring it was the inconsistency.
        //
        // Unknown slots still fall back to `completion.annotation.custom`
        // inside `annotation_slot`, so nothing that worked before moves.
        Annotation::Custom { slot, .. } => (ids.annotation_slot(slot), 0x89b4fa, 0xb6d3ff),
        // `Styled` cells are painted per-segment by the caller (each
        // segment resolves its own slot via `ids.annotation_slot`), so
        // this whole-cell color path is never taken for them; map to the
        // custom fallback for exhaustiveness.
        Annotation::Styled { .. } => (ids.completion_annotation_custom, 0x89b4fa, 0xb6d3ff),
    };
    if selected {
        rgb_u32_to_ratatui(brightened)
    } else {
        resolved
            .get(id)
            .fg
            .map(crate::theme::host_color_to_ratatui)
            .unwrap_or_else(|| rgb_u32_to_ratatui(base_fallback))
    }
}

/// Draw the help buffer (DESIGN.md §5.11) as a centred popup. Popup
/// is the v1 display strategy; multi-buffer support brings split /
/// Vertico-style picker prompt (DESIGN.md §5.9.7) drawn in the
/// cmdline row when a [`lattice_picker::Picker`] is open. Format:
/// `<title>[ <root>]> <query>` -- the title stands in for the `:`
/// prompt so the user knows what they're picking, and `query` is
/// the live filter they're typing. Sits at the screen bottom; the
/// candidate list is rendered below by
/// [`draw_picker_candidates`].
///
/// PP.2: `root` appears only for a picker whose results are scoped
/// to a project (`Picker::root_label`), because when several
/// checkouts are open the rows cannot say which one answered and
/// memory is not a reliable substitute. Most pickers have no root
/// and their prompt is byte-identical to what it was.
fn draw_picker_prompt(frame: &mut Frame, area: Rect, app: &App) {
    // Slice 3c.final.B (group 3): bind picker substate Arc.
    let picker = app.picker_state();
    let Some(p) = picker.state.as_deref() else {
        return;
    };
    let count = if p.candidates.is_empty() {
        "(0/0) ".to_string()
    } else {
        format!("({}/{}) ", p.selected + 1, p.candidates.len())
    };
    // PH/grep UX: an in-flight async fetch (initial `:picker grep
    // <pat>` or a live re-query) shows `searching…` so a slow grep
    // reads as "working" rather than "nothing happened".
    let trailing = if p.loading {
        format!("  {count}searching… ")
    } else {
        format!("  {count}")
    };
    // PP.2: a rooted picker names the root it is operating on, between the
    // source and the `>`. Dimmer than the title and brighter than the count:
    // it is context, read once on open, not the thing you came to read.
    //
    // `None` for every picker whose results are not root-scoped, which is most
    // of them — the span simply is not emitted, so nothing about those prompts
    // moves.
    // PP.2c: every colour on this line resolves through the theme. It
    // was the last wholly un-themeable surface in the editor — `Cyan`
    // and `DarkGray` written straight into the spans, so `:colorscheme`
    // could not reach the picker prompt at all. Resolved together here
    // rather than per span, which is also what makes a collision
    // visible: the root shared the count's tone for a release because
    // the two were written ten lines apart.
    let cells_rs = app.render_state.load().cells.load_full();
    let ids = &cells_rs.theme_ids;
    let fg = |id, fallback| {
        cells_rs
            .resolved_theme
            .get(id)
            .fg
            .map(crate::theme::host_color_to_ratatui)
            .unwrap_or(fallback)
    };
    let title_fg = fg(ids.picker_title, Color::Cyan);
    let prompt_fg = fg(ids.picker_prompt, Color::Cyan);
    let count_fg = fg(ids.picker_count, Color::DarkGray);
    let root_fg = fg(ids.picker_root, Color::Blue);

    let mut spans = vec![Span::styled(
        p.title.clone(),
        TuiStyle::default()
            .fg(title_fg)
            .add_modifier(Modifier::BOLD),
    )];
    if let Some(root) = p.root_label.as_deref() {
        // PP.2b: two spaces, not one — the root used to abut the `>`
        // (`project-files ~/src/lattice> `), which read as one run of
        // punctuation and made the prompt hard to find at a glance.
        // Padded on BOTH sides so the root is a field rather than a
        // suffix of the title.
        //
        // Resolved through `picker.root` rather than a hardcoded
        // `DarkGray`: PP.2 shipped it at the same dimness as the
        // `(n/m)` count, so the one piece of context the prompt carries
        // read as chrome. It is also what makes the line themeable at
        // all — the title and count beside it are still hardcoded, and
        // are the next thing to migrate.
        spans.push(Span::styled(
            format!("  {root}  "),
            TuiStyle::default().fg(root_fg),
        ));
    }
    spans.push(Span::styled(
        "> ",
        TuiStyle::default()
            .fg(prompt_fg)
            .add_modifier(Modifier::BOLD),
    ));
    // The query stays at the default foreground: it is the user's own
    // text, and an accent there would make what they typed compete with
    // the chrome around it.
    spans.push(Span::raw(p.query.clone()));
    spans.push(Span::styled(trailing, TuiStyle::default().fg(count_fg)));
    frame.render_widget(Paragraph::new(Line::from(spans)), area);
}

/// Vertico-style candidate list (DESIGN.md §5.9.7) drawn in the
/// row band below the picker prompt. Selected row sits at the
/// TOP of the band (closest to the prompt below), alternatives
/// fan upward in match-rank order. Reuses [`candidate_to_line`]
/// for per-row rendering so match highlights + marginalia stay
/// consistent with the cmdline completion popup.
fn draw_picker_candidates(frame: &mut Frame, area: Rect, app: &App) {
    // Slice 3c.final.B (group 3): bind picker substate Arc.
    let picker = app.picker_state();
    let Some(p) = picker.state.as_deref() else {
        return;
    };
    frame.render_widget(Clear, area);
    if p.candidates.is_empty() {
        let empty = Paragraph::new(Line::from(Span::styled(
            "  (no matches)",
            TuiStyle::default().fg(Color::DarkGray),
        )));
        frame.render_widget(empty, area);
        return;
    }
    // Window the visible slice around the selected candidate so
    // it's always on screen. With the prompt ABOVE the list
    // (vertico's flipped variant), the selected candidate sits at
    // the TOP of the band (closest to the prompt) so the eye
    // tracks naturally from query to selection.
    let visible_count = area.height as usize;
    if visible_count == 0 {
        return;
    }
    let scroll = if p.selected < visible_count {
        0
    } else {
        p.selected + 1 - visible_count
    };
    let display_col_chars = p
        .candidates
        .iter()
        .skip(scroll)
        .take(visible_count)
        .map(|c| c.raw.display.chars().count())
        .max()
        .unwrap_or(0);
    // MARG.5 (2026-06-03): per-category column layout across
    // the visible candidate set. Each row's annotation cells
    // render against this so columns align vertically even
    // when some rows have keybindings and others don't.
    let columns = lattice_completion::AnnotationColumns::from_visible(
        p.candidates.iter().skip(scroll).take(visible_count),
    );
    // MR.1: resolved theme + ids so annotation colors read the
    // registered `completion.annotation.*` slots (TUI/GPUI parity).
    let cells_rs = app.render_state.load().cells.load_full();
    let visible: Vec<Line> = p
        .candidates
        .iter()
        .enumerate()
        .skip(scroll)
        .take(visible_count)
        .map(|(i, c)| {
            candidate_to_line(
                c,
                i == p.selected,
                display_col_chars,
                &columns,
                &cells_rs.resolved_theme,
                &cells_rs.theme_ids,
            )
        })
        .collect();
    let para = Paragraph::new(visible);
    frame.render_widget(para, area);
}

/// Reads `picker.display` from the typed-options registry and
/// returns `true` iff the user wants vertico-style (default).
/// Unknown / missing values fall back to the design default
/// rather than panicking -- consistency with the validator's
/// behaviour at parse time.
fn picker_display_is_minibuffer(app: &App) -> bool {
    // Slice 3c.final.B.10: typed-options registry via published
    // `options()` sub-state — wait-free Arc clone, no actor
    // round-trip.
    app.options()
        .config
        .get_typed::<lattice_config::core_options::PickerDisplay>()
        .map(|s| s.as_str() != "popup")
        .unwrap_or(true)
}

// Centered overlay rendering of the picker for the
// `picker.display = "popup"` mode. Layout inside the overlay:
//
//   line 1: title (`p.title`) + count `(n / m)`
//   line 2: prompt `> <query>`
//   line 3: separator
//   line 4..: candidate list (vertico-style, selected row
//            at the top so the eye tracks from prompt to
//            selection identically to minibuffer mode)
//
// Sizing mirrors the help-popup convention so the picker
// feels like part of the same overlay family. The overlay is
// painted on top of [`Clear`] so buffer content underneath
// doesn't bleed through.

/// Rows a transient's group+item list occupies — per group, one
/// header row, one row per item and one blank separator row;
/// EXCLUDING preview/footer (those only apply to the popup layout;
/// the minibuffer candidate band has no room for them, mirroring how
/// the regular picker's minibuffer strip only ever shows the
/// candidate list, not a preview pane).
///
/// **The separator counts.** It is a line `transient_group_item_lines`
/// actually emits, and this number sets the popup's height and bounds
/// the scroll. Undercounting by one row per group made the box that
/// many rows too short AND capped the scroll before the bottom rows,
/// so the last items of a multi-group menu were both off-screen and
/// unreachable — reported against magit's file dispatch, whose last
/// group ends in the blame row.
///
/// The count itself now lives on `TransientSpec` so both renderers and
/// the host share one copy; this stays as the local name
/// `chrome_rows`' row-budget accounting already uses.
fn transient_row_count(spec: &lattice_picker::TransientSpec) -> usize {
    spec.row_count()
}

/// The scroll-windowed group/item lines a transient renders — the
/// ONE place that walks `spec.groups`, applies `scroll`, and stops
/// once `visible` lines are produced. Deciding *where* these lines
/// go (a bordered popup box vs. a bottom strip) is `picker.display`'s
/// call, made once by the caller in `draw_frame` — a transient's own
/// job stops at "what are the visible lines", so both
/// `draw_transient_overlay` (popup) and
/// `draw_transient_minibuffer_candidates` (minibuffer band) call
/// this and differ only in where they paint the result. Before this
/// extraction each had its own copy of the windowing loop. Returns
/// the lines plus the running line-index they ended at, so a caller
/// that keeps counting past the group/item section (the popup's
/// preview/footer rows) continues from the right number.
/// The transient menu's colours, resolved once per frame.
///
/// A transient row is three columns that mean different things — the
/// key you press, what it does, and (for a flag or variable) its
/// current value — and each needs its own colour or the row reads as
/// undifferentiated text. This used to be four hard-coded ANSI
/// constants here, which looked deliberate and meant `:colorscheme`
/// could not reach the menu at all.
#[derive(Clone, Copy)]
struct TransientPalette {
    title: TuiStyle,
    group: TuiStyle,
    key: TuiStyle,
    key_inactive: TuiStyle,
    description: TuiStyle,
    value: TuiStyle,
    border: TuiStyle,
}

impl TransientPalette {
    fn resolve(app: &App) -> Self {
        let cells = app.render_state.load().cells.load_full();
        let resolved = &cells.resolved_theme;
        let ids = &cells.theme_ids;
        let st = |id| crate::theme::host_style_to_ratatui(resolved.get(id));
        Self {
            title: st(ids.transient_title),
            group: st(ids.transient_group),
            key: st(ids.transient_key),
            key_inactive: st(ids.transient_key_inactive),
            description: st(ids.transient_description),
            value: st(ids.transient_value),
            border: st(ids.transient_border),
        }
    }
}

fn transient_group_item_lines(
    spec: &lattice_picker::TransientSpec,
    transient_state: &lattice_picker::TransientState,
    scroll: usize,
    visible: usize,
    selected: usize,
    prefix: &str,
    palette: &TransientPalette,
) -> (Vec<Line<'static>>, usize) {
    let mut lines: Vec<Line> = Vec::new();
    let mut ln: usize = 0;
    // Which item we are on, counted across groups the same way
    // `TransientSpec::selectable_count` counts — the highlight and the
    // host's selection index have to mean the same thing or `<CR>`
    // fires a row other than the one that looks chosen.
    let mut item_index: usize = 0;

    for group in &spec.groups {
        if ln >= scroll && lines.len() < visible {
            lines.push(Line::from(Span::styled(
                format!("  ▸ {}", group.label),
                palette.group,
            )));
        }
        ln += 1;

        for item in &group.items {
            if ln >= scroll && lines.len() < visible {
                let is_selected = item_index == selected;
                let key = format!("[{}]", item.key.join("/"));
                let flag = match &item.kind {
                    lattice_picker::TransientItemKind::Flag { name, .. } => {
                        let v = transient_state
                            .get(name)
                            .and_then(|v| match v {
                                lattice_picker::TransientValue::Bool(b) => Some(*b),
                                _ => None,
                            })
                            .unwrap_or(false);
                        if v {
                            "[x]".to_string()
                        } else {
                            "[ ]".to_string()
                        }
                    }
                    // MG.43g: a variable reports the CURRENT value
                    // inline — that is the whole point of the row.
                    // Three states, not two: `…` means "not read yet",
                    // which is not the same claim as `unset`.
                    lattice_picker::TransientItemKind::Variable { key, value, .. } => {
                        let shown = match value.as_deref() {
                            None => "…".to_string(),
                            Some("") => "unset".to_string(),
                            Some(v) => v.to_string(),
                        };
                        format!("{key} = {shown}")
                    }
                    _ => String::new(),
                };
                // The selection is marked with a leading caret and a
                // bold label rather than a reversed row: a transient is
                // primarily key-driven, so the marker has to say
                // "this is where <CR> would land" without competing
                // with the key column for attention.
                let (marker, label_style) = if is_selected {
                    ("  ❯ ", TuiStyle::default().add_modifier(Modifier::BOLD))
                } else {
                    ("    ", TuiStyle::default())
                };
                let _ = &palette;
                // With a multi-key row part-way typed, rows that can no
                // longer match go dull — magit's own behaviour, and the
                // only thing that says "`,` was received, keep going"
                // rather than leaving the menu looking inert.
                let reachable = lattice_picker::TransientSpec::item_matches_prefix(item, prefix);
                let (key_style, label_style, desc_style) = if reachable {
                    (palette.key, label_style, palette.description)
                } else {
                    // One tone for the whole row: a row the typed prefix
                    // has ruled out should read as "not this one", not as
                    // a row whose key is merely a different colour.
                    (
                        palette.key_inactive,
                        palette.key_inactive,
                        palette.key_inactive,
                    )
                };
                lines.push(Line::from(vec![
                    Span::styled(format!("{marker}{:<6}", key), key_style),
                    Span::styled(format!("{:<20}", item.label), label_style),
                    Span::styled(item.description.clone(), desc_style),
                    Span::styled(format!("  {}", flag), palette.value),
                ]));
            }
            ln += 1;
            item_index += 1;
        }

        if ln >= scroll && lines.len() < visible {
            lines.push(Line::from(""));
        }
        ln += 1;
    }
    (lines, ln)
}

/// NOTIF.1b: the notification stack, anchored bottom-right.
///
/// §5.9.9's corner and order: they stack in a corner, newest **below**
/// older ones here because the stack grows upward from the bottom edge
/// — `visible` arrives oldest-first, so painting it in order down the
/// block puts the newest nearest the corner, which is where the eye
/// lands.
///
/// **Drawn last, over everything.** A notification that a picker or a
/// transient could cover would be invisible exactly when the user is
/// busy, which is when it matters most.
///
/// Nothing here is timer-driven: expiry happens in the store and
/// arrives as an ordinary repaint. This function only ever paints what
/// it is given.
fn draw_notifications(frame: &mut Frame, area: Rect, app: &App) {
    let rs = app.render_state.load_full();
    let n = &rs.notifications;
    if n.visible.is_empty() {
        return;
    }

    // One row per notification, plus the "+N more" line when some are
    // queued. Width is a third of the screen, clamped so it stays
    // readable on a narrow split and does not swallow a wide one.
    let extra = usize::from(n.queued > 0);
    let rows = (n.visible.len() + extra) as u16;
    let width = (area.width / 3).clamp(24, 60).min(area.width);
    // Every pane reserves its BOTTOM row for the per-pane status line
    // (see `draw_panes`), so the usable area stops one row short of
    // `area`. Anchoring to `area` itself covers the modeline — which is
    // the row telling you which buffer and mode you are in, and the one
    // surface that must never be occluded, since a notification is
    // transient and the modeline is how you stay oriented while it is
    // up.
    let usable_h = area.height.saturating_sub(1);
    let height = (rows + 2).min(usable_h);
    if height == 0 {
        return;
    }
    let block_area = Rect {
        x: area.x + area.width.saturating_sub(width),
        y: area.y + usable_h.saturating_sub(height),
        width,
        height,
    };

    frame.render_widget(Clear, block_area);
    let block = Block::default()
        .borders(Borders::ALL)
        .border_style(TuiStyle::default().fg(Color::DarkGray));
    let inner = block.inner(block_area);
    frame.render_widget(block, block_area);

    let theme = &app.theme;
    let mut lines: Vec<Line> = n
        .visible
        .iter()
        .map(|item| notification_line(item, theme, inner.width))
        .collect();
    if n.queued > 0 {
        // Named rather than dropped: a burst that silently discarded
        // the tail would be the invisible-work bug again.
        lines.push(Line::from(vec![Span::styled(
            format!("+{} more", n.queued),
            TuiStyle::default().fg(Color::DarkGray),
        )]));
    }
    frame.render_widget(Paragraph::new(lines), inner);
}

/// One notification row: the level's icon, then the text, both in the
/// level's colour.
///
/// Colours come from the theme rather than fixed terminal colours, and
/// from the same elements the GPUI peer reads — `diagnostic.*` for the
/// severities and `diff.add.sign` for success — so `:colorscheme`
/// recolours both, identically.
fn notification_line(
    item: &lattice_notify::Notification,
    theme: &crate::theme::Theme,
    width: u16,
) -> Line<'static> {
    use lattice_notify::NotificationLevel as L;
    let style = match item.level {
        L::Info => theme.diagnostic_info_style,
        L::Success => theme.diff_add_sign_style,
        L::Warn => theme.diagnostic_warning_style,
        L::Error => theme.diagnostic_error_style,
    };
    let icon = format!("{} ", item.level.glyph(theme.nerd_fonts));
    // NC.2: the scope is its own bold span, so two repositories'
    // notifications differ in one place the eye can find.
    // Capped at a third of the row: a long repository name must not
    // leave no room for what happened in it.
    let scope = item
        .scope
        .as_deref()
        .map(|s| {
            let s = clip_to_width(s, width / 3);
            format!("{} {} ", s.trim_end(), lattice_notify::SCOPE_SEPARATOR)
        })
        .unwrap_or_default();
    let used = (icon.chars().count() + scope.chars().count()) as u16;
    let rest = width.saturating_sub(used);
    let mut spans = vec![Span::styled(icon, style)];
    if !scope.is_empty() {
        spans.push(Span::styled(
            scope,
            style.add_modifier(ratatui::style::Modifier::BOLD),
        ));
    }
    spans.push(Span::styled(clip_to_width(&item.text, rest), style));
    Line::from(spans)
}

fn draw_transient_overlay(frame: &mut Frame, buffer_area: Rect, app: &App) {
    let picker = app.picker_state();
    let Some(p) = picker.state.as_deref() else {
        return;
    };
    let Some(ref spec) = p.transient else { return };

    let preview_rows = if spec.preview.is_some() { 2 } else { 0 };
    let footer_rows = if spec.footer.is_some() { 1 } else { 0 };
    let row_count = transient_row_count(spec) + preview_rows + footer_rows;
    // Clamped to the area as well as to 35: a box taller than the
    // terminal is clipped by whoever paints last, which loses rows
    // with no scroll position that can bring them back.
    let height = (row_count as u16 + 3)
        .clamp(8, 35)
        .min(buffer_area.height.max(3));
    let width = buffer_area.width.saturating_sub(4).clamp(40, 80);
    let x = buffer_area.x + buffer_area.width.saturating_sub(width) / 2;
    let y = buffer_area.y + buffer_area.height.saturating_sub(height) / 3;
    let area = Rect {
        x,
        y,
        width,
        height,
    };

    let palette = TransientPalette::resolve(app);
    frame.render_widget(Clear, area);
    let block = Block::default()
        .borders(Borders::ALL)
        .border_style(palette.border);
    let title_line = Line::from(vec![Span::styled(
        format!(" {} ", spec.title),
        palette.title,
    )]);
    let block = block.title(title_line);
    let inner = block.inner(area);
    frame.render_widget(block, area);

    let visible = inner.height as usize;
    // Derived from the selection every frame rather than stored: there
    // is no scroll state left to drift past the end, which is what made
    // `<C-n>` overshoot and `<C-p>` feel stuck.
    let scroll = spec.scroll_for(p.transient_selected, visible);

    let (mut lines, mut ln) = transient_group_item_lines(
        spec,
        &p.transient_state,
        scroll,
        visible,
        p.transient_selected,
        &p.transient_prefix,
        &palette,
    );

    if let Some(ref preview_fn) = spec.preview {
        if ln >= scroll && lines.len() < visible {
            let sep = "─".repeat(inner.width as usize);
            lines.push(Line::from(Span::styled(sep, palette.border)));
        }
        ln += 1;
        if ln >= scroll && lines.len() < visible {
            let text = (preview_fn)(&p.transient_state);
            lines.push(Line::from(Span::styled(
                format!("  {}", text),
                palette.description.add_modifier(Modifier::ITALIC),
            )));
        }
        ln += 1;
    }

    if let Some(ref footer) = spec.footer
        && ln >= scroll
        && lines.len() < visible
    {
        lines.push(Line::from(Span::styled(
            format!("  {}", footer),
            palette.description,
        )));
    }

    frame.render_widget(Paragraph::new(lines), inner);
}

/// Fold audit fix: transients used to hard-code the popup overlay
/// regardless of `picker.display` — a `"minibuffer"` preference
/// controlled every OTHER picker surface but was silently ignored
/// for transient menus. This is the minibuffer-mode title row,
/// mirroring `draw_picker_prompt`'s cmdline-row shape.
fn draw_transient_minibuffer_prompt(frame: &mut Frame, area: Rect, app: &App) {
    let picker = app.picker_state();
    let Some(p) = picker.state.as_deref() else {
        return;
    };
    let Some(ref spec) = p.transient else { return };
    // The same `transient.title` element the popup's title uses. It was
    // `Color::Cyan` + bold here, which meant the two display modes of
    // the SAME menu disagreed about its colour and neither followed the
    // theme.
    let palette = TransientPalette::resolve(app);
    let para = Paragraph::new(Line::from(vec![Span::styled(
        format!(" {} ", spec.title),
        palette.title,
    )]));
    frame.render_widget(para, area);
}

/// Minibuffer-mode candidate band for a transient — the group/item
/// list, windowed to `area`'s height around `transient_selected` (the
/// SAME field + the same "skip until scroll, stop once the band is
/// full" shape `draw_transient_overlay` uses for its popup box, just
/// flowed into a bottom strip instead of a bordered floating area;
/// see `transient_row_count`'s doc comment for why preview/footer
/// are dropped here). Flag indicators render the same way; preview
/// and footer don't fit the band and are omitted (matching the
/// regular picker's minibuffer candidate band, which never shows a
/// preview pane either).
fn draw_transient_minibuffer_candidates(frame: &mut Frame, area: Rect, app: &App) {
    let picker = app.picker_state();
    let Some(p) = picker.state.as_deref() else {
        return;
    };
    let Some(ref spec) = p.transient else { return };
    frame.render_widget(Clear, area);

    let visible = area.height as usize;
    if visible == 0 {
        return;
    }
    let scroll = spec.scroll_for(p.transient_selected, visible);

    let palette = TransientPalette::resolve(app);
    let (lines, _) = transient_group_item_lines(
        spec,
        &p.transient_state,
        scroll,
        visible,
        p.transient_selected,
        &p.transient_prefix,
        &palette,
    );
    frame.render_widget(Paragraph::new(lines), area);
}

fn draw_picker_overlay(frame: &mut Frame, buffer_area: Rect, app: &App) {
    // Slice 3c.final.B (group 3): bind picker substate Arc.
    let picker = app.picker_state();
    let Some(p) = picker.state.as_deref() else {
        return;
    };
    // Cap width at 80 cells / 70% of the buffer area; cap
    // height at 18 rows including the title + prompt + sep.
    let cand_count = p.candidates.len().max(1) as u16;
    let max_w = buffer_area.width.saturating_sub(4).min(80);
    let max_h = buffer_area.height.saturating_sub(4).min(18);
    let height = (cand_count + 3).min(max_h).max(5);
    let width = max_w.max(40).min(buffer_area.width.saturating_sub(2));
    let x = buffer_area.x + buffer_area.width.saturating_sub(width) / 2;
    let y = buffer_area.y + buffer_area.height.saturating_sub(height) / 3;
    let area = Rect {
        x,
        y,
        width,
        height,
    };

    frame.render_widget(Clear, area);
    let block = Block::default().borders(Borders::ALL).title(format!(
        " {}  ({} / {}) ",
        p.title,
        if p.candidates.is_empty() {
            0
        } else {
            p.selected + 1
        },
        p.candidates.len(),
    ));
    let inner = block.inner(area);
    frame.render_widget(block, area);

    // Slice inner into prompt (row 0) + separator (row 1) +
    // candidate band (remaining). Constraints rather than
    // hand-arithmetic so terminal resizes degrade cleanly.
    let inner_chunks = Layout::default()
        .direction(Direction::Vertical)
        .constraints(vec![
            Constraint::Length(1), // prompt
            Constraint::Length(1), // separator
            Constraint::Min(1),    // candidate list
        ])
        .split(inner);

    let prompt = Paragraph::new(Line::from(vec![
        Span::styled(
            "> ",
            TuiStyle::default()
                .fg(Color::Cyan)
                .add_modifier(Modifier::BOLD),
        ),
        Span::raw(p.query.clone()),
    ]));
    frame.render_widget(prompt, inner_chunks[0]);

    let sep_text = "─".repeat(inner_chunks[1].width as usize);
    let sep = Paragraph::new(Line::from(Span::styled(
        sep_text,
        TuiStyle::default().fg(Color::DarkGray),
    )));
    frame.render_widget(sep, inner_chunks[1]);

    let cand_area = inner_chunks[2];
    if p.candidates.is_empty() {
        let empty = Paragraph::new(Line::from(Span::styled(
            "  (no matches)",
            TuiStyle::default().fg(Color::DarkGray),
        )));
        frame.render_widget(empty, cand_area);
        return;
    }
    let visible_count = cand_area.height as usize;
    if visible_count == 0 {
        return;
    }
    // Selected row stays at the TOP of the band -- same eye
    // path as the minibuffer mode (prompt above, selection
    // adjacent below).
    let scroll = if p.selected < visible_count {
        0
    } else {
        p.selected + 1 - visible_count
    };
    let display_col_chars = p
        .candidates
        .iter()
        .skip(scroll)
        .take(visible_count)
        .map(|c| c.raw.display.chars().count())
        .max()
        .unwrap_or(0);
    // MARG.5 (2026-06-03): per-category column layout across
    // the visible candidate set. Each row's annotation cells
    // render against this so columns align vertically even
    // when some rows have keybindings and others don't.
    let columns = lattice_completion::AnnotationColumns::from_visible(
        p.candidates.iter().skip(scroll).take(visible_count),
    );
    // MR.1: resolved theme + ids so annotation colors read the
    // registered `completion.annotation.*` slots (TUI/GPUI parity).
    let cells_rs = app.render_state.load().cells.load_full();
    let visible: Vec<Line> = p
        .candidates
        .iter()
        .enumerate()
        .skip(scroll)
        .take(visible_count)
        .map(|(i, c)| {
            candidate_to_line(
                c,
                i == p.selected,
                display_col_chars,
                &columns,
                &cells_rs.resolved_theme,
                &cells_rs.theme_ids,
            )
        })
        .collect();
    let para = Paragraph::new(visible);
    frame.render_widget(para, cand_area);
}

/// Slice 3c.gpui-cmdline-completion: centered-overlay variant of
/// the cmdline-completion popup. Activates when `picker.display
/// = "popup"` and a `:` line completion is open. Mirrors
/// `draw_picker_overlay` minus the title + separator + prompt
/// rows — the cmdline at the bottom of the screen IS the prompt,
/// so the overlay is candidate-band-only.
fn draw_completion_overlay(frame: &mut Frame, buffer_area: Rect, app: &App) {
    let completion = app.completion();
    let Some(state) = completion.state.as_deref() else {
        return;
    };
    if state.candidates.is_empty() {
        return;
    }
    let cand_count = state.candidates.len() as u16;
    let max_w = buffer_area.width.saturating_sub(4).min(80);
    let max_h = buffer_area.height.saturating_sub(4).min(18);
    let height = (cand_count + 2).min(max_h).max(5);
    let width = max_w.max(40).min(buffer_area.width.saturating_sub(2));
    let x = buffer_area.x + buffer_area.width.saturating_sub(width) / 2;
    let y = buffer_area.y + buffer_area.height.saturating_sub(height) / 3;
    let area = Rect {
        x,
        y,
        width,
        height,
    };
    frame.render_widget(Clear, area);
    let block = Block::default().borders(Borders::ALL).title(format!(
        " completion  ({} / {}) ",
        state.selected + 1,
        state.candidates.len(),
    ));
    let inner = block.inner(area);
    frame.render_widget(block, area);
    let visible_count = inner.height as usize;
    if visible_count == 0 {
        return;
    }
    let scroll = if state.selected < visible_count {
        0
    } else {
        state.selected + 1 - visible_count
    };
    let display_col_chars = state
        .candidates
        .iter()
        .skip(scroll)
        .take(visible_count)
        .map(|c| c.raw.display.chars().count())
        .max()
        .unwrap_or(0);
    // MARG.5 (2026-06-03): per-category column layout across
    // the visible candidate set. Each row's annotation cells
    // render against this so columns align vertically even
    // when some rows have keybindings and others don't.
    let columns = lattice_completion::AnnotationColumns::from_visible(
        state.candidates.iter().skip(scroll).take(visible_count),
    );
    // MR.1: resolved theme + ids so annotation colors read the
    // registered `completion.annotation.*` slots (TUI/GPUI parity).
    let cells_rs = app.render_state.load().cells.load_full();
    let visible: Vec<Line> = state
        .candidates
        .iter()
        .enumerate()
        .skip(scroll)
        .take(visible_count)
        .map(|(i, c)| {
            candidate_to_line(
                c,
                i == state.selected,
                display_col_chars,
                &columns,
                &cells_rs.resolved_theme,
                &cells_rs.theme_ids,
            )
        })
        .collect();
    let para = Paragraph::new(visible);
    frame.render_widget(para, inner);
}

/// PU.1b-3: recompute the floating help popup's inner rect `(rows,
/// cols)` for the host geometry hand-off (`App::set_popup_viewport`).
/// Returns `None` when no FLOATING popup is open (no popup, or help is
/// shown as an in-pane leaf — that case is a real pane). The buffer
/// area is reconstructed from the terminal width + the runtime's
/// already-resolved `buffer_height`, so the `popup_outer_size` inputs
/// match exactly what `draw_help_overlay` paints into — the synthetic
/// popup-pane matrix and the painted box agree on width. `buffer_height`
/// already excludes the tabline row (the caller computes it via
/// `chrome_rows`, the single source of truth — no local recomputation
/// here). Inner = outer − 2 (the `Borders::ALL` block).
pub(crate) fn popup_feedback_inner_dims(
    app: &App,
    terminal_width: u16,
    buffer_height: u32,
) -> Option<(u32, u32)> {
    if !app.popup().is_open() {
        return None;
    }
    // In-pane help is a real pane leaf — `build_cells_panes` already
    // covers it; only the floating overlay needs the synthetic pane.
    if app.panes().tree.active().buffer == crate::buffers::BufferKind::Help {
        return None;
    }
    let help = app.popup_help()?;
    let line_count = u16::try_from(help.line_count().max(1)).unwrap_or(u16::MAX);
    let (outer_w, outer_h) = lattice_core::ui::popup::popup_outer_size(
        terminal_width,
        u16::try_from(buffer_height).unwrap_or(u16::MAX),
        line_count,
        app.popup().placement,
    );
    let inner_w = u32::from(outer_w.saturating_sub(2)).max(1);
    let inner_h = u32::from(outer_h.saturating_sub(2)).max(1);
    Some((inner_h, inner_w))
}

fn draw_help_overlay(frame: &mut Frame, buffer_area: Rect, app: &App, snap: &DocumentSnapshot) {
    let Some(help) = app.popup_help() else {
        return;
    };
    // Slice 3c.final.B (group 3): popup buffer id via published
    // substate.
    let popup_id = app.popup().buffer_id.expect("popup_help is Some");
    // Sizing routes through `lattice_core::ui::popup::popup_outer_size`
    // so the renderer + the App's `help_popup_inner_height`
    // (motion / scroll / ensure_cursor_visible) agree on the
    // viewport bounds. Centred popups (reading surfaces:
    // `:help`, `:options`, `:describe-*`, `:apropos`,
    // `:customize`) get a larger cap (120 wide, 40 tall);
    // cursor-anchored popups (hover, signature help) keep
    // tight tooltip caps (80 wide, 20 tall).
    let line_count = help.line_count().max(1) as u16;
    let (width, height) = lattice_core::ui::popup::popup_outer_size(
        buffer_area.width,
        buffer_area.height,
        line_count,
        app.popup().placement,
    );
    let popup = position_help_popup(app, snap, buffer_area, width, height);

    frame.render_widget(Clear, popup);

    // Header: bold accent title + dim hint, both from the themeable
    // `ui.popup.title` / `ui.popup.hint` elements (resolved into
    // `app.theme.popup_{title,hint}`) — same source the GPUI peer uses, so
    // the accent is themeable and identical across peers. GPUI additionally
    // bumps the title font size; no separator rule on either peer.
    // PU-A.4: title = the popup buffer's registry name (the synthetic
    // Document name slot), not `help.title` — de-Help-ifies the chrome to
    // match the GPUI peer, which sources it from `name_of` since PU.1b-4b.
    // `help.title` == this name today (`register_help_document` sets
    // `name: Some(buffer.title)`), so the swap is invisible to the user.
    let title = app.buffers().registry.name_of(popup_id).unwrap_or_default();
    let block = Block::default()
        .borders(Borders::ALL)
        .title(Line::from(vec![
            Span::styled(format!(" {} ", title), app.theme.popup_title),
            Span::styled("Esc to dismiss ", app.theme.popup_hint),
        ]));
    let inner = block.inner(popup);
    frame.render_widget(block, popup);

    // PU.1b-3: the popup CONTENT renders through the shared document
    // compose path (`compose_pane_lines`) reading the synthetic
    // popup-pane `DisplayMatrix` (`PaneId::POPUP`, built off-thread by
    // the cells worker — markdown colour from PU.1b-1, link styling
    // from the PU.1b-2a `ExtraHighlights` merge, hlsearch / fold /
    // soft-wrap / horizontal-scroll all for free). Only the box
    // (border + title) above is popup-specific chrome. A help popup is
    // now pixel-equivalent to a `:set nonu signcolumn=no wrap` document
    // in a box — the K.4 / `feedback_render_is_option_derived` endgame.
    //
    // Options resolve PER-BUFFER via `for_buffer(popup_id)`, so
    // help-mode's `nonu` / `signcolumn=no` / `wrap = true` drive the
    // layout regardless of which buffer is active under the popup
    // (State A: the doc is active; State B: focus moved into help).
    let Some(handle) = app.buffers().registry.document_handle(popup_id) else {
        return;
    };
    let content_snap = handle.snapshot();
    let view = FrameView::for_buffer(app, popup_id);
    // State B (focus moved into the popup): the popup buffer IS the
    // active buffer, so its live cursor / scroll / leftcol are on
    // `app.ad()`. State A (popup shown, doc focused): the popup's
    // persisted scroll is `popup_help().scroll` (the `popup_scroll`
    // stash), no cursor inside the popup, leftcol pinned (help wraps).
    let popup_focused = app.ad().popup_focused;
    let (scroll, cursor_line, leftcol) = if popup_focused {
        (app.ad().scroll, app.ad().cursor.line, app.ad().leftcol)
    } else {
        (help.scroll as u32, 0, 0)
    };
    let ctx = PaneComposeCtx {
        // State B feeds the interaction overlays (cursor line, hlsearch,
        // current match) the same way the active pane does; State A
        // suppresses them (popup shown but not focused).
        is_active: popup_focused,
        pane_id: lattice_core::ui::pane::PaneId::POPUP,
        buffer_id: popup_id,
        cursor_line,
        // Preserve prior behaviour: State B (focused popup) paints the
        // cursor line iff cursorline is on; State A suppresses it.
        cursor_line_highlight: popup_focused && app.ad().option_cache.current_line_highlight,
        scroll,
        leftcol,
        display_line_numbers: handle.display_line_numbers(),
    };
    let lines = compose_pane_lines(
        &view,
        &content_snap,
        inner.height as u32,
        inner.width as u32,
        &ctx,
    );
    frame.render_widget(Paragraph::new(lines), inner);

    // Place the terminal cursor INSIDE the popup only in State B —
    // focus has moved into it and vim grammar acts on the popup's
    // content. In State A the cursor stays where the doc renderer put
    // it (on the symbol the user K'd). `cursor_screen_position_at` is
    // the compose-aware placement (matches `split_body_into_segments`
    // wrap + the nonu gutter), so it replaces the bespoke
    // `wrap_aware_cursor_offset` that tracked the deleted
    // `manually_wrap_lines`.
    // …unless a minibuffer owns the caret. The `:` / `/` / prompt lines each
    // draw their own at their own buffer's cursor, and the terminal has ONE
    // hardware caret — so without this guard the last writer won and the caret
    // stayed parked in the popup, merely changing shape to the Bar that
    // `ModalState::Search` implies. Reported in use as "the cursor changes
    // from block to an insert-mode line cursor" inside a read-only popup.
    //
    // The pane path below has always asked this question (its local
    // `prompt_owns_cursor`); the popup path never did. It is one question, so
    // it now has one answer, in `lattice_host::cursor_shape`.
    if popup_focused
        && !lattice_host::cursor_shape::minibuffer_owns_caret(app.ad().modal)
        && inner.height > 0
        && inner.width > 0
        && let Some((screen_x, screen_y)) = cursor_screen_position_at(
            &view,
            &content_snap,
            inner,
            app.ad().cursor,
            app.ad().scroll,
            // PIC.1: the popup caret walks the POPUP pane's matrices —
            // the same source `compose_pane_lines` uses for the body +
            // cursorline above (`ctx.pane_id`). Reading the active
            // document pane instead drifts the caret past the cursorline.
            lattice_core::ui::pane::PaneId::POPUP,
        )
    {
        frame.set_cursor_position((screen_x, screen_y));
    }
}

/// Soft-wrap (W.4): gutter continuation marker for wrapped-line
/// segments after the first. `↩`-style left arrow (U+21AA) is a
/// plain BMP glyph that renders in every terminal font, so unlike
/// nerd-font icons it needs no palette fallback
/// (`feedback_icon_palette` governs nerd-font surfaces).
const WRAP_CONT_MARKER: &str = "↪";

/// Soft-wrap (W.4): split a fully-overlaid body row into display
/// segments of `width` columns each, preserving every span's style.
/// One column == one char (the cell-grid's ASCII design target,
/// where char == byte == display column; wide chars are an explicit
/// approximation shared with the cells layer). `width == 0` (wrap
/// off) or a body that fits returns a single segment, so the caller
/// can treat the result uniformly.
///
/// Segment boundaries match the host's
/// `CellMatrix::segment_count(line) = ⌈col_count / width⌉`, so the
/// scroll model and the renderer agree on how many display rows a
/// source line occupies. The continuation marker lives in the
/// gutter (see the compose loop), not in the body, so every segment
/// uses the full content width.
///
/// `wrap_cols` is how many leading columns of `body` sit on the
/// SOURCE axis — the width the `DisplayMatrix` measured, and the
/// only width the host's `segment_count` knows about. Columns past
/// it are trailing decoration the compose loop appended (the
/// closed-fold ` ⋯ N lines` summary, completion ghost text, the
/// cursorline's right-edge pad). Those ride the final segment and
/// are clipped at the pane edge; they must never break a new one,
/// or the row would exist in the painted body but not in the
/// segment count the scroll model and the caret walk
/// ([`buffer_line_to_visible_row_with`]) share.
fn split_body_into_segments(
    body: Vec<Span<'static>>,
    width: usize,
    wrap_cols: usize,
) -> Vec<Vec<Span<'static>>> {
    if width == 0 {
        return vec![body];
    }
    if wrap_cols <= width {
        return vec![body];
    }
    let mut segments: Vec<Vec<Span<'static>>> = Vec::new();
    let mut current: Vec<Span<'static>> = Vec::new();
    let mut used: usize = 0; // columns filled in the current segment
    let mut col: usize = 0; // columns consumed from the whole body
    for span in body {
        let style = span.style;
        let mut chunk = String::new();
        for ch in span.content.chars() {
            // Break only while still inside the source-axis run;
            // once `col` reaches `wrap_cols` the rest is decoration
            // and stays on the segment it started.
            if used == width && col < wrap_cols {
                if !chunk.is_empty() {
                    current.push(Span::styled(std::mem::take(&mut chunk), style));
                }
                segments.push(std::mem::take(&mut current));
                used = 0;
            }
            chunk.push(ch);
            used += 1;
            col += 1;
        }
        if !chunk.is_empty() {
            current.push(Span::styled(chunk, style));
        }
    }
    if !current.is_empty() || segments.is_empty() {
        segments.push(current);
    }
    segments
}

/// W.4.t.1: char-count column of source `byte` within the
/// tab-expanded cell body — the column model
/// [`split_body_into_segments`] slices by: one column per char, with
/// a `\t` filling to the next `tabstop` multiple (mirroring the cells
/// builder's `cells.len()`-based expansion). Identity for ASCII
/// without tabs (`byte == col`), so overlays on plain code are
/// unchanged. Char-count (not display-width) is deliberate — it
/// matches how the body is segmented and how the cells were laid out.
fn source_byte_to_body_col(line: &str, byte: usize, tabstop: u32) -> usize {
    let ts = (tabstop.max(1)) as usize;
    let mut col = 0usize;
    let mut b = 0usize;
    for ch in line.chars() {
        if b >= byte {
            break;
        }
        if ch == '\t' {
            col += ts - (col % ts);
        } else {
            col += 1;
        }
        b += ch.len_utf8();
    }
    col
}

/// W.4.t.1: byte offset of the `col`-th char (0-based char index) in
/// `s`, clamped to `s.len()`. Maps a body column (from
/// [`source_byte_to_body_col`]) back onto the expanded cell-body's
/// byte index so the byte-slicing overlay appliers cut at the right
/// cell. `col` past the end clamps to the body end (EOL overlays).
fn nth_char_byte(s: &str, col: usize) -> usize {
    s.char_indices().nth(col).map(|(b, _)| b).unwrap_or(s.len())
}

/// Placement for the help popup overlay.
///
/// Honors the popup's [`crate::popup::PopupPlacement`]:
/// - `Centered` (default for command-launched popups like
///   `:lsp-status`, `:describe-*`, `:apropos`, `:help`, `:keymap`,
///   `:options`, `:ls`) sits at the centre of the buffer area.
/// - `CursorAnchored` (hover, signature help) anchors next to the
///   document cursor: below when there's room, above otherwise,
///   horizontally aligned with the cursor column. Falls back to
///   centred if the cursor isn't visible.
///
/// In State A (active = Document) the doc cursor is `app.editor.cursor`
/// / `app.editor.scroll`; in State B (active = Help) it lives in the
/// active pane's stash.
fn position_help_popup(
    app: &App,
    snap: &DocumentSnapshot,
    buffer_area: Rect,
    width: u16,
    height: u16,
) -> Rect {
    let centered = || {
        let cx = buffer_area.x + buffer_area.width.saturating_sub(width) / 2;
        let cy = buffer_area.y + buffer_area.height.saturating_sub(height) / 2;
        Rect {
            x: cx,
            y: cy,
            width,
            height,
        }
    };
    if matches!(
        app.popup().placement,
        crate::popup::PopupPlacement::Centered
    ) {
        return centered();
    }
    let pane_area = match active_pane_content_rect(app, buffer_area) {
        Some(r) => r,
        None => return centered(),
    };
    // WK.5: which-key's placement — the active pane's full width, flush to
    // its bottom edge. `height` already carries the half-pane cap from
    // `popup_outer_size`, so the only work here is the anchor.
    if matches!(
        app.popup().placement,
        crate::popup::PopupPlacement::MinibufferBand
    ) {
        let h = height.min(pane_area.height);
        return Rect {
            x: pane_area.x,
            y: pane_area.y + pane_area.height.saturating_sub(h),
            width: pane_area.width,
            height: h,
        };
    }
    // Active pane must be a Document for the anchor to make sense
    // (the popup is only painted when active_pane.buffer != Help,
    // so this is the State A / B case where the active pane shows
    // a doc).
    //
    // K.4.9 (2026-06-02): explicit enumeration of which kinds hit
    // each branch (per `feedback_buffers_no_special_case`):
    //
    // - `Document` arm: reads cursor + scroll from
    //   `app.ad()` (the active document's published render
    //   state). Used when the active pane shows a regular
    //   document buffer.
    // - `_` fallback: hit by Messages / Multibuffer / FileTree /
    //   Oil / Terminal / Help. Reads from `panes.tree.active()`'s
    //   PaneState — the per-pane cursor/scroll the pane carries
    //   in its non-Document state. Same anchoring math; just a
    //   different source for the cursor coords. Help typically
    //   doesn't render its own popup anchor (the popup
    //   placement function isn't reached for Help-active panes
    //   per the comment above) but is defensively included in
    //   the fallback since the function may be called from
    //   future paths.
    // …and NOT `ad()` while a minibuffer holds focus. The `*search-line*`,
    // `*command-line*` and prompt buffers are Documents, so the `Document`
    // arm below would take the MINIBUFFER's cursor — (0, 0) on a fresh
    // search line — and anchor the popup to the top of the pane. Reported in
    // use: "hitting `/` jumps the popup up near the top".
    //
    // The pane's stashed cursor / scroll is the document's own: focusing a
    // minibuffer calls `snapshot_active_pane()` before it swaps, precisely so
    // the unfocused path reads live state (`focus_editing_buffer`). That is
    // the same source the non-Document arm already uses.
    //
    // Third instance of one mistake — `BufferKind::Document` standing in for
    // a question about focus. See `popup-unification.md` §9.
    //
    // FS.2 generalised it: the question is not "is a minibuffer focused" but
    // **"is the active document the pane's buffer"**. Since a focused popup
    // became the active document too, `ad()` diverges from the pane for two
    // reasons now, and an anchor read from `ad()` is wrong for both — it is
    // the popup's own caret when the popup has focus, and the search line's
    // (0, 0) when a `/` is open inside it.
    // The published state carries BOTH identities by name, which is the
    // distinction this whole initiative is about — use them rather than
    // inferring one from a `BufferKind`.
    let pane_buffer = app.ad().active_pane_buffer_id;
    let active_is_pane = app.ad().document_buffer_id == pane_buffer;
    let (cursor, scroll) = if active_is_pane {
        (app.ad().cursor, app.ad().scroll)
    } else {
        // The pane's stash IS the document's live state: every path that
        // takes focus calls `snapshot_active_pane()` before swapping,
        // precisely so the unfocused reader sees the truth.
        let panes = app.panes();
        let pane = panes.tree.active();
        (pane.cursor, pane.scroll)
    };
    // A cursor-anchored popup is anchored to where the caret WAS when it
    // opened, which is what `popup().anchor` records — the live caret is only
    // a fallback for popups that never captured one. Preferring the anchor
    // keeps the popup still while the caret moves inside it.
    let cursor = app.popup().anchor.unwrap_or(cursor);
    // …and the anchor is a line in the PANE's buffer, so it has to be mapped
    // through that buffer's snapshot. `snap` is the ACTIVE document's, which
    // is the popup itself or a one-line `*search-line*` — mapping a file line
    // through either lands the popup somewhere unrelated to it. That was the
    // other half of "hitting `/` jumps the popup".
    let pane_snap = if active_is_pane {
        None
    } else {
        app.buffers()
            .registry
            .document_handle(pane_buffer)
            .map(|h| h.snapshot())
    };
    let snap: &DocumentSnapshot = pane_snap.as_deref().unwrap_or(snap);
    let view = FrameView::from_app(app);
    let Some((cx, cy)) = cursor_screen_position_at(
        &view,
        snap,
        pane_area,
        cursor,
        scroll,
        app.panes().tree.active().id,
    ) else {
        return centered();
    };
    // Vertical: prefer below the cursor row; if the popup wouldn't
    // fit, place above. Pin to buffer_area bounds.
    let area_bottom = buffer_area.y + buffer_area.height;
    let space_below = area_bottom.saturating_sub(cy + 1);
    let space_above = cy.saturating_sub(buffer_area.y);
    let y = if space_below >= height {
        cy + 1
    } else if space_above >= height {
        cy.saturating_sub(height)
    } else if space_below >= space_above {
        // Not enough room either side -- pick the larger gap and
        // clamp the popup so it stays on-screen.
        area_bottom.saturating_sub(height).max(buffer_area.y)
    } else {
        buffer_area.y
    };
    // Horizontal: align to cursor column; shift left if it would
    // overflow the buffer area's right edge. Clamp to area.x.
    let max_x = (buffer_area.x + buffer_area.width).saturating_sub(width);
    let x = cx.min(max_x).max(buffer_area.x);
    Rect {
        x,
        y,
        width,
        height,
    }
}

/// Compute the *content* rect (status row excluded) of the active
/// pane within `buffer_area`. Replicates the layout
/// [`draw_panes`] computes per pane. Returns `None` if the pane
/// tree has no active leaf (shouldn't happen in practice).
fn active_pane_content_rect(app: &App, buffer_area: Rect) -> Option<Rect> {
    let pane_area = crate::pane::PaneRect {
        x: buffer_area.x,
        y: buffer_area.y,
        width: buffer_area.width,
        height: buffer_area.height,
    };
    // Slice 3c.final.B (group 1): pane geometry through `app.panes()`.
    let panes = app.panes();
    let rects = panes.tree.compute_rects(pane_area);
    let active_idx = panes.tree.active_index();
    let multi = rects.len() > 1;
    let prect = rects
        .iter()
        .find(|(idx, _)| *idx == active_idx)
        .map(|(_, r)| *r)?;
    let rect = Rect {
        x: prect.x,
        y: prect.y,
        width: prect.width,
        height: prect.height,
    };
    if multi && rect.height >= 2 {
        Some(Rect {
            x: rect.x,
            y: rect.y,
            width: rect.width,
            height: rect.height - 1,
        })
    } else {
        Some(rect)
    }
}

/// True iff the active pane's buffer kind is the same kind as
/// `app.ad().buffer_kind`. When mismatched, the active pane is
/// painted as visually inactive (frozen at `pane.cursor`) -- the
/// scenario that matters is help-popup-overlay (State B) where
/// the active pane shows a Document but motions go to the help
/// popup's buffer.
fn pane_buffer_matches_active(app: &App, idx: usize) -> bool {
    // Slice 3c.final.B (group 1): pane leaves via `app.panes()`.
    let panes = app.panes();
    panes
        .tree
        .leaves()
        .get(idx)
        .map(|p| p.buffer == app.ad().buffer_kind)
        .unwrap_or(false)
}

/// Lay the pane tree out across `area` and draw each pane
/// (DESIGN.md §5.9). Each pane renders its actual buffer content
/// (vim-style: no decorative borders) plus a one-row status line
/// at its bottom edge. The active pane's status line is reverse-
/// videoed so focus is unambiguous; inactive status lines are
/// dim. With a single pane we skip the status line so the buffer
/// area looks identical to the pre-split rendering.
fn draw_panes(frame: &mut Frame, area: Rect, app: &App, snap: &DocumentSnapshot) {
    let pane_area = crate::pane::PaneRect {
        x: area.x,
        y: area.y,
        width: area.width,
        height: area.height,
    };
    // Slice 3c.final.B (group 1): pane geometry through `app.panes()`.
    // Bind the Arc once so subsequent `panes.tree.X()` reads share
    // the same snapshot for the duration of `draw_panes`.
    let panes_state = app.panes();
    let rects = panes_state.tree.compute_rects(pane_area);
    let active = panes_state.tree.active_index();
    let multi = rects.len() > 1;
    for (idx, prect) in rects.iter().copied() {
        let rect = Rect {
            x: prect.x,
            y: prect.y,
            width: prect.width,
            height: prect.height,
        };
        // A pane is *active for input* iff it's the focused pane
        // AND the active buffer kind matches the pane's buffer.
        // The mismatch case is the help-popup-overlay scenario:
        // active pane shows a Document, but `app.ad().buffer_kind ==
        // Help` because the popup is focused (State B). The doc
        // must paint with its own (frozen) `pane.cursor`, not
        // `app.editor.cursor` (which is help's). draw_inactive_document
        // already reads pane state, so we route there.
        // PI.3: a pane that is *previewing* another buffer must render
        // through the isolated projection path (`draw_inactive_document`
        // reads the displayed buffer), NOT the active path (`draw_buffer`
        // reads `app.ad()` = the committed buffer A). So the focused pane
        // is "active for input" only when it is showing its committed
        // buffer, not while a preview override is seated on it.
        let previewing = panes_state
            .tree
            .leaves()
            .get(idx)
            .map(|p| p.is_previewing())
            .unwrap_or(false);
        // MB.1: while the `:` line is open, `self.document` is the
        // synthetic `*command-line*` buffer. The active pane must keep
        // rendering ITS OWN buffer (via the registry-keyed inactive
        // path), not the command-line text — the Help-popup pattern.
        // MB.5: same for the `/`·`?` search line.
        let is_active = idx == active
            && pane_buffer_matches_active(app, idx)
            && !previewing
            && !app.ad().command_line_active
            && !app.ad().search_line_active;
        // Every pane reserves its bottom row for the per-pane status
        // line (Option A: global modeline removed).
        let (content_rect, status_rect) = if rect.height >= 2 {
            let content_h = rect.height - 1;
            (
                Rect {
                    x: rect.x,
                    y: rect.y,
                    width: rect.width,
                    height: content_h,
                },
                Some(Rect {
                    x: rect.x,
                    y: rect.y + content_h,
                    width: rect.width,
                    height: 1,
                }),
            )
        } else {
            (rect, None)
        };
        // Slice 3c.final.B (group 1): reuse the `panes_state` Arc
        // bound at the top of `draw_panes` so the slice borrow is
        // safe for the duration of the iteration.
        let pane_leaves = panes_state.tree.leaves();
        let Some(pane) = pane_leaves.get(idx) else {
            continue;
        };
        let pane = *pane;
        // M.4: per-kind dispatch consolidated into
        // `draw_pane_content`. The match still lives inside that
        // helper; from `draw_panes`'s POV the call is uniform.
        // Mode-driven dispatch (each major mode contributes its
        // own draw fn) replaces the helper-side match in a
        // follow-up.
        // MO.2: record this pane's painted body for mouse hit-testing,
        // beside the paint rather than derived from the layout later —
        // the `ModelineHitMap` rule, and for the same reason: a second
        // computation of the layout is free to disagree with the one on
        // screen, and the symptom is a click landing in the wrong pane.
        // `content_rect` excludes the status footer, so a click there is
        // not a click in the buffer.
        app.pane_hits
            .borrow_mut()
            .push(lattice_host::mouse::PaneHitZone {
                pane_id: pane.id,
                buffer_id: pane.buffer_id,
                x: content_rect.x,
                y: content_rect.y,
                width: content_rect.width,
                height: content_rect.height,
                text_left: pane_text_left(app, &pane, is_active, content_rect),
                scroll: pane.scroll,
                leftcol: pane.leftcol,
            });
        draw_pane_content(frame, content_rect, app, snap, &pane, is_active, idx);
        if let Some(sr) = status_rect {
            draw_pane_status_line(frame, sr, app, &pane, is_active);
        }
    }
    // Draw vertical separators in the column gaps between
    // side-by-side panes. The separator overlays the boundary
    // column of the right-side pane; horizontal splits don't get
    // an explicit separator -- the per-pane status line at the
    // bottom of the upper pane already provides one.
    if multi {
        draw_pane_separators(frame, &rects, app);
    }
}

/// M.4: pane-content dispatch. Looks up the active buffer's mode
/// in `App::pane_render_registry` (walks minors then major) so
/// each major / minor mode owns its render path; falls back to
/// the document path when no provider matches. Replaces the
/// helper-side `match buffer.kind` so a plugin-installed mode can
/// register its own renderer without touching the dispatcher.
fn draw_pane_content(
    frame: &mut Frame,
    content_rect: Rect,
    app: &App,
    snap: &DocumentSnapshot,
    pane: &crate::pane::PaneState,
    is_active: bool,
    idx: usize,
) {
    // DL.4: a provider may own only its status label. A `None` render
    // means "paint me through the shared document path" — which is
    // where every converged kind ends up.
    if let Some(provider) = app.pane_render_provider(pane.buffer_id)
        && let Some(render) = provider.render
    {
        render(frame, content_rect, app, snap, pane, is_active, idx);
        return;
    }
    // Issue #40 / Terminal-mode T1: paint the terminal cell
    // grid when the pane's buffer is a Terminal. T2/T3 will
    // promote this to a pane-render provider registered by
    // `terminal-mode` (the major mode); T1 keeps it inline
    // since terminal-mode doesn't exist yet.
    if matches!(pane.buffer, crate::buffers::BufferKind::Terminal) {
        draw_terminal_pane(frame, content_rect, app, pane, is_active);
        return;
    }
    // Default path: document buffer. The active branch reads the
    // live `app.editor.cursor` / `app.editor.scroll`; the inactive one reads the
    // pane's stashed cursor + scroll.
    draw_pane_document(frame, content_rect, app, snap, pane, is_active);
}

/// Map a terminal-substrate colour to ratatui's `Color`. `Default`
/// stays `Reset` so the cell renders with the terminal's own fg/bg
/// defaults (honouring the user's terminal theme).
fn term_to_tui(c: lattice_terminal::TerminalColor) -> ratatui::style::Color {
    use lattice_terminal::{NamedColor as TermNamed, TerminalColor};
    use ratatui::style::Color as TuiColor;
    match c {
        TerminalColor::Default => TuiColor::Reset,
        TerminalColor::Named(n) => match n {
            TermNamed::Black => TuiColor::Black,
            TermNamed::Red => TuiColor::Red,
            TermNamed::Green => TuiColor::Green,
            TermNamed::Yellow => TuiColor::Yellow,
            TermNamed::Blue => TuiColor::Blue,
            TermNamed::Magenta => TuiColor::Magenta,
            TermNamed::Cyan => TuiColor::Cyan,
            TermNamed::White => TuiColor::Gray,
            TermNamed::BrightBlack => TuiColor::DarkGray,
            TermNamed::BrightRed => TuiColor::LightRed,
            TermNamed::BrightGreen => TuiColor::LightGreen,
            TermNamed::BrightYellow => TuiColor::LightYellow,
            TermNamed::BrightBlue => TuiColor::LightBlue,
            TermNamed::BrightMagenta => TuiColor::LightMagenta,
            TermNamed::BrightCyan => TuiColor::LightCyan,
            TermNamed::BrightWhite => TuiColor::White,
        },
        TerminalColor::Indexed(i) => TuiColor::Indexed(i),
        TerminalColor::Rgb(r, g, b) => TuiColor::Rgb(r, g, b),
    }
}

/// Build the ratatui `Style` for a terminal cell's SGR fg/bg/attrs.
fn terminal_cell_style(
    fg: lattice_terminal::TerminalColor,
    bg: lattice_terminal::TerminalColor,
    attrs: lattice_terminal::CellAttrs,
) -> ratatui::style::Style {
    use ratatui::style::{Modifier, Style};
    let mut s = Style::default().fg(term_to_tui(fg)).bg(term_to_tui(bg));
    let mut m = Modifier::empty();
    if attrs.bold {
        m |= Modifier::BOLD;
    }
    if attrs.italic {
        m |= Modifier::ITALIC;
    }
    if attrs.underline {
        m |= Modifier::UNDERLINED;
    }
    if attrs.reverse {
        m |= Modifier::REVERSED;
    }
    if attrs.dim {
        m |= Modifier::DIM;
    }
    if attrs.strikethrough {
        m |= Modifier::CROSSED_OUT;
    }
    if !m.is_empty() {
        s = s.add_modifier(m);
    }
    s
}

/// Build the styled spans for one terminal grid row. Adjacent cells
/// with identical resolved style coalesce into one `Span`.
///
/// **Width contract** (see `docs/dev/audit/terminal-wide-char-ghosting.md`):
/// a width-2 glyph occupies two grid cells — the glyph plus a
/// `wide_spacer` placeholder. Spacer cells are SKIPPED so the row's
/// total display width equals `cols_to_paint`; the wide glyph owns
/// its second display column via ratatui's own shaping. Emitting the
/// spacer as a space would make the row one column wide per glyph and
/// corrupt ratatui's width-based cell diff (the auto-scroll ghosting
/// bug).
#[allow(clippy::too_many_arguments)]
fn terminal_row_spans(
    snap: &lattice_terminal::TerminalSnapshot,
    row: u16,
    cols_to_paint: u16,
    paint_cursor_cell: bool,
    cursor_row: u16,
    cursor_col: u16,
    match_overlay: Option<(u16, u16, u16)>,
    all_matches: &[lattice_terminal::GridSearchHit],
    visual: Option<lattice_terminal::TerminalVisualState>,
) -> Vec<ratatui::text::Span<'static>> {
    use ratatui::style::{Modifier, Style};
    use ratatui::text::Span;
    let mut spans: Vec<Span> = Vec::new();
    let mut run_text = String::with_capacity(cols_to_paint as usize);
    let mut run_style: Option<Style> = None;
    for col in 0..cols_to_paint {
        let cell = snap.cell_at(row, col);
        // Width contract: a wide glyph owns its two display columns via
        // ratatui's own shaping; its trailing `wide_spacer` cell must NOT
        // be emitted as a stray space (that pushes the row one column wide
        // per glyph and corrupts ratatui's width-based cell diff — the
        // auto-scroll ghosting bug). Skip it so grid col stays 1:1 with
        // display col. See docs/dev/audit/terminal-wide-char-ghosting.md.
        if cell.wide_spacer {
            continue;
        }
        let mut style = terminal_cell_style(cell.fg, cell.bg, cell.attrs);
        // Splice the cursor cell on inactive panes (the active pane
        // uses the hardware cursor).
        if paint_cursor_cell && row == cursor_row && col == cursor_col {
            style = style.add_modifier(Modifier::REVERSED);
        }
        // Hlsearch-style soft underline for every all_matches hit.
        if !all_matches.is_empty() {
            let off = snap.scroll_offset as i32;
            let cell_line = row as i32 - off;
            for h in all_matches {
                if h.line == cell_line {
                    let c_start = h.column;
                    let c_end = h.column.saturating_add(h.len.min(u16::MAX as u32) as u16);
                    if col >= c_start && col < c_end {
                        style = style.add_modifier(Modifier::UNDERLINED);
                        break;
                    }
                }
            }
        }
        // Current match wins style precedence on its row.
        if let Some((m_row, c_start, c_end)) = match_overlay
            && row == m_row
            && col >= c_start
            && col < c_end
        {
            style = style.add_modifier(Modifier::REVERSED);
        }
        // Visual selection cells paint REVERSED (per-kind predicate).
        if let Some(v) = visual {
            use lattice_terminal::VisualKind as Vk;
            let off = snap.scroll_offset as i32;
            let cell_line = row as i32 - off;
            let in_sel = match v.kind {
                Vk::Line => {
                    let (lo, hi) = v.line_range();
                    cell_line >= lo && cell_line <= hi
                }
                Vk::Block => {
                    let (lo, hi) = v.line_range();
                    let (lo_c, hi_c) = v.block_col_range();
                    cell_line >= lo && cell_line <= hi && col >= lo_c && col <= hi_c
                }
                Vk::Char => {
                    let ((sl, sc), (el, ec)) = v.char_endpoints();
                    if sl == el {
                        cell_line == sl && col >= sc && col <= ec
                    } else if cell_line == sl {
                        col >= sc
                    } else if cell_line == el {
                        col <= ec
                    } else {
                        cell_line > sl && cell_line < el
                    }
                }
            };
            if in_sel {
                style = style.add_modifier(Modifier::REVERSED);
            }
        }
        match run_style {
            Some(prev) if prev == style => {
                run_text.push(cell.ch);
            }
            _ => {
                if !run_text.is_empty() {
                    spans.push(Span::styled(
                        std::mem::take(&mut run_text),
                        run_style.unwrap_or_default(),
                    ));
                }
                run_text.push(cell.ch);
                run_style = Some(style);
            }
        }
    }
    if !run_text.is_empty() {
        spans.push(Span::styled(run_text, run_style.unwrap_or_default()));
    }
    spans
}

/// Issue #40 / Terminal-mode T1: paint the terminal cell grid
/// from the published `TerminalSnapshot`. T1 ignores the
/// per-cell fg/bg/attrs and renders monochrome — T2 wires
/// alacritty_terminal's real SGR colors via the same path.
fn draw_terminal_pane(
    frame: &mut Frame,
    area: Rect,
    app: &App,
    pane: &crate::pane::PaneState,
    is_active: bool,
) {
    use ratatui::text::{Line, Span};
    use ratatui::widgets::Paragraph;
    let rs = app.render_state.load();
    let (snap_arc, current_match, mut visual, all_matches, mut nav_cursor) =
        match rs.buffers.registry.with_terminal(pane.buffer_id, |t| {
            (
                t.snapshot.load_full(),
                t.current_match,
                t.visual,
                t.all_matches.clone(),
                t.nav_cursor,
            )
        }) {
            Some(p) => p,
            None => {
                let p = Paragraph::new(Line::from(Span::raw("(terminal buffer unavailable)")));
                frame.render_widget(p, area);
                return;
            }
        };
    // T-clean-1 Phase A.2 (2026-05-28): for the active pane,
    // prefer the publisher's derived values from
    // `rs.active_document.load().terminal_nav_cursor` /
    // `terminal_visual` (computed from `self.cursor` (doc-space)
    // + `synthetic.origin_top_line`). This is the path that
    // will retire `t.nav_cursor` / `t.visual` direct reads
    // entirely once per-pane publishing lands. Inactive panes
    // keep using `with_terminal` (their stashed values are
    // intentionally last-known-good across pane switches).
    if is_active {
        if rs.active_document.load().terminal_nav_cursor.is_some() {
            nav_cursor = rs.active_document.load().terminal_nav_cursor;
        }
        if rs.active_document.load().terminal_visual.is_some() {
            visual = rs.active_document.load().terminal_visual;
        }
    }
    let rows_to_paint = area.height.min(snap_arc.rows);
    let cols_to_paint = area.width.min(snap_arc.cols);
    // Diagnostic probe (opt-in via RUST_LOG=lattice_ui_tui::terminal_clip=debug):
    // fires whenever the PTY's own row/col count (what alacritty and the
    // child process believe their screen size is) exceeds this frame's real
    // paint area. That gap is exactly what makes `rows_to_paint` cut the
    // BOTTOM of the terminal's content (the last N rows of the PTY grid —
    // often where a full-screen program like `claude` puts its prompt /
    // status — are never painted). If the "last line clipped" bug persists
    // after the `empty_sized` placeholder fix (spawner.rs), enable this to
    // capture the exact PTY-vs-pane numbers at the moment it happens.
    if snap_arc.rows > area.height || snap_arc.cols > area.width {
        tracing::debug!(
            target: "lattice_ui_tui::terminal_clip",
            pty_rows = snap_arc.rows,
            pty_cols = snap_arc.cols,
            pane_area_rows = area.height,
            pane_area_cols = area.width,
            rows_to_paint,
            cols_to_paint,
            "draw_terminal_pane: PTY believes it is larger than the paint area — \
             the bottom/right of its content is not being painted",
        );
    }
    // 2026-05-25: nav_cursor overrides the PTY cursor in
    // Normal-in-terminal so the user sees a "you are here"
    // marker that j / k / etc. moves. When nav_cursor is None
    // we fall back to the live PTY cursor (the snapshot's
    // cursor_row/col).
    let (cursor_row, cursor_col, cursor_visible) = if let Some((nav_l, nav_c)) = nav_cursor {
        let off = snap_arc.scroll_offset as i32;
        let row = nav_l + off;
        if (0..rows_to_paint as i32).contains(&row) && nav_c < cols_to_paint {
            (row as u16, nav_c, true)
        } else {
            (0, 0, false)
        }
    } else {
        let r = snap_arc.cursor_row;
        let c = snap_arc.cursor_col;
        let v = snap_arc.cursor_visible && r < rows_to_paint && c < cols_to_paint;
        (r, c, v)
    };
    // Per-cell SGR colour + style mapping and the row-span builder
    // live as module-level fns (`term_to_tui`, `terminal_cell_style`,
    // `terminal_row_spans`) so the wide-char width contract is unit-
    // testable. See `docs/dev/audit/terminal-wide-char-ghosting.md`.
    // Terminal-mode T2.b (2026-05-25): the active pane drives the
    // ratatui hardware cursor at the terminal's grid position, so
    // the user sees a real terminal cursor with the right shape
    // (block in Normal-in-terminal, bar in Terminal-Insert — set
    // by `runtime::cursor_style_for`). The cell-reverse splice
    // stays on inactive panes since the hardware cursor can only
    // be in one place at a time.
    let paint_cursor_cell = cursor_visible && !is_active;
    // T3.b.3: translate the current_match's alacritty grid
    // line into the snapshot's visible-window row coordinates.
    // `snap.scroll_offset` is the number of rows scrolled back
    // from the live edge; the topmost visible row corresponds
    // to alacritty `Line(-scroll_offset)`. A match at grid
    // line `L` therefore lands at visible row `L + scroll_offset`.
    let match_overlay = current_match.and_then(|h| {
        let row = h.line + snap_arc.scroll_offset as i32;
        if (0..rows_to_paint as i32).contains(&row) {
            let col_start = h.column;
            let col_end = h
                .column
                .saturating_add(h.len.min(u16::MAX as u32) as u16)
                .min(cols_to_paint);
            Some((row as u16, col_start, col_end))
        } else {
            None
        }
    });
    // T3.b.2 / T3.b.2.b: Visual selection predicate. Walks
    // each cell and asks "is this in the selection?" based on
    // kind. Char + block need col-precision so the row-range
    // shortcut isn't enough.
    let visual_state = visual;
    // Row spans (with cursor / match / visual overlays and the
    // wide-char width contract) are built by `terminal_row_spans`.
    let lines: Vec<Line> = (0..rows_to_paint)
        .map(|row| {
            Line::from(terminal_row_spans(
                &snap_arc,
                row,
                cols_to_paint,
                paint_cursor_cell,
                cursor_row,
                cursor_col,
                match_overlay,
                &all_matches,
                visual_state,
            ))
        })
        .collect();
    let para = Paragraph::new(lines);
    frame.render_widget(para, area);
    // Place the hardware cursor on the active pane only —
    // ratatui's frame.set_cursor_position drives the terminal's
    // single hardware cursor, so multi-pane setups would race
    // without the active gate. Out-of-area positions are clamped
    // so a stale snapshot can't park the cursor outside the pane.
    if is_active && cursor_visible {
        let screen_x = area
            .x
            .saturating_add(cursor_col)
            .min(area.x + area.width.saturating_sub(1));
        let screen_y = area
            .y
            .saturating_add(cursor_row)
            .min(area.y + area.height.saturating_sub(1));
        frame.set_cursor_position((screen_x, screen_y));
    }
}

// M.4: per-mode pane-render adapters. Each adapter has the
// uniform [`crate::pane_render::PaneRenderFn`] signature; the
// existing per-kind draw fns retain their original signatures and
// the adapter forwards the relevant subset.

fn help_pane_render(
    frame: &mut Frame,
    area: Rect,
    app: &App,
    snap: &DocumentSnapshot,
    pane: &crate::pane::PaneState,
    is_active: bool,
    _idx: usize,
) {
    // PU.1b-2b: in-pane help is a Document — its markdown `SyntaxHandle`
    // + link `ExtraHighlights` are baked into the cells-worker
    // `DisplayMatrix` — so it renders through the SAME compose path as
    // any document, with NO bespoke help painter. help-mode's options
    // (`nonu`, `signcolumn=no`, `wrap`) give it the clean gutterless
    // wrapped look the old `draw_help_in_pane` hand-rolled. This provider
    // stays registered only for `help_pane_status` (the status-line
    // contribution); the render arm forwards to the generic path, so a
    // help pane is pixel-equivalent to a `:set nonu signcolumn=no wrap`
    // document (K.4 / `feedback_render_is_option_derived`).
    draw_pane_document(frame, area, app, snap, pane, is_active);
}

fn help_pane_status(app: &App, _pane: &crate::pane::PaneState) -> String {
    app.popup_help()
        .map(|h| format!("[help] {}", h.title))
        .unwrap_or_else(|| "[help]".to_string())
}

fn file_tree_pane_status(app: &App, pane: &crate::pane::PaneState) -> String {
    // Slice 3c.final.B.9: buffer_locals via published map.
    let locals_map = app.buffer_locals();
    let root = locals_map
        .map
        .get(&pane.buffer_id)
        .and_then(|locals| locals.get::<crate::modes::FileTreeRoot>())
        .map(|r| r.0.clone());
    root.map(|p| format!("[tree] {}", p.display()))
        .unwrap_or_else(|| "[tree]".to_string())
}

fn oil_pane_status(app: &App, pane: &crate::pane::PaneState) -> String {
    // Slice 3c.final.E.5j: `with_oil` via published `buffers()` sub-
    // state; OilDir buffer-local via `read_editor`.
    let dirty_opt = app
        .buffers()
        .registry
        .document_handle(pane.buffer_id)
        .map(|h| h.snapshot().buffer.as_string())
        .and_then(|text| {
            app.buffer_locals()
                .map
                .get(&pane.buffer_id)
                .and_then(|l| l.get::<lattice_listing::oil::modes::OilSnapshotLocal>())
                .map(|s| s.0.is_dirty(&text))
        });
    let Some(is_dirty) = dirty_opt else {
        return "[oil]".to_string();
    };
    let dirty = if is_dirty { " [+]" } else { "" };
    // Slice 3c.final.B.9: OilDir via published map.
    let locals_map = app.buffer_locals();
    let dir: String = locals_map
        .map
        .get(&pane.buffer_id)
        .and_then(|locals| locals.get::<crate::modes::OilDir>())
        .map(|d| d.0.display().to_string())
        .unwrap_or_default();
    format!("[oil] {dir}{dirty}")
}

/// Boot-time registration of the renderer-side providers for the
/// built-in modes. Plugin-installed modes (post-1.0) extend this
/// registry through the same interface.
pub fn build_pane_render_registry() -> crate::pane_render::PaneRenderRegistry {
    use crate::pane_render::{PaneRenderProvider, PaneRenderRegistry};
    use lattice_mode::Mode;
    let mut registry = PaneRenderRegistry::new();
    // Help-mode is a *minor* mode layered onto markdown-mode; the
    // pane-render dispatcher walks minors first, so this entry
    // wins over markdown's default (document) path when the
    // help-mode minor is active.
    registry.register(
        lattice_mode::modes::HelpMode.id(),
        PaneRenderProvider {
            render: Some(help_pane_render),
            status: help_pane_status,
        },
    );
    // DL.4: the file tree has NO `render` provider — it is a Document
    // now and paints through the shared compose path like every other
    // buffer. Only the status label stays mode-owned.
    registry.register_status_only(
        lattice_listing::file_tree::FileTreeMode.id(),
        file_tree_pane_status,
    );
    // DL.5: oil has NO `render` provider either — the last bespoke
    // listing painter is gone, so both listing kinds paint through the
    // shared compose path. Only the status label is mode-owned.
    registry.register_status_only(lattice_listing::oil::OilMode.id(), oil_pane_status);
    registry
}

/// Walk the pane rects and draw a vertical separator wherever two
/// rects share a vertical seam (same y range, A's right edge ==
/// B's left edge). Uses [`Theme::pane_separator_vertical`] for the
/// glyph and [`Theme::pane_separator`] for the style.
fn draw_pane_separators(frame: &mut Frame, rects: &[(usize, crate::pane::PaneRect)], app: &App) {
    let glyph = app.theme.pane_separator_vertical;
    let style = app.theme.pane_separator;
    for (col, y_start, y_end) in separator_segments(rects) {
        for row in y_start..y_end {
            let r = Rect {
                x: col,
                y: row,
                width: 1,
                height: 1,
            };
            let para = Paragraph::new(Line::from(Span::styled(glyph.to_string(), style)));
            frame.render_widget(para, r);
        }
    }
}

/// Compute the vertical separator segments between horizontally
/// adjacent panes. Each segment is `(col, y_start, y_end)` (half-open
/// row range) painted on the boundary column shared by a left pane's
/// right edge and a right pane's left edge.
///
/// The separator is drawn over the *vertical overlap* of the two
/// panes, NOT the full height of either. This is what lets a column
/// that has itself been sub-split (e.g. `:vsplit` then `:split` the
/// left pane) still get a continuous divider against the neighbour:
/// each stacked sub-pane contributes the segment covering its own
/// rows. The earlier "same band" gate (`a.y == b.y && a.height ==
/// b.height`) required identical rects and silently dropped the
/// divider whenever one side was sub-split.
fn separator_segments(rects: &[(usize, crate::pane::PaneRect)]) -> Vec<(u16, u16, u16)> {
    let mut segments = Vec::new();
    for (i, (_, a)) in rects.iter().enumerate() {
        for (_, b) in rects.iter().skip(i + 1) {
            // Identify which pane sits directly to the left of the
            // other (order in `rects` is tree-walk order, not sorted
            // by x), so both `a|b` and `b|a` adjacencies are caught.
            let (left, right) = if a.x + a.width == b.x {
                (a, b)
            } else if b.x + b.width == a.x {
                (b, a)
            } else {
                continue;
            };
            let y_start = left.y.max(right.y);
            let y_end = (left.y + left.height).min(right.y + right.height);
            if y_start < y_end {
                segments.push((left.x + left.width - 1, y_start, y_end));
            }
        }
    }
    segments
}

/// One-row status line at the bottom of a pane (vim's "statusline"
/// per-window). ML.1a-render: the row is laid out from the registered
/// modeline elements (`RenderState.modeline_elements`) in three zones —
/// Left (flush-left), Right (flush-right, the block right-aligned),
/// Center (centered in the gap). Built-in (`core.*`) content is resolved
/// per pane *host-side* (`lattice_host::modeline`), so the TUI and GPUI
/// peers paint identical content; only this layout/paint is
/// renderer-specific. The Center zone is fed by the temporary mode-items
/// pull until ML.3 migrates LSP/diff to registered elements.
///
/// Active pane is reverse-videoed; inactive panes are dim — one
/// `pane_status_*` style for the whole row until ML.1b's per-role
/// theming resolves each span's `ModelineRole` through `ResolvedTheme`.
fn draw_pane_status_line(
    frame: &mut Frame,
    area: Rect,
    app: &App,
    pane: &crate::pane::PaneState,
    is_active: bool,
) {
    let width = area.width as usize;
    if width == 0 {
        return;
    }
    let segments = modeline_segments(app, pane, is_active, width);
    // ML.4: record before painting, from the same run list the painter
    // consumes, so the click map and the pixels come from one source.
    record_modeline_hits(&mut app.modeline_hits.borrow_mut(), area, &segments);
    let spans = segments_to_spans(app, &segments, is_active);
    frame.render_widget(Paragraph::new(Line::from(spans)), area);
}

/// One styled run within the modeline: text, its theme role (`None` =
/// neutral padding / separator, painted as the bar base only), and
/// (ML.4) the command a click on it dispatches.
///
/// This was a bare `(String, Option<ModelineRole>)` tuple until ML.4.
/// It had to grow identity because a terminal has no element tree to
/// hang a listener on: the only way to know what the user clicked is to
/// remember which columns each element painted into, which means the
/// run has to carry its element's action all the way through layout
/// and truncation.
#[derive(Debug, Clone, PartialEq, Eq)]
struct ModelineSeg {
    text: String,
    role: Option<lattice_mode::ModelineRole>,
    /// `None` for padding, separators, and elements that declared no
    /// `on_click` — i.e. almost everything.
    click: Option<lattice_protocol::CommandId>,
}

impl ModelineSeg {
    /// A neutral run: padding, separator, or filler. Never clickable.
    fn filler(text: String) -> Self {
        Self {
            text,
            role: None,
            click: None,
        }
    }

    fn width(&self) -> usize {
        self.text.chars().count()
    }
}

/// Flatten an element's content into role-tagged runs, dropping empty
/// spans.
///
/// ML.4: every run of one element carries that element's `on_click`, so
/// clicking anywhere on a multi-span element (an icon plus its label,
/// say) fires the same command — which is what a user means by
/// "clicking the element".
fn content_to_runs(
    content: lattice_mode::ElementContent,
    click: Option<lattice_protocol::CommandId>,
) -> Vec<ModelineSeg> {
    content
        .spans
        .into_iter()
        .filter(|s| !s.text.is_empty())
        .map(|s| ModelineSeg {
            text: s.text,
            role: Some(s.role),
            click,
        })
        .collect()
}

/// Build the per-Span modeline line for `pane` (ML.1b). Resolves each
/// zone's content into role-tagged runs via the shared host resolver,
/// lays them out into `width` columns, then maps each role → a ratatui
/// style through the theme cache ([`crate::theme::Theme::modeline_style`]).
/// Extracted from [`draw_pane_status_line`] so tests can assert span text +
/// style without a frame. The whole row sits on the active/inactive
/// bar; per-role foregrounds compose over it.
fn modeline_segments(
    app: &App,
    pane: &crate::pane::PaneState,
    is_active: bool,
    width: usize,
) -> Vec<ModelineSeg> {
    let rs = app.render_state.load();
    let snap = &rs.modeline_elements;
    // The file-tree / oil / help custom label (M.4 provider mechanism) is
    // the one renderer-resolved content input; it overrides `core.path`.
    // Resolved once and threaded into the shared host resolver so the
    // assembly stays common across peers.
    // PI.3: the per-pane status line reports the pane's COMMITTED buffer,
    // not the previewed one (design §5) — the modeline shows what you'd
    // save / switch back to. `core.path` already comes from the active
    // document's `modeline_elements`; the provider label resolves against
    // the committed buffer too.
    let provider_label = app
        .pane_render_provider(pane.committed_id())
        .map(|p| (p.status)(app, pane));
    let provider_ref = provider_label.as_deref();

    // ML.5: the `ui.modeline.{left,center,right}` config drives zone
    // membership + order; `resolve_layout` returns the per-zone
    // descriptor lists (Auto = descriptor placement) + the configured
    // separator. The renderer still resolves each descriptor's content
    // itself (built-ins host-side, pushed from the snapshot).
    let layout = lattice_host::modeline::resolve_layout(&snap.registry, &rs.options.config);
    let sep = layout.separator.clone();
    let resolve_zone = |els: &[&lattice_mode::ModelineElement]| -> Vec<ModelineSeg> {
        let mut runs: Vec<ModelineSeg> = Vec::new();
        for el in els {
            // §7: Global-scope elements (e.g. the diff summary) render
            // only on the active pane; PaneLocal is the default.
            if matches!(el.scope, lattice_mode::Scope::Global) && !is_active {
                continue;
            }
            let id = el.id.as_str();
            let content = if id.starts_with("core.") {
                lattice_host::modeline::resolve_builtin_content(
                    id,
                    pane,
                    is_active,
                    &rs,
                    provider_ref,
                )
            } else {
                // Pushed elements (modes / plugins, ML.3): content from
                // the published store, resolved per the descriptor's
                // scope against this pane's buffer (PaneLocal) or the
                // global slot.
                snap.resolve(el, pane.buffer_id)
                    .cloned()
                    .unwrap_or_default()
            };
            if content.is_empty() {
                continue;
            }
            // Configured separator between elements within a zone
            // (`ui.modeline.separator`, default a single space).
            if !runs.is_empty() && !sep.is_empty() {
                runs.push(ModelineSeg::filler(sep.clone()));
            }
            // ML.4: the descriptor's declared click target rides along
            // with its runs. The separator above deliberately does not
            // get one — the gap between two elements belongs to
            // neither.
            let click = el.interaction.as_ref().and_then(|i| i.on_click);
            runs.extend(content_to_runs(content, click));
        }
        runs
    };

    let left = resolve_zone(&layout.left);
    let center = resolve_zone(&layout.center);
    let right = resolve_zone(&layout.right);

    compose_modeline_segments(width, layout.padding, left, center, right)
}

/// Paint a composed run list as ratatui spans.
fn segments_to_spans(app: &App, segments: &[ModelineSeg], is_active: bool) -> Vec<Span<'static>> {
    segments
        .iter()
        .map(|seg| {
            let style = app
                .theme
                .modeline_style(seg.role.as_ref().map(|r| r.as_str()), is_active);
            Span::styled(seg.text.clone(), style)
        })
        .collect()
}

/// ML.4: record every clickable run's absolute cell span into `hits`.
///
/// Walks the composed runs left to right accumulating columns, which is
/// exactly how the painter lays them down — so the recorded regions
/// cannot disagree with what the user sees unless the painter itself
/// changes. `area` is the modeline's own `Rect`, so this handles splits
/// (each pane's modeline records its own column range on its own row)
/// with no extra work.
fn record_modeline_hits(
    hits: &mut lattice_host::modeline::ModelineHitMap,
    area: Rect,
    segments: &[ModelineSeg],
) {
    let mut col = area.x;
    for seg in segments {
        let w = seg.width() as u16;
        if let Some(action) = seg.click {
            hits.push(lattice_host::modeline::ModelineHitZone {
                row: area.y,
                col_start: col,
                // Clip to the pane's own width: a run can only be
                // clicked where it was actually painted.
                col_end: col.saturating_add(w).min(area.x + area.width),
                action,
            });
        }
        col = col.saturating_add(w);
    }
}

/// Truncate `s` to at most `max` display columns (char count), adding a
/// `…` ellipsis when it overflows. `max == 0` ⇒ empty; `max == 1` ⇒ just
/// the ellipsis. Never panics.
fn truncate_to(s: &str, max: usize) -> String {
    if s.chars().count() <= max {
        return s.to_string();
    }
    match max {
        0 => String::new(),
        1 => "…".to_string(),
        _ => {
            let mut out: String = s.chars().take(max - 1).collect();
            out.push('…');
            out
        }
    }
}

/// Total display width (char count) of a run list.
fn runs_width(runs: &[ModelineSeg]) -> usize {
    runs.iter().map(|s| s.width()).sum()
}

/// Truncate a run list to at most `max` columns, ellipsising the run that
/// straddles the boundary (preserving its role and its click target).
/// Never panics.
///
/// ML.4: the ellipsised remnant keeps its `click`. A half-visible
/// element is still that element — refusing the click on the grounds
/// that it got shortened would make clickability depend on pane width,
/// which the user experiences as the modeline randomly not working.
fn truncate_runs(runs: Vec<ModelineSeg>, max: usize) -> Vec<ModelineSeg> {
    let mut out: Vec<ModelineSeg> = Vec::new();
    let mut used = 0usize;
    for seg in runs {
        let w = seg.width();
        if used + w <= max {
            used += w;
            out.push(seg);
        } else {
            let remaining = max - used;
            if remaining > 0 {
                out.push(ModelineSeg {
                    text: truncate_to(&seg.text, remaining),
                    ..seg
                });
            }
            break;
        }
    }
    out
}

/// Lay three role-tagged run lists into a `width`-wide row of styled
/// segments: Left flush-left, Right flush-right (block right-aligned),
/// Center centered in the gap. On overflow, sacrifice **Center first,
/// then Right, then Left** (design §7) via greedy keep-priority
/// Left > Right > Center, each block ellipsised to its remaining budget.
/// Padding / separator segments carry no role (`None`) → the bar base.
/// The returned segments sum to exactly `width` columns (empty when
/// `width == 0`). Saturating throughout: never panics, blocks never
/// overlap (≥1 column between any two non-empty blocks).
fn compose_modeline_segments(
    width: usize,
    padding: usize,
    left: Vec<ModelineSeg>,
    center: Vec<ModelineSeg>,
    right: Vec<ModelineSeg>,
) -> Vec<ModelineSeg> {
    if width == 0 {
        return Vec::new();
    }
    // `ui.modeline.padding`: reserve a blank margin on each edge, lay the
    // zones out into the inner width, then bookend with the margins so the
    // total is still exactly `width`. Capped at half-width so a huge
    // padding on a narrow pane can't underflow.
    let pad = padding.min(width / 2);
    if pad > 0 {
        let inner = compose_modeline_segments(width - 2 * pad, 0, left, center, right);
        let mut out: Vec<ModelineSeg> = Vec::with_capacity(inner.len() + 2);
        out.push(ModelineSeg::filler(" ".repeat(pad)));
        out.extend(inner);
        out.push(ModelineSeg::filler(" ".repeat(pad)));
        return out;
    }
    // Left is highest-priority: keep as much as fits.
    let left = truncate_runs(left, width);
    let used_l = runs_width(&left);
    // Right gets the remainder after Left + a 1-col separator.
    let sep_lr = if used_l > 0 { 1 } else { 0 };
    let right = truncate_runs(right, width.saturating_sub(used_l + sep_lr));
    let used_r = runs_width(&right);
    // Center gets the gap minus a 1-col pad on each abutting side.
    let pad_l = if used_l > 0 { 1 } else { 0 };
    let pad_r = if used_r > 0 { 1 } else { 0 };
    let center_budget = width.saturating_sub(used_l + used_r + pad_l + pad_r);
    let center = truncate_runs(center, center_budget);
    let used_c = runs_width(&center);

    let mut out: Vec<ModelineSeg> = Vec::new();
    out.extend(left);
    // Region between the left block and the right block (≥ 0 by budget).
    let region_w = width - used_l - used_r;
    if used_c > 0 {
        let offset = (region_w - used_c) / 2;
        if offset > 0 {
            out.push(ModelineSeg::filler(" ".repeat(offset)));
        }
        out.extend(center);
        let after = region_w - used_c - offset;
        if after > 0 {
            out.push(ModelineSeg::filler(" ".repeat(after)));
        }
    } else if region_w > 0 {
        out.push(ModelineSeg::filler(" ".repeat(region_w)));
    }
    out.extend(right);
    out
}

/// DR.3 (decoration-retention): render a Document pane that isn't
/// focused. This is now a thin entry point — it builds the per-pane
/// [`PaneComposeCtx`] (`is_active: false`, the pane's OWN buffer /
/// cursor / scroll / display-line-number map) and a `for_buffer`
/// [`FrameView`], then defers to the SAME [`compose_pane_lines`] the
/// active pane uses via [`draw_buffer`]. The old parallel inactive
/// compose body — a smaller, drifting decoration set keyed on focus —
/// is retired; the only inactive-specific behaviour now lives in the
/// ctx flags (interaction overlays off, dim opacity on) interpreted
/// inside the one shared path. Inactive panes therefore carry the
/// FULL buffer-intrinsic decoration set (syntax, semantic tokens,
/// inlay hints, diagnostics) dimmed, per the design's §Render
/// contract.
/// Assemble the compose inputs for ONE pane.
///
/// The single place a pane's `FrameView` and `PaneComposeCtx` are built, for
/// both the focused pane and every other one. There used to be two — an
/// `is_active` builder inside `compose_visible_lines` and a second inside
/// `draw_inactive_document` — and they disagreed about where a pane's options
/// come from: the active one read `ad().option_cache` (the active DOCUMENT),
/// the inactive one resolved against the pane's own buffer. That is how a
/// focused magit pane came to paint with the file's `number` and lose it again
/// on blur.
///
/// `is_active` survives, but only as what it should have been: a flag for
/// INTERACTION state — whose cursor and scroll to read, and whether this pane
/// paints a cursorline. Everything that is a property of the buffer being
/// painted is resolved from `pane.buffer_id` either way.
fn pane_compose_inputs<'a>(
    app: &'a App,
    pane: &crate::pane::PaneState,
    is_active: bool,
) -> (FrameView<'a>, PaneComposeCtx) {
    // M.4: options for THIS pane's buffer — its own mode stack drives its
    // gutter and LSP gates — whether or not it is the focused one.
    let view = FrameView::for_buffer(app, pane.buffer_id);
    // Per-pane composed→source row map, pulled from the pane's OWN handle: a
    // multibuffer pane shows source line numbers whoever is focused, and a
    // regular Document returns None (identity numbering). The GPUI peer takes
    // it from the same handle for the same reason.
    let display_line_numbers = app
        .buffers()
        .registry
        .document_handle(pane.buffer_id)
        .and_then(|h| h.display_line_numbers());
    // PI.3: a focused pane that is PREVIEWING renders through the unfocused
    // path (routed in `draw_panes`) but keeps its cursorline, so the target
    // line of an LSP-reference or grep preview stays highlighted. Ordinary
    // unfocused panes paint none.
    let focused_preview = pane.is_previewing() && app.panes().tree.active().id == pane.id;
    // The OPTION is a property of the buffer; whether this pane paints one at
    // all is interaction state. Splitting the two is what lets one expression
    // serve both paths.
    let cursor_line_highlight = (is_active || focused_preview)
        && app
            .render_state
            .load()
            .current_line_highlight_for(pane.buffer_id);

    // The one genuine difference: the focused pane's cursor and scroll are
    // LIVE in `ad()`, while a pane's stashed copy is only written when it
    // loses focus — so reading the stash for the active pane would render it
    // one focus-change stale.
    let ctx = if is_active {
        let ad = app.ad();
        PaneComposeCtx {
            is_active,
            pane_id: pane.id,
            buffer_id: pane.buffer_id,
            cursor_line: ad.cursor.line,
            cursor_line_highlight,
            scroll: ad.scroll,
            leftcol: ad.leftcol,
            display_line_numbers,
        }
    } else {
        PaneComposeCtx {
            is_active,
            pane_id: pane.id,
            buffer_id: pane.buffer_id,
            cursor_line: pane.cursor.line,
            cursor_line_highlight,
            scroll: pane.scroll,
            leftcol: pane.leftcol,
            display_line_numbers,
        }
    };
    (view, ctx)
}

/// Paint one document pane — focused or not.
///
/// The unification: `draw_buffer` and `draw_inactive_document` were two
/// functions that opened differently, built their compose inputs differently,
/// and then called the same `compose_pane_lines`. The duplicated half is the
/// half that drifted, and dimming — the thing that actually distinguishes an
/// unfocused pane — was never in either of them: it lives inside
/// `compose_pane_lines`, keyed on `ctx.is_active`, exactly where a decoration
/// belongs.
///
/// So what is left of `is_active` here is the terminal caret, which only the
/// focused pane owns.
fn draw_pane_document(
    frame: &mut Frame,
    area: Rect,
    app: &App,
    snap: &DocumentSnapshot,
    pane: &crate::pane::PaneState,
    is_active: bool,
) {
    // The focused pane paints the frame's already-taken snapshot, so its text
    // cannot tear against the cursor and scroll read beside it. Another pane
    // has no such snapshot and reads its own handle's.
    let owned;
    let snap = if is_active {
        snap
    } else {
        let Some(handle) = app.buffers().registry.document_handle(pane.buffer_id) else {
            return;
        };
        owned = handle.snapshot();
        &owned
    };
    let (view, ctx) = pane_compose_inputs(app, pane, is_active);
    let lines = compose_pane_lines(&view, snap, area.height as u32, area.width as u32, &ctx);
    frame.render_widget(Paragraph::new(lines), area);

    if !is_active {
        return;
    }
    // Place the buffer-area cursor only when a minibuffer isn't claiming it.
    // In Command (`:`), Search (`/`, `?`) and Prompt the caret lives in the
    // bottom row -- handled by `draw_command_or_echo`.
    //
    // Shared with the popup path above through
    // `lattice_host::cursor_shape::minibuffer_owns_caret`, which also adds
    // `Prompt` — the local copy this replaces listed only two of the three
    // readline surfaces, so a prompt and the pane both placed the caret and
    // whichever drew last won.
    let ad = app.ad();
    let prompt_owns_cursor = lattice_host::cursor_shape::minibuffer_owns_caret(ad.modal);
    if !prompt_owns_cursor
        && let Some((screen_x, screen_y)) = cursor_screen_position_at(
            &view,
            snap,
            area,
            ad.cursor,
            ad.scroll,
            app.panes().tree.active().id,
        )
    {
        frame.set_cursor_position((screen_x, screen_y));
    }
}

fn draw_command_or_echo(frame: &mut Frame, area: Rect, app: &App) {
    // MB.2: the expanded tier-2 mini-buffer band — draw the multi-line
    // `*command-line*` buffer across the grown area (`:` prompt on line 0),
    // with the caret at the buffer's cursor. Full modal editing (the edit
    // path) is unchanged; this is the presentation grown in place.
    if app.command_line_expanded() {
        let modeline = app.modeline();
        let prompt: char = if modeline.search_direction.is_some() {
            match modeline.search_direction {
                Some(lattice_grammar::SearchDirection::Forward) => '/',
                Some(lattice_grammar::SearchDirection::Backward) => '?',
                _ => '/',
            }
        } else {
            ':'
        };
        let raw = modeline.cmdline_full_text.to_string();
        let deco = modeline.cmdline_decorations.as_ref();
        let cells = app.render_state.load().cells.load_full();
        let resolved = &cells.resolved_theme;
        let ids = &cells.theme_ids;
        let base = TuiStyle::default();
        let lines: Vec<Line<'static>> = raw
            .split('\n')
            .enumerate()
            .map(|(i, l)| {
                let line_str = if i == 0 {
                    format!("{prompt}{l}")
                } else {
                    l.to_string()
                };
                if i == 0
                    && let Some(d) = deco
                    && !d.spans.is_empty()
                {
                    let mut spans: Vec<Span<'_>> = Vec::with_capacity(d.spans.len() + 2);
                    let prompt_span = Span::raw(prompt.to_string());
                    let full_first = line_str.clone();
                    let first_line = l;
                    let prefix_len = prompt.len_utf8();
                    let mut pos = 0usize;
                    for sp in &d.spans {
                        let s = sp.range.start.min(first_line.len());
                        let e = sp.range.end.min(first_line.len());
                        if s < pos || e < s {
                            continue;
                        }
                        if s > pos {
                            spans.push(Span::styled(
                                full_first[pos + prefix_len..s + prefix_len].to_string(),
                                base,
                            ));
                        }
                        let styled = match lattice_host::ui::theme::resolve_syntax_style(
                            resolved, ids, sp.style,
                        )
                        .fg
                        .map(crate::theme::host_color_to_ratatui)
                        {
                            Some(c) => base.fg(c),
                            None => base,
                        };
                        spans.push(Span::styled(
                            full_first[s + prefix_len..e + prefix_len].to_string(),
                            styled,
                        ));
                        pos = e;
                    }
                    if pos < first_line.len() {
                        spans.push(Span::styled(
                            full_first[pos + prefix_len..].to_string(),
                            base,
                        ));
                    }
                    // Prepend the prompt character (":" / "/" / "?") as
                    // the first span, BEFORE the decorated content. The
                    // decoration spans are byte ranges into the raw line
                    // text and start at prefix_len, so they never include
                    // the prompt. Without this, the command line ":comp"
                    // renders as "comp" when decorations are present.
                    spans.insert(0, prompt_span);
                    return Line::from(spans);
                }
                Line::from(line_str)
            })
            .collect();
        frame.render_widget(Paragraph::new(lines), area);
        // Caret: buffer (line, byte) → band cell; the `:` prompt adds one
        // column on line 0. Clamp inside the band.
        let cur = app.ad().cursor;
        let lead: u16 = if cur.line == 0 { 1 } else { 0 };
        let cy = area.y.saturating_add(cur.line as u16);
        if cy < area.y.saturating_add(area.height) {
            let cx = area
                .x
                .saturating_add((cur.byte as u16).saturating_add(lead))
                .min(area.x.saturating_add(area.width.saturating_sub(1)));
            frame.set_cursor_position((cx, cy));
        }
        return;
    }
    if matches!(app.ad().modal, ModalState::Command) {
        // MB.1: ":<typed>" with the caret at the `*command-line*` buffer's
        // cursor (byte offset into the single line) so mid-line editing
        // shows where the user is typing — not pinned to the end.
        let line = app.command_line();
        let caret_byte = (app.ad().cursor.byte as usize).min(line.len());
        let cursor_col = area
            .x
            .saturating_add((1 + caret_byte).min(area.width as usize) as u16);

        // Visual hints. Two non-mutually-exclusive layers show
        // after the cursor in a dim style:
        //   1. `auto_submit_after_chord` (missing-arg prompt
        //      armed by `:describe-key<CR>`): show a clear
        //      "press a chord" cue so the user knows the next
        //      keypress runs the lookup.
        //   2. Otherwise, if chord-capture is just active
        //      (cursor in a `Chord` arg slot), show a softer
        //      `(chord)` tag so the user knows the cmdline is
        //      consuming raw key events as chord tokens.
        // Slice 3c.final.B.7: auto_submit hint via published
        // `modeline()` sub-state (wait-free Arc clone, no actor
        // round-trip).
        let hint: Option<&'static str> = if app.modeline().auto_submit_hint {
            Some("press a chord")
        } else if app.chord_capture_active() {
            Some("(chord)")
        } else {
            None
        };

        // MB.4: draw the `:` prompt then the line, coloured per the
        // published decoration spans (syntax highlight). The spans are
        // produced off the render thread; here we only map each token's
        // `Style` to its themed colour and slice the line.
        let cells = app.render_state.load().cells.load_full();
        let resolved = &cells.resolved_theme;
        let ids = &cells.theme_ids;
        let modeline = app.modeline();
        let deco = modeline.cmdline_decorations.as_ref();
        let base = TuiStyle::default();
        let mut spans: Vec<Span<'_>> = vec![Span::raw(":".to_string())];
        match deco {
            Some(d) if !d.spans.is_empty() => {
                let mut pos = 0usize;
                for sp in &d.spans {
                    let s = sp.range.start.min(line.len());
                    let e = sp.range.end.min(line.len());
                    if s < pos || e < s || !line.is_char_boundary(s) || !line.is_char_boundary(e) {
                        continue;
                    }
                    if s > pos {
                        spans.push(Span::styled(line[pos..s].to_string(), base));
                    }
                    let styled = match lattice_host::ui::theme::resolve_syntax_style(
                        resolved, ids, sp.style,
                    )
                    .fg
                    .map(crate::theme::host_color_to_ratatui)
                    {
                        Some(c) => base.fg(c),
                        None => base,
                    };
                    spans.push(Span::styled(line[s..e].to_string(), styled));
                    pos = e;
                }
                if pos < line.len() {
                    spans.push(Span::styled(line[pos..].to_string(), base));
                }
            }
            _ => spans.push(Span::raw(line.clone())),
        }
        if let Some(text) = hint {
            spans.push(Span::styled(
                text,
                TuiStyle::default()
                    .fg(Color::DarkGray)
                    .add_modifier(Modifier::ITALIC),
            ));
        }
        // Vertico-style count hint when the completion popup is
        // open: `(selected/total)` faintly trailing the cmdline.
        // Mirrors the picker prompt's `(n/m)` so both surfaces
        // read the same.
        if let Some(state) = app.completion().state.as_deref()
            && !state.candidates.is_empty()
        {
            spans.push(Span::styled(
                format!("  ({}/{})", state.selected + 1, state.candidates.len()),
                TuiStyle::default().fg(Color::DarkGray),
            ));
        }
        // MB.4: a live error indicator (unknown command / bad args) wins
        // the trailing slot; otherwise a dim parameter hint from the
        // command's ArgSpec — suppressed while the completion popup is up
        // to avoid clutter.
        if let Some(d) = deco {
            if let Some(err) = &d.error {
                let err_color = lattice_host::ui::theme::resolve_syntax_style(
                    resolved,
                    ids,
                    lattice_cells::style::Style::DiagnosticError,
                )
                .fg
                .map(crate::theme::host_color_to_ratatui)
                .unwrap_or(Color::Red);
                spans.push(Span::styled(
                    format!("  {err}"),
                    TuiStyle::default()
                        .fg(err_color)
                        .add_modifier(Modifier::ITALIC),
                ));
            } else if let Some(ph) = &d.param_hint {
                let popup_open = app
                    .completion()
                    .state
                    .as_deref()
                    .is_some_and(|s| !s.candidates.is_empty());
                if !popup_open {
                    spans.push(Span::styled(
                        format!("  {ph}"),
                        TuiStyle::default()
                            .fg(Color::DarkGray)
                            .add_modifier(Modifier::ITALIC),
                    ));
                }
            }
        }
        let para = Paragraph::new(Line::from(spans));
        frame.render_widget(para, area);
        frame.set_cursor_position((cursor_col, area.y));
        return;
    }

    if let ModalState::Search(direction) = app.ad().modal {
        let lead = match direction {
            SearchDirection::Forward => '/',
            SearchDirection::Backward => '?',
        };
        // Slice 3c.final.B.7: search pattern via published
        // `modeline()` sub-state (Arc<str> clone, wait-free).
        let modeline = app.modeline();
        let pattern: &str = modeline.search_pattern.as_deref().unwrap_or("");
        let prompt = format!("{lead}{pattern}");
        let para = Paragraph::new(Line::from(prompt.clone()));
        frame.render_widget(para, area);
        let col = area
            .x
            .saturating_add(prompt.len().min(area.width as usize) as u16);
        frame.set_cursor_position((col, area.y));
        return;
    }

    // MG.51: the prompt line (`Effect::OpenPrompt` — magit's branch
    // checkout, rename, tag name, …).
    //
    // Without this arm the row fell through to the echo below, which
    // draws the LABEL and nothing else: `open_prompt_line` puts the
    // label in the echo (`set_message`) and the typed text in the
    // `*prompt-line*` buffer, and only the label was ever drawn. Keys
    // reached the buffer — submitting worked — so the prompt read as a
    // dead input that mysteriously did the right thing.
    //
    // The prompt buffer IS the focused editing document (see
    // `focus_editing_buffer`), so its first line is the typed text and
    // `ad().cursor` is the caret inside it, exactly as the `:` line
    // reads its own buffer above.
    if matches!(app.ad().modal, ModalState::Prompt) {
        let messages = app.messages();
        let label: String = messages
            .last
            .as_deref()
            .map(|m| m.text.clone())
            .unwrap_or_default();
        let typed = app.modeline().prompt_text.to_string();
        let caret_byte = (app.ad().cursor.byte as usize).min(typed.len());
        let para = Paragraph::new(Line::from(format!("{label}{typed}")));
        frame.render_widget(para, area);
        // Columns, not bytes: the label is user-facing text and may hold
        // multi-byte characters.
        let col_of = |s: &str, upto: usize| s[..upto].chars().count();
        let col = area.x.saturating_add(
            (label.chars().count() + col_of(&typed, caret_byte)).min(area.width as usize) as u16,
        );
        frame.set_cursor_position((col, area.y));
        return;
    }

    // Slice 3c.final.B.7: last message via published `messages()`
    // sub-state — wait-free Arc clone.
    let messages = app.messages();
    let Some(msg) = messages.last.as_deref() else {
        // Nothing to show -- render nothing (the row stays blank).
        return;
    };
    let level = msg.level;
    let style = match level {
        // Trace + Debug are below the default messages.filter
        // threshold and don't normally surface to the echo
        // area; if a record at one of these levels does reach
        // the echo, render dim to match `*messages*` convention.
        EchoLevel::Trace | EchoLevel::Debug => TuiStyle::default().add_modifier(Modifier::DIM),
        EchoLevel::Info => TuiStyle::default(),
        EchoLevel::Warn => TuiStyle::default().fg(Color::Yellow),
        EchoLevel::Error => TuiStyle::default()
            .fg(Color::Red)
            .add_modifier(Modifier::BOLD),
    };
    let para = Paragraph::new(Line::from(vec![Span::styled(msg.text.clone(), style)]));
    frame.render_widget(para, area);
}

/// Produce the visible buffer lines as `ratatui::text::Line`s, including
/// gutter (line numbers), tab expansion, and styled spans pulled from
/// the canonical `DisplayMatrix` (rebuilt off the UI thread by the
/// cells worker). display-line B4.2: the old `app.editor.visible_highlights`
/// span cache + `App::refresh_highlights` prime were deleted.
///
/// Spans are owned (`Cow::Owned`) so the returned `Line`s outlive the
/// document text we slice out of for this frame. One alloc per visible line
/// per frame -- negligible at terminal sizes (typically 50-100 lines).
/// DR.3 (decoration-retention): the per-pane inputs that vary
/// between the focused pane and inactive panes, so ONE compose path
/// ([`compose_pane_lines`]) serves both. Buffer-intrinsic
/// decorations are sourced by `buffer_id` — syntax via the per-pane
/// `DisplayMatrix` keyed by `pane_id`, plus semantic tokens, inlay
/// hints, and diagnostic underlines/severity from their per-buffer
/// caches — so they paint on inactive panes too (dimmed). The state
/// gated on `is_active` is exactly *interaction* (cursor-line,
/// visual selection, hlsearch, current match, ghost text, substitute
/// preview) plus the layout that still reads active-doc-scoped state
/// (closed-fold skipping/summary, soft-wrap) — documented seams that
/// lift to per-pane when per-buffer fold + option state lands. See
/// docs/dev/architecture/decoration-retention.md §Render contract.
pub(crate) struct PaneComposeCtx {
    pub is_active: bool,
    pub pane_id: crate::pane::PaneId,
    pub buffer_id: crate::buffers::BufferId,
    pub cursor_line: u32,
    /// PI.3: whether to paint the cursor-line background on
    /// [`Self::cursor_line`] for THIS pane. Decouples cursorline from
    /// "is this the active document": the active pane sets it from
    /// `option_cache.current_line_highlight`; a focused *preview* pane sets
    /// it from the displayed buffer's `CursorLine` (so an LSP-reference /
    /// grep preview keeps its target line highlighted); every other
    /// inactive pane leaves it `false`.
    pub cursor_line_highlight: bool,
    pub scroll: u32,
    /// Horizontal scroll: first visible display column. Drives the
    /// body's left clip when `wrap` is off; ignored under wrap.
    pub leftcol: u32,
    pub display_line_numbers: Option<Arc<[u32]>>,
}

pub fn compose_visible_lines(
    app: &App,
    snap: &DocumentSnapshot,
    height: u32,
    width: u32,
) -> Vec<Line<'static>> {
    // Audit slice 7 / M2: snapshot the App's render-relevant
    // state once at chain entry. Helpers below read through
    // `view` rather than `app` for `folds` / `visible_highlights`
    // / `show_line_numbers` so a multi-thread renderer (GPUI,
    // future Web) can't see a torn mid-render view if a
    // concurrent input event mutates the underlying App fields.
    // Through the SAME builder the painter uses, with the active pane as its
    // subject. This function is now a named shortcut for "compose the focused
    // pane" rather than a second construction path — which is what it was, and
    // what let it drift onto the active DOCUMENT's options while its inactive
    // counterpart resolved per buffer.
    let pane = *app.panes().tree.active();
    let (view, ctx) = pane_compose_inputs(app, &pane, true);
    compose_pane_lines(&view, snap, height, width, &ctx)
}

/// DR.3: the single compose path for every Document pane. The active
/// pane calls it via [`compose_visible_lines`] with `is_active =
/// true` + a `from_app` view; inactive panes call it from
/// [`draw_pane_content`] with `is_active = false` + a `for_buffer`
/// view. The body the active pane produces is byte-identical to the
/// pre-merge path (pinned by `dr3_active_pane_compose_characterization`):
/// for the active pane `ctx.buffer_id == app.ad().document_buffer_id`,
/// so the per-buffer decoration sourcing resolves the same id.
/// Columns the gutter occupies before the first text cell.
///
/// Extracted so the compose loop, the caret walk and MO.2's mouse hit
/// map all read ONE expression. Four inputs feed it (line count,
/// `number`, the trailing-pad rule, the centring pad) and each extra
/// copy is a chance for the body, the caret and a click to land in three
/// different columns — which is the bug class the `2`-vs-`GUTTER_TRAILING_PAD`
/// comment below records, from back when there were two copies.
fn gutter_cols(view: &FrameView<'_>, total_lines: u32) -> u32 {
    (if view.show_line_numbers {
        gutter_width(total_lines)
    } else {
        // `:set nonumber` still paints a gutter — `format_gutter_cell`
        // ALWAYS emits its three trailing cells (separator + fold-glyph
        // slot + gap), so the width must cover them. `2` here made
        // `saturating_sub(label_cols + 3)` clamp to zero and the cell
        // came out 3 cells wide against a declared width of 2: the body
        // painted one column right of where every arithmetic consumer
        // thought it was, and the caret landed a cell to its LEFT — on
        // the last character instead of after it. Same class as the `↪`
        // fix in `format_gutter_cell`, opposite direction.
        GUTTER_TRAILING_PAD
    })
    // DB.4: horizontal centring widens the gutter (content + cursor shift
    // right); 0 for non-centred buffers.
    + view.content_left_pad
}

/// MO.2: the column a pane's text starts at, for the mouse hit map.
///
/// The gutter plus the sign columns — the same two terms the compose
/// loop subtracts from the pane width to get its body width, read
/// through the same helpers, so a click and a glyph agree on where
/// column 0 is.
fn pane_text_left(app: &App, pane: &crate::pane::PaneState, is_active: bool, rect: Rect) -> u16 {
    let Some(handle) = app.buffers().registry.document_handle(pane.buffer_id) else {
        return 0;
    };
    let total_lines = handle.snapshot().buffer.content_line_count();
    let (view, _ctx) = pane_compose_inputs(app, pane, is_active);
    let cols = gutter_cols(&view, total_lines) + sign_columns_width(&view);
    // Clamped into the pane: a gutter wider than the pane cannot leave a
    // text origin outside it, and an out-of-range `text_left` would make
    // every cell in the pane read as gutter.
    cols.min(rect.width as u32) as u16
}

pub(crate) fn compose_pane_lines(
    view: &FrameView<'_>,
    snap: &DocumentSnapshot,
    height: u32,
    width: u32,
    ctx: &PaneComposeCtx,
) -> Vec<Line<'static>> {
    let app = view.app;
    // msg-mode.3: when the active pane's major mode is
    // `messages-mode`, every visible line is rendered through
    // a level-aware path instead of the normal
    // syntax-highlight pipeline. The legacy spans path is
    // bypassed because the level styles aren't expressible as
    // `lattice_syntax::Style` enum variants (which is the
    // unit the spans pipeline carries).
    // DR.3: key the messages-mode body path on THIS pane's buffer,
    // not the globally-active one, so an inactive messages pane still
    // renders level-aware. For the active pane `ctx.buffer_id` IS the
    // active buffer (byte-identical).
    // Slice 3c.final.B.11: active_modes via published `modes()`
    // sub-state — wait-free Arc-bump lookup, no actor round-trip.
    // §5.6.8 contract: one snapshot per frame, used for everything.
    // The snapshot was loaded by the runtime via
    // `app.editor.snapshot_cache.load_arc()` and threaded through.
    // §8.2 hot path: never materialise the whole buffer -- iterate
    // ropey's line API and pull only the visible window. A 100MB
    // log file should cost the same per-frame as a 100-line file.
    let total_lines = snap.buffer.content_line_count();
    let gutter_w = gutter_cols(view, total_lines);
    // Severity column is prepended (Phase 4.1.d.iii); reserve
    // one cell so buffer width stays correct. D.3.d.1: diff
    // sign column sits between severity and gutter, costs one
    // more cell — reserved unconditionally so the layout
    // doesn't shift on `:diff` / `:diffoff`.
    let buffer_w = width
        .saturating_sub(gutter_w)
        .saturating_sub(sign_columns_width(view));

    // Compute visual selection range once (instead of per line).
    // DR.3: visual selection is interaction state — present only on
    // the focused pane.
    let visual_range = if ctx.is_active {
        visual_selection_range(app)
    } else {
        None
    };
    let block = if ctx.is_active {
        visual_block_extents(app)
    } else {
        None
    };

    // Perf plan B.2 slice B.2.b: load the worker's per-row pre-
    // bucketed static-overlay quads once for the whole frame
    // instead of walking `app.ad().all_matches` and
    // `substitute_preview.matches` per row × per match. Active
    // pane only — when the bucket is empty (boot before first
    // recompute or non-active pane), per-row code falls back to
    // the legacy walk. DocHighlight stays on the per-row walk
    // because the TUI's per-quad style is keyed off
    // `DocumentHighlightKind` which the bucket doesn't carry.
    // DR.3: the per-row hlsearch/substitute bucket is the ACTIVE
    // pane's (published from `app.ad()`), and both layers it feeds are
    // interaction state — only loaded for the focused pane. Inactive
    // panes get an empty bucket and skip the hlsearch/substitute
    // blocks below.
    let active_overlay_quads_for_frame = if ctx.is_active {
        let rs = app.render_state.load();
        rs.syntax.static_overlay_quads.load_full()
    } else {
        std::sync::Arc::new(lattice_host::render_state::StaticOverlayQuads::default())
    };
    let frame_scroll = ctx.scroll;

    // Build the visible-buffer-line ordering: starting from `scroll`,
    // skip lines inside closed folds, taking up to `height` entries.
    // Shared with the GPUI peer (`lattice_host::folds::
    // visible_source_lines`) — this walk used to live inline here and
    // GPUI grew its own source-line-windowed version that under-filled
    // the pane whenever a fold closed. One implementation, one
    // behaviour.
    //
    // CV.2: bounded in CONTENT space. `total_lines` above is ropey's
    // raw count and stays that way — it sizes the gutter, which must
    // keep matching the host's `cells_worker::gutter_cols` — but a
    // file's terminating `\n` must not earn a painted row.
    let visible: Vec<u32> = lattice_host::folds::visible_source_lines(
        &view.fold_index,
        ctx.scroll,
        height,
        snap.buffer.content_line_count(),
    );

    // D.3.b.1 (2026-05-29): snapshot the virtual-row matrix
    // so we can interleave Above / Below rows around document
    // lines. Lock-free `Arc` clone; the matrix lives on the
    // RenderState snapshot already loaded by callers.
    //
    // K.4.6 c.ii (2026-06-02, FIXED 2026-06-02): each pane reads ITS
    // OWN virtual-rows matrix. DR.3 keys it on `ctx.pane_id` (was
    // `active_pane_id`) so the one compose path serves both the
    // focused pane and inactive panes correctly — for the active pane
    // `ctx.pane_id` IS the active pane (byte-identical). Drop the
    // boot-seeded fallback: falling back to `rs.virtual_rows.matrix`
    // leaks the last-active-pane's headers into panes (e.g. a file
    // pane) that have no providers.
    let virtual_rows_matrix = {
        let rs = view.app.render_state.load();
        rs.virtual_rows
            .matrix_for_pane(ctx.pane_id)
            .map(|cell| cell.load_full())
            .unwrap_or_else(|| std::sync::Arc::new(lattice_cells::VirtualRowMatrix::empty()))
    };
    // Sticky rows occupy the top of the pane, but they are NOT paid for
    // here: the host reserves them once in the scroll budget
    // (`ensure_cursor_visible`'s `effective_height`), and the fill loop
    // below counts the sticky pre-pass rows against `height`. Shrinking
    // `visible` as well would reserve the row twice and silently delete
    // the last document line — which, for a buffer whose final line is an
    // editable prompt (the ACP conversation buffer), is always the prompt.
    let body_col_width = buffer_w;
    // W.4 (soft-wrap): `:set wrap`. When on, the per-line body is
    // kept at full width (truncation below is skipped) so
    // `split_body_into_segments` can wrap it into `body_col_width`
    // columns; when off, the body is clipped to the viewport
    // (horizontal-scroll behaviour, unchanged).
    // Soft-wrap is a global option today; `view.wrap_lines` is the
    // resolver seam — `FrameView::from_app` and `::for_buffer` both
    // read the global `option_cache.wrap_lines` for now. When
    // buffer-local options land, `for_buffer` resolves the
    // buffer-local override with the global as default (emacs
    // buffer-local pattern) and this site stays unchanged.
    let wrap_on = view.wrap_lines;
    let body_trunc_w = if wrap_on { u32::MAX } else { buffer_w };
    // Horizontal scroll (HS.1): with wrap off, drop the first
    // `leftcol` display columns of each body line before clipping to
    // the body width — the cursor-follow clamp (`leftcol`) keeps the
    // cursor inside `[leftcol, leftcol + buffer_w)`. Under wrap the
    // host pins `leftcol = 0`, so this is a no-op there regardless.
    let leftcol_off = if wrap_on { 0 } else { ctx.leftcol };
    // DR.3: composed→source row map + cursor line come from the pane
    // ctx — the active pane passes `app.ad()`'s values, inactive panes
    // pass their own handle's mapping + stashed cursor. Cloned once
    // per frame (Arc bump).
    let active_display_line_numbers = ctx.display_line_numbers.clone();
    let active_cursor_line = ctx.cursor_line;
    // DR.3: load THIS pane's retained `DisplayMatrix` ONCE per frame,
    // keyed by `pane_id`, instead of the top-level
    // `cells.display_matrix` per line. For the active pane this entry
    // is published from the same `p.display_matrix.clone()` that backs
    // the top-level, so the body is byte-identical; inactive panes get
    // their own buffer's matrix (no focus-keyed source branch — the
    // DR.3 "one producer, one path" payoff). Empty fallback (boot /
    // transient publish gap / a pane with no matrix entry) → the
    // per-line plain-text fallback. Hoisting the lookup out of the
    // loop keeps the body O(viewport) with no per-line HashMap probe
    // (paramount #1). `cells_rs` is held for the whole function so
    // `display_theme` can borrow its `theme`.
    let cells_rs = view.app.render_state.load().cells.load_full();
    let display_matrix = cells_rs
        .display_matrix_for_pane(ctx.pane_id)
        .map(|cell| cell.load_full())
        .unwrap_or_else(|| {
            std::sync::Arc::new(lattice_host::display_matrix::DisplayMatrix::empty())
        });
    // IG.3: this pane's indentation guides, loaded once per frame beside
    // its `DisplayMatrix` and for the same reason — one HashMap probe
    // per pane, not one per line (paramount #1). The layer is published
    // in the same worker pass as the matrix above, so it needs no
    // staleness check of its own: if the matrix is current, so is this.
    let indent_guides = cells_rs
        .indent_guides_for_pane(ctx.pane_id)
        .map(|cell| cell.load_full())
        .unwrap_or_else(|| std::sync::Arc::new(lattice_host::indent_guides::IndentGuides::empty()));
    // TC.3b: this pane's pinned context strip, loaded once per frame for the
    // same reason as the guides above — one map probe per pane. Published in
    // the same worker pass as the matrix, so it needs no staleness check.
    let sticky_context = cells_rs
        .sticky_context_for_pane(ctx.pane_id)
        .map(|cell| cell.load_full())
        .unwrap_or_else(|| {
            std::sync::Arc::new(lattice_host::sticky_context::StickyContext::empty())
        });
    // The guide glyph and the two styles, resolved once. The active
    // block is picked per frame from the cursor row the pane already
    // holds — that is what keeps a cursor move off the worker entirely
    // and the highlight free of lag.
    let indent_guide_style = IndentGuideStyle::resolve(
        view.app,
        &indent_guides,
        ctx.cursor_line,
        &cells_rs.resolved_theme,
        &cells_rs.theme_ids,
    );
    // T.5.b: the body-compose path resolves syntax styles through
    // `cells_rs.resolved_theme` + `cells_rs.theme_ids` (the resolved
    // table) rather than the retired `Theme::syntax_style`.
    // T.6: the search / selection / doc-highlight / substitute / inlay
    // overlay stylers read the same resolved table. Bind once here
    // (`cells_rs` is held for the whole fn) so each call is an O(1)
    // array index, not a per-overlay name lookup (paramount #1).
    let overlay_resolved = &cells_rs.resolved_theme;
    let overlay_ids = &cells_rs.theme_ids;
    // W.4.t.2: the whitespace stamp a matrix built RIGHT NOW would
    // carry. The per-line body compose below compares the retained
    // matrix's stamp against it — see the `display_stale` comment. One
    // lookup per pane per frame (O(#panes)), hoisted out of the line
    // loop like every other per-frame read here (paramount #1).
    let current_whitespace_version = cells_rs.whitespace_version_for_pane(ctx.pane_id);
    // Fold-marker colours, resolved once per pane from the theme
    // (`gutter.fold.open` / `gutter.fold.closed`). Muted by cross-editor
    // convention; the GPUI peer resolves the same two elements. `DarkGray`
    // (the historical gutter tone) is the fallback when a theme leaves the
    // element unset, so the marker never vanishes.
    let fold_colors = FoldColors {
        open: overlay_resolved
            .get(overlay_ids.gutter_fold_open)
            .fg
            .map(crate::theme::host_color_to_ratatui)
            .unwrap_or(Color::DarkGray),
        closed: overlay_resolved
            .get(overlay_ids.gutter_fold_closed)
            .fg
            .map(crate::theme::host_color_to_ratatui)
            .unwrap_or(Color::DarkGray),
    };
    // The ` ⋯ N lines` trailer's tone, from `gutter.fold.summary`. Was a
    // literal `Color::DarkGray` here — registering it is what lets the
    // GPUI peer paint the SAME trailer instead of inventing its own.
    let fold_summary_color = overlay_resolved
        .get(overlay_ids.gutter_fold_summary)
        .fg
        .map(crate::theme::host_color_to_ratatui)
        .unwrap_or(Color::DarkGray);
    // MO.4.a: gutter-decoration pre-loop. Walk active modes for this
    // pane's buffer once per frame; accumulate GutterDecoration
    // contributions into per-line maps. Replaces per-line RenderState
    // reads from render_diff_sign_cell / render_diagnostic_severity_cell
    // — both now read the maps, not the render-state directly.
    // SG.4b: ONE map per gutter column, indexed by column position. Nothing
    // here knows what a diagnostic or a hunk mark is any more — they are signs
    // whose definitions name a column, exactly like a plugin's.
    let sign_gutter: Vec<std::collections::HashMap<u32, lattice_mode::SignId>> = {
        use lattice_mode::{DecorationCtx, GutterDecoration, ServiceRegistry, SignId};
        let mut services = ServiceRegistry::new();
        let rs_deco = app.render_state.load();
        // D-fix.3b: per-pane gutter signs — register THIS pane's buffer's
        // sign map (proposed→current-side, baseline→baseline-side), so both
        // panes of a side-by-side diff show gutter signs, not just the active
        // one. `None` (no session for this buffer) → no signs.
        if let Some(sign_map) = rs_deco.diff.sign_maps.get(&ctx.buffer_id) {
            services.register(lattice_host::diff::mode::DiffDecorationData {
                sign_map: sign_map.clone(),
            });
        }
        // LspDiagnosticsData: gated on lsp_diagnostics_enabled (M.5.6).
        if view.lsp_diagnostics_enabled {
            let diagnostics = app
                .buffer_uri(ctx.buffer_id)
                .and_then(|u| rs_deco.diagnostics.layer.diagnostics_arc(&u));
            services.register(lattice_lsp::modes::LspDiagnosticsData { diagnostics });
        }
        // CM.3c: inject the `*compilation*` buffer's severity index. The
        // producer scans off-thread (in the compilation drain) and the host
        // snapshots the per-buffer index into `render_state.compilation_severity`;
        // here the renderer only reads the slot for this pane's buffer and
        // registers the carrier — no `lattice-compilation` dependency, no
        // paint-time scan. `CompilationMode::gutter_decorations` reads it and
        // emits `Severity` marks through the SAME gutter column as LSP.
        if let Some(entries) = rs_deco.compilation_severity.get(&ctx.buffer_id) {
            services.register(lattice_mode::CompilationSeverityData {
                entries: entries.clone(),
            });
        }
        // SG.4b: the interned built-in sign ids, so a producer emitting a
        // mark per visible line names it by field rather than by string.
        services.register(rs_deco.signs.builtin);
        let deco_ctx = DecorationCtx::new(ctx.buffer_id, &services);
        let modes_rs = rs_deco.modes.clone();
        // SG.2b: one cell holds one sign, so contention is resolved HERE,
        // as placements arrive, rather than by whoever paints last.
        // `winning_sign` breaks equal priorities on name, so the glyph a
        // line shows does not depend on which producer the mode walk
        // reached first — or on a `HashMap` reseeding between runs.
        let signs_rs = rs_deco.signs.clone();
        let mut columns: Vec<std::collections::HashMap<u32, SignId>> =
            vec![Default::default(); lattice_mode::BUILTIN_SIGN_COLUMNS.len()];
        fn place_sign(
            registry: &lattice_mode::SignRegistry,
            columns: &mut [std::collections::HashMap<u32, SignId>],
            line: u32,
            sign: SignId,
        ) {
            // A retired id resolves to nothing and must not displace a live
            // sign on the same line — SG.1 retires rather than reuses
            // precisely so a stale placement paints nothing.
            let Some(incoming) = registry.get(sign) else {
                return;
            };
            // A definition naming a column the host does not paint lands in
            // the leftmost one rather than vanishing — the `gutter.sign`
            // principle, where the failure that loses the information
            // entirely is the worst one available.
            let col = lattice_mode::BUILTIN_SIGN_COLUMNS
                .iter()
                .position(|c| *c == incoming.column)
                .unwrap_or(0);
            let map = &mut columns[col];
            let held = map.get(&line).and_then(|id| registry.get(*id));
            let takes_it = match held {
                Some(held) => {
                    std::sync::Arc::ptr_eq(lattice_mode::winning_sign(held, incoming), incoming)
                }
                None => true,
            };
            if takes_it {
                map.insert(line, sign);
            }
        }
        if let Some(active) = modes_rs.map.get(&ctx.buffer_id) {
            let registry = &modes_rs.mode_registry;
            let mut all_ids: Vec<lattice_mode::ModeId> = Vec::new();
            if let Some(major) = active.major() {
                all_ids.push(major);
            }
            all_ids.extend_from_slice(active.minors());
            for id in all_ids {
                if let Some(mode) = registry.get(id) {
                    for deco in mode.gutter_decorations(&deco_ctx) {
                        match deco {
                            GutterDecoration::Sign { line, sign } => {
                                place_sign(&signs_rs.registry, &mut columns, line, sign);
                            }
                        }
                    }
                }
            }
        }
        // PL8.E: merge WASM plugin gutter decorations (host-cached, read
        // wait-free) into the SAME partition. Never runs WASM at paint time —
        // the producer wrote this cache off the render path; here we only read
        // it. Identical partition as the native mode walk above, so plugin marks
        // paint through the identical glyph/style mapping downstream.
        {
            use lattice_host::per_buffer_cache::PerBufferCacheExt;
            if let Some(cache) = rs_deco.wasm_gutter_decorations.get_for(ctx.buffer_id) {
                for deco in &cache.decorations {
                    match deco {
                        GutterDecoration::Sign { line, sign } => {
                            place_sign(&signs_rs.registry, &mut columns, *line, *sign);
                        }
                    }
                }
            }
        }
        columns
    };
    let mut out: Vec<Line<'static>> = Vec::with_capacity(height as usize);
    // MO.2: what each painted row came from, recorded in lockstep with
    // `out` so the mouse can invert the compose loop rather than
    // re-implement it. `None` is a row mirroring no source line — a
    // virtual row, or the `~` filler past the end of the buffer. Pushed
    // beside EVERY `out.push` below; the two must stay the same length
    // or every click past the divergence lands on the wrong line, which
    // is why the tail asserts it.
    let mut row_src: Vec<Option<lattice_host::mouse::RowOrigin>> =
        Vec::with_capacity(height as usize);
    // Sticky pre-pass: render fixed-top rows before the scrollable content.
    // These are excluded from virtual_rows_at so they don't double-paint.
    for vrow in virtual_rows_matrix.sticky_rows() {
        if (out.len() as u32) >= height {
            break;
        }
        out.push(render_virtual_row(view, vrow, gutter_w, body_col_width));
        row_src.push(None);
    }
    // TC.3b: the pinned context strip, painted AFTER the matrix's sticky rows
    // and never instead of them. That ordering is the whole contract — the
    // headerline keeps row 0 whatever it is showing, and context reaches the
    // top of the pane only when there is no headerline to displace. It falls
    // out of appending rather than needing a rank field or any negotiation
    // between the two producers.
    //
    // Rows are adapted to `VirtualRow` and painted by `render_virtual_row`
    // rather than given their own painter: two implementations of "paint a
    // pinned row of cells" would drift, and the cells here are already
    // worker-built from the same builder as the document rows.
    // TC.12: a trailing separator row is not a scope, so it must not take
    // the `active` styling meant for the scope the cursor is in.
    let innermost = sticky_context.innermost_scope();
    for (idx, row) in sticky_context.rows.iter().enumerate() {
        if (out.len() as u32) >= height {
            break;
        }
        let is_innermost = Some(idx) == innermost;
        let vrow = lattice_cells::VirtualRow {
            media: None,
            anchor_line: row.source_line,
            position: lattice_cells::AnchorPosition::Above,
            cells: row.cells.clone(),
            height: 1,
            kind: lattice_cells::VirtualRowKind::Sticky,
            // TC.11: the LAST row is the innermost scope — the one the cursor
            // is actually in, and the line the reader is looking for. Falls
            // back to the shared backdrop when the theme leaves `active`
            // unset, so a theme that does not distinguish them still works.
            bg: if is_innermost {
                sticky_context.active_bg.or(sticky_context.bg)
            } else {
                sticky_context.bg
            },
            scales: None,
            // TC.8: the header's real place in the file. The decision was made
            // host-side (`context.line-numbers`), so the renderer never reads
            // a plugin option — it only paints what the layer carries.
            // ANDed with the pane's own `number`: `context.line-numbers` asks
            // for numbers, `:set nonumber` says this pane shows none, and the
            // pane wins — a strip numbered above unnumbered code reads as a
            // stray column.
            // A separator mirrors no source line, so it shows no number.
            gutter_line: (sticky_context.line_numbers
                && view.show_line_numbers
                && !(sticky_context.has_separator && idx + 1 == sticky_context.rows.len()))
            .then_some(row.source_line),
            gutter_fg: sticky_context.line_number_fg,
        };
        out.push(render_virtual_row(view, &vrow, gutter_w, body_col_width));
        row_src.push(None);
    }
    let mut visible_idx: usize = 0;
    while (out.len() as u32) < height {
        let line_idx = match visible.get(visible_idx) {
            Some(&l) => {
                visible_idx += 1;
                l
            }
            None => {
                out.push(empty_marker_line(gutter_w));
                row_src.push(None);
                continue;
            }
        };
        // D.3.b.1: emit Above-anchored virtual rows for this
        // document line first.
        for vrow in virtual_rows_at(
            &virtual_rows_matrix,
            line_idx,
            lattice_cells::AnchorPosition::Above,
        ) {
            if (out.len() as u32) >= height {
                break;
            }
            out.push(render_virtual_row(view, vrow, gutter_w, body_col_width));
            row_src.push(None);
        }
        if (out.len() as u32) >= height {
            break;
        }
        // Pull just this line's text (O(log n) lookup +
        // O(line_len) materialisation).
        let line_text = snap.buffer.line(line_idx).unwrap_or_default();
        let gutter = render_gutter_for(
            view,
            line_idx,
            gutter_w,
            active_cursor_line,
            active_display_line_numbers.as_deref(),
            fold_colors,
        );
        // Highlight slot is keyed by buffer-line offset from
        // `scroll`, NOT by viewport row -- once closed folds skip
        // interior lines, viewport row `i` no longer corresponds
        // to buffer line `scroll + i`, and using the row index
        // would paint a post-fold line with stale spans for the
        // hidden interior.
        // msg-mode.3: messages-mode buffers bypass the
        // syntax-spans pipeline entirely -- the level token
        // styling isn't expressible as a `lattice_syntax::Style`
        // variant. `messages_line_spans` scans the fixed
        // `HH:MM:SS.mmm LEVEL text` format and returns a
        // ratatui `Vec<Span<'static>>` directly. Lines that
        // don't match the format render plain (e.g. blank
        // lines at the end of the rope).
        // W.4.t: tracks whether `body` came from the cells matrix
        // (already whitespace-decorated + tab-expanded by the
        // builder) vs the raw-text fallback. The compose-loop
        // whitespace pass below must NOT re-decorate a cell-derived
        // body — doing so re-classifies the tab's expanded fill
        // spaces and desyncs (cell spans no longer align 1:1 with
        // source bytes once tabs/markers expand).
        let mut body_from_cells = false;
        // IG.3: whether this row's body came from a display row at all.
        //
        // Distinct from `body_from_cells`, which is `!spans.is_empty()` and
        // therefore ALSO false for a blank line whose display row was built
        // perfectly well. Guides need the wider predicate: a blank line
        // inside a block is exactly the row a guide has to carry through,
        // and gating on emptiness would drop it.
        let mut body_is_display_row = false;
        let mut body = {
            // S3.c.final (2026-05-26): cell-derived spans are the
            // ONLY source for document-buffer bodies. The
            // `cell_row_to_source_spans` converter (S3.b) filters
            // INLAY-flagged cells so the resulting spans cover
            // source-byte positions one-to-one with `line_text`,
            // preserving overlay byte-coordinate semantics for
            // every downstream layer (whitespace, semantic
            // tokens, hlsearch, visual, diagnostics, fold suffix,
            // post-overlay inlay splice — all validated against
            // cell-derived bodies in S3.c.1–4).
            //
            // The RowPrepaint fallback that lived here through
            // S3.c.0–4 has been retired. Empty-matrix windows
            // (boot frames before the first cell-builder publish,
            // or the brief gap during a buffer switch) emit
            // plain-text `Span::raw(line_text)` instead — exactly
            // what the legacy fallback degraded to once the prepaint
            // rows ran out. Semantically equivalent for the user; one
            // source-of-truth from the code's perspective.
            //
            // display-line B4.2: the worker-published prepaint-rows
            // cell (`view.visible_rows`) was deleted — it had no live
            // readers left (the document body, markdown, help, and
            // messages bodies all read their own sources). Only the
            // overlay worker's `static_overlay_quads` survives as a
            // worker output. The document-body branch reads the
            // canonical `DisplayMatrix` below.
            // B2.4 (2026-06-04): consume the canonical `DisplayMatrix`
            // directly — its style-tagged runs resolve to ratatui via the
            // host theme at paint (`display_line_to_source_spans`). Pre-B2.4
            // the TUI read the projected cell grid here; the projection (and
            // the whole cell path) is deleted in B4.
            // DR.3: `display_matrix` + `display_theme` are this pane's
            // retained matrix, loaded once above (keyed by `ctx.pane_id`),
            // not a per-line top-level cell read.
            // Three paths fall through to plain `line_text`:
            //   1. matrix has no row at `line_idx` (boot frames before the
            //      first build, doc-switch gap, or off-window on a large
            //      file — the windowed build covers only the viewport),
            //   2. matrix has a row but it is entirely INLAY runs —
            //      `display_line_to_source_spans` drops those, so the Vec is
            //      empty even though `line_text` has content,
            //   3. matrix text lags the snapshot
            //      (`version.text != snap.text_version`). B2.3 rebuilds the
            //      edited region's `DisplayMatrix` SYNCHRONOUSLY in the
            //      publish tail, so a single-keystroke edit is already
            //      text-current here and this guard does NOT fire — that is
            //      what retired the per-keystroke whole-viewport flicker
            //      (user-reported 2026-06-02: "after adding one character …
            //      I suddenly see changes" was the old async-lag window).
            //      It still fires for the rare publish the sync path skips
            //      (multi-edit batch, doc switch); painting current
            //      plain-text for a frame beats painting PRE-edit content,
            //      and the async worker recolours within a frame or two.
            //   4. W.4.t.2: matrix whitespace config lags the options
            //      (`version.whitespace` differs from what a matrix built
            //      now would carry). The builder bakes whitespace markers
            //      into `Cell.ch` at emission, and the compose-loop
            //      pre-pass below deliberately skips cell-derived bodies
            //      (it would double-decorate) — so a matrix built before
            //      `:set list` paints UNDECORATED text and the pre-pass
            //      declines to fix it. Toggling whitespace would then do
            //      nothing visible until the async worker rebuilt. Same
            //      trade-off as (3): fall back to raw text for a frame so
            //      the pre-pass runs and the glyphs appear on the very
            //      next paint; syntax colour catches up when the worker
            //      republishes. Whitespace toggles are a rare, deliberate
            //      gesture, so the momentary uncoloured frame costs
            //      nothing on the hot path.
            let display_stale = display_matrix.version.text != snap.text_version
                || display_matrix.version.whitespace != current_whitespace_version;
            let spans = if display_stale {
                Vec::new()
            } else {
                match display_matrix.row_at_source_line(line_idx) {
                    Some(line) => crate::cells_render::display_line_to_source_spans(
                        line,
                        &cells_rs.resolved_theme,
                        &cells_rs.theme_ids,
                    ),
                    None => Vec::new(),
                }
            };
            if spans.is_empty() && !line_text.is_empty() {
                clip_spans_horizontally(
                    vec![Span::raw(line_text.clone())],
                    leftcol_off,
                    body_trunc_w,
                )
            } else {
                body_from_cells = !spans.is_empty();
                body_is_display_row =
                    !display_stale && display_matrix.row_at_source_line(line_idx).is_some();
                clip_spans_horizontally(spans, leftcol_off, body_trunc_w)
            }
        };
        // M.7.3.b: whitespace decoration pre-pass. Cheap when
        // `show_whitespace` is off (single bool check); when
        // on, walks each rendered span and substitutes glyphs
        // for tab / trailing / leading / space / EOL per the
        // typed `display.whitespace.*` options.
        //
        // W.4.t: skip the cell-derived path — the cells builder
        // already decorated whitespace (and expanded tabs to their
        // display width), so re-running here would double-decorate
        // and desync against source bytes. Only the raw-text
        // fallback (cells stale / absent) needs decoration here.
        if app.ad().option_cache.show_whitespace && !body_from_cells {
            let decoration = WhitespaceDecoration::from_app(app);
            body = apply_whitespace_decoration(body, &line_text, &decoration);
        }
        // IG.3: indentation guides, AFTER the horizontal clip.
        //
        // After, not before, because `clip_spans_horizontally` and
        // `truncate_spans_to_width` measure in BYTES (their own comment
        // calls the display-width model a punt). A guide glyph is three
        // bytes, so substituting it ahead of the clip would shorten every
        // indented line by two columns per guide — a visible regression
        // bought for nothing, since the glyph occupies one column either
        // way. Running after means the pass sees the same columns the
        // user sees, and `leftcol` pans the guides with the text.
        //
        // Still before the overlay remap below: that maps source byte →
        // body COLUMN → body byte, and guides change no column, exactly
        // as whitespace markers change none.
        //
        // Cell-derived bodies only. The plain-text fallback has not
        // expanded tabs, so a display column does not index it and a
        // guide would land wrong on every tab-indented line. A fallback
        // frame therefore shows no guides — the same degradation it
        // already makes for syntax colour, lasting exactly as long.
        if body_is_display_row {
            body = apply_indent_guides(
                body,
                indent_guides.marks_for_line(line_idx),
                &indent_guide_style,
                leftcol_off,
                body_trunc_w,
            );
        }
        let line_len = line_text.len();
        // W.4.t.1: the overlay ranges below carry SOURCE-byte offsets,
        // but the cell-derived `body` has tabs expanded to their display
        // width (and may carry multi-byte whitespace markers), so source
        // bytes no longer index it — selection / search / diagnostic /
        // semantic / document-highlight overlays drift on tab-indented
        // lines. Map each overlay endpoint: source byte → body column
        // (the char-count model `split_body_into_segments` slices by) →
        // body byte. Identity on the plain-text fallback
        // (`!body_from_cells`), where body bytes already equal source
        // bytes, so plain ASCII code is unchanged. Inlays splice AFTER
        // the overlays, so the body carries no inlay runs here — the
        // column model is tab-only (empty-inlay equivalent).
        let overlay_tabstop = app.ad().option_cache.tabstop;
        let body_concat: String = if body_from_cells {
            body.iter().map(|s| s.content.as_ref()).collect()
        } else {
            String::new()
        };
        let map_ob = |src: usize| -> usize {
            if body_from_cells {
                nth_char_byte(
                    &body_concat,
                    source_byte_to_body_col(&line_text, src, overlay_tabstop),
                )
            } else {
                src
            }
        };
        // Whether this line begins a closed fold. Used to append the
        // ` ⋯ N lines` suffix AFTER overlay processing, so
        // visual selection / hlsearch / current_match still paint
        // the heading correctly.
        // Fold-bleed fix (2026-06-30): computed for every pane (matches
        // the now-ungated visible-line walk above). `view.fold_start_at`
        // reads the pane's own per-buffer folds, so an inactive pane
        // shows its fold summary identically to when it was focused.
        let closed_fold_at_start = view.fold_start_at(line_idx).filter(|f| f.closed).map(|f| {
            // The "⋯ N lines" suffix should reflect the
            // user's perception of how much content collapsed
            // onto this single visible row -- including any
            // sibling / nested closed folds whose headings are
            // themselves hidden by this fold and whose ranges
            // chain past `f.end_line`. Without this walk, two
            // touching folds (1..=3 then 3..=5, both closed)
            // visually hide 5 lines but report only the first
            // fold's own 3 lines, which doesn't match what the
            // user just collapsed.
            closed_fold_display_span(view, snap, f)
        });
        // 4.4.h: LSP semantic-tokens overlay. Replaces the
        // foreground color (folding in modifier bits) for
        // each token's byte range. Painted BEFORE visual /
        // hlsearch / diagnostic passes so those still layer
        // their bg / underline on top of the LSP-driven fg
        // -- the user's selection and search highlight stay
        // visible over semantic-colored text.
        // 5.8.AF.5 / Slice 3b.2: read semantic-tokens through
        // `RenderState.lsp.semantic_tokens`. The spawned request
        // task writes via `insert_for` into the same underlying
        // `PerBufferCache` -- this read sees fresh data without
        // any UI-thread drain.
        // DR.3: semantic tokens are a buffer-intrinsic decoration —
        // source from THIS pane's per-buffer cache (`ctx.buffer_id`)
        // and the per-pane `view` gate, so they paint on inactive
        // panes too (dimmed). For the active pane `ctx.buffer_id` IS
        // the active doc → byte-identical.
        use lattice_host::per_buffer_cache::PerBufferCacheExt;
        let rs_st = app.render_state.load();
        if let Some(cache) = rs_st.lsp.semantic_tokens.get_for(ctx.buffer_id)
            && view.lsp_semantic_tokens_enabled
        {
            for tok in cache.tokens.iter().filter(|t| t.line == line_idx) {
                let start =
                    lattice_lsp::position::utf16_column_to_utf8_byte(&line_text, tok.start_char)
                        as usize;
                let end = lattice_lsp::position::utf16_column_to_utf8_byte(
                    &line_text,
                    tok.start_char + tok.length,
                ) as usize;
                let start = start.min(line_len);
                let end = end.min(line_len);
                if start >= end {
                    continue;
                }
                let mut mods = Modifier::empty();
                let style_with_mods =
                    apply_semantic_token_modifiers(TuiStyle::default(), &tok.modifiers);
                mods.insert(style_with_mods.add_modifier);
                body = apply_semantic_token_overlay(
                    body,
                    map_ob(start),
                    map_ob(end),
                    semantic_token_color(&tok.token_type),
                    mods,
                );
            }
        }
        // Blockwise visual: per-line column band [min_col, max_col].
        // Charwise / Linewise visual go through `visual_range` instead.
        if let Some(b) = block
            && line_idx >= b.start_line
            && line_idx <= b.end_line
        {
            let start = (b.start_col as usize).min(line_len);
            let end = ((b.end_col as usize) + 1).min(line_len);
            if start < end {
                body = apply_match_overlay(
                    body,
                    map_ob(start),
                    map_ob(end),
                    visual_style(overlay_resolved, overlay_ids),
                );
            }
        } else if let Some(range) = visual_range
            && let Some((overlay_start, overlay_end)) =
                match_overlay_range(range, line_idx, line_len)
        {
            body = apply_match_overlay(
                body,
                map_ob(overlay_start),
                map_ob(overlay_end),
                visual_style(overlay_resolved, overlay_ids),
            );
        }
        // Perf plan B.2 slice B.2.b: hlsearch (`all_matches`) overlay
        // now reads from the worker's per-row bucket. The bucket is
        // indexed by visible-row offset from `scroll` (= worker's
        // recompute `start`), so for buffer line `line_idx` the row
        // index is `line_idx - frame_scroll`. Bucket is empty
        // pre-first-recompute or for non-active panes; in those cases
        // we fall back to the legacy per-frame walk so search hits
        // still paint correctly through the warm-up window.
        // DR.3: hlsearch + current-match are interaction state — the
        // `all_matches` walk reads the ACTIVE doc's matches (no
        // per-buffer search store yet), so both run only on the
        // focused pane. The bucket is empty when inactive anyway; the
        // gate also stops the `else` walk from painting the active
        // buffer's matches onto an inactive pane.
        let bucket_row: Option<&Vec<lattice_host::render_state::RowOverlayQuad>> = (line_idx
            >= frame_scroll)
            .then(|| (line_idx - frame_scroll) as usize)
            .and_then(|idx| active_overlay_quads_for_frame.quads.get(idx));
        // MB.5: while the `/`·`?` search line is open, the document
        // pane renders via the inactive path (registry-keyed buffer),
        // but hlsearch / current-match overlays must still paint — the
        // user sees live match highlighting as they type.
        if ctx.is_active || app.ad().search_line_active {
            if let Some(row_quads) = bucket_row {
                for q in row_quads {
                    if matches!(
                        q.layer,
                        lattice_host::render_state::OverlayLayer::AllMatches
                    ) {
                        let start = (q.source_byte_start as usize).min(line_len);
                        let end = (q.source_byte_end as usize).min(line_len);
                        if start < end {
                            body = apply_match_overlay(
                                body,
                                map_ob(start),
                                map_ob(end),
                                hlsearch_style(overlay_resolved, overlay_ids),
                            );
                        }
                    }
                }
            } else {
                for &range in app.ad().all_matches.iter() {
                    if let Some((overlay_start, overlay_end)) =
                        match_overlay_range(range, line_idx, line_len)
                    {
                        body = apply_match_overlay(
                            body,
                            map_ob(overlay_start),
                            map_ob(overlay_end),
                            hlsearch_style(overlay_resolved, overlay_ids),
                        );
                    }
                }
            }
            if let Some(range) = app.ad().current_match
                && let Some((overlay_start, overlay_end)) =
                    match_overlay_range(range, line_idx, line_len)
            {
                body = apply_match_overlay(
                    body,
                    map_ob(overlay_start),
                    map_ob(overlay_end),
                    match_style(overlay_resolved, overlay_ids),
                );
            }
        }
        // LSP diagnostic underline overlay (Phase 4.1.d.iii):
        // for each diagnostic touching this line, underline the
        // affected range with the severity colour. Underline
        // modifier composes with any prior bg / fg overlays
        // (visual / hlsearch / current_match) -- all four can
        // co-exist on a single span without conflict.
        // DR.3: diagnostics are a buffer-intrinsic decoration —
        // sourced by `ctx.buffer_id` (the layer is per-URI) so they
        // underline on inactive panes too (dimmed). Active pane's
        // `ctx.buffer_id` is the active doc → byte-identical.
        for d in diagnostics_on_line(view, ctx.buffer_id, line_idx) {
            let start = if d.range.start.line == line_idx {
                (d.range.start.character as usize).min(line_len)
            } else {
                0
            };
            let end = if d.range.end.line == line_idx {
                (d.range.end.character as usize).min(line_len)
            } else {
                line_len
            };
            if start >= end {
                continue;
            }
            let color = match d.severity {
                Some(DiagnosticSeverity::ERROR) => Color::Red,
                Some(DiagnosticSeverity::WARNING) => Color::Yellow,
                Some(DiagnosticSeverity::INFORMATION) => Color::Blue,
                Some(DiagnosticSeverity::HINT) => Color::DarkGray,
                _ => Color::Blue,
            };
            body = apply_underline_overlay(body, map_ob(start), map_ob(end), color);
        }
        // 4.4.e: `documentHighlight` soft overlay. Reads from
        // the App's per-buffer cache (populated by the per-tick
        // pump). The overlay walks each highlight; the range
        // intersected with this row gets a background tint with
        // hue keyed off the `kind` field (Read = green-ish,
        // Write = red-ish, Text/None = blue-ish). The styling
        // composes with diagnostics + hlsearch + visual so a
        // symbol caught by all four still reads correctly.
        // Phase 5.8.AF.5 / Slice 3b.0: read through the
        // `RenderState.lsp.document_highlights` ArcSwap. The
        // spawned LSP request task `.store()`s directly into
        // the same underlying slot, so this `load_full()` sees
        // the latest result without any tick-driven drain on
        // the renderer thread.
        // DR.3: document-highlight is a buffer-intrinsic decoration —
        // the highlight ranges are positions in `cache.buffer_id`, so
        // paint them on ANY pane showing that buffer (active or
        // inactive, dimmed), matching the GPUI peer
        // (`feedback_tui_gpui_parity`). Keyed on `ctx.buffer_id` (was
        // `app.ad().document_buffer_id`): the active pane's id is the
        // active doc → byte-identical; an inactive pane showing a
        // DIFFERENT buffer no longer mis-claims the active buffer's
        // highlights.
        let rs = app.render_state.load();
        let dh_guard = rs.lsp.document_highlights.load_full();
        if let Some(cache) = dh_guard.as_deref()
            && cache.buffer_id == ctx.buffer_id
            && view.lsp_document_highlight_enabled
        {
            for h in &cache.highlights {
                let start_line = h.range.start.line;
                let end_line = h.range.end.line;
                if line_idx < start_line || line_idx > end_line {
                    continue;
                }
                let start = if line_idx == start_line {
                    (h.range.start.character as usize).min(line_len)
                } else {
                    0
                };
                let end = if line_idx == end_line {
                    (h.range.end.character as usize).min(line_len)
                } else {
                    line_len
                };
                if start >= end {
                    continue;
                }
                body = apply_match_overlay(
                    body,
                    map_ob(start),
                    map_ob(end),
                    document_highlight_style(h.kind, overlay_resolved, overlay_ids),
                );
            }
        }
        // Perf plan A.2 slice A.2b.2: `inlayHint` virtual-text
        // overlay reads from `rs.syntax.inlay_hints` — the
        // publish-time gated + flattened list with
        // `padding_left/right` already baked in and the utf-16
        // column already converted to utf-8 bytes. The mode gate,
        // per-buffer-cache lookup, label flatten, and column
        // conversion all moved off the per-line hot loop onto
        // dispatch (once per publish). Filters per row by `line`;
        // splices in reverse byte order so earlier splices don't
        // shift later ones.
        //
        // display-line B-series: the active-pane document body reads
        // the canonical `DisplayMatrix` (which already weaves inlay
        // text into its runs); this post-hoc inlay splice covers the
        // markdown / help / messages bodies that still build spans
        // from raw line text. (The old prepaint-rows cell that would
        // have woven it was deleted in B4.2.)
        //
        // Fold-bleed follow-up (2026-06-30): inlay hints are a
        // buffer-intrinsic decoration shown on EVERY pane through ONE
        // path. `view.inlay_hints` is this pane's own byte-baked list
        // (`RenderState::inlay_hints_for_buffer`: active → baked
        // `syntax.inlay_hints`; inactive → its `cells.panes` entry).
        // This replaces the prior active-vs-inactive split where the
        // inactive branch re-derived hints from the LSP cache with its
        // own utf-16→utf-8 conversion — two sources that could drift.
        // Splices through `map_ob` so W.4.t tab expansion lands them on
        // the right cell; reverse byte order keeps earlier splices from
        // shifting later ones.
        let rs = app.render_state.load();
        if !view.inlay_hints.is_empty() {
            let mut on_line: Vec<&lattice_host::render_state::InlayHintRow> = view
                .inlay_hints
                .iter()
                .filter(|h| h.line == line_idx)
                .collect();
            on_line.sort_by(|a, b| b.byte.cmp(&a.byte));
            for h in on_line {
                body = splice_virtual_text_into_spans(
                    body,
                    map_ob((h.byte as usize).min(line_len)),
                    h.text.clone(),
                    inlay_row_style(overlay_resolved, overlay_ids, h.style),
                );
            }
        }
        // L4a.3 (lsp-architecture.md §15): inline cursor-line diagnostic
        // summary. The host idle gate (L4a.2) publishes
        // `rs.diagnostics.inline_summary = Some((line, summary))` for the
        // ACTIVE buffer's cursor line; render it as trailing eol virtual
        // text, severity-themed to match the gutter glyph. Active pane
        // only — unlike the buffer-intrinsic inlay/underline decorations
        // above, the cursor-line summary is interaction state tied to the
        // focused cursor (Helix/Zed show it only in the focused view).
        // Spliced at `usize::MAX` so it appends at the very end of the
        // rendered line — AFTER any inlay-hint virtual text spliced
        // above — rather than at the source-text end (which would land
        // it before trailing inlays, mid-line). The leading gap
        // separates it from the code.
        if ctx.is_active
            && view.lsp_diagnostics_enabled
            && let Some((sum_line, summary)) = rs.diagnostics.inline_summary.as_ref()
            && *sum_line == line_idx
        {
            body = splice_virtual_text_into_spans(
                body,
                usize::MAX,
                format!("    {}", summary.text),
                diagnostic_summary_style(summary.severity_rank, view),
            );
        }
        // Substitute live preview overlay (DESIGN.md §5.9.10): paint
        // the about-to-be-replaced ranges in a strike-through-ish
        // style so the user sees what will change before they hit
        // Enter. Distinct from hlsearch's plain match highlight.
        //
        // Perf plan B.2 slice B.2.b: consume the worker bucket's
        // Substitute layer when available; legacy walk as fallback.
        // DR.3: the substitute preview is driven by the command line
        // (`:s///`) typed in the focused pane — interaction state, so
        // it paints only on the active pane.
        if ctx.is_active {
            if let Some(row_quads) = bucket_row {
                let mut found_any = false;
                for q in row_quads {
                    if matches!(
                        q.layer,
                        lattice_host::render_state::OverlayLayer::Substitute
                    ) {
                        let start = (q.source_byte_start as usize).min(line_len);
                        let end = (q.source_byte_end as usize).min(line_len);
                        if start < end {
                            body = apply_match_overlay(
                                body,
                                map_ob(start),
                                map_ob(end),
                                substitute_preview_style(overlay_resolved, overlay_ids),
                            );
                            found_any = true;
                        }
                    }
                }
                // If the worker bucket existed but had no substitute
                // quads, that's accurate state — no substitute preview is
                // active. Don't fall back to per-frame walk.
                let _ = found_any;
            } else if let Some(preview) = app.ad().substitute_preview.as_ref() {
                for &range in preview.matches.iter() {
                    if let Some((overlay_start, overlay_end)) =
                        match_overlay_range(range, line_idx, line_len)
                    {
                        body = apply_match_overlay(
                            body,
                            map_ob(overlay_start),
                            map_ob(overlay_end),
                            substitute_preview_style(overlay_resolved, overlay_ids),
                        );
                    }
                }
            }
        }
        // W.4.t: the columns of this row that live on the SOURCE axis,
        // measured before any trailing decoration is appended. This is
        // what `split_body_into_segments` is allowed to wrap at — see
        // its `wrap_cols` doc. Everything pushed below (fold summary,
        // ghost text, cursorline pad) is decoration outside the
        // source-byte axis; letting it wrap would give the line more
        // display rows than `wrap_segments(col_count, …)`, the count
        // the host's scroll model and the caret walk both use.
        let wrap_cols: usize = body.iter().map(|s| s.content.chars().count()).sum();
        // Heading-preserved fold render (`docs/user/folding.md`):
        // append the ` ⋯ N lines` suffix AFTER all overlays so the
        // heading's syntax / visual / search styling is preserved, with
        // the dim summary trailing off the right.
        if let Some(n) = closed_fold_at_start {
            body.push(Span::styled(
                lattice_host::folds::fold_summary_text(n),
                TuiStyle::default().fg(fold_summary_color),
            ));
        }
        // Ghost text (Phase 4.2.g.7 polish). When the cursor
        // sits at end-of-line on this row AND the popup's
        // top-ranked candidate has a suffix to preview, paint
        // it as a dimmed inline overlay so the user sees the
        // most-likely accept inline. Cursor block visually
        // overlays the first ghost char (the typed prefix
        // ends right before it).
        // DR.3: ghost text previews the active completion at the
        // active cursor — interaction state, focused pane only.
        if ctx.is_active
            && line_idx == app.ad().cursor.line
            && (app.ad().cursor.byte as usize) == line_text.len()
            && let Some(suffix) = app.completion_ghost_text_suffix()
        {
            body.push(Span::styled(
                suffix,
                TuiStyle::default()
                    .fg(Color::DarkGray)
                    .add_modifier(Modifier::ITALIC),
            ));
        }
        // M.7.3.c: current-line highlight. When
        // `current-line-highlight-mode` is active (M.7.2 minor
        // / `:set cursorline`) and this row is the cursor's,
        // OR `theme.cursor_line_bg` into each body span's style
        // where the span's bg is unset. Selection wins
        // per-cell -- spans with bg already set (visual /
        // hlsearch / current_match overlays) keep their bg.
        // Pads to buffer width so the highlight extends to the
        // pane's right edge.
        //
        // DR.3: the cursor line is interaction state — `is_active`
        // gates it so inactive panes (no cursor) never paint a
        // cursor-line bg.
        //
        // Gutter + severity cell are intentionally not
        // highlighted -- they're their own visual column. vim
        // does highlight the line-number column; lattice can
        // add that as a follow-up if users want it.
        // PI.3: cursorline is now a per-pane decision on `ctx`, not gated on
        // "is this the active document". For the active pane this resolves
        // identically (`cursor_line` = `app.ad().cursor.line`,
        // `cursor_line_highlight` = the active option_cache value); a focused
        // preview pane paints its displayed buffer's cursorline at the
        // preview cursor.
        if ctx.cursor_line_highlight && line_idx == ctx.cursor_line {
            let bg = app.theme.cursor_line_bg;
            for span in body.iter_mut() {
                if span.style.bg.is_none() {
                    span.style = span.style.bg(bg);
                }
            }
            let used: usize = body.iter().map(|s| s.content.len()).sum();
            let pad_width = (buffer_w as usize).saturating_sub(used);
            if pad_width > 0 {
                body.push(Span::styled(
                    " ".repeat(pad_width),
                    TuiStyle::default().bg(bg),
                ));
            }
        }
        // LSP severity cell (Phase 4.1.d.iii). One cell pre-
        // pended to the gutter; severity glyph + colour when a
        // diagnostic touches the line, blank otherwise. Costs
        // one cell of gutter width on every frame -- visible
        // even when no diagnostics exist so the layout doesn't
        // shift when one arrives.
        // SG.4b: one cell per gutter column, left to right, each showing that
        // column's winning sign. Diagnostics land in `mark` and hunk marks in
        // `diff` because their DEFINITIONS say so, not because this loop knows
        // the difference — which is the whole point of the unification.
        //
        // The column order is the host's (a gutter whose columns moved per
        // buffer would be unreadable); what goes in each one is entirely the
        // registry's answer. Adjacent dedicated columns rather than one
        // contended cell is the Helix / Zed shape, and it is what stops a
        // diagnostic hiding a hunk mark on the lines a user is most likely to
        // be looking at.
        //
        // DR.3: sourced by `ctx.buffer_id`, so an inactive pane shows ITS
        // buffer's marks. Active pane's id is the active doc → byte-identical.
        let sign_cells: Vec<Span<'static>> = sign_gutter
            .iter()
            .map(|col| render_sign_cell(col.get(&line_idx).copied(), view))
            .collect();
        // D.3.e: line-background tint. Applied AFTER all other
        // body overlays (whitespace decoration, hlsearch,
        // visual selection, etc.) — the tint sits BEHIND the
        // already-styled content, so we layer bg last and
        // preserve every fg / modifier the upstream overlays
        // set. Conditional on the active-document sign map;
        // no-session / no-hunk-on-line → no allocation.
        let body = match diff_tint_bg(view, ctx.buffer_id, line_idx) {
            Some(bg) => apply_diff_tint(body, bg),
            None => body,
        };
        // CM.3d (2026-07-22): compilation location line tint —
        // background tint on the whole line + link foreground on
        // the file-path portion.
        let body = match compilation_location_tint(view, ctx.buffer_id, line_idx) {
            Some((start, end, bg, fg)) => apply_compilation_location_tint(body, start, end, bg, fg),
            None => body,
        };
        // MC.3: fenced/indented code-block background — the weakest, widest
        // tint, applied LAST so any narrower background already set (diff line,
        // compilation location, search match, visual selection) wins on
        // overlap. `apply_diff_tint` fills spans without their own bg (the
        // text), then a trailing pad fills the rest of the row to `buffer_w`
        // so the block reads as a solid rectangle including blank lines and
        // trailing space (mirrors the cursorline pad above; matches the GPUI
        // peer's full-row code-block quad). The pad only fills the gap, so a
        // row already padded to full width by a stronger tint (e.g. the
        // cursorline on a code line) is left untouched.
        let body = match code_block_tint_bg(view, ctx.buffer_id, line_idx) {
            Some(bg) => {
                let mut body = apply_diff_tint(body, bg);
                let used: usize = body.iter().map(|s| s.content.len()).sum();
                let pad_width = (buffer_w as usize).saturating_sub(used);
                if pad_width > 0 {
                    body.push(Span::styled(
                        " ".repeat(pad_width),
                        TuiStyle::default().bg(bg),
                    ));
                }
                body
            }
            None => body,
        };
        // DR.3: inactive panes are a paint-time opacity (the design's
        // §Render contract). Dim the fully-decorated body (syntax +
        // semantic + diagnostics + inlays + diff tint) uniformly AFTER
        // every decoration overlay and BEFORE wrap-segmenting, so the
        // pane reads as unfocused without dropping any decoration cue
        // (`feedback_decorations_update_in_place`). The focused pane
        // skips this entirely (opacity 1.0 → byte-identical). The
        // gutter/severity/diff-sign prefix keeps its own styling, as
        // it did on the pre-merge inactive path.
        let body = if ctx.is_active || !view.app.theme.dim_inactive_panes {
            body
        } else {
            let overlay = view.app.theme.inactive_pane_overlay;
            body.into_iter()
                .map(|mut s| {
                    s.style = s.style.patch(overlay);
                    s
                })
                .collect()
        };
        // W.4 (soft-wrap): split the fully-overlaid body into
        // display segments of `body_col_width` columns when `:set
        // wrap` is on. Segment 0 carries the real prefix + gutter
        // (line number / fold / diagnostic); continuation segments
        // get a blank severity/diff prefix and a `↪` gutter. Wrap
        // off ⇒ one segment ⇒ byte-identical to the prior single
        // push. The height cap stops mid-line if the viewport
        // fills (matches the pre-wrap truncation behaviour).
        let segments = if wrap_on {
            split_body_into_segments(body, body_col_width as usize, wrap_cols)
        } else {
            vec![body]
        };
        let mut seg_iter = segments.into_iter();
        if let Some(seg0) = seg_iter.next() {
            // PU.1b-1a: drop the severity + diff sign cells entirely
            // when `signcolumn=no` so content abuts the gutter — the
            // exact geometry `buffer_w` reserved via
            // `sign_columns_width`. Reserved (default) → byte-identical.
            let sign_prefix = if view.sign_column {
                sign_cells
            } else {
                Vec::new()
            };
            out.push(combine_prefixed(sign_prefix, gutter, seg0));
            row_src.push(Some(lattice_host::mouse::RowOrigin {
                source_line: line_idx,
                segment: 0,
            }));
        }
        // MO.2: `cont_idx + 1` — continuation rows are segments 1, 2, …
        // of the same logical line, and that index is what shifts a
        // click's column into the right part of it. Without it the tail
        // of a wrapped paragraph would resolve to its head.
        for (cont_idx, seg) in seg_iter.enumerate() {
            if (out.len() as u32) >= height {
                break;
            }
            // Continuation rows carry no fold marker (the blank glyph
            // slot is part of `format_gutter_cell`'s layout), so the
            // whole cell is one dim span.
            let cont_gutter = vec![Span::styled(
                format_gutter_cell(WRAP_CONT_MARKER, gutter_w, None),
                TuiStyle::default()
                    .fg(Color::DarkGray)
                    .add_modifier(Modifier::DIM),
            )];
            // PU.1b-1a: continuation rows mirror seg0's sign-column
            // geometry — two blank cells when reserved, none when
            // `signcolumn=no`.
            let cont_sign_prefix = if view.sign_column {
                vec![Span::raw(" "); lattice_mode::BUILTIN_SIGN_COLUMNS.len()]
            } else {
                Vec::new()
            };
            out.push(combine_prefixed(cont_sign_prefix, cont_gutter, seg));
            row_src.push(Some(lattice_host::mouse::RowOrigin {
                source_line: line_idx,
                segment: cont_idx as u32 + 1,
            }));
        }
        // D.3.b.1: emit Below-anchored virtual rows for this
        // document line, then continue to the next visible
        // document line.
        for vrow in virtual_rows_at(
            &virtual_rows_matrix,
            line_idx,
            lattice_cells::AnchorPosition::Below,
        ) {
            if (out.len() as u32) >= height {
                break;
            }
            out.push(render_virtual_row(view, vrow, gutter_w, body_col_width));
            row_src.push(None);
        }
    }
    debug_assert_eq!(
        out.len(),
        row_src.len(),
        "MO.2: every painted row records its origin"
    );
    app.pane_hits.borrow_mut().set_rows(ctx.pane_id, row_src);
    out
}

fn hlsearch_style(
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) -> TuiStyle {
    // T.6: hlsearch is now a BACKGROUND tint resolved from
    // `search.match` (both renderers agree; the legacy cyan-fg recolor
    // is retired). Softer than the current match so it reads as
    // "another instance of what you're searching for".
    let bg = resolved
        .get(ids.search_match)
        .bg
        .map(crate::theme::host_color_to_ratatui)
        .unwrap_or(Color::Cyan);
    TuiStyle::default().bg(bg)
}

/// 4.4.e: `documentHighlight` overlay style. Soft tint that
/// reads as "same symbol, related to the one your cursor is
/// on". Distinct hue per kind so the user can spot reads-vs-
/// writes-vs-other without consulting the spec:
///
/// - `Read` (default) — dim green; "this is being consulted"
/// - `Write` — dim red; "this site mutates the symbol"
/// - `Text` / `None` — dim blue; "this is an occurrence"
///
/// All three use a dark background tint + the original fg so
/// the text stays readable; composes with the other overlays
/// (diagnostics underline, visual selection bg, hlsearch).
fn document_highlight_style(
    kind: Option<lattice_lsp::lsp_types::DocumentHighlightKind>,
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) -> TuiStyle {
    use lattice_lsp::lsp_types::DocumentHighlightKind;
    // T.6: the 3 distinct kinds resolve from the registered
    // `doc_highlight.{read,write,text}` elements (both renderers honor
    // all three). Fallbacks mirror the legacy literals.
    let (id, fallback) = match kind {
        Some(DocumentHighlightKind::READ) => (ids.doc_highlight_read, Color::Rgb(20, 50, 25)),
        Some(DocumentHighlightKind::WRITE) => (ids.doc_highlight_write, Color::Rgb(60, 20, 20)),
        _ => (ids.doc_highlight_text, Color::Rgb(20, 30, 60)),
    };
    let bg = resolved
        .get(id)
        .bg
        .map(crate::theme::host_color_to_ratatui)
        .unwrap_or(fallback);
    TuiStyle::default().bg(bg)
}

/// Style for substitute live-preview matches. Magenta-bg with a
/// strike-through reads as "this is going to be replaced if you
/// hit Enter" -- distinct from hlsearch's "this is what your
/// search is finding" cyan, and distinct from the current-match
/// yellow.
fn substitute_preview_style(
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) -> TuiStyle {
    // T.6: bg resolves from `substitute.preview` (shared with GPUI).
    // The CROSSED_OUT strikethrough stays TUI-only ("this is going to
    // be replaced if you hit Enter").
    let bg = resolved
        .get(ids.substitute_preview)
        .bg
        .map(crate::theme::host_color_to_ratatui)
        .unwrap_or(Color::Magenta);
    TuiStyle::default()
        .bg(bg)
        .add_modifier(Modifier::CROSSED_OUT)
}

/// For blockwise Visual: the rectangle defined by the selection's
/// `(anchor, head)` positions. Returns `None` if not in blockwise
/// mode.
///
/// 2026-05-27: migrated to
/// [`lattice_host::visual::BlockExtents`] / `Editor::
/// visual_block_extents` — renderer-neutral so the GPUI peer can
/// consume the same data. Thin wrapper kept so this peer's call
/// sites resolve unchanged.
fn visual_block_extents(app: &App) -> Option<BlockExtents> {
    app.ad().visual_block_extents
}

type BlockExtents = lattice_host::visual::BlockExtents;

/// Compute the rendered range of the visual selection. Returns `None` if
/// not in Visual mode. For Linewise visual the byte extents on the first
/// and last lines are normalized to cover the full lines (mirrored from
/// the dispatcher's `Range::Selection` resolution).
// 5.8.P: `visual_selection_range` migrated to
// `lattice_host::editor::Editor::visual_selection_range` — renderer-
// neutral logic shared between TUI and GPUI peers. Thin wrapper
// kept here so this peer's call sites resolve unchanged.
fn visual_selection_range(app: &App) -> Option<ProtoRange> {
    app.ad().visual_range
}

fn visual_style(
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) -> TuiStyle {
    // T.6: visual selection bg resolves from `selection` (shared with
    // GPUI's selection quad). Distinct from the search-match style.
    let bg = resolved
        .get(ids.selection)
        .bg
        .map(crate::theme::host_color_to_ratatui)
        .unwrap_or(Color::Blue);
    TuiStyle::default().bg(bg)
}

/// If `range` covers any bytes on `line_idx`, return the within-line
/// half-open byte interval `[start, end)`. `line_len` is the line's
/// content length excluding the trailing newline.
fn match_overlay_range(
    range: ProtoRange,
    line_idx: u32,
    line_len: usize,
) -> Option<(usize, usize)> {
    if line_idx < range.start.line || line_idx > range.end.line {
        return None;
    }
    let start = if line_idx == range.start.line {
        range.start.byte as usize
    } else {
        0
    };
    let end = if line_idx == range.end.line {
        range.end.byte as usize
    } else {
        line_len
    };
    if start >= end || start >= line_len {
        return None;
    }
    Some((start, end.min(line_len)))
}

/// S3.c.3 (2026-05-26): visibility bumped to `pub(crate)` so
/// `cells_render::tests` can validate the overlay walks cell-
/// derived spans correctly. Matches the precedent set by
/// `apply_whitespace_decoration` / `apply_semantic_token_overlay`.
pub(crate) fn apply_match_overlay(
    spans: Vec<Span<'static>>,
    overlay_start: usize,
    overlay_end: usize,
    overlay_style: TuiStyle,
) -> Vec<Span<'static>> {
    let mut out: Vec<Span<'static>> = Vec::with_capacity(spans.len() + 2);
    let mut cursor = 0usize;
    for span in spans {
        let s = span.content.as_ref().to_string();
        let span_start = cursor;
        let span_end = cursor + s.len();
        let overlap_start = span_start.max(overlay_start);
        let overlap_end = span_end.min(overlay_end);
        if overlap_start >= overlap_end {
            out.push(Span::styled(s, span.style));
        } else {
            if overlap_start > span_start {
                let pre = s[..overlap_start - span_start].to_string();
                out.push(Span::styled(pre, span.style));
            }
            let mid = s[overlap_start - span_start..overlap_end - span_start].to_string();
            out.push(Span::styled(mid, overlay_style));
            if overlap_end < span_end {
                let post = s[overlap_end - span_start..].to_string();
                out.push(Span::styled(post, span.style));
            }
        }
        cursor = span_end;
    }
    out
}

fn match_style(
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) -> TuiStyle {
    // T.6: the current search match resolves from `search.current` as a
    // BACKGROUND tint (both renderers agree; the legacy yellow-fg
    // recolor is retired).
    let bg = resolved
        .get(ids.search_current)
        .bg
        .map(crate::theme::host_color_to_ratatui)
        .unwrap_or(Color::Yellow);
    TuiStyle::default().bg(bg)
}

/// 4.4.g: splice `virtual_text` into `spans` at `byte_offset`
/// (utf-8 byte index within the *concatenated* span text, i.e.
/// the original line). When `byte_offset` lands strictly inside
/// a span, the span is split on the byte boundary; when it
/// lands at a span boundary (or past the end), the virtual
/// text inserts cleanly between spans without splitting.
///
/// `byte_offset` past the end of all spans appends -- the
/// caller's responsibility to convert LSP utf-16 columns to
/// utf-8 bytes before passing in.
/// S3.c.4 (2026-05-26): visibility bumped to `pub(crate)` so
/// `cells_render::tests` can validate the splice walks cell-
/// derived spans correctly. Matches the precedent set by the
/// other overlay-engine fns.
pub(crate) fn splice_virtual_text_into_spans(
    spans: Vec<Span<'static>>,
    byte_offset: usize,
    virtual_text: String,
    virtual_style: TuiStyle,
) -> Vec<Span<'static>> {
    if virtual_text.is_empty() {
        return spans;
    }
    let mut out: Vec<Span<'static>> = Vec::with_capacity(spans.len() + 2);
    let mut cursor = 0usize;
    let mut spliced = false;
    for span in spans {
        let s = span.content.as_ref().to_string();
        let span_start = cursor;
        let span_end = cursor + s.len();
        if !spliced && byte_offset >= span_start && byte_offset <= span_end {
            if byte_offset == span_start {
                // Inject before this span.
                out.push(Span::styled(virtual_text.clone(), virtual_style));
                out.push(Span::styled(s, span.style));
            } else if byte_offset == span_end {
                // Inject after this span -- push the span first,
                // then the virtual text, then continue.
                out.push(Span::styled(s, span.style));
                out.push(Span::styled(virtual_text.clone(), virtual_style));
            } else {
                // Split inside this span on the byte boundary.
                let prefix = s[..byte_offset - span_start].to_string();
                let suffix = s[byte_offset - span_start..].to_string();
                out.push(Span::styled(prefix, span.style));
                out.push(Span::styled(virtual_text.clone(), virtual_style));
                out.push(Span::styled(suffix, span.style));
            }
            spliced = true;
        } else {
            out.push(Span::styled(s, span.style));
        }
        cursor = span_end;
    }
    if !spliced {
        // Offset past every span -- append at the line end.
        out.push(Span::styled(virtual_text, virtual_style));
    }
    out
}

/// 4.4.g: style for inlay-hint virtual text. Dimmed inline so
/// the user can spot it as "annotation, not actual buffer
/// content" -- italic + dim gray on default bg. Kind-specific
/// hue could differentiate type vs parameter hints in a
/// follow-up; v1 keeps a single style for simplicity.
fn inlay_hint_style(
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
) -> TuiStyle {
    // T.6: inlay-hint fg resolves from `inlay.hint` (shared with GPUI's
    // `inlay_color`). The italic modifier reads as "annotation, not
    // actual buffer content".
    let fg = resolved
        .get(ids.inlay_hint)
        .fg
        .map(crate::theme::host_color_to_ratatui)
        .unwrap_or(Color::DarkGray);
    TuiStyle::default().fg(fg).add_modifier(Modifier::ITALIC)
}

/// Style for ONE spliced inlay row — the row's own element, not a
/// blanket `inlay.hint`.
///
/// The splice above re-inserts virtual text that
/// `display_line_to_source_spans` deliberately dropped, so the run's
/// style does not survive the round trip and has to be resolved again
/// here. It was resolved as [`inlay_hint_style`] unconditionally, which
/// is right for an LSP hint and wrong for every other producer: DL.3a
/// gave `InlayHintRow` a real style precisely so a producer with its own
/// vocabulary paints in it, and the cells worker and GPUI's
/// `display_run_to_synthetic_cell` both honour it. This peer did not, so
/// `directory-listing-mode`'s per-language icons all painted one grey —
/// the published data was correct and only the TUI's paint discarded it.
///
/// Italic stays exclusive to [`lattice_syntax::Style::InlayHint`]. It is
/// the "annotation, not buffer content" cue for an LSP hint; a listing's
/// icon glyph IS the row's content, and slanting a devicon just smears it.
fn inlay_row_style(
    resolved: &lattice_host::ui::theme::ResolvedTheme,
    ids: &lattice_host::ui::theme::BuiltinElementIds,
    style: lattice_syntax::Style,
) -> TuiStyle {
    if matches!(style, lattice_syntax::Style::InlayHint) {
        return inlay_hint_style(resolved, ids);
    }
    let s = lattice_host::ui::theme::resolve_syntax_style(resolved, ids, style);
    let mut out = TuiStyle::default();
    if let Some(fg) = s.fg {
        out = out.fg(crate::theme::host_color_to_ratatui(fg));
    }
    // An element may carry weight/emphasis of its own (`listing.dir` is
    // bold), and dropping those would make a themed element half-applied.
    if s.modifiers.bold {
        out = out.add_modifier(Modifier::BOLD);
    }
    if s.modifiers.italic {
        out = out.add_modifier(Modifier::ITALIC);
    }
    if s.modifiers.dim {
        out = out.add_modifier(Modifier::DIM);
    }
    if s.modifiers.underline {
        out = out.add_modifier(Modifier::UNDERLINED);
    }
    out
}

/// L4a.3 (lsp-architecture.md §15): style for the inline end-of-line
/// diagnostic summary. Reuses the gutter's per-severity themed style
/// (so the eol text colour matches the gutter glyph exactly) and adds
/// italic to read as virtual, non-document text — the same cue inlay
/// hints use. `severity_rank` is Error = 0 … Hint = 3 (matching
/// `lattice_lsp`'s `severity_rank` / the published summary).
fn diagnostic_summary_style(severity_rank: u8, view: &FrameView<'_>) -> TuiStyle {
    let theme = &view.app.theme;
    let base = match severity_rank {
        0 => theme.diagnostic_error_style,
        1 => theme.diagnostic_warning_style,
        2 => theme.diagnostic_info_style,
        _ => theme.diagnostic_hint_style,
    };
    base.add_modifier(Modifier::ITALIC)
}

/// 4.4.h: apply LSP semantic styling to the spans intersecting
/// `[overlay_start, overlay_end)`. Replaces fg + folds in
/// modifiers WITHOUT clobbering existing bg / underline /
/// reverse from earlier passes (tree-sitter set bg = None
/// commonly; visual / hlsearch / diagnostics overlays may
/// have set bg). Same span-splitting machinery as
/// `apply_match_overlay`.
///
/// S3.c.2 (2026-05-26): visibility bumped to `pub(crate)` so
/// `cells_render::tests` can validate the overlay's behaviour
/// against cell-derived bodies. Matches the existing precedent
/// set by `apply_whitespace_decoration`.
pub(crate) fn apply_semantic_token_overlay(
    spans: Vec<Span<'static>>,
    overlay_start: usize,
    overlay_end: usize,
    fg: Color,
    modifiers: Modifier,
) -> Vec<Span<'static>> {
    let mut out: Vec<Span<'static>> = Vec::with_capacity(spans.len() + 2);
    let mut cursor = 0usize;
    for span in spans {
        let s = span.content.as_ref().to_string();
        let span_start = cursor;
        let span_end = cursor + s.len();
        let overlap_start = span_start.max(overlay_start);
        let overlap_end = span_end.min(overlay_end);
        if overlap_start >= overlap_end {
            out.push(Span::styled(s, span.style));
        } else {
            if overlap_start > span_start {
                let pre = s[..overlap_start - span_start].to_string();
                out.push(Span::styled(pre, span.style));
            }
            let mid = s[overlap_start - span_start..overlap_end - span_start].to_string();
            // Merge: keep prior bg / underline / reverse;
            // override fg + add modifier bits.
            let merged = span.style.fg(fg).add_modifier(modifiers);
            out.push(Span::styled(mid, merged));
            if overlap_end < span_end {
                let post = s[overlap_end - span_start..].to_string();
                out.push(Span::styled(post, span.style));
            }
        }
        cursor = span_end;
    }
    out
}

/// 4.4.h: pick a foreground color for a semantic-token kind.
/// Names are the LSP-standard token-type strings (see
/// `SemanticTokenType` consts in `lsp-types`). Servers may
/// declare custom token types beyond the standard set; those
/// fall through to the default magenta so they're at least
/// distinguishable from un-styled text.
///
/// Modifiers are folded into the style via
/// `apply_semantic_token_modifiers` (italic / bold / etc.);
/// this fn only chooses the hue.
fn semantic_token_color(kind: &str) -> Color {
    match kind {
        "keyword" | "controlKeyword" => Color::Magenta,
        "type" | "class" | "struct" | "interface" | "enum" | "typeParameter" => Color::Cyan,
        "function" | "method" | "macro" => Color::Yellow,
        "string" => Color::Green,
        "number" => Color::LightYellow,
        "comment" => Color::DarkGray,
        "operator" => Color::LightCyan,
        "variable" | "parameter" | "property" | "enumMember" => Color::White,
        "namespace" | "modifier" => Color::LightMagenta,
        _ => Color::Magenta,
    }
}

/// 4.4.h: apply LSP modifier bits to a base style. `static`,
/// `readonly`, `deprecated` etc. carry visual cues
/// (italic / strike-through). Idempotent; missing modifiers
/// leave the style untouched.
fn apply_semantic_token_modifiers(mut style: TuiStyle, modifiers: &[String]) -> TuiStyle {
    for m in modifiers {
        match m.as_str() {
            "deprecated" => style = style.add_modifier(Modifier::CROSSED_OUT),
            "readonly" | "static" => style = style.add_modifier(Modifier::ITALIC),
            "defaultLibrary" => style = style.add_modifier(Modifier::DIM),
            _ => {}
        }
    }
    style
}

// Slice A.2b.2: `inlay_hint_label_text` is no longer imported here
// — the per-line splice block previously called it to flatten LSP
// inlay-hint labels, but that flattening now happens once per
// publish on the host (`Editor::build_active_inlay_hints`) and the
// renderer reads `rs.syntax.inlay_hints` with the text already
// flattened. The function still exists at `lattice_lsp::
// inlay_hint_label_text` for any other callers.

/// Trailing-side padding cells between the gutter's content and the
/// buffer column. Layout of the three cells: one separator space, the
/// fold-glyph slot, then one more space so the glyph doesn't run flush
/// against the code (`_99_▸_code`). The extra gap makes the fold marker
/// read as a distinct affordance rather than part of the text.
const GUTTER_TRAILING_PAD: u32 = 3;

fn gutter_width(line_count: u32) -> u32 {
    // Layout: 1 cell leading pad + N digits + GUTTER_TRAILING_PAD
    // (separator space + fold-glyph slot + trailing gap). For
    // line_count = 99 and pad = 3 that's "_99_▸_" => 6 cells.
    let digits = line_count.max(1).ilog10() + 1;
    digits + 1 + GUTTER_TRAILING_PAD
}

/// Resolved fold-marker colours for a pane, one per marker state.
/// Themed via `gutter.fold.open` / `gutter.fold.closed`; the GPUI peer
/// resolves the same two elements. `Copy` so it threads cheaply through
/// the per-line gutter path.
#[derive(Debug, Clone, Copy)]
struct FoldColors {
    open: Color,
    closed: Color,
}

/// Pick the gutter fold marker for a buffer line: `▸` + the closed
/// colour when the line begins a closed fold, `▾` + the open colour when
/// it begins an open fold, or `None` when the line is unaffiliated with
/// any fold start (`docs/user/folding.md`). Shows a marker on every
/// foldable head — open or closed — matching the GPUI peer. Even on a
/// gutterless / centred buffer (help, the dashboard) the marker renders
/// just before the text: the centring pad is folded into `gutter_w`, so
/// `format_gutter_cell` right-aligns the glyph against the content.
fn fold_glyph_for(
    view: &FrameView<'_>,
    line_idx: u32,
    colors: FoldColors,
) -> Option<(char, Color)> {
    let f = view.fold_start_at_any(line_idx)?;
    Some(if f.closed {
        ('▸', colors.closed)
    } else {
        ('▾', colors.open)
    })
}

/// Build the gutter cell as styled spans. With no fold marker the whole
/// cell is one dim-gutter span; with a marker the glyph is split into its
/// own themed span (the `… 99 ▸ ` layout puts the glyph second-from-last,
/// with a separator space before and a trailing gap after), so the fold
/// colour applies to the glyph alone and the line number keeps the
/// gutter tone.
fn gutter_spans(label: &str, width: u32, marker: Option<(char, Color)>) -> Vec<Span<'static>> {
    let num_style = TuiStyle::default().fg(Color::DarkGray);
    let cell = format_gutter_cell(label, width, marker.map(|(g, _)| g));
    let Some((_, color)) = marker else {
        return vec![Span::styled(cell, num_style)];
    };
    // `cell` ends `…{sep}{glyph}{trailing}` — split on chars so the
    // multi-byte glyph (`▸`/`▾`, 3 bytes) is handled cleanly.
    let chars: Vec<char> = cell.chars().collect();
    let n = chars.len();
    let prefix: String = chars[..n - 2].iter().collect();
    let glyph: String = chars[n - 2..n - 1].iter().collect();
    let trailing: String = chars[n - 1..].iter().collect();
    vec![
        Span::styled(prefix, num_style),
        Span::styled(glyph, TuiStyle::default().fg(color)),
        Span::styled(trailing, num_style),
    ]
}

/// Format the gutter cell text for a numbered line.
/// Layout: `[leading_pad][label][separator][glyph_or_space]`.
/// The separator is one plain space sitting between the line
/// number and the rightmost cell so digits don't run flush against
/// the fold glyph; the glyph (or a plain space when no fold starts
/// on this line) occupies the rightmost cell, immediately
/// adjacent to the buffer column. This mirrors vim's
/// `signcolumn`-on-the-right convention -- e.g. ` 99 ▸` for a
/// closed fold's heading.
fn format_gutter_cell(label: &str, width: u32, glyph: Option<char>) -> String {
    use unicode_width::UnicodeWidthStr;
    // Rightmost cell is the glyph; one separator space sits before
    // the label. Leading pad fills the rest.
    //
    // Pad by the label's DISPLAY WIDTH, not its byte length: the wrap
    // continuation marker `↪` (U+21AA) is 3 bytes but occupies a single
    // terminal cell, so `label.len()` under-counts it by 2 and the
    // gutter comes out one cell short (the extra byte-vs-cell gap gets
    // clamped by `saturating_sub`). That made wrapped continuation rows
    // paint one column left of segment 0's body and, because the cursor
    // math uses segment 0's `gutter_w`, put the cursor one cell right of
    // the glyph on every wrapped line. For ASCII numeric labels
    // display-width == byte-len, so the numbered gutter is unchanged.
    let label_cols = UnicodeWidthStr::width(label);
    // 3 trailing cells: separator space + glyph + trailing gap.
    let leading = (width as usize).saturating_sub(label_cols + 3);
    let g = glyph.unwrap_or(' ');
    format!("{:lead$}{label} {g} ", "", lead = leading)
}

fn render_gutter(line_idx: u32, width: u32, marker: Option<(char, Color)>) -> Vec<Span<'static>> {
    let n = (line_idx + 1).to_string();
    gutter_spans(&n, width, marker)
}

fn render_gutter_for(
    view: &FrameView<'_>,
    line_idx: u32,
    width: u32,
    cursor_line: u32,
    display_line_numbers: Option<&[u32]>,
    fold_colors: FoldColors,
) -> Vec<Span<'static>> {
    let marker = fold_glyph_for(view, line_idx, fold_colors);
    if !view.show_line_numbers {
        // No-numbers gutter: glyph (or empty) at the inner edge,
        // GUTTER_TRAILING_PAD - 1 trailing spaces, the rest leading
        // padding. The layout still aligns with the numbered case
        // so toggling `:set number` doesn't shift content.
        return gutter_spans("", width, marker);
    }
    // K.4.6 follow-up (2026-06-02): consult the substrate's
    // composed→source row map (`display_line_numbers`) when
    // present. Multibuffer publishes it; regular Documents
    // return None (their composed row IS their source line).
    // Substrate-aligned per [[feedback_buffers_no_special_case]]
    // — the renderer checks the published mapping, not BufferKind.
    //
    // 2026-06-02 follow-up: `cursor_line` + `display_line_numbers`
    // are now passed by the caller (per-pane state) so this fn
    // works correctly for inactive panes too. Active path passes
    // `app.ad().cursor.line` + `app.ad().display_line_numbers`;
    // inactive path passes `pane.cursor.line` + the inactive
    // handle's own `display_line_numbers()`. No more `app.ad()`
    // reads — the gutter stays per-pane consistent.
    let display_line_idx: u32 = if let Some(map) = display_line_numbers {
        // Multibuffer: composed_row → source line. Out-of-bounds
        // is theoretically possible during transient renders
        // mid-recompose; fall back to identity rather than
        // panic.
        *map.get(line_idx as usize).unwrap_or(&line_idx)
    } else {
        line_idx
    };
    // K.4.6 follow-up (2026-06-02): suppress relativenumber on
    // multibuffer views — relative distance across non-
    // contiguous source rows is meaningless. Matches Zed.
    let multibuffer_mode = display_line_numbers.is_some();
    if !view.relative_line_numbers || line_idx == cursor_line || multibuffer_mode {
        return render_gutter(display_line_idx, width, marker);
    }
    let dist = line_idx.abs_diff(cursor_line);
    let n = dist.to_string();
    gutter_spans(&n, width, marker)
}

/// Width of the diagnostic-severity column prepended to the
/// PU.1b-1a (`signcolumn`): total width of the gutter sign columns for `view`,
/// or `0` when the pane's resolved `signcolumn=no`.
///
/// SG.4b: ONE cell per registered gutter column — the two hardcoded widths
/// (`DIAG_GUTTER_WIDTH` + `DIFF_SIGN_GUTTER_WIDTH`) are gone with the two
/// hardcoded columns. The count is `BUILTIN_SIGN_COLUMNS.len()`, which is 2,
/// so the geometry is byte-identical to what it replaced; the difference is
/// that a third column would now widen the gutter by construction rather than
/// by someone remembering to add a constant here.
///
/// The single gate every compose site reads, so the width math (`buffer_w`,
/// cursor `wrap_width` / `col`) and the per-line prefix cells stay in lockstep
/// — a buffer with `signcolumn=no` (help-mode, synthetic buffers) drops every
/// sign cell and renders gutterless, with the renderer never branching on
/// buffer kind.
fn sign_columns_width(view: &FrameView<'_>) -> u32 {
    if view.sign_column {
        lattice_mode::BUILTIN_SIGN_COLUMNS.len() as u32
    } else {
        0
    }
}

/// D.3.b.1 (2026-05-29): iterate `VirtualRowMatrix` rows
/// anchored at `line` with the given `position`. The matrix
/// keeps rows sorted by `(anchor_line, position)` with
/// `Above < Below`, so this is a single contiguous slice we
/// just `take_while` over.
fn virtual_rows_at<'a>(
    matrix: &'a lattice_cells::VirtualRowMatrix,
    line: u32,
    position: lattice_cells::AnchorPosition,
) -> impl Iterator<Item = &'a lattice_cells::VirtualRow> + 'a {
    let start = matrix.first_row_at_or_after(line) as usize;
    matrix.rows[start..]
        .iter()
        .take_while(move |r| r.anchor_line == line)
        .filter(move |r| r.position == position)
        // Pinned rows (sticky headerlines + the branding masthead) are
        // rendered at the pane top in the pre-pass; skip them here so they
        // don't double-paint in the content loop.
        .filter(|r| !r.kind.is_pinned())
}

/// D.3.b.1: render a virtual row as a ratatui `Line`.
/// Emits the same blank severity + diff-sign + gutter prefix
/// as a document row so the body column lines up exactly,
/// then renders the row's cells as a single styled span with
/// a dim-red background (the "this content existed in
/// baseline but is gone / replaced in current" convention
/// borrowed from Vim's `:diff` and GitHub-style diffs).
/// Empty `cells` (D.3.a's empty placeholder) still emit a
/// row of the correct width so the deletion appears as a
/// visible gap.
/// TC.8: a virtual row's gutter — the document gutter when the row carries a
/// source line, the blank one otherwise.
///
/// Built by `render_gutter` rather than formatted here so the two cannot
/// drift: a context row whose digits sit one column off from the code beneath
/// it reads as a layout bug, and the only way to be sure they agree is to run
/// the same formatter. The blank branch is the same total width by
/// construction (`format_gutter_cell` pads to `width`), so toggling
/// `line-numbers` never shifts the strip.
fn virtual_row_gutter_spans(
    gutter_line: Option<u32>,
    gutter_w: u32,
    gutter_fg: Option<u32>,
) -> Vec<Span<'static>> {
    match gutter_line {
        Some(line) => {
            let mut spans = render_gutter(line, gutter_w, None);
            // TC.11: recolour rather than re-format. `render_gutter` owns the
            // LAYOUT (which is the thing that must match the document gutter
            // exactly); the theme owns only the colour, so the two concerns
            // cannot drift into each other.
            if let Some(rgb) = gutter_fg {
                let c = Color::Rgb(
                    ((rgb >> 16) & 0xff) as u8,
                    ((rgb >> 8) & 0xff) as u8,
                    (rgb & 0xff) as u8,
                );
                for span in &mut spans {
                    span.style = span.style.fg(c);
                }
            }
            spans
        }
        None => vec![Span::styled(
            " ".repeat(gutter_w as usize),
            TuiStyle::default().fg(Color::DarkGray),
        )],
    }
}

fn render_virtual_row(
    view: &FrameView<'_>,
    vrow: &lattice_cells::VirtualRow,
    gutter_w: u32,
    body_width: u32,
) -> Line<'static> {
    let severity_blank = Span::styled(" ".to_string(), TuiStyle::default());
    let diff_sign_blank = Span::styled(" ".to_string(), TuiStyle::default());
    let gutter = virtual_row_gutter_spans(vrow.gutter_line, gutter_w, vrow.gutter_fg);
    // D.3.b.2 (2026-05-29): emit per-cell spans with run
    // coalescing — adjacent cells sharing the same `fg`
    // merge into a single styled Span so an 80-char
    // baseline line produces ~5 spans, not 80.
    //
    // D.6.i (2026-05-31): backdrop selection by `vrow.kind`.
    // `vrow.bg` (0xRRGGBB u32) overrides the kind-based default
    // when `Some` — sticky rows supply their own retro HUD palette.
    // Deletion blocks / generic rows fall back to the theme's
    // diff_deletion_block_bg; filler and sticky rows without an
    // explicit bg have no backdrop.
    //
    // `cell.fg = 0` means "use terminal default" (renderer
    // leaves fg unset).
    let bg: Option<Color> = vrow
        .bg
        .map(|rgb| {
            Color::Rgb(
                ((rgb >> 16) & 0xff) as u8,
                ((rgb >> 8) & 0xff) as u8,
                (rgb & 0xff) as u8,
            )
        })
        .or(match vrow.kind {
            lattice_cells::VirtualRowKind::DeletionBlock
            | lattice_cells::VirtualRowKind::Generic => Some(view.app.theme.diff_deletion_block_bg),
            // Filler/Sticky/BrandingBlock: no kind backdrop. The TUI paints
            // the branding cells as its terminal-art treatment (half-block
            // mark); no full-row backdrop behind them.
            lattice_cells::VirtualRowKind::Filler
            | lattice_cells::VirtualRowKind::Sticky
            // MG.26b: an annotation carries no backdrop of its own —
            // a blame heading tinted like a deletion would read as one.
            | lattice_cells::VirtualRowKind::Annotation
            // IM.3: a media block's rows carry their alt text as ordinary
            // cells, which is the TUI's whole rendering of it. A deletion
            // backdrop behind them would read as removed lines; the block
            // supplies its own `bg` when it wants a box.
            | lattice_cells::VirtualRowKind::MediaBlock
            | lattice_cells::VirtualRowKind::BrandingBlock => None,
        });
    let mut spans: Vec<Span<'static>> = Vec::new();
    let mut run_text = String::new();
    let mut run_fg: Option<u32> = None;
    let flush = |text: &mut String, fg: Option<u32>, spans: &mut Vec<Span<'static>>| {
        if text.is_empty() {
            return;
        }
        let mut style = TuiStyle::default();
        if let Some(c) = bg {
            style = style.bg(c);
        }
        if let Some(rgb) = fg
            && rgb != 0
        {
            let r = ((rgb >> 16) & 0xff) as u8;
            let g = ((rgb >> 8) & 0xff) as u8;
            let b = (rgb & 0xff) as u8;
            style = style.fg(Color::Rgb(r, g, b));
        }
        spans.push(Span::styled(std::mem::take(text), style));
    };
    for cell in vrow.cells.iter() {
        let Some(ch) = char::from_u32(cell.codepoint) else {
            continue;
        };
        let cell_fg = Some(cell.fg);
        if run_fg.is_none() {
            run_fg = cell_fg;
        }
        if run_fg != cell_fg {
            flush(&mut run_text, run_fg, &mut spans);
            run_fg = cell_fg;
        }
        run_text.push(ch);
    }
    flush(&mut run_text, run_fg, &mut spans);
    // Pad the row out to body_width so the backdrop (when present — deletion
    // blocks; not filler rows) covers the full body column. Horizontal
    // centring is handled upstream by the gutter (content_left_pad), not here.
    let used: u32 = spans.iter().map(|s| s.content.chars().count() as u32).sum();
    if used < body_width {
        let mut pad_style = TuiStyle::default();
        if let Some(c) = bg {
            pad_style = pad_style.bg(c);
        }
        spans.push(Span::styled(
            " ".repeat((body_width - used) as usize),
            pad_style,
        ));
    }
    let mut out: Vec<Span<'static>> = Vec::with_capacity(3 + spans.len());
    out.push(severity_blank);
    out.push(diff_sign_blank);
    out.extend(gutter);
    out.extend(spans);
    Line::from(out)
}

/// D.3.e (2026-05-29): line background tint colour for
/// `line_idx`, if any. Reuses the same `DiffSignMap` data
/// path as `render_diff_sign_cell` — one classification
/// source for both decorations. Returns `None` when no
/// session, no hunk on this row, or the hunk is `Remove`
/// (which has no current-side row to tint; the deletion
/// block from D.3.b is the visible surface for removes).
///
/// Tint colours are intentionally dim — the tint sits BEHIND
/// source text, and a saturated background would crush
/// foreground colours. Hardcoded for v1; future theme
/// integration routes through `DiffAdd` / `DiffChange` /
/// `DiffRemove` theme entries (deferred to the theme
/// expansion slice).
fn diff_tint_bg(
    view: &FrameView<'_>,
    buffer_id: crate::buffers::BufferId,
    line_idx: u32,
) -> Option<Color> {
    use lattice_host::diff::overlay::DiffSignKind;
    let rs = view.app.render_state.load();
    // D-fix.3b: tint each pane from ITS buffer's sign map (per-pane), so a
    // side-by-side diff colours BOTH sides — baseline (left) shows
    // removed/changed, proposed (right) shows added/changed. Colours resolve
    // from the active theme.
    let sign_map = rs.diff.sign_maps.get(&buffer_id)?;
    match sign_map.sign_at(line_idx)? {
        // D.3.b.3: read tint colours from the theme.
        DiffSignKind::Add => Some(view.app.theme.diff_add_line_bg),
        DiffSignKind::Change => Some(view.app.theme.diff_change_line_bg),
        // D-fix.3b: the baseline pane's removed lines tint red (was None —
        // only the current side was ever shown before pane-group tints).
        DiffSignKind::Remove => Some(view.app.theme.diff_remove_line_bg),
        // D.6.f (2026-05-31): three-way Conflict gets its
        // own tint so a 30-row file with one conflict block
        // is readable at a glance.
        DiffSignKind::Conflict => Some(view.app.theme.diff_conflict_line_bg),
    }
}

/// MC.3: full-width background for a line inside a fenced/indented code block.
/// Reads the per-buffer code-block line set from the render-state snapshot
/// (sorted, so `binary_search` is O(log n)) and returns the resolved
/// `syntax.code_block` background for `line_idx`, or `None` when the line is
/// not in a code block. Painted via [`apply_diff_tint`] like the diff tint.
fn code_block_tint_bg(
    view: &FrameView<'_>,
    buffer_id: crate::buffers::BufferId,
    line_idx: u32,
) -> Option<Color> {
    let rs = view.app.render_state.load();
    let lines = rs.code_block_lines.get(&buffer_id)?;
    lines.binary_search(&line_idx).ok()?;
    Some(view.app.theme.code_block_bg)
}

/// D.3.e: layer a background tint over every span in
/// `spans`, preserving each span's foreground colour and
/// modifiers. Used to apply diff-line backgrounds on top of
/// syntax-highlighted source content.
fn apply_diff_tint(spans: Vec<Span<'static>>, bg: Color) -> Vec<Span<'static>> {
    spans
        .into_iter()
        .map(|s| {
            // A span that already carries its OWN background keeps it.
            //
            // This function used to set `bg` unconditionally, and the
            // row tint is applied last — so it erased every narrower
            // background underneath it. Intra-line diff refinement was
            // the visible casualty: it computed correctly, reached the
            // run, and was painted onto the style, and then this
            // overwrote it one step later. `cells_render`'s
            // `display_run_to_style` states the contract this broke —
            // "a refined run overrides its row's diff tint with a
            // stronger one".
            //
            // The rule generalises rather than special-casing
            // refinement: the row tint is the WIDER, weaker statement
            // ("this line changed"); anything that painted a narrower
            // background — refinement, a search match, the visual
            // selection — is the more specific one and wins. Every
            // comparable editor resolves it that way, and a selection
            // that vanishes because it happens to fall on a diff line
            // is the same bug wearing different clothes.
            let new_style = if s.style.bg.is_some() {
                s.style
            } else {
                s.style.bg(bg)
            };
            Span::styled(s.content.into_owned(), new_style)
        })
        .collect()
}

/// T.7 (2026-07-22): compilation location tint. Reads the
/// per-buffer location-line index from the render-state snapshot and
/// returns `(path_byte_start, path_byte_end, bg, fg)` for `line_idx`
/// if it carries a file-location link.
fn compilation_location_tint(
    view: &FrameView<'_>,
    buffer_id: crate::buffers::BufferId,
    line_idx: u32,
) -> Option<(u32, u32, Color, Color)> {
    let rs = view.app.render_state.load();
    let entries = rs.compilation_location_lines.get(&buffer_id)?;
    let entry = entries.iter().find(|(l, _, _)| *l == line_idx)?;
    let (bg, fg) = *rs.compilation_theme_colors;
    let bg = Color::Rgb(
        (bg >> 16) as u8,
        ((bg >> 8) & 0xff) as u8,
        (bg & 0xff) as u8,
    );
    let fg = Color::Rgb(
        (fg >> 16) as u8,
        ((fg >> 8) & 0xff) as u8,
        (fg & 0xff) as u8,
    );
    Some((entry.1, entry.2, bg, fg))
}

/// Apply compilation location link tint: set the background tint on
/// every span, and set the link foreground on spans whose byte range
/// overlaps `[path_byte_start, path_byte_end)`.
fn apply_compilation_location_tint(
    spans: Vec<Span<'static>>,
    path_byte_start: u32,
    path_byte_end: u32,
    bg: Color,
    fg: Color,
) -> Vec<Span<'static>> {
    let mut byte_pos: usize = 0;
    spans
        .into_iter()
        .map(|s| {
            let span_len = s.content.len();
            let span_end = byte_pos + span_len;
            let inside_link =
                byte_pos < path_byte_end as usize && span_end > path_byte_start as usize;
            let style = s.style.bg(bg);
            let style = if inside_link { style.fg(fg) } else { style };
            byte_pos = span_end;
            Span::styled(s.content.into_owned(), style)
        })
        .collect()
}

/// SG.4b — the cell for one gutter column on one line.
///
/// `sign` is that column's winning placement from the decoration pre-loop, or
/// `None` for a line nothing marked. There is exactly ONE of these now: the
/// separate `render_diagnostic_severity_cell` and `render_diff_sign_cell`
/// paths are gone, because a diagnostic and a hunk mark are signs whose
/// definitions carry their glyph, their theme element and their column. This
/// function cannot tell them apart and does not need to.
///
/// A retired id paints a BLANK: SG.1 retires ids rather than reusing them so
/// that a placement produced before an `undefine` paints nothing, where a
/// reused slot would have painted some later sign's glyph. A blank cell is a
/// visible absence; the wrong glyph is a lie.
fn render_sign_cell(sign: Option<lattice_mode::SignId>, view: &FrameView<'_>) -> Span<'static> {
    let blank = Span::styled(" ".to_string(), TuiStyle::default());
    let Some(sign) = sign else {
        return blank;
    };
    let rs = view.app.render_state.load();
    let Some(def) = rs.signs.registry.get(sign) else {
        return blank;
    };
    // The theme decides the COLOUR, the font capability decides the GLYPH.
    // Both palettes are the same cell width by the icon-degradation rule, so
    // toggling `ui.nerd_fonts` cannot shift the gutter's geometry.
    let glyph = def.glyph_char(view.app.theme.nerd_fonts).to_string();
    // An unregistered element falls back to `gutter.sign` rather than to no
    // style: a sign was placed to tell the user something, and painting it
    // invisibly is the one outcome that loses the information entirely
    // rather than merely showing it in the wrong tone.
    let element = rs
        .signs
        .elements
        .get(&sign)
        .copied()
        .unwrap_or(rs.theme_ids.gutter_sign);
    let style = rs
        .resolved_theme
        .get(element)
        .fg
        .map(crate::theme::host_color_to_ratatui)
        .map(|c| TuiStyle::default().fg(c))
        .unwrap_or_default();
    Span::styled(glyph, style)
}

/// Diagnostics that overlap `line_idx` of `buffer_id`. Used by the
/// inline-underline overlay. Gated on `lsp-mode` (M.5.6); the
/// diagnostics layer keeps storing data when the mode is off, but
/// the renderer pretends none exist.
///
/// DR.3: takes `buffer_id` (was the active `_snap`) so inactive panes
/// underline their OWN buffer's diagnostics; the active pane passes
/// its own id (byte-identical).
pub(crate) fn diagnostics_on_line(
    view: &FrameView<'_>,
    buffer_id: crate::buffers::BufferId,
    line_idx: u32,
) -> Vec<LspDiagnostic> {
    // Slice 3c.extension.fold-rs: gate on the cached
    // `view.lsp_diagnostics_enabled` instead of the prior
    // per-line `app.lsp_diagnostics_mode_enabled_for(...)`
    // actor RPC.
    if !view.lsp_diagnostics_enabled {
        return Vec::new();
    }
    let app = view.app;
    let Some(uri) = app.buffer_uri(buffer_id) else {
        return Vec::new();
    };
    // Slice 3c.final.B.8: read via the already-published
    // `diagnostics.layer` sub-state — wait-free against the
    // supervisor's `ArcSwap`-backed snapshot. No actor round-trip.
    app.render_state
        .load()
        .diagnostics
        .layer
        .diagnostics_on_line(&uri, line_idx)
}

/// M.7.3.b parameter bundle for the whitespace-decoration
/// pre-pass. Per-glyph `Option<char>` -- `None` ⇒ category
/// disabled. `style_normal` covers tab / leading / mid-text
/// space / EOL; `style_trailing` covers trailing whitespace
/// (separated because trailing is a lint signal where the
/// others are structural).
#[derive(Debug, Clone, Copy)]
pub(crate) struct WhitespaceDecoration {
    pub tab: Option<char>,
    pub trailing: Option<char>,
    pub leading: Option<char>,
    pub space: Option<char>,
    pub eol: Option<char>,
    pub style_normal: TuiStyle,
    pub style_trailing: TuiStyle,
}

impl WhitespaceDecoration {
    /// Build from app + theme. Used at every render-line call
    /// site that wants whitespace decoration applied -- gating
    /// on `app.editor.option_cache.show_whitespace` is the caller's
    /// responsibility.
    fn from_app(app: &App) -> Self {
        // Slice 3c.final.B (group 2): read whitespace glyphs via
        // `app.ad().option_cache` (published mirror of
        // `editor.option_cache`).
        let oc = app.ad().option_cache;
        Self {
            tab: oc.whitespace_tab,
            trailing: oc.whitespace_trailing,
            leading: oc.whitespace_leading,
            space: oc.whitespace_space,
            eol: oc.whitespace_eol,
            style_normal: app.theme.whitespace_style,
            style_trailing: app.theme.whitespace_trailing_style,
        }
    }

    /// Quick-test path: every glyph disabled ⇒ no work to do.
    /// Lets callers skip the post-pass walk when the user has
    /// turned `whitespace-show-mode` on but configured every
    /// category to empty (degenerate, but free to handle).
    fn is_noop(&self) -> bool {
        self.tab.is_none()
            && self.trailing.is_none()
            && self.leading.is_none()
            && self.space.is_none()
            && self.eol.is_none()
    }
}

/// Classify a single character + its byte-offset within the
/// line, returning the `(glyph, style)` substitution if any
/// category fires. Precedence: trailing > tab > leading > space.
/// Returns `None` to leave the character unchanged.
fn classify_whitespace(
    ch: char,
    pos: usize,
    first_non_ws: usize,
    trailing_start: usize,
    d: &WhitespaceDecoration,
) -> Option<(char, TuiStyle)> {
    // Trailing wins: every whitespace byte in `[trailing_start,
    // line.len())` becomes trailing-marked.
    if pos >= trailing_start
        && (ch == ' ' || ch == '\t')
        && let Some(g) = d.trailing
    {
        return Some((g, d.style_trailing));
    }
    if ch == '\t' {
        // Tabs anywhere except in the trailing zone (handled
        // above) get the tab glyph.
        return d.tab.map(|g| (g, d.style_normal));
    }
    if ch == ' ' {
        if pos < first_non_ws {
            // Leading non-tab whitespace; emacs's `indentation`.
            if let Some(g) = d.leading {
                return Some((g, d.style_normal));
            }
        } else if pos < trailing_start {
            // Mid-text space; emacs's `space-mark`.
            if let Some(g) = d.space {
                return Some((g, d.style_normal));
            }
        }
    }
    None
}

/// Apply whitespace-glyph substitution to a vector of styled
/// spans. Walks every char, classifies it via
/// [`classify_whitespace`], emits glyph-substituted spans where
/// categories fire and keeps original content otherwise. The
/// EOL glyph (if configured) appends as a final span after all
/// content. Output spans are width-equivalent to input spans
/// (one char in, one char out for substitutions).
///
/// The caller passes the original line text (unsubstituted)
/// for whitespace position classification -- spans hold byte
/// substrings of `line`, so byte-position tracking across spans
/// stays consistent with the original.
pub(crate) fn apply_whitespace_decoration(
    spans: Vec<Span<'static>>,
    line: &str,
    d: &WhitespaceDecoration,
) -> Vec<Span<'static>> {
    if d.is_noop() {
        return spans;
    }
    let bytes = line.as_bytes();
    let first_non_ws = bytes
        .iter()
        .position(|b| !b.is_ascii_whitespace())
        .unwrap_or(bytes.len());
    let trailing_start = bytes
        .iter()
        .rposition(|b| !b.is_ascii_whitespace())
        .map(|i| i + 1)
        .unwrap_or(0);

    let mut out: Vec<Span<'static>> = Vec::with_capacity(spans.len());
    let mut pos = 0usize;
    for span in spans {
        let span_style = span.style;
        let content = span.content.into_owned();
        let mut accum = String::new();
        for ch in content.chars() {
            let ch_len = ch.len_utf8();
            match classify_whitespace(ch, pos, first_non_ws, trailing_start, d) {
                Some((glyph, style)) => {
                    if !accum.is_empty() {
                        out.push(Span::styled(std::mem::take(&mut accum), span_style));
                    }
                    let mut g = String::new();
                    g.push(glyph);
                    out.push(Span::styled(g, style));
                }
                None => accum.push(ch),
            }
            pos += ch_len;
        }
        if !accum.is_empty() {
            out.push(Span::styled(accum, span_style));
        }
    }
    if let Some(eol_glyph) = d.eol {
        let mut g = String::new();
        g.push(eol_glyph);
        out.push(Span::styled(g, d.style_normal));
    }
    out
}

/// IG.3: the resolved indentation-guide paint state for one pane, for one
/// frame.
///
/// Built once per pane per frame — the glyph and both styles are constant
/// across the viewport, and the active block is picked from the cursor row
/// the pane already holds. That pick is the reason the worker publishes block
/// *extents* rather than a precomputed "is active" flag: moving the cursor
/// restyles one column here, and costs the worker nothing.
pub(crate) struct IndentGuideStyle {
    /// `None` ⇒ paint nothing (guides off, or the glyph set to empty).
    glyph: Option<char>,
    normal: TuiStyle,
    active: TuiStyle,
    /// Index into the layer's `blocks`, or `None` when the cursor is at
    /// top level or `display.indent-guides.active` is off.
    active_block: Option<u16>,
}

impl IndentGuideStyle {
    pub(crate) fn resolve(
        app: &crate::app::App,
        guides: &lattice_host::indent_guides::IndentGuides,
        cursor_line: u32,
        resolved: &lattice_host::ui::theme::ResolvedTheme,
        ids: &lattice_host::ui::theme::BuiltinElementIds,
    ) -> Self {
        let oc = &app.ad().option_cache;
        let to_style = |e: lattice_host::ui::theme::ElementId| {
            let st = resolved.get(e);
            let mut out = TuiStyle::default();
            if let Some(fg) = st.fg {
                out = out.fg(crate::cells_render::rgb_u32_to_color(fg.to_rgb_u32(0)));
            }
            if st.modifiers.dim {
                out = out.add_modifier(Modifier::DIM);
            }
            out
        };
        Self {
            glyph: oc.indent_guide_char,
            normal: to_style(ids.indent_guide),
            active: to_style(ids.indent_guide_active),
            active_block: if oc.indent_guide_active {
                guides.active_block(cursor_line)
            } else {
                None
            },
        }
    }

    fn style_for(&self, block: u16) -> TuiStyle {
        if self.active_block == Some(block) {
            self.active
        } else {
            self.normal
        }
    }
}

/// Substitute the guide glyph into every column the worker marked.
///
/// Runs AFTER the horizontal clip, so `marks` (absolute display columns) are
/// translated by `leftcol` and dropped outside `[leftcol, leftcol + width)`.
/// The clip measures in bytes — see the call site — so substituting a
/// three-byte glyph before it would shorten the line; doing it after means the
/// pass and the user see the same columns.
///
/// No "is this column blank" check: the worker applies
/// [`lattice_core::indent_blocks::IndentBlock::paints_on`] before publishing,
/// so a mark is only ever emitted for a column that holds a space.
/// Re-deriving that here would be a second implementation of the rule, and
/// the one that disagreed would be the one painting over code.
///
/// Where a guide and a `:set list` leading-whitespace marker want the same
/// cell, the guide wins — it carries structure, the marker only says "space".
pub(crate) fn apply_indent_guides(
    spans: Vec<Span<'static>>,
    marks: &[lattice_host::indent_guides::GuideMark],
    style: &IndentGuideStyle,
    leftcol: u32,
    width: u32,
) -> Vec<Span<'static>> {
    let Some(glyph) = style.glyph else {
        return spans;
    };
    if marks.is_empty() {
        return spans;
    }
    // Body-local columns. `width` is `u32::MAX` under soft wrap, where the
    // body is deliberately left unclipped for the segmenter.
    let visible = |m: &lattice_host::indent_guides::GuideMark| -> Option<u32> {
        let col = (m.col as u32).checked_sub(leftcol)?;
        (col < width).then_some(col)
    };
    let mut out: Vec<Span<'static>> = Vec::with_capacity(spans.len() + marks.len() * 2);
    let mut col: u32 = 0;
    let mut next = 0usize;
    for span in spans {
        let span_style = span.style;
        let content = span.content.into_owned();
        let mut accum = String::new();
        for ch in content.chars() {
            // Marks arrive in ascending column order per row, so one forward
            // cursor covers the walk. Marks scrolled off the left are skipped
            // by the same step.
            while next < marks.len() && visible(&marks[next]).is_none_or(|c| c < col) {
                next += 1;
            }
            if next < marks.len() && visible(&marks[next]) == Some(col) {
                if !accum.is_empty() {
                    out.push(Span::styled(std::mem::take(&mut accum), span_style));
                }
                out.push(Span::styled(
                    glyph.to_string(),
                    style.style_for(marks[next].block),
                ));
                next += 1;
            } else {
                accum.push(ch);
            }
            col = col.saturating_add(1);
        }
        if !accum.is_empty() {
            out.push(Span::styled(accum, span_style));
        }
    }
    // Guides past the end of the rendered body. Only a blank row can reach
    // here: `paints_on` requires the column to be left of where the line's
    // text starts, so a line with content is always long enough to hold its
    // own guides. Padding a blank row is what carries a guide through the
    // blank lines inside a block.
    for mark in &marks[next..] {
        let Some(target) = visible(mark) else {
            continue;
        };
        if target < col {
            continue;
        }
        if target > col {
            out.push(Span::raw(" ".repeat((target - col) as usize)));
            col = target;
        }
        out.push(Span::styled(glyph.to_string(), style.style_for(mark.block)));
        col = col.saturating_add(1);
    }
    out
}

// DR.2 (decoration-retention): `render_styled_line` (the legacy
// `StyledSpan` → ratatui renderer for the inactive-pane span path) was
// retired. Both panes now render bodies from the `DisplayMatrix` via
// `cells_render::display_line_to_source_spans`; `truncate_spans_to_width`
// (below) is still shared by both paths.

/// Horizontal scroll (HS.1): drop the first `skip` display columns
/// from the body spans, then clip the remainder to `max_width`.
/// Byte-based, mirroring [`truncate_spans_to_width`]'s ASCII-width
/// model (the cells path feeds tab-/inlay-expanded text, so byte ≈
/// column for the common case; non-ASCII width is punted there too).
/// `skip == 0` is exactly `truncate_spans_to_width`.
fn clip_spans_horizontally(
    spans: Vec<Span<'static>>,
    skip: u32,
    max_width: u32,
) -> Vec<Span<'static>> {
    if skip == 0 {
        return truncate_spans_to_width(spans, max_width);
    }
    let mut remaining = skip as usize;
    let mut kept: Vec<Span<'static>> = Vec::with_capacity(spans.len());
    for span in spans {
        if remaining == 0 {
            kept.push(span);
            continue;
        }
        let s = span.content.as_ref();
        let len = s.len();
        if len <= remaining {
            remaining -= len;
        } else {
            // Drop `remaining` bytes from the front; land on a char
            // boundary so the retained tail is valid UTF-8.
            let mut cut = remaining;
            while cut < len && !s.is_char_boundary(cut) {
                cut += 1;
            }
            kept.push(Span::styled(s[cut..].to_string(), span.style));
            remaining = 0;
        }
    }
    truncate_spans_to_width(kept, max_width)
}

fn truncate_spans_to_width(spans: Vec<Span<'static>>, max_width: u32) -> Vec<Span<'static>> {
    // Naive byte-based truncation. Adequate for ASCII; non-ASCII display
    // width is a real problem we punt on until we own a width-aware shaping
    // path (Phase 9 / rich-buffer).
    let mut out = Vec::with_capacity(spans.len());
    let mut budget = max_width as usize;
    for span in spans {
        if budget == 0 {
            break;
        }
        let s = span.content.as_ref().to_string();
        if s.len() <= budget {
            budget -= s.len();
            out.push(Span::styled(s, span.style));
        } else {
            let cut = s
                .char_indices()
                .map(|(i, _)| i)
                .take_while(|i| *i <= budget)
                .last()
                .unwrap_or(0);
            out.push(Span::styled(s[..cut].to_string(), span.style));
            break;
        }
    }
    out
}

fn empty_marker_line(gutter_w: u32) -> Line<'static> {
    // Treat the `~` like a pseudo line-number label so its column
    // alignment matches `render_gutter`'s numbered output: leading
    // pad + `~` + GUTTER_TRAILING_PAD.
    // Prepended one-cell severity column blank (Phase 4.1.d.iii)
    // so the `~` lines align with body lines below the document.
    let cell = format_gutter_cell("~", gutter_w, None);
    Line::from(vec![
        Span::styled(" ".to_string(), TuiStyle::default()),
        Span::styled(cell, TuiStyle::default().fg(Color::DarkGray)),
    ])
}

/// Like [`combine_prefixed`] but accepts a multi-span prefix -- used by
/// the LSP diagnostic gutter where the leading severity cell
/// has its own per-severity style and can't share a span with
/// the line-number gutter (which is always dim-darkgray).
fn combine_prefixed(
    prefix: Vec<Span<'static>>,
    gutter: Vec<Span<'static>>,
    mut body: Vec<Span<'static>>,
) -> Line<'static> {
    let mut all = Vec::with_capacity(prefix.len() + gutter.len() + body.len());
    all.extend(prefix);
    all.extend(gutter);
    all.append(&mut body);
    Line::from(all)
}

/// Apply an underline overlay over a byte range of a line's
/// existing styled spans. Unlike [`apply_match_overlay`], this
/// PRESERVES the underlying span's foreground / background and
/// only ADDs the `UNDERLINED` modifier. Used for inline LSP
/// diagnostic decoration.
///
/// Why no underline-colour: setting an explicit underline colour
/// emits the SGR 58 / 59 extension codes (`\x1b[58:5:Nm` /
/// `\x1b[59m`). They're widely supported but not universally;
/// terminals that don't recognise them have produced
/// reproducible visual breakage where text on lines following
/// the diagnostic line rendered as if `fg = Color::Black` --
/// the parameters of the unrecognised sequence get swallowed
/// into subsequent SGR state and pin the foreground to a value
/// the user perceives as "the next several lines went black"
/// (the severity colour belongs in the gutter glyph; the body
/// underline is enough signal). Symptom cleared as soon as the
/// flagged line scrolled past the viewport. The severity-cell
/// gutter still carries the per-severity colour, so the user
/// sees which kind of diagnostic is on the line.
/// S3.c.3 (2026-05-26): visibility bumped to `pub(crate)` so
/// `cells_render::tests` can validate the overlay walks cell-
/// derived spans correctly.
pub(crate) fn apply_underline_overlay(
    spans: Vec<Span<'static>>,
    overlay_start: usize,
    overlay_end: usize,
    _severity_color: Color,
) -> Vec<Span<'static>> {
    let mut out: Vec<Span<'static>> = Vec::with_capacity(spans.len() + 2);
    let mut cursor = 0usize;
    for span in spans {
        let s = span.content.as_ref().to_string();
        let span_start = cursor;
        let span_end = cursor + s.len();
        let overlap_start = span_start.max(overlay_start);
        let overlap_end = span_end.min(overlay_end);
        if overlap_start >= overlap_end {
            out.push(Span::styled(s, span.style));
        } else {
            if overlap_start > span_start {
                let pre = s[..overlap_start - span_start].to_string();
                out.push(Span::styled(pre, span.style));
            }
            let mid = s[overlap_start - span_start..overlap_end - span_start].to_string();
            let mid_style = span.style.add_modifier(Modifier::UNDERLINED);
            out.push(Span::styled(mid, mid_style));
            if overlap_end < span_end {
                let post = s[overlap_end - span_start..].to_string();
                out.push(Span::styled(post, span.style));
            }
        }
        cursor = span_end;
    }
    out
}

/// Number of buffer lines collapsed onto the visible head row of
/// `fold`. Thin wrapper over the shared [`lattice_host::folds::
/// folded_line_span`] so the TUI and GPUI renderers report identical
/// counts (see that function for the abut-vs-overlap chaining rule).
fn closed_fold_display_span(
    view: &FrameView<'_>,
    snap: &DocumentSnapshot,
    fold: &crate::app::Fold,
) -> u32 {
    lattice_host::folds::folded_line_span(
        view.folds.as_ref(),
        fold.start_line,
        fold.end_line,
        snap.buffer.content_line_count(),
    )
}

/// Translate a buffer line into the corresponding visible row index
/// in the active pane, accounting for closed folds. Walks the same
/// "skip closed-fold interior" algorithm `compose_visible_lines`
/// uses to build the visible-line list.
///
/// If `target` is hidden by a closed fold, the result is the row
/// where that fold's heading renders -- so the cursor projection
/// always lands on a line the user can see.
///
/// Returns `None` when the resulting row is past `viewport_height`
/// (the cursor is below the visible window) or before scroll.
/// Map a buffer line to the visible row inside a pane viewport,
/// taking closed folds into account. `scroll` is the pane's
/// top-of-viewport buffer line -- usually `app.editor.scroll`, but the
/// popup-anchor path passes the active pane's stashed doc scroll
/// (State B) where the doc isn't the active buffer.
fn buffer_line_to_visible_row_with(
    view: &FrameView<'_>,
    snap: &DocumentSnapshot,
    target: u32,
    viewport_height: u32,
    scroll: u32,
    // W.4.t cursor-fix: columns a wrapped line is broken at, or `0`
    // when `:set wrap` is off. Each doc line then contributes
    // `segment_count` display rows (not 1) to the walk, so the
    // cursor row stays correct when a wrapped line sits above it.
    // Composes with the existing virtual-row + fold accounting:
    // every kind of virtual textual height is summed here, matching
    // what `compose_visible_lines_inner` paints.
    wrap_width: u32,
    // PIC.1: the pane whose matrices the walk must read — the caret
    // must sum wrap-segment / virtual-row heights from the SAME pane
    // the body + cursorline compose from (`compose_pane_lines`'s
    // `ctx.pane_id`). For the active document pane this is
    // `tree.active().id` (byte-identical to the top-level matrix); for
    // a focused popup it is `PaneId::POPUP`, whose help-buffer line
    // widths differ from the background document's — reading the wrong
    // pane compounds a per-line wrap error and drifts the caret.
    pane_id: lattice_core::ui::pane::PaneId,
) -> Option<u32> {
    if target < scroll {
        return None;
    }
    // B2.4: per-line display width from the canonical `DisplayMatrix`
    // (tab-expanded col_count == what the renderer paints). Stale /
    // missing rows fall back to the rope line's char count.
    // PIC.1: read THIS pane's matrix (keyed by `pane_id`), matching
    // `compose_pane_lines`'s body/cursorline source. For the active
    // document pane this entry is byte-identical to the top-level
    // `cells.display_matrix`; for `PaneId::POPUP` it is the popup
    // buffer's matrix, so the caret walks the same wrap widths the
    // popup body paints.
    let cells_rs = view.app.render_state.load().cells.load_full();
    let display_matrix = cells_rs
        .display_matrix_for_pane(pane_id)
        .map(|cell| cell.load_full())
        .unwrap_or_else(|| {
            std::sync::Arc::new(lattice_host::display_matrix::DisplayMatrix::empty())
        });
    let segment_rows = |line: u32| -> u32 {
        if wrap_width == 0 {
            return 1;
        }
        let width = display_matrix
            .row_at_source_line(line)
            .map(|r| r.col_count)
            .unwrap_or_else(|| {
                snap.buffer
                    .line(line)
                    .map(|s| s.chars().count() as u32)
                    .unwrap_or(0)
            });
        lattice_cells::wrap_segments(width, wrap_width)
    };
    // D.3.b.1.cursor-fix (2026-05-29): account for virtual
    // rows the renderer interleaves between document rows.
    // Without this, the cursor was painted at the doc-row
    // count past scroll — which is the position the line
    // WOULD occupy if there were no virtual rows in between.
    // After D.3.b.1's interleaver added Above- and Below-
    // anchored virtual rows around each doc row, the cursor
    // visually landed on the wrong row whenever a deletion
    // block sat between the scroll and the cursor.
    //
    // K.4.6 c.ii (2026-06-02, FIXED 2026-06-02): per-pane matrix
    // lookup, no boot-seeded fallback. Same fix as
    // compose_visible_lines_inner.
    let virtual_rows_matrix = {
        let rs = view.app.render_state.load();
        rs.virtual_rows
            .matrix_for_pane(pane_id)
            .map(|cell| cell.load_full())
            .unwrap_or_else(|| std::sync::Arc::new(lattice_cells::VirtualRowMatrix::empty()))
    };
    let total_lines = snap.buffer.content_line_count();
    let mut buf_line = scroll;
    let mut row: u32 = 0;
    while row < viewport_height && buf_line < total_lines {
        // Above-anchored virtual rows at buf_line render
        // BEFORE the doc row, so they shift `row` by their
        // count when walking past this position.
        let above_count = virtual_rows_at(
            &virtual_rows_matrix,
            buf_line,
            lattice_cells::AnchorPosition::Above,
        )
        .count() as u32;
        row += above_count;
        if row >= viewport_height {
            return None;
        }
        // If a closed fold starts at buf_line, the fold's whole
        // range collapses onto this single visible row. The cursor
        // resolves to this row whether it's at the fold heading or
        // anywhere in the hidden body.
        let fold_at = view.fold_start_at(buf_line);
        let next_buf_line = match fold_at {
            Some(fold) => fold.end_line + 1,
            None => buf_line + 1,
        };
        let covers_target = match fold_at {
            Some(fold) => target >= fold.start_line && target <= fold.end_line,
            None => target == buf_line,
        };
        if covers_target {
            return Some(row);
        }
        if buf_line == target {
            // Defensive: the line wasn't claimed above (no fold,
            // not equal); should be unreachable, but return the
            // current row rather than None so the cursor still
            // shows somewhere sensible.
            return Some(row);
        }
        if view.line_inside_closed_fold(buf_line) {
            // Hidden interior line -- not the start of any fold but
            // still part of one (the renderer skips it). Don't
            // increment row; just advance buf_line.
            buf_line += 1;
            continue;
        }
        // Below-anchored virtual rows of buf_line render
        // AFTER the doc row, before the next doc row.
        let below_count = virtual_rows_at(
            &virtual_rows_matrix,
            buf_line,
            lattice_cells::AnchorPosition::Below,
        )
        .count() as u32;
        row += below_count;
        // W.4.t: the doc line occupies `segment_count` display rows
        // under wrap (1 when wrap is off), not a flat 1.
        row += segment_rows(buf_line);
        buf_line = next_buf_line;
    }
    None
}

#[allow(dead_code)]
fn cursor_screen_position(
    view: &FrameView<'_>,
    snap: &DocumentSnapshot,
    area: Rect,
) -> Option<(u16, u16)> {
    cursor_screen_position_at(
        view,
        snap,
        area,
        view.app.ad().cursor,
        view.app.ad().scroll,
        view.app.panes().tree.active().id,
    )
}

/// Same as [`cursor_screen_position`] but with explicit `cursor`
/// and `scroll`. Used by the help-popup tooltip-anchor path where
/// the document's cursor / scroll live in the active pane's stash
/// (State B), not on `app.editor.cursor` / `app.editor.scroll` (which hold the
/// help buffer's). Folds are document-state and read straight off
/// `app`, which is correct for both states.
fn cursor_screen_position_at(
    view: &FrameView<'_>,
    snap: &DocumentSnapshot,
    area: Rect,
    cursor: lattice_protocol::Position,
    scroll: u32,
    // PIC.1: the pane whose matrices back the caret walk — see
    // `buffer_line_to_visible_row_with`. `tree.active().id` for the
    // active document caret; `PaneId::POPUP` for a focused popup.
    pane_id: lattice_core::ui::pane::PaneId,
) -> Option<(u16, u16)> {
    // Snapshot ad() once so wrap_lines, leftcol, and tabstop come
    // from the same atomic snapshot — without this the cursor
    // screen position and cursorline highlight can disagree when
    // the actor publishes between two independent app.ad() calls.
    let ad = view.app.ad();
    if cursor.line < scroll {
        return None;
    }
    // Map the buffer cursor line to the visible row taking closed
    // folds into account. If the cursor sits inside a closed fold's
    // hidden body, project it onto the fold's heading row -- the
    // user always sees the cursor on a real visible line, never
    // adrift inside collapsed content. This is the safety net for
    // any code path that sets `app.editor.cursor` without first running
    // `snap_cursor_past_closed_folds` (e.g. edits that shift line
    // numbers underneath an unchanged cursor).
    let total_lines = snap.buffer.content_line_count().max(1);
    let gutter_w = (if view.show_line_numbers {
        gutter_width(total_lines)
    } else {
        // Must match `compose_visible_lines_inner`'s `gutter_w` exactly —
        // see the note there. `2` put the caret one cell left of the
        // glyph on every `nonumber` buffer.
        GUTTER_TRAILING_PAD
    }) + view.content_left_pad; // DB.4: keep cursor col aligned with centring.
    // W.4.t: body content width = the columns a wrapped line is
    // broken at. Must match `compose_visible_lines_inner`'s
    // `buffer_w` exactly so the cursor row/col agree with what is
    // painted. `0` when `:set wrap` is off (no wrapping).
    //
    // Resolve wrap through `view.wrap_lines` — the SAME per-buffer
    // resolver (`App::wrap_lines_for`) the compose loop reads at
    // `wrap_on`. Reading the global `option_cache.wrap_lines` here
    // instead diverges the moment a buffer-local override exists:
    // help / popup buffers carry `wrap=off` from their mode (HP.3),
    // so with `:set wrap` on globally the body composed unwrapped
    // while the caret walk still split every line into segments,
    // drifting the caret off the cursorline. For the active document
    // pane the two resolve identically.
    let wrap_width = if view.wrap_lines {
        (area.width as u32)
            .saturating_sub(gutter_w)
            .saturating_sub(sign_columns_width(view))
            .max(1)
    } else {
        0
    };
    // Map the buffer cursor line to the visible row, accounting for
    // virtual rows + folds (existing) AND wrap-segment height
    // (W.4.t) of every line above it. This is the first display row
    // of the cursor's line; the cursor's own wrap segment is added
    // below from its display column.
    let row_in_view = buffer_line_to_visible_row_with(
        view,
        snap,
        cursor.line,
        area.height as u32,
        scroll,
        wrap_width,
        pane_id,
    )?;
    // `cursor.byte` is a UTF-8 byte offset into the line; the
    // terminal places glyphs by display width, not byte count. A
    // line containing `§` (2 bytes / 1 cell) or a CJK glyph (3
    // bytes / 2 cells) puts the cursor at the wrong column if we
    // use the byte offset directly. Compute the display width of
    // the prefix `line[..cursor.byte]` -- handles ASCII (1:1),
    // Latin-1 / Greek / Cyrillic (multi-byte but 1 cell), CJK and
    // emoji (1-4 bytes, 2 cells).
    //
    // 2026-05-26: LSP inlay hints render inline via
    // `splice_virtual_text_into_spans` (compose loop) but live
    // outside the source-byte axis. Cursor column has to add the
    // cumulative display width of every inlay on this line whose
    // anchor byte sits at-or-before `cursor.byte`, mirroring the
    // GPUI peer's `byte_to_combined_col` shift. Without it, `$`
    // (and every motion past an inlay) lands cells short of the
    // glyph it logically points at.
    let rs_st = view.app.render_state.load();
    let inlay_hints = &rs_st.syntax.inlay_hints;
    // Display column of the cursor within its (unwrapped) line —
    // tab-expanded + inlay-shifted.
    let display_col =
        display_col_for_byte(&snap.buffer, cursor, inlay_hints, ad.option_cache.tabstop);
    // W.4.t: split that column across wrap segments. The cursor's
    // own segment index (`display_col / wrap_width`) adds to the
    // row; the remainder (`display_col % wrap_width`) is the column
    // within the segment. This is the exact inverse of
    // `split_body_into_segments` (which breaks the body every
    // `wrap_width` columns), so it stays correct for a line that
    // wraps into any number of visual rows, not just two. Wrap off
    // (`wrap_width == 0`) ⇒ the whole column, no extra row.
    let (own_segment, body_col) = if wrap_width > 0 {
        (display_col / wrap_width, display_col % wrap_width)
    } else {
        (0, display_col)
    };
    // Sticky rows are emitted in a pre-pass before the scrollable
    // content (compose_pane_lines), so they occupy the first N screen
    // rows of the pane regardless of scroll. virtual_rows_at /
    // buffer_line_to_visible_row_with exclude sticky rows from their
    // counts (to avoid double-painting), so row_in_view is relative
    // to the *scrollable* region starting at sticky_count, not to the
    // pane top. Add sticky_count here so the terminal cursor lands on
    // the correct physical row.
    let sticky_count = {
        let rs = view.app.render_state.load();
        let matrix_rows = rs
            .virtual_rows
            .matrix_for_pane(pane_id)
            .map(|cell| cell.load_full().sticky_rows().count() as u32)
            .unwrap_or(0);
        // TC.3b: the context strip is emitted in the SAME pre-pass, after the
        // matrix's sticky rows, so it occupies physical rows too. Counting only
        // the matrix rows here drew the caret N rows above the cursorline —
        // the cursorline is painted as part of the composed row list, which
        // does include these, so the two disagreed by exactly the strip height.
        let context_rows = rs
            .cells
            .load()
            .sticky_context_for_pane(pane_id)
            .map(|cell| cell.load_full().rows.len() as u32)
            .unwrap_or(0);
        matrix_rows + context_rows
    };
    // Horizontal scroll (HS.1): shift the body column left by
    // `leftcol` so the cursor tracks the scrolled view. Wrap off
    // only — under wrap the host pins `leftcol = 0`. `saturating_sub`
    // guards the (transient) case where the cursor sits left of the
    // anchor before the next `ensure_cursor_horizontally_visible`.
    // Same per-buffer resolver as the compose loop's `leftcol_off`.
    let leftcol = if view.wrap_lines { 0 } else { ad.leftcol };
    let col = sign_columns_width(view) + gutter_w + body_col.saturating_sub(leftcol);
    let row = row_in_view
        .saturating_add(own_segment)
        .saturating_add(sticky_count);
    Some((
        area.x.saturating_add(col.try_into().unwrap_or(u16::MAX)),
        area.y.saturating_add(row.try_into().unwrap_or(u16::MAX)),
    ))
}

/// Display column (terminal cells) of `pos.byte` within
/// `pos.line`. Falls back to `pos.byte` when the line is missing
/// or the byte index lands past the line end (so the cursor still
/// renders at a sensible position rather than disappearing).
///
/// 2026-05-26: `inlay_hints` is the publish-time
/// `rs.syntax.inlay_hints` slice. Every hint on `pos.line` whose
/// anchor byte is `<= pos.byte` shifts the cursor by its label's
/// display width — the same accounting the compose loop applies
/// when it splices the inlay text into the row. Mirrors the GPUI
/// peer's `byte_to_combined_col` (the `inlay_offsets <= byte`
/// filter there). Pass an empty slice to skip the shift (the
/// pre-inlay behaviour).
fn display_col_for_byte(
    buffer: &lattice_core::Buffer,
    pos: lattice_protocol::Position,
    inlay_hints: &[lattice_host::render_state::InlayHintRow],
    tabstop: u32,
) -> u32 {
    use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};

    let line = match buffer.line(pos.line) {
        Some(s) => s,
        None => return pos.byte,
    };
    let byte = (pos.byte as usize).min(line.len());
    // Truncate to the prefix at a UTF-8 boundary. `is_char_boundary`
    // is true at index 0 and at every codepoint start; if the
    // caller happened to point inside a multi-byte char (motions
    // shouldn't, but guard anyway), step back to the previous
    // boundary so `&line[..byte]` is a valid str slice.
    let mut byte = byte;
    while byte > 0 && !line.is_char_boundary(byte) {
        byte -= 1;
    }
    // W.4.t: tab-aware prefix width. The cells builder expands each
    // `\t` to the next multiple of `tabstop` columns, so the cursor
    // must advance the same way (plain `UnicodeWidthStr` treats a
    // tab as ~0 and would land the cursor inside the expanded tab).
    let ts = tabstop.max(1);
    let mut base = 0u32;
    for ch in line[..byte].chars() {
        if ch == '\t' {
            base += ts - (base % ts);
        } else {
            base += UnicodeWidthChar::width(ch).unwrap_or(0) as u32;
        }
    }
    // Inlay shift: cumulative display width of every hint on
    // `pos.line` with `hint.byte <= cursor.byte`. The `<=`
    // matches the splice site (`splice_virtual_text_into_spans`
    // inserts BEFORE the char at `hint.byte`, so the cursor at
    // that same byte sits AFTER the inlay).
    let inlay_shift: u32 = inlay_hints
        .iter()
        .filter(|h| h.line == pos.line && (h.byte as usize) <= byte)
        .map(|h| UnicodeWidthStr::width(h.text.as_str()) as u32)
        .sum();
    base + inlay_shift
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic)]
    use super::*;
    use crate::app::App;
    use lattice_core::Document;

    // ── the row tint must not erase narrower backgrounds ──────────
    //
    // Live-reported: intra-line diff refinement was invisible in
    // magit-status. It computed correctly, survived the splice, reached
    // the run, and was painted onto the span style — and then the
    // row-level diff tint, applied last, overwrote every span's
    // background including that one. GPUI never had the bug because it
    // paints the tint as a quad BEHIND the text runs; the TUI flattens
    // both into one ratatui `Style`, so ordering decides it.

    use ratatui::style::{Color as RColor, Style as RStyle};
    use ratatui::text::Span as RSpan;

    /// TC.8: a virtual row that carries a source line shows it in the gutter,
    /// formatted EXACTLY like a document row's.
    ///
    /// Asserted against `render_gutter` rather than against a literal, because
    /// the property that matters is not "shows a number" but "occupies the
    /// same columns as the rows beneath it". A gutter one cell narrower puts
    /// the whole context strip out of alignment with the code it heads, which
    /// reads as a rendering bug rather than an off-by-one.
    #[test]
    fn a_virtual_row_with_a_source_line_paints_the_document_gutter() {
        for width in [4u32, 6, 9] {
            let mine = virtual_row_gutter_spans(Some(41), width, None);
            let theirs = render_gutter(41, width, None);
            let text = |v: &[RSpan<'static>]| -> String {
                v.iter().map(|s| s.content.to_string()).collect()
            };
            assert_eq!(
                text(&mine),
                text(&theirs),
                "width {width}: the context gutter must be the document gutter"
            );
            assert!(text(&mine).contains("42"), "1-based, like every gutter");
        }
    }

    /// Without a source line the gutter is blank — and blank at exactly the
    /// document width, which is what keeps deletion blocks and filler rows
    /// aligned today.
    #[test]
    fn a_virtual_row_without_a_source_line_paints_a_blank_gutter() {
        let spans = virtual_row_gutter_spans(None, 6, None);
        let text: String = spans.iter().map(|s| s.content.to_string()).collect();
        assert_eq!(text, " ".repeat(6));
        assert_eq!(
            text.chars().count(),
            render_gutter(0, 6, None)
                .iter()
                .map(|s| s.content.chars().count())
                .sum::<usize>(),
            "blank and numbered gutters are the same width, so toggling \
             `line-numbers` never shifts the strip"
        );
    }

    /// TC.11: the theme's `sticky.context.line_number` recolours the digits
    /// without changing their LAYOUT.
    ///
    /// Layout and colour are separated deliberately: `render_gutter` owns the
    /// columns (which must match the document gutter exactly, or the strip
    /// sits off from the code it heads) and the theme owns only the paint. A
    /// recolour that also reflowed would reintroduce the alignment bug the
    /// blank/numbered width tests exist to prevent.
    #[test]
    fn a_themed_gutter_colour_changes_paint_but_not_columns() {
        let plain = virtual_row_gutter_spans(Some(41), 6, None);
        let themed = virtual_row_gutter_spans(Some(41), 6, Some(0x00_ff_00));
        let text =
            |v: &[RSpan<'static>]| -> String { v.iter().map(|s| s.content.to_string()).collect() };
        assert_eq!(text(&plain), text(&themed), "same columns, same digits");
        assert!(
            themed
                .iter()
                .all(|s| s.style.fg == Some(RColor::Rgb(0, 0xff, 0))),
            "every span takes the themed colour"
        );
        assert!(
            plain
                .iter()
                .all(|s| s.style.fg != Some(RColor::Rgb(0, 0xff, 0))),
            "and without a theme colour it keeps the default"
        );
    }

    /// A span with no background of its own takes the row tint — the
    /// ordinary case, and the behaviour that must not change.
    #[test]
    fn the_row_tint_applies_where_there_is_no_background() {
        let body = vec![RSpan::styled(
            "let x = 1;",
            RStyle::default().fg(RColor::White),
        )];
        let tinted = apply_diff_tint(body, RColor::Rgb(60, 0, 0));
        assert_eq!(tinted[0].style.bg, Some(RColor::Rgb(60, 0, 0)));
        assert_eq!(
            tinted[0].style.fg,
            Some(RColor::White),
            "the tint never touches foreground"
        );
    }

    /// A span that already carries a background KEEPS it. This is the
    /// regression: refinement paints the narrower, stronger background,
    /// and the wider row tint must not win over it.
    #[test]
    fn the_row_tint_does_not_erase_an_existing_background() {
        let refine_bg = RColor::Rgb(0x6f, 0x00, 0x00);
        let body = vec![
            RSpan::styled("let ", RStyle::default().fg(RColor::White)),
            RSpan::styled("old", RStyle::default().fg(RColor::White).bg(refine_bg)),
            RSpan::styled(" = 1;", RStyle::default().fg(RColor::White)),
        ];
        let tinted = apply_diff_tint(body, RColor::Rgb(60, 0, 0));
        assert_eq!(
            tinted[1].style.bg,
            Some(refine_bg),
            "the refined span keeps its own background"
        );
        assert_eq!(
            tinted[0].style.bg,
            Some(RColor::Rgb(60, 0, 0)),
            "its unrefined neighbours still take the row tint"
        );
        assert_eq!(tinted[2].style.bg, Some(RColor::Rgb(60, 0, 0)));
    }

    /// The same rule protects a selection or search match that happens
    /// to fall on a diff line — previously the tint erased those too,
    /// which is the same defect wearing different clothes.
    #[test]
    fn a_selection_background_survives_the_row_tint() {
        let selection_bg = RColor::Rgb(0x30, 0x30, 0x60);
        let body = vec![RSpan::styled(
            "selected",
            RStyle::default().bg(selection_bg),
        )];
        let tinted = apply_diff_tint(body, RColor::Rgb(0, 50, 0));
        assert_eq!(tinted[0].style.bg, Some(selection_bg));
    }

    /// The row budget must equal the rows actually emitted.
    ///
    /// Live-reported against magit's file dispatch: the last group's
    /// items were off-screen and `<C-n>` would not bring them back.
    /// `transient_row_count` counted a header and the items per group
    /// but not the blank separator the walker emits, and BOTH the popup
    /// height and the scroll bound come off that number — so the box
    /// was short by one row per group and the scroll stopped before the
    /// bottom.
    ///
    /// Pinned as an identity rather than an arithmetic expectation:
    /// whatever the walker emits, the budget must say so, including
    /// when either side gains a row.
    /// A palette for the row-walking tests.
    ///
    /// These assert row COUNTS and which row carries the selection
    /// marker, not colours, so any palette works — but the walker takes
    /// one now, and a shared fixture keeps that from being restated at
    /// each call site.
    fn test_palette() -> TransientPalette {
        let plain = TuiStyle::default();
        TransientPalette {
            title: plain,
            group: plain,
            key: plain,
            key_inactive: plain,
            description: plain,
            value: plain,
            border: plain,
        }
    }

    #[test]
    fn a_transients_row_budget_matches_the_rows_it_emits() {
        use lattice_picker::{TransientGroup, TransientItem, TransientItemKind, TransientSpec};

        fn item(key: &str) -> TransientItem {
            TransientItem {
                key: vec![key.to_string()],
                label: key.to_string(),
                description: String::new(),
                kind: TransientItemKind::Dismiss,
            }
        }
        let spec = TransientSpec {
            title: "t".into(),
            groups: vec![
                TransientGroup {
                    label: "one".into(),
                    items: vec![item("a"), item("b")],
                },
                TransientGroup {
                    label: "two".into(),
                    items: vec![item("c")],
                },
                TransientGroup {
                    label: "three".into(),
                    items: vec![item("d"), item("e"), item("f")],
                },
            ],
            preview: None,
            footer: None,
        };

        let state = lattice_picker::TransientState::default();
        // A visible budget far past the end, so the walker emits
        // everything it has.
        let (lines, _) = transient_group_item_lines(&spec, &state, 0, 1000, 0, "", &test_palette());
        assert_eq!(
            transient_row_count(&spec),
            lines.len(),
            "the budget and the walker must agree, or the popup is sized \
             and scrolled against a number of rows that do not exist"
        );

        // And the consequence the user actually sees: with a window
        // shorter than the menu, the clamp must still reach the last
        // row.
        let visible = 5;
        let max_scroll = transient_row_count(&spec).saturating_sub(visible);
        let (tail, _) =
            transient_group_item_lines(&spec, &state, max_scroll, visible, 0, "", &test_palette());
        assert_eq!(
            tail.len(),
            visible,
            "scrolled to the clamp, the window must still be full — a \
             short count leaves rows below it unreachable"
        );
    }

    /// The selection must always be on screen, at every position and
    /// every window size — including the last item, which is what the
    /// overshoot bug made unreachable in practice.
    ///
    /// Asserted through the walker rather than against `scroll_for`'s
    /// arithmetic: what matters is that the marked row is among the
    /// emitted lines, which is what the user sees.
    #[test]
    fn the_selected_transient_row_is_always_inside_the_window() {
        use lattice_picker::{TransientGroup, TransientItem, TransientItemKind, TransientSpec};

        fn item(key: &str) -> TransientItem {
            TransientItem {
                key: vec![key.to_string()],
                label: format!("label-{key}"),
                description: String::new(),
                kind: TransientItemKind::Dismiss,
            }
        }
        let spec = TransientSpec {
            title: "t".into(),
            groups: vec![
                TransientGroup {
                    label: "one".into(),
                    items: vec![item("a"), item("b"), item("c")],
                },
                TransientGroup {
                    label: "two".into(),
                    items: vec![item("d"), item("e")],
                },
                TransientGroup {
                    label: "three".into(),
                    items: vec![item("f"), item("g")],
                },
            ],
            preview: None,
            footer: None,
        };
        let state = lattice_picker::TransientState::default();
        let labels = ["a", "b", "c", "d", "e", "f", "g"];

        for visible in [3usize, 5, 8, 40] {
            for (selected, key) in labels.iter().enumerate() {
                let scroll = spec.scroll_for(selected, visible);
                let (lines, _) = transient_group_item_lines(
                    &spec,
                    &state,
                    scroll,
                    visible,
                    selected,
                    "",
                    &test_palette(),
                );
                let rendered: Vec<String> = lines
                    .iter()
                    .map(|l| l.spans.iter().map(|s| s.content.as_ref()).collect())
                    .collect();
                let marked: Vec<&String> = rendered.iter().filter(|r| r.contains('❯')).collect();
                assert_eq!(
                    marked.len(),
                    1,
                    "exactly one row must be marked at selection {selected} \
                     with {visible} visible rows, got {rendered:?}"
                );
                assert!(
                    marked[0].contains(&format!("label-{key}")),
                    "the marked row must be the selected item ({key}): {marked:?}"
                );
            }
        }
    }

    /// PU.1b-3 regression (link styling): the FLOATING help popup must
    /// render its markdown/link styling end-to-end. `:describe-command`
    /// emits a source link and opens a focused (State B) popup. The popup
    /// content lives in the registry (help is never `activate_document`'d
    /// as `self.document`), so the synthetic `PaneId::POPUP` pane must
    /// source its snapshot from the registry handle — NOT `self.document`,
    /// which still points at the underlying buffer. We drive the cells
    /// worker for the popup pane, compose the popup interior the way
    /// `draw_help_overlay` does, and assert a span carries the resolved
    /// `Style::Link` style (not the unstyled plain-text fallback).
    #[test]
    fn floating_popup_composes_link_styling_end_to_end() {
        use lattice_core::ui::pane::PaneId;
        let mut a = App::new(Document::from_text("xx\n"));
        a.set_viewport_height(20);
        a.editor.set_command_line_text("describe-command ex:write");
        a.editor.modal = ModalState::Command;
        a.apply(crate::app::Action::CommandLineSubmit);
        let popup_id = a.editor.popup_buffer.expect("floating popup open");
        // Renderer normally feeds this from the runtime loop.
        a.editor.popup_viewport_height = 30;
        a.editor.popup_viewport_width = 100;
        a.editor.publish_render_state();
        // Drive the cells worker for the synthetic popup pane (sim async).
        let cells = a.editor.render_state.load().cells.load_full();
        let pop = cells
            .panes
            .iter()
            .find(|p| p.pane_id == PaneId::POPUP)
            .expect("synthetic popup pane present");
        let ct = lattice_host::cells_worker::CellTheme {
            resolved: &cells.resolved_theme,
            ids: &cells.theme_ids,
        };
        let _ = lattice_host::cells_worker::recompute_pane(pop, ct, &cells.whitespace);
        // Compose the popup interior the way draw_help_overlay does.
        let handle = a
            .buffers()
            .registry
            .document_handle(popup_id)
            .expect("popup buffer in registry");
        let snap = handle.snapshot();
        let view = FrameView::for_buffer(&a, popup_id);
        let ctx = PaneComposeCtx {
            is_active: true,
            pane_id: PaneId::POPUP,
            buffer_id: popup_id,
            cursor_line: a.ad().cursor.line,
            cursor_line_highlight: a.ad().option_cache.current_line_highlight,
            scroll: a.ad().scroll,
            leftcol: a.ad().leftcol,
            display_line_numbers: handle.display_line_numbers(),
        };
        let lines = compose_pane_lines(&view, &snap, 30, 100, &ctx);
        let link_style =
            crate::theme::host_style_to_ratatui(lattice_host::ui::theme::resolve_syntax_style(
                &cells.resolved_theme,
                &cells.theme_ids,
                lattice_syntax::Style::Link,
            ));
        let styled_link = lines
            .iter()
            .flat_map(|l| l.spans.iter())
            .any(|sp| sp.style == link_style && !sp.content.trim().is_empty());
        assert!(
            styled_link,
            "floating popup must render a span with the resolved Style::Link style \
             (got the unstyled plain-text fallback — link styling regressed)"
        );
    }

    /// PIC.1 regression: in a FOCUSED popup (State B) the terminal caret
    /// must land on the cursorline row. The popup body + cursorline
    /// compose from the `PaneId::POPUP` matrix, but the caret used to
    /// walk the background document's top-level matrix — so a wrapping
    /// line above the cursor drifted the caret below the cursorline
    /// (they coincide on line 0, diverge going down). Here popup line 0
    /// wraps into several segments while the background document's line 0
    /// is a single segment: the caret for popup line 1 must sit on the
    /// popup's cursorline row, NOT the (higher) row the document matrix
    /// would put it on.
    #[test]
    fn focused_popup_caret_row_matches_cursorline_row() {
        use lattice_core::ui::pane::PaneId;
        // Background document: line 0 is a single wrap segment.
        let mut a = App::new(Document::from_text("a\nb\nc\n"));
        a.set_viewport_height(20);
        // Focused popup whose line 0 is very wide (wraps into several
        // segments), followed by two short lines.
        let content = lattice_help::parse_help_lines(
            "t",
            vec!["x".repeat(200), "second".to_string(), "third".to_string()],
        );
        a.editor
            .open_popup(content, lattice_host::popup::PopupPlacement::Centered);
        let popup_id = a.editor.popup_buffer.expect("popup open");
        // Wrap on so the caret's wrap-width (from `ad().option_cache`)
        // matches the popup body's wrapping — isolates the matrix-source
        // fix (PIC.1) from the separate wrap-flag source question.
        a.editor.option_cache.wrap_lines = true;
        // Cursor onto popup line 1, below the wrap of line 0.
        a.editor.cursor = lattice_protocol::Position::new(1, 0);
        a.editor.popup_viewport_height = 20;
        a.editor.popup_viewport_width = 40;
        a.editor.publish_render_state();
        assert_eq!(
            a.ad().buffer_kind,
            crate::buffers::BufferKind::Help,
            "open_popup is State B (focused)"
        );
        // Drive the cells worker for the synthetic popup pane so its
        // DisplayMatrix is populated (sim async).
        let cells = a.editor.render_state.load().cells.load_full();
        let pop = cells
            .panes
            .iter()
            .find(|p| p.pane_id == PaneId::POPUP)
            .expect("synthetic popup pane present");
        let ct = lattice_host::cells_worker::CellTheme {
            resolved: &cells.resolved_theme,
            ids: &cells.theme_ids,
        };
        let _ = lattice_host::cells_worker::recompute_pane(pop, ct, &cells.whitespace);

        let handle = a
            .buffers()
            .registry
            .document_handle(popup_id)
            .expect("popup buffer in registry");
        let snap = handle.snapshot();
        let inner = Rect::new(0, 0, 40, 18);
        let view = FrameView::for_buffer(&a, popup_id);

        // Cursorline row: the cursor-line background is applied to every
        // wrap segment of line 1, so its FIRST row is line 1 segment 0 —
        // exactly where the caret (col 0) should land.
        let ctx = PaneComposeCtx {
            is_active: true,
            pane_id: PaneId::POPUP,
            buffer_id: popup_id,
            cursor_line: 1,
            cursor_line_highlight: true,
            scroll: 0,
            leftcol: 0,
            display_line_numbers: handle.display_line_numbers(),
        };
        let lines = compose_pane_lines(&view, &snap, inner.height as u32, inner.width as u32, &ctx);
        let cursor_line_bg = a.theme.cursor_line_bg;
        let cursorline_row = lines
            .iter()
            .position(|l| l.spans.iter().any(|s| s.style.bg == Some(cursor_line_bg)))
            .expect("cursorline row present");
        // HP.3 (`bb84a517`) gave help buffers `wrap=off` via their mode,
        // so the popup body composes line 0 as a SINGLE row even though
        // `:set wrap` is on globally — hence row 1, not row 6.
        assert_eq!(
            cursorline_row, 1,
            "help popups do not wrap (HP.3), so popup line 1 composes on row 1"
        );

        // ...and the caret must agree. This is the live bug HP.3 opened:
        // compose resolves wrap per-buffer (`view.wrap_lines` →
        // `App::wrap_lines_for`, which help-mode overrides to `off`) while
        // `cursor_screen_position_at` used to read the GLOBAL
        // `option_cache.wrap_lines`. With `:set wrap` on, the caret walk
        // split the 200-column line 0 into ~6 segments the composed body
        // never painted and placed the caret ~5 rows below the cursorline.
        // Both sides now read the one per-buffer resolver.
        let (_, caret_y) = cursor_screen_position_at(
            &view,
            &snap,
            inner,
            lattice_protocol::Position::new(1, 0),
            0,
            PaneId::POPUP,
        )
        .expect("caret placed");
        assert_eq!(
            caret_y as usize, cursorline_row,
            "focused-popup caret must land on the cursorline row"
        );

        // NOTE (PIC.1 coverage): this test used to also prove the caret
        // walks the POPUP pane's matrix rather than the background
        // document's, by making popup line 0 wrap while the document's
        // line 0 did not. HP.3 removed wrap from help popups, so that
        // construction is no longer reachable — with wrap off every line
        // is one row and the matrix source cannot change the row math.
        // If popup buffers ever wrap again, restore the wrapping-line
        // arm here; `buffer_line_to_visible_row_with`'s `pane_id`
        // argument is the thing under test.
    }

    /// A sticky headerline must not cost a document line. The host already
    /// reserves the sticky row in the scroll budget (`ensure_cursor_visible`'s
    /// `effective_height`), and the fill loop below the sticky pre-pass already
    /// caps at `height` — so shrinking `visible` on top of that deletes a real
    /// line. For a buffer whose last line is an editable prompt (the ACP
    /// conversation buffer) the deleted line is always the prompt.
    #[test]
    fn sticky_headerline_does_not_clip_the_last_document_line() {
        let mut a = app_with("alpha\nbravo\n> ", 6);
        a.editor.publish_render_state();
        let buffer_id = a.ad().document_buffer_id;

        let handle = lattice_cells::SimpleHeaderlineHandle::new((), |_: &()| {
            let cells: std::sync::Arc<[lattice_cells::Cell]> =
                vec![lattice_cells::Cell::new('H' as u32, 0xff_ff_ff, 0, 0)].into();
            Some(lattice_cells::HeaderlineRow { cells, bg: None })
        });
        a.editor
            .virtual_row_providers
            .register(buffer_id, std::sync::Arc::new(handle.provider(7)));

        let mut state = lattice_host::virtual_rows_worker::VirtualRowsWorkerState::new();
        lattice_host::virtual_rows_worker::recompute(
            &mut state,
            &a.editor.render_state,
            &a.editor.virtual_row_providers,
        );

        let snap = a.ad().snapshot.clone();
        let lines = compose_visible_lines(&a, &snap, 6, 40);
        let rendered: Vec<String> = lines
            .iter()
            .map(|l| {
                l.spans
                    .iter()
                    .map(|s| s.content.as_ref())
                    .collect::<String>()
            })
            .collect();

        assert!(
            rendered.iter().any(|l| l.contains('H')),
            "sticky headerline should paint: {rendered:#?}"
        );
        assert!(
            rendered.iter().any(|l| l.contains("bravo")),
            "last transcript line should paint: {rendered:#?}"
        );
        assert!(
            rendered.iter().any(|l| l.trim_end().ends_with('>')),
            "the prompt (last document line) must still be painted: {rendered:#?}"
        );
    }

    fn app_with(text: &str, viewport: u32) -> App {
        let mut a = App::new(Document::from_text(text));
        a.set_viewport_height(viewport);
        // display-line B4.2: `App::refresh_highlights` was deleted with
        // the overlay worker's dead span/row cache. Syntax now flows
        // through the cells / `DisplayMatrix` substrate (rebuilt on
        // publish); no explicit prime is needed for these render tests.
        a
    }

    /// Regression (2026-09-29): describe/help opened in a horizontal split
    /// (`help.describe-display=split-h`) must not leak the underlying
    /// document into the help pane's rows below the (short) help content.
    ///
    /// `PaneTree::split_active` clones the source leaf, so the new pane's
    /// region already belongs to the original document; `draw_pane_document`
    /// paints a full-height `Paragraph`, but a composed line shorter than the
    /// pane width leaves its trailing cells untouched and the `~`-filler rows
    /// past EOF paint only one glyph — so without a per-pane `Clear` those
    /// cells read as the cloned document. The user's report: "after the
    /// content of describe ends, I see the contents of the previous buffer
    /// where the help was triggered."
    #[tokio::test]
    async fn describe_in_split_does_not_leak_underlying_buffer_below_help() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let (tw, th): (u16, u16) = (40, 24);
        // A tall, visually-distinct underlying document — every content column
        // is `Z`, so any leak into the help pane is unmistakable.
        let underlying: String = "ZZZZZZZZZZZZ\n".repeat(60);
        let mut a = app_with(&underlying, th as u32);

        // Describe content is deliberately SHORT so the help pane has many
        // rows below it where a leak would show.
        let content = crate::help::HelpContent::from_lines(
            "describe-test",
            vec!["describe line one".into(), "describe line two".into()],
        );
        let _id = a.open_help_in_split(content, crate::pane::SplitOrientation::Horizontal);
        // Drive the app the way production does between the split and its next
        // frame: the actor republishes `ad()` keyed on the freshly-activated
        // buffer. Without settling, `ad().snapshot` (which `draw_frame` hands
        // the active pane) stays on the underlying document.
        for _ in 0..50 {
            a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
                e.publish_render_state();
            });
            let sigs =
                a.mutate_editor_with(|e: &mut lattice_host::editor::Editor| e.run_tick_pending());
            for s in sigs {
                a.handle_renderer_signal(s);
            }
            if a.ad().snapshot.buffer.as_string().contains("describe line") {
                break;
            }
            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
        }

        let snap = a.ad().snapshot.clone();
        let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &a, &snap);
            })
            .unwrap();
        let buf = terminal.backend().buffer().clone();

        let rows: Vec<String> = (0..th)
            .map(|y| {
                (0..tw)
                    .map(|x| buf[(x, y)].symbol().to_string())
                    .collect::<String>()
            })
            .collect();

        // The last help-content row.
        let describe_row = rows
            .iter()
            .rposition(|r| r.contains("describe line two"))
            .unwrap_or_else(|| panic!("describe content must paint:\n{rows:#?}"));

        // Rows between the help content and the help pane's status line must be
        // help-pane filler (blank / `~`), NEVER the underlying `Z`s. The status
        // line ("[help] …") ends the help pane; the underlying buffer resumes
        // only in the SECOND (bottom) pane, below that status line.
        for (i, row) in rows.iter().enumerate().skip(describe_row + 1) {
            if row.contains("help") || row.contains("describe-test") {
                break; // reached the help pane's status line
            }
            assert!(
                !row.contains("ZZZ"),
                "row {i} sits between the help content and the help pane's \
                 status line but shows the underlying buffer (`Z`s) — the \
                 describe-in-split leak:\n{rows:#?}"
            );
        }
    }

    /// **CV.5: in a pane-scoped listing the cursor highlight and the
    /// caret must land on the same screen row, at any scroll.**
    ///
    /// Reported against oil in a horizontal split: scrolling the
    /// cursor past the bottom of the pane made the highlight fall
    /// behind while the caret stayed on the right line. The split is
    /// not incidental — a full-height pane shows a short listing
    /// without ever scrolling, and at `scroll == 0` the two agree.
    ///
    /// Oil and the file tree are checked together on purpose. They are
    /// separate hand-written paint paths that were copied from each
    /// other, so they carried the same defect; the report named only
    /// oil, and testing only oil would have left the twin broken with
    /// nothing to announce it.
    #[tokio::test]
    async fn pane_listing_cursor_highlight_and_caret_share_a_row_when_scrolled() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        fn tempdir(tag: &str) -> std::path::PathBuf {
            use std::sync::atomic::{AtomicU64, Ordering};
            static COUNTER: AtomicU64 = AtomicU64::new(0);
            let nanos = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0);
            let n = COUNTER.fetch_add(1, Ordering::Relaxed);
            let d = std::env::temp_dir().join(format!("lattice-{tag}-cursorline-{nanos}-{n}"));
            std::fs::create_dir_all(&d).unwrap();
            d
        }

        for kind in ["oil", "file-tree"] {
            let dir = tempdir(kind);
            for i in 0..40 {
                std::fs::write(dir.join(format!("file{i:03}.txt")), "x").unwrap();
            }

            let (tw, th): (u16, u16) = (60, 24);
            let mut a = app_with("scratch\n", 1);
            // A horizontal split, as reported: the pane is short enough
            // that walking down the listing has to scroll.
            a.editor
                .pane_tree
                .split_active(crate::pane::SplitOrientation::Horizontal);
            a.editor.publish_render_state();
            // The bodies `App::do_open_oil` / `do_open_file_tree` run —
            // both are `pub(super)` to the `app` module, so drive the
            // host call plus the signal fan-out directly.
            let target = dir.clone();
            let signals = a.mutate_editor_with(move |e| match kind {
                "oil" => e.do_open_oil(Some(target)),
                _ => e.do_open_file_tree(Some(target)),
            });
            for s in signals {
                a.handle_renderer_signal(s);
            }

            // DL.4: the converged tree marks its cursor row with the
            // cursorline, which `directory-listing-mode` contributes —
            // so the mode has to be ACTIVE before the frame means
            // anything. Mode activation is async; without settling, the
            // first frame has no mark and the assertion below would be
            // measuring the gap rather than the invariant.
            {
                let mode = lattice_listing::listing_mode::DirectoryListingMode::mode_id();
                let bid = a.editor.active_pane_buffer_id();
                let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
                while std::time::Instant::now() < deadline {
                    let active = a
                        .editor
                        .active_modes
                        .get(&bid)
                        .map(|m| m.is_active(mode))
                        .unwrap_or(false);
                    if active {
                        break;
                    }
                    tokio::time::sleep(std::time::Duration::from_millis(10)).await;
                    let signals = a.editor.run_tick_pending();
                    for sig in signals {
                        a.handle_renderer_signal(sig);
                    }
                }
            }

            let chrome = chrome_rows(&a);
            let buffer_height = th
                .saturating_sub(1)
                .saturating_sub(chrome.tabline)
                .saturating_sub(chrome.extra()) as u32;
            let vh = a.active_pane_content_height(buffer_height);
            a.set_viewport_height(vh);

            // Walk down far enough that the pane must scroll.
            let down = a.editor.builtins.line_down;
            for _ in 0..(vh + 6) {
                a.apply(crate::app::Action::Invoke(
                    lattice_grammar::CommandInvocation::of(down.0),
                ));
            }
            a.mutate_editor(|e| {
                e.publish_render_state();
            });
            assert!(
                a.editor.scroll > 0,
                "{kind}: precondition — the split pane must have scrolled \
                 (scroll={}, vh={vh})",
                a.editor.scroll,
            );

            let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();
            let snap = a.ad().snapshot.clone();
            terminal
                .draw(|f| {
                    let _ = draw_frame(f, &a, &snap);
                })
                .unwrap();

            let caret_row = terminal.get_cursor_position().unwrap().y;
            let buf = terminal.backend().buffer().clone();
            let screen: Vec<String> = (0..th)
                .map(|y| {
                    (0..tw)
                        .map(|x| buf[(x, y)].symbol().to_string())
                        .collect::<String>()
                        .trim_end()
                        .to_string()
                })
                .collect();

            // The cursor's own row, identified by its TEXT rather than
            // by how the pane marks it.
            //
            // DL.4 moved the file tree between paint paths — the
            // bespoke painter reverse-videoed the cursor row, the
            // shared compose path tints it with the cursorline — so an
            // assertion on either mechanism would have had to be
            // rewritten and would only ever guard one of them. What the
            // report was actually about survives both: the caret must
            // sit on the row showing the cursor's entry. Oil moves to
            // the shared path in DL.5 and this needs no change.
            // `active_text` resolves per kind, so this reads the pane's
            // OWN buffer for both — `ad()` is the background document
            // for oil, which is not converged until DL.5.
            //
            // Matched on the entry name rather than the whole row: the
            // tree's row carries an indent and an expand marker, and
            // both kinds now splice a leading icon that is virtual text
            // and therefore not in the rope. The filenames in the
            // fixture are unique, so one row matches.
            let cursor_text = a
                .editor
                .active_text()
                .line(a.editor.cursor.line)
                .unwrap_or_default()
                .trim()
                .to_string();
            assert!(
                !cursor_text.is_empty(),
                "{kind}: precondition — the cursor's line has text to find"
            );
            let rows_with_cursor_text: Vec<u16> = (0..th)
                .filter(|&y| screen[y as usize].contains(&cursor_text))
                .collect();

            let (scroll, cursor_line) = (a.editor.scroll, a.editor.cursor.line);
            let _ = std::fs::remove_dir_all(&dir);

            assert_eq!(
                rows_with_cursor_text,
                vec![caret_row],
                "{kind}: the caret must sit on the row showing the cursor's own \
                 entry ({cursor_text:?}) — caret_row={caret_row}, scroll={scroll}, \
                 cursor.line={cursor_line}",
            );
        }
    }

    /// **A listing icon paints in its OWN theme element, not one blanket
    /// `inlay.hint` grey.**
    ///
    /// `directory-listing-mode` publishes one icon per row carrying
    /// `Style::Element(listing.file.rust)` / `…python` / `listing.dir`
    /// (DL.3b), and the cells worker and GPUI both resolve that style.
    /// The TUI's post-hoc splice did not: it re-inserted the virtual text
    /// that `display_line_to_source_spans` drops and re-styled every row
    /// with `inlay_hint_style`, so a `.rs`, a `.py` and a directory all
    /// painted `#7f849c`. The published data was correct the whole time —
    /// only this paint discarded it, which is why the host-side
    /// `listing_icons_resolve_their_element_before_the_mode_cascade_runs`
    /// test passed while the screen showed one colour.
    ///
    /// Asserted on the PAINTED frame, and against the resolved elements
    /// rather than literals: "the icons differ from each other" alone
    /// would pass on any palette, and hardcoded RGB would re-break the
    /// moment a theme retunes `listing.*` — which is the entire point of
    /// having rooted them in the theme.
    #[tokio::test]
    async fn a_listing_icon_paints_in_its_own_element_not_one_inlay_grey() {
        use lattice_host::ui::theme::{ElementName, ThemeRegistryHandle};
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let dir = {
            use std::sync::atomic::{AtomicU64, Ordering};
            static N: AtomicU64 = AtomicU64::new(0);
            let nanos = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0);
            let d = std::env::temp_dir().join(format!(
                "lattice-listing-icon-colour-{nanos}-{}",
                N.fetch_add(1, Ordering::Relaxed)
            ));
            std::fs::create_dir_all(&d).unwrap();
            d
        };
        std::fs::create_dir_all(dir.join("subdir")).unwrap();
        std::fs::write(dir.join("main.rs"), "x").unwrap();
        std::fs::write(dir.join("script.py"), "x").unwrap();

        let (tw, th): (u16, u16) = (60, 24);
        let mut a = app_with("scratch\n", 20);
        let target = dir.clone();
        let signals = a.mutate_editor_with(move |e: &mut lattice_host::editor::Editor| {
            e.do_open_file_tree(Some(target))
        });
        for s in signals {
            a.handle_renderer_signal(s);
        }
        // Icons reach the frame through `PendingInlays` → `ExtraInlays`,
        // drained on a tick — not on the open call. Settling on the mode
        // is the same wait the CV.5 test above makes.
        {
            let mode = lattice_listing::listing_mode::DirectoryListingMode::mode_id();
            let bid = a.editor.active_pane_buffer_id();
            let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
            while std::time::Instant::now() < deadline {
                if a.editor
                    .active_modes
                    .get(&bid)
                    .map(|m| m.is_active(mode))
                    .unwrap_or(false)
                {
                    break;
                }
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
                let signals = a.editor.run_tick_pending();
                for sig in signals {
                    a.handle_renderer_signal(sig);
                }
            }
        }
        a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
            e.publish_render_state();
        });

        // What the theme says each element should paint as.
        let theme = a
            .editor
            .services
            .get::<ThemeRegistryHandle>()
            .expect("the theme registry is a boot service");
        let resolved = theme.resolved();
        let want = |name: &'static str| -> Color {
            let id = theme
                .id(&ElementName::from_static(name))
                .unwrap_or_else(|| panic!("{name} must be registered by the listing mode"));
            crate::theme::host_color_to_ratatui(
                resolved
                    .get(id)
                    .fg
                    .unwrap_or_else(|| panic!("{name} must resolve a foreground")),
            )
        };
        let want_dir = want(lattice_listing::listing_mode::ELEM_LISTING_DIR);
        let want_rust = want("listing.file.rust");
        let want_python = want("listing.file.python");
        assert!(
            want_rust != want_python && want_rust != want_dir,
            "precondition: the three elements resolve to different colours \
             ({want_rust:?} / {want_python:?} / {want_dir:?}) — if the palette \
             collapsed them this test could not tell a fix from the bug"
        );

        let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();
        let snap = a.ad().snapshot.clone();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &a, &snap);
            })
            .unwrap();
        let buf = terminal.backend().buffer().clone();

        // The painted fg of the icon on the row whose text contains
        // `name`. The icon is virtual text, so it is not in the rope and
        // cannot be located by byte — find the row by its name, then take
        // the cell just left of where the name starts.
        let icon_fg = |name: &str| -> Color {
            for y in 0..th {
                // Searched per COLUMN, not per byte: the icon glyph is
                // multi-byte, so a byte offset into the row's text is not
                // the column the name starts at — and the cell two to its
                // left would be some interior byte of the name.
                let cols: Vec<String> = (0..tw).map(|x| buf[(x, y)].symbol().to_string()).collect();
                for c in 0..cols.len() {
                    if cols[c..].concat().starts_with(name) {
                        // Back over the icon's trailing space onto the glyph.
                        return buf[(c.saturating_sub(2) as u16, y)].fg;
                    }
                }
            }
            panic!("no painted row contains {name:?}");
        };

        let (rust, python, subdir) = (icon_fg("main.rs"), icon_fg("script.py"), icon_fg("subdir"));
        let _ = std::fs::remove_dir_all(&dir);

        assert_eq!(
            rust, want_rust,
            "the .rs icon must paint `listing.file.rust`; painting the \
             blanket `inlay.hint` grey here is the reported bug"
        );
        assert_eq!(
            python, want_python,
            "the .py icon must paint `listing.file.python`"
        );
        assert_eq!(
            subdir, want_dir,
            "a directory icon must paint `listing.dir`"
        );
    }

    /// **DL.8b: a listing row's NAME paints in the row's element too, and
    /// the tree's indent + expand marker do not.**
    ///
    /// The icon alone carried colour until DL.8b, so every filename —
    /// directories included — painted plain `text`, which is what the
    /// report "no colour coding" was mostly about. Names publish through
    /// the generic `PendingSyntheticHighlights` channel, so this asserts
    /// the whole path end to end: entries → spans → `ExtraHighlights` →
    /// the cells build → painted cells.
    ///
    /// The marker assertion is the other half and is the one that can
    /// regress quietly: spanning from byte 0 instead of `icon_byte`
    /// would tint a directory's `▾` with the directory colour and make
    /// the tree's structure read as content. It looks fine on an oil
    /// buffer (`icon_byte == 0`), which is why the tree is what is
    /// checked here.
    #[tokio::test]
    async fn a_listing_row_name_paints_its_element_and_the_tree_marker_does_not() {
        use lattice_host::ui::theme::{ElementName, ThemeRegistryHandle};
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let dir = {
            use std::sync::atomic::{AtomicU64, Ordering};
            static N: AtomicU64 = AtomicU64::new(0);
            let nanos = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0);
            let d = std::env::temp_dir().join(format!(
                "lattice-listing-name-colour-{nanos}-{}",
                N.fetch_add(1, Ordering::Relaxed)
            ));
            std::fs::create_dir_all(&d).unwrap();
            d
        };
        std::fs::create_dir_all(dir.join("subdir")).unwrap();
        std::fs::write(dir.join("main.rs"), "x").unwrap();
        std::fs::write(dir.join("script.py"), "x").unwrap();

        let (tw, th): (u16, u16) = (60, 24);
        let mut a = app_with("scratch\n", 20);
        let target = dir.clone();
        let signals = a.mutate_editor_with(move |e: &mut lattice_host::editor::Editor| {
            e.do_open_file_tree(Some(target))
        });
        for s in signals {
            a.handle_renderer_signal(s);
        }
        {
            let mode = lattice_listing::listing_mode::DirectoryListingMode::mode_id();
            let bid = a.editor.active_pane_buffer_id();
            let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
            while std::time::Instant::now() < deadline {
                if a.editor
                    .active_modes
                    .get(&bid)
                    .map(|m| m.is_active(mode))
                    .unwrap_or(false)
                {
                    break;
                }
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
                let signals = a.editor.run_tick_pending();
                for sig in signals {
                    a.handle_renderer_signal(sig);
                }
            }
        }
        a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
            e.publish_render_state();
        });

        let theme = a
            .editor
            .services
            .get::<ThemeRegistryHandle>()
            .expect("the theme registry is a boot service");
        let resolved = theme.resolved();
        let want = |name: &'static str| -> Color {
            let id = theme
                .id(&ElementName::from_static(name))
                .unwrap_or_else(|| panic!("{name} must be registered"));
            crate::theme::host_color_to_ratatui(
                resolved.get(id).fg.expect("element resolves a foreground"),
            )
        };
        let want_dir = want(lattice_listing::listing_mode::ELEM_LISTING_DIR);
        let want_rust = want("listing.file.rust");
        let want_python = want("listing.file.python");
        let plain = want(lattice_listing::listing_mode::ELEM_LISTING_FILE);

        let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();

        // `(fg of the name's first cell, fg of the expand marker on that
        // row)`. Located per column, not per byte — the icon glyph is
        // multi-byte.
        let row_colours = |buf: &ratatui::buffer::Buffer, name: &str| -> (Color, Option<Color>) {
            for y in 0..th {
                let cols: Vec<String> = (0..tw).map(|x| buf[(x, y)].symbol().to_string()).collect();
                for c in 0..cols.len() {
                    if cols[c..].concat().starts_with(name) {
                        let marker = (0..c)
                            .find(|&x| cols[x] == "▾" || cols[x] == "▸")
                            .map(|x| buf[(x as u16, y)].fg);
                        return (buf[(c as u16, y)].fg, marker);
                    }
                }
            }
            panic!("no painted row contains {name:?}");
        };

        // Names, unlike icons, need the cells / `DisplayMatrix` REBUILD:
        // they colour source spans that the matrix bakes in, where an icon
        // is spliced post-hoc onto whatever body exists. That build is the
        // async worker's, so the colour lands a frame or two after the
        // publish — the eventual consistency the keystroke UX contract
        // allows for syntax colour, and the same window `display_stale`
        // paints plain text through.
        //
        // So this settles on the PAINTED result rather than on the mode. A
        // single draw passes on an idle machine and fails under a loaded
        // one, which is a flake that would get argued with instead of
        // obeyed; and if the colour never arrives, this still fails — on
        // the assertions below, with the deadline spent.
        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
        let buf = loop {
            let snap = a.ad().snapshot.clone();
            terminal
                .draw(|f| {
                    let _ = draw_frame(f, &a, &snap);
                })
                .unwrap();
            let buf = terminal.backend().buffer().clone();
            if row_colours(&buf, "main.rs").0 == want_rust || std::time::Instant::now() >= deadline
            {
                break buf;
            }
            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            let signals = a.editor.run_tick_pending();
            for sig in signals {
                a.handle_renderer_signal(sig);
            }
            a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
                e.publish_render_state();
            });
        };

        let (rust_name, _) = row_colours(&buf, "main.rs");
        let (python_name, _) = row_colours(&buf, "script.py");
        let (dir_name, dir_marker) = row_colours(&buf, "subdir");
        let _ = std::fs::remove_dir_all(&dir);

        assert_eq!(
            rust_name, want_rust,
            "a .rs row's NAME must paint `listing.file.rust` — painting it \
             {plain:?} (plain text) is the state DL.8b fixes"
        );
        assert_eq!(
            python_name, want_python,
            "a .py row's name must paint `listing.file.python`"
        );
        assert_eq!(
            dir_name, want_dir,
            "a directory's name must paint `listing.dir`"
        );
        assert_ne!(
            rust_name, python_name,
            "two languages must not collapse to one colour — that is what \
             'the colour coding is gone' looks like from the user's side"
        );
        assert_eq!(
            dir_marker,
            Some(plain),
            "the tree's expand marker is STRUCTURE and must keep the default \
             text colour — a span anchored at byte 0 instead of `icon_byte` \
             would tint it with the directory's colour and make the tree's \
             shape read as content"
        );
    }

    /// **CV.2: a file that ends in a newline must not paint an extra
    /// empty row.**
    ///
    /// ropey reports one more line than the file has for any rope
    /// ending in `\n` — the convention `Buffer::line_count` surfaces
    /// verbatim. Feeding that raw count to the matrix build made the
    /// phantom logical line into a phantom *display row*, so a
    /// 219-line `todo.org` painted a numbered, empty line 220 that no
    /// other editor shows. Below the real last line the frame must
    /// show the no-such-line filler, not a numbered row.
    #[test]
    fn a_file_ending_in_a_newline_paints_no_extra_row() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        // (label, text, lines the file actually has)
        for (label, text, want_lines) in [
            ("terminated", "alpha\nbravo\ncharlie\n", 3u32),
            ("unterminated", "alpha\nbravo\ncharlie", 3),
            // A genuinely blank final line IS content — the file ends
            // with an empty line and then its terminator. Trimming it
            // too would be the same bug in the other direction.
            ("blank last line", "alpha\nbravo\ncharlie\n\n", 4),
            ("single line", "alpha\n", 1),
            ("empty", "", 1),
        ] {
            let (tw, th): (u16, u16) = (40, 12);
            let mut a = app_with(text, 10);
            a.set_pane_viewport(0, 10, tw as u32);
            a.mutate_editor(|e| {
                e.publish_render_state();
            });
            let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();
            let snap = a.ad().snapshot.clone();
            terminal
                .draw(|f| {
                    let _ = draw_frame(f, &a, &snap);
                })
                .unwrap();
            let buf = terminal.backend().buffer().clone();
            let numbered: Vec<u32> = (0..th)
                .filter_map(|y| {
                    let row: String = (0..tw).map(|x| buf[(x, y)].symbol().to_string()).collect();
                    row.trim_start().split(' ').next()?.parse::<u32>().ok()
                })
                .collect();

            assert_eq!(
                numbered,
                (1..=want_lines).collect::<Vec<_>>(),
                "{label}: the frame must number exactly the {want_lines} line(s) the \
                 file has — a trailing newline terminates the last line, it does not \
                 start another one"
            );
        }
    }

    /// **CV.1: after `G`, the cursor's line must be a line the frame
    /// actually painted.**
    ///
    /// Reported against a 219-line `todo.org` with `wrap = true`: `G`
    /// put the cursor on line 219 while the last row drawn was 218, so
    /// the caret sat one row below the visible area. The cause was in
    /// the host's bottom clamp (`bottom_anchored_scroll`), which read
    /// soft-wrap geometry from the cells matrix — published
    /// asynchronously by the worker and windowed to the viewport. On
    /// the keystroke that runs the motion that cache routinely holds
    /// neither the pane's wrap width nor a row for the jump target,
    /// and `segment_count` answers `1` for both, so the clamp budgeted
    /// one row per line for content the renderer wrapped into two or
    /// three.
    ///
    /// Asserted as the invariant rather than the instance, against the
    /// painted frame rather than against `editor.scroll`: whatever the
    /// geometry, the cursor's source line is among the line numbers in
    /// the gutter. The app is deliberately **not** settled first — a
    /// test that lets the worker publish before pressing `G` passes on
    /// the broken build, which is exactly how this survived the
    /// existing wrap tests (they pre-seed the matrix with
    /// `seed_wrap_matrix`, handing the clamp the answer it is supposed
    /// to derive).
    #[test]
    fn cursor_lands_on_a_painted_row_after_goto_last_line() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        // Prose-shaped: a mix of short lines and lines long enough to
        // wrap into two or three rows at every width under test.
        let text: String = (0..219)
            .map(|i: u32| match i % 4 {
                0 => format!("line {i}\n"),
                1 => format!("{} {i}\n", "medium length body text".repeat(2)),
                2 => String::from("\n"),
                _ => format!("{} {i}\n", "a much longer paragraph of prose".repeat(4)),
            })
            .collect();

        let mut failures: Vec<String> = Vec::new();
        for wrap in [false, true] {
            for split in [false, true] {
                for &(tw, th) in &[(120u16, 30u16), (80, 30), (80, 24), (60, 20), (100, 45)] {
                    let mut a = app_with(&text, 1);
                    if wrap {
                        a.editor
                            .config
                            .parse_and_set_command("wrap")
                            .expect("`wrap` is settable");
                        a.mutate_editor(|e| {
                            e.rebuild_option_cache();
                        });
                    }
                    if split {
                        a.editor
                            .pane_tree
                            .split_active(crate::pane::SplitOrientation::Horizontal);
                        a.editor.publish_render_state();
                    }

                    // Mirrors runtime.rs's per-frame viewport push.
                    let chrome = chrome_rows(&a);
                    let buffer_height =
                        th.saturating_sub(1)
                            .saturating_sub(chrome.tabline)
                            .saturating_sub(chrome.extra()) as u32;
                    let vh = a.active_pane_content_height(buffer_height);
                    a.set_viewport_height(vh);
                    a.set_pane_viewport(0, vh, tw as u32);

                    let id = a.editor.builtins.goto_last_line;
                    a.apply(crate::app::Action::Invoke(
                        lattice_grammar::CommandInvocation::of(id.0),
                    ));
                    a.mutate_editor(|e| {
                        e.publish_render_state();
                    });

                    let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();
                    let snap = a.ad().snapshot.clone();
                    terminal
                        .draw(|f| {
                            let _ = draw_frame(f, &a, &snap);
                        })
                        .unwrap();
                    let buf = terminal.backend().buffer().clone();
                    // Painted source lines = the leading gutter numbers.
                    // Wrap-continuation rows have a blank gutter and so
                    // contribute nothing, which is what we want: the
                    // cursor's line must have a numbered row of its own.
                    let painted: Vec<u32> = (0..th)
                        .filter_map(|y| {
                            let row: String =
                                (0..tw).map(|x| buf[(x, y)].symbol().to_string()).collect();
                            row.trim_start().split(' ').next()?.parse::<u32>().ok()
                        })
                        .collect();

                    let want = a.editor.cursor.line + 1;
                    if !painted.contains(&want) {
                        failures.push(format!(
                            "wrap={wrap} split={split} {tw}x{th}: cursor on line {want} but the \
                             frame painted lines {:?}..={:?} (scroll={})",
                            painted.first(),
                            painted.last(),
                            a.editor.scroll,
                        ));
                    }
                }
            }
        }
        assert!(
            failures.is_empty(),
            "`G` left the cursor off the painted area in {} of 20 geometries:\n  {}",
            failures.len(),
            failures.join("\n  "),
        );
    }

    /// `chrome_rows` is the single source of truth the runtime loop and
    /// `draw_frame` both read; verify it actually reflects tabline
    /// MG.41b: a transient's band is bounded by
    /// `ui.transient.max-rows`, not the picker's 10.
    ///
    /// The magit dispatch is 25 rows plus group headers, so the shared
    /// picker cap showed under half of it — the reported complaint.
    #[test]
    fn transient_band_uses_its_own_row_budget() {
        let a = app_with("x\n", 10);
        // Default: 20, not the picker's 10.
        assert_eq!(transient_max_rows(&a), 20);
        // The cap is a MAXIMUM — a short menu still claims only its own
        // rows, so a two-item transient does not paint an 18-row hole.
        assert_eq!(popup_height_capped(3, 20), 3);
        assert_eq!(popup_height_capped(25, 20), 20);
        // Zero/negative clamp to 1 rather than producing an empty band.
        assert_eq!(popup_height_capped(25, 0), 1);
    }

    /// The picker's own budget is untouched by the transient option —
    /// they were sharing one constant before this slice.
    #[test]
    fn picker_band_is_unchanged_at_ten() {
        assert_eq!(popup_height(25), PICKER_MAX_ROWS);
        assert_eq!(popup_height(4), 4);
    }

    /// `:set ui.transient.max-rows` is honoured live.
    #[test]
    fn transient_row_budget_is_configurable() {
        let mut a = app_with("x\n", 10);
        a.editor
            .config
            .parse_and_set_command("ui.transient.max-rows=40")
            .expect("option is settable");
        a.editor.publish_render_state();
        assert_eq!(transient_max_rows(&a), 40);
    }

    /// visibility (Auto mode: visible iff more than one tab is open).
    #[test]
    fn chrome_rows_reflects_tabline_visibility() {
        let mut a = app_with("one\ntwo\nthree\n", 10);
        assert_eq!(chrome_rows(&a).tabline, 0, "single tab: no tabline row");
        a.editor.do_new_tab();
        a.editor.publish_render_state();
        assert_eq!(
            chrome_rows(&a).tabline,
            1,
            "two tabs: tabline claims one row"
        );
    }

    /// Regression guard for the "last line off-screen once the tabline is
    /// visible" bug: the runtime loop's `buffer_height` formula (terminal
    /// height minus cmdline, tabline, and candidate-band rows) must always
    /// equal the pane area `draw_frame` actually lays out via the ratatui
    /// `Layout`. Before this fix the runtime's copy never subtracted the
    /// tabline row at all, so the viewport/scroll logic believed it had one
    /// more row to show than `draw_frame` ever painted — the "last" line by
    /// its reckoning was never physically drawn. Both sides now read
    /// `chrome_rows`, so this test also guards against a future edit
    /// reintroducing a hand-duplicated, divergent copy of either formula.
    #[test]
    fn runtime_buffer_height_matches_draw_frame_pane_area_with_tabline() {
        let mut a = app_with("one\ntwo\nthree\n", 10);
        a.editor.do_new_tab();
        a.editor.publish_render_state();
        let chrome = chrome_rows(&a);
        assert_eq!(chrome.tabline, 1, "precondition: tabline visible");

        let terminal_width: u16 = 80;
        let terminal_height: u16 = 40;
        // Mirrors `runtime.rs`'s `buffer_height` formula exactly.
        let runtime_buffer_height = terminal_height
            .saturating_sub(1)
            .saturating_sub(chrome.tabline)
            .saturating_sub(chrome.extra());

        // Mirrors `draw_frame`'s own Layout constraints (no candidate band
        // open in this scenario).
        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .constraints([
                Constraint::Length(chrome.tabline),
                Constraint::Min(1),
                Constraint::Length(1),
            ])
            .split(Rect::new(0, 0, terminal_width, terminal_height));

        assert_eq!(
            runtime_buffer_height, chunks[1].height,
            "runtime's buffer_height must equal draw_frame's actual pane-area \
             height — a mismatch means the viewport/scroll logic and the paint \
             layout disagree on how many rows are visible"
        );
    }

    /// Same invariant as above, tabline hidden (single tab) — the two
    /// computations must still agree when there's nothing extra to reserve.
    #[test]
    fn runtime_buffer_height_matches_draw_frame_pane_area_without_tabline() {
        let a = app_with("one\ntwo\nthree\n", 10);
        let chrome = chrome_rows(&a);
        assert_eq!(chrome.tabline, 0, "precondition: tabline hidden");

        let terminal_width: u16 = 80;
        let terminal_height: u16 = 40;
        let runtime_buffer_height = terminal_height
            .saturating_sub(1)
            .saturating_sub(chrome.tabline)
            .saturating_sub(chrome.extra());

        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .constraints([
                Constraint::Length(chrome.tabline),
                Constraint::Min(1),
                Constraint::Length(1),
            ])
            .split(Rect::new(0, 0, terminal_width, terminal_height));

        assert_eq!(runtime_buffer_height, chunks[1].height);
    }

    /// Generalises the two invariant tests above from "one pane" to
    /// ARBITRARY split trees and ARBITRARY window sizes — Dhruva's
    /// concern that the fix must hold "regardless of these constraints"
    /// (2-way, 3-way, 4-way splits; any terminal size, i.e. any resize),
    /// not just the shapes happened to be spot-checked.
    ///
    /// Both `compute_rects` (lattice-core) and the split-geometry loops in
    /// `runtime.rs` / `draw_panes` are PURE recursive functions of
    /// `(pane tree, total area)` — the tabline/cmdline/candidate-band
    /// reservation happens exactly once, one layer ABOVE the split tree,
    /// via `chrome_rows`. So proving the invariant composes with splits
    /// and resizes reduces to: for every split depth and every terminal
    /// size, does `compute_rects` over the runtime's `area_for_panes`
    /// (built from `chrome_rows`-corrected `buffer_height`) produce THE
    /// SAME per-leaf rects as `compute_rects` over `draw_frame`'s actual
    /// `chunks[1]`? If a future edit ever special-cased tabline handling
    /// PER-PANE instead of once at the top, this test would catch the
    /// divergence immediately at any split count.
    #[test]
    fn chrome_rows_composes_with_arbitrary_splits_and_terminal_sizes() {
        use crate::pane::{PaneRect, SplitOrientation};

        // 0, 1, 2, 3 splits => 1, 2, 3, 4-way pane trees. Mix of
        // orientations so both HorizontalSplit and VerticalSplit recursion
        // arms are exercised, not just one.
        let split_plans: &[&[SplitOrientation]] = &[
            &[],
            &[SplitOrientation::Horizontal],
            &[SplitOrientation::Vertical],
            &[SplitOrientation::Horizontal, SplitOrientation::Vertical],
            &[
                SplitOrientation::Horizontal,
                SplitOrientation::Vertical,
                SplitOrientation::Horizontal,
            ],
        ];

        // A spread of terminal sizes standing in for "the user resized the
        // window" — including sizes too small to hold every split cleanly,
        // where `saturating_sub`/`.max(1)` clamping must still agree
        // between both sides.
        let terminal_sizes: &[(u16, u16)] =
            &[(80, 24), (80, 40), (200, 60), (40, 10), (120, 8), (30, 6)];

        for splits in split_plans {
            for tabline_visible in [false, true] {
                for &(terminal_width, terminal_height) in terminal_sizes {
                    let mut a = app_with("one\ntwo\nthree\n", 10);
                    for orientation in *splits {
                        a.editor.pane_tree.split_active(*orientation);
                    }
                    if tabline_visible {
                        a.editor
                            .pane_tree
                            .split_active(SplitOrientation::Horizontal);
                        // Second tab makes `tabs.visible` true in Auto mode
                        // (`self.tabs.len() > 1`) without depending on any
                        // particular `tabline.show` config default.
                        a.editor.do_new_tab();
                    }
                    a.editor.publish_render_state();

                    let chrome = chrome_rows(&a);
                    assert_eq!(
                        chrome.tabline > 0,
                        tabline_visible,
                        "tabline visibility precondition failed for splits={splits:?} \
                         size=({terminal_width}x{terminal_height})"
                    );

                    // Mirrors runtime.rs: buffer_height, then compute_rects
                    // over the FULL terminal area (tabline/cmdline/candidate
                    // rows already excluded by buffer_height).
                    let runtime_buffer_height = terminal_height
                        .saturating_sub(1)
                        .saturating_sub(chrome.tabline)
                        .saturating_sub(chrome.extra());
                    let panes_arc = a.panes();
                    let runtime_area = PaneRect {
                        x: 0,
                        y: 0,
                        width: terminal_width,
                        height: runtime_buffer_height,
                    };
                    let mut runtime_rects = panes_arc.tree.compute_rects(runtime_area);
                    runtime_rects.sort_by_key(|(idx, _)| *idx);

                    // Mirrors draw_frame: the real ratatui Layout split,
                    // then draw_panes's own compute_rects over chunks[1].
                    let constraints: Vec<Constraint> = if chrome.extra() > 0 {
                        vec![
                            Constraint::Length(chrome.tabline),
                            Constraint::Min(1),
                            Constraint::Length(1),
                            Constraint::Length(chrome.extra()),
                        ]
                    } else {
                        vec![
                            Constraint::Length(chrome.tabline),
                            Constraint::Min(1),
                            Constraint::Length(1),
                        ]
                    };
                    let chunks = Layout::default()
                        .direction(Direction::Vertical)
                        .constraints(constraints)
                        .split(Rect::new(0, 0, terminal_width, terminal_height));
                    let draw_area = PaneRect {
                        x: chunks[1].x,
                        y: chunks[1].y,
                        width: chunks[1].width,
                        height: chunks[1].height,
                    };
                    let mut draw_rects = panes_arc.tree.compute_rects(draw_area);
                    draw_rects.sort_by_key(|(idx, _)| *idx);

                    // Compare (width, height) per leaf, NOT the full rect:
                    // `runtime.rs`'s `area_for_panes` is deliberately
                    // anchored at `y:0` (it only sizes the PTY / viewport
                    // row-col COUNTS, never paints), while `draw_frame`'s
                    // real `chunks[1]` starts at `y:1` once the tabline
                    // claims the first screen row. Different absolute
                    // position, same size — that's expected, not a bug.
                    // The invariant that actually matters (does the
                    // runtime compute the SAME row/col count per pane that
                    // gets painted?) is the size, which this checks.
                    let runtime_sizes: Vec<(usize, u16, u16)> = runtime_rects
                        .iter()
                        .map(|(idx, r)| (*idx, r.width, r.height))
                        .collect();
                    let draw_sizes: Vec<(usize, u16, u16)> = draw_rects
                        .iter()
                        .map(|(idx, r)| (*idx, r.width, r.height))
                        .collect();
                    assert_eq!(
                        runtime_sizes, draw_sizes,
                        "runtime-pushed vs. actually-painted per-pane sizes diverged \
                         for splits={splits:?}, tabline_visible={tabline_visible}, \
                         terminal_size=({terminal_width}x{terminal_height})"
                    );

                    // Every leaf's content height (status row reserved) must
                    // also agree — the same `rect.height - 1` formula both
                    // `runtime.rs`'s per-leaf loop and `draw_panes` apply,
                    // checked here across the SAME split/size matrix rather
                    // than just the whole-buffer area.
                    for (idx, rect) in &draw_rects {
                        let content_h = if rect.height >= 2 {
                            rect.height - 1
                        } else {
                            rect.height
                        };
                        assert!(
                            content_h <= rect.height,
                            "leaf {idx} content height must not exceed its pane rect \
                             for splits={splits:?} size=({terminal_width}x{terminal_height})"
                        );
                    }
                }
            }
        }
    }

    fn line_text(line: &Line<'_>) -> String {
        line.spans.iter().map(|s| s.content.as_ref()).collect()
    }

    /// Regression for the auto-scroll ghosting bug
    /// (`docs/dev/audit/terminal-wide-char-ghosting.md`): a width-2
    /// glyph occupies two grid cells (the glyph + a `wide_spacer`
    /// placeholder). The emitted row must have the SAME total display
    /// width as the grid column count — the wide glyph owns its two
    /// columns and the spacer must NOT be emitted as a stray space.
    /// Emitting the spacer pushed the row one column wide per glyph,
    /// desyncing ratatui's width-based cell diff and stranding stale
    /// glyphs on scroll.
    #[test]
    fn terminal_row_with_wide_glyph_keeps_grid_column_count() {
        use lattice_terminal::{Cell, TerminalSnapshot};

        // Grid row: 🚀 (wide) + its spacer + "abc" → 5 grid columns.
        let cells = vec![
            Cell {
                ch: '🚀',
                wide_spacer: false,
                ..Cell::default()
            },
            Cell {
                ch: ' ',
                wide_spacer: true,
                ..Cell::default()
            },
            Cell {
                ch: 'a',
                ..Cell::default()
            },
            Cell {
                ch: 'b',
                ..Cell::default()
            },
            Cell {
                ch: 'c',
                ..Cell::default()
            },
        ];
        let cols = cells.len() as u16;
        let snap = TerminalSnapshot {
            cells: cells.into(),
            ..TerminalSnapshot::empty_sized(1, cols)
        };

        let spans = super::terminal_row_spans(&snap, 0, cols, false, 0, 0, None, &[], None);
        let text: String = spans.iter().map(|s| s.content.as_ref()).collect();
        let display_width: usize = spans.iter().map(|s| s.width()).sum();
        assert_eq!(
            display_width, cols as usize,
            "emitted row display width ({display_width}) must equal the grid column \
             count ({cols}); the wide glyph owns 2 columns and the spacer must be \
             skipped — got text {text:?}",
        );
        assert_eq!(
            text, "🚀abc",
            "the wide-char spacer cell must be skipped, not emitted as a space",
        );
    }

    /// MG.47: **a synthetic buffer keeps rendering its own text while the
    /// `:` line is open.**
    ///
    /// Reported against magit: pressing `:` in a magit buffer made the pane
    /// paint the file magit was opened *from*. `draw_panes` drops `is_active`
    /// while `command_line_active`, routing the focused pane to
    /// `draw_inactive_document` — which resolves the pane's OWN buffer from
    /// the registry. So the content must not change when the line opens.
    ///
    /// `*plugins*` stands in for a magit buffer: same
    /// `Effect::OpenSyntheticBuffer` open onto a provider-registered mode,
    /// and this crate cannot depend on `lattice-magit`.
    #[test]
    fn a_synthetic_buffer_keeps_its_content_while_the_command_line_is_open() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let mut app = app_with("ORIGINFILECONTENT\n", 24);
        let mut terminal = Terminal::new(TestBackend::new(80, 26)).unwrap();
        let screen = |t: &Terminal<TestBackend>| -> String {
            let buf = t.backend().buffer().clone();
            (0..26u16)
                .map(|y| {
                    (0..80u16)
                        .map(|x| buf[(x, y)].symbol().to_string())
                        .collect::<String>()
                })
                .collect::<Vec<_>>()
                .join("\n")
        };

        app.mutate_editor(|e| {
            e.open_synthetic_buffer("*plugins*", "plugins-mode");
            e.publish_render_state();
        });
        let snap = app.ad().snapshot.clone();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &app, &snap);
            })
            .unwrap();
        let before = screen(&terminal);
        assert!(
            !before.contains("ORIGINFILECONTENT"),
            "sanity: after opening the synthetic buffer the origin file's text \
             is gone from the pane; got:\n{before}",
        );

        // Now open the `:` line. The pane must keep painting ITS buffer.
        app.mutate_editor(|e| {
            e.open_command_line("");
            e.publish_render_state();
        });
        let snap = app.ad().snapshot.clone();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &app, &snap);
            })
            .unwrap();
        let during = screen(&terminal);
        assert!(
            !during.contains("ORIGINFILECONTENT"),
            "opening `:` must not make the pane fall back to the buffer the \
             synthetic one was opened from; got:\n{during}",
        );
    }

    /// MG.47, on the buffer it was actually reported against.
    ///
    /// The `*plugins*` case above covers the generic mechanism; magit differs
    /// in ways that could plausibly matter to the render path — a headerline
    /// virtual row, async content, and a `prev_pane_for_popup` stash taken at
    /// open. This renders a real magit buffer across the `:` transition.
    #[test]
    fn a_magit_buffer_keeps_its_content_while_the_command_line_is_open() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let mut app = app_with("ORIGINFILECONTENT\n", 24);
        let mut terminal = Terminal::new(TestBackend::new(80, 26)).unwrap();
        let screen = |t: &Terminal<TestBackend>| -> String {
            let buf = t.backend().buffer().clone();
            (0..26u16)
                .map(|y| {
                    (0..80u16)
                        .map(|x| buf[(x, y)].symbol().to_string())
                        .collect::<String>()
                })
                .collect::<Vec<_>>()
                .join("\n")
        };

        // Seed the magit buffer with known text. Without this the buffer is
        // empty in a test (no git repo, no async refresh), and every
        // "origin text is absent" assertion below would pass vacuously —
        // which is exactly how this bug hid from an earlier version of this
        // test.
        app.mutate_editor(|e| {
            e.open_synthetic_buffer("*magit:status*", "magit-status-mode");
            let id = e.buffers.by_name("*magit:status*").unwrap();
            e.append_to_owned_buffer(id, "MAGITSTATUSCONTENT\n");
            e.publish_render_state();
        });
        let snap = app.ad().snapshot.clone();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &app, &snap);
            })
            .unwrap();
        let before = screen(&terminal);
        assert!(
            before.contains("MAGITSTATUSCONTENT"),
            "sanity: the magit buffer's own text must be on screen before `:` \
             — otherwise the assertions below prove nothing; got:\n{before}",
        );
        assert!(
            !before.contains("ORIGINFILECONTENT"),
            "sanity: the magit buffer replaced the origin file in the pane",
        );

        app.mutate_editor(|e| {
            e.open_command_line("");
            e.publish_render_state();
        });
        let snap = app.ad().snapshot.clone();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &app, &snap);
            })
            .unwrap();
        let during = screen(&terminal);
        assert!(
            !during.contains("ORIGINFILECONTENT"),
            "opening `:` in a magit buffer must not repaint the pane with the \
             file magit was opened from; got:\n{during}",
        );
        assert!(
            during.contains("MAGITSTATUSCONTENT"),
            "the pane must keep painting the magit buffer's own text while \
             the `:` line is open; got:\n{during}",
        );
    }

    /// MG.51: **the prompt line shows what you type.**
    ///
    /// `Effect::OpenPrompt` (magit's branch checkout, tag name, …) puts
    /// the LABEL in the echo and the typed text in the `*prompt-line*`
    /// buffer. `draw_command_or_echo` had no `ModalState::Prompt` arm,
    /// so the row fell through to the echo and drew the label alone —
    /// keys reached the buffer and submitting worked, so the prompt read
    /// as a dead input that mysteriously did the right thing.
    ///
    /// Seeded through `initial` rather than keypresses: the defect is in
    /// what gets DRAWN, and `initial` puts text in the same buffer the
    /// dispatcher writes to.
    #[test]
    fn the_prompt_line_renders_the_text_being_typed() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let mut app = app_with("x\n", 10);
        let mut terminal = Terminal::new(TestBackend::new(60, 12)).unwrap();

        app.mutate_editor(|e| {
            e.open_prompt_line(
                "Checkout branch/revision: ".to_string(),
                "feature/x".to_string(),
                "action:magit-global-branch-checkout".to_string(),
                None,
            );
            e.publish_render_state();
        });

        let snap = app.ad().snapshot.clone();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &app, &snap);
            })
            .unwrap();
        let buf = terminal.backend().buffer().clone();
        let out: String = (0..12u16)
            .map(|y| {
                (0..60u16)
                    .map(|x| buf[(x, y)].symbol().to_string())
                    .collect::<String>()
            })
            .collect::<Vec<_>>()
            .join("\n");

        assert!(
            out.contains("Checkout branch/revision:"),
            "the label must still show; got:\n{out}"
        );
        assert!(
            out.contains("feature/x"),
            "the TYPED TEXT must show — this is the bug: the label \
             rendered and the input did not; got:\n{out}"
        );
    }

    /// Evidence test for the preview-switch "bleeding" report: render a LONG
    /// active document, then a SHORT one (the binary-placeholder case), to
    /// the same TestBackend terminal. After the switch, NO row may still
    /// show the long document's content. If this FAILS, the per-frame render
    /// isn't clearing vacated rows (a real render bug). If it PASSES, the
    /// on-screen bleed is an out-of-band terminal write, not the renderer.
    #[test]
    fn shrinking_active_document_clears_vacated_rows() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let dir = std::env::temp_dir().join(format!("lattice-bleed-{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        let long = dir.join("long.txt");
        let short = dir.join("short.txt");
        let body: String = (0..30)
            .map(|i| format!("members entry line {i} XXXXXXXXXXXXXXXXXXXX\n"))
            .collect();
        std::fs::write(&long, &body).unwrap();
        std::fs::write(&short, "only one line\n").unwrap();

        let mut app = app_with("origin\n", 24);
        let mut terminal = Terminal::new(TestBackend::new(80, 26)).unwrap();

        let row_text = |buf: &ratatui::buffer::Buffer, y: u16| -> String {
            (0..80).map(|x| buf[(x, y)].symbol().to_string()).collect()
        };

        // Frame 1: preview the long file.
        let long_c = long.clone();
        app.mutate_editor(move |e| {
            let _ = e.do_preview(long_c, None);
            e.publish_render_state();
        });
        let snap = app.ad().snapshot.clone();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &app, &snap);
            })
            .unwrap();
        let buf1 = terminal.backend().buffer().clone();
        let frame1_has_long = (0..26u16).any(|y| row_text(&buf1, y).contains("members entry"));
        assert!(
            frame1_has_long,
            "sanity: the long preview must actually render its content"
        );

        // Frame 2: preview the short file (active doc shrinks 30 → 1 line).
        let short_c = short.clone();
        app.mutate_editor(move |e| {
            let _ = e.do_preview(short_c, None);
            e.publish_render_state();
        });
        let snap = app.ad().snapshot.clone();
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &app, &snap);
            })
            .unwrap();
        let buf2 = terminal.backend().buffer().clone();
        // Check BOTH the line START ("members entry") AND the line TAIL
        // ("XXXX…") — the reported bleed is the trailing chars, which a
        // start-only check would miss.
        let stale: Vec<(u16, String)> = (0..26u16)
            .filter_map(|y| {
                let r = row_text(&buf2, y);
                if r.contains("members entry") || r.contains("XXXX") {
                    Some((y, r.trim_end().to_string()))
                } else {
                    None
                }
            })
            .collect();

        std::fs::remove_dir_all(&dir).ok();
        assert!(
            stale.is_empty(),
            "stale long-file content after switching to a short preview: {stale:?}"
        );
    }

    // ---- W.4: body wrap segment splitting ----

    #[test]
    fn split_body_wrap_off_or_fits_is_single_segment() {
        let body = vec![Span::raw("hello world")];
        // width 0 ⇒ wrap off.
        assert_eq!(split_body_into_segments(body.clone(), 0, 11).len(), 1);
        // fits within width ⇒ single segment.
        assert_eq!(split_body_into_segments(body, 80, 11).len(), 1);
    }

    #[test]
    fn split_body_trailing_decoration_never_breaks_a_segment() {
        // Regression (2026-08-08): the closed-fold ` ⋯ N lines`
        // summary is appended to the body AFTER the source spans, so
        // it used to push a heading that fits on one row onto two —
        // one more row than `wrap_segments(col_count, width)`, which
        // is what the host's scroll model and the caret walk count.
        // Trailing decoration rides the final segment instead.
        let src = Span::raw("0123456789"); // 10 source columns
        let deco = Span::raw(" ⋯ 4 lines"); // 10 decoration columns
        let body = vec![src.clone(), deco.clone()];
        let segs = split_body_into_segments(body, 12, 10);
        assert_eq!(
            segs.len(),
            lattice_cells::wrap_segments(10, 12) as usize,
            "decoration past `wrap_cols` must not create a display row"
        );

        // The source axis still wraps normally, and the decoration
        // lands on the LAST segment.
        let body = vec![src, deco];
        let segs = split_body_into_segments(body, 4, 10);
        assert_eq!(segs.len(), lattice_cells::wrap_segments(10, 4) as usize);
        let text =
            |s: &[Span<'static>]| -> String { s.iter().map(|sp| sp.content.as_ref()).collect() };
        assert_eq!(text(&segs[0]), "0123");
        assert_eq!(text(&segs[1]), "4567");
        assert_eq!(text(&segs[2]), "89 ⋯ 4 lines");
    }

    #[test]
    fn w4t1_source_byte_maps_to_expanded_body_position() {
        // W.4.t.1: overlays carry SOURCE bytes, but the cell body has
        // tabs expanded; the mapping must land them on the right cell.
        // tabstop 4. "\tfoo": tab fills col 0→4, then "foo".
        let line = "\tfoo";
        assert_eq!(source_byte_to_body_col(line, 0, 4), 0); // before the tab
        assert_eq!(source_byte_to_body_col(line, 1, 4), 4); // after tab → col 4 ('f')
        assert_eq!(source_byte_to_body_col(line, 4, 4), 7); // after "foo" → col 7 (EOL)
        // Mid-line tab "a\tb": 'a' at 0, tab fills 1→4, 'b' at col 4.
        let line2 = "a\tb";
        assert_eq!(source_byte_to_body_col(line2, 1, 4), 1); // after 'a'
        assert_eq!(source_byte_to_body_col(line2, 2, 4), 4); // after tab
        assert_eq!(source_byte_to_body_col(line2, 3, 4), 5); // after 'b'
        // ASCII without tabs: identity (col == byte) ⇒ plain code unchanged.
        assert_eq!(source_byte_to_body_col("hello", 3, 4), 3);
        // nth_char_byte walks the expanded body "    foo" by char index.
        let body = "    foo";
        assert_eq!(nth_char_byte(body, 4), 4); // 4th char = 'f'
        assert_eq!(nth_char_byte(body, 7), body.len()); // past end clamps to EOL
        // Composed: source byte 1 of "\tfoo" → body byte 4 (start of "foo").
        assert_eq!(nth_char_byte(body, source_byte_to_body_col(line, 1, 4)), 4);
    }

    #[test]
    fn split_body_breaks_at_width_preserving_styles() {
        // Two styled spans: "abcd" + "efghij" = 10 cols, width 4 ⇒
        // segments [abcd][efgh][ij]. Styles must survive the split.
        let red = TuiStyle::default().fg(Color::Red);
        let blue = TuiStyle::default().fg(Color::Blue);
        let body = vec![Span::styled("abcd", red), Span::styled("efghij", blue)];
        let segs = split_body_into_segments(body, 4, 10);
        assert_eq!(segs.len(), 3);
        let text =
            |s: &[Span<'static>]| -> String { s.iter().map(|sp| sp.content.as_ref()).collect() };
        assert_eq!(text(&segs[0]), "abcd");
        assert_eq!(text(&segs[1]), "efgh");
        assert_eq!(text(&segs[2]), "ij");
        // Segment 0 is fully red; segment 1 spans the red→blue
        // boundary ("e" was blue, but so is the rest of seg1).
        assert_eq!(segs[0][0].style.fg, Some(Color::Red));
        assert_eq!(segs[1][0].style.fg, Some(Color::Blue));
        // Total column count matches ⌈10/4⌉ = 3 segments — the
        // host's `CellMatrix::segment_count` agrees.
        assert_eq!(segs.len(), lattice_cells::wrap_segments(10, 4) as usize);
    }

    // ---- IG.3: indentation-guide pre-pass ----

    fn guide_style() -> IndentGuideStyle {
        IndentGuideStyle {
            glyph: Some('\u{2502}'),
            normal: TuiStyle::default().fg(Color::DarkGray),
            active: TuiStyle::default().fg(Color::White),
            active_block: None,
        }
    }

    fn marks(cols: &[u16]) -> Vec<lattice_host::indent_guides::GuideMark> {
        cols.iter()
            .enumerate()
            .map(|(i, c)| lattice_host::indent_guides::GuideMark {
                col: *c,
                block: i as u16,
            })
            .collect()
    }

    /// Apply guides the way the compose loop does with no horizontal scroll.
    fn guides_on(body: &str, cols: &[u16], style: &IndentGuideStyle) -> Vec<Span<'static>> {
        let spans = if body.is_empty() {
            Vec::new()
        } else {
            vec![Span::raw(body.to_string())]
        };
        apply_indent_guides(spans, &marks(cols), style, 0, u32::MAX)
    }

    #[test]
    fn indent_guides_noop_without_marks_or_glyph() {
        let input = vec![Span::raw("        work();".to_string())];
        let out = apply_indent_guides(input.clone(), &[], &guide_style(), 0, u32::MAX);
        assert_eq!(spans_text(&out), spans_text(&input));

        let mut off = guide_style();
        off.glyph = None;
        let out = apply_indent_guides(input.clone(), &marks(&[0, 4]), &off, 0, u32::MAX);
        assert_eq!(spans_text(&out), spans_text(&input), "empty glyph disables");
    }

    #[test]
    fn indent_guides_substitute_at_marked_columns() {
        let out = guides_on("        work();", &[0, 4], &guide_style());
        let rendered = spans_text(&out);
        assert_eq!(rendered, "\u{2502}   \u{2502}   work();");
        // Width is preserved: one char in, one char out. A guide that
        // widened the row would shift every column right of it, and the
        // overlay remap downstream indexes by column.
        assert_eq!(rendered.chars().count(), "        work();".chars().count());
    }

    #[test]
    fn indent_guides_never_replace_a_non_blank_character() {
        // The producer only marks blank columns, so this asserts the
        // renderer honours that rather than re-deriving it: every char the
        // pass replaced must have been a space.
        let line = "        work();";
        let out = guides_on(line, &[0, 4], &guide_style());
        for (i, ch) in spans_text(&out).chars().enumerate() {
            if ch == '\u{2502}' {
                assert_eq!(
                    line.chars().nth(i),
                    Some(' '),
                    "guide at col {i} replaced a non-blank"
                );
            }
        }
    }

    #[test]
    fn indent_guides_pad_a_blank_row() {
        // The blank-line-inside-a-block case: nothing to substitute into,
        // so the pass pads out to each marked column.
        let out = guides_on("", &[0, 4], &guide_style());
        assert_eq!(spans_text(&out), "\u{2502}   \u{2502}");
    }

    #[test]
    fn indent_guides_pad_from_a_short_body() {
        // A body shorter than its marks: substitute what exists, pad the
        // rest out to the absolute column each guide belongs at.
        let out = guides_on("  ", &[0, 4], &guide_style());
        assert_eq!(spans_text(&out), "\u{2502}   \u{2502}");
    }

    #[test]
    fn indent_guides_style_the_active_block_apart() {
        let mut style = guide_style();
        style.active_block = Some(1); // marks(&[0, 4]) gives block 1 col 4
        let out = guides_on("        work();", &[0, 4], &style);
        let guides: Vec<TuiStyle> = out
            .iter()
            .filter(|s| s.content.as_ref() == "\u{2502}")
            .map(|s| s.style)
            .collect();
        assert_eq!(guides.len(), 2);
        assert_eq!(guides[0], style.normal, "outer guide stays normal");
        assert_eq!(guides[1], style.active, "enclosing block is highlighted");
    }

    #[test]
    fn indent_guides_survive_a_multi_span_body() {
        // Syntax colouring splits the leading whitespace across runs; the
        // walk is by column, not by span, so the guide still lands.
        let body = vec![
            Span::styled("    ".to_string(), TuiStyle::default()),
            Span::styled("    ".to_string(), TuiStyle::default().fg(Color::Blue)),
            Span::styled("work();".to_string(), TuiStyle::default().fg(Color::Red)),
        ];
        let out = apply_indent_guides(body, &marks(&[0, 4]), &guide_style(), 0, u32::MAX);
        assert_eq!(spans_text(&out), "\u{2502}   \u{2502}   work();");
    }

    #[test]
    fn indent_guides_replace_whitespace_markers_at_their_column() {
        // `:set list` has already decorated the indentation. A guide and a
        // leading-whitespace marker want the same cell; the guide wins,
        // because it carries structure and the marker only says "space".
        let out = guides_on("\u{b7}\u{b7}\u{b7}\u{b7}work();", &[0], &guide_style());
        assert_eq!(spans_text(&out), "\u{2502}\u{b7}\u{b7}\u{b7}work();");
    }

    #[test]
    fn indent_guides_pan_with_leftcol() {
        // Guides run after the clip, so a horizontally scrolled body gets
        // its marks translated: the column-4 guide lands at body column 0
        // and the column-0 guide has scrolled off.
        let clipped =
            clip_spans_horizontally(vec![Span::raw("        work();".to_string())], 4, 40);
        let out = apply_indent_guides(clipped, &marks(&[0, 4]), &guide_style(), 4, 40);
        assert_eq!(spans_text(&out), "\u{2502}   work();");
    }

    #[test]
    fn indent_guides_do_not_shorten_the_clipped_body() {
        // The regression this ordering exists to prevent: the clip measures
        // in BYTES, so substituting three-byte glyphs ahead of it would eat
        // two columns of real text per guide.
        let line = "        work();  tail";
        let clipped = clip_spans_horizontally(vec![Span::raw(line.to_string())], 0, 21);
        let out = apply_indent_guides(clipped, &marks(&[0, 4]), &guide_style(), 0, 21);
        assert_eq!(
            spans_text(&out).chars().count(),
            21,
            "every column the clip kept survives the guide pass"
        );
        assert!(spans_text(&out).ends_with("tail"));
    }

    #[test]
    fn indent_guides_outside_the_viewport_are_dropped() {
        // A guide past the right edge must not pad the row out past it.
        let out = apply_indent_guides(Vec::new(), &marks(&[0, 40]), &guide_style(), 0, 8);
        assert_eq!(spans_text(&out), "\u{2502}");
    }

    // ---- M.7.3.b: whitespace decoration pre-pass ----

    fn ws_decoration_default() -> WhitespaceDecoration {
        // Mirrors the emacs-default option set: tab, trailing,
        // leading on; space + EOL off.
        WhitespaceDecoration {
            tab: Some('→'),
            trailing: Some('·'),
            leading: Some('·'),
            space: None,
            eol: None,
            style_normal: TuiStyle::default().fg(Color::DarkGray),
            style_trailing: TuiStyle::default().fg(Color::Red),
        }
    }

    fn spans_text(spans: &[Span<'static>]) -> String {
        spans.iter().map(|s| s.content.as_ref()).collect()
    }

    #[test]
    fn whitespace_decoration_noop_when_all_disabled() {
        let mut d = ws_decoration_default();
        d.tab = None;
        d.trailing = None;
        d.leading = None;
        let line = "  hello \t  ";
        let input: Vec<Span<'static>> = vec![Span::raw(line.to_string())];
        let out = apply_whitespace_decoration(input.clone(), line, &d);
        assert_eq!(spans_text(&out), spans_text(&input));
    }

    #[test]
    fn whitespace_decoration_substitutes_tab_glyph() {
        let d = ws_decoration_default();
        let line = "abc\tdef";
        let input = vec![Span::raw(line.to_string())];
        let out = apply_whitespace_decoration(input, line, &d);
        let rendered = spans_text(&out);
        assert!(rendered.contains('→'), "tab glyph missing: {rendered:?}");
        assert!(!rendered.contains('\t'), "raw tab leaked: {rendered:?}");
    }

    #[test]
    fn whitespace_decoration_marks_trailing_in_red() {
        let d = ws_decoration_default();
        let line = "hello   "; // three trailing spaces
        let input = vec![Span::raw(line.to_string())];
        let out = apply_whitespace_decoration(input, line, &d);
        // Trailing dots present.
        let rendered = spans_text(&out);
        let dot_count = rendered.chars().filter(|c| *c == '·').count();
        assert_eq!(dot_count, 3, "expected 3 trailing dots, got {rendered:?}");
        // Each trailing-glyph span carries the trailing style.
        let trailing_spans: Vec<_> = out.iter().filter(|s| s.content.as_ref() == "·").collect();
        assert_eq!(trailing_spans.len(), 3);
        for s in trailing_spans {
            assert_eq!(s.style.fg, Some(Color::Red), "trailing should be red");
        }
    }

    #[test]
    fn whitespace_decoration_marks_leading_with_normal_style() {
        let d = ws_decoration_default();
        let line = "  hello";
        let input = vec![Span::raw(line.to_string())];
        let out = apply_whitespace_decoration(input, line, &d);
        // Two leading dots.
        let dot_spans: Vec<_> = out.iter().filter(|s| s.content.as_ref() == "·").collect();
        assert_eq!(dot_spans.len(), 2);
        // Leading uses style_normal (DarkGray), not trailing's red.
        for s in dot_spans {
            assert_eq!(s.style.fg, Some(Color::DarkGray));
        }
    }

    #[test]
    fn whitespace_decoration_trailing_wins_over_leading_for_pure_ws_line() {
        // A line that's nothing but whitespace: trailing
        // covers the whole range (last_non_ws = 0) and trailing
        // has higher precedence than leading.
        let d = ws_decoration_default();
        let line = "   ";
        let input = vec![Span::raw(line.to_string())];
        let out = apply_whitespace_decoration(input, line, &d);
        let dots: Vec<_> = out.iter().filter(|s| s.content.as_ref() == "·").collect();
        assert_eq!(dots.len(), 3);
        for s in dots {
            assert_eq!(
                s.style.fg,
                Some(Color::Red),
                "pure-ws line should be all trailing-marked",
            );
        }
    }

    #[test]
    fn whitespace_decoration_does_not_mark_mid_text_space_when_disabled() {
        // `space: None` (default): mid-text spaces stay bare.
        let d = ws_decoration_default();
        let line = "a b c";
        let input = vec![Span::raw(line.to_string())];
        let out = apply_whitespace_decoration(input, line, &d);
        let rendered = spans_text(&out);
        // No dots (no leading / trailing in this line).
        assert!(!rendered.contains('·'), "should be bare: {rendered:?}");
        // The bare spaces are preserved.
        assert!(rendered.contains("a b c"), "got: {rendered:?}");
    }

    #[test]
    fn whitespace_decoration_marks_mid_text_space_when_enabled() {
        let mut d = ws_decoration_default();
        d.space = Some('·');
        let line = "a b c";
        let input = vec![Span::raw(line.to_string())];
        let out = apply_whitespace_decoration(input, line, &d);
        let dots = spans_text(&out).chars().filter(|c| *c == '·').count();
        assert_eq!(dots, 2);
    }

    // ---- M.7.3.c: current-line highlight ----

    fn span_with_bg<'a>(line: &'a Line<'_>, expected_bg: Color) -> Option<&'a Span<'a>> {
        line.spans.iter().find(|s| s.style.bg == Some(expected_bg))
    }

    #[test]
    fn current_line_highlight_off_emits_no_special_bg() {
        // Default state: the option is off ⇒ cursor row has no
        // bg from the highlight pass.
        let app = app_with("hello\nworld\n", 5);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        for line in &lines {
            assert!(
                span_with_bg(line, Color::Indexed(236)).is_none(),
                "no cursor-line bg expected when off",
            );
        }
    }

    #[test]
    fn current_line_highlight_on_paints_cursor_row_bg() {
        // Activate `current-line-highlight-mode`; the cursor's
        // row should pick up the theme's cursor_line_bg.
        let mut app = app_with("hello\nworld\n", 5);
        app.toggle_mode_by_name("current-line-highlight-mode");
        // Cursor starts on line 0; verify its row has the bg.
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let cursor_row = &lines[0];
        assert!(
            span_with_bg(cursor_row, Color::Indexed(236)).is_some(),
            "cursor row should have cursor_line_bg: {cursor_row:?}",
        );
        // Non-cursor row stays clean.
        let other_row = &lines[1];
        assert!(
            span_with_bg(other_row, Color::Indexed(236)).is_none(),
            "other rows should not have cursor_line_bg: {other_row:?}",
        );
    }

    #[test]
    fn current_line_highlight_pads_to_pane_width() {
        // Even on a short line, the highlight should reach
        // the right edge -- the renderer appends a pad-span
        // with bg-only style.
        let mut app = app_with("hi\n", 5);
        app.toggle_mode_by_name("current-line-highlight-mode");
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let cursor_row = &lines[0];
        // Find any pad span: bg = cursor_line_bg, content all
        // spaces.
        let pad = cursor_row.spans.iter().find(|s| {
            s.style.bg == Some(Color::Indexed(236))
                && s.content.chars().all(|c| c == ' ')
                && s.content.len() > 1
        });
        assert!(pad.is_some(), "expected a pad span: {cursor_row:?}",);
    }

    #[test]
    fn whitespace_show_mode_off_produces_no_decoration_in_pipeline() {
        // Default state: whitespace-show-mode is inactive ⇒
        // `option_cache.show_whitespace == false` ⇒ pre-pass
        // is skipped ⇒ rendered body shows raw text.
        let app = app_with("hello   \n", 5);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(!row0.contains('·'), "no dots when ws-mode off: {row0:?}");
    }

    #[test]
    fn whitespace_show_mode_on_produces_trailing_dots_in_pipeline() {
        // Activate `whitespace-show-mode` (cascade flips
        // `Whitespace=true`); the renderer's pipeline wires
        // through the cache and pre-pass kicks in.
        let mut app = app_with("hello   \n", 5);
        app.toggle_mode_by_name("whitespace-show-mode");
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            row0.contains("hello") && row0.contains('·'),
            "ws-mode on should show content + trailing dots: {row0:?}",
        );
    }

    /// W.4.t.2: the same assertion as the sibling above, but with a
    /// **late worker write** — a rebuild that was already in flight when
    /// the toggle landed and finishes afterwards, storing cells built
    /// under the PRE-toggle whitespace config into the pane's (shared,
    /// stable-identity) matrix cell. Nothing re-runs the worker after
    /// that, so this is the state a frame paints from.
    ///
    /// The builder bakes whitespace markers into `Cell.ch` at emission
    /// and the compose-loop pre-pass deliberately skips cell-derived
    /// bodies (re-decorating would desync source bytes), so without the
    /// whitespace axis in the staleness guard the frame paints
    /// undecorated text and `:set list` looks like it did nothing.
    ///
    /// This is the deterministic form of a flake: pre-fix, the sibling
    /// test failed whenever the real worker lost this race (~50% of
    /// full-suite runs under `--features system-clipboard`, green in
    /// isolation).
    #[test]
    fn whitespace_shows_dots_when_a_late_worker_write_predates_the_toggle() {
        let mut app = app_with("hello   \n", 5);
        app.editor.publish_render_state();
        let pane_id = app.panes().tree.active().id;
        // Capture the PRE-toggle worker inputs: version stamp + whitespace
        // config as they were when the in-flight rebuild started.
        let stale_inputs = app.editor.render_state.load().cells.load_full();
        assert!(
            !stale_inputs.whitespace.show,
            "precondition: the in-flight rebuild started with whitespace off"
        );
        // Toggle whitespace on. The option cascade republishes (and
        // rebuilds) with the new config.
        app.toggle_mode_by_name("whitespace-show-mode");

        // The painted matrix's whitespace stamp, and the stamp a matrix
        // built now would carry.
        let stamps = || {
            let live = app.editor.render_state.load().cells.load_full();
            let painted = live
                .display_matrix_for_pane(pane_id)
                .expect("pane matrix")
                .load()
                .version
                .whitespace;
            (painted, live.whitespace_version_for_pane(pane_id))
        };
        // The toggle also woke the LIVE cells worker, which rebuilds on its
        // own thread. If that rebuild lands after the replay below, it
        // overwrites the stale stamp and the precondition fails: a race in
        // this test's SETUP, lost more often the busier the suite is (it
        // failed 3 of 4 full runs on 2026-09-15 and never alone). So wait for
        // the worker to catch up with the toggle first. The budget is only
        // spent if the worker never rebuilds, in which case there is no race.
        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
        while {
            let (painted, current) = stamps();
            painted != current
        } && std::time::Instant::now() < deadline
        {
            std::thread::sleep(std::time::Duration::from_millis(10));
        }

        // Now the in-flight rebuild lands, stamping the pane's matrix cell
        // with the pre-toggle version + undecorated cells.
        let pane = stale_inputs
            .panes
            .iter()
            .find(|p| p.pane_id == pane_id)
            .expect("active document pane present in cells inputs");
        let replay_stale_write = || {
            let _ = lattice_host::cells_worker::recompute_pane(
                pane,
                lattice_host::cells_worker::CellTheme {
                    resolved: &stale_inputs.resolved_theme,
                    ids: &stale_inputs.theme_ids,
                },
                &stale_inputs.whitespace,
            );
        };
        replay_stale_write();
        // A coalesced tail rebuild can still land once more. Only the setup is
        // retried here; the assertions below run once, against a matrix that
        // is stale when they start.
        while {
            let (painted, current) = stamps();
            painted == current
        } && std::time::Instant::now() < deadline
        {
            std::thread::sleep(std::time::Duration::from_millis(10));
            replay_stale_write();
        }
        let (painted, current) = stamps();
        assert_ne!(
            painted, current,
            "precondition: the painted matrix carries the pre-toggle \
             whitespace stamp"
        );
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            row0.contains("hello") && row0.contains('·'),
            "a stale-whitespace matrix must fall back to the raw-text \
             pre-pass so the glyphs appear on this frame: {row0:?}",
        );
    }

    #[test]
    fn whitespace_decoration_appends_eol_glyph_when_enabled() {
        let mut d = ws_decoration_default();
        d.eol = Some('¬');
        let line = "hello";
        let input = vec![Span::raw(line.to_string())];
        let out = apply_whitespace_decoration(input, line, &d);
        let rendered = spans_text(&out);
        assert!(rendered.ends_with('¬'), "got: {rendered:?}");
    }

    #[test]
    fn whitespace_decoration_preserves_syntax_highlight_around_substitutions() {
        // Two-span input simulating syntax highlight: keyword
        // span + raw rest. The whitespace pre-pass should keep
        // the keyword's style on its non-whitespace content
        // and split out a separate trailing-styled span for the
        // trailing dots.
        let kw_style = TuiStyle::default().fg(Color::Yellow);
        let line = "fn main()  ";
        let input = vec![
            Span::styled("fn".to_string(), kw_style),
            Span::raw(" main()  ".to_string()),
        ];
        let d = ws_decoration_default();
        let out = apply_whitespace_decoration(input, line, &d);
        // Keyword span survives unchanged.
        assert!(
            out.iter()
                .any(|s| s.content.as_ref() == "fn" && s.style.fg == Some(Color::Yellow)),
            "keyword span lost: {out:?}",
        );
        // Two trailing dots present + red.
        let trailing: Vec<_> = out
            .iter()
            .filter(|s| s.content.as_ref() == "·" && s.style.fg == Some(Color::Red))
            .collect();
        assert_eq!(trailing.len(), 2);
    }

    /// The host's gutter reservation must equal what this renderer
    /// actually paints, for every combination of the two options that
    /// change it.
    ///
    /// 2026-08-16: they differed by one column. `gutter_cols` accounted
    /// for the severity column but not the diff-sign column added later,
    /// so the host's soft-wrap width was one wider than the painted one.
    /// A line whose length fell exactly between the two wrapped on screen
    /// but not in the scroll budget, and the extra rendered row pushed
    /// the cursor below the last painted line — `G` on a 219-line
    /// todo.org with a 173-character line, host width 173, renderer 172.
    ///
    /// A previous fix for the same symptom made the host's two clamps
    /// share `gutter_cols` with each other. They agreed, and both
    /// disagreed with what was painted — which is why this test asserts
    /// across the crate boundary rather than within the host.
    #[test]
    fn gutter_cols_matches_the_tui_gutter() {
        for lines in [1u32, 9, 10, 99, 100, 219, 1000, 12345] {
            for numbers in [true, false] {
                for signs in [true, false] {
                    let painted = (if numbers {
                        gutter_width(lines)
                    } else {
                        GUTTER_TRAILING_PAD
                    }) + if signs {
                        lattice_mode::BUILTIN_SIGN_COLUMNS.len() as u32
                    } else {
                        0
                    };
                    let reserved = lattice_host::cells_worker::gutter_cols(lines, numbers, signs);
                    assert_eq!(
                        reserved, painted,
                        "lines={lines} number={numbers} signcolumn={signs}: the host \
                         reserves {reserved} columns, the renderer paints {painted}"
                    );
                }
            }
        }
    }

    #[test]
    fn gutter_width_for_small_buffers() {
        // Layout: 1 leading pad + N digits + GUTTER_TRAILING_PAD (3)
        // = N + 4 cells. 1-digit numbers => 5 cells (" 1   "),
        // 2-digit => 6 (" 99   "), 3-digit => 7 ("100   ").
        assert_eq!(gutter_width(1), 5);
        assert_eq!(gutter_width(9), 5);
        assert_eq!(gutter_width(10), 6);
        assert_eq!(gutter_width(99), 6);
        assert_eq!(gutter_width(100), 7);
    }

    /// Concatenate a gutter's span contents back into one string.
    fn gutter_text(spans: &[Span<'static>]) -> String {
        spans.iter().map(|s| s.content.as_ref()).collect()
    }

    #[test]
    fn render_gutter_separates_number_from_buffer_with_two_cells() {
        // Layout: `[lead][digits][space][glyph_or_space]`. With no
        // fold the rightmost cell is a plain space, so output ends
        // in two spaces -- one separator between digits and glyph
        // slot, one empty glyph slot. No fold ⇒ a single span.
        let spans = render_gutter(0, gutter_width(1), None);
        assert_eq!(spans.len(), 1, "no-fold gutter is one span: {spans:?}");
        let s = gutter_text(&spans);
        assert!(s.ends_with("  "), "expected two trailing spaces, got {s:?}");
        assert!(s.contains('1'), "line number missing: {s:?}");
    }

    #[test]
    fn render_gutter_places_glyph_near_buffer_with_a_gap() {
        // Closed fold ▸ sits near the buffer column, with a separator
        // space before it and a one-cell gap after it so the glyph
        // doesn't run flush against code -- the `[ 1 ▸ ]` layout. The
        // glyph rides its own themed span so its colour is independent
        // of the dim line-number tone.
        let spans = render_gutter(0, gutter_width(1), Some(('▸', Color::Yellow)));
        let s = gutter_text(&spans);
        assert!(s.contains(" 1 ▸ "), "expected ' 1 ▸ ' shape, got {s:?}");
        assert!(s.ends_with("▸ "), "glyph must have a trailing gap: {s:?}");
        // Exactly one span carries the glyph, in the themed colour.
        let glyph_spans: Vec<_> = spans
            .iter()
            .filter(|sp| sp.content.as_ref() == "▸")
            .collect();
        assert_eq!(glyph_spans.len(), 1, "glyph is its own span: {spans:?}");
        assert_eq!(glyph_spans[0].style.fg, Some(Color::Yellow));
    }

    #[test]
    fn compose_visible_lines_returns_height_lines_padded_with_marker() {
        let app = app_with("a\nb", 5);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        assert_eq!(lines.len(), 5);
        // Past EOF lines start with the `~` marker.
        let past_eof = format!("{:?}", lines[3]);
        assert!(past_eof.contains('~'), "expected ~ marker, got {past_eof}");
    }

    /// Set an option the way `:set` does, then republish.
    ///
    /// Poking `editor.option_cache.<field>` directly used to work because the
    /// active pane's `FrameView` read that cache. It reads the PUBLISHED
    /// per-buffer resolved options now (PI.4, shared with the GPUI peer), so a
    /// cache poke sets a field nothing consults. Going through the real
    /// option path is what these tests meant all along — they are about what
    /// `:set signcolumn=no` renders, not about a struct field.
    fn set_opt(app: &mut App, spec: &str) {
        let spec = spec.to_string();
        app.mutate_editor(move |e| {
            e.handle_effect(lattice_grammar::Effect::SetOption { spec });
            e.publish_render_state();
        });
    }

    #[test]
    fn compose_wraps_long_line_when_wrap_on() {
        // 36-char single line; narrow total width forces wrapping.
        let long = "abcdefghijklmnopqrstuvwxyz0123456789";
        let mut app = app_with(long, 10);
        set_opt(&mut app, "wrap=true");
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 10, 20);
        let texts: Vec<String> = lines.iter().map(line_text).collect();
        // Wrapping produces ↪ continuation gutters …
        assert!(
            texts.iter().any(|t| t.contains('↪')),
            "expected a ↪ continuation row, got {texts:?}"
        );
        // … and the tail of the long line still renders (not clipped
        // away as it was with horizontal-scroll truncation). The
        // final segment carries the end of the line.
        assert!(
            texts.iter().any(|t| t.contains("23456789")),
            "wrapped tail must render in a continuation segment, got {texts:?}"
        );
    }

    #[test]
    fn compose_does_not_wrap_when_wrap_off() {
        let long = "abcdefghijklmnopqrstuvwxyz0123456789";
        let app = app_with(long, 10); // wrap defaults off
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 10, 20);
        let texts: Vec<String> = lines.iter().map(line_text).collect();
        assert!(
            !texts.iter().any(|t| t.contains('↪')),
            "wrap off ⇒ no continuation rows, got {texts:?}"
        );
    }

    #[test]
    fn signcolumn_no_and_nonumber_drops_sign_and_number_columns() {
        // PU.1b-1a: gutter geometry is option-derived, never
        // kind-derived. With `signcolumn=no` + `nonu` a document line
        // abuts the 2-cell no-number margin — no severity/diff sign
        // cells, no line-number gutter. This is exactly the geometry
        // help-mode gets via its option overrides; the renderer does
        // not know (or care) which buffer kind it is painting.
        let mut app = app_with("hello\nworld\n", 5);

        // Default (`signcolumn=yes` + `number=yes`) reserves the sign
        // cells + the line-number gutter, so content sits further in.
        let default0 =
            line_text(&compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 40)[0]);
        let default_indent = default0.find("hello").expect("hello rendered");
        assert!(
            default_indent >= 3,
            "default reserves 2 sign cells + a line-number gutter; got indent \
             {default_indent} in {default0:?}"
        );

        // `signcolumn=no` + `nonu`: only the fold-marker gutter remains
        // (separator + fold slot + trailing gap = 3 cells, so a fold `▸`
        // still shows with numbers off), and the body starts at column 3.
        set_opt(&mut app, "signcolumn=no");
        set_opt(&mut app, "number=false");
        let lean0 = line_text(&compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 40)[0]);
        assert_eq!(
            lean0.find("hello"),
            Some(3),
            "signcolumn=no + nonu ⇒ content at the 3-cell fold gutter, got {lean0:?}"
        );
    }

    /// Reported 2026-08-09: typing in the magit commit buffer drew the
    /// caret one cell to the LEFT of the insertion point — on the last
    /// character typed rather than after it.
    ///
    /// Not commit-specific: `magit-commit-mode` sets `Number = false`,
    /// and that is the whole trigger. `format_gutter_cell` ALWAYS emits
    /// three trailing cells (separator + fold-glyph slot + gap), but the
    /// `nonumber` gutter width was declared as `2`, so its
    /// `saturating_sub(label_cols + 3)` clamped to zero and the cell came
    /// out 3 wide. The body painted at column 3 while `buffer_w` and the
    /// caret's `sign + gutter_w + body_col` both assumed 2.
    ///
    /// Asserts the invariant that actually matters — the caret column is
    /// the column the NEXT glyph will occupy — with numbers off and on,
    /// so a future change to either gutter branch cannot drift them
    /// apart again.
    #[test]
    fn caret_lands_after_the_last_glyph_with_numbers_off() {
        for numbers in [false, true] {
            let mut app = app_with("abc\n", 5);
            set_opt(
                &mut app,
                if numbers {
                    "number=true"
                } else {
                    "number=false"
                },
            );
            // Insertion point: end of "abc".
            app.editor
                .set_cursor(lattice_protocol::position::Position::new(0, 3));
            app.editor.publish_render_state();
            let snap = app.ad().snapshot.clone();
            let composed = compose_visible_lines(&app, &snap, 5, 40);
            let painted: String = composed[0]
                .spans
                .iter()
                .map(|sp| sp.content.as_ref())
                .collect();
            let body_col = painted.find('a').expect("body painted");
            let area = Rect::new(0, 0, 40, 5);
            let pos = cursor_screen_position_at(
                &FrameView::from_app(&app),
                &snap,
                area,
                app.ad().cursor,
                0,
                app.panes().tree.active().id,
            )
            .expect("caret visible");
            assert_eq!(
                pos.0 as usize,
                body_col + 3,
                "number={numbers}: caret must sit AFTER the last glyph \
                 (body starts at {body_col} in {painted:?})"
            );
        }
    }

    #[test]
    fn clip_spans_horizontally_skips_then_truncates() {
        // "abcdefghij", skip 3, width 4 ⇒ "defg".
        let spans = vec![Span::raw("abcdefghij".to_string())];
        let out = clip_spans_horizontally(spans, 3, 4);
        let joined: String = out.iter().map(|s| s.content.as_ref()).collect();
        assert_eq!(joined, "defg");
    }

    #[test]
    fn clip_spans_horizontally_skip_zero_is_truncate() {
        let spans = vec![Span::raw("abcdef".to_string())];
        let out = clip_spans_horizontally(spans, 0, 3);
        let joined: String = out.iter().map(|s| s.content.as_ref()).collect();
        assert_eq!(joined, "abc");
    }

    #[test]
    fn clip_spans_horizontally_skip_spans_whole_first_span() {
        // Skip crosses a span boundary: ["ab","cdef"], skip 3 ⇒ drop
        // "ab" entirely + 1 byte of "cdef" ⇒ "def" (width 8).
        let spans = vec![Span::raw("ab".to_string()), Span::raw("cdef".to_string())];
        let out = clip_spans_horizontally(spans, 3, 8);
        let joined: String = out.iter().map(|s| s.content.as_ref()).collect();
        assert_eq!(joined, "def");
    }

    #[test]
    fn compose_visible_lines_starts_at_scroll_offset() {
        let mut app = app_with("0\n1\n2\n3\n4", 2);
        app.editor.set_scroll(2);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 2, 80);
        // Line index 2 is "2"; expect that text in the rendered first line.
        let l0 = format!("{:?}", lines[0]);
        assert!(
            l0.contains('2'),
            "first visible line should be '2', got {l0}"
        );
    }

    #[test]
    fn cursor_position_advances_for_byte_offset() {
        let mut app = app_with("hello", 5);
        app.editor.set_cursor_byte(3);
        let area = Rect::new(0, 0, 80, 5);
        let pos =
            cursor_screen_position(&FrameView::from_app(&app), &app.ad().snapshot.clone(), area)
                .unwrap();
        // severity_cell (1) + diff_sign_cell (1) + gutter_width(1)=5 + 3 = 10.
        assert_eq!(pos.0, 10);
        assert_eq!(pos.1, 0);
    }

    #[test]
    fn display_col_for_byte_shifts_by_inlay_widths_at_or_before_cursor() {
        // 2026-05-26 regression guard. Inlay hints render inline
        // via `splice_virtual_text_into_spans`, but
        // `display_col_for_byte` historically returned the source-
        // prefix width only — so the cursor lagged the rendered
        // line by the cumulative inlay width once any inlay sat
        // at or before `cursor.byte`. Mirrors GPUI's
        // `byte_to_combined_col` semantics.
        let app = app_with("let x = 42\n", 5);
        let inlays = [lattice_host::render_state::InlayHintRow::hint(
            0,
            5, // after `let x`, before ` =`
            ": i32".to_string(),
        )];
        // Cursor before the inlay anchor: no shift.
        let before = display_col_for_byte(
            &app.ad().snapshot.buffer,
            lattice_protocol::Position::new(0, 4),
            &inlays,
            4,
        );
        assert_eq!(before, 4, "shift must not apply before inlay anchor");
        // Cursor at the inlay anchor: shift applies (splice is
        // BEFORE the source char at the anchor).
        let at = display_col_for_byte(
            &app.ad().snapshot.buffer,
            lattice_protocol::Position::new(0, 5),
            &inlays,
            4,
        );
        assert_eq!(at, 5 + 5, "shift applies at the inlay anchor");
        // Cursor past the inlay anchor (e.g. `$` to last byte):
        // same shift.
        let eol = display_col_for_byte(
            &app.ad().snapshot.buffer,
            lattice_protocol::Position::new(0, 9),
            &inlays,
            4,
        );
        assert_eq!(eol, 9 + 5, "shift carries through to EOL");
        // Empty inlay slice: behaviour matches the pre-inlay path.
        let no_inlay = display_col_for_byte(
            &app.ad().snapshot.buffer,
            lattice_protocol::Position::new(0, 9),
            &[],
            4,
        );
        assert_eq!(no_inlay, 9);
    }

    #[test]
    fn cursor_row_accounts_for_multi_segment_wrap_above_and_within() {
        // W.4.t: a line wrapping into 3 visual rows must shift the
        // cursor row of lines below by 3 (not 1), and the cursor on
        // that wrapped line must land on its own segment. This is
        // the `dd`-deletes-wrong-line bug + the N-segment
        // generalisation.
        //
        // Widths: gutter_width(n) = digits + 3 (lead+sep+glyph);
        // DIAG + DIFF = 2. With width 40 and ≤9 lines ⇒ gutter 4 ⇒
        // body_w = 40 - 4 - 2 = 34. line 1 is 69 chars ⇒ ⌈69/34⌉ = 3
        // segments.
        let body_w = 34usize;
        let long = "x".repeat(2 * body_w + 1); // 69 ⇒ 3 segments
        let text = format!("a\n{long}\nb\n");
        let mut app = app_with(&text, 20);
        app.editor.option_cache.wrap_lines = true;
        app.editor.publish_render_state();
        let area = Rect::new(0, 0, 40, 20);
        let snap = app.ad().snapshot.clone();
        let view = FrameView::from_app(&app);

        // Cursor on line 2 ("b"), below the 3-row wrap of line 1.
        // Display rows: line0 seg0 = 0; line1 segs = 1,2,3; line2 = 4.
        let below = cursor_screen_position_at(
            &view,
            &snap,
            area,
            lattice_protocol::Position::new(2, 0),
            0,
            app.panes().tree.active().id,
        )
        .unwrap();
        assert_eq!(below.1, 4, "line below a 3-row wrap sits at display row 4");

        // Cursor within the wrapped line, in its 3rd segment (byte
        // 68 ⇒ 68/34 = segment 2). Rows: line0=0; line1 seg0=1,
        // seg1=2, seg2=3.
        let within = cursor_screen_position_at(
            &view,
            &snap,
            area,
            lattice_protocol::Position::new(1, 68),
            0,
            app.panes().tree.active().id,
        )
        .unwrap();
        assert_eq!(
            within.1, 3,
            "cursor in the 3rd wrap segment sits at display row 3"
        );
    }

    /// Screen column (char index) where the first non-gutter body char
    /// appears on `composed[row]`. The gutter/marker prefix is all
    /// spaces + at most one glyph; the body starts at the first char
    /// that isn't part of that prefix. We find it by counting the
    /// leading run of prefix cells the compose loop emits, which equals
    /// the display width of the gutter.
    fn body_start_col(line: &Line<'static>, body_first_char: char) -> usize {
        let s: String = line.spans.iter().map(|sp| sp.content.as_ref()).collect();
        s.chars().position(|c| c == body_first_char).unwrap()
    }

    #[test]
    fn wrapped_continuation_gutter_aligns_body_and_cursor() {
        // Regression (2026-07-03): the wrap continuation marker `↪`
        // (U+21AA, 3 bytes / 1 display column) made `format_gutter_cell`
        // under-pad the continuation gutter, because it computed the
        // leading pad from `label.len()` (BYTES) instead of display
        // width. The wrapped body then painted one column LEFT of
        // segment 0's body, while `cursor_screen_position_at` kept using
        // the segment-0 `gutter_w` — so the cursor sat one cell RIGHT of
        // the glyph on every wrapped continuation segment.
        //
        // 56-char ASCII line, viewport 40, line numbers on (default):
        // the gutter is 7 cells (2 sign + 5 = ` 1   ` under the 3-cell
        // trailing pad), so the body is 33 columns; segment 0 body is 33
        // chars and segment 1 starts at source char 33 (the digit '7').
        let long = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRST";
        assert_eq!(long.len(), 56);
        let text = format!("{long}\n");
        let mut app = app_with(&text, 20);
        app.editor.option_cache.wrap_lines = true;
        app.editor.publish_render_state();
        let area = Rect::new(0, 0, 40, 20);
        let snap = app.ad().snapshot.clone();
        let view = FrameView::from_app(&app);

        let composed = compose_pane_lines(
            &view,
            &snap,
            area.height as u32,
            area.width as u32,
            &PaneComposeCtx {
                buffer_id: app.ad().document_buffer_id,
                pane_id: app.panes().tree.active().id,
                is_active: true,
                scroll: 0,
                cursor_line: app.ad().cursor.line,
                cursor_line_highlight: app.ad().option_cache.current_line_highlight,
                leftcol: 0,
                display_line_numbers: app.ad().display_line_numbers.clone(),
            },
        );

        // Segment 0 body ('a') and segment 1 body ('7') must start at the
        // SAME screen column — the continuation gutter is the same width
        // as the numbered gutter, so wrapped text aligns vertically.
        let seg0_col = body_start_col(&composed[0], 'a');
        let seg1_col = body_start_col(&composed[1], '7');
        assert_eq!(
            seg0_col, seg1_col,
            "wrapped continuation body must align with segment 0 body \
             (seg0 at {seg0_col}, continuation at {seg1_col})"
        );

        // And the cursor on a continuation-segment byte must land on the
        // exact screen column where that glyph is painted. Byte 37 is
        // 'B' — the 5th char of segment 1 (source chars 33='7', 34='8',
        // 35='9', 36='A', 37='B'), so painted at `seg1_col + 4`.
        let pos = cursor_screen_position_at(
            &view,
            &snap,
            area,
            lattice_protocol::Position::new(0, 37),
            0,
            app.panes().tree.active().id,
        )
        .unwrap();
        assert_eq!(pos.1, 1, "byte 37 sits on the first wrap continuation row");
        assert_eq!(
            pos.0 as usize,
            seg1_col + 4,
            "cursor column must match the painted glyph column on the \
             continuation segment"
        );
    }

    #[test]
    fn display_col_for_byte_expands_tabs_to_tabstop() {
        // W.4.t: a leading tab advances the cursor to the next
        // tab-stop, matching the cells builder's expansion.
        let app = app_with("\tab", 5);
        let buf = &app.ad().snapshot.buffer;
        let col =
            |byte: u32| display_col_for_byte(buf, lattice_protocol::Position::new(0, byte), &[], 4);
        assert_eq!(col(0), 0, "cursor on the tab sits at its start column");
        assert_eq!(col(1), 4, "'a' after a tab lands at column tabstop");
        assert_eq!(col(2), 5, "'b' follows at column tabstop+1");
    }

    #[test]
    fn cursor_position_uses_display_width_for_multibyte_chars() {
        // `§` is 2 bytes / 1 cell in a terminal. With cursor.byte = 6
        // (the `P` of "Performance" on the line below), the rendered
        // column must be 5 cells in (`-`, ` `, `§`, `8`, ` `, `P`),
        // not 6 -- which is what the byte offset would give us if
        // we used it as the column.
        let mut app = app_with("- §8 Performance commitments", 5);
        app.editor.set_cursor_byte(6);
        let area = Rect::new(0, 0, 80, 5);
        let pos =
            cursor_screen_position(&FrameView::from_app(&app), &app.ad().snapshot.clone(), area)
                .unwrap();
        // severity_cell (1) + diff_sign_cell (1) + gutter_w (5) + 5 = 12.
        assert_eq!(pos.0, 12);
    }

    #[test]
    fn cursor_position_handles_cjk_double_width() {
        // CJK chars are 3 bytes / 2 cells. After "abc中" the cursor
        // at byte 6 (the space after the CJK char) should land at
        // display col 5 (a, b, c, 中=2 cells = total 5 cells).
        let mut app = app_with("abc中 def", 5);
        app.editor.set_cursor_byte(6); // past the 3-byte CJK char
        let area = Rect::new(0, 0, 80, 5);
        let pos =
            cursor_screen_position(&FrameView::from_app(&app), &app.ad().snapshot.clone(), area)
                .unwrap();
        // severity_cell (1) + diff_sign_cell (1) + gutter_w (5) + 5 = 12.
        assert_eq!(pos.0, 12);
    }

    #[test]
    fn cursor_position_is_none_when_out_of_view() {
        let mut app = app_with("a\nb\nc\nd\ne", 2);
        app.editor.set_scroll(0);
        app.editor.set_cursor_line(4); // not in viewport [0,1]
        let area = Rect::new(0, 0, 80, 2);
        assert!(
            cursor_screen_position(&FrameView::from_app(&app), &app.ad().snapshot.clone(), area)
                .is_none()
        );
    }

    #[test]
    fn cursor_inside_closed_fold_renders_at_fold_heading_row() {
        // Buffer: lines 0..6. Closed fold spans lines 2..=4. The
        // cursor sitting on hidden line 3 must render at the
        // heading row (= row 2 in the visible-line list, since
        // scroll=0). Without the fold-aware projection, the
        // cursor would draw at row 3, which doesn't correspond to
        // any drawn buffer line.
        let mut app = app_with("a\nb\nh\nx\ny\nz\nq", 7);
        app.editor
            .set_cursor(lattice_protocol::position::Position::new(3, 0)); // hidden by fold
        // Push a closed fold over lines 2..=4.
        app.editor.folds.push(crate::app::Fold {
            start_line: 2,
            end_line: 4,
            closed: true,
            identity: None,
        });
        // Slice 3c.final.B (group 2): direct fold mutation needs
        // a publish — the renderer reads folds via the published
        // `rs.active_document.load().folds` snapshot now.
        app.editor.publish_render_state();
        let area = Rect::new(0, 0, 80, 7);
        let pos =
            cursor_screen_position(&FrameView::from_app(&app), &app.ad().snapshot.clone(), area)
                .expect("cursor visible");
        // Visible rows: 0=line0, 1=line1, 2=line2 (heading + summary),
        // 3=line5, 4=line6. Cursor at hidden line 3 → screen row 2
        // (area.y + 2 since area.y is 0).
        assert_eq!(
            pos.1,
            area.y + 2,
            "cursor must render on the fold heading row, got row {}",
            pos.1
        );
    }

    /// Row index of the first composed line whose text contains
    /// `needle`, or `None`.
    fn composed_row_containing(lines: &[Line<'static>], needle: &str) -> Option<usize> {
        lines.iter().position(|l| {
            let s: String = l.spans.iter().map(|sp| sp.content.as_ref()).collect();
            s.contains(needle)
        })
    }

    #[test]
    fn closed_fold_summary_does_not_add_a_wrap_row() {
        // Regression (2026-08-08): under `:set wrap` in a narrow pane
        // (a vertical split), the ` ⋯ N lines` summary appended to a
        // closed fold's heading pushed the composed body past the wrap
        // width, so the heading painted on TWO display rows. The caret
        // walk (`buffer_line_to_visible_row_with`) sizes every source
        // line by `wrap_segments(col_count, …)` — the SOURCE width,
        // which knows nothing about the summary — so it counted ONE
        // row. Every line below a closed fold then drew its caret one
        // row ABOVE the cursorline compose painted: cursorline right,
        // cursor a line behind.
        //
        // The summary is decoration, not source text. It must ride the
        // final segment (clipped at the pane edge, as the GPUI peer's
        // end-of-row overlay does) and never create a display row —
        // that is the invariant `split_body_into_segments` documents
        // and the host's scroll model shares.
        let heading = "## a markdown heading of 30 ch";
        assert_eq!(heading.chars().count(), 30);
        let text = format!("{heading}\nh1\nh2\nh3\nTARGET\ntail\n");
        let mut app = app_with(&text, 10);
        app.editor.option_cache.wrap_lines = true;
        app.editor
            .set_cursor(lattice_protocol::position::Position::new(4, 0));
        // Closed fold over lines 0..=3 — summary reads ` ⋯ 4 lines`
        // (10 columns).
        app.editor.folds.push(crate::app::Fold {
            start_line: 0,
            end_line: 3,
            closed: true,
            identity: None,
        });
        app.editor.publish_render_state();

        // width 40 → gutter 5 + sign columns 2 → body width 33.
        // Heading alone (30) fits on one segment; heading + summary
        // (40) does not.
        let area = Rect::new(0, 0, 40, 10);
        let snap = app.ad().snapshot.clone();
        let composed = compose_visible_lines(&app, &snap, area.height as u32, area.width as u32);
        let target_row =
            composed_row_containing(&composed, "TARGET").expect("TARGET line must be composed");

        let pos = cursor_screen_position_at(
            &FrameView::from_app(&app),
            &snap,
            area,
            app.ad().cursor,
            app.ad().scroll,
            app.panes().tree.active().id,
        )
        .expect("cursor visible");

        assert_eq!(
            target_row, 1,
            "the folded heading must occupy exactly one display row \
             (the ` ⋯ N lines` summary is decoration, not a wrap row)"
        );
        assert_eq!(
            pos.1 as usize, target_row,
            "caret row must match the composed row of the cursor line"
        );
    }

    // DR.2 (decoration-retention): the `render_styled_line_*` tests were
    // retired with the function. Body styling now comes from the
    // `DisplayMatrix` via `cells_render::display_line_to_source_spans`
    // (covered in `cells_render` tests); truncation is covered by
    // `truncation_does_not_overrun_max_width` below.

    /// msg-mode.3: a well-formed messages record produces a
    /// styled level token. Order: timestamp (dim), space,
    /// LEVEL (themed), space, body.

    #[test]
    fn truncation_does_not_overrun_max_width() {
        // DR.2: `render_styled_line` retired; exercise the surviving
        // shared `truncate_spans_to_width` directly.
        let spans = truncate_spans_to_width(
            vec![Span::raw("this is a long line of text".to_string())],
            6,
        );
        let total: usize = spans.iter().map(|s| s.content.len()).sum();
        assert!(total <= 6, "rendered length {total} exceeded max width 6");
    }

    // ---- Match overlay ----

    use lattice_protocol::position::{Position, Range as ProtoRange};

    fn pos(l: u32, b: u32) -> Position {
        Position::new(l, b)
    }

    #[test]
    fn match_overlay_range_returns_within_line_interval_when_match_is_local() {
        // Match: (0,4)-(0,7) on a 11-char line.
        let r = ProtoRange::new(pos(0, 4), pos(0, 7));
        assert_eq!(match_overlay_range(r, 0, 11), Some((4, 7)));
    }

    #[test]
    fn match_overlay_range_returns_none_when_line_outside_match_band() {
        let r = ProtoRange::new(pos(1, 0), pos(1, 3));
        assert_eq!(match_overlay_range(r, 0, 10), None);
        assert_eq!(match_overlay_range(r, 2, 10), None);
    }

    #[test]
    fn match_overlay_range_extends_to_eol_for_first_line_of_multiline_match() {
        // Match starts on line 0 byte 5 and ends on line 1 byte 2.
        let r = ProtoRange::new(pos(0, 5), pos(1, 2));
        assert_eq!(match_overlay_range(r, 0, 10), Some((5, 10)));
        assert_eq!(match_overlay_range(r, 1, 8), Some((0, 2)));
    }

    #[test]
    fn match_overlay_range_returns_none_when_match_starts_past_line_end() {
        let r = ProtoRange::new(pos(0, 12), pos(0, 15));
        // Line is shorter than the match's start byte -- nothing to overlay.
        assert_eq!(match_overlay_range(r, 0, 10), None);
    }

    #[test]
    fn apply_match_overlay_splits_a_single_span() {
        let spans = vec![Span::raw("hello world".to_string())];
        let style = TuiStyle::default().bg(Color::Yellow);
        let out = apply_match_overlay(spans, 6, 11, style);
        // Expect three spans: "hello ", "world", and (none after, since 11 == len).
        assert_eq!(out.len(), 2);
        assert_eq!(out[0].content.as_ref(), "hello ");
        assert_eq!(out[1].content.as_ref(), "world");
        assert_eq!(out[1].style, style);
    }

    #[test]
    fn apply_match_overlay_clips_when_match_partially_overlaps_styled_span() {
        // "fn main" with "fn" already styled as keyword; overlay covers "n m".
        let spans = vec![
            Span::styled("fn".to_string(), TuiStyle::default().fg(Color::Magenta)),
            Span::raw(" main".to_string()),
        ];
        let style = TuiStyle::default().bg(Color::Yellow);
        let out = apply_match_overlay(spans, 1, 4, style);
        // Pieces: "f" (kw), "n" (overlay), " m" (overlay), "ain" (raw)
        let texts: Vec<&str> = out.iter().map(|s| s.content.as_ref()).collect();
        assert_eq!(texts, vec!["f", "n", " m", "ain"]);
    }

    #[test]
    fn apply_match_overlay_passes_through_when_no_overlap() {
        let spans = vec![Span::raw("untouched".to_string())];
        let style = TuiStyle::default().bg(Color::Yellow);
        let out = apply_match_overlay(spans, 100, 110, style);
        assert_eq!(out.len(), 1);
        assert_eq!(out[0].content.as_ref(), "untouched");
    }

    /// 4.4.g: splice virtual text inside a single span.
    #[test]
    fn splice_virtual_text_inside_a_single_span() {
        let spans = vec![Span::raw("let x = 1".to_string())];
        let style = TuiStyle::default().fg(Color::DarkGray);
        let out = splice_virtual_text_into_spans(spans, 5, ": i32".into(), style);
        let texts: Vec<&str> = out.iter().map(|s| s.content.as_ref()).collect();
        assert_eq!(texts, vec!["let x", ": i32", " = 1"]);
        assert_eq!(out[1].style.fg, Some(Color::DarkGray));
    }

    /// 4.4.g: splice at a span boundary inserts without
    /// splitting; preserves the adjacent spans' styles.
    #[test]
    fn splice_virtual_text_at_a_span_boundary() {
        let spans = vec![
            Span::styled("fn".to_string(), TuiStyle::default().fg(Color::Magenta)),
            Span::raw(" main()".to_string()),
        ];
        let style = TuiStyle::default().fg(Color::DarkGray);
        // Boundary at byte 2 (end of "fn").
        let out = splice_virtual_text_into_spans(spans, 2, "[hint]".into(), style);
        let texts: Vec<&str> = out.iter().map(|s| s.content.as_ref()).collect();
        assert_eq!(texts, vec!["fn", "[hint]", " main()"]);
        // Original spans' styles preserved.
        assert_eq!(out[0].style.fg, Some(Color::Magenta));
        assert_eq!(out[2].style.fg, None);
    }

    /// 4.4.g: empty virtual text is a no-op.
    #[test]
    fn splice_virtual_text_empty_is_noop() {
        let spans = vec![Span::raw("hi".to_string())];
        let style = TuiStyle::default();
        let out = splice_virtual_text_into_spans(spans.clone(), 1, String::new(), style);
        assert_eq!(out.len(), 1);
        assert_eq!(out[0].content.as_ref(), "hi");
    }

    /// 4.4.g: offset past the end appends at the line end.
    #[test]
    fn splice_virtual_text_past_end_appends() {
        let spans = vec![Span::raw("abc".to_string())];
        let style = TuiStyle::default();
        let out = splice_virtual_text_into_spans(spans, 999, " // EOL".into(), style);
        let texts: Vec<&str> = out.iter().map(|s| s.content.as_ref()).collect();
        assert_eq!(texts, vec!["abc", " // EOL"]);
    }

    // 5.8.N: `inlay_hint_label_text` test migrated to
    // `lattice_lsp::inlay_hint_label_tests`. This peer's tests
    // exercise the call-site (label flattening + paint splicing)
    // via `inlay_hint_overlay_splices_virtual_text` below.

    #[test]
    fn compose_visible_lines_appends_ghost_text_at_eol_when_enabled() {
        // With completion.ghost_text on AND popup open with a
        // prefix-matching top candidate, the cursor's line ends
        // with a dimmed span carrying the suffix.
        let mut app = app_with("foo", 5);
        app.editor.set_modal(lattice_grammar::ModalState::Insert);
        app.editor.set_cursor(pos(0, 3));
        app.editor
            .config
            .set_typed::<lattice_config::CompletionGhostText>(true)
            .expect("set ghost_text");
        // Install a popup with `foobar` as the top candidate
        // and `foo` as the typed query.
        let mut state = lattice_completion::InsertCompletionState::open(
            lattice_completion::CompletionTrigger::Manual,
            app.editor.cursor,
            app.editor.cursor,
            "foo".into(),
        );
        let raw = lattice_completion::RawCandidate::plain(
            "foobar",
            lattice_completion::CandidateKind::Plain,
        );
        state.raw.push(raw.clone());
        state
            .rendered
            .push(lattice_completion::RenderedCandidate::from_scored(
                lattice_completion::ScoredCandidate {
                    raw,
                    score: lattice_completion::MatchScore(800),
                    match_ranges: Vec::new(),
                },
            ));
        app.editor.insert_completion = Some(state);

        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 1, 80);
        let composed = line_text(&lines[0]);
        // The line should contain BOTH the buffer text `foo`
        // AND the ghost suffix `bar`.
        assert!(
            composed.contains("foo") && composed.contains("bar"),
            "expected ghost suffix appended; got `{composed}`",
        );
        // The LAST span on the line is the ghost — confirm it's
        // dim-styled (DarkGray) so it renders subtler than the
        // buffer text.
        let last = lines[0]
            .spans
            .last()
            .expect("at least one span on the rendered line");
        assert_eq!(last.content.as_ref(), "bar");
        assert_eq!(last.style.fg, Some(Color::DarkGray));
    }

    #[test]
    fn compose_visible_lines_no_ghost_when_cursor_not_at_eol() {
        // Cursor mid-line -> ghost would visually clash with
        // existing buffer content; producer suppresses.
        let mut app = app_with("foobaz", 5);
        app.editor.set_modal(lattice_grammar::ModalState::Insert);
        app.editor.set_cursor(pos(0, 3)); // between `foo` and `baz`
        app.editor
            .config
            .set_typed::<lattice_config::CompletionGhostText>(true)
            .expect("set ghost_text");
        let mut state = lattice_completion::InsertCompletionState::open(
            lattice_completion::CompletionTrigger::Manual,
            app.editor.cursor,
            app.editor.cursor,
            "foo".into(),
        );
        let raw = lattice_completion::RawCandidate::plain(
            "foobar",
            lattice_completion::CandidateKind::Plain,
        );
        state.raw.push(raw.clone());
        state
            .rendered
            .push(lattice_completion::RenderedCandidate::from_scored(
                lattice_completion::ScoredCandidate {
                    raw,
                    score: lattice_completion::MatchScore(800),
                    match_ranges: Vec::new(),
                },
            ));
        app.editor.insert_completion = Some(state);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 1, 80);
        let composed = line_text(&lines[0]);
        // `foobaz` from the buffer is fine; `foobar` (ghost)
        // mustn't sneak in.
        assert!(composed.contains("foobaz"));
        assert!(
            !composed.contains("foobar"),
            "ghost suppressed mid-line; got `{composed}`",
        );
    }

    #[test]
    fn compose_visible_lines_applies_match_overlay() {
        let mut app = app_with("hello world", 1);
        app.editor.current_match = Some(ProtoRange::new(pos(0, 6), pos(0, 11)));
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 1, 80);
        let dump = format!("{:?}", lines[0]);
        // Spans should be split so "world" is its own span; we look for the
        // match style's signature in the debug dump.
        assert!(dump.contains("world"), "rendered: {dump}");
    }

    // DR.2 (decoration-retention): the `source_spans_from_runs_*` tests
    // were retired with the function (the inactive-pane span fallback).

    // ---- Visual selection rendering ----

    use lattice_grammar::VisualKind;
    use lattice_protocol::selection::{Selection, SelectionSet, VisualMode};

    #[test]
    fn visual_selection_range_is_none_when_not_in_visual() {
        let app = app_with("hello", 5);
        assert!(visual_selection_range(&app).is_none());
    }

    #[test]
    fn visual_selection_range_charwise_includes_head_byte() {
        let mut app = app_with("hello", 5);
        app.apply(crate::app::Action::EnterVisual(VisualKind::Charwise));
        // Move cursor to byte 2 -- selection extends from 0 to 2 inclusive.
        let sel = Selection {
            anchor: pos(0, 0),
            head: pos(0, 2),
            visual: Some(VisualMode::Charwise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        let r = visual_selection_range(&app).expect("range");
        assert_eq!(r.start, pos(0, 0));
        // Charwise includes head: end byte = head.byte + 1.
        assert_eq!(r.end, pos(0, 3));
    }

    #[test]
    fn visual_selection_range_linewise_covers_full_lines() {
        let mut app = app_with("aaa\nbbb\nccc", 5);
        app.apply(crate::app::Action::EnterVisual(VisualKind::Linewise));
        let sel = Selection {
            anchor: pos(0, 1),
            head: pos(2, 1),
            visual: Some(VisualMode::Linewise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        let r = visual_selection_range(&app).expect("range");
        assert_eq!(r.start, pos(0, 0));
        // Linewise end byte is u32::MAX so per-line clamping picks line_len.
        assert_eq!(r.end.line, 2);
    }

    #[test]
    fn visual_selection_range_normalises_reversed_anchor_head() {
        let mut app = app_with("hello", 5);
        app.apply(crate::app::Action::EnterVisual(VisualKind::Charwise));
        // anchor > head (the user moved leftward in Visual).
        let sel = Selection {
            anchor: pos(0, 4),
            head: pos(0, 1),
            visual: Some(VisualMode::Charwise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        let r = visual_selection_range(&app).expect("range");
        assert_eq!(r.start, pos(0, 1));
        assert_eq!(r.end, pos(0, 5));
    }

    #[test]
    fn visual_block_extents_returns_none_when_not_blockwise() {
        let app = app_with("hello", 5);
        assert!(visual_block_extents(&app).is_none());
    }

    #[test]
    fn visual_block_extents_normalises_anchor_and_head() {
        let mut app = app_with("aaa\nbbb\nccc", 10);
        app.apply(crate::app::Action::EnterVisual(VisualKind::Blockwise));
        let sel = Selection {
            anchor: pos(2, 1),
            head: pos(0, 2),
            visual: Some(VisualMode::Blockwise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        let b = visual_block_extents(&app).unwrap();
        assert_eq!(b.start_line, 0);
        assert_eq!(b.end_line, 2);
        assert_eq!(b.start_col, 1);
        assert_eq!(b.end_col, 2);
    }

    #[test]
    fn compose_visible_lines_overlays_visual_selection() {
        let mut app = app_with("hello world", 1);
        app.apply(crate::app::Action::EnterVisual(VisualKind::Charwise));
        let sel = Selection {
            anchor: pos(0, 0),
            head: pos(0, 4),
            visual: Some(VisualMode::Charwise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 1, 80);
        let dump = format!("{:?}", lines[0]);
        // The selected "hello" should appear as its own span(s); we just
        // verify the line still contains the original text after overlay.
        assert!(dump.contains("hello"));
        assert!(dump.contains("world"));
    }

    // --- DR.3 characterization: active-pane compose byte-identity ---

    /// Serialise every span of every line to a stable
    /// `text/fg/bg/modifier` fingerprint. Used to pin the active-pane
    /// compose output across the DR.3 render-path merge: the merge
    /// parameterizes one path over `(buffer, interaction|None,
    /// opacity)`, and the active pane must come out pixel-identical.
    fn compose_fingerprint(lines: &[Line<'static>]) -> String {
        lines
            .iter()
            .map(|l| {
                l.spans
                    .iter()
                    .map(|s| {
                        format!(
                            "{:?}/{:?}/{:?}/{:?}",
                            s.content.as_ref(),
                            s.style.fg,
                            s.style.bg,
                            s.style.add_modifier
                        )
                    })
                    .collect::<Vec<_>>()
                    .join("|")
            })
            .collect::<Vec<_>>()
            .join("\n")
    }

    #[test]
    fn dr3_active_pane_compose_characterization() {
        // DR.3: pins the active-pane overlay stack (syntax spans,
        // gutter, line-number column, cursor-line bg, visual
        // selection, hlsearch, current-match) byte-identical through
        // the render-path merge. LSP-decoration sourcing (semantic,
        // diagnostics) is provably id-equivalent for the active pane
        // — `ctx.buffer_id == app.ad().document_buffer_id` — so it is
        // not injected here; the existing LSP overlay tests cover it.
        // T.6: visual selection + current-match are now BACKGROUND
        // tints resolved from the `selection` / `search.current`
        // elements (no fg recolor / bold), matching the GPUI peer — the
        // expected fingerprint reflects that converged styling.
        // CV.2: the scene is a 4-line file, and the fingerprint used to
        // carry a fifth NUMBERED row — the phantom line ropey reports
        // for the terminating `\n`. It is now the second `~` filler,
        // which is what vim shows and what the buffer actually has.
        // IG.3: lines 2 and 3 now open with an indentation guide — the
        // `\u{2502}` span in `indent.guide`'s resolved fg, followed by the
        // remaining three columns of their indent. This is the pin doing
        // its job: guides are on by default, so every indented line in
        // every buffer gains one, and that change had to be looked at
        // rather than absorbed.
        let mut app = app_with("fn main() {\n    let x = 1;\n    foo();\n}\n", 6);
        app.toggle_mode_by_name("current-line-highlight-mode");
        // Visual selection on line 1 (cols 4..=6), hlsearch + current
        // match on line 2 (cols 4..7) — exercises every active-only
        // overlay branch in one scene.
        app.apply(crate::app::Action::EnterVisual(VisualKind::Charwise));
        let sel = Selection {
            anchor: pos(1, 4),
            head: pos(1, 6),
            visual: Some(VisualMode::Charwise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        app.editor.current_match = Some(ProtoRange::new(pos(2, 4), pos(2, 7)));
        app.editor.all_matches = vec![ProtoRange::new(pos(2, 4), pos(2, 7))];
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 6, 40);
        let fp = compose_fingerprint(&lines);
        let expected = "\" \"/None/None/NONE|\" \"/None/None/NONE|\" 1   \"/Some(DarkGray)/None/NONE|\"fn main() {\"/Some(Rgb(205, 214, 244))/Some(Indexed(236))/NONE|\"                      \"/None/Some(Indexed(236))/NONE\n\" \"/None/None/NONE|\" \"/None/None/NONE|\" 2   \"/Some(DarkGray)/None/NONE|\"\u{2502}\"/Some(Rgb(108, 112, 134))/None/NONE|\"   \"/Some(Rgb(205, 214, 244))/None/NONE|\"let\"/None/Some(Rgb(69, 71, 90))/NONE|\" x = 1;\"/Some(Rgb(205, 214, 244))/None/NONE\n\" \"/None/None/NONE|\" \"/None/None/NONE|\" 3   \"/Some(DarkGray)/None/NONE|\"\u{2502}\"/Some(Rgb(108, 112, 134))/None/NONE|\"   \"/Some(Rgb(205, 214, 244))/None/NONE|\"foo\"/None/Some(Rgb(108, 90, 30))/NONE|\"();\"/Some(Rgb(205, 214, 244))/None/NONE\n\" \"/None/None/NONE|\" \"/None/None/NONE|\" 4   \"/Some(DarkGray)/None/NONE|\"}\"/Some(Rgb(205, 214, 244))/None/NONE\n\" \"/None/None/NONE|\" ~   \"/Some(DarkGray)/None/NONE\n\" \"/None/None/NONE|\" ~   \"/Some(DarkGray)/None/NONE";
        assert_eq!(fp, expected, "active-pane compose output changed");
    }

    /// PP.2: the root reaches the PAINTED prompt row, and an unrooted picker's
    /// prompt does not move.
    ///
    /// Asserted on the frame rather than on `Picker::root_label`, because the
    /// host-side test already pins the field and the thing that can still go
    /// missing is this render. A prompt that carries the root in its model and
    /// never paints it is indistinguishable, to the user, from the feature not
    /// existing.
    #[test]
    fn pp2_a_rooted_picker_paints_its_root_in_the_prompt() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let row_text = |app: &App| -> String {
            let (tw, th): (u16, u16) = (80, 10);
            let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();
            let snap = app.ad().snapshot.clone();
            terminal
                .draw(|f| {
                    draw_picker_prompt(
                        f,
                        Rect {
                            x: 0,
                            y: 0,
                            width: tw,
                            height: 1,
                        },
                        app,
                    );
                    let _ = &snap;
                })
                .unwrap();
            let buf = terminal.backend().buffer().clone();
            (0..tw)
                .map(|x| buf[(x, 0)].symbol().to_string())
                .collect::<String>()
                .trim_end()
                .to_string()
        };

        let mut a = app_with("scratch\n", 20);
        let _ = a.mutate_editor_with(|e: &mut lattice_host::editor::Editor| {
            e.open_picker("buffers".to_string(), Vec::new())
        });
        let unrooted = row_text(&a);
        assert!(
            unrooted.starts_with("buffers> "),
            "an unrooted picker's prompt is unchanged: {unrooted:?}"
        );

        a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
            if let Some(p) = e.picker.as_mut() {
                p.root_label = Some("~/src/lattice".to_string());
            }
        });
        let rooted = row_text(&a);
        // PP.2b: padded on BOTH sides. The root used to abut the `>`
        // (`buffers ~/src/lattice> `), which read as one run of
        // punctuation with the prompt lost inside it — the gap is what
        // makes the `>` findable at a glance.
        assert!(
            rooted.starts_with("buffers  ~/src/lattice  > "),
            "the root sits between the source and the `>`, with a gap on \
             each side: {rooted:?}"
        );
    }

    /// PP.2b: the root is painted in its own colour, distinct from the
    /// `(n/m)` count beside it.
    ///
    /// The point of the slot is that the root stopped being the dimmest
    /// thing on the line — it shared `DarkGray` with the count, so the
    /// one piece of context the prompt carries read as chrome. Asserted
    /// as "different from the count's colour" rather than against a
    /// concrete colour, so a theme is free to choose one without
    /// breaking the test that exists to keep them distinguishable.
    #[test]
    fn pp2b_the_root_is_painted_distinctly_from_the_count() {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let mut a = app_with("scratch\n", 20);
        let _ = a.mutate_editor_with(|e: &mut lattice_host::editor::Editor| {
            e.open_picker("buffers".to_string(), Vec::new())
        });
        a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
            if let Some(p) = e.picker.as_mut() {
                p.root_label = Some("~/src/lattice".to_string());
            }
        });

        let (tw, th): (u16, u16) = (80, 10);
        let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();
        terminal
            .draw(|f| {
                draw_picker_prompt(
                    f,
                    Rect {
                        x: 0,
                        y: 0,
                        width: tw,
                        height: 1,
                    },
                    &a,
                );
            })
            .unwrap();
        let buf = terminal.backend().buffer().clone();
        let row: String = (0..tw).map(|x| buf[(x, 0)].symbol().to_string()).collect();

        let fg_at = |col: u16| -> Color { buf[(col, 0)].style().fg.expect("a foreground") };
        let root_fg = fg_at(row.find("~/src/lattice").expect("the root is painted") as u16);
        // The count is `(n/m)`, and `n` depends on how many buffers the
        // picker seated — so find it by its opening paren rather than by
        // a literal that a different fixture would change.
        let count_fg = fg_at(row.rfind('(').expect("the count is painted") as u16);
        assert_ne!(
            root_fg, count_fg,
            "the root must not share the count's colour — that is what made \
             it read as chrome"
        );
        assert_ne!(
            root_fg,
            Color::DarkGray,
            "…and specifically must not still be the dim grey PP.2 shipped"
        );
    }

    /// PP.2c: every span on the prompt takes its colour from the theme,
    /// so `:colorscheme` reaches the picker at all.
    ///
    /// Driven by actually retuning the four elements and re-rendering,
    /// rather than by comparing against the defaults. A line that
    /// resolves through the theme and a line that hardcodes four colours
    /// are indistinguishable until the theme changes — which is exactly
    /// the bug: the prompt looked fine and no colorscheme could touch it.
    #[test]
    fn pp2c_the_whole_prompt_line_follows_the_theme() {
        use lattice_host::ui::theme::{ElementName, StyleSpec, ThemeRegistryHandle};
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;

        let mut a = app_with("scratch\n", 20);
        let _ = a.mutate_editor_with(|e: &mut lattice_host::editor::Editor| {
            e.open_picker("buffers".to_string(), Vec::new())
        });
        a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
            if let Some(p) = e.picker.as_mut() {
                p.root_label = Some("~/src/lattice".to_string());
            }
        });

        // Four unmistakable, mutually distinct colours — a span that is
        // still hardcoded cannot land on one of these.
        a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
            let reg = e
                .services
                .get::<ThemeRegistryHandle>()
                .expect("the theme registry is a boot service");
            for (name, colour) in [
                ("picker.title", "red"),
                ("picker.prompt", "green"),
                ("picker.count", "blue"),
                ("picker.root", "yellow"),
            ] {
                reg.set_override(ElementName::from_static(name), StyleSpec::new().fg(colour));
            }
        });
        // The prompt reads its colours from the published table, so the
        // override has to reach a publish before it reaches a frame —
        // the same hop `RendererSignal::ThemeChanged` drives in
        // production.
        a.mutate_editor(|e: &mut lattice_host::editor::Editor| {
            e.publish_render_state();
        });
        lattice_host::cells_worker::recompute(&a.editor.render_state);

        let (tw, th): (u16, u16) = (80, 10);
        let mut terminal = Terminal::new(TestBackend::new(tw, th)).unwrap();
        terminal
            .draw(|f| {
                draw_picker_prompt(
                    f,
                    Rect {
                        x: 0,
                        y: 0,
                        width: tw,
                        height: 1,
                    },
                    &a,
                );
            })
            .unwrap();
        let buf = terminal.backend().buffer().clone();
        let row: String = (0..tw).map(|x| buf[(x, 0)].symbol().to_string()).collect();
        let fg_at = |col: u16| -> Color { buf[(col, 0)].style().fg.expect("a foreground") };

        let title_fg = fg_at(0);
        let root_fg = fg_at(row.find("~/src/lattice").expect("root") as u16);
        let prompt_fg = fg_at(row.find('>').expect("prompt marker") as u16);
        let count_fg = fg_at(row.rfind('(').expect("count") as u16);

        // Four overrides, four distinct palette roles → four distinct
        // painted colours. A span still holding `Color::Cyan` would
        // collide with another or keep the old literal, and both show up
        // here.
        let all = [title_fg, root_fg, prompt_fg, count_fg];
        let distinct: std::collections::HashSet<String> =
            all.iter().map(|c| format!("{c:?}")).collect();
        assert_eq!(
            distinct.len(),
            4,
            "every span must follow its own element; got {all:?}"
        );
        for (what, c) in [
            ("title", title_fg),
            ("prompt", prompt_fg),
            ("count", count_fg),
            ("root", root_fg),
        ] {
            assert!(
                !matches!(c, Color::Cyan | Color::DarkGray),
                "{what} is still painting the hardcoded literal: {c:?}"
            );
        }
    }

    #[test]
    fn dr3_inactive_pane_drops_interaction_and_dims_decorations() {
        // DR.3: the SAME scene as the active characterization, but
        // composed through `compose_pane_lines` with `is_active:
        // false`. Interaction overlays (visual selection, current
        // match, cursor-line bg) must be GONE; buffer-intrinsic
        // decorations (syntax here) must REMAIN, dimmed by the theme's
        // `inactive_pane_overlay` (default DIM). This is the
        // decoration-vs-interaction split the merge encodes.
        let mut app = app_with("fn main() {\n    let x = 1;\n    foo();\n}\n", 6);
        app.toggle_mode_by_name("current-line-highlight-mode");
        app.apply(crate::app::Action::EnterVisual(VisualKind::Charwise));
        let sel = Selection {
            anchor: pos(1, 4),
            head: pos(1, 6),
            visual: Some(VisualMode::Charwise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        app.editor.current_match = Some(ProtoRange::new(pos(2, 4), pos(2, 7)));
        app.editor.all_matches = vec![ProtoRange::new(pos(2, 4), pos(2, 7))];
        app.editor.publish_render_state();
        // Build the styled cells NOW. The worker does this off-thread, so
        // without it the compose below races the build and, losing, sees
        // text with no syntax colour — which this test then reports as the
        // inactive pane having dropped its decorations.
        lattice_host::cells_worker::recompute(&app.editor.render_state);

        let view = FrameView::for_buffer(&app, app.ad().document_buffer_id);
        let ctx = PaneComposeCtx {
            is_active: false,
            pane_id: app.panes().tree.active().id,
            buffer_id: app.ad().document_buffer_id,
            cursor_line: app.ad().cursor.line,
            cursor_line_highlight: false,
            scroll: app.ad().scroll,
            leftcol: app.ad().leftcol,
            display_line_numbers: app.ad().display_line_numbers.clone(),
        };
        let lines = compose_pane_lines(&view, &app.ad().snapshot.clone(), 6, 40, &ctx);
        let spans: Vec<&Span<'static>> = lines.iter().flat_map(|l| l.spans.iter()).collect();

        // Interaction state is gone on the inactive pane.
        assert!(
            spans.iter().all(|s| s.style.bg != Some(Color::Blue)),
            "visual selection leaked onto inactive pane",
        );
        assert!(
            spans.iter().all(|s| s.style.bg != Some(Color::Yellow)),
            "current-match leaked onto inactive pane",
        );
        assert!(
            spans
                .iter()
                .all(|s| s.style.bg != Some(Color::Indexed(236))),
            "cursor-line leaked onto inactive pane",
        );
        // Decorations retained + dimmed: the syntax-coloured body span
        // keeps its fg and gains the DIM overlay.
        assert!(
            spans
                .iter()
                .any(|s| s.style.fg == Some(Color::Rgb(205, 214, 244))
                    && s.style.add_modifier.contains(Modifier::DIM)),
            "inactive pane lost its dimmed syntax decoration: {lines:?}",
        );
    }

    // --- Heading-preserved fold render -------------------------

    #[test]
    fn closed_fold_preserves_heading_and_appends_summary() {
        let mut app = app_with("# Heading\nbody one\nbody two\nafter\n", 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Markdown);
        app.recompute_folds();
        // Close the heading fold.
        let idx = app
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("heading fold");
        app.editor.folds[idx].closed = true;
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        // Heading text is preserved.
        assert!(row0.contains("# Heading"), "row0 = {row0:?}");
        // Summary suffix appended.
        assert!(row0.contains("⋯"), "row0 = {row0:?}");
    }

    #[test]
    fn closed_fold_hides_interior_lines() {
        let mut app = app_with("# H\nhidden1\nhidden2\nshown\n", 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Markdown);
        app.recompute_folds();
        let idx = app
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("heading fold");
        app.editor.folds[idx].closed = true;
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let blob: String = lines.iter().map(line_text).collect::<Vec<_>>().join("\n");
        assert!(!blob.contains("hidden1"), "interior leaked: {blob}");
        assert!(!blob.contains("hidden2"), "interior leaked: {blob}");
    }

    /// Fold-bleed fix (2026-06-30): an INACTIVE pane must elide its
    /// closed folds and show the summary exactly like the active pane —
    /// the user's repro was a folded buffer un-folding the instant focus
    /// moved to another split. Previously `compose_pane_lines` gated all
    /// fold handling on `ctx.is_active`, so inactive panes walked lines
    /// 1:1. With per-buffer fold state (`folds_for_buffer`) the gate is
    /// gone; this composes the buffer with `is_active: false` and asserts
    /// the interior is still hidden and the summary still appears.
    #[test]
    fn inactive_pane_elides_closed_folds_like_active() {
        let mut app = app_with("# H\nhidden1\nhidden2\nshown\n", 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Markdown);
        app.recompute_folds();
        let idx = app
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("heading fold");
        app.editor.folds[idx].closed = true;
        app.editor.publish_render_state();

        let view = FrameView::for_buffer(&app, app.ad().document_buffer_id);
        let ctx = PaneComposeCtx {
            is_active: false,
            pane_id: app.panes().tree.active().id,
            buffer_id: app.ad().document_buffer_id,
            cursor_line: app.ad().cursor.line,
            cursor_line_highlight: false,
            scroll: app.ad().scroll,
            leftcol: app.ad().leftcol,
            display_line_numbers: app.ad().display_line_numbers.clone(),
        };
        let lines = compose_pane_lines(&view, &app.ad().snapshot.clone(), 5, 80, &ctx);
        let blob: String = lines.iter().map(line_text).collect::<Vec<_>>().join("\n");
        assert!(
            !blob.contains("hidden1"),
            "inactive interior leaked: {blob}"
        );
        assert!(
            !blob.contains("hidden2"),
            "inactive interior leaked: {blob}"
        );
        assert!(blob.contains("⋯"), "inactive summary missing: {blob}");
    }

    #[test]
    fn closed_fold_summary_includes_chained_closed_folds() {
        // Reproduces the user's "fold both branches of an if/else
        // under foldmethod=indent" case: two closed folds touch at
        // line 3 -- the outer (1, 3) hides 2..=3, the sibling
        // (3, 5) hides 4..=5 (its heading at 3 is itself hidden by
        // the first fold). Visually the user collapses 5 buffer
        // lines onto one row; the summary should report 5, not 3.
        let mut app = app_with("a\nb\nc\nd\ne\nf\ng\n", 7);
        app.editor.folds.push(crate::app::Fold {
            start_line: 1,
            end_line: 3,
            closed: true,
            identity: None,
        });
        app.editor.folds.push(crate::app::Fold {
            start_line: 3,
            end_line: 5,
            closed: true,
            identity: None,
        });
        // Slice 3c.final.B (group 2): publish after direct fold
        // mutations so `rs.active_document.load().folds` reflects them.
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 7, 80);
        // Find the row that summarises the chained folds (line 1's
        // heading row).
        let row1_text = line_text(&lines[1]);
        assert!(
            row1_text.contains("⋯ 5 lines"),
            "expected '⋯ 5 lines' for chained folds, got: {row1_text:?}"
        );
    }

    #[test]
    fn adjacent_folds_count_only_their_own_lines() {
        // Two back-to-back but NON-overlapping closed folds (foldmethod=
        // indent on two sibling blocks): (0, 2) then (3, 5). The second
        // fold's heading at line 3 is the first VISIBLE row after fold
        // one, so each fold summarises only its own 3 lines. Regression:
        // the display-span walk used to chain a fold starting at `end+1`,
        // making the first fold report all 6 lines.
        let mut app = app_with("a\nb\nc\nd\ne\nf\n", 7);
        app.editor.folds.push(crate::app::Fold {
            start_line: 0,
            end_line: 2,
            closed: true,
            identity: None,
        });
        app.editor.folds.push(crate::app::Fold {
            start_line: 3,
            end_line: 5,
            closed: true,
            identity: None,
        });
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 7, 80);
        // Row 0 = fold one's heading; row 1 = fold two's heading (visible).
        let row0_text = line_text(&lines[0]);
        let row1_text = line_text(&lines[1]);
        assert!(
            row0_text.contains("⋯ 3 lines"),
            "first fold should count only its own 3 lines, got: {row0_text:?}"
        );
        assert!(
            row1_text.contains("⋯ 3 lines"),
            "second fold should count only its own 3 lines, got: {row1_text:?}"
        );
    }

    #[test]
    fn open_fold_renders_lines_normally_without_summary() {
        let mut app = app_with("# H\nbody\n", 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Markdown);
        app.recompute_folds();
        // Leave the fold open (default).
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(row0.contains("# H"), "row0 = {row0:?}");
        assert!(
            !row0.contains("⋯"),
            "summary should only appear on closed folds: {row0:?}"
        );
    }

    // --- Fold gutter glyphs ------------------------------------

    #[test]
    fn open_fold_gutter_shows_down_glyph() {
        let mut app = app_with("# H\nbody\n", 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Markdown);
        app.recompute_folds();
        // Slice 3c.final.B (group 2): recompute_folds mutates
        // editor.folds outside dispatch; publish so the renderer's
        // `rs.active_document.load().folds` reflects the new set.
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            row0.contains('▾'),
            "expected ▾ glyph on open fold: {row0:?}"
        );
        assert!(!row0.contains('▸'), "did not expect ▸ glyph: {row0:?}");
    }

    #[test]
    fn closed_fold_gutter_shows_right_glyph() {
        let mut app = app_with("# H\nbody\n", 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Markdown);
        app.recompute_folds();
        let idx = app
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("heading fold");
        app.editor.folds[idx].closed = true;
        app.editor.publish_render_state();
        // Slice 3c.final.B (group 2): publish after direct
        // `editor.folds[idx].closed` mutation.
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            row0.contains('▸'),
            "expected ▸ glyph on closed fold: {row0:?}"
        );
        assert!(!row0.contains('▾'), "did not expect ▾ glyph: {row0:?}");
    }

    #[test]
    fn gutterless_buffer_still_shows_fold_marker_before_text() {
        // Folding is useful on gutterless buffers too (help / the
        // dashboard have many markdown sections), so a foldable head must
        // STILL paint its `▾`/`▸` — positioned immediately before the row
        // text, not stranded at the pane's left edge. The centring pad is
        // folded into `gutter_w`, so `format_gutter_cell` right-aligns the
        // glyph against the content.
        let mut app = app_with("# H\nbody\n", 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Markdown);
        app.recompute_folds();
        app.editor.option_cache.sign_column = false;
        app.editor.option_cache.show_line_numbers = false;
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            row0.contains('▾'),
            "gutterless head still shows ▾: {row0:?}"
        );
        // The glyph sits just before the heading text (a single trailing
        // gap), not at column 0 with the text far to the right.
        let chars: Vec<char> = row0.chars().collect();
        let glyph_ci = chars.iter().position(|&c| c == '▾').expect("glyph");
        let text_ci = chars.iter().position(|&c| c == '#').expect("heading");
        assert!(
            text_ci > glyph_ci && text_ci - glyph_ci <= 2,
            "▾ should sit just before the text (glyph@{glyph_ci}, text@{text_ci}): {row0:?}"
        );
    }

    #[test]
    fn line_after_closed_fold_keeps_correct_syntax_highlighting() {
        // Reproduces a user-reported regression: with a closed fold
        // hiding interior lines, the next visible line was being
        // styled with stale spans from `visible_highlights[viewport_row]`
        // because the row index assumed `visible[i] == scroll + i`.
        // The fix indexes into `visible_highlights` by buffer-line
        // delta instead of viewport row.
        //
        // The struct fold now also swallows the trailing `}` (closer
        // inclusion), so the "next visible line" is the trailing
        // statement, not the brace.
        let src = "pub struct Buffer {\n    rope: Rope,\n}\nlet trailing = 1;\n";
        let mut app = app_with(src, 10);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Indent);
        app.recompute_folds();
        let idx = app
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("struct fold");
        app.editor.folds[idx].closed = true;
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 4, 80);
        // Row 0: heading + " ⋯ N lines".
        // Row 1: the post-fold statement -- correct content, not
        //        leaking interior spans.
        let row1 = line_text(&lines[1]);
        assert!(
            row1.contains("let trailing"),
            "row1 should be the post-fold statement: {row1:?}"
        );
        assert!(!row1.contains("rope"), "interior leaked: {row1:?}");
        assert!(
            !row1.contains('}'),
            "closer should be inside the fold: {row1:?}"
        );
    }

    #[test]
    fn closed_indent_fold_swallows_trailing_close_brace() {
        // Vim's `foldmethod=indent` strictly excludes lines whose
        // indent isn't > start. We extend that with closer-line
        // inclusion: a `}` / `]` / `)` line at the same indent as
        // the fold start gets pulled in, so the user doesn't see an
        // orphan brace below `... ⋯ N lines`.
        let src = "pub struct Buffer {\n    rope: Rope,\n}\n";
        let mut app = app_with(src, 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Indent);
        app.recompute_folds();
        let f = app
            .editor
            .folds
            .iter()
            .find(|f| f.start_line == 0)
            .expect("fold");
        assert_eq!(f.end_line, 2, "expected `}}` swallowed: {f:?}");
    }

    /// **Closing a fold must not change the heading row's syntax colours.**
    ///
    /// Reported against a real org file: with `#+STARTUP: overview` most
    /// sections open collapsed, and every `▶` heading rendered its TITLE
    /// unstyled while its keyword and tags still coloured. The `▼` headings
    /// right beside them — same level, same query — were coloured. So it is
    /// the fold state, not the language or the level.
    ///
    /// The suspicion this pins: a capture whose node SPANS the folded subtree
    /// (org's `(section)` is "a headline plus everything beneath it") produces
    /// a span reaching past the one visible row a closed fold renders, and the
    /// composer drops or mis-clips it — keeping the short spans that sit
    /// entirely within the line (keyword, tags) and losing the long one.
    ///
    /// Asserted as an INVARIANT rather than against fixed colours: whatever
    /// the heading looked like open, it must look the same closed, minus the
    /// summary suffix and the fold marker. That holds for any grammar and
    /// cannot rot into asserting a theme.
    ///
    /// **This fixture does NOT reproduce the org report, and that is the
    /// finding.** It passes: the composer looks its spans up by buffer line
    /// and a closed fold's heading keeps them. Which means the org failure is
    /// not here — `visible_highlights` is already per-LINE (the syntax layer
    /// decomposes a multi-line capture before the renderer sees it), so there
    /// is no long span for a fold to clip. The remaining suspect is the
    /// highlight RANGE: with everything collapsed, ~60 visible rows span ~2500
    /// buffer lines, and whatever band actually gets computed is what colours.
    /// Kept as a guard for the composer, which is now known-good.
    #[test]
    fn closing_a_fold_preserves_the_heading_rows_syntax_spans() {
        let src = "pub struct Buffer {\n    rope: Rope,\n}\nlet trailing = 1;\n";
        let mut app = app_with(src, 10);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Indent);
        app.recompute_folds();
        let idx = app
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("struct fold");

        // Open: the heading row as the user sees it uncollapsed.
        app.editor.folds[idx].closed = false;
        app.editor.publish_render_state();
        let open = compose_visible_lines(&app, &app.ad().snapshot.clone(), 4, 80);
        let open_styles: Vec<_> = open[0]
            .spans
            .iter()
            .map(|s| (s.content.to_string(), s.style.fg))
            .collect();

        // Closed: same row, plus a summary suffix.
        app.editor.folds[idx].closed = true;
        app.editor.publish_render_state();
        let closed = compose_visible_lines(&app, &app.ad().snapshot.clone(), 4, 80);
        let closed_styles: Vec<_> = closed[0]
            .spans
            .iter()
            .map(|s| (s.content.to_string(), s.style.fg))
            // The `⋯ N lines` suffix is decoration the open row has no peer
            // for; everything before it must match.
            .filter(|(text, _)| !text.contains('\u{22ef}'))
            .collect();
        // The fold MARKER legitimately differs (`▾` open, `▸` closed) — that
        // is the feature, not the regression.
        fn drop_marker<C>(v: Vec<(String, Option<C>)>) -> Vec<(String, Option<C>)> {
            v.into_iter()
                .filter(|(t, _)| !t.contains('\u{25be}') && !t.contains('\u{25b8}'))
                .collect()
        }
        let open_styles = drop_marker(open_styles);
        let closed_styles = drop_marker(closed_styles);

        // Compare the STYLED runs only — trailing padding differs by the
        // suffix's width and carries no colour either way.
        fn styled<C: Clone>(v: &[(String, Option<C>)]) -> Vec<(String, Option<C>)> {
            v.iter()
                .filter(|(t, c)| c.is_some() && !t.trim().is_empty())
                .cloned()
                .collect()
        }
        assert_eq!(
            styled(&closed_styles),
            styled(&open_styles),
            "a closed fold's heading lost syntax spans the open one had"
        );
    }

    #[test]
    fn linewise_visual_highlights_closed_fold_heading() {
        // Regression: previously the closed-fold heading branch in
        // compose_visible_lines emitted the summary suffix and
        // `continue`'d before the visual overlay ran -- so V on a
        // closed-fold heading appeared unhighlighted. The summary
        // suffix is now appended AFTER overlay processing.
        let src = "pub struct Buffer {\n    rope: Rope,\n}\n";
        let mut app = app_with(src, 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Indent);
        app.recompute_folds();
        let idx = app
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("fold");
        app.editor.folds[idx].closed = true;
        app.editor.publish_render_state();
        app.editor.cursor = lattice_protocol::position::Position::new(0, 0);
        app.apply(crate::app::Action::EnterVisual(VisualKind::Linewise));
        let sel = Selection {
            anchor: pos(0, 0),
            head: pos(0, 0),
            visual: Some(VisualMode::Linewise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        // T.6: visual_style now resolves through the app's published
        // resolved table — derive the expected bg from the same source.
        let cells_rs = app.render_state.load().cells.load_full();
        let visual_bg = visual_style(&cells_rs.resolved_theme, &cells_rs.theme_ids).bg;
        let row0 = &lines[0];
        let has_visual_span = row0.spans.iter().any(|s| s.style.bg == visual_bg);
        assert!(
            has_visual_span,
            "linewise visual on a closed-fold heading must still overlay: {row0:?}"
        );
        // Summary suffix is still present.
        let row0_text = line_text(row0);
        assert!(
            row0_text.contains("⋯"),
            "summary suffix lost: {row0_text:?}"
        );
    }

    #[test]
    fn linewise_visual_overlays_full_line_after_fold_change() {
        // After the v-line key, a line outside any fold should still
        // overlay correctly. This is a guard against the fold work
        // accidentally breaking line-visual on plain documents.
        let mut app = app_with("alpha\nbeta\ngamma\n", 5);
        app.editor.cursor = lattice_protocol::position::Position::new(1, 0);
        app.apply(crate::app::Action::EnterVisual(VisualKind::Linewise));
        let sel = Selection {
            anchor: pos(1, 0),
            head: pos(1, 0),
            visual: Some(VisualMode::Linewise),
        };
        app.editor
            .set_selections_blocking(SelectionSet::single(sel));
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        // Verify the second visible line ("beta") has at least one
        // span styled with the visual color.
        // T.6: derive expected bg from the app's published resolved table.
        let cells_rs = app.render_state.load().cells.load_full();
        let visual_bg = visual_style(&cells_rs.resolved_theme, &cells_rs.theme_ids).bg;
        let row1 = &lines[1];
        let has_visual_span = row1.spans.iter().any(|s| s.style.bg == visual_bg);
        assert!(
            has_visual_span,
            "linewise visual should overlay the selected line: {row1:?}"
        );
    }

    #[test]
    fn lines_without_fold_start_have_no_glyph() {
        let mut app = app_with("# H\nbody one\nbody two\nafter\n", 5);
        app.set_foldmethod_for_test(crate::app::FoldMethod::Markdown);
        app.recompute_folds();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        // Row 1 (body one) is inside the fold, not a fold start.
        let row1 = line_text(&lines[1]);
        assert!(!row1.contains('▸'), "row1: {row1:?}");
        assert!(!row1.contains('▾'), "row1: {row1:?}");
    }

    // ---- LSP diagnostic rendering tests (Phase 4.1.d.iii) ----

    /// Helper: seed a diagnostic into the App's LSP layer for
    /// the given line range + severity, mapping the App's
    /// active buffer to a fake URI.
    ///
    /// M.5.6: also activates `lsp-mode` on the buffer so the
    /// renderer's gate (`severity_for_line` /
    /// `diagnostics_on_line`) lets the diagnostic through. Tests
    /// were written before the gate; activating here keeps them
    /// probing the rendering path they were originally probing.
    fn seed_diagnostic(
        app: &mut App,
        line: u32,
        start_col: u32,
        end_col: u32,
        severity: lattice_lsp::DiagnosticSeverity,
        message: &str,
    ) {
        use std::str::FromStr;
        let uri = lattice_lsp::Uri::from_str("file:///tmp/x.rs").unwrap();
        let doc_id = app.ad().document_buffer_id;
        app.editor.buffer_uris.insert(doc_id, uri.clone());
        // Activate lsp-mode so the M.5.6 render gate doesn't
        // suppress what we're about to paint. Idempotent: tests
        // that have already toggled it on no-op here.
        if !app.lsp_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-mode");
        }
        let diag = lattice_lsp::Diagnostic {
            range: lattice_lsp::LspRange {
                start: lattice_lsp::LspPosition {
                    line,
                    character: start_col,
                },
                end: lattice_lsp::LspPosition {
                    line,
                    character: end_col,
                },
            },
            severity: Some(severity),
            code: None,
            code_description: None,
            source: None,
            message: message.into(),
            related_information: None,
            tags: None,
            data: None,
        };
        app.editor
            .lsp_diagnostics
            .apply(lattice_lsp::DiagnosticEvent {
                server_id: std::sync::Arc::from("rust"),
                uri,
                version: None,
                diagnostics: std::sync::Arc::from(vec![diag].into_boxed_slice()),
            });
        // Phase 5.8.AF.5 / Slice 3a: republish the renderer's
        // `RenderState` so the diagnostic the test just wrote
        // appears in `render_state.diagnostics.layer`. In prod
        // this fires automatically at the end of every
        // `Editor::dispatch`; tests that mutate `Editor` state
        // directly must publish manually.
        app.editor.publish_render_state();
    }

    #[test]
    fn lsp_mode_off_suppresses_diagnostic_glyphs() {
        // M.5.6: the render-side gate hides diagnostics when
        // `lsp-mode` is off, even if the diagnostics layer holds
        // data and a URI is mapped. Mirrors the supervisor-side
        // gates in M.5.4 / M.5.5: the user's "off" setting
        // suppresses every visible LSP signal for that buffer.
        let mut app = app_with("fn main() {}\n", 5);
        // Seed the diagnostic the same way other tests do (this
        // also auto-activates lsp-mode via the helper).
        seed_diagnostic(
            &mut app,
            0,
            0,
            7,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "boom",
        );
        // Toggle lsp-mode OFF; the diagnostic glyph should
        // disappear from the rendered gutter.
        app.toggle_mode_by_name("lsp-mode");
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            !row0.contains('■'),
            "lsp-mode off should suppress the error glyph; got {row0:?}"
        );
        // (LSP segment was in the old global modeline; now covered by pane_status_label.)
    }

    #[test]
    fn lsp_diagnostics_mode_off_suppresses_glyphs_independently() {
        // M.6.3: the render-side gate moves from `lsp-mode`
        // (umbrella) to `lsp-diagnostics-mode` (sub-mode). User
        // can disable just the diagnostic visual surface while
        // keeping other LSP features (hover / completion / nav)
        // active.
        let mut app = app_with("fn main() {}\n", 5);
        seed_diagnostic(
            &mut app,
            0,
            0,
            7,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "boom",
        );
        // Helper auto-activated lsp-mode (and via cascade,
        // lsp-diagnostics-mode). Toggle just diagnostics-mode
        // off; lsp-mode stays on.
        assert!(app.lsp_mode_enabled_for(app.ad().document_buffer_id));
        assert!(app.lsp_diagnostics_mode_enabled_for(app.ad().document_buffer_id));
        app.toggle_mode_by_name("lsp-diagnostics-mode");
        assert!(app.lsp_mode_enabled_for(app.ad().document_buffer_id));
        assert!(!app.lsp_diagnostics_mode_enabled_for(app.ad().document_buffer_id));
        // Glyph suppressed.
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            !row0.contains('■'),
            "lsp-diagnostics-mode off should suppress glyph; got {row0:?}",
        );
    }

    /// 4.4.e: a seeded `documentHighlight` cache produces a
    /// background-tinted run on the matching row when
    /// `lsp-document-highlight-mode` is on.
    #[test]
    fn document_highlight_overlay_tints_matched_range() {
        use std::str::FromStr;
        let mut app = app_with("let x = x + 1;\n", 5);
        // M.5.6: the overlay gate also requires lsp-mode.
        // Seed a URI so the mode gate's URI check passes (the
        // overlay also checks lsp_document_highlight_mode).
        let uri = lattice_lsp::Uri::from_str("file:///tmp/x.rs").unwrap();
        let doc_id = app.ad().document_buffer_id;
        app.editor.buffer_uris.insert(doc_id, uri);
        if !app.lsp_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-mode");
        }
        // `lsp-document-highlight-mode` should have cascaded
        // on with lsp-mode (capability cascade is per-mode);
        // if not, force it.
        if !app.lsp_document_highlight_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-document-highlight-mode");
        }
        // 5.8.AF.5 / Slice 3b.0: `lsp_document_highlights` is
        // now `Arc<ArcSwapOption<...>>`. Tests `.store()` the
        // cache and `publish_render_state()` so renderer reads
        // via `RenderState` reflect the seeded value (mirrors
        // the prod path where the spawned task stores + the
        // ArcSwap is shared with the render-state snapshot).
        app.editor
            .lsp_document_highlights
            .store(Some(std::sync::Arc::new(
                crate::app::DocumentHighlightCache {
                    buffer_id: app.ad().document_buffer_id,
                    cursor: lattice_protocol::Position::new(0, 4),
                    highlights: vec![
                        lattice_lsp::lsp_types::DocumentHighlight {
                            range: lattice_lsp::lsp_types::Range {
                                start: lattice_lsp::lsp_types::Position {
                                    line: 0,
                                    character: 4,
                                },
                                end: lattice_lsp::lsp_types::Position {
                                    line: 0,
                                    character: 5,
                                },
                            },
                            kind: Some(lattice_lsp::lsp_types::DocumentHighlightKind::WRITE),
                        },
                        lattice_lsp::lsp_types::DocumentHighlight {
                            range: lattice_lsp::lsp_types::Range {
                                start: lattice_lsp::lsp_types::Position {
                                    line: 0,
                                    character: 8,
                                },
                                end: lattice_lsp::lsp_types::Position {
                                    line: 0,
                                    character: 9,
                                },
                            },
                            kind: Some(lattice_lsp::lsp_types::DocumentHighlightKind::READ),
                        },
                    ],
                },
            )));
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        // Walk the spans on row 0; expect at least one span
        // with the read tint (rgb(20,50,25)) and one with the
        // write tint (rgb(60,20,20)). Span splitting depends on
        // overlay composition, so we tolerate any number of
        // them as long as both tints appear at least once.
        let row0 = &lines[0];
        let mut saw_read = false;
        let mut saw_write = false;
        for span in &row0.spans {
            match span.style.bg {
                Some(Color::Rgb(20, 50, 25)) => saw_read = true,
                Some(Color::Rgb(60, 20, 20)) => saw_write = true,
                _ => {}
            }
        }
        assert!(saw_read, "expected READ tint span; got {row0:?}");
        assert!(saw_write, "expected WRITE tint span; got {row0:?}");
    }

    /// 4.4.g: a seeded inlay-hint cache produces a virtual
    /// span at the hint's character position, styled with the
    /// inlay-hint italic+dim color.
    #[test]
    fn inlay_hint_overlay_splices_virtual_text() {
        use std::str::FromStr;
        let mut app = app_with("let x = 1;\n", 5);
        let uri = lattice_lsp::Uri::from_str("file:///tmp/x.rs").unwrap();
        let doc_id = app.ad().document_buffer_id;
        app.editor.buffer_uris.insert(doc_id, uri);
        if !app.lsp_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-mode");
        }
        if !app.lsp_inlay_hint_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-inlay-hint-mode");
        }
        // Hint at column 5 (end of "let x") with label ": i32".
        // 5.8.AF.5 / Slice 3b.1: use `insert_for` + publish.
        {
            use lattice_host::per_buffer_cache::PerBufferCacheExt;
            app.editor.lsp_inlay_hints_cache.insert_for(
                app.ad().document_buffer_id,
                crate::app::LspInlayHintCache {
                    document_version: app.editor.document.snapshot().version,
                    hints: vec![lattice_lsp::lsp_types::InlayHint {
                        position: lattice_lsp::lsp_types::Position {
                            line: 0,
                            character: 5,
                        },
                        label: lattice_lsp::lsp_types::InlayHintLabel::String(": i32".into()),
                        kind: Some(lattice_lsp::lsp_types::InlayHintKind::TYPE),
                        text_edits: None,
                        tooltip: None,
                        padding_left: Some(false),
                        padding_right: Some(false),
                        data: None,
                    }],
                    requested_first_line: 0,
                    requested_last_line: u32::MAX,
                },
            );
        }
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        // T.6: inlay-hint fg now resolves from the `inlay.hint` element
        // (shared with GPUI). Derive the expected fg from the same
        // resolved table the renderer reads, so this stays a parity pin.
        let cells_rs = app.render_state.load().cells.load_full();
        let expected_fg = inlay_hint_style(&cells_rs.resolved_theme, &cells_rs.theme_ids).fg;
        let row0 = &lines[0];
        let mut found = false;
        for span in &row0.spans {
            if span.content.as_ref().contains(": i32") {
                assert_eq!(span.style.fg, expected_fg);
                found = true;
            }
        }
        assert!(found, "expected `: i32` inlay-hint span; got {row0:?}");
    }

    /// Inlay-hint de-duplication (2026-06-30): an INACTIVE pane renders
    /// inlay hints through the SAME single path as the active pane —
    /// `view.inlay_hints` (per-buffer). Guards the unified
    /// `inlay_hints_for_buffer` source against a regression back to the
    /// active-only / inactive-LSP-cache split.
    #[test]
    fn inactive_pane_renders_inlay_hints_like_active() {
        use std::str::FromStr;
        let mut app = app_with("let x = 1;\n", 5);
        let uri = lattice_lsp::Uri::from_str("file:///tmp/x.rs").unwrap();
        let doc_id = app.ad().document_buffer_id;
        app.editor.buffer_uris.insert(doc_id, uri);
        if !app.lsp_mode_enabled_for(doc_id) {
            app.toggle_mode_by_name("lsp-mode");
        }
        if !app.lsp_inlay_hint_mode_enabled_for(doc_id) {
            app.toggle_mode_by_name("lsp-inlay-hint-mode");
        }
        {
            use lattice_host::per_buffer_cache::PerBufferCacheExt;
            app.editor.lsp_inlay_hints_cache.insert_for(
                doc_id,
                crate::app::LspInlayHintCache {
                    document_version: app.editor.document.snapshot().version,
                    hints: vec![lattice_lsp::lsp_types::InlayHint {
                        position: lattice_lsp::lsp_types::Position {
                            line: 0,
                            character: 5,
                        },
                        label: lattice_lsp::lsp_types::InlayHintLabel::String(": i32".into()),
                        kind: Some(lattice_lsp::lsp_types::InlayHintKind::TYPE),
                        text_edits: None,
                        tooltip: None,
                        padding_left: Some(false),
                        padding_right: Some(false),
                        data: None,
                    }],
                    requested_first_line: 0,
                    requested_last_line: u32::MAX,
                },
            );
        }
        app.editor.publish_render_state();

        // Compose the buffer as an INACTIVE pane.
        let view = FrameView::for_buffer(&app, doc_id);
        let ctx = PaneComposeCtx {
            is_active: false,
            pane_id: app.panes().tree.active().id,
            buffer_id: doc_id,
            cursor_line: app.ad().cursor.line,
            cursor_line_highlight: false,
            scroll: app.ad().scroll,
            leftcol: app.ad().leftcol,
            display_line_numbers: app.ad().display_line_numbers.clone(),
        };
        let lines = compose_pane_lines(&view, &app.ad().snapshot.clone(), 5, 80, &ctx);
        let blob: String = lines.iter().map(line_text).collect::<Vec<_>>().join("");
        assert!(
            blob.contains(": i32"),
            "inactive pane lost its inlay hint via the unified path: {blob}"
        );
    }

    /// MR.1: an unselected annotation's color now reads the registered
    /// `completion.annotation.*` theme slot (was a hardcoded `Color::*`
    /// before; GPUI already did this via T.6). Closes the TUI theme gap.
    #[test]
    fn annotation_color_reads_theme_for_unselected_rows() {
        let app = app_with("x\n", 5);
        let cells = app.render_state.load().cells.load_full();
        let resolved = &cells.resolved_theme;
        let ids = &cells.theme_ids;
        let kind = lattice_completion::Annotation::Kind("motion".into());
        let got = super::annotation_color(&kind, false, resolved, ids);
        let want = resolved
            .get(ids.completion_annotation_kind)
            .fg
            .map(crate::theme::host_color_to_ratatui)
            .expect("completion.annotation.kind has a default fg");
        assert_eq!(
            got, want,
            "unselected annotation fg must resolve from completion.annotation.kind"
        );
    }

    /// MR.1: the selected-row brightening stays renderer logic (a
    /// brightened literal), NOT a theme read — mirrors the GPUI peer's
    /// `annotation_color_rgb` exactly so the two peers agree.
    #[test]
    fn annotation_color_brightens_selected_independent_of_theme() {
        let app = app_with("x\n", 5);
        let cells = app.render_state.load().cells.load_full();
        let kind = lattice_completion::Annotation::Kind("motion".into());
        let got = super::annotation_color(&kind, true, &cells.resolved_theme, &cells.theme_ids);
        // Same brightened literal GPUI returns for a selected Kind row.
        assert_eq!(got, Color::Rgb(0xcd, 0xd6, 0xf4));
    }

    /// MR.2: a `Styled` annotation paints one span per segment, each
    /// colored by its own theme slot — the per-bit permission coloring.
    #[test]
    fn styled_annotation_paints_each_segment_with_its_slot_color() {
        let app = app_with("x\n", 5);
        let cells = app.render_state.load().cells.load_full();
        let resolved = &cells.resolved_theme;
        let ids = &cells.theme_ids;
        let perm = lattice_completion::Annotation::Styled {
            category: "perm".into(),
            segments: vec![
                lattice_completion::AnnotationSegment {
                    text: "w".into(),
                    slot: "completion.annotation.perm.write".into(),
                },
                lattice_completion::AnnotationSegment {
                    text: "x".into(),
                    slot: "completion.annotation.perm.exec".into(),
                },
            ],
        };
        let scored = lattice_completion::ScoredCandidate {
            raw: lattice_completion::RawCandidate::plain(
                "f",
                lattice_completion::CandidateKind::Plain,
            ),
            score: lattice_completion::MatchScore::PERFECT,
            match_ranges: vec![],
        };
        let mut c = lattice_completion::RenderedCandidate::from_scored(scored);
        c.annotations = vec![perm];
        let cols = lattice_completion::AnnotationColumns::from_visible(std::iter::once(&c));
        let line = super::candidate_to_line(&c, false, 1, &cols, resolved, ids);

        let want = |id| {
            resolved
                .get(id)
                .fg
                .map(crate::theme::host_color_to_ratatui)
                .unwrap()
        };
        let w = line
            .spans
            .iter()
            .find(|s| s.content.as_ref() == "w")
            .expect("w span");
        let x = line
            .spans
            .iter()
            .find(|s| s.content.as_ref() == "x")
            .expect("x span");
        assert_eq!(w.style.fg, Some(want(ids.completion_annotation_perm_write)));
        assert_eq!(x.style.fg, Some(want(ids.completion_annotation_perm_exec)));
    }

    /// MR.4: a theme change recolors styled marginalia on the TUI peer —
    /// overriding the `perm.write` element changes the rendered `w`
    /// segment's fg through `candidate_to_line`.
    #[test]
    fn styled_segment_recolors_on_theme_change_tui() {
        use lattice_host::ui::theme::{
            BuiltinElementIds, ElementName, InMemoryThemeRegistry, StyleSpec, ThemeRegistry,
        };
        let reg = InMemoryThemeRegistry::with_defaults();
        let ids = BuiltinElementIds::capture(&reg);
        let perm = lattice_completion::Annotation::Styled {
            category: "perm".into(),
            segments: vec![lattice_completion::AnnotationSegment {
                text: "w".into(),
                slot: "completion.annotation.perm.write".into(),
            }],
        };
        let scored = lattice_completion::ScoredCandidate {
            raw: lattice_completion::RawCandidate::plain(
                "f",
                lattice_completion::CandidateKind::Plain,
            ),
            score: lattice_completion::MatchScore::PERFECT,
            match_ranges: vec![],
        };
        let mut c = lattice_completion::RenderedCandidate::from_scored(scored);
        c.annotations = vec![perm];
        let cols = lattice_completion::AnnotationColumns::from_visible(std::iter::once(&c));
        let w_fg = |reg: &InMemoryThemeRegistry| {
            let r = reg.resolved();
            let line = super::candidate_to_line(&c, false, 1, &cols, &r, &ids);
            line.spans
                .iter()
                .find(|s| s.content.as_ref() == "w")
                .map(|s| s.style.fg)
        };
        let before = w_fg(&reg);
        reg.set_override(
            ElementName::from_static("completion.annotation.perm.write"),
            StyleSpec::new().fg("green"),
        );
        let after = w_fg(&reg);
        assert_ne!(
            before, after,
            "styled marginalia tracks the active theme on TUI"
        );
    }

    /// PH.1: a candidate's `display_spans` syntax-color the
    /// preview run, composing with fuzzy match-highlight so the
    /// match style wins on overlap (picker-preview-highlight.md
    /// §5). The matched prefix paints cyan+bold (match), the
    /// non-matched suffix keeps the keyword syntax color.
    #[test]
    fn display_spans_compose_with_match_highlight_tui() {
        let app = app_with("x\n", 5);
        let cells = app.render_state.load().cells.load_full();
        let resolved = &cells.resolved_theme;
        let ids = &cells.theme_ids;

        // "test": whole word colored as Keyword; first half "te"
        // also a fuzzy match.
        let scored = lattice_completion::ScoredCandidate {
            raw: lattice_completion::RawCandidate::plain(
                "test",
                lattice_completion::CandidateKind::Plain,
            ),
            score: lattice_completion::MatchScore::PERFECT,
            match_ranges: Vec::from([0..2]),
        };
        let mut c = lattice_completion::RenderedCandidate::from_scored(scored);
        c.raw.display_spans = vec![lattice_completion::DisplaySpan {
            range: 0..4,
            style: lattice_cells::style::Style::Keyword,
        }];
        let cols = lattice_completion::AnnotationColumns::from_visible(std::iter::once(&c));
        let line = super::candidate_to_line(&c, false, 1, &cols, resolved, ids);

        let keyword_fg = resolved
            .get(ids.syntax_keyword)
            .fg
            .map(crate::theme::host_color_to_ratatui);

        // Matched prefix "te" paints the match style, NOT keyword.
        let te = line
            .spans
            .iter()
            .find(|s| s.content.as_ref() == "te")
            .expect("matched run");
        assert_eq!(te.style.fg, Some(Color::Cyan), "match wins on overlap");
        assert!(te.style.add_modifier.contains(Modifier::BOLD));
        // Non-matched suffix "st" keeps the keyword syntax color.
        let st = line
            .spans
            .iter()
            .find(|s| s.content.as_ref() == "st")
            .expect("syntax run");
        assert_eq!(st.style.fg, keyword_fg);
        assert_ne!(st.style.fg, Some(Color::Cyan));
    }

    /// PH.1: a `:colorscheme` swap recolors preview syntax spans
    /// live on the TUI peer — overriding `syntax.keyword` changes
    /// the rendered keyword-span fg (semantic `Style` resolved at
    /// the seam, never baked).
    #[test]
    fn display_spans_recolor_on_theme_change_tui() {
        use lattice_host::ui::theme::{
            BuiltinElementIds, ElementName, InMemoryThemeRegistry, StyleSpec, ThemeRegistry,
        };
        let reg = InMemoryThemeRegistry::with_defaults();
        let ids = BuiltinElementIds::capture(&reg);
        let scored = lattice_completion::ScoredCandidate {
            raw: lattice_completion::RawCandidate::plain(
                "kw",
                lattice_completion::CandidateKind::Plain,
            ),
            score: lattice_completion::MatchScore::PERFECT,
            match_ranges: vec![],
        };
        let mut c = lattice_completion::RenderedCandidate::from_scored(scored);
        c.raw.display_spans = vec![lattice_completion::DisplaySpan {
            range: 0..2,
            style: lattice_cells::style::Style::Keyword,
        }];
        let cols = lattice_completion::AnnotationColumns::from_visible(std::iter::once(&c));
        let kw_fg = |reg: &InMemoryThemeRegistry| {
            let r = reg.resolved();
            let line = super::candidate_to_line(&c, false, 1, &cols, &r, &ids);
            line.spans
                .iter()
                .find(|s| s.content.as_ref() == "kw")
                .map(|s| s.style.fg)
        };
        let before = kw_fg(&reg);
        reg.set_override(
            ElementName::from_static("syntax.keyword"),
            StyleSpec::new().fg("green"),
        );
        let after = kw_fg(&reg);
        assert_ne!(
            before, after,
            "preview syntax color tracks the active theme on TUI"
        );
    }

    /// 4.4.h: a seeded semantic-tokens cache repaints the
    /// foreground color within each token's byte range.
    #[test]
    fn semantic_tokens_overlay_repaints_fg_within_token_range() {
        use std::str::FromStr;
        let mut app = app_with("fn main() {}\n", 5);
        let uri = lattice_lsp::Uri::from_str("file:///tmp/x.rs").unwrap();
        let doc_id = app.ad().document_buffer_id;
        app.editor.buffer_uris.insert(doc_id, uri);
        if !app.lsp_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-mode");
        }
        if !app.lsp_semantic_tokens_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-semantic-tokens-mode");
        }
        // Seed: "fn" as keyword (chars 0..=1), "main" as function
        // (chars 3..=6).
        // 5.8.AF.5 / Slice 3b.2: `lsp_semantic_tokens_cache` is
        // now a `PerBufferCache<...>`; use `insert_for` + publish.
        {
            use lattice_host::per_buffer_cache::PerBufferCacheExt;
            app.editor.lsp_semantic_tokens_cache.insert_for(
                app.ad().document_buffer_id,
                crate::app::LspSemanticTokensCache {
                    document_version: app.editor.document.snapshot().version,
                    result_id: None,
                    raw_data: Vec::new(),
                    tokens: vec![
                        crate::app::DecodedSemanticToken {
                            line: 0,
                            start_char: 0,
                            length: 2,
                            token_type: "keyword".into(),
                            modifiers: Vec::new(),
                        },
                        crate::app::DecodedSemanticToken {
                            line: 0,
                            start_char: 3,
                            length: 4,
                            token_type: "function".into(),
                            modifiers: Vec::new(),
                        },
                    ],
                },
            );
        }
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = &lines[0];
        // Magenta = keyword, Yellow = function. Find at least
        // one span of each in the row.
        let mut saw_keyword = false;
        let mut saw_function = false;
        for span in &row0.spans {
            match span.style.fg {
                Some(Color::Magenta) if span.content.as_ref().contains("fn") => {
                    saw_keyword = true;
                }
                Some(Color::Yellow) if span.content.as_ref().contains("main") => {
                    saw_function = true;
                }
                _ => {}
            }
        }
        assert!(saw_keyword, "expected keyword fg on `fn`; got {row0:?}");
        assert!(saw_function, "expected function fg on `main`; got {row0:?}");
    }

    /// 4.4.h: with the mode off, the cache is ignored.
    #[test]
    fn semantic_tokens_overlay_suppressed_when_mode_off() {
        use std::str::FromStr;
        let mut app = app_with("fn main() {}\n", 5);
        let uri = lattice_lsp::Uri::from_str("file:///tmp/x.rs").unwrap();
        let doc_id = app.ad().document_buffer_id;
        app.editor.buffer_uris.insert(doc_id, uri);
        if !app.lsp_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-mode");
        }
        if app.lsp_semantic_tokens_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-semantic-tokens-mode");
        }
        // 5.8.AF.5 / Slice 3b.2: see seed pattern note above.
        {
            use lattice_host::per_buffer_cache::PerBufferCacheExt;
            app.editor.lsp_semantic_tokens_cache.insert_for(
                app.ad().document_buffer_id,
                crate::app::LspSemanticTokensCache {
                    document_version: app.editor.document.snapshot().version,
                    result_id: None,
                    raw_data: Vec::new(),
                    tokens: vec![crate::app::DecodedSemanticToken {
                        line: 0,
                        start_char: 0,
                        length: 2,
                        token_type: "keyword".into(),
                        modifiers: Vec::new(),
                    }],
                },
            );
        }
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = &lines[0];
        // No magenta fg should appear on the "fn" span.
        for span in &row0.spans {
            if span.content.as_ref().contains("fn") {
                assert_ne!(
                    span.style.fg,
                    Some(Color::Magenta),
                    "mode-off should suppress semantic-tokens overlay; got {span:?}"
                );
            }
        }
    }

    /// 4.4.g: with the mode off, the cache content is ignored
    /// and the overlay does not paint.
    #[test]
    fn inlay_hint_overlay_suppressed_when_mode_off() {
        use std::str::FromStr;
        let mut app = app_with("let x = 1;\n", 5);
        let uri = lattice_lsp::Uri::from_str("file:///tmp/x.rs").unwrap();
        let doc_id = app.ad().document_buffer_id;
        app.editor.buffer_uris.insert(doc_id, uri);
        if !app.lsp_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-mode");
        }
        // Force mode OFF.
        if app.lsp_inlay_hint_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-inlay-hint-mode");
        }
        // 5.8.AF.5 / Slice 3b.1: use `insert_for` + publish.
        {
            use lattice_host::per_buffer_cache::PerBufferCacheExt;
            app.editor.lsp_inlay_hints_cache.insert_for(
                app.ad().document_buffer_id,
                crate::app::LspInlayHintCache {
                    document_version: app.editor.document.snapshot().version,
                    hints: vec![lattice_lsp::lsp_types::InlayHint {
                        position: lattice_lsp::lsp_types::Position {
                            line: 0,
                            character: 5,
                        },
                        label: lattice_lsp::lsp_types::InlayHintLabel::String(": i32".into()),
                        kind: None,
                        text_edits: None,
                        tooltip: None,
                        padding_left: None,
                        padding_right: None,
                        data: None,
                    }],
                    requested_first_line: 0,
                    requested_last_line: u32::MAX,
                },
            );
        }
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = &lines[0];
        for span in &row0.spans {
            assert!(
                !span.content.as_ref().contains(": i32"),
                "mode-off should suppress hint span; got {span:?}"
            );
        }
    }

    /// 4.4.e: with the mode off, the overlay must NOT paint --
    /// even if the cache still holds entries (mode disable is
    /// a render-side gate).
    #[test]
    fn document_highlight_overlay_suppressed_when_mode_off() {
        use std::str::FromStr;
        let mut app = app_with("let x = x;\n", 5);
        let uri = lattice_lsp::Uri::from_str("file:///tmp/x.rs").unwrap();
        let doc_id = app.ad().document_buffer_id;
        app.editor.buffer_uris.insert(doc_id, uri);
        if !app.lsp_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-mode");
        }
        // Force the sub-mode OFF (lsp-mode cascade may have
        // turned it on by default).
        if app.lsp_document_highlight_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-document-highlight-mode");
        }
        // 5.8.AF.5 / Slice 3b.0: see seed pattern note above.
        app.editor
            .lsp_document_highlights
            .store(Some(std::sync::Arc::new(
                crate::app::DocumentHighlightCache {
                    buffer_id: app.ad().document_buffer_id,
                    cursor: lattice_protocol::Position::new(0, 4),
                    highlights: vec![lattice_lsp::lsp_types::DocumentHighlight {
                        range: lattice_lsp::lsp_types::Range {
                            start: lattice_lsp::lsp_types::Position {
                                line: 0,
                                character: 4,
                            },
                            end: lattice_lsp::lsp_types::Position {
                                line: 0,
                                character: 5,
                            },
                        },
                        kind: None,
                    }],
                },
            )));
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = &lines[0];
        for span in &row0.spans {
            // No DH-tinted span should appear.
            assert!(
                !matches!(span.style.bg, Some(Color::Rgb(20, 30, 60))),
                "expected suppressed; got tinted span: {span:?}"
            );
        }
    }

    /// SG.2b: define a sign and return its id. Goes through the registered
    /// `SignRegistryHandle` service — the same handle a provider's install
    /// or a plugin's load writes — so a test that passes here proves the
    /// boot wiring, not just the paint code.
    fn define_sign(app: &App, name: &str, glyph: char, priority: i32) -> lattice_mode::SignId {
        let handle = app
            .editor
            .services
            .get::<lattice_mode::SignRegistryHandle>()
            .expect("SG.2b: boot registers the sign registry service");
        let mut reg = (**handle.load()).clone();
        let id = reg.define(lattice_mode::SignDefinition {
            name: name.to_string(),
            text: glyph.to_string(),
            fallback: glyph.to_string(),
            theme_element: format!("gutter.sign.{name}"),
            priority,
            column: lattice_mode::SIGN_COLUMN_MARK.to_string(),
        });
        handle.store(std::sync::Arc::new(reg));
        id
    }

    /// SG.2b: place signs on lines through the WASM decoration cache — the
    /// path a plugin's producer writes, read wait-free by the renderer.
    fn place_signs(app: &mut App, placements: &[(u32, lattice_mode::SignId)]) {
        use lattice_host::per_buffer_cache::PerBufferCacheExt;
        let buffer_id = app.ad().document_buffer_id;
        let cache = &app.editor.wasm_decorations.cache;
        cache.insert_for(
            buffer_id,
            lattice_host::wasm_decorations::WasmGutterDecorationCache {
                document_version: 0,
                decorations: placements
                    .iter()
                    .map(|(line, sign)| lattice_mode::GutterDecoration::Sign {
                        line: *line,
                        sign: *sign,
                    })
                    .collect(),
            },
        );
        app.editor.publish_render_state();
    }

    #[test]
    fn a_placed_sign_paints_in_the_gutter_mark_cell() {
        let mut app = app_with("fn main() {}\nlet x = 1;\n", 5);
        let id = define_sign(&app, "test-mark", '◆', 5);
        place_signs(&mut app, &[(0, id)]);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(row0.contains('◆'), "expected the sign glyph; got {row0:?}");
        let row1 = line_text(&lines[1]);
        assert!(
            !row1.contains('◆'),
            "an unmarked line must stay clean: {row1:?}"
        );
    }

    #[test]
    fn a_default_priority_sign_yields_the_cell_to_a_diagnostic() {
        // The two share one cell, so one of them loses it. A sign at vim's
        // default priority (10, level with the LOWEST diagnostic) loses to an
        // error outright — an error is a state of the user's code they did not
        // ask for, and it must not be hidden by a mark somebody chose to show.
        let mut app = app_with("fn main() {}\n", 5);
        seed_diagnostic(
            &mut app,
            0,
            0,
            7,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "boom",
        );
        let id = define_sign(&app, "tie", '◆', lattice_mode::DIAGNOSTIC_HINT_PRIORITY);
        place_signs(&mut app, &[(0, id)]);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(row0.contains('■'), "the error must hold the cell: {row0:?}");
        assert!(!row0.contains('◆'), "the sign must yield: {row0:?}");
    }

    #[test]
    fn a_higher_priority_sign_takes_the_cell_from_a_diagnostic() {
        // The escape hatch for a producer that genuinely outranks an error —
        // a debugger stopped on this very line. It says so by exceeding
        // `DIAGNOSTIC_ERROR_PRIORITY`, not by being placed later.
        //
        // SG.4b raised that bar. A diagnostic used to hold the cell at one
        // priority (`SEVERITY_SIGN_PRIORITY`, 10) whatever its severity, so
        // any sign above 10 displaced an ERROR. Now the severities span
        // 10..40 — which is what carries "most severe wins" through the
        // unification — and displacing an error means beating 40. The
        // stricter reading is the right one: a sign that hides a compiler
        // error had better mean it.
        let mut app = app_with("fn main() {}\n", 5);
        seed_diagnostic(
            &mut app,
            0,
            0,
            7,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "boom",
        );
        let id = define_sign(
            &app,
            "stop",
            '◆',
            lattice_mode::DIAGNOSTIC_ERROR_PRIORITY + 1,
        );
        place_signs(&mut app, &[(0, id)]);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(row0.contains('◆'), "the sign must hold the cell: {row0:?}");
        assert!(!row0.contains('■'), "the error must yield: {row0:?}");
    }

    #[test]
    fn the_higher_priority_sign_wins_the_cell() {
        // Two producers, one line. The winner is the higher priority, not
        // whichever the decoration walk reached last.
        let mut app = app_with("fn main() {}\n", 5);
        let low = define_sign(&app, "low", '◆', 1);
        let high = define_sign(&app, "high", '■', 9);
        place_signs(&mut app, &[(0, high), (0, low)]);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(row0.contains('■'), "higher priority must win: {row0:?}");
        assert!(!row0.contains('◆'), "lower priority must lose: {row0:?}");
    }

    #[test]
    fn a_retired_sign_id_paints_nothing_rather_than_a_later_sign() {
        // SG.1 retires ids instead of reusing them so that a placement
        // produced before an `undefine` paints NOTHING. A reused slot would
        // paint some later sign's glyph, and a wrong answer in place of the
        // right one is worse than a blank — it is also the silent one.
        let mut app = app_with("fn main() {}\n", 5);
        let doomed = define_sign(&app, "doomed", '◆', 5);
        {
            let handle = app
                .editor
                .services
                .get::<lattice_mode::SignRegistryHandle>()
                .unwrap();
            let mut reg = (**handle.load()).clone();
            reg.undefine("doomed");
            // A later definition must not inherit the retired slot.
            reg.define(lattice_mode::SignDefinition {
                name: "successor".into(),
                text: "■".into(),
                fallback: "■".into(),
                theme_element: "gutter.sign.successor".into(),
                priority: 5,
                column: lattice_mode::SIGN_COLUMN_MARK.into(),
            });
            handle.store(std::sync::Arc::new(reg));
        }
        place_signs(&mut app, &[(0, doomed)]);
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            !row0.contains('◆'),
            "the retired sign must not paint: {row0:?}"
        );
        assert!(
            !row0.contains('■'),
            "and must not paint its successor's glyph either: {row0:?}"
        );
    }

    #[test]
    fn a_sign_does_not_shift_the_content_column() {
        // The reason signs share the mark cell rather than getting their own
        // column: a gutter that widens when a sign arrives is a pixel change
        // to content the user did not edit. Same row, with and without.
        let mut app = app_with("fn main() {}\n", 5);
        let before = line_text(&compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80)[0]);
        let id = define_sign(&app, "shift", '◆', 5);
        place_signs(&mut app, &[(0, id)]);
        let after = line_text(&compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80)[0]);
        // Compare the CHARACTER column, not the byte offset — the glyph is
        // multi-byte, and a byte-offset comparison would report a shift the
        // terminal never renders.
        let col = |row: &str| {
            let idx = row.find("fn main").expect("content row");
            row[..idx].chars().count()
        };
        assert_eq!(
            col(&before),
            col(&after),
            "the sign must not move the content: {before:?} vs {after:?}"
        );
    }

    #[test]
    fn diagnostic_severity_glyph_appears_in_gutter_for_error() {
        let mut app = app_with("fn main() {}\nlet x = 1;\n", 5);
        seed_diagnostic(
            &mut app,
            0,
            0,
            7,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "boom",
        );
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        // Row 0 has the error; expect the ■ glyph somewhere in
        // the rendered first span (the severity cell).
        let row0 = line_text(&lines[0]);
        assert!(
            row0.contains('■'),
            "expected error glyph on diag line; got {row0:?}"
        );
        // Row 1 has no diagnostic; should NOT have any
        // severity glyph.
        let row1 = line_text(&lines[1]);
        assert!(!row1.contains('■'), "row 1 should be clean: {row1:?}");
        assert!(!row1.contains('▲'), "row 1 should be clean: {row1:?}");
    }

    #[test]
    fn diagnostic_warning_uses_triangle_glyph() {
        let mut app = app_with("hello\n", 3);
        seed_diagnostic(
            &mut app,
            0,
            0,
            5,
            lattice_lsp::DiagnosticSeverity::WARNING,
            "warn",
        );
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 3, 80);
        let row0 = line_text(&lines[0]);
        assert!(row0.contains('▲'), "expected warning glyph; got {row0:?}");
    }

    #[test]
    fn diagnostic_hint_uses_dot_glyph() {
        let mut app = app_with("hello\n", 3);
        seed_diagnostic(
            &mut app,
            0,
            0,
            1,
            lattice_lsp::DiagnosticSeverity::HINT,
            "hint",
        );
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 3, 80);
        let row0 = line_text(&lines[0]);
        assert!(row0.contains('·'), "expected hint glyph; got {row0:?}");
    }

    #[test]
    fn most_severe_wins_per_line() {
        let mut app = app_with("hello\n", 3);
        seed_diagnostic(
            &mut app,
            0,
            0,
            3,
            lattice_lsp::DiagnosticSeverity::WARNING,
            "warn",
        );
        seed_diagnostic(
            &mut app,
            0,
            2,
            5,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "err",
        );
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 3, 80);
        let row0 = line_text(&lines[0]);
        // Error wins over warning on the same line for the
        // gutter glyph (most-severe semantics).
        assert!(row0.contains('■'), "row0 expected ■: {row0:?}");
    }

    #[test]
    fn no_lsp_attachment_no_severity_glyph() {
        let app = app_with("hello\n", 3);
        // No buffer_uri mapping -> no diagnostics queryable.
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 3, 80);
        let row0 = line_text(&lines[0]);
        assert!(!row0.contains('■'), "no LSP -> no error glyph: {row0:?}");
        assert!(!row0.contains('▲'), "no LSP -> no warn glyph: {row0:?}");
    }

    /// L4a.3: the inline cursor-line diagnostic summary renders as
    /// trailing eol text on the cursor's line once the idle gate fires.
    #[test]
    fn inline_diagnostic_summary_renders_at_eol_on_cursor_line() {
        let mut app = app_with("let x = 1;\n", 3);
        seed_diagnostic(
            &mut app,
            0,
            0,
            5,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "boom error",
        );
        // seed_diagnostic enables lsp-mode (cascading lsp-diagnostics-
        // mode on); ensure the render-side diagnostics gate is active.
        if !app.lsp_diagnostics_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-diagnostics-mode");
        }
        // Cursor is on line 0 by default. Arm the idle gate, then fire
        // it (simulating the ~300 ms settle) so the summary is visible.
        app.editor.publish_render_state();
        app.editor.fire_inline_diag_gate();
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 3, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            row0.contains("boom error"),
            "eol summary expected on the cursor line: {row0:?}"
        );
    }

    /// L4a.3: the summary respects the render-side lsp-diagnostics-mode
    /// gate — with the mode off it is suppressed even though the host
    /// gate published it (matching the gutter / underline gate).
    #[test]
    fn inline_diagnostic_summary_suppressed_when_diagnostics_mode_off() {
        let mut app = app_with("let x = 1;\n", 3);
        seed_diagnostic(
            &mut app,
            0,
            0,
            5,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "boom error",
        );
        // Force lsp-diagnostics-mode OFF (the lsp-mode cascade in
        // seed_diagnostic may have enabled it).
        if app.lsp_diagnostics_mode_enabled_for(app.ad().document_buffer_id) {
            app.toggle_mode_by_name("lsp-diagnostics-mode");
        }
        app.editor.publish_render_state();
        app.editor.fire_inline_diag_gate();
        app.editor.publish_render_state();
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 3, 80);
        let row0 = line_text(&lines[0]);
        assert!(
            !row0.contains("boom error"),
            "mode-off must suppress the eol summary: {row0:?}"
        );
    }

    #[test]
    fn diagnostic_underline_modifier_applied_to_overlap_range() {
        let mut app = app_with("hello world\n", 3);
        // Underline cols 6..11 ("world") with an error.
        seed_diagnostic(
            &mut app,
            0,
            6,
            11,
            lattice_lsp::DiagnosticSeverity::ERROR,
            "err",
        );
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 3, 80);
        // Walk every span on row 0; at least one span covering
        // bytes 6..11 must have UNDERLINED set.
        let mut found_underline = false;
        for span in &lines[0].spans {
            if span.style.add_modifier.contains(Modifier::UNDERLINED)
                || span.style.sub_modifier.is_empty()
                    && span.style.add_modifier.contains(Modifier::UNDERLINED)
            {
                found_underline = true;
                break;
            }
        }
        assert!(
            found_underline,
            "expected an UNDERLINED modifier somewhere in the row's spans: {:?}",
            lines[0]
        );
    }

    /// Pins the rendering-breakage fix: when a diagnostic
    /// underlines a range on the diagnostic's line, no span on
    /// that line OR on subsequent lines may carry an explicit
    /// `underline_color`. Setting `underline_color` emits the
    /// SGR 58/59 extension codes; in terminals that don't
    /// recognise them, the parameters bleed into following
    /// SGR state and pin the foreground colour on subsequent
    /// lines (visible as "the next several lines went black").
    /// See `apply_underline_overlay`'s docstring for the full
    /// trail of evidence.
    #[test]
    fn diagnostic_underline_does_not_set_underline_color() {
        let mut app = app_with("first line\nsecond line\nthird line\n", 5);
        seed_diagnostic(
            &mut app,
            0,
            0,
            "first line".len() as u32,
            lattice_lsp::DiagnosticSeverity::WARNING,
            "unused",
        );
        let lines = compose_visible_lines(&app, &app.ad().snapshot.clone(), 5, 80);
        for (row, line) in lines.iter().enumerate() {
            for (i, span) in line.spans.iter().enumerate() {
                assert!(
                    span.style.underline_color.is_none(),
                    "row {row} span {i} ({:?}) carries underline_color {:?}; \
                     this leaks SGR 58/59 into terminals that don't support \
                     it and breaks rendering on subsequent lines",
                    span.content,
                    span.style.underline_color,
                );
            }
        }
    }

    /// Slice 3c.extension.fold-rs.test: regression scaffold.
    ///
    /// Catches the class of bug that fold-rs fixed: per-frame paint
    /// paths reaching the actor mailbox via `read_editor` /
    /// `mutate_editor`. The previous regression
    /// (`frame_120_lines/200` going from 90µs to 43.73ms because
    /// 120 per-line `read_editor` calls crept into
    /// `compose_visible_lines_inner`) would have been caught here.
    ///
    /// **Why the bound is 0**: every per-frame paint read must go
    /// through wait-free RS accessors (`ad()`, `panes()`, `popup()`,
    /// `modes()`, `buffer_locals()`, `render_state.load().X`). The
    /// `App::{read,mutate,mutate_with}_editor` seam is for cold-
    /// path App helpers (LSP autopilots, picker accept tails, ex-
    /// command bodies), never the paint loop.
    ///
    /// If a future change adds a `read_editor` call inside
    /// `compose_visible_lines` or any of its callees, this test
    /// flips red — the fix is to either lift the read to RS or
    /// route through a FrameView-cached value.
    #[test]
    fn compose_visible_lines_makes_zero_actor_calls() {
        let app = app_with("a\nb\nc\nd\ne\nf\ng\nh\ni\nj\n", 10);
        let snap = app.ad().snapshot.clone();
        // Warm any one-time setup the test fixture itself does
        // (theme construction, FrameView's first publish read,
        // tree-sitter seeding) so the snapshot we take just
        // before `compose_visible_lines` reflects steady state.
        let _warmup = compose_visible_lines(&app, &snap, 10, 80);
        let before = crate::actor_call_counter::snapshot();
        let _lines = compose_visible_lines(&app, &snap, 10, 80);
        let after = crate::actor_call_counter::snapshot();
        let delta = after - before;
        assert_eq!(
            delta, 0,
            "compose_visible_lines made {delta} actor-seam calls; \
             paint paths must read RS, not route through \
             read_editor / mutate_editor. See slice \
             3c.extension.fold-rs for the migration recipe.",
        );
    }

    /// The unfocused paint path must be as actor-free as the focused one.
    ///
    /// The guard above only ever watched `compose_visible_lines` — the path
    /// that was already clean, because it read the hot-path `option_cache`.
    /// Every OTHER pane went through `FrameView::for_buffer`, whose four
    /// option reads called `App::resolved_option` → `read_editor`: four
    /// actor-seam calls per unfocused pane per frame, in a split, forever,
    /// with nothing watching. Unifying the two painters is what surfaced it,
    /// and this is what stops it coming back on the side nobody was looking
    /// at.
    #[test]
    fn an_unfocused_panes_compose_inputs_make_zero_actor_calls() {
        let app = app_with("a\nb\nc\nd\ne\nf\ng\nh\ni\nj\n", 10);
        let pane = *app.panes().tree.active();
        let _warmup = pane_compose_inputs(&app, &pane, false);
        let before = crate::actor_call_counter::snapshot();
        let _inputs = pane_compose_inputs(&app, &pane, false);
        let after = crate::actor_call_counter::snapshot();
        let delta = after - before;
        assert_eq!(
            delta, 0,
            "an unfocused pane's compose inputs made {delta} actor-seam calls; \
             per-frame paint reads resolve through the published RS snapshot \
             (`RenderState::resolved_option_for`), never `read_editor`.",
        );
    }

    /// A pane's VIEW options do not depend on whether it is focused.
    ///
    /// `is_active` may change interaction state — whose cursor and scroll are
    /// read, whether a cursorline paints. It must not change the gutter, the
    /// wrap, the sign columns or the fold gates, which are properties of the
    /// buffer being painted.
    ///
    /// **What this does NOT prove**, stated because the name would otherwise
    /// promise it: the fixture's pane IS the active document, so the two
    /// option sources agree here and this test still passes against the old
    /// two-painter split (checked, by reintroducing it). Making them disagree
    /// needs a buffer whose MODE overrides an option — magit's
    /// `Number = false` — and that reproduction lives where it belongs, in
    /// `magit_bindings::navigating_to_a_magit_pane_does_not_give_it_the_files_gutter`.
    ///
    /// What this one guards is the shape: one builder, agreeing with itself,
    /// so a future option added to only one branch of `is_active` fails here
    /// rather than in a split three months later.
    #[test]
    fn a_panes_view_options_do_not_depend_on_whether_it_is_focused() {
        let mut app = app_with("hello\nworld\n", 5);
        // Non-vacuous: pick values that differ from the defaults, so an
        // implementation that ignored the buffer entirely would still have to
        // agree with itself on something wrong — and the assertions below
        // check the VALUES, not just that the two paths match.
        set_opt(&mut app, "number=false");
        set_opt(&mut app, "signcolumn=no");
        set_opt(&mut app, "wrap=true");
        let pane = *app.panes().tree.active();

        let (focused, focused_ctx) = pane_compose_inputs(&app, &pane, true);
        let (blurred, blurred_ctx) = pane_compose_inputs(&app, &pane, false);

        assert!(!focused.show_line_numbers, "the option actually took");
        assert_eq!(focused.show_line_numbers, blurred.show_line_numbers);
        assert_eq!(focused.sign_column, blurred.sign_column);
        assert!(!focused.sign_column);
        assert_eq!(focused.wrap_lines, blurred.wrap_lines);
        assert!(focused.wrap_lines);
        assert_eq!(focused.relative_line_numbers, blurred.relative_line_numbers);
        assert_eq!(focused.foldenable, blurred.foldenable);
        // …and both describe the pane's own buffer, not the active document.
        assert_eq!(focused_ctx.buffer_id, pane.buffer_id);
        assert_eq!(blurred_ctx.buffer_id, pane.buffer_id);
        // The one thing `is_active` is still allowed to decide.
        assert!(focused_ctx.is_active && !blurred_ctx.is_active);
    }

    // Slice 3c.final.X.cleanup: modeline-text builder must read

    /// Slice 3c.final.X.cleanup: pane-status text builder also
    /// counts as a per-frame paint path (drawn once per pane per
    /// frame in horizontal-split layouts).
    #[test]
    fn pane_status_label_makes_zero_actor_calls() {
        let app = app_with("a\nb\nc\nd\ne\n", 10);
        let pane = *app.panes().tree.active();
        let _warmup = app.pane_status_label(&pane);
        let before = crate::actor_call_counter::snapshot();
        let _label = app.pane_status_label(&pane);
        let after = crate::actor_call_counter::snapshot();
        let delta = after - before;
        assert_eq!(
            delta, 0,
            "pane_status_label made {delta} actor-seam calls; \
             status-line paths must read RS, not route through \
             read_editor.",
        );
    }

    /// Slice 3c.final.X.cleanup → I.7: `App::apply(Action::None)` is the
    /// keystroke entry point's minimum-work path. It MUST go
    /// through the actor seam — the dispatch itself is a mutation —
    /// but extra RPCs there stack up at typing rate. This test
    /// caps the count so future additions surface as a red bar.
    ///
    /// Pre-I.7 baseline was 5 RPCs per `Action::None` keystroke
    /// (`dispatch` + a four-op tail each its own `mutate_editor*`
    /// crossing). Slice I.7 fused the deterministic tail into the
    /// dispatch round-trip via [`Editor::dispatch_fused`]: when the
    /// dispatch produces no renderer-coupled work and no popup is up
    /// (the hot typing path — `Action::None` qualifies),
    /// `ensure_cursor_visible` / `maybe_reparse_syntax` /
    /// `sync_keymap_overlays` / `run_tick_pending` all run IN-actor in
    /// the same crossing.
    ///
    /// Post-I.7 baseline: **1** RPC per `Action::None` keystroke —
    /// `mutate_editor_with(|e| e.dispatch_fused(..))`, the single
    /// unavoidable command-dispatch into the actor. Everything else on
    /// the apply path (`ad()`, `cursor()`, `popup()`, the tick-signal
    /// fan-out) is a wait-free published read. On WSL2 ~0.5ms/crossing,
    /// so this is the ~6× felt-latency drop I.7 set out to deliver.
    ///
    /// Bound: ≤ 2 gives one slot of headroom. If a change pushes it
    /// past 2 the right move is to lift the new read to RS (or fold the
    /// new mutation into `dispatch_fused`'s in-actor tail), NOT to raise
    /// the bound. See docs/dev/operations/slice-plans/input-latency.md
    /// § I.7.
    #[test]
    fn apply_noop_action_makes_bounded_actor_calls() {
        let mut app = app_with("a\nb\n", 10);
        // Warmup — first apply may pay one-time setup.
        app.apply(lattice_host::action::Action::None);
        let before = crate::actor_call_counter::snapshot();
        app.apply(lattice_host::action::Action::None);
        let after = crate::actor_call_counter::snapshot();
        let delta = after - before;
        assert!(
            delta <= 2,
            "App::apply(Action::None) made {delta} actor-seam calls; \
             keystroke entry path must stay <= 2 (baseline 1 since I.7). \
             If you need to raise this you've added a per-keystroke \
             RPC — consider RS-lifting first, or fold the mutation into \
             Editor::dispatch_fused's in-actor tail. See slice I.7 \
             (docs/dev/operations/slice-plans/input-latency.md).",
        );
    }

    // --- ML.1a-render: zone layout + truncation + built-in parity -----

    #[test]
    fn truncate_to_adds_ellipsis_on_overflow() {
        assert_eq!(truncate_to("hello", 10), "hello");
        assert_eq!(truncate_to("hello", 5), "hello");
        assert_eq!(truncate_to("hello", 4), "hel…");
        assert_eq!(truncate_to("hello", 1), "…");
        assert_eq!(truncate_to("hello", 0), "");
    }

    /// A role-less run, for layout tests where the role is irrelevant.
    fn run(text: &str) -> ModelineSeg {
        ModelineSeg::filler(text.to_string())
    }
    /// ML.4: a run carrying a click target.
    fn clickable(text: &str, action: u64) -> ModelineSeg {
        ModelineSeg {
            text: text.to_string(),
            role: None,
            click: Some(lattice_protocol::CommandId(action)),
        }
    }
    /// Concatenated text of a composed segment list.
    fn seg_text(segs: &[ModelineSeg]) -> String {
        segs.iter().map(|s| s.text.as_str()).collect()
    }

    #[test]
    fn compose_row_places_left_and_right_at_edges() {
        let row = seg_text(&compose_modeline_segments(
            20,
            0,
            vec![run("L")],
            vec![],
            vec![run("R")],
        ));
        assert_eq!(row.chars().count(), 20, "row fills width");
        assert!(row.starts_with('L'), "left flush-left: {row:?}");
        assert!(row.ends_with('R'), "right flush-right: {row:?}");
    }

    #[test]
    fn compose_row_applies_edge_padding() {
        // padding 2 ⇒ a 2-col blank margin at each edge; content fills
        // the inner width; total still exactly `width`.
        let row = seg_text(&compose_modeline_segments(
            20,
            2,
            vec![run("L")],
            vec![],
            vec![run("R")],
        ));
        assert_eq!(row.chars().count(), 20, "row still fills width");
        assert!(row.starts_with("  L"), "2-col left margin: {row:?}");
        assert!(row.ends_with("R  "), "2-col right margin: {row:?}");
    }

    // --- ML.4: click regions ------------------------------------------
    //
    // The property these pin is that the recorded regions agree with
    // where the runs were painted. They are asserted against the SAME
    // composed list the painter consumes, so a layout change that moved
    // an element without moving its click target would fail here.

    use lattice_host::modeline::ModelineHitMap;

    fn hits_for(area: Rect, segs: &[ModelineSeg]) -> ModelineHitMap {
        let mut map = ModelineHitMap::new();
        record_modeline_hits(&mut map, area, segs);
        map
    }

    #[test]
    fn a_clickable_run_records_exactly_the_columns_it_paints() {
        let area = Rect::new(0, 23, 20, 1);
        let segs = compose_modeline_segments(
            20,
            0,
            vec![run("ab"), clickable("CLICK", 7)],
            vec![],
            vec![],
        );
        let hits = hits_for(area, &segs);
        // "ab" occupies 0..2, so the clickable run is 2..7.
        assert_eq!(hits.hit(1, 23), None, "the run before it is not clickable");
        assert_eq!(hits.hit(2, 23), Some(lattice_protocol::CommandId(7)));
        assert_eq!(hits.hit(6, 23), Some(lattice_protocol::CommandId(7)));
        assert_eq!(hits.hit(7, 23), None, "one past the last painted column");
    }

    #[test]
    fn padding_shifts_the_recorded_region_with_the_paint() {
        // The regression this guards: recording from the zone lists
        // rather than the composed row would put the region two
        // columns left of the glyphs under `ui.modeline.padding=2`.
        let area = Rect::new(0, 5, 20, 1);
        let segs = compose_modeline_segments(20, 2, vec![clickable("X", 3)], vec![], vec![]);
        let hits = hits_for(area, &segs);
        assert_eq!(hits.hit(1, 5), None, "inside the left margin");
        assert_eq!(hits.hit(2, 5), Some(lattice_protocol::CommandId(3)));
        assert_eq!(hits.hit(3, 5), None);
    }

    #[test]
    fn a_pane_offset_by_a_split_records_absolute_columns() {
        // A right-hand pane in a vertical split: its modeline starts at
        // column 40, so its regions must too.
        let area = Rect::new(40, 23, 20, 1);
        let segs = compose_modeline_segments(20, 0, vec![clickable("X", 9)], vec![], vec![]);
        let hits = hits_for(area, &segs);
        assert_eq!(hits.hit(0, 23), None, "the other pane's columns");
        assert_eq!(hits.hit(40, 23), Some(lattice_protocol::CommandId(9)));
    }

    #[test]
    fn an_ellipsised_run_stays_clickable() {
        // Half-visible is still that element. If clickability depended
        // on pane width the modeline would appear to randomly stop
        // working as the user resizes.
        let segs = truncate_runs(vec![clickable("verylongelement", 4)], 5);
        assert_eq!(segs.len(), 1);
        assert_eq!(segs[0].text, "very…");
        assert_eq!(segs[0].click, Some(lattice_protocol::CommandId(4)));

        let hits = hits_for(Rect::new(0, 1, 10, 1), &segs);
        assert_eq!(hits.hit(4, 1), Some(lattice_protocol::CommandId(4)));
    }

    #[test]
    fn separators_and_padding_are_not_clickable() {
        let segs = compose_modeline_segments(
            12,
            0,
            vec![clickable("A", 1)],
            vec![],
            vec![clickable("B", 2)],
        );
        let hits = hits_for(Rect::new(0, 1, 12, 1), &segs);
        assert_eq!(hits.hit(0, 1), Some(lattice_protocol::CommandId(1)));
        assert_eq!(hits.hit(11, 1), Some(lattice_protocol::CommandId(2)));
        for col in 1..11 {
            assert_eq!(hits.hit(col, 1), None, "filler at column {col} is dead");
        }
    }

    #[test]
    fn an_element_without_on_click_records_nothing() {
        let segs = compose_modeline_segments(10, 0, vec![run("plain")], vec![], vec![]);
        let hits = hits_for(Rect::new(0, 1, 10, 1), &segs);
        assert!(
            hits.is_empty(),
            "the overwhelmingly common case must cost no regions"
        );
    }

    #[test]
    fn every_run_of_a_multi_span_element_shares_one_click_target() {
        // An icon plus its label is one element to the user; clicking
        // either half must fire the same command.
        let content = lattice_mode::ElementContent {
            spans: vec![
                lattice_mode::Span {
                    text: "\u{f05a} ".into(),
                    role: lattice_mode::ModelineRole::new("x"),
                },
                lattice_mode::Span {
                    text: "label".into(),
                    role: lattice_mode::ModelineRole::new("x"),
                },
            ],
        };
        let runs = content_to_runs(content, Some(lattice_protocol::CommandId(5)));
        assert_eq!(runs.len(), 2);
        assert!(
            runs.iter()
                .all(|r| r.click == Some(lattice_protocol::CommandId(5)))
        );
    }

    #[test]
    fn compose_row_centers_center_block() {
        // width 11, "mid" (3) ⇒ offset (11-3)/2 = 4.
        let row = seg_text(&compose_modeline_segments(
            11,
            0,
            vec![],
            vec![run("mid")],
            vec![],
        ));
        assert_eq!(row, "    mid    ");
    }

    #[test]
    fn compose_row_width_zero_is_empty() {
        assert!(
            compose_modeline_segments(0, 0, vec![run("L")], vec![run("C")], vec![run("R")])
                .is_empty()
        );
    }

    #[test]
    fn compose_row_overflow_sacrifices_center_then_right_then_left() {
        // width 12: left(8) kept; sep(1); right budget 3 ⇒ "RI…";
        // center budget saturates to 0 ⇒ dropped first.
        let row = seg_text(&compose_modeline_segments(
            12,
            0,
            vec![run("LEFTLEFT")],
            vec![run("CENTER")],
            vec![run("RIGHTRIGHT")],
        ));
        assert_eq!(row.chars().count(), 12, "row fills width");
        assert!(row.starts_with("LEFTLEFT"), "left preserved last: {row:?}");
        assert!(!row.contains("CENTER"), "center sacrificed first: {row:?}");
        assert!(row.contains('…'), "right truncated with ellipsis: {row:?}");
        // Extreme narrow width must not panic.
        let _ = compose_modeline_segments(
            1,
            0,
            vec![run("LEFTLEFT")],
            vec![run("CENTER")],
            vec![run("RIGHTRIGHT")],
        );
    }

    /// ML.1b: active-pane spans carry per-role foregrounds composed over
    /// the active bar background (the `NOR` mode span is blue + bold
    /// on the surface1 bar in the default theme).
    #[test]
    fn modeline_active_spans_carry_per_role_styles() {
        use ratatui::style::{Color, Modifier};
        let app = app_with("hello", 10);
        let pane = *app.panes().tree.active();
        let spans = segments_to_spans(&app, &modeline_segments(&app, &pane, true, 60), true);

        // ML.5d: lean 3-letter tag (no brackets).
        let mode = spans
            .iter()
            .find(|s| s.content.contains("NOR"))
            .expect("mode span present");
        assert_eq!(
            mode.style.fg,
            Some(Color::Rgb(0x89, 0xb4, 0xfa)),
            "mode fg = blue"
        );
        assert!(
            mode.style.add_modifier.contains(Modifier::BOLD),
            "mode is bold"
        );
        // Every span (segments + padding) sits on the active bar bg.
        assert!(
            spans
                .iter()
                .all(|s| s.style.bg == Some(Color::Rgb(0x45, 0x47, 0x5a))),
            "whole active row sits on the surface1 bar"
        );
    }

    /// ML.1b: inactive-pane spans are uniformly muted (the single
    /// `modeline.inactive` bar style — no per-role colour).
    #[test]
    fn modeline_inactive_spans_are_uniformly_muted() {
        let app = app_with("hello", 10);
        let pane = *app.panes().tree.active();
        let spans = segments_to_spans(&app, &modeline_segments(&app, &pane, false, 60), false);
        let muted = app.theme.modeline_inactive;
        assert!(!spans.is_empty());
        assert!(
            spans.iter().all(|s| s.style == muted),
            "inactive row is uniformly muted (no per-role fg)"
        );
    }

    /// Render `draw_pane_status_line` to a `TestBackend` and read the
    /// one-row footer as a string.
    fn render_status_row(
        app: &App,
        pane: &crate::pane::PaneState,
        is_active: bool,
        width: u16,
    ) -> String {
        use ratatui::Terminal;
        use ratatui::backend::TestBackend;
        let mut terminal = Terminal::new(TestBackend::new(width, 1)).unwrap();
        terminal
            .draw(|f| {
                let area = Rect {
                    x: 0,
                    y: 0,
                    width,
                    height: 1,
                };
                draw_pane_status_line(f, area, app, pane, is_active);
            })
            .unwrap();
        let buf = terminal.backend().buffer().clone();
        (0..width)
            .map(|x| buf[(x, 0)].symbol().to_string())
            .collect()
    }

    /// Active pane: `core.mode` (`NOR`) + `core.path` in the Left
    /// zone, `core.position` right-aligned in the Right zone — the same
    /// content the legacy single-string footer showed.
    #[test]
    fn modeline_active_pane_lays_out_mode_path_position() {
        let app = app_with("hello", 10);
        let pane = *app.panes().tree.active();
        let row = render_status_row(&app, &pane, true, 40);
        assert_eq!(row.chars().count(), 40, "row fills pane width: {row:?}");
        // ML.5d: lean 3-letter tag (no brackets).
        assert!(
            row.trim_start().starts_with("NOR"),
            "Left zone leads with the modal label: {row:?}"
        );
        assert!(row.contains("[no name]"), "core.path present: {row:?}");
        assert!(
            row.trim_end().ends_with("1:0"),
            "core.position right-aligned: {row:?}"
        );
    }

    /// Inactive pane: the modal label is omitted (it is a single
    /// active-document read), but the path + position still render.
    #[test]
    fn modeline_inactive_pane_omits_modal_label() {
        let app = app_with("hello", 10);
        let pane = *app.panes().tree.active();
        let row = render_status_row(&app, &pane, false, 40);
        assert!(!row.contains("NOR"), "no modal on inactive: {row:?}");
        assert!(row.contains("[no name]"), "path still shows: {row:?}");
        assert!(
            row.trim_end().ends_with("1:0"),
            "position still shows: {row:?}"
        );
    }

    /// The footer never panics at a tiny pane width (overflow path).
    #[test]
    fn modeline_narrow_pane_does_not_panic() {
        let app = app_with("hello", 10);
        let pane = *app.panes().tree.active();
        for w in [1u16, 2, 3, 8] {
            let row = render_status_row(&app, &pane, true, w);
            assert_eq!(row.chars().count(), w as usize, "row fills width {w}");
        }
    }

    // --- pane separator geometry (draw_pane_separators) ---

    use crate::pane::PaneRect;

    /// Collect the individual `(col, row)` separator cells that
    /// `separator_segments` would paint, sorted for stable asserts.
    fn separator_cells(rects: &[(usize, PaneRect)]) -> Vec<(u16, u16)> {
        let mut cells: Vec<(u16, u16)> = separator_segments(rects)
            .into_iter()
            .flat_map(|(col, y0, y1)| (y0..y1).map(move |row| (col, row)))
            .collect();
        cells.sort_unstable();
        cells
    }

    /// A plain `:vsplit` (two equal side-by-side panes) draws a
    /// full-height divider on the left pane's right edge.
    #[test]
    fn separator_simple_vsplit_full_height() {
        // Left: (0,0,5,4)   Right: (5,0,5,4)
        let rects = vec![
            (
                0,
                PaneRect {
                    x: 0,
                    y: 0,
                    width: 5,
                    height: 4,
                },
            ),
            (
                1,
                PaneRect {
                    x: 5,
                    y: 0,
                    width: 5,
                    height: 4,
                },
            ),
        ];
        let cells = separator_cells(&rects);
        assert_eq!(cells, vec![(4, 0), (4, 1), (4, 2), (4, 3)]);
    }

    /// Regression: `:vsplit` then `:split` the LEFT pane. The left
    /// column now holds two half-height stacked panes while the right
    /// pane is full height. The divider must still be continuous over
    /// the full height — the earlier "same band" gate dropped it
    /// entirely because no pair shared identical (y, height).
    #[test]
    fn separator_subsplit_left_column_stays_continuous() {
        // Left-top:    (0,0,5,2)
        // Left-bottom: (0,2,5,2)
        // Right:       (5,0,5,4)
        let rects = vec![
            (
                0,
                PaneRect {
                    x: 0,
                    y: 0,
                    width: 5,
                    height: 2,
                },
            ),
            (
                2,
                PaneRect {
                    x: 0,
                    y: 2,
                    width: 5,
                    height: 2,
                },
            ),
            (
                1,
                PaneRect {
                    x: 5,
                    y: 0,
                    width: 5,
                    height: 4,
                },
            ),
        ];
        let cells = separator_cells(&rects);
        // Continuous column at x=4 over every row 0..4.
        assert_eq!(cells, vec![(4, 0), (4, 1), (4, 2), (4, 3)]);
    }

    /// Symmetric case: sub-split the RIGHT column instead. Still one
    /// continuous divider on the boundary column.
    #[test]
    fn separator_subsplit_right_column_stays_continuous() {
        // Left:         (0,0,5,4)
        // Right-top:    (5,0,5,2)
        // Right-bottom: (5,2,5,2)
        let rects = vec![
            (
                0,
                PaneRect {
                    x: 0,
                    y: 0,
                    width: 5,
                    height: 4,
                },
            ),
            (
                1,
                PaneRect {
                    x: 5,
                    y: 0,
                    width: 5,
                    height: 2,
                },
            ),
            (
                2,
                PaneRect {
                    x: 5,
                    y: 2,
                    width: 5,
                    height: 2,
                },
            ),
        ];
        let cells = separator_cells(&rects);
        assert_eq!(cells, vec![(4, 0), (4, 1), (4, 2), (4, 3)]);
    }

    /// A pure horizontal split (stacked panes, same column) has no
    /// vertical separator — the per-pane status line divides them.
    #[test]
    fn separator_horizontal_split_has_no_vertical_divider() {
        let rects = vec![
            (
                0,
                PaneRect {
                    x: 0,
                    y: 0,
                    width: 10,
                    height: 2,
                },
            ),
            (
                1,
                PaneRect {
                    x: 0,
                    y: 2,
                    width: 10,
                    height: 2,
                },
            ),
        ];
        assert!(separator_cells(&rects).is_empty());
    }
}

#[cfg(test)]
mod notification_line_tests {
    use super::notification_line;
    use lattice_notify::{Notification, NotificationId, NotificationLevel};

    fn item(level: NotificationLevel, text: &str) -> Notification {
        Notification {
            id: NotificationId(1),
            level,
            scope: None,
            text: text.into(),
            timeout: None,
            actions: Vec::new(),
        }
    }

    fn line_text(line: &ratatui::text::Line<'_>) -> String {
        line.spans.iter().map(|s| s.content.as_ref()).collect()
    }

    #[test]
    fn a_row_leads_with_its_levels_icon() {
        let mut theme = crate::theme::Theme::default();
        for nerd in [false, true] {
            theme.nerd_fonts = nerd;
            let line = notification_line(&item(NotificationLevel::Success, "pushed"), &theme, 40);
            let text = line_text(&line);
            assert!(
                text.starts_with(NotificationLevel::Success.glyph(nerd)),
                "nerd_fonts={nerd}: {text:?}"
            );
            assert!(text.trim_end().ends_with("pushed"), "{text:?}");
        }
    }

    /// Success must not look like info — that is why the level exists.
    #[test]
    fn success_is_coloured_apart_from_info() {
        let theme = crate::theme::Theme::default();
        let style = |level| notification_line(&item(level, "x"), &theme, 40).spans[0].style;
        assert_ne!(
            style(NotificationLevel::Success),
            style(NotificationLevel::Info)
        );
        assert_eq!(
            style(NotificationLevel::Success),
            theme.diff_add_sign_style,
            "success reads the same element GPUI does"
        );
    }

    /// NC.2: the scope leads the text, bold, so two repositories'
    /// notifications cannot read the same.
    #[test]
    fn the_scope_is_its_own_bold_span_before_the_text() {
        let theme = crate::theme::Theme::default();
        let mut n = item(NotificationLevel::Success, "push main");
        n.scope = Some("lattice".into());
        let line = notification_line(&n, &theme, 60);
        let text = line_text(&line);
        let scope_at = text.find("lattice").unwrap();
        assert!(scope_at < text.find("push main").unwrap(), "{text:?}");
        let scope_span = line
            .spans
            .iter()
            .find(|s| s.content.contains("lattice"))
            .unwrap();
        assert!(
            scope_span
                .style
                .add_modifier
                .contains(ratatui::style::Modifier::BOLD)
        );
    }

    /// The icon costs width; the text is clipped to what is left, so a
    /// long message cannot push past the box.
    #[test]
    fn the_text_is_clipped_to_the_width_left_after_the_icon() {
        let theme = crate::theme::Theme::default();
        let line = notification_line(&item(NotificationLevel::Info, &"a".repeat(80)), &theme, 20);
        assert!(line_text(&line).chars().count() <= 20);
    }
}

#[cfg(test)]
mod transient_palette_tests {
    /// **Neither renderer may hard-code a transient colour.**
    ///
    /// The TUI used fixed ANSI constants (`Cyan` border, `Yellow` keys,
    /// `DarkGray` descriptions, `Green` flags) and GPUI borrowed
    /// `popup_border` / `cursor_background` for five roles — which left
    /// GPUI painting **keys and flags in the same colour** and
    /// descriptions in the border tone, so a row read as
    /// undifferentiated text where the TUI showed three columns.
    ///
    /// The two symptoms had one cause: no role was NAMED, so each peer
    /// invented its own answer and they drifted. Asserted against the
    /// source of both files because the defect is a literal in a paint
    /// call — visible in the text, and not reachable by any test that
    /// can run without a terminal or a GPU window.
    #[test]
    fn neither_renderer_hard_codes_a_transient_colour() {
        // (file, source, the span that holds its transient painting)
        let tui = include_str!("render.rs");
        let gpui_src = include_str!("../../lattice-ui-gpui/src/window.rs");

        // Each transient function's OWN body, not one span covering
        // all of them: `draw_notifications` sits between them in this
        // file and legitimately maps severities to fixed colours, so a
        // span-based check reports it and teaches the reader to ignore
        // the guard.
        //
        // Comments are stripped first. A comment recording what a
        // colour USED to be is exactly the context worth keeping —
        // "it was `Color::Cyan` here" explains the fix to the next
        // reader — and a guard that reads prose as code punishes
        // writing it down, which is the wrong incentive for a rule
        // whose whole purpose is that the reasoning survives.
        fn body(src: &str, name: &str) -> String {
            let start = src
                .find(&format!("fn {name}"))
                .unwrap_or_else(|| panic!("`{name}` not found — renamed?"));
            let end = src[start + 4..]
                .find("\nfn ")
                .map(|o| start + 4 + o)
                .unwrap_or(src.len());
            src[start..end]
                .lines()
                .map(|l| match l.find("//") {
                    Some(i) => &l[..i],
                    None => l,
                })
                .collect::<Vec<_>>()
                .join("\n")
        }
        for name in [
            "transient_group_item_lines",
            "draw_transient_overlay",
            "draw_transient_minibuffer_prompt",
            "draw_transient_minibuffer_candidates",
        ] {
            let span = body(tui, name);
            let span = span.as_str();
            for banned in [
                "Color::Yellow",
                "Color::Green",
                "Color::Cyan",
                "Color::DarkGray",
            ] {
                assert!(
                    !span.contains(banned),
                    "`{name}` still hard-codes `{banned}` — `:colorscheme` \
                     cannot reach a fixed ANSI constant, so the transient \
                     menu stays the one surface a theme does not govern",
                );
            }
        }

        let gpui_span = {
            let a = gpui_src
                .find("fn transient_rows_gpui")
                .expect("GPUI row builder");
            let b = gpui_src[a..]
                .find("fn build_transient_minibuffer_gpui")
                .map(|o| a + o)
                .expect("end of the transient builders");
            &gpui_src[a..b]
        };
        for borrowed in ["theme.popup_border", "theme.cursor_background"] {
            assert!(
                !gpui_span.contains(borrowed),
                "the GPUI transient painter still borrows `{borrowed}`. That \
                 is what made keys and flags the same colour: one field \
                 standing in for several roles cannot distinguish them.",
            );
        }
    }
}

#[cfg(test)]
mod searching_from_a_focused_popup_tests {
    //! The reported sequence, at the pixel level: focus a cursor-anchored
    //! popup, press `/`, and the popup must neither move nor take the caret.
    //!
    //! These assert on a rendered frame rather than on state, because both
    //! symptoms ARE the frame: "the popup jumps up near the top" is its
    //! `Rect`, and "the cursor changes shape" is which surface owns the
    //! terminal's one caret. A state-level test would have passed on both.

    use super::*;
    use crate::app::App;
    use lattice_core::Document;
    use ratatui::Terminal;
    use ratatui::backend::TestBackend;

    /// A document long enough that "anchored at the caret" and "anchored at
    /// the top" are different rows — with the caret on line 0 the bug is
    /// invisible.
    fn app_with_popup_at_line(line: u32) -> App {
        let text = (0..20)
            .map(|n| format!("line {n} of the document\n"))
            .collect::<String>();
        let mut a = App::new(Document::from_text(&text));
        a.set_viewport_height(20);
        a.mutate_editor(move |e| {
            e.cursor.line = line;
            let content = lattice_help::parse_help_lines(
                "hover",
                vec!["fn thing() -> u32".to_string(), "the docs".to_string()],
            );
            let _ = e.open_floating_popup(content, crate::popup::PopupPlacement::CursorAnchored);
            e.focus_help_popup();
            e.publish_render_state();
        });
        a
    }

    fn popup_rect(a: &App, w: u16, h: u16) -> Rect {
        let snap = a.ad().snapshot.clone();
        // The same area the frame gives the buffer region: everything above
        // the one-row minibuffer.
        let buffer_area = Rect {
            x: 0,
            y: 0,
            width: w,
            height: h.saturating_sub(1),
        };
        position_help_popup(a, &snap, buffer_area, 30, 4)
    }

    /// `/` must not move the popup. Before the fix the anchor came from
    /// `ad()`, which a focused search line replaces — cursor `(0, 0)` — so
    /// the popup jumped to the top of the pane.
    #[test]
    fn opening_the_search_line_does_not_move_a_focused_popup() {
        let (w, h) = (80u16, 24u16);
        let mut a = app_with_popup_at_line(10);
        let before = popup_rect(&a, w, h);
        assert!(
            before.y > 4,
            "the fixture must anchor the popup well down the pane, or this \
             test cannot tell 'moved to the top' from 'already there': {before:?}"
        );

        a.mutate_editor(|e| {
            e.open_search_line(lattice_grammar::SearchDirection::Forward);
            e.publish_render_state();
        });
        assert_eq!(
            popup_rect(&a, w, h),
            before,
            "the popup is anchored where it was opened; opening a search line \
             is not the document's caret moving"
        );
    }

    /// …and the caret belongs to the search line, not the popup.
    ///
    /// Asserted through the rendered frame's cursor position: the terminal
    /// has ONE hardware caret, so "the popup kept it and merely changed
    /// shape" and "the search line has it" are the same question.
    #[test]
    fn the_search_line_owns_the_caret_not_the_popup() {
        let (w, h) = (80u16, 24u16);
        let mut a = app_with_popup_at_line(10);
        a.mutate_editor(|e| {
            e.open_search_line(lattice_grammar::SearchDirection::Forward);
            e.publish_render_state();
        });

        let snap = a.ad().snapshot.clone();
        let mut terminal = Terminal::new(TestBackend::new(w, h)).unwrap();
        // Read back off the terminal after the draw: `Frame::cursor_position`
        // is private, and the backend is where the placement actually lands.
        terminal
            .draw(|f| {
                let _ = draw_frame(f, &a, &snap);
            })
            .unwrap();
        let y = terminal
            .get_cursor_position()
            .expect("something places the caret")
            .y;
        assert_eq!(
            y,
            h - 1,
            "the caret sits on the minibuffer row, where `/` is drawn — if it \
             is anywhere else the popup claimed it, and wearing the Bar shape \
             `ModalState::Search` implies it reads as a read-only popup that \
             entered Insert"
        );
    }
}