lattice_mode/

activator.rs

//! `ModeActivator`: synchronous activation surface for extension
//! crates that create buffers and need their major / minor modes
//! activated on the host side.
//!
//! M.2.b.2 (2026-06-01) introduces this trait so `lattice-multibuffer`
//! (and every future in-tree provider that ships within it) can
//! atomically insert + activate-major a buffer without depending on
//! `lattice-host` directly. The activation cascade requires `&mut Editor`
//! (it mutates per-buffer mode state, options cache, completion sources,
//! LSP wiring) — but extension crates can't import `lattice-host`'s
//! `Editor` type. This trait, living in `lattice-mode`, is the seam
//! both crates depend on.
//!
//! See `docs/dev/architecture/multibuffer-views.md` §3.7 + the H-series
//! deferral note in `docs/dev/architecture/kind-agnostic-buffers.md`
//! §10 for the design.

use std::sync::Arc;

use lattice_core::{BufferFlags, BufferId, BufferKind};

use crate::mode::ModeId;
use crate::services::ServiceRegistry;

/// Activation surface implemented by `lattice-host::Editor` and
/// consumed by extension crates that need to drive activation
/// without holding a typed `&mut Editor`.
///
/// All three methods run synchronously on the App thread (caller
/// owns `&mut Self`). The implementor is responsible for routing
/// the cascade's renderer signals into its own pending-signals
/// queue — extension crates never see `RendererSignal`, keeping
/// host-layer types out of `lattice-mode`.
///
/// Failures (mode not registered, missing capability, conflict)
/// are logged + swallowed by the impl (matching the existing
/// `Editor::activate_*` helpers' shape). Callers that need to
/// observe activation outcome subscribe to
/// [`crate::ModeEvent`] on the event bus.
pub trait ModeActivator {
    /// Activate the major mode bound to `kind` on `buffer`. Uses
    /// the [`crate::ModeRegistry::find_major_for_kind`] lookup
    /// (populated by `Mode::target_buffer_kind` declarations)
    /// to resolve the mode id. No-ops if a major is already
    /// active on the buffer (idempotency / preserve-intent).
    fn activate_major_for_kind(&mut self, buffer: BufferId, kind: BufferKind);

    /// Activate a minor mode by id on `buffer`. The mode must
    /// be registered. Idempotent: re-activating an already-active
    /// minor is a no-op.
    fn activate_minor_by_id(&mut self, buffer: BufferId, mode: ModeId);

    /// Deactivate a minor mode by id on `buffer`. Idempotent: a mode
    /// that is not active is a no-op.
    ///
    /// PD.4: the symmetric half of [`Self::activate_minor_by_id`], and
    /// it exists because a re-triggered provider view reuses its buffer.
    /// A view that was read-only for one query and is editable for the
    /// next has to be able to say so — without this, "open the staged
    /// diff, then open the working-tree diff" would leave the second one
    /// unwritable, and the cause would be invisible because the buffer
    /// looks identical.
    ///
    /// Default impl is a no-op so test activators that do not model
    /// mode state stay valid; the host impl forwards to
    /// `Editor::deactivate_mode_by_id`.
    fn deactivate_minor_by_id(&mut self, buffer: BufferId, mode: ModeId) {
        let _ = (buffer, mode);
    }

    /// Find-or-create a synthetic **named `Document`** buffer and
    /// activate `major` on it *by id* (no on-disk language detection),
    /// returning its [`BufferId`]. This is the reliable, `&mut`-backed
    /// creation seam a mode / provider uses to **provision its own
    /// buffer** — the creation of a mode-owned buffer is the mode's
    /// responsibility, triggered through here.
    ///
    /// Unlike [`crate::BufferStore`] (whose `&self` handle can only
    /// *find* an existing buffer — activating a mode mutates the mode
    /// registry / active-modes / options cache and needs `&mut`), this
    /// method actually creates: the host impl mints the `BufferId`,
    /// spawns an empty `Document`, registers it with `flags`, seeds
    /// mode-locals, and runs `major`'s `on_activate` — so any drain /
    /// subscription the mode establishes there is live by the time this
    /// returns. Idempotent: a second call with the same `name` returns
    /// the existing id without re-activating (the drain from the first
    /// activation stays put).
    fn ensure_named_document(&mut self, name: &str, major: ModeId, flags: BufferFlags) -> BufferId;

