lattice_ui_tui/

runtime.rs

//! Terminal IO loop. Sets up raw mode + alt screen, draws frames, polls
//! events, restores terminal state on exit.
//!
//! This is the only file in the crate that talks to the terminal directly.
//! Everything else is pure and unit-tested.

use std::io::Stdout;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::mpsc;
use std::thread;
use std::time::{Duration, Instant};

use anyhow::{Context, Result};
use crossterm::cursor::SetCursorStyle;
use crossterm::event::{
    self, DisableBracketedPaste, DisableMouseCapture, EnableBracketedPaste, EnableMouseCapture,
    Event, KeyboardEnhancementFlags, PopKeyboardEnhancementFlags, PushKeyboardEnhancementFlags,
};
use crossterm::execute;
use crossterm::terminal::{
    EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode,
    supports_keyboard_enhancement,
};
use lattice_grammar::ModalState;
use ratatui::Terminal;
use ratatui::backend::CrosstermBackend;

use lattice_core::Document;

use crate::app::{Action, App};
use crate::input::{TranslateContext, translate};
use crate::render::draw_frame;

/// Perf instrumentation (paired with `LATTICE_PERF_INPUT`): counts bytes
/// written to the terminal so the input timer can report **per-frame write
/// volume**. This is the real driver of terminal present time on a slow pty:
/// `terminal.draw()` returns as soon as the diff lands in the pty buffer, but
/// the terminal emulator then spends time parsing + presenting those bytes —
/// time our `input→glyph` timer can't see. vim writes a few bytes per
/// keystroke; if we write kilobytes (a whole-viewport rewrite) the same
/// terminal that renders vim instantly will visibly lag on us. Reset before
/// each `draw()`, read after.
static PERF_FRAME_BYTES: AtomicU64 = AtomicU64::new(0);

/// Wraps the terminal writer and tallies bytes into [`PERF_FRAME_BYTES`].
/// Forwards everything to the inner writer; the relaxed atomic add is
/// negligible. Always wired (so the byte count is available whenever
/// `LATTICE_PERF_INPUT` is set) — the only cost when the env is unset is the
/// add itself, which is in the noise next to the syscall it accompanies.
struct CountingWriter<W> {
    inner: W,
}

impl<W: std::io::Write> std::io::Write for CountingWriter<W> {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        let n = self.inner.write(buf)?;
        PERF_FRAME_BYTES.fetch_add(n as u64, Ordering::Relaxed);
        Ok(n)
    }

    fn flush(&mut self) -> std::io::Result<()> {
        self.inner.flush()
    }
}

/// The concrete terminal backend type, now wrapped in the byte counter.
type TermBackend = CrosstermBackend<CountingWriter<Stdout>>;

/// The chord table a modal state resolves against — the same mapping the host
/// uses. Needed by the AP.0.2 fall-through to ask the trie which layer bound a
/// declined chord.
pub fn run(document: Document, startup_lesson: Option<u32>) -> Result<()> {
    let mut terminal = setup().context("setup terminal")?;
    let mut app = App::new(document);
    // Load persistent config (TOML) before LSP attach work so
    // any overrides that affect LSP behaviour land before the
    // attach driver processes the initial document's
    // `Event::DocumentOpened`. Workspace root is the CWD
    // walked up to the first `.git` / `.lattice/` marker (or
    // the CWD itself if neither is found). Failures are
    // surfaced via the App's echo, never abort startup.
    // Phase 5.8.AA.u: workspace-root discovery + persistent-config
    // loading both live on the host so GPUI gets the same boot
    // behaviour. The TUI runtime is now a thin wrapper.
    let workspace_root = lattice_core::project::root_from_cwd();
    app.load_persistent_config(workspace_root.as_deref());
    app.apply_per_language_toml_overrides();
    // OS.1: only now is `ui.keyboard_enhancement` real -- `setup()` ran before
    // the TOML was read, so asking there would always answer the default.
    let keyboard_enhanced = push_keyboard_enhancement(
        app.options()
            .config
            .get_typed::<lattice_host::ui::theme_options::UiKeyboardEnhancement>()
            .map(|v| *v)
            .unwrap_or(true),
    );
    // built-ins 2026-06-13: load embedded + user snippet packs once
    // at startup (after config so `snippet_dirs` overrides apply).
    // Quiet — logs, no echo.
    app.load_snippets_at_startup();
    // T.5: `--tutor [N]` opens the tutor buffer before the first draw.
    if let Some(n) = startup_lesson {
        app.open_tutor(n);
    }
    // LSP attach is event-driven: `App::new` already
    // published `Event::DocumentOpened` for the initial
    // document (if path-bearing). The attach driver wired in
    // `build_lsp_subsystem` runs on the LSP runtime and
    // submits the open to the supervisor *off* the UI thread.
    // The first frame can draw immediately without waiting on
    // the LSP `initialize` round-trip -- paramount goal #4
    // (asynchronicity).
    let result = main_loop(&mut terminal, app);
    teardown(&mut terminal, keyboard_enhanced).context("teardown terminal")?;
    result
}

// Phase 5.8.AA.u hoisted this out of the TUI runtime onto the host;
// PR.2 moved it again, to `lattice_core::project::root_from_cwd` —
// so both renderers and every other consumer share one rule about
// where a project begins.

// Phase 5.5.LSP.1: the shared LSP runtime + spawn helper now
// live in `lattice_runtime::runtime` so host-side dispatchers
// can fire LSP requests without taking a back-edge through this
// (renderer-specific) crate. Re-exported here so the existing
// `crate::runtime::*` call sites (34 inside `App`) keep
// compiling unchanged. Both names point at the single
// `lattice_runtime::LSP_RUNTIME` OnceLock -- no behaviour change.
// Phase 5.8.AD.2: `lsp_runtime` re-export retired -- last
// caller (`do_lsp_restart`) migrated host-side. `spawn_on_lsp_runtime`
// is still publicly re-exported for the few App-resident async
// helpers that haven't migrated yet.
pub use lattice_runtime::runtime::spawn_on_lsp_runtime;

fn setup() -> Result<Terminal<TermBackend>> {
    enable_raw_mode().context("enable raw mode")?;
    let mut stdout = std::io::stdout();
    execute!(stdout, EnterAlternateScreen).context("enter alt screen")?;
    // Bracketed paste tells the terminal to wrap clipboard pastes in
    // ESC[200~ ... ESC[201~ markers. Crossterm decodes those as
    // `Event::Paste(String)`, which we hand to the App as a single
    // bracketed-paste burst (one undo unit). Without this, terminals
    // that bind Ctrl+V to clipboard paste (Konsole, Windows Terminal,
    // tmux configs) replay the clipboard contents as a stream of
    // raw key events -- which Normal mode then interprets as commands
    // and the user gets unexpected behaviour instead of a paste.
    execute!(stdout, EnableBracketedPaste).context("enable bracketed paste")?;
    let backend = CrosstermBackend::new(CountingWriter { inner: stdout });
    Terminal::new(backend).context("create terminal")
}

/// OS.1: should the keyboard-enhancement protocol be pushed?
///
/// Both conditions, extracted so the decision is testable without a tty —
/// which is the only part of this slice a test can reach.
fn should_push_enhancement(option: bool, supported: bool) -> bool {
    option && supported
}

