lattice_multibuffer/

lib.rs

//! Multibuffers: one buffer composed of excerpts from other buffers and
//! files, and every concern that comes with them.
//!
//! A dedicated crate since M.2.b.1 (2026-05-31). Lives outside
//! `lattice-runtime` so that:
//!
//! - The runtime crate stays focused on the actor + handle +
//!   Document-trait substrate; multibuffer is one specific kind
//!   of document built on top of that substrate, not part of it.
//! - Plugins (post-v1) can depend on `lattice-multibuffer`
//!   directly without pulling in the full actor machinery.
//! - The crate boundary makes the design self-documenting —
//!   every multibuffer concern is in one tree; nothing else
//!   knows multibuffer exists except `lattice-host`'s tiny
//!   boot-wiring registration.
//!
//! See `docs/dev/architecture/multibuffer-views.md` §3.6 for the
//! crate-layout decision.
//!
//! ## What this crate ships (M.2.b.1)
//!
//! * **Data model**: `Excerpt`, `ExcerptId`, `ExcerptHeader`,
//!   `ExcerptHeaderStyle`, `RowEntry`, `RowTranslation`.
//! * **Handle**: `MultibufferDocumentHandle` — read-only impl of
//!   `lattice_runtime::Document` composing N source handles into
//!   one view. M.3 lifts the read-only restriction.
//! * **Header provider**: `MultibufferExcerptHeaderProvider` (impl
//!   `lattice_cells::VirtualRowProvider`) emitting one virtual
//!   row per excerpt header.
//!
//! ## What lands later
//!
//! * **M.2.b.2** — `MultibufferMode` as the major mode for
//!   `BufferKind::Multibuffer`. Activation owns the header
//!   provider registration + per-buffer typed context Guard.
//! * **M.2.b.3** — `]e` / `[e` / `]E` / `[E` motions registered
//!   through the grammar; bound in `MultibufferMode` keymap.
//! * **M.3** — edit propagation (writes flow back to source
//!   handles via the row translation).
//! * **M.4** — live updates from sources (auto-recompose on
//!   `EventKind::DocumentChanged`; anchor sliding; source-close
//!   auto-remove).
//! * **M.5–M.8** — expand-context, provider trait + first
//!   consumer, fold providers.

// PV.1 (2026-08-12): crate-level events, moved out of the
// feature-gated `providers::search` so the off-keystroke wake exists in
// every build and every provider crate can publish it.
pub mod events;
pub mod install;
pub mod mode;
pub mod motions;
pub mod providers;
pub mod registry;
pub mod view;

pub use crate::events::MultibufferExcerptsReady;
pub use crate::install::install;
pub use crate::mode::{
    MultibufferMode, register_multibuffer_ex_commands, register_multibuffer_modes,
};
pub use crate::motions::{MultibufferMotionIds, register_multibuffer_motions};
pub use crate::registry::{
    InMemoryMultibufferRegistry, MultibufferRegistry, MultibufferRegistryHandle,
};
pub use crate::view::create_multibuffer_view;

use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};

use arc_swap::ArcSwap;
use lattice_cells::cell::Cell;
use lattice_cells::headerline::{Headerline, HeaderlineProvider, HeaderlineRow};
use lattice_cells::virtual_rows::{
    AnchorPosition, ProviderId, VirtualRow, VirtualRowKind, VirtualRowProvider,
};
use lattice_core::buffer::AppliedEdit;
use lattice_core::{Buffer, BufferId};
use lattice_grammar::{
    CancellationToken, CommandInvocation, CommandKind, CommandRegistryHandle, Effect,
    execute_with_env,
};
use lattice_protocol::edit::Edit;
use lattice_protocol::ids::DocumentId;
use lattice_protocol::position::Position;
use lattice_protocol::selection::SelectionSet;
use lattice_runtime::{
    Document, DocumentSnapshot, Pending, PublishedSnapshot, RuntimeError, SnapshotCache,
};
// K.4.7 (2026-06-07): per-excerpt syntax highlighting.
use lattice_syntax::{Lang, LangRegistry, Syntax, SyntaxHandle, SyntaxSnapshot};
// T.7 (2026-06-18): mode-owned theme elements for the excerpt header.
use lattice_theme::{
    Color, ColorRef, ElementId, ElementName, ElementOwner, StyleSpec, ThemeRegistryHandle,
};

// ─────────────────────────────────────────────────────────────────
// Excerpt + identity + header
// ─────────────────────────────────────────────────────────────────

/// Unique identity for an excerpt within a multibuffer. Stable
/// for the excerpt's lifetime; survives reorders / source-edit
/// rebuilds.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ExcerptId(pub u64);

impl ExcerptId {
    pub fn next() -> Self {
        static SEQ: AtomicU64 = AtomicU64::new(1);
        Self(SEQ.fetch_add(1, Ordering::Relaxed))
    }
}

/// Header presentation for an excerpt — title + style + the
/// mode-owned semantic data the rich header renderer reads
/// (MH.A2, see multibuffer-views.md §3.8).
#[derive(Debug, Clone, Default)]
pub struct ExcerptHeader {
    /// Human-readable label. Conventionally
    /// `"<path> : <start_line+1>-<end_line+1>"` for a regular
    /// file excerpt (1-indexed for display). Empty string = no
    /// header rendered. Fallback basename when `path` is `None`.
    pub title: String,
    pub style: ExcerptHeaderStyle,
    /// MH.A2: the source file path. Drives the leading file-type
    /// icon and the basename-bright / dir-dim split in
    /// [`header_cells`]. `None` ⇒ fall back to `title`. Set by the
    /// producing mode (e.g. the search provider) at excerpt
    /// creation, NOT baked into cells here — the glyph + colours
    /// are resolved live in `collect()` so `ui.nerd_fonts` /
    /// `:colorscheme` toggles re-render correctly.
    pub path: Option<std::path::PathBuf>,
    /// MH.A2: hit count for the `· N matches` badge. Mode-consumed
    /// datum set at production (the search mode counts hits per
    /// source). `None` ⇒ no badge rendered.
    pub match_count: Option<u32>,
}

impl ExcerptHeader {
    pub fn new(title: impl Into<String>) -> Self {
        Self {
            title: title.into(),
            style: ExcerptHeaderStyle::default(),
            path: None,
            match_count: None,
        }
    }
}

/// Style discriminator for excerpt headers. M.2 shipped a single
/// `Default` variant and said future ones would distinguish header
/// presentation; MH.A6 adds the first.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ExcerptHeaderStyle {
    #[default]
    Default,
    /// MH.A6: **this header is the one to look at.** Rendered from its
    /// own theme elements (`multibuffer.excerpt_header.emphasis[.*]`)
    /// rather than the shared backdrop / path pair, so a colourscheme
    /// decides what "prominent" means instead of this enum.
    ///
    /// The agenda's today block is the first consumer: a view whose
    /// whole purpose is "what do I do now" reads badly when the day
    /// you are actually in paints identically to a Thursday three
    /// weeks out. Deliberately NOT named `Today` — the mechanism is
    /// "one header outranks its peers", and a diagnostics view
    /// wanting to lift its errors block, or a diff view its conflicted
    /// file, is the same want.
    ///
    /// **At most one per view is a convention, not a rule.** Nothing
    /// here enforces it, because nothing here could: excerpts arrive
    /// from a sort the provider does not control. A provider that
    /// emphasises everything has emphasised nothing, and that is its
    /// bug to avoid.
    Emphasis,
}

/// One excerpt of a source document, identified by its source
/// `BufferId` and an inclusive line range
/// `[start_line, end_line]`.
///
/// M.1 keeps the range as integer line numbers; M.4 swaps to
/// `Anchor`-based positions that slide on source edits.
#[derive(Debug, Clone)]
pub struct Excerpt {
    pub id: ExcerptId,
    pub source: BufferId,
    pub start_line: u32,
    pub end_line: u32,
    pub header: ExcerptHeader,
}

impl Excerpt {
    pub fn new(source: BufferId, start_line: u32, end_line: u32) -> Self {
        Self {
            id: ExcerptId::next(),
            source,
            start_line,
            end_line,
            header: ExcerptHeader::default(),
        }
    }

    pub fn with_header(mut self, header: ExcerptHeader) -> Self {
        self.header = header;
        self
    }

    /// Number of source rows this excerpt covers. Always `>= 1`
    /// for a well-formed excerpt.
    pub fn line_count(&self) -> u32 {
        self.end_line.saturating_sub(self.start_line) + 1
    }
}

// ─────────────────────────────────────────────────────────────────
// Row translation
// ─────────────────────────────────────────────────────────────────

/// One row in the composed multibuffer view, mapped back to its
/// source.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RowEntry {
    Excerpt {
        excerpt_id: ExcerptId,
        source_row: u32,
    },
}

/// Composed-row → source-row mapping. One entry per composed
/// row, in display order. Rebuilt on every recompose.
#[derive(Debug, Clone, Default)]
pub struct RowTranslation {
    pub entries: Vec<RowEntry>,
}

impl RowTranslation {
    pub fn build(excerpts: &[Excerpt]) -> Self {
        let mut this = Self::default();
        this.append(excerpts);
        this
    }

    /// MH.B1 (2026-06-19): extend the translation in place with a
    /// batch of newly-appended excerpts. Because `build` is pure
    /// concatenation (one `RowEntry::Excerpt` per source row, per
    /// excerpt, in order — no cross-excerpt state), appending a
    /// batch's entries to an existing translation yields exactly
    /// the same `Vec<RowEntry>` as rebuilding from the full excerpt
    /// list. This is the row-translation half of the O(batch)
    /// incremental `append_excerpts`; the equivalence is pinned by
    /// `incremental_append_matches_full_build`.
    pub fn append(&mut self, excerpts: &[Excerpt]) {
        for excerpt in excerpts {
            for row in excerpt.start_line..=excerpt.end_line {
                self.entries.push(RowEntry::Excerpt {
                    excerpt_id: excerpt.id,
                    source_row: row,
                });
            }
        }
    }
}

// ─────────────────────────────────────────────────────────────────
// MultibufferDocumentHandle
// ─────────────────────────────────────────────────────────────────

struct MultibufferInner {
    id: DocumentId,
    buffer_id: BufferId,
    // M.2.b.2 (2026-06-01): sources + excerpts move behind a
    // Mutex so providers can stream updates asynchronously via
    // `append_excerpts` / `replace_excerpts` / `add_source` /
    // `remove_source`. Hot reads (`snapshot`, `row_translation`,
    // `excerpts`) go through the lock-free `PublishedSnapshot`
    // cell and the `ArcSwap<RowTranslation>` — the Mutex is
    // only acquired on mutation + on the recompose seam.
    state: std::sync::Mutex<MultibufferState>,
    /// M.11 (2026-06-02): the composed rope, owned LOCALLY.
    /// Edits apply here synchronously (byte-identical to
    /// `RopeDocumentHandle`'s apply_edit) before being forwarded
    /// to the relevant source actor async. The multibuffer is no
    /// longer a proxy — it IS a buffer.
    ///
    /// Wrapped in `Mutex` because `apply_edit` runs on the
    /// caller's thread (the host's block_on bridge) while the
    /// source forwarder task and excerpt-mutation paths
    /// (append_excerpts / replace_excerpts) read it from other
    /// contexts. Lock-free reads go through `snapshot_cell`.
    composed_doc: std::sync::Mutex<lattice_core::Document>,
    /// M.11 (2026-06-02): mpsc sender into the source-forwarder
    /// task. Each `apply_edit` queues a (composed_edit,
    /// row_translation_snapshot) pair; the forwarder task
    /// translates to source coords and ships to the source
    /// actor. Fire-and-forget — caller doesn't wait.
    source_forward_tx: tokio::sync::mpsc::UnboundedSender<SourceForwardMsg>,
    snapshot_cell: Arc<PublishedSnapshot>,
    row_translation: ArcSwap<RowTranslation>,
    // M.4 (2026-06-01): view-level headerline rendered above the
    // first excerpt. Async providers update this to surface
    // progress + completion status (see
    // `multibuffer-views.md` §3.7 "headerline status convention").
    // Lock-free read via `ArcSwap`; writes go through
    // `set_headerline` which also publishes
    // `MultibufferHeaderlineChanged`.
    headerline: ArcSwap<HeaderlineStatus>,
    // M.6.5 (2026-06-08): monotonic version for the view-status headerline.
    // Bumped in `set_headerline` so `MultibufferStatusProvider::version()`
    // advances and the cells worker rebuilds the sticky row.
    headerline_version: AtomicU64,
    // M.4 (2026-06-01): event-bus subscription bookkeeping for
    // the auto-recompose forwarder. `SubscriptionId`s registered
    // by `attach_event_subscriptions` are unsubscribed on Drop.
    subscriptions: std::sync::Mutex<SubscriptionBookkeeping>,
    // K.4.11 (2026-06-02): CommandRegistry the multibuffer runs
    // grammar against in `dispatch_with_cancel`. Passed at
    // construction so the multibuffer is a self-sufficient
    // Document — same shape `spawn_document(id, doc, registry)`
    // takes for regular Document handles. Replaces the
    // host-side kind-branch in `Editor::dispatch_blocking` (the
    // multibuffer's own `Document::dispatch_with_cancel` impl
    // now does the work uniformly).
    //
    // B3b: the `ArcSwap` handle (was `Arc<CommandRegistry>`) so a plugin
    // grammar contribution registered at runtime is live for this view's
    // next dispatch; `dispatch_with_cancel` `.load_full()`s an owned
    // snapshot for each keystroke.
    registry: CommandRegistryHandle,
    // K.4.7 (2026-06-07): language registry for per-source
    // SyntaxHandle creation. Set once after construction via
    // `set_lang_registry`; `None` until the host wires it.
    lang_registry: std::sync::OnceLock<Arc<LangRegistry>>,
    /// AF.1: how this view's rows GROUP for folding, declared by the provider
    /// that built it. See [`FoldGrouping`].
    fold_grouping: std::sync::atomic::AtomicU8,
    // K.4.7 (2026-06-08): monotonic generation counter. Incremented
    // every time `source_syntax` gains a new handle (`add_source` /
    // `set_lang_registry`). Folded into `MatrixVersion::syntax` in
    // `publish_render_state` so the cells worker invalidates its cache
    // when per-source handles are first populated. XOR of individual
    // handle text_versions is unreliable: N handles all at version=1
    // XOR to 0 for even N, colliding with the initial-zero and
    // producing a false cache hit that freezes highlighting.
    excerpt_syntax_gen: std::sync::atomic::AtomicU64,
    // K.4.7 (2026-06-08): monotonic publish counter. Stamped as the
    // `text_version` on every DocumentSnapshot emitted by
    // `append_excerpts` / `replace_excerpts`. Document::from_text()
    // always returns text_version=0, so without this counter the
    // MatrixVersion.text axis is permanently 0 and the cells worker
    // always returns CacheHit — the "empty until keypress" bug.
    publish_seq: std::sync::atomic::AtomicU64,
}

#[derive(Default)]
struct SubscriptionBookkeeping {
    /// Subscription ids returned by `EventBus::subscribe`; cleared
    /// on Inner Drop via `unsubscribe`.
    ids: Vec<lattice_runtime::SubscriptionId>,
    /// Cheap-clone Arc for the unsubscribe path. `None` until
    /// `attach_event_subscriptions` runs.
    bus: Option<Arc<lattice_runtime::EventBus>>,
}

impl Drop for MultibufferInner {
    fn drop(&mut self) {
        // Unsubscribe + drop the bus reference so the forwarder
        // task (which holds a Weak<MultibufferInner>) sees the
        // upgrade fail and exits cleanly.
        if let Ok(mut book) = self.subscriptions.lock()
            && let Some(bus) = book.bus.take()
        {
            for id in book.ids.drain(..) {
                let _ = bus.unsubscribe(id);
            }
        }
    }
}

/// M.11 (2026-06-02): one outbound edit waiting to be forwarded
/// to a source actor. Carries pre-resolved source coords so the
/// forwarder task doesn't need to re-walk the row translation
/// (which may have shifted by the time the task runs).
#[derive(Debug)]
/// What the forwarder needs to announce a source change it just made.
///
/// Carried in the message rather than held by the forwarder task, because the
/// task is spawned inside `new()` — before `Self` exists — while the sender
/// (`apply_edit_batch_sync`) has `&self` and can hand over both the bus and a
/// `Weak` back to the view.
struct AnnounceSource {
    /// The source's buffer id, for the self-origin record below.
    source_id: BufferId,
    /// Weak so a dropped view lets the forwarder fall through to a no-op
    /// rather than keeping the whole multibuffer alive.
    inner: std::sync::Weak<MultibufferInner>,
    bus: Arc<lattice_runtime::EventBus>,
}

enum SourceForwardMsg {
    /// Propagate a composed-coordinate edit to its source actor.
    ///
    /// `announce` is how the source's change gets ANNOUNCED. Applying it here
    /// used to be the end of the story: the source actor was mutated and
    /// nothing published, so nothing downstream — this view's own syntax
    /// reparse, a second view on the same file, the diff subsystem, a plugin
    /// watching `DocumentChanged` — ever learned the file had changed. A
    /// buffer that changes without an event is one every subscriber has
    /// stale.
    Edit {
        source_handle: Arc<dyn Document>,
        source_edit: Edit,
        announce: Option<AnnounceSource>,
    },
    /// OA.23b: an edit written straight at a source, in SOURCE
    /// coordinates, for a line the view does not contain.
    ///
    /// The agenda's `s` / `d`: a row is one line — the headline — and
    /// the planning line goes below it, outside every excerpt. There is
    /// no composed coordinate for it, so it cannot arrive as an
    /// ordinary [`Self::Edit`].
    ///
    /// **Through the forwarder rather than straight at the handle**, so
    /// it queues behind whatever composed edits are still in flight. A
    /// direct `source.apply_edit(..)` could overtake them, and then
    /// their source coordinates — computed before this insert shifted
    /// the lines below it — would land in the wrong place. FIFO is the
    /// whole reason this channel exists; a second door into the same
    /// document would defeat it.
    ///
    /// `reply` carries the result back because this one has a caller
    /// waiting on it: the host's `Effect::ApplyEdit` route reports
    /// failure, unlike composed propagation which is best-effort.
    DirectEdit {
        source_handle: Arc<dyn Document>,
        source_edit: Edit,
        reply: tokio::sync::oneshot::Sender<Result<AppliedEdit, RuntimeError>>,
    },
    /// Save-flush barrier (2026-06-10). Sent by
    /// [`MultibufferDocumentHandle::save`] through the SAME FIFO
    /// channel as edits, so by the time the forwarder pops it every
    /// prior edit has been applied to (and `await`ed on) its source
    /// actor. The forwarder then signals `done`, telling `save()` the
    /// sources are current — without this, `:w` would race the async
    /// forwarder and persist stale sources (drop the last keystrokes).
    Flush {
        done: tokio::sync::oneshot::Sender<()>,
    },
}

struct MultibufferState {
    sources: HashMap<BufferId, Arc<dyn Document>>,
    /// SS.2 (2026-08-11): the on-disk identity each source had when it
    /// entered the view.
    ///
    /// A multibuffer's sources are SNAPSHOTS — read once at
    /// view-creation and held for the view's lifetime — while
    /// `Document::save` writes every dirty one back. Without a baseline
    /// that silently overwrites whatever changed the file externally
    /// (a rebase, a formatter, another pane). SS.3 compares against
    /// this before writing.
    ///
    /// Pathless sources (synthetic documents) are absent and are never
    /// stale — there is no file to conflict with.
    /// See `docs/dev/architecture/multibuffer-stale-sources.md`.
    source_fingerprints: HashMap<BufferId, lattice_core::on_disk::OnDiskFingerprint>,
    /// The newest source `text_version` this view itself produced, per source.
    ///
    /// The view forwards its composed edits to the sources, and those now
    /// announce themselves on the bus — which means this view's own
    /// subscription hears its own edit come back. That echo must not be
    /// treated as an outside change: `slide_anchors_for_source` would shift
    /// excerpts for an edit the composed edit already accounted for, moving
    /// every row below the one you just typed on.
    ///
    /// Matching on the VERSION rather than adding a field to
    /// `Event::DocumentChanged`: the version is already carried, is already
    /// unique per mutation, and keeps the provenance question inside the one
    /// crate that has it. An event field would put it in the protocol for
    /// every subscriber that does not care.
    self_forwarded_versions: HashMap<BufferId, u64>,
    excerpts: Vec<Excerpt>,
    /// K.4.7 (2026-06-07): per-source SyntaxHandle for excerpt
    /// highlighting. Populated by `add_source` when `lang_registry`
    /// is set. Sources with `Lang::Plain` are absent.
    source_syntax: HashMap<BufferId, Arc<SyntaxHandle>>,
    /// K.4.5 (2026-06-02): composed-coordinate selection set
    /// for the view. Multibuffers don't propagate selections to
    /// their source buffers (M.3 design — composed coordinates
    /// don't map cleanly back through edits / excerpts), but
    /// the view itself IS a buffer and carries its own
    /// selection state. Visual-mode highlight painting
    /// (`Editor::visual_selection_range` → renderer) reads
    /// these via `snapshot.selections`. Updated by
    /// `set_selections` (Document trait); rebuilt-but-preserved
    /// by every recompose path so excerpt mutations don't
    /// clobber the user's selection.
    selections: Arc<SelectionSet>,
}

// ─────────────────────────────────────────────────────────────────
// M.4 (2026-06-01): headerline status + typed events
// ─────────────────────────────────────────────────────────────────

/// View-level headerline status. Rendered above the first
/// excerpt (M.2.a `MultibufferExcerptHeaderProvider` extends to handle
/// the view header in a later renderer slice).
///
/// Async providers transition `Idle → InProgress → Complete` /
/// `Failed` as their scan progresses. See
/// `multibuffer-views.md` §3.7.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub enum HeaderlineStatus {
    /// No status rendered. The view-header virtual row is empty.
    #[default]
    Idle,
    /// A scan / fetch / computation is running. `label` describes
    /// it; `count` is an optional running tally (hits found so
    /// far, files scanned, etc.). `emphasis` is an optional
    /// substring of `label` (e.g. the search query) that the
    /// renderer paints with the `multibuffer.status.query` accent
    /// role so it stands out; providers with nothing to emphasise
    /// pass `None`.
    InProgress {
        label: String,
        count: Option<usize>,
        emphasis: Option<String>,
    },
    /// The operation completed successfully. `summary` is the
    /// terminal label rendered to the user. `emphasis` is an
    /// optional substring of `summary` painted with the accent
    /// role (see [`HeaderlineStatus::InProgress`]).
    Complete {
        summary: String,
        emphasis: Option<String>,
    },
    /// The operation failed. `reason` is the terminal label
    /// rendered to the user.
    Failed { reason: String },
}

/// M.4 (2026-06-01): published whenever a view's headerline
/// status changes. Renderers + status-line consumers subscribe
/// via `EventBus::subscribe_typed::<MultibufferHeaderlineChanged>`.
#[derive(Debug, Clone)]
pub struct MultibufferHeaderlineChanged {
    pub view: BufferId,
    pub status: HeaderlineStatus,
}

lattice_protocol::register_event!(
    MultibufferHeaderlineChanged,
    "multibuffer.headerline-changed",
    "Multibuffer view's headerline status changed (Idle / InProgress / Complete / Failed).",
    "lattice-multibuffer",
);

/// M.4 (2026-06-01): published when one of a multibuffer's
/// source buffers closes. Providers subscribe to choose a
/// source-close policy: project-search drops the stale excerpts;
/// project-diff may keep them as historical reference.
/// Multibuffer itself prunes the source from its internal map.
#[derive(Debug, Clone)]
pub struct MultibufferSourceClosed {
    pub view: BufferId,
    pub source: BufferId,
}

lattice_protocol::register_event!(
    MultibufferSourceClosed,
    "multibuffer.source-closed",
    "One of a multibuffer view's source buffers closed; providers choose policy (drop excerpts, keep stale, etc.).",
    "lattice-multibuffer",
);

/// PD.7c: published when one of a multibuffer's source buffers is
/// **edited** — the peer of [`MultibufferSourceClosed`], and it exists
/// for the same reason.
///
/// The view keeps composing correctly on its own (excerpts slide,
/// content recomposes). What an edit invalidates is whatever the
/// PROVIDER derived from the source's content at scan time — diff
/// classifications, match positions, symbol ranges — and only the
/// provider knows what that is or what to do about it. Publishing the
/// fact here rather than letting each provider re-derive
/// `DocumentId → source` from raw `DocumentChanged` events keeps that
/// translation in the one place that already owns the source map.
///
/// Fires once per applied change, so a provider that reacts expensively
/// should react once per source (project-diff clears that file's
/// styling on the first edit and then ignores the rest until `gr`).
#[derive(Debug, Clone)]
pub struct MultibufferSourceEdited {
    pub view: BufferId,
    pub source: BufferId,
}

lattice_protocol::register_event!(
    MultibufferSourceEdited,
    "multibuffer.source-edited",
    "One of a multibuffer view's source buffers was edited; providers choose policy for data they derived from its content.",
    "lattice-multibuffer",
);

/// A multibuffer document handle. Composes N source
/// `Arc<dyn Document>`s into one read-only composed view; impls
/// [`Document`] so dispatch / motion / render code paths serve
/// it the same as a regular `RopeDocumentHandle`.
#[derive(Clone)]
pub struct MultibufferDocumentHandle {
    inner: Arc<MultibufferInner>,
}

/// SS.3: has `path`'s content changed since `baseline` was taken?
///
/// Cheap `(mtime, size)` pre-gate first; only a file that looks moved
/// is re-read and hashed. The content hash is authoritative, so a bare
/// `touch` — mtime bumped, bytes identical — is correctly NOT stale.
///
/// An unreadable file is treated as **not stale**: the subsequent save
/// will fail on its own and report a real I/O error, which is a better
/// message than "changed on disk" for a file that was deleted.
fn is_stale_on_disk(
    path: &std::path::Path,
    baseline: &lattice_core::on_disk::OnDiskFingerprint,
) -> bool {
    if baseline.stat_unchanged(path) {
        return false;
    }
    let Ok(disk_text) = std::fs::read_to_string(path) else {
        return false;
    };
    let current = lattice_core::on_disk::OnDiskFingerprint::from_path_and_text(path, &disk_text);
    !current.same_content(baseline)
}

/// SS.2: the on-disk baseline for one source, or `None` when it has no
/// path (a synthetic document — nothing on disk to conflict with).
///
/// Called at insertion, where the source's in-memory text IS what was
/// just read from disk, so the baseline is exact and costs one `stat`.
fn fingerprint_source(
    source: &Arc<dyn Document>,
) -> Option<lattice_core::on_disk::OnDiskFingerprint> {
    let path = source.path()?;
    let text = source.snapshot().buffer.as_string();
    Some(lattice_core::on_disk::OnDiskFingerprint::from_path_and_text(&path, &text))
}

impl MultibufferDocumentHandle {
    /// Construct a multibuffer composing `sources` + `excerpts`.
    ///
    /// M.2.b.2 (2026-06-01): empty `sources` + empty `excerpts`
    /// are valid — async providers (project-search, lsp-references,
    /// etc.) open an empty view immediately and stream content in
    /// via [`Self::append_excerpts`] / [`Self::add_source`] as
    /// their scan progresses. The previous `EmptyExcerpts` error
    /// was relaxed when the async-provider pattern landed; see
    /// `multibuffer-views.md` §3.7.
    ///
    /// Returns `UnknownSource` if any excerpt references a
    /// source BufferId not present in `sources`.
    pub fn new(
        sources: HashMap<BufferId, Arc<dyn Document>>,
        excerpts: Vec<Excerpt>,
        registry: CommandRegistryHandle,
    ) -> Result<Self, MultibufferError> {
        for ex in &excerpts {
            if !sources.contains_key(&ex.source) {
                return Err(MultibufferError::UnknownSource {
                    excerpt: ex.id,
                    source_buffer: ex.source,
                });
            }
        }

        let id = next_multibuffer_document_id();
        let buffer_id = BufferId::next();
        let row_translation = RowTranslation::build(&excerpts);
        // M.11 (2026-06-02): build the composed Document LOCALLY
        // from source content at construction time. From here on,
        // the multibuffer's composed_doc is authoritative — edits
        // land on it synchronously; sources are downstream
        // observers that get the same edit forwarded async.
        let composed_text = compose_text_from_sources(&sources, &excerpts);
        let composed_doc = lattice_core::Document::from_text(composed_text);
        let composed =
            snapshot_from_composed_doc(&composed_doc, id, Arc::new(SelectionSet::default()));
        let snapshot_cell = Arc::new(PublishedSnapshot::new(composed));

        // M.11 (2026-06-02): spawn the source-forwarder task on
        // the shared multi-thread runtime — the same runtime that
        // owns source actors (via `spawn_document` →
        // `shared_runtime().spawn(actor.run())`). This guarantees:
        // (1) the forwarder isn't tied to the caller's runtime
        // (which may be a current_thread editor actor about to
        // block in `block_on`); (2) cross-runtime mpsc + oneshot
        // semantics aren't needed (both forwarder + source actor
        // are on the same runtime); (3) the forwarder never gets
        // starved by the caller's runtime.
        let (source_forward_tx, mut source_forward_rx) =
            tokio::sync::mpsc::unbounded_channel::<SourceForwardMsg>();
        lattice_runtime::shared_runtime().spawn(async move {
            while let Some(msg) = source_forward_rx.recv().await {
                match msg {
                    // Discard the AppliedEdit — the multibuffer's
                    // local composed_doc is already authoritative.
                    // Best-effort propagation.
                    SourceForwardMsg::Edit {
                        source_handle,
                        source_edit,
                        announce,
                    } => {
                        let applied = source_handle.apply_edit(source_edit).await;
                        // Announce the source change. Only on SUCCESS: a
                        // failed apply left the source untouched, and telling
                        // the world it changed would make every subscriber
                        // recompute against content that never existed.
                        if let (Ok(applied), Some(announce)) = (applied, announce) {
                            let snap = source_handle.snapshot();
                            // Record BEFORE publishing: the subscription runs
                            // on another task and the publish is what wakes
                            // it, so writing the version afterwards is a race
                            // this view would lose by sliding its own anchors.
                            if let Some(inner) = announce.inner.upgrade()
                                && let Ok(mut state) = inner.state.lock()
                            {
                                state
                                    .self_forwarded_versions
                                    .insert(announce.source_id, snap.text_version);
                            }
                            announce
                                .bus
                                .publish(lattice_protocol::Event::DocumentChanged {
                                    id: snap.id,
                                    path: snap.path().map(|p| p.to_path_buf()),
                                    version: snap.version,
                                    edits: vec![lattice_protocol::event::AppliedEdit {
                                        original_range: applied.original_range,
                                        inserted_range: applied.inserted_range,
                                        replaced_text: applied.replaced_text.clone(),
                                        inserted_text: applied.inserted_text.clone(),
                                    }],
                                });
                        }
                    }
                    // Same await, but the result goes back: this one has
                    // a caller that reports failure.
                    SourceForwardMsg::DirectEdit {
                        source_handle,
                        source_edit,
                        reply,
                    } => {
                        let _ = reply.send(source_handle.apply_edit(source_edit).await);
                    }
                    // FIFO: every prior Edit was applied + awaited
                    // above, so the sources are now current. Signal
                    // `save()` to proceed (best-effort — a dropped
                    // `done` just means save() falls through).
                    SourceForwardMsg::Flush { done } => {
                        let _ = done.send(());
                    }
                }
            }
        });

        Ok(Self {
            inner: Arc::new(MultibufferInner {
                id,
                buffer_id,
                state: std::sync::Mutex::new(MultibufferState {
                    source_fingerprints: sources
                        .iter()
                        .filter_map(|(id, src)| fingerprint_source(src).map(|fp| (*id, fp)))
                        .collect(),
                    self_forwarded_versions: HashMap::new(),
                    sources,
                    excerpts,
                    source_syntax: HashMap::new(),
                    selections: Arc::new(SelectionSet::default()),
                }),
                composed_doc: std::sync::Mutex::new(composed_doc),
                source_forward_tx,
                snapshot_cell,
                row_translation: ArcSwap::from_pointee(row_translation),
                headerline: ArcSwap::from_pointee(HeaderlineStatus::Idle),
                headerline_version: AtomicU64::new(0),
                subscriptions: std::sync::Mutex::new(SubscriptionBookkeeping::default()),
                registry,
                lang_registry: std::sync::OnceLock::new(),
                excerpt_syntax_gen: std::sync::atomic::AtomicU64::new(0),
                fold_grouping: std::sync::atomic::AtomicU8::new(FoldGrouping::SourceFile as u8),
                publish_seq: std::sync::atomic::AtomicU64::new(0),
            }),
        })
    }

    /// Convenience constructor for the async-provider pattern:
    /// build an empty view with no sources and no excerpts. The
    /// provider streams content in via [`Self::append_excerpts`].
    /// Infallible.
    ///
    /// K.4.11 (2026-06-02): takes the same `CommandRegistryHandle`
    /// as the full [`Self::new`] constructor. The multibuffer is
    /// grammar-capable from creation — empty-view or not.
    pub fn empty(registry: CommandRegistryHandle) -> Self {
        Self::new(HashMap::new(), Vec::new(), registry)
            .expect("empty inputs are valid; UnknownSource impossible")
    }

    pub fn buffer_id(&self) -> BufferId {
        self.inner.buffer_id
    }

    /// M.2.b.2 (2026-06-01): the multibuffer's `DocumentId`, used
    /// by the cleanup subscriber to match an `Event::DocumentClosed`
    /// payload (which carries `DocumentId`, not `BufferId`) back
    /// to a registry entry keyed by `BufferId`.
    pub fn document_id(&self) -> DocumentId {
        self.inner.id
    }

    pub fn row_translation(&self) -> Arc<RowTranslation> {
        self.inner.row_translation.load_full()
    }

    /// Snapshot the current excerpt list. M.2.b.2 (2026-06-01):
    /// returns an owned `Vec` clone because excerpts now live
    /// behind a Mutex (async providers mutate); callers that
    /// need a borrow held across `await` points or across
    /// concurrent mutations get a deterministic copy instead.
    pub fn excerpts(&self) -> Vec<Excerpt> {
        self.lock_state().excerpts.clone()
    }

    /// Count of currently-registered excerpts. Cheap probe that
    /// avoids the `Vec` clone of [`Self::excerpts`].
    pub fn excerpt_count(&self) -> usize {
        self.lock_state().excerpts.len()
    }

    pub fn source_buffer_ids(&self) -> Vec<BufferId> {
        self.lock_state().sources.keys().copied().collect()
    }

    /// OA.23b: whether `id` is one of this view's sources.
    ///
    /// Membership, not path-ness: a synthetic source has no path, and asking
    /// `source_path(..).is_some()` would say a view does not own one it does.
    pub fn has_source(&self, id: BufferId) -> bool {
        self.lock_state().sources.contains_key(&id)
    }

    /// Generic multibuffer jump-to-source: resolve a source buffer
    /// id to its on-disk path by reading the source document's path
    /// directly. Unlike the per-provider `source_path` mapping
    /// (e.g. `ProjectSearchService::source_path`), this works for
    /// ANY multibuffer view without provider-specific state — every
    /// source document carries its path through the `Document` trait.
    /// Consumed by the generic `action:multibuffer-jump-to-source`
    /// handler registered by `MultibufferMode::on_activate`. Returns
    /// `None` when the source buffer id is unknown or has no path.
    pub fn source_path(&self, source_buffer_id: BufferId) -> Option<PathBuf> {
        self.lock_state().sources.get(&source_buffer_id)?.path()
    }

