lattice_mode/

contributions.rs

//! Declarative contributions on [`crate::Mode`].
//!
//! `Keymap` and `KeymapBinding` moved to `lattice-keymap::contribution`
//! in K.3 (2026-06-07) — re-exported here for backward compatibility.
//!
//! Stubs still pending real impls:
//! - [`DecorationProvider`] -- M.4 / decoration registry.

use lattice_core::BufferId;

use crate::services::ServiceRegistry;

pub use lattice_keymap::{Keymap, KeymapBinding};

/// RAII subscription handle. Unsubscribes from the event bus on drop.
///
/// Acquire in `Mode::on_activate` via `ctx.events_handle()` +
/// `EventBus::subscribe_typed`; store in the mode's `Guard` struct so
/// deactivation cleanup is compiler-enforced. Modes with conditional
/// subscriptions (e.g. skip when no URI) use `Option<Subscription>`.
///
/// MO.4.c: replaces the `_private:()` stub; `Mode::subscriptions()`
/// removed — `on_activate` + Guard IS the subscription mechanism.
pub struct Subscription {
    bus: std::sync::Arc<lattice_runtime::EventBus>,
    id: lattice_runtime::SubscriptionId,
}

impl Subscription {
    /// Wrap the `id` returned by one of `bus`'s subscribe calls so that
    /// dropping this value calls [`EventBus::unsubscribe`] on it.
    ///
    /// Takes an owned `Arc` because the handle outlives the activation that
    /// created it: it is moved into the mode's [`Guard`](crate::Mode::Guard),
    /// and the Guard is dropped whenever the mode deactivates.
    ///
    /// [`EventBus::unsubscribe`]: lattice_runtime::EventBus::unsubscribe
    pub fn new(
        bus: std::sync::Arc<lattice_runtime::EventBus>,
        id: lattice_runtime::SubscriptionId,
    ) -> Self {
        Self { bus, id }
    }
}

impl Drop for Subscription {
    fn drop(&mut self) {
        self.bus.unsubscribe(self.id);
    }
}

/// Stub. Reserved for the WIT plugin-facing contribution surface
/// (M.10). Not used by the `Mode` trait today — see
/// `Mode::gutter_decorations` for the live decoration path.
#[derive(Debug, Clone)]
pub struct DecorationProvider {
    _private: (),
}

/// Renderer-agnostic diff-sign kind for the gutter diff column.
/// Mirrors `DiffSignKind` without importing `lattice-host`.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum GutterDiffKind {
    /// Line added relative to the diff base (`+`, sign `diff.add`).
    Add,
    /// Line(s) removed at this position (`-`, sign `diff.remove`).
    Remove,
    /// Line modified relative to the diff base (`~`, sign `diff.change`).
    Change,
    /// Line inside an unresolved merge conflict (`?`, sign `diff.conflict`).
    Conflict,
}

/// Renderer-agnostic diagnostic severity level for the gutter
/// severity column. Ordered ascending by severity so `max()` selects
/// the most severe: `Hint < Info < Warning < Error`.
#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum GutterSeverityLevel {
    /// Lowest severity; sign `diagnostic.hint`.
    Hint,
    /// Informational; sign `diagnostic.info`.
    Info,
    /// Warning; sign `diagnostic.warning`.
    Warning,
    /// Error — the most severe; sign `diagnostic.error`.
    Error,
}

/// A single gutter decoration contributed by a [`crate::Mode`].
/// Each variant maps to one physical gutter column.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum GutterDecoration {
    /// A sign placement — vim's `:sign place`, and since SG.4b the ONLY
    /// kind of gutter decoration there is (SG.1).
    ///
    /// `Diff` and `Severity` used to sit beside this. They were deleted rather
    /// than deprecated because leaving them would have left the host with two
    /// privileged gutter paths and a mechanism pretending to be general — the
    /// exact half-migration shape that makes a "generic" seam quietly untrue.
    /// A diff mark and a diagnostic are now definitions in the same registry a
    /// plugin writes, named by their producers.
    ///
    /// Carries only the line and the definition's NAME; the glyph, its theme
    /// element and its priority live in the [`SignRegistry`]. A placement is
    /// produced per visible line on every refresh, so it stays the cheap half
    /// of the pair on purpose.
    ///
    /// An unknown id resolves to nothing and paints nothing — a provider
    /// placing a sign it never defined is a provider bug, and refusing to paint
    /// is the answer that keeps the gutter honest rather than inventing a
    /// glyph for it.
    Sign {
        /// Zero-based source line the sign is placed on.
        line: u32,
        /// The registered definition to paint; resolved through the
        /// [`SignRegistry`].
        sign: SignId,
    },
}

