lattice_host/

editor.rs

// The renderer-agnostic editor state.
//
// Phase 5.B.3 introduces [`Editor`] as the destination for
// the per-cluster field migration from
// `lattice-ui-tui::App`. See
// [`docs/dev/architecture/phase-5b-app-design.md`] for the
// Option-D → Option-E pivot that this struct realises:
//
// - The host owns the editor's state and logic in `Editor`.
// - Each renderer crate composes `Editor` into its own
//   concrete `App` wrapper alongside its renderer-specific
//   caches (`theme`, `pane_render_registry`, ...).
//
// Subsequent slices (5.B.4 onwards) relocate field clusters
// one at a time from `App` into `Editor`, moving the methods
// that touch only those fields into `impl Editor` here. Each
// per-cluster commit ships green: methods that still live in
// `impl App` access migrated fields via `self.editor.foo`;
// methods that have moved access them via `self.foo` (now an
// inherent method on `Editor`).
//
// The empty-now/grows-later shape is intentional: it lets
// the wrapper field `editor: Editor` get added to `App`
// before any field actually moves, giving every subsequent
// migration a target that already exists in the type
// system.

use std::collections::HashMap;
use std::path::PathBuf;

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

use std::sync::Arc;

use lattice_config::{ConfigRegistry, OptionOverrideSet, ResolvedOptions};
use lattice_core::ui::popup::PopupPlacement;
use lattice_grammar::ModalState;
use lattice_grammar::builtins::Builtins;
use lattice_help::topics::HelpTopicRegistryHandle;
use lattice_lsp::cache::{
    CodeActionOutcome, CodeActionRow, CompletionItemRow, CompletionOutcome,
    CompletionResolveOutcome, DocumentHighlightCache, FormatOutcome, HoverOutcome,
    LspCodeLensCache, LspDocumentColorCache, LspDocumentLinksCache, LspFoldsCache,
    LspInlayHintCache, LspNavKind, LspPullDiagnosticsCache, LspSelectionChain,
    LspSemanticTokensCache, ReferencesOutcome, RenameOutcome, SelectionRangeOutcome,
    SignatureHelpOutcome, SymbolsOutcome,
};
// Phase 5.8.AF.5 / Slice 3b.0–3b.5: `CodeLensOutcome`,
// `DocumentColorOutcome`, `DocumentHighlightOutcome`,
// `DocumentLinksOutcome`, `FoldingRangeOutcome`,
// `InlayHintOutcome`, `PullDiagnosticsOutcome`,
// `SemanticTokensOutcome` no longer imported -- their
// `pending_*_rx` fields retired (spawned tasks write directly
// via `PerBufferCache::insert_for` / `ArcSwapOption::store`).
use lattice_lsp::{DiagnosticsLayer, LspLogger, LspSupervisorHandle};
use lattice_mode::{
    ActiveModes, BufferLocals, GuardStoreHandle, ServiceRegistry, TickCallbackRegistration,
};
use lattice_picker::{Picker, PickerMruIndex};
use lattice_protocol::CancellationToken;
use lattice_protocol::Event;
use lattice_protocol::edit::EditDelta;
use lattice_runtime::{EventBus, MessagePushed, MessagesRing, SnapshotCache};
use lattice_syntax::{LangRegistry, SyntaxHandle};

use crate::action::{Action, EchoMessage};
use crate::actions::ActionIds;
use crate::buffer_registry::BufferRegistry;
use crate::buffers::BufferId;
use crate::chord::KeyChord;
use crate::dispatch::RendererSignal;
use crate::keymap_registry::{KeymapHandle, LayerId};
use crate::pane::PaneTree;
use crate::state::{
    CompletionState, LastFind, LastSearch, LastVisual, LivePickerQueryState, MacroRecording,
    OptionCache, PendingBlockInsert, PendingPickerAccept, PendingPickerInit, PositionEntry,
    PrevPaneState, ReplaceEntry, SearchLine, SubstitutePreview, TagStackEntry, UnnamedRegister,
};
use crate::versioned::Versioned;
use lattice_core::BufferKind;
use lattice_protocol::position::Position as ProtoPosition;

/// Cross-thread wake signal for the overlay worker.
///
/// Wraps `Arc<tokio::sync::Notify>` so `Editor` can keep its
/// `#[derive(Default)]` (Notify itself doesn't impl Default).
/// Cloning the wrapper clones the inner Arc — same notify
/// channel. `notify_one()` is fired at the tail of
/// `publish_render_state` so the worker re-evaluates inputs after
/// every state change without polling.
///
/// Phase 5.8.AF.5 / Slice X2; renamed from `HighlightWake` in
/// display-line B4.2 (the worker no longer makes highlights).
#[derive(Clone)]
pub struct OverlayWake(pub Arc<tokio::sync::Notify>);

/// 2026-05-26: invocation-runner function pointer. The host
/// registers one per [`lattice_mode::Mode`] whose
/// EP.6 (2026-08-11): where a references result should land.
///
/// One query, three surfaces. Kept as an enum rather than a bool
/// because a third case arrived within a day of the second — and a
/// bool that grew a "…or the error list" meaning would have been the
/// silent-wrong-terminus bug waiting to happen.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ReferencesTerminus {
    /// `gr` — the locations picker. The historical behaviour.
    #[default]
    Picker,
    /// `:lsp-references` — the editable multibuffer.
    View,
    /// `:lsp-references-to-error-list` — the core error list.
    ErrorList,
}

/// [`lattice_mode::Mode::invocation_runner`] returns `Some(id)`.
/// Returns `true` when the runner claimed the invocation,
/// `false` when [`Editor::run_invocation`] should fall through
/// to the grammar Action gate / `run_document_invocation` for
/// central dispatch.
pub type InvocationRunnerFn = fn(&mut Editor, lattice_grammar::CommandInvocation) -> bool;

impl Default for OverlayWake {
    fn default() -> Self {
        Self(Arc::new(tokio::sync::Notify::new()))
    }
}

impl std::fmt::Debug for OverlayWake {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("OverlayWake").finish_non_exhaustive()
    }
}

/// S2.1 (2026-05-26): wake signal for the cell-builder worker
/// (S2.2+). Same shape as [`OverlayWake`]: a `Notify` cloned
/// into [`Editor::cells_wake`] and a sibling clone held by the
/// worker task. `publish_render_state` fires `notify_one()`
/// after every dispatch tick so the worker re-evaluates inputs
/// from the latest published
/// [`crate::render_state::CellsRenderState`].
#[derive(Clone)]
pub struct CellsWake(pub Arc<tokio::sync::Notify>);

/// D.0a.1 (2026-05-29): wake signal for the
/// `virtual_rows_worker`. Sibling of `CellsWake`. Fired by
/// `publish_render_state` and by provider-state changes (e.g.,
/// `DiffSubsystem` after publishing new hunks). The worker
/// awaits via `notified()` and rebuilds the `VirtualRowMatrix`
/// off the UI thread.
#[derive(Clone)]
pub struct VirtualRowsWake(pub Arc<tokio::sync::Notify>);

impl Default for VirtualRowsWake {
    fn default() -> Self {
        Self(Arc::new(tokio::sync::Notify::new()))
    }
}

impl std::fmt::Debug for VirtualRowsWake {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("VirtualRowsWake").finish_non_exhaustive()
    }
}

impl Default for CellsWake {
    fn default() -> Self {
        Self(Arc::new(tokio::sync::Notify::new()))
    }
}

impl std::fmt::Debug for CellsWake {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CellsWake").finish_non_exhaustive()
    }
}

/// A minor mode whose active/inactive state is driven by a
/// predicate reading a shared, mode-owned session service —
/// reconciled on the active buffer each `sync_keymap_overlays`
/// cycle. Modes contribute these at boot so the generic
/// overlay-sync carries no subsystem-specific knowledge:
/// `active-snippet-mode` keys off the shared `SnippetSession`
/// (`lattice_snippet::snippet_active_predicate`). See
/// `feedback_mode_owns_its_surface`.
#[derive(Clone)]
pub struct SessionBackedMinor {
    /// `true` ⇒ the mode should be active on the **given buffer**.
    /// SN.3e: the predicate is buffer-scoped so a session live in one
    /// buffer never activates the mode in another; `sync_keymap_overlays`
    /// passes the buffer it is reconciling.
    pub active: std::sync::Arc<dyn Fn(lattice_core::BufferId) -> bool + Send + Sync>,
    /// The minor mode toggled by `active`.
    pub mode_id: lattice_mode::ModeId,
}

impl std::fmt::Debug for SessionBackedMinor {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // The predicate closure isn't Debug and is now buffer-scoped
        // (no buffer to evaluate against here); report the mode it
        // drives instead.
        f.debug_struct("SessionBackedMinor")
            .field("mode_id", &self.mode_id)
            .finish_non_exhaustive()
    }
}

/// I4 (openDiff) D-fix.1: the pane/buffer bookkeeping needed to tear a
/// programmatic side-by-side diff down cleanly — close the two transient diff
/// panes and return focus to the pane the `openDiff` was launched from (the
/// `:claude` terminal). Recorded by
/// [`Editor::open_programmatic_diff`](crate::dispatch), consumed by
/// `Editor::finish_programmatic_diff_panes` on `:diff-accept` / `:diff-reject`.
/// Keyed in [`Editor::programmatic_diff_panes`] by the session's primary
/// (proposed / right) `BufferId`.
#[derive(Debug, Clone)]
pub struct ProgrammaticDiffPanes {
    /// The pane that was active when `openDiff` fired (the `:claude` terminal
    /// pane). Focus returns here on resolve — Option A: claude stays put while
    /// the diff opens in transient panes to its right.
    pub origin_pane: lattice_core::ui::pane::PaneId,
    /// The transient baseline + proposed panes opened for the diff; both closed
    /// on resolve. The `origin_pane` is never in this list.
    pub diff_panes: Vec<lattice_core::ui::pane::PaneId>,
    /// The throwaway in-memory baseline + proposed buffers; removed from the
    /// registry on resolve so they don't linger in `:ls`.
    pub diff_buffers: Vec<lattice_core::BufferId>,
    /// D-fix.6: the IDE-peer connection that opened this diff (its
    /// `ProgrammaticDiffRequest.origin_session`). A session-scoped close
    /// (`close_tab` / `closeAllDiffTabs` from that same connection) tears
    /// down only the diffs whose `origin_session` matches — so one agent
    /// session can never close another's diffs. `0` = no originating session
    /// (a non-IDE producer), matched by no connection's close.
    pub origin_session: u64,
}

/// MG.17b: a transient menu parked while its argument is being typed.
///
/// Carries everything needed to put the menu back exactly as it was —
/// including the parent stack, so an argument inside a submenu returns
/// you to that submenu rather than to the root.
#[derive(Debug, Clone)]
pub struct PendingTransientArgument {
    /// The menu to re-seat.
    pub spec: std::sync::Arc<lattice_picker::TransientSpec>,
    /// Its state, with the typed value written in on submit.
    pub state: lattice_picker::TransientState,
    /// Parent menus, so `BS` still walks back out after the round-trip.
    pub stack: Vec<(
        std::sync::Arc<lattice_picker::TransientSpec>,
        lattice_picker::TransientState,
        usize,
    )>,
    /// Which argument's value is being collected.
    pub name: String,
}

/// IM.7a — the drawing peer's cell geometry, in pixels.
///
/// Two numbers rather than a pane-width channel: combined with a pane's
/// column count (already published per pane) they give that pane's pixel
/// width, which is what `lattice_media::block_geometry` needs alongside the
/// line height.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CellMetrics {
    /// One display row's height in pixels — GPUI's `font_size * 1.3`.
    pub row_px: f32,
    /// One column's advance in pixels.
    pub col_px: f32,
}

/// Renderer-agnostic editor state.
///
/// The renderer-agnostic half of every editor App. Each
/// renderer's `App` struct composes one of these alongside
/// its renderer-specific caches. Host-level code (mode
/// lifecycle, dispatch, picker sources, LSP supervisor, ...)
/// takes `&mut Editor` directly; renderer-side code takes
/// `&mut App` and reaches the editor via `app.editor`.
///
/// **Field set grows per-cluster.** Each 5.B.x slice
/// migrates a logical cluster of fields here from
/// `lattice-ui-tui::App`. As clusters land, this struct
/// accumulates state; in parallel, `App`'s direct field set
/// shrinks. When the migration completes, every renderer-
/// agnostic field on App lives here, every renderer-agnostic
/// method on App lives in this crate's `impl Editor` blocks,
/// and App becomes a thin wrapper holding `editor: Editor`
/// plus renderer-specific caches only.
///
/// **Clusters landed so far:**
/// - 5.B.4 -- macro recording state (`macros`,
///   `macro_recording`, `last_played_macro`).
/// - 5.B.5 -- marks + registers (`marks`, `registers`,
///   `pending_register`, `unnamed_register`).
/// - 5.B.6 -- position history + tag stack
///   (`position_history`, `position_history_cursor`,
///   `recent_files`, `tag_stack`, `pending_tag_origin`).
/// - 5.B.7 -- search state (`search_line`, `last_search`,
///   `current_match`, `all_matches`, `substitute_preview`).
/// - 5.B.8 -- vim repeat + visual state (`pending_count`,
///   `op_count`, `visual_anchor`, `last_change`,
///   `last_visual`, `last_find`).
/// - 5.B.9 -- replace + insert state (`replace_history`,
///   `last_insert`, `recording_insert`,
///   `pending_block_insert`).
/// - 5.B.10 -- popup (subset) (`popup_buffer`,
///   `prev_pane_for_popup`, `popup_placement`). Skipped:
///   `popup_back_stack` -- holds `PopupSnapshot` which still
///   lives in `lattice-ui-tui::app::popup`; follow-up slice
///   moves the snapshot type to host before migrating the
///   field.
/// - 5.B.11 -- cmdline + echo (`command_line`,
///   `last_message`, `messages`,
///   `pending_message_event_rx`, `pending_redraw`,
///   `command_history`, `command_history_cursor`,
///   `command_history_pending`, `auto_submit_after_chord`).
/// - 5.B.12 -- syntax (`lang_registry`, `syntax`,
///   `last_parsed_text_version`, `pending_syntax_edits`,
///   `last_synced_syntax_version`, `visible_highlights`,
///   `pane_highlights`). Skipped:
///   `visible_highlights_key` -- its type
///   `VisibleHighlightsKey` lives in
///   `lattice-ui-tui::app::highlights` with `pub(super)`
///   visibility; follow-up slice promotes it to host first.
/// - 5.B.13 -- picker (`picker`, `picker_registry`,
///   `picker_mru`, `picker_mru_path`,
///   `pending_picker_init`, `live_picker_query`,
///   `previewing`). Picker support types (`PendingPickerInit`,
///   `LivePickerQueryState`, `InFlightLiveQuery`,
///   `LIVE_PICKER_DEBOUNCE`) also moved from
///   `lattice-ui-tui::app` to `lattice_host::state`.
/// - 5.B.14 -- config + modes (`config`, `option_cache`,
///   `mode_registry`, `services`, `mode_guards`,
///   `active_modes`, `buffer_locals`, `resolved_options`,
///   `buffer_local_overrides`, `option_change_rx`,
///   `help_topics`, `host_theme`).
/// - 5.B.15 -- modal + dispatch (`modal`, `partial_chord`,
///   `registry`, `event_bus`, `builtins`, `action_ids`,
///   `keymap`, `completion_popup_layer`).
/// - 5.B.16 -- active-pane state (subset) (`cursor`,
///   `scroll`, `should_quit`, `viewport_height`,
///   `terminal_width`, `active_buffer`,
///   `document_buffer_id`, `buffers`). Skipped:
///   `document`, `snapshot_cache`, `pane_tree` --
///   their types have no natural `Default` (actor handles +
///   tree-with-root invariants). Follow-up slice removes
///   `#[derive(Default)]` from `Editor` in favour of an
///   `Editor::new(...)` constructor so these can migrate.
/// - 5.B.17 -- LSP per-buffer caches (`lsp_progress`,
///   `lsp_selection_chain`, `lsp_selection_chain_index`,
///   `lsp_document_highlights`,
///   `last_document_highlight_issue_cursor`,
///   `lsp_folds_cache`, `lsp_inlay_hints_cache`,
///   `lsp_document_links_cache`, `lsp_code_lens_cache`,
///   `lsp_document_color_cache`,
///   `lsp_semantic_tokens_cache`,
///   `lsp_pull_diagnostics_cache`).
/// - 5.B.18 -- all remaining LSP fields: subsystem handles
///   (`lsp`, `lsp_diagnostics`, `lsp_logger`, plus
///   `lsp_log_event_rx`, `lsp_progress_event_rx`,
///   `lsp_config_tree`, `buffer_uris`), server-initiated
///   channels (`pending_apply_edit_rx`,
///   `pending_show_message_request_rx`,
///   `lsp_pending_show_message_requests`,
///   `lsp_show_message_request_queue`,
///   `lsp_next_show_message_request_id`), and all per-
///   feature request channels (the `pending_*_rx` /
///   `pending_*_token` pairs for hover, definition,
///   references, symbols, format, signature-help,
///   completion, moniker, rename, code-action,
///   selection-range, document-highlight, folding-range,
///   document-links, code-lens, document-color, inlay-hint,
///   semantic-tokens, pull-diagnostics, plus the refresh
///   channels and the lifecycle / detach channels).
///   `LspSupervisorHandle` and `DiagnosticsLayer` gained
///   placeholder `Default` impls (dropped-receiver
///   channels; production overwrites in `boot.rs`).
///   `lsp_file_watcher` stays on App for now: its inner
///   type `LspFileWatcher` lives in `lattice-ui-tui::app::
///   lsp_watcher` -- migrates with a follow-up that moves
///   the watcher into a host module.
/// - 5.B.19 -- call-site migration for all LSP per-feature
///   request channel fields scaffolded in 5.B.18: updated
///   all `self.pending_*` / `app.pending_*` accesses in
///   `app/lsp.rs`, `app/boot.rs`, `app/picker.rs`,
///   `app/mode.rs`, `app/completion.rs` to
///   `self.editor.pending_*`; removed the now-redundant
///   duplicate declarations from `App`. Completion cluster
///   (`completion_registry`, `completion_state`,
///   `insert_completion`, etc.) stays on App -- next slice.
/// - 5.B.20 -- completion cluster tail + popup back-stack +
///   pending config bucket. `insert_completion`,
///   `snippet_registry`, `insert_completion_snippet_meta`,
///   `completion_accept_freq`, `per_language_completion`,
///   `completion_in_path_context`, `active_snippet`,
///   `snippet_dirs`, `popup_back_stack` (popup #7 tail), and
///   `pending_config_structural_sections` move from `App`
///   to `Editor`. `SnippetCandidateMeta` moved from
///   `lattice-ui-tui::app` to `lattice-host::state` so
///   the sidecar type lives next to the field that owns it;
///   `lattice-ui-tui::app` re-exports the type for
///   compatibility. After this slice the only fields left on
///   `App` are the renderer-specific caches (`theme`,
///   `pane_render_registry`) plus the `LspFileWatcher`
///   wrapper -- `App` becomes a thin renderer wrapper.
#[derive(Debug, Default)]
pub struct Editor {
    /// Perf plan B.4: identity-preserving sub-state cache for
    /// `build_render_state`. Cached `Arc<SubState>` slots keyed
    /// by the `u64` version captured from the corresponding
    /// `Versioned<T>` field. `std::sync::Mutex` (not `RefCell`)
    /// because `Editor` is shared across threads as `Arc<Editor>`
    /// and therefore must be `Sync`; uncontested in practice
    /// because only `build_render_state` (called on the actor
    /// thread) takes the lock. See
    /// [`crate::render_state::PublishCache`] for the slot
    /// inventory and rebuild contract.
    pub publish_cache: std::sync::Mutex<crate::render_state::PublishCache>,