    /// The current text of a source document, by the same key
    /// [`Self::source_path`] takes.
    ///
    /// PD.4: the peer of `source_path`, and it exists for the same
    /// reason — a provider that spawns its own sources (project-diff,
    /// search) hands them to `add_source` and keeps no handle, so
    /// without this there is no way to ask whether an edit made in the
    /// view actually arrived in the file's document. Propagating into
    /// *some* document proves nothing; the claim is that it reaches the
    /// one anchored to the path.
    ///
    /// Reads through the source's own snapshot, so it observes the
    /// forwarder task's progress rather than the composed rope's.
    pub fn source_text(&self, source_buffer_id: BufferId) -> Option<String> {
        Some(self.lock_state().sources.get(&source_buffer_id)?.text())
    }

    /// OA.23b: one line of a source, by the key [`Self::source_path`] takes,
    /// without its trailing newline. `None` for an unknown source or a line
    /// past its last.
    ///
    /// The read half of acting on a row's source. A caller that has located a
    /// headline through `translate_composed_to_source` needs to see the line
    /// BELOW it to know whether there is already a planning line there, and
    /// that line is outside every excerpt — the composed text cannot show it.
    ///
    /// Reads the source's own snapshot, so it sees edits the forwarder has
    /// already applied. Reading the FILE instead would not: a second `s` in a
    /// row would see the first one's absence and stack a duplicate line.
    pub fn source_line(&self, source_buffer_id: BufferId, line: u32) -> Option<String> {
        let source = self.lock_state().sources.get(&source_buffer_id)?.clone();
        source.snapshot().buffer.line(line)
    }

    /// OA.23b: a source's current snapshot, by the key [`Self::source_path`]
    /// takes. What a caller needs to publish a `DocumentChanged` for an edit
    /// it just made through [`Self::apply_to_source`].
    pub fn source_snapshot(&self, source_buffer_id: BufferId) -> Option<Arc<DocumentSnapshot>> {
        Some(self.lock_state().sources.get(&source_buffer_id)?.snapshot())
    }

    /// OA.23b: apply an edit in SOURCE coordinates to one of this view's
    /// sources — a line the view does not compose.
    ///
    /// See [`SourceForwardMsg::DirectEdit`] for why it goes through the
    /// forwarder rather than at the handle. `None` when `source_buffer_id` is
    /// not one of this view's sources; the returned `Pending` resolves to
    /// Replay `applied` — the result of an undo or redo on the composed doc —
    /// at each edit's source.
    ///
    /// Each `AppliedEdit` says a composed range held `replaced_text` and now
    /// holds `inserted_text`. Sending exactly that as a composed-coordinate
    /// `Edit` through the same translation the forward path uses is what
    /// keeps the two in step, and is why there is no second code path to
    /// drift: `resolve_edit_target` + `build_source_edit`, unchanged.
    ///
    /// Fire-and-forget onto the same FIFO the forward edits ride, so the
    /// source sees the undo strictly after the edit it undoes. A `:w` flushes
    /// that queue before reading, so a save immediately after `u` persists
    /// the undone text rather than racing it.
    pub(crate) fn forward_applied_to_sources(&self, applied: &[AppliedEdit]) {
        if applied.is_empty() {
            return;
        }
        let messages: Vec<SourceForwardMsg> = {
            let state = self.lock_state();
            applied
                .iter()
                .filter_map(|a| {
                    let edit = Edit {
                        range: a.original_range,
                        kind: lattice_protocol::edit::EditKind::Replace {
                            text: a.inserted_text.clone(),
                        },
                    };
                    let target = resolve_edit_target(&state, edit.range.start)?;
                    let source_edit = build_source_edit(&target, &edit);
                    let announce = self.announce_for(target.source_id);
                    Some(SourceForwardMsg::Edit {
                        source_handle: target.source_handle.clone(),
                        source_edit,
                        announce,
                    })
                })
                .collect()
        };
        for msg in messages {
            let _ = self.inner.source_forward_tx.send(msg);
        }
    }

    /// MU.1: symmetric with [`Self::undo`] in every respect, including
    /// carrying the result to the sources. An asymmetry here would be the
    /// nastier half of the same bug — `u` then `<C-r>` would leave the file
    /// holding the undone text.
    /// whatever the source actor made of the edit.
    pub fn apply_to_source(
        &self,
        source_buffer_id: BufferId,
        edit: Edit,
    ) -> Option<Pending<AppliedEdit>> {
        let source_handle = self.lock_state().sources.get(&source_buffer_id)?.clone();
        let (reply, rx) = tokio::sync::oneshot::channel();
        self.inner
            .source_forward_tx
            .send(SourceForwardMsg::DirectEdit {
                source_handle,
                source_edit: edit,
                reply,
            })
            .ok()?;
        // Wrapped rather than spawned: the work is already queued on the
        // forwarder, and the caller is the editor actor about to block on
        // this. See `Pending::from_channel`.
        Some(Pending::from_channel(rx))
    }

    /// M.10.2 (2026-06-03): translate a composed-coordinate
    /// cursor to its source-coordinate equivalent. Walks excerpts
    /// in display order to find the one containing
    /// `cursor.line`; returns `(source_buffer_id,
    /// source_position)` where `source_position.line` is the
    /// row in the originating source rope and
    /// `source_position.byte` is preserved verbatim (each
    /// composed row is a verbatim copy of its source line, so
    /// byte columns map 1:1).
    ///
    /// Returns `None` when the cursor is past the last
    /// excerpt's last composed row. Pure read; doesn't mutate
    /// any state.
    ///
    /// Consumed by mode handlers (search `<CR>`, project-diff
    /// `<CR>`, lsp-references `<CR>` once those land) — see
    /// `mode-architecture.md` §5.3.4 (substrate-vs-helper
    /// rule). Returning data, not behavior — the chord-binding +
    /// open-and-position logic lives in the mode's handler
    /// closure registered via the M.10.1.b
    /// `ActionHandlerRegistry`.
    pub fn translate_composed_to_source(&self, cursor: Position) -> Option<(BufferId, Position)> {
        let state = self.lock_state();
        let mut composed_cursor: u32 = 0;
        for excerpt in &state.excerpts {
            let next = composed_cursor.saturating_add(excerpt.line_count());
            if cursor.line < next {
                let offset = cursor.line - composed_cursor;
                let source_row = excerpt.start_line.saturating_add(offset);
                return Some((
                    excerpt.source,
                    Position {
                        line: source_row,
                        byte: cursor.byte,
                    },
                ));
            }
            composed_cursor = next;
        }
        None
    }

    /// M.5 (2026-06-01): grow / shrink the excerpt containing
    /// `cursor_row` by `delta_rows` total rows, split
    /// symmetrically above and below.
    ///
    /// Behaviour:
    /// - `delta_rows > 0` expands; `delta_rows < 0` contracts;
    ///   `delta_rows == 0` is a no-op.
    /// - Symmetric split: `delta_rows / 2` above, the remainder
    ///   below. With `delta_rows = 5`: 2 rows added above, 3 below.
    /// - Clip: `start_line` never goes below 0; `end_line` never
    ///   exceeds the source's last row (read from
    ///   `source.snapshot().buffer.line_count() - 1`).
    /// - Min size: if the contract would make `start > end`,
    ///   no-op (excerpt keeps its existing range).
    /// - No-op when the cursor sits outside every excerpt OR the
    ///   excerpt's source isn't in the source map (closed source).
    ///
    /// Recomposes + publishes after the mutation, matching
    /// `append_excerpts` / `replace_excerpts` shape.
    pub fn expand_excerpt_at(&self, cursor_row: u32, delta_rows: i32) {
        if delta_rows == 0 {
            return;
        }
        let mut state = self.lock_state();
        let Some(idx) = crate::motions::containing_excerpt_index(&state.excerpts, cursor_row)
        else {
            return;
        };
        // `containing_excerpt_index` returns the last excerpt for
        // rows past the view's end (motion-friendly). For
        // expand-context the cursor must actually sit within the
        // excerpt's composed range — verify by checking the
        // start-rows table.
        let starts = crate::motions::excerpt_start_rows(&state.excerpts);
        let excerpt_start_composed = starts[idx];
        let excerpt_end_composed = excerpt_start_composed
            .saturating_add(state.excerpts[idx].line_count())
            .saturating_sub(1);
        if cursor_row > excerpt_end_composed {
            return;
        }

        let source_id = state.excerpts[idx].source;
        let Some(source) = state.sources.get(&source_id) else {
            return;
        };
        // CV.3: content space — an excerpt may only expand onto lines
        // the source actually has, never the phantom one ropey reports
        // after a terminating newline.
        let source_line_count = source.snapshot().buffer.content_line_count() as i64;
        if source_line_count == 0 {
            return;
        }

        // Symmetric split: half above (integer divide rounds
        // toward zero, so positive delta puts the extra below;
        // negative delta puts the extra above).
        let above = (delta_rows / 2) as i64;
        let below = (delta_rows as i64) - above;

        let current_start = state.excerpts[idx].start_line as i64;
        let current_end = state.excerpts[idx].end_line as i64;

        let new_start = (current_start - above).clamp(0, source_line_count - 1);
        let new_end = (current_end + below).clamp(0, source_line_count - 1);

        if new_end < new_start {
            // Contract would invert: leave the excerpt as-is.
            return;
        }
        if new_start == current_start && new_end == current_end {
            // Hit both clips; no observable change.
            return;
        }

        state.excerpts[idx].start_line = new_start as u32;
        state.excerpts[idx].end_line = new_end as u32;

        let snapshot = compose_snapshot(
            self.inner.id,
            &state.sources,
            &state.excerpts,
            state.selections.clone(),
        );
        let translation = RowTranslation::build(&state.excerpts);
        drop(state);
        self.inner.snapshot_cell.store(snapshot);
        self.inner.row_translation.store(Arc::new(translation));
    }

    /// M.2.b.2 (2026-06-01): append excerpts to the end of the
    /// view. Used by async providers streaming batches of
    /// results (project-search, lsp-references, etc.). Any
    /// excerpts whose source isn't present are silently
    /// skipped (log + drop). Recomposes + publishes after the
    /// mutation.
    pub fn append_excerpts(&self, excerpts: Vec<Excerpt>) {
        if excerpts.is_empty() {
            return;
        }
        let mut state = self.lock_state();
        // MH.B1 (2026-06-19): collect the excerpts actually added
        // this call (mirroring the skip-if-missing-source filter)
        // so we can compose + translate ONLY the batch, not the
        // accumulated total.
        let mut added: Vec<Excerpt> = Vec::with_capacity(excerpts.len());
        for ex in excerpts {
            if !state.sources.contains_key(&ex.source) {
                // Silently drop — the provider is responsible
                // for adding the source first via `add_source`
                // if it's a new file. M.6 SearchProvider does
                // this in its scan task.
                continue;
            }
            state.excerpts.push(ex.clone());
            added.push(ex);
        }
        if added.is_empty() {
            // Every excerpt was dropped (unknown source). Nothing
            // to compose or publish — leave the view untouched.
            return;
        }
        // MH.B1 (2026-06-19): compose ONLY the batch we just added.
        // `compose_text_from_sources` carries no cross-excerpt
        // state — each line is pulled independently and given a
        // trailing `\n` — so composing the added sub-list yields
        // exactly the bytes that sub-list contributes to the full
        // composition. Appending those bytes to the END of the
        // existing composed_doc is therefore byte-identical to
        // `from_text(old_full_text + batch_text)`, at O(batch)
        // instead of O(total). Pinned by
        // `incremental_append_matches_full_build`.
        let batch_text = compose_text_from_sources(&state.sources, &added);
        // K.4.7: stamp with monotonic seq — `Document::apply_edit`
        // bumps text_version, but starting from a `from_text`-built
        // rope (which begins at text_version=0) means an empty view
        // streaming its first batch would land at text_version=1
        // regardless; we use the inner monotonic publish_seq so the
        // MatrixVersion advances on every publish.
        let seq = self.inner.publish_seq.fetch_add(1, Ordering::Relaxed) + 1;
        let selections = state.selections.clone();
        // MH.B1: extend (not rebuild) the row translation by the
        // batch's entries. Pure concatenation == byte-identical to
        // `RowTranslation::build(&state.excerpts)`.
        let mut translation = (*self.inner.row_translation.load_full()).clone();
        translation.append(&added);
        drop(state);
        // MH.B1 (2026-06-02 superseded): append the batch text to
        // the END of composed_doc rather than rebuilding it from
        // all sources. This APPENDS — it preserves any local edits
        // already present in composed_doc (the previous full-rebuild
        // here CLOBBERED them). Insert-at-end keeps the local rope
        // authoritative + in sync with the growing excerpt set so
        // user edits land on a rope reflecting current content.
        let snapshot = {
            let mut doc = self
                .inner
                .composed_doc
                .lock()
                .expect("composed_doc mutex poisoned");
            if !batch_text.is_empty() {
                // Insert at the very end of the current rope. The
                // end Position is derived from the rope's byte
                // length so it is correct whether or not the rope
                // ends in a trailing newline.
                let end_byte = doc.buffer().byte_len() as usize;
                let at = doc
                    .buffer()
                    .byte_to_position(end_byte)
                    .expect("end-of-rope position is always in bounds");
                // Best-effort: a failed append leaves the rope as-is
                // (recoverable — we still publish the extended
                // translation + bumped seq). Never panic on this path.
                if let Err(err) = doc.apply_edit(Edit::insert(at, batch_text)) {
                    tracing::debug!(
                        ?err,
                        "append_excerpts: composed_doc append failed; rope unchanged"
                    );
                }
            }
            let mut snapshot = snapshot_from_composed_doc(&doc, self.inner.id, selections);
            snapshot.text_version = seq;
            snapshot
        };
        self.inner.snapshot_cell.store(snapshot);
        self.inner.row_translation.store(Arc::new(translation));
    }

    /// M.2.b.2 (2026-06-01): replace the entire excerpt list +
    /// source map atomically. Used by providers reacting to a
    /// query / filter change (e.g. user refines a search). The
    /// previous excerpts are dropped; the new set is composed
    /// + published in one mutation.
    pub fn replace_excerpts(
        &self,
        sources: HashMap<BufferId, Arc<dyn Document>>,
        excerpts: Vec<Excerpt>,
    ) {
        for ex in &excerpts {
            if !sources.contains_key(&ex.source) {
                // Same skip-and-continue behaviour as append.
                // Provider's responsibility to keep sources
                // map coherent with excerpts.
            }
        }
        let mut state = self.lock_state();
        // SS.2: re-baseline against the NEW source set. Carrying the old
        // map forward would leave fingerprints for sources that are gone
        // and none for the ones just added — a refresh must not inherit
        // a stale baseline.
        state.source_fingerprints = sources
            .iter()
            .filter_map(|(id, src)| fingerprint_source(src).map(|fp| (*id, fp)))
            .collect();
        state.sources = sources;
        state.excerpts = excerpts;
        // M.11 (2026-06-02): same rebuild as `append_excerpts` —
        // keep composed_doc in sync with the new excerpt set so
        // user edits land on a rope reflecting current content.
        let composed_text = compose_text_from_sources(&state.sources, &state.excerpts);
        let new_composed_doc = lattice_core::Document::from_text(composed_text);
        // K.4.7: same monotonic seq stamp as append_excerpts.
        let seq = self.inner.publish_seq.fetch_add(1, Ordering::Relaxed) + 1;
        let mut snapshot =
            snapshot_from_composed_doc(&new_composed_doc, self.inner.id, state.selections.clone());
        snapshot.text_version = seq;
        let translation = RowTranslation::build(&state.excerpts);
        drop(state);
        {
            let mut doc = self
                .inner
                .composed_doc
                .lock()
                .expect("composed_doc mutex poisoned");
            *doc = new_composed_doc;
        }
        self.inner.snapshot_cell.store(snapshot);
        self.inner.row_translation.store(Arc::new(translation));
    }

    /// M.2.b.2 (2026-06-01): add a source buffer to the view's
    /// source map. Subsequent `append_excerpts` calls can
    /// reference it. Idempotent: re-adding an existing source
    /// updates the handle reference (which may have been
    /// replaced via slot-replacement upstream).
    ///
    /// K.4.7 (2026-06-07): if `set_lang_registry` has been called,
    /// detect the source's language from its path and create a
    /// long-lived `SyntaxHandle` for it. The handle worker runs on
    /// the tokio runtime of the caller (the scan task); subsequent
    /// reparsing is async and wait-free at read time.
    /// SS.2: the recorded on-disk baseline for `source`, if any.
    /// `None` for a pathless (synthetic) source, which is never stale.
    pub fn source_fingerprint(
        &self,
        source: BufferId,
    ) -> Option<lattice_core::on_disk::OnDiskFingerprint> {
        self.lock_state().source_fingerprints.get(&source).cloned()
    }

    pub fn add_source(&self, id: BufferId, source: Arc<dyn Document>) {
        let mut state = self.lock_state();
        if let Some(fp) = fingerprint_source(&source) {
            state.source_fingerprints.insert(id, fp);
        }
        state.sources.insert(id, source.clone());
        let path = source.path();
        tracing::debug!(
            buffer = ?id,
            path = ?path,
            has_lang_registry = self.inner.lang_registry.get().is_some(),
            "add_source: checking for syntax handle creation"
        );
        if self.inner.lang_registry.get().is_some() {
            let lang = Lang::detect_from_path(path.as_deref());
            tracing::debug!(buffer = ?id, ?lang, "add_source: detected language");
            if lang != Lang::Plain {
                // AH.1: resolve against the LIVE registry, not the stored
                // handle.
                //
                // `LangRegistry::standard()` *is* `registry::live()` — it
                // returns a SNAPSHOT of the process-global ArcSwap. Plugin
                // grammars arrive later: `install_plugin_config` RCUs a new
                // `LangRegistry` in, which leaves every previously-held `Arc`
                // pointing at the value from before the plugin loaded. The
                // stored registry is captured at boot, so it is bundled-only
                // and can NEVER contain a plugin language.
                //
                // The symptom was total and silent: every excerpt over a
                // plugin-language file — the whole org agenda — got no
                // `SyntaxHandle`, so every row painted uncoloured while the
                // same file syntax-highlighted perfectly when opened directly.
                // `detect_from_path` resolved `.org` correctly, the registry
                // was present, and the grammar existed; only the registry
                // being asked was the wrong one.
                //
                // The stored field survives as the host's "is highlighting
                // wired" gate (`set_lang_registry` is what turns this on) —
                // its VALUE is what could not be trusted, not its presence.
                let live = match lattice_syntax::registry::live() {
                    Ok(lr) => lr,
                    Err(e) => {
                        tracing::debug!(buffer = ?id, error = ?e, "add_source: no live registry");
                        return;
                    }
                };
                match Syntax::for_language_with_registry(lang, live) {
                    Ok(Some(mut syntax)) => {
                        let snap = source.snapshot();
                        let text = snap.buffer.as_string();
                        syntax.parse(&text);
                        let handle = self.seed_source_syntax(syntax);
                        state.source_syntax.insert(id, Arc::new(handle));
                        self.inner
                            .excerpt_syntax_gen
                            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
                        tracing::debug!(buffer = ?id, ?lang, "add_source: syntax handle created");
                    }
                    Ok(None) => {
                        tracing::debug!(buffer = ?id, ?lang, "add_source: no grammar registered");
                    }
                    Err(e) => {
                        tracing::debug!(buffer = ?id, ?lang, error = ?e, "add_source: grammar error");
                    }
                }
            }
        }
    }

    /// K.4.7 (2026-06-07): enable per-source syntax highlighting.
    /// Called by the host immediately after `create_multibuffer_view`.
    /// Subsequent `add_source` calls use the registry to detect the
    /// source language and create a `SyntaxHandle` per source.
    ///
    /// AF.1: how this view's rows group for folding. Declared by the provider
    /// that builds the view, because the provider is the only thing that knows
    /// what its rows MEAN — see [`FoldGrouping`].
    pub fn set_fold_grouping(&self, grouping: FoldGrouping) {
        self.inner
            .fold_grouping
            .store(grouping as u8, std::sync::atomic::Ordering::Relaxed);
    }

    /// This view's fold grouping. [`FoldGrouping::SourceFile`] unless a
    /// provider said otherwise, which is the pre-AF.1 behaviour.
    pub fn fold_grouping(&self) -> FoldGrouping {
        match self
            .inner
            .fold_grouping
            .load(std::sync::atomic::Ordering::Relaxed)
        {
            x if x == FoldGrouping::HeaderRuns as u8 => FoldGrouping::HeaderRuns,
            _ => FoldGrouping::SourceFile,
        }
    }

    /// Also retroactively creates handles for sources that were already
    /// added before this call (the common case: `new(sources, ...)` is
    /// called first, then `set_lang_registry` wires highlighting).
    pub fn set_lang_registry(&self, lr: Arc<LangRegistry>) {
        if self.inner.lang_registry.set(lr).is_err() {
            return;
        }
        // AH.1 (mirrored from `add_source`): the back-fill must resolve
        // grammars against the LIVE process-global registry, NOT the `lr`
        // just stored. `lr` is a boot snapshot — bundled-only, captured before
        // any plugin grammar RCUs itself in — so resolving against it silently
        // drops every excerpt over a plugin-language file (the whole org agenda
        // painted uncoloured while the same file highlighted fine opened
        // directly). This is the path `*problems*` and the references view take
        // (all sources handed to `new` up front, then back-filled here), where
        // `add_source`'s streaming path — already on the live registry — is
        // what project-search uses; the asymmetry was why search highlighted
        // and `*problems*` did not. The stored field survives as the "is
        // highlighting wired" gate; only its VALUE could not be trusted.
        let live = match lattice_syntax::registry::live() {
            Ok(reg) => reg,
            Err(e) => {
                tracing::debug!(error = ?e, "set_lang_registry: no live registry; back-fill skipped");
                return;
            }
        };
        let mut state = self.lock_state();
        let ids: Vec<(BufferId, Arc<dyn Document>)> = state
            .sources
            .iter()
            .filter(|(id, _)| !state.source_syntax.contains_key(id))
            .map(|(id, src)| (*id, src.clone()))
            .collect();
        let mut added = 0u64;
        for (id, source) in ids {
            let lang = Lang::detect_from_path(source.path().as_deref());
            if lang == Lang::Plain {
                continue;
            }
            if let Ok(Some(mut syntax)) = Syntax::for_language_with_registry(lang, live.clone()) {
                let snap = source.snapshot();
                let text = snap.buffer.as_string();
                syntax.parse(&text);
                let handle = self.seed_source_syntax(syntax);
                state.source_syntax.insert(id, Arc::new(handle));
                added += 1;
            }
        }
        if added > 0 {
            self.inner
                .excerpt_syntax_gen
                .fetch_add(added, std::sync::atomic::Ordering::Relaxed);
        }
    }

    /// The payload the forwarder needs to announce a source change, or `None`
    /// before `attach_event_subscriptions` has handed this view a bus.
    ///
    /// `None` is the correct quiet case, not a failure: with no bus there is
    /// no subscriber to tell, and a view that has not been attached yet is not
    /// on screen.
    fn announce_for(&self, source_id: BufferId) -> Option<AnnounceSource> {
        let bus = self
            .inner
            .subscriptions
            .lock()
            .ok()
            .and_then(|b| b.bus.clone())?;
        Some(AnnounceSource {
            source_id,
            inner: Arc::downgrade(&self.inner),
            bus,
        })
    }

    /// Build a source's `SyntaxHandle` with its reparse WAKE already wired.
    ///
    /// The one constructor both creation sites use, because the wake is the
    /// part that gets forgotten. `SyntaxHandle::seeded` passes
    /// `on_publish: None`, so a handle built with it parses exactly once and
    /// its snapshot is frozen for the life of the view. That is what made a
    /// task toggled to DONE keep painting in TODO's colour: the composed text
    /// updated (the `DocumentChanged` arm recomposes), the spans did not, and
    /// re-rendering — including `<C-l>` — re-read the same frozen snapshot, so
    /// the one escape hatch a user has did not work either.
    ///
    /// `on_publish` does the two things a fresh parse needs:
    ///
    /// 1. **Bump `excerpt_syntax_gen`.** It is folded into
    ///    `MatrixVersion::syntax`, so without it the cells worker sees an
    ///    unchanged version and returns `CacheHit` — a correct new snapshot
    ///    nobody reads.
    /// 2. **Publish `MultibufferExcerptsReady`.** `install`'s
    ///    `wake_on_event` turns it into `async_landed`, which is what makes an
    ///    async result reach the screen with no keypress in flight. A reparse
    ///    that lands while the user is reading their agenda has no next
    ///    keystroke to hide behind.
    ///
    /// Mirrors how the host wires a regular document's handle
    /// (`seeded_with_runtime` + a wake that fires `async_landed` and an
    /// invalidation event) rather than inventing a second mechanism.
    fn seed_source_syntax(&self, syntax: Syntax) -> SyntaxHandle {
        let weak = Arc::downgrade(&self.inner);
        let view = self.inner.buffer_id;
        SyntaxHandle::seeded_with_runtime(
            syntax,
            lattice_runtime::shared_runtime(),
            Some(Arc::new(move || {
                let Some(inner) = weak.upgrade() else {
                    return;
                };
                inner
                    .excerpt_syntax_gen
                    .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
                // The bus is stashed by `attach_event_subscriptions`; before
                // that there is no one to wake and nothing on screen yet.
                let bus = inner.subscriptions.lock().ok().and_then(|b| b.bus.clone());
                if let Some(bus) = bus {
                    bus.publish_typed(crate::events::MultibufferExcerptsReady { view });
                }
            })),
        )
    }

    /// K.4.7 (2026-06-08): monotonic version that increments whenever
    /// per-source `SyntaxHandle`s are created. Used by `publish_render_state`
    /// to invalidate the cells-worker cache when handles are first populated.
    pub fn excerpt_syntax_version(&self) -> u64 {
        self.inner
            .excerpt_syntax_gen
            .load(std::sync::atomic::Ordering::Relaxed)
    }

    /// K.4.7 (2026-06-07): per-excerpt syntax entries for the cells
    /// worker. Each entry is `(composed_start, composed_end,
    /// source_start, handle)` where `composed_start`/`composed_end`
    /// are inclusive row bounds in the composed snapshot (0-indexed)
    /// and `source_start` is the first source row mapped to
    /// `composed_start`. Only excerpts with a `SyntaxHandle` are
    /// included.
    pub fn excerpt_syntax_entries(&self) -> Vec<(u32, u32, u32, Arc<SyntaxHandle>)> {
        let state = self.lock_state();
        let mut entries = Vec::new();
        let mut composed_row = 0u32;
        for ex in &state.excerpts {
            let line_count = ex.end_line.saturating_sub(ex.start_line) + 1;
            if let Some(handle) = state.source_syntax.get(&ex.source) {
                let composed_end = composed_row + line_count - 1;
                entries.push((composed_row, composed_end, ex.start_line, handle.clone()));
            }
            composed_row += line_count;
        }
        entries
    }

    /// Recompose the snapshot from current source state.
    /// Rebuilds the composed buffer + row translation, then
    /// publishes via `ArcSwap::store`.
    ///
    /// M.1 shipped this as a manual API; M.4 wires automatic
    /// invocation via source-edit event subscriptions. M.2.b.2
    /// kept the public surface stable but rerouted reads through
    /// the Mutex.
    pub fn recompose(&self) {
        let state = self.lock_state();
        let new_snapshot = compose_snapshot(
            self.inner.id,
            &state.sources,
            &state.excerpts,
            state.selections.clone(),
        );
        let new_translation = RowTranslation::build(&state.excerpts);
        drop(state);
        self.inner.snapshot_cell.store(new_snapshot);
        self.inner.row_translation.store(Arc::new(new_translation));
    }

    fn lock_state(&self) -> std::sync::MutexGuard<'_, MultibufferState> {
        self.inner
            .state
            .lock()
            .expect("MultibufferInner state mutex poisoned")
    }

    /// M.4 (2026-06-01): the view's current headerline status.
    /// Lock-free read.
    pub fn headerline(&self) -> Arc<HeaderlineStatus> {
        self.inner.headerline.load_full()
    }

    /// M.4 (2026-06-01): set the view's headerline status.
    /// Publishes `MultibufferHeaderlineChanged` on the event bus
    /// the handle was attached to (no-op if
    /// [`Self::attach_event_subscriptions`] hasn't been called —
    /// the status still updates locally).
    pub fn set_headerline(&self, status: HeaderlineStatus) {
        let bus = self
            .inner
            .subscriptions
            .lock()
            .ok()
            .and_then(|book| book.bus.clone());
        self.inner.headerline.store(Arc::new(status.clone()));
        self.inner
            .headerline_version
            .fetch_add(1, Ordering::Release);
        if let Some(bus) = bus {
            bus.publish_typed(MultibufferHeaderlineChanged {
                view: self.inner.buffer_id,
                status,
            });
        }
    }

    /// M.4 (2026-06-01): subscribe the view to its sources'
    /// `DocumentChanged` / `DocumentClosed` events. On a source
    /// change, the view auto-recomposes; on a source close, the
    /// view publishes [`MultibufferSourceClosed`] and removes the
    /// source from its internal map.
    ///
    /// Subscriptions live until the handle drops — `MultibufferInner::drop`
    /// unsubscribes via the bookkeeping. The spawned forwarder
    /// task holds a `Weak<MultibufferInner>` so it exits cleanly
    /// once the handle is dropped.
    ///
    /// Idempotent: re-calling on an already-attached handle is a
    /// no-op. Requires a current tokio runtime context (the
    /// forwarder task is spawned via `tokio::spawn`).
    pub fn attach_event_subscriptions(&self, events: &Arc<lattice_runtime::EventBus>) {
        let mut book = self
            .inner
            .subscriptions
            .lock()
            .expect("subscriptions mutex poisoned");
        if book.bus.is_some() {
            // Already attached.
            return;
        }
        // Drop into the no-tokio-runtime case gracefully: the
        // event-bus subscribe still works, but the forwarder
        // task can't spawn. Match `register_multibuffer_modes`'s
        // shape.
        if tokio::runtime::Handle::try_current().is_err() {
            tracing::debug!(
                "MultibufferDocumentHandle::attach_event_subscriptions: no tokio runtime; \
                 skipping forwarder task wiring (expected in test paths)"
            );
            // Still stash the bus so set_headerline can publish.
            book.bus = Some(events.clone());
            return;
        }

        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<lattice_protocol::Event>();
        let sub_id = events.subscribe(
            lattice_runtime::EventFilter::kinds(vec![
                lattice_protocol::EventKind::DocumentChanged,
                lattice_protocol::EventKind::DocumentClosed,
            ]),
            lattice_runtime::SubscriptionTarget::Channel(tx),
        );
        book.ids.push(sub_id);
        book.bus = Some(events.clone());
        drop(book);

        let weak_inner = Arc::downgrade(&self.inner);
        let events_for_task = events.clone();
        tokio::spawn(async move {
            while let Some(event) = rx.recv().await {
                let Some(inner) = weak_inner.upgrade() else {
                    break;
                };
                match event {
                    lattice_protocol::Event::DocumentChanged {
                        id, edits, version, ..
                    } => {
                        if let Some(source_id) = source_buffer_for_document_id(&inner, id) {
                            // Is this our OWN edit coming back? The composed
                            // edit already moved the rope and the anchors, so
                            // treating the echo as an outside change would
                            // slide every excerpt below the edited row a
                            // second time.
                            let echo = take_self_forwarded(&inner, source_id, version);
                            // M.4.1: slide excerpts whose start
                            // row sits strictly below the edit's
                            // original end. Edits that overlap
                            // an excerpt's range, or sit below
                            // it, leave excerpts alone — the
                            // recompose picks up the new
                            // content for in-excerpt edits.
                            if !echo {
                                slide_anchors_for_source(&inner, source_id, &edits);
                                recompose_inner(&inner);
                            }
                            // Reparse on BOTH paths. The echo is the case that
                            // matters most — an edit made THROUGH the view is
                            // how a task gets toggled to DONE — and it is the
                            // one where the composed text is already right, so
                            // skipping the reparse here is precisely the "new
                            // text, old colours" bug.
                            reparse_source_syntax(&inner, source_id);
                            // PD.7c: the view has recomposed correctly;
                            // what may now be wrong is whatever the
                            // PROVIDER derived from this source's
                            // content. Tell it, with the translation
                            // already done — the source map lives here.
                            events_for_task.publish_typed(MultibufferSourceEdited {
                                view: inner.buffer_id,
                                source: source_id,
                            });
                        }
                    }
                    lattice_protocol::Event::DocumentClosed { id } => {
                        if let Some(source_id) = source_buffer_for_document_id(&inner, id) {
                            // Remove the source from our map.
                            if let Ok(mut state) = inner.state.lock() {
                                state.sources.remove(&source_id);
                            }
                            // Publish the typed event so providers
                            // pick up the close + choose policy.
                            events_for_task.publish_typed(MultibufferSourceClosed {
                                view: inner.buffer_id,
                                source: source_id,
                            });
                            // Recompose: removed source's
                            // excerpts will render empty rows
                            // (no entries in the source map).
                            recompose_inner(&inner);
                        }
                    }
                    _ => {}
                }
            }
        });
    }
}

/// Translate a [`DocumentId`] (carried by `Event::DocumentChanged`
/// / `Event::DocumentClosed`) to the `BufferId` key in our source
/// map, if the document is one of our sources.
fn source_buffer_for_document_id(
    inner: &Arc<MultibufferInner>,
    document_id: DocumentId,
) -> Option<BufferId> {
    let state = inner.state.lock().ok()?;
    state
        .sources
        .iter()
        .find(|(_, h)| h.id() == document_id)
        .map(|(id, _)| *id)
}

/// M.4.1 (2026-06-01): walk the `AppliedEdit`s from a source's
/// `DocumentChanged` event and slide excerpts of that source
/// whose `start_line` sits strictly below the edit's original
/// end row. Edits overlapping or below the excerpt leave it
/// alone — the recompose picks up new content for in-excerpt
/// edits; below-edits don't affect the excerpt's position.
///
/// Behaviourally equivalent to anchor tracking in the
/// linewise case (which is what excerpts care about — they're
/// line-bounded). A first-class `Anchor` primitive (line + col +
/// generation) can land later if column-precise tracking
/// proves load-bearing (none of the M.4.1 worked examples
/// need it).
///
/// Conservative bias: edits whose original_range end is AT or
/// ABOVE the excerpt's start_line don't slide. Erring against
/// false-positive slides keeps the user's mental model stable
/// when an edit straddles an excerpt boundary.
fn slide_anchors_for_source(
    inner: &Arc<MultibufferInner>,
    source: BufferId,
    edits: &[lattice_protocol::event::AppliedEdit],
) {
    if edits.is_empty() {
        return;
    }
    let Ok(mut state) = inner.state.lock() else {
        return;
    };
    for edit in edits {
        let old_end_row = edit.original_range.end.line;
        let new_end_row = edit.inserted_range.end.line;
        let row_delta = (new_end_row as i64) - (old_end_row as i64);
        if row_delta == 0 {
            continue;
        }
        for excerpt in state.excerpts.iter_mut() {
            if excerpt.source != source {
                continue;
            }
            if old_end_row < excerpt.start_line {
                let new_start = (excerpt.start_line as i64).saturating_add(row_delta).max(0);
                let new_end = (excerpt.end_line as i64).saturating_add(row_delta).max(0);
                excerpt.start_line = new_start as u32;
                excerpt.end_line = new_end as u32;
            }
        }
    }
}