/// OS.1: ask the terminal to disambiguate `<S-CR>` / `<C-CR>` / `<M-S-CR>`
/// from a bare `<CR>`.
///
/// Without this a terminal sends the same `\r` for all four, so those chords
/// are unreachable however they are bound. `lattice-protocol` has always
/// spelled them and the GPUI peer has always delivered them; this closes the
/// renderer asymmetry rather than adding a capability.
///
/// `DISAMBIGUATE_ESCAPE_CODES` only. `REPORT_ALL_KEYS_AS_ESCAPE_CODES` would
/// route ordinary text input through the escape path, which is not wanted.
///
/// **Called after the persistent config loads, not from [`setup`].** `setup`
/// runs before `load_persistent_config`, so an option read there would always
/// see the compiled-in default and `:set ui.keyboard_enhancement=off` in a
/// user's TOML would be silently ignored. Nothing reads a key between the two
/// points, so pushing here costs nothing.
///
/// Returns whether the push actually happened, so teardown pops exactly what
/// was pushed. A terminal that advertises support and then refuses must not
/// fail startup: log and carry on unenhanced.
fn push_keyboard_enhancement(option: bool) -> bool {
    if !should_push_enhancement(option, supports_keyboard_enhancement().unwrap_or(false)) {
        return false;
    }
    let mut stdout = std::io::stdout();
    match execute!(
        stdout,
        PushKeyboardEnhancementFlags(KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES)
    ) {
        Ok(()) => true,
        Err(e) => {
            tracing::debug!(error = %e, "terminal refused the keyboard-enhancement push");
            false
        }
    }
}

/// MO.1: turn terminal mouse reporting on or off, following `ui.mouse`.
///
/// Kept out of [`setup`] because it is the one terminal capability the
/// editor asks for that **takes something away**: while capture is on,
/// the terminal emulator stops seeing the mouse, so click-drag text
/// selection and middle-click paste no longer work (some terminals
/// offer Shift-drag as an escape hatch; not all do). That is why the
/// option defaults off and why this is toggleable at runtime rather
/// than decided once at startup — `:set ui.mouse` takes effect on the
/// next loop iteration, and the user can turn it back off the moment
/// they want to copy something.
///
/// Failures are logged and swallowed: a terminal that rejects the
/// escape sequence should leave the editor running without mouse
/// support, not refuse to start.
fn set_mouse_capture(on: bool) {
    let mut stdout = std::io::stdout();
    let result = if on {
        execute!(stdout, EnableMouseCapture)
    } else {
        execute!(stdout, DisableMouseCapture)
    };
    if let Err(e) = result {
        tracing::debug!(error = %e, enable = on, "terminal rejected mouse-capture toggle");
    }
}

fn teardown(terminal: &mut Terminal<TermBackend>, keyboard_enhanced: bool) -> Result<()> {
    // Unconditional, and harmless when capture was never enabled: the
    // sequence is a no-op for a terminal that is not reporting. Leaving
    // a terminal in reporting mode after exit is the failure worth
    // avoiding — the user's shell would receive mouse escape codes as
    // garbage input.
    execute!(terminal.backend_mut(), DisableMouseCapture)
        .context("disable mouse capture")
        .unwrap_or_else(|e| tracing::debug!(error = %e, "disable mouse capture"));
    // Restore the user's default cursor shape before tearing down the
    // alt screen -- otherwise the shell prompt inherits whatever the
    // editor was rendering.
    execute!(terminal.backend_mut(), SetCursorStyle::DefaultUserShape)
        .context("restore cursor style")?;
    // OS.1: pop exactly what was pushed, and before raw mode goes away. A
    // terminal left in enhancement mode hands the user's shell disambiguated
    // key encodings, which is a worse failure than the one the push fixes --
    // so this is best-effort-logged rather than `?`, like the mouse restore
    // above: one refused sequence must not skip the restores below it.
    if keyboard_enhanced {
        execute!(terminal.backend_mut(), PopKeyboardEnhancementFlags)
            .unwrap_or_else(|e| tracing::debug!(error = %e, "pop keyboard enhancement"));
    }
    execute!(terminal.backend_mut(), DisableBracketedPaste).context("disable bracketed paste")?;
    disable_raw_mode().context("disable raw mode")?;
    execute!(terminal.backend_mut(), LeaveAlternateScreen).context("leave alt screen")?;
    terminal.show_cursor().context("show cursor")?;
    Ok(())
}

/// Map the App's modal state to a terminal cursor shape via the
/// renderer-neutral `host::cursor_shape::CursorShape`. The vim
/// convention (Block for command-language modes, Bar for Insert /
/// Command-line, Underscore for Replace) lives once on the host
/// (5.8.N); this peer just maps to crossterm's primitive.
///
/// Terminal-mode T2.b (2026-05-25): when the active buffer is a
/// Terminal AND `terminal-insert-mode` is active, the shape
/// flips to `SteadyBar` even though `ModalState` stays `Normal`
/// (TerminalInsert is a minor mode, not a separate modal
/// variant). The Normal-in-terminal state keeps `SteadyBlock`.
fn cursor_style_for(modal: ModalState, terminal_insert_active: bool) -> SetCursorStyle {
    use lattice_host::cursor_shape::CursorShape;
    if terminal_insert_active {
        return SetCursorStyle::SteadyBar;
    }
    match CursorShape::for_mode(modal) {
        CursorShape::Block => SetCursorStyle::SteadyBlock,
        CursorShape::Bar => SetCursorStyle::SteadyBar,
        CursorShape::Underline => SetCursorStyle::SteadyUnderScore,
    }
}

/// I.3 (event-driven wake): a reason the main loop woke. The loop blocks on a
/// single channel of these instead of polling the terminal on a 100ms timer.
/// `Input` carries a decoded terminal event from the dedicated reader thread;
/// `Repaint` is forwarded from the actor's `paint_request` `Notify` (async
/// syntax / LSP / worker republishes) so a background republish reaches the
/// screen promptly without the loop spinning. See
/// `docs/dev/operations/slice-plans/input-latency.md` I.3.
enum Wake {
    Input(Event),
    Repaint,
}