/// Render-time carrier for `compilation-mode`'s severity gutter
/// marks. The off-thread compilation drain builds a per-buffer severity
/// index and ships it to the host (`AppEffect::CompilationGutterSet`),
/// which stores it in `render_state`; the renderer reads that slot for the
/// pane's buffer and registers this into the [`DecorationCtx`]'s
/// `ServiceRegistry`. `CompilationMode::gutter_decorations` then pulls it
/// and maps each `(line, level)` to a [`GutterDecoration::Sign`] naming the
/// built-in diagnostic sign for that level
/// ([`BuiltinSignIds::for_severity`]) — the same mark an LSP diagnostic
/// paints (CM.3c; before SG.4b this was a dedicated `Severity` variant).
///
/// Deliberately lives here (in `lattice-mode`), NOT in `lattice-compilation`,
/// so neither renderer needs a `lattice-compilation` dependency to inject it
/// — the same dependency-inversion the `Mode::gutter_decorations` seam uses
/// for `LspDiagnosticsData` / `DiffDecorationData`. `entries` is shared
/// (`Arc`) so the render-path read is an O(1) pointer clone.
pub struct CompilationSeverityData {
    /// `(zero-based line, severity)` for every marked line of the
    /// `*compilation*` buffer, built off-thread by the compilation drain.
    pub entries: std::sync::Arc<Vec<(u32, GutterSeverityLevel)>>,
}

/// Read-only context passed to [`crate::Mode::gutter_decorations`].
///
/// Dependency inversion: the renderer builds a per-pane
/// [`ServiceRegistry`] of typed render-state snapshots (diff sign map, LSP
/// diagnostics, [`CompilationSeverityData`], [`BuiltinSignIds`], …) and
/// each mode pulls only the data it knows about through
/// [`service`](Self::service). The renderer therefore never depends on the
/// crate that owns a mode, and a mode never sees another mode's data.
///
/// Built once per pane per frame, on the render path: a
/// `gutter_decorations` implementation must do nothing heavier than a map
/// over data already computed off-thread.
///
/// # Examples
///
/// ```
/// use lattice_core::BufferId;
/// use lattice_mode::{DecorationCtx, ServiceRegistry};
///
/// struct MyMarks(Vec<u32>);
///
/// let mut services = ServiceRegistry::new();
/// services.register(MyMarks(vec![3, 7]));
/// let ctx = DecorationCtx::new(BufferId(1), &services);
///
/// assert_eq!(ctx.service::<MyMarks>().unwrap().0, vec![3, 7]);
/// // A snapshot nobody injected is simply absent: contribute nothing.
/// assert!(ctx.service::<String>().is_none());
/// ```
pub struct DecorationCtx<'a> {
    /// The buffer shown in the pane being decorated.
    pub buffer_id: BufferId,
    services: &'a ServiceRegistry,
}

impl<'a> DecorationCtx<'a> {
    /// Build a context over `services` for the pane showing `buffer_id`.
    /// Called by the renderers, not by modes.
    pub fn new(buffer_id: BufferId, services: &'a ServiceRegistry) -> Self {
        Self {
            buffer_id,
            services,
        }
    }

    /// Typed lookup of a render-state snapshot the renderer injected.
    /// `None` when nothing of type `T` was registered for this frame — a
    /// stripped render path or data not yet produced — and the mode should
    /// then contribute nothing rather than fail. Same `TypeId` rule as
    /// [`ServiceRegistry::get`]: look up with exactly the registered type.
    pub fn service<T: std::any::Any + Send + Sync>(&self) -> Option<std::sync::Arc<T>> {
        self.services.get::<T>()
    }
}

// ML.3: `StatusLineItem` + `StatusLineCtx` retired with the
// `Mode::status_line_items` trait. Modes contribute modeline content as
// registered elements pushed over the event bus
// (`crate::ModelineElementUpdate`), not via a render-path service pull.

// ── SG.1: generic gutter signs ──────────────────────────────────────────────

