lattice_runtime/

document.rs

//! M.0 (2026-05-31): `Document` trait — the handle-layer
//! abstraction over a buffer that the rest of the editor talks
//! to.
//!
//! Today's `RopeDocumentHandle` (a rope-backed actor handle) impls
//! this trait; M.1 lands `MultibufferDocumentHandle` as a sibling
//! impl composing N source handles. Dispatch / motion / render
//! code paths hold `Arc<dyn Document>` so they serve both kinds
//! without kind-branching at the buffer boundary.
//!
//! See `docs/dev/architecture/multibuffer-views.md` §3.1 for the
//! design and the Path-A/B/C alternatives that were considered
//! and rejected.
//!
//! ## Slot replacement is the only path
//!
//! There is intentionally no `replace(...)` method on this trait.
//! Per the M.0 design (§3.1 "Why no `replace`"), "the active
//! document changes" is expressed by replacing the slot's
//! `Arc<dyn Document>` with a freshly spawned handle, not by
//! mutating the existing handle in place. The old handle drops
//! when its last Arc reference goes away; the actor task exits
//! cleanly through its mailbox-close branch. One uniform code
//! path for `:edit foo` / `:edit bar` / regular ↔ multibuffer
//! transitions / `:b N` switches.
//!
//! ## Object safety
//!
//! Trait is `dyn`-safe: `Arc<dyn Document>` is the canonical
//! reference shape. All methods take `&self` (writes return
//! `Pending<T>` which round-trips the impl's internal write
//! path — actor mpsc for `RopeDocumentHandle`, fan-out for
//! `MultibufferDocumentHandle`).
//!
//! Most read methods carry default implementations derived from
//! `snapshot()` so impls only need to provide `snapshot()` plus
//! the write methods. `MultibufferDocumentHandle` may override
//! `text()` if it can compose more cheaply than `snapshot()
//! .text()`.

use std::path::PathBuf;
use std::sync::Arc;

use lattice_grammar::{CancellationToken, CommandInvocation, Effect};
use lattice_protocol::edit::Edit;
use lattice_protocol::ids::DocumentId;
use lattice_protocol::position::Position;
use lattice_protocol::selection::SelectionSet;

use crate::actor::AppliedEdit;
use crate::handle::RopeDocumentHandle;
use crate::pending::Pending;
use crate::snapshot::{DocumentSnapshot, SnapshotCache};

/// N.1.4b (2026-06-10): a sharable, thread-safe scope resolver
/// handle threaded through grammar dispatch. The host wraps the
/// active document's `Arc<SyntaxSnapshot>` (which impls
/// `lattice_grammar::ScopeResolver`) in this alias, bundles it into a
/// [`DispatchEnv`], and passes it to [`Document::dispatch_with_env`];
/// the actor hands it to `execute_with_env` so tree-sitter text objects
/// (af/ac/aa/al) resolve against the live tree. `Send + Sync`
/// because the actor message crosses the dispatch channel onto the
/// document-actor thread. The bare `ScopeResolver` trait lives in
/// `lattice-grammar` (tree-sitter-agnostic); this threading-layer
/// alias adds the `Arc + Send + Sync` shape per the handle
/// convention (cf. `CommandRegistryHandle`).
pub type ScopeResolverHandle = Arc<dyn lattice_grammar::ScopeResolver + Send + Sync>;

/// IN.7: the same handle convention for the `=` operator's per-line
/// indent source. Owned + `Send + Sync` so it can cross the actor
/// channel; the grammar side sees a bare `&dyn IndentResolver`.
pub type IndentResolverHandle = Arc<dyn lattice_grammar::IndentResolver + Send + Sync>;

/// VM.3i: the same handle convention for `zj` / `zk`'s fold edges. The host
/// builds one from its fold table for a dispatch; the grammar sees a bare
/// `&dyn FoldResolver`.
pub type FoldResolverHandle = Arc<dyn lattice_grammar::FoldResolver + Send + Sync>;
/// VM.3e: owned mark table for `'x` / `` `x ``, like [`FoldResolverHandle`].
pub type MarkResolverHandle = Arc<dyn lattice_grammar::MarkResolver + Send + Sync>;
/// VM.3f: owned window lines for `H` / `M` / `L`, like [`FoldResolverHandle`].
pub type ViewportResolverHandle = Arc<dyn lattice_grammar::ViewportResolver + Send + Sync>;
/// VM.3g-2: owned display geometry for `gj` / `gk` / `g0` / `g$`.
pub type DisplayResolverHandle = Arc<dyn lattice_grammar::DisplayResolver + Send + Sync>;

