Crate lattice_multibuffer 

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.

Re-exports

pub use crate::events::MultibufferExcerptsReady;

pub use crate::install::install;

pub use crate::mode::MultibufferMode;

pub use crate::mode::register_multibuffer_ex_commands;

pub use crate::mode::register_multibuffer_modes;

pub use crate::motions::MultibufferMotionIds;

pub use crate::motions::register_multibuffer_motions;

pub use crate::registry::InMemoryMultibufferRegistry;

pub use crate::registry::MultibufferRegistry;

pub use crate::registry::MultibufferRegistryHandle;

pub use crate::view::create_multibuffer_view;

Modules

events

Crate-level multibuffer events.

install

BC.7 (2026-06-24): the crate-owned install(boot) entry point.

mode

M.2.b.2 (2026-06-01): MultibufferMode — the major mode bound to BufferKind::Multibuffer via H.2’s Mode::target_buffer_kind declaration.

motions

M.2.b.3 (2026-06-01): excerpt-jump motions.

providers

M.6 (2026-06-01) onwards: in-tree multibuffer providers.

registry

M.2.b.2 (2026-06-01): typed handle lookup for multibuffer views.

view

M.2.b.2 (2026-06-01): create_multibuffer_view — the atomic “make me a multibuffer view” entry point that providers (and tests) call.

Structs

Excerpt

One excerpt of a source document, identified by its source BufferId and an inclusive line range [start_line, end_line].

ExcerptFoldProvider

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.

ExcerptHeader

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

ExcerptId

Unique identity for an excerpt within a multibuffer. Stable for the excerpt’s lifetime; survives reorders / source-edit rebuilds.

FileBoundaryFoldProvider

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.

HeaderGroupFoldProvider

AF.1: one open [lattice_core::Fold] per header run — the rows a user sees under one header.

MultibufferDocumentHandle

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.

MultibufferExcerptHeaderProvider

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

MultibufferHeaderElementIds

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.

MultibufferHeaderlineChanged

M.4 (2026-06-01): published whenever a view’s headerline status changes. Renderers + status-line consumers subscribe via EventBus::subscribe_typed::<MultibufferHeaderlineChanged>.

MultibufferSourceClosed

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.

MultibufferSourceEdited

PD.7c: published when one of a multibuffer’s source buffers is edited — the peer of MultibufferSourceClosed, and it exists for the same reason.

MultibufferStatusProvider

Sticky headerline provider that surfaces the view’s HeaderlineStatus as a pinned row above line 0.

RowTranslation

Composed-row → source-row mapping. One entry per composed row, in display order. Rebuilt on every recompose.

Enums

ExcerptHeaderStyle

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.

FoldGrouping

AF.1: how a multibuffer view’s rows group for folding.

HeaderlineStatus

View-level headerline status. Rendered above the first excerpt (M.2.a MultibufferExcerptHeaderProvider extends to handle the view header in a later renderer slice).

MultibufferError

RowEntry

One row in the composed multibuffer view, mapped back to its source.

Constants

ELEM_EXCERPT_HEADER

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

ELEM_EXCERPT_HEADER_COUNT

Element name: the excerpt-header match-count foreground.

ELEM_EXCERPT_HEADER_EMPHASIS

Element name: the emphasised excerpt-header row’s backdrop.

ELEM_EXCERPT_HEADER_EMPHASIS_TITLE

Element name: the emphasised excerpt-header’s title foreground.

ELEM_EXCERPT_HEADER_PATH

Element name: the excerpt-header file-path / title foreground.

ELEM_STATUS_COMPLETE

Element name: the completed status row foreground (green).

ELEM_STATUS_FAILED

Element name: the failed status row foreground (red).

ELEM_STATUS_IN_PROGRESS

Element name: the in-progress status row foreground (neutral grey).

ELEM_STATUS_QUERY

Element name: the emphasised-term foreground (accent) — e.g. the project-search query woven into the status label.

Functions

compose_header_rows

Pure function from excerpt list → header virtual rows, under grouping.

default_header_cells

Default header-rendering: ── <title> ── (box-drawing rules). Empty title yields a row of box rules only.

multibuffer_excerpt_header_provider_id

multibuffer_expand_excerpt_at

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.

multibuffer_status_provider_id

register_multibuffer_theme_elements

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.