/// Apply one decoded terminal event to the app. Mirrors the per-event arm the
/// pre-I.3 inline drain ran: keys translate through the published `translator`
/// substate (no `&Editor` borrow); a bracketed paste is one edit; a resize
/// defers to the next iteration's viewport setup. Sets `last_input_at` only for
/// events that produced fresh input, so the `LATTICE_PERF_INPUT` timer
/// attributes the next draw to a keystroke and not to an async repaint.
fn apply_event(app: &mut App, ev: Event, perf_input: bool, last_input_at: &mut Option<Instant>) {
    match ev {
        Event::Key(k) => {
            // Esc dismisses an open floating popup (hover / signature /
            // `:describe-*`) even when the DOCUMENT keeps focus (State A) —
            // mirrors the GPUI peer's `on_key_down` gate (window.rs). Without
            // this, Esc only closed the popup once focus had moved into it
            // (State B) or on cursor motion (HoverMode auto-dismiss); plain
            // `<Esc>` over the document did nothing. Gated to State A
            // (`buffer_kind != Help`) so a FOCUSED popup (State B) keeps the
            // normal Esc path, where in-popup sub-modes (search, …) can
            // cancel first before the popup closes.
            if matches!(k.code, crossterm::event::KeyCode::Esc)
                && app.popup().is_open()
                && !app.ad().popup_focused
            {
                app.dismiss_popup();
                if perf_input {
                    *last_input_at = Some(Instant::now());
                }
                return;
            }
            // Slice 3c.final.B (group 5): translator inputs read through
            // `rs.translator` instead of `&app.editor.{builtins,keymap,
            // partial_chord}`. The Arc-bound substate keeps the borrows valid
            // for the translate call without tying them to `Editor`'s lifetime.
            let ad = app.ad();
            let translator = app.render_state.load().translator.clone();
            let ctx = TranslateContext {
                modal: ad.modal,
                builtins: &translator.builtins,
                pending_count: ad.pending_count,
                op_count: ad.op_count,
                recording_macro: ad.macro_recording,
                active_buffer: ad.buffer_kind,
                completion_open: ad.completion_open,
                chord_capture: app.chord_capture_active(),
                picker_open: ad.picker_open,
                insert_completion_open: app.completion_popup_active(),
                snippet_active: ad.snippet_active,
                terminal_insert_active: ad.terminal_insert_active,
                terminal_esc_exits: ad.terminal_esc_exits,
                terminal_app_cursor_keys: ad.terminal_app_cursor_keys,
                terminal_insert_exit_pending: ad.terminal_insert_exit_pending,
                terminal_visual_active: ad.terminal_visual_active,
                keymap: &translator.keymap,
                partial_chord: &translator.partial_chord,
                active_minor_modes: &translator.active_minor_modes,
            };
            // AP.0.2: the inputs the fall-through has to reuse, captured
            // BEFORE `apply` mutates the partial-chord state. Re-resolving with
            // an empty prefix resolves the trailing key alone, which is how a
            // declined `<leader>oJ` ran vim's `J` and joined two lines.
            let prefix_before: Vec<lattice_protocol::KeyChord> = translator.partial_chord.to_vec();
            let layers_before: Vec<lattice_mode::ModeId> = translator.active_minor_modes.to_vec();
            let action = translate(ctx, k);
            if app.apply(action) {
                // AP.0.2 fall-through (TUI live path): the resolved binding
                // was a plugin grammar action that DECLINED — it did nothing,
                // so re-resolve with the DECLINING LAYER REMOVED, peeling one
                // layer per decline until something handles the key or only the
                // always-on Builtin / User layers are left.
                //
                // Mirrors the host `dispatch_chord` peel exactly (GPUI rides
                // that path). Dropping every mode layer at once — which is what
                // this did — means a second declining layer never sees the
                // chord, so org-table-mode's `<Tab>` skipped org-mode's fold
                // cycle and hit the builtin. The TUI's translate→apply path
                // lost the chord by dispatch time, so the re-translate happens
                // here where `k` is still in hand.
                // `k` is still the crossterm event; the trie speaks `KeyChord`.
                let Some(k_chord) = crate::chord::from_event(&k) else {
                    return;
                };
                // The walk is `lattice_host::decline::DeclinePeel`'s, not this
                // loop's. It was this loop's, and the host dispatcher had a
                // second copy, and the GPUI peer had none — which is how every
                // key auto-pair binds came to be dead in that renderer while
                // this one was fine.
                let mut peel = lattice_host::decline::DeclinePeel::new(
                    app.ad().modal,
                    prefix_before.clone(),
                    k_chord,
                    layers_before.clone(),
                );
                loop {
                    let ad = app.ad();
                    let translator = app.render_state.load().translator.clone();
                    // `None` ⇒ the winner came from Builtin / User, which
                    // cannot decline: nothing left to peel.
                    let Some(layers) = peel
                        .peel(&translator.keymap)
                        .map(<[lattice_mode::ModeId]>::to_vec)
                    else {
                        break;
                    };
                    let ctx = TranslateContext {
                        modal: ad.modal,
                        builtins: &translator.builtins,
                        pending_count: ad.pending_count,
                        op_count: ad.op_count,
                        recording_macro: ad.macro_recording,
                        active_buffer: ad.buffer_kind,
                        completion_open: ad.completion_open,
                        chord_capture: app.chord_capture_active(),
                        picker_open: ad.picker_open,
                        insert_completion_open: app.completion_popup_active(),
                        snippet_active: ad.snippet_active,
                        terminal_insert_active: ad.terminal_insert_active,
                        terminal_esc_exits: ad.terminal_esc_exits,
                        terminal_app_cursor_keys: ad.terminal_app_cursor_keys,
                        terminal_insert_exit_pending: ad.terminal_insert_exit_pending,
                        terminal_visual_active: ad.terminal_visual_active,
                        keymap: &translator.keymap,
                        partial_chord: &prefix_before,
                        active_minor_modes: &layers,
                    };
                    let fallthrough = translate(ctx, k);
                    let declined_again = app.apply(fallthrough);
                    if !declined_again || peel.exhausted() {
                        break;
                    }
                }
            }
            if perf_input {
                *last_input_at = Some(Instant::now());
            }
        }
        Event::Paste(text) => {
            // Real bracketed-paste burst from the terminal's clipboard
            // shortcut. Hand the payload to the app as a single edit; Ctrl+V
            // keystrokes (the binding for blockwise visual) still arrive as
            // `Event::Key` because they're not the terminal's paste path.
            app.apply(Action::PasteText(text));
            if perf_input {
                *last_input_at = Some(Instant::now());
            }
        }
        Event::Resize(_, _) => {
            // next iteration's top-of-loop setup reads the new size
        }
        // ML.4: a left-click on a modeline element dispatches the
        // element's declared command. Mouse events only arrive at all
        // when `ui.mouse` is on (MO.1), so no gate is needed here.
        //
        // The host is a router and nothing more: the handler body lives
        // in the mode or plugin that registered the element, reached
        // through the same `CommandInvocation` path a keystroke takes
        // (modeline.md §6, §9). No per-element handler, and no new
        // `Action` variant.
        Event::Mouse(m) => {
            use crossterm::event::{MouseButton, MouseEventKind};
            // The modeline claims a left-press before the body sees it:
            // its zones sit on the pane's status row, which is outside
            // every `PaneHitZone` (those cover `content_rect` only), so
            // the two maps cannot both answer — but asking the modeline
            // first keeps that a property of the code and not only of
            // the geometry.
            let modeline_hit = if matches!(m.kind, MouseEventKind::Down(MouseButton::Left)) {
                // Bound out of the `if` so the `RefCell` borrow ends
                // before `app.apply` takes `&mut app`.
                app.modeline_hits.borrow().hit(m.column, m.row)
            } else {
                None
            };
            if let Some(command) = modeline_hit {
                app.apply(Action::Invoke(lattice_grammar::CommandInvocation::of(
                    command,
                )));
                if perf_input {
                    *last_input_at = Some(Instant::now());
                }
                return;
            }
            // MO.2: the editor body. `resolve` answers `None` for a cell
            // no pane painted (the `:` line, a status row, the gap
            // between splits), which is how those stay inert.
            let resolved = app.pane_hits.borrow().resolve(m.column, m.row);
            let Some(hit) = resolved else {
                return;
            };
            let action = match m.kind {
                // The wheel scrolls the pane under the POINTER and does
                // not focus it — vim's `mousescroll`, Zed and Helix all
                // agree, and it is what makes a wheel over a reference
                // split usable mid-edit.
                MouseEventKind::ScrollDown => Some(Action::MouseScroll {
                    pane: hit.zone.pane_id,
                    down: true,
                }),
                MouseEventKind::ScrollUp => Some(Action::MouseScroll {
                    pane: hit.zone.pane_id,
                    down: false,
                }),
                // A press positions the caret; dragging with the button
                // held extends from where the press landed. `Drag` is
                // reported only while a button is down, so the two share
                // one resolver and differ by `extend` alone.
                MouseEventKind::Down(MouseButton::Left) => mouse_goto(app, &hit, false),
                MouseEventKind::Drag(MouseButton::Left) => mouse_goto(app, &hit, true),
                _ => None,
            };
            if let Some(action) = action {
                app.apply(action);
                if perf_input {
                    *last_input_at = Some(Instant::now());
                }
            }
        }
        _ => {}
    }
}