    /// Completed macro recordings keyed by register name.
    /// Replays go through the dispatch layer's `PlayMacro`
    /// action handler. v1 records `Action` streams; insert-
    /// mode keystrokes ARE captured (every Action::Insert is
    /// recorded), but dot-repeat-style replay of insert content
    /// from `c`/`i`/`a` remains a §15 follow-up.
    pub macros: HashMap<char, Vec<Action>>,
    /// In-flight macro recording. `Some` while between
    /// `q<reg>` start and the matching `q` stop; pushed
    /// Actions append to `actions`.
    pub macro_recording: Option<MacroRecording>,
    /// The most recently played macro register, for `@@`
    /// repeat.
    pub last_played_macro: Option<char>,
    /// Unnamed register -- destination of `y` / `d` / `c`,
    /// source of `p` / `P`. `None` until something has been
    /// yanked.
    pub unnamed_register: Option<UnnamedRegister>,
    /// User-set marks. v1 stores them flat by name (a-z,
    /// A-Z, 0-9); uppercase / numbered global marks treat
    /// all marks as buffer-local since the v1 TUI runs
    /// against a single document.
    pub marks: HashMap<char, Position>,
    /// Named registers `"a-z`, `"A-Z`, numbered `"0-"9`,
    /// etc. Stores content + kind. `""` (the unnamed
    /// register) is [`Self::unnamed_register`]; this map
    /// covers everything else.
    pub registers: HashMap<Register, UnnamedRegister>,
    /// YR.1: every yank and every delete, newest first. Distinct from
    /// `registers`, which is addressed by name — this is addressed by
    /// recency, and it is what the yank picker lists and what YR.2's
    /// `"0`–`"9` projection reads.
    pub yank_ring: crate::state::YankRing,
    /// Register selected for the next operator / paste
    /// (`"a` prefix). Consumed-and-cleared by `run_invocation`
    /// (operators) and `do_paste` (paste). `None` means use
    /// unnamed.
    pub pending_register: Option<Register>,
    /// Unified position-history ring (DESIGN.md §5.1.1).
    /// Every entry is tagged by source so different keybindings
    /// walk filtered views of the same data (`Ctrl-O` / `Ctrl-I`
    /// walk `AutoJump` + `PluginPush`; `g;` / `g,` walk
    /// `NamedMark`).
    pub position_history: Vec<PositionEntry>,
    /// Cursor into [`Self::position_history`] -- the next entry
    /// the navigation action would visit.
    pub position_history_cursor: usize,
    /// CM.2 (2026-07-22): the error list — a persistent,
    /// cross-file list of navigable locations walked by generic
    /// `:cnext` / `]q` dispatch. Core/host state shaped like
    /// [`Self::position_history`], NOT owned by any mode:
    /// compilation (CM.3), diagnostics, and search are *producers*
    /// that populate it via [`Self::set_error_list`]. See
    /// `docs/dev/architecture/compilation-mode.md` §3.
    pub error_list: crate::error_list::ErrorList,
    /// CM.3c (2026-07-22): per-buffer severity gutter index for the
    /// `*compilation*` buffer, keyed by [`lattice_core::BufferId`].
    /// Written by the `AppEffect::CompilationGutterSet` arm (the
    /// off-thread compilation drain's host-state seam) and snapshotted
    /// into `RenderState::compilation_severity` at publish. Shaped like a
    /// producer-fed cache (compilation is the only producer today); the
    /// outer `Arc` lets the publish clone be O(1) and the inner
    /// per-buffer `Arc<Vec<..>>` lets the renderer read wait-free.
    pub compilation_severity: std::sync::Arc<
        std::collections::HashMap<
            lattice_core::BufferId,
            std::sync::Arc<Vec<(u32, lattice_mode::GutterSeverityLevel)>>,
        >,
    >,
    /// CM.3c (2026-07-22): per-buffer compilation location-line
    /// index for theme-based highlighting. Twin of
    /// `compilation_severity` above. Written by the
    /// `AppEffect::CompilationLocationLines` arm and snapshotted
    /// into `RenderState::compilation_location_lines` at publish.
    /// The outer `Arc` lets the publish clone be O(1) and the
    /// inner per-buffer `Arc<Vec<(u32,u32,u32)>>` lets the renderer read
    /// wait-free.
    pub compilation_location_lines: std::sync::Arc<
        std::collections::HashMap<lattice_core::BufferId, std::sync::Arc<Vec<(u32, u32, u32)>>>,
    >,
    /// MC.2b: per-buffer set of source lines inside a fenced/indented code
    /// block, for the full-width `syntax.code_block` background tint. Recomputed
    /// from the syntax tree in `recompute_folds_because` (the same reparse-driven
    /// trigger folds ride) and snapshotted into `RenderState::code_block_lines`.
    /// Outer `Arc` = O(1) publish clone; inner per-buffer `Arc` = wait-free read.
    pub code_block_lines:
        std::sync::Arc<std::collections::HashMap<lattice_core::BufferId, std::sync::Arc<Vec<u32>>>>,
    /// MG.21a (2026-07-29): per-buffer diff sign maps published by a
    /// *mode*, for buffers whose content is itself a unified diff.
    /// Written by the `AppEffect::DiffLineSigns` arm and merged into
    /// `RenderState::diff.sign_maps` by `diff_sign_maps_by_buffer`, so
    /// the existing line-tint path in both renderers picks them up
    /// unchanged.
    ///
    /// Kept as a slot separate from the session-derived maps because the
    /// two have different lifetimes: a session map is recomputed as the
    /// user edits, while these are rewritten only when the mode
    /// regenerates the buffer. Sessions win on the (currently
    /// impossible) key collision — see `diff_sign_maps_by_buffer`.
    pub provider_diff_signs: std::sync::Arc<
        std::collections::HashMap<
            lattice_core::BufferId,
            std::sync::Arc<crate::diff::overlay::DiffSignMap>,
        >,
    >,
    /// CM.3d (2026-07-22): resolved `compilation.location` theme
    /// colours — published by the mode during activation so the TUI
    /// and GPUI renderers read from the theme rather than hardcoding
    /// RGB. `bg` is the location-line background tint; `fg` is the
    /// link-like file-path foreground. Defaults: surface2 bg, blue fg.
    pub compilation_theme_colors: std::sync::Arc<(u32, u32)>,
    /// MRU list of canonical paths the user has opened via
    /// `:edit` (or any path flowing through `do_edit`). Newest
    /// first; deduplicated; capped at `MAX_RECENT_FILES`. Source
    /// for the `:recent` picker.
    pub recent_files: Vec<PathBuf>,
    /// Vim-style tag stack (DESIGN.md §5.1.1 follow-up).
    /// Distinct from the jump list: each "drill-down" navigation
    /// (`gd` / `gD` / `gy` / `gI` and their multi-result picker
    /// accept variants) pushes one entry; `<C-t>` pops the most
    /// recent entry. `<C-o>` walks all jumps chronologically;
    /// `<C-t>` pops only the LIFO tag-style drill-downs.
    pub tag_stack: Vec<TagStackEntry>,
    /// Pre-jump origin captured when an LSP nav request fires;
    /// transferred to [`Self::tag_stack`] on the actual jump
    /// (single-result drain or multi-result picker accept).
    /// Cleared on picker dismiss / nav cancellation / drain
    /// with no results.
    pub pending_tag_origin: Option<TagStackEntry>,
    /// In-progress `/` or `?` search. `Some` only while
    /// `modal == ModalState::Search(_)`.
    pub search_line: Option<SearchLine>,
    /// The `action:*` name to fire on `<CR>` while a generic
    /// `Effect::OpenPrompt` prompt is focused (`modal ==
    /// ModalState::Prompt`). Set by `open_prompt_line`, consumed
    /// (`.take()`) by `do_prompt_line_submit`.
    pub pending_prompt_submit_action: Option<String>,
    /// OC.3a: the synthetic name the prompt was opened with, held so the
    /// submit can hand it back to the action.
    ///
    /// `open-prompt-payload.buffer-name` is documented as the channel a caller
    /// uses to "smuggle state through a multi-step flow", and a NATIVE handler
    /// reads it off the prompt buffer it is handed. A plugin action cannot: it
    /// receives a `buffer-id` over WIT and has no way to turn that into a name.
    /// So the host carries it back in the fired invocation's args instead —
    /// same channel, reachable from both sides.
    pub pending_prompt_buffer_name: Option<String>,