/// A sign **definition**: what it looks like, how it is styled, how it
/// competes for its cell (SG.1).
///
/// vim's `:sign define` / `:sign place` split, and the split is load-bearing
/// rather than historical. A definition is registered once and carries the
/// expensive, reusable parts — the glyph and its theme element. A *placement*
/// is `(line, name)` and happens per keystroke, per visible line, on every
/// refresh. Folding the two together would re-carry a glyph and a theme key
/// across the boundary for every marked line of every refresh, to say something
/// that was already true at load.
///
/// The host knows what a sign IS and nothing about what any particular sign
/// MEANS — which is what makes this a mechanism rather than a feature. A
/// provider's marks, a plugin's breakpoints and a future built-in all place
/// signs through the same registry and are styled through the same theme.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SignDefinition {
    /// The name placements refer to. A provider's own namespace by convention
    /// (`org-agenda-mark`), unenforced — last definition wins, as with every
    /// other registry here.
    pub name: String,
    /// The glyph when `ui.nerd_fonts` is on. **One cell** — SG.2b put signs
    /// in the gutter's single shared mark cell, so anything wider would push
    /// every line of content right. [`Self::glyph_char`] is what the
    /// renderers paint and it takes the first character.
    pub text: String,
    /// The BMP fallback, used when it is off — **the same cell width**, per the
    /// icon-degradation rule, so toggling the option cannot shift the gutter's
    /// geometry.
    pub fallback: String,
    /// The theme element the glyph is painted in (`gutter.sign.*` by
    /// convention). Resolved by the renderer through the ordinary theme
    /// registry, so a user or a theme retunes a plugin's signs without either
    /// knowing about the other.
    pub theme_element: String,
    /// Which sign wins when two land on one line **of the same column**.
    /// Higher wins; ties break on name so the answer is stable rather than
    /// incidental to hash order.
    ///
    /// One cell, one sign: a cell that stacked them would either grow
    /// unpredictably or silently drop one, and vim's answer — priority — is the
    /// one users already know.
    pub priority: i32,
    /// Which gutter column this sign paints in (SG.4a).
    ///
    /// Columns exist because contention is only meaningful between marks that
    /// mean comparable things. A diagnostic and a git-diff mark are both
    /// "something is true of this line", but they answer different questions,
    /// and a single contended cell would drop the git gutter on exactly the
    /// lines a diagnostic touches — the lines a user is most likely to be
    /// looking at. Vim's single `signcolumn` accepts that trade; Helix and Zed
    /// do not, and neither does this.
    ///
    /// A name the host does not paint falls back to the FIRST column rather
    /// than vanishing, on the same principle as the `gutter.sign` theme
    /// fallback: a sign was placed to say something, and the failure mode that
    /// loses the information entirely is the worst one available.
    ///
    /// Use [`SIGN_COLUMN_MARK`] / [`SIGN_COLUMN_DIFF`] for the built-ins.
    pub column: String,
}

/// The leftmost gutter column: diagnostics, compilation severity, and
/// any sign that does not name a column of its own. Vim's `signcolumn` (SG.4a).
pub const SIGN_COLUMN_MARK: &str = "mark";

/// The git-diff column, between the mark column and the line numbers.
/// Separate from [`SIGN_COLUMN_MARK`] so a diagnostic cannot hide a hunk mark (SG.4a).
pub const SIGN_COLUMN_DIFF: &str = "diff";

/// The built-in gutter columns, left to right (SG.4a).
///
/// The host owns the ORDER (a gutter whose columns moved per buffer would be
/// unreadable) but nothing about what goes in each one — that is entirely the
/// registry's answer. Making this list user-configurable is the obvious next
/// step and is deliberately not taken here: it changes the gutter's WIDTH,
/// which every scroll, wrap and cursor-column calculation reads.
pub const BUILTIN_SIGN_COLUMNS: [&str; 2] = [SIGN_COLUMN_MARK, SIGN_COLUMN_DIFF];

impl SignDefinition {
    /// The glyph for the current palette. Not a theme question — the theme
    /// decides the COLOUR, the font capability decides the GLYPH, and
    /// conflating them is how a themed editor renders tofu.
    pub fn glyph(&self, nerd_fonts: bool) -> &str {
        if nerd_fonts && !self.text.is_empty() {
            &self.text
        } else {
            &self.fallback
        }
    }

    /// The single character the renderers paint into the gutter's
    /// mark cell (SG.2b).
    ///
    /// The cell is one column, so this TRUNCATES rather than trusting a
    /// producer to have obeyed the one-cell rule. A definition that ignores
    /// it loses its tail; the alternative is a gutter that silently widens
    /// and pushes every line of content sideways, which is a pixel change to
    /// content the user did not edit and costs far more than the glyph.
    /// An empty definition paints a blank, so a producer can place a sign
    /// that reserves the cell without drawing in it.
    pub fn glyph_char(&self, nerd_fonts: bool) -> char {
        self.glyph(nerd_fonts).chars().next().unwrap_or(' ')
    }
}