/// N.1.6 (2026-06-10): the owned, thread-safe per-dispatch environment
/// for text objects, carried across the actor channel. Bundles the
/// inputs a text object's `apply` may read — the tree-sitter
/// `scope_resolver` (`af`/`ac`, N.1.4) and the `comment_syntax`
/// (`aC`/`iC`, N.1.6) — so the dispatch seam threads ONE value instead
/// of a widening parameter list (the long-term-fit choice over parallel
/// params). The actor borrows these into a `lattice_grammar::GrammarEnv`
/// at the `execute_with_env` call. `Default` is the no-input case.
#[derive(Clone, Default)]
pub struct DispatchEnv {
    pub scope_resolver: Option<ScopeResolverHandle>,
    pub comment_syntax: Option<Arc<lattice_grammar::CommentSyntax>>,
    /// OT.4: the buffer's tree-sitter snapshot, type-erased so
    /// `lattice-runtime` stays syntax-free (the plugin trampoline
    /// downcasts it back to an `Arc<SyntaxSnapshot>`).
    ///
    /// Distinct from `scope_resolver` rather than replacing it, and the
    /// distinction is why this field had to exist. The resolver answers
    /// "what scope encloses this point" for the NATIVE structural objects
    /// and is deliberately erased to that one question — the concrete
    /// snapshot cannot be recovered from it, so it cannot mint a plugin's
    /// `tree-snapshot` resource.
    ///
    /// TS.1 left this out because grammar *actions* were the only
    /// tree-snapshot consumer, and those dispatch through the host's Action
    /// gate rather than this channel. OT.1 made motions and text objects
    /// consumers too, and they come through here — so without this field
    /// org's `ar` / `]]` / `g{` received `none` on every real keystroke
    /// while every test that built a `GrammarEnv` by hand passed.
    pub syntax: Option<Arc<dyn std::any::Any + Send + Sync>>,
    /// IN.0: one level of indentation, resolved by the host from
    /// `shiftwidth` / `expandtab` / `tabstop`. Read by `>` / `<`.
    /// `Default` is the registered option defaults, so the actor path
    /// indents like an unconfigured buffer rather than not at all.
    pub indent: lattice_core::IndentUnit,
    /// IN.7: per-line indent depth for `=`. `None` means no
    /// structural source, and `=` reindents nothing rather than
    /// guessing.
    pub indent_resolver: Option<IndentResolverHandle>,
    /// RF.2: the buffer's `textwidth`, for the reflow operator. Carried
    /// here for the reason `syntax` and `selection` had to be: `gq`
    /// reaches the grammar through the ACTOR path on every real
    /// keystroke, so a field missing here is a field the operator never
    /// sees no matter how well the direct path is tested.
    ///
    /// `WrapWidth`, not `usize`, so this struct keeps its derived
    /// `Default` and still means 80 rather than 0.
    pub textwidth: lattice_core::WrapWidth,
    /// RF.5b: which formatting intents this buffer handles natively.
    /// Carried for the reason `textwidth` is: `=` and `gq` reach the
    /// grammar through the ACTOR path on every real keystroke.
    pub native_format: lattice_grammar::registry::NativeFormatIntents,
    /// OS.2: the active region — the Visual/Select selection extent, or `None`
    /// outside Visual/Select.
    ///
    /// Carried here for the reason `syntax` above had to be: an action reached
    /// through the ACTOR path builds its `ActionContext` from this env, so a
    /// hard `None` would make a plugin's Visual action see no region on every
    /// real keystroke while every test that hand-built a `GrammarEnv` passed.
    /// That is the OT.4 failure verbatim, and it is cheaper to carry the field
    /// than to rediscover it.
    pub selection: Option<lattice_protocol::position::Range>,
    /// VM.3c: the last `f` / `F` / `t` / `T`, so `;` and `,` can be motions.
    ///
    /// Same reasoning as every field above it: `;` is an ordinary motion on
    /// the keystroke path, so it comes through the actor, so the state it
    /// needs has to travel with the dispatch. `None` is the pre-first-`f`
    /// state and makes `;` a no-op, which is what vim does.
    pub last_find: Option<lattice_grammar::LastFind>,
    /// VM.3i: the fold edges `zj` / `zk` step between. Same reasoning as
    /// `last_find`: they're motions on the keystroke path, so they come
    /// through the actor. `None` for a buffer with no folds.
    pub fold_resolver: Option<FoldResolverHandle>,
    /// VM.3d-2: the last search, for `n` / `N` / `*` / `#`, which are motions
    /// on the keystroke path and so come through the actor too.
    pub last_search: Option<lattice_grammar::LastSearch>,
    /// VM.3e: the mark table, for `'x` / `` `x ``, which come through the
    /// actor like every keystroke motion. `None` when no mark is set.
    pub marks: Option<MarkResolverHandle>,
    /// VM.3f: the lines the window shows, for `H` / `M` / `L`. The host builds
    /// it only when the invocation is one of them.
    pub viewport: Option<ViewportResolverHandle>,
    /// VM.3f: `!startofline` — `H` / `M` / `L` keep the cursor's column.
    pub nostartofline: bool,
    /// VM.3f: `scrolloff`, the margin `H` / `L` stop short of the window's
    /// edges by. `0` puts them on the first and last lines shown.
    pub scrolloff: u32,
    /// VM.3g-1: vim's `curswant`, the column `j` / `k` aim for across short
    /// lines. Carried like every other keystroke input: `j` comes through the
    /// actor on every press.
    pub curswant: Option<lattice_grammar::Curswant>,
    /// VM.3g-2: display geometry for `gj` / `gk` / `g0` / `g$`, built only when
    /// the invocation is one of them.
    pub display: Option<DisplayResolverHandle>,
    /// VM.3g-3: where a motion reports the goal column it AIMED at, which for
    /// `gj` / `gk` is not the column it reached — the display row it lands on
    /// may be too short, and vim keeps the aim (measured: a clamped `gj`
    /// landing at column 100 records `curswant` 160).
    ///
    /// Owned rather than borrowed, unlike its `GrammarEnv` counterpart, and
    /// that is forced rather than chosen: this struct crosses the `Document`
    /// trait into a `Pending<Effect>`, so a borrow could not outlive the
    /// future. The actor borrows it back out at the `execute_with_env` call,
    /// which is the same shape every other field here already has.
    ///
    /// `None` — the default — discards the report, which is right for every
    /// caller that keeps no goal column.
    pub curswant_out: Option<Arc<std::sync::Mutex<Option<lattice_grammar::Curswant>>>>,
}

