Crate lattice_mode

Expand description

The mode system’s foundation: the Mode trait, the mode registry, the per-buffer set of active modes, and the typed lifecycle events — plus the generic host seams a mode uses to own its whole surface (action handlers, services, inbound wakes, buffer creation) and the foundation modes that have no other owning crate.

The major / minor mode system is the primary customization mechanism (DESIGN.md §5.8, docs/dev/architecture/mode-architecture.md). A buffer has exactly one major mode (content-type identity: rust-mode, help-mode’s markdown major, messages-mode) and any number of minor modes layered over it (line-numbers-mode, table-mode, emacs-keys-mode). A mode contributes declaratively — option overrides, a keymap layer, completion sources, gutter signs, action handlers — and imperatively through one lifecycle hook whose returned Guard is the only cleanup path.

§What this crate owns

The contract. Mode (and its object-safe adapter DynMode), ModeId, ModeKind, ActivationPolicy, EditableTail, CapabilitySet, ModeContext, LifecycleFuture and ModeActivationError.
Activation. ModeRegistry registers modes and drives activation / deactivation against a buffer’s ActiveModes, stashing each activation’s Guard in a GuardStoreHandle. Observable transitions (MajorEntered / MinorActivated / …) ride the protocol Event enum; internal failures ride ModeEvent.
The host seams a mode needs to own its surface without depending on the host. ServiceRegistry (typed services), ActionHandlerRegistry (chord bodies), ModeActivator and BufferStore (buffer creation / lookup), SubsystemBoot (a subsystem’s one-line install), inbound and TickCallbackRegistry (off-keystroke results that wake the editor), idle_gate (armed deadlines), ProviderViewRegistry (open a provider’s view), ForegroundCancel, and the producer registries for plugin-backed content (MediaSourceRegistry, ContextSourceRegistry, GutterDecorationSourceRegistry, ScannedExcerptSourceRegistry, BufferScopeSourceRegistry).
Shared render-facing vocabularies a mode writes without seeing a renderer: gutter signs (SignRegistry, GutterDecoration), the modeline element model (ModelineService, ModelineElementUpdate), async highlight / inlay hand-off (PendingSyntheticHighlights, PendingInlays), buffer-locals (BufferLocals).
Foundation modes (modes, registered by register_foundation_modes): text-mode, help-mode, hover-mode, messages-mode, image-mode, the completion and display minors, table-mode, surround-mode, which-key-mode, and the shared minors that own one chord for a whole class of view (RefreshableViewMode gr, FoldableViewMode <Tab>, ReplMode, EmacsKeysMode). Feature-crate modes live with their feature (lattice-lsp, lattice-listing, lattice-magit, …).

§What it must not depend on, and why

Nothing above it: not lattice-host, no renderer (lattice-ui-tui, lattice-ui-gpui), no feature crate. Every feature crate depends on this one to declare its modes, and the host depends on every feature crate, so a dependency upward is a cycle — and, more to the point, it is the structural guarantee that a mode can own its keymap, handler bodies, buffers and async wakes without an Editor:: method or a host Action variant (the mode-ownership acid test). Where a mode needs the host, the host implements a trait defined here (ModeActivator, BufferStore, SubsystemBoot) or registers a service. Its own dependencies are the substrate below: protocol, core, grammar, keymap, config, completion, runtime, cells.

§Example: a minimal minor mode

use lattice_core::BufferKind;
use lattice_mode::{
    ActivationPolicy, LifecycleFuture, Mode, ModeContext, ModeId, ModeKind, ModeRegistry,
    OptionOverrideSet,
};

/// Wraps long lines in prose buffers.
struct ProseMode;

impl Mode for ProseMode {
    type Guard = (); // nothing to clean up
    fn id(&self) -> ModeId {
        ModeId::new("prose-mode")
    }
    fn kind(&self) -> ModeKind {
        ModeKind::Minor
    }
    fn options(&self) -> OptionOverrideSet {
        lattice_config::overrides! { lattice_config::Wrap = true, }
    }
    fn activation_policy(&self) -> ActivationPolicy {
        ActivationPolicy::Majors(vec![ModeId::new("markdown-mode")])
    }
    fn on_activate(&self, _ctx: ModeContext) -> LifecycleFuture<'_, ()> {
        Box::pin(async { Ok(()) })
    }
}

let mut registry = ModeRegistry::new();
let id = registry.register(ProseMode).unwrap();
// The host's minor resolver asks this when a buffer enters a major.
assert_eq!(registry.auto_activatable_minors("markdown-mode", BufferKind::Document), vec![id]);
assert!(registry.auto_activatable_minors("rust-mode", BufferKind::Document).is_empty());

