Trait Document 

pub trait Document:
    Send
    + Sync
    + 'static
    + Debug {
    // Required methods
    fn snapshot(&self) -> Arc<DocumentSnapshot> ;
    fn snapshot_cache(&self) -> SnapshotCache;
    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<()> ;
    fn dispatch_with_cancel(
        &self,
        invocation: CommandInvocation,
        cursor: Position,
        cancel: CancellationToken,
    ) -> Pending<Effect> ;

    // Provided methods
    fn id(&self) -> DocumentId { ... }
    fn text(&self) -> String { ... }
    fn path(&self) -> Option<PathBuf> { ... }
    fn dirty(&self) -> bool { ... }
    fn version(&self) -> u64 { ... }
    fn text_version(&self) -> u64 { ... }
    fn selections(&self) -> Arc<SelectionSet>  { ... }
    fn begin_undo_group(&self) { ... }
    fn end_undo_group(&self) { ... }
    fn dispatch_with_env(
        &self,
        invocation: CommandInvocation,
        cursor: Position,
        cancel: CancellationToken,
        env: DispatchEnv,
    ) -> Pending<Effect>  { ... }
    fn dispatch(
        &self,
        invocation: CommandInvocation,
        cursor: Position,
    ) -> Pending<Effect>  { ... }
    fn display_line_numbers(&self) -> Option<Arc<[u32]>> { ... }
    fn excerpt_highlights(&self) -> Vec<ExcerptHighlight> { ... }
    fn excerpt_syntax_version(&self) -> u64 { ... }
}

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.

Required Methods

fn snapshot(&self) -> Arc<DocumentSnapshot>

Load the current snapshot. The returned Arc lives as long as the caller needs it; subsequent publishes don’t invalidate it.

fn snapshot_cache(&self) -> SnapshotCache

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 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<()>

fn dispatch_with_cancel( &self, invocation: CommandInvocation, cursor: Position, cancel: CancellationToken, ) -> Pending<Effect>

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).

Provided Methods

fn id(&self) -> DocumentId

fn text(&self) -> String

Rendered text. Allocates — prefer snapshot().buffer .as_string() on a held snapshot when looping.

fn path(&self) -> Option<PathBuf>

fn dirty(&self) -> bool

fn version(&self) -> u64

fn text_version(&self) -> u64

fn selections(&self) -> Arc<SelectionSet>

fn begin_undo_group(&self)

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 end_undo_group(&self)

Close the group opened by Self::begin_undo_group. Default no-op; see that method.

fn dispatch_with_env( &self, invocation: CommandInvocation, cursor: Position, cancel: CancellationToken, env: DispatchEnv, ) -> 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( &self, invocation: CommandInvocation, cursor: Position, ) -> Pending<Effect>

Convenience: dispatch with a never-cancelled token.

fn display_line_numbers(&self) -> Option<Arc<[u32]>>

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 excerpt_highlights(&self) -> Vec<ExcerptHighlight>

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_syntax_version(&self) -> u64

Monotonic counter that bumps whenever the excerpt highlight set changes (new sources added, lang registry wired). Default: 0.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Document for RopeDocumentHandle

M.0 (2026-05-31): handle-layer [Document] trait impl. Delegates every method to the inherent method of the same name on RopeDocumentHandle via fully-qualified syntax — the trait is a thin abstraction over the existing API surface; callers gain Arc<dyn Document> polymorphism for free.