lattice_multibuffer/

view.rs

//! M.2.b.2 (2026-06-01): `create_multibuffer_view` — the atomic
//! "make me a multibuffer view" entry point that providers (and
//! tests) call.
//!
//! Composes the five steps so providers can't forget any:
//!
//! 1. Allocate a `BufferId`.
//! 2. Build the typed `MultibufferDocumentHandle` from `sources` +
//!    `excerpts` (empty inputs are valid — async providers
//!    open empty views and stream content via
//!    [`MultibufferDocumentHandle::append_excerpts`]).
//! 3. Register the typed handle in `MultibufferRegistry` (pulled
//!    from `activator.services()`).
//! 4. Insert the upcast handle into `BufferStore` via H.1's
//!    `insert_document_buffer(id, BufferKind::Multibuffer, ...)`.
//! 5. Activate `multibuffer-mode` on the buffer via
//!    `activator.activate_major_for_kind(id, Multibuffer)` —
//!    H.2's `ModeRegistry::find_major_for_kind` resolves the
//!    mode id from the kind.
//!
//! Failures (missing `BufferStore` / `MultibufferRegistry`
//! service) log + return early. The activation cascade's own
//! failure path publishes through `ModeEvent::ModeActivationFailed`.
//! Return type is `BufferId` (not `Result`) to match
//! `Editor::activate_major_for_buffer_kind`'s existing shape.
//!
//! See `docs/dev/architecture/multibuffer-views.md` §3.7.

use std::collections::HashMap;
use std::sync::Arc;

use lattice_core::{BufferFlags, BufferId, BufferKind};
use lattice_mode::{BufferStoreHandle, ModeActivator};
use lattice_runtime::{Document, EventBus};
use lattice_syntax::LangRegistry;

use crate::registry::MultibufferRegistryHandle;
use crate::{
    Excerpt, MultibufferDocumentHandle, MultibufferExcerptHeaderProvider, MultibufferStatusProvider,
};