The Mode docs carry the full lifecycle (registration → activation → deactivation) as a runnable example; SubsystemBoot shows a whole subsystem install with an off-thread producer.

§Design documents

docs/dev/architecture/mode-architecture.md — the mode model, activation, Guards, option layering (§5–§9).
docs/dev/architecture/boot-composition.md — SubsystemBoot, the inbound primitive and why the wake lives in the sender (§3).
docs/dev/architecture/keymap-architecture.md — keymap layers.
docs/dev/architecture/modeline.md — the modeline element model.
docs/dev/architecture/cancellation.md — ForegroundCancel.

Re-exports§

pub use crate::action_handler_registry::ActionContext;
pub use crate::action_handler_registry::ActionHandler;
pub use crate::action_handler_registry::ActionHandlerContribution;
pub use crate::action_handler_registry::ActionHandlerRegistration;
pub use crate::action_handler_registry::ActionHandlerRegistry;
pub use crate::action_handler_registry::ActionHandlerRegistryHandle;
pub use crate::activator::ModeActivator;
pub use crate::activator::VirtualRowRegistrar;
pub use crate::active::ActiveModes;
pub use crate::buffer_store::BufferStore;
pub use crate::buffer_store::BufferStoreHandle;
pub use crate::capability::CapabilitySet;
pub use crate::context::ModeContext;
pub use crate::context_source::AsyncContextSource;
pub use crate::context_source::ContextFuture;
pub use crate::context_source::ContextSourceRegistry;
pub use crate::context_source::ContextSourceRegistryHandle;
pub use crate::contributions::BUILTIN_SIGN_COLUMNS;
pub use crate::contributions::BuiltinSignIds;
pub use crate::contributions::CompilationSeverityData;
pub use crate::contributions::DIAGNOSTIC_ERROR_PRIORITY;
pub use crate::contributions::DIAGNOSTIC_HINT_PRIORITY;
pub use crate::contributions::DIAGNOSTIC_INFO_PRIORITY;
pub use crate::contributions::DIAGNOSTIC_WARNING_PRIORITY;
pub use crate::contributions::DIFF_SIGN_PRIORITY;
pub use crate::contributions::DecorationCtx;
pub use crate::contributions::DecorationProvider;
pub use crate::contributions::DiagnosticGlyphs;
pub use crate::contributions::GutterDecoration;
pub use crate::contributions::GutterDiffKind;
pub use crate::contributions::GutterSeverityLevel;
pub use crate::contributions::SIGN_COLUMN_DIFF;
pub use crate::contributions::SIGN_COLUMN_MARK;
pub use crate::contributions::SignDefinition;
pub use crate::contributions::SignId;
pub use crate::contributions::SignRegistry;
pub use crate::contributions::SignRegistryHandle;
pub use crate::contributions::Subscription;
pub use crate::contributions::register_builtin_signs;
pub use crate::contributions::winning_sign;
pub use crate::decoration_source::AsyncGutterDecorationSource;
pub use crate::decoration_source::DecorationEpoch;
pub use crate::decoration_source::DecorationEpochHandle;
pub use crate::decoration_source::DecorationFuture;
pub use crate::decoration_source::GutterDecorationSourceRegistry;
pub use crate::decoration_source::GutterDecorationSourceRegistryHandle;
pub use crate::error::ModeActivationError;
pub use crate::event::ModeEvent;
pub use crate::guards::GuardStore;
pub use crate::guards::GuardStoreHandle;
pub use crate::locals::BufferLocal;
pub use crate::locals::BufferLocals;
pub use crate::locals::BufferScopeDir;
pub use crate::locals::BufferScopeSource;
pub use crate::locals::BufferScopeSourceRegistry;
pub use crate::locals::BufferScopeSourceRegistryHandle;
pub use crate::locals::LocalDescriptor;
pub use crate::media_source::AsyncMediaSource;
pub use crate::media_source::MediaBlockRequest;
pub use crate::media_source::MediaFuture;
pub use crate::media_source::MediaSourceRegistry;
pub use crate::media_source::MediaSourceRegistryHandle;
pub use crate::mode::ActivationPolicy;
pub use crate::mode::DynMode;
pub use crate::mode::EditableTail;
pub use crate::mode::LifecycleFuture;
pub use crate::mode::Mode;
pub use crate::mode::ModeKind;
pub use crate::modes::ActiveCompletionSources;
pub use crate::modes::BufferWordsMode;
pub use crate::modes::CompletionMode;
pub use crate::modes::CompletionPopupMode;
pub use crate::modes::HelpMode;
pub use crate::modes::HoverMode;
pub use crate::modes::MessagesMode;
pub use crate::modes::PathCompletionMode;
pub use crate::modes::TextMode;
pub use crate::modes::register_foundation_modes;
pub use crate::modes::register_help_mode_actions;
pub use crate::operator_chord::OperatorChordWirer;
pub use crate::operator_chord::OperatorChordWirerHandle;
pub use crate::modes::table::mode::TableMode;
pub use crate::modes::table::mode::register_table_actions;
pub use crate::modes::table::mode::register_table_mode;
pub use crate::plugin_meta_sink::PluginMetaSink;
pub use crate::plugin_meta_sink::PluginMetaSinkHandle;
pub use crate::provider_view::ProviderViewOpener;
pub use crate::provider_view::ProviderViewOutcome;
pub use crate::provider_view::ProviderViewRegistry;
pub use crate::provider_view::ProviderViewRegistryHandle;
pub use crate::scanned_excerpt_source::ClockSpan;
pub use crate::scanned_excerpt_source::RowAnnotation;
pub use crate::scanned_excerpt_source::ScanBeginFuture;
pub use crate::scanned_excerpt_source::ScanDescribeFuture;
pub use crate::scanned_excerpt_source::ScanFuture;
pub use crate::scanned_excerpt_source::ScanResult;
pub use crate::scanned_excerpt_source::ScannedExcerpt;
pub use crate::scanned_excerpt_source::ScannedExcerptSource;
pub use crate::scanned_excerpt_source::ScannedExcerptSourceRegistry;
pub use crate::scanned_excerpt_source::ScannedExcerptSourceRegistryHandle;
pub use crate::services::ServiceRegistry;
pub use crate::startup::Startup;
pub use crate::subsystem_boot::SubsystemBoot;
pub use crate::tick_callback::TickCallback;
pub use crate::tick_callback::TickCallbackRegistration;
pub use crate::tick_callback::TickCallbackRegistry;
pub use crate::tick_callback::TickCallbackRegistryHandle;
pub use crate::emacs_keys_mode::EmacsKeysMode;
pub use crate::emacs_keys_mode::emacs_keys_layer_bindings;
pub use crate::repl_mode::ReplMode;
pub use crate::repl_mode::register_repl_mode;
pub use crate::repl_mode::register_repl_mode_actions;
pub use crate::refreshable_view_mode::RefreshableViewMode;
pub use crate::refreshable_view_mode::VIEW_REFRESH_ACTION;
pub use crate::refreshable_view_mode::register_refreshable_view_actions;
pub use crate::refreshable_view_mode::register_refreshable_view_mode;
pub use crate::foldable_view_mode::FOLD_TOGGLE_DEFAULT_ACTION;
pub use crate::foldable_view_mode::FoldableViewMode;
pub use crate::foldable_view_mode::VIEW_FOLD_CYCLE_ACTION;
pub use crate::foldable_view_mode::VIEW_FOLD_TOGGLE_ACTION;
pub use crate::foldable_view_mode::register_foldable_view_actions;
pub use crate::foldable_view_mode::register_foldable_view_mode;
pub use crate::foreground_cancel::ForegroundCancel;
pub use crate::foreground_cancel::ForegroundCancelHandle;
pub use crate::modeline::ElementContent;
pub use crate::modeline::ElementId;
pub use crate::modeline::HoverSpec;
pub use crate::modeline::Interaction;
pub use crate::modeline::ModelineElement;
pub use crate::modeline::ModelineElementUpdate;
pub use crate::modeline::ModelineKey;
pub use crate::modeline::ModelineRegistry;
pub use crate::modeline::ModelineRole;
pub use crate::modeline::ModelineService;
pub use crate::modeline::ModelineServiceHandle;
pub use crate::modeline::ModelineSnapshot;
pub use crate::modeline::Scope;
pub use crate::modeline::Span;
pub use crate::modeline::Zone;
pub use crate::pending_inlays::InlayRow;
pub use crate::pending_inlays::PendingInlays;
pub use crate::pending_inlays::PendingInlaysHandle;
pub use crate::pending_synthetic_highlights::HighlightsOp;
pub use crate::pending_synthetic_highlights::PendingSyntheticHighlights;
pub use crate::pending_synthetic_highlights::PendingSyntheticHighlightsHandle;
pub use crate::registry::ModeRegistry;
pub use crate::registry::ModeRegistryHandle;
pub use crate::registry::RegistrationError;