/// MO.2: turn a resolved cell into a buffer position.
///
/// The inverse of the compose loop, and derived from it rather than
/// re-implemented: the row's origin was **recorded while painting**
/// (`PaneHitMap::set_rows`), and the column goes back through
/// `lattice_cells::display_col_to_source_byte`, the binary-search
/// inverse of the very map the caret is drawn with. That is what makes
/// a click land exactly where the caret would be — including under soft
/// wrap, inlay hints and conceal, none of which this function knows
/// anything about individually.
///
/// `None` when the cell is on the gutter or on a row mirroring no source
/// line, which is how those stay inert rather than resolving to
/// column 0 of something.
fn mouse_goto(app: &App, hit: &lattice_host::mouse::BodyHit, extend: bool) -> Option<Action> {
    let body_width = hit.zone.width.saturating_sub(hit.zone.text_left).max(1) as u32;
    let logical_col = hit.logical_col(body_width)?;
    let origin = hit.origin?;

    let handle = app.buffers().registry.document_handle(hit.zone.buffer_id)?;
    let snapshot = handle.snapshot();
    let line_text = snapshot.buffer.line(origin.source_line).unwrap_or_default();

    // The display row carries the tables the forward map used: inlay
    // splices and conceal ranges for THIS line. Absent (matrix not built
    // yet for a just-opened buffer) means no splices, which is the
    // identity — a click still lands, just without corrections nothing
    // has applied yet either.
    let matrix = app
        .render_state
        .load()
        .cells
        .load_full()
        .display_matrix_for_pane(hit.zone.pane_id)
        .map(|cell| cell.load_full());
    let row = matrix
        .as_ref()
        .and_then(|m| m.row_at_source_line(origin.source_line));

    // Char columns, not bytes — the space the cell substrate's column
    // tables live in (see the byte-vs-char note on
    // `CellRow::byte_to_combined_col`). The conversion back to a byte
    // offset is this function's job, and it is why `max_source_byte` is
    // a char count.
    let char_len = line_text.chars().count() as u32;
    let char_col = match row {
        Some(r) => lattice_cells::display_col_to_source_byte(
            logical_col,
            char_len,
            &r.col_map,
            &r.conceals,
        ),
        None => logical_col.min(char_len),
    };
    let byte = line_text
        .char_indices()
        .nth(char_col as usize)
        .map(|(b, _)| b as u32)
        .unwrap_or(line_text.len() as u32);

    Some(Action::MouseGoto {
        pane: hit.zone.pane_id,
        line: origin.source_line,
        byte,
        extend,
    })
}

/// Drain a batch of wakes: the `first` one that unblocked the loop plus every
/// other wake already buffered (zero-wait `try_recv`). Input events apply and
/// coalesce — a typing burst of N queued keys becomes N applies + ONE draw (the
/// keystroke UX contract: the displayed text never trails the keystrokes).
/// Stops the instant a quit lands so later buffered keys aren't applied against
/// a tearing-down app. `Repaint` wakes apply nothing — they exist purely to
/// trigger the single redraw at the loop top so an async republish (syntax
/// recolour, LSP decoration) reaches the screen.
///
/// Returns `true` when the batch contained at least one `Repaint` and NO input
/// events. The caller uses this to call `drain_async_pending` so idle LSP
/// arrivals (hover, signature-help) reach the screen on the repaint itself
/// rather than waiting for the next keystroke (X1b).
fn drain_wakes(
    app: &mut App,
    rx: &mpsc::Receiver<Wake>,
    first: Wake,
    perf_input: bool,
    last_input_at: &mut Option<Instant>,
) -> bool {
    let mut had_input = false;
    let mut next = Some(first);
    while let Some(wake) = next.take() {
        if let Wake::Input(ev) = wake {
            had_input = true;
            apply_event(app, ev, perf_input, last_input_at);
        }
        if app.render_state.load().lifecycle.should_quit {
            return false;
        }
        next = rx.try_recv().ok();
    }
    !had_input
}