/// Handle-layer abstraction over a buffer. See module docs.
///
/// `Debug` is a supertrait so containers holding `dyn Document`
/// (e.g., `lattice_host::buffer_registry::DocumentEntry`) can
/// derive `Debug` without hand-rolling per-field formatters.
pub trait Document: Send + Sync + 'static + std::fmt::Debug {
    // ---- Reads (wait-free, snapshot-backed) ----

    /// Load the current snapshot. The returned `Arc` lives as
    /// long as the caller needs it; subsequent publishes don't
    /// invalidate it.
    fn snapshot(&self) -> Arc<DocumentSnapshot>;

    /// Per-thread cache for hot loops that load the snapshot
    /// many times between edits. The cache reduces per-load cost
    /// from ~17 ns to ~2 ns when the writer hasn't published
    /// since the last load.
    fn snapshot_cache(&self) -> SnapshotCache;

    fn id(&self) -> DocumentId {
        self.snapshot().id
    }

    /// Rendered text. Allocates — prefer `snapshot().buffer
    /// .as_string()` on a held snapshot when looping.
    fn text(&self) -> String {
        self.snapshot().text()
    }

    fn path(&self) -> Option<PathBuf> {
        self.snapshot().path.as_ref().map(|a| (**a).clone())
    }

    fn dirty(&self) -> bool {
        self.snapshot().dirty
    }

    fn version(&self) -> u64 {
        self.snapshot().version
    }

    fn text_version(&self) -> u64 {
        self.snapshot().text_version
    }

    fn selections(&self) -> Arc<SelectionSet> {
        self.snapshot().selections.clone()
    }

    // ---- Writes (enqueue + Pending) ----

    fn apply_edit(&self, edit: Edit) -> Pending<AppliedEdit>;

    fn apply_edit_batch(&self, edits: Vec<Edit>) -> Pending<Vec<AppliedEdit>>;

    fn undo(&self) -> Pending<Vec<AppliedEdit>>;

    fn redo(&self) -> Pending<Vec<AppliedEdit>>;

    fn save(&self) -> Pending<PathBuf>;

    fn save_as(&self, path: PathBuf) -> Pending<()>;

    fn set_selections(&self, selections: SelectionSet) -> Pending<()>;

    /// Open an undo-coalescing group so a run of edits (a vim insert
    /// session: `i`/`a`/`o`/`cw` .. `<Esc>`) collapses into a single
    /// undo unit until [`Self::end_undo_group`]. Fire-and-forget:
    /// ordering against the following edits is the impl's responsibility
    /// (the actor mailbox is FIFO), so there is nothing to await.
    ///
    /// Default no-op. Buffer kinds without a first-class undo stack --
    /// the `MultibufferDocumentHandle` and the default placeholder
    /// handle -- ignore grouping; `RopeDocumentHandle` overrides both to
    /// signal its actor. A no-op default keeps grouping non-regressive
    /// for those kinds (their edits remain individually undoable, as
    /// today) without every impl having to opt in.
    fn begin_undo_group(&self) {}

    /// Close the group opened by [`Self::begin_undo_group`]. Default
    /// no-op; see that method.
    fn end_undo_group(&self) {}

    // ---- Grammar dispatch ----

    /// Dispatch a [`CommandInvocation`] through the impl's
    /// internal grammar execution path. `MultibufferDocument
    /// Handle` (M.1) routes the invocation through its
    /// row-translation table to the underlying source(s).
    fn dispatch_with_cancel(
        &self,
        invocation: CommandInvocation,
        cursor: Position,
        cancel: CancellationToken,
    ) -> Pending<Effect>;

    /// N.1.4b / N.1.6 (2026-06-10): dispatch carrying a [`DispatchEnv`]
    /// (tree-sitter `scope_resolver` for af/ac/aa/al + `comment_syntax`
    /// for aC/iC) so the grammar resolves those text objects against the
    /// caller's live syntax + language. The default impl ignores the env
    /// and delegates to [`Self::dispatch_with_cancel`] -- correct for
    /// buffer kinds with no syntax / no leader (oil, terminal,
    /// plain-language). `RopeDocumentHandle` overrides it to forward the
    /// env into the actor's `execute_with_env` call; the multibuffer
    /// overrides `dispatch_with_cancel` (N.1.5) and ignores this env.
    fn dispatch_with_env(
        &self,
        invocation: CommandInvocation,
        cursor: Position,
        cancel: CancellationToken,
        env: DispatchEnv,
    ) -> Pending<Effect> {
        let _ = env;
        self.dispatch_with_cancel(invocation, cursor, cancel)
    }

    /// Convenience: dispatch with a never-cancelled token.
    fn dispatch(&self, invocation: CommandInvocation, cursor: Position) -> Pending<Effect> {
        self.dispatch_with_cancel(invocation, cursor, CancellationToken::never())
    }

    /// K.4.6 follow-up (2026-06-02): per-composed-row source line
    /// number lookup for the gutter. `None` (default) = identity:
    /// the composed-row index IS the source line number, so the
    /// gutter formats `composed_row` directly. `Some(arr)` =
    /// composed→source map: `arr[composed_row]` gives the source
    /// line number to display.
    ///
    /// Regular `RopeDocumentHandle` keeps the default None impl —
    /// for a single-file buffer, composed_row == source_row.
    /// `MultibufferDocumentHandle` (lattice-multibuffer) overrides
    /// to return the flattened `RowTranslation` so the gutter
    /// shows the original file's line numbers (e.g. 429, 430,
    /// 432 — skipping non-hit rows) rather than the meaningless
    /// composed indices (0, 1, 2).
    ///
    /// Substrate-aligned per [[feedback_buffers_no_special_case]]:
    /// the publisher reads `self.document.display_line_numbers()`
    /// uniformly across all BufferKinds; no renderer-side or
    /// publish-side kind branch needed.
    fn display_line_numbers(&self) -> Option<Arc<[u32]>> {
        None
    }

    /// K.4.7: per-excerpt highlight entries for multibuffer panes.
    /// Default returns empty — regular single-file documents carry
    /// no excerpt structure.  `MultibufferDocumentHandle` overrides
    /// to return one entry per excerpt that has a `SyntaxHandle`.
    ///
    /// The cells worker calls this uniformly on every pane's document;
    /// no `BufferKind` branch needed in `publish_render_state`.
    fn excerpt_highlights(&self) -> Vec<lattice_cells::ExcerptHighlight> {
        Vec::new()
    }

    /// Monotonic counter that bumps whenever the excerpt highlight set
    /// changes (new sources added, lang registry wired).  Default: 0.
    fn excerpt_syntax_version(&self) -> u64 {
        0
    }
}