Modules§

action_handler_registry: Action-handler registry — mode-contributed closures per CommandId (M.10.1).
activator: ModeActivator: synchronous activation surface for extension crates that create buffers and need their major / minor modes activated on the host side.
active: ActiveModes: the major + ordered minors set per buffer.
binding_mode: Re-export shim — BindingMode now lives in lattice-keymap.
buffer_store: BufferStore: host primitive for mode-owned buffer lifecycles.
capability: CapabilitySet: typed bitfield describing what a buffer can offer. Modes declare what they require via crate::Mode::required_capabilities; the registry validates the buffer satisfies all required bits before activation.
context: ModeContext: the handle passed to crate::Mode::on_activate.
context_source: The native seam for an async producer of structural context scopes (TC.2).
contributions: Declarative contributions on crate::Mode.
decoration_source: The async gutter-decoration producer seam (PL8.E).
emacs_keys_mode: emacs-keys-mode — a default-on builtin minor mode contributing an emacs-style <C-x> leader (a tribute layer). Design: docs/dev/architecture/emacs-keys.md; sequencing: docs/dev/operations/slice-plans/emacs-keys.md.
error: Errors surfaced by the registry’s activation / deactivation path.
event: Typed internal mode-dispatch signals.
foldable_view_mode: foldable-view-mode — the one place <Tab> folds the block at point.
foreground_cancel: The foreground-cancellation seam, as a registered service (CG.2).
guards: GuardStore: type-erased storage for per-(buffer, mode) Guards returned by Mode::on_activate.
idle_gate: Idle-gate registry — the generic armed-deadline primitive (WK.3).
inbound: Boot-composition BC.1: the generic inbound primitive.
keymap_entry: Static keymap catalog + keymap_entry! macro (DESIGN.md §5.2.3).
locals: Buffer-local mode-internal state — Shape A from mode-architecture.md §9.4 (M.3.2.a).
media_source: The registry of inline-media producers (IM.6b).
mode: The Mode trait, plus ModeId, ModeKind, and the LifecycleFuture type alias.
modeline: Modeline element model + descriptor registry (slice ML.0a).
modes: Foundation modes that ship with lattice-mode.
operator_chord: Wiring a plugin-registered operator’s chord into the grammar (CM.2).
pending_inlays: Mode-published inline virtual text (DL.3b).
pending_synthetic_highlights: Pending synthetic-buffer highlights mechanism (MG.2).
plugin_meta_sink: PluginMetaSink — the generic seam the plugin loader writes plugin provenance through (PL8.B).
provider_view: The provider-view seam — one generic host primitive for “open the multibuffer view a provider owns” (PV.1, 2026-08-12).
refreshable_view_mode: refreshable-view-mode — the one place gr means “refresh this view”.
registry: ModeRegistry: register modes, look them up, drive activation / deactivation against a per-buffer ActiveModes and an App-owned GuardStoreHandle.
repl_mode: repl-mode — a builtin minor mode contributing the REPL input surface.
scanned_excerpt_source: OM.A1 — the registry of agenda-row producers.
services: ServiceRegistry: typed lookup for subsystem handles that modes need access to from their lifecycle hooks (Phase 3 of the mode-architecture ModeContext extension).
startup: The generic boot-completion signal (design.md §9.1) (DB.5).
subsystem_boot: SubsystemBoot — the capability surface a subsystem wires against at boot.
tick_callback: IDE-protocol I1.1: tick-callback registry — the one generic host primitive the Claude Code IDE peer needs.

Macros§

keymap_entry: Construct a KeymapEntry with the row’s source location captured at the macro invocation site. Forms:

Structs§

Keymap: A mode’s full keymap contribution.
KeymapBinding: One mode-contributed keymap binding.
KeymapEntry: One row in the catalog. Ordering of fields matches the rendering order in :describe-key so reading one field at a time still tells a coherent story.
ModeId: Canonical identity of a mode. Interned-string for Copy + Eq + Hash at zero allocation cost on the hot path.
OptionOverride: One option-value override from a single layer producer (a mode, a buffer-local set, a modal-state hook).
OptionOverrideSet: A set of OptionOverrides contributed by one layer producer (typically the return value of Mode::options()).

Enums§

BindingMode: Where a binding takes effect. Multi-key sequences (e.g. gg) resolve atomically; intermediate single-key prefixes (g, z) get their own descriptor entries so :describe-key g explains the pending substate.
OverridePriority: Tie-break priority for two layer entries that target the same option.