Struct RopeDocumentHandle 

pub struct RopeDocumentHandle { /* private fields */ }

Cheap-clone handle to one document actor. All callers (App, renderer, future LSP clients, plugins) talk to the actor through a RopeDocumentHandle – there is no other way to reach the document’s writable state.

Implementations

impl RopeDocumentHandle

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

Load the current snapshot. The returned Arc lives as long as the caller needs it; the actor’s subsequent publishes don’t invalidate it. Renderers call this once per visible document per frame.

Costs ~17ns (one atomic acquire-load + one Arc bump). For hot paths that read the snapshot many times between edits, prefer Self::snapshot_cache – it caches the Arc per thread and brings the per-load cost to ~2ns.

pub fn snapshot_cache(&self) -> SnapshotCache

Build a per-thread cache for the snapshot read path. Each call returns a fresh crate::snapshot::SnapshotCache; threads that read the snapshot every frame should hold one of these on the stack of the read loop and call load() on it instead of going through Self::snapshot.

Wait-free thread-local-cached: when the writer hasn’t changed the snapshot since the last load, the call is one Relaxed atomic compare and returns a borrowed Arc reference at no further cost (~2ns). When the writer has published, the next load reloads + caches the new Arc.

pub fn id(&self) -> DocumentId

Convenience: id (stable for the actor’s lifetime).

pub fn text(&self) -> String

Convenience: rendered text. Allocates – prefer snapshot().buffer.as_string() on a held snapshot when looping.

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

Convenience: path (clone of the Arc<PathBuf> slice).

pub fn dirty(&self) -> bool

Convenience: dirty flag.

pub fn version(&self) -> u64

pub fn text_version(&self) -> u64

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

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

Apply one edit. Resolves to the resulting AppliedEdit (range info + replaced text) once the actor commits.

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

Apply multiple edits as one undo unit.

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

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

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

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

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

pub fn begin_undo_group(&self)

Open an undo-coalescing group on the actor so a run of edits (a vim insert session) collapses into a single undo unit until Self::end_undo_group. Fire-and-forget – ordering against the following apply_edit burst is guaranteed by the FIFO mailbox, so there is nothing to await. A closed receiver (actor gone) is a silent no-op: there is nothing to coalesce on a dead actor.

pub fn end_undo_group(&self)

Close the group opened by Self::begin_undo_group. Same fire-and-forget semantics.

pub fn dispatch( &self, invocation: CommandInvocation, cursor: Position, ) -> Pending<Effect>

Dispatch a [CommandInvocation] through [lattice_grammar::execute] inside the actor. The actor holds the only &mut Document so all grammar-driven mutations route here. The returned Effect is for the App to apply to its session-scoped state (registers, modal transitions, marks, etc.).

This form uses a no-op CancellationToken::never(); the dispatch will run to completion. Use Self::dispatch_with_cancel when the caller needs to cancel a long-running motion / operator on user Esc.

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

Like Self::dispatch but routes a caller-owned CancellationToken into the grammar execute call. The caller keeps a clone and flips it (e.g. on user Esc) to short-circuit a long-running motion / operator. Per DESIGN.md §5.7, cancellation is cooperative – the grammar polls at quantisation points (per-row in blockwise ops, per match in search loops, etc.).

pub fn dispatch_with_env( &self, invocation: CommandInvocation, cursor: Position, cancel: CancellationToken, env: DispatchEnv, ) -> Pending<Effect>

N.1.4b / N.1.6 (2026-06-10): the env-carrying dispatch entry. Threads the DispatchEnv (the tree-sitter scope_resolver for af/ac/aa/al + the comment_syntax for aC/iC) into [ActorMsg::Dispatch] so the actor hands it to execute_with_env. The env’s Arc fields cross the actor channel as Arc bumps; the snapshot is immutable so the actor reads it wait-free. Staleness note: the resolver reflects the last-published syntax tree, which may trail the actor’s rope by an in-flight edit – acceptable eventual consistency (CLAUDE.md), never a blocking reparse on the hot path (paramount #1).

pub fn buffer_id(&self) -> BufferId

M.2.b.0.A (2026-05-31): registry-level identity of this handle. Stable for the handle’s lifetime.

Trait Implementations

impl Clone for RopeDocumentHandle

fn clone(&self) -> RopeDocumentHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RopeDocumentHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RopeDocumentHandle

Placeholder handle for Editor::default() headless / test scaffolding. The receiver is dropped immediately, so any message sent through this handle silently fails (the caller’s reply oneshot drops without being completed, reported as “actor gone” by the typed wrappers). Production handles come from spawn_document; Editor::new(...) overwrites this slot before any traffic flows.

fn default() -> Self

Returns the “default value” for a type.

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.

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

fn end_undo_group(&self)

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

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

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.

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.

fn excerpt_syntax_version(&self) -> u64

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