/// A definition's interned handle (SG.1).
///
/// **Placements carry this, not a name**, and the reason is the render path:
/// `GutterDecoration` is `Copy` and one placement exists per visible marked
/// line per refresh, so a `String` there would be both a clone per line and the
/// end of `Copy` for every consumer. The name→id resolution happens ONCE, where
/// a placement is produced — at the WASM boundary, off the render path.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct SignId(pub u32);

/// The registered sign definitions (SG.1).
///
/// Read on the render path (one lookup per placed line) and written rarely (a
/// provider registering at load), which is the `ArcSwap` shape every other
/// contribution registry here uses.
/// `Clone` because the `ArcSwap` write path is copy-on-write: a producer
/// defining a sign clones the current snapshot, mutates, and stores. The
/// clone is `Vec<Option<Arc<_>>>` + the name index — Arc bumps, not glyph
/// copies — and it happens at registration, never on the render path.
#[derive(Debug, Default, Clone)]
pub struct SignRegistry {
    /// Indexed by [`SignId`]. Never shrinks: an id handed out must keep
    /// resolving, or an in-flight placement from a producer that ran before an
    /// `undefine` would paint some LATER sign's glyph. A removed definition
    /// leaves a `None` hole instead.
    defs: Vec<Option<std::sync::Arc<SignDefinition>>>,
    by_name: std::collections::HashMap<String, SignId>,
}

impl SignRegistry {
    /// An empty registry. The host registers the built-ins into it with
    /// [`register_builtin_signs`] at boot.
    ///
    /// # Examples
    ///
    /// ```
    /// use lattice_mode::{SignDefinition, SignRegistry, SIGN_COLUMN_MARK};
    ///
    /// let mut signs = SignRegistry::new();
    /// let id = signs.define(SignDefinition {
    ///     name: "my-plugin.breakpoint".into(),
    ///     text: "\u{f111}".into(), // Nerd Font glyph
    ///     fallback: "●".into(),   // BMP fallback, same cell width
    ///     theme_element: "gutter.sign.breakpoint".into(),
    ///     priority: 10,
    ///     column: SIGN_COLUMN_MARK.into(),
    /// });
    /// assert_eq!(signs.id_of("my-plugin.breakpoint"), Some(id));
    /// assert_eq!(signs.get(id).unwrap().glyph_char(false), '●');
    ///
    /// // Removal retires the id: a stale placement paints nothing.
    /// signs.undefine_prefix("my-plugin.");
    /// assert!(signs.get(id).is_none());
    /// assert!(signs.is_empty());
    /// ```
    pub fn new() -> Self {
        Self::default()
    }

    /// Define a sign, or redefine one of the same name.
    ///
    /// A redefinition KEEPS the id, so a plugin reloading with a new glyph does
    /// not orphan placements already in flight — they simply start painting the
    /// new glyph, which is what "redefine" should mean.
    pub fn define(&mut self, def: SignDefinition) -> SignId {
        let def = std::sync::Arc::new(def);
        if let Some(&id) = self.by_name.get(&def.name) {
            self.defs[id.0 as usize] = Some(def);
            return id;
        }
        let id = SignId(self.defs.len() as u32);
        self.by_name.insert(def.name.clone(), id);
        self.defs.push(Some(def));
        id
    }

    /// The id a name resolves to, for a producer turning its own vocabulary
    /// into placements.
    pub fn id_of(&self, name: &str) -> Option<SignId> {
        self.by_name.get(name).copied()
    }

    /// Forget one, by name. What a plugin's teardown reverses. The id is
    /// retired rather than reused, so an in-flight placement from a producer
    /// that ran before the removal paints nothing instead of painting some
    /// LATER sign's glyph.
    pub fn undefine(&mut self, name: &str) {
        if let Some(id) = self.by_name.remove(name) {
            self.defs[id.0 as usize] = None;
        }
    }

    /// Forget every sign a namespace defined — `org.` removes `org.mark` and
    /// its peers. The unload path, since a plugin's definitions are not tracked
    /// individually anywhere else.
    pub fn undefine_prefix(&mut self, prefix: &str) {
        let names: Vec<String> = self
            .by_name
            .keys()
            .filter(|n| n.starts_with(prefix))
            .cloned()
            .collect();
        for name in names {
            self.undefine(&name);
        }
    }

    /// The definition behind a placement, or `None` for a retired id — which
    /// paints nothing.
    pub fn get(&self, id: SignId) -> Option<&std::sync::Arc<SignDefinition>> {
        self.defs.get(id.0 as usize)?.as_ref()
    }