/// Was this `DocumentChanged` the view's OWN forwarded edit coming back?
///
/// Consumes the record when it matches, so the answer is true exactly once per
/// forwarded edit: a later outside change at a higher version is a genuine
/// outside change and must slide anchors normally.
///
/// Compares `>=` rather than `==` because several composed edits can be in
/// flight at once (`apply_edit_batch`), and the newest recorded version is the
/// tip of what this view produced. A stale record below the incoming version
/// cannot be an echo of it.
fn take_self_forwarded(inner: &Arc<MultibufferInner>, source_id: BufferId, version: u64) -> bool {
    let Ok(mut state) = inner.state.lock() else {
        return false;
    };
    match state.self_forwarded_versions.get(&source_id).copied() {
        Some(recorded) if recorded >= version => {
            if recorded == version {
                state.self_forwarded_versions.remove(&source_id);
            }
            true
        }
        _ => false,
    }
}

/// Ask a source's `SyntaxHandle` to reparse, after that source's text changed.
///
/// Peer of [`recompose_inner`], and called beside it for the same reason: a
/// `DocumentChanged` makes BOTH the composed text and the source's spans
/// stale, and recomposing only the first is what leaves new text under old
/// colours.
///
/// **Full reparse — `edits` is empty on purpose.** The worker reads empty
/// edits as "reparse from scratch", which is always correct. The incremental
/// path would need the event's `AppliedEdit`s translated into tree-sitter
/// deltas against the version the handle's cached tree is actually at, and a
/// delta applied to the wrong baseline corrupts the tree silently — colours
/// that are wrong until something forces a full parse, which is the bug class
/// this function exists to close, reintroduced one layer down. Sources are
/// agenda-sized files and the parse runs on the handle's own blocking pool,
/// off both the UI thread and this event task; if it ever shows up in a
/// profile the deltas can be threaded through then, with a test that pins the
/// baseline.
fn reparse_source_syntax(inner: &Arc<MultibufferInner>, source_id: BufferId) {
    let Ok(state) = inner.state.lock() else {
        return;
    };
    let (Some(handle), Some(source)) = (
        state.source_syntax.get(&source_id).cloned(),
        state.sources.get(&source_id).cloned(),
    ) else {
        return;
    };
    drop(state);
    let snap = source.snapshot();
    let from = handle.with_snapshot(|s| s.text_version());
    handle.request_reparse(from, snap.text_version, snap.buffer.clone(), Vec::new());
}

/// Recompose an Inner — same shape as `MultibufferDocumentHandle::recompose`
/// but works against an `Arc<MultibufferInner>` so the forwarder
/// task can call it without holding a strong handle reference.
fn recompose_inner(inner: &Arc<MultibufferInner>) {
    let Ok(state) = inner.state.lock() else {
        return;
    };
    let new_snapshot = compose_snapshot(
        inner.id,
        &state.sources,
        &state.excerpts,
        state.selections.clone(),
    );
    let new_translation = RowTranslation::build(&state.excerpts);
    drop(state);
    inner.snapshot_cell.store(new_snapshot);
    inner.row_translation.store(Arc::new(new_translation));
}

impl Document for MultibufferDocumentHandle {
    fn snapshot(&self) -> Arc<DocumentSnapshot> {
        self.inner.snapshot_cell.load()
    }

    fn snapshot_cache(&self) -> SnapshotCache {
        SnapshotCache::new(self.inner.snapshot_cell.clone())
    }

    /// M.3 (2026-06-01): translate the composed-coordinate `edit`
    /// to its source-coordinate equivalent and forward to the
    /// source document's `apply_edit`.
    ///
    /// The returned `Pending<AppliedEdit>` carries the source's
    /// AppliedEdit — ranges + delta in source coordinates. Caller
    /// recompose()s (M.3) or auto-subscribes (M.4) to reflect.
    ///
    /// Boundary clipping (architecture §4): if `edit.range.end`
    /// extends past the start excerpt's last composed row, the
    /// end is clipped to the end-of-line of the excerpt's last
    /// source row. The edit's contribution to subsequent
    /// excerpts (and their sources) is dropped — matching Zed's
    /// "edits stay in the excerpt" rule. Out-of-range edits
    /// (cursor past view end, no excerpts) return
    /// `RuntimeError::ReadOnly`.
    fn apply_edit(&self, edit: Edit) -> Pending<AppliedEdit> {
        // M.11 (2026-06-02): byte-identical shape to
        // `RopeDocumentHandle::apply_edit` — mutate the LOCAL
        // composed rope, publish the new snapshot, return
        // synchronously. The multibuffer is now a true buffer at
        // the substrate level: insert-mode keystrokes, motions,
        // operators, undo/redo all flow through the same
        // `Document` code path as a regular `Document`. No
        // cross-actor round-trip, no Pending::spawn, no race
        // with M.4 forwarder. Source actors catch up async via
        // the source-forwarder task spawned at construction.
        //
        // Look up where the edit lands so the source forwarder
        // can translate to source coords. The lookup uses the
        // PRE-edit row translation (the only one that still
        // describes the source position the cursor is on); after
        // the edit the composed_doc's contents diverge from the
        // source until the forwarder catches up, but the row
        // translation continues to describe excerpt boundaries
        // in the composed view (one row per excerpt today).
        let state = self.lock_state();
        let source_forward = resolve_edit_target(&state, edit.range.start).map(|target| {
            let source_edit = build_source_edit(&target, &edit);
            SourceForwardMsg::Edit {
                source_handle: target.source_handle.clone(),
                source_edit,
                announce: self.announce_for(target.source_id),
            }
        });
        drop(state);

        // Mutate the local composed_doc synchronously.
        let applied = {
            let mut doc = self
                .inner
                .composed_doc
                .lock()
                .expect("composed_doc mutex poisoned");
            match doc.apply_edit(edit) {
                Ok(applied) => {
                    // Publish the post-edit snapshot before
                    // releasing the lock so consumers see a
                    // consistent (rope, version) pair.
                    let selections = self.lock_state().selections.clone();
                    let snap = snapshot_from_composed_doc(&doc, self.inner.id, selections);
                    self.inner.snapshot_cell.store(snap);
                    applied
                }
                Err(e) => return Pending::ready(Err(RuntimeError::Core(e))),
            }
        };

        // Fire-and-forget source forwarding. `try_send` so a full
        // unbounded mpsc (effectively impossible) doesn't block;
        // the forwarder task drains FIFO order so source actors
        // see edits in the same order the user typed them. If
        // construction had no tokio runtime (test paths), the rx
        // half was dropped and try_send returns Err — that's
        // expected, edits stay local-only.
        if let Some(msg) = source_forward {
            let _ = self.inner.source_forward_tx.send(msg);
        }

        Pending::ready(Ok(applied))
    }

    /// M.3 (2026-06-01): translate + forward each edit to its
    /// source. The batch is serialised through `apply_edit`
    /// per-edit and combined via `Pending::spawn` so the
    /// returned `Pending` resolves asynchronously without
    /// blocking the runtime. Multi-source batches dispatch
    /// each sub-edit sequentially; per-edit parallelism is a
    /// later refinement once a consumer needs it.
    fn apply_edit_batch(&self, edits: Vec<Edit>) -> Pending<Vec<AppliedEdit>> {
        Pending::ready(self.apply_edit_batch_sync(edits))
    }

    /// MU.1: undo the composed view **and carry it to the sources**.
    ///
    /// ## Why this is not `source.undo()`
    ///
    /// The obvious shape — fan out and pop each source's undo stack — is
    /// wrong twice over, and the code carried both bugs in turn.
    ///
    /// It is wrong on *correctness*: a source's undo stack is its own. If a
    /// third pane edited that file since, its most-recent entry is the third
    /// pane's edit, so `u` in the multibuffer would silently roll back
    /// somebody else's work. The old comment here called that "v1 atomicity"
    /// and queued transaction tracking for later; that is the later.
    ///
    /// It was also wrong on *liveness*: the pre-M.11 version awaited each
    /// source and deadlocked the editor actor. M.11 fixed it by dropping the
    /// fan-out entirely, which left `u` looking like it worked while the file
    /// on disk kept the change — a visual undo over a real edit, which is the
    /// worse failure of the two because nothing on screen says so.
    ///
    /// ## What it does instead
    ///
    /// The undo's OWN result is the transaction record. `composed_doc.undo()`
    /// returns `AppliedEdit`s describing exactly what changed in composed
    /// coordinates — `original_range` and `inserted_text` — so each one is
    /// replayed at its source through the same `resolve_edit_target` +
    /// `build_source_edit` translation the forward path uses.
    ///
    /// Nothing is guessed and nothing is stored: the record is derived from
    /// the operation that just happened, so it cannot drift from it, and a
    /// concurrent edit in another pane is untouched because we address a
    /// range rather than pop a stack.
    fn undo(&self) -> Pending<Vec<AppliedEdit>> {
        let applied = {
            let mut doc = self
                .inner
                .composed_doc
                .lock()
                .expect("composed_doc mutex poisoned");
            match doc.undo() {
                Ok(applied) => {
                    let selections = self.lock_state().selections.clone();
                    let snap = snapshot_from_composed_doc(&doc, self.inner.id, selections);
                    self.inner.snapshot_cell.store(snap);
                    applied
                }
                Err(e) => return Pending::ready(Err(RuntimeError::Core(e))),
            }
        };
        // AFTER the composed_doc lock is released, like `apply_edit` — the
        // forwarding takes the state lock, and taking it under the doc lock
        // would invent a lock order this file otherwise does not have.
        self.forward_applied_to_sources(&applied);
        Pending::ready(Ok(applied))
    }

    fn redo(&self) -> Pending<Vec<AppliedEdit>> {
        let applied = {
            let mut doc = self
                .inner
                .composed_doc
                .lock()
                .expect("composed_doc mutex poisoned");
            match doc.redo() {
                Ok(applied) => {
                    let selections = self.lock_state().selections.clone();
                    let snap = snapshot_from_composed_doc(&doc, self.inner.id, selections);
                    self.inner.snapshot_cell.store(snap);
                    applied
                }
                Err(e) => return Pending::ready(Err(RuntimeError::Core(e))),
            }
        };
        self.forward_applied_to_sources(&applied);
        Pending::ready(Ok(applied))
    }

    fn save(&self) -> Pending<std::path::PathBuf> {
        // 2026-06-10: save every dirty source back to disk. Generic
        // for ALL multibuffer views (narrow, project-search, future
        // diff / references): the host's `save_blocking` calls this
        // `Document::save` uniformly, so `:w` persists the underlying
        // files with no kind-branch.
        //
        // Edits reach sources ASYNC via the source-forwarder, so we
        // FLUSH it first — a barrier sent through the same FIFO
        // channel guarantees every queued edit has been applied to
        // (and awaited on) its source actor before we read + save the
        // sources. Without the flush, `:w` races the forwarder and
        // could persist a source missing the user's last keystrokes.
        // SS.3: carry each source's baseline alongside it so the write
        // can be refused if the file moved underneath the view.
        let sources: Vec<(
            Arc<dyn Document>,
            Option<lattice_core::on_disk::OnDiskFingerprint>,
        )> = {
            let state = self.lock_state();
            state
                .sources
                .iter()
                .map(|(id, src)| (src.clone(), state.source_fingerprints.get(id).cloned()))
                .collect()
        };
        let forward_tx = self.inner.source_forward_tx.clone();
        Pending::spawn(async move {
            // Flush barrier. Best-effort: if the forwarder is gone the
            // send fails and we fall through (sources are as current
            // as they can be); if `done` is dropped the await errors
            // and we likewise proceed.
            let (done_tx, done_rx) = tokio::sync::oneshot::channel();
            if forward_tx
                .send(SourceForwardMsg::Flush { done: done_tx })
                .is_ok()
            {
                let _ = done_rx.await;
            }

            // Save each dirty source; report the first saved path for
            // the `:w` echo. A view whose sources are all clean reports
            // the first source's path as a no-op success (matching
            // vim's `:w` on an unmodified buffer); an empty view (no
            // sources) is `ReadOnly`.
            let mut saved_path: Option<std::path::PathBuf> = None;
            let mut fallback_path: Option<std::path::PathBuf> = None;
            let mut last_err: Option<RuntimeError> = None;
            let mut skipped: Vec<std::path::PathBuf> = Vec::new();
            for (source, baseline) in &sources {
                if fallback_path.is_none() {
                    fallback_path = source.path();
                }
                if !source.dirty() {
                    continue;
                }
                // SS.3: refuse a source whose file changed on disk after
                // the view snapshotted it. Writing it would silently
                // discard that external change — the whole reason this
                // guard exists.
                //
                // Refuse the SOURCE, not the save: a 30-file view must
                // not fail wholesale because one file moved, and a save
                // that fails wholesale teaches a `:w!` habit that
                // discards exactly what is being protected.
                if let (Some(path), Some(baseline)) = (source.path(), baseline.as_ref())
                    && is_stale_on_disk(&path, baseline)
                {
                    tracing::warn!(
                        path = %path.display(),
                        "multibuffer save: source changed on disk since the view loaded it; \
                         refusing to overwrite"
                    );
                    skipped.push(path);
                    continue;
                }
                match source.save().await {
                    Ok(path) => {
                        saved_path.get_or_insert(path);
                    }
                    Err(e) => {
                        last_err = Some(e);
                    }
                }
            }
            if let Some(e) = last_err {
                return Err(e);
            }
            if !skipped.is_empty() {
                // Surface WHICH files, not a count: the user has to go
                // look at them, and the recovery (refresh the view —
                // `gr`, `:copen`, `:search`) re-reads from disk. The
                // other sources already persisted above; this is a
                // partial-success report.
                return Err(RuntimeError::SourcesChangedOnDisk { paths: skipped });
            }
            saved_path.or(fallback_path).ok_or(RuntimeError::ReadOnly)
        })
    }

    fn save_as(&self, _path: std::path::PathBuf) -> Pending<()> {
        Pending::ready(Err(RuntimeError::ReadOnly))
    }

    fn set_selections(&self, selections: SelectionSet) -> Pending<()> {
        // K.4.5 (2026-06-02): selections ARE view-owned in the
        // composed coordinate space (M.3 design — they don't
        // propagate to sources). Prior shape returned
        // `Err(ReadOnly)` which left the snapshot's selections
        // at `SelectionSet::default()`, breaking Visual-mode
        // highlight painting on multibuffer views
        // (`Editor::visual_selection_range` reads
        // `self.document.selections().primary()` uniformly
        // across BufferKinds — the right fix is for the
        // Document impl to honour the call, not for callers
        // to special-case multibuffer).
        //
        // Store the new selection set in `state.selections`
        // and rebuild the snapshot so the next snapshot read
        // sees the updated selections. Synchronous (Mutex-
        // routed write + ArcSwap publish) so
        // `set_selections_blocking` callers see the change
        // immediately. See [[feedback_buffers_no_special_case]].
        let selections = Arc::new(selections);
        let snapshot = {
            let mut state = self.lock_state();
            state.selections = Arc::clone(&selections);
            compose_snapshot(self.inner.id, &state.sources, &state.excerpts, selections)
        };
        self.inner.snapshot_cell.store(snapshot);
        Pending::ready(Ok(()))
    }

    /// K.4.6 follow-up (2026-06-02): publish the composed→source
    /// row map so the gutter can show original file line numbers
    /// (429, 430, 432, …) instead of composed-row indices
    /// (0, 1, 2, …). Walks the published `RowTranslation` once
    /// per call; cheap (typical N = hundreds-to-thousands; called
    /// once per render-state publish, NOT per keystroke).
    fn display_line_numbers(&self) -> Option<Arc<[u32]>> {
        let translation = self.inner.row_translation.load_full();
        let rows: Vec<u32> = translation
            .entries
            .iter()
            .map(|e| match e {
                RowEntry::Excerpt { source_row, .. } => *source_row,
            })
            .collect();
        Some(Arc::from(rows.into_boxed_slice()))
    }

    // K.4.7 (2026-06-08): mode owns its highlighting surface. The host's
    // `publish_render_state` calls these uniformly on every document; no
    // `BufferKind` branch needed there.
    fn excerpt_highlights(&self) -> Vec<lattice_cells::ExcerptHighlight> {
        let state = self.lock_state();
        let mut out = Vec::new();
        let mut composed_row = 0u32;
        for ex in &state.excerpts {
            let line_count = ex.end_line.saturating_sub(ex.start_line) + 1;
            if let Some(handle) = state.source_syntax.get(&ex.source) {
                out.push(lattice_cells::ExcerptHighlight {
                    composed_start: composed_row,
                    composed_end: composed_row + line_count - 1,
                    source_start: ex.start_line,
                    highlighter: Arc::clone(handle) as Arc<dyn lattice_cells::ExcerptHighlighter>,
                    // OA.7b: the row's own grammar, so conceal can resolve
                    // per excerpt the way highlighting already does.
                    lang: Some(handle.lang().name()),
                });
            }
            composed_row += line_count;
        }
        out
    }

    fn excerpt_syntax_version(&self) -> u64 {
        self.inner
            .excerpt_syntax_gen
            .load(std::sync::atomic::Ordering::Relaxed)
    }

    fn dispatch_with_cancel(
        &self,
        invocation: CommandInvocation,
        cursor: Position,
        cancel: CancellationToken,
    ) -> Pending<Effect> {
        self.dispatch_composed(
            invocation,
            cursor,
            cancel,
            lattice_runtime::DispatchEnv::default(),
        )
    }

    /// IN.0: the multibuffer overrides this too, purely to forward
    /// `env.indent` to `>` / `<`.
    ///
    /// It still ignores `env.scope_resolver` -- it builds its own
    /// composed↔source resolver in `dispatch_composed` (N.1.5), which
    /// is why the env was ignored wholesale before. But `indent` is a
    /// plain resolved value with nothing multibuffer-specific about it,
    /// and dropping it would mean `>` obeys `:setlocal shiftwidth=2` in
    /// a document buffer and silently ignores it in a multibuffer --
    /// kind-specific behaviour in a buffer, which is the thing
    /// `multibuffer_is_a_regular_buffer.rs` exists to prevent.
    fn dispatch_with_env(
        &self,
        invocation: CommandInvocation,
        cursor: Position,
        cancel: CancellationToken,
        env: lattice_runtime::DispatchEnv,
    ) -> Pending<Effect> {
        // VM.3c: `last_find` is forwarded, unlike the composed-coordinate
        // fields below. It needs no source mapping — `;` searches the line in
        // front of the user, and in a composed view that line IS the composed
        // one — so defaulting it to `None` would make `;` dead here for no
        // reason other than the field being new.
        // VM.3i: so is the fold resolver. The host's folds for a composed
        // view are composed-view lines, which are the lines `zj` walks here.
        // VM.3d-2: and so is the last search, for `n` / `N`: in a composed view
        // the text `n` searches is the composed text.
        self.dispatch_composed(invocation, cursor, cancel, env)
    }
}

impl MultibufferDocumentHandle {
    /// The batch-apply body, synchronous.
    ///
    /// M.11 (2026-06-02): local mutation per edit, sync source-forward
    /// enqueue, return synchronously. No `Pending::spawn`, no
    /// cross-actor round-trip.
    ///
    /// Factored out of [`Document::apply_edit_batch`] so grammar
    /// dispatch can reach it too — a `Pending` is the wrong shape for a
    /// caller that is already inside the synchronous dispatch path and
    /// would otherwise have to block on a future it knows is ready.
    fn apply_edit_batch_sync(&self, edits: Vec<Edit>) -> Result<Vec<AppliedEdit>, RuntimeError> {
        let mut applied_results = Vec::with_capacity(edits.len());
        let mut forwards = Vec::with_capacity(edits.len());

        for edit in edits {
            // Pre-resolve source forward target before mutating
            // (the row translation uses composed coords valid
            // before this edit lands).
            let state = self.lock_state();
            let source_forward = resolve_edit_target(&state, edit.range.start).map(|target| {
                let source_edit = build_source_edit(&target, &edit);
                SourceForwardMsg::Edit {
                    source_handle: target.source_handle.clone(),
                    source_edit,
                    announce: self.announce_for(target.source_id),
                }
            });
            drop(state);

            let mut doc = self
                .inner
                .composed_doc
                .lock()
                .expect("composed_doc mutex poisoned");
            match doc.apply_edit(edit) {
                Ok(applied) => {
                    let selections = self.lock_state().selections.clone();
                    let snap = snapshot_from_composed_doc(&doc, self.inner.id, selections);
                    self.inner.snapshot_cell.store(snap);
                    applied_results.push(applied);
                    if let Some(msg) = source_forward {
                        forwards.push(msg);
                    }
                }
                Err(e) => return Err(RuntimeError::Core(e)),
            }
        }

        for msg in forwards {
            let _ = self.inner.source_forward_tx.send(msg);
        }

        Ok(applied_results)
    }

    /// K.4.11-fix: land the edits a grammar operator produced.
    ///
    /// `dispatch_composed` runs the grammar against a **scratch**
    /// `Document` cloned from the composed snapshot — cheap, because
    /// `Buffer::clone` is an `Arc`-backed rope clone, and necessary,
    /// because `execute_with_env` wants `&mut Document` while the real
    /// composed doc lives behind a mutex the dispatch also reads through.
    /// The scratch is then dropped.
    ///
    /// That is fine for a motion, which only reports a cursor, and wrong
    /// for an operator, which reports edits it has already made — to the
    /// throwaway. The host's `Effect::Edits` arm (`handle_edits`) records
    /// the cursor and publishes the deltas on the premise, true for a
    /// real `Document` actor and false here, that the document has
    /// already applied them. Nothing wrote back, so `x` / `dd` / `cw`
    /// were inert in every multibuffer view — search results, references,
    /// project diff — while insert-mode typing worked, because typing
    /// goes through `apply_edit` rather than through dispatch.
    ///
    /// So: replay the scratch's edits onto the real composed doc through
    /// [`Self::apply_edit_batch_sync`], which is the M.3 path that also
    /// forwards to the source documents, and return the `AppliedEdit`s
    /// that landed rather than the scratch's. Replaying is sound because
    /// the batch applies in the same order the grammar did, so each
    /// edit's `original_range` describes the same text in both runs.
    fn land_composed_edits(&self, effect: Effect) -> Result<Effect, RuntimeError> {
        match effect {
            Effect::Edits(scratch_edits) => {
                if scratch_edits.is_empty() {
                    return Ok(Effect::Edits(scratch_edits));
                }
                let edits: Vec<Edit> = scratch_edits
                    .iter()
                    .map(|a| Edit::replace(a.original_range, a.inserted_text.clone()))
                    .collect();
                Ok(Effect::Edits(self.apply_edit_batch_sync(edits)?))
            }
            // `Many` is how an operator reports edits alongside its yank
            // and cursor move, so the edits are almost always nested one
            // level down rather than at the top.
            Effect::Many(effects) => Ok(Effect::Many(
                effects
                    .into_iter()
                    .map(|e| self.land_composed_edits(e))
                    .collect::<Result<Vec<_>, _>>()?,
            )),
            other => Ok(other),
        }
    }

    /// Body shared by [`Document::dispatch_with_cancel`] and
    /// [`Document::dispatch_with_env`].
    fn dispatch_composed(
        &self,
        invocation: CommandInvocation,
        cursor: Position,
        cancel: CancellationToken,
        env: lattice_runtime::DispatchEnv,
    ) -> Pending<Effect> {
        // Only the fields that need no composed↔source mapping are read here;
        // the coordinate-bearing ones (`scope_resolver`, …) are rebuilt below.
        let lattice_runtime::DispatchEnv {
            indent,
            last_find,
            fold_resolver,
            last_search,
            marks,
            viewport,
            nostartofline,
            scrolloff,
            curswant,
            display,
            curswant_out,
            ..
        } = env;
        // K.4.11 (2026-06-02): the multibuffer now owns grammar
        // dispatch directly. Pre-K.4.11 this returned
        // Err(ReadOnly), and `Editor::dispatch_blocking`
        // carried a kind-branch that ran `lattice_grammar::execute`
        // against a scratch `lattice_core::Document` built from
        // the composed snapshot. That was a paramount-#3 violation
        // (kind-special-casing in the host); the registry now
        // lives on `MultibufferInner` (passed at construction
        // per spawn_document's shape) so the multibuffer can do
        // the same work itself and the host's kind-branch
        // disappears.
        //
        // Resulting Effect flows through the usual host pipeline:
        // motions return a cursor Effect; operators return
        // Effect::Edits in composed coordinates.
        //
        // This comment used to claim those edits reached the sources
        // because "the host's apply_edit_blocking routes through this
        // handle's `apply_edit`". It did not — the host's Effect::Edits
        // arm only records the cursor and publishes deltas, on the
        // premise that the document already applied them. Nothing
        // applied them here, so every operator was a silent no-op. The
        // route the comment described now exists for real, in
        // `land_composed_edits` below; see its doc.
        // K.4.11.perf-fix (2026-06-02): Pre-fix this routed
        // `snapshot.buffer.as_string() → Document::from_text(&composed)`,
        // which allocated O(composed_size) bytes + rebuilt a fresh
        // Rope on EVERY keystroke on the App thread. For a search
        // multibuffer growing to 100s of KB during the scan, that
        // was tens of ms per `j`/`k` motion — the user-visible
        // "cursor moves after a lot of delay" + "lattice freezes
        // during scan" regressions. Architectural relocation per
        // [[feedback_no_ui_thread_work]]: reuse the snapshot's
        // existing Rope-backed Buffer directly. `Buffer::clone`
        // is `Rope::clone` which is Arc-backed + O(1); the new
        // path is one Arc bump per keystroke.
        let snapshot = self.snapshot();
        let mut scratch = lattice_core::Document::from_buffer(snapshot.buffer.clone());
        let buffer_id = self.inner.buffer_id;
        // B3b: owned snapshot for this dispatch (was `Arc::clone`); a
        // runtime plugin registration is live on the next keystroke.
        let registry = self.inner.registry.load_full();
        // N.1.5: tree-sitter text objects (`af` / `daf` / `znaf`) inside a
        // multibuffer view resolve against the SOURCE syntax, not the
        // composed text (which has no parse tree of its own). Build a
        // composed↔source `ScopeResolver` from the per-excerpt source
        // SyntaxSnapshots (K.4.7) and hand it to the dispatcher. Only
        // built for Operator / TextObject invocations -- motions
        // (j/k/w/...) never read it, so navigation in a big search view
        // stays O(1) per keystroke (paramount #1).
        let composed_resolver = if matches!(
            registry.lookup(invocation.command).map(|s| s.kind),
            Some(CommandKind::Operator | CommandKind::TextObject)
        ) {
            ComposedScopeResolver::build(&self.lock_state())
        } else {
            None
        };
        let result = execute_with_env(
            &registry,
            &mut scratch,
            buffer_id,
            cursor,
            invocation,
            &cancel,
            lattice_grammar::GrammarEnv {
                scope_resolver: composed_resolver
                    .as_ref()
                    .map(|r| r as &dyn lattice_grammar::ScopeResolver),
                // Comment objects inside multibuffer views would resolve
                // the per-excerpt source's comment leader -- deferred (a
                // follow-up, like N.1.5's scope resolver was). v1: None.
                comment_syntax: None,
                // A composed view has no tree of its own, and there is no ONE
                // source snapshot to hand over — an excerpt list spans several
                // files. `ComposedScopeResolver` above exists precisely because
                // the composed↔source mapping has to be applied per excerpt,
                // and a raw handle carries no mapping. So `None` here is the
                // honest answer rather than a gap: a plugin text object inside
                // a multibuffer view resolves from text, as it did before OT.1.
                // The composed peer of this handle is the same shape N.1.5
                // built for the resolver, and is deferred with it.
                syntax: None,
                indent,
                // IN.7: `=` inside a multibuffer view would need a
                // composed->source indent resolver, the same shape
                // N.1.5 built for text objects. Deferred; `=` is a
                // no-op there rather than wrong.
                indent_resolver: None,
                // RF.2: `gq` in a composed view reflows the COMPOSED text,
                // which is the right thing -- unlike `=` above it needs no
                // source mapping, because filling is a property of the lines
                // in front of the user. The width is the registered default
                // rather than the source buffer's `:setlocal textwidth`;
                // resolving that per excerpt is the same deferred mapping,
                // and a wrong-by-a-column reflow beats no reflow.
                textwidth: lattice_core::WrapWidth::default(),
                // RF.5b: a composed view formats natively or not at all —
                // delegating would send an LSP a range in COMPOSED
                // coordinates, which is the wrong-not-merely-absent
                // failure the `indent_resolver` deferral above avoids.
                native_format: Default::default(),
                // OS.2: a composed view's region would need the same
                // composed->source mapping the resolver above is deferred for
                // -- a selection in composed coordinates handed to an action
                // that edits SOURCE lines would be wrong, not merely absent.
                // `None` is the honest answer, and matches the `syntax` and
                // `indent_resolver` deferrals either side of it.
                selection: None,
                // VM.3c: forwarded, not deferred — see `dispatch_with_env`.
                last_find,
                // VM.3i: forwarded, not deferred — see `dispatch_with_env`.
                fold_resolver: fold_resolver.as_deref().map(|r| r as _),
                // VM.3d-2: forwarded, like `last_find`: `n` searches the text in
                // front of the user, which in a composed view is the composed text.
                last_search: last_search.as_ref(),
                marks: marks.as_deref().map(|m| m as _),
                viewport: viewport.as_deref().map(|v| v as _),
                nostartofline,
                // VM.3f: forwarded, like `nostartofline` — `H` / `L` in a
                // composed view keep the same margin they do anywhere else.
                scrolloff,
                curswant,
                display: display.as_deref().map(|d| d as _),
                // VM.3g-3: forwarded, like `curswant` and `display` above —
                // `gj` in a composed view aims and clamps against the COMPOSED
                // rows, so its goal is the composed one, and dropping the slot
                // here would make the goal stick in multibuffers only.
                curswant_out: curswant_out.as_deref(),
            },
        )
        .map_err(RuntimeError::Grammar);
        // K.4.11-fix: the grammar edited the scratch. Land those edits on
        // the real composed doc (and forward them to the sources), or the
        // operator is a no-op the host cannot tell from a successful one.
        Pending::ready(result.and_then(|effect| self.land_composed_edits(effect)))
    }
}

// ──────────────────────────────────────────────────────────────
// N.1.5 — composed↔source scope resolver
// ──────────────────────────────────────────────────────────────

/// N.1.5: a [`lattice_grammar::ScopeResolver`] that bridges composed
/// multibuffer coordinates to the per-excerpt SOURCE syntax. Tree-sitter
/// text objects dispatched against a multibuffer view (narrow / search /
/// project-diff) resolve their enclosing scope against the source file's
/// parse tree — the composed text has no tree of its own — and the
/// result is mapped back to composed coordinates so the operator applies
/// in the view. Built per Operator/TextObject dispatch from a snapshot
/// of the excerpt layout + source `SyntaxSnapshot`s (cheap Arc clones);
/// see [`MultibufferDocumentHandle::dispatch_with_cancel`].
struct ComposedScopeResolver {
    excerpts: Vec<ComposedExcerptSpan>,
    snapshots: HashMap<BufferId, Arc<SyntaxSnapshot>>,
}

/// One excerpt's placement: its source rows `[start_line, start_line +
/// line_count)` occupy composed rows `[composed_offset, composed_offset
/// + line_count)`.
struct ComposedExcerptSpan {
    source: BufferId,
    start_line: u32,
    line_count: u32,
    composed_offset: u32,
}

impl ComposedScopeResolver {
    /// Snapshot the excerpt layout + per-source `SyntaxSnapshot`s.
    /// Returns `None` when no excerpt has a source `SyntaxHandle` (a
    /// plain-text / no-language multibuffer) — the resolver would
    /// resolve nothing, so the caller passes `None` and text objects
    /// degrade to empty (graceful operator no-op).
    fn build(state: &MultibufferState) -> Option<Self> {
        let mut excerpts = Vec::with_capacity(state.excerpts.len());
        let mut snapshots: HashMap<BufferId, Arc<SyntaxSnapshot>> = HashMap::new();
        let mut composed_offset = 0u32;
        for ex in &state.excerpts {
            excerpts.push(ComposedExcerptSpan {
                source: ex.source,
                start_line: ex.start_line,
                line_count: ex.line_count(),
                composed_offset,
            });
            composed_offset = composed_offset.saturating_add(ex.line_count());
            if !snapshots.contains_key(&ex.source)
                && let Some(h) = state.source_syntax.get(&ex.source)
            {
                snapshots.insert(ex.source, h.snapshot());
            }
        }
        if snapshots.is_empty() {
            return None;
        }
        Some(Self {
            excerpts,
            snapshots,
        })
    }
}

impl lattice_grammar::ScopeResolver for ComposedScopeResolver {
    fn scope_at(
        &self,
        composed_line: u32,
        col_byte: u32,
        suffix: &str,
    ) -> Option<lattice_protocol::position::Range> {
        for ex in &self.excerpts {
            // First composed row PAST this excerpt (exclusive upper bound).
            let composed_end_exclusive = ex.composed_offset.saturating_add(ex.line_count);
            if composed_line < composed_end_exclusive {
                let source_line = ex.start_line + (composed_line - ex.composed_offset);
                let snap = self.snapshots.get(&ex.source)?;
                let src = snap.scope_at_cursor(source_line, col_byte, suffix)?;
                // Clamp the source range to THIS excerpt's source bounds,
                // then map back to composed rows. A scope extending past
                // the excerpt (a narrowed sub-region) is clipped to the
                // visible rows; a clamped edge loses its byte column
                // (falls to col 0) since it no longer marks a real token.
                // `saturating_sub` guards a (shouldn't-happen) zero-line
                // excerpt rather than underflowing to u32::MAX.
                let ex_last = ex
                    .start_line
                    .saturating_add(ex.line_count)
                    .saturating_sub(1);
                let cs = src.start.line.max(ex.start_line);
                let ce = src.end.line.min(ex_last);
                if cs > ce {
                    return None;
                }
                let start_byte = if src.start.line >= ex.start_line {
                    src.start.byte
                } else {
                    0
                };
                let end_byte = if src.end.line <= ex_last {
                    src.end.byte
                } else {
                    0
                };
                return Some(lattice_protocol::position::Range::new(
                    lattice_protocol::position::Position::new(
                        ex.composed_offset + (cs - ex.start_line),
                        start_byte,
                    ),
                    lattice_protocol::position::Position::new(
                        ex.composed_offset + (ce - ex.start_line),
                        end_byte,
                    ),
                ));
            }
        }
        None
    }

    // TSM.1: stub -- the real composed↔source tree walk for structural
    // motions (`]f`/`[c`/…) lands in a later slice, mirroring how
    // `scope_at` maps source scopes back to composed coordinates.
    // Graceful no-op until then (heuristic #5).
    fn scope_toward(
        &self,
        _composed_line: u32,
        _col_byte: u32,
        _suffix: &str,
        _dir: lattice_grammar::NavDir,
        _boundary: lattice_grammar::NavBoundary,
        _count: u32,
    ) -> Option<lattice_protocol::Position> {
        None
    }
}

// ──────────────────────────────────────────────────────────────
// M.3 translation helpers
// ──────────────────────────────────────────────────────────────

/// One excerpt + position pair resolved from a composed-coordinate
/// edit point. M.4 will likely read `source_id` for live-update
/// subscription bookkeeping; M.3 only needs the handle.
#[allow(dead_code)]
struct EditTarget {
    source_id: BufferId,
    source_handle: Arc<dyn Document>,
    /// The composed `Position` we translated from.
    composed_start: Position,
    /// Source-coordinate position equivalent to `composed_start`.
    source_start: Position,
    /// Last composed row of the containing excerpt (inclusive).
    excerpt_end_composed_row: u32,
    /// Last source row of the containing excerpt (inclusive).
    excerpt_end_source_row: u32,
}