/// Atomic insert + activate-major for a multibuffer view. Returns
/// the freshly-allocated view `BufferId`. After this call:
///
/// - The view buffer exists in `BufferRegistry` (as a
///   `BufferData::Multibuffer` entry).
/// - `MultibufferRegistry::handle(buffer_id)` returns the typed
///   handle.
/// - `multibuffer-mode` is the active major on the buffer.
///
/// The caller (typically a provider's public trigger function,
/// e.g. `project_search`) is responsible for activating its own
/// provider-minor mode after this returns (see §3.7 worked
/// example).
///
/// **Empty `sources` + empty `excerpts` are valid.** Async
/// providers (project-search, lsp-references, etc.) call this
/// with empty inputs to open the view immediately, then stream
/// content in via [`MultibufferDocumentHandle::append_excerpts`]
/// as their scan progresses.
///
/// **Missing services log + return a fresh `BufferId`** — the
/// caller can detect by checking
/// `activator.services().get::<MultibufferRegistryHandle>()
/// .and_then(|r| r.handle(id))` returning `Some`. Production
/// boot wires both services unconditionally; failure here means
/// boot order is broken.
pub fn create_multibuffer_view(
    activator: &mut dyn ModeActivator,
    sources: HashMap<BufferId, Arc<dyn Document>>,
    excerpts: Vec<Excerpt>,
    name: Option<String>,
    flags: BufferFlags,
    registry: lattice_grammar::CommandRegistryHandle,
    // K.4.7 (2026-06-07): when `Some`, wired into the handle so
    // `add_source` creates a `SyntaxHandle` per source file.
    lang_registry: Option<Arc<LangRegistry>>,
    // AF.1: how this view's rows group for folding. A PARAMETER rather than a
    // setter on the returned handle because `MultibufferMode::on_activate`
    // reads it while activating the mode below — by the time the caller has a
    // BufferId back, the fold source has already been chosen.
    fold_grouping: crate::FoldGrouping,
) -> BufferId {
    let services = activator.services();

    let buffer_store = match services.get::<BufferStoreHandle>() {
        Some(h) => h,
        None => {
            tracing::warn!(
                "create_multibuffer_view: BufferStoreHandle service not registered; \
                 returning sentinel BufferId — boot order is broken"
            );
            return BufferId::next();
        }
    };

    let mb_registry = match services.get::<MultibufferRegistryHandle>() {
        Some(h) => h,
        None => {
            tracing::warn!(
                "create_multibuffer_view: MultibufferRegistryHandle service not \
                 registered; returning sentinel BufferId — boot order is broken"
            );
            return BufferId::next();
        }
    };

    let handle = match MultibufferDocumentHandle::new(sources, excerpts, registry) {
        Ok(h) => h,
        Err(e) => {
            tracing::warn!(
                error = ?e,
                "create_multibuffer_view: MultibufferDocumentHandle::new failed; \
                 returning sentinel BufferId"
            );
            return BufferId::next();
        }
    };
    // K.4.7: wire lang_registry so subsequent add_source calls can
    // create SyntaxHandles for per-excerpt syntax highlighting.
    if let Some(lr) = lang_registry {
        handle.set_lang_registry(lr);
    }
    handle.set_fold_grouping(fold_grouping);
    let buffer_id = handle.buffer_id();

    // Step 2.5 (M.4 2026-06-01): auto-subscribe to source events
    // so the view recomposes when a source publishes
    // DocumentChanged and prunes + publishes
    // MultibufferSourceClosed when a source closes. No-op if the
    // EventBus service isn't registered (test paths without the
    // bus wired up).
    // EventBus is registered as `Arc<EventBus>` at boot
    // (`editor_boot.rs` -> `s.register(event_bus.clone())` where
    // `event_bus: Arc<EventBus>`); lookup must query the same
    // shape and unwrap one Arc layer. Earlier
    // `services.get::<EventBus>()` returned None silently —
    // tests still pass because they wire the bus directly via
    // `attach_event_subscriptions`, but production paths missed
    // their subscriptions.
    if let Some(events_outer) = services.get::<Arc<EventBus>>() {
        let events: Arc<EventBus> = (*events_outer).clone();
        handle.attach_event_subscriptions(&events);
    }

    let typed_handle = Arc::new(handle);

    // Step 3: typed-handle registry insert (providers reach
    // through this via service lookup).
    mb_registry.insert(buffer_id, typed_handle.clone());

    // Step 4: buffer-registry insert via H.1's primitive method.
    // Upcast to `Arc<dyn Document>`.
    let dyn_handle: Arc<dyn Document> = typed_handle.clone();
    buffer_store.insert_document_buffer(
        buffer_id,
        BufferKind::Multibuffer,
        dyn_handle,
        flags,
        name,
    );

    // K.4.6 (2026-06-02): excerpt-header provider — one VirtualRow per
    // excerpt (anchored Above the excerpt's first composed row).
    // M.6.5 (2026-06-08): renamed to MultibufferExcerptHeaderProvider.
    //
    // T.7 (2026-06-18): register the mode-owned excerpt-header theme
    // elements + capture their ids, then wire the resolved theme
    // handle into the provider so `collect()` bakes the registered
    // backdrop / path colors into the header rows. Registration is
    // idempotent by name; `MultibufferMode::on_activate` registers
    // the same elements (mode-ownership contract) — both hit the same
    // interned ids. Build the provider with theme only when the
    // service is wired (production); test activators that don't
    // register the service fall back to the no-theme provider.
    // MH.A4: register the mode's theme elements ONCE (idempotent by
    // name) and share the interned ids between the excerpt-header and
    // status providers — both bake their colors from the same table.
    let theme_handle = services
        .get::<lattice_theme::ThemeRegistryHandle>()
        .map(|outer| (*outer).clone());
    let theme_elements = theme_handle.as_ref().map(|theme| {
        let owner = lattice_theme::ElementOwner::Mode(
            crate::MultibufferMode::mode_id()
                .as_str()
                .to_string()
                .into(),
        );
        crate::register_multibuffer_theme_elements(theme.as_ref(), owner)
    });
    let excerpt_header_provider: Arc<MultibufferExcerptHeaderProvider> =
        match (theme_handle.clone(), theme_elements) {
            (Some(theme), Some(elements)) => {
                // MH.A3 (2026-06-19): read the GLOBAL `ui.nerd_fonts`
                // default via the ConfigRegistry service (registered at
                // boot; read by name so we needn't import host's
                // `UiNerdFonts` decl) to pick the icon palette. Defaults
                // to `false` (BMP fallback) when the service or option is
                // absent — matching the icon-palette rule's safe default.
                //
                // MH.A3 follow-on: live per-buffer `ui.nerd_fonts` toggle
                // — captured once here, so a runtime toggle does not yet
                // re-render the header. Needs the `FrameView::for_buffer`
                // seam threaded into the provider.
                let nerd_fonts = services
                    .get::<Arc<lattice_config::ConfigRegistry>>()
                    .and_then(|cfg| cfg.get_bool_by_name("ui.nerd_fonts"))
                    .unwrap_or(false);
                Arc::new(
                    MultibufferExcerptHeaderProvider::with_theme(
                        (*typed_handle).clone(),
                        theme,
                        elements,
                        nerd_fonts,
                    )
                    // OA.2: headers group the way this view folds. The two
                    // must agree, so they read one declaration.
                    .with_grouping(fold_grouping),
                )
            }
            _ => Arc::new(
                MultibufferExcerptHeaderProvider::new((*typed_handle).clone())
                    .with_grouping(fold_grouping),
            ),
        };
    let registered = activator.register_virtual_row_provider(buffer_id, excerpt_header_provider);
    if !registered {
        tracing::debug!(
            buffer = ?buffer_id,
            "create_multibuffer_view: excerpt header provider not registered \
             (test activator with default impl, or duplicate ProviderId)"
        );
    }

    // M.6.5 (2026-06-08): view-status sticky headerline — surfaces
    // HeaderlineStatus (Idle / InProgress / Complete / Failed) as a
    // pinned row above line 0. Hidden when status is Idle.
    // MH.A4: thread the resolved theme + the shared status element ids
    // into the status provider so its `render()` resolves the
    // `multibuffer.status.*` foregrounds (falls back to the no-theme
    // provider for test activators with no theme service).
    let status_provider = match (theme_handle, theme_elements) {
        (Some(theme), Some(elements)) => {
            MultibufferStatusProvider::with_theme((*typed_handle).clone(), theme, elements)
        }
        _ => MultibufferStatusProvider::new((*typed_handle).clone()),
    }
    .into_provider(buffer_id);
    let registered = activator.register_virtual_row_provider(buffer_id, Arc::new(status_provider));
    if !registered {
        tracing::debug!(
            buffer = ?buffer_id,
            "create_multibuffer_view: status provider not registered \
             (test activator with default impl, or duplicate ProviderId)"
        );
    }

    // Step 5: activate the major via H.2's kind dispatch. The
    // activator's impl runs the full cascade (default minor +
    // auto minors + options recompute + completion sources +
    // maybe-auto-LSP) and queues any renderer signals into the
    // implementor's pending-signals queue.
    activator.activate_major_for_kind(buffer_id, BufferKind::Multibuffer);

    buffer_id
}