    /// MG.17b: the transient a prompt was opened *from*, held across
    /// the surface switch.
    ///
    /// A transient's `TransientState` already survives flag toggles —
    /// the `Flag` arm mutates it in place and the menu stays open, and
    /// the preview closure re-reads it every frame. What it cannot
    /// survive on its own is an `Argument`: the prompt is a different
    /// surface that takes the editing buffer and the modal state, so
    /// the picker is torn down and something has to own the menu until
    /// it can be re-seated. That is this.
    ///
    /// `Some` only between opening an argument's prompt and its submit
    /// or cancel.
    pub pending_transient_argument: Option<PendingTransientArgument>,
    /// Most recent submitted search; consulted by `n` / `N`.
    pub last_search: Option<LastSearch>,
    /// Range of the most recent search match, used to draw
    /// the primary highlight in the buffer view. Cleared on
    /// Esc and on cursor motion.
    pub current_match: Option<ProtoRange>,
    /// Every occurrence of the most recent search pattern,
    /// used to draw the secondary "hlsearch" overlay.
    /// Cleared on Esc; persists after submit until the next
    /// search.
    pub all_matches: Vec<ProtoRange>,
    /// In-progress substitute preview. Populated as the user
    /// types `:s/pat...`; the renderer overlays match ranges
    /// (and the typed replacement once the second `/` has
    /// been entered) so the user sees the substitution before
    /// pressing Enter. Cleared when the cmdline closes or the
    /// input no longer parses as a substitute (DESIGN.md
    /// §5.9.10).
    pub substitute_preview: Option<SubstitutePreview>,
    /// MB.4: live `:` command-line decorations — syntax spans, a
    /// validation error, and a parameter hint. Recomputed on every
    /// command-line edit (`refresh_command_line_decorations`, on the
    /// actor thread) and published into the modeline render state.
    /// `None` when the command line is closed / empty.
    pub command_line_decorations: Option<crate::excommand::CommandLineDecorations>,
    /// In-progress count prefix being typed (`3` of `3w`,
    /// `12` of `12dd`). 0 means "no count typed". The next
    /// `Action::Invoke` consumes this and resets it to 0.
    pub pending_count: u32,
    /// Count latched when an operator key was pressed (`2`
    /// of `2d3w`). Multiplied with the motion's count (`3`)
    /// to give the final count the operator dispatches with
    /// (`6`). 0 means "no operator count".
    pub op_count: u32,
    /// Anchor position when Visual mode was entered. `None`
    /// outside Visual; restored on Esc. The `head` of the
    /// selection follows the cursor; the anchor stays put so
    /// the selection extends or contracts as the user moves.
    pub visual_anchor: Option<Position>,
    /// Last operator-class invocation that mutated the
    /// buffer. `.` re-dispatches it from the current cursor.
    /// v1 records operator + motion / operator + range /
    /// Visual-mode operator; insert-mode text replay remains
    /// a §5.2.4 gap.
    pub last_change: Option<CommandInvocation>,
    /// Last Visual-mode selection extents, captured on exit
    /// so `gv` can re-enter Visual with the same anchor /
    /// head / kind.
    pub last_visual: Option<LastVisual>,
    /// Last f/F/t/T find on this buffer, for `;` / `,`.
    pub last_find: Option<LastFind>,
    /// Per-Replace-session log of overwritten bytes so
    /// backspace can restore the original (rather than
    /// deleting). Cleared on entry, pushed on each
    /// `OverwriteChar`, popped on `ReplaceUndoLast`.
    pub replace_history: Vec<ReplaceEntry>,
    /// IN.1: line that was auto-indented and has gained nothing
    /// since. Vim strips such indent when the line is left, so
    /// `o<Esc>` leaves no trailing whitespace on a line the user
    /// never typed into. Set by `note_auto_indent`, cleared by the
    /// first content typed into the line, consumed by
    /// `strip_pending_auto_indent` on leaving Insert.
    pub auto_indent_line: Option<u32>,
    /// RF.5: whether the `formatprg` deprecation note has been emitted
    /// this session.
    ///
    /// Once, not per format: a note repeated on every `:w` with
    /// `formatonsave` on is noise the user learns to scroll past, which
    /// is the opposite of what a deprecation notice is for.
    pub formatprg_deprecation_noted: bool,
    /// Text inserted during the most recently completed
    /// Insert session. Captured on Esc out of Insert;
    /// replayed by dot-repeat after the operator part. `None`
    /// if the last change had no insert phase.
    pub last_insert: Option<String>,
    /// In-flight blockwise-visual `I` / `A` session. Captured
    /// at mode-entry time (block extents + per-line insert
    /// column); consumed when Insert exits, at which point
    /// the recorded text is replicated to every line in the
    /// block other than the top row (the top row's insert is
    /// the recording itself). `None` outside a block-visual
    /// insert.
    pub pending_block_insert: Option<PendingBlockInsert>,
    /// Text being captured during the *current* Insert
    /// session. Promoted into [`Self::last_insert`] when
    /// leaving Insert.
    pub recording_insert: Option<String>,
    /// Active popup buffer slot, if a popup overlay is open.
    /// The concrete content lives in the [`crate::buffer_registry::BufferRegistry`]
    /// keyed by this id, flagged
    /// `BufferFlags { listed: false, hidden: true }`.
    pub popup_buffer: Option<BufferId>,
    /// Pane state captured before activating help -- used by
    /// `dismiss_popup` to restore the user to whatever buffer
    /// / cursor / scroll they came from. Set by the in-pane
    /// help activation path; cleared by dismiss.
    ///
    /// **Popup lifetime only.** The bury-back address for an
    /// in-pane synthetic buffer lives in [`Self::bury_target`]
    /// and is deliberately a different field -- see there.
    pub prev_pane_for_popup: Option<PrevPaneState>,
    /// The pane [`Editor::open_help_in_split`] created for a help buffer, when
    /// help was opened in its OWN split (not layered over an existing pane).
    /// `dismiss_popup` reads it to decide between CLOSING that pane (help
    /// brought it into being, so `<Esc>` removes it) and restoring the buffer
    /// an active-pane help displaced. `None` for popup / active-pane help and
    /// once the pane is gone. Cleared on dismiss.
    pub help_split_pane: Option<lattice_core::ui::pane::PaneId>,
    /// Where `Effect::BuryBuffer` (magit's `q`) returns the pane
    /// after an in-pane synthetic buffer is closed. Written by
    /// `open_synthetic_buffer_seeded`, consumed by
    /// [`Editor::bury_buffer`](crate::editor::Editor::bury_buffer).
    ///
    /// **Its own field because the two mechanisms have different
    /// lifetimes.** Both used to share `prev_pane_for_popup`, and
    /// whichever teardown ran first consumed whatever was in the
    /// slot regardless of who wrote it. Reported against
    /// org-capture: a transient menu was still up (State A) when
    /// the `*org-capture*` draft opened, so the draft's bury
    /// address landed in the shared slot; dismissing the menu
    /// then hand-restored the pane to the pre-capture buffer
    /// *without* going through `activate_buffer` -- silently,
    /// since only that function echoes. `C-c C-c`'s
    /// `Effect::BufferDelete` resolves its target from
    /// `active_pane_buffer_id()`, so it deleted the buffer the
    /// user came from and left the draft alive, unsaved and
    /// unreachable. MG.47 had patched one call site of this on
    /// the reasoning that a State-A popup "leaves
    /// `prev_pane_for_popup` as `None` -- so this guard cannot
    /// move the pane"; that holds only until something opens a
    /// synthetic buffer underneath the popup.
    ///
    /// See `crates/lattice-host/tests/a_popup_dismiss_must_not_move_the_pane.rs`.
    pub bury_target: Option<PrevPaneState>,
    /// Where the popup overlay sits on screen when one is
    /// open. Lives on the editor (not on the buffer) because
    /// the popup is a generic rectangular surface inside
    /// which any buffer kind renders -- placement is a
    /// property of the popup, not of whatever buffer happens
    /// to be its content.
    pub popup_placement: PopupPlacement,
    /// PU refactor (2026-07-22): decoupled focus-state bool,
    /// extracted from `active_buffer == BufferKind::Help` which
    /// was an architectural leak — a focus flag smuggled inside
    /// a content-identity field. `true` when a Steal popup has
    /// keyboard focus (State B). Set in `focus_help_popup`,
    /// `activate_help_in_pane`, `open_popup_buffer` (Steal);
    /// cleared in `dismiss_popup`. Published in render state so
    /// both TUI and GPUI renderers read it directly.
    pub popup_focused: bool,
    /// Cursor position snapshot at popup-open time, used as
    /// the anchor for `CursorAnchored` popups. Captured in
    /// `open_floating_popup` / `open_popup` BEFORE any cursor
    /// mutation so the renderer paints the popup at the
    /// symbol the user pressed K on, not the cursor's current
    /// position. Issue 2026-05-22 (third triage round): without
    /// this the popup follows the cursor — moving with motions
    /// rather than staying anchored. `None` when no popup is
    /// open OR for centered popups (anchor irrelevant).
    pub popup_anchor: Option<lattice_protocol::Position>,
    /// Document scroll captured at popup-open time so
    /// CursorAnchored renderers can convert `popup_anchor.line`
    /// to a screen row in State B (where `self.scroll` is the
    /// POPUP's scroll, not the document's).
    pub popup_doc_scroll_at_anchor: u32,
    /// PU.1a: the popup's persisted view state when it is NOT the
    /// focused buffer (State A), and the stash loaded into
    /// `self.scroll` / `self.cursor` when focus moves into the
    /// popup (State B). Replaces the old `HelpBuffer.{scroll,cursor}`
    /// registry fields now that help content is an actor-backed
    /// Document with no per-view cursor of its own. Reset to 0 /
    /// ZERO on every popup open; updated by `snapshot_active_pane`
    /// when an in-pane help buffer is stashed.
    pub popup_scroll: u32,
    pub popup_cursor: lattice_protocol::Position,
    /// PU.1b-3: inner-rect geometry of the floating popup overlay,
    /// fed back from the renderer each frame (mirrors the per-pane
    /// `set_pane_viewport` 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 `(height, width)` here. `build_cells_panes` reads them
    /// to size the synthetic popup-pane `DisplayMatrix` (wrap width =
    /// `popup_viewport_width`). Both 0 until the first feedback after a
    /// popup opens; the synthetic pane is gated on
    /// `popup_viewport_width > 0` so a zero-geometry frame is skipped
    /// (the renderer's plain-text fallback covers that one frame).
    pub popup_viewport_height: u32,
    pub popup_viewport_width: u32,
    /// PU.5c: the ephemeral registry buffer backing the Insert-mode
    /// completion-docs side popup. `None` when no docs are shown.
    /// Reconciled from `insert_completion.doc_popup.body` once per cycle
    /// (`reconcile_completion_docs_buffer` in `run_tick_pending`):
    /// created when docs appear, text-replaced when they change, and
    /// garbage-collected when they vanish — a single chokepoint instead
    /// of the scattered `insert_completion = None` teardown sites. It is a
    /// help-flavoured `BufferData::Help` Document with the `ephemeral`
    /// flag, so it reuses markdown syntax + link styling + the
    /// `nonu`/`signcolumn=no`/`wrap` help-mode options and renders through
    /// the shared compose seam (`PaneId::COMPLETION_DOCS`).
    pub completion_docs_buffer: Option<BufferId>,
    /// Picker live-preview reusable slot. A single ephemeral, read-only
    /// buffer the find-file (and other file-opening) picker previews load
    /// content into as the selection changes — instead of running the full
    /// `do_edit` open path per keystroke (which synchronously parses +
    /// attaches LSP + leaks a registry buffer per candidate, freezing the
    /// UI thread). `do_preview` reuses this one buffer; `do_edit` is
    /// reserved for the final accept. GC'd on picker dismiss.
    pub preview_buffer: Option<BufferId>,
    /// PU.5c: inner-rect geometry of the completion-docs side popup, fed
    /// back from the renderer each frame (the second synthetic popup, peer
    /// of `popup_viewport_*`). `build_cells_panes` reads them to size the
    /// `PaneId::COMPLETION_DOCS` matrix; the synthetic pane is gated on
    /// `completion_docs_viewport_width > 0`.
    pub completion_docs_viewport_height: u32,
    pub completion_docs_viewport_width: u32,
    /// WK.12: the minibuffer band's buffer — a popup opened with
    /// `PopupPlacement::MinibufferBand` lands HERE rather than in
    /// [`Self::popup_buffer`], and the two are independent: opening the band
    /// never dismisses a popup, which is the bug this slot exists to remove.
    /// Never focused, so it has no anchor, scroll or focus-stack frame.
    pub band_buffer: Option<BufferId>,
    /// Renderer-fed inner geometry for the band, exactly as
    /// `completion_docs_viewport_*` is fed. The synthetic
    /// `PaneId::MINIBUFFER_BAND` pane is gated on `band_viewport_width > 0`.
    pub band_viewport_height: u32,
    pub band_viewport_width: u32,
    /// VM.3g-1: vim's `curswant` — the column `j` / `k` aim for, which survives
    /// a short line in between. `None` until something sets one.
    pub curswant: Option<lattice_grammar::Curswant>,
    /// VM.3g-1: set when THIS dispatch was a motion that keeps or pins the goal
    /// column (`j` / `k` / `$`). Everything else — every other motion, every
    /// edit, Insert exit and yank — lets the dispatch tail set the goal from
    /// wherever the cursor ended up, which is vim's rule.
    pub curswant_claimed: bool,
    /// VM.3g-3: where a motion reports the goal column it AIMED at, when that
    /// is not the column it reached. Only `gj` / `gk` do: they aim at a screen
    /// column the landing display row may be too short to hold, and vim keeps
    /// the aim (measured: a clamped `gj` landing at column 100 records 160).
    ///
    /// A long-lived slot on the Editor rather than one built per dispatch
    /// because `dispatch_blocking` takes `&self` — it can clone this `Arc`
    /// into the `DispatchEnv` but cannot hand anything back. The dispatch tail,
    /// which has `&mut self`, `take()`s it.
    ///
    /// Taken rather than read: a motion writes it on every motion dispatch
    /// (`None` for all but two), but an operator or action never touches it,
    /// so leaving a value behind would let one `gj`'s aim resurface after an
    /// unrelated command.
    pub curswant_report: std::sync::Arc<std::sync::Mutex<Option<lattice_grammar::Curswant>>>,
    /// FS.1: the focus **stack** — one frame per surface that has taken
    /// focus away from the pane's own buffer, innermost last.
    ///
    /// MB.1 introduced this as a single `Option`, which was right while only
    /// one surface could hold focus: the `:` line, the `/` line, or a
    /// prompt. It is wrong the moment focus can nest, and it can — a popup
    /// holds focus, and `/` inside it takes focus again:
    ///
    /// ```text
    ///     []                       editing the file
    ///     [popup]                  the popup has focus
    ///     [popup, search-line]     …and `/` inside it
    /// ```
    ///
    /// As an `Option` the second push recorded nothing (it was guarded on
    /// `is_none()`) and one restore returned to the FILE, skipping the popup
    /// — which is how `<Esc>` out of a search left the editor focused
    /// nowhere. See `focused-surface.md` §2.
    ///
    /// [`Editor::focused_surface`] reads the top frame; use it rather than
    /// indexing, so "is something focused" and "what is focused" stay one
    /// question.
    pub focus_stack: Vec<crate::state::MinibufferFocus>,
    /// FS.2: the [`Self::focus_stack`] depth a focused popup sits at, so
    /// dismissing it unwinds any surface opened INSIDE it (a `/` line, a
    /// prompt) rather than leaving that focused over a popup that is gone.
    /// `None` whenever no popup holds focus.
    pub popup_focus_depth: Option<usize>,
    /// Most recent transient status / error message,
    /// displayed in the echo area until replaced.
    pub last_message: Option<EchoMessage>,
    /// Append-only chronological ring of every echo
    /// (`set_message` call). The `:messages` ex-command
    /// opens a `*messages*` buffer rendered from this ring
    /// (the emacs `*Messages*` analogue). Bounded by
    /// `MessagesRing::capacity`. Wrapped in `Arc<Mutex<>>`
    /// so the boot-installed `MessagesLayer` (a
    /// `tracing::Layer` running on whatever thread emitted
    /// the event) can push into the same ring the App reads
    /// on the main thread for backlog seeding.
    pub messages: std::sync::Arc<std::sync::Mutex<MessagesRing>>,
    /// Receiver for [`lattice_runtime::MessagePushed`] events
    /// published by `set_message`. The runtime's per-tick
    /// drain coalesces bursts and rebuilds the `*messages*`
    /// buffer view once per frame.
    pub pending_message_event_rx: Option<tokio::sync::mpsc::UnboundedReceiver<MessagePushed>>,
    /// Set by `Action::RedrawScreen` (`<C-l>`); the runtime
    /// clears this on its next frame after issuing a full
    /// terminal-clear so any leftover ANSI / stale glyph
    /// state gets repainted from scratch.
    pub pending_redraw: bool,
    /// Submitted `:` command history. Newest at the back.
    /// Bounded.
    pub command_history: Vec<String>,
    /// While in Command modal: index into
    /// [`Self::command_history`] of the entry currently
    /// shown (`None` = the user's in-progress text).
    pub command_history_cursor: Option<usize>,
    /// Snapshot of the user's typed `command_line` on the
    /// first Up so Down can return to it after walking
    /// through history.
    pub command_history_pending: Option<String>,
    /// MB.5b: search-line history (peer of `command_history`).
    /// Each submitted `/` or `?` pattern is pushed here;
    /// `<C-p>`/`<C-n>` walk this in the search line.
    pub search_history: Vec<String>,
    /// MB.5b: index into `search_history` during history walk.
    pub search_history_cursor: Option<usize>,
    /// MB.5b: user's typed pattern saved on first `<C-p>` so
    /// `<C-n>` can return to it.
    pub search_history_pending: Option<String>,
    /// Chord-capture overlay flag. Set when the user submitted
    /// a Chord-arg-required command with no value
    /// (`:describe-key<CR>` or the K.3.2 `<C-h>k` binding); the
    /// cmdline pre-fills with the command word + space and
    /// translation routes every key through
    /// `translate_command_chord_capture` so plain letters
    /// appear as chord tokens (`g` → `g`, `<C-c>` → `<C-c>`,
    /// `<Up>` → `<Up>`, ...). The renderer reads this through
    /// `auto_submit_hint` to draw the chord-capture cmdline
    /// hint. Reset on cancel / submit.
    ///
    /// K.3.5.fix (2026-06-03): the field's original purpose
    /// also included auto-submitting on the FIRST captured
    /// chord token — that auto-submit was dropped because
    /// chord arguments are sequences (`gg`, `<C-w>v`, `]e`,
    /// `<leader>fz`), not single chords. The user now types
    /// the full chord text and submits with `<CR>`. Field name
    /// kept for backward compat across the renderer / context
    /// boundaries; behavior is "chord-capture mode active,"
    /// no longer "auto-submit on chord."
    ///
    /// DK.2 (2026-09-07): the explicit `<CR>` is gone again, but not by
    /// reinstating auto-submit-on-first-chord. The trie decides —
    /// see [`Self::chord_capture_seq`].
    pub auto_submit_after_chord: bool,
    /// DK.2: the chords captured so far in the current chord-capture session.
    ///
    /// Capture has to accumulate a SEQUENCE (`gg`, `<C-w>v`, `<leader>fz`), so
    /// it cannot submit on the first keystroke; but making the user terminate
    /// with `<CR>` meant `<CR>` — and the `<Esc>` and `<BS>` reserved beside it
    /// — could never themselves be described. The keymap trie already
    /// distinguishes "waiting for more" (`Partial`) from "this is the answer"
    /// (`Bound` / `Unbound`) on every ordinary keystroke, so capture asks it
    /// instead of asking the user, and no key needs reserving.
    ///
    /// Parallel to the command line's TEXT rather than derived from it: the
    /// line also holds the command word and any earlier args, and re-parsing a
    /// chord argument back out of it would mean re-deriving the arg span on
    /// every keystroke to answer a question this vector answers directly.
    /// Cleared when a prompt arms, and on submit / dismiss.
    pub chord_capture_seq: Vec<lattice_protocol::chord::KeyChord>,
    /// Tree-sitter language registry. Services the document
    /// buffer's `Syntax` and every `HelpBuffer` constructed
    /// by `:describe-*` / `:apropos` / `:keymap` (help
    /// bodies render with markdown highlighting + fenced-
    /// block injections sourced from this same registry).
    pub lang_registry: Arc<LangRegistry>,
    /// Per-document tree-sitter state. `None` when the
    /// document's language is `Plain` (no grammar bundled).
    /// Reparses run on a worker task; reads against the
    /// latest snapshot are wait-free via `ArcSwap`.
    pub syntax: Option<SyntaxHandle>,
    /// `text_version` last sent to the syntax handle's
    /// reparse channel. Used to skip republishing identical
    /// state when no text mutation has happened since the
    /// previous frame.
    pub last_parsed_text_version: u64,

    /// Tree-sitter-shaped edit deltas accumulated since the
    /// last `maybe_reparse_syntax` call. Pushed by
    /// `publish_document_changed` after each
    /// `Buffer::apply_edit`; drained by
    /// `maybe_reparse_syntax` and shipped to the syntax
    /// worker as `Vec<EditDelta>` for incremental reparse.
    pub pending_syntax_edits: Vec<EditDelta>,
    /// `text_version` the syntax worker's tree is known to
    /// be at. Sent as `from_version` on the next reparse
    /// request so the worker can verify edits apply to the
    /// correct tree baseline.
    pub last_synced_syntax_version: u64,
    /// OWC: per-buffer text version last seen after a host-issued
    /// edit. Used to detect owner writes: when the active document's
    /// `text_version` exceeds this, the host did not issue the edit
    /// and should adopt the document's primary selection head.
    pub last_seen_text_version: HashMap<BufferId, u64>,
    /// LA.2: the `LanguagesRegistered` drain — a plugin whose load changed the
    /// mode/language catalog lands here, and `run_tick_pending` re-resolves the
    /// majors and languages of buffers that were opened against the old one.
    ///
    /// A channel rather than a flag, and drained here rather than acted on in
    /// the subscription, because the re-resolution needs `&mut Editor` and the
    /// bus forwarder runs on the runtime. `EventBus::publish_typed` calls the
    /// forwarder synchronously, so a publish is visible to the very next tick —
    /// the paired wake forwarder in `editor_boot` is what makes that tick
    /// happen without a keypress.
    ///
    /// `None` when nothing subscribed it (bare `Editor::default()` in tests);
    /// the drain is then a no-op.
    pub pending_catalog_change_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_plugin_loader::LanguagesRegistered>>,
    /// Pane tree (DESIGN.md §5.9). Always represents the
    /// ACTIVE tab's panes — when switching tabs we
    /// `mem::swap` between this field and `tabs[target].panes`.
    /// Perf plan B.4: wrapped in [`Versioned`] so the panes
    /// sub-state cache in `build_render_state` can reuse its prior
    /// `Arc<PanesRenderState>` when the tree hasn't moved since the
    /// last publish. `Deref` reads (e.g. `editor.pane_tree.active()`)
    /// do NOT bump; `DerefMut` accesses (split/close/set_active)
    /// fire one `u64` increment.
    pub pane_tree: Versioned<PaneTree>,

    /// Issue #29 (2026-05-22): tab pages. Each `TabSlot` carries
    /// one tab's pane tree + optional label. The active tab's
    /// `panes` field is a default placeholder while live — its
    /// real tree sits on `editor.pane_tree`. Inactive tabs hold
    /// the full stashed tree. Always non-empty; default boot
    /// state is one tab whose pane_tree matches `editor.pane_tree`.
    /// Perf plan B.4.b: wrapped in [`Versioned`] so the tabs
    /// sub-state cache can detect when the tab list shape changes
    /// (push / remove / reorder). The composite cache key for
    /// `tabs` also includes `active_tab`, `pane_tree.version()`,
    /// and `buffers.version()` because label resolution reads
    /// across all four inputs.
    pub tabs: Versioned<Vec<lattice_core::ui::tab::TabSlot>>,
    /// Index of the active tab in `tabs`. Always valid (clamped
    /// on tab close).
    pub active_tab: usize,