    /// The buffer that is active right now (MR.6).
    ///
    /// A provider view is opened *over* something — the file you were
    /// reading, the magit buffer you pressed a chord in — and what it
    /// should show usually depends on which. `ProviderViewOpener`
    /// received the services and the trigger's arguments but no way to
    /// name that buffer, so magit's project diff had to fall back to the
    /// process's working directory and showed the wrong repository's
    /// changes for anyone with two checkouts open.
    ///
    /// The peer of `TransientContext::buffer` and
    /// `ExCommandContext::buffer_id`, and generic for the same reason:
    /// "which buffer did this come from" is a question every
    /// context-varying surface asks, not a magit one.
    ///
    /// Default `None` so test activators that model no pane tree stay
    /// valid; the host impl returns its active document buffer.
    fn active_buffer(&self) -> Option<BufferId> {
        None
    }

    /// Cheap-clone handle to the App's [`ServiceRegistry`]. Used
    /// by extension-crate trigger functions that need to look up
    /// service handles (`BufferStoreHandle`, per-provider
    /// services, the per-extension-crate registries) without
    /// fighting the borrow checker against the `&mut Self`
    /// activator borrow.
    fn services(&self) -> Arc<ServiceRegistry>;

    /// Register a virtual-row provider against
    /// `buffer`. Used by extension crates that contribute virtual
    /// rows for their own buffer kinds (multibuffer excerpt
    /// headers — `MultibufferHeaderProvider`; future fold-range
    /// providers, diff-hunk overlays, LSP code-lens, ...). The
    /// host-side impl forwards to
    /// `Editor::virtual_row_providers.register(buffer, provider)`;
    /// the worker picks the provider up on its next wake (K.4.6, 2026-06-02).
    ///
    /// Returns `true` on registration, `false` if a provider with
    /// the same `ProviderId` was already registered in the same
    /// buffer scope (no replacement — caller `unregister`s first
    /// via the existing registry handle). The default impl
    /// returns `false` so test activators that don't wire the
    /// virtual-row pipeline behave as no-ops; production impls
    /// (Editor) override.
    ///
    /// Paramount-#2 anchor: every mode contributing to a buffer
    /// registers its own virtual rows via this seam, matching
    /// the mode-owns-its-surface principle (keymaps via
    /// `register_<mode>_keymap`, virtual rows via this method,
    /// future status-line items via similar). WIT plugin path
    /// inherits the trait surface.
    fn register_virtual_row_provider(
        &mut self,
        buffer: lattice_core::BufferId,
        provider: Arc<dyn lattice_cells::VirtualRowProvider>,
    ) -> bool {
        let _ = (buffer, provider);
        false
    }

    /// Record the directory `buffer` is *about*
    /// ([`BufferScopeDir`](crate::BufferScopeDir)).
    ///
    /// A provider calls this from its trigger, where it has already resolved
    /// the directory — a magit repository's workdir, an oil listing's dir, a
    /// scan root. Project resolution (`:files`, `:search`) then answers for
    /// that buffer instead of falling through to the working directory.
    ///
    /// Pass the directory, not a project root: the host resolves the project
    /// from it through the ordinary resolver, so a provider never has to
    /// learn what a project is and the two cannot be recorded inconsistently.
    ///
    /// Default impl is a no-op so test activators stay valid; the host
    /// forwards to `Editor::set_buffer_scope_dir`.
    fn set_buffer_scope_dir(&mut self, buffer: BufferId, dir: std::path::PathBuf) {
        let _ = (buffer, dir);
    }
}

/// Service-accessible interface for registering virtual row providers
/// on a buffer. The host registers an `Arc<dyn VirtualRowRegistrar>` during boot
/// so subsystems (e.g. `lattice-ai`) can register headerlines without depending
/// on `lattice-host`'s concrete `VirtualRowProviderRegistry` (AUX‑2).
pub trait VirtualRowRegistrar: Send + Sync {
    /// Register `provider` against `buffer`. Returns `false` if a provider with
    /// the same `ProviderId` is already registered in the same buffer scope.
    fn register(
        &self,
        buffer: BufferId,
        provider: Arc<dyn lattice_cells::VirtualRowProvider>,
    ) -> bool;
    /// Remove the provider identified by `id` from `buffer`'s scope.
    fn unregister(&self, buffer: BufferId, id: lattice_cells::ProviderId) -> bool;
}