    /// Every live definition with its id, for a consumer that has to
    /// pre-resolve something per definition — the publish path turning each
    /// `theme_element` into an `ElementId` (SG.2b). Skips retired ids, so a
    /// caller never has to re-check `get`. Order is id order, which is
    /// definition order; nothing here depends on it, but it is stable rather
    /// than hash-dependent, which is the property that keeps such a caller's
    /// tests from reseeding.
    pub fn iter(&self) -> impl Iterator<Item = (SignId, &std::sync::Arc<SignDefinition>)> {
        self.defs
            .iter()
            .enumerate()
            .filter_map(|(i, d)| d.as_ref().map(|d| (SignId(i as u32), d)))
    }

    /// How many definitions are live. Retired ids do not count.
    pub fn len(&self) -> usize {
        self.by_name.len()
    }

    /// True when no definition is live (every id retired or none defined).
    pub fn is_empty(&self) -> bool {
        self.by_name.is_empty()
    }
}

/// Register **and** look up with this exact alias (the `ServiceRegistry` TypeId
/// rule).
pub type SignRegistryHandle = std::sync::Arc<arc_swap::ArcSwap<SignRegistry>>;

// ── SG.4a: the built-in signs ───────────────────────────────────────────────
//
// Diagnostics and diff marks are signs like any other. Nothing about them is
// privileged in the host any more: they are definitions in the same registry a
// plugin writes, painted through the same theme elements, contended by the
// same priority rule. What used to be two hardcoded gutter paths is now two
// producers naming what they mean.
//
// Their priorities span the diagnostic severity order, because "most severe
// wins" was the semantics the old `Severity` arm's `max()` gave and it has to
// survive the unification. `10` is vim's default sign priority and the floor:
// a plugin sign shipping the vim default ties with a HINT (broken by name) and
// loses to everything above it. Outranking an ERROR now means exceeding
// `DIAGNOSTIC_ERROR_PRIORITY`, which is a real change from SG.2b — where any
// priority above 10 did it — and the stricter reading is the right one. A
// sign that displaces a compiler error had better mean it.

/// The lowest diagnostic, level with vim's default sign priority.
pub const DIAGNOSTIC_HINT_PRIORITY: i32 = 10;
/// Priority of the built-in `diagnostic.info` sign: above a hint, below a
/// warning.
pub const DIAGNOSTIC_INFO_PRIORITY: i32 = 20;
/// Priority of the built-in `diagnostic.warning` sign: above info, below an
/// error.
pub const DIAGNOSTIC_WARNING_PRIORITY: i32 = 30;
/// The highest built-in. A sign must EXCEED this to take the cell from an
/// error.
pub const DIAGNOSTIC_ERROR_PRIORITY: i32 = 40;

/// Diff marks never contend with each other — a line belongs to at most one
/// hunk — so they share one priority, and it is the vim default because
/// nothing about a hunk mark argues for out-ranking a plugin's sign in a
/// column plugins do not normally use.
pub const DIFF_SIGN_PRIORITY: i32 = 10;

/// The interned ids of the built-in signs (SG.4a).
///
/// The `BuiltinElementIds` shape, for the same reason: a producer emitting a
/// mark per visible line must not hash a string per line to say which mark it
/// is. Interned once at registration, published, and read as a field.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BuiltinSignIds {
    /// `diagnostic.error` (mark column, [`DIAGNOSTIC_ERROR_PRIORITY`]).
    pub diagnostic_error: SignId,
    /// `diagnostic.warning` (mark column, [`DIAGNOSTIC_WARNING_PRIORITY`]).
    pub diagnostic_warning: SignId,
    /// `diagnostic.info` (mark column, [`DIAGNOSTIC_INFO_PRIORITY`]).
    pub diagnostic_info: SignId,
    /// `diagnostic.hint` (mark column, [`DIAGNOSTIC_HINT_PRIORITY`]).
    pub diagnostic_hint: SignId,
    /// `diff.add`, glyph `+` (diff column).
    pub diff_add: SignId,
    /// `diff.change`, glyph `~` (diff column).
    pub diff_change: SignId,
    /// `diff.remove`, glyph `-` (diff column).
    pub diff_remove: SignId,
    /// `diff.conflict`, glyph `?` (diff column).
    pub diff_conflict: SignId,
}