    /// Issue #32 (2026-05-22): override for the next picker
    /// accept's open routing. Set by `<C-s>` / `<C-v>` / `<C-t>`
    /// chords on picker overlays before dispatching the accept;
    /// read + cleared by `apply_picker_outcome` for the file-
    /// targeting variants (OpenFile / SwitchBuffer / JumpInBuffer
    /// / JumpToLocation). `Default` for `<CR>`.
    pub picker_open_target: lattice_picker::OpenTarget,
    /// YR.3: where a `FillCaller` accept should put its text, recorded
    /// when the picker was **opened**.
    ///
    /// Not resolved at accept: by then the picker has been dismissed and
    /// the modal state that identified the caller is gone, so resolving
    /// would read whatever context happens to be current. That is right
    /// often enough to pass a single-level test and wrong in exactly the
    /// picker-inside-a-prompt case this exists for.
    ///
    /// `None` means the picker was opened to act, not to answer, and a
    /// `FillCaller` arriving against it is a wiring bug the host reports
    /// rather than swallows.
    /// PC.1: the root the OPEN picker resolves against, overriding the active
    /// buffer's project until it closes.
    ///
    /// Beside its picker-scoped peers rather than threaded through
    /// `build_picker_context`, because a `live` source re-queries through
    /// `on_query_changed` — which sees the context and NOT the open's args — so
    /// the root has to outlive the single `init` call that carried it.
    ///
    /// `None` is the ordinary case: every picker before PC.1 resolved from the
    /// active buffer and still does.
    pub picker_root: Option<std::path::PathBuf>,
    pub picker_fill_target: Option<lattice_picker::FillTarget>,
    /// YR.6: the byte range on the `:` line a `FillCaller` should
    /// REPLACE rather than insert before.
    ///
    /// An argument picker is opened while the user is part-way through
    /// typing that argument (`:magit-checkout ma`), so the picked value
    /// has to take the place of `ma`. A plain insert — which is right
    /// for YR.5's `<C-r><C-r>`, where nothing was being replaced —
    /// would produce `mamain`, silently, and only for users who typed a
    /// prefix before opening the picker.
    ///
    /// Captured at open for the same reason the fill target is: by
    /// accept time the cursor has moved and the slot that identified
    /// the range is gone. `None` = insert at the cursor.
    pub picker_fill_replace: Option<(usize, usize)>,
    /// YR.5b: the picker the yank picker was opened *over*.
    ///
    /// `do_picker_accept` takes `self.picker` before applying the
    /// outcome, and `open_picker` replaces it — so without stashing, a
    /// yank picker opened from `:files` would destroy the `:files`
    /// picker on the way in and have nothing to fill on the way out.
    /// Restored both on accept (then filled) and on dismiss, because
    /// pressing Esc in the yank picker must return you to the list you
    /// were filtering rather than closing both.
    pub stashed_picker: Option<lattice_picker::Picker>,

    /// T.12a: the theme to restore if the colorscheme picker is
    /// dismissed (`<Esc>`). Captured on the FIRST live preview as a
    /// `(palette, overrides)` snapshot of the theme active when the
    /// picker opened. `<Esc>` calls `ThemeRegistry::set_theme` with
    /// these to undo the preview; `<CR>` clears it (keeps the
    /// previewed theme). `None` when no colorscheme preview is in flight.
    pub pending_theme_preview_restore: Option<(
        lattice_theme::Palette,
        Vec<(lattice_theme::ElementName, lattice_theme::StyleSpec)>,
    )>,

    /// Handle to the per-document actor (or, in M.1+, a
    /// composing multibuffer handle) and its snapshot cache.
    /// M.0: typed as the [`ActiveDocument`] newtype around
    /// `Arc<dyn Document>` so the slot can hold either a
    /// `RopeDocumentHandle` or a `MultibufferDocumentHandle`
    /// without kind-branching at the use site. `Default::
    /// default()` populates this with a placeholder rope
    /// handle whose actor is already gone — production code
    /// overwrites the slot before any traffic flows.
    pub document: lattice_runtime::ActiveDocument,
    pub snapshot_cache: SnapshotCache,

    // DR.2 (decoration-retention): the `pane_highlights` /
    // `pane_highlight_keys` inactive-pane span cache + its
    // `refresh_pane_highlights` producer were retired here. Inactive
    // panes now render from their own retained per-pane `DisplayMatrix`
    // (the cells worker builds one for every visible pane), the same
    // canonical producer the active pane uses — one producer, zero
    // decoration recompute on focus change. See
    // `docs/dev/architecture/decoration-retention.md`.
    /// Active picker overlay. `None` outside picker mode.
    pub picker: Option<Picker>,
    /// Manual folds. v1 supports non-nested folds defined by line range.
    pub folds: Vec<lattice_core::Fold>,
    /// D.3.f.0 (2026-05-29): fold-provider registry. Holds the
    /// five built-in `Primary` providers (Manual / Indent /
    /// Markdown / Syntax / Lsp) and the list of registered
    /// `Overlay` providers, which are mode-owned (DX.3-C7):
    /// `diff-mode`'s `HunkFoldSource`, multibuffer's excerpt +
    /// file-boundary sources, all registered via the
    /// `FoldOverlayService` on mode activation).
    /// See `docs/dev/architecture/fold-architecture.md`.
    /// M.7: shared behind `Arc<Mutex>` so `FoldOverlayServiceImpl`
    /// can call `add_overlay`/`remove_overlay` from mode-activation
    /// context (outside `&mut Editor`) without blocking the UI thread.
    pub fold_registry: std::sync::Arc<std::sync::Mutex<crate::fold_provider::FoldRegistry>>,

    /// BC.3b: boot-lifetime tick-callback registration tokens handed off from
    /// the `BootContext` via `into_registrations()`. A subsystem `install(boot)`
    /// that wires an off-keystroke `boot.inbound::<T>` drain (the first is the
    /// Claude Code IDE peer's write bus) produces an RAII token here; holding it
    /// for the editor's lifetime keeps the drain registered (dropping it would
    /// unregister the drain mid-session). Empty when no subsystem installs an
    /// inbound/tick drain at boot. Never read — held purely to keep the drains
    /// alive; the leading `_` documents that.
    pub _boot_tick_registrations: Vec<TickCallbackRegistration>,
    /// D.4.a (2026-05-29): scroll-binding pane groups. Each
    /// entry binds a set of `(pane, buffer)` pairs through a
    /// pluggable `RowMapper`; propagation runs at
    /// `publish_render_state` tail. Membership keyed on the
    /// pair so buffer changes within a pane suspend the
    /// binding automatically. Subsystems (diff D.4.d, future
    /// `:set scrollbind`, zen mode, `:windo`) add/drop their
    /// groups around lifecycle. See
    /// `docs/dev/architecture/pane-groups.md`.
    pub pane_groups: Vec<crate::pane_group::PaneGroup>,
    /// D.0b (2026-06-08): id of the singleton identity-mapper
    /// pane group that backs `:set scrollbind`. `None` when no
    /// panes currently have `scrollbind=true` (the group is
    /// dropped when the last member opts out). Rebuilt by
    /// `rebuild_scrollbind_group` on every `scrollbind`
    /// option-change cascade.
    pub scrollbind_group_id: Option<lattice_core::ui::pane::PaneGroupId>,
    /// D.8.e (2026-05-31): session key of the **singleton**
    /// `:diffthis` group, if any. `:diffthis` toggles per-buffer
    /// membership in this one group; other diff sessions
    /// (`:diffsplit`, AI-driven openDiff flows, future magit)
    /// run as independent `DiffSession`s and **don't** affect
    /// this field.
    ///
    /// State transitions (per
    /// `docs/dev/architecture/n-way-diff-membership.md` §6.2):
    /// - `None` → user runs `:diffthis` in any pane: create
    ///   N=1 dormant session keyed under the active buffer;
    ///   set this to `Some(active_buf)`.
    /// - `Some(g)` + active buffer not in g: extend the group
    ///   via `add_participant`; arity grows.
    /// - `Some(g)` + active buffer in g: shrink the group via
    ///   `remove_participant_buffer`; if arity drops to 0 the
    ///   subsystem auto-drops the session and this clears
    ///   back to `None`.
    pub diffthis_group: Option<lattice_core::BufferId>,
    /// D.8.e (2026-05-31): pane members corresponding to each
    /// participant of the diffthis group, in `:diffthis`-call
    /// order. The first entry is the pane the FIRST
    /// `:diffthis` invocation came from; subsequent entries
    /// are appended as the user invokes `:diffthis` in new
    /// panes. Used to construct / reshape the pane group when
    /// arity transitions across 2 (need scroll-bind +
    /// fillers).
    ///
    /// Cleared in lockstep with `diffthis_group` — both reset
    /// to empty / `None` when the group drops to arity 0.
    pub diffthis_members: Vec<crate::pane_group::PaneGroupMember>,
    /// Picker source registry -- `:picker` source kinds. Held behind
    /// `ArcSwap` (`PickerRegistryHandle`) so the plugin loader can register a
    /// loaded picker plugin's source at runtime by copy-on-write RCU while the
    /// picker-open path reads it wait-free (PL8.B). Shared as a service so
    /// `lattice-plugin-loader` reaches it without a host dep.
    pub picker_registry: lattice_picker::PickerRegistryHandle,
    /// Per-source MRU index that biases the picker's initial
    /// candidate ordering toward recently-accepted picks.
    pub picker_mru: PickerMruIndex,
    /// Optional on-disk persistence path for [`Self::picker_mru`].
    /// `None` for ephemeral / test installs.
    pub picker_mru_path: Option<PathBuf>,
    /// In-flight async picker init, if the active picker
    /// source's `init` returned a Future.
    pub pending_picker_init: Option<PendingPickerInit>,
    /// In-flight async picker accept, if the accepted source's
    /// `accept_async` returned a Future (a WASM plugin source).
    /// Its resolved outcome commits via
    /// `drain_pending_picker_accept`.
    pub pending_picker_accept: Option<PendingPickerAccept>,
    /// TR.2: in-flight async transient build, if the named menu's
    /// builder is guest-backed. Seated by
    /// `drain_pending_transient_build` on the async-landed wake — never
    /// by a keystroke, which is what makes a plugin menu open on the
    /// chord that asked for it.
    pub pending_transient_build: Option<crate::state::PendingTransientBuild>,
    /// Live-picker query state -- present only when the
    /// active picker source has `spec().live == true`.
    pub live_picker_query: Option<LivePickerQueryState>,
    /// CD.6a: the query the next picker to SEAT starts with, set by
    /// `Effect::OpenPicker { query }`. Consumed at seat for any source —
    /// unlike a live source's own seed, which only a live source has — and
    /// cleared if the open is refused.
    pub pending_picker_query: Option<String>,
    /// PI.1 (preview isolation): per-pane preview projection. A pane
    /// keeps its committed `PaneState.buffer_id`; the entry here (keyed
    /// by `PaneId`) records the buffer it currently *displays* plus the
    /// preview cursor / scroll. Baked into the published pane-tree
    /// leaves at `build_render_state` time so the renderers show the
    /// displayed buffer while `:ls` / modeline / dispatch read the
    /// committed one. Ephemeral: never persisted / snapshotted; cleared
    /// on accept / dismiss / selection-cleared. See
    /// `docs/dev/architecture/preview-isolation.md` §5 and
    /// [`crate::preview::PreviewOverride`].
    pub preview_overrides:
        std::collections::HashMap<lattice_core::ui::pane::PaneId, crate::preview::PreviewOverride>,
    /// PI.1: monotonic version bumped on every `preview_overrides`
    /// mutation. Folded into the panes-substate cache key (`panes_v`)
    /// so the published projection rebuilds when an override changes —
    /// the override lives outside `pane_tree.version()`.
    pub preview_overrides_version: u64,
    /// PBH.1: per-pane buffer history — the trail of buffers each pane
    /// has shown, walked with `<C-6>` / `<C-7>`.
    ///
    /// A **side table keyed by `PaneId`**, deliberately not a field on
    /// `PaneState`: that type is `Copy` and `PaneTree::split_active`
    /// copies it field-wise (`PaneState { id: PaneId::next(),
    /// ..new_state }`), so a history field there would be inherited by
    /// the split — the one behaviour this feature must not have.
    /// `PaneId::next()` is process-monotonic and never reuses ids, so
    /// a freshly split pane has no entry here and therefore starts with
    /// a fresh trail **by construction**, with nothing to remember to
    /// reset. Keeping it out of `PaneState` also keeps that type `Copy`,
    /// so split / close / layout stay allocation-free.
    ///
    /// Reaped by [`crate::dispatch::Editor::reconcile_pane_history`],
    /// which retains only ids still present in the tree rather than
    /// hooking each pane-removal site. See
    /// `docs/dev/architecture/pane-buffer-history.md` §4.
    pub pane_buffer_history: std::collections::HashMap<
        lattice_core::ui::pane::PaneId,
        crate::pane_history::PaneBufferHistory,
    >,
    /// PBH.3: set for the duration of a `<C-6>` / `<C-7>` walk so the
    /// buffer switch it performs is not recorded as a new visit.
    ///
    /// Without this the step back would push an entry, truncate the
    /// forward tail it was moving into, and make `<C-7>` permanently
    /// unreachable — the walk would eat its own future.
    pub(crate) walking_pane_history: bool,
    /// 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.
    /// User-set working directory (`:cd`). `None` falls back to
    /// `std::env::current_dir()` for path resolution.
    pub current_dir: Option<PathBuf>,
    pub config: Arc<ConfigRegistry>,
    /// Hot-path read cache for the option values.
    /// Repopulated by `rebuild_option_cache` after every
    /// `:set`. Accessor methods on App read this cached
    /// primitive directly (~1ns) instead of going through
    /// the registry's mutex + ArcSwap + downcast (~33ns).
    pub option_cache: OptionCache,
    /// Mode registry (M.1). Owns the catalogue of registered
    /// modes; activation / deactivation routes through here.
    pub mode_registry: lattice_mode::ModeRegistryHandle,
    /// SG.4a: the interned ids of the built-in signs (diagnostics + diff),
    /// registered into the sign registry at boot. The `builtin_element_ids`
    /// shape — a producer emitting a mark per visible line reads a field
    /// rather than hashing a name per line.
    pub builtin_sign_ids: lattice_mode::BuiltinSignIds,
    /// 2026-05-26: per-mode invocation runner table. Boot
    /// registers a runner function under each mode-id whose
    /// [`lattice_mode::Mode::invocation_runner`] returns
    /// `Some(id)`; [`Editor::run_invocation`] looks the runner
    /// up by walking the active modes on the active pane's
    /// buffer (minors first, then major) and calls the first
    /// match. Empty for modes that don't own dispatch
    /// (text-mode, completion-mode, semantic-tokens-mode, …).
    /// Replaces the hardcoded `match BufferKind` block in
    /// `run_invocation`; plugin-installed modes for plugin-
    /// installed buffer kinds extend the dispatcher through
    /// this map without touching host code.
    pub invocation_runners: HashMap<lattice_mode::ModeId, InvocationRunnerFn>,
    /// Typed service map subsystems hand off to modes so
    /// `Mode::on_activate` can pull subsystem handles via
    /// `ctx.service::<T>()`. Populated at boot; read-only
    /// after init.
    pub services: Arc<ServiceRegistry>,
    /// Per-`(buffer, mode)` Guard storage. Modes return an
    /// owned `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. Wrapped in `Arc<Mutex<>>` because the
    /// spawned lifecycle task inserts from a worker thread.
    pub mode_guards: GuardStoreHandle,
    /// Per-buffer active modes (major + minors).
    ///
    /// Perf plan B.4: wrapped in [`Versioned`] so the modes
    /// sub-state cache can reuse its prior Arc across publishes
    /// when no mode toggle has fired. The `.insert` / `.remove`
    /// sites in dispatch autoref `&mut self.active_modes`, which
    /// bumps the version once per mutation.
    pub active_modes: Versioned<HashMap<BufferId, ActiveModes>>,
    /// TC.9b: activations refused only because the buffer did not offer a
    /// required capability YET, to be retried when it does.
    ///
    /// A buffer opens, its modes activate, and its first parse has not run —
    /// so a mode requiring `TREE_SITTER` is refused at exactly the moment
    /// every mode is activated, and without this nothing ever asks again. The
    /// user sees a mode that is simply never on.
    ///
    /// Only `MissingCapability` refusals land here. A conflict or a wrong kind
    /// is a decision, not a race, and retrying it would loop forever.
    ///
    /// A `Vec` because it is empty in every ordinary session — the retry pass
    /// costs a length check — and because the natural operations are "walk all"
    /// and "remove one", neither of which wants a map.
    pub deferred_mode_activations: Vec<(BufferId, lattice_mode::ModeId)>,
    /// Per-buffer mode-owned local state. Modes populate
    /// locals via the `BufferLocal` typed-map during
    /// `on_activate`; the App routes `&mut BufferLocals`
    /// into the registry's activation methods.
    ///
    /// Perf plan B.4: wrapped in [`Versioned`] for the same reason
    /// as `active_modes` — most publishes don't touch
    /// `buffer_locals`, so the deep typed-map clone in
    /// `build_render_state` can be avoided via Arc reuse.
    pub buffer_locals: Versioned<HashMap<BufferId, BufferLocals>>,
    /// Per-buffer mode-resolved options cache. Refreshed
    /// eagerly on mode toggle and option write.
    pub resolved_options: HashMap<BufferId, ResolvedOptions>,
    /// AR.0: on-disk fingerprint per file-backed Document buffer, stamped
    /// on load and after the buffer's own `:w`. The autoread watcher (AR.2)
    /// compares an incoming filesystem event against this to suppress
    /// self-writes and skip no-op touches. Non-file buffers (oil, help,
    /// synthetic) never get an entry — the map is keyed by the property
    /// "has an on-disk backing", not by `BufferKind`. See
    /// `docs/dev/architecture/autoread.md`.
    pub on_disk_fingerprints: HashMap<BufferId, crate::autoread::OnDiskFingerprint>,
    /// PI.4: monotonic version bumped whenever [`Self::resolved_options`]
    /// changes. Keys the published `ResolvedOptionsRenderState` cache so
    /// both renderer peers read per-buffer resolved options through ONE
    /// renderer-agnostic seam (`RenderState::resolved_option_for`) instead
    /// of each peer resolving options its own way.
    pub resolved_options_version: u64,
    /// Buffer-local explicit overrides (`:setlocal foo=bar`)
    /// per buffer. Inputs to resolution; the resolver chains
    /// these with mode contributions before writing
    /// [`Self::resolved_options`].
    pub buffer_local_overrides: HashMap<BufferId, OptionOverrideSet>,
    /// Receiver for `OptionChanged` events published by the
    /// option-cascade pipeline. `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.
    pub option_change_rx: Option<tokio::sync::mpsc::UnboundedReceiver<Event>>,
    /// 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.
    ///
    /// CR.1: a copy-on-write RCU handle, not a fixed `Arc`. Every read
    /// site takes one `.load()` snapshot for the duration of its work,
    /// so a plugin loading mid-render affects the next `:help`, never
    /// half of this one. Also registered as a boot service under
    /// `HelpTopicRegistryHandle` so the plugin loader's drain can reach
    /// it without a host method.
    pub help_topics: HelpTopicRegistryHandle,
    /// T.4: builtin element ids interned once at boot from the
    /// `ThemeRegistryHandle` (looked up from [`Self::services`]).
    /// Snapshotted (Copy) into `RenderState` so a renderer read is
    /// `resolved.get(ids.<elem>)`. The registry handle itself lives
    /// only in `services` (it is `Arc<dyn ThemeRegistry>`, which has no
    /// `Default`, so it cannot be a field on this `derive(Default)`
    /// struct); `build_render_state` looks it up to snapshot
    /// `resolved()`.
    pub builtin_element_ids: crate::ui::theme::BuiltinElementIds,
    /// Buffer-level modal state machine (DESIGN.md §5.2).
    /// One of Normal / Insert / Visual / Op-pending /
    /// Command / Search / Replace.
    pub modal: ModalState,
    /// In-flight partial-chord stack from the trie. When the
    /// trie returns `LookupResult::Partial`, the dispatch
    /// layer appends the chord here; the next keystroke
    /// runs through the trie with this stack as prefix.
    /// Cleared on every non-`AbsorbPartialChord` action.
    pub partial_chord: Vec<KeyChord>,
    /// Grammar registry shared with the document actor by the
    /// `ArcSwap` handle. The actor calls `lattice_grammar::execute`
    /// with a wait-free snapshot from inside its own task. The App
    /// also reads it directly (`.load()`, or `.load_full()` where an
    /// owned snapshot must outlive a `&mut self` borrow) for the
    /// parser, completion pipeline, and introspection.
    ///
    /// PL8.B / B3b: held behind `ArcSwap` (was `Arc<CommandRegistry>`)
    /// so the plugin loader can RCU-register a runtime grammar
    /// contribution and `store` it; every reader picks it up on its
    /// next `.load()`. See [`lattice_grammar::CommandRegistryHandle`].
    pub registry: lattice_grammar::CommandRegistryHandle,
    /// 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.
    pub event_bus: Arc<EventBus>,
    /// Built-in command-ids (`d`, `y`, `w`, `j`, …) -- the
    /// canonical `CommandId` values keymap registrations
    /// resolve against.
    pub builtins: Builtins,
    /// App-side typed action IDs (`CommandKind::Action`
    /// registrations). Each field is a `CommandId`
    /// resolving to an `ActionSpec` whose `apply` returns
    /// `Effect::AppAction(AppEffect::Foo)`.
    pub action_ids: ActionIds,
    /// Layered keymap registry (DESIGN.md §5.2.3).
    /// Populated at construction; the input dispatcher
    /// reads from it on every keystroke. Wait-free reads
    /// via internal `ArcSwap`; concurrent writes (mode
    /// push/pop, plugin registration, `:bind`) never stall
    /// the input path.
    pub keymap: KeymapHandle,
    /// `LayerId` of the active completion-popup minor-mode
    /// layer when the popup is open; `None` otherwise.
    /// Pushed / popped in lockstep with `insert_completion`.
    pub completion_popup_layer: Option<LayerId>,
    /// Pluggable completion pipeline (DESIGN.md §5.11.3). Owned by
    /// the host editor.
    pub completion_registry: lattice_completion::CompletionRegistry,
    /// Active command-line completion popup state (for `:` line).
    pub completion_state: Option<CompletionState>,
    /// Active **Insert-mode** completion popup (Phase 4.2.g).
    /// Distinct from `completion_state` (which drives the `:` line
    /// completion popup): this one floats over the buffer, shows
    /// candidates from sources (LSP / snippets / buffer-words /
    /// path / tree-sitter / plugin), and the host's keystroke
    /// dispatcher routes through a "completion-popup minor mode"
    /// keymap layer while it's `Some`. Behavioural spec lives in
    /// [`docs/dev/architecture/insert-completion.md`].
    pub insert_completion: Option<lattice_completion::InsertCompletionState>,
    /// Per-language snippet registry (Phase 4.2.g.4). Loaded
    /// at startup from bundled / user / project paths via
    /// `lattice-snippet::load`; the `gen:snippet` source
    /// consults it per-popup-trigger.
    /// CSM.5: held as `Arc<ArcSwap<...>>` so the mode-captured
    /// handle stays valid across `:reload-snippets`. Source reads
    /// load the current snapshot via `.load()` (wait-free); the
    /// reload path swaps the inner via `.store()` so the mode's
    /// next produce sees the fresh data.
    pub snippet_registry: Arc<arc_swap::ArcSwap<lattice_snippet::SnippetRegistry>>,
    /// SN.3b: shared cell holding the folded `snippet-mode`
    /// [`ActivationPolicy`](lattice_mode::ActivationPolicy).
    /// `register_snippet_modes` creates it (default `Global`) and the
    /// `snippet-mode` gate reads it on every `MajorEntered`; boot +
    /// the `snippet.activation` / `snippet.languages`
    /// `apply_option_cascade` arm fold config into it via
    /// `lattice_snippet::fold_activation_policy`.
    pub snippet_activation_policy: lattice_snippet::SnippetActivationPolicyHandle,
    /// SN.3c.0: app-lifetime registration tokens for modes'
    /// declarative *global* action handlers (`Mode::action_handlers()`,
    /// registered once at boot by
    /// [`crate::mode_action_handlers::register_mode_action_handlers`]).
    /// Held here so the handlers stay registered for the editor's
    /// whole lifetime; dropped at shutdown when `Editor` drops.
    pub global_action_handler_regs: Vec<lattice_mode::ActionHandlerRegistration>,
    /// Sidecar metadata for snippet candidates in the active
    /// insert-completion popup.
    /// CSM.5: retired. Snippet candidates now carry their stable
    /// `name` in the `Extension::payload` field; the accept path
    /// re-resolves the body via `Editor.snippet_registry.by_name`.
    /// Field kept as an empty Vec for one slice so callers that
    /// haven't migrated still compile; field deletion in a
    /// follow-up cleanup slice.
    pub insert_completion_snippet_meta: Vec<crate::state::SnippetCandidateMeta>,
    /// Per-session accept-count map for the insert-mode
    /// completion popup (Phase 4.2.g.5). Each accepted candidate
    /// bumps the counter for its `(text, kind)` pair; the ranker
    /// reads this map and adds a bounded bonus
    /// (`InsertRanker::FREQUENCY_BONUS_CAP`) so recently-accepted
    /// items bubble above tied peers next time.
    pub completion_accept_freq: HashMap<(String, lattice_completion::CandidateKind), u32>,
    /// TOML structural sections collected by the config loader at
    /// startup but not yet routed to their owners. Keyed by full
    /// dotted path (e.g. `"completion.per-language.markdown"`,
    /// `"plugin.rust-analyzer"`); value is the sub-table verbatim.
    /// Phase 4.2.g.5 (3b/3) drains the `completion.per-language.*`
    /// entries into `per_language_completion`; the plugin host
    /// (Phase 7) will drain `plugin.*`.
    pub pending_config_structural_sections: std::collections::BTreeMap<String, toml::Table>,
    /// Per-language insert-completion overrides (Phase 4.2.g.5
    /// (3b/3); spec at `docs/dev/architecture/insert-completion.md` §9).
    pub per_language_completion: HashMap<String, lattice_completion::PerLanguageOverrides>,
    /// `true` while the active insert-completion popup is in
    /// path-completion mode (Phase 4.2.g.6 (2/2)).
    pub completion_in_path_context: bool,
    /// Live snippet expansion (SN.2: relocated to a shared
    /// `SnippetSession` service so the `SnippetActiveMode`-owned
    /// `<Tab>` / `<S-Tab>` handlers can reach it). Active while a
    /// snippet is expanding; the session ends on `$0` consumption /
    /// `<Esc>` / cursor leaving the tabstop ranges. The same `Arc` is
    /// registered in `ServiceRegistry` under `SnippetSessionHandle`.
    pub snippet_session: lattice_snippet::SnippetSessionHandle,
    /// Session-backed minor modes reconciled on the active buffer
    /// each `sync_keymap_overlays` cycle (one entry per
    /// service-driven minor). Each pairs a predicate — reading a
    /// shared, mode-owned session service — with the minor's
    /// `ModeId`; the mode is active iff its predicate is true. Modes
    /// contribute these at boot (`active-snippet-mode` keys off the
    /// shared `SnippetSession`), so the generic overlay-sync carries
    /// no subsystem-specific `is_active()` literal
    /// (`feedback_mode_owns_its_surface`).
    pub session_backed_minors: Vec<SessionBackedMinor>,
    /// Per-language directories from which snippet packs are
    /// loaded on startup / `:reload-snippets` (Phase 4.2.g.4).
    pub snippet_dirs: Vec<PathBuf>,
    /// LIFO stack of snapshots taken every time the popup's content
    /// gets swapped in place by a help -> help link follow (e.g.
    /// `:describe-buffer` -> click `[text-mode](mode:text-mode)` ->
    /// `:describe-mode text-mode`). One popup buffer is reused
    /// across the navigation so jump-list / marks / search /
    /// register state stay coherent; this stack records what was
    /// in the buffer before each swap so `<C-o>` from inside the
    /// popup can restore the prior frame without leaving Help.
    pub popup_back_stack: Vec<crate::popup::PopupSnapshot>,
    /// Active buffer's cursor (DESIGN.md §5.1.1). Updated
    /// in lockstep with the active pane's stash so cross-
    /// pane jumps restore the right position.
    pub cursor: ProtoPosition,
    /// Sticky display-column target for `gj`/`gk` (vim's `w_curswant`).
    /// Stores the byte offset within the current wrap segment so
    /// consecutive display-line moves try to land at the same column.
    /// `None` between any non-display-line motion.
    /// First visible line in the viewport (0-based).
    pub scroll: u32,
    /// First visible display column in the viewport (0-based) —
    /// horizontal scroll for the active pane. Mirrors the active
    /// `PaneState::leftcol`; maintained by
    /// `ensure_cursor_horizontally_visible`. Always 0 when `wrap`
    /// is on (the body reflows, nothing is off-screen-right).
    pub leftcol: u32,
    /// Quit flag. The main loop reads this and tears down
    /// after the next paint. Set by `:q` / `:qa` / `Ctrl-C`
    /// / SIGINT.
    pub should_quit: bool,
    /// Last height we were drawn at; used by motion
    /// clamping and viewport scrolling. Updated by the
    /// renderer before each frame.
    ///
    /// IM.1: this is a **budget in line-heights**, not a count of rows. The
    /// two are the same number whenever rows are uniform — which is always,
    /// for the TUI — but they diverge once a row is taller than one line
    /// (a scaled heading, an IM.3 media block), because how many rows fit
    /// then depends on which rows. Spend it through
    /// [`Editor::row_weights`]; do not count rows against it.
    pub viewport_height: u32,