fn main_loop(terminal: &mut Terminal<TermBackend>, mut app: App) -> Result<()> {
    // Terminal-mode T2.b (2026-05-25): cursor-style cache now keys
    // off `(modal, terminal_insert_active)` since TerminalInsert is
    // a minor mode that doesn't flip `ModalState`. Without the
    // minor-mode bit in the cache key, entering / leaving
    // Terminal-Insert wouldn't re-push the cursor style and the
    // user would see a stale block where a bar belongs.
    let mut last_cursor_inputs: Option<(ModalState, bool)> = None;
    // Diff cache for the per-frame terminal-width dispatch (see loop body):
    // the width only changes on a resize, so we dispatch only on change
    // rather than every frame.
    let mut last_terminal_width: Option<u16> = None;
    // Diff cache for the per-frame viewport-height push. `set_viewport_height`
    // was dispatched UNCONDITIONALLY every iteration → a publish (+ both worker
    // wakes) per loop tick even when nothing changed — the idle/per-keystroke
    // publish storm. Push only when the resolved height actually changes.
    let mut last_viewport_height: Option<u32> = None;
    // PU.1b-3: diff cache for the floating-popup inner-geometry hand-off
    // (mirror of `last_viewport_height` for the synthetic popup pane).
    // `None` when no floating popup is open; `Some((rows, cols))` carries
    // the popup's inner rect. Push only on change so a steady-state popup
    // costs zero actor RPCs per frame.
    let mut last_popup_dims: Option<(u32, u32)> = None;
    let mut last_band_dims: Option<(u32, u32)> = None;
    // PU.5c: diff-then-send cache for the completion-docs popup geometry.
    let mut last_completion_docs_dims: Option<(u32, u32)> = None;
    // Opt-in keystroke→glyph timer (set env `LATTICE_PERF_INPUT=1`). Measures
    // OUR input-to-draw latency only — from the instant an input event was
    // applied to the instant `terminal.draw()` returns (i.e. we've written the
    // frame's diff to stdout). It does NOT include the terminal emulator /
    // pty / compositor present time, which on WSL2 is outside our process.
    // So: a tiny number here + felt lag ⇒ the lag is the WSL2 terminal, not us;
    // a large number here ⇒ the lag is our draw. Writes one clean line per
    // rendered keystroke straight to stderr (bypasses tracing, so it does not
    // add to the debug-log flood). Off by default — zero cost when unset.
    // Emit the perf line ONLY when stderr is REDIRECTED (not the
    // alternate-screen terminal). In the TUI, stderr is the same tty as the
    // rendered display, so a raw `eprintln!` corrupts it: ratatui's diff
    // can't repair an out-of-band write, and each line's newline scrolls the
    // alt-screen — leaving fragments of the previous frame (e.g. preview
    // line-tails) on screen until a force redraw. Require `2>file`.
    use std::io::IsTerminal;
    let perf_env = std::env::var_os("LATTICE_PERF_INPUT").is_some();
    let stderr_redirected = !std::io::stderr().is_terminal();
    if perf_env && !stderr_redirected {
        tracing::info!(
            "LATTICE_PERF_INPUT is set but stderr is the terminal — perf lines are \
             suppressed to avoid corrupting the TUI display. Re-run with `2>perf.log` \
             (or any redirect) to capture them."
        );
    }
    let perf_input = perf_env && stderr_redirected;
    let mut last_input_at: Option<Instant> = None;
    // Tracks the active buffer + its line count across frames so a buffer
    // switch that SHRINKS the content can force a full repaint (see the
    // clear in the draw loop).
    let mut last_active_buffer: Option<(crate::buffers::BufferId, usize)> = None;

    // I.3 (event-driven wake): replace the 100ms terminal poll with a wake on
    // (input-ready OR actor-publish). A dedicated reader thread owns terminal
    // events and forwards each as `Wake::Input`; a tiny task on the shared LSP
    // runtime forwards the actor's `paint_request` `Notify` (async syntax / LSP
    // / worker republishes) as `Wake::Repaint`. The loop blocks on a single
    // channel of `Wake`s, so it draws exactly when something changed and stays
    // fully idle (zero draws, zero CPU) otherwise — the up-to-100ms async-
    // repaint lag is gone. The reader polls a stop flag on a 100ms tick (NOT a
    // redraw timer — it never wakes the loop on its own) purely so it tears
    // down cleanly on quit. See input-latency.md I.3.
    let (wake_tx, wake_rx) = mpsc::channel::<Wake>();
    let reader_stop = std::sync::Arc::new(AtomicBool::new(false));
    let reader_handle = {
        let tx = wake_tx.clone();
        let stop = reader_stop.clone();
        thread::Builder::new()
            .name("lattice-tui-input".into())
            .spawn(move || {
                while !stop.load(Ordering::Relaxed) {
                    // Block up to 100ms for an event; on timeout, loop back to
                    // re-check the stop flag. `poll` returns the instant an
                    // event is ready, so input latency is NOT capped at 100ms.
                    match event::poll(Duration::from_millis(100)) {
                        Ok(true) => match event::read() {
                            Ok(ev) => {
                                if tx.send(Wake::Input(ev)).is_err() {
                                    break; // main loop dropped the receiver
                                }
                            }
                            Err(_) => break,
                        },
                        Ok(false) => {}
                        Err(_) => break,
                    }
                }
            })
            .expect("spawn input reader thread")
    };
    // Forward async `paint_request` notifications onto the same wake channel.
    // The actor's workers (syntax highlights, cells, virtual-rows) call
    // `paint_request.notify_one()` after publishing; `Notify` is permit-style,
    // so a notify that arrives before this re-awaits is not lost. The task
    // exits when the main loop drops the receiver (`send` errors).
    {
        let tx = wake_tx.clone();
        // App holds the actor handle in production (`cfg(not(test))`) and the
        // Editor directly in test builds (3c.final.E.swap); both expose the
        // same shared `paint_request` Notify.
        #[cfg(not(test))]
        let paint_request = app.editor_actor.paint_request();
        #[cfg(test)]
        let paint_request = app.editor.paint_request.clone();
        spawn_on_lsp_runtime(async move {
            loop {
                paint_request.notified().await;
                if tx.send(Wake::Repaint).is_err() {
                    break;
                }
            }
        });
    }
    // The main loop owns only the receiver; the two producer clones above keep
    // the channel alive until both the reader thread and the bridge task exit.
    drop(wake_tx);

    // Slice 3c.final.B (group 6): lifecycle read via published
    // substate. `should_quit` flips from inside dispatch (`:q`,
    // `:wq`, `:qa!`) which republishes at its tail, so the next
    // iteration's load sees the new value.
    // Slice 3c.final.E.4: read through App-cached `render_state`.
    // MO.1: mirrors `ui.mouse` into the terminal's reporting state.
    // Checked once per iteration (an O(1) typed-option read, not work
    // proportional to content) and acted on only when it *changes*, so
    // `:set ui.mouse` takes effect without a restart while the steady
    // state costs one lookup and no escape sequences.
    let mut mouse_capture = false;
    while !app.render_state.load().lifecycle.should_quit {
        let want_mouse = app
            .render_state
            .load()
            .options
            .config
            .get_typed::<lattice_config::MouseEnabled>()
            .map(|a| *a)
            .unwrap_or(false);
        if want_mouse != mouse_capture {
            set_mouse_capture(want_mouse);
            mouse_capture = want_mouse;
        }
        // Phase 5.8.AF.5 / Slice X1: `run_tick_pending` no longer
        // runs per-frame here. It moved to `App::apply`'s tail
        // (`crates/lattice-ui-tui/src/app/dispatch.rs`) so the
        // drain happens on the keystroke that caused the work,
        // not in the renderer's per-frame body. Per paramount
        // goal #1, the UI thread does no I/O / event drain; the
        // ~30-channel aggregator we used to call here is exactly
        // the kind of work the spec forbids on this thread.
        //
        // Idle LSP arrivals (a response with no keystroke in flight)
        // drain off-keystroke via the editor actor's `async_landed`
        // arm, NOT here: every async LSP result fires `async_landed`
        // (direct-write caches, event-bus forwarders, and — since slice
        // AW.1 — the channel-delivered action results: gr/gd/K/code-
        // actions/rename/format/…). The actor runs `run_tick_pending` +
        // publish + `paint_request` on that wake, which lands here as a
        // `Wake::Repaint`. See `docs/dev/architecture/lsp-architecture.md`
        // §12 ("Async-result render-wake").
        // Update viewport height. The buffer-area band is the
        // terminal minus the mode line + cmdline/echo row (and the
        // candidate-list row band, when a picker / completion popup
        // is up). Within that band, the active *pane* gets only its
        // share -- horizontal/vertical splits divide the area, and
        // multi-pane layouts reserve the bottom row of each pane
        // for its status line. The viewport must reflect the active
        // pane's content height, not the full buffer band, so
        // motions / scroll / cursor visibility agree with what the
        // renderer actually paints.
        let size = terminal.size().context("query terminal size")?;
        // `chrome_rows` is the single source of truth for tabline +
        // picker/completion candidate-band rows, shared with
        // `draw_frame`'s paint layout (see its doc comment for the
        // regression this closes: this loop used to hand-duplicate the
        // candidate-band formula and omit the tabline row entirely, so
        // the viewport logic believed it had one more row than
        // `draw_frame` actually painted once the tabline showed).
        let chrome = crate::render::chrome_rows(&app);
        // Option A: global modeline removed; each pane has its own
        // 1-row status footer. Subtract cmdline (1), the tabline (0/1),
        // and any picker/completion candidate band.
        let buffer_height = size
            .height
            .saturating_sub(1)
            .saturating_sub(chrome.tabline)
            .saturating_sub(chrome.extra()) as u32;
        // Diff-then-push: only dispatch when the resolved viewport height
        // changed. Unconditional dispatch here was publishing (+ waking both
        // cells/virtual-rows workers) every loop iteration.
        let vh = app.active_pane_content_height(buffer_height);
        if last_viewport_height != Some(vh) {
            app.set_viewport_height(vh);
            last_viewport_height = Some(vh);
        }
        // 2026-05-27: fire `set_pane_viewport(idx, rows, cols)` per
        // leaf so the host writes the per-pane geometry onto
        // `PaneState` AND, for terminal panes, resizes alacritty +
        // PTY to match the allocated area. Without this, terminal
        // grids stayed at their spawn-time 80×24 default and never
        // wrapped to the actual TUI pane width — the GPUI peer
        // had this loop in its render path but the TUI never did.
        //
        // Diff-then-send: only send when the leaf's published
        // viewport differs from what compute_rects computed this
        // frame. Steady-state (no resize) fires zero commands.
        let panes_arc = app.panes();
        let area_for_panes = crate::pane::PaneRect {
            x: 0,
            y: 0,
            width: size.width,
            height: buffer_height as u16,
        };
        let rects = panes_arc.tree.compute_rects(area_for_panes);
        let current_leaves: Vec<_> = panes_arc.tree.leaves().to_vec();
        for (idx, prect) in &rects {
            // Every pane reserves a bottom row for its status line
            // (Option A: global modeline removed). Mirror of
            // draw_panes which unconditionally splits rect.height >= 2.
            let content_h = if prect.height >= 2 {
                prect.height - 1
            } else {
                prect.height
            };
            let rows = u32::from(content_h).max(1);
            let cols = u32::from(prect.width).max(1);
            let needs = current_leaves
                .get(*idx)
                .map(|l| l.viewport_height != rows || l.viewport_width != cols)
                .unwrap_or(true);
            if needs {
                app.set_pane_viewport(*idx, rows, cols);
            }
        }
        // PU.1b-3: floating-popup inner-geometry hand-off. Mirror of the
        // per-pane loop above: the renderer is the sizing authority, so it
        // pushes the popup's resolved inner `(rows, cols)` to the host for
        // `build_cells_panes` to size the synthetic popup-pane matrix.
        // `popup_feedback_inner_dims` recomputes the SAME geometry
        // `draw_help_overlay` paints into (`popup_outer_size` over the
        // buffer area minus tabline/cmdline/candidate rows), so the matrix
        // and the painted box agree on width. Diff-then-send: a steady-state
        // popup fires zero RPCs; closing the popup pushes `None` once.
        // WK.12: the band's geometry hand-off, beside the popup's.
        let band_dims = crate::render::band_feedback_inner_dims(&app, size.width, buffer_height);
        if last_band_dims != band_dims {
            if let Some((rows, cols)) = band_dims {
                app.set_band_viewport(rows, cols);
            }
            last_band_dims = band_dims;
        }
        let popup_dims = crate::render::popup_feedback_inner_dims(&app, size.width, buffer_height);
        if last_popup_dims != popup_dims {
            if let Some((rows, cols)) = popup_dims {
                app.set_popup_viewport(rows, cols);
            }
            last_popup_dims = popup_dims;
        }
        // Slice 3c.final.C: terminal_width via Action. Diff-then-send
        // (mirrors the pane-viewport loop above): the width only changes
        // on a terminal resize, so dispatching every frame meant a blocking
        // actor RPC + a full `publish_render_state` on every frame (hence on
        // every keystroke's draw) for a no-op field write. Cache the
        // last-sent width UI-side; dispatch only on change.
        if last_terminal_width != Some(size.width) {
            app.apply(lattice_host::action::Action::SetTerminalWidth(size.width));
            last_terminal_width = Some(size.width);
        }
        // `<C-l>` (RedrawScreen) sets `pending_redraw`; honour it
        // by clearing the terminal buffer so the next draw repaints
        // every cell instead of letting ratatui's diff engine
        // assume the previous frame's contents are intact.
        // Slice 3c.final.B (group 6) + 3c.final.C: pending_redraw
        // read via the published substate; acknowledge-write goes
        // through `Action::AcknowledgeRedraw` so the renderer no
        // longer mutates editor state directly. Dispatch tail
        // republishes RS so the next iteration's load observes
        // the cleared flag.
        // Slice 3c.final.E.4: read through App-cached `render_state`.
        if app.render_state.load().lifecycle.pending_redraw {
            terminal.clear().context("clear terminal for redraw")?;
            app.apply(lattice_host::action::Action::AcknowledgeRedraw);
        }
        // Force a full repaint when a buffer switch SHRINKS the content. A
        // switch to a shorter buffer (picker live-preview flipping to a
        // smaller file, the binary "<no preview>" placeholder, or the
        // no-match restore to the empty origin) leaves rows the previous
        // buffer painted that the new (shorter) content can't cover; ratatui
        // leaves those stale in the live async run — the preview "bleeding"
        // (line-tail fragments surviving until a manual `<C-l>`). Clearing
        // makes the next draw repaint every cell, like RedrawScreen.
        //
        // Scoped to SHRINK only: switching among full-screen buffers (the
        // common preview-typing case) grows/keeps the line count, so it
        // never clears → no flicker. Within-row trailing cells already clear
        // for rows present in both frames; only the vacated rows bleed.
        let active_buffer = app.active_buffer_id();
        let line_count = app.ad().snapshot.buffer.content_line_count() as usize;
        if last_active_buffer.is_some_and(|(prev_id, prev_lines)| {
            prev_id != active_buffer && line_count < prev_lines
        }) {
            terminal.clear().context("clear terminal on shrink")?;
        }
        last_active_buffer = Some((active_buffer, line_count));
        // Phase 5.8.AF.5 / Slice X2.5: removed
        // `app.refresh_highlights()` from the per-frame body.
        // display-line B4.2: active-pane syntax colour now flows
        // through the cells / `DisplayMatrix` substrate (rebuilt off
        // the UI thread by the cells worker), and overlay backgrounds
        // through the `lattice_host::overlay_worker` (woken via
        // `Editor::overlay_wake`). Both keep the per-frame body free
        // of any tree-sitter walk. Pre-X2 cost: 200–600µs per frame
        // on scroll cache miss (tree-sitter walk on UI thread);
        // now zero UI-thread parse cost. Goal #1 violation B1 closed
        // for the TUI peer.
        // B4: the per-frame UI-thread `refresh_pane_highlights`
        // recompute was disabled then deleted (it only fed the dead
        // inactive-pane `pane_highlights` cache; inactive panes read
        // their retained per-pane `DisplayMatrix`).

        // Push the cursor shape only when the inputs change --
        // terminals accept these every frame, but emitting on every
        // iteration adds a few bytes of escape sequence to the
        // stream that isn't free. Cache key includes both `modal`
        // and `terminal_insert_active` so the bar / block flip on
        // entering / leaving TerminalInsert re-pushes.
        let cursor_inputs = (app.ad().modal, app.ad().terminal_insert_active);
        if last_cursor_inputs != Some(cursor_inputs) {
            execute!(
                terminal.backend_mut(),
                cursor_style_for(cursor_inputs.0, cursor_inputs.1)
            )
            .context("set cursor style")?;
            last_cursor_inputs = Some(cursor_inputs);
        }

        // §5.6.8: one Cache::load per frame for the active document.
        // Steady-state ~300ps when the actor hasn't published since
        // last frame; ~16ns on the first read after a publish.
        // The Arc keeps the snapshot alive for the entire frame --
        // the actor is free to publish concurrently and the new
        // pointer is observed by next frame's load.
        // Slice 3c.final.E.5j: per-frame snapshot read via the
        // published `ad().snapshot` mirror (Arc-bump clone off the
        // same source as `snapshot_cache.load_arc()`).
        let frame_snap = app.ad().snapshot.clone();
        let draw_t0 = if perf_input {
            // Reset the per-frame byte tally so we count only THIS draw's
            // write (the cursor-style execute! above already happened).
            PERF_FRAME_BYTES.store(0, Ordering::Relaxed);
            Some(Instant::now())
        } else {
            None
        };
        // Pin the ActiveDocumentRenderState snapshot so every
        // `app.ad()` call inside the draw sees the same cursor,
        // scroll, option, and modal state — without the pin the
        // actor can publish a new RenderState between any two
        // independent ad() calls, causing the cursorline highlight
        // and cursor blink position to disagree.
        app.pin_render_state();
        let mut completion_docs_dims: Option<(u32, u32)> = None;
        terminal
            .draw(|frame| {
                completion_docs_dims = draw_frame(frame, &app, &frame_snap);
            })
            .context("draw frame")?;
        app.unpin_render_state();
        // PU.5c: completion-docs popup geometry hand-off (diff-then-send,
        // peer of the floating-popup feedback above). `draw_frame` returns
        // the docs popup's inner (rows, cols) when shown — computed at the
        // exact draw site (it is cursor-anchored, so position-dependent) —
        // and the host sizes the `PaneId::COMPLETION_DOCS` matrix from it.
        // `None` when no docs popup → nothing sent (the synthetic pane just
        // isn't built).
        if last_completion_docs_dims != completion_docs_dims {
            if let Some((rows, cols)) = completion_docs_dims {
                app.set_completion_docs_viewport(rows, cols);
            }
            last_completion_docs_dims = completion_docs_dims;
        }
        // Perf timer: this draw is the one that renders the keystroke applied
        // at the end of the PREVIOUS iteration. Report input→glyph (our side),
        // the bare draw duration, AND the bytes written to the terminal — the
        // last is the real driver of present time on a slow pty (vim writes a
        // handful; a whole-viewport rewrite is kilobytes). Clear so we only log
        // frames that actually rendered fresh input (not async repaints).
        if perf_input && let (Some(input_at), Some(t0)) = (last_input_at.take(), draw_t0) {
            let done = Instant::now();
            eprintln!(
                "[perf] input→glyph {:>7.3}ms  (draw {:>7.3}ms, {} bytes)",
                done.duration_since(input_at).as_secs_f64() * 1e3,
                done.duration_since(t0).as_secs_f64() * 1e3,
                PERF_FRAME_BYTES.load(Ordering::Relaxed),
            );
        }

        // I.3 (event-driven wake): block until the input reader forwards a
        // terminal event or the actor's `paint_request` forwards a repaint,
        // then drain every wake already buffered before looping back to draw
        // once. A typing burst collapses to N applies + ONE draw (I.1's
        // coalescing, now over the wake channel — the mockable seam I.1
        // deferred to here). `recv()` parks the thread with zero CPU while
        // idle, so an idle editor issues zero draws and the up-to-100ms
        // async-repaint lag is gone. The translate context is rebuilt per key
        // inside `apply_event` because applying one event can change the modal
        // state / mode stack that governs the next event's translation. See
        // docs/dev/architecture/input-pipeline.md.
        match wake_rx.recv() {
            Ok(first) => {
                let repaint_only =
                    drain_wakes(&mut app, &wake_rx, first, perf_input, &mut last_input_at);
                // X1b: repaint-only wakes (hover response, syntax reparse,
                // search excerpts) need a tick drain so the pending channel
                // is read before the next draw. Keystrokes drain it already
                // at the apply tail; this path covers the idle-arrival gap.
                if repaint_only {
                    app.drain_async_pending();
                }
            }
            // Both producer clones are gone (the reader thread died and the
            // paint bridge exited) — nothing can wake us again; leave the loop.
            Err(_) => break,
        }
    }
    // I.3 teardown: stop the reader thread and join it before `run` restores
    // the terminal, so no detached thread is left reading stdin once raw mode
    // is disabled. The reader observes the flag within its 100ms poll tick.
    reader_stop.store(true, Ordering::Relaxed);
    let _ = reader_handle.join();
    Ok(())
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic)]
    use super::*;
    use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
    use lattice_grammar::{SearchDirection, VisualKind};

    /// Build a plain `Event::Key` for a character (no modifiers).
    fn key(c: char) -> Event {
        Event::Key(KeyEvent::new(KeyCode::Char(c), KeyModifiers::NONE))
    }

    /// I.3: `drain_wakes` applies every buffered input event in one batch —
    /// the coalescing the event-driven loop relies on for the keystroke UX
    /// contract (N queued keys → N applies → ONE draw) — and arms the perf
    /// timer because real input was applied. The wake channel is the mockable
    /// event source I.1's burst test was deferred to.
    #[test]
    fn drain_wakes_applies_and_coalesces_buffered_input() {
        let mut app = App::new(Document::from_text("hello\n"));
        let (tx, rx) = mpsc::channel::<Wake>();
        // Queue a burst: `i` enters Insert, `X` types a char.
        tx.send(Wake::Input(key('i'))).unwrap();
        tx.send(Wake::Input(key('X'))).unwrap();
        let first = rx.recv().unwrap();
        let mut last_input_at = None;
        let _ = drain_wakes(&mut app, &rx, first, true, &mut last_input_at);
        // Whole burst drained in one batch — nothing left for a second draw.
        assert!(rx.try_recv().is_err(), "burst must coalesce into one drain");
        // Real input applied → perf timer armed + modal advanced to Insert.
        assert!(
            last_input_at.is_some(),
            "applied input must arm the perf timer"
        );
        assert_eq!(app.ad().modal, ModalState::Insert, "`i` must enter Insert");
    }

    // --- ML.4: modeline clicks ----------------------------------------

    /// Build a left-button press at `(col, row)`.
    fn click(col: u16, row: u16) -> Event {
        Event::Mouse(crossterm::event::MouseEvent {
            kind: crossterm::event::MouseEventKind::Down(crossterm::event::MouseButton::Left),
            column: col,
            row,
            modifiers: KeyModifiers::NONE,
        })
    }

    /// A click that lands on a recorded region dispatches that region's
    /// command through the ordinary invocation path — the same one a
    /// keystroke bound to the action would take.
    #[test]
    fn a_click_on_a_recorded_region_invokes_its_command() {
        let mut app = App::new(Document::from_text("hello world\n"));
        // `:` opens the command line — a visible, cheap-to-assert effect
        // reachable from a CommandId without standing up a mode.
        let command = app.editor.builtins.word_forward.0;
        app.modeline_hits
            .borrow_mut()
            .push(lattice_host::modeline::ModelineHitZone {
                row: 23,
                col_start: 4,
                col_end: 9,
                action: command,
            });

        let mut last_input_at = None;
        apply_event(&mut app, click(5, 23), true, &mut last_input_at);

        assert_eq!(
            app.ad().cursor.byte,
            6,
            "the click must dispatch the element's command (w → next word)"
        );
        assert!(
            last_input_at.is_some(),
            "a click that did something is real input"
        );
    }

    /// A click on dead space is a no-op — not a swallowed key, not a
    /// spurious perf-timer arm.
    #[test]
    fn a_click_outside_every_region_does_nothing() {
        let mut app = App::new(Document::from_text("hello\n"));
        let command = app.editor.builtins.word_forward.0;
        app.modeline_hits
            .borrow_mut()
            .push(lattice_host::modeline::ModelineHitZone {
                row: 23,
                col_start: 4,
                col_end: 9,
                action: command,
            });

        let mut last_input_at = None;
        apply_event(&mut app, click(20, 23), true, &mut last_input_at);

        assert_eq!(app.ad().cursor.byte, 0, "cursor must not move");
        assert!(
            last_input_at.is_none(),
            "a click on nothing must not be counted as input"
        );
    }

    /// Only the left button acts. Right / middle are reserved (a context
    /// menu is a plausible future) and wheel events must never be
    /// mistaken for clicks — scrolling over a modeline would otherwise
    /// fire its command repeatedly.
    #[test]
    fn non_left_button_events_are_ignored() {
        let mut app = App::new(Document::from_text("hello\n"));
        let command = app.editor.builtins.word_forward.0;
        app.modeline_hits
            .borrow_mut()
            .push(lattice_host::modeline::ModelineHitZone {
                row: 23,
                col_start: 4,
                col_end: 9,
                action: command,
            });

        let mut last_input_at = None;
        for kind in [
            crossterm::event::MouseEventKind::Down(crossterm::event::MouseButton::Right),
            crossterm::event::MouseEventKind::Up(crossterm::event::MouseButton::Left),
            crossterm::event::MouseEventKind::ScrollDown,
            crossterm::event::MouseEventKind::Moved,
        ] {
            apply_event(
                &mut app,
                Event::Mouse(crossterm::event::MouseEvent {
                    kind,
                    column: 5,
                    row: 23,
                    modifiers: KeyModifiers::NONE,
                }),
                true,
                &mut last_input_at,
            );
            assert_eq!(app.ad().cursor.byte, 0, "{kind:?} must not dispatch");
        }
    }

    /// I.3: a `Repaint` wake (forwarded from `paint_request`) drives the
    /// redraw at the loop top but applies NO input — it must not arm the perf
    /// timer or mutate modal state. This is what keeps an async republish
    /// (syntax recolour, LSP) repainting promptly without being mistaken for a
    /// keystroke.
    #[test]
    fn drain_wakes_repaint_applies_no_input() {
        let mut app = App::new(Document::from_text("hello\n"));
        let (_tx, rx) = mpsc::channel::<Wake>();
        let mut last_input_at = None;
        let repaint_only = drain_wakes(&mut app, &rx, Wake::Repaint, true, &mut last_input_at);
        assert!(repaint_only, "repaint batch must return repaint_only=true");
        assert!(last_input_at.is_none(), "repaint must not look like input");
        assert_eq!(
            app.ad().modal,
            ModalState::Normal,
            "repaint must not change modal"
        );
    }

    /// `<Esc>` dismisses an open floating popup even when the DOCUMENT keeps
    /// focus (State A) — the GPUI peer already does this; the TUI used to
    /// only close on State-B Esc or cursor motion. Regression guard for the
    /// user-reported "Esc doesn't close the hover popup" bug.
    #[test]
    fn esc_dismisses_floating_popup_in_state_a() {
        let mut app = App::new(Document::from_text("fn main() {}\n"));
        let content = crate::help::HelpContent::from_lines("hover", vec!["doc".to_string()]);
        app.open_floating_popup(
            content,
            lattice_core::ui::popup::PopupPlacement::CursorAnchored,
        );
        assert!(app.popup().is_open(), "floating popup open");
        assert_ne!(
            app.ad().buffer_kind,
            crate::buffers::BufferKind::Help,
            "State A: document keeps focus (popup not focused)"
        );
        let mut last = None;
        apply_event(
            &mut app,
            Event::Key(KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE)),
            false,
            &mut last,
        );
        assert!(
            !app.popup().is_open(),
            "Esc over the document must dismiss the floating popup (State A)"
        );
    }

    #[test]
    fn esc_closes_a_help_split_pane() {
        // `help.describe-display=split-h` opens help in its OWN split pane.
        // `<Esc>` — now owned by help-mode's keymap — must CLOSE that pane and
        // return to the sibling, NOT restore a buffer into it (the reported
        // "Esc should close help buffers even when opened in splits"). Driven
        // end-to-end through `apply_event` so the whole path is exercised: the
        // help-mode `<Esc>` keymap → `action:help-dismiss` → `Effect::DismissPopup`
        // → `dismiss_popup`'s split-close branch. `App::new` runs `Editor::boot`,
        // so the mode keymap + the command are wired exactly as in production.
        let mut app = App::new(Document::from_text("fn main() {}\n"));
        let content = crate::help::HelpContent::from_lines("describe", vec!["body".to_string()]);
        app.open_help_in_split(
            content,
            lattice_core::ui::pane::SplitOrientation::Horizontal,
        );
        assert_eq!(
            app.editor.pane_tree.len(),
            2,
            "split-h opens a second pane holding help"
        );
        assert_eq!(app.editor.active_buffer, crate::buffers::BufferKind::Help);

        let mut last = None;
        apply_event(
            &mut app,
            Event::Key(KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE)),
            false,
            &mut last,
        );

        assert_eq!(
            app.editor.pane_tree.len(),
            1,
            "Esc must CLOSE the help split pane, not restore a buffer into it"
        );
        assert_ne!(
            app.editor.active_buffer,
            crate::buffers::BufferKind::Help,
            "focus returns to the surviving (document) pane"
        );
    }

    #[test]
    fn normal_mode_uses_block_cursor() {
        assert!(matches!(
            cursor_style_for(ModalState::Normal, false),
            SetCursorStyle::SteadyBlock
        ));
    }

    #[test]
    fn insert_mode_uses_bar_cursor() {
        assert!(matches!(
            cursor_style_for(ModalState::Insert, false),
            SetCursorStyle::SteadyBar
        ));
    }

    #[test]
    fn visual_charwise_uses_block_cursor() {
        assert!(matches!(
            cursor_style_for(ModalState::Visual(VisualKind::Charwise), false),
            SetCursorStyle::SteadyBlock
        ));
    }

    #[test]
    fn visual_linewise_uses_block_cursor() {
        assert!(matches!(
            cursor_style_for(ModalState::Visual(VisualKind::Linewise), false),
            SetCursorStyle::SteadyBlock
        ));
    }

    #[test]
    fn operator_pending_uses_block_cursor() {
        assert!(matches!(
            cursor_style_for(ModalState::OperatorPending, false),
            SetCursorStyle::SteadyBlock
        ));
    }

    #[test]
    fn replace_mode_uses_underscore_cursor() {
        assert!(matches!(
            cursor_style_for(ModalState::Replace, false),
            SetCursorStyle::SteadyUnderScore
        ));
    }

    #[test]
    fn command_mode_uses_bar_cursor() {
        assert!(matches!(
            cursor_style_for(ModalState::Command, false),
            SetCursorStyle::SteadyBar
        ));
    }

    #[test]
    fn search_mode_uses_bar_cursor() {
        assert!(matches!(
            cursor_style_for(ModalState::Search(SearchDirection::Forward), false),
            SetCursorStyle::SteadyBar
        ));
        assert!(matches!(
            cursor_style_for(ModalState::Search(SearchDirection::Backward), false),
            SetCursorStyle::SteadyBar
        ));
    }

    /// Terminal-mode T2.b: `terminal_insert_active` forces the
    /// shape to `SteadyBar` regardless of `ModalState` (which
    /// stays `Normal` because TerminalInsert is a minor mode).
    /// Normal-in-terminal (insert-active = false) stays
    /// `SteadyBlock` so the user can tell at a glance which
    /// sub-state they're in.
    #[test]
    fn terminal_insert_minor_mode_overrides_to_bar() {
        assert!(matches!(
            cursor_style_for(ModalState::Normal, true),
            SetCursorStyle::SteadyBar
        ));
        assert!(matches!(
            cursor_style_for(ModalState::Normal, false),
            SetCursorStyle::SteadyBlock
        ));
    }
}

/// OS.1: the keyboard-enhancement gate.
///
/// The push itself needs a tty and cannot be tested here; the DECISION can,
/// which is why it is a separate function. Both conditions must hold, and the
/// two failure directions are different bugs: pushing when the user turned it
/// off ignores their config, and pushing when the terminal does not support it
/// sends an escape sequence into a terminal that will render it as garbage.
#[cfg(test)]
mod os1_tests {
    use super::should_push_enhancement;

    #[test]
    fn the_option_off_means_no_push_even_when_supported() {
        assert!(!should_push_enhancement(false, true));
    }

    #[test]
    fn an_unsupporting_terminal_is_not_pushed_to() {
        assert!(!should_push_enhancement(true, false));
    }

    #[test]
    fn a_supporting_terminal_with_the_option_on_is_pushed_to() {
        assert!(should_push_enhancement(true, true));
    }
}