/// M.0 (2026-05-31): the active-document slot held by
/// `Editor.document`. Wraps an `Arc<dyn Document>` so that:
///
/// * The slot can hold either a regular rope-backed handle
///   (today: `RopeDocumentHandle`, renamed to `RopeDocumentHandle`
///   in M.0 Phase E) or a `MultibufferDocumentHandle` (M.1)
///   without kind-branching at the use site — dispatch /
///   motion / render code paths just call `Document` trait
///   methods through `Deref<Target = dyn Document>`.
///
/// * The slot impls `Default` (initialised to a placeholder
///   rope handle via `RopeDocumentHandle::default()`) so consumers
///   that `#[derive(Default)]` over a struct containing this
///   field work without hand-rolling the impl. The
///   placeholder's actor receiver is closed immediately at
///   construction, so any traffic sent through the placeholder
///   reports `RuntimeError::ActorGone` — production code
///   overwrites the slot before any real traffic flows.
///
/// * The newtype is cheap to clone (one atomic refcount bump
///   on the inner `Arc`).
///
/// `Arc<dyn Document>` directly cannot implement `Default`
/// (orphan rule on `Arc` + `dyn Trait: !Sized`), so this
/// newtype is the smallest viable wrapper that keeps the
/// derive ergonomics intact without forcing a manual
/// `impl Default` over every struct that holds the slot.
#[derive(Clone)]
pub struct ActiveDocument(Arc<dyn Document>);