/// Walk excerpts in display order to find the one that contains
/// `composed_pos`. Returns the source handle + the source
/// position equivalent. `None` when the position is past the
/// last excerpt or the source map doesn't have the excerpt's
/// source (an invariant violation, treated as out-of-range).
fn resolve_edit_target(state: &MultibufferState, composed_pos: Position) -> Option<EditTarget> {
    let mut composed_cursor: u32 = 0;
    for excerpt in &state.excerpts {
        let lines = excerpt.line_count();
        let next_cursor = composed_cursor.saturating_add(lines);
        if composed_pos.line < next_cursor {
            let offset_in_excerpt = composed_pos.line - composed_cursor;
            let source_row = excerpt.start_line.saturating_add(offset_in_excerpt);
            let source_handle = state.sources.get(&excerpt.source)?.clone();
            return Some(EditTarget {
                source_id: excerpt.source,
                source_handle,
                composed_start: composed_pos,
                source_start: Position {
                    line: source_row,
                    byte: composed_pos.byte,
                },
                excerpt_end_composed_row: next_cursor.saturating_sub(1),
                excerpt_end_source_row: excerpt.end_line,
            });
        }
        composed_cursor = next_cursor;
    }
    None
}

/// Build the source-coordinate `Edit` from a translation target +
/// the original composed-coordinate edit. Applies boundary
/// clipping: if `edit.range.end` extends past the start
/// excerpt's last row, the end is clipped to the end-of-line
/// of the excerpt's last source row.
fn build_source_edit(target: &EditTarget, edit: &Edit) -> Edit {
    let end_composed = edit.range.end;
    let source_end = if end_composed.line > target.excerpt_end_composed_row {
        // Boundary clip: pull `end` back to end-of-line of the
        // excerpt's last source row. Length comes from the
        // source's current snapshot — we already hold the
        // handle.
        let snap = target.source_handle.snapshot();
        let line_text = snap.buffer.line(target.excerpt_end_source_row);
        let line_byte_len = line_text
            .as_deref()
            .map(|s| s.trim_end_matches('\n').len() as u32)
            .unwrap_or(0);
        Position {
            line: target.excerpt_end_source_row,
            byte: line_byte_len,
        }
    } else {
        let row_offset = end_composed.line.saturating_sub(target.composed_start.line);
        Position {
            line: target.source_start.line.saturating_add(row_offset),
            byte: end_composed.byte,
        }
    };

    Edit {
        range: lattice_protocol::position::Range {
            start: target.source_start,
            end: source_end,
        },
        kind: edit.kind.clone(),
    }
}

// M.11 (2026-06-02): `translate_applied_to_composed` deleted —
// edits now apply to the local composed_doc, so AppliedEdit
// is already in composed coords. No translation needed.

impl std::fmt::Debug for MultibufferDocumentHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let state = self.lock_state();
        f.debug_struct("MultibufferDocumentHandle")
            .field("id", &self.inner.id)
            .field("buffer_id", &self.inner.buffer_id)
            .field("sources", &state.sources.len())
            .field("excerpts", &state.excerpts.len())
            .finish()
    }
}

#[derive(Debug, thiserror::Error)]
pub enum MultibufferError {
    /// An excerpt referenced a `source` BufferId not present in
    /// the sources map. M.2.b.2 (2026-06-01) relaxed
    /// `EmptyExcerpts` (the async-provider pattern needs empty
    /// views).
    #[error("excerpt {excerpt:?} references unknown source buffer {source_buffer:?}")]
    UnknownSource {
        excerpt: ExcerptId,
        source_buffer: BufferId,
    },
}

// ─────────────────────────────────────────────────────────────────
// Header provider (VirtualRowProvider impl) — moved from
// `lattice-host::multibuffer` in M.2.b.1.
// ─────────────────────────────────────────────────────────────────

/// Namespace prefix for multibuffer header provider ids.
/// Distinct from the diff filler / overlay namespaces (`0xD1FF_*`).
const MULTIBUFFER_EXCERPT_HEADER_NAMESPACE: u64 = 0xBBBB_0001_0000_0000;

pub fn multibuffer_excerpt_header_provider_id(buffer_id: BufferId) -> ProviderId {
    MULTIBUFFER_EXCERPT_HEADER_NAMESPACE | u64::from(buffer_id.0)
}

// ─────────────────────────────────────────────────────────────────
// T.7 (2026-06-18): mode-owned theme elements for the excerpt header.
//
// The multibuffer MODE owns these elements + their defaults — they
// are NOT core builtins ([[feedback_mode_owns_its_surface]]). The
// mode registers them (idempotent by name) so the excerpt-header
// provider can resolve them into BAKED `u32` colors at row-build
// time (off the UI thread, the established cell/virtual-row pattern).
//
// This is the extensibility acid test: a provider crate adds ZERO
// host `Theme`/style fields and ZERO renderer match arms — it
// registers elements + references them, and the renderer paints
// `VirtualRow.bg` / `Cell.fg` generically.
// ─────────────────────────────────────────────────────────────────

/// Element name: the excerpt-header row's backdrop (a neutral
/// surface tint, distinct from the diff-deletion-block red the
/// renderer would otherwise fall a `bg: None` Generic row through to).
pub const ELEM_EXCERPT_HEADER: &str = "multibuffer.excerpt_header";
/// Element name: the excerpt-header file-path / title foreground.
pub const ELEM_EXCERPT_HEADER_PATH: &str = "multibuffer.excerpt_header.path";
/// Element name: the excerpt-header match-count foreground.
pub const ELEM_EXCERPT_HEADER_COUNT: &str = "multibuffer.excerpt_header.count";

// MH.A6: the emphasised header's own backdrop + title foreground.
//
// Two elements rather than a "make the normal one brighter" rule,
// because brightness is not portable: a light colourscheme emphasises
// by going DARKER, and a theme that expressed prominence as
// `header_fg + 0x202020` would invert on half the themes people use.
// Naming the elements hands that decision to the colourscheme, which
// is the only layer that knows which direction is louder.
/// Element name: the emphasised excerpt-header row's backdrop.
pub const ELEM_EXCERPT_HEADER_EMPHASIS: &str = "multibuffer.excerpt_header.emphasis";
/// Element name: the emphasised excerpt-header's title foreground.
pub const ELEM_EXCERPT_HEADER_EMPHASIS_TITLE: &str = "multibuffer.excerpt_header.emphasis.title";

// MH.A4 (2026-06-20): view-status headerline foreground elements.
// The status row (` ⟳ Searching … ` / ` ◆ N hits ` / ` ■ reason `)
// previously hardcoded its fg as ad-hoc hex (0x999999 / 0x44cc88 /
// 0xff4444); these map the three states onto palette role-keys so a
// `:colorscheme` swap recolors the status line.
/// Element name: the in-progress status row foreground (neutral grey).
pub const ELEM_STATUS_IN_PROGRESS: &str = "multibuffer.status.in_progress";
/// Element name: the completed status row foreground (green).
pub const ELEM_STATUS_COMPLETE: &str = "multibuffer.status.complete";
/// Element name: the failed status row foreground (red).
pub const ELEM_STATUS_FAILED: &str = "multibuffer.status.failed";
/// Element name: the emphasised-term foreground (accent) — e.g. the
/// project-search query woven into the status label.
pub const ELEM_STATUS_QUERY: &str = "multibuffer.status.query";

/// Register the multibuffer mode's theme elements against `reg`.
/// Idempotent by name (safe to call on every mode activation /
/// every view creation). Returns the interned [`ElementId`]s the
/// excerpt-header provider bakes from.
///
/// `owner` is the mode's id string ([`MultibufferMode::mode_id`] →
/// `as_str`), so `:describe-element` attributes these to the mode
/// rather than core. `lattice-theme` is a leaf crate that can't
/// depend on `lattice-mode`, hence the string owner.
pub fn register_multibuffer_theme_elements(
    reg: &dyn lattice_theme::ThemeRegistry,
    owner: ElementOwner,
) -> MultibufferHeaderElementIds {
    let backdrop = reg.register(
        ElementName::from(ELEM_EXCERPT_HEADER.to_string()),
        owner.clone(),
        // Neutral surface backdrop (Catppuccin "surface0"-ish), NOT
        // the diff-deletion red — that was the smell this slice fixes.
        StyleSpec::new().bg(Color::Rgb(0x31, 0x32, 0x44)),
        "Multibuffer excerpt header backdrop.",
    );
    let path = reg.register(
        ElementName::from(ELEM_EXCERPT_HEADER_PATH.to_string()),
        owner.clone(),
        StyleSpec::new().fg(ColorRef::Palette("blue".into())),
        "Excerpt header file path.",
    );
    let count = reg.register(
        ElementName::from(ELEM_EXCERPT_HEADER_COUNT.to_string()),
        owner.clone(),
        StyleSpec::new().fg(ColorRef::Palette("overlay2".into())),
        "Excerpt header match count.",
    );
    // MH.A6: the emphasised header — `surface2` behind, `text` in
    // front, against the ordinary header's `surface0` + palette-blue.
    //
    // `surface2` rather than an accent hue (`purple`, `blue`) because
    // it is the SAME LADDER the normal backdrop sits on, two rungs up:
    // every shipped palette defines `surface0/1/2` as a lift, so the
    // emphasis reads as "this band is raised" in a light colourscheme
    // exactly as it does in a dark one. An accent backdrop would have
    // to be re-chosen per theme to avoid clashing with whatever that
    // theme already spends its purple on.
    //
    // Both are palette role-keys rather than literal RGB (unlike the
    // ordinary backdrop above, which predates the palette), so a
    // `:colorscheme` swap carries the emphasis with it.
    let emphasis = reg.register(
        ElementName::from(ELEM_EXCERPT_HEADER_EMPHASIS.to_string()),
        owner.clone(),
        StyleSpec::new().bg(ColorRef::Palette("surface2".into())),
        "Multibuffer emphasised excerpt header backdrop (e.g. the agenda's today block).",
    );
    let emphasis_title = reg.register(
        ElementName::from(ELEM_EXCERPT_HEADER_EMPHASIS_TITLE.to_string()),
        owner.clone(),
        StyleSpec::new().fg(ColorRef::Palette("text".into())),
        "Multibuffer emphasised excerpt header title foreground.",
    );
    // MH.A4: status-row state colors. `in_progress` maps to the
    // muted `subtext` grey (the old 0x999999), `complete` to `green`
    // (old 0x44cc88), `failed` to `red` (old 0xff4444) — the nearest
    // semantic role-keys in the registered palette.
    let status_in_progress = reg.register(
        ElementName::from(ELEM_STATUS_IN_PROGRESS.to_string()),
        owner.clone(),
        StyleSpec::new().fg(ColorRef::Palette("subtext".into())),
        "Multibuffer in-progress status foreground.",
    );
    let status_complete = reg.register(
        ElementName::from(ELEM_STATUS_COMPLETE.to_string()),
        owner.clone(),
        StyleSpec::new().fg(ColorRef::Palette("green".into())),
        "Multibuffer completed status foreground.",
    );
    let status_failed = reg.register(
        ElementName::from(ELEM_STATUS_FAILED.to_string()),
        owner.clone(),
        StyleSpec::new().fg(ColorRef::Palette("red".into())),
        "Multibuffer failed status foreground.",
    );
    // The emphasised-term accent (e.g. the search query) maps to the
    // palette `yellow` — the conventional search-highlight hue,
    // distinct from the green/red/blue state colors above.
    let status_query = reg.register(
        ElementName::from(ELEM_STATUS_QUERY.to_string()),
        owner,
        StyleSpec::new().fg(ColorRef::Palette("yellow".into())),
        "Multibuffer emphasised-term (query) status foreground.",
    );
    MultibufferHeaderElementIds {
        backdrop,
        path,
        count,
        emphasis,
        emphasis_title,
        status_in_progress,
        status_complete,
        status_failed,
        status_query,
    }
}

/// The interned [`ElementId`]s for the excerpt-header elements,
/// captured once at view-creation and held by the provider so each
/// `collect()` is an array-index resolve (`resolved.get(id)`), never
/// a per-row name lookup. `Copy`; cheap to thread through.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MultibufferHeaderElementIds {
    pub backdrop: ElementId,
    pub path: ElementId,
    pub count: ElementId,
    /// MH.A6: the emphasised header's backdrop + title, interned with
    /// the rest so an emphasised row costs the same array-index
    /// resolve as an ordinary one.
    pub emphasis: ElementId,
    pub emphasis_title: ElementId,
    /// MH.A4: view-status row foregrounds, interned alongside the
    /// header elements so the status provider's `collect()` resolves
    /// by array index (never a per-row name lookup).
    pub status_in_progress: ElementId,
    pub status_complete: ElementId,
    pub status_failed: ElementId,
    /// The accent foreground for an emphasised term (e.g. the search
    /// query) woven into the status label.
    pub status_query: ElementId,
}

impl Default for MultibufferHeaderElementIds {
    /// All-INVALID placeholder for test paths that build the provider
    /// without a theme registry. Reads against an empty/default table
    /// return `Style::empty()` (no bg/fg baked) — never a panic.
    fn default() -> Self {
        Self {
            backdrop: ElementId::INVALID,
            path: ElementId::INVALID,
            count: ElementId::INVALID,
            emphasis: ElementId::INVALID,
            emphasis_title: ElementId::INVALID,
            status_in_progress: ElementId::INVALID,
            status_complete: ElementId::INVALID,
            status_failed: ElementId::INVALID,
            status_query: ElementId::INVALID,
        }
    }
}

/// Emits one virtual row per excerpt header, anchored above the
/// excerpt's first composed row. Cheap-clone reference to the
/// multibuffer handle; re-reads excerpts on each `collect()`.
///
/// T.7: when a [`ThemeRegistryHandle`] + the header element ids are
/// supplied, `collect()` resolves the backdrop + path elements and
/// bakes them into the row's `bg` / cells' `fg` — resolution happens
/// off-thread at row-build time, never on a paint path. Without a
/// handle (test paths) the rows fall back to `bg: None` (the renderer
/// then picks its kind default).
///
/// `Debug` is hand-rolled because `ThemeRegistryHandle` (a
/// `dyn ThemeRegistry` trait object) is not `Debug`; the
/// `VirtualRowProvider` trait requires `Debug`.
pub struct MultibufferExcerptHeaderProvider {
    multibuffer: MultibufferDocumentHandle,
    /// T.7: `None` for test paths that don't wire a theme registry.
    theme: Option<ThemeRegistryHandle>,
    elements: MultibufferHeaderElementIds,
    /// MH.A3: `ui.nerd_fonts`, captured at view construction so the
    /// leading file-type icon picks the nerd-font glyph vs the BMP
    /// fallback. Folded into `version()` so a global toggle re-runs
    /// `collect()`.
    ///
    /// MH.A3 follow-on: this is the GLOBAL default captured once at
    /// view creation — a live per-buffer `ui.nerd_fonts` toggle does
    /// not yet re-render the header. Reading per-buffer
    /// `ui.nerd_fonts` here needs the `FrameView::for_buffer` seam
    /// plumbed into the provider, deferred to avoid over-building.
    nerd_fonts: bool,
    /// OA.2: how consecutive excerpts share a header row. The same
    /// declaration that decides folding, because the two MUST agree — a fold
    /// spanning a different range than a header run would swallow a visible
    /// header, or leave one stranded above a closed fold.
    grouping: FoldGrouping,
}

impl std::fmt::Debug for MultibufferExcerptHeaderProvider {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("MultibufferExcerptHeaderProvider")
            .field("buffer_id", &self.multibuffer.buffer_id())
            .field("has_theme", &self.theme.is_some())
            .field("elements", &self.elements)
            .field("nerd_fonts", &self.nerd_fonts)
            .finish()
    }
}

impl MultibufferExcerptHeaderProvider {
    /// Construct without theme wiring — headers render with no baked
    /// bg/fg (the renderer's kind default applies). Test convenience;
    /// production uses [`Self::with_theme`]. Defaults `nerd_fonts` to
    /// `false` (BMP-fallback palette).
    pub fn new(multibuffer: MultibufferDocumentHandle) -> Self {
        Self {
            multibuffer,
            theme: None,
            elements: MultibufferHeaderElementIds::default(),
            nerd_fonts: false,
            grouping: FoldGrouping::SourceFile,
        }
    }

    /// OA.2: group header rows the way this view folds. Defaults to
    /// `SourceFile`, which is what every provider but the agenda wants.
    pub fn with_grouping(mut self, grouping: FoldGrouping) -> Self {
        self.grouping = grouping;
        self
    }

    /// T.7: construct with the resolved theme handle + the header
    /// element ids so `collect()` bakes the registered backdrop / path
    /// colors into the header rows. MH.A3: `nerd_fonts` selects the
    /// icon palette (captured at view creation; see the struct field
    /// doc for the per-buffer-toggle follow-on note).
    pub fn with_theme(
        multibuffer: MultibufferDocumentHandle,
        theme: ThemeRegistryHandle,
        elements: MultibufferHeaderElementIds,
        nerd_fonts: bool,
    ) -> Self {
        Self {
            multibuffer,
            theme: Some(theme),
            elements,
            nerd_fonts,
            grouping: FoldGrouping::SourceFile,
        }
    }
}

impl VirtualRowProvider for MultibufferExcerptHeaderProvider {
    fn id(&self) -> ProviderId {
        multibuffer_excerpt_header_provider_id(self.multibuffer.buffer_id())
    }

    fn version(&self) -> u64 {
        // T.7: fold the resolved theme version into the provider
        // version so a `:colorscheme` / `:set ui.*` change re-runs
        // `collect()` and re-bakes the header colors. Mirrors how the
        // cell matrix invalidates via `MatrixVersion::theme =
        // resolved().version()` (dispatch.rs). The worker's
        // fingerprint is `hash[(id, version)]`, so a version bump on
        // any axis (excerpt content OR theme) triggers a rebuild.
        let content = self.multibuffer.snapshot().version;
        let theme = self
            .theme
            .as_ref()
            .map(|t| t.resolved().version())
            .unwrap_or(0);
        // MH.A3: fold the nerd_fonts term so a global toggle re-runs
        // `collect()` (the worker fingerprint is `hash[(id, version)]`).
        content
            .wrapping_add(theme)
            .wrapping_add(if self.nerd_fonts { 1 } else { 0 })
    }

    fn collect(&self) -> Vec<VirtualRow> {
        // Resolve the backdrop bg + all three segment fgs ONCE per
        // collect (off the UI thread), then bake into each header
        // row. `0` (the Cell "transparent / use default" sentinel) is
        // the fg fallback when an element is unresolved.
        //
        // header_fg = `multibuffer.excerpt_header` (the base/backdrop
        //   element)'s `.fg` — currently unset in the default
        //   registration (only `.bg`), so this resolves to 0 until a
        //   future slice adds a base fg; the renderer then uses its
        //   default fg. path_fg / count_fg come from the dedicated
        //   `.path` / `.count` elements.
        let resolved = self.theme.as_ref().map(|t| t.resolved());
        let header_bg: Option<u32> = resolved
            .as_ref()
            .and_then(|r| r.get(self.elements.backdrop).bg)
            .map(|c| c.to_rgb_u32(0));
        let header_fg: u32 = resolved
            .as_ref()
            .and_then(|r| r.get(self.elements.backdrop).fg)
            .map(|c| c.to_rgb_u32(0))
            .unwrap_or(0);
        let path_fg: u32 = resolved
            .as_ref()
            .and_then(|r| r.get(self.elements.path).fg)
            .map(|c| c.to_rgb_u32(0))
            .unwrap_or(0);
        let count_fg: u32 = resolved
            .as_ref()
            .and_then(|r| r.get(self.elements.count).fg)
            .map(|c| c.to_rgb_u32(0))
            .unwrap_or(0);
        // MH.A6: the emphasised pair, resolved in the same pass. Both
        // fall back to the ordinary header's colours rather than to
        // `0`, so a colourscheme that does not define these elements
        // renders an emphasised header exactly like a normal one —
        // undistinguished, never invisible.
        let emphasis_bg: Option<u32> = resolved
            .as_ref()
            .and_then(|r| r.get(self.elements.emphasis).bg)
            .map(|c| c.to_rgb_u32(0))
            .or(header_bg);
        let emphasis_fg: u32 = resolved
            .as_ref()
            .and_then(|r| r.get(self.elements.emphasis_title).fg)
            .map(|c| c.to_rgb_u32(0))
            .unwrap_or(header_fg);
        let nerd_fonts = self.nerd_fonts;
        // The style has to be read TWICE — once for the cells and once
        // for the row's `bg` — and `compose_header_rows` hands the
        // closure the excerpt while the `map` below sees only the
        // finished row. Carried in a parallel vec keyed by position
        // rather than threaded through `VirtualRow`: the row type is
        // shared with every other provider and does not want a field
        // that only headers mean anything by.
        let mut emphasised: Vec<bool> = Vec::new();
        let rows = compose_header_rows(&self.multibuffer.excerpts(), self.grouping, |excerpt| {
            let emph = excerpt.header.style == ExcerptHeaderStyle::Emphasis;
            emphasised.push(emph);
            let (fg, path_fg) = if emph {
                // The title takes the emphasis foreground, and so does
                // the trailing `(today)` parenthetical — OA.7 dims that
                // against the normal backdrop, and dimming it against
                // the emphasised one would undo the emphasis on the
                // half of the header that says WHY it is emphasised.
                (emphasis_fg, emphasis_fg)
            } else {
                (header_fg, path_fg)
            };
            header_cells(&excerpt.header, nerd_fonts, fg, path_fg, count_fg)
        });
        rows.into_iter()
            .enumerate()
            .map(|(i, mut row)| {
                row.bg = if emphasised.get(i).copied().unwrap_or(false) {
                    emphasis_bg
                } else {
                    header_bg
                };
                row
            })
            .collect()
    }
}

/// MH.A3: rich per-segment header builder. Replaces the old
/// single-fg `themed_header_cells`. Layout (per multibuffer-views.md
/// §3.8):
///
/// ```text
///   filename.rs  src/multibuffer/  ·  7 matches
/// ```
///
/// - leading file-type **icon** (resolved live from `header.path`'s
///   extension via [`lattice_core::ui::icons::glyph_for_entry`];
///   nerd glyph when `nerd_fonts`, BMP fallback otherwise — both the
///   same cell width) + a trailing space, fg `header_fg`.
/// - **basename** (`header.path.file_name()`, else `header.title`),
///   fg `header_fg`.
/// - a space + the **dir** path (dimmed) when `header.path` has a
///   parent, fg `path_fg`.
/// - ` · {n} matches` / ` · {n} match` when `header.match_count` is
///   `Some`, fg `count_fg`.
/// - empty title AND no path ⇒ `[untitled]` fallback in `header_fg`.
///
/// Colours are **resolved in `collect()` and passed in** — never
/// baked at excerpt-creation time — so a live `ui.nerd_fonts` /
/// `:colorscheme` toggle re-renders the whole surface. A fg of `0`
/// is the Cell "use renderer default" sentinel (test paths without a
/// theme).
pub(crate) fn header_cells(
    header: &ExcerptHeader,
    nerd_fonts: bool,
    header_fg: u32,
    path_fg: u32,
    count_fg: u32,
) -> Arc<[Cell]> {
    let mut cells: Vec<Cell> = Vec::new();

    let push = |cells: &mut Vec<Cell>, s: &str, fg: u32| {
        for ch in s.chars() {
            cells.push(Cell::new(ch as u32, fg, 0, 0));
        }
    };

    match &header.path {
        Some(path) => {
            // Leading file-type icon (already 2 cells wide: glyph +
            // trailing space in both palettes) — fg `header_fg`.
            let icon = lattice_core::ui::icons::glyph_for_entry(path, false, nerd_fonts);
            push(&mut cells, icon, header_fg);

            // Basename (bright). Fall back to the whole path string,
            // then to the title, if `file_name()` is unavailable.
            let basename: std::borrow::Cow<'_, str> = path
                .file_name()
                .map(|n| n.to_string_lossy())
                .unwrap_or_else(|| path.to_string_lossy());
            if basename.is_empty() {
                push(&mut cells, header.title.as_str(), header_fg);
            } else {
                push(&mut cells, basename.as_ref(), header_fg);
            }

            // Directory path (dimmed) when there's a parent.
            if let Some(parent) = path.parent() {
                let parent_str = parent.to_string_lossy();
                if !parent_str.is_empty() {
                    push(&mut cells, "  ", path_fg);
                    push(&mut cells, parent_str.as_ref(), path_fg);
                }
            }
        }
        None => {
            // No path → use the title; `[untitled]` when even that is
            // empty so the row never collapses to nothing.
            if header.title.is_empty() {
                push(&mut cells, "[untitled]", header_fg);
            } else {
                // OA.7: a trailing parenthetical is ANNOTATION, not identity,
                // and reads as such when it is dimmed. The agenda's labels are
                // `2026-09-01 Mon (today)`, `(overdue by 2 day(s))`,
                // `(in 3 day(s))` — the date names the block and the phrase
                // qualifies it, so rendering both at one weight makes the
                // header longer without making it say more.
                //
                // Generic rather than agenda-shaped: it keys on the SHAPE of
                // the title, and any provider whose header ends in a
                // parenthetical gets the same reading. A title with no
                // parenthetical is byte-identical to before.
                let (name, note) = split_trailing_parenthetical(header.title.as_str());
                push(&mut cells, name, header_fg);
                if !note.is_empty() {
                    push(&mut cells, note, path_fg);
                }
            }
        }
    }

    // Match-count badge (` · N matches`), fg `count_fg`.
    if let Some(n) = header.match_count {
        let badge = if n == 1 {
            format!(" · {n} match")
        } else {
            format!(" · {n} matches")
        };
        push(&mut cells, badge.as_str(), count_fg);
    }

    Arc::from(cells)
}

/// OA.7: split `title` into its name and a trailing ` (…)` annotation.
///
/// The note keeps its leading space so the two concatenate back to the input
/// exactly — the dimming is the only difference, and a caller that ignores the
/// second half still renders the whole title.
///
/// Only a parenthetical that CLOSES the string counts, and only when there is
/// a name in front of it. `(overdue by 2 day(s))` therefore splits at the
/// first `(` of the trailing run rather than at the nested one, and a title
/// that is nothing but a parenthetical stays whole rather than becoming an
/// empty name and a dim remainder.
fn split_trailing_parenthetical(title: &str) -> (&str, &str) {
    let trimmed = title.trim_end();
    if !trimmed.ends_with(')') {
        return (title, "");
    }
    // Walk back to the `(` that opens the trailing run, counting nesting so
    // `day(s)` inside it does not close it early.
    let bytes = trimmed.as_bytes();
    let mut depth = 0i32;
    let mut open = None;
    for (i, b) in bytes.iter().enumerate().rev() {
        match b {
            b')' => depth += 1,
            b'(' => {
                depth -= 1;
                if depth == 0 {
                    open = Some(i);
                    break;
                }
            }
            _ => {}
        }
    }
    let Some(open) = open else {
        return (title, "");
    };
    // Require a name before it, and a space between: `(today)` alone is the
    // whole title, not an annotation on nothing.
    if open == 0 || !title.is_char_boundary(open) {
        return (title, "");
    }
    let name = title[..open].trim_end();
    if name.is_empty() {
        return (title, "");
    }
    (name, &title[open - 1..])
}

/// Pure function from excerpt list → header virtual rows, under `grouping`.
///
/// [`FoldGrouping::SourceFile`] emits ONE row per distinct consecutive
/// source — when N consecutive excerpts share `excerpt.source`, only the first
/// contributes a header, anchored `Above` its first composed line.
///
/// K.4.6 follow-up (2026-06-02): pre-fix this emitted one row per excerpt
/// unconditionally, which broke "1 header per file" for providers like search
/// that emit multiple excerpts per file (one per hit cluster). The dedup
/// happens here in substrate, not in providers.
///
/// [`FoldGrouping::HeaderRuns`] groups by the header TITLE instead, with
/// exactly the rule [`HeaderGroupFoldProvider`] already folds by:
///
/// - a non-empty title differing from the current group's starts a group;
/// - a non-empty title equal to it continues it;
/// - an **empty** title continues it — that is what "I belong to the group
///   above" has always meant in this tree.
///
/// OA.2. The agenda needs this because it groups by DATE and its rows
/// interleave files by design, so a file boundary is not a group boundary
/// there. It gave the first row of a date group the label and the rest an
/// empty title, on the documented assumption that an empty title renders no
/// header — but source-run dedup emitted one at every file change, and
/// `header_cells` renders a titleless, pathless header as `[untitled]`. One
/// date group drawn from two files rendered
/// `["2026-08-31 Mon (today)", "[untitled]", "[untitled]"]`.
///
/// Not the default, and that is not timidity: `lattice-lsp`'s references view
/// titles each excerpt with its LINE NUMBER, so consecutive excerpts from one
/// file carry different titles and title-runs would give it a header per
/// reference instead of per file.
pub fn compose_header_rows(
    excerpts: &[Excerpt],
    grouping: FoldGrouping,
    mut render_cells: impl FnMut(&Excerpt) -> Arc<[Cell]>,
) -> Vec<VirtualRow> {
    let mut rows = Vec::with_capacity(excerpts.len());
    let mut composed_cursor: u32 = 0;
    let mut last_source: Option<BufferId> = None;
    let mut group_title: Option<String> = None;
    for excerpt in excerpts {
        let starts_group = match grouping {
            FoldGrouping::SourceFile => last_source != Some(excerpt.source),
            FoldGrouping::HeaderRuns => {
                let title = excerpt.header.title.as_str();
                // An empty title continues whatever is open. With nothing
                // open it starts nothing either — emitting here is what
                // produced `[untitled]`, and a header with no text is not a
                // header.
                !title.is_empty() && group_title.as_deref() != Some(title)
            }
        };
        if starts_group {
            group_title = Some(excerpt.header.title.clone());
            let cells = render_cells(excerpt);
            rows.push(VirtualRow {
                media: None,
                anchor_line: composed_cursor,
                position: AnchorPosition::Above,
                cells,
                height: 1,
                kind: VirtualRowKind::Generic,
                bg: None,
                scales: None,
                gutter_line: None,
                gutter_fg: None,
            });
        }
        last_source = Some(excerpt.source);
        composed_cursor = composed_cursor.saturating_add(excerpt.line_count());
    }
    rows
}

// ─────────────────────────────────────────────────────────────────
// M.6.5 (2026-06-08): view-status sticky headerline
// ─────────────────────────────────────────────────────────────────

/// Namespace prefix for the view-status headerline provider.
/// Distinct from the excerpt-header namespace (`0xBBBB_0001_*`).
const MULTIBUFFER_STATUS_NAMESPACE: u64 = 0xBBBB_0002_0000_0000;

pub fn multibuffer_status_provider_id(buffer_id: BufferId) -> ProviderId {
    MULTIBUFFER_STATUS_NAMESPACE | u64::from(buffer_id.0)
}

/// MH.A4: fallback hex used when no theme is wired (test paths). These
/// are the pre-MH.A4 hardcoded colors; production resolves the
/// `multibuffer.status.*` theme elements instead.
const STATUS_IN_PROGRESS_FALLBACK_FG: u32 = 0x999999;
const STATUS_COMPLETE_FALLBACK_FG: u32 = 0x44cc88;
const STATUS_FAILED_FALLBACK_FG: u32 = 0xff4444;
/// Fallback accent for the emphasised term when the theme (or the
/// `multibuffer.status.query` element) is unresolved — a warm yellow,
/// the conventional search-highlight hue.
const STATUS_QUERY_FALLBACK_FG: u32 = 0xf9e2af;

/// Pure function: `HeaderlineStatus` → display row (or `None` when idle).
///
/// MH.A4: the per-state foregrounds are **resolved in `collect()` and
/// passed in** (from the `multibuffer.status.*` theme elements) — never
/// hardcoded here — so a `:colorscheme` swap recolors the status line.
/// Color legend:
///   InProgress — `in_progress_fg` (neutral grey), theme bg
///   Complete   — `complete_fg` (green), green `◆` prefix, theme bg
///   Failed     — `failed_fg` (red), red `■` prefix, theme bg
fn render_multibuffer_status(
    status: &HeaderlineStatus,
    in_progress_fg: u32,
    complete_fg: u32,
    failed_fg: u32,
    query_fg: u32,
) -> Option<HeaderlineRow> {
    let (text, emphasis): (String, Option<&str>) = match status {
        HeaderlineStatus::Idle => return None,
        HeaderlineStatus::InProgress {
            label,
            count: None,
            emphasis,
        } => (format!(" ⟳ {label} … "), emphasis.as_deref()),
        HeaderlineStatus::InProgress {
            label,
            count: Some(n),
            emphasis,
        } => (format!(" ⟳ {label} ({n}) … "), emphasis.as_deref()),
        HeaderlineStatus::Complete { summary, emphasis } => {
            (format!(" ◆ {summary} "), emphasis.as_deref())
        }
        HeaderlineStatus::Failed { reason } => (format!(" ■ {reason} "), None),
    };
    let fg: u32 = match status {
        HeaderlineStatus::InProgress { .. } => in_progress_fg,
        HeaderlineStatus::Complete { .. } => complete_fg,
        HeaderlineStatus::Failed { .. } => failed_fg,
        HeaderlineStatus::Idle => unreachable!(),
    };
    // Char-index range of the emphasised term within `text` (first
    // occurrence). Only the query cells get `query_fg`; everything else
    // keeps the state fg. Non-empty emphasis that isn't found → no accent.
    let emphasis_range: Option<(usize, usize)> = emphasis.filter(|e| !e.is_empty()).and_then(|e| {
        text.find(e).map(|byte_start| {
            let char_start = text[..byte_start].chars().count();
            (char_start, char_start + e.chars().count())
        })
    });
    let cells: Arc<[Cell]> = text
        .chars()
        .enumerate()
        .map(|(i, c)| {
            let cell_fg = match emphasis_range {
                Some((start, end)) if i >= start && i < end => query_fg,
                _ => fg,
            };
            Cell::new(c as u32, cell_fg, 0, 0)
        })
        .collect::<Vec<_>>()
        .into();
    Some(HeaderlineRow { cells, bg: None })
}

/// Sticky headerline provider that surfaces the view's
/// [`HeaderlineStatus`] as a pinned row above line 0.
///
/// Implements [`Headerline`] directly — the status lives in
/// `MultibufferInner` (behind an `ArcSwap`); no extra dedicated
/// state allocation is needed.
pub struct MultibufferStatusProvider {
    multibuffer: MultibufferDocumentHandle,
    /// MH.A4: `None` for test paths that don't wire a theme registry —
    /// `render()` then falls back to the pre-MH.A4 hardcoded hex.
    theme: Option<ThemeRegistryHandle>,
    /// MH.A4: the interned status element ids (mirrors the
    /// excerpt-header provider's `elements`), captured once at
    /// view-creation so `render()` resolves by array index.
    elements: MultibufferHeaderElementIds,
}

impl std::fmt::Debug for MultibufferStatusProvider {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("MultibufferStatusProvider")
            .field("buffer_id", &self.multibuffer.buffer_id())
            .field("has_theme", &self.theme.is_some())
            .field("elements", &self.elements)
            .finish()
    }
}