impl Default for BuiltinSignIds {
    /// Every id `SignId(u32::MAX)`, which resolves to nothing.
    ///
    /// A test fixture or a stripped host that never registered the built-ins
    /// then paints NO marks, rather than painting whatever happens to sit at
    /// id 0 — which would be some plugin's sign, silently, and only in the
    /// configurations nobody looks at.
    fn default() -> Self {
        let none = SignId(u32::MAX);
        Self {
            diagnostic_error: none,
            diagnostic_warning: none,
            diagnostic_info: none,
            diagnostic_hint: none,
            diff_add: none,
            diff_change: none,
            diff_remove: none,
            diff_conflict: none,
        }
    }
}

impl BuiltinSignIds {
    /// The id for a severity level — what an LSP or compilation producer calls
    /// instead of building a `Severity` decoration.
    pub fn for_severity(&self, level: GutterSeverityLevel) -> SignId {
        match level {
            GutterSeverityLevel::Error => self.diagnostic_error,
            GutterSeverityLevel::Warning => self.diagnostic_warning,
            GutterSeverityLevel::Info => self.diagnostic_info,
            GutterSeverityLevel::Hint => self.diagnostic_hint,
        }
    }

    /// The id for a diff kind — what the diff mode calls instead of building a
    /// `Diff` decoration.
    pub fn for_diff(&self, kind: GutterDiffKind) -> SignId {
        match kind {
            GutterDiffKind::Add => self.diff_add,
            GutterDiffKind::Change => self.diff_change,
            GutterDiffKind::Remove => self.diff_remove,
            GutterDiffKind::Conflict => self.diff_conflict,
        }
    }
}

/// Register the built-in signs into `registry` and return their ids (SG.4a).
///
/// `glyphs` supplies the four diagnostic glyphs, which are live typed options
/// (`ui.diagnostic-*-glyph`) rather than constants — so this is called again
/// when one changes. Redefinition KEEPS the id (SG.1), which is what makes
/// re-registering safe with placements already in flight: they simply start
/// painting the new glyph. That property was built before anything needed it;
/// this is the thing that needed it.
///
/// Diff glyphs stay `+ ~ - ?` — cross-editor convention, and no option has
/// ever exposed them.
///
/// # Examples
///
/// ```
/// use lattice_mode::{
///     register_builtin_signs, DiagnosticGlyphs, GutterSeverityLevel, SignRegistry,
///     SIGN_COLUMN_DIFF,
/// };
///
/// let mut signs = SignRegistry::new();
/// let ids = register_builtin_signs(&mut signs, DiagnosticGlyphs::default());
/// let error = signs.get(ids.for_severity(GutterSeverityLevel::Error)).unwrap();
/// assert_eq!(error.glyph_char(false), '■');
/// assert_eq!(signs.get(ids.diff_add).unwrap().column, SIGN_COLUMN_DIFF);
///
/// // Re-registering with a new glyph keeps every id.
/// let glyphs = DiagnosticGlyphs { error: 'E', ..DiagnosticGlyphs::default() };
/// assert_eq!(register_builtin_signs(&mut signs, glyphs), ids);
/// assert_eq!(signs.get(ids.diagnostic_error).unwrap().glyph_char(false), 'E');
/// ```
pub fn register_builtin_signs(
    registry: &mut SignRegistry,
    glyphs: DiagnosticGlyphs,
) -> BuiltinSignIds {
    let mut sev = |name: &str, glyph: char, element: &str, priority: i32| {
        let g = glyph.to_string();
        registry.define(SignDefinition {
            name: name.to_string(),
            // The SAME glyph for both palettes: these are the user's own
            // configured characters, and silently substituting a different one
            // when `ui.nerd_fonts` flips would be a surprise no option asked
            // for. A user wanting a Nerd Font diagnostic glyph sets the option
            // to one.
            text: g.clone(),
            fallback: g,
            theme_element: element.to_string(),
            priority,
            column: SIGN_COLUMN_MARK.to_string(),
        })
    };
    let diagnostic_error = sev(
        "diagnostic.error",
        glyphs.error,
        "diagnostic.error",
        DIAGNOSTIC_ERROR_PRIORITY,
    );
    let diagnostic_warning = sev(
        "diagnostic.warning",
        glyphs.warning,
        "diagnostic.warning",
        DIAGNOSTIC_WARNING_PRIORITY,
    );
    let diagnostic_info = sev(
        "diagnostic.info",
        glyphs.info,
        "diagnostic.info",
        DIAGNOSTIC_INFO_PRIORITY,
    );
    let diagnostic_hint = sev(
        "diagnostic.hint",
        glyphs.hint,
        "diagnostic.hint",
        DIAGNOSTIC_HINT_PRIORITY,
    );
    let mut diff = |name: &str, glyph: char, element: &str| {
        let g = glyph.to_string();
        registry.define(SignDefinition {
            name: name.to_string(),
            text: g.clone(),
            fallback: g,
            theme_element: element.to_string(),
            priority: DIFF_SIGN_PRIORITY,
            column: SIGN_COLUMN_DIFF.to_string(),
        })
    };
    let diff_add = diff("diff.add", '+', "diff.add.sign");
    let diff_change = diff("diff.change", '~', "diff.change.sign");
    let diff_remove = diff("diff.remove", '-', "diff.remove.sign");
    let diff_conflict = diff("diff.conflict", '?', "diff.conflict.sign");
    BuiltinSignIds {
        diagnostic_error,
        diagnostic_warning,
        diagnostic_info,
        diagnostic_hint,
        diff_add,
        diff_change,
        diff_remove,
        diff_conflict,
    }
}