    /// IM.1: per-source-line vertical cost overrides, in line-heights.
    ///
    /// Empty for every TUI buffer and for any GPUI buffer with no scaled or
    /// media rows, and the scroll walks short-circuit on that — see
    /// [`lattice_cells::RowWeights::is_uniform`]. Published by the renderer
    /// peer, which is the only layer that knows how tall it draws things.
    pub row_weights: std::sync::Arc<lattice_cells::RowWeights>,
    /// Last terminal width we were drawn at. Used by pane
    /// geometry (DESIGN.md §5.9 navigation needs to know
    /// which pane is horizontally adjacent). `None` until
    /// the renderer first records it.
    pub terminal_width: Option<u16>,
    /// IM.7a: the drawing peer's cell geometry in pixels, published through
    /// [`crate::action::Action::SetCellMetrics`].
    ///
    /// `None` until a peer that draws images reports it, and forever on one
    /// that does not — which is how a media block stays at its provisional
    /// reservation in the TUI without the host reading any image header.
    pub cell_metrics: Option<CellMetrics>,
    /// Which buffer the input pipeline currently routes to.
    /// When a help overlay is open this is `Help`; otherwise
    /// `Document`. Denormalized from
    /// `pane_tree.active().buffer` -- updated in lockstep
    /// with the active pane.
    pub active_buffer: BufferKind,
    /// Stable id for the *active* document buffer. Mirrors
    /// the active pane's `buffer_id` whenever that pane
    /// holds a Document leaf.
    pub document_buffer_id: BufferId,
    /// Unified buffer registry (DESIGN.md §5.9). Holds
    /// every open buffer regardless of kind -- documents,
    /// file trees, future outline / diagnostics views.
    pub buffers: BufferRegistry,
    /// ML.0b-2: shared modeline element service (descriptor registry +
    /// content store, ArcSwap-backed). The SAME `Arc` is registered into
    /// `services` at boot so modes reach it via
    /// `ctx.service::<ModelineServiceHandle>()`; the host reads
    /// `modeline.snapshot()` each `build_render_state` into
    /// `RenderState.modeline_elements`. `Arc<ModelineService>` is
    /// `Default`, so `#[derive(Default)]` on `Editor` still holds (the
    /// boot literal overrides it with the registered instance).
    pub modeline: lattice_mode::ModelineServiceHandle,
    /// ML.3: actor-thread drain channel for [`lattice_mode::ModelineElementUpdate`]
    /// events pushed by modes/plugins over the event bus. Boot subscribes
    /// a sender; `drain_modeline_element_updates` (in `run_tick_pending`)
    /// applies each into `modeline`'s content store (single-writer). A
    /// separate boot subscription fires `async_landed` so a pushed update
    /// repaints off-keystroke (§12 wake). `Option` is `Default` (None), so
    /// `#[derive(Default)]` on `Editor` still holds.
    pub modeline_update_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_mode::ModelineElementUpdate>>,
    /// Cached `textDocument/selectionRange` chain for the
    /// smart-expansion operator.
    pub lsp_selection_chain: Option<LspSelectionChain>,
    /// Current step inside `lsp_selection_chain.ranges`.
    /// 0 = innermost; `chain.ranges.len() - 1` = outermost.
    pub lsp_selection_chain_index: usize,
    /// Cached `textDocument/documentHighlight` for the
    /// active buffer + symbol position.
    ///
    /// Phase 5.8.AF.5 / Slice 3b.0: the cache lives behind
    /// `Arc<ArcSwapOption<...>>` so the spawned task on the LSP
    /// runtime can store results directly when the response
    /// arrives — no channel, no UI-thread drain. Renderers read
    /// wait-free via `editor.render_state.load().lsp.document_highlights.load()`.
    pub lsp_document_highlights: std::sync::Arc<arc_swap::ArcSwapOption<DocumentHighlightCache>>,
    /// Cursor position at which the most recent
    /// `documentHighlight` request was issued.
    pub last_document_highlight_issue_cursor: Option<ProtoPosition>,
    /// Per-buffer cache of the last
    /// `textDocument/foldingRange` response.
    ///
    /// Phase 5.8.AF.5 / Slice 3b.1: `PerBufferCache<T>` so the
    /// spawned LSP request task can write results directly when
    /// the response arrives -- no channel, no UI-thread drain.
    /// Renderers read wait-free via
    /// `rs.lsp.folds.get_for(buffer_id)`.
    pub lsp_folds_cache: crate::per_buffer_cache::PerBufferCache<LspFoldsCache>,
    /// Phase 5.8.AF.5 / Slice 3b.1: the old drain
    /// (`drain_pending_folding_range`) called `recompute_folds()`
    /// inline after writing the cache so `self.folds` reflected
    /// the latest LSP response. The new shape has the task
    /// writing the cache off-thread; this tuple lets
    /// `maybe_request_folding_range` detect when the cache
    /// version has changed and trigger `recompute_folds()` on
    /// the renderer thread (where `&mut self.folds` is safe).
    /// `Some((buffer_id, document_version))` records the cache
    /// state last reflected into `self.folds`.
    pub last_recomputed_lsp_fold_version: Option<(BufferId, u64)>,
    /// OA.4d: `(buffer, text_version)` the current [`Editor::folds`] were
    /// computed from, so the tick can notice when they no longer match.
    ///
    /// Folds are otherwise seeded in two places, and neither covers a view
    /// that fills in ASYNCHRONOUSLY: `activate_buffer` seeds them when the
    /// buffer is activated — which for a provider view is while it is still
    /// EMPTY, before the scan lands — and `maybe_reparse_syntax` recomputes
    /// on the edit path, which a view nobody typed into never takes. So the
    /// agenda had no folds at all until something forced a redraw, and
    /// `<Tab>` was a no-op because there was nothing under the cursor to
    /// cycle.
    pub last_folded_text_version: Option<(BufferId, u64)>,
    /// Per-buffer `inlayHint` cache.
    ///
    /// Phase 5.8.AF.5 / Slice 3b.1: see `lsp_folds_cache` note.
    /// Renderers read wait-free via
    /// `rs.lsp.inlay_hints.get_for(buffer_id)`.
    pub lsp_inlay_hints_cache: crate::per_buffer_cache::PerBufferCache<LspInlayHintCache>,
    /// PL8.E: WASM gutter-decoration wiring (per-buffer cache + producer
    /// registry handle + off-keystroke paint generation + single-flight
    /// bookkeeping), bundled so this struct grows by one field. The per-tick
    /// `maybe_refresh_wasm_decorations` drives the producers off the render
    /// path; renderers read `rs.wasm_gutter_decorations`. Inert in
    /// `Editor::default()` (no registry wired).
    pub wasm_decorations: crate::wasm_decorations::WasmDecorationState,
    /// IM.7: inline-media producer wiring — the cache the virtual-row builder
    /// reads, plus the registry the loader registers into.
    pub wasm_media: crate::wasm_media::WasmMediaState,
    /// TC.3a: WASM sticky-context wiring (per-buffer scope cache + producer
    /// registry handle + off-keystroke paint generation + single-flight
    /// bookkeeping). The per-tick `maybe_refresh_wasm_context` drives the
    /// producers off the render path; per-pane resolution reads the cache.
    /// Inert in `Editor::default()` (no registry wired).
    pub wasm_context: crate::wasm_context::WasmContextState,
    /// Per-buffer `documentLink` cache.
    /// Per-buffer `textDocument/documentLink` cache. Phase
    /// 5.8.AF.5 / Slice 3b.4: `PerBufferCache<T>` so the spawned
    /// LSP request task writes results directly. Renderers read
    /// via `rs.lsp.document_links.get_for(buffer_id)`.
    pub lsp_document_links_cache: crate::per_buffer_cache::PerBufferCache<LspDocumentLinksCache>,
    /// Per-buffer code-lens cache.
    /// Per-buffer `textDocument/codeLens` cache. Phase 5.8.AF.5
    /// / Slice 3b.3: `PerBufferCache<T>` so the spawned LSP
    /// request task writes results directly. Renderers read
    /// via `rs.lsp.code_lens.get_for(buffer_id)`.
    pub lsp_code_lens_cache: crate::per_buffer_cache::PerBufferCache<LspCodeLensCache>,
    /// Per-buffer `documentColor` cache.
    /// Per-buffer `textDocument/documentColor` cache. Phase
    /// 5.8.AF.5 / Slice 3b.4: `PerBufferCache<T>`.
    pub lsp_document_color_cache: crate::per_buffer_cache::PerBufferCache<LspDocumentColorCache>,
    /// Per-buffer semantic-tokens cache.
    /// Per-buffer cache of the last `textDocument/semanticTokens/*`
    /// response. Phase 5.8.AF.5 / Slice 3b.2: `PerBufferCache<T>`
    /// so the spawned LSP request task writes results (Items /
    /// Delta-applied / Empty) directly when the response arrives.
    /// Renderers read wait-free via
    /// `rs.lsp.semantic_tokens.get_for(buffer_id)`.
    pub lsp_semantic_tokens_cache: crate::per_buffer_cache::PerBufferCache<LspSemanticTokensCache>,
    /// Per-buffer pull-diagnostics cache (keyed
    /// `result_id`s for `Unchanged` short-circuit).
    /// Per-buffer `textDocument/diagnostic` (pull) cache.
    /// Phase 5.8.AF.5 / Slice 3b.5: `PerBufferCache<T>`.
    pub lsp_pull_diagnostics_cache:
        crate::per_buffer_cache::PerBufferCache<LspPullDiagnosticsCache>,
    // ---- LSP subsystem handles + log/progress channels ----
    pub lsp: LspSupervisorHandle,
    /// ML.3c: handle to the `lattice-lsp`-owned progress/status store
    /// (decision A — the accumulator relocated out of the host). The
    /// modeline forwarder writes it; the host reads it here only for
    /// `:lsp-progress-cancel` (in-flight cancellable tokens). `Arc<…>` is
    /// `Default`, so `#[derive(Default)]` on `Editor` still holds.
    pub lsp_progress_store: lattice_lsp::modeline::LspProgressStoreHandle,
    pub lsp_diagnostics: DiagnosticsLayer,
    /// L4a.2 (lsp-architecture.md §15): inline cursor-line
    /// diagnostic-summary idle gate. `inline_diag_line` is the line
    /// the gate is currently timing (the cursor line at arm time);
    /// `inline_diag_deadline` is the [`tokio::time::Instant`] at which
    /// its summary becomes visible (the actor's pinned sleep targets
    /// it); `inline_diag_visible` flips true when that deadline passes
    /// and back to false on re-arm (new cursor line) / Insert mode /
    /// `ui.diagnostics.inline = off`. The published summary in
    /// `DiagnosticsRenderState::inline_summary` is recomputed each
    /// `build_render_state` while visible, so diagnostics landing on
    /// the line after the gate fires refresh it for free. See
    /// `update_inline_diag_gate` / `fire_inline_diag_gate`.
    pub inline_diag_line: Option<u32>,
    pub inline_diag_deadline: Option<tokio::time::Instant>,
    pub inline_diag_visible: bool,
    /// WK.4: the last `PartialChordPending` published, so the publisher
    /// can skip republishing an unchanged tuple. This is the publisher's
    /// own dedup cache — not subsystem state — and it is what keeps an
    /// ORDINARY keystroke's cost at a tuple compare that short-circuits
    /// on two empty slices. See `publish_partial_chord_pending`.
    pub last_partial_chord_event: Option<lattice_keymap::PartialChordPending>,
    pub lsp_logger: LspLogger,
    /// 4.4.l.2 / 5.8.AA.o / 5.8.AF.5: file-watcher service handle.
    /// `None` until the first actor with `workspace/didChangeWatchedFiles`
    /// capability is observed; at that point the actual watcher +
    /// notify event loop is spawned on the LSP runtime (see
    /// `crate::lsp_watcher::spawn_lsp_file_watcher_task`). Editor
    /// only sends `SyncSubscriptions` commands through this
    /// handle — no notify API calls, no event drains, ever run
    /// on the renderer's per-tick loop. Per paramount goal #4.
    pub lsp_watcher: Option<crate::lsp_watcher::LspFileWatcherHandle>,
    /// Editor-side memo of `server_id → CachedSubscription`. Used
    /// to detect whether the actor roster or its compiled
    /// subscriptions changed since the last `sync` call; only
    /// non-trivial diffs are pushed to the task. Mirrors the
    /// per-server map the task itself holds, but lives here so the
    /// "did anything change?" check stays a cheap fingerprint
    /// compare on the renderer's `refresh_lsp_file_watcher` path.
    pub lsp_watcher_subscriptions:
        std::collections::HashMap<String, crate::lsp_watcher::CachedSubscription>,
    /// Editor-side memo of currently-watched roots. Mirrors the
    /// task's set so we can skip sending `SyncSubscriptions` when
    /// nothing changed.
    pub lsp_watcher_watched_roots: std::collections::HashSet<std::path::PathBuf>,
    /// AR.3: handle to the autoread watcher task (spawned lazily on the
    /// first file-backed buffer with `autoread` on; dropped → task exits
    /// when the last such buffer closes). `Editor` only sends `Sync`
    /// commands through it — no notify calls on the renderer thread. See
    /// `docs/dev/architecture/autoread.md`.
    pub autoread_watcher: Option<crate::autoread::AutoreadWatcherHandle>,
    /// AR.3: the change stream from the watcher task, drained host-side by
    /// AR.4's reload policy. `None` until the watcher is spawned.
    pub autoread_changes:
        Option<tokio::sync::mpsc::UnboundedReceiver<crate::autoread::AutoreadChange>>,
    /// AR.3: order-independent hash of the last-synced desired watch set.
    /// The cheap "did the watch set change?" gate on `refresh_autoread_watcher`
    /// so buffer-switches that don't change the set skip the cmd-send.
    pub autoread_watch_fingerprint: u64,
    /// AR.4: the latest un-applied external change per buffer. The tick drain
    /// records watcher changes here (keyed by `BufferId`) and applies the
    /// *active* buffer's entry immediately; a background buffer's entry is
    /// applied when it next becomes active (vim's checktime-on-`BufEnter`).
    pub autoread_pending: std::collections::HashMap<BufferId, crate::autoread::AutoreadChange>,
    /// AR.5: buffers with an open autoread **conflict diff** (on-disk change +
    /// unsaved edits). While a buffer is in this set autoread stays hands-off
    /// for it — no re-opened resolver, no reload — so a resolve-then-save
    /// can't loop. Cleared when the buffer is reloaded (`:e!` → new id) or
    /// closed.
    pub autoread_conflict_open: std::collections::HashSet<BufferId>,
    /// Phase 5.8.AF.5 / Slice 3a: renderer's wait-free read
    /// contract. Published by `Editor::publish_render_state` at
    /// the end of every `dispatch()` tick. Renderers load via
    /// `editor.render_state.load_full()` once per frame and read
    /// every per-frame field through the returned snapshot.
    pub render_state: std::sync::Arc<arc_swap::ArcSwap<crate::render_state::RenderState>>,
    /// Phase 5.8.AF.5 / Slice X2: wake signal for the overlay
    /// worker. `publish_render_state` fires
    /// `overlay_wake.0.notify_one()` at its tail so the worker
    /// re-evaluates the syntax inputs published into
    /// `RenderState.syntax` and re-buckets overlay quads on a cache
    /// miss. `Notify` coalesces — a burst of publishes wakes the
    /// worker once, which is what we want (it always reads the
    /// latest published inputs anyway).
    ///
    /// display-line B4.2: renamed from `highlight_wake`; the dead
    /// span/row prepaint cache the worker also fed was deleted.
    pub overlay_wake: OverlayWake,
    /// Perf plan B.2 slice B.2.a: parallel cell carrying the
    /// worker's per-row pre-bucketed static-overlay quads
    /// (doc_highlight / all_matches / substitute) for the active
    /// pane's visible window. The Arc identity lives on `Editor` so
    /// `build_render_state` clones it into every snapshot; the
    /// overlay worker writes directly and renderer peers read the
    /// latest write via the published Arc without a republish
    /// round-trip.
    pub syntax_static_overlay_quads_cell:
        std::sync::Arc<arc_swap::ArcSwap<crate::render_state::StaticOverlayQuads>>,
    /// S2.1 (2026-05-26): cell-grid renderer output cell. Same
    /// stability pattern as `syntax_static_overlay_quads_cell`: the Arc
    /// identity lives on `Editor` so `build_render_state` clones
    /// it into every snapshot; the cell-builder worker (S2.2+)
    /// holds a sibling clone and writes directly via
    /// `cell.store(new_matrix)`. Empty `CellMatrix` until the
    /// worker lands.
    pub cells_matrix_cell: std::sync::Arc<arc_swap::ArcSwap<lattice_cells::CellMatrix>>,
    /// D.4.d.0 (2026-05-29): per-document cells-matrix
    /// registry. Each visible buffer gets its own
    /// `Arc<ArcSwap<CellMatrix>>` so the cells worker can
    /// rebuild per buffer, and the renderer can pull the
    /// matrix matching each pane's buffer at paint time
    /// (load-bearing for side-by-side diff — D.4 — where
    /// two panes show different buffers simultaneously).
    ///
    /// The active-document entry is stored under
    /// `document_buffer_id` and **shares its Arc identity
    /// with [`Self::cells_matrix_cell`]** so the existing
    /// hot path (cells_worker writing through the field,
    /// renderer reading through `RenderState.cells.matrix`)
    /// stays bit-identical until the worker iteration
    /// upgrade lands in D.4.d.1.
    ///
    /// Inserts are lazy via
    /// [`Self::cells_matrix_for`] — a buffer's entry shows
    /// up the first time anything asks for its matrix.
    /// Pruning of stale entries is deferred until the
    /// worker actually consumes the registry; for now,
    /// entries accumulate without harm because
    /// [`arc_swap::ArcSwap`] over an empty `CellMatrix` is
    /// a cheap idle resource.
    pub cells_matrices: std::sync::Arc<
        std::sync::Mutex<
            std::collections::HashMap<
                lattice_core::BufferId,
                std::sync::Arc<arc_swap::ArcSwap<lattice_cells::CellMatrix>>,
            >,
        >,
    >,
    /// B2.1 (2026-06-04): per-line display-cache output cell — the
    /// substrate that retires `cells_matrix_cell`. Same stability
    /// pattern: the Arc identity lives on `Editor` so the publisher
    /// clones it into every snapshot; the worker (B2.2) holds a
    /// sibling clone and writes via `cell.store(new_matrix)`. Empty
    /// `DisplayMatrix` until the worker build path lands.
    /// See `docs/dev/architecture/display-line.md`.
    pub display_matrix_cell:
        std::sync::Arc<arc_swap::ArcSwap<crate::display_matrix::DisplayMatrix>>,
    /// B2.1 (2026-06-04): per-document display-matrix registry.
    /// Mirror of [`Self::cells_matrices`] for the per-line cache.
    /// Each visible buffer gets its own `Arc<ArcSwap<DisplayMatrix>>`
    /// so the worker can rebuild per buffer and the renderer can pull
    /// the matrix matching each pane's buffer at paint time. The
    /// active-document entry is boot-seeded to share its Arc identity
    /// with [`Self::display_matrix_cell`]; other entries are inserted
    /// lazily via [`Self::display_matrix_for`].
    pub display_matrices: std::sync::Arc<
        std::sync::Mutex<
            std::collections::HashMap<
                lattice_core::BufferId,
                std::sync::Arc<arc_swap::ArcSwap<crate::display_matrix::DisplayMatrix>>,
            >,
        >,
    >,
    /// IG.2 (2026-08-16): per-document indentation-guide registry.
    /// Exact peer of [`Self::display_matrices`] — the guide layer is
    /// built in the same worker pass, from the same snapshot, and
    /// carries the same `MatrixVersion`, so it is keyed and reached
    /// the same way. Inserted lazily via [`Self::indent_guides_for`].
    pub indent_guides: std::sync::Arc<
        std::sync::Mutex<
            std::collections::HashMap<
                lattice_core::BufferId,
                std::sync::Arc<arc_swap::ArcSwap<crate::indent_guides::IndentGuides>>,
            >,
        >,
    >,
    /// TC.3b: per-PANE sticky-context registry. The one per-pane layer keyed
    /// by `PaneId` rather than `BufferId` — see
    /// [`crate::sticky_context`] for why the usual buffer keying is wrong
    /// here. Inserted lazily via [`Self::sticky_context_for`].
    pub sticky_contexts: std::sync::Arc<
        std::sync::Mutex<
            std::collections::HashMap<
                lattice_core::ui::pane::PaneId,
                std::sync::Arc<arc_swap::ArcSwap<crate::sticky_context::StickyContext>>,
            >,
        >,
    >,
    /// D.2.d (2026-05-29): diff subsystem instance. Holds the
    /// per-buffer `DiffSession` registry, the routing inverse
    /// index, and the per-session lazy debouncer. Reads through
    /// the host's `BufferTextProvider` impl (wired post-D.2.c
    /// when the first consumer slice lands) for live-rope
    /// baselines / current sources. `:describe-diff` reads
    /// `diff_subsystem.build_describe_diff_content()` directly.
    /// See `docs/dev/architecture/diff-system.md` §3.4.
    pub diff_subsystem: std::sync::Arc<crate::diff::subsystem::DiffSubsystem>,
    /// D.0a.1 (2026-05-29): virtual-rows worker output cell.
    /// Same stability pattern as `cells_matrix_cell`: the Arc
    /// identity lives on `Editor` so `build_render_state`
    /// clones it into every snapshot; the
    /// `virtual_rows_worker` holds a sibling clone and writes
    /// directly via `cell.store(new_matrix)`. Empty
    /// `VirtualRowMatrix` until the first provider registers
    /// and the worker rebuilds.
    pub virtual_rows_matrix_cell:
        std::sync::Arc<arc_swap::ArcSwap<lattice_cells::VirtualRowMatrix>>,
    /// D.4.d.2.0 (2026-05-29): per-document virtual-rows
    /// matrix registry. Mirror of [`Self::cells_matrices`]
    /// for the displacing-virtual-row primitive. Each
    /// visible buffer that takes the virtual-rows path gets
    /// its own `Arc<ArcSwap<VirtualRowMatrix>>` so the
    /// worker (after D.4.d.2.1.b) can rebuild per buffer,
    /// and the renderer can pull the right matrix per pane
    /// at paint time (load-bearing for side-by-side diff
    /// fillers — D.4 — where two panes show different
    /// hunks' filler rows simultaneously).
    ///
    /// The active-document entry is stored under
    /// `document_buffer_id` and **shares its Arc identity
    /// with [`Self::virtual_rows_matrix_cell`]** so the
    /// existing hot path (virtual_rows_worker writing
    /// through the field, renderer reading through
    /// `RenderState.virtual_rows.matrix`) stays bit-identical
    /// until the worker iteration upgrade lands in
    /// D.4.d.2.1.b.
    ///
    /// Inserts are lazy via
    /// [`Self::virtual_rows_matrix_for`] — a buffer's entry
    /// shows up the first time anything asks for its matrix.
    /// Pruning of stale entries is deferred until the worker
    /// actually consumes the registry.
    pub virtual_rows_matrices: std::sync::Arc<
        std::sync::Mutex<
            std::collections::HashMap<
                lattice_core::BufferId,
                std::sync::Arc<arc_swap::ArcSwap<lattice_cells::VirtualRowMatrix>>,
            >,
        >,
    >,
    /// D.0a.1 (2026-05-29): wake signal for the virtual-rows
    /// worker. `publish_render_state` fires `notify_one()`
    /// after every dispatch tick (permit-style coalescing
    /// mirrors `cells_wake`). Provider state changes fire the
    /// same signal directly to wake the worker between
    /// dispatch ticks.
    pub virtual_rows_wake: VirtualRowsWake,
    /// D.0a.1 (2026-05-29): the provider registry the
    /// virtual-rows worker iterates on every wake. Consumers
    /// (D.3 inline diff deletion-block provider, M.2
    /// multibuffer excerpt-header provider) register their
    /// providers here at slice-mount time and unregister at
    /// teardown.
    pub virtual_row_providers:
        std::sync::Arc<crate::virtual_rows_worker::VirtualRowProviderRegistry>,
    /// D.3.a.1 (2026-05-29): the bus-subscription guard from
    /// `DiffSubsystem::bind`. Held for the editor's lifetime;
    /// its `Drop` unsubscribes the bus + aborts the drainer
    /// task on editor teardown. Stored behind `Option` so the
    /// `Editor::default()` path (used by tests that don't
    /// boot through `editor_boot`) can leave it unset without
    /// the bind machinery firing.
    pub diff_subscription_guard: Option<crate::diff::subsystem::DiffSubscriptionGuard>,
    /// VCS.2 (2026-07-25): the bus-subscription guard from
    /// `VcsSubsystem::bind`. Held for the editor's lifetime;
    /// its `Drop` unsubscribes the bus + aborts the drainer
    /// task on editor teardown. Mirrors `diff_subscription_guard`.
    pub vcs_subscription_guard: Option<crate::vcs::VcsSubscriptionGuard>,
    /// D.3.a.1 (2026-05-29): per-session wake-forwarder
    /// `JoinHandle`s. `:diff` spawns a tokio task that awaits
    /// `DiffSession::publish_notify().notified()` and fires
    /// `VirtualRowsWake` on each publish; `:diffoff` aborts
    /// the task by `BufferId` and unregisters the provider.
    /// `tokio::sync::Mutex` is overkill here — mutation is
    /// `:diff`/`:diffoff` frequency, never per-frame.
    pub diff_forwarders: std::sync::Arc<
        std::sync::Mutex<
            std::collections::HashMap<lattice_core::BufferId, tokio::task::JoinHandle<()>>,
        >,
    >,
    /// I4 (Claude Code IDE peer, `openDiff`): host-drained inbound receiver for
    /// programmatic side-by-side diff requests. An off-thread producer (the IDE
    /// peer) `send`s a [`lattice_diff::ProgrammaticDiffRequest`] on the matching
    /// [`lattice_diff::ProgrammaticDiffBus`] (registered as a boot service); the
    /// `send` wakes the editor, and [`Self::drain_inbound_programmatic_diffs`]
    /// drains this receiver per tick, opening each diff on the actor thread. The
    /// open is irreducibly `&mut Editor` + lattice-diff types, so — like LSP
    /// `workspace/applyEdit` (`pending_apply_edit_rx`) — it is host-drained, not
    /// a mode-owned `Effect` handler.
    pub pending_programmatic_diff_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_diff::ProgrammaticDiffRequest>>,
    /// I4: per-session "save the current (right) side to this path on Accept"
    /// map, keyed by the session's primary `BufferId` (the proposed/right
    /// buffer). Set when [`Self::open_programmatic_diff`] registers a session;
    /// honored in `tear_down_single_diff_session` (a `DiffOutcome::Accept` writes
    /// the buffer here before firing the bound oneshot — the openDiff
    /// `FILE_SAVED` contract: the review *is* the save). Removed on teardown.
    pub programmatic_diff_accept_paths:
        std::collections::HashMap<lattice_core::BufferId, std::path::PathBuf>,
    /// I4 (openDiff) D-fix.1: per programmatic-diff-session pane teardown info,
    /// keyed by the session's primary (proposed) `BufferId`. Recorded by
    /// `open_programmatic_diff`; consumed by `finish_programmatic_diff_panes`
    /// on `:diff-accept` / `:diff-reject` to close the transient diff panes and
    /// return focus to the originating (`:claude`) pane. Populated/cleared in
    /// lockstep with `programmatic_diff_accept_paths`.
    pub programmatic_diff_panes:
        std::collections::HashMap<lattice_core::BufferId, ProgrammaticDiffPanes>,
    /// D-fix.5: per diff-participant buffer, the last `HunkIndex`
    /// revision its folds were recomputed against. `refresh_diff_folds`
    /// (run each tick on the diff-publish wake) consults this to skip
    /// buffers whose hunks haven't moved — so a diff session's unchanged +
    /// hunk folds refresh off-keystroke when the async recompute
    /// publishes, without re-folding on every unrelated wake. Keyed by
    /// the participant `BufferId` (each side tracked independently, since
    /// each folds its own slot). Stale entries are harmless; the buffer's
    /// `diff-mode` deactivation drops its fold sources, and the next
    /// recompute simply finds none.
    pub diff_fold_seen_revisions: std::collections::HashMap<lattice_core::BufferId, u64>,
    /// Document version each buffer's overlay folds were last computed
    /// at — see `Editor::refresh_overlay_folds`. Peer of
    /// `diff_fold_seen_revisions`, keyed on the document rather than a
    /// diff session so it covers overlays whose buffer is edited out of
    /// band (magit-status's inline diff toggle).
    pub overlay_fold_seen_versions: std::collections::HashMap<lattice_core::BufferId, u64>,
    /// S2.1 (2026-05-26): wake signal for the cell-builder worker.
    /// `publish_render_state` fires `notify_one()` after every
    /// dispatch tick. The worker `notified().await`s; permit-style
    /// coalescing handles bursts.
    pub cells_wake: CellsWake,
    /// S2.4.b (2026-05-26): single-edit tracker for the
    /// cell-builder's incremental rebuild path. `Some(delta)`
    /// iff exactly one `apply_edit_blocking` (or LSP-applied
    /// edit) call has happened since the last
    /// `build_render_state` AND the previous publish cycle had no
    /// pending delta. Any second edit, batch, undo, redo, or
    /// other multi-edit path clears it back to `None` —
    /// conservatively forcing the worker to full-rebuild rather
    /// than risk applying a stale single-edit shift.
    /// `build_render_state` `take()`s and hands it to the cells
    /// substate.
    pub last_edit_for_cells: Option<lattice_cells::EditDelta>,
    /// Phase 5.8.AF.6 / Slice X1b: paint-request signal. The
    /// highlights worker fires `paint_request.notify_one()` after
    /// every `WorkerDecision::Recomputed` so renderer peers can
    /// schedule a paint even when no user input was in flight.
    /// `Notify` coalesces; bursts of recomputes wake the bridge
    /// once and a single paint covers the latest spans. The TUI
    /// peer's 100ms event-poll picks up the new cell naturally
    /// (no bridge needed); the GPUI peer spawns a foreground-
    /// executor future that awaits this Notify and calls
    /// `cx.notify()` to schedule a render.
    pub paint_request: std::sync::Arc<tokio::sync::Notify>,
    /// Slice B.1 (2026-06-03): "async work landed" wake. Fired by
    /// async completions that produce render-relevant state with no
    /// keystroke in flight — today the syntax reparse worker (via the
    /// `on_publish` Notify handed to each `SyntaxHandle`). The editor
    /// actor's loop `select!`s on this and runs `run_tick_pending` +
    /// `publish_render_state`, so an idle reparse repaints without
    /// waiting for the next key (closes the X1b idle-arrival gap for
    /// syntax; LSP-response tasks can fire the same Notify as a
    /// follow-up). Distinct from `paint_request`, which is the
    /// downstream UI-redraw signal fired after a worker publishes.
    pub async_landed: std::sync::Arc<tokio::sync::Notify>,
    pub lsp_log_event_rx: Option<tokio::sync::mpsc::UnboundedReceiver<lattice_lsp::LspLogPushed>>,
    /// Merged user+project `lsp.*` config tree. BC.8b: shared
    /// (`Arc<ArcSwap<…>>`) so the mode-owned `workspace/configuration` inbound
    /// handler (`lattice_lsp::configuration::make_handler`) reads the *current*
    /// tree; the host re-`store`s it on config reload.
    pub lsp_config_tree: std::sync::Arc<arc_swap::ArcSwap<toml::Table>>,
    /// Perf plan B.4.b: wrapped in [`Versioned`] so the buffers
    /// sub-state cache can elide the per-publish HashMap clone.
    /// Mutators (`buffer_uris.insert/remove`) autoref `&mut`,
    /// fire `DerefMut`, and bump.
    pub buffer_uris: Versioned<HashMap<BufferId, lattice_lsp::Uri>>,
    // ---- LSP server-initiated channels ----
    pub pending_apply_edit_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_lsp::InboundApplyEdit>>,
    // BC.8b/BC.8c: `pending_configuration_rx` + `pending_show_document_rx`
    // removed — the `workspace/configuration` and `window/showDocument` buses
    // are now the generic `InboundBus`, drained per-tick through their mode-
    // owned handlers (`boot.inbound`), not host `Editor` receiver fields.
    pub pending_show_message_request_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_lsp::InboundShowMessageRequest>>,
    pub lsp_pending_show_message_requests: HashMap<u32, lattice_lsp::InboundShowMessageRequest>,
    pub lsp_show_message_request_queue: std::collections::VecDeque<u32>,
    pub lsp_next_show_message_request_id: u32,
    /// CG.1/CG.2: the **foreground** cancellation slot — work the user
    /// explicitly triggered that may hold up the next interaction
    /// (project search, an LSP command, a WASM plugin call).
    /// Background work (indexing, file watchers, the LSP boot
    /// handshake) owns its own long-lived tokens and is deliberately
    /// out of scope — see `docs/dev/architecture/cancellation.md` §3.
    ///
    /// CG.2 moved this from an owned `Option<CancellationToken>` to a
    /// shared handle, and registered the same `Arc` as a service. The
    /// `Editor` is only one of its users: providers arm through
    /// `services.get::<ForegroundCancelHandle>()`, because the places
    /// that spawn cancellable work — action-handler closures, event
    /// subscriptions — hold `&self` services and never `&mut Editor`.
    ///
    /// `Arc<T: Default>` is `Default`, so `#[derive(Default)]` on
    /// `Editor` still holds.
    pub foreground_cancel: lattice_mode::ForegroundCancelHandle,
    // ---- LSP per-feature request channels (rx + token pairs) ----
    pub pending_hover_rx: Option<tokio::sync::mpsc::UnboundedReceiver<HoverOutcome>>,
    pub pending_hover_token: Option<CancellationToken>,
    /// 2026-05-27: cursor + scroll captured at K-press time, consumed
    /// by `open_floating_popup` when the LSP response arrives so the
    /// hover popup anchors to the invocation site rather than wherever
    /// the cursor has drifted to. One-shot — cleared after the popup
    /// opens (or when the request is cancelled).
    pub pending_hover_anchor: Option<(lattice_protocol::position::Position, u32)>,
    pub pending_definition_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<Vec<lattice_lsp::lsp_types::Location>>>,
    pub pending_definition_token: Option<CancellationToken>,
    pub pending_nav_kind: Option<LspNavKind>,
    /// LR.2 / EP.6: which terminus the in-flight references request is
    /// for.
    ///
    /// Recorded when the request is issued so the drain routes without
    /// guessing. Defaults to `Picker` because that is what `gr` has
    /// always done and what every existing caller means.
    pub pending_references_terminus: ReferencesTerminus,
    /// LR.3: when the in-flight references request is a *refresh*, the
    /// view to rebuild in place. `None` means "open a new view".
    ///
    /// Without this a refresh would open a SECOND `*references*` buffer
    /// beside the one the user pressed `gr` in — the same mistake
    /// `*problems*` refresh had to avoid, since `create_multibuffer_view`
    /// mints a fresh `BufferId` every call.
    pub refreshing_references_view: Option<lattice_core::BufferId>,
    pub pending_references_rx: Option<tokio::sync::mpsc::UnboundedReceiver<ReferencesOutcome>>,
    pub pending_references_token: Option<CancellationToken>,
    pub pending_symbols_rx: Option<tokio::sync::mpsc::UnboundedReceiver<SymbolsOutcome>>,
    pub pending_symbols_token: Option<CancellationToken>,
    pub pending_format_rx: Option<tokio::sync::mpsc::UnboundedReceiver<FormatOutcome>>,
    /// IN.8b: results from an external formatter run. Separate channel
    /// from the LSP one because the payloads differ -- see
    /// `ExternalFormatOutcome`.
    pub pending_external_format_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<crate::dispatch::ExternalFormatOutcome>>,
    pub pending_format_token: Option<CancellationToken>,
    pub pending_signature_help_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<SignatureHelpOutcome>>,
    pub pending_signature_help_token: Option<CancellationToken>,
    pub pending_completion_rx: Option<tokio::sync::mpsc::UnboundedReceiver<CompletionOutcome>>,
    pub pending_completion_token: Option<CancellationToken>,
    pub pending_completion_items: Option<Vec<CompletionItemRow>>,
    pub pending_moniker_rx: Option<tokio::sync::mpsc::UnboundedReceiver<String>>,
    pub pending_rename_rx: Option<tokio::sync::mpsc::UnboundedReceiver<RenameOutcome>>,
    pub pending_rename_token: Option<CancellationToken>,
    pub pending_code_action_rx: Option<tokio::sync::mpsc::UnboundedReceiver<CodeActionOutcome>>,
    pub pending_code_action_token: Option<CancellationToken>,
    pub pending_code_action_items: Option<Vec<CodeActionRow>>,
    pub pending_code_action_handle: Option<lattice_lsp::ServerHandle>,
    pub pending_selection_range_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<SelectionRangeOutcome>>,
    pub pending_selection_range_token: Option<CancellationToken>,
    pub pending_document_highlight_token: Option<CancellationToken>,
    // Phase 5.8.AF.5 / Slice 3b.0: `pending_document_highlight_rx`
    // retired -- the spawned task now writes directly into
    // `lsp_document_highlights` (`ArcSwapOption`) when the
    // response arrives. No channel, no drain.
    pub pending_folding_range_token: Option<CancellationToken>,
    // Phase 5.8.AF.5 / Slice 3b.1: `pending_folding_range_rx`
    // retired -- the spawned task writes directly into
    // `lsp_folds_cache` via `PerBufferCacheExt::insert_for`.
    pub pending_document_links_token: Option<CancellationToken>,
    // Phase 5.8.AF.5 / Slice 3b.4: `pending_document_links_rx`
    // retired -- spawned task writes directly into
    // `lsp_document_links_cache` via `PerBufferCacheExt::insert_for`.
    pub pending_code_lens_token: Option<CancellationToken>,
    // Phase 5.8.AF.5 / Slice 3b.3: `pending_code_lens_rx` retired
    // -- spawned task writes directly into `lsp_code_lens_cache`
    // via `PerBufferCacheExt::insert_for`.
    pub pending_code_lens_refresh_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_lsp::LspCodeLensRefresh>>,
    pub pending_code_lens_items: Option<Vec<lattice_lsp::lsp_types::CodeLens>>,
    pub pending_code_lens_server: Option<Arc<str>>,
    pub pending_document_color_token: Option<CancellationToken>,
    // Phase 5.8.AF.5 / Slice 3b.4: `pending_document_color_rx`
    // retired -- spawned task writes directly into
    // `lsp_document_color_cache` via `PerBufferCacheExt::insert_for`.
    pub pending_color_presentations: Option<Vec<lattice_lsp::lsp_types::ColorPresentation>>,
    pub pending_color_range: Option<lattice_lsp::lsp_types::Range>,
    pub pending_inlay_hint_token: Option<CancellationToken>,
    // Phase 5.8.AF.5 / Slice 3b.1: `pending_inlay_hint_rx`
    // retired -- the spawned task writes directly into
    // `lsp_inlay_hints_cache` via `PerBufferCacheExt::insert_for`.
    pub pending_semantic_tokens_token: Option<CancellationToken>,
    // Phase 5.8.AF.5 / Slice 3b.2: `pending_semantic_tokens_rx`
    // retired -- the spawned task writes directly into
    // `lsp_semantic_tokens_cache` via `PerBufferCacheExt::insert_for`
    // (or `remove_for` on result_id mismatch in the Delta path).
    pub pending_pull_diagnostics_token: Option<CancellationToken>,
    // Phase 5.8.AF.5 / Slice 3b.5: `pending_pull_diagnostics_rx`
    // retired -- spawned task writes directly into
    // `lsp_pull_diagnostics_cache` + `lsp_diagnostics` layer.
    pub pending_diagnostic_refresh_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_lsp::LspDiagnosticRefresh>>,
    pub pending_inlay_hint_refresh_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_lsp::LspInlayHintRefresh>>,
    /// 2026-06-03: buffers whose server sent
    /// `workspace/inlayHint/refresh` since their hints were last
    /// requested. `drain_inlay_hint_refresh` marks here instead of
    /// wiping `lsp_inlay_hints_cache`, so the previously-resolved
    /// hints stay rendered until the refetch lands (no
    /// disappear-then-reappear flicker — `feedback_decorations_update_in_place`).
    /// `maybe_request_inlay_hint` consults this to force a refetch
    /// even when the document version is unchanged, and clears the
    /// entry once it issues the request.
    pub inlay_refresh_pending: std::collections::HashSet<lattice_core::BufferId>,
    /// 2026-06-03: same shape as [`Self::inlay_refresh_pending`] for
    /// `workspace/semanticTokens/refresh`. The semantic-token colour
    /// overlay renders directly from `lsp_semantic_tokens_cache` every
    /// frame, so wiping the cache on refresh blanked all LSP colouring
    /// until the refetch landed (whole-viewport flicker per keystroke).
    /// `drain_semantic_tokens_refresh` marks here instead; the prior
    /// tokens keep rendering and `maybe_request_semantic_tokens` forces
    /// a refetch (delta from the retained `result_id`) that swaps them
    /// in place. (Pull diagnostics render from the persistent
    /// `DiagnosticsLayer` and code lenses are picker-only, so neither
    /// needs this — audited 2026-06-03.)
    pub semantic_tokens_refresh_pending: std::collections::HashSet<lattice_core::BufferId>,
    pub pending_semantic_tokens_refresh_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_lsp::LspSemanticTokensRefresh>>,
    pub pending_lsp_detach_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_lsp::events::LspBufferDetached>>,
    pub pending_mode_lifecycle_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_mode::ModeEvent>>,
    /// MA.2: receives `Event::MajorEntered` so the per-tick
    /// minor-activation resolver (`drain_minor_activation`) can
    /// auto-activate minors whose `ActivationPolicy` admits the
    /// just-entered major on this buffer's kind.
    pub pending_major_entered_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_protocol::Event>>,
    /// CI.4: receives `Event::ModeEnablementRequested` (a plugin's `enable-mode`)
    /// so the per-tick `drain_mode_enablement` flips the mode registry and
    /// re-activates open buffers.
    pub pending_mode_enablement_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_protocol::Event>>,
    /// Receives `Event::BufferOptionOverrideRequested` (a plugin's
    /// `set-option-in-buffer`) so the per-tick drain writes the buffer-local
    /// layer. `pending_mode_enablement_rx`'s shape and its reason: the layer
    /// lives here, on the Editor, and the guest holds only a `ConfigRegistry`
    /// handle — which is the global layer and the wrong scope.
    pub pending_buffer_option_override_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_protocol::Event>>,
    /// OA.15a: receives `ProviderViewRefreshRequested` (a plugin's
    /// `refresh-view`) so the per-tick `drain_provider_view_refresh` re-opens
    /// the view. The guest cannot reach the activator, so the call is a request
    /// and this is where it is applied — `pending_mode_enablement_rx`'s shape,
    /// with a typed event so the wake comes for free.
    pub pending_provider_view_refresh_rx: Option<
        tokio::sync::mpsc::UnboundedReceiver<
            lattice_mode::provider_view::ProviderViewRefreshRequested,
        >,
    >,
    pub pending_insert_completion_async_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<lattice_completion::AsyncCompletionOutcome>>,
    pub pending_insert_completion_async_token: Option<CancellationToken>,
    pub pending_completion_resolve_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<CompletionResolveOutcome>>,
    pub pending_completion_resolve_token: Option<CancellationToken>,
    /// M.2.b.2 (2026-06-01): `RendererSignal`s accumulated by
    /// `impl ModeActivator for Editor` calls made through
    /// extension-crate code paths (`create_multibuffer_view` and
    /// future provider triggers). The trait surface returns `()`
    /// — keeping `RendererSignal` out of `lattice-mode` — so
    /// signals are stashed here until the App's dispatch loop
    /// drains them via
    /// [`Editor::drain_pending_renderer_signals`].
    pub pending_renderer_signals: Vec<RendererSignal>,
    /// OR.16: see [`Editor::drain_pending_renderer_effects`].
    pub pending_renderer_effects: Vec<lattice_grammar::Effect>,
}

impl Editor {
    /// M.2.b.2 (2026-06-01): drain renderer signals accumulated
    /// by `impl ModeActivator for Editor` calls — extension-crate
    /// code (`lattice_multibuffer::create_multibuffer_view`,
    /// future provider triggers) drives activation through the
    /// trait surface that returns `()`, so the host loop must
    /// pull queued signals into the active `DispatchOutcome`
    /// after the call frame returns.
    #[must_use]
    pub fn drain_pending_renderer_signals(&mut self) -> Vec<RendererSignal> {
        std::mem::take(&mut self.pending_renderer_signals)
    }

    /// OR.16: renderer-owned effects produced on a path with no renderer to
    /// hand them to, for the peers to apply on their next frame.
    ///
    /// The off-renderer paths (the async picker accept, the fill target, the
    /// picker's delete verb) apply what they can themselves; anything left is
    /// queued here instead of being dropped, which is how four features went
    /// missing before. Both peers drain this beside the tick's signals.
    #[must_use]
    pub fn drain_pending_renderer_effects(&mut self) -> Vec<lattice_grammar::Effect> {
        std::mem::take(&mut self.pending_renderer_effects)
    }

    /// M.2.b.2 (2026-06-01): push a renderer-signal batch onto
    /// the trait-activator's pending queue. Called by
    /// [`crate::activator`]'s impl after each cascade returns.
    pub(crate) fn enqueue_renderer_signals(&mut self, mut signals: Vec<RendererSignal>) {
        self.pending_renderer_signals.append(&mut signals);
    }

    /// 2026-05-26: register an invocation-runner function under
    /// the mode-id its owning [`lattice_mode::Mode`] declares via
    /// [`lattice_mode::Mode::invocation_runner`]. Called from
    /// `Editor::boot` for each built-in runner
    /// (`run_help_invocation` / `run_oil_invocation` /
    /// `run_file_tree_invocation` / `run_terminal_invocation`);
    /// plugins (post Phase 7) reuse this entry point for the
    /// modes they install. Overwrites silently on duplicate
    /// registration — boot order is the single writer.
    pub fn register_invocation_runner(
        &mut self,
        id: lattice_mode::ModeId,
        runner: InvocationRunnerFn,
    ) {
        self.invocation_runners.insert(id, runner);
    }

    /// 2026-05-26: resolve the invocation runner for `buffer_id`
    /// by walking the active modes (minors most-recently-
    /// activated first, then major) and returning the first
    /// runner whose mode declared
    /// [`lattice_mode::Mode::invocation_runner`] and has a
    /// registered function on `self.invocation_runners`.
    /// Mirrors [`crate::pane_render::resolve_pane_render_mode`]
    /// — same walk, different table. Returns `None` when no
    /// active mode owns dispatch (Document panes today).
    pub fn resolve_invocation_runner(
        &self,
        buffer_id: lattice_core::BufferId,
    ) -> Option<InvocationRunnerFn> {
        let modes = self.active_modes.get(&buffer_id)?;
        for &minor_id in modes.minors().iter().rev() {
            let mode = self.mode_registry.load().get(minor_id)?;
            if let Some(runner_id) = mode.invocation_runner()
                && let Some(runner) = self.invocation_runners.get(&runner_id)
            {
                return Some(*runner);
            }
        }
        let major_id = modes.major()?;
        let mode = self.mode_registry.load().get(major_id)?;
        let runner_id = mode.invocation_runner()?;
        self.invocation_runners.get(&runner_id).copied()
    }

    /// RV.1: is `id` the generic `action:view-refresh` the shared `gr`
    /// binds to?
    ///
    /// Resolved by name rather than cached in a field so there is no
    /// boot-ordering coupling between this and command registration.
    /// The cost is one `ServiceRegistry` lookup plus one name hash on
    /// the action-dispatch path — which runs at chord rate (human
    /// keypresses), not per frame or per glyph, so it is nowhere near
    /// paramount-goal-#1 territory. Memoize if a dispatch bench ever
    /// says otherwise.
    pub fn is_view_refresh_command(&self, id: lattice_protocol::ids::CommandId) -> bool {
        self.services
            .get::<lattice_grammar::CommandRegistryHandle>()
            .and_then(|reg| reg.load().id_by_name(lattice_mode::VIEW_REFRESH_ACTION))
            == Some(id)
    }

    /// RV.1 (2026-08-10): resolve the refresh action for `buffer_id` by
    /// walking the active modes (minors most-recently-activated first,
    /// then major) and returning the `CommandId` of the first
    /// [`lattice_mode::Mode::refresh_action`] declared.
    ///
    /// Same walk as [`Self::resolve_invocation_runner`], different
    /// table — most-specific-wins, so a provider minor on a multibuffer
    /// beats the generic `MultibufferMode`. Backs the shared `gr` chord
    /// (`refreshable-view-mode`): the mode declares which of its own
    /// actions refreshes, the host walks and dispatches it.
    ///
    /// `None` when no active mode declares one — the caller echoes
    /// rather than swallowing the key, so a view without a refresh says
    /// so. See `docs/dev/architecture/mode-architecture.md` §5.5.
    pub fn resolve_refresh_action(
        &self,
        buffer_id: lattice_core::BufferId,
    ) -> Option<lattice_protocol::ids::CommandId> {
        let modes = self.active_modes.get(&buffer_id)?;
        let registry = self.mode_registry.load();
        let mut declared: Option<&'static str> = None;
        // Walk minors (most-recently-activated first), then the major.
        // The walk does NOT stop at the first hit: continuing costs a
        // handful of `Option` reads over the buffer's active modes and
        // buys a `debug!` naming every shadowed declaration. Two modes
        // both claiming the refresh is a wiring bug in one of them, and
        // silently picking one is how it would stay invisible.
        //
        // Unlike `resolve_invocation_runner`, a minor missing from the
        // registry skips rather than aborting the walk — one absent
        // minor must not mask a major's declaration.
        let candidates = modes
            .minors()
            .iter()
            .rev()
            .copied()
            .chain(modes.major())
            .filter_map(|id| registry.get(id).map(|m| (id, m)));
        for (mode_id, mode) in candidates {
            let Some(action) = mode.refresh_action() else {
                continue;
            };
            match declared {
                None => declared = Some(action),
                Some(winner) => tracing::debug!(
                    %mode_id,
                    shadowed = action,
                    winner,
                    "several active modes declare a refresh action; the most specific wins"
                ),
            }
        }
        let action = declared?;
        let cmd_reg = self
            .services
            .get::<lattice_grammar::CommandRegistryHandle>()?;
        let id = cmd_reg.load().id_by_name(action);
        if id.is_none() {
            // A mode declared an action name the command registry does
            // not know. Loud at debug rather than a silent dead key —
            // this is a wiring bug in the declaring crate.
            tracing::debug!(
                action,
                "refresh_action names an unregistered command; `gr` will report nothing to refresh"
            );
        }
        id
    }

    /// OA.4b: is `id` the generic `action:view-fold-toggle` the shared
    /// `<Tab>` binds to? Peer of [`Self::is_view_refresh_command`], same
    /// resolve-by-name reasoning.
    pub fn is_view_fold_toggle_command(&self, id: lattice_protocol::ids::CommandId) -> bool {
        self.services
            .get::<lattice_grammar::CommandRegistryHandle>()
            .and_then(|reg| reg.load().id_by_name(lattice_mode::VIEW_FOLD_TOGGLE_ACTION))
            == Some(id)
    }

    /// OA.4b: resolve the fold-toggle action for `buffer_id` by walking the
    /// active modes (minors most-recently-activated first, then major) and
    /// returning the `CommandId` of the first
    /// [`lattice_mode::Mode::fold_toggle_action`] declared.
    ///
    /// Identical walk to [`Self::resolve_refresh_action`], different table,
    /// and deliberately so: `<Tab>` and `gr` are the same shape of problem —
    /// one chord that means the same *verb* in every grouped view while the
    /// *body* stays each view's own. Most-specific wins, so a provider minor
    /// on a multibuffer beats the generic `MultibufferMode`.
    ///
    /// `None` when no active mode declares one — the caller leaves `<Tab>`
    /// alone, so an ordinary document keeps jump-list-forward.
    pub fn resolve_fold_toggle_action(
        &self,
        buffer_id: lattice_core::BufferId,
    ) -> Option<lattice_protocol::ids::CommandId> {
        let modes = self.active_modes.get(&buffer_id)?;
        let registry = self.mode_registry.load();
        let mut declared: Option<&'static str> = None;
        let candidates = modes
            .minors()
            .iter()
            .rev()
            .copied()
            .chain(modes.major())
            .filter_map(|id| registry.get(id).map(|m| (id, m)));
        for (mode_id, mode) in candidates {
            let Some(action) = mode.fold_toggle_action() else {
                continue;
            };
            match declared {
                None => declared = Some(action),
                Some(winner) => tracing::debug!(
                    %mode_id,
                    shadowed = action,
                    winner,
                    "several active modes declare a fold toggle; the most specific wins"
                ),
            }
        }
        let action = declared?;
        let cmd_reg = self
            .services
            .get::<lattice_grammar::CommandRegistryHandle>()?;
        let id = cmd_reg.load().id_by_name(action);
        if id.is_none() {
            tracing::debug!(
                action,
                "fold_toggle_action names an unregistered command; `<Tab>` will do nothing"
            );
        }
        id
    }

    /// D.4.d.0 (2026-05-29): lazy port into the per-document
    /// [`Self::cells_matrices`] registry. Returns the matrix
    /// cell for `buffer_id`, inserting an empty
    /// `Arc<ArcSwap<CellMatrix>>` on first ask.
    ///
    /// Idempotent: every call for the same `buffer_id`
    /// returns the same `Arc` identity so renderer reads and
    /// worker writes stay coherent.
    ///
    /// The active document's entry is seeded at boot to
    /// share its `Arc` with [`Self::cells_matrix_cell`], so
    /// callers that resolve the active doc through either
    /// surface land on the same cell.
    pub fn cells_matrix_for(
        &self,
        buffer_id: lattice_core::BufferId,
    ) -> std::sync::Arc<arc_swap::ArcSwap<lattice_cells::CellMatrix>> {
        let mut map = self
            .cells_matrices
            .lock()
            .expect("cells_matrices mutex poisoned");
        map.entry(buffer_id).or_default().clone()
    }

    /// B2.1 (2026-06-04): lazy port into the per-document
    /// [`Self::display_matrices`] registry. Mirror of
    /// [`Self::cells_matrix_for`] for the per-line display cache.
    /// Returns the matrix cell for `buffer_id`, inserting an empty
    /// `Arc<ArcSwap<DisplayMatrix>>` on first ask.
    ///
    /// Idempotent: every call for the same `buffer_id` returns the
    /// same `Arc` identity so renderer reads and worker writes stay
    /// coherent. The active document's entry is boot-seeded to share
    /// its `Arc` with [`Self::display_matrix_cell`].
    pub fn display_matrix_for(
        &self,
        buffer_id: lattice_core::BufferId,
    ) -> std::sync::Arc<arc_swap::ArcSwap<crate::display_matrix::DisplayMatrix>> {
        let mut map = self
            .display_matrices
            .lock()
            .expect("display_matrices mutex poisoned");
        map.entry(buffer_id).or_default().clone()
    }

    /// IG.2 (2026-08-16): lazy port into [`Self::indent_guides`].
    /// Peer of [`Self::display_matrix_for`], with the same idempotence
    /// contract: every call for the same `buffer_id` returns the same
    /// `Arc` identity, so renderer reads and worker writes stay
    /// coherent.
    pub fn indent_guides_for(
        &self,
        buffer_id: lattice_core::BufferId,
    ) -> std::sync::Arc<arc_swap::ArcSwap<crate::indent_guides::IndentGuides>> {
        let mut map = self
            .indent_guides
            .lock()
            .expect("indent_guides mutex poisoned");
        map.entry(buffer_id).or_default().clone()
    }

    /// TC.3b: the sticky-context cell for `pane_id`, inserting an empty layer
    /// on first ask. Keyed by PANE — two panes on one buffer resolve different
    /// context and must not share a cell.
    ///
    /// Same idempotence contract as the sibling accessors: every call for the
    /// same `pane_id` returns the same `Arc` identity, so renderer reads and
    /// worker writes stay coherent.
    pub fn sticky_context_for(
        &self,
        pane_id: lattice_core::ui::pane::PaneId,
    ) -> std::sync::Arc<arc_swap::ArcSwap<crate::sticky_context::StickyContext>> {
        let mut map = self
            .sticky_contexts
            .lock()
            .expect("sticky_contexts mutex poisoned");
        map.entry(pane_id).or_default().clone()
    }

    /// D.4.d.2.0 (2026-05-29): lazy port into the per-document
    /// [`Self::virtual_rows_matrices`] registry. Mirror of
    /// [`Self::cells_matrix_for`] for the virtual-row pipeline.
    /// Returns the matrix cell for `buffer_id`, inserting an
    /// empty `Arc<ArcSwap<VirtualRowMatrix>>` on first ask.
    ///
    /// Idempotent: every call for the same `buffer_id`
    /// returns the same `Arc` identity so renderer reads and
    /// worker writes stay coherent.
    ///
    /// The active document's entry is seeded at boot to
    /// share its `Arc` with
    /// [`Self::virtual_rows_matrix_cell`], so callers that
    /// resolve the active doc through either surface land
    /// on the same cell.
    pub fn virtual_rows_matrix_for(
        &self,
        buffer_id: lattice_core::BufferId,
    ) -> std::sync::Arc<arc_swap::ArcSwap<lattice_cells::VirtualRowMatrix>> {
        let mut map = self
            .virtual_rows_matrices
            .lock()
            .expect("virtual_rows_matrices mutex poisoned");
        map.entry(buffer_id).or_default().clone()
    }
}