impl MultibufferStatusProvider {
    /// Construct without theme wiring — the status row renders with the
    /// pre-MH.A4 fallback hex. Test convenience; production uses
    /// [`Self::with_theme`].
    pub fn new(multibuffer: MultibufferDocumentHandle) -> Self {
        Self {
            multibuffer,
            theme: None,
            elements: MultibufferHeaderElementIds::default(),
        }
    }

    /// MH.A4: construct with the resolved theme handle + the interned
    /// status element ids so `render()` resolves the
    /// `multibuffer.status.*` foregrounds (mirrors the excerpt-header
    /// provider's `with_theme`).
    pub fn with_theme(
        multibuffer: MultibufferDocumentHandle,
        theme: ThemeRegistryHandle,
        elements: MultibufferHeaderElementIds,
    ) -> Self {
        Self {
            multibuffer,
            theme: Some(theme),
            elements,
        }
    }

    pub fn into_provider(self, buffer_id: BufferId) -> HeaderlineProvider {
        HeaderlineProvider::new(multibuffer_status_provider_id(buffer_id), Arc::new(self))
    }

    /// Resolve the three status foregrounds from the wired theme,
    /// falling back to the pre-MH.A4 hex per-state when the theme or an
    /// element is unresolved (test paths).
    fn status_fgs(&self) -> (u32, u32, u32, u32) {
        let resolved = self.theme.as_ref().map(|t| t.resolved());
        let resolve = |id: ElementId, fallback: u32| -> u32 {
            resolved
                .as_ref()
                .and_then(|r| r.get(id).fg)
                .map(|c| c.to_rgb_u32(fallback))
                .unwrap_or(fallback)
        };
        (
            resolve(
                self.elements.status_in_progress,
                STATUS_IN_PROGRESS_FALLBACK_FG,
            ),
            resolve(self.elements.status_complete, STATUS_COMPLETE_FALLBACK_FG),
            resolve(self.elements.status_failed, STATUS_FAILED_FALLBACK_FG),
            resolve(self.elements.status_query, STATUS_QUERY_FALLBACK_FG),
        )
    }
}

impl Headerline for MultibufferStatusProvider {
    fn version(&self) -> u64 {
        // MH.A4: fold the resolved theme version into the status
        // version so a `:colorscheme` / `:set ui.*` change re-runs
        // `render()` and re-resolves the status foregrounds. Mirrors
        // the excerpt-header provider's version composition.
        let content = self
            .multibuffer
            .inner
            .headerline_version
            .load(Ordering::Acquire);
        let theme = self
            .theme
            .as_ref()
            .map(|t| t.resolved().version())
            .unwrap_or(0);
        content.wrapping_add(theme)
    }

    fn render(&self) -> Option<HeaderlineRow> {
        let (in_progress_fg, complete_fg, failed_fg, query_fg) = self.status_fgs();
        render_multibuffer_status(
            &self.multibuffer.inner.headerline.load(),
            in_progress_fg,
            complete_fg,
            failed_fg,
            query_fg,
        )
    }
}

/// M.10.4 (2026-06-03): host glue for the
/// `:multibuffer-expand [n]` / `:multibuffer-contract [n]`
/// ex-commands. Looks up the active buffer's typed
/// `MultibufferDocumentHandle` via the
/// `MultibufferRegistryHandle` service and calls
/// `expand_excerpt_at(cursor_row, delta)`. No-op when the
/// active buffer isn't a multibuffer view, the service isn't
/// registered (test harness), or the cursor is out of range.
///
/// Replaces `Editor::do_multibuffer_expand` which used to live
/// in `lattice-host::dispatch`. Per
/// [[feedback_mode_owns_its_surface]] + `mode-architecture.md`
/// §5.3.4: this helper is the substrate-side counterpart to
/// the ex-command registration in `MultibufferMode`. Host's
/// `apply_effect` arm calls this directly — no longer
/// trampolines through `Action::MultibufferExpand` +
/// `Editor::do_multibuffer_expand`.
pub fn multibuffer_expand_excerpt_at(
    services: &lattice_mode::services::ServiceRegistry,
    buffer_id: BufferId,
    cursor_row: u32,
    delta: i32,
) {
    let Some(mb_registry) = services.get::<crate::registry::MultibufferRegistryHandle>() else {
        return;
    };
    let Some(view) = mb_registry.handle(buffer_id) else {
        return;
    };
    view.expand_excerpt_at(cursor_row, delta);
}

/// Default header-rendering: `── <title> ──` (box-drawing
/// rules). Empty title yields a row of box rules only.
pub fn default_header_cells(excerpt: &Excerpt) -> Arc<[Cell]> {
    let title = &excerpt.header.title;
    let mut cells = Vec::new();
    for _ in 0..2 {
        cells.push(Cell::with_codepoint('─' as u32));
    }
    if !title.is_empty() {
        cells.push(Cell::with_codepoint(' ' as u32));
        for ch in title.chars() {
            cells.push(Cell::with_codepoint(ch as u32));
        }
        cells.push(Cell::with_codepoint(' ' as u32));
    }
    for _ in 0..2 {
        cells.push(Cell::with_codepoint('─' as u32));
    }
    Arc::from(cells)
}

// ─────────────────────────────────────────────────────────────────
// Internals
// ─────────────────────────────────────────────────────────────────

fn next_multibuffer_document_id() -> DocumentId {
    static NEXT: AtomicU64 = AtomicU64::new(0x1000_0000_0000_0000);
    DocumentId::new(NEXT.fetch_add(1, Ordering::Relaxed))
}

/// M.11 (2026-06-02): build the composed text from sources at
/// initialization time. The result feeds `Document::from_text`
/// so the composed_doc starts in sync with the sources. After
/// this point, the composed_doc evolves through `apply_edit` —
/// sources catch up via the forwarder.
fn compose_text_from_sources(
    sources: &HashMap<BufferId, Arc<dyn Document>>,
    excerpts: &[Excerpt],
) -> String {
    let mut composed_text = String::new();
    for excerpt in excerpts {
        let Some(source) = sources.get(&excerpt.source) else {
            continue;
        };
        let snap = source.snapshot();
        for row in excerpt.start_line..=excerpt.end_line {
            if let Some(line) = snap.buffer.line(row) {
                composed_text.push_str(&line);
                if !composed_text.ends_with('\n') {
                    composed_text.push('\n');
                }
            }
        }
    }
    composed_text
}

/// M.11 (2026-06-02): build a `DocumentSnapshot` from the
/// composed_doc plus identity metadata. The composed_doc IS the
/// source of truth — this just wraps its current state in the
/// shape the renderer reads.
fn snapshot_from_composed_doc(
    doc: &lattice_core::Document,
    id: DocumentId,
    selections: Arc<SelectionSet>,
) -> DocumentSnapshot {
    DocumentSnapshot {
        id,
        version: doc.version(),
        text_version: doc.text_version(),
        buffer: doc.buffer().clone(),
        path: None,
        dirty: doc.dirty(),
        selections,
    }
}

fn compose_snapshot(
    id: DocumentId,
    sources: &HashMap<BufferId, Arc<dyn Document>>,
    excerpts: &[Excerpt],
    selections: Arc<SelectionSet>,
) -> DocumentSnapshot {
    let mut composed_text = String::new();
    let mut composed_version: u64 = 0;
    let mut composed_text_version: u64 = 0;

    for excerpt in excerpts {
        let Some(source) = sources.get(&excerpt.source) else {
            continue;
        };
        let snap = source.snapshot();
        composed_version = composed_version.saturating_add(snap.version);
        composed_text_version = composed_text_version.saturating_add(snap.text_version);
        for row in excerpt.start_line..=excerpt.end_line {
            if let Some(line) = snap.buffer.line(row) {
                composed_text.push_str(&line);
                if !composed_text.ends_with('\n') {
                    composed_text.push('\n');
                }
            }
        }
    }

    DocumentSnapshot {
        id,
        version: composed_version,
        text_version: composed_text_version,
        buffer: Buffer::from_text(&composed_text),
        path: None,
        dirty: false,
        // K.4.5 (2026-06-02): selections come from
        // `MultibufferState`, preserved across recomposes so
        // excerpt mutations (append / replace / clip) don't
        // clobber the user's Visual selection. Updated via
        // `set_selections` (Document trait).
        selections,
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic)]
    use super::*;
    use lattice_core::Document as CoreDocument;
    use lattice_grammar::CommandRegistry;
    use lattice_runtime::spawn_document;

    fn empty_registry() -> lattice_grammar::CommandRegistryHandle {
        Arc::new(arc_swap::ArcSwap::from_pointee(CommandRegistry::new()))
    }

    fn make_sources(texts: &[&str]) -> (HashMap<BufferId, Arc<dyn Document>>, Vec<BufferId>) {
        let mut map: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        let mut ids = Vec::new();
        for text in texts {
            let id = BufferId::next();
            let handle = spawn_document(id, CoreDocument::from_text(*text), empty_registry());
            map.insert(id, Arc::new(handle));
            ids.push(id);
        }
        (map, ids)
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn single_source_single_excerpt_composes() {
        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\ndelta\nepsilon\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 1, 3)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let snap = mb.snapshot();
        assert_eq!(snap.buffer.as_string(), "beta\ngamma\ndelta\n");
        assert!(!snap.dirty);
        assert!(snap.path.is_none());
        assert_eq!(snap.selections.all().len(), 1);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn multi_source_multi_excerpt_composes_in_order() {
        let (sources, ids) = make_sources(&["a1\na2\na3\n", "b1\nb2\nb3\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 1), Excerpt::new(ids[1], 2, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let snap = mb.snapshot();
        assert_eq!(snap.buffer.as_string(), "a1\na2\nb3\n");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn save_is_readonly_for_a_pathless_view() {
        // A path-less in-memory source has nothing to persist on
        // disk, so `:w` on such a view is `ReadOnly`. Real
        // file-backed sources DO save now — see
        // `save_persists_view_edits_to_the_source_file`.
        let (sources, ids) = make_sources(&["x"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        assert!(matches!(mb.save().await, Err(RuntimeError::ReadOnly)));
    }

    /// 2026-06-10: editing a multibuffer view and calling `save()`
    /// flushes the source-forwarder and persists the edit to the
    /// source FILE on disk — the generic `:w`-saves-sources path that
    /// narrow + project-search both rely on. The flush is load-
    /// bearing: without it `save()` would race the async forwarder
    /// and write the pre-edit source.
    #[tokio::test(flavor = "multi_thread")]
    async fn save_persists_view_edits_to_the_source_file() {
        let unique = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let path = std::env::temp_dir().join(format!("lattice-mb-save-{unique}.txt"));
        std::fs::write(&path, "alpha\nbeta\ngamma\n").unwrap();

        let id = BufferId::next();
        let doc = lattice_core::DocumentBuilder::default()
            .with_text("alpha\nbeta\ngamma\n")
            .with_path(path.clone())
            .build();
        let handle = spawn_document(id, doc, empty_registry());
        let source: Arc<dyn Document> = Arc::new(handle);
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(id, source);
        let excerpts = vec![Excerpt::new(id, 0, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Insert "X" at the start of row 1 in the composed view.
        mb.apply_edit(Edit::insert(Position::new(1, 0), "X"))
            .await
            .expect("edit applies");

        // save() flushes the forwarder (so the source has the edit)
        // then writes the source file back to disk.
        let saved = mb.save().await.expect("save ok");
        assert_eq!(saved, path);

        let on_disk = std::fs::read_to_string(&path).unwrap();
        assert_eq!(on_disk, "alpha\nXbeta\ngamma\n");
        std::fs::remove_file(&path).ok();
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn set_selections_stores_composed_selections_post_k_4_5() {
        // K.4.5 (2026-06-02): selections are view-owned in
        // composed coordinate space. set_selections now
        // stores the SelectionSet on `MultibufferState` and
        // republishes the snapshot, so
        // `Editor::visual_selection_range` reading
        // `self.document.selections().primary()` sees the
        // updated anchor / head — Visual-mode highlights
        // paint uniformly across BufferKinds.
        use lattice_protocol::position::Position;
        use lattice_protocol::selection::{Selection, VisualMode};

        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Initial snapshot: default empty selection set.
        let initial = mb.snapshot();
        assert_eq!(initial.selections.all().len(), 1);
        assert_eq!(initial.selections.primary().anchor, Position::new(0, 0));
        assert_eq!(initial.selections.primary().head, Position::new(0, 0));

        // Set a Visual-mode selection spanning the composed view.
        let sel = Selection {
            anchor: Position::new(0, 0),
            head: Position::new(1, 3),
            visual: Some(VisualMode::Charwise),
        };
        let set = SelectionSet::single(sel);
        mb.set_selections(set.clone()).await.expect("ok");

        // Snapshot now reflects the new selection.
        let after = mb.snapshot();
        assert_eq!(after.selections.primary().anchor, Position::new(0, 0));
        assert_eq!(after.selections.primary().head, Position::new(1, 3));
        assert_eq!(
            after.selections.primary().visual,
            Some(VisualMode::Charwise)
        );

        // Recompose preserves the selection (excerpt-mutation
        // paths read state.selections through compose_snapshot).
        mb.recompose();
        let recomposed = mb.snapshot();
        assert_eq!(
            recomposed.selections.primary().head,
            Position::new(1, 3),
            "recompose must preserve composed-coordinate selections"
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m3_insert_translates_and_forwards_to_source() {
        // M.11 (2026-06-02): under the local-rope architecture
        // the composed snapshot reflects the edit IMMEDIATELY
        // (synchronous local mutation). The source rope catches
        // up async via the source-forwarder task.
        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        let source_handle = sources.get(&ids[0]).expect("source present").clone();
        let excerpts = vec![Excerpt::new(ids[0], 0, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        let applied = mb
            .apply_edit(Edit::insert(Position::new(1, 0), "X-"))
            .await
            .expect("insert should land locally");
        assert_eq!(applied.inserted_text, "X-");
        // Composed snapshot reflects the edit synchronously.
        assert_eq!(mb.snapshot().buffer.as_string(), "alpha\nX-beta\ngamma\n");

        // Source catches up async via the forwarder task running
        // on shared_runtime (cross-runtime from the test's
        // multi_thread runtime). Poll with sleep.
        for _ in 0..40 {
            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
            if source_handle.text() == "alpha\nX-beta\ngamma\n" {
                return;
            }
        }
        panic!(
            "source did not converge to multibuffer edit; got: {:?}",
            source_handle.text()
        );
    }

    // ── OA.23b: writing at a line the view does not compose ───

    /// The agenda's `s`: the row is the headline, and `SCHEDULED:` goes on a
    /// line BELOW it that no excerpt contains. There is no composed coordinate
    /// for it, so `apply_edit` cannot reach it.
    #[tokio::test(flavor = "multi_thread")]
    async fn apply_to_source_writes_outside_every_excerpt() {
        let (sources, ids) = make_sources(&["* TODO write it\n* TODO and it\n"]);
        let source_handle = sources.get(&ids[0]).expect("source present").clone();
        // Only the FIRST line is excerpted — an agenda row.
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        assert_eq!(mb.snapshot().buffer.as_string(), "* TODO write it\n");

        mb.apply_to_source(
            ids[0],
            Edit::insert(Position::new(1, 0), "  SCHEDULED: <2026-09-03 Thu>\n"),
        )
        .expect("the view owns this source")
        .await
        .expect("the edit lands");

        assert_eq!(
            source_handle.text(),
            "* TODO write it\n  SCHEDULED: <2026-09-03 Thu>\n* TODO and it\n"
        );
        // The view shows the headline and only the headline: the planning line
        // is outside it, which is the whole reason it needed this door.
        assert_eq!(mb.snapshot().buffer.as_string(), "* TODO write it\n");
        assert!(source_handle.dirty(), "`:w` on the view must write this");
    }

    /// A source id no view owns gets `None` rather than a panic or a write
    /// somewhere else — the caller is acting on an id it was handed, and a
    /// view can close between the two.
    #[tokio::test(flavor = "multi_thread")]
    async fn apply_to_source_declines_a_source_it_does_not_own() {
        let (sources, ids) = make_sources(&["a\n"]);
        let mb = MultibufferDocumentHandle::new(
            sources,
            vec![Excerpt::new(ids[0], 0, 0)],
            empty_registry(),
        )
        .unwrap();
        assert!(
            mb.apply_to_source(BufferId::next(), Edit::insert(Position::new(0, 0), "x"))
                .is_none()
        );
    }

    /// The ordering the `DirectEdit` variant exists for.
    ///
    /// A composed edit reaches its source ASYNC, through the forwarder. A
    /// direct source write that went straight at the document could overtake
    /// one still in flight — and that queued edit's source coordinates were
    /// computed BEFORE this insert shifted the lines below it, so it would
    /// then land in the wrong place. Riding the same FIFO is what prevents it.
    ///
    /// Written as: type into the composed line, then immediately insert a line
    /// ABOVE everything through the direct door. If the direct write overtook,
    /// the composed edit's `X-` would land on the wrong row.
    #[tokio::test(flavor = "multi_thread")]
    async fn a_direct_write_queues_behind_composed_edits_in_flight() {
        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        let source_handle = sources.get(&ids[0]).expect("source present").clone();
        let excerpts = vec![Excerpt::new(ids[0], 1, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Composed line 0 is source line 1 (`beta`). Queued, not yet applied.
        mb.apply_edit(Edit::insert(Position::new(0, 0), "X-"))
            .await
            .expect("insert lands locally");
        // Straight after, a write at the top of the FILE.
        mb.apply_to_source(ids[0], Edit::insert(Position::new(0, 0), "header\n"))
            .expect("the view owns this source")
            .await
            .expect("the edit lands");

        assert_eq!(
            source_handle.text(),
            "header\nalpha\nX-beta\ngamma\n",
            "the composed edit must have landed on `beta` before the header shifted it"
        );
    }

    // ── K.4.11-fix: an operator's edits have to LAND ──────────
    //
    // Grammar dispatch runs against a scratch clone of the composed
    // rope, so an operator reported edits it had made to a throwaway.
    // The host publishes those deltas assuming the document already
    // applied them — true for a real `Document` actor, false here — so
    // `x` / `dd` / `cw` were inert in every multibuffer view while
    // insert-mode typing worked, because typing does not go through
    // dispatch.

    /// Build a one-source view and run `invocation` through the real
    /// dispatch path, returning the source handle so the test can watch
    /// it converge.
    fn view_for_dispatch(
        text: &str,
    ) -> (
        MultibufferDocumentHandle,
        std::sync::Arc<dyn Document>,
        lattice_grammar::CommandRegistryHandle,
        lattice_grammar::builtins::Builtins,
    ) {
        let (sources, ids) = make_sources(&[text]);
        let source_handle = sources.get(&ids[0]).expect("source present").clone();
        let mut registry = lattice_grammar::CommandRegistry::new();
        let builtins = lattice_grammar::builtins::populate(&mut registry);
        let handle: lattice_grammar::CommandRegistryHandle =
            Arc::new(arc_swap::ArcSwap::from_pointee(registry));
        let excerpts = vec![Excerpt::new(ids[0], 0, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, handle.clone()).unwrap();
        (mb, source_handle, handle, builtins)
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn an_operator_edits_the_composed_view() {
        let (mb, _source, _reg, builtins) = view_for_dispatch("alpha\nbeta\ngamma\n");
        assert_eq!(mb.snapshot().buffer.as_string(), "alpha\nbeta\ngamma\n");

        // `x` at (0,0): delete-char-forward over one character.
        let inv = lattice_grammar::CommandInvocation::of(builtins.delete.0).with_target(
            lattice_grammar::Target::Motion(builtins.char_right, lattice_grammar::args::Args::None),
        );
        mb.dispatch(inv, Position::new(0, 0))
            .await
            .expect("dispatch succeeds");

        assert_eq!(
            mb.snapshot().buffer.as_string(),
            "lpha\nbeta\ngamma\n",
            "the operator's edit must land on the composed rope, not on the scratch"
        );
    }

    /// The half that would still be missing if the fix only mutated the
    /// composed rope: a multibuffer edit is an edit to a FILE, and the
    /// view exists to propagate it. Replaying through
    /// `apply_edit_batch_sync` is what buys this — it is the M.3 path,
    /// so the source forward comes with it.
    #[tokio::test(flavor = "multi_thread")]
    async fn an_operator_edit_reaches_the_source_document() {
        let (mb, source, _reg, builtins) = view_for_dispatch("alpha\nbeta\ngamma\n");
        let inv = lattice_grammar::CommandInvocation::of(builtins.delete.0).with_target(
            lattice_grammar::Target::Motion(builtins.char_right, lattice_grammar::args::Args::None),
        );
        mb.dispatch(inv, Position::new(0, 0))
            .await
            .expect("dispatch succeeds");

        for _ in 0..40 {
            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
            if source.text() == "lpha\nbeta\ngamma\n" {
                return;
            }
        }
        panic!(
            "source never saw the operator's edit; got {:?}",
            source.text()
        );
    }

    /// A motion reports a cursor and no edits, so it must pass through
    /// the landing step untouched. Without this, a fix that blindly
    /// re-applied everything would turn every `j` into a rope mutation.
    #[tokio::test(flavor = "multi_thread")]
    async fn a_motion_changes_no_text() {
        let (mb, _source, _reg, builtins) = view_for_dispatch("alpha\nbeta\ngamma\n");
        let before = mb.snapshot().buffer.as_string();
        let inv = lattice_grammar::CommandInvocation::of(builtins.line_down.0);
        mb.dispatch(inv, Position::new(0, 0))
            .await
            .expect("dispatch succeeds");
        assert_eq!(mb.snapshot().buffer.as_string(), before);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m3_insert_translates_when_excerpt_starts_off_zero() {
        // M.11: composed snapshot reflects edit synchronously.
        let (sources, ids) = make_sources(&["zero\none\ntwo\nthree\nfour\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 2, 4)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        assert_eq!(mb.snapshot().buffer.as_string(), "two\nthree\nfour\n");

        mb.apply_edit(Edit::insert(Position::new(0, 0), "Z "))
            .await
            .expect("insert should land locally");
        assert_eq!(mb.snapshot().buffer.as_string(), "Z two\nthree\nfour\n");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m3_delete_within_excerpt_translates() {
        // M.11: composed snapshot reflects edit synchronously.
        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        use lattice_protocol::position::Range;
        let _ = mb
            .apply_edit(Edit::delete(Range::new(
                Position::new(1, 0),
                Position::new(2, 0),
            )))
            .await
            .expect("delete should land locally");
        assert_eq!(mb.snapshot().buffer.as_string(), "alpha\ngamma\n");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m3_out_of_range_edit_returns_read_only() {
        // M.11: the local composed_doc is a regular `Document`,
        // so its `apply_edit` rejects out-of-range edits via
        // `CoreError`. Any Err variant is acceptable — the
        // contract is "out-of-range fails, doesn't panic."
        let (sources, ids) = make_sources(&["a\nb\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        assert!(
            mb.apply_edit(Edit::insert(Position::new(50, 0), "x"))
                .await
                .is_err(),
            "out-of-range edit must fail (any Err variant)"
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m3_boundary_clip_drops_cross_excerpt_tail() {
        // Two excerpts from two different sources.
        let (mut sources, ids) = make_sources(&["AA\nBB\nCC\n", "11\n22\n33\n"]);
        // sources contains both; ids[0] = A-source, ids[1] = B-source.
        let excerpts = vec![
            // composed rows 0..=2 — A
            Excerpt::new(ids[0], 0, 2),
            // composed rows 3..=5 — B
            Excerpt::new(ids[1], 0, 2),
        ];
        // Snapshot the original B-source text for the post-edit assertion.
        let b_handle = sources.remove(&ids[1]).expect("B source present");
        sources.insert(ids[1], b_handle.clone());
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let original_b_text = b_handle.text();

        // Cross-excerpt delete: range (0,0)..(5,0) — spans into B.
        use lattice_protocol::position::Range;
        let _ = mb
            .apply_edit(Edit::delete(Range::new(
                Position::new(0, 0),
                Position::new(5, 0),
            )))
            .await;

        // A was edited (boundary-clipped to A's last row).
        // B was NOT edited (boundary clip dropped the tail).
        assert_eq!(
            b_handle.text(),
            original_b_text,
            "B source must be untouched"
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m3_apply_edit_batch_serialises_inserts() {
        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Two inserts in row order. Batch dispatches them
        // sequentially; second insert sees the buffer state
        // after the first.
        let edits = vec![
            Edit::insert(Position::new(0, 0), "<"),
            Edit::insert(Position::new(2, 5), ">"),
        ];
        let results = mb.apply_edit_batch(edits).await.expect("batch ok");
        assert_eq!(results.len(), 2);
        // M.11: composed snapshot reflects edits synchronously.
        // After "<" at (0,0): "<alpha\nbeta\ngamma\n"
        // After ">" at composed (2,5) = source (2,5): "<alpha\nbeta\ngamma>\n"
        assert_eq!(mb.snapshot().buffer.as_string(), "<alpha\nbeta\ngamma>\n");
    }

    /// 2026-06-02 cursor-jump regression: an excerpt that
    /// covers SOURCE rows 5..=7 maps to COMPOSED rows 0..=2.
    /// An insert at composed (0, 5) hits source (5, 5). The
    /// host's insert-mode path
    /// (`lattice-host::dispatch::do_insert_str_blocking`)
    /// reads `applied.inserted_range.end.line` and sets the
    /// cursor — if `apply_edit` returned the source's
    /// inserted_range.end (line 5) instead of the composed
    /// equivalent (line 0), the cursor would jump to line 5
    /// of the composed view, which renders the wrong text and
    /// breaks every subsequent insert. Verify the translation
    /// happens.
    #[tokio::test(flavor = "multi_thread")]
    async fn m3_apply_edit_returns_composed_coords() {
        let (sources, ids) = make_sources(&["a\nb\nc\nd\ne\nf\ng\nh\n"]);
        // Excerpt covers source rows 5..=7 → composed rows
        // 0..=2.
        let excerpts = vec![Excerpt::new(ids[0], 5, 7)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Insert "X" at composed (0, 0). In source coords
        // that's (5, 0). The host's cursor advance reads
        // `applied.inserted_range.end`; pre-fix that returned
        // `Position { line: 5, byte: 1 }` (source coords),
        // jumping the cursor to composed row 5 — past the
        // multibuffer's three composed rows.
        let applied = mb
            .apply_edit(Edit::insert(Position::new(0, 0), "X"))
            .await
            .expect("edit ok");

        assert_eq!(
            applied.inserted_range.start,
            Position::new(0, 0),
            "start must be composed (0,0), not source (5,0)"
        );
        assert_eq!(
            applied.inserted_range.end,
            Position::new(0, 1),
            "end must be composed (0,1), not source (5,1) — \
             this is the cursor-jump bug"
        );
        assert_eq!(applied.original_range.start, Position::new(0, 0));
        assert_eq!(applied.original_range.end, Position::new(0, 0));
        // EditDelta positions also translated.
        assert_eq!(applied.delta.start_position, Position::new(0, 0));
        assert_eq!(applied.delta.new_end_position, Position::new(0, 1));
    }

    /// Same property for `apply_edit_batch` — each result in
    /// the batch must carry composed coords for that edit's
    /// excerpt.
    #[tokio::test(flavor = "multi_thread")]
    async fn m3_apply_edit_batch_returns_composed_coords() {
        // Two excerpts: source rows 5..=5 (composed 0..=0) and
        // source rows 10..=10 (composed 1..=1).
        let (sources, ids) = make_sources(&["0\n1\n2\n3\n4\n5\n6\n7\n8\n9\nA\nB\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 5, 5), Excerpt::new(ids[0], 10, 10)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        let results = mb
            .apply_edit_batch(vec![
                Edit::insert(Position::new(0, 0), "X"),
                Edit::insert(Position::new(1, 0), "Y"),
            ])
            .await
            .expect("batch ok");

        assert_eq!(results.len(), 2);
        // First result: composed row 0 (was source row 5).
        assert_eq!(
            results[0].inserted_range.end,
            Position::new(0, 1),
            "first batch result must be composed (0,1)"
        );
        // Second result: composed row 1 (was source row 10).
        // Note: the second edit's actual source row after the
        // first edit lands is 10 (the first insert was at
        // source col 0 of row 5, only widening that row's
        // bytes — row indices unchanged). Composed row 1.
        assert_eq!(
            results[1].inserted_range.end,
            Position::new(1, 1),
            "second batch result must be composed (1,1)"
        );
    }

    /// 2026-06-02 stale-snapshot regression: typing a character
    /// in a multibuffer must update the composed snapshot the
    /// renderer reads on the next frame. Pre-fix the host's
    /// `publish_document_changed` fired under the multibuffer's
    /// id (not the source's), so the M.4 forwarder ignored it
    /// and the composed snapshot stayed pre-edit. Cursor would
    /// advance correctly (translate_applied_to_composed) but the
    /// rendered text never changed. Verify the snapshot updates
    /// synchronously after apply_edit returns.
    #[tokio::test(flavor = "multi_thread")]
    async fn m3_apply_edit_updates_composed_snapshot_without_forwarder() {
        let (sources, ids) = make_sources(&["hello\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        // No attach_event_subscriptions call — production path
        // does it in create_multibuffer_view, but the forwarder
        // wouldn't fire here anyway because no event bus is
        // wired. Verify apply_edit's own recompose lands.
        assert_eq!(mb.snapshot().buffer.as_string(), "hello\n");

        let _ = mb
            .apply_edit(Edit::insert(Position::new(0, 5), "!"))
            .await
            .expect("edit ok");

        assert_eq!(
            mb.snapshot().buffer.as_string(),
            "hello!\n",
            "composed snapshot must reflect the new content; \
             the renderer reads this on the next frame"
        );
    }

    /// M.10.2 (2026-06-03): cursor at composed (0, 5) on an
    /// excerpt covering source rows 5..=7 maps to source
    /// (5, 5). Byte column preserved (each composed row is a
    /// verbatim copy of its source line).
    #[tokio::test(flavor = "multi_thread")]
    async fn m10_2_translate_composed_to_source_single_excerpt() {
        let (sources, ids) = make_sources(&["0\n1\n2\n3\n4\n5\n6\n7\n8\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 5, 7)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        let target = mb
            .translate_composed_to_source(Position::new(0, 5))
            .expect("composed (0,5) must translate");
        assert_eq!(target.0, ids[0], "source buffer id");
        assert_eq!(target.1, Position::new(5, 5), "source position");

        // Composed (2, 0) → source (5 + 2, 0) = (7, 0).
        let target = mb
            .translate_composed_to_source(Position::new(2, 0))
            .expect("composed (2,0) must translate");
        assert_eq!(target.1, Position::new(7, 0));
    }

    // ---- N.1.5: ComposedScopeResolver (composed↔source text objects) ----

    use lattice_grammar::ScopeResolver as _;

    fn rust_snapshot(src: &str) -> Arc<SyntaxSnapshot> {
        let lr = LangRegistry::standard().unwrap();
        let mut syntax = Syntax::for_language_with_registry(Lang::Rust, lr)
            .unwrap()
            .unwrap();
        syntax.parse(src);
        SyntaxHandle::seeded(syntax).snapshot()
    }

    #[test]
    fn composed_resolver_maps_function_outer_to_source() {
        // Source: a `target` fn on rows 1..=3, narrowed into a one-excerpt
        // view (composed rows 0..=2 == source rows 1..=3).
        let src = "fn keep_a() {}\nfn target() {\n    let x = 1;\n}\nfn keep_b() {}\n";
        let snap = rust_snapshot(src);
        let resolver = ComposedScopeResolver {
            excerpts: vec![ComposedExcerptSpan {
                source: BufferId(1),
                start_line: 1,
                line_count: 3,
                composed_offset: 0,
            }],
            snapshots: HashMap::from([(BufferId(1), snap)]),
        };
        // Cursor at composed (1,4) == source (2,4), inside `target`'s body.
        // `af` resolves the whole function (source rows 1..=3) and maps
        // back to composed rows 0..=2.
        let r = resolver.scope_at(1, 4, "function.outer");
        assert_eq!(
            r,
            Some(lattice_protocol::position::Range::new(
                lattice_protocol::position::Position::new(0, 0),
                lattice_protocol::position::Position::new(2, 1),
            )),
            "af inside a narrow view resolves the source function, mapped to composed rows"
        );
    }

    #[test]
    fn composed_resolver_clamps_scope_to_excerpt() {
        // Excerpt covers only source row 2 (the body line). `af` resolves
        // the function (source 1..=3) but the result is CLAMPED to the
        // single visible row — never out-of-bounds composed rows.
        let src = "fn keep_a() {}\nfn target() {\n    let x = 1;\n}\nfn keep_b() {}\n";
        let snap = rust_snapshot(src);
        let resolver = ComposedScopeResolver {
            excerpts: vec![ComposedExcerptSpan {
                source: BufferId(1),
                start_line: 2,
                line_count: 1,
                composed_offset: 0,
            }],
            snapshots: HashMap::from([(BufferId(1), snap)]),
        };
        let r = resolver.scope_at(0, 4, "function.outer");
        assert_eq!(
            r,
            Some(lattice_protocol::position::Range::new(
                lattice_protocol::position::Position::new(0, 0),
                lattice_protocol::position::Position::new(0, 0),
            )),
            "a scope extending past the excerpt is clipped to the visible rows"
        );
    }

    #[test]
    fn composed_resolver_applies_composed_offset_for_second_excerpt() {
        // Two excerpts from the same source: [0,0] then [1,3]. The second
        // sits at composed_offset 1, so resolving inside it must add the
        // offset back when mapping the source range to composed rows.
        let src = "fn keep_a() {}\nfn target() {\n    let x = 1;\n}\nfn keep_b() {}\n";
        let snap = rust_snapshot(src);
        let resolver = ComposedScopeResolver {
            excerpts: vec![
                ComposedExcerptSpan {
                    source: BufferId(1),
                    start_line: 0,
                    line_count: 1,
                    composed_offset: 0,
                },
                ComposedExcerptSpan {
                    source: BufferId(1),
                    start_line: 1,
                    line_count: 3,
                    composed_offset: 1,
                },
            ],
            snapshots: HashMap::from([(BufferId(1), snap)]),
        };
        // Composed row 2 lives in the second excerpt → source row 2.
        let r = resolver.scope_at(2, 4, "function.outer");
        assert_eq!(
            r,
            Some(lattice_protocol::position::Range::new(
                lattice_protocol::position::Position::new(1, 0),
                lattice_protocol::position::Position::new(3, 1),
            )),
            "the second excerpt's composed_offset (1) is added to the mapped rows"
        );
    }

    /// M.10.2 (2026-06-03): out-of-range composed cursor
    /// returns None (no excerpt covers that row).
    #[tokio::test(flavor = "multi_thread")]
    async fn m10_2_translate_composed_to_source_out_of_range() {
        let (sources, ids) = make_sources(&["a\nb\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Excerpt covers composed rows 0..=1; row 5 is past.
        assert!(
            mb.translate_composed_to_source(Position::new(5, 0))
                .is_none()
        );
    }

    /// M.10.2 (2026-06-03): multi-excerpt walk — cursor on the
    /// second excerpt maps to its source.
    #[tokio::test(flavor = "multi_thread")]
    async fn m10_2_translate_composed_to_source_multi_excerpt() {
        let (sources, ids) = make_sources(&["AA\nBB\n", "11\n22\n"]);
        let excerpts = vec![
            Excerpt::new(ids[0], 0, 1), // composed 0..=1
            Excerpt::new(ids[1], 0, 1), // composed 2..=3
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Composed (0, 1) → source A (0, 1).
        let t = mb
            .translate_composed_to_source(Position::new(0, 1))
            .unwrap();
        assert_eq!(t.0, ids[0]);
        assert_eq!(t.1, Position::new(0, 1));

        // Composed (3, 1) → source B (1, 1).
        let t = mb
            .translate_composed_to_source(Position::new(3, 1))
            .unwrap();
        assert_eq!(t.0, ids[1]);
        assert_eq!(t.1, Position::new(1, 1));
    }

    /// M.11 (2026-06-02): the search provider's exact flow —
    /// construct an empty multibuffer, then stream excerpts via
    /// `append_excerpts`, then type. Pre-fix the composed_doc
    /// stayed empty (only state.excerpts + the published
    /// snapshot reflected the stream), so user inserts hit an
    /// empty rope and silently no-op'd through
    /// do_insert_text's `let Ok(applied) = … else { return };`.
    /// This was the root cause of "typing does nothing" the
    /// user reported after M.11 first landed.
    #[tokio::test(flavor = "multi_thread")]
    async fn m11_streamed_excerpts_keep_composed_doc_in_sync_for_insert() {
        // Empty construction — exactly what
        // `project_search → create_multibuffer_view` does for
        // an in-progress scan.
        let (sources, ids) = make_sources(&["zero\none\ntwo\nthree\nfour\n"]);
        let mb = MultibufferDocumentHandle::new(sources, vec![], empty_registry()).unwrap();
        assert_eq!(mb.snapshot().buffer.as_string(), "");

        // Stream an excerpt (the search hit).
        mb.append_excerpts(vec![Excerpt::new(ids[0], 2, 2)]);
        assert_eq!(
            mb.snapshot().buffer.as_string(),
            "two\n",
            "snapshot must reflect the streamed excerpt"
        );

        // Now type — insert at the end of the line.
        let applied = mb
            .apply_edit(Edit::insert(Position::new(0, 3), "X"))
            .await
            .expect("post-stream insert must succeed (pre-fix this Err'd silently)");
        assert_eq!(applied.inserted_range.end, Position::new(0, 4));
        assert_eq!(
            mb.snapshot().buffer.as_string(),
            "twoX\n",
            "composed snapshot must reflect the insert; \
             pre-fix the snapshot stayed at \"two\\n\" because \
             composed_doc was empty and apply_edit no-op'd"
        );
    }

    /// 2026-06-02: simulate the user's insert-mode flow — two
    /// consecutive single-char apply_edit calls. After each, the
    /// composed snapshot must reflect the cumulative text. The
    /// user reported the first char landed visibly but the second
    /// didn't ("switched to how it was before, every character in
    /// insert mode just moves the cursor along").
    #[tokio::test(flavor = "multi_thread")]
    async fn m3_consecutive_inserts_accumulate_in_composed_snapshot() {
        // Source with 8 lines; excerpt covers source row 5 only.
        let (sources, ids) = make_sources(&["0\n1\n2\n3\n4\nfive\n6\n7\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 5, 5)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        assert_eq!(mb.snapshot().buffer.as_string(), "five\n");

        // First insert at end-of-line (composed (0, 4)) — vim
        // `a` at end-of-line lands here. Append 'x'.
        let r1 = mb
            .apply_edit(Edit::insert(Position::new(0, 4), "x"))
            .await
            .expect("first edit ok");
        assert_eq!(
            r1.inserted_range.end,
            Position::new(0, 5),
            "first cursor must be composed (0,5)"
        );
        assert_eq!(
            mb.snapshot().buffer.as_string(),
            "fivex\n",
            "first char must land in composed snapshot"
        );

        // Second insert at composed (0, 5) — append 'y'.
        let r2 = mb
            .apply_edit(Edit::insert(Position::new(0, 5), "y"))
            .await
            .expect("second edit ok");
        assert_eq!(
            r2.inserted_range.end,
            Position::new(0, 6),
            "second cursor must be composed (0,6)"
        );
        assert_eq!(
            mb.snapshot().buffer.as_string(),
            "fivexy\n",
            "second char must accumulate; not revert to original"
        );

        // Third insert at composed (0, 6) — append 'z'.
        let r3 = mb
            .apply_edit(Edit::insert(Position::new(0, 6), "z"))
            .await
            .expect("third edit ok");
        assert_eq!(r3.inserted_range.end, Position::new(0, 7));
        assert_eq!(mb.snapshot().buffer.as_string(), "fivexyz\n");
    }

    // ─────────────────────────────────────────────────────────────
    // M.4 tests
    // ─────────────────────────────────────────────────────────────

    #[tokio::test(flavor = "multi_thread")]
    async fn m4_headerline_starts_idle_and_can_be_set() {
        let (sources, ids) = make_sources(&["x\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        assert!(matches!(*mb.headerline(), HeaderlineStatus::Idle));

        mb.set_headerline(HeaderlineStatus::InProgress {
            label: "Searching".into(),
            count: Some(42),
            emphasis: None,
        });
        match &*mb.headerline() {
            HeaderlineStatus::InProgress { label, count, .. } => {
                assert_eq!(label, "Searching");
                assert_eq!(*count, Some(42));
            }
            other => panic!("expected InProgress, got {other:?}"),
        }

        mb.set_headerline(HeaderlineStatus::Complete {
            summary: "87 hits".into(),
            emphasis: None,
        });
        match &*mb.headerline() {
            HeaderlineStatus::Complete { summary, .. } => assert_eq!(summary, "87 hits"),
            other => panic!("expected Complete, got {other:?}"),
        }
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m4_set_headerline_publishes_changed_event_when_attached() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<MultibufferHeaderlineChanged>();
        bus.subscribe_typed::<MultibufferHeaderlineChanged>(tx);

        let (sources, ids) = make_sources(&["y\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let view_id = mb.buffer_id();
        mb.attach_event_subscriptions(&bus);

        mb.set_headerline(HeaderlineStatus::Complete {
            summary: "done".into(),
            emphasis: None,
        });

        let evt = tokio::time::timeout(std::time::Duration::from_millis(200), rx.recv())
            .await
            .expect("event should arrive")
            .expect("channel open");
        assert_eq!(evt.view, view_id);
        assert!(matches!(evt.status, HeaderlineStatus::Complete { .. }));
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m4_source_change_auto_recomposes_view() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (sources, ids) = make_sources(&["alpha\nbeta\n"]);
        let source_handle = sources.get(&ids[0]).unwrap().clone();
        let excerpts = vec![Excerpt::new(ids[0], 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);
        assert_eq!(mb.snapshot().buffer.as_string(), "alpha\nbeta\n");

        // Source edit publishes DocumentChanged on the bus the
        // multibuffer subscribed to. After a brief yield, the
        // forwarder task should have recomposed.
        // The mock setup above doesn't wire the source handle to
        // PUBLISH on the bus — `spawn_document` publishes events
        // only when given a bus. So this test verifies the
        // SUBSCRIBE path: directly publish a DocumentChanged
        // event with the source's DocumentId and confirm the
        // multibuffer recomposes.
        source_handle
            .apply_edit(Edit::insert(Position::new(0, 0), "<"))
            .await
            .unwrap();
        // Simulate the source's DocumentChanged publish.
        bus.publish(lattice_protocol::Event::DocumentChanged {
            id: source_handle.id(),
            path: None,
            version: source_handle.version(),
            edits: Vec::new(),
        });

        // Wait for the spawned forwarder to process. Longer
        // budget than yield_now because tokio's multi-thread
        // runtime may park the task briefly.
        for _ in 0..50 {
            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
            if mb.snapshot().buffer.as_string() != "alpha\nbeta\n" {
                break;
            }
        }
        assert_eq!(mb.snapshot().buffer.as_string(), "<alpha\nbeta\n");
    }

    /// A source edit must reparse that source's syntax, not just recompose.
    ///
    /// The reported bug: a task toggled to DONE in the agenda kept painting in
    /// TODO's colour, and `<C-l>` did not fix it either. `add_source` built
    /// handles with `SyntaxHandle::seeded` (`on_publish: None`), and nothing
    /// anywhere called `request_reparse` on one — so a source handle parsed
    /// once at creation and its snapshot was frozen for the life of the view.
    /// The `DocumentChanged` arm recomposed the TEXT beside it, which is
    /// exactly why the symptom reads as "new text, old colours" rather than
    /// "nothing updates".
    ///
    /// Asserted through `excerpt_syntax_version`, because that is the value
    /// the host folds into `MatrixVersion::syntax`: a reparse the cells worker
    /// cannot see is a reparse that changes nothing on screen.
    ///
    /// **No second edit, no keypress.** The wake is the other half of the fix
    /// and a test that nudged the view first would pass on the frozen build.
    #[tokio::test(flavor = "multi_thread")]
    async fn a_source_edit_reparses_that_sources_syntax() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let unique = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let path = std::env::temp_dir().join(format!("lattice-mb-reparse-{unique}.rs"));
        let text = "fn main() { let x = 1; }\n";
        std::fs::write(&path, text).unwrap();

        let id = BufferId::next();
        let doc = lattice_core::DocumentBuilder::default()
            .with_text(text)
            .with_path(path.clone())
            .build();
        let source_handle = spawn_document(id, doc, empty_registry());
        let source: Arc<dyn Document> = Arc::new(source_handle.clone());
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(id, source);
        let excerpts = vec![Excerpt::new(id, 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);

        // Highlighting is only wired once a language registry exists; without
        // it there is no handle and this test would pass vacuously.
        let Ok(live) = lattice_syntax::registry::live() else {
            eprintln!("skipping: no live language registry in this process");
            return;
        };
        mb.set_lang_registry(live);
        if mb.excerpt_highlights().is_empty() {
            eprintln!("skipping: no grammar registered for .rs in this process");
            return;
        }
        let before = mb.excerpt_syntax_version();

        source_handle
            .apply_edit(Edit::insert(Position::new(0, 0), "//"))
            .await
            .unwrap();
        bus.publish(lattice_protocol::Event::DocumentChanged {
            id: source_handle.id(),
            path: Some(path.clone()),
            version: source_handle.version(),
            edits: Vec::new(),
        });

        let mut moved = false;
        for _ in 0..100 {
            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            if mb.excerpt_syntax_version() != before {
                moved = true;
                break;
            }
        }
        assert!(
            moved,
            "the source's syntax must reparse and bump the version the cells \
             worker invalidates on; frozen at {before} means the view keeps \
             painting the old spans forever"
        );
    }

    /// An edit made THROUGH the view must reparse its source too.
    ///
    /// This is the path an agenda `DONE` toggle takes: org's `rewrite_headline`
    /// reads composed rows and targets the VIEW, so the edit lands in the
    /// composed rope and is forwarded to the source. That forward used to
    /// apply the edit and publish nothing — "the multibuffer's local
    /// composed_doc is already authoritative" — so the source changed
    /// silently and NOTHING downstream learned of it: not this view's syntax,
    /// not a second view on the same file, not the diff subsystem.
    ///
    /// The sibling test above drives the same repair from an OUTSIDE change
    /// (a synthetic `DocumentChanged`). It passes with the forwarder still
    /// silent, which is exactly why this one has to exist.
    #[tokio::test(flavor = "multi_thread")]
    async fn an_edit_through_the_view_reparses_its_source() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let unique = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let path = std::env::temp_dir().join(format!("lattice-mb-through-{unique}.rs"));
        let text = "fn main() { let x = 1; }\nfn other() {}\n";
        std::fs::write(&path, text).unwrap();

        let id = BufferId::next();
        let doc = lattice_core::DocumentBuilder::default()
            .with_text(text)
            .with_path(path.clone())
            .build();
        let source: Arc<dyn Document> = Arc::new(spawn_document(id, doc, empty_registry()));
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(id, source);
        let excerpts = vec![Excerpt::new(id, 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);

        let Ok(live) = lattice_syntax::registry::live() else {
            eprintln!("skipping: no live language registry in this process");
            return;
        };
        mb.set_lang_registry(live);
        if mb.excerpt_highlights().is_empty() {
            eprintln!("skipping: no grammar registered for .rs in this process");
            return;
        }
        let before_syntax = mb.excerpt_syntax_version();
        let before_rows = mb.snapshot().buffer.as_string();

        // Through the VIEW, at composed coordinates — no synthetic event.
        mb.apply_edit(Edit::insert(Position::new(0, 0), "//"))
            .await
            .expect("composed edit applies");

        // Nothing else is dispatched: the forwarder's announce is the only
        // thing that can carry this to the source's syntax.
        let mut moved = false;
        for _ in 0..100 {
            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
            if mb.excerpt_syntax_version() != before_syntax {
                moved = true;
                break;
            }
        }
        assert!(
            moved,
            "an edit through the view must reach the source's syntax; frozen \
             at {before_syntax} is the DONE-painted-as-TODO bug"
        );

        // …and the echo must not be mistaken for an outside change. Sliding
        // anchors for an edit the composed rope already accounted for would
        // move every row below the edited one.
        assert_eq!(
            mb.snapshot().buffer.as_string(),
            format!("//{before_rows}"),
            "the composed rows must be the edit and nothing else — a second \
             anchor slide shows up here as duplicated or dropped rows"
        );
    }

    /// Regression (2026-09-28): the back-fill path — `new(sources)` then
    /// `set_lang_registry` — must resolve grammars against the LIVE registry,
    /// not the `lr` it is handed. `*problems*` and the references view take
    /// this path, and production wires it with the host's BOOT-SNAPSHOT
    /// registry (bundled-only, and for a plugin grammar or a stale capture it
    /// lacks the language entirely), so every excerpt painted uncoloured while
    /// project-search — which streams through `add_source` on the live
    /// registry — highlighted fine. That asymmetry was the whole bug: "the
    /// *problems* buffer should have syntax highlighting like any other
    /// multibuffer view."
    ///
    /// The test hands `set_lang_registry` a DELIBERATELY-EMPTY registry as the
    /// snapshot. Pre-fix that empty registry was what `.rs` resolved against,
    /// so `excerpt_highlights()` came back empty; post-fix resolution goes
    /// through `registry::live()` and the excerpt highlights regardless of
    /// what the snapshot held. A test that passed `live()` here (as the two
    /// above do) would pass on the broken build too — the empty snapshot is
    /// the point.
    #[test]
    fn back_fill_resolves_against_live_not_the_passed_registry() {
        // Skip only when this process has no bundled `.rs` grammar at all —
        // then even the correct behaviour cannot produce a handle, so an empty
        // result would be a false negative rather than the regression.
        let Ok(live) = lattice_syntax::registry::live() else {
            eprintln!("skipping: no live language registry in this process");
            return;
        };
        if !matches!(
            Syntax::for_language_with_registry(Lang::Rust, live.clone()),
            Ok(Some(_))
        ) {
            eprintln!("skipping: no .rs grammar registered in this process");
            return;
        }

        let unique = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let path = std::env::temp_dir().join(format!("lattice-mb-backfill-{unique}.rs"));
        let text = "fn main() { let x = 1; }\n";
        std::fs::write(&path, text).unwrap();

        let id = BufferId::next();
        let doc = lattice_core::DocumentBuilder::default()
            .with_text(text)
            .with_path(path.clone())
            .build();
        let source: Arc<dyn Document> = Arc::new(spawn_document(id, doc, empty_registry()));
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(id, source);
        let excerpts = vec![Excerpt::new(id, 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // The boot-snapshot analogue: a registry that contains NO grammars.
        // Pre-fix, this is what `.rs` would (fail to) resolve against.
        let empty_snapshot = Arc::new(LangRegistry::default());
        mb.set_lang_registry(empty_snapshot);

        assert!(
            !mb.excerpt_highlights().is_empty(),
            "the back-fill must resolve grammars against the LIVE registry, not \
             the (here empty) snapshot it was handed; an empty result means \
             *problems* / references excerpts paint uncoloured while search does not"
        );

        let _ = std::fs::remove_file(&path);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m4_source_close_publishes_typed_event_and_prunes() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<MultibufferSourceClosed>();
        bus.subscribe_typed::<MultibufferSourceClosed>(tx);

        let (sources, ids) = make_sources(&["a\n", "b\n"]);
        let source_a_handle = sources.get(&ids[0]).unwrap().clone();
        let excerpts = vec![Excerpt::new(ids[0], 0, 0), Excerpt::new(ids[1], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let view_id = mb.buffer_id();
        mb.attach_event_subscriptions(&bus);
        assert_eq!(mb.source_buffer_ids().len(), 2);

        // Publish DocumentClosed for source A.
        bus.publish(lattice_protocol::Event::DocumentClosed {
            id: source_a_handle.id(),
        });

        let evt = tokio::time::timeout(std::time::Duration::from_millis(200), rx.recv())
            .await
            .expect("event should arrive")
            .expect("channel open");
        assert_eq!(evt.view, view_id);
        assert_eq!(evt.source, ids[0]);

        // Source A pruned from the map.
        for _ in 0..10 {
            tokio::task::yield_now().await;
            if mb.source_buffer_ids().len() == 1 {
                break;
            }
        }
        assert_eq!(mb.source_buffer_ids(), vec![ids[1]]);
    }

    // ─────────────────────────────────────────────────────────────
    // M.4.1 tests — anchor sliding
    // ─────────────────────────────────────────────────────────────

    fn applied_edit(
        old_start: (u32, u32),
        old_end: (u32, u32),
        new_end: (u32, u32),
        replaced: &str,
        inserted: &str,
    ) -> lattice_protocol::event::AppliedEdit {
        use lattice_protocol::position::Range;
        lattice_protocol::event::AppliedEdit {
            original_range: Range::new(
                Position::new(old_start.0, old_start.1),
                Position::new(old_end.0, old_end.1),
            ),
            inserted_range: Range::new(
                Position::new(old_start.0, old_start.1),
                Position::new(new_end.0, new_end.1),
            ),
            replaced_text: replaced.into(),
            inserted_text: inserted.into(),
        }
    }

    async fn pump_forwarder() {
        for _ in 0..30 {
            tokio::time::sleep(std::time::Duration::from_millis(5)).await;
        }
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m41_insert_above_excerpt_slides_down() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (sources, ids) = make_sources(&["aa\nbb\ncc\ndd\nee\n"]);
        let src = sources.get(&ids[0]).unwrap().clone();
        // Excerpt covers source rows 2-3 (cc, dd).
        let excerpts = vec![Excerpt::new(ids[0], 2, 3)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);

        // Synthesise: edit at line 0 byte 0 → line 0 byte 0
        // inserts 2 lines of content (row_delta = +2).
        // original_range end = (0, 0); inserted_range end = (2, 0).
        let edit = applied_edit((0, 0), (0, 0), (2, 0), "", "X\nY\n");
        bus.publish(lattice_protocol::Event::DocumentChanged {
            id: src.id(),
            path: None,
            version: 1,
            edits: vec![edit],
        });

        pump_forwarder().await;
        let excerpts_after = mb.excerpts();
        assert_eq!(
            excerpts_after[0].start_line, 4,
            "excerpt should slide to row 4"
        );
        assert_eq!(excerpts_after[0].end_line, 5);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m41_delete_above_excerpt_slides_up() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (sources, ids) = make_sources(&["aa\nbb\ncc\ndd\nee\nff\n"]);
        let src = sources.get(&ids[0]).unwrap().clone();
        // Excerpt covers rows 4-5 (ee, ff).
        let excerpts = vec![Excerpt::new(ids[0], 4, 5)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);

        // Delete rows 0-1 (aa\nbb\n). original_range end = (2, 0);
        // inserted_range end = (0, 0). row_delta = -2.
        let edit = applied_edit((0, 0), (2, 0), (0, 0), "aa\nbb\n", "");
        bus.publish(lattice_protocol::Event::DocumentChanged {
            id: src.id(),
            path: None,
            version: 1,
            edits: vec![edit],
        });

        pump_forwarder().await;
        let excerpts_after = mb.excerpts();
        assert_eq!(
            excerpts_after[0].start_line, 2,
            "excerpt should slide up to row 2"
        );
        assert_eq!(excerpts_after[0].end_line, 3);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m41_edit_below_excerpt_does_not_slide() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (sources, ids) = make_sources(&["aa\nbb\ncc\ndd\nee\n"]);
        let src = sources.get(&ids[0]).unwrap().clone();
        let excerpts = vec![Excerpt::new(ids[0], 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);

        // Edit at row 3: original_range end = (3, 0).
        // excerpt.start_line = 0; condition is `old_end < start_line`
        // → `3 < 0` false → no slide.
        let edit = applied_edit((3, 0), (3, 0), (4, 0), "", "X\n");
        bus.publish(lattice_protocol::Event::DocumentChanged {
            id: src.id(),
            path: None,
            version: 1,
            edits: vec![edit],
        });

        pump_forwarder().await;
        let excerpts_after = mb.excerpts();
        assert_eq!(excerpts_after[0].start_line, 0);
        assert_eq!(excerpts_after[0].end_line, 1);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m41_overlapping_edit_does_not_slide_excerpt() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (sources, ids) = make_sources(&["aa\nbb\ncc\ndd\n"]);
        let src = sources.get(&ids[0]).unwrap().clone();
        // Excerpt covers rows 1-2.
        let excerpts = vec![Excerpt::new(ids[0], 1, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);

        // Edit that ends inside the excerpt (rows 0..=1):
        // original_range end = (2, 0). `2 < 1` false → no slide.
        let edit = applied_edit((0, 0), (2, 0), (1, 0), "aa\nbb\n", "X\n");
        bus.publish(lattice_protocol::Event::DocumentChanged {
            id: src.id(),
            path: None,
            version: 1,
            edits: vec![edit],
        });

        pump_forwarder().await;
        // Conservative slide: excerpt stays put. Recompose
        // picks up new content for the now-overlapped rows.
        let excerpts_after = mb.excerpts();
        assert_eq!(excerpts_after[0].start_line, 1);
        assert_eq!(excerpts_after[0].end_line, 2);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m41_other_source_edits_dont_slide_this_source() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (sources, ids) = make_sources(&["aa\nbb\n", "11\n22\n"]);
        let src_b = sources.get(&ids[1]).unwrap().clone();
        // Excerpt of source A at rows 0-1; source B has its own.
        let excerpts = vec![Excerpt::new(ids[0], 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);

        // Insert 5 rows in source B above row 0. Should NOT
        // slide source A's excerpt.
        let edit = applied_edit((0, 0), (0, 0), (5, 0), "", "x\nx\nx\nx\nx\n");
        bus.publish(lattice_protocol::Event::DocumentChanged {
            id: src_b.id(),
            path: None,
            version: 1,
            edits: vec![edit],
        });

        pump_forwarder().await;
        let excerpts_after = mb.excerpts();
        assert_eq!(excerpts_after[0].start_line, 0);
        assert_eq!(excerpts_after[0].end_line, 1);
    }

    // ─────────────────────────────────────────────────────────────
    // M.5 tests — expand-context
    // ─────────────────────────────────────────────────────────────

    #[tokio::test(flavor = "multi_thread")]
    async fn m5_expand_grows_symmetrically() {
        // Source has 10 rows (line 0..9); excerpt covers rows 4-5.
        let mut text = String::new();
        for i in 0..10 {
            text.push_str(&format!("L{i}\n"));
        }
        let (sources, ids) = make_sources(&[&text]);
        let excerpts = vec![Excerpt::new(ids[0], 4, 5)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Cursor on composed row 0 (= source row 4). Expand by 4
        // rows: 2 above + 2 below → new range 2..7.
        mb.expand_excerpt_at(0, 4);
        let excerpts = mb.excerpts();
        assert_eq!(excerpts[0].start_line, 2);
        assert_eq!(excerpts[0].end_line, 7);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m5_expand_clips_to_source_start() {
        // Excerpt at rows 1-2; expand by 6 should clip top to 0.
        let mut text = String::new();
        for i in 0..10 {
            text.push_str(&format!("L{i}\n"));
        }
        let (sources, ids) = make_sources(&[&text]);
        let excerpts = vec![Excerpt::new(ids[0], 1, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // delta=6 → above=3, below=3. start = 1-3 = -2 → clipped to 0.
        // end = 2+3 = 5.
        mb.expand_excerpt_at(0, 6);
        let excerpts = mb.excerpts();
        assert_eq!(excerpts[0].start_line, 0);
        assert_eq!(excerpts[0].end_line, 5);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m5_expand_clips_to_source_end() {
        // Source text "L0\n...L9\n" has 10 content lines, plus the
        // phantom row ropey reports after the terminating newline.
        // CV.3 clips expansion in CONTENT space, so the last row an
        // excerpt may reach is index 9 — the phantom row is not a line
        // the source has, and an excerpt ending on it would render a
        // blank tail row that is not in the file.
        let mut text = String::new();
        for i in 0..10 {
            text.push_str(&format!("L{i}\n"));
        }
        let (sources, ids) = make_sources(&[&text]);
        let excerpts = vec![Excerpt::new(ids[0], 7, 8)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // delta=6 → above=3, below=3. start = 7-3 = 4.
        // end = 8+3 = 11 → clipped to content_line_count - 1 = 9.
        mb.expand_excerpt_at(0, 6);
        let excerpts = mb.excerpts();
        assert_eq!(excerpts[0].start_line, 4);
        assert_eq!(excerpts[0].end_line, 9);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m5_contract_shrinks_symmetrically() {
        let mut text = String::new();
        for i in 0..20 {
            text.push_str(&format!("L{i}\n"));
        }
        let (sources, ids) = make_sources(&[&text]);
        // Excerpt at rows 5-15 (11 rows).
        let excerpts = vec![Excerpt::new(ids[0], 5, 15)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // delta=-4 → above=-2, below=-2. start = 5+2 = 7. end = 15-2 = 13.
        mb.expand_excerpt_at(0, -4);
        let excerpts = mb.excerpts();
        assert_eq!(excerpts[0].start_line, 7);
        assert_eq!(excerpts[0].end_line, 13);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m5_contract_below_one_row_is_noop() {
        let (sources, ids) = make_sources(&["a\nb\n"]);
        // Excerpt at rows 0-0 (single row).
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        // Contract by 4 → new start = 2, new end = -2 (clipped to 0).
        // 0 > 2 inverted → no-op.
        mb.expand_excerpt_at(0, -4);
        let excerpts = mb.excerpts();
        assert_eq!(excerpts[0].start_line, 0);
        assert_eq!(excerpts[0].end_line, 0);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m5_zero_delta_is_noop() {
        let (sources, ids) = make_sources(&["a\nb\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.expand_excerpt_at(0, 0);
        let excerpts = mb.excerpts();
        assert_eq!(excerpts[0].start_line, 0);
        assert_eq!(excerpts[0].end_line, 1);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m5_no_excerpt_at_cursor_is_noop() {
        let (sources, ids) = make_sources(&["a\nb\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        // Cursor at composed row 50 — well past the single excerpt.
        mb.expand_excerpt_at(50, 4);
        let excerpts = mb.excerpts();
        assert_eq!(excerpts[0].start_line, 0);
        assert_eq!(excerpts[0].end_line, 0);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m5_expand_then_recompose_reflects_new_content() {
        let mut text = String::new();
        for i in 0..10 {
            text.push_str(&format!("L{i}\n"));
        }
        let (sources, ids) = make_sources(&[&text]);
        let excerpts = vec![Excerpt::new(ids[0], 4, 5)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        assert_eq!(mb.snapshot().buffer.as_string(), "L4\nL5\n");

        mb.expand_excerpt_at(0, 4);
        // After expand_excerpt_at recomposes, the snapshot
        // should already reflect the new rows.
        assert_eq!(mb.snapshot().buffer.as_string(), "L2\nL3\nL4\nL5\nL6\nL7\n");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn m4_attach_is_idempotent() {
        let bus = Arc::new(lattice_runtime::EventBus::new());
        let (sources, ids) = make_sources(&["x\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        mb.attach_event_subscriptions(&bus);
        // Second call returns immediately; no second subscription
        // ID is recorded (verifiable via the unique-ID set count
        // staying at 1, but our internal bookkeeping isn't
        // public — instead we verify no panic + behaviour stays
        // correct).
        mb.attach_event_subscriptions(&bus);
        mb.set_headerline(HeaderlineStatus::Complete {
            summary: "x".into(),
            emphasis: None,
        });
    }

    /// M.11 (2026-06-02): undo operates on the LOCAL composed_doc,
    /// not via fan-out to source actors. The composed_doc has its
    /// own undo stack populated by `apply_edit`; `undo()` pops
    /// the most recent entry and applies its inverse. Sources
    /// are NOT reverted (they retain their forwarded edits) —
    /// richer multi-source transaction tracking is a future
    /// slice. Replaces the pre-M.11 `m3_undo_fans_out_to_each_source`
    /// test whose semantics no longer apply.
    #[tokio::test(flavor = "multi_thread")]
    async fn m11_undo_reverses_local_composed_doc_edit() {
        let (sources, ids) = make_sources(&["aaa\nbbb\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let pre_text = mb.snapshot().buffer.as_string();
        assert_eq!(pre_text, "aaa\nbbb\n");

        // Apply an edit via the multibuffer (lands in composed_doc).
        mb.apply_edit(Edit::insert(Position::new(0, 3), "X"))
            .await
            .expect("insert ok");
        assert_eq!(mb.snapshot().buffer.as_string(), "aaaX\nbbb\n");

        // Undo reverses on composed_doc — synchronous, no
        // Pending::spawn deadlock (the user-reported freeze on
        // `u` after an insert was the pre-M.11 fan-out path).
        let applied = mb.undo().await.expect("undo ok");
        assert!(
            !applied.is_empty(),
            "undo should return the inverse edits applied to composed_doc"
        );
        assert_eq!(
            mb.snapshot().buffer.as_string(),
            "aaa\nbbb\n",
            "composed_doc must roll back to pre-edit state"
        );

        // Redo replays the insert.
        let _ = mb.redo().await.expect("redo ok");
        assert_eq!(mb.snapshot().buffer.as_string(), "aaaX\nbbb\n");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn empty_excerpts_is_valid_for_async_providers() {
        // M.2.b.2 (2026-06-01): empty inputs are valid. Async
        // providers open an empty view and stream excerpts in
        // as their scan progresses.
        let mb = MultibufferDocumentHandle::empty(empty_registry());
        assert_eq!(mb.excerpt_count(), 0);
        assert_eq!(mb.snapshot().buffer.as_string(), "");
        let (sources, _ids) = make_sources(&["x"]);
        let mb = MultibufferDocumentHandle::new(sources, Vec::new(), empty_registry()).unwrap();
        assert_eq!(mb.excerpt_count(), 0);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn append_excerpts_extends_the_view() {
        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        let mb =
            MultibufferDocumentHandle::new(sources.clone(), Vec::new(), empty_registry()).unwrap();
        assert_eq!(mb.excerpt_count(), 0);

        mb.append_excerpts(vec![Excerpt::new(ids[0], 0, 0)]);
        assert_eq!(mb.excerpt_count(), 1);
        assert_eq!(mb.snapshot().buffer.as_string(), "alpha\n");

        mb.append_excerpts(vec![Excerpt::new(ids[0], 2, 2)]);
        assert_eq!(mb.excerpt_count(), 2);
        assert_eq!(mb.snapshot().buffer.as_string(), "alpha\ngamma\n");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn append_excerpts_drops_unknown_source_silently() {
        let (sources, ids) = make_sources(&["alpha\nbeta\n"]);
        let mb = MultibufferDocumentHandle::new(sources, Vec::new(), empty_registry()).unwrap();
        let bogus = BufferId(0xDEAD_BEEF);
        mb.append_excerpts(vec![Excerpt::new(ids[0], 0, 0), Excerpt::new(bogus, 0, 0)]);
        assert_eq!(
            mb.excerpt_count(),
            1,
            "unknown-source excerpt should be silently dropped",
        );
    }

    // MH.B2 (2026-06-19): the correctness gate for the incremental
    // `append_excerpts`. Build one view by streaming the excerpt
    // list in N batches; build a second view with the identical
    // full excerpt list in ONE shot. The composed rope TEXT and
    // the row-translation entries MUST be identical between the
    // two — this proves incremental append == full build, both for
    // the rope (insert-at-end == from_text(old + batch)) and for
    // the translation (concatenation == build-from-all).
    #[tokio::test(flavor = "multi_thread")]
    async fn incremental_append_matches_full_build() {
        // Six sources, each multi-line, so each batch contributes
        // several composed rows.
        let texts = [
            "a1\na2\na3\n",
            "b1\nb2\nb3\n",
            "c1\nc2\nc3\n",
            "d1\nd2\nd3\n",
            "e1\ne2\ne3\n",
            "f1\nf2\nf3\n",
        ];
        let (sources, ids) = make_sources(&texts);

        // The full excerpt list, varied start/end so spans differ.
        let all_excerpts = vec![
            Excerpt::new(ids[0], 0, 1),
            Excerpt::new(ids[1], 1, 2),
            Excerpt::new(ids[2], 0, 2),
            Excerpt::new(ids[3], 2, 2),
            Excerpt::new(ids[4], 0, 0),
            Excerpt::new(ids[5], 1, 2),
        ];

        // INCREMENTAL: empty view, stream in 3 batches of 2.
        let incremental =
            MultibufferDocumentHandle::new(sources.clone(), Vec::new(), empty_registry()).unwrap();
        for batch in all_excerpts.chunks(2) {
            incremental.append_excerpts(batch.to_vec());
        }

        // FULL: same source map + the entire excerpt list at once,
        // via the constructor's full build.
        let full = MultibufferDocumentHandle::new(sources, all_excerpts.clone(), empty_registry())
            .unwrap();

        // (a) composed rope text byte-identical.
        assert_eq!(
            incremental.snapshot().buffer.as_string(),
            full.snapshot().buffer.as_string(),
            "incremental append must produce a byte-identical composed rope",
        );

        // (b) row_translation entries identical (same Vec<RowEntry>),
        // modulo the ExcerptId values — the two views allocate
        // distinct ExcerptIds, so compare structurally on
        // (source_row) ordering within the same shape. We assert
        // the entry COUNT and source_row sequence match; the
        // excerpt_id mapping is per-view by construction.
        let inc_entries = incremental.row_translation().entries.clone();
        let full_entries = full.row_translation().entries.clone();
        assert_eq!(
            inc_entries.len(),
            full_entries.len(),
            "row translation length must match the full build",
        );
        let inc_rows: Vec<u32> = inc_entries
            .iter()
            .map(|RowEntry::Excerpt { source_row, .. }| *source_row)
            .collect();
        let full_rows: Vec<u32> = full_entries
            .iter()
            .map(|RowEntry::Excerpt { source_row, .. }| *source_row)
            .collect();
        assert_eq!(
            inc_rows, full_rows,
            "row translation source_row sequence must match the full build",
        );
    }

    // MH.B2 (2026-06-19): edge case — a batch containing an excerpt
    // whose source was never added is dropped identically by both
    // the incremental and full paths, leaving the composed text +
    // translation in lock-step.
    #[tokio::test(flavor = "multi_thread")]
    async fn incremental_append_skips_unknown_source_like_full_build() {
        let (sources, ids) = make_sources(&["a1\na2\n", "b1\nb2\n"]);
        let bogus = BufferId(0x0BAD_C0DE);

        let valid = vec![Excerpt::new(ids[0], 0, 0), Excerpt::new(ids[1], 1, 1)];

        // INCREMENTAL: stream one valid excerpt, then a batch that
        // mixes a valid + a bogus-source excerpt (bogus dropped).
        let incremental =
            MultibufferDocumentHandle::new(sources.clone(), Vec::new(), empty_registry()).unwrap();
        incremental.append_excerpts(vec![valid[0].clone()]);
        incremental.append_excerpts(vec![Excerpt::new(bogus, 0, 0), valid[1].clone()]);

        // FULL: only the two valid excerpts (the constructor would
        // reject an unknown source, so the full build's coherent
        // input is the valid set — the same set the incremental
        // path retains after dropping the bogus excerpt).
        let full =
            MultibufferDocumentHandle::new(sources, valid.clone(), empty_registry()).unwrap();

        assert_eq!(incremental.excerpt_count(), 2);
        assert_eq!(
            incremental.snapshot().buffer.as_string(),
            full.snapshot().buffer.as_string(),
            "dropping an unknown-source excerpt must leave the rope identical to the full build",
        );
        assert_eq!(
            incremental.row_translation().entries.len(),
            full.row_translation().entries.len(),
        );
    }

    // MH.B2 (2026-06-19): structural pin on the O(batch) guarantee.
    // Appending a 1-excerpt batch (covering R source rows) to an
    // N-excerpt view must grow the row translation by EXACTLY R
    // entries and grow the composed rope by EXACTLY the batch
    // text's byte length — i.e. no full recompute. Together with
    // `incremental_append_matches_full_build` this pins both the
    // correctness AND the incremental nature of `append_excerpts`.
    #[tokio::test(flavor = "multi_thread")]
    async fn append_excerpts_grows_by_exactly_the_batch() {
        let (sources, ids) = make_sources(&["l0\nl1\nl2\nl3\nl4\n"]);
        let mb = MultibufferDocumentHandle::new(sources, Vec::new(), empty_registry()).unwrap();

        // Seed with a 2-row excerpt.
        mb.append_excerpts(vec![Excerpt::new(ids[0], 0, 1)]);
        let rows_before = mb.row_translation().entries.len();
        let bytes_before = mb.snapshot().buffer.byte_len();
        assert_eq!(rows_before, 2);

        // Append a 3-row excerpt (rows 2..=4 → "l2\nl3\nl4\n" = 9 bytes).
        mb.append_excerpts(vec![Excerpt::new(ids[0], 2, 4)]);
        let rows_after = mb.row_translation().entries.len();
        let bytes_after = mb.snapshot().buffer.byte_len();

        assert_eq!(
            rows_after - rows_before,
            3,
            "translation must grow by exactly the batch's source-row count (O(batch))",
        );
        assert_eq!(
            bytes_after - bytes_before,
            "l2\nl3\nl4\n".len() as u64,
            "composed rope must grow by exactly the batch text length (insert-at-end, no recompute)",
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn replace_excerpts_swaps_atomically() {
        let (sources_a, ids_a) = make_sources(&["a-1\na-2\n"]);
        let excerpts_a = vec![Excerpt::new(ids_a[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources_a, excerpts_a, empty_registry()).unwrap();
        assert_eq!(mb.snapshot().buffer.as_string(), "a-1\n");

        let (sources_b, ids_b) = make_sources(&["b-1\nb-2\n"]);
        let excerpts_b = vec![Excerpt::new(ids_b[0], 1, 1)];
        mb.replace_excerpts(sources_b, excerpts_b);
        assert_eq!(mb.snapshot().buffer.as_string(), "b-2\n");
        assert_eq!(mb.excerpt_count(), 1);
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn unknown_source_returns_error() {
        let (sources, _ids) = make_sources(&["x"]);
        let bogus = BufferId(99_999);
        let excerpts = vec![Excerpt::new(bogus, 0, 0)];
        let err = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap_err();
        assert!(matches!(
            err,
            MultibufferError::UnknownSource { source_buffer, .. } if source_buffer == bogus
        ));
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn dispatches_via_dyn_document() {
        let (sources, ids) = make_sources(&["foo\nbar\nbaz\n"]);
        let excerpts = vec![Excerpt::new(ids[0], 0, 1)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();

        let dyn_doc: Arc<dyn Document> = Arc::new(mb);
        assert_eq!(dyn_doc.text(), "foo\nbar\n");
        assert!(!dyn_doc.dirty());
        // M.3 (2026-06-01): apply_edit now translates and
        // forwards rather than returning ReadOnly.
        let applied = dyn_doc
            .apply_edit(Edit::insert(Position::ZERO, "x"))
            .await
            .expect("apply_edit should propagate");
        assert_eq!(applied.inserted_text, "x");
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn source_edit_propagates_after_recompose() {
        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        let source_handle = sources.get(&ids[0]).expect("source present").clone();
        let excerpts = vec![Excerpt::new(ids[0], 0, 2)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        assert_eq!(mb.snapshot().text(), "alpha\nbeta\ngamma\n");

        source_handle
            .apply_edit(Edit::insert(Position::new(1, 0), "BB-"))
            .await
            .unwrap();
        assert_eq!(mb.snapshot().text(), "alpha\nbeta\ngamma\n");
        mb.recompose();
        assert_eq!(mb.snapshot().text(), "alpha\nBB-beta\ngamma\n");
    }

    // ─────────────────────────────────────────────────────────────
    // Header provider tests (moved from `lattice-host::multibuffer`)
    // ─────────────────────────────────────────────────────────────

    #[test]
    fn header_rows_dedupe_consecutive_same_source() {
        // K.4.6 follow-up (2026-06-02): three excerpts sharing
        // the same source BufferId emit ONE header row (anchored
        // at the first excerpt's composed start). The remaining
        // two excerpts advance the composed cursor without
        // emitting headers. Closes the "1 header per file" UX
        // for grep-style search results.
        let mb_source = BufferId::next();
        let excerpts = vec![
            Excerpt::new(mb_source, 0, 2).with_header(ExcerptHeader::new("a")),
            Excerpt::new(mb_source, 0, 1).with_header(ExcerptHeader::new("b")),
            Excerpt::new(mb_source, 0, 0).with_header(ExcerptHeader::new("c")),
        ];
        let rows = compose_header_rows(&excerpts, FoldGrouping::SourceFile, |_| {
            Arc::from(Vec::<Cell>::new())
        });

        assert_eq!(
            rows.len(),
            1,
            "consecutive same-source excerpts dedup to one header"
        );
        assert_eq!(rows[0].anchor_line, 0);
        assert_eq!(rows[0].position, AnchorPosition::Above);
        assert_eq!(rows[0].height, 1);
        assert_eq!(rows[0].kind, VirtualRowKind::Generic);
    }

    #[test]
    fn header_rows_distinct_sources_each_emit_header() {
        // K.4.6 follow-up (2026-06-02): excerpts with distinct
        // source BufferIds each emit their own header at the
        // correct composed offset. Three sources → three headers
        // at 0, 3, 5. Mirrors the production scenario where
        // search-provider clusters from three different files
        // appear in the composed view.
        let src_a = BufferId::next();
        let src_b = BufferId::next();
        let src_c = BufferId::next();
        let excerpts = vec![
            Excerpt::new(src_a, 0, 2).with_header(ExcerptHeader::new("a")),
            Excerpt::new(src_b, 0, 1).with_header(ExcerptHeader::new("b")),
            Excerpt::new(src_c, 0, 0).with_header(ExcerptHeader::new("c")),
        ];
        let rows = compose_header_rows(&excerpts, FoldGrouping::SourceFile, |_| {
            Arc::from(Vec::<Cell>::new())
        });

        assert_eq!(rows.len(), 3);
        assert_eq!(rows[0].anchor_line, 0);
        assert_eq!(rows[1].anchor_line, 3);
        assert_eq!(rows[2].anchor_line, 5);
        for row in &rows {
            assert_eq!(row.position, AnchorPosition::Above);
            assert_eq!(row.height, 1);
            assert_eq!(row.kind, VirtualRowKind::Generic);
        }
    }

    #[test]
    fn header_rows_interleaved_sources_each_get_header() {
        // K.4.6 follow-up (2026-06-02): when the same source
        // re-appears after a different source, it gets its own
        // header (the dedup is on *consecutive* same-source, not
        // on "has this source ever been seen"). Models a
        // pathological search ordering where hits from file A
        // and file B are interleaved.
        let src_a = BufferId::next();
        let src_b = BufferId::next();
        let excerpts = vec![
            Excerpt::new(src_a, 0, 0).with_header(ExcerptHeader::new("a")),
            Excerpt::new(src_b, 0, 0).with_header(ExcerptHeader::new("b")),
            Excerpt::new(src_a, 1, 1).with_header(ExcerptHeader::new("a-again")),
        ];
        let rows = compose_header_rows(&excerpts, FoldGrouping::SourceFile, |_| {
            Arc::from(Vec::<Cell>::new())
        });

        assert_eq!(
            rows.len(),
            3,
            "non-consecutive same source still emits its own header"
        );
    }

    /// The agenda's grouping contract vs. what the substrate does.
    ///
    /// `providers/agenda.rs::build_excerpts` gives the FIRST row of a
    /// date group the label and every later row `String::new()`, on the
    /// documented assumption that "an empty `ExcerptHeader.title`
    /// renders no header row". The dedup is on `excerpt.source`, not on
    /// the title — and a date group interleaves files by design — so
    /// each file change inside one group emits another header, and an
    /// empty title with no path renders `[untitled]`.
    /// The other half of the title-run rule, and why one rule serves both
    /// header conventions: search titles every excerpt of a file with the
    /// same path, so equal titles must CONTINUE a group rather than start one.
    /// If they did not, `HeaderRuns` would be agenda-only.
    /// OA.7: the split that dims a header's trailing annotation. Pure, so the
    /// nesting and the refusals are pinned without rendering anything.
    #[test]
    fn a_trailing_parenthetical_splits_off_as_annotation() {
        let cases: &[(&str, &str, &str)] = &[
            // The agenda's three label shapes.
            ("2026-09-01 Mon (today)", "2026-09-01 Mon", " (today)"),
            (
                "2026-08-30 Sat (overdue by 2 day(s))",
                "2026-08-30 Sat",
                " (overdue by 2 day(s))",
            ),
            (
                "2026-09-04 Fri (in 3 day(s))",
                "2026-09-04 Fri",
                " (in 3 day(s))",
            ),
            // No parenthetical: unchanged, byte for byte.
            ("Unscheduled", "Unscheduled", ""),
            ("src/lib.rs", "src/lib.rs", ""),
            // A parenthetical with no name in front is the whole title, not
            // an annotation on nothing.
            ("(today)", "(today)", ""),
            // Unbalanced: left alone rather than guessed at.
            ("Overdue )", "Overdue )", ""),
            ("Overdue (", "Overdue (", ""),
        ];
        for (input, name, note) in cases {
            assert_eq!(
                split_trailing_parenthetical(input),
                (*name, *note),
                "on {input:?}"
            );
        }
    }

    /// The two halves must reconstruct the input exactly — dimming is the only
    /// difference, so a header can never lose text to this.
    #[test]
    fn the_split_halves_reconstruct_the_title() {
        for title in [
            "2026-09-01 Mon (today)",
            "Unscheduled",
            "(today)",
            "a (b) c (d)",
            "café (naïve)",
        ] {
            let (name, note) = split_trailing_parenthetical(title);
            assert_eq!(format!("{name}{note}"), title, "on {title:?}");
        }
    }

    #[test]
    fn header_runs_continue_across_equal_titles() {
        let a = BufferId::next();
        let b = BufferId::next();
        let excerpts = vec![
            Excerpt::new(a, 0, 0).with_header(ExcerptHeader::new("src/lib.rs")),
            Excerpt::new(a, 9, 9).with_header(ExcerptHeader::new("src/lib.rs")),
            Excerpt::new(b, 3, 3).with_header(ExcerptHeader::new("src/main.rs")),
        ];
        let rows = compose_header_rows(&excerpts, FoldGrouping::HeaderRuns, |e| {
            header_cells(&e.header, false, 0, 0, 0)
        });
        assert_eq!(rows.len(), 2, "one header per title run");
        assert_eq!(rows[0].anchor_line, 0);
        assert_eq!(rows[1].anchor_line, 2);
    }

    /// A leading empty title emits nothing rather than `[untitled]`. A header
    /// with no text is not a header, and this is the shape that produced the
    /// bug — it must not merely be rarer now.
    #[test]
    fn header_runs_never_emit_an_untitled_row() {
        let a = BufferId::next();
        let excerpts = vec![
            Excerpt::new(a, 0, 0).with_header(ExcerptHeader::new("")),
            Excerpt::new(a, 1, 1).with_header(ExcerptHeader::new("")),
        ];
        let rows = compose_header_rows(&excerpts, FoldGrouping::HeaderRuns, |e| {
            header_cells(&e.header, false, 0, 0, 0)
        });
        assert!(rows.is_empty(), "got {} header row(s)", rows.len());
    }

    #[test]
    fn agenda_group_of_interleaved_files_emits_one_header_not_untitled_rows() {
        let todo = BufferId::next();
        let plans = BufferId::next();
        // One date group, three rows, drawn from two files in sort order.
        let excerpts = vec![
            Excerpt::new(todo, 0, 0).with_header(ExcerptHeader::new("2026-08-31 Mon (today)")),
            Excerpt::new(plans, 4, 4).with_header(ExcerptHeader::new("")),
            Excerpt::new(todo, 9, 9).with_header(ExcerptHeader::new("")),
        ];
        let rows = compose_header_rows(&excerpts, FoldGrouping::HeaderRuns, |e| {
            header_cells(&e.header, false, 0, 0, 0)
        });
        let text = |r: &VirtualRow| {
            r.cells
                .iter()
                .filter_map(|c| char::from_u32(c.codepoint))
                .collect::<String>()
        };

        assert_eq!(
            rows.len(),
            1,
            "one date group renders one header; got {:?}",
            rows.iter().map(text).collect::<Vec<_>>()
        );
        assert_eq!(text(&rows[0]), "2026-08-31 Mon (today)");
    }

    #[test]
    fn default_header_paints_box_rules_around_title() {
        let mb_source = BufferId::next();
        let with_title = Excerpt::new(mb_source, 0, 0).with_header(ExcerptHeader::new("hi"));
        let cells = default_header_cells(&with_title);
        assert_eq!(cells.len(), 8);
        assert_eq!(cells[0].codepoint, '─' as u32);
        assert_eq!(cells[3].codepoint, 'h' as u32);
        assert_eq!(cells[4].codepoint, 'i' as u32);

        let without_title = Excerpt::new(mb_source, 0, 0);
        let cells = default_header_cells(&without_title);
        assert_eq!(cells.len(), 4);
        for cell in cells.iter() {
            assert_eq!(cell.codepoint, '─' as u32);
        }
    }

    // ── MH.A3 / MH.A5: rich per-segment header_cells ────────────

    /// Collect the codepoints of every cell carrying `fg` into a String.
    fn cells_with_fg(cells: &[Cell], fg: u32) -> String {
        cells
            .iter()
            .filter(|c| c.fg == fg)
            .filter_map(|c| char::from_u32(c.codepoint))
            .collect()
    }

    fn cells_to_string(cells: &[Cell]) -> String {
        cells
            .iter()
            .filter_map(|c| char::from_u32(c.codepoint))
            .collect()
    }

    #[test]
    fn header_cells_with_path_splits_basename_and_dir() {
        // header_fg=0xAA, path_fg=0xBB, count_fg=0xCC (distinct).
        let header = ExcerptHeader {
            path: Some(std::path::PathBuf::from("src/multibuffer/view.rs")),
            ..ExcerptHeader::new("fallback-title")
        };
        let cells = header_cells(&header, false, 0xAA, 0xBB, 0xCC);

        // First cell is the (BMP-fallback) file-type icon in header_fg.
        let expected_icon = lattice_core::ui::icons::glyph_for_entry(
            std::path::Path::new("src/multibuffer/view.rs"),
            false,
            false,
        );
        let first_icon_ch = expected_icon.chars().next().unwrap();
        assert_eq!(cells[0].codepoint, first_icon_ch as u32);
        assert_eq!(cells[0].fg, 0xAA, "icon carries header_fg");

        // Basename present in header_fg.
        let header_seg = cells_with_fg(&cells, 0xAA);
        assert!(
            header_seg.contains("view.rs"),
            "basename rendered in header_fg; got {header_seg:?}"
        );
        assert!(
            !header_seg.contains("src/multibuffer"),
            "dir must NOT be in header_fg; got {header_seg:?}"
        );

        // Directory path present in path_fg (dim).
        let path_seg = cells_with_fg(&cells, 0xBB);
        assert!(
            path_seg.contains("src/multibuffer"),
            "dir rendered in path_fg; got {path_seg:?}"
        );
    }

    #[test]
    fn header_cells_match_count_badge_in_count_fg() {
        let header = ExcerptHeader {
            path: Some(std::path::PathBuf::from("a/b.rs")),
            match_count: Some(3),
            ..ExcerptHeader::default()
        };
        let cells = header_cells(&header, false, 0xAA, 0xBB, 0xCC);
        let count_seg = cells_with_fg(&cells, 0xCC);
        assert!(
            count_seg.contains("3 matches"),
            "plural badge in count_fg; got {count_seg:?}"
        );

        // Singular form for n == 1.
        let header1 = ExcerptHeader {
            match_count: Some(1),
            ..header.clone()
        };
        let cells1 = header_cells(&header1, false, 0xAA, 0xBB, 0xCC);
        let count_seg1 = cells_with_fg(&cells1, 0xCC);
        assert!(
            count_seg1.contains("1 match") && !count_seg1.contains("matches"),
            "singular badge for n==1; got {count_seg1:?}"
        );
    }

    #[test]
    fn header_cells_nerd_vs_bmp_same_width_different_icon() {
        let header = ExcerptHeader {
            path: Some(std::path::PathBuf::from("src/lib.rs")),
            ..ExcerptHeader::default()
        };
        let bmp = header_cells(&header, false, 0xAA, 0xBB, 0xCC);
        let nerd = header_cells(&header, true, 0xAA, 0xBB, 0xCC);

        // Width parity: the icon helper emits a 2-cell glyph in both
        // palettes, so total cell count is identical.
        assert_eq!(
            bmp.len(),
            nerd.len(),
            "nerd vs BMP must occupy the same cell count (column geometry stable)"
        );

        // Different leading icon codepoint between palettes.
        let bmp_icon = lattice_core::ui::icons::glyph_for_entry(
            std::path::Path::new("src/lib.rs"),
            false,
            false,
        );
        let nerd_icon = lattice_core::ui::icons::glyph_for_entry(
            std::path::Path::new("src/lib.rs"),
            false,
            true,
        );
        // (Guard: only assert "different" if the helper actually
        // returns distinct glyphs for this extension — it does for
        // `.rs`, but keep the test honest about its premise.)
        assert_ne!(
            bmp_icon.chars().next(),
            nerd_icon.chars().next(),
            "nerd and BMP icon glyphs differ for .rs"
        );
        assert_eq!(bmp[0].codepoint, bmp_icon.chars().next().unwrap() as u32);
        assert_eq!(nerd[0].codepoint, nerd_icon.chars().next().unwrap() as u32);
    }

    #[test]
    fn header_cells_empty_title_no_path_falls_back() {
        let header = ExcerptHeader::default(); // empty title, no path
        let cells = header_cells(&header, false, 0xAA, 0xBB, 0xCC);
        let s = cells_to_string(&cells);
        assert_eq!(s, "[untitled]", "empty title + no path renders fallback");
        // Fallback rendered in header_fg.
        assert!(cells.iter().all(|c| c.fg == 0xAA));
    }

    #[test]
    fn header_cells_no_path_uses_title() {
        let header = ExcerptHeader::new("my synthetic title");
        let cells = header_cells(&header, false, 0xAA, 0xBB, 0xCC);
        let s = cells_to_string(&cells);
        assert_eq!(s, "my synthetic title");
        assert!(cells.iter().all(|c| c.fg == 0xAA));
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn provider_collects_one_row_per_distinct_source() {
        // K.4.6 follow-up (2026-06-02): two excerpts from the
        // same source dedup to ONE header — the search-provider
        // "1 header per file, N excerpts per file (one per
        // cluster)" UX.
        let (sources, ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        let excerpts = vec![
            Excerpt::new(ids[0], 0, 1).with_header(ExcerptHeader::new("first")),
            Excerpt::new(ids[0], 2, 2).with_header(ExcerptHeader::new("second")),
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let provider = MultibufferExcerptHeaderProvider::new(mb);
        let rows = provider.collect();

        assert_eq!(rows.len(), 1);
        assert_eq!(rows[0].anchor_line, 0);
    }

    #[test]
    fn provider_id_namespace_is_stable() {
        let buffer_id = BufferId(42);
        let id = multibuffer_excerpt_header_provider_id(buffer_id);
        assert_eq!(id & 0xFFFF_FFFF, 42);
        assert!(!(0xD1FF_0000_0000_0000..0xD200_0000_0000_0000).contains(&id));
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn provider_version_bumps_with_recompose() {
        let (sources, ids) = make_sources(&["alpha\nbeta\n"]);
        let source = sources.get(&ids[0]).unwrap().clone();
        let excerpts = vec![Excerpt::new(ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let provider = MultibufferExcerptHeaderProvider::new(mb.clone());

        let v_before = provider.version();
        source
            .apply_edit(Edit::insert(Position::ZERO, "X"))
            .await
            .unwrap();
        mb.recompose();
        let v_after = provider.version();
        assert!(
            v_after > v_before,
            "version must bump after recompose; before={v_before} after={v_after}"
        );
    }

    // ── T.7: mode-owned theme-element acid test ─────────────────

    #[tokio::test(flavor = "multi_thread")]
    async fn excerpt_header_elements_register_and_bake_into_virtual_row() {
        // T.7 acid test: the multibuffer mode registers its OWN theme
        // elements (`multibuffer.excerpt_header[.path|.count]`) and the
        // header provider resolves+bakes them into the header
        // VirtualRow's `bg`. No host `Theme` field, no renderer match
        // arm — the renderer paints `VirtualRow.bg` generically.
        use lattice_theme::{
            ElementName, ElementOwner, InMemoryThemeRegistry, ThemeRegistry, ThemeRegistryHandle,
            default_palette,
        };

        // A registry with the default palette (so `blue` / `overlay2`
        // palette keys resolve) but NO core builtins — proving the mode
        // is the sole registrant of these elements.
        let registry = Arc::new(InMemoryThemeRegistry::new(default_palette()));

        // The mode registers its elements (idempotent by name).
        let owner = ElementOwner::Mode(
            crate::MultibufferMode::mode_id()
                .as_str()
                .to_string()
                .into(),
        );
        let ids = crate::register_multibuffer_theme_elements(registry.as_ref(), owner);

        // 1) The element is registered + resolves to the neutral backdrop.
        let backdrop_name = ElementName::from(ELEM_EXCERPT_HEADER.to_string());
        let id = registry
            .id(&backdrop_name)
            .expect("multibuffer.excerpt_header registered after activation");
        assert_eq!(id, ids.backdrop);
        let resolved = registry.resolved();
        assert_eq!(
            resolved.get(id).bg,
            Some(Color::Rgb(0x31, 0x32, 0x44)),
            "excerpt_header backdrop resolves to the neutral surface tint, \
             NOT the diff-deletion red"
        );

        // 2) The built header VirtualRow carries the BAKED bg —
        //    `Some(0x313244)`, not `None` (which would fall through to
        //    the renderer's diff-deletion-block tint).
        let theme: ThemeRegistryHandle = registry.clone();
        let (sources, src_ids) = make_sources(&["alpha\nbeta\ngamma\n"]);
        // MH.A3: supply a `path` so the rich header renders the dir
        // segment in the resolved `.path` (blue) fg — the basename is
        // in `header_fg` (the backdrop element's `.fg`, unset here).
        let header = ExcerptHeader {
            path: Some(std::path::PathBuf::from("src/file.rs")),
            ..ExcerptHeader::new("file.rs")
        };
        let excerpts = vec![Excerpt::new(src_ids[0], 0, 1).with_header(header)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let provider = MultibufferExcerptHeaderProvider::with_theme(mb, theme, ids, false);
        let rows = provider.collect();
        assert_eq!(rows.len(), 1);
        assert_eq!(
            rows[0].bg,
            Some(0x0031_3244),
            "header VirtualRow.bg is the baked backdrop, not None"
        );
        assert_eq!(rows[0].kind, VirtualRowKind::Generic);
        // The dir-path cells carry the baked `blue` fg (0x89b4fa).
        assert!(
            rows[0].cells.iter().any(|c| c.fg == 0x0089_b4fa),
            "dir-path cells carry the resolved path fg (blue)"
        );
    }

    /// MH.A6: an emphasised header paints from its OWN elements, and its
    /// unemphasised neighbour is unchanged.
    ///
    /// Both rows in one `collect()` on purpose. The interesting failure is
    /// not "emphasis does nothing" — it is "emphasis leaked", a `collect()`
    /// that resolved the emphasis colours once and baked them into every
    /// header, which a single-row test cannot see.
    #[tokio::test(flavor = "multi_thread")]
    async fn an_emphasised_header_paints_from_its_own_elements() {
        use lattice_theme::{
            ElementOwner, InMemoryThemeRegistry, ThemeRegistryHandle, default_palette,
        };

        let registry = Arc::new(InMemoryThemeRegistry::new(default_palette()));
        let owner = ElementOwner::Mode(
            crate::MultibufferMode::mode_id()
                .as_str()
                .to_string()
                .into(),
        );
        let ids = crate::register_multibuffer_theme_elements(registry.as_ref(), owner);
        let theme: ThemeRegistryHandle = registry.clone();

        // Two sources so each excerpt starts its own header run.
        let (sources, src_ids) = make_sources(&["alpha\n", "beta\n"]);
        let plain = ExcerptHeader::new("Wednesday");
        let loud = ExcerptHeader {
            style: ExcerptHeaderStyle::Emphasis,
            ..ExcerptHeader::new("Tuesday (today)")
        };
        let excerpts = vec![
            Excerpt::new(src_ids[0], 0, 0).with_header(plain),
            Excerpt::new(src_ids[1], 0, 0).with_header(loud),
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let provider = MultibufferExcerptHeaderProvider::with_theme(mb, theme, ids, false);
        let rows = provider.collect();
        assert_eq!(rows.len(), 2, "one header per source: {rows:?}");

        // `mauve` from the default palette, baked.
        let emphasis_bg = rows[1].bg.expect("the emphasised row has a backdrop");
        let plain_bg = rows[0].bg.expect("so does the ordinary one");
        assert_ne!(
            emphasis_bg, plain_bg,
            "the emphasised header must not paint on the ordinary backdrop — \
             that is the whole of what 'prominent' buys"
        );
        assert_eq!(
            plain_bg, 0x0031_3244,
            "and the ordinary header is untouched by its loud neighbour"
        );

        // The title AND its trailing parenthetical take the emphasis fg. OA.7
        // dims `(today)` against the normal backdrop; dimming it here would
        // mute the half of the header that says why it is emphasised.
        let text_fg = 0x00cd_d6f4; // palette `text`
        let loud_title: String = rows[1]
            .cells
            .iter()
            .filter(|c| c.fg == text_fg)
            .filter_map(|c| char::from_u32(c.codepoint))
            .collect();
        assert_eq!(loud_title, "Tuesday (today)");
    }

    /// A colourscheme with no emphasis elements renders an emphasised header
    /// like an ordinary one — undistinguished, never invisible.
    ///
    /// The failure this forbids is a header whose backdrop resolves to `None`
    /// and falls through to the renderer's diff-deletion tint, which is the
    /// exact bug the `.emphasis` element's `or(header_bg)` fallback exists to
    /// prevent and which T.7 already paid for once.
    #[tokio::test(flavor = "multi_thread")]
    async fn emphasis_without_theme_elements_degrades_to_the_ordinary_header() {
        let (sources, src_ids) = make_sources(&["alpha\n"]);
        let loud = ExcerptHeader {
            style: ExcerptHeaderStyle::Emphasis,
            ..ExcerptHeader::new("Tuesday (today)")
        };
        let excerpts = vec![Excerpt::new(src_ids[0], 0, 0).with_header(loud)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        // No theme at all — every element id is INVALID.
        let provider = MultibufferExcerptHeaderProvider::new(mb);
        let rows = provider.collect();

        assert_eq!(rows.len(), 1);
        let text: String = rows[0]
            .cells
            .iter()
            .filter_map(|c| char::from_u32(c.codepoint))
            .collect();
        assert_eq!(
            text, "Tuesday (today)",
            "the header still says what it says"
        );
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn excerpt_header_provider_version_folds_theme_version() {
        // T.7 invalidation: a theme change bumps the provider version
        // (the worker's fingerprint axis), so `collect()` re-runs and
        // re-bakes — mirrors `MatrixVersion::theme = resolved().version()`.
        use lattice_theme::{
            ElementName, ElementOwner, InMemoryThemeRegistry, StyleSpec, ThemeRegistry,
            ThemeRegistryHandle, default_palette,
        };
        let registry = Arc::new(InMemoryThemeRegistry::new(default_palette()));
        let owner = ElementOwner::Mode(
            crate::MultibufferMode::mode_id()
                .as_str()
                .to_string()
                .into(),
        );
        let ids = crate::register_multibuffer_theme_elements(registry.as_ref(), owner);
        let theme: ThemeRegistryHandle = registry.clone();
        let (sources, src_ids) = make_sources(&["a\nb\n"]);
        let excerpts = vec![Excerpt::new(src_ids[0], 0, 0)];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, empty_registry()).unwrap();
        let provider = MultibufferExcerptHeaderProvider::with_theme(mb, theme, ids, false);

        // Force the table to resolve so the version is established.
        let _ = registry.resolved();
        let v_before = provider.version();
        // A `:set ui.*`-style override dirties the table → next
        // `resolved()` bumps the version.
        registry.set_override(
            ElementName::from(ELEM_EXCERPT_HEADER.to_string()),
            StyleSpec::new().bg(Color::Rgb(1, 2, 3)),
        );
        let v_after = provider.version();
        assert!(
            v_after > v_before,
            "theme change must bump provider version; before={v_before} after={v_after}"
        );
    }

    // ── M.6.5: MultibufferStatusProvider ────────────────────────

    #[test]
    fn status_provider_hidden_when_idle() {
        let mb = MultibufferDocumentHandle::empty(empty_registry());
        let provider = MultibufferStatusProvider::new(mb.clone()).into_provider(mb.buffer_id());
        // Idle → no sticky row
        assert!(provider.collect().is_empty());
    }

    #[test]
    fn status_provider_emits_sticky_row_when_in_progress() {
        let mb = MultibufferDocumentHandle::empty(empty_registry());
        mb.set_headerline(HeaderlineStatus::InProgress {
            label: "searching".into(),
            count: Some(3),
            emphasis: None,
        });
        let provider = MultibufferStatusProvider::new(mb.clone()).into_provider(mb.buffer_id());
        let rows = provider.collect();
        assert_eq!(rows.len(), 1);
        assert_eq!(rows[0].kind, VirtualRowKind::Sticky);
        assert_eq!(rows[0].anchor_line, 0);
        assert_eq!(rows[0].bg, None); // theme bg
    }

    #[test]
    fn status_provider_version_bumps_on_set_headerline() {
        let mb = MultibufferDocumentHandle::empty(empty_registry());
        let buffer_id = mb.buffer_id();
        let provider = MultibufferStatusProvider::new(mb.clone()).into_provider(buffer_id);
        let v0 = provider.version();
        mb.set_headerline(HeaderlineStatus::Complete {
            summary: "done".into(),
            emphasis: None,
        });
        assert!(
            provider.version() > v0,
            "version must advance after set_headerline"
        );
    }

    #[test]
    fn status_provider_namespace_does_not_collide_with_excerpt_header() {
        let buf = BufferId(7);
        let excerpt_id = multibuffer_excerpt_header_provider_id(buf);
        let status_id = multibuffer_status_provider_id(buf);
        assert_ne!(excerpt_id, status_id);
        assert_eq!(status_id & 0xFFFF_FFFF, 7);
    }

    // ── MH.A4: status colors resolve from theme elements ────────

    #[test]
    fn status_provider_no_theme_uses_fallback_hex() {
        // Test path (no theme service): the three states render with
        // the pre-MH.A4 fallback hex so nothing regresses where the
        // theme isn't wired.
        let cases = [
            (
                HeaderlineStatus::InProgress {
                    label: "x".into(),
                    count: None,
                    emphasis: None,
                },
                STATUS_IN_PROGRESS_FALLBACK_FG,
            ),
            (
                HeaderlineStatus::Complete {
                    summary: "done".into(),
                    emphasis: None,
                },
                STATUS_COMPLETE_FALLBACK_FG,
            ),
            (
                HeaderlineStatus::Failed {
                    reason: "boom".into(),
                },
                STATUS_FAILED_FALLBACK_FG,
            ),
        ];
        for (status, expected_fg) in cases {
            let mb = MultibufferDocumentHandle::empty(empty_registry());
            mb.set_headerline(status);
            let provider = MultibufferStatusProvider::new(mb);
            let row = provider.render().expect("non-idle status renders a row");
            assert!(
                row.cells.iter().all(|c| c.fg == expected_fg),
                "no-theme status uses fallback fg {expected_fg:#08x}"
            );
        }
    }

    #[test]
    fn status_elements_register_and_bake_resolved_fg() {
        // MH.A4 acid test: the mode registers `multibuffer.status.*`
        // elements; the status provider resolves them and bakes the
        // per-state fg into the rendered row. Assert against the
        // RESOLVED palette role-key (green / red / subtext), NOT the old
        // ad-hoc hex.
        use lattice_theme::{
            ElementName, ElementOwner, InMemoryThemeRegistry, ThemeRegistry, ThemeRegistryHandle,
            default_palette,
        };

        let registry = Arc::new(InMemoryThemeRegistry::new(default_palette()));
        let owner = ElementOwner::Mode(
            crate::MultibufferMode::mode_id()
                .as_str()
                .to_string()
                .into(),
        );
        let ids = crate::register_multibuffer_theme_elements(registry.as_ref(), owner);

        // 1) The three elements are registered + resolve to the mapped
        //    palette role-keys.
        let resolved = registry.resolved();
        let palette = default_palette();
        let role = |key: &str| palette.get(&key.to_string().into()).unwrap();
        assert_eq!(
            resolved
                .get(
                    registry
                        .id(&ElementName::from(ELEM_STATUS_IN_PROGRESS.to_string()))
                        .unwrap()
                )
                .fg,
            Some(role("subtext")),
            "in_progress maps to the grey `subtext` role-key"
        );
        assert_eq!(
            resolved
                .get(
                    registry
                        .id(&ElementName::from(ELEM_STATUS_COMPLETE.to_string()))
                        .unwrap()
                )
                .fg,
            Some(role("green")),
            "complete maps to the `green` role-key"
        );
        assert_eq!(
            resolved
                .get(
                    registry
                        .id(&ElementName::from(ELEM_STATUS_FAILED.to_string()))
                        .unwrap()
                )
                .fg,
            Some(role("red")),
            "failed maps to the `red` role-key"
        );

        // 2) The rendered status row bakes the resolved fg per state.
        let theme: ThemeRegistryHandle = registry.clone();
        let expect_fg = |status: HeaderlineStatus, key: &str| {
            let mb = MultibufferDocumentHandle::empty(empty_registry());
            mb.set_headerline(status);
            let provider = MultibufferStatusProvider::with_theme(mb, theme.clone(), ids);
            let row = provider.render().expect("non-idle status renders a row");
            let want = role(key).to_rgb_u32(0);
            assert!(
                row.cells.iter().all(|c| c.fg == want),
                "status row baked fg = resolved {key} ({want:#08x})"
            );
        };
        expect_fg(
            HeaderlineStatus::InProgress {
                label: "s".into(),
                count: Some(2),
                emphasis: None,
            },
            "subtext",
        );
        expect_fg(
            HeaderlineStatus::Complete {
                summary: "done".into(),
                emphasis: None,
            },
            "green",
        );
        expect_fg(
            HeaderlineStatus::Failed {
                reason: "err".into(),
            },
            "red",
        );
    }

    #[test]
    fn status_emphasis_term_gets_query_accent_fg() {
        // The emphasised substring (e.g. the search query woven into the
        // status label) is painted with the resolved
        // `multibuffer.status.query` accent (yellow); the rest of the row
        // keeps the state fg. Only the term cells get the accent.
        use lattice_theme::{
            ElementName, ElementOwner, InMemoryThemeRegistry, ThemeRegistry, ThemeRegistryHandle,
            default_palette,
        };
        let registry = Arc::new(InMemoryThemeRegistry::new(default_palette()));
        let owner = ElementOwner::Mode(
            crate::MultibufferMode::mode_id()
                .as_str()
                .to_string()
                .into(),
        );
        let ids = crate::register_multibuffer_theme_elements(registry.as_ref(), owner);

        // The query element resolves to the `yellow` role-key.
        let resolved = registry.resolved();
        let palette = default_palette();
        let role = |key: &str| palette.get(&key.to_string().into()).unwrap();
        assert_eq!(
            resolved
                .get(
                    registry
                        .id(&ElementName::from(ELEM_STATUS_QUERY.to_string()))
                        .unwrap()
                )
                .fg,
            Some(role("yellow")),
            "query accent maps to the `yellow` role-key"
        );

        // Render a Complete status carrying an emphasised term.
        let theme: ThemeRegistryHandle = registry.clone();
        let mb = MultibufferDocumentHandle::empty(empty_registry());
        mb.set_headerline(HeaderlineStatus::Complete {
            summary: "\"needle\" — 3 hits in 2 files".into(),
            emphasis: Some("needle".into()),
        });
        let provider = MultibufferStatusProvider::with_theme(mb, theme, ids);
        let row = provider.render().expect("non-idle status renders a row");

        let query_fg = role("yellow").to_rgb_u32(0);
        let complete_fg = role("green").to_rgb_u32(0);
        let text: String = row
            .cells
            .iter()
            .map(|c| char::from_u32(c.codepoint).unwrap_or(' '))
            .collect();
        let byte_start = text.find("needle").expect("term present in row");
        let char_start = text[..byte_start].chars().count();
        let char_end = char_start + "needle".chars().count();
        for (i, cell) in row.cells.iter().enumerate() {
            if i >= char_start && i < char_end {
                assert_eq!(cell.fg, query_fg, "emphasis cell {i} uses the query accent");
            } else {
                assert_eq!(
                    cell.fg, complete_fg,
                    "non-emphasis cell {i} keeps the state (complete) fg"
                );
            }
        }
    }

    #[test]
    fn status_provider_version_folds_theme_version() {
        // MH.A4: a colorscheme swap (theme override) bumps the status
        // provider version so the headerline re-renders the recolored
        // status row.
        use lattice_theme::{
            ElementName, ElementOwner, InMemoryThemeRegistry, StyleSpec, ThemeRegistry,
            ThemeRegistryHandle, default_palette,
        };
        let registry = Arc::new(InMemoryThemeRegistry::new(default_palette()));
        let owner = ElementOwner::Mode(
            crate::MultibufferMode::mode_id()
                .as_str()
                .to_string()
                .into(),
        );
        let ids = crate::register_multibuffer_theme_elements(registry.as_ref(), owner);
        let theme: ThemeRegistryHandle = registry.clone();
        let mb = MultibufferDocumentHandle::empty(empty_registry());
        mb.set_headerline(HeaderlineStatus::Complete {
            summary: "done".into(),
            emphasis: None,
        });
        let provider = MultibufferStatusProvider::with_theme(mb, theme, ids);

        let _ = registry.resolved();
        let v_before = provider.version();
        registry.set_override(
            ElementName::from(ELEM_STATUS_COMPLETE.to_string()),
            StyleSpec::new().fg(Color::Rgb(1, 2, 3)),
        );
        let v_after = provider.version();
        assert!(
            v_after > v_before,
            "theme change must bump status provider version; before={v_before} after={v_after}"
        );
    }
}

/// AF.1: how a multibuffer view's rows group for folding.
///
/// A per-VIEW property because the answer is not a property of multibuffers —
/// it is a property of what a given provider's rows mean, and the three
/// shipped providers disagree:
///
/// - **search** headers every excerpt with its file path, and its excerpts
///   arrive grouped by file, so a file IS a contiguous run;
/// - **project-diff** headers each hunk with its LINE NUMBER, so titles are
///   neither unique nor a grouping key at all — only the source path is;
/// - **the agenda** headers the first row of each date/section run and blanks
///   the rest, and its rows deliberately INTERLEAVE across files (OM.A2), so
///   the source path is the one thing that is not a grouping.
///
/// Hence a declaration rather than a heuristic. A provider says how its rows
/// group; the mode registers the matching fold source. Guessing from the
/// excerpt shape would be right for two of the three and silently wrong for
/// the third, which is how `home.org`'s fold came to swallow `work.org`'s rows.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum FoldGrouping {
    /// One fold per source file, spanning that file's first excerpt to its
    /// last. The default, and correct wherever excerpts arrive grouped by file.
    SourceFile = 0,
    /// One fold per HEADER RUN — what the user actually sees as a group.
    HeaderRuns = 1,
}

/// Namespace for header-group fold provider IDs.
const HEADER_GROUP_FOLD_NAMESPACE: u64 = 0xBBBB_0005_0000_0000;

/// AF.1: one open [`lattice_core::Fold`] per **header run** — the rows a user
/// sees under one header.
///
/// The grouping rule handles both header conventions in the tree with one
/// pass, which is what lets this be a shared mechanism rather than an
/// agenda-shaped special case:
///
/// - a **non-empty** title that differs from the current group's starts a new
///   group (search's per-excerpt file headers; the agenda's run labels);
/// - a **non-empty** title equal to the current group's continues it (search's
///   second and later excerpts from one file);
/// - an **empty** title continues the current group (the agenda's rows after
///   the first of a run — an empty title renders no header row, which is
///   exactly what "I belong to the group above" means).
///
/// `identity` is the group's TITLE, so the closed/open state survives a `gr`
/// refresh — `recompute_folds` carries state by matching identity, and the
/// title is what the user was collapsing. That is the same reasoning PD.5a
/// applied to paths for [`FileBoundaryFoldProvider`], and it holds here for the
/// same reason: the hit-count badge lives in its own field rather than in
/// `title`, so a refresh that changes the count does not change the identity.
pub struct HeaderGroupFoldProvider {
    id: lattice_core::ProviderId,
    handle: MultibufferDocumentHandle,
}

impl HeaderGroupFoldProvider {
    pub fn new(handle: MultibufferDocumentHandle, buffer_id: BufferId) -> Self {
        let id = lattice_core::ProviderId(HEADER_GROUP_FOLD_NAMESPACE | buffer_id.0 as u64);
        Self { id, handle }
    }
}

impl lattice_core::FoldSource for HeaderGroupFoldProvider {
    fn id(&self) -> lattice_core::ProviderId {
        self.id
    }

    fn compute_folds(&self) -> Vec<lattice_core::Fold> {
        let excerpts = self.handle.excerpts();
        let starts = crate::motions::excerpt_start_rows(&excerpts);
        let mut folds: Vec<lattice_core::Fold> = Vec::new();
        let mut current: Option<String> = None;
        for (excerpt, &start) in excerpts.iter().zip(starts.iter()) {
            let end = start.saturating_add(excerpt.line_count().saturating_sub(1));
            let title = excerpt.header.title.as_str();
            let starts_group = !title.is_empty() && current.as_deref() != Some(title);
            if starts_group {
                current = Some(title.to_string());
                let mut hasher = std::collections::hash_map::DefaultHasher::new();
                std::hash::Hash::hash(title, &mut hasher);
                folds.push(lattice_core::Fold {
                    start_line: start,
                    end_line: end,
                    closed: false,
                    identity: Some(std::hash::Hasher::finish(&hasher)),
                });
            } else if let Some(last) = folds.last_mut() {
                // Extend the open group. `max` rather than assignment because
                // an excerpt's rows are contiguous but a provider is not
                // required to emit them in row order.
                last.end_line = last.end_line.max(end);
            }
            // No `else`: rows before the first header belong to no group and
            // get no fold, rather than being swept into a group that has not
            // started. A view whose first excerpt has an empty title is
            // malformed rather than something to guess about.
        }
        folds
    }
}

// ── M.7: ExcerptFoldProvider ────────────────────────────────────────────────

/// Namespace for excerpt fold provider IDs: `0xBBBB_0003_0000_0000 | buffer_id`.
/// Distinct from the header provider (`0xBBBB_0001_*`) and status
/// provider (`0xBBBB_0002_*`) namespaces.
const EXCERPT_FOLD_NAMESPACE: u64 = 0xBBBB_0003_0000_0000;
const FILE_BOUNDARY_FOLD_NAMESPACE: u64 = 0xBBBB_0004_0000_0000;

/// M.7: computes one open [`lattice_core::Fold`] per excerpt in the
/// composed multibuffer. Registered as a
/// [`lattice_core::FoldSource`] by `MultibufferMode::on_activate`
/// via `FoldOverlayService`; the `FoldSourceAdapter` in `lattice-host`
/// gates `compute_folds` to calls where `FoldContext::buffer_id`
/// matches this multibuffer's buffer ID.
pub struct ExcerptFoldProvider {
    id: lattice_core::ProviderId,
    handle: MultibufferDocumentHandle,
}

impl ExcerptFoldProvider {
    pub fn new(handle: MultibufferDocumentHandle, buffer_id: BufferId) -> Self {
        let id = lattice_core::ProviderId(EXCERPT_FOLD_NAMESPACE | buffer_id.0 as u64);
        Self { id, handle }
    }
}

impl lattice_core::FoldSource for ExcerptFoldProvider {
    fn id(&self) -> lattice_core::ProviderId {
        self.id
    }

    /// One fold per excerpt — **except a single-line one, which is not a
    /// fold at all** (OA.4c).
    ///
    /// A fold whose `start_line == end_line` can never hide anything: closed,
    /// it shows its head, which is the whole of it. Emitting one is not merely
    /// wasteful, it is actively wrong, because `innermost_fold_idx` picks the
    /// fold with the greatest `start_line` — so a degenerate per-excerpt fold
    /// SHADOWS the group fold that actually contains the row, and `<Tab>`
    /// toggles something with no visible effect while the block stays closed.
    ///
    /// That is what one-line agenda rows (OA.1) turned this into: before them
    /// an agenda excerpt spanned its planning line, so every fold here was a
    /// real two-line one. The report was "`<Tab>` doesn't work cleanly, only
    /// `<S-Tab>` seems to work" — `<S-Tab>` sets every fold at once, so it was
    /// unaffected.
    ///
    /// Generic, not agenda-shaped: project search with `context_lines = 0`
    /// produces one-line excerpts too.
    fn compute_folds(&self) -> Vec<lattice_core::Fold> {
        let excerpts = self.handle.excerpts();
        let starts = crate::motions::excerpt_start_rows(&excerpts);
        excerpts
            .iter()
            .zip(starts.iter())
            .filter(|(excerpt, _)| excerpt.line_count() > 1)
            .map(|(excerpt, &start)| {
                let line_count = excerpt.line_count();
                let end = start.saturating_add(line_count.saturating_sub(1));
                lattice_core::Fold {
                    start_line: start,
                    end_line: end,
                    closed: false,
                    identity: Some(excerpt.id.0),
                }
            })
            .collect()
    }
}

/// M.8: computes one open [`lattice_core::Fold`] per distinct source
/// [`BufferId`] (file), spanning the composed-row range from the first
/// to the last excerpt belonging to that file. Registered alongside
/// `ExcerptFoldProvider` by `MultibufferMode::on_activate`. Enables
/// collapsing all excerpts from a file to its header row with `za`.
///
/// PD.5a: the fold's `identity` is derived from the source **path**,
/// not its `BufferId`. `recompute_folds` carries closed/open state
/// across a rebuild by matching identity, and a refreshing provider
/// re-reads its files under fresh `BufferId::next()` values — so a
/// BufferId-derived identity changes on every refresh, the match
/// misses, and every file the user had collapsed springs back open.
/// The path is what the user was collapsing, so it is what the
/// identity should track.
pub struct FileBoundaryFoldProvider {
    id: lattice_core::ProviderId,
    handle: MultibufferDocumentHandle,
}

impl FileBoundaryFoldProvider {
    pub fn new(handle: MultibufferDocumentHandle, buffer_id: BufferId) -> Self {
        let id = lattice_core::ProviderId(FILE_BOUNDARY_FOLD_NAMESPACE | buffer_id.0 as u64);
        Self { id, handle }
    }
}

impl lattice_core::FoldSource for FileBoundaryFoldProvider {
    fn id(&self) -> lattice_core::ProviderId {
        self.id
    }

    fn compute_folds(&self) -> Vec<lattice_core::Fold> {
        let excerpts = self.handle.excerpts();
        if excerpts.is_empty() {
            return Vec::new();
        }
        let starts = crate::motions::excerpt_start_rows(&excerpts);
        // Group by source BufferId: track (start_row, end_row) per file.
        // First appearance sets start_row; later excerpts from the same
        // file extend end_row (handles non-contiguous same-file excerpts).
        let mut by_source: std::collections::HashMap<BufferId, (u32, u32)> =
            std::collections::HashMap::new();
        for (excerpt, &start) in excerpts.iter().zip(starts.iter()) {
            let end = start.saturating_add(excerpt.line_count().saturating_sub(1));
            by_source
                .entry(excerpt.source)
                .and_modify(|(_, e)| *e = end)
                .or_insert((start, end));
        }
        // Sort by start_row for deterministic output order.
        let mut groups: Vec<(BufferId, (u32, u32))> = by_source.into_iter().collect();
        groups.sort_by_key(|(_, (start, _))| *start);
        groups
            .into_iter()
            .map(|(source, (start, end))| lattice_core::Fold {
                start_line: start,
                end_line: end,
                closed: false,
                identity: Some(self.source_identity(source)),
            })
            .collect()
    }
}

impl FileBoundaryFoldProvider {
    /// PD.5a: stable identity for a source file's fold.
    ///
    /// Hashed from the source's path when it has one. A pathless source
    /// — a synthetic buffer, or a scratch source a provider composes in
    /// memory — falls back to its `BufferId`, which is as stable as such
    /// a source gets and at least keeps the identity unique.
    ///
    /// The two spaces are kept apart by a discriminant byte, so a path
    /// whose hash happens to equal some buffer id cannot be mistaken for
    /// that buffer's pathless fold.
    fn source_identity(&self, source: BufferId) -> u64 {
        use std::hash::{Hash, Hasher};
        match self.handle.source_path(source) {
            Some(path) => {
                let mut h = std::collections::hash_map::DefaultHasher::new();
                0u8.hash(&mut h);
                path.hash(&mut h);
                h.finish()
            }
            None => {
                let mut h = std::collections::hash_map::DefaultHasher::new();
                1u8.hash(&mut h);
                source.0.hash(&mut h);
                h.finish()
            }
        }
    }
}

#[cfg(test)]
mod excerpt_fold_tests {
    #![allow(clippy::unwrap_used)]
    use std::sync::Arc;
    use std::sync::atomic::{AtomicBool, Ordering};

    use lattice_core::Document as CoreDocument;
    use lattice_core::DocumentBuilder as CoreDocumentBuilder;
    use lattice_core::{FoldOverlayService, FoldOverlayServiceHandle, FoldSource};
    use lattice_grammar::CommandRegistry;
    use lattice_runtime::spawn_document;

    use super::*;

    fn reg() -> lattice_grammar::CommandRegistryHandle {
        Arc::new(arc_swap::ArcSwap::from_pointee(CommandRegistry::new()))
    }

    #[tokio::test(flavor = "current_thread")]
    async fn compute_folds_returns_one_fold_per_excerpt() {
        let r = reg();
        let buf_a = BufferId::next();
        let buf_b = BufferId::next();
        let doc_a = spawn_document(buf_a, CoreDocument::from_text("a\nb\nc\n"), r.clone());
        let doc_b = spawn_document(buf_b, CoreDocument::from_text("x\ny\n"), r.clone());
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(buf_a, Arc::new(doc_a));
        sources.insert(buf_b, Arc::new(doc_b));
        let excerpts = vec![
            Excerpt::new(buf_a, 0, 2), // 3 lines → composed rows 0–2
            Excerpt::new(buf_b, 0, 1), // 2 lines → composed rows 3–4
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, r).unwrap();
        let buf_id = mb.buffer_id();
        let provider = ExcerptFoldProvider::new(mb, buf_id);
        let folds = provider.compute_folds();
        assert_eq!(folds.len(), 2);
        assert_eq!(folds[0].start_line, 0);
        assert_eq!(folds[0].end_line, 2);
        assert!(!folds[0].closed);
        assert!(folds[0].identity.is_some());
        assert_eq!(folds[1].start_line, 3);
        assert_eq!(folds[1].end_line, 4);
        assert!(!folds[1].closed);
        assert!(folds[1].identity.is_some());
    }

    #[test]
    fn excerpt_fold_namespace_distinct_from_header_and_status() {
        let buf = BufferId(42);
        let fold_id = ExcerptFoldProvider::new(MultibufferDocumentHandle::empty(reg()), buf).id;
        // header/status ProviderId uses lattice_cells::virtual_rows::ProviderId;
        // compare raw u64 values to verify no namespace collision.
        let header_raw: u64 = multibuffer_excerpt_header_provider_id(buf);
        let status_raw: u64 = multibuffer_status_provider_id(buf);
        assert_ne!(fold_id.0, header_raw);
        assert_ne!(fold_id.0, status_raw);
        assert_eq!(fold_id.0 >> 32, 0xBBBB_0003);
        assert_eq!(fold_id.0 & 0xFFFF_FFFF, 42);
    }

    #[test]
    fn compute_folds_empty_when_no_excerpts() {
        let mb = MultibufferDocumentHandle::empty(reg());
        let buf_id = mb.buffer_id();
        let provider = ExcerptFoldProvider::new(mb, buf_id);
        assert!(provider.compute_folds().is_empty());
    }

    // ── MultibufferModeGuard drop ───────────────────────────────────────

    struct MockFoldService {
        removed: Arc<AtomicBool>,
    }
    impl FoldOverlayService for MockFoldService {
        fn add_source(
            &self,
            _source: Arc<dyn FoldSource>,
            _buffer_id: BufferId,
        ) -> lattice_core::ProviderId {
            lattice_core::ProviderId(1)
        }
        fn remove_source(&self, _id: lattice_core::ProviderId) {
            self.removed.store(true, Ordering::SeqCst);
        }
    }

    #[test]
    fn mode_guard_drop_calls_remove_source() {
        let removed = Arc::new(AtomicBool::new(false));
        let svc: FoldOverlayServiceHandle = Arc::new(MockFoldService {
            removed: removed.clone(),
        });
        {
            let _guard = crate::mode::MultibufferModeGuard {
                fold_registrations: vec![(svc, lattice_core::ProviderId(1))],
                // Empty: this test covers the fold-registration half
                // of Drop only. The action-handler tokens unregister
                // themselves via their own Drop impl, which
                // `lattice-mode` tests separately.
                _action_handler_registrations: Vec::new(),
            };
        }
        assert!(
            removed.load(Ordering::SeqCst),
            "remove_source must fire on guard drop"
        );
    }

    // ── AF.1: HeaderGroupFoldProvider ───────────────────────────────────

    /// **The agenda's convention**: a label on the first row of a run, an
    /// empty title on the rest. An empty title renders no header row, which is
    /// exactly what "I belong to the group above" means — so it continues the
    /// group rather than starting one.
    #[tokio::test(flavor = "current_thread")]
    async fn header_groups_fold_a_run_that_interleaves_files() {
        let r = reg();
        let buf_a = BufferId::next();
        let buf_b = BufferId::next();
        let doc_a = spawn_document(buf_a, CoreDocument::from_text("a\nb\nc\n"), r.clone());
        let doc_b = spawn_document(buf_b, CoreDocument::from_text("x\ny\nz\n"), r.clone());
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(buf_a, Arc::new(doc_a));
        sources.insert(buf_b, Arc::new(doc_b));
        // Two groups, each drawing rows from BOTH files — the agenda's shape.
        let excerpts = vec![
            Excerpt::new(buf_a, 0, 0).with_header(ExcerptHeader::new("Overdue".to_string())),
            Excerpt::new(buf_b, 0, 0).with_header(ExcerptHeader::new(String::new())),
            Excerpt::new(buf_a, 1, 1).with_header(ExcerptHeader::new("Today".to_string())),
            Excerpt::new(buf_b, 1, 1).with_header(ExcerptHeader::new(String::new())),
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, r).unwrap();
        let buf_id = mb.buffer_id();
        let folds = HeaderGroupFoldProvider::new(mb, buf_id).compute_folds();

        assert_eq!(folds.len(), 2, "one fold per header run, got {folds:?}");
        assert_eq!((folds[0].start_line, folds[0].end_line), (0, 1), "Overdue");
        assert_eq!((folds[1].start_line, folds[1].end_line), (2, 3), "Today");
        // The property `FileBoundaryFoldProvider` cannot give the agenda: no
        // fold spans a row belonging to a different group.
        assert!(
            folds[0].end_line < folds[1].start_line,
            "groups must not overlap: {folds:?}"
        );
    }

    /// **Search's convention**: EVERY excerpt carries its file's path as the
    /// title. A repeated title continues the run, so this still yields one
    /// fold per file — the same answer `FileBoundaryFoldProvider` gives on the
    /// layout it was built for. That equivalence is what makes this a shared
    /// mechanism rather than an agenda-shaped special case.
    #[tokio::test(flavor = "current_thread")]
    async fn header_groups_match_file_folds_on_the_search_layout() {
        let r = reg();
        let buf_a = BufferId::next();
        let buf_b = BufferId::next();
        let doc_a = spawn_document(buf_a, CoreDocument::from_text("a\nb\nc\n"), r.clone());
        let doc_b = spawn_document(buf_b, CoreDocument::from_text("x\ny\n"), r.clone());
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(buf_a, Arc::new(doc_a));
        sources.insert(buf_b, Arc::new(doc_b));
        let hdr = |p: &str| ExcerptHeader::new(p.to_string());
        let excerpts = vec![
            Excerpt::new(buf_a, 0, 0).with_header(hdr("/a.rs")),
            Excerpt::new(buf_a, 1, 1).with_header(hdr("/a.rs")),
            Excerpt::new(buf_b, 0, 0).with_header(hdr("/b.rs")),
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts.clone(), r.clone()).unwrap();
        let buf_id = mb.buffer_id();
        let header_folds = HeaderGroupFoldProvider::new(mb.clone(), buf_id).compute_folds();
        let file_folds = FileBoundaryFoldProvider::new(mb, buf_id).compute_folds();

        let bounds = |fs: &[lattice_core::Fold]| -> Vec<(u32, u32)> {
            let mut v: Vec<_> = fs.iter().map(|f| (f.start_line, f.end_line)).collect();
            v.sort_unstable();
            v
        };
        assert_eq!(
            bounds(&header_folds),
            bounds(&file_folds),
            "on a file-grouped layout the two providers must agree"
        );
        assert_eq!(bounds(&header_folds), vec![(0, 1), (2, 2)]);
    }

    /// Identity is the group's TITLE, so a `gr` refresh that mints new
    /// `BufferId`s keeps the user's collapsed groups collapsed. Same reasoning
    /// as PD.5a's path identity, and the reason a row-position fallback is not
    /// enough: the rows themselves move.
    #[tokio::test(flavor = "current_thread")]
    async fn header_group_identity_is_the_title_not_the_rows() {
        let build = |extra: &str| {
            let r = reg();
            let id = BufferId::next();
            let doc = spawn_document(id, CoreDocument::from_text("a\nb\nc\n"), r.clone());
            let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
            sources.insert(id, Arc::new(doc) as Arc<dyn Document>);
            // `extra` shifts the group DOWN a row between the two builds.
            let mut excerpts = Vec::new();
            if !extra.is_empty() {
                excerpts.push(
                    Excerpt::new(id, 0, 0).with_header(ExcerptHeader::new(extra.to_string())),
                );
            }
            excerpts
                .push(Excerpt::new(id, 1, 1).with_header(ExcerptHeader::new("Today".to_string())));
            let mb = MultibufferDocumentHandle::new(sources, excerpts, r).unwrap();
            let buf_id = mb.buffer_id();
            (id, HeaderGroupFoldProvider::new(mb, buf_id).compute_folds())
        };
        let (first, before) = build("");
        let (second, after) = build("Overdue");
        assert_ne!(first, second, "the fixture must mint a new BufferId");

        let today_before = before.iter().find(|_| true).expect("a fold");
        let today_after = after.last().expect("the Today fold");
        assert_ne!(
            today_before.start_line, today_after.start_line,
            "the fixture must MOVE the group, or identity is not what is tested"
        );
        assert_eq!(
            today_before.identity, today_after.identity,
            "same title across a rebuild must keep its fold identity"
        );
    }

    /// Rows before the first header belong to no group and get no fold, rather
    /// than being swept into a group that has not started.
    #[tokio::test(flavor = "current_thread")]
    async fn rows_before_the_first_header_are_not_folded() {
        let r = reg();
        let id = BufferId::next();
        let doc = spawn_document(id, CoreDocument::from_text("a\nb\nc\n"), r.clone());
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(id, Arc::new(doc));
        let excerpts = vec![
            Excerpt::new(id, 0, 0).with_header(ExcerptHeader::new(String::new())),
            Excerpt::new(id, 1, 1).with_header(ExcerptHeader::new("Group".to_string())),
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, r).unwrap();
        let buf_id = mb.buffer_id();
        let folds = HeaderGroupFoldProvider::new(mb, buf_id).compute_folds();
        assert_eq!(folds.len(), 1, "got {folds:?}");
        assert_eq!(folds[0].start_line, 1, "the fold starts at the header row");
    }

    /// A view that declares nothing keeps the pre-AF.1 grouping.
    #[tokio::test(flavor = "current_thread")]
    async fn fold_grouping_defaults_to_source_file() {
        let mb = MultibufferDocumentHandle::empty(reg());
        assert_eq!(mb.fold_grouping(), FoldGrouping::SourceFile);
        mb.set_fold_grouping(FoldGrouping::HeaderRuns);
        assert_eq!(mb.fold_grouping(), FoldGrouping::HeaderRuns);
    }

    // ── FileBoundaryFoldProvider ────────────────────────────────────────

    #[tokio::test(flavor = "current_thread")]
    async fn file_boundary_folds_one_fold_per_source_file() {
        let r = reg();
        let buf_a = BufferId::next();
        let buf_b = BufferId::next();
        let doc_a = spawn_document(buf_a, CoreDocument::from_text("a\nb\nc\n"), r.clone());
        let doc_b = spawn_document(buf_b, CoreDocument::from_text("x\ny\n"), r.clone());
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(buf_a, Arc::new(doc_a));
        sources.insert(buf_b, Arc::new(doc_b));
        // Two excerpts from buf_a, one from buf_b.
        // buf_a excerpt 1: rows 0-2 (3 lines); buf_a excerpt 2: rows 3-4 (2 lines);
        // buf_b excerpt:   rows 5-6 (2 lines)
        let excerpts = vec![
            Excerpt::new(buf_a, 0, 2),
            Excerpt::new(buf_a, 0, 1),
            Excerpt::new(buf_b, 0, 1),
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, r).unwrap();
        let buf_id = mb.buffer_id();
        let provider = FileBoundaryFoldProvider::new(mb, buf_id);
        let folds = provider.compute_folds();
        assert_eq!(folds.len(), 2, "one fold per source file");
        // buf_a fold spans rows 0-4 (first excerpt start to second excerpt end).
        let a_fold = folds
            .iter()
            .find(|f| f.start_line == 0)
            .expect("buf_a fold");
        assert_eq!(a_fold.end_line, 4);
        // buf_b fold spans rows 5-6.
        let b_fold = folds
            .iter()
            .find(|f| f.start_line == 5)
            .expect("buf_b fold");
        assert_eq!(b_fold.end_line, 6);
        // PD.5a: identity used to be the raw `BufferId`, and this test
        // asserted exactly that. It is now derived (path when there is
        // one, hashed buffer id otherwise), so the raw value was an
        // implementation detail to stop pinning. What the fold engine
        // actually needs is that the two files do not collide — see
        // `file_boundary_fold_identity_survives_a_refresh` for the
        // stability half.
        assert!(a_fold.identity.is_some());
        assert_ne!(a_fold.identity, b_fold.identity);
    }

    #[test]
    fn file_boundary_fold_namespace_distinct() {
        let buf = BufferId(42);
        let fold_id =
            FileBoundaryFoldProvider::new(MultibufferDocumentHandle::empty(reg()), buf).id;
        let excerpt_id = ExcerptFoldProvider::new(MultibufferDocumentHandle::empty(reg()), buf).id;
        let header_raw: u64 = multibuffer_excerpt_header_provider_id(buf);
        let status_raw: u64 = multibuffer_status_provider_id(buf);
        assert_ne!(fold_id.0, excerpt_id.0);
        assert_ne!(fold_id.0, header_raw);
        assert_ne!(fold_id.0, status_raw);
        assert_eq!(fold_id.0 >> 32, 0xBBBB_0004);
        assert_eq!(fold_id.0 & 0xFFFF_FFFF, 42);
    }

    /// **A file-boundary fold spans every row between a file's first and last
    /// excerpt — including OTHER files' rows when they interleave.**
    ///
    /// Harmless for the search provider, whose excerpts arrive grouped by
    /// file. Wrong for the agenda, whose whole point is that rows interleave
    /// across files by date (OM.A2): collapsing `home.org` there would
    /// swallow the `work.org` rows sitting between its earliest and latest
    /// entry, and the fold's header would claim rows that are not its.
    ///
    /// Pinned as the CURRENT behaviour rather than as a bug to fix in place —
    /// it is correct for the provider it was built for. The agenda's answer
    /// is to group folds by what the user actually sees (the header runs),
    /// which is `HeaderGroupFoldProvider`.
    #[tokio::test(flavor = "current_thread")]
    async fn file_boundary_folds_swallow_interleaved_rows() {
        let r = reg();
        let buf_a = BufferId::next();
        let buf_b = BufferId::next();
        let doc_a = spawn_document(buf_a, CoreDocument::from_text("a\nb\nc\n"), r.clone());
        let doc_b = spawn_document(buf_b, CoreDocument::from_text("x\ny\n"), r.clone());
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(buf_a, Arc::new(doc_a));
        sources.insert(buf_b, Arc::new(doc_b));
        // INTERLEAVED, the agenda's shape: a(row 0), b(row 1), a(row 2).
        let excerpts = vec![
            Excerpt::new(buf_a, 0, 0),
            Excerpt::new(buf_b, 0, 0),
            Excerpt::new(buf_a, 1, 1),
        ];
        let mb = MultibufferDocumentHandle::new(sources, excerpts, r).unwrap();
        let buf_id = mb.buffer_id();
        let folds = FileBoundaryFoldProvider::new(mb, buf_id).compute_folds();

        let a_fold = folds
            .iter()
            .find(|f| f.start_line == 0)
            .expect("buf_a fold");
        assert_eq!(
            (a_fold.start_line, a_fold.end_line),
            (0, 2),
            "buf_a's fold spans row 1, which belongs to buf_b"
        );
    }

    #[test]
    fn file_boundary_folds_empty_when_no_excerpts() {
        let mb = MultibufferDocumentHandle::empty(reg());
        let buf_id = mb.buffer_id();
        let provider = FileBoundaryFoldProvider::new(mb, buf_id);
        assert!(provider.compute_folds().is_empty());
    }

    // ── PD.5a: identity has to outlive the source buffer ──────
    //
    // `recompute_folds` carries the closed/open state across a rebuild
    // by matching `Fold::identity`, falling back to `(start_line,
    // end_line)`. A refreshing provider re-reads its files and calls
    // `BufferId::next()` for each one (`attach_batch` in project-diff,
    // and the search provider does the same), so a `BufferId`-derived
    // identity is a fresh number on every refresh: the match misses,
    // the fallback keys on rows that have themselves moved, and every
    // file the user collapsed springs back open. Deriving identity from
    // the source *path* fixes it, because the path is the thing the
    // user was collapsing.

    /// Same file, same path, new `BufferId` — the shape a `gr` refresh
    /// produces.
    #[tokio::test]
    async fn file_boundary_fold_identity_survives_a_refresh() {
        let build = |text: &str| {
            let r = reg();
            let id = BufferId::next();
            let doc = CoreDocumentBuilder::default()
                .with_text(text)
                .with_path(std::path::PathBuf::from("/repo/src/main.rs"))
                .build();
            let handle = spawn_document(id, doc, r.clone());
            let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
            sources.insert(id, Arc::new(handle) as Arc<dyn Document>);
            let mb =
                MultibufferDocumentHandle::new(sources, vec![Excerpt::new(id, 0, 1)], r).unwrap();
            let buf_id = mb.buffer_id();
            (
                id,
                FileBoundaryFoldProvider::new(mb, buf_id).compute_folds(),
            )
        };

        let (first_id, before) = build("a\nb\n");
        let (second_id, after) = build("a\nchanged\n");

        assert_ne!(
            first_id, second_id,
            "the fixture must mint a new BufferId, or this proves nothing"
        );
        assert_eq!(before.len(), 1);
        assert_eq!(after.len(), 1);
        assert_eq!(
            before[0].identity, after[0].identity,
            "same path across a refresh must keep its fold identity"
        );
    }

    /// Two different files must not collide, or collapsing one would
    /// collapse the other.
    #[tokio::test]
    async fn file_boundary_fold_identity_differs_between_paths() {
        let r = reg();
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        let mut ids = Vec::new();
        for path in ["/repo/src/a.rs", "/repo/src/b.rs"] {
            let id = BufferId::next();
            let doc = CoreDocumentBuilder::default()
                .with_text("x\ny\n")
                .with_path(std::path::PathBuf::from(path))
                .build();
            sources.insert(
                id,
                Arc::new(spawn_document(id, doc, r.clone())) as Arc<dyn Document>,
            );
            ids.push(id);
        }
        let excerpts = ids.iter().map(|id| Excerpt::new(*id, 0, 1)).collect();
        let mb = MultibufferDocumentHandle::new(sources, excerpts, r).unwrap();
        let buf_id = mb.buffer_id();
        let folds = FileBoundaryFoldProvider::new(mb, buf_id).compute_folds();
        assert_eq!(folds.len(), 2);
        assert_ne!(
            folds[0].identity, folds[1].identity,
            "distinct paths must get distinct fold identities"
        );
    }

    /// A source with no path — a synthetic buffer, or a scratch source a
    /// future provider composes — still needs *an* identity. It falls
    /// back to the buffer id, which is as stable as such a source gets.
    #[tokio::test]
    async fn a_pathless_source_still_gets_an_identity() {
        let r = reg();
        let id = BufferId::next();
        let doc = spawn_document(id, CoreDocument::from_text("a\nb\n"), r.clone());
        let mut sources: HashMap<BufferId, Arc<dyn Document>> = HashMap::new();
        sources.insert(id, Arc::new(doc) as Arc<dyn Document>);
        let mb = MultibufferDocumentHandle::new(sources, vec![Excerpt::new(id, 0, 1)], r).unwrap();
        let buf_id = mb.buffer_id();
        let folds = FileBoundaryFoldProvider::new(mb, buf_id).compute_folds();
        assert_eq!(folds.len(), 1);
        assert!(folds[0].identity.is_some());
    }
}