/// The four `ui.diagnostic-*-glyph` values, read once by the caller so
/// `lattice-mode` needs no typed-options dependency.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DiagnosticGlyphs {
    /// `ui.diagnostic-error-glyph` (default `■`).
    pub error: char,
    /// `ui.diagnostic-warning-glyph` (default `▲`).
    pub warning: char,
    /// `ui.diagnostic-info-glyph` (default `●`).
    pub info: char,
    /// `ui.diagnostic-hint-glyph` (default `·`).
    pub hint: char,
}

impl Default for DiagnosticGlyphs {
    /// The same defaults the renderers carried before the unification, so a
    /// host that reads no options still paints what it used to.
    fn default() -> Self {
        Self {
            error: '■',
            warning: '▲',
            info: '●',
            hint: '·',
        }
    }
}

/// Pick the winner when several signs land on one line (SG.1).
///
/// Higher priority wins; equal priorities break on name. The tiebreak is not
/// arbitrary politeness — without it the painted glyph depends on iteration
/// order, so the same buffer renders differently between runs and a test that
/// passes today fails when a `HashMap` reseeds.
pub fn winning_sign<'a>(
    a: &'a std::sync::Arc<SignDefinition>,
    b: &'a std::sync::Arc<SignDefinition>,
) -> &'a std::sync::Arc<SignDefinition> {
    match a.priority.cmp(&b.priority) {
        std::cmp::Ordering::Greater => a,
        std::cmp::Ordering::Less => b,
        std::cmp::Ordering::Equal => {
            if a.name <= b.name {
                a
            } else {
                b
            }
        }
    }
}

#[cfg(test)]
mod sign_tests {
    #![allow(clippy::unwrap_used)]
    use super::*;

    fn def(name: &str, priority: i32) -> SignDefinition {
        SignDefinition {
            name: name.to_string(),
            text: "\u{f111}".to_string(),
            fallback: "\u{25cf}".to_string(),
            theme_element: format!("gutter.sign.{name}"),
            priority,
            column: SIGN_COLUMN_MARK.to_string(),
        }
    }

    #[test]
    fn a_definition_resolves_by_its_id() {
        let mut r = SignRegistry::new();
        let id = r.define(def("mark", 10));
        assert_eq!(r.id_of("mark"), Some(id));
        assert_eq!(r.get(id).unwrap().name, "mark");
        assert_eq!(r.len(), 1);
    }

    /// A redefinition KEEPS the id, so placements already in flight start
    /// painting the new glyph rather than being orphaned.
    #[test]
    fn redefining_keeps_the_id() {
        let mut r = SignRegistry::new();
        let first = r.define(def("mark", 10));
        let second = r.define(def("mark", 99));
        assert_eq!(first, second);
        assert_eq!(r.get(first).unwrap().priority, 99);
        assert_eq!(r.len(), 1, "and does not accumulate a second definition");
    }

    /// An id is RETIRED, never reused. A placement produced before the removal
    /// must paint nothing — reusing the slot would make it paint some later
    /// sign's glyph, which is a wrong answer where nothing is the right one.
    #[test]
    fn a_removed_id_is_retired_rather_than_reused() {
        let mut r = SignRegistry::new();
        let old = r.define(def("mark", 10));
        r.undefine("mark");
        assert!(r.get(old).is_none(), "the stale placement paints nothing");
        let new = r.define(def("other", 10));
        assert_ne!(old, new, "the slot is not handed to a different sign");
        assert!(r.get(old).is_none());
    }