impl ActiveDocument {
    /// Wrap a concrete document handle. The handle must impl
    /// `Document` (today: `RopeDocumentHandle` / future
    /// `RopeDocumentHandle`; M.1: `MultibufferDocumentHandle`).
    pub fn new<D: Document>(handle: D) -> Self {
        Self(Arc::new(handle))
    }

    /// Wrap an already-`Arc`'d handle. Useful when an
    /// `Arc<dyn Document>` is constructed elsewhere (e.g., by
    /// the buffer registry) and the slot just takes ownership
    /// of it.
    pub fn from_arc(arc: Arc<dyn Document>) -> Self {
        Self(arc)
    }

    /// Cheap clone of the inner `Arc`. Use when handing the
    /// reference off to a long-lived consumer that wants to
    /// store it independently.
    pub fn as_arc(&self) -> Arc<dyn Document> {
        Arc::clone(&self.0)
    }
}

impl Default for ActiveDocument {
    fn default() -> Self {
        Self(Arc::new(RopeDocumentHandle::default()))
    }
}

impl std::ops::Deref for ActiveDocument {
    type Target = dyn Document;

    fn deref(&self) -> &Self::Target {
        &*self.0
    }
}

impl std::fmt::Debug for ActiveDocument {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_tuple("ActiveDocument").field(&self.0.id()).finish()
    }
}