lattice_ui_tui/

app.rs

//! Pure application state and transitions.
//!
//! The state machine is intentionally separated from the IO loop so it can be
//! unit-tested without spinning up a terminal. Each input keystroke becomes
//! an `Action`; `App::apply` consumes the action, dispatching motion / edit
//! work through `lattice_grammar::execute()` where appropriate.
//!
//! Slice 3c.final.E.swap aftermath: many App-side delegate methods +
//! free helper functions in this file are only reachable from
//! `#[cfg(test)] mod tests` blocks; the production paint / dispatch
//! paths route through the `mutate_editor` / `read_editor` seam or
//! the published RS sub-states (`ad()`, `panes()`, `popup()`, ...).
//! The `#![allow(dead_code)]` below acknowledges that test-only state
//! without restructuring 30+ methods into `#[cfg(test)] impl App`
//! blocks. A follow-up cleanup slice (`3c.final.E.cleanup`) can
//! tighten this if the lint signal becomes load-bearing for catching
//! genuine future dead code.
#![allow(dead_code)]
//!
//! ## Module layout
//!
//! This file holds the `App` struct definition, the cross-feature data
//! types it carries (`Action`, the LSP outcome enums + structs,
//! `OptionCache`, `PositionEntry`, `LspNavKind`, `CompletionState`,
//! `Fold`, `EchoMessage`, `EchoLevel`, `SearchLine`, ...), the
//! cross-module free helpers (`line_byte_len`, `is_word_char_byte`,
//! `word_under_cursor`, etc.), and a `mod tests` block of cross-
//! feature integration tests. Per-feature App methods live in
//! `app/<feature>.rs` submodules -- see `docs/dev/notes/ui-tui-refactor.md`
//! for the full per-module catalog. The R.1.x slice sequence
//! (R.1.0 -- R.1.98) split the App's monolithic impl block apart.
//!
//! ## Where to look for App methods
//!
//! - `app/dispatch.rs` -- `apply` / `apply_effect` /
//!   `apply_app_effect` / `handle_edits` / `dispatch_blocking` /
//!   `run_*_invocation` / `execute_ex_line` / Effect classifiers.
//! - `app/lsp.rs` -- every `lattice-lsp` consumer (requests,
//!   drains, log buffers, hover, navigation, references,
//!   signature help, completion, rename, code action, format,
//!   symbols, trace, on-type formatting, trigger chars,
//!   workspace/applyEdit + workspace/configuration drains).
//! - `app/lifecycle.rs` -- `:e` / `:w` / `:q` / `:bn` / `:ls` /
//!   `<C-l>`, save family, help-buffer adoption, document swap,
//!   buffer-state hooks, pane snapshot, event publishers.
//! - `app/completion.rs` -- popup state machine, ranker, ghost
//!   text, snippet expansion, refilter, `EffectiveCompletionConfig`.
//! - `app/edit.rs` -- actor-bridge mutation wrappers,
//!   yank / paste / register store, Insert+Replace primitives,
//!   `:d`, block-insert.
//! - `app/motions.rs` -- bracket match, history walkers,
//!   mark jump, viewport / scroll, cursor clamp, viewport
//!   sizing, active-buffer accessors.
//! - `app/folds.rs` -- fold compute / open / close / auto-open.
//! - `app/search.rs` -- `/`, `?`, `:s`, `:%s`, find family.
//! - `app/options.rs` -- `:set`, typed options, customize,
//!   per-language overrides, typed-option getters.
//! - `app/cmdline.rs` -- `:` minibuffer + completion.
//! - `app/help.rs` -- `:help`, `:describe-*`, `:apropos`,
//!   `:keymap`, `do_help_follow_link`.
//! - `app/highlights.rs` -- tree-sitter highlight cache +
//!   per-frame refresh + post-edit shift.
//! - `app/visual.rs` -- charwise / linewise / blockwise
//!   selection state, `set_selections_blocking`.
//! - `app/picker.rs` -- picker state machine + candidate
//!   builders.
//! - `app/boot.rs` -- `App::new`, `build_lsp_subsystem`,
//!   `load_persistent_config`, `sync_keymap_overlays`,
//!   `sync_theme_from_config`.
//! - `app/file_tree.rs` -- file-tree buffer ops.
//! - `app/oil.rs` -- oil buffer ops.
//! - `app/macros.rs` -- `q` recording / `@` replay.
//! - `app/mode.rs` -- `modal_label` + `enter_mode` +
//!   `activate_major_for_buffer_kind`.
//! - `app/syntax.rs` -- `maybe_reparse_syntax`.
//! - `app/test_helpers.rs` -- shared test fixtures.

use lattice_core::Buffer;
#[cfg(test)]
use lattice_core::Document;
// SearchDirection + YankKind + ModalState: only referenced
// from `mod tests` after the migrations. Gate to test-only
// (or `pub use`) so the `#![deny(unused_imports)]` lint
// stays clean for production builds while submodule tests
// keep resolving them via `use super::*;`.
#[cfg(test)]
use lattice_grammar::SearchDirection;
#[cfg(test)]
use lattice_grammar::YankKind;
// Re-exported so submodule tests using `use super::*;` keep
// seeing the names after Phase 5.B.* migrations.
// `BufferRegistry` + `DocumentEntry` were used inline by the
// App::new boot body before Phase 5.7.B.1 moved that work to
// `lattice_host::editor::Editor::boot`. The crate-root re-export
// (lib.rs `pub use buffer_registry::{...}`) keeps the external
// path `lattice_ui_tui::BufferRegistry` available for downstream
// consumers; `BufferData` + `BufferEntry` stay in scope here for
// the submodule tests that build entries by hand.
#[cfg(test)]
use crate::buffer_registry::{BufferData, BufferEntry};
#[cfg(test)]
use crate::buffers::BufferFlags;
use crate::buffers::{BufferId, BufferKind};
pub use lattice_grammar::ModalState;
pub use lattice_grammar::command::CommandInvocation;
#[cfg(test)]
use lattice_grammar::register::Register;
use lattice_protocol::position::Position;
#[cfg(test)]
use lattice_protocol::selection::{Selection, SelectionSet};

// Re-export PaneDirection so `super::*` in the tests module
// resolves it. The `Action::NavigatePane(PaneDirection)` variant
// now lives in `lattice_host::action::Action`; this re-export
// keeps the test paths compiling.
pub use lattice_grammar::PaneDirection;

// R.1.0 -- app/ submodule skeleton. Each submodule is a
// per-feature destination for the App's methods. R.1.0 only
// creates the empty modules with scoping doc comments;
// subsequent R.1.x slices move method blocks across without
// rethinking the structure. See docs/dev/architecture/keymap-architecture.md
// (or the dedicated R.1 doc) for the full feature -> module
// mapping.
mod boot;
// CG.1: `<C-c>` foreground cancellation, exercised key-first through
// translate + apply. Test-only — the handlers live in `lattice-host`.
#[cfg(test)]
mod cancel;
mod cmdline;
mod completion;
mod dispatch;
mod display;
mod edit;
mod file_tree;
mod folds;
mod help;
mod highlights;
// Paramount goal #1's ratchet clause: the keystroke→glyph distribution
// gate. Test-only — it measures the production path (translate → apply →
// compose) rather than adding one.
/// The shipped `comment` plugin, driven through the real keystroke path.
#[cfg(test)]
mod comment_plugin;
#[cfg(test)]
mod keystroke_glyph_ratchet;
mod lifecycle;
mod lsp;
mod lsp_log_buffers;
mod lsp_watcher;
mod macros;
#[cfg(test)]
mod magit_bindings;
mod messages;
mod mode;
/// VM.3: operator+motion composition, driven through the real keystroke path.
mod motion_composition;
mod motions;
mod oil;
mod operators;
mod options;
pub(crate) mod picker;
mod popup;
mod search;
mod state;
#[cfg(test)]
mod surround_bindings;
mod syntax;
mod visual;

#[cfg(test)]
pub(crate) mod test_helpers;

// Slice 8.i.4.d: the `Pending` enum and `Action::SetPending`
// variant retired here. All multi-key Normal-mode chord state
// flows through `App::partial_chord` driven by
// `Action::AbsorbPartialChord` (slices 8.i.4.a/b) plus
// `AppEffect::AbsorbOperatorPrefix(_)` for operator prefixes
// (slice 8.i.4.c). `App::apply`'s pending field, the
// `Action::SetPending(_)` arm, and the "non-SetPending clears
// pending" guard are gone.

/// Vim's `H` / `M` / `L` cursor target within the visible
/// viewport. Slice 8.i.2.c hoisted the type into
/// `lattice_grammar::app_effect` so `AppEffect::JumpViewport`
/// can carry it; this is a re-export so existing
/// `crate::app::ViewportPos` callers stay compiling.
pub use lattice_grammar::ViewportPos;

/// Vim's `zz` / `zt` / `zb` post-scroll cursor target. Re-export
/// of the `lattice_grammar` definition (see `ViewportPos` above
/// for rationale).
pub use lattice_grammar::ScrollPos;

// Phase 5.2: `FindKind`, `EchoMessage`, `EchoLevel`, and the
// `Action` enum (below) moved to `lattice_host::action`. The
// re-exports preserve every existing `crate::app::Action` /
// `crate::app::EchoLevel` import in this crate's modules + tests
// + benches; no call-site changes needed.
pub use lattice_host::action::{Action, EchoLevel, EchoMessage, FindKind};

// `MessageRecord` / `MessagesRing` / `MessagePushed` are
// renderer-agnostic, live in [`lattice_runtime`], and re-
// exported below so existing call sites that imported them
// through `crate::app::*` keep working. The wire-typed
// `lattice_grammar::EchoLevel` rides through unchanged --
// `crate::app::EchoLevel` is the display-typed peer kept for
// renderer-side ergonomics; conversion lives at the
// `set_message` seam.
pub use lattice_runtime::{MessagePushed, MessageRecord, MessagesRing};

/// Convert the renderer's display-typed `EchoLevel` to the
/// wire-typed `lattice_grammar::EchoLevel` used by
/// `MessageRecord` (and every other host-side / plugin-side
/// subscriber on the typed bus). The variants are bit-
/// identical; the split between display-typed (ui-tui) and
/// wire-typed (grammar / runtime / plugin host) is the
/// existing convention that kept the renderer surface from
/// leaking into the grammar layer.
/// Convert the renderer's display-typed `EchoLevel` to the
/// wire-typed `lattice_grammar::EchoLevel`. Mirror exists in
/// [`lattice_host::dispatch`] (private) for the host-side
/// `set_message`; this copy stays around for any future ui-tui
/// caller that needs wire-typed projection without crossing the
/// host boundary.
#[allow(dead_code)]
pub(crate) fn echo_level_to_wire(level: EchoLevel) -> lattice_grammar::EchoLevel {
    match level {
        EchoLevel::Trace => lattice_grammar::EchoLevel::Trace,
        EchoLevel::Debug => lattice_grammar::EchoLevel::Debug,
        EchoLevel::Info => lattice_grammar::EchoLevel::Info,
        EchoLevel::Warn => lattice_grammar::EchoLevel::Warn,
        EchoLevel::Error => lattice_grammar::EchoLevel::Error,
    }
}

/// Reverse of [`echo_level_to_wire`]: every renderer-side
/// reader of `MessageRecord` (e.g. the `*messages*` formatter)
/// projects the wire-typed level back to the renderer's
/// display-typed enum. Allowed-dead until the renderer grows
/// a reader site -- the formatter currently matches on the
/// wire-typed enum directly to skip the round-trip.
#[allow(dead_code)]
pub(crate) fn echo_level_from_wire(level: lattice_grammar::EchoLevel) -> EchoLevel {
    match level {
        lattice_grammar::EchoLevel::Trace => EchoLevel::Trace,
        lattice_grammar::EchoLevel::Debug => EchoLevel::Debug,
        lattice_grammar::EchoLevel::Info => EchoLevel::Info,
        lattice_grammar::EchoLevel::Warn => EchoLevel::Warn,
        lattice_grammar::EchoLevel::Error => EchoLevel::Error,
    }
}

// Convert grammar's wire-typed [`lattice_grammar::EchoLevel`] (carried
// by `Effect::Echo`) into the App's display-typed `EchoLevel`. Two types
// because the App's is part of the public crate API; the grammar's is a
// dispatch detail.
// Resolve user-typed command text to a `CommandId`, accepting
// either the canonical registry name (`ex:write`) or an alias
// (`write`, `w`). Used by App handlers that take a command name
// from user input -- mirrors the two-stage logic in
// `excommand::parse_invocation`.
// 5.5.F.2: `resolve_command_name_or_alias` relocated to
// `lattice_host::excommand::resolve_command_name_or_alias` alongside
// `aliases()`. The in-module test now imports it directly through the
// fully-qualified path.

// Phase 5.2: `SearchLine`, `LastSearch`, `UnnamedRegister`,
// `PrevPaneState` moved to `lattice_host::state`. Re-exported
// below.
pub use lattice_host::state::{
    CompletionState, LastSearch, PrevPaneState, SearchLine, UnnamedRegister,
};

// Phase 5.B.13: `PendingPickerInit`, `LivePickerQueryState`,
// `InFlightLiveQuery`, `LIVE_PICKER_DEBOUNCE` moved to
// `lattice_host::state`. Re-exported below so existing
// `crate::app::*` references keep resolving.
pub use lattice_host::state::{
    InFlightLiveQuery, LIVE_PICKER_DEBOUNCE, LivePickerQueryState, PendingPickerInit,
};

// `UnnamedRegister` and `PrevPaneState` moved to
// `lattice_host::state` (re-export above).

// Phase 5.2: LSP cache + outcome types moved to
// `lattice_lsp::cache`. Re-exported here so existing
// `crate::app::HoverOutcome` etc. references continue to
// resolve unchanged across this crate + downstream consumers.
// OR.7: the async-completion drain payload is `lattice-completion`'s now
// (it carries every async source's candidates, not only LSP's).
pub use lattice_completion::AsyncCompletionOutcome;
pub use lattice_lsp::cache::{
    CodeActionOutcome, CodeActionRow, CodeLensOutcome, CompletionItemRow, CompletionOutcome,
    CompletionResolveOutcome, DecodedSemanticToken, DocumentColorOutcome, DocumentHighlightCache,
    DocumentHighlightOutcome, DocumentLinksOutcome, FoldingRangeOutcome, FormatOutcome,
    HoverOutcome, InlayHintOutcome, LspCodeLensCache, LspDocumentColorCache, LspDocumentLinksCache,
    LspFoldsCache, LspInlayHintCache, LspNavKind, LspPullDiagnosticsCache, LspSelectionChain,
    LspSemanticTokensCache, PullDiagnosticsOutcome, ReferencesOutcome, RenameOutcome,
    SelectionRangeOutcome, SelectionRangeStep, SemanticTokensOutcome, SignatureHelpOutcome,
    SymbolRow, SymbolsOutcome, apply_semantic_token_edits, decode_semantic_tokens,
};

// Phase 5.B.3: composition pivot (see
// `docs/dev/architecture/phase-5b-app-design.md`). App is a
// concrete struct -- a thin renderer-specific wrapper around
// the renderer-agnostic `lattice_host::editor::Editor` plus
// the two TUI-shaped caches (`theme`, `pane_render_registry`).
// GPUI's analogue (future `lattice_ui_gpui::App`) takes the
// same shape with its own renderer-specific caches. No
// generics: every `impl App` inside this crate is a plain
// inherent impl, the orphan rule doesn't bite, and per-cluster
// field migrations from App → Editor can land green one at a
// time. The 5.B.2 `App<R: Renderer>` parametrization is
// reverted; the `lattice_host::Renderer` trait + `TuiRenderer`
// marker are retained as Phase 5.6's `lattice-render` work may
// reuse them.
pub struct App {
    /// Composition root for the renderer-agnostic editor state.
    ///
    /// Slice 3c.final.E.swap: the field is cfg-gated. In
    /// production builds (`cfg(not(test))`) the renderer holds
    /// an [`EditorActorHandle`] — Editor lives on its own
    /// thread and the renderer reaches it only through the
    /// handle's blocking RPCs (`mutate_blocking`,
    /// `with_editor`, `mutate_blocking_with`,
    /// `apply_blocking`). In test builds (`cfg(test)`) the
    /// field keeps the original direct-ownership shape so the
    /// existing test fixtures (which mutate state without going
    /// through the dispatch path) keep compiling. This is the
    /// architectural realisation of paramount goal #4: the
    /// `&mut Editor` type cannot escape the actor thread in
    /// production, enforced by the type system.
    #[cfg(not(test))]
    pub editor_actor: lattice_host::editor_actor::EditorActorHandle,
    #[cfg(test)]
    pub editor: lattice_host::editor::Editor,
    /// Phase 5.8.AF.5 / Slice 3c.atomic.A: renderer-owned clone
    /// of the editor's `Arc<ArcSwap<RenderState>>`. Lets the
    /// renderer read state without going through `self.editor`,
    /// which is the structural seam the eventual actor migration
    /// pivots on. Today this Arc is a direct clone of
    /// `editor.render_state` at construction; after 3c moves
    /// Editor to its own thread, the same Arc is published from
    /// the actor thread and read here -- identical contract,
    /// different writer.
    pub render_state: std::sync::Arc<arc_swap::ArcSwap<lattice_host::render_state::RenderState>>,
    /// Per-frame pinned `ActiveDocumentRenderState`. When `Some`
    /// (between `pin_render_state` / `unpin_render_state` calls),
    /// [`Self::ad`] returns this cached snapshot so every `ad()` read
    /// within a single frame draw sees the exact same cursor, scroll,
    /// option, and modal state — regardless of how many call sites
    /// exist or whether the actor publishes a new `RenderState` mid-
    /// frame. Both the TUI and GPUI peers call pin/unpin (or equivalent
    /// in their render loop); without this every independent `ad()`
    /// site in a renderer loads a fresh `Arc` from the shared ArcSwap
    /// and can see a torn snapshot relative to other sites.
    frame_ad: std::sync::Mutex<
        Option<std::sync::Arc<lattice_host::render_state::ActiveDocumentRenderState>>,
    >,
    /// Perf plan B.2 slice B.2.a: renderer-owned clone of the
    /// editor's `syntax_static_overlay_quads_cell`. The cell is the
    /// overlay worker's output channel — written by
    /// `lattice_host::overlay_worker::recompute`, read by the
    /// per-frame overlay paint path. Caching the `Arc` on App
    /// matches the `render_state` pattern (slice 3c.atomic.A):
    /// pre-swap this is a direct clone at construction; post-swap
    /// the same Arc comes from the actor handle.
    ///
    /// display-line B4.2: the dead `syntax_visible_spans_cell` /
    /// `syntax_visible_rows_cell` clones were deleted with the
    /// overlay worker's span/row cache; this is the only worker
    /// output cell the App keeps a clone of now.
    pub syntax_static_overlay_quads_cell:
        std::sync::Arc<arc_swap::ArcSwap<lattice_host::render_state::StaticOverlayQuads>>,
    /// ML.4: where each clickable modeline element was painted, rebuilt
    /// every frame and read when a mouse click arrives.
    ///
    /// `RefCell` because the paint path takes `&App` and this is the
    /// one thing it produces rather than consumes. It is renderer-local
    /// by nature — a record of where THIS terminal put THIS frame's
    /// pixels — so it lives on the TUI's `App` rather than in
    /// `RenderState`, which is the renderer-neutral publication the
    /// GPUI peer reads too. GPUI needs no equivalent: its elements are
    /// real `div`s and the window system does the hit test.
    pub modeline_hits: std::cell::RefCell<lattice_host::modeline::ModelineHitMap>,
    /// MO.2: this frame's pane bodies, for editor-body mouse
    /// hit-testing. Same lifecycle as `modeline_hits` beside it —
    /// recorded during paint, cleared at the top of each frame — so a
    /// pane that stops painting stops taking clicks.
    pub pane_hits: std::cell::RefCell<lattice_host::mouse::PaneHitMap>,
    /// Handle to the per-document actor (DESIGN.md §5.2.1, §5.7).
    /// The actor owns the writable `Document` (from `lattice-core`);
    /// mutations route through it; reads load a versioned snapshot.
    /// Denormalized from `documents[active_document_id].handle` for
    /// hot-path access.
    // Moved to `editor.document`.
    /// Per-thread cached reader for [`Self::document`]'s published
    /// snapshot cell (DESIGN.md §5.6.8). The renderer's per-frame
    /// `snapshot_cache.load()` returns the current
    /// `Arc<DocumentSnapshot>` in ~300ps in steady state (no edit
    /// since last frame); ~16ns when the actor has just published.
    /// Rebuilt whenever [`Self::document`] is reassigned --
    /// `arc_swap::Cache` caches against a specific cell, so it must
    /// follow the active document's handle.
    // Moved to `editor.snapshot_cache`.
    /// Stable id for the *active* document buffer. Mirrors the
    /// active pane's `buffer_id` whenever that pane holds a
    /// Document leaf. Position-history entries (§5.1.1) and
    /// per-pane state record this id; switching the active
    /// document via `:bnext` / `:e FILE` rotates `Self::document` /
    /// `Self::syntax` etc. to the new active.
    // Phase 5.B.16: `document_buffer_id`, `buffers`,
    // `active_buffer`, `cursor`, `scroll`, `should_quit`,
    // `viewport_height`, `terminal_width` moved to
    // `editor.{document_buffer_id, buffers, active_buffer,
    // cursor, scroll, should_quit, viewport_height,
    // terminal_width}`.
    /// Pane tree (DESIGN.md §5.9).
    /// Moved to `editor.pane_tree` (Phase 5.B C4).
    // Phase 5.B.15: `modal` moved to `editor.editor.modal`.
    /// In-flight partial-chord stack from the trie (slice 8.i.4).
    /// When the trie returns `LookupResult::Partial`,
    /// `dispatch_normal` / `dispatch_insert` emit
    /// `Action::AbsorbPartialChord(c)` and `App::apply` appends
    /// `c` here. The next keystroke runs through the trie with
    /// this stack as prefix and resolves the full multi-key
    /// chord. Cleared on every non-`AbsorbPartialChord` action.
    /// Operator-prefix pushes (8 prefixes: `d`, `c`, `y`, `>`,
    /// `<`, `gU`, `gu`, `g~`) come from
    /// `AppEffect::AbsorbOperatorPrefix(_)` via
    /// `apply_app_effect`, which also latches `pending_count`
    /// into `op_count` atomically with the prefix push.
    // Phase 5.B.15: `partial_chord` moved to
    // `editor.editor.partial_chord`.
    /// Grammar registry shared with the document actor by `Arc`. The
    /// actor calls `lattice_grammar::execute` with this registry from
    /// inside its own task. The App also reads it directly for the
    /// parser, completion pipeline, and introspection -- all
    /// read-only operations.
    // Phase 5.B.15: `registry` moved to `editor.editor.registry`.
    /// In-process event bus (DESIGN.md §5.10). The App publishes
    /// editor lifecycle events (DocumentChanged, SelectionsChanged,
    /// ModalModeChanged, BeforeSave, DocumentSaved, BeforeQuit,
    /// OptionChanged) after observing the corresponding state
    /// transitions. The App itself subscribes to `OptionChanged`
    /// for the cascade hook (see [`Self::option_change_rx`]);
    /// other subscribers (plugins, autocmds) wire up the same way.
    // Phase 5.B.15: `event_bus` moved to
    // `editor.editor.event_bus`.
    // Phase 5.B.19: all LSP per-feature request channel fields
    // (`pending_hover_rx/token`, `pending_definition_rx/token`,
    // `pending_nav_kind`, `pending_references_rx/token`,
    // `pending_symbols_rx/token`, `pending_format_rx/token`,
    // `pending_signature_help_rx/token`, `pending_completion_rx/token/items`,
    // `pending_moniker_rx`, `pending_rename_rx/token`,
    // `pending_code_action_rx/token/items/handle`) moved to
    // `editor.*` -- access via `self.editor.pending_*`.
    /// Receiver end of the App's own subscription to
    /// `EventKind::OptionChanged` (DESIGN.md §5.10 + §5.12). The
    /// typed-options registry publishes through `event_bus` on
    /// every successful set; this channel queues those events for
    /// [`Self::drain_option_changes`] to consume on the App's main
    /// thread. Decouples cascade timing from the publish path
    /// (publishes can come from any thread -- plugin tasks, future
    /// LSP-driven config writes, the customize buffer) without
    /// risking re-entrancy on the registry mutex or the renderer.
    ///
    /// `Option` only because the field needs to be `take`-able so
    /// the drain method can borrow `&mut self` for cascade work
    /// while iterating the receiver. Always `Some` between calls.
    // Phase 5.B.14: `option_change_rx` moved to
    // `editor.editor.option_change_rx`.
    /// Shared language registry for tree-sitter highlighting. One
    /// `Arc<LangRegistry>` services the document buffer's `Syntax`
    /// AND every `HelpBuffer` constructed by `:describe-*` /
    /// `:apropos` / `:keymap`. Help bodies render with markdown
    /// highlighting (headings, fenced-block injections to the
    /// language tag) sourced from this same registry.
    // Phase 5.B.12: `lang_registry` moved to
    // `editor.editor.lang_registry`.
    // Phase 5.B.15: `builtins` moved to `editor.editor.builtins`.
    /// App-side typed action IDs (`CommandKind::Action`
    /// registrations from `crate::actions::populate`). Each
    /// field is a `CommandId` resolving to an `ActionSpec` whose
    /// `apply` returns `Effect::AppAction(AppEffect::Foo)`. Per-
    /// mode keymap modules consume this alongside `builtins` to
    /// build typed `CommandInvocation`s for chord bindings (slice
    /// 8.i; see `docs/dev/notes/8i-approach.md`).
    // Phase 5.B.15: `action_ids` moved to
    // `editor.editor.action_ids`.
    /// Layered keymap registry (DESIGN.md §5.2.3, audit slice 8.c).
    /// Populated at construction time; the input dispatcher reads
    /// from it on every keystroke. Wait-free reads via the
    /// internal `ArcSwap`; concurrent registration writes (mode
    /// push/pop, plugin registration, `:bind`) never stall the
    /// input path. Slices 8.d / 8.e / 8.f wire Replace, Visual,
    /// and Insert through this; Normal follows in 8.g.
    // Phase 5.B.15: `keymap` moved to `editor.editor.keymap`.
    /// `LayerId` of the active completion-popup minor-mode
    /// layer when the popup is open; `None` otherwise. Pushed /
    /// popped by [`Self::sync_keymap_overlays`] in lockstep with
    /// `self.editor.insert_completion`. Slice 8.f.
    // Phase 5.B.15: `completion_popup_layer` moved to
    // `editor.editor.completion_popup_layer`.
    /// `LayerId` of the active-snippet minor-mode layer when a
    /// snippet is in flight; `None` otherwise. Same lockstep
    /// pattern as [`Self::completion_popup_layer`].
    // Phase 5.B.15: `snippet_layer` moved to
    // `editor.editor.snippet_layer`.
    // Phase 5.B.11: `command_line`, `last_message`,
    // `messages`, `pending_message_event_rx`, `pending_redraw`
    // moved to `editor.{command_line, last_message, messages,
    // pending_message_event_rx, pending_redraw}`.
    /// Per-document tree-sitter state. `None` when the document's language
    /// is `Plain` (no grammar bundled).
    ///
    /// Audit slice 3: this is now an async handle. Reparses run
    /// on a worker task (`tokio::task::spawn_blocking`) so the
    /// UI thread never parses; reads against the latest snapshot
    /// are wait-free via `ArcSwap`. The `Syntax` struct itself
    /// stays accessible for one-shot users (help-buffer
    /// markdown highlighting).
    // Phase 5.B.12: `syntax`, `last_parsed_text_version`,
    // `pending_syntax_edits`, `last_synced_syntax_version`,
    // `visible_highlights` moved to `editor.{syntax,
    // last_parsed_text_version, pending_syntax_edits,
    // last_synced_syntax_version, visible_highlights}`.
    /// Slice B.3: cache key validating the contents of
    /// `visible_highlights`. When `refresh_highlights` finds the
    /// freshly-computed key matches this stored key, the
    /// existing `visible_highlights` is still valid and the
    /// `highlight_lines` call is skipped entirely (~178µs at
    /// 24-line viewport on rust per BENCHMARKS.md →
    /// noise-floor on cache hit).
    ///
    /// Invariant: `Some` ⟹ `visible_highlights` was computed
    /// against this key's snapshot+state. `None` after construction,
    /// after the syntax handle is replaced, and after a state-
    /// change render where the key check passes the recompute
    /// branch (the new key is stored).
    ///
    /// Steady-state hit rate: ~100% (cursor blinking, no edit).
    /// Drops cleanly to 0% during edits/scroll/fold-toggle.
    // 5.B C5 cleanup: `visible_highlights_key` moved to
    // `editor.visible_highlights_key`.
    // Phase 5.B.7: `search_line`, `last_search`,
    // `current_match`, `all_matches`, `substitute_preview`
    // moved to `editor.search_line` / `editor.last_search`
    // / `editor.current_match` / `editor.all_matches` /
    // `editor.substitute_preview`.
    // Phase 5.B.5: `unnamed_register` moved to
    // `editor.unnamed_register`.
    // Phase 5.B.8: `pending_count`, `op_count`,
    // `visual_anchor`, `last_change`, `last_visual` moved
    // to `editor.{pending_count, op_count, visual_anchor,
    // last_change, last_visual}`.
    // Phase 5.B.5: `marks` moved to `editor.marks`.
    // Phase 5.B.9: `replace_history` moved to
    // `editor.replace_history`.
    // Phase 5.B.5: `registers` and `pending_register` moved
    // to `editor.registers` / `editor.pending_register`.
    /// Unified position-history ring (§5.1.1). Every entry is tagged
    /// by source, so different keybindings can iterate filtered views
    /// of the same data:
    ///
    /// - `Ctrl-O` / `Ctrl-I` (Tab) walk `AutoJump` and `PluginPush`.
    /// - `g;` / `g,` walk `NamedMark`.
    ///
    /// Pushed before "big jumps" (gg, G, search submit, n / N, *, #,
    /// %, mark jumps) with `AutoJump`, plus on every `mX` with
    /// `NamedMark(X)`. The cursor sits at one past the last navigated
    // Phase 5.B.6: `position_history`,
    // `position_history_cursor`, `recent_files`, `tag_stack`,
    // `pending_tag_origin` moved to
    // `editor.position_history` / `editor.position_history_cursor`
    // / `editor.recent_files` / `editor.tag_stack` /
    // `editor.pending_tag_origin`.
    // Phase 5.B.4: `macros`, `macro_recording`,
    // `last_played_macro` moved to `editor.macros` /
    // `editor.macro_recording` / `editor.last_played_macro`.
    // Phase 5.B.8: `last_find` moved to `editor.last_find`.
    /// Manual folds. v1 supports non-nested folds defined by line range.
    /// `closed=true` means the fold's interior is skipped during render.
    // Moved to editor.folds.
    // Phase 5.B.9: `last_insert`, `pending_block_insert`,
    // `recording_insert` moved to `editor.{last_insert,
    // pending_block_insert, recording_insert}`.
    /// Shared typed-options registry (DESIGN.md §5.12). Every
    /// option's *current value* lives in here behind an
    /// `ArcSwap<T>`; `:set` parses against it; the customize
    /// buffer view (post-1.0) reads + writes through the same
    /// surface. Renderer-agnostic options self-register via
    /// the `linkme`-aggregated `OPTION_DECLS` slice; this
    /// renderer's own options register via the `linkme` slice in
    /// `crate::tui_options`.
    // Phase 5.B.14: `config` moved to `editor.editor.config`.
    /// Hot-path read cache for the option values. Populated at
    /// [`Self::new`] time; refreshed inside the
    /// `Event::OptionChanged` cascade so writes through any path
    /// (cmdline, plugins, the future customize buffer) propagate.
    /// Accessor methods on `App` (`foldmethod()` / `tabstop()` /
    /// `show_line_numbers()` / ...) read the cached primitive
    /// directly (~1ns field access) instead of going through the
    /// registry's mutex + ArcSwap + downcast (~33ns). The
    /// renderer hits these accessors per visible line, so the
    /// difference is measurable on the 60-line / 120-line frame
    /// benchmarks. Single source of truth stays in
    /// [`Self::config`]; this struct is a derived projection.
    // Phase 5.B.14: `option_cache` moved to
    // `editor.editor.option_cache`.
    // M.2.0c: TUI-specific options self-register via the
    // linkme slice. No `tui_options` field needed -- callers
    // read directly via `config.get_typed::<UiDimInactive>()`
    // etc. (see `sync_theme_from_config`).
    /// Mode registry (M.1). Owns the catalogue of registered
    /// modes; activation / deactivation routes through here.
    /// One process-shared registry; all Documents share the
    /// same mode definitions.
    // Phase 5.B.14: `mode_registry` moved to
    // `editor.editor.mode_registry`.
    /// Phase 3: typed service map subsystems hand off to modes
    /// so the mode's `Mode::on_activate` can pull subsystem
    /// handles via `ctx.service::<T>()`. Populated at boot (LSP
    /// supervisor handle, buffer-uri resolver). Read-only after
    /// init.
    ///
    /// M-async.1: `Arc<ServiceRegistry>` (not bare
    /// `ServiceRegistry`) because `ModeContext` owns its handles
    /// by Arc clone -- the dispatcher does `services.clone()`
    /// per activation to build the owned ctx.
    // Phase 5.B.14: `services` moved to `editor.editor.services`.
    /// M-async.1/2: per-`(buffer, mode)` Guard storage. Modes
    /// return an owned [`Mode::Guard`](lattice_mode::Mode::Guard)
    /// from `on_activate`; the dispatcher stashes it here keyed
    /// by `(BufferId, ModeId)`. On deactivation the dispatcher
    /// drops the Guard, firing its `Drop` impl for synchronous
    /// cleanup (unsubscribe, restore prior option, drop
    /// supervisor handle).
    ///
    /// M-async.2: wrapped in [`GuardStoreHandle`] (Arc<Mutex<>>)
    /// because the spawned lifecycle task locks + inserts on
    /// `on_activate` resolve from a tokio worker thread; the App
    /// thread locks + removes on deactivate.
    // Phase 5.B.14: `mode_guards` moved to
    // `editor.editor.mode_guards`.
    /// Mode-keyed pane render dispatch (M.4 follow-up). Populated
    /// at boot; lookup walks active minors then the major to find
    /// the per-buffer renderer + status formatter, with the
    /// document path as the fallback when no provider matches.
    /// Replaces the helper-side `match buffer.kind` in
    /// `draw_pane_content` and `pane_status_label`.
    pub pane_render_registry: crate::pane_render::PaneRenderRegistry,
    /// Per-buffer active modes (major + minors). M.1 wired the
    /// field on `Document` for the document buffer, but
    /// `Document` lives behind the actor's snapshot-cache, so
    /// for M.2.1 the App layer maintains a parallel
    /// per-buffer map keyed by `buffers::BufferId` -- this is
    /// the version `recompute_options_for_buffer` reads to
    /// pull mode contributions. `Document.modes` and this map
    /// converge in M.4 when `ActiveModes` joins
    /// `DocumentSnapshot`.
    // Phase 5.B.14: `active_modes` moved to
    // `editor.editor.active_modes`.
    /// Per-buffer mode-owned local state (M.3.2.a). Modes
    /// populate locals via the `BufferLocal` typed-map during
    /// `on_activate`; the App routes
    /// `&mut BufferLocals` into the registry's activation
    /// methods. M.3.2.b/c migrates existing per-variant data
    /// (`SyntaxHandle`, `Vec<Fold>`, etc.) into locals owned
    /// by their respective modes; until then this map exists
    /// to thread through the new activation API and to back
    /// `:describe-buffer`'s inspection (no entries until
    /// M.3.2.b).
    // Phase 5.B.14: `buffer_locals` moved to
    // `editor.editor.buffer_locals`.
    /// Per-buffer mode-resolved options cache (M.2.1, see
    /// `mode-architecture.md` §6.3 / §9.4 — note: the doc shows
    /// this on `Document`, but lattice-core cannot depend on
    /// lattice-config without a dep cycle, so the cache lives
    /// at the App layer keyed by `buffers::BufferId` (the App's
    /// per-buffer key, not the lower-level
    /// `lattice_protocol::BufferId`). Refreshed eagerly on mode
    /// toggle and option write per §6.3.1. Reads via type-keyed
    /// access against the cached snapshot are O(1).
    // Phase 5.B.14: `resolved_options` moved to
    // `editor.editor.resolved_options`.
    /// Buffer-local explicit overrides (`:setlocal foo=bar`)
    /// per buffer. Inputs to resolution; the resolver chains
    /// these with mode contributions before writing
    /// [`Self::resolved_options`]. Empty for buffers the user
    /// has never run `:setlocal` against.
    // Phase 5.B.14: `buffer_local_overrides` moved to
    // `editor.editor.buffer_local_overrides`.
    /// Free-form help topic registry (DESIGN.md §5.11). `:help`
    /// reads from this; built-ins are sourced from `docs/user/*.md`
    /// at build time. Plugins / future LSP integrations register
    /// additional topics through the same registry.
    // Phase 5.B.14: `help_topics` moved to
    // `editor.editor.help_topics`.
    /// UI styling knobs (DESIGN.md §5.6). Carries per-pane status
    /// line colors, the inactive-pane dim overlay, separator
    /// characters, etc. Customizable via `:set ui.*` options.
    ///
    /// Phase 5.3: the canonical state is [`Self::host_theme`]
    /// (renderer-neutral). This field is the cached ratatui-typed
    /// adapter that the TUI renderer reads on the hot path; it's
    /// rebuilt from `host_theme` on every successful
    /// `sync_theme_from_config`. The duplication is transitional;
    /// when GPUI lands and the TUI cache moves off `App`,
    /// `App.theme` collapses into `host_theme` (renamed) and each
    /// renderer maintains its own cached view.
    pub theme: crate::theme::Theme,
    // Phase 5.3: renderer-neutral canonical theme. `:set ui.*`
    // writes this; the cached TUI adapter [`Self::theme`] is
    // rebuilt from it. Future renderers (GPUI) read from this
    // field and maintain their own cached view -- the host owns
    // the canonical neutral state.
    // Phase 5.B.14: `host_theme` moved to
    // `editor.editor.host_theme`.
    // Per-frame snapshot of inactive panes' visible-window syntax
    // highlights, keyed by pane index. Refreshed by
    // [`Self::refresh_pane_highlights`] before each draw so the
    // renderer can read via `&App`. The active pane uses the live
    // [`Self::visible_highlights`] field instead.
    // Phase 5.B.12: `pane_highlights` moved to
    // `editor.editor.pane_highlights`.
    // Phase 5.B.11: `command_history`,
    // `command_history_cursor`, `command_history_pending`
    // moved to `editor.{command_history,
    // command_history_cursor, command_history_pending}`.
    // Active popup overlay's buffer id (DESIGN.md §5.11; M.4).
    // `Some(id)` while a `:describe-*` / `:apropos` / hover / etc.
    // popup is open; the actual buffer lives in
    // [`Self::buffers`] (the unified registry) with
    // `BufferFlags { listed: false, hidden: true }`. Resolve the
    // concrete handle through [`Self::popup_help`] /
    // [`Self::popup_help_mut`] -- the slot itself is just a
    // reference into the registry. Display strategy is governed
    // by [`lattice_core::ui::display::BufferDisplayCategory`];
    // callers route through the private `display_buffer` helper.
    // Phase 5.B.10: `popup_buffer` moved to
    // `editor.popup_buffer`.
    // Phase 5.B.20: `popup_back_stack` moved to
    // `editor.popup_back_stack`.
    // Phase 5.B.10: `prev_pane_for_popup` moved to
    // `editor.prev_pane_for_popup`.
    // Phase 5.B.10: `popup_placement` moved to
    // `editor.popup_placement`.
    // Phase 5.B.19: `pending_insert_completion_async_rx/token`,
    // `pending_completion_resolve_rx/token` moved to `editor.*`.
    // Phase 5.B.20: completion cluster tail moved to `editor.*`:
    // `insert_completion`, `snippet_registry`,
    // `insert_completion_snippet_meta`, `completion_accept_freq`,
    // `pending_config_structural_sections`, `per_language_completion`,
    // `completion_in_path_context`, `active_snippet`, `snippet_dirs`.
    // Active vertico-style picker (DESIGN.md §5.9.7, §5.9.10).
    // `Some` while a picker is open over a buffer / LSP instance
    // / future generator. Input routes here in
    // [`crate::input::translate`] before falling through to the
    // modal handlers; render takes precedence over completion +
    // hover popups.
    // Phase 5.B.13: `picker` moved to `editor.editor.picker`.
    // Metadata registry of every picker source the
    // `:picker <source>` ex-command can dispatch to. Populated
    // at boot with first-party source specs; feature crates
    // (LSP, snippets) add their sources through dedicated
    // `register_picker_sources` entry points. The plugin host
    // will feed WIT-imported sources into the same registry
    // (Phase 7+). See `docs/dev/architecture/picker.md`.
    //
    // Held as `Arc<...>` so the `gen:picker-sources` completion
    // generator can capture a `Weak<PickerRegistry>` and walk
    // the source list on every keystroke without keeping the
    // registry alive past the App. Mirror of the
    // `Arc<ModeRegistry>` pattern used by `gen:modes`.
    // Phase 5.B.13: `picker_registry` moved to
    // `editor.editor.picker_registry`.
    // Picker MRU index. Loaded from
    // `$XDG_CACHE_HOME/lattice/picker-mru.bincode` at boot
    // (best-effort -- corruption / version-mismatch silently
    // discards and starts fresh per `docs/dev/architecture/picker.md`
    // § 9.3). `open_picker` reads via `frecency_bonus` on
    // each candidate; `do_picker_accept` records on the
    // chosen row and best-effort persists. Single-threaded
    // host today; if plugin sources ever need shared access
    // this becomes `Arc<RwLock<...>>` -- the trait surface
    // already supports that move.
    // Phase 5.B.13: `picker_mru` moved to
    // `editor.editor.picker_mru`.
    // Resolved persistence path for the MRU cache.
    // `Some(path)` when `dirs::cache_dir()` returned a usable
    // path at boot; `None` disables persistence (in-memory
    // only -- sandboxed runs, headless test fixtures).
    // Phase 5.B.13: `picker_mru_path` moved to
    // `editor.editor.picker_mru_path`.
    // `Some` while an async picker source's `init` future is
    // in-flight. Holds the spawned-task channel handle + the
    // generator + the source id; the main loop's
    // `drain_pending_picker_init` pumps the channel and seats
    // the picker once results arrive.
    //
    // A second `:picker <source>` invocation while one is
    // pending cancels the predecessor (`cancel.cancel()`) and
    // replaces this slot -- vim-style "do what I last said."
    // Phase 5.B.13: `pending_picker_init` moved to
    // `editor.editor.pending_picker_init`.
    // `Some` while a live picker is open
    // ([`PickerSourceSpec::live`] == true). Holds the
    // generator + debounce deadline + any in-flight
    // `on_query_changed` task. The main loop's
    // `drain_pending_live_picker_query` fires the source's
    // re-fetch when the debounce expires and seats the new
    // batch when the future resolves.
    // Phase 5.B.13: `live_picker_query` moved to
    // `editor.editor.live_picker_query`.
    // PI.5: the `previewing` flag is gone — picker preview is now an
    // isolated projection (`editor.editor.preview_overrides`) that never
    // activates a buffer, so no activate-path gating flag is needed.
    // Receiver for [`lattice_lsp::LspLogPushed`] events (Phase
    // 4; M.5.3.b moved the event type from `lattice-protocol`'s
    // central enum to `lattice-lsp::events`). Drained once per
    // main-loop tick by [`Self::drain_lsp_log_events`];
    // matching log buffers in `BufferRegistry` are rebuilt from
    // the logger snapshot so `*lsp*` / `*lsp:<server>*` /
    // `*lsp:<server>:trace*` views update live without the
    // user having to reopen them.
    // 5.B.18b: `lsp_log_event_rx`, `lsp_progress_event_rx`
    // moved to `editor.{lsp_log_event_rx,
    // lsp_progress_event_rx}`.
    // Phase 5.B.19: `pending_lsp_detach_rx`, `pending_mode_lifecycle_rx`,
    // `pending_inlay_hint_refresh_rx`, `pending_semantic_tokens_refresh_rx`
    // moved to `editor.*`.
    // Accumulated `$/progress` state keyed by
    // (server_id, token). `Begin` inserts; `Report` updates;
    // `End` removes. The modeline picks the most recent
    // active entry to surface.
    // Phase 5.B.17: `lsp_progress` moved to
    // `editor.lsp_progress`.
    // 4.4.e: cached `textDocument/selectionRange` chain for
    // the smart-expansion operator. Index 0 is the innermost
    // range (closest to the cursor); each subsequent entry is
    // one `parent` step outward. `cursor` and `buffer` are the
    // anchor that captured this chain; we invalidate the cache
    // when the cursor moves outside the innermost range or
    // the active buffer changes.
    // Phase 5.B.17: `lsp_selection_chain` moved to
    // `editor.lsp_selection_chain`.
    // 4.4.e: current step inside `lsp_selection_chain.ranges`.
    // `0` = innermost; `chain.ranges.len() - 1` = outermost.
    // Phase 5.B.17: `lsp_selection_chain_index` moved to
    // `editor.lsp_selection_chain_index`.
    // Phase 5.B.19: `pending_selection_range_rx/token` moved to `editor.*`.
    // 4.4.e: cached `textDocument/documentHighlight` for the
    // active buffer + symbol position. Refreshed by the
    // per-tick pump when the cursor moves to a different
    // (line, byte). Renderer reads this to paint the soft
    // overlay across same-symbol occurrences.
    // Phase 5.B.17: `lsp_document_highlights` moved to
    // `editor.lsp_document_highlights`.
    // 4.4.e: cursor position at which the most recent
    // `documentHighlight` request was issued. Used by the
    // pump to decide whether to re-issue (cursor moved) vs.
    // reuse the cache. Distinct from `cache.cursor` because
    // the in-flight request may not have landed yet.
    // Phase 5.B.17: `last_document_highlight_issue_cursor`
    // moved to
    // `editor.last_document_highlight_issue_cursor`.
    // Phase 5.B.19: `pending_document_highlight_token/rx` moved to `editor.*`.
    // 4.4.f: per-buffer cache of the last `textDocument/foldingRange`
    // response. Keyed by `BufferId` because the foldmethod is a
    // per-buffer setting; multiple open buffers can each track
    // their own LSP fold list. Invalidated by the pump when
    // the document version bumps.
    // Phase 5.B.17: `lsp_folds_cache` moved to
    // `editor.lsp_folds_cache`.
    // Phase 5.B.19: `pending_folding_range_token/rx` moved to `editor.*`.
    // 4.4.g: per-buffer `inlayHint` cache. Refilled by the
    // per-tick pump when the document version changes; the
    // renderer overlay splices each hint as virtual text.
    // Phase 5.B.17: `lsp_inlay_hints_cache` moved to
    // `editor.lsp_inlay_hints_cache`.
    // 4.5.c: per-buffer `documentLink` cache. Refilled by
    // the per-tick pump on document-version change; consumed
    // by `gx` (Normal-mode keystroke) -- the first link whose
    // range covers the cursor wins. The renderer overlay
    // (underline link ranges) is queued; today the cache only
    // drives navigation, not visuals.
    // Phase 5.B.17: `lsp_document_links_cache` moved to
    // `editor.lsp_document_links_cache`.
    // Phase 5.B.19: `pending_document_links_token/rx` moved to `editor.*`.
    // 4.5.d: per-buffer code-lens cache. Refilled by the
    // per-tick pump on document-version change; consumed by
    // `:lsp-code-lens` (opens a picker over the cached
    // lenses). Cleared via `workspace/codeLens/refresh` so
    // servers that recompute lenses out-of-band (test runs,
    // debug session start) can force a refetch.
    // Phase 5.B.17: `lsp_code_lens_cache` moved to
    // `editor.lsp_code_lens_cache`.
    // Phase 5.B.19: `pending_code_lens_{token,rx,refresh_rx,items,server}`,
    // `pending_document_color_{token,rx}`, `pending_color_{presentations,range}`,
    // `pending_inlay_hint_{token,rx}` moved to `editor.*`.
    // 4.4.h: per-buffer semantic-tokens cache. Refilled when
    // the document version changes; the renderer overlay
    // repaints span ranges that fall under a token with a
    // kind-driven style.
    // Phase 5.B.17: `lsp_semantic_tokens_cache` moved to
    // `editor.lsp_semantic_tokens_cache`.
    // Phase 5.B.19: `pending_semantic_tokens_{token,rx}` moved to `editor.*`.
    // 4.4.j: per-buffer pull-diagnostics cache. Keys the
    // last `result_id` the server issued so the next pull
    // can be answered as `Unchanged` cheaply. The pump
    // re-issues on document-version change OR cache miss
    // (e.g. after `workspace/diagnostic/refresh` evicts).
    // Phase 5.B.17: `lsp_pull_diagnostics_cache` moved to
    // `editor.lsp_pull_diagnostics_cache`.
    // Phase 5.B.19: `pending_pull_diagnostics_{token,rx}`,
    // `pending_diagnostic_refresh_rx` moved to `editor.*`.
    // 4.4.f: stash for `lsp-folding-mode` activation moved
    // into `BufferLocals` (owned by the mode via the
    // `PriorFoldmethod` typed local in
    // `lattice_lsp::folding_sync`). Modes own their own
    // lifecycle state; the App is just the orchestrator.
    // `completion.auto_insert_single` lives on the typed-options
    // registry (`self.editor.config` type-keyed by
    // `lattice_config::CompletionAutoInsertSingle`). Read via
    // [`Self::completion_auto_insert_single`].
    // Phase 5.B.11: `auto_submit_after_chord` moved to
    // `editor.editor.auto_submit_after_chord`.
    // LSP subsystem handle (DESIGN.md §5.4, Phase 4.1.h +
    // audit slice 1). Reads (`servers_for`, `running_actors`,
    // `configs`, ...) are wait-free against an
    // `ArcSwap<SupervisorSnapshot>`; writes (`open_buffer`,
    // `attach_handle`, `close_buffer`, `flush*`, `shutdown`)
    // route through the supervisor task's mailbox. The UI
    // thread can call any read on the keystroke / render path
    // without ever blocking, and the previous
    // `Arc<tokio::sync::Mutex<LspSupervisor>>` -- which
    // silently dropped work via `try_lock` whenever an async
    // `:e <path>` held the mutex across the LSP `initialize`
    // handshake -- is gone.
    // 5.B.18b: `lsp`, `lsp_diagnostics`, `lsp_logger`
    // moved to `editor.{lsp, lsp_diagnostics, lsp_logger}`.
    // 5.8.AA.o: `lsp_file_watcher` moved to `editor.lsp_file_watcher`
    // so the GPUI peer reaches the same watcher path via
    // `Editor::refresh_lsp_file_watcher` + `drain_lsp_fs_events`
    // (called from `run_tick_pending`).
    // 5.B.18b: `pending_apply_edit_rx`,
    // `pending_show_message_request_rx` moved to
    // `editor.{pending_apply_edit_rx, pending_show_message_request_rx}`.
    // BC.8b/BC.8c: `pending_configuration_rx` + `pending_show_document_rx`
    // are gone entirely — those buses are now the generic `InboundBus`,
    // drained per-tick through mode-owned handlers (`boot.inbound`).
    // 5.B.18b: `lsp_pending_show_message_requests` moved to
    // `editor.lsp_pending_show_message_requests`.
    // 5.B.18b: `lsp_show_message_request_queue`,
    // `lsp_next_show_message_request_id` moved to
    // `editor.{lsp_show_message_request_queue,
    // lsp_next_show_message_request_id}`.
    // 5.B.18b: `lsp_config_tree` moved to
    // `editor.lsp_config_tree`.
    // 5.B.18b: `buffer_uris` moved to `editor.buffer_uris`.
}

/// One open completion popup (DESIGN.md §5.11.3 vertico-style
/// rendering). Built by `Action::CommandLineCompleteOrAdvance`
/// when the user presses Tab; consumed by accept / dismiss / scroll
/// actions.
// `Fold` + `FoldMethod` moved to `lattice_core::folding` for
// renderer-agnostic ownership. Both re-exported through
// `lattice_core`'s crate root + this re-export so existing
// `crate::app::Fold` / `crate::app::FoldMethod` call sites
// keep resolving unchanged.
pub use lattice_core::{Fold, FoldMethod};

/// CSM.8b: `LspCompletionMeta` + `LSP_COMPLETION_KIND_ID`
/// moved into `lattice-lsp::completion` so the type lives in
/// the crate that owns lsp-types. The host imports them via
/// this re-export -- candidate payloads carry the serde-
/// encoded form directly (`encode_meta` / `decode_meta`) so
/// the parallel `App.insert_completion_lsp_meta` sidecar is
/// gone; the candidate IS the metadata.
pub use lattice_lsp::completion::{
    LSP_COMPLETION_KIND_ID, LspCompletionMeta, decode_meta, encode_meta,
};
/// `Extension::kind_id` discriminant for snippet-sourced
/// candidates (Phase 4.2.g.4). Sidecar metadata lives in
/// `App.insert_completion_snippet_meta`.
pub const SNIPPET_COMPLETION_KIND_ID: u32 = 2;

/// Sidecar metadata for snippet candidates in the popup. The
/// host renders the snippet body on accept and starts an
/// `ActiveSnippet`; this struct carries the parsed body +
/// the display fields the popup row uses.
///
/// Phase 5.B.20: definition moved to
/// [`lattice_host::state::SnippetCandidateMeta`] alongside the
/// `editor.insert_completion_snippet_meta` field that owns it.
/// Re-exported here so existing callers keep compiling.
pub use lattice_host::state::SnippetCandidateMeta;

// Phase 5.2: OptionCache, LastFind, MacroRecording, TagStackEntry,
// PositionEntry, PositionSource, ReplaceEntry, LastVisual,
// SubstitutePreview, PendingBlockInsert moved to lattice_host::state.
pub use lattice_host::state::{
    LastFind, LastVisual, MacroRecording, OptionCache, PendingBlockInsert, PositionEntry,
    PositionSource, ReplaceEntry, SubstitutePreview, TagStackEntry,
};

impl std::fmt::Debug for App {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Slice 3c.final.E.5e: Debug reads route through RS
        // accessors + `read_editor` so post-swap the Editor lives
        // off-thread. `last_message` is cloned (`EchoMessage: Clone`).
        let ad = self.ad();
        let rs = self.render_state.load();
        // Slice 3c.final.X.cleanup: read from the published
        // `MessagesRenderState.last` (slice B.7) instead of routing
        // through the actor mailbox just to print Debug output.
        let last_message = self.messages().last.as_deref().cloned();
        f.debug_struct("App")
            .field("cursor", &self.cursor())
            .field("scroll", &ad.scroll)
            .field("should_quit", &rs.lifecycle.should_quit)
            .field("viewport_height", &ad.viewport_height)
            .field("modal", &ad.modal)
            .field("command_line", &self.command_line())
            .field("last_message", &last_message)
            .field("dirty", &ad.snapshot.dirty)
            .finish()
    }
}

impl App {
    /// Phase 5.8.AF.5 / Slice 3c.2: wait-free snapshot of the
    /// active-buffer hot-path render state. Returns an `Arc`
    /// clone of `RenderState.active_document`. Used by renderer
    /// code that today reads `app.editor.cursor` / `.scroll` /
    /// `.modal` / etc. -- those reads migrate to
    /// `app.ad().cursor` (etc.) during 3c.2 / 3c.3. After 3c.5
    /// severs the `Arc<Editor>` reference, the method body
    /// flips to read from a renderer-owned `render_state`
    /// field; call sites stay unchanged.
    pub fn ad(&self) -> std::sync::Arc<lattice_host::render_state::ActiveDocumentRenderState> {
        // Per-frame pin: when the renderer has pinned a snapshot
        // (between pin/unpin calls), return it so all ad() call
        // sites within one frame draw see the same cursor, scroll,
        // options, and modal state — regardless of intermediate
        // actor publications. Without the pin, each independent
        // ad() loads a fresh Arc from the shared ArcSwap and can
        // observe a different snapshot, causing the cursorline
        // highlight and cursor blink position to disagree.
        if let Some(pinned) = self.frame_ad.lock().unwrap().as_ref() {
            return pinned.clone();
        }
        // Fall through to the live ArcSwap when no pin is active
        // (e.g. during non-render reads).
        self.render_state.load().active_document.load_full()
    }

    /// Pin the current `ActiveDocumentRenderState` snapshot so every
    /// [`ad()`](Self::ad) call until [`unpin_render_state`](Self::unpin_render_state)
    /// returns the same `Arc`. Call at the start of each frame render
    /// (before `terminal.draw()` in the TUI, before the GPUI render).
    pub fn pin_render_state(&self) {
        let snap = self.render_state.load().active_document.load_full();
        *self.frame_ad.lock().unwrap() = Some(snap);
    }

    /// Release the per-frame pin so the next [`ad()`](Self::ad) call
    /// loads a fresh snapshot from the actor. Call after each frame
    /// render completes.
    pub fn unpin_render_state(&self) {
        *self.frame_ad.lock().unwrap() = None;
    }

    /// Phase 5.8.AF.5 / Slice 3c.final.B (group 1): wait-free
    /// snapshot of the pane-tree sub-state. Renderer code reads
    /// `app.panes().tree.X()` instead of `app.editor.pane_tree.X()`.
    /// Body matches `ad()` — one Arc clone off the same
    /// `Arc<ArcSwap<RenderState>>` cell.
    pub fn panes(&self) -> std::sync::Arc<lattice_host::render_state::PanesRenderState> {
        self.render_state.load().panes.clone()
    }

    /// Phase 5.8.AF.5 / Slice 3c.final.B (group 1): wait-free
    /// snapshot of the buffer-registry sub-state. Renderer code
    /// reads `app.buffers().registry.X()` and
    /// `app.buffers().uris.get(&id)` instead of reaching through
    /// `app.editor.buffers.X()` / `app.editor.buffer_uris.get(...)`.
    pub fn buffers(&self) -> std::sync::Arc<lattice_host::render_state::BuffersRenderState> {
        self.render_state.load().buffers.clone()
    }

    /// Phase 5.8.AF.5 / Slice 3c.final.B (group 3): wait-free
    /// snapshot of the picker sub-state. Renderer code reads
    /// `app.picker_state().state.as_deref()` instead of
    /// `app.editor.picker.as_ref()`. Named to avoid colliding with
    /// the legacy `app.editor.picker` field name.
    pub fn picker_state(&self) -> std::sync::Arc<lattice_host::render_state::PickerRenderState> {
        self.render_state.load().picker.clone()
    }

    /// Phase 5.8.AF.5 / Slice 3c.final.B (group 3): wait-free
    /// snapshot of the completion sub-state. Carries both the
    /// in-buffer ghost popup (`insert`) and the cmdline
    /// completion popup (`state`).
    pub fn completion(&self) -> std::sync::Arc<lattice_host::render_state::CompletionRenderState> {
        self.render_state.load().completion.clone()
    }

    /// Phase 5.8.AF.5 / Slice 3c.final.B (group 3): wait-free
    /// snapshot of the popup sub-state. Renderer code reads
    /// `app.popup().is_open()` / `.placement` / `.buffer_id`
    /// instead of `app.editor.popup_buffer.is_some()` etc.
    pub fn popup(&self) -> std::sync::Arc<lattice_host::render_state::PopupRenderState> {
        self.render_state.load().popup.clone()
    }

    /// WK.12: the minibuffer band's published sub-state. Separate from
    /// [`Self::popup`] because both can be open at once — that independence is
    /// the point of the band.
    pub fn band(&self) -> std::sync::Arc<lattice_host::render_state::PopupRenderState> {
        self.render_state.load().band.clone()
    }

    /// Slice 3c.final.B.7: published echo-area state. Replaces
    /// `read_editor(|e| e.last_message.clone())` in render.rs.
    pub fn messages(&self) -> std::sync::Arc<lattice_host::render_state::MessagesRenderState> {
        self.render_state.load().messages.clone()
    }

    /// Slice 3c.final.B.7: published modeline + cmdline + search
    /// state. Replaces the per-frame `read_editor` calls for
    /// `command_line`, `auto_submit_after_chord`, `search_line`.
    pub fn modeline(&self) -> std::sync::Arc<lattice_host::render_state::ModelineRenderState> {
        self.render_state.load().modeline.clone()
    }

    /// Slice 3c.final.B.10: published typed-options registry.
    /// Replaces `read_editor(|e| e.config.get_typed::<X>())` —
    /// caller does `app.options().config.get_typed::<X>()`.
    pub fn options(&self) -> std::sync::Arc<lattice_host::render_state::OptionsRenderState> {
        self.render_state.load().options.clone()
    }

    /// Slice 3c.final.B.11: published active-modes map.
    /// `app.modes().map.get(&buf)` replaces
    /// `read_editor(|e| e.active_modes.get(&buf).cloned())`.
    pub fn modes(&self) -> std::sync::Arc<lattice_host::render_state::ModesRenderState> {
        self.render_state.load().modes.clone()
    }

    /// Slice 3c.final.B.9: published buffer-locals map.
    /// `app.buffer_locals().map.get(&buf).and_then(|l| l.get::<T>())`
    /// replaces the equivalent `read_editor` chain.
    pub fn buffer_locals(
        &self,
    ) -> std::sync::Arc<lattice_host::render_state::BufferLocalsRenderState> {
        self.render_state.load().buffer_locals.clone()
    }

    /// Phase 5.8.AF.5 / Slice 3c.final.E.2: routing helper for
    /// editor mutations. Pre-swap: runs `f` against the in-process
    /// `Editor` and publishes RenderState. Post-swap (when Editor
    /// moves to the actor thread): the body delegates to
    /// `self.editor_actor.mutate_blocking(Box::new(f))`. The
    /// `Send + 'static` bounds are forward-compatible — every
    /// caller already passes a closure that satisfies them today,
    /// so the swap is a one-line change in this method's body.
    /// Used to migrate `self.editor.X(args)` method call sites
    /// across the renderer App.
    pub fn mutate_editor<F>(&mut self, f: F)
    where
        F: FnOnce(&mut lattice_host::editor::Editor) + Send + 'static,
    {
        crate::actor_call_counter::bump();
        #[cfg(not(test))]
        {
            self.editor_actor
                .mutate_blocking(Box::new(f))
                .expect("editor actor alive");
        }
        #[cfg(test)]
        {
            f(&mut self.editor);
            self.editor.publish_render_state();
        }
    }

    /// 2026-05-27: per-pane geometry hand-off. Mirrors the GPUI
    /// peer's `set_pane_viewport`. The host writes onto
    /// `PaneState[idx]`; for terminal-kind panes the
    /// `SetPaneViewport` handler also resizes alacritty + PTY so
    /// the shell wraps its output to the new column count.
    /// Without this, TUI terminal panes never reflowed on split /
    /// resize and content overflowed past the visible area.
    pub fn set_pane_viewport(&mut self, idx: usize, rows: u32, cols: u32) {
        #[cfg(not(test))]
        {
            let _ = self.editor_actor.set_pane_viewport(idx, rows, cols);
        }
        #[cfg(test)]
        {
            let active_idx = self.editor.pane_tree.active_index();
            let leaves = self.editor.pane_tree.leaves_mut();
            if idx < leaves.len() {
                leaves[idx].viewport_height = rows.max(1);
                leaves[idx].viewport_width = cols.max(1);
            }
            if idx == active_idx {
                self.editor.viewport_height = rows.max(1);
                self.editor.ensure_cursor_visible();
            }
            self.editor.publish_render_state();
        }
    }

    /// PU.1b-3: floating-popup geometry hand-off. The renderer is the
    /// single authority on the popup's inner rect (it computes it from
    /// the buffer area + `popup_outer_size` + placement), so it pushes
    /// the resolved inner `(rows, cols)` to the host each frame —
    /// exactly mirroring [`Self::set_pane_viewport`] for real panes.
    /// `build_cells_panes` reads `popup_viewport_{height,width}` to size
    /// the synthetic popup-pane `DisplayMatrix`. Diff-then-send in the
    /// runtime loop keeps steady-state cost at zero.
    pub fn set_popup_viewport(&mut self, rows: u32, cols: u32) {
        self.mutate_editor(move |e| {
            e.popup_viewport_height = rows.max(1);
            e.popup_viewport_width = cols.max(1);
        });
    }

    /// WK.12: the band's inner-geometry hand-off, the peer of
    /// [`Self::set_popup_viewport`] for `PaneId::MINIBUFFER_BAND`. Without it
    /// `build_cells_panes` never sizes the band's matrix and the band paints
    /// nothing.
    pub fn set_band_viewport(&mut self, rows: u32, cols: u32) {
        self.mutate_editor(move |e| {
            e.band_viewport_height = rows.max(1);
            e.band_viewport_width = cols.max(1);
        });
    }

    /// PU.5c: completion-docs side-popup inner-geometry hand-off — the peer
    /// of [`Self::set_popup_viewport`] for the second synthetic popup
    /// (`PaneId::COMPLETION_DOCS`). `build_cells_panes` reads
    /// `Editor::completion_docs_viewport_{height,width}` to size the docs
    /// `DisplayMatrix`. Diff-then-send in the runtime loop keeps churn down.
    pub fn set_completion_docs_viewport(&mut self, rows: u32, cols: u32) {
        self.mutate_editor(move |e| {
            e.completion_docs_viewport_height = rows.max(1);
            e.completion_docs_viewport_width = cols.max(1);
        });
    }

    /// Variant of [`Self::mutate_editor`] for closures that
    /// return a value (typically `Vec<RendererSignal>` from
    /// host helpers). Same routing contract.
    pub fn mutate_editor_with<F, R>(&mut self, f: F) -> R
    where
        F: FnOnce(&mut lattice_host::editor::Editor) -> R + Send + 'static,
        R: Send + 'static,
    {
        crate::actor_call_counter::bump();
        #[cfg(not(test))]
        {
            self.editor_actor.mutate_blocking_with(f)
        }
        #[cfg(test)]
        {
            let r = f(&mut self.editor);
            self.editor.publish_render_state();
            r
        }
    }

    /// Slice 3c.final.E.swap: read-side helper for `&self`
    /// methods that need to query editor state without mutating.
    /// In production it routes through the actor handle's
    /// `with_editor` blocking RPC; in tests it calls the closure
    /// directly against the in-process Editor.
    pub fn read_editor<F, R>(&self, f: F) -> R
    where
        F: FnOnce(&lattice_host::editor::Editor) -> R + Send + 'static,
        R: Send + 'static,
    {
        crate::actor_call_counter::bump();
        #[cfg(not(test))]
        {
            self.editor_actor.with_editor(f)
        }
        #[cfg(test)]
        {
            f(&self.editor)
        }
    }

    /// Slice 3c.final.E.5d: hot-field accessor for the active
    /// document's cursor. Earns its place by call-site frequency
    /// (rule of three: cursor has 8+ reader sites across
    /// `dispatch`, `help`, `search`, `lsp`, the Debug impl). Post-
    /// swap routes through `editor_actor.with_editor(|e| e.cursor)`
    /// in one place instead of N. `Position` is `Copy` so this is
    /// a value return, not an Arc clone.
    pub(crate) fn cursor(&self) -> lattice_protocol::position::Position {
        // Slice 3c.final.X.cleanup: published on `ad().cursor` —
        // wait-free Arc-bump read. Cursor changes always publish RS
        // via the dispatch tail; per-keystroke readers (motions,
        // edit, status redraw) now skip the actor mailbox.
        //
        // cfg(test) escape hatch reads from `self.editor.cursor`
        // directly so tests that mutate `editor.cursor.X = Y`
        // without `publish_render_state()` keep working. Production
        // always goes through RS; tests preserve the "direct
        // mutation is immediately visible" convention.
        #[cfg(test)]
        {
            self.editor.cursor
        }
        #[cfg(not(test))]
        {
            self.ad().cursor
        }
    }

    /// Companion writer. Routes through `mutate_editor` so the
    /// post-swap landing is a no-touch on call sites.
    pub(crate) fn set_cursor(&mut self, pos: lattice_protocol::position::Position) {
        self.mutate_editor(move |e| e.cursor = pos);
    }

    /// Slice 3c.final.E.5d: hot-field accessor for the active
    /// document's buffer id. 5+ real reader sites across `lsp`,
    /// `boot`, `lifecycle`. `BufferId` is `Copy`.
    pub(crate) fn document_buffer_id(&self) -> crate::buffers::BufferId {
        // Slice 3c.final.X.cleanup: `BufferId` is `Copy` and mirrored
        // on `ad().document_buffer_id`. cfg(test) escape hatch as
        // per `cursor()` — see its docstring.
        #[cfg(test)]
        {
            self.editor.document_buffer_id
        }
        #[cfg(not(test))]
        {
            self.ad().document_buffer_id
        }
    }

    /// Slice 3c.final.E.5d: hot-field accessor for the `:` line
    /// command-buffer text. 5 reader sites across `cmdline`,
    /// `search`, the Debug impl. Returns by value — `String`
    /// clone — so the closure body is `Send + 'static`.
    pub(crate) fn command_line(&self) -> String {
        // Slice 3c.final.X.cleanup: read from the published
        // `ModelineRenderState.cmdline_text` (slice B.7). The Arc<str>
        // → String conversion is one heap copy, matching the prior
        // `e.command_line().clone()` cost without the mailbox RPC.
        // cfg(test) escape hatch as per `cursor()` — see its docstring.
        #[cfg(test)]
        {
            self.editor.command_line().clone()
        }
        #[cfg(not(test))]
        {
            self.modeline().cmdline_text.to_string()
        }
    }

    /// MB.2: whether the `:` line is expanded into the tier-2 band. Read
    /// from the published modeline state (wait-free), test escape hatch as
    /// per [`Self::command_line`].
    pub(crate) fn command_line_expanded(&self) -> bool {
        #[cfg(test)]
        {
            self.editor.command_line_expanded()
        }
        #[cfg(not(test))]
        {
            self.modeline().cmdline_expanded
        }
    }

    /// MB.2e: the resolved `command-line.expand-height` policy sizing the
    /// expanded band. Read from the published modeline state (wait-free);
    /// test escape hatch reads the editor directly, as [`Self::command_line_expanded`].
    pub(crate) fn command_line_expand_height(&self) -> lattice_config::ExpandHeight {
        #[cfg(test)]
        {
            self.editor.command_line_expand_height()
        }
        #[cfg(not(test))]
        {
            self.modeline().cmdline_expand_height
        }
    }

    /// MB.2: the full (possibly multi-line) `:` line text for the expanded
    /// band renderer. Empty in tier 1.
    pub(crate) fn command_line_full_text(&self) -> String {
        #[cfg(test)]
        {
            self.editor.command_line_full_text()
        }
        #[cfg(not(test))]
        {
            self.modeline().cmdline_full_text.to_string()
        }
    }

    /// Slice 3c.final.E.5e: ExCommandRegistry accessor. Backed by
    /// `Arc<CommandRegistry>` on the host so the clone is one Arc
    /// bump, not a deep copy. 6+ sites across `cmdline` and
    /// `dispatch` need a `&CommandRegistry` for parser /
    /// completion-slot lookups; callers do
    /// `let reg = self.registry(); ... &reg ...` to keep the Arc
    /// alive across the borrow.
    pub(crate) fn registry(&self) -> std::sync::Arc<lattice_grammar::CommandRegistry> {
        // B3b: `load_full` yields an owned snapshot of the current registry
        // (the field is now an `ArcSwap` handle) so callers keep receiving a
        // plain `Arc<CommandRegistry>` and see runtime plugin registrations.
        self.read_editor(|e| e.registry.load_full())
    }

    /// Thin renderer-side wrapper around
    /// [`lattice_host::editor::Editor::set_message`].
    ///
    /// 5.5.D moved the implementation into the host so renderer and
    /// non-renderer call sites share one code path. Existing
    /// `app.set_message(...)` call sites in tests / boot keep working
    /// without churn; the body just routes through `mutate_editor`.
    /// The host-side impl preserves the legacy two-step contract:
    /// write to the echo-area slot + push to the bounded `*messages*`
    /// ring + emit a typed [`lattice_runtime::MessagePushed`] event
    /// so per-App isolation (one bus + ring per App) survives the
    /// move.
    pub fn set_message(&mut self, level: EchoLevel, text: impl Into<String>) {
        // Slice 3c.final.E.5i: materialize the `impl Into<String>`
        // conversion eagerly outside the closure so the captured
        // value is `Send + 'static`. Earlier E.5c attempt left this
        // on direct `self.editor.X` because the trait bound on the
        // impl arg isn't carried into the closure; the eager
        // `.into()` sidesteps that.
        let text: String = text.into();
        self.mutate_editor(move |e| e.set_message(level, text));
    }
}

pub(crate) fn line_byte_len(buf: &Buffer, line: u32) -> u32 {
    // §8.2 hot path: use ropey's O(log n) line API instead of
    // materialising the whole buffer.
    buf.line_byte_len(line)
}

/// The last line a motion or range may address — content space.
///
/// CV.3: the third of three hand-rolled copies of this correction,
/// all now sitting on `Buffer::content_line_count`.
pub(crate) fn last_addressable_line(buf: &Buffer) -> u32 {
    buf.content_line_count().saturating_sub(1)
}

pub(super) fn is_valid_mark_name(c: char) -> bool {
    c.is_ascii_alphabetic() || c.is_ascii_digit()
}

// 5.5.E.2: `preview_register` moved to
// [`lattice_host::dispatch::preview_register`] alongside its
// primary caller [`Editor::do_list_registers`]. The picker source
// import sites now route through the host crate directly.

pub(super) fn is_word_char_byte(b: u8) -> bool {
    b.is_ascii_alphanumeric() || b == b'_'
}

// 5.5.G.23.insert-prep: body migrated to
// [`lattice_host::dispatch::dedup_rendered_by_text`]. Re-exported at
// the App-side super scope so 4 existing call sites
// (`completion.rs` x2, `lsp.rs` x1, in-file test x1) continue
// working unchanged.
pub(super) use lattice_host::dispatch::dedup_rendered_by_text;

/// True for bytes the path-completion source treats as part of
/// a filename / directory component. Wider than `is_word_char_byte`
/// so common filename characters (`.`, `-`, `~`) ride the same
/// segment; the trigger anchor breaks at `/` (dir boundary)
/// rather than at these characters.
pub(super) fn is_path_byte(b: u8) -> bool {
    b.is_ascii_alphanumeric() || matches!(b, b'_' | b'-' | b'.' | b'~' | b'+' | b'@')
}

/// Expand `~/...` against `$HOME` and absolutise a relative
/// path against the process's current working directory.
///
/// Two failure modes this closes:
///
/// 1. `:e ~/foo.rs` -- without expansion, `Document::open`
///    forwards the literal `~` to `read_to_string` and fails
///    ENOENT. Cmdline completion (`gen:files`) already does
///    its own tilde expansion for `read_dir`, which is why
///    completion appears to work but submit fails.
///
/// 2. Oil opened at a single-component relative path (`src`,
///    `foo.rs`, `.`) navigating up. `Path::parent()` returns
///    `Some("")` for those, and `read_dir("")` is ENOENT.
///    Normalising before storing keeps `OilDir` absolute, so
///    `parent()` walks the filesystem correctly.
///
/// We deliberately do not call `canonicalize` -- it requires
/// the target to exist (`:e new.rs` against an unsaved path
/// has to work) and would surprise users by resolving symlinks
/// vim treats as opaque. Cwd-failure or HOME-missing falls
/// through to the input verbatim; the caller's open then
/// produces the same error it would have produced without
/// the normalise step.
/// 5.8.AA.j: migrated to `lattice_host::dispatch::normalize_user_path`.
/// Wrapper retained so the existing call sites in this peer keep
/// resolving via `crate::app::normalize_user_path`.
pub(super) fn normalize_user_path(path: &std::path::Path) -> std::path::PathBuf {
    lattice_host::dispatch::normalize_user_path(path)
}

// 5.5.G.23: `is_blank_line` migrated to
// `lattice_host::dispatch` (private helper colocated with
// `Editor::snap_cursor_past_closed_folds`). Zero remaining App
// callers after `snap_cursor_past_closed_folds` and `fold_start_at`
// retire to delegators.

/// Phase 4.2 features (hover, definition, references, completion)
/// all need this; later we'll thread the per-server negotiated
/// `PositionEncodingKind` through here so utf-8 / utf-32 servers
/// don't pay the utf-16 conversion. For 4.2.b utf-16 is correct
/// for every server we care about today.
/// Render an LSP `SignatureHelp` response into a markdown body
// 5.5.LSP.4: `signature_help_to_markdown` relocated to
// `lattice_host::lsp_helpers`. No production App-side caller
// remains; tests still exercise it through `super::*`, so the
// re-export stays under `cfg(test)`.
#[cfg(test)]
pub(crate) use lattice_host::lsp_helpers::signature_help_to_markdown;

/// Inverse of `app_to_lsp_position` -- LSP utf-16 character
/// column → utf-8 byte column on the given line. Used by
/// `apply_lsp_text_edits` to convert TextEdit ranges back to
/// the App's `Position` shape.
pub(crate) fn lsp_position_to_app_byte(buffer: &Buffer, line: u32, character: u32) -> u32 {
    let line_text = buffer.line(line).unwrap_or_default();
    lattice_lsp::position::utf16_column_to_utf8_byte(&line_text, character)
}

/// 4.4.e: does the App `(line, byte)` cursor sit inside the
/// half-open LSP `range`? We compare only by (line, character)
/// in LSP utf-16 space because the range itself is LSP-shape;
/// the App cursor is converted on the fly.
pub(crate) fn cursor_inside_range(cursor: Position, range: &lattice_lsp::lsp_types::Range) -> bool {
    let line = cursor.line;
    let col = cursor.byte;
    let start = (range.start.line, range.start.character);
    let end = (range.end.line, range.end.character);
    let here = (line, col);
    here >= start && here < end
}

/// 4.4.f: convert an LSP `FoldingRange` to our `Fold`. LSP
/// returns line-based extents; the identity hash combines
/// start_line + end_line + kind so closed-state survives
/// re-fetches that produce the same logical fold.
pub(crate) fn folding_range_to_fold(r: lattice_lsp::lsp_types::FoldingRange) -> Fold {
    use std::hash::{Hash, Hasher};
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    r.start_line.hash(&mut hasher);
    r.end_line.hash(&mut hasher);
    // Spec omits a stable u32 for `kind`; hash the string form
    // when present so a fold's kind change still re-keys.
    if let Some(kind) = r.kind.as_ref() {
        std::mem::discriminant(kind).hash(&mut hasher);
    }
    Fold {
        start_line: r.start_line,
        end_line: r.end_line,
        closed: false,
        identity: Some(hasher.finish()),
    }
}

/// 4.4.e: flatten an LSP `SelectionRange` (linked list via
/// `parent`) into a `Vec<Range>` ordered innermost-first.
pub(crate) fn flatten_selection_range_chain(
    head: &lattice_lsp::lsp_types::SelectionRange,
) -> Vec<lattice_lsp::lsp_types::Range> {
    let mut out = Vec::new();
    let mut cur = Some(head);
    while let Some(node) = cur {
        out.push(node.range);
        cur = node.parent.as_deref();
    }
    out
}

// 5.5.LSP.1 step 2: `app_to_lsp_position` and
// `hover_contents_to_markdown` (below) relocated to
// `lattice_host::lsp_helpers`. Re-exported under their original
// `crate::app::*` paths so the ~21 existing call sites continue
// to compile unchanged through the rest of the LSP cluster
// migration. Once every App-side LSP request helper has migrated
// host-side (LSP.5), the re-exports can be retired in a follow-
// up sweep alongside the helpers themselves.
pub(crate) use lattice_host::lsp_helpers::app_to_lsp_position;

// 5.5.LSP.5: `flatten_document_symbol_response`,
// `symbol_information_to_row`, and `workspace_symbol_to_row`
// relocated to `lattice_host::lsp_helpers`. `flatten` has test
// callers in `mod lsp::tests`; the other two have none, so only
// `flatten` gets a re-export.
#[cfg(test)]
pub(crate) use lattice_host::lsp_helpers::flatten_document_symbol_response;

/// 4.5.a: render one `CallHierarchyItem` (the caller in an
/// `IncomingCall.from` or the callee in an
/// `OutgoingCall.to`) as a [`SymbolRow`] for the picker. The
/// item's `detail` (if any) plus the *originating* callable's
/// name ride in `container` -- e.g. for an incoming-calls
/// listing of `foo`, the rows say "bar.rs:42 fn quux  (in foo)".
/// Falls back to `(path, 0, 0)` if the URI doesn't parse;
/// keeping the row visible beats silently dropping it.
pub(crate) fn call_hierarchy_to_row(
    item: &lattice_lsp::lsp_types::CallHierarchyItem,
    related_to: &str,
) -> SymbolRow {
    let path = lattice_lsp::actor::uri_to_path(&item.uri).unwrap_or_default();
    SymbolRow {
        name: item.name.clone(),
        kind_glyph: symbol_kind_glyph(item.kind),
        container: Some(format!("in {related_to}")),
        depth: 0,
        path,
        line: item.selection_range.start.line,
        col: item.selection_range.start.character,
    }
}

/// 4.5.c: does the given `range` cover the LSP `position`?
/// Inclusive on both ends (matches VSCode's "click-through"
/// semantics on a link's rightmost char). Used by the `gx`
/// keystroke to find the first cached `documentLink` under
/// the cursor.
pub(crate) fn range_covers(
    range: lattice_lsp::lsp_types::Range,
    position: lattice_lsp::lsp_types::Position,
) -> bool {
    let after_start =
        (range.start.line, range.start.character) <= (position.line, position.character);
    let before_end = (position.line, position.character) <= (range.end.line, range.end.character);
    after_start && before_end
}

/// 4.5.b: render one `TypeHierarchyItem` (a supertype or
/// subtype of the cursor's type) as a [`SymbolRow`] for the
/// picker. Same projection as [`call_hierarchy_to_row`]
/// because the item shape is identical (name, kind, uri,
/// range, selection_range); the container hint differs
/// (`"super of foo"` / `"sub of foo"`).
pub(crate) fn type_hierarchy_to_row(
    item: &lattice_lsp::lsp_types::TypeHierarchyItem,
    related_to: &str,
) -> SymbolRow {
    let path = lattice_lsp::actor::uri_to_path(&item.uri).unwrap_or_default();
    SymbolRow {
        name: item.name.clone(),
        kind_glyph: symbol_kind_glyph(item.kind),
        container: Some(format!("of {related_to}")),
        depth: 0,
        path,
        line: item.selection_range.start.line,
        col: item.selection_range.start.character,
    }
}

/// Extract a placeholder string from a `PrepareRenameResponse`.
/// The spec gives three shapes: a Range (no placeholder, just
/// "you can rename here"), a Range+Placeholder (preferred), or
/// a DefaultBehavior signal (server defers to the editor's
/// word-under-cursor heuristic). We pull the placeholder when
/// present, else `None` so the App's caller can fall back to
/// the heuristic.
pub(crate) fn prepare_rename_placeholder(
    resp: &lattice_lsp::lsp_types::PrepareRenameResponse,
) -> Option<String> {
    match resp {
        lattice_lsp::lsp_types::PrepareRenameResponse::RangeWithPlaceholder {
            placeholder, ..
        } => Some(placeholder.clone()),
        lattice_lsp::lsp_types::PrepareRenameResponse::Range(_) => None,
        lattice_lsp::lsp_types::PrepareRenameResponse::DefaultBehavior { .. } => None,
    }
}

/// Flatten a `WorkspaceEdit` into a per-file
/// `Vec<(Uri, Vec<TextEdit>)>`. Handles both the legacy `changes`
/// HashMap shape and the modern `document_changes` shape (which
/// also carries DocumentChangeOperation::Op create/rename/delete
/// -- those are skipped in v1; rename returns plain text edits
/// for ~100% of identifiers).
///
/// Empty Vec means "nothing to apply" (the App echoes `Empty`).
pub(crate) fn flatten_workspace_edit(
    we: lattice_lsp::lsp_types::WorkspaceEdit,
) -> Vec<(
    lattice_lsp::lsp_types::Uri,
    Vec<lattice_lsp::lsp_types::TextEdit>,
)> {
    let mut out: Vec<(
        lattice_lsp::lsp_types::Uri,
        Vec<lattice_lsp::lsp_types::TextEdit>,
    )> = Vec::new();
    if let Some(changes) = we.changes {
        for (uri, edits) in changes {
            if !edits.is_empty() {
                out.push((uri, edits));
            }
        }
    }
    if let Some(doc_changes) = we.document_changes {
        match doc_changes {
            lattice_lsp::lsp_types::DocumentChanges::Edits(edits) => {
                for te_doc in edits {
                    let uri = te_doc.text_document.uri.clone();
                    let raw_edits: Vec<lattice_lsp::lsp_types::TextEdit> = te_doc
                        .edits
                        .into_iter()
                        .filter_map(|e| match e {
                            lattice_lsp::lsp_types::OneOf::Left(te) => Some(te),
                            // AnnotatedTextEdit -- strip the
                            // annotation; v1 doesn't surface
                            // change-annotations to the user.
                            lattice_lsp::lsp_types::OneOf::Right(ate) => Some(ate.text_edit),
                        })
                        .collect();
                    if !raw_edits.is_empty() {
                        out.push((uri, raw_edits));
                    }
                }
            }
            // create-file / rename-file / delete-file ops are
            // skipped in v1 -- the rename use case is identifier
            // rewrites, which servers return as plain text edits.
            lattice_lsp::lsp_types::DocumentChanges::Operations(_) => {}
        }
    }
    out
}

/// Single-character glyph for an LSP `CodeActionKind`. Maps
/// the standard kinds (quickfix, refactor*, source*) to a
/// short visual marker for the picker margin. Unknown / custom
/// kinds and bare `Command` payloads land on `?`.
pub(crate) fn code_action_kind_glyph(
    kind: Option<&lattice_lsp::lsp_types::CodeActionKind>,
) -> &'static str {
    use lattice_lsp::lsp_types::CodeActionKind as K;
    let Some(kind) = kind else {
        return "?";
    };
    if *kind == K::QUICKFIX {
        "🛠"
    } else if *kind == K::REFACTOR {
        "♻"
    } else if *kind == K::REFACTOR_EXTRACT {
        "↗"
    } else if *kind == K::REFACTOR_INLINE {
        "↘"
    } else if *kind == K::REFACTOR_REWRITE {
        "↺"
    } else if *kind == K::SOURCE {
        "★"
    } else if *kind == K::SOURCE_ORGANIZE_IMPORTS {
        "≡"
    } else if *kind == K::SOURCE_FIX_ALL {
        "✓"
    } else {
        "?"
    }
}

/// Single-character glyph for an LSP `CompletionItemKind`.
// 5.5.LSP.4: `completion_kind_glyph` relocated to
// `lattice_host::lsp_helpers`. Tests in `app/completion.rs` call
// it as `crate::app::completion_kind_glyph`, so the re-export
// stays available; no production App-side caller remains, so
// it's `cfg(test)`-scoped.
#[cfg(test)]
pub(crate) use lattice_host::lsp_helpers::completion_kind_glyph;

/// Single-character glyph for an LSP `SymbolKind`. Picked to
/// fit a fixed-width column in picker rows so the marginalia
/// column stays aligned. Falls back to `?` for kinds we don't
/// have a specific glyph for.
pub(crate) fn symbol_kind_glyph(kind: lattice_lsp::lsp_types::SymbolKind) -> &'static str {
    use lattice_lsp::lsp_types::SymbolKind as K;
    match kind {
        K::FILE => "📄",
        K::MODULE | K::NAMESPACE | K::PACKAGE => "📦",
        K::CLASS | K::INTERFACE => "🅒",
        K::METHOD | K::FUNCTION => "ƒ",
        K::CONSTRUCTOR => "🅒",
        K::PROPERTY | K::FIELD => "•",
        K::VARIABLE => "v",
        K::CONSTANT => "K",
        K::STRING | K::NUMBER | K::BOOLEAN | K::ARRAY | K::OBJECT => "≡",
        K::ENUM | K::ENUM_MEMBER => "🅔",
        K::STRUCT => "🅢",
        K::EVENT => "🅔",
        K::OPERATOR => "⊕",
        K::TYPE_PARAMETER => "T",
        _ => "?",
    }
}

/// Word (alphanumeric + `_` run) under `cursor` in `buffer`, or
/// `None` when the cursor isn't on a word byte. Mirrors vim's
/// `<cword>` for the simple case that `:references` needs to
/// label its results buffer ("References for \"foo\""). Walks
/// the line once at the cursor column; doesn't scan forward to
/// the next word like `do_search_word_under_cursor` does --
/// "no symbol under cursor" is preferable to a label that
/// jumps to a different identifier than the user pointed at.
pub(crate) fn word_under_cursor(buffer: &Buffer, cursor: Position) -> Option<String> {
    let line = buffer.line(cursor.line)?;
    let bytes = line.as_bytes();
    let byte_idx = cursor.byte as usize;
    if byte_idx >= bytes.len() || !is_word_char_byte(bytes[byte_idx]) {
        return None;
    }
    let mut start = byte_idx;
    while start > 0 && is_word_char_byte(bytes[start - 1]) {
        start -= 1;
    }
    let mut end = byte_idx;
    while end < bytes.len() && is_word_char_byte(bytes[end]) {
        end += 1;
    }
    if start == end {
        return None;
    }
    Some(String::from_utf8_lossy(&bytes[start..end]).into_owned())
}

// 5.5.LSP.2: `definition_response_to_locations` relocated to
// `lattice_host::lsp_helpers`. After the nav migration no
// production App-side caller remains (only `mod lsp::tests`
// exercises it through `super::*`), so the re-export is scoped
// under `cfg(test)` -- same shape as `hover_contents_to_markdown`.
#[cfg(test)]
pub(crate) use lattice_host::lsp_helpers::definition_response_to_locations;

// 5.5.LSP.1 step 2: see the re-export block above
// (`app_to_lsp_position`). The hover-content renderer now lives at
// `lattice_host::lsp_helpers::hover_contents_to_markdown`. After
// LSP.1's hover-request migration there are no remaining App-side
// production callers (only the `mod lsp::tests` block exercises
// it), so the re-export is `cfg(test)`-scoped to satisfy
// `deny(unused_imports)` in release builds.
#[cfg(test)]
pub(crate) use lattice_host::lsp_helpers::hover_contents_to_markdown;

// 5.5.H: `previous_position` retired (its sole caller was the
// search-side `step_byte`, also retired). Host's
// `lattice_host::dispatch::previous_position` is the live copy.

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic)]
    use super::test_helpers::{
        app_with, attach_test_syntax, invoke_motion, submit_ex, write_temp_file,
    };
    use super::*;
    use crate::help::HelpContent;

    #[test]
    fn normalize_user_path_expands_tilde_slash_against_home() {
        // `~/foo.rs` → `$HOME/foo.rs`. Mutating env vars
        // requires `unsafe` post-edition-2024 and the workspace
        // bans `unsafe_code`, so anchor the assertion against
        // the runner's actual HOME instead. Skip silently if
        // HOME isn't set -- not a meaningful environment.
        let Some(home) = std::env::var_os("HOME") else {
            return;
        };
        let got = normalize_user_path(std::path::Path::new("~/projects/foo.rs"));
        let expected = std::path::PathBuf::from(&home).join("projects/foo.rs");
        assert_eq!(got, expected);
    }

    #[test]
    fn normalize_user_path_expands_bare_tilde_to_home() {
        let Some(home) = std::env::var_os("HOME") else {
            return;
        };
        let got = normalize_user_path(std::path::Path::new("~"));
        assert_eq!(got, std::path::PathBuf::from(home));
    }

    #[test]
    fn normalize_user_path_leaves_absolute_paths_unchanged() {
        // Absolute paths are pass-through -- the cwd-join branch
        // is skipped. Critical for the oil dedupe path
        // (`oil_with_dir`) where two callers compare against the
        // same stored absolute key.
        // `temp_dir()`, not `/tmp/...`: drive-less is not absolute on Windows.
        let abs = std::env::temp_dir().join("abs").join("path.rs");
        assert!(abs.is_absolute());
        let got = normalize_user_path(&abs);
        assert_eq!(got, abs);
    }

    #[test]
    fn normalize_user_path_absolutises_relative_against_cwd() {
        // Single-component relative paths are the case that
        // broke oil's `-` (parent of `"foo.rs"` is `""`, and
        // `read_dir("")` is ENOENT). Post-fix the input is
        // already absolute by the time it reaches `read_dir`.
        let got = normalize_user_path(std::path::Path::new("foo.rs"));
        let expected = std::env::current_dir().unwrap().join("foo.rs");
        assert_eq!(got, expected);
    }

    #[test]
    fn normalize_user_path_preserves_dotdot_relative_against_cwd() {
        // `..` segments stay -- we deliberately don't
        // canonicalise (would require the path to exist). The
        // filesystem resolves `../foo.rs` correctly through
        // `read_to_string`.
        let got = normalize_user_path(std::path::Path::new("../foo.rs"));
        let expected = std::env::current_dir().unwrap().join("../foo.rs");
        assert_eq!(got, expected);
    }

    // Sanity check: a bare motion drives the cursor through
    // the full translate + apply path. If this fails, the
    // harness itself is broken; every other `press_*` test
    // is suspect.
    // Sanity check: an operator + motion deletes the right
    // span end-to-end. Exercises the `[d]` action-kind
    // short-circuit (pushes `d` into `partial_chord`) plus
    // the `[d, w]` resolution under the prefix.
    // -- count flow seam ----------------------------------------
    //
    // These pin the path translate -> attach_count -> dispatcher
    // multiplication. Slice 8.i.4.d documented the failure mode if
    // the action-kind short-circuit didn't bypass
    // `run_document_invocation`'s `pending_count = 0;`: the reset
    // would fire before `AbsorbOperatorPrefix` could latch op_count,
    // breaking `2dw`-style flows. These tests would catch a
    // regression of that fix.

    /// `3j` moves down 3 lines: pending_count fed straight to a
    /// motion (no operator latch path).
    /// `3dd` deletes 3 lines: count latches into op_count via
    /// the `d` action-kind dispatch; the second `d` resolves
    /// linewise with the count baked in by `attach_count`. Pins
    /// slice 8.i.4.f's removal of the dispatcher's redundant
    /// multiplication, AND slice 8.i.4.g's `dd`-consumes-newline
    /// fix (line count drops by 3 -- the buffer goes from 5
    /// lines to 2, with no leading empty line).
    /// `d2w` deletes 2 words: the `2` between operator and motion
    /// must reach the digit accumulator, not get eaten by the
    /// partial_chord lookup. Pins slice 8.i.4.f's hoist of digit
    /// handling above the partial_chord short-circuit.
    /// `2d2w` deletes 4 words: op_count=2 multiplies with
    /// motion_count=2. Pins both 8.i.4.f fixes end-to-end --
    /// digit-after-operator survives, and the dispatcher honours
    /// the input-side baked count without re-multiplying.
    /// After `3j`, a bare `j` moves only one line: pending_count
    /// must reset after the motion fires.
    // -- partial_chord state machine ----------------------------
    //
    // Pins the multi-keystroke prefix walk. `gg` is a Normal-mode
    // multi-key motion (no operator); `dd` is the operator
    // self-key linewise resolution; `df,` is a 3-keystroke chord
    // (operator -> find-char prefix -> captured delimiter).

    /// `gg` jumps to the first line: prefix `g` parks in
    /// partial_chord, second `g` resolves the terminal.
    /// `df,` deletes up to (exclusive of) the comma: 3-keystroke
    /// chord across the operator + find-char captured-delimiter
    /// sub-tree (slice 8.i.4.c). Lattice's `f`-motion is exclusive
    /// (see `df_deletes_through_target_char` near the dispatch
    /// tests), so the comma stays.
    // -- <C-w> sub-tree (action-kind short-circuit, 8.i.4.d) ----

    /// `<C-w>v` splits the active pane vertically. Exercises the
    /// `<C-w>` action-kind short-circuit + the AfterCtrlW layer.
    // -- mode transition seam -----------------------------------

    /// `i` enters Insert, typed chars land in the buffer, `<Esc>`
    /// returns to Normal. Pins the modal state machine across a
    /// mode round-trip in a single keystroke stream.
    /// Subscribe a channel sink to the App's event bus. Returns

    // ---- Slice B.2 part 2: edit-delta accumulation -------------
    //
    // Pin that EditDeltas accumulate on App.editor.pending_syntax_edits
    // across edits, drain on maybe_reparse_syntax, and the
    // version baseline tracks correctly. The actual incremental
    // reparse correctness is covered by lattice-syntax's parity
    // tests; these App-level tests pin the plumbing.

    // ---- Initial state ----

    #[test]
    fn new_app_starts_at_origin_in_normal_mode() {
        let a = app_with("abc", 10);
        assert_eq!(a.editor.cursor, Position::ZERO);
        assert_eq!(a.editor.scroll, 0);
        assert!(!a.editor.should_quit);
        assert_eq!(a.editor.modal, ModalState::Normal);
        assert!(a.editor.partial_chord.is_empty());
    }

    #[test]
    fn every_advertised_completion_source_resolves_at_boot() {
        // Every `ArgSpec::completion = Some(...)` declared in
        // `lattice_grammar::ex_commands` must resolve to a
        // generator registered at App boot. Otherwise typing
        // `<Tab>` on that arg silently produces no candidates --
        // the bug class that motivated this slice.
        let a = app_with("hi", 5);
        let reg = a.editor.registry.load();
        for name in reg.names() {
            let id = reg.id_by_name(name).unwrap();
            let Some(spec) = reg.ex_command_spec(id) else {
                continue;
            };
            for arg in &spec.args_schema {
                if let Some(source) = arg.completion.as_deref() {
                    assert!(
                        a.editor
                            .completion_registry
                            .generator_by_name(source)
                            .is_some(),
                        "{name}'s arg `{}` advertises completion source `{source}` \
                         but no generator with that name is registered at boot",
                        arg.name,
                    );
                }
            }
        }
    }

    #[test]
    fn modal_label_reports_state() {
        let mut a = app_with("", 10);
        assert_eq!(a.modal_label(), "NORMAL");
        a.apply(Action::EnterMode(ModalState::Insert));
        assert_eq!(a.modal_label(), "INSERT");
    }

    #[test]
    fn quit_sets_flag() {
        let mut a = app_with("abc", 10);
        a.apply(Action::Quit);
        assert!(a.editor.should_quit);
    }

    // ---- Motion via grammar engine ----

    // ---- Insert mode ----

    // ---- Operator + motion composition ----

    // ---- Undo / Redo ----

    // ---- Viewport scrolling ----

    // ---- Command-line minibuffer ----

    #[test]
    fn submitting_returns_to_normal_modal() {
        let mut a = app_with("hello", 10);
        a.apply(Action::EnterCommandLine);
        a.apply(Action::CommandLineAppend('q'));
        a.apply(Action::CommandLineSubmit);
        assert_eq!(a.editor.modal, ModalState::Normal);
    }

    #[test]
    fn echo_action_replaces_last_message() {
        let mut a = app_with("", 10);
        a.apply(Action::Echo(EchoMessage {
            text: "hi".into(),
            level: EchoLevel::Info,
        }));
        assert_eq!(a.editor.last_message.as_ref().unwrap().text, "hi");
        a.apply(Action::Echo(EchoMessage {
            text: "bye".into(),
            level: EchoLevel::Warn,
        }));
        assert_eq!(a.editor.last_message.as_ref().unwrap().text, "bye");
        assert_eq!(
            a.editor.last_message.as_ref().unwrap().level,
            EchoLevel::Warn
        );
    }
    // ---- change operator end-to-end ----

    // ---- Substitute (:s/foo/bar/[g]) ----

    // ---- Line join (J / gJ) ----

    // ---- WORD motions (W, B, E) end-to-end ----

    // ---- Position history (Ctrl-O / Ctrl-I) ----

    // ---- partial_chord lifecycle (regression) ----
    //
    // Slice 8.i.4 retired the legacy `Pending` enum; the regression
    // these tests pin is now expressed against `partial_chord`:
    // any non-`AbsorbPartialChord(_)` action must clear the
    // chord stack so a leftover prefix doesn't mis-route the
    // next keystroke.

    #[test]
    fn zz_clears_partial_chord_so_next_key_is_a_motion() {
        // Regression: previously `zz` left pending=AfterZ, so `j` after
        // `zz` was interpreted as `zj` (GotoNextFold) and emitted "no
        // more folds". Now expressed against partial_chord.
        let mut a = app_with("a\nb\nc\nd\ne", 10);
        a.apply(Action::AbsorbPartialChord(crate::chord::KeyChord::char(
            'z',
        )));
        a.apply(Action::ScrollCursorTo(ScrollPos::Center));
        assert!(a.editor.partial_chord.is_empty());
    }

    #[test]
    fn play_macro_clears_partial_chord() {
        let mut a = app_with("hello", 10);
        a.apply(Action::AbsorbPartialChord(crate::chord::KeyChord::char(
            '@',
        )));
        // No macro recorded; this errors but should still clear partial_chord.
        a.apply(Action::PlayMacro('z'));
        assert!(a.editor.partial_chord.is_empty());
    }

    // ---- §5.1.1 unified position history ----

    #[test]
    fn g_semicolon_walks_named_mark_history_backward() {
        let mut a = app_with("a\nb\nc\nd\ne", 10);
        // Set marks at three positions.
        a.editor.cursor = Position::new(1, 0);
        a.apply(Action::SetMark('a'));
        a.editor.cursor = Position::new(3, 0);
        a.apply(Action::SetMark('b'));
        a.editor.cursor = Position::new(4, 0);
        // g; lands on 'b' (most recent named mark).
        a.apply(Action::WalkMarkHistoryBack);
        assert_eq!(a.editor.cursor, Position::new(3, 0));
        // g; again -> 'a'.
        a.apply(Action::WalkMarkHistoryBack);
        assert_eq!(a.editor.cursor, Position::new(1, 0));
    }

    #[test]
    fn g_comma_walks_named_mark_history_forward() {
        let mut a = app_with("a\nb\nc\nd\ne", 10);
        a.editor.cursor = Position::new(1, 0);
        a.apply(Action::SetMark('a'));
        a.editor.cursor = Position::new(3, 0);
        a.apply(Action::SetMark('b'));
        a.editor.cursor = Position::new(4, 0);
        a.apply(Action::WalkMarkHistoryBack); // -> 'b'
        a.apply(Action::WalkMarkHistoryBack); // -> 'a'
        a.apply(Action::WalkMarkHistoryForward); // -> 'b'
        assert_eq!(a.editor.cursor, Position::new(3, 0));
    }

    #[test]
    fn g_semicolon_with_no_named_marks_emits_error() {
        let mut a = app_with("a\nb\nc", 10);
        a.editor.cursor = Position::new(2, 0);
        a.apply(invoke_motion(a.editor.builtins.goto_first_line)); // pushes AutoJump
        a.apply(Action::WalkMarkHistoryBack);
        let msg = a.editor.last_message.as_ref().unwrap();
        assert_eq!(msg.level, EchoLevel::Error);
        assert!(msg.text.contains("no marks"));
    }

    // ---- Multiple registers ----

    // ---- ~ toggle case at cursor ----

    // ---- Word-search (* / #) and matching-bracket (%) ----

    #[test]
    fn hash_finds_previous_occurrence_of_word_under_cursor() {
        let mut a = app_with("foo bar foo bar", 10);
        a.editor.cursor = Position::new(0, 8); // on 'f' of second "foo"
        a.apply(Action::SearchWordUnderCursor(SearchDirection::Backward));
        assert_eq!(a.editor.cursor, Position::ZERO);
    }

    // ---- Viewport motions ----

    // ---- Replace mode ----

    #[test]
    fn esc_exits_replace_to_normal_and_pulls_cursor_back() {
        let mut a = app_with("hello", 10);
        a.apply(Action::EnterMode(ModalState::Replace));
        a.apply(Action::OverwriteChar('H'));
        // Cursor at (0,1) after one overwrite.
        a.apply(Action::EnterMode(ModalState::Normal));
        // enter_mode pulls cursor back one byte on Normal entry.
        assert_eq!(a.editor.modal, ModalState::Normal);
        assert_eq!(a.editor.cursor, Position::new(0, 0));
    }

    // ---- Marks ----

    #[test]
    fn invalid_mark_name_emits_error() {
        let mut a = app_with("hello", 10);
        a.apply(Action::SetMark(' '));
        let msg = a.editor.last_message.as_ref().unwrap();
        assert_eq!(msg.level, EchoLevel::Error);
        assert!(a.editor.marks.is_empty());
    }

    #[test]
    fn marks_are_keyed_by_name() {
        let mut a = app_with("hello\nworld", 10);
        a.editor.cursor = Position::new(0, 1);
        a.apply(Action::SetMark('a'));
        a.editor.cursor = Position::new(1, 3);
        a.apply(Action::SetMark('b'));
        a.editor.cursor = Position::ZERO;
        a.apply(Action::JumpToMarkExact('a'));
        assert_eq!(a.editor.cursor, Position::new(0, 1));
        a.apply(Action::JumpToMarkExact('b'));
        assert_eq!(a.editor.cursor, Position::new(1, 3));
    }

    #[test]
    fn uppercase_mark_works_same_as_lowercase_in_v1() {
        // v1 makes no distinction between buffer-local (a-z) and global
        // (A-Z) marks since the TUI runs against a single document.
        let mut a = app_with("hello\nworld", 10);
        a.editor.cursor = Position::new(1, 2);
        a.apply(Action::SetMark('A'));
        a.editor.cursor = Position::ZERO;
        a.apply(Action::JumpToMarkExact('A'));
        assert_eq!(a.editor.cursor, Position::new(1, 2));
    }

    #[test]
    fn jumping_to_mark_with_invalid_name_is_error() {
        let mut a = app_with("hello", 10);
        a.apply(Action::JumpToMarkExact(' '));
        let msg = a.editor.last_message.as_ref().unwrap();
        assert_eq!(msg.level, EchoLevel::Error);
    }

    // ---- Dot-repeat ----

    #[test]
    fn motion_does_not_record_last_change() {
        let mut a = app_with("hello world", 10);
        a.apply(invoke_motion(a.editor.builtins.word_forward));
        assert!(a.editor.last_change.is_none());
    }

    // ---- count prefix end-to-end ----

    #[test]
    fn push_digit_accumulates_pending_count() {
        let mut a = app_with("abc", 10);
        a.apply(Action::PushDigit(1));
        a.apply(Action::PushDigit(2));
        a.apply(Action::PushDigit(3));
        assert_eq!(a.editor.pending_count, 123);
    }

    // Slice 8.i.4.f: the next batch of tests bake `Count(N)`
    // directly into the operator invocation -- mirroring what the
    // input-side `attach_count` produces when the keystroke
    // pipeline runs. The dispatcher's job is now to honour the
    // baked count and drain `pending_count` / `op_count` from
    // App state. The full keystroke -> count pipeline lives in
    // the `key_harness_*` press-harness tests.

    // ---- find / till motions end-to-end ----

    #[test]
    fn fz_jumps_to_z_on_current_line() {
        let mut a = app_with("hello, world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.find_char_forward.0)
            .with_args(lattice_grammar::Args::Char('w'));
        a.apply(Action::Invoke(inv));
        assert_eq!(a.editor.cursor, Position::new(0, 7));
    }

    #[test]
    fn t_lands_one_byte_before_target() {
        let mut a = app_with("hello, world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.till_char_forward.0)
            .with_args(lattice_grammar::Args::Char('w'));
        a.apply(Action::Invoke(inv));
        assert_eq!(a.editor.cursor, Position::new(0, 6));
    }

    #[test]
    fn df_deletes_through_target_char() {
        // From "hello, world" with cursor at 0, `df,` deletes "hello," and
        // leaves " world".
        let mut a = app_with("hello, world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.delete.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.find_char_forward,
                lattice_grammar::Args::Char(','),
            ),
        );
        a.apply(Action::Invoke(inv));
        // `f` is inclusive: find_char_forward lands on the comma (byte 5) and
        // the operator covers it too -> [0, 6) = "hello," is deleted, leaving
        // " world". (Vim parity; the inclusive flag is now honoured.)
        assert_eq!(a.editor.document.text(), " world");
    }

    #[test]
    fn ct_with_change_enters_insert_mode() {
        let mut a = app_with("hello, world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.change.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.till_char_forward,
                lattice_grammar::Args::Char(','),
            ),
        );
        a.apply(Action::Invoke(inv));
        assert_eq!(a.editor.modal, ModalState::Insert);
    }

    // ---- yank + paste end-to-end ----

    #[test]
    fn yw_populates_unnamed_register_charwise() {
        let mut a = app_with("hello world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.yank.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.word_forward,
                lattice_grammar::Args::None,
            ),
        );
        a.apply(Action::Invoke(inv));
        let reg = a.editor.unnamed_register.as_ref().unwrap();
        assert_eq!(reg.content, "hello ");
        assert_eq!(reg.kind, YankKind::Charwise);
        // Buffer untouched by yank.
        assert_eq!(a.editor.document.text(), "hello world");
    }

    #[test]
    fn goto_first_line_into_closed_fold_auto_opens() {
        let initial = "# H1\nbody\nbody2\n# H2\nafter\n";
        let mut a = app_with(initial, 10);
        a.set_foldmethod_for_test(FoldMethod::Markdown);
        a.recompute_folds();
        let idx = a
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("H1 fold");
        a.editor.folds[idx].closed = true;
        // Move cursor away first (so gg is a non-trivial jump).
        a.editor.cursor = Position::new(4, 0);
        let inv = CommandInvocation::of(a.editor.builtins.goto_first_line.0);
        a.apply(Action::Invoke(inv));
        let fold = a
            .editor
            .folds
            .iter()
            .find(|f| f.start_line == 0)
            .expect("H1 fold still present");
        assert!(!fold.closed, "gg should auto-open the destination fold");
    }

    #[test]
    fn zi_toggles_foldenable_and_renders_folds_open() {
        let mut a = app_with("# H\nbody\n# H2\n", 10);
        a.set_foldmethod_for_test(FoldMethod::Markdown);
        a.recompute_folds();
        let idx = a
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("H1 fold");
        a.editor.folds[idx].closed = true;
        a.editor.publish_render_state();
        // Sanity: the fold is closed and visible to the renderer.
        assert!(a.line_inside_closed_fold(1));
        assert!(a.fold_start_at(0).is_some());
        // zi disables.
        a.apply(Action::ToggleFoldEnable);
        assert!(!a.foldenable());
        // With foldenable=false, the renderer sees no closed folds.
        assert!(!a.line_inside_closed_fold(1));
        assert!(a.fold_start_at(0).is_none());
        // zi again re-enables and the closed-state is preserved.
        a.apply(Action::ToggleFoldEnable);
        assert!(a.foldenable());
        assert!(a.line_inside_closed_fold(1));
        assert!(a.fold_start_at(0).is_some());
    }

    #[test]
    fn nofoldenable_disables_fold_aware_operators() {
        let initial = "# H1\nbody one\nbody two\n# H2\nafter\n";
        let mut a = app_with(initial, 10);
        a.set_foldmethod_for_test(FoldMethod::Markdown);
        a.recompute_folds();
        let idx = a
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("H1 fold");
        a.editor.folds[idx].closed = true;
        a.set_foldenable_for_test(false);
        a.editor.cursor = Position::new(0, 0);
        let inv = CommandInvocation::of(a.editor.builtins.delete.0)
            .with_range(lattice_grammar::Range::CurrentLine);
        a.apply(Action::Invoke(inv));
        // With foldenable=false, dd should affect just one line.
        let text = a.editor.document.text();
        assert!(
            !text.contains("# H1"),
            "heading should be deleted: {text:?}"
        );
        assert!(
            text.contains("body one"),
            "body one should remain: {text:?}"
        );
    }

    #[test]
    fn linear_j_does_not_auto_open_fold() {
        // `docs/user/folding.md`: linear motions (j/k/h/l/w/b) do
        // NOT trigger auto-open. The cursor "skips" over closed
        // folds via `line_inside_closed_fold` filtering -- but the
        // fold itself stays closed. Here we simulate a synthetic
        // cursor move into the fold range to verify the rule.
        let initial = "# H1\nbody\nbody2\n# H2\nafter\n";
        let mut a = app_with(initial, 10);
        a.set_foldmethod_for_test(FoldMethod::Markdown);
        a.recompute_folds();
        let idx = a
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("H1 fold");
        a.editor.folds[idx].closed = true;
        // Direct cursor move (not via auto-open path).
        a.editor.cursor = Position::new(1, 0);
        let still_closed = a
            .editor
            .folds
            .iter()
            .find(|f| f.start_line == 0)
            .expect("H1 fold still present");
        assert!(
            still_closed.closed,
            "merely setting cursor should not open folds"
        );
    }

    #[test]
    fn read_only_j_snaps_past_closed_fold() {
        // Regression (dashboard / help): read-only buffers fold markdown
        // sections too, but their motion runner (`run_read_only_motion`)
        // ignored folds — so `j` walked line-by-line through the hidden
        // body instead of stepping over the closed section to the next
        // visible line. The document path (`run_document_invocation`)
        // already snapped; this pins the read-only path to match.
        let mut a = app_with("# H1\nbody\nbody2\n# H2\nafter\n", 10);
        a.set_foldmethod_for_test(FoldMethod::Markdown);
        a.recompute_folds();
        let idx = a
            .editor
            .folds
            .iter()
            .position(|f| f.start_line == 0)
            .expect("H1 fold");
        let end = a.editor.folds[idx].end_line;
        a.editor.folds[idx].closed = true;
        a.editor.cursor = Position::new(0, 0);
        // Drive the read-only motion path directly (help-mode's runner).
        let inv = lattice_grammar::CommandInvocation::of(a.editor.builtins.line_down.0);
        a.editor.run_read_only_motion(inv);
        assert_eq!(
            a.editor.cursor.line,
            end + 1,
            "read-only `j` must land on the first visible line past the closed fold"
        );
    }

    // ---- Bracketed-paste burst (Action::PasteText) ----

    // ---- Blockwise visual operators (DESIGN.md §15:18) ----

    /// Drive into Blockwise visual at `anchor`, then move the cursor to
    /// `head` so the rectangle is `[anchor, head]`. Returns the App
    /// ready for an operator dispatch.
    // ---- Help overlay (DESIGN.md §5.11) ----

    // ---- Command-line completion (DESIGN.md §5.11.3) ----

    #[test]
    fn accept_completion_replaces_prefix_with_chosen_text() {
        let mut a = app_in_command_mode("descri");
        a.apply(Action::CommandLineCompleteOrAdvance);
        // The accepted candidate uses the user-facing alias form,
        // not the canonical `ex:*` name. The first candidate (after
        // ranking) is one of the describe-* family.
        a.apply(Action::CommandLineAcceptCompletion);
        assert!(
            a.editor.command_line().starts_with("describe-")
                || a.editor.command_line() == "apropos",
            "expected user-facing alias, got `{}`",
            a.editor.command_line()
        );
        assert!(a.editor.completion_state.is_none());
    }

    // ---- Chord-capture (DESIGN.md §B.1, ArgKind::Chord) ----

    // ---- Missing-arg chord prompt (DESIGN.md §B.1) ----

    #[test]
    fn cancel_clears_armed_chord_prompt() {
        let mut a = app_in_command_mode("describe-key");
        a.apply(Action::CommandLineSubmit);
        assert!(a.editor.auto_submit_after_chord);
        a.apply(Action::CommandLineCancel);
        assert!(!a.editor.auto_submit_after_chord);
    }

    #[test]
    fn arg_slot_completion_for_describe_command_shows_command_names() {
        // After "describe-command moti", the slot is arg 0 with
        // completion source "gen:commands" -- the popup lists motion:*
        // commands. UD.2: motions are invocable via `:` (the host
        // dispatch is unified), so `gen:commands` includes them and
        // `:describe-command` can complete (and describe) them.
        let mut a = app_in_command_mode("describe-command moti");
        a.apply(Action::CommandLineCompleteOrAdvance);
        let state = a.editor.completion_state.as_ref().expect("popup");
        assert!(
            state
                .candidates
                .iter()
                .any(|c| c.raw.text.starts_with("motion:")),
            "expected motion:* candidates: {:?}",
            state
                .candidates
                .iter()
                .map(|c| &c.raw.text)
                .collect::<Vec<_>>()
        );
    }

    #[test]
    fn accept_in_arg_slot_replaces_only_the_arg_prefix() {
        let mut a = app_in_command_mode("describe-command moti");
        a.apply(Action::CommandLineCompleteOrAdvance);
        a.apply(Action::CommandLineAcceptCompletion);
        // Should now be "describe-command motion:..." -- the command
        // word + space preserved; only the `moti` arg prefix replaced.
        assert!(
            a.editor
                .command_line()
                .starts_with("describe-command motion:"),
            "got: {:?}",
            a.editor.command_line()
        );
    }

    // ---- Hybrid <C-h> (DESIGN.md §5.11.3 Q11) ----

    // ---- delete_trailing_word helper ----

    // ---- Alias preference for command candidates ----

    #[test]
    fn resolve_command_name_or_alias_handles_both_forms() {
        let mut registry = lattice_grammar::CommandRegistry::new();
        let _ = lattice_grammar::builtins::populate(&mut registry);
        let _ = lattice_grammar::ex_commands::populate(&mut registry);
        // Canonical hits.
        assert!(
            lattice_host::excommand::resolve_command_name_or_alias(&registry, "ex:write").is_some()
        );
        assert!(
            lattice_host::excommand::resolve_command_name_or_alias(&registry, "ex:apropos")
                .is_some()
        );
        assert!(
            lattice_host::excommand::resolve_command_name_or_alias(&registry, "motion:line-down")
                .is_some()
        );
        // Alias hits.
        assert!(lattice_host::excommand::resolve_command_name_or_alias(&registry, "w").is_some());
        assert!(
            lattice_host::excommand::resolve_command_name_or_alias(&registry, "apropos").is_some()
        );
        assert!(
            lattice_host::excommand::resolve_command_name_or_alias(&registry, "describe-command")
                .is_some()
        );
        // Misses.
        assert!(
            lattice_host::excommand::resolve_command_name_or_alias(&registry, "nope").is_none()
        );
        assert!(lattice_host::excommand::resolve_command_name_or_alias(&registry, "").is_none());
    }

    #[test]
    fn parser_accepts_canonical_name_directly() {
        // Defensive: even if the user types the canonical name
        // (`:ex:describe-command`), the parser resolves it. The
        // assertion: no "unknown command" error message. Whatever
        // happens downstream (e.g. `:ex:write` errors on no file
        // name) is unrelated to parser resolution.
        let mut a = app_in_command_mode("ex:describe-command ex:write");
        a.apply(Action::CommandLineSubmit);
        // Should have opened the help buffer; no "unknown
        // command" error from the parser.
        assert!(
            a.editor.popup_buffer.is_some(),
            "help should open from canonical-name describe-command"
        );
    }

    // ---- completion.auto_insert_single (B + sub-decision (i)) ----
    //
    // Single-candidate auto-insert at popup-open: when `<Tab>` would
    // open a popup with exactly one candidate AND the option is on,
    // skip the popup and apply the candidate to the cmdline directly.
    // Today there's only one completion path (cmdline `:` Tab), so
    // this hook covers `gen:commands`, `gen:options`, and every other
    // arg-slot generator uniformly. When LSP / Insert-mode completion
    // lands (Phase 4.2, task #199), Phase 4.2 should reuse
    // `open_completion_popup` (or factor a shared helper) so this
    // option stays universal without a second knob.

    // ---- Pane tree (DESIGN.md §5.9, B.1.b) ----

    #[test]
    fn focused_hover_does_not_auto_dismiss_on_motion() {
        // State B: cursor is *inside* the popup; motions move the
        // popup's cursor, not the doc's. The State-A auto-dismiss
        // hook is gated on `prev_pane_for_popup.is_none()` -- in
        // State B that field is Some, so motion doesn't drop the
        // popup.
        let mut a = app_with("fn main() {}\n", 5);
        a.do_open_hover("line 1\nline 2\nline 3");
        a.apply_effect(lattice_grammar::Effect::Lsp(
            lattice_grammar::LspRequest::Hover,
        )); // -> State B (5.5.LSP.1)
        assert!(matches!(a.editor.active_buffer, BufferKind::Help));
        // Move within popup.
        let inv = lattice_grammar::CommandInvocation::of(a.editor.builtins.line_down.0);
        a.apply(Action::Invoke(inv));
        assert!(a.editor.popup_buffer.is_some(), "popup persists in State B");
        assert_eq!(a.editor.cursor.line, 1);
    }

    // ---- Multiple Document buffers (DESIGN.md §5.9, B.1.c) ----

    #[test]
    fn bnext_cycles_through_open_buffers() {
        let path = write_temp_file("b", "one\n");
        let mut a = app_with("xx", 10);
        let first_id = a.editor.document_buffer_id;
        a.editor
            .set_command_line_text(&format!("e {}", path.display()));
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        let second_id = a.editor.document_buffer_id;
        assert_ne!(first_id, second_id);
        a.editor.set_command_line_text("bn");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert_eq!(a.editor.document_buffer_id, first_id);
        a.editor.set_command_line_text("bn");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert_eq!(a.editor.document_buffer_id, second_id);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn editing_already_open_path_switches_back_to_it() {
        let path = write_temp_file("d", "alpha\n");
        let mut a = app_with("xx", 10);
        let initial_id = a.editor.document_buffer_id;
        a.editor
            .set_command_line_text(&format!("e {}", path.display()));
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        let new_id = a.editor.document_buffer_id;
        // Cycle back to first buffer.
        a.editor.set_command_line_text("bn");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert_eq!(a.editor.document_buffer_id, initial_id);
        // Re-editing the new file's path should switch to its
        // existing buffer rather than spawning a third.
        a.editor
            .set_command_line_text(&format!("e {}", path.display()));
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert_eq!(a.editor.document_buffer_id, new_id);
        // Listed-count gates the "did we accidentally spawn a third?"
        // assertion; synthetic `*lsp*` doesn't count.
        assert_eq!(a.editor.buffers.listed_ids_sorted().len(), 2);
        let _ = std::fs::remove_file(path);
    }

    // ---- Buffer activation lifecycle ----
    //
    // Regression coverage for the `<C-l>`-needed bug: opening a
    // second file via `:e <path>` left the new buffer with empty
    // folds and stale highlight caches because no single hook ran
    // on activation. `App::activate_buffer_state` is now the one
    // place to add buffer-level state that needs to come up with
    // the buffer.

    #[test]
    fn activation_skips_fold_seed_for_manual_foldmethod() {
        // Manual foldmethod => activation must NOT auto-create folds
        // (the user's `zf` ranges are authoritative; auto-seeding
        // would surprise them).
        let path = write_temp_file("activate-manual", "a:\n    x\n    y\nb:\n    p\n    q\n");
        let mut a = app_with("xx", 10);
        a.set_foldmethod_for_test(FoldMethod::Manual);
        a.editor
            .set_command_line_text(&format!("e {}", path.display()));
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert!(
            a.editor.folds.is_empty(),
            "manual foldmethod should not auto-seed folds: {:?}",
            a.editor.folds
        );
        let _ = std::fs::remove_file(path);
    }

    // ---- File-tree buffer (DESIGN.md §5.9, B.1.d) ----

    // ---- Typed options registry (DESIGN.md §5.12, B.2) ----

    // ---- Hover popup (DESIGN.md §5.9.6, B.3) ----

    // ---- LSP hover (Phase 4.2.b) ----

    // ---- LSP goto-definition (Phase 4.2.c) ----

    /// 4.5.c: `range_covers` returns true for points strictly
    /// inside the range; inclusive on both ends to match the
    /// "click on the rightmost char of a link" UX.
    #[test]
    fn range_covers_inclusive_at_both_ends() {
        let r = lattice_lsp::lsp_types::Range {
            start: lattice_lsp::lsp_types::Position {
                line: 2,
                character: 4,
            },
            end: lattice_lsp::lsp_types::Position {
                line: 2,
                character: 10,
            },
        };
        // Inside.
        assert!(super::range_covers(
            r,
            lattice_lsp::lsp_types::Position {
                line: 2,
                character: 6
            }
        ));
        // Boundary (inclusive).
        assert!(super::range_covers(r, r.start));
        assert!(super::range_covers(r, r.end));
        // Before start -> miss.
        assert!(!super::range_covers(
            r,
            lattice_lsp::lsp_types::Position {
                line: 2,
                character: 3
            }
        ));
        // After end -> miss.
        assert!(!super::range_covers(
            r,
            lattice_lsp::lsp_types::Position {
                line: 2,
                character: 11
            }
        ));
        // Different line outside the range.
        assert!(!super::range_covers(
            r,
            lattice_lsp::lsp_types::Position {
                line: 1,
                character: 7
            }
        ));
        assert!(!super::range_covers(
            r,
            lattice_lsp::lsp_types::Position {
                line: 3,
                character: 0
            }
        ));
    }

    /// 4.5.c: `range_covers` works across line boundaries when
    /// the range spans multiple lines.
    #[test]
    fn range_covers_multi_line_range() {
        let r = lattice_lsp::lsp_types::Range {
            start: lattice_lsp::lsp_types::Position {
                line: 2,
                character: 4,
            },
            end: lattice_lsp::lsp_types::Position {
                line: 4,
                character: 8,
            },
        };
        // Mid-range second line: covered regardless of column.
        assert!(super::range_covers(
            r,
            lattice_lsp::lsp_types::Position {
                line: 3,
                character: 0
            }
        ));
        // First line before start column -> miss.
        assert!(!super::range_covers(
            r,
            lattice_lsp::lsp_types::Position {
                line: 2,
                character: 3
            }
        ));
        // Last line after end column -> miss.
        assert!(!super::range_covers(
            r,
            lattice_lsp::lsp_types::Position {
                line: 4,
                character: 9
            }
        ));
    }

    #[test]
    fn symbol_kind_glyph_distinct_for_common_kinds() {
        // We don't assert the *exact* glyph (those may evolve);
        // we just want the common kinds to map to *distinct*
        // glyphs so a glance distinguishes a fn from a struct.
        use lattice_lsp::lsp_types::SymbolKind as K;
        let f = super::symbol_kind_glyph(K::FUNCTION);
        let s = super::symbol_kind_glyph(K::STRUCT);
        let m = super::symbol_kind_glyph(K::MODULE);
        let v = super::symbol_kind_glyph(K::VARIABLE);
        assert_ne!(f, s);
        assert_ne!(f, m);
        assert_ne!(f, v);
    }

    #[test]
    fn prepare_rename_placeholder_extracted_from_range_with_placeholder() {
        let r = lattice_lsp::lsp_types::Range {
            start: lattice_lsp::lsp_types::Position {
                line: 0,
                character: 0,
            },
            end: lattice_lsp::lsp_types::Position {
                line: 0,
                character: 3,
            },
        };
        let resp = lattice_lsp::lsp_types::PrepareRenameResponse::RangeWithPlaceholder {
            range: r,
            placeholder: "foo".into(),
        };
        assert_eq!(
            super::prepare_rename_placeholder(&resp),
            Some("foo".to_string())
        );
        let resp = lattice_lsp::lsp_types::PrepareRenameResponse::Range(r);
        assert_eq!(super::prepare_rename_placeholder(&resp), None);
    }

    #[test]
    fn picker_dismiss_clears_pending_tag_origin() {
        let mut a = app_with("foo\n", 10);
        a.editor.pending_tag_origin = Some(super::TagStackEntry {
            buffer: a.editor.active_buffer,
            buffer_id: a.active_pane_buffer_id(),
            position: Position::new(0, 0),
            label: "foo".into(),
        });
        // Open + dismiss a picker. We don't need real candidates;
        // a non-Some picker dismiss already takes the picker
        // first. Simulate by setting picker Some.
        let mut p = lattice_picker::Picker::new(
            "test",
            lattice_picker::PickerSource::LspLocations,
            lattice_picker::PickerAction::JumpToLspLocation,
        );
        p.set_lsp_locations(Vec::new());
        a.editor.picker = Some(p);
        a.apply(Action::PickerDismiss);
        assert!(a.editor.pending_tag_origin.is_none());
    }

    #[test]
    fn diagnostics_picker_clears_stale_tag_origin() {
        // If a stale nav-intent origin was set (race scenario:
        // gd fired but drain hasn't run; user invokes
        // :diagnostics), opening the diagnostics picker MUST
        // clear the origin so a later JumpToLspLocation accept
        // doesn't push the wrong entry.
        let mut a = app_with("foo\n", 10);
        a.editor.pending_tag_origin = Some(super::TagStackEntry {
            buffer: a.editor.active_buffer,
            buffer_id: a.active_pane_buffer_id(),
            position: Position::new(0, 0),
            label: "stale".into(),
        });
        a.do_list_diagnostics();
        assert!(a.editor.pending_tag_origin.is_none());
    }

    // ---- :help (DESIGN.md §5.11) ----

    #[test]
    fn h_alias_resolves_to_help() {
        let mut a = app_with("xx", 10);
        a.editor.set_command_line_text("h folding");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        let h = a.popup_help().expect("help open");
        assert_eq!(h.title, "help folding");
    }

    #[test]
    fn after_change_user_can_type_and_replacement_lands() {
        let mut a = app_with("hello world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.change.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.word_forward,
                lattice_grammar::Args::None,
            ),
        );
        a.apply(Action::Invoke(inv));
        assert_eq!(a.editor.modal, ModalState::Insert);
        a.apply(Action::Insert("HEY ".into()));
        assert_eq!(a.editor.document.text(), "HEY world");
    }

    // ---- LSP wiring tests (Phase 4.1.i) ---------------------

    #[test]
    fn pathless_document_does_not_register_buffer_uri() {
        // Path-less scratch document -> `App::new` publishes no
        // `Event::DocumentOpened` (well, *publishes one for
        // observability, but with `path: None`*) and registers
        // no `buffer_uris` entry. The attach driver ignores
        // path-less events.
        let app = App::new(Document::from_text("fn main() {}"));
        assert!(app.buffer_uri(app.editor.document_buffer_id).is_none());
    }

    // ---- LSP diagnostic navigation tests (Phase 4.1.d.iv) ----

    /// Helper: seed N diagnostics into the App's LSP layer at
    /// the given lines + map a fake URI to the active buffer.
    // ---- LSP introspection tests (Phase 4.1.g) ---------------

    #[test]
    fn k_chord_registered_in_lsp_mode_keymap() {
        // MO.1: `K` migrated from Builtin layer to LspMode::keymap().
        // `:describe-key K` on an lsp-mode buffer walks the mode-contributed
        // layer and finds it there. On a non-lsp buffer it correctly shows
        // "not bound" — the binding is mode-gated by K.1.c.
        use lattice_lsp::modes::LspMode;
        use lattice_mode::Mode as _;
        let km = LspMode::new().keymap();
        let k = km.entries.iter().find(|e| e.chord == "K");
        assert!(k.is_some(), "K should be in LspMode::keymap() entries");
        let entry = k.unwrap();
        assert!(
            entry.doc.to_lowercase().contains("hover"),
            "doc should mention hover, got {:?}",
            entry.doc
        );
    }

    // ---- Edit-dispatch wiring tests (Phase 4.1.i.2) ----------

    /// Path-bearing initial documents publish
    /// `Event::DocumentOpened` from `App::new` and register the
    /// URI eagerly. The attach driver picks the event up off
    /// the bus and submits to the supervisor on the LSP runtime
    /// -- the UI thread never parks. We verify the eager URI
    /// registration here (`buffer_uris` is observable on the
    /// public App API); full driver -> supervisor behaviour
    /// (the publish path itself) is covered in
    /// `lattice_lsp::attach_driver::tests`.
    #[test]
    fn path_bearing_initial_document_registers_uri_eagerly() {
        use std::str::FromStr;
        // Build a Document with a fixed path. We can't use
        // `Document::open` here without I/O; the builder
        // surface (DocumentBuilder::with_path) lets us seed
        // the path directly.
        let path = std::path::PathBuf::from("/tmp/lattice-test/initial.rs");
        let doc = lattice_core::DocumentBuilder::default()
            .with_path(path.clone())
            .with_text("fn main() {}")
            .build();
        let app = App::new(doc);
        let expected = <lattice_lsp::Uri as FromStr>::from_str(
            lattice_lsp::actor::uri_from_path(&path).as_str(),
        )
        .unwrap();
        assert_eq!(
            app.buffer_uri(app.editor.document_buffer_id),
            Some(expected),
            "path-bearing initial document must register URI eagerly"
        );
    }

    // ---- Snippet host integration (Phase 4.2.g.4) ----

    /// Test helper: attach a freshly-parsed `Syntax` for `lang`
    /// to `a`, wrapped in a [`SyntaxHandle`]. Mirrors the audit

    #[test]
    fn dedup_helper_keeps_first_occurrence_by_text() {
        // Direct unit test on the dedup helper. Ranker has
        // already sorted; we feed in a vec mimicking the
        // post-rank state (highest-ranked entry first per
        // text), confirm the deduped vec keeps the first
        // occurrence and preserves order otherwise.
        use lattice_completion::{
            CandidateKind, MatchScore, RawCandidate, RenderedCandidate, ScoredCandidate, SourceId,
        };
        let mk = |text: &str, source: &str, score: u32| {
            let raw =
                RawCandidate::plain(text, CandidateKind::Plain).with_source(SourceId::new(source));
            RenderedCandidate::from_scored(ScoredCandidate {
                raw,
                score: MatchScore(score),
                match_ranges: Vec::new(),
            })
        };
        let mut rendered = vec![
            mk("outer", "gen:buffer-words", 200),
            mk("alpha", "gen:buffer-words", 180),
            mk("outer", "gen:tree-sitter-symbol", 180),
            mk("beta", "gen:tree-sitter-symbol", 150),
            mk("alpha", "gen:tree-sitter-symbol", 150),
        ];
        super::dedup_rendered_by_text(&mut rendered);
        let texts: Vec<&str> = rendered.iter().map(|c| c.raw.text.as_str()).collect();
        let sources: Vec<&str> = rendered
            .iter()
            .map(|c| c.raw.source.as_ref().map(|s| s.as_str()).unwrap_or(""))
            .collect();
        assert_eq!(texts, vec!["outer", "alpha", "beta"]);
        // Each kept row carries the higher-ranked source's
        // tag (the first occurrence of each text).
        assert_eq!(
            sources,
            vec![
                "gen:buffer-words",
                "gen:buffer-words",
                "gen:tree-sitter-symbol",
            ],
        );
    }

    // Inject an `InboundApplyEdit` into the App's drain
    // receiver. Replaces whatever was there; tests start with
    // an empty receiver so this is fine.

    fn install_lsp_candidate_with_commit_chars(
        a: &mut App,
        text: &str,
        commit_chars: Vec<char>,
        anchor: Position,
    ) {
        let cursor = a.editor.cursor;
        let snap = a.editor.document.snapshot();
        let line = snap.buffer.line(cursor.line).unwrap_or_default();
        let query = line
            .get(anchor.byte as usize..cursor.byte as usize)
            .unwrap_or("")
            .to_string();
        let mut state = lattice_completion::InsertCompletionState::open(
            lattice_completion::CompletionTrigger::Manual,
            anchor,
            cursor,
            query,
        );
        let meta = LspCompletionMeta {
            label: text.to_string(),
            insert_text: text.to_string(),
            filter_text: None,
            sort_text: None,
            detail: None,
            documentation: None,
            kind: Some(lattice_lsp::lsp_types::CompletionItemKind::FUNCTION),
            deprecated: false,
            preselect: false,
            commit_characters: commit_chars,
            additional_text_edits: Vec::new(),
            command: None,
            insert_text_format: lattice_lsp::lsp_types::InsertTextFormat::PLAIN_TEXT,
            replace_range: None,
            server_id: "test-server".to_string(),
            original_item: lattice_lsp::lsp_types::CompletionItem::new_simple(
                text.to_string(),
                String::new(),
            ),
            resolved: false,
        };
        let payload = lattice_lsp::completion::encode_meta(&meta);
        let mut raw =
            lattice_completion::RawCandidate::plain(text, lattice_completion::CandidateKind::Plain)
                .with_source(lattice_completion::SourceId::new(
                    lattice_completion::LSP_COMPLETION_SOURCE_ID,
                ));
        raw.data = lattice_completion::CandidateData::Extension {
            kind_id: LSP_COMPLETION_KIND_ID,
            payload,
        };
        state.raw.push(raw);
        a.refilter_insert_completion(&mut state);
        a.editor.insert_completion = Some(state);
    }

    #[test]
    fn commit_char_in_lsp_item_accepts_then_inserts() {
        let mut a = app_with("foo", 10);
        a.editor.modal = ModalState::Insert;
        a.editor.cursor = Position::new(0, 3);
        install_lsp_candidate_with_commit_chars(&mut a, "foo", vec!['.', '('], Position::new(0, 0));
        a.do_completion_accept_then_insert('.');
        // Popup closed; accept replaced the partial with the
        // full LSP insert, then `.` was appended.
        assert!(
            a.editor.insert_completion.is_none(),
            "popup closed on commit"
        );
        assert_eq!(a.editor.document.snapshot().buffer.as_string(), "foo.");
    }

    #[test]
    fn non_commit_char_is_plain_insert_popup_refilters() {
        let mut a = app_with("foo", 10);
        a.editor.modal = ModalState::Insert;
        a.editor.cursor = Position::new(0, 3);
        install_lsp_candidate_with_commit_chars(&mut a, "foo", vec!['.'], Position::new(0, 0));
        a.do_completion_accept_then_insert('a');
        // `a` isn't a commit char -> the focused candidate
        // wasn't accepted; `a` was inserted plainly. The
        // refresh hook closes the popup because the new
        // query "fooa" no longer matches the candidate
        // "foo" prefix-wise (matcher returns no rows).
        assert_eq!(a.editor.document.snapshot().buffer.as_string(), "fooa");
    }

    #[test]
    fn extra_commit_chars_option_contributes_globally() {
        let mut a = app_with("foo", 10);
        a.editor.modal = ModalState::Insert;
        a.editor.cursor = Position::new(0, 3);
        // Server says no commit chars; the global option
        // adds `,`.
        install_lsp_candidate_with_commit_chars(&mut a, "foo", Vec::new(), Position::new(0, 0));
        a.do_set("completion.extra_commit_chars=,");
        a.do_completion_accept_then_insert(',');
        assert!(a.editor.insert_completion.is_none());
        assert_eq!(a.editor.document.snapshot().buffer.as_string(), "foo,");
    }

    #[test]
    fn sync_candidate_honors_extra_commit_chars_only() {
        // A buffer-words candidate has no per-item commit
        // list (sync sources don't carry one). The global
        // extras still apply.
        let mut a = app_with("alpha bravo ", 10);
        a.editor.modal = ModalState::Insert;
        a.editor.cursor = Position::new(0, 12);
        a.do_completion_trigger();
        // Server-supplied list is empty for sync candidates;
        // set the global extras to include `;`.
        a.do_set("completion.extra_commit_chars=;");
        // Focus the `alpha` candidate (insert at cursor).
        if let Some(state) = a.editor.insert_completion.as_mut() {
            state.selected = state
                .rendered
                .iter()
                .position(|r| r.raw.text == "alpha")
                .expect("alpha");
        }
        a.do_completion_accept_then_insert(';');
        // Popup closed; `alpha` inserted then `;`.
        assert!(a.editor.insert_completion.is_none());
        let text = a.editor.document.snapshot().buffer.as_string();
        assert!(text.ends_with("alpha;"), "got `{text}`");
    }

    #[test]
    fn populate_insert_completion_sync_drops_disabled_source() {
        // Inject a per-language override that limits rust to
        // snippets only -> buffer-words emit is suppressed even
        // though the buffer is full of word-completion fodder.
        let mut a = app_with("foo bar baz qux quux ", 10);
        a.editor.modal = ModalState::Insert;
        a.editor.cursor = Position::new(0, 21);
        // Pretend the active language is rust by overriding
        // the `rust` slot. (Test buffer has no path so
        // active_language_id() returns ""; insert that as the
        // key directly to land the override.)
        a.editor.per_language_completion.insert(
            String::new(),
            lattice_completion::PerLanguageOverrides {
                sources: Some(vec![lattice_completion::SourceId::new(
                    lattice_completion::SNIPPET_SOURCE_ID,
                )]),
                ..Default::default()
            },
        );
        a.do_completion_trigger();
        // Popup either closed (no candidates) or has only
        // snippet items. Buffer-words mustn't appear.
        if let Some(state) = a.editor.insert_completion.as_ref() {
            for cand in &state.rendered {
                let src = cand.raw.source.as_ref().map(|s| s.as_str()).unwrap_or("");
                assert_ne!(
                    src,
                    lattice_completion::BufferWordsSource::ID,
                    "buffer-words filtered out",
                );
            }
        }
    }

    // ---- M.3.0: built-in major modes registered at boot ----

    // ---- M.3.1: ReadOnly option flows from major modes ----

    #[test]
    fn document_buffer_active_mode_is_text_mode() {
        // Plain document with no path ⇒ Lang::Plain ⇒ text-mode.
        let a = app_with("hi", 5);
        let buf = a.editor.document_buffer_id;
        let active = a
            .editor
            .active_modes
            .get(&buf)
            .expect("active_modes populated");
        assert_eq!(active.major(), Some(lattice_mode::TextMode::mode_id()));
    }

    // ---- M.3.2.b.1: help-mode locals seeded at construction ----

    #[test]
    fn renderer_reads_help_data_through_buffer_locals() {
        // M.3.2.c.5: BufferLocals are the canonical owner of help
        // per-buffer state -- the HelpBuffer struct no longer
        // carries `links` / `anchors` / `highlights` fields. Open
        // a help buffer (which seeds two parsed links into
        // locals), then mutate the locals; readers must reflect
        // the mutation since there's no struct-field fallback.
        let mut a = app_with("hi", 5);
        let help = crate::help::HelpContent::from_lines(
            "test-render",
            vec!["[link-a](command:a) and [link-b](command:b)".into()],
        );
        let help_id = a.open_help_in_pane(help);

        let synthetic = crate::modes::HelpLinks(vec![crate::help::HelpLink {
            range: lattice_protocol::position::Range::new(
                lattice_protocol::position::Position::ZERO,
                lattice_protocol::position::Position::new(0, 5),
            ),
            target: crate::help::HelpLinkTarget::Unresolved("synthetic".into()),
        }]);
        a.editor
            .buffer_locals
            .get_mut(&help_id)
            .expect("locals seeded")
            .insert(synthetic);

        let _ = a.popup_help().expect("popup_buffer set");
        let locals = a
            .editor
            .buffer_locals
            .get(&help_id)
            .expect("locals seeded by open_help_in_pane");
        let from_locals = locals.get::<crate::modes::HelpLinks>().unwrap();
        assert_eq!(from_locals.0.len(), 1);
        assert_eq!(
            from_locals.0[0].target,
            crate::help::HelpLinkTarget::Unresolved("synthetic".into())
        );
    }

    #[test]
    fn help_buffer_gets_markdown_syntax_handle() {
        // PU.1b-1 (2A): `register_help_document` attaches a live
        // markdown `SyntaxHandle` so the cells worker builds the help
        // `DisplayMatrix` from grammar — the seam that lets help render
        // through `compose_pane_lines` like any document. Bespoke
        // renderers still paint this slice, so the attach is invisible;
        // here we just assert the handle is present.
        let mut a = app_with("hi", 5);
        let help = crate::help::HelpContent::from_lines(
            "syntax-check",
            vec!["# Title".into(), "body text".into()],
        );
        let help_id = a.open_help_in_pane(help);
        assert!(
            a.editor.document_syntax_for(help_id).is_some(),
            "help buffer should carry a markdown SyntaxHandle after register_help_document"
        );
    }

    #[test]
    fn help_in_pane_seeds_link_extra_highlights() {
        // PU.1b-2b: opening help whose content has a link seeds the
        // link-only spans into `ExtraHighlights` so the cells worker
        // merges `Style::Link` into the help `DisplayMatrix` — the
        // grammar can't, since the `[label](target)` markup is stripped
        // before it parses.
        let mut a = app_with("hi", 5);
        let help_id = a.open_help_in_pane(crate::help::HelpContent::from_lines(
            "links",
            vec!["see [rust](mode:rust) docs".into()],
        ));
        let extra = a
            .editor
            .buffer_locals
            .get(&help_id)
            .and_then(|l| l.get::<crate::modes::ExtraHighlights>())
            .map(|e| e.0.clone())
            .unwrap_or_default();
        assert!(
            extra
                .iter()
                .flatten()
                .any(|s| s.style == lattice_syntax::Style::Link),
            "help link must seed a Style::Link span into ExtraHighlights for the matrix merge"
        );
    }

    #[test]
    fn help_in_pane_swap_reseeds_links_and_syntax() {
        // PU.1b-2b: a same-title re-open swaps the help content in place
        // (reuses the buffer id) and routes through
        // `seed_help_metadata_locals`, which re-seeds `ExtraHighlights`
        // AND re-attaches the markdown SyntaxHandle from the NEW text —
        // so the matrix's link styling + grammar colour stay fresh across
        // swaps (link-follow / `<C-o>` take the same re-seed path).
        let mut a = app_with("hi", 5);
        let id1 = a.open_help_in_pane(crate::help::HelpContent::from_lines(
            "topic",
            vec!["[one](mode:rust)".into()],
        ));
        let id2 = a.open_help_in_pane(crate::help::HelpContent::from_lines(
            "topic",
            vec!["plain".into(), "[two](mode:zig) tail".into()],
        ));
        assert_eq!(
            id1, id2,
            "same-title re-open swaps in place (reuses the help buffer id)"
        );
        let extra = a
            .editor
            .buffer_locals
            .get(&id2)
            .and_then(|l| l.get::<crate::modes::ExtraHighlights>())
            .map(|e| e.0.clone())
            .unwrap_or_default();
        let has_link = |line: usize| {
            extra
                .get(line)
                .map(|v| v.iter().any(|s| s.style == lattice_syntax::Style::Link))
                .unwrap_or(false)
        };
        assert!(!has_link(0), "after swap, line 0 (plain) carries no link");
        assert!(has_link(1), "after swap, line 1 carries the new link");
        assert!(
            a.editor.document_syntax_for(id2).is_some(),
            "syntax handle re-attached against the swapped-in text"
        );
    }

    // ---- M.3.2.c.2: file-tree-mode locals seeded + readers ----

    // ---- M.3.2.c.3: oil-mode locals seeded ----

    #[test]
    fn list_registers_with_no_state_says_so() {
        let mut a = app_with("hello", 10);
        submit_ex(&mut a, "reg");
        let msg = a.editor.last_message.as_ref().unwrap();
        assert!(msg.text.contains("no registers"));
    }

    #[test]
    fn list_registers_includes_unnamed_and_zero() {
        let mut a = app_with("hello world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.yank.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.word_forward,
                lattice_grammar::Args::None,
            ),
        );
        a.apply(Action::Invoke(inv));
        submit_ex(&mut a, "reg");
        let msg = a.editor.last_message.as_ref().unwrap();
        assert!(msg.text.contains("\"\""));
        assert!(msg.text.contains("\"0"));
    }

    #[test]
    fn list_marks_with_no_marks_says_so() {
        let mut a = app_with("hello", 10);
        submit_ex(&mut a, "marks");
        let msg = a.editor.last_message.as_ref().unwrap();
        assert!(msg.text.contains("no marks"));
    }

    #[test]
    fn list_marks_shows_set_marks() {
        let mut a = app_with("hello\nworld", 10);
        a.editor.cursor = Position::new(1, 2);
        a.apply(Action::SetMark('a'));
        submit_ex(&mut a, "marks");
        let msg = a.editor.last_message.as_ref().unwrap();
        assert!(msg.text.contains('a'));
        // Line 2 (1-indexed for display) at byte 2.
        assert!(msg.text.contains("2:2"));
    }

    #[test]
    fn global_delete_matching_lines() {
        let mut a = app_with("foo\nbar\nfoo\nbaz", 10);
        submit_ex(&mut a, "g/foo/d");
        // Both "foo" lines deleted; "bar" and "baz" remain.
        assert_eq!(a.editor.document.text(), "bar\nbaz");
    }

    #[test]
    fn vglobal_delete_non_matching_lines() {
        let mut a = app_with("foo\nbar\nfoo\nbaz", 10);
        submit_ex(&mut a, "v/foo/d");
        // Only "foo" lines remain.
        assert_eq!(a.editor.document.text(), "foo\nfoo");
    }

    #[test]
    fn global_substitute_on_matching_lines() {
        let mut a = app_with("foo\nbaz\nfoo", 10);
        submit_ex(&mut a, "g/foo/s/foo/X/");
        // Both "foo" lines get substituted.
        assert_eq!(a.editor.document.text(), "X\nbaz\nX");
    }

    #[test]
    fn global_no_matches_emits_error() {
        let mut a = app_with("hello\nworld", 10);
        submit_ex(&mut a, "g/xyz/d");
        let msg = a.editor.last_message.as_ref().unwrap();
        assert_eq!(msg.level, EchoLevel::Error);
    }

    #[test]
    fn capital_w_skips_punctuation() {
        let mut a = app_with("foo,bar baz", 10);
        a.apply(invoke_motion(a.editor.builtins.big_word_forward));
        assert_eq!(a.editor.cursor, Position::new(0, 8));
    }

    #[test]
    fn fold_action_clears_partial_chord() {
        let mut a = app_with("a\nb\nc", 10);
        a.apply(Action::AbsorbPartialChord(crate::chord::KeyChord::char(
            'z',
        )));
        a.apply(Action::OpenFoldAtCursor);
        assert!(a.editor.partial_chord.is_empty());
    }

    #[test]
    fn yank_with_named_register_stores_into_named_and_unnamed() {
        let mut a = app_with("hello world", 10);
        a.apply(Action::SelectRegister(Register::Named('a')));
        let inv = CommandInvocation::of(a.editor.builtins.yank.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.word_forward,
                lattice_grammar::Args::None,
            ),
        );
        a.apply(Action::Invoke(inv));
        // Named slot populated.
        let named = a.editor.registers.get(&Register::Named('a')).unwrap();
        assert_eq!(named.content, "hello ");
        // Unnamed also populated.
        assert_eq!(
            a.editor.unnamed_register.as_ref().unwrap().content,
            "hello "
        );
        // Pending register consumed.
        assert!(a.editor.pending_register.is_none());
    }

    #[test]
    fn yank_auto_populates_zero_register() {
        let mut a = app_with("hello world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.yank.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.word_forward,
                lattice_grammar::Args::None,
            ),
        );
        a.apply(Action::Invoke(inv));
        let zero = a.editor.registers.get(&Register::Numbered(0)).unwrap();
        assert_eq!(zero.content, "hello ");
    }

    #[test]
    fn yank_does_not_record_last_change() {
        let mut a = app_with("hello world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.yank.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.word_forward,
                lattice_grammar::Args::None,
            ),
        );
        a.apply(Action::Invoke(inv));
        // Yank doesn't mutate the buffer; dot-repeat shouldn't pick this up.
        assert!(a.editor.last_change.is_none());
    }

    #[test]
    fn change_records_last_change() {
        let mut a = app_with("hello world", 10);
        let inv = CommandInvocation::of(a.editor.builtins.change.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.word_forward,
                lattice_grammar::Args::None,
            ),
        );
        a.apply(Action::Invoke(inv));
        // change drops to Insert, but the change itself is recorded.
        assert!(a.editor.last_change.is_some());
    }

    #[test]
    fn capital_f_jumps_backward() {
        let mut a = app_with("hello, world", 10);
        a.editor.cursor = Position::new(0, 11); // on 'd'
        let inv = CommandInvocation::of(a.editor.builtins.find_char_backward.0)
            .with_args(lattice_grammar::Args::Char('h'));
        a.apply(Action::Invoke(inv));
        assert_eq!(a.editor.cursor, Position::ZERO);
    }

    fn app_in_command_mode(line: &str) -> App {
        let mut a = app_with("xx", 10);
        a.editor.modal = ModalState::Command;
        a.editor.set_command_line_text(line);
        a
    }

    #[test]
    fn dismiss_completion_keeps_command_line_intact() {
        let mut a = app_in_command_mode("descri");
        a.apply(Action::CommandLineCompleteOrAdvance);
        a.apply(Action::CommandLineDismissCompletion);
        assert_eq!(a.editor.command_line(), "descri");
        assert!(a.editor.completion_state.is_none());
    }

    #[test]
    fn clear_with_open_popup_widens_to_all_commands() {
        let mut a = app_in_command_mode("descri");
        a.apply(Action::CommandLineCompleteOrAdvance);
        let narrow_count = a.editor.completion_state.as_ref().unwrap().candidates.len();
        a.apply(Action::CommandLineClear);
        assert!(a.editor.completion_state.is_some());
        assert_eq!(a.editor.command_line(), "");
        let widened = a.editor.completion_state.as_ref().unwrap().candidates.len();
        assert!(widened >= narrow_count);
    }

    #[test]
    /// DK.2: a token whose sequence is still a PREFIX stays on the line.
    ///
    /// `<C-w>` is the prefix here on purpose. A token that COMPLETES a
    /// sequence now submits immediately (the trie ends capture, not `<CR>`),
    /// so asserting on the command line after a bound chord would race the
    /// cmdline closing — which is what this test used to do with `<C-c>`.
    fn append_chord_concatenates_token() {
        let mut a = app_in_command_mode("describe-key ");
        a.apply(Action::CommandLineAppendChord("<C-w>".into()));
        assert_eq!(a.editor.command_line(), "describe-key <C-w>");
    }

    /// Multi-stroke chords (`<C-w>j`) still accumulate token by token; only
    /// the token that completes the sequence ends capture.
    #[test]
    fn append_chord_supports_multi_token_sequences() {
        let mut a = app_in_command_mode("describe-key ");
        a.apply(Action::CommandLineAppendChord("<C-w>".into()));
        assert_eq!(
            a.editor.command_line(),
            "describe-key <C-w>",
            "the prefix alone must not submit"
        );
        a.apply(Action::CommandLineAppendChord("j".into()));
        assert!(
            matches!(a.editor.modal, ModalState::Normal),
            "`<C-w>j` is a complete sequence, so capture submits it"
        );
    }

    #[test]
    fn close_last_pane_is_a_noop_with_warning() {
        let mut a = app_with("xx", 10);
        a.apply(Action::ClosePane);
        assert_eq!(a.editor.pane_tree.len(), 1);
        let msg = a.editor.last_message.as_ref().expect("warn echo");
        assert!(msg.text.contains("only one pane"));
    }

    #[test]
    fn dismiss_focused_hover_restores_doc_cursor() {
        // Esc / q in State B routes to HelpDismiss, which restores
        // the pre-State-B cursor / scroll on the doc.
        let mut a = app_with("fn main() {}\nlet x = 1;\n", 5);
        a.editor.cursor = lattice_protocol::Position::new(1, 4);
        a.do_open_hover("hover body");
        a.apply_effect(lattice_grammar::Effect::Lsp(
            lattice_grammar::LspRequest::Hover,
        )); // -> State B (5.5.LSP.1)
        // Move inside the popup.
        let inv = lattice_grammar::CommandInvocation::of(a.editor.builtins.line_down.0);
        a.apply(Action::Invoke(inv));
        assert!(matches!(a.editor.active_buffer, BufferKind::Help));
        // Dismiss.
        a.apply(Action::HelpDismiss);
        assert!(a.editor.popup_buffer.is_none());
        assert!(matches!(a.editor.active_buffer, BufferKind::Document));
        assert_eq!(a.editor.cursor, lattice_protocol::Position::new(1, 4));
        assert!(a.editor.prev_pane_for_popup.is_none());
    }

    #[test]
    fn opening_help_in_pane_swaps_document_and_preserves_underlying_syntax() {
        // Help opened in a pane is a real buffer switch, NOT a popup overlay
        // over the underlying document: the active pane is Help, the floating
        // overlay is suppressed (`render.rs` `active_pane_kind != Help`), so the
        // pane paints `self.document` — which must therefore FOLLOW the help
        // buffer, exactly as Messages / Multibuffer / Oil / FileTree do. When it
        // did not, a `:help` / `:describe-*` split rendered the buffer help
        // replaced instead of the help content ("describe-in-split shows the
        // previous buffer").
        //
        // The underlying document must not LOSE its syntax across the switch:
        // `activate_help_in_pane` -> `load_active_pane` ->
        // `snapshot_active_document` stashes it into the document's
        // buffer-locals while `active_buffer` is still Document, and the round
        // trip back restores it — the same invariant
        // `dismissing_tree_preserves_document_syntax_state` checks for the tree.
        let mut a = app_with("fn main() {}\n", 10);
        a.editor.terminal_width = Some(80);
        attach_test_syntax(&mut a, lattice_syntax::Lang::Rust);
        assert!(a.editor.syntax.is_some(), "fixture syntax wired");
        let doc_id = a
            .editor
            .buffers
            .document_ids_sorted()
            .first()
            .copied()
            .unwrap();
        // Open a help buffer in pane (mimics `:lsp-log rust`).
        let help_id =
            a.open_help_in_pane(HelpContent::from_lines("lsp:rust", vec!["log line".into()]));
        assert!(matches!(a.editor.active_buffer, BufferKind::Help));
        // The active document now IS the help buffer — the pane renders help,
        // not the buffer it replaced. This is what failed before the fix.
        assert_eq!(
            a.editor.document_buffer_id, help_id,
            "the active document must follow the help buffer so the pane paints \
             help content, not the underlying buffer"
        );
        // Round-trip back to the document: its syntax survived the switch.
        a.activate_document(doc_id);
        assert!(matches!(a.editor.active_buffer, BufferKind::Document));
        assert!(
            a.editor.syntax.is_some(),
            "syntax must survive the help-in-pane round trip"
        );
    }

    #[test]
    fn dismissing_tree_preserves_document_syntax_state() {
        // Regression: opening `:Tree` and pressing `q` to dismiss
        // it returned to the document with `self.editor.syntax = None`,
        // so the renderer fell back to plain text (no
        // colours). Cause: the on-tree-open snapshot moved syntax
        // into the document entry, then activate_document on
        // dismiss called snapshot_active_document again and
        // overwrote the entry's stashed syntax with None.
        let dir = std::env::temp_dir().join(format!("lattice-tree-syntax-{}", std::process::id()));
        std::fs::create_dir_all(&dir).ok();
        let mut a = app_with("fn main() {}\n", 10);
        a.editor.terminal_width = Some(80);
        // Wire up a Rust syntax instance so there's something to lose.
        attach_test_syntax(&mut a, lattice_syntax::Lang::Rust);
        // Open the tree, then dismiss.
        a.editor
            .set_command_line_text(&format!("Filetree {}", dir.display()));
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert!(matches!(
            a.editor.active_buffer,
            crate::buffers::BufferKind::FileTree
        ));
        // `:TreeClose` (the path `q` takes in the tree).
        a.editor.set_command_line_text("FiletreeClose");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert!(matches!(
            a.editor.active_buffer,
            crate::buffers::BufferKind::Document
        ));
        assert!(
            a.editor.syntax.is_some(),
            "syntax must survive the tree round-trip"
        );
        std::fs::remove_dir_all(&dir).ok();
    }

    #[test]
    fn close_tree_pane_keeps_tree_in_registry() {
        // Trees now live in the unified buffer registry; closing
        // the only pane that referenced one leaves the tree
        // accessible via `:bn` / `:bp` / `:b N`. Use `:bd` to
        // actually drop it.
        let dir = std::env::temp_dir().join(format!("lattice-tree-gc-{}", std::process::id()));
        std::fs::create_dir_all(&dir).ok();
        let mut a = app_with("xx", 10);
        a.editor.terminal_width = Some(80);
        a.apply(Action::SplitPaneVertical);
        a.apply(Action::NavigatePane(PaneDirection::Right));
        a.editor
            .set_command_line_text(&format!("Filetree {}", dir.display()));
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert_eq!(a.editor.buffers.file_tree_ids_sorted().len(), 1);
        a.apply(Action::ClosePane);
        // Tree stays in the registry post-close.
        assert_eq!(a.editor.buffers.file_tree_ids_sorted().len(), 1);
        std::fs::remove_dir_all(&dir).ok();
    }

    #[test]
    fn bdelete_closes_active_buffer_and_picks_a_successor() {
        let path = write_temp_file("e", "alpha\n");
        let mut a = app_with("xx", 10);
        let initial_id = a.editor.document_buffer_id;
        a.editor
            .set_command_line_text(&format!("e {}", path.display()));
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        // Now active = new buffer; delete it. Successor should
        // be initial_id.
        a.editor.set_command_line_text("bd");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        assert_eq!(a.editor.document_buffer_id, initial_id);
        // Listed-count: only the original document remains in the
        // user-facing cycle; the synthetic `*lsp*` is unlisted.
        assert_eq!(a.editor.buffers.listed_ids_sorted().len(), 1);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn bdelete_only_buffer_is_rejected() {
        let mut a = app_with("xx", 10);
        a.editor.set_command_line_text("bd");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        // The listed count gates the "only buffer" check.
        // Synthetic unlisted buffers (`*lsp*`, ...) don't count as
        // switch destinations, so the rejection still fires when
        // only one user-listed buffer remains.
        assert_eq!(a.editor.buffers.listed_ids_sorted().len(), 1);
        let msg = a.editor.last_message.as_ref().expect("error echo");
        assert!(msg.text.contains("only buffer"));
    }

    #[test]
    fn opening_new_file_seeds_folds_for_indent_foldmethod() {
        // foldmethod=indent on the initial buffer; then `:e <new>`
        // should populate folds for the new buffer without requiring
        // a manual `<C-l>` redraw.
        let path = write_temp_file(
            "activate-folds-indent",
            "a:\n    x\n    y\nb:\n    p\n    q\n",
        );
        let mut a = app_with("xx", 10);
        a.set_foldmethod_for_test(FoldMethod::Indent);
        a.editor
            .set_command_line_text(&format!("e {}", path.display()));
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        // The new buffer should have folds without `<C-l>`.
        assert!(
            !a.editor.folds.is_empty(),
            "expected folds to be seeded on activation, got empty"
        );
        assert!(
            a.editor.folds.iter().any(|f| f.start_line == 0),
            "expected a fold starting at line 0: {:?}",
            a.editor.folds
        );
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn docs_toggle_pulls_body_from_cached_metadata_documentation() {
        let mut a = app_with("xx", 10);
        a.editor.modal = ModalState::Insert;
        a.editor.cursor = Position::ZERO;
        // Seed popup state with a single LSP candidate that
        // already has documentation cached.
        let mut state = lattice_completion::InsertCompletionState::open(
            lattice_completion::CompletionTrigger::Manual,
            Position::ZERO,
            Position::ZERO,
            String::new(),
        );
        let meta = super::LspCompletionMeta {
            label: "foo".into(),
            insert_text: "foo".into(),
            filter_text: None,
            sort_text: None,
            detail: Some("fn foo() -> i32".into()),
            documentation: Some("Returns 42.".into()),
            kind: Some(lattice_lsp::lsp_types::CompletionItemKind::FUNCTION),
            deprecated: false,
            preselect: false,
            commit_characters: Vec::new(),
            additional_text_edits: Vec::new(),
            command: None,
            insert_text_format: lattice_lsp::lsp_types::InsertTextFormat::PLAIN_TEXT,
            replace_range: None,
            server_id: "test-server".to_string(),
            original_item: lattice_lsp::lsp_types::CompletionItem::default(),
            resolved: true,
        };
        let mut raw = lattice_completion::RawCandidate::plain(
            "foo",
            lattice_completion::CandidateKind::Plain,
        );
        raw.display = "foo".into();
        raw.data = lattice_completion::CandidateData::Extension {
            kind_id: super::LSP_COMPLETION_KIND_ID,
            payload: lattice_lsp::completion::encode_meta(&meta),
        };
        let scored = lattice_completion::ScoredCandidate {
            raw,
            score: lattice_completion::MatchScore(100),
            match_ranges: Vec::new(),
        };
        state
            .rendered
            .push(lattice_completion::RenderedCandidate::from_scored(scored));
        // CSM.8b.5: candidate payload IS the meta -- no sidecar push.
        let _ = meta;
        a.editor.insert_completion = Some(state);
        a.do_completion_toggle_docs();
        let body = a
            .editor
            .insert_completion
            .as_ref()
            .and_then(|s| s.doc_popup.as_ref())
            .and_then(|d| d.body.clone())
            .expect("body populated");
        assert!(body.contains("fn foo() -> i32"));
        assert!(body.contains("Returns 42."));
    }

    #[test]
    fn docs_toggle_a_second_time_closes_popup() {
        let mut a = app_with("xx", 10);
        a.editor.modal = ModalState::Insert;
        a.editor.cursor = Position::ZERO;
        a.editor.insert_completion = Some(lattice_completion::InsertCompletionState::open(
            lattice_completion::CompletionTrigger::Manual,
            Position::ZERO,
            Position::ZERO,
            String::new(),
        ));
        a.do_completion_toggle_docs();
        // Even with no candidate, the popup opens with an
        // empty body slot. Toggling again closes it.
        let was_open = a
            .editor
            .insert_completion
            .as_ref()
            .map(|s| s.doc_popup.is_some())
            .unwrap_or(false);
        assert!(was_open);
        a.do_completion_toggle_docs();
        let now_closed = a
            .editor
            .insert_completion
            .as_ref()
            .map(|s| s.doc_popup.is_none())
            .unwrap_or(true);
        assert!(now_closed);
    }

    #[test]
    fn docs_scroll_clamps_at_zero_and_advances_by_eight() {
        let mut a = app_with("xx", 10);
        a.editor.modal = ModalState::Insert;
        a.editor.cursor = Position::ZERO;
        a.editor.insert_completion = Some(lattice_completion::InsertCompletionState::open(
            lattice_completion::CompletionTrigger::Manual,
            Position::ZERO,
            Position::ZERO,
            String::new(),
        ));
        a.do_completion_toggle_docs();
        // Default scroll is 0; up clamps at 0.
        assert_eq!(
            a.editor
                .insert_completion
                .as_ref()
                .and_then(|s| s.doc_popup.as_ref())
                .map(|d| d.scroll),
            Some(0)
        );
        a.apply(Action::CompletionDocsScrollUp);
        assert_eq!(
            a.editor
                .insert_completion
                .as_ref()
                .and_then(|s| s.doc_popup.as_ref())
                .map(|d| d.scroll),
            Some(0)
        );
        a.apply(Action::CompletionDocsScrollDown);
        assert_eq!(
            a.editor
                .insert_completion
                .as_ref()
                .and_then(|s| s.doc_popup.as_ref())
                .map(|d| d.scroll),
            Some(8)
        );
        a.apply(Action::CompletionDocsScrollDown);
        assert_eq!(
            a.editor
                .insert_completion
                .as_ref()
                .and_then(|s| s.doc_popup.as_ref())
                .map(|d| d.scroll),
            Some(16)
        );
        a.apply(Action::CompletionDocsScrollUp);
        assert_eq!(
            a.editor
                .insert_completion
                .as_ref()
                .and_then(|s| s.doc_popup.as_ref())
                .map(|d| d.scroll),
            Some(8)
        );
    }

    #[test]
    fn follow_link_source_opens_file_at_line() {
        // `:describe-command :lsp-trace` (and similar) renders a
        // `[<source>](file:PATH:LINE)` link. Following it should
        // open the file via the multi-buffer machinery and
        // position the cursor at the requested line. Pre-fix this
        // arm just echoed "(file open arrives with multi-buffer)"
        // -- we already had multi-buffer; the placeholder was
        // stale.
        let path = std::env::temp_dir().join(format!("lattice-srclink-{}.rs", std::process::id()));
        std::fs::write(&path, "first\nsecond\nthird\nfourth\n").unwrap();
        let mut a = app_with("xx", 10);
        // Open a help buffer so the active modal/buffer state
        // matches what `FollowLink` expects.
        a.editor.set_command_line_text("help");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        // Build a synthetic source link inside the help buffer.
        // 1-based line number: line 3 in the file → cursor at
        // line index 2 in the buffer.
        let link = crate::help::HelpLink {
            range: lattice_protocol::Range::new(
                lattice_protocol::Position::ZERO,
                lattice_protocol::Position::new(0, 1),
            ),
            target: crate::help::HelpLinkTarget::Source {
                path: path.clone(),
                line: 3,
            },
        };
        // M.3.2.c.5: production reads route through buffer_locals;
        // seed the synthetic link there directly. The locals key
        // is the popup buffer's construction id (centred-popup
        // resolution rule).
        let buf_id = a.editor.popup_buffer.unwrap();
        // PU.1a: the focused help cursor is `editor.cursor`
        // (`popup_cursor` is the persisted stash). Zero both so
        // FollowLink reads the link at (0,0).
        a.editor.cursor = lattice_protocol::Position::ZERO;
        a.editor.popup_cursor = lattice_protocol::Position::ZERO;
        let mut existing_links = a
            .editor
            .buffer_locals
            .get(&buf_id)
            .and_then(|l| l.get::<crate::modes::HelpLinks>())
            .map(|l| l.0.clone())
            .unwrap_or_default();
        existing_links.push(link);
        a.editor
            .buffer_locals
            .entry(buf_id)
            .or_default()
            .insert(crate::modes::HelpLinks(existing_links));
        a.editor.active_buffer = BufferKind::Help;
        a.apply(Action::FollowLink);
        // The file should now be the active document.
        assert_eq!(a.editor.active_buffer, BufferKind::Document);
        let opened = a.editor.document.path().expect("active doc has a path");
        assert_eq!(opened, path);
        // Cursor at line index 2 (1-based 3 → 0-based 2).
        assert_eq!(a.editor.cursor.line, 2);
        // NOTE: a `PluginPush` history entry is pushed *before*
        // `do_edit` runs, but `do_edit`'s new-file branch clears
        // the position history (so a fresh buffer's `<C-o>` doesn't
        // walk into the previous buffer's positions). That means
        // cross-buffer jumps from FollowLink and from
        // `jump_to_lsp_location` currently lose their walk-back
        // entry. Per-buffer position history is queued as the
        // proper fix; for now this test asserts the open-and-jump
        // primary behaviour and lets the history side-effect
        // regress until that fix lands.
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn follow_link_source_clamps_line_past_eof() {
        let path =
            std::env::temp_dir().join(format!("lattice-srclink-clamp-{}.rs", std::process::id()));
        std::fs::write(&path, "only-line\n").unwrap();
        let mut a = app_with("xx", 10);
        a.editor.set_command_line_text("help");
        a.editor.modal = ModalState::Command;
        a.apply(Action::CommandLineSubmit);
        let link = crate::help::HelpLink {
            range: lattice_protocol::Range::new(
                lattice_protocol::Position::ZERO,
                lattice_protocol::Position::new(0, 1),
            ),
            target: crate::help::HelpLinkTarget::Source {
                path: path.clone(),
                line: 999,
            },
        };
        // M.3.2.c.5: production reads route through buffer_locals;
        // seed the synthetic link there directly. The locals key
        // is the popup buffer's construction id (centred-popup
        // resolution rule).
        let buf_id = a.editor.popup_buffer.unwrap();
        // PU.1a: the focused help cursor is `editor.cursor`
        // (`popup_cursor` is the persisted stash). Zero both so
        // FollowLink reads the link at (0,0).
        a.editor.cursor = lattice_protocol::Position::ZERO;
        a.editor.popup_cursor = lattice_protocol::Position::ZERO;
        let mut existing_links = a
            .editor
            .buffer_locals
            .get(&buf_id)
            .and_then(|l| l.get::<crate::modes::HelpLinks>())
            .map(|l| l.0.clone())
            .unwrap_or_default();
        existing_links.push(link);
        a.editor
            .buffer_locals
            .entry(buf_id)
            .or_default()
            .insert(crate::modes::HelpLinks(existing_links));
        a.editor.active_buffer = BufferKind::Help;
        a.apply(Action::FollowLink);
        // Out-of-range line should clamp to the last valid line,
        // not panic and not echo a confusing error.
        let last_line = a
            .editor
            .document
            .snapshot()
            .buffer
            .content_line_count()
            .saturating_sub(1);
        assert_eq!(a.editor.cursor.line, last_line);
        let _ = std::fs::remove_file(path);
    }

    #[test]
    fn yank_then_paste_round_trips_word() {
        let mut a = app_with("hello world", 10);
        let yank = CommandInvocation::of(a.editor.builtins.yank.0).with_target(
            lattice_grammar::Target::Motion(
                a.editor.builtins.word_forward,
                lattice_grammar::Args::None,
            ),
        );
        a.apply(Action::Invoke(yank));
        // Move cursor to end of buffer.
        a.editor.cursor = Position::new(0, 11);
        a.apply(Action::PasteAfter);
        assert_eq!(a.editor.document.text(), "hello worldhello ");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn open_lsp_log_in_pane_renders_per_server_records() {
        // Slice B: per-server log lives as a Document in the
        // registry; records arrive through the event-bus drain
        // (`drain_lsp_log_events`) rather than a snapshot rebuild.
        // B'.4: use cwd-backed instance so it matches
        // `resolve_lsp_instance_for("rust")`'s no-actor fallback.
        let mut app = app_with("hi\n", 5);
        let instance = lattice_lsp::InstanceKey::new(
            std::sync::Arc::<str>::from("rust"),
            std::sync::Arc::<std::path::Path>::from(
                std::env::current_dir()
                    .unwrap_or_else(|_| std::path::PathBuf::from("/"))
                    .as_path(),
            ),
        );
        app.editor.lsp_logger.log(
            Some(&instance),
            lattice_lsp::LogLevel::Warn,
            lattice_lsp::LogSource::Stderr,
            "compile error",
        );
        // `open_lsp_log_in_pane` drains queued events first so the
        // buffer reflects pre-existing records.
        app.open_lsp_log_in_pane("rust");
        // Wait for LspServerLogMode's tokio task to drain the
        // pre-open record.
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        let log_id = app
            .editor
            .buffers
            .by_name(&lattice_lsp::lsp_server_log_name(&instance))
            .expect("per-instance log buffer registered");
        assert_eq!(app.active_pane_buffer_id(), log_id);
        let body = app
            .editor
            .buffers
            .document_handle(log_id)
            .expect("log buffer is a Document")
            .text();
        assert!(body.contains("compile error"), "got `{body}`");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn open_lsp_log_in_pane_excludes_trace_records() {
        let mut app = app_with("hi\n", 5);
        let instance = lattice_lsp::InstanceKey::new(
            std::sync::Arc::<str>::from("rust"),
            std::sync::Arc::<std::path::Path>::from(
                std::env::current_dir()
                    .unwrap_or_else(|_| std::path::PathBuf::from("/"))
                    .as_path(),
            ),
        );
        app.editor.lsp_logger.enable_trace(instance.clone());
        app.editor.lsp_logger.log(
            Some(&instance),
            lattice_lsp::LogLevel::Trace,
            lattice_lsp::LogSource::Trace,
            "→ Request id=1",
        );
        app.editor.lsp_logger.log(
            Some(&instance),
            lattice_lsp::LogLevel::Info,
            lattice_lsp::LogSource::Client,
            "lifecycle",
        );
        app.open_lsp_log_in_pane("rust");
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        let log_id = app
            .editor
            .buffers
            .by_name(&lattice_lsp::lsp_server_log_name(&instance))
            .expect("per-instance log buffer registered");
        let body = app.editor.buffers.document_handle(log_id).unwrap().text();
        // Trace records route to the trace buffer; non-trace
        // records (including lifecycle) land here.
        assert!(!body.contains("→ Request"), "got `{body}`");
        assert!(body.contains("lifecycle"), "got `{body}`");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn open_lsp_trace_log_in_pane_shows_only_trace_records() {
        let mut app = app_with("hi\n", 5);
        let instance = lattice_lsp::InstanceKey::new(
            std::sync::Arc::<str>::from("rust"),
            std::sync::Arc::<std::path::Path>::from(
                std::env::current_dir()
                    .unwrap_or_else(|_| std::path::PathBuf::from("/"))
                    .as_path(),
            ),
        );
        app.editor.lsp_logger.enable_trace(instance.clone());
        app.editor.lsp_logger.log(
            Some(&instance),
            lattice_lsp::LogLevel::Trace,
            lattice_lsp::LogSource::Trace,
            "→ Request id=1",
        );
        app.editor.lsp_logger.log(
            Some(&instance),
            lattice_lsp::LogLevel::Info,
            lattice_lsp::LogSource::Client,
            "lifecycle",
        );
        app.open_lsp_trace_log_in_pane("rust");
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        let trace_id = app
            .editor
            .buffers
            .by_name(&lattice_lsp::lsp_server_trace_log_name(&instance))
            .expect("per-instance trace buffer registered");
        let body = app.editor.buffers.document_handle(trace_id).unwrap().text();
        // Trace records here; non-trace records routed to the
        // matching `*lsp:rust:<ws>*` buffer instead.
        assert!(body.contains("→ Request"), "got `{body}`");
        assert!(!body.contains("lifecycle"), "got `{body}`");
    }

    #[test]
    fn app_boot_registers_every_built_in_major_mode() {
        let a = app_with("hi", 5);
        // Foundation
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(lattice_mode::TextMode::mode_id())
        );
        // Languages (lattice-syntax)
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(lattice_syntax::RustMode::mode_id())
        );
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(lattice_syntax::PythonMode::mode_id())
        );
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(lattice_syntax::JavascriptMode::mode_id())
        );
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(lattice_syntax::MarkdownMode::mode_id())
        );
        // Buffer-kind majors (lattice-ui-tui)
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(crate::modes::HelpMode::mode_id())
        );
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(crate::modes::FileTreeMode::mode_id())
        );
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(crate::modes::OilMode::mode_id())
        );
        // LSP log majors (lattice-lsp)
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(lattice_lsp::modes::LspLogMode::mode_id())
        );
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(lattice_lsp::modes::LspTraceLogMode::mode_id())
        );
        assert!(
            a.editor
                .mode_registry
                .load()
                .is_registered(lattice_lsp::modes::LspServerLogMode::mode_id())
        );
    }

    #[test]
    fn open_file_tree_seeds_file_tree_locals() {
        // Construct a temp dir + file, open as a tree, confirm
        // the locals are populated.
        let tmp = std::env::temp_dir().join(format!("lattice-m3-2-c-2-{}", std::process::id()));
        let _ = std::fs::create_dir_all(&tmp);
        let f = tmp.join("file.txt");
        let _ = std::fs::write(&f, "hi");

        let mut a = app_with("hi", 5);
        // Drive via the production path. `do_open_file_tree`
        // constructs the FileTreeBuffer, calls
        // `seed_file_tree_locals`, inserts into the registry,
        // and activates the pane on it.
        a.do_open_file_tree(Some(tmp.clone()));
        let tree_id = a.active_pane_buffer_id();

        let locals = a
            .editor
            .buffer_locals
            .get(&tree_id)
            .expect("file-tree locals seeded");
        let root = locals
            .get::<crate::modes::FileTreeRoot>()
            .expect("FileTreeRoot local present");
        assert_eq!(root.0, tmp);
        let entries = locals
            .get::<crate::modes::FileTreeEntries>()
            .expect("FileTreeEntries local present");
        // At minimum the root row + the file row.
        assert!(entries.0.len() >= 2);
        // FileTreeNerdFonts seeded; concrete value matches
        // App's `theme.nerd_fonts` (we don't assert a specific
        // boolean since the theme default may evolve -- the
        // important contract is "the local exists post-seed").
        assert!(locals.get::<crate::modes::FileTreeNerdFonts>().is_some());

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn set_ui_nerd_fonts_reissues_open_file_tree_icons() {
        // Regression for the bug where toggling `ui.nerd_fonts` updated
        // the theme but left open trees showing the old palette.
        //
        // DL.4 moved WHERE that shows. The glyph used to be baked into
        // the rope, so the test asserted on the buffer text; icons are
        // virtual text now, so the rope holds names and the palette
        // flip has to re-publish the ICONS instead. The regression the
        // test guards is unchanged — flip the option, an open tree must
        // follow — only the surface it reads moved.
        let tmp =
            std::env::temp_dir().join(format!("lattice-tree-nerd-rerender-{}", std::process::id()));
        let _ = std::fs::create_dir_all(&tmp);
        std::fs::write(tmp.join("main.rs"), "").unwrap();

        let mut a = app_with("hi", 5);
        a.do_open_file_tree(Some(tmp.clone()));
        let tree_id = a.active_pane_buffer_id();

        // The rope is names — no glyph, either palette.
        let body = a
            .editor
            .buffers
            .document_handle(tree_id)
            .map(|h| h.snapshot().buffer.as_string())
            .unwrap();
        assert!(body.contains("main.rs"), "rope must hold the name: {body}");
        for glyph in ["\u{f1617} ", "· "] {
            assert!(
                !body.contains(glyph),
                "glyph {glyph:?} leaked into the rope: {body}"
            );
        }

        // Icons publish through `PendingInlays` and land in the local on
        // the next tick, exactly as in production.
        let icons = |a: &mut App| -> Vec<String> {
            let _ = a.editor.run_tick_pending();
            a.editor
                .buffer_locals
                .get(&tree_id)
                .and_then(|l| l.get::<lattice_host::modes::ExtraInlays>())
                .map(|e| e.0.iter().map(|r| r.text.clone()).collect())
                .unwrap_or_default()
        };

        let before = icons(&mut a);
        assert!(
            !before.is_empty(),
            "the tree must publish one icon per row before the toggle"
        );

        // Flip the typed option via the same path `:set` takes.
        submit_ex(&mut a, "set ui.nerd_fonts=on");

        let after = icons(&mut a);
        assert_ne!(
            before, after,
            "flipping ui.nerd_fonts must re-publish the tree's icons — an \
             open tree that keeps the old palette is the reported bug"
        );

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn follow_link_reads_link_from_buffer_locals() {
        // M.3.2.c.1: prove `do_help_follow_link` reads the
        // link data from `buffer_locals` (canonical), not the
        // HelpBuffer's struct field. We open a help buffer,
        // overwrite its locals with a synthetic link pointing
        // somewhere different than the buffer's actual links,
        // and verify FollowLink dispatches based on the
        // locals-side link.
        let mut a = app_with("xx", 10);
        let help = crate::help::HelpContent::from_lines(
            "test-locals-link",
            vec!["plain text -- no markdown link".into()],
        );
        let help_id = a.open_help_in_pane(help);

        // Replace the locals-side links with a synthetic
        // Topic link that the production reader should pick
        // up -- the HelpBuffer's own `links` is empty (no
        // markdown link in the source), so without the
        // locals-first read, FollowLink would say "no link
        // under cursor".
        let synthetic = crate::modes::HelpLinks(vec![crate::help::HelpLink {
            range: lattice_protocol::Range::new(
                lattice_protocol::Position::ZERO,
                lattice_protocol::Position::new(0, 5),
            ),
            target: crate::help::HelpLinkTarget::Topic("synthetic-topic".into()),
        }]);
        a.editor
            .buffer_locals
            .get_mut(&help_id)
            .expect("locals seeded")
            .insert(synthetic);

        a.editor.cursor = lattice_protocol::Position::new(0, 0);
        // `open_help_in_pane` already activates the pane on
        // the registered help buffer; FollowLink reads
        // `pane_tree.active().buffer_id` to look up locals.
        a.apply(Action::FollowLink);

        // The link target was `help:synthetic-topic`; the
        // FollowLink path routes Topic targets to
        // `:help <topic>`. The topic doesn't exist so we
        // expect an info echo about the topic; the key
        // assertion is "the link was found and dispatched"
        // which we observe via the message kind. If the
        // production path had read from the (empty) struct
        // field, the message would have been "no link under
        // cursor".
        let msg = a
            .editor
            .last_message
            .as_ref()
            .expect("echo set by FollowLink");
        assert!(
            !msg.text.contains("no link under cursor"),
            "production reader should have found the link via buffer_locals, \
             got message: {}",
            msg.text
        );
    }
}