    #[test]
    fn a_namespace_can_be_removed_at_once() {
        let mut r = SignRegistry::new();
        let a = r.define(def("org.mark", 1));
        let b = r.define(def("org.flag", 1));
        let keep = r.define(def("dap.breakpoint", 1));
        r.undefine_prefix("org.");
        assert!(r.get(a).is_none() && r.get(b).is_none());
        assert!(
            r.get(keep).is_some(),
            "another plugin's signs are untouched"
        );
        assert_eq!(r.len(), 1);
    }

    /// Higher priority wins. One cell, one sign — a column that stacked them
    /// would grow unpredictably or drop one silently.
    #[test]
    fn priority_decides_which_sign_paints() {
        let mut r = SignRegistry::new();
        let lo = r.define(def("low", 1));
        let hi = r.define(def("high", 100));
        let (lo, hi) = (r.get(lo).unwrap(), r.get(hi).unwrap());
        assert_eq!(winning_sign(lo, hi).name, "high");
        assert_eq!(winning_sign(hi, lo).name, "high", "and it is symmetric");
    }

    /// Ties break on NAME, not on iteration order. Without it the painted glyph
    /// depends on hash seeding — the same buffer renders differently between
    /// runs, and a test that passes today fails when the map reseeds.
    #[test]
    fn equal_priorities_break_on_name_not_on_luck() {
        let mut r = SignRegistry::new();
        let a = r.define(def("aaa", 5));
        let z = r.define(def("zzz", 5));
        let (a, z) = (r.get(a).unwrap(), r.get(z).unwrap());
        assert_eq!(winning_sign(a, z).name, "aaa");
        assert_eq!(winning_sign(z, a).name, "aaa");
    }

    /// The theme decides the COLOUR; the font capability decides the GLYPH.
    /// Conflating them is how a themed editor renders tofu.
    #[test]
    fn the_palette_decides_the_glyph_not_the_theme() {
        let d = def("mark", 1);
        assert_eq!(d.glyph(true), "\u{f111}");
        assert_eq!(d.glyph(false), "\u{25cf}");
        assert_eq!(
            d.glyph(true).chars().count(),
            d.glyph(false).chars().count(),
            "both palettes occupy the same cell width, so toggling \
             `ui.nerd_fonts` cannot shift the gutter"
        );
    }

    /// SG.2b: the mark cell is one column, so a definition that ignores the
    /// one-cell rule loses its tail rather than widening the gutter and
    /// pushing every line of content sideways.
    #[test]
    fn a_wide_glyph_is_truncated_rather_than_widening_the_gutter() {
        let mut d = def("wide", 1);
        d.text = "ab".into();
        d.fallback = "cd".into();
        assert_eq!(d.glyph_char(true), 'a');
        assert_eq!(d.glyph_char(false), 'c');
    }

    /// An empty definition reserves the cell without drawing in it.
    #[test]
    fn an_empty_glyph_paints_a_blank() {
        let mut d = def("blank", 1);
        d.text = String::new();
        d.fallback = String::new();
        assert_eq!(d.glyph_char(true), ' ');
        assert_eq!(d.glyph_char(false), ' ');
    }

    /// SG.4b: a sign and a diagnostic contend by ORDINARY priority now —
    /// there is no separate "does this beat a severity" rule, because a
    /// diagnostic IS a sign. A plugin shipping vim's default (10) ties with a
    /// hint and loses to everything above it.
    #[test]
    fn a_vim_default_sign_sits_at_the_bottom_of_the_diagnostics() {
        let mut r = SignRegistry::new();
        let ids = register_builtin_signs(&mut r, DiagnosticGlyphs::default());
        let plugin = std::sync::Arc::new(def("a-plugin.mark", DIAGNOSTIC_HINT_PRIORITY));
        let hint = r.get(ids.diagnostic_hint).unwrap();
        let error = r.get(ids.diagnostic_error).unwrap();
        // Ties with the hint (broken by name, deterministically) and loses to
        // the error outright.
        assert_eq!(plugin.priority, hint.priority);
        assert_eq!(winning_sign(error, &plugin).name, error.name);
    }

    /// The publish path pre-resolves one theme element per DEFINITION, so it
    /// needs to walk them — and must not be handed a retired id, which
    /// resolves to nothing.
    #[test]
    fn iter_yields_live_definitions_and_skips_retired_ids() {
        let mut r = SignRegistry::new();
        let a = r.define(def("a", 1));
        let b = r.define(def("b", 2));
        r.undefine("a");
        let seen: Vec<SignId> = r.iter().map(|(id, _)| id).collect();
        assert_eq!(seen, vec![b], "the retired id must not be walked");
        assert!(r.get(a).is_none());
    }
}