escriba-render 0.1.18

//! GPU renderer — implements [`madori::RenderCallback`] backed by garasu's
//! glyphon-wrapped text renderer. Each frame:
//!
//!   1. Locks the shared `EditorState`.
//!   2. Collects visible buffer lines into a single string.
//!   3. Builds a glyphon `Buffer` (re-created each frame — phase 1.B; phase 2
//!      will diff + reuse).
//!   4. Prepares + renders through `madori::RenderContext::text`.
//!
//! Colors are the **Vellum** fleet theme (warm aged-paper Nord-matte),
//! sourced from `escriba_ui::chrome::ChromePalette` so the GPU chrome matches
//! the rest of the fleet (mado, tear, frostmourne, …) and escriba's TUI
//! backend. Text is rendered in `snow1` (#E2DBC8, warm cream foreground)
//! over a `night0` (#16140E, parchment ground) background. The status
//! line is rendered in `ice_cyan` (#94BBB8, the matte accent).

use std::sync::{Arc, Mutex};

use escriba_core::{EditGen, Mode};
use escriba_runtime::EditorState;
use glyphon::{Attrs, Buffer, Color as GlyphColor, Family, Metrics, Shaping, TextArea, TextBounds};
use escriba_ui::chrome::ChromePalette;
use ishou_tokens::{EscribaSignals, Rgb, SignalMode, Srgb};
use madori::{RenderCallback, RenderContext};
// hikari (光) — the fleet syntax-highlighting spine. path→Box<dyn Highlighter>,
// coverage-complete HlClass span partition, HlClass→Rgb via NordTheme.
use hikari_core::{Ecosystem, Language, NordTheme, Rgb as HlRgb, Theme};

/// Shared handle to the editor state — both the GPU renderer (reads) and
/// the madori `on_event` callback (writes) hold one.
pub type SharedState = Arc<Mutex<EditorState>>;

/// The GPU render callback.
///
/// Holds a shared reference to the editor state. `render()` reads it under
/// lock, computes a frame, releases the lock before touching the GPU to
/// minimise contention with the event loop.
pub struct GpuRenderer {
    state: SharedState,
    font_size: f32,
    line_height: f32,
    /// Cached font metrics — rebuilt if font_size changes.
    metrics: Metrics,
    /// hikari highlight registry (built once — resolves path→Highlighter).
    eco: Ecosystem,
    /// Nord syntax theme (HlClass→Rgb).
    theme: NordTheme,
    /// The resolved CHROME palette this renderer paints with.
    ///
    /// Held as state rather than re-derived per paint site, so a theme is
    /// a VALUE the renderer owns and `set_theme` can change at runtime.
    /// Every site previously called `ChromePalette::prescribed()` directly,
    /// which hardwired the paint path to the FLEET default and made
    /// `(deftheme :preset …)` inert no matter what the operator authored.
    chrome: ChromePalette,
    /// The refresh generation of the currently-cached text buffer — the seal
    /// (`theory/ESCRIBA.md` §Refresh-Seal). When `EditorState::edit_gen()`
    /// still equals this, the cached shaped buffer is reused verbatim: no
    /// re-highlight, no re-shape. Init `u64::MAX` so the first frame always
    /// paints.
    last_gen: EditGen,
    /// The shaped main-text glyphon buffer, cached across frames while the
    /// generation is unchanged. `None` before the first paint.
    cached_text: Option<Buffer>,
    /// The incremental highlighter for the active buffer's language (M2). Held
    /// across frames so a re-highlight re-lexes only the lines that changed
    /// (hikari's `LineState` fixpoint, `theory/ESCRIBA.md` §X) instead of the
    /// whole visible window. Keyed by path so a language switch rebuilds it;
    /// `None` before the first paint.
    highlighter: Option<(String, Box<dyn hikari_core::IncrementalHighlighter>)>,
}

impl GpuRenderer {
    #[must_use]
    pub fn new(state: SharedState) -> Self {
        let font_size = 14.0;
        let line_height = 20.0;
        Self {
            state,
            font_size,
            line_height,
            metrics: Metrics::new(font_size, line_height),
            eco: build_ecosystem(),
            theme: NordTheme,
            // Nord (the fleet prescribed default) until a config resolves
            // otherwise — never a hand-written constant, so a fleet
            // re-point lands here for free.
            chrome: ChromePalette::prescribed(),
            last_gen: EditGen(u64::MAX),
            cached_text: None,
            highlighter: None,
        }
    }

    /// Point the renderer at a theme — the wiring that makes
    /// `(deftheme :preset …)` real.
    ///
    /// `ChromePalette::for_theme` is total over `FleetTheme` (no wildcard
    /// arm), so a theme added upstream fails this to compile rather than
    /// silently painting the wrong thing.
    pub fn set_theme(&mut self, theme: ishou_tokens::FleetTheme) {
        self.chrome = ChromePalette::for_theme(theme);
    }

    /// The palette currently painted with.
    #[must_use]
    pub fn chrome(&self) -> ChromePalette {
        self.chrome
    }

    /// Builder form of [`Self::set_theme`].
    #[must_use]
    pub fn with_theme(mut self, theme: ishou_tokens::FleetTheme) -> Self {
        self.set_theme(theme);
        self
    }

    #[must_use]
    pub fn with_font_size(mut self, font_size: f32, line_height: f32) -> Self {
        self.font_size = font_size;
        self.line_height = line_height;
        self.metrics = Metrics::new(font_size, line_height);
        self
    }
}

impl RenderCallback for GpuRenderer {
    fn render(&mut self, ctx: &mut RenderContext<'_>) {
        // ── 1. Read state under lock. The visible text is built ONLY when a
        //    rebuild is due (the refresh-generation gate): an idle frame reads
        //    just mode/cursor for the status line and reuses the cached shaped
        //    buffer below — zero re-highlight, zero re-shape. `rebuild_input`
        //    is Some((text, path)) exactly when the generation moved.
        let (rebuild_input, mode, cursor_line, cursor_col, cur_gen) = {
            let s = self
                .state
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            let Some(buf) = s.buffers.get(s.active) else {
                return clear_frame(ctx);
            };
            let cur_gen = s.edit_gen();
            let rebuild = cur_gen != self.last_gen || self.cached_text.is_none();
            let rebuild_input: Option<(String, String)> = if rebuild {
                // The open file's path drives hikari language resolution.
                let path = buf
                    .path
                    .as_ref()
                    .map(|p| p.to_string_lossy().into_owned())
                    .unwrap_or_default();
                let win = s.layout.active_window().cloned();
                let top_line = win.as_ref().map_or(0, |w| w.viewport.top_line);
                let left_column = win.as_ref().map_or(0, |w| w.viewport.left_column) as usize;
                let visible_lines = win
                    .as_ref()
                    .map_or(40, |w| w.viewport.visible_lines.max(20));
                let visible_columns = win
                    .as_ref()
                    .map_or(usize::MAX, |w| w.viewport.visible_columns as usize);
                let mut out = String::new();
                for row in 0..visible_lines {
                    let ln = top_line + row;
                    if ln >= buf.line_count() {
                        break;
                    }
                    if let Some(line) = buf.line(ln) {
                        let trimmed = line.trim_end_matches('\n').trim_end_matches('\r');
                        // Slice to the visible horizontal window
                        // `[left_column, left_column + visible_columns)`.
                        // Char-based so multibyte text stays aligned; long
                        // lines clip to the window, no glyphon wrap.
                        let sliced: String = trimmed
                            .chars()
                            .skip(left_column)
                            .take(visible_columns)
                            .collect();
                        out.push_str(&sliced);
                        out.push('\n');
                    }
                }
                Some((out, path))
            } else {
                None
            };
            (rebuild_input, s.modal.mode(), s.cursor().line, s.cursor().column, cur_gen)
        };

        // ── 2. Rebuild the shaped main-text buffer ONLY on a generation
        //    change; otherwise reuse the cached one. This is the seal
        //    (theory/ESCRIBA.md §Refresh-Seal): highlight + set_rich_text +
        //    shape — the frame's dominant cost — run once per edit, never
        //    per vsync.
        let palette = self.chrome;
        let fg = chrome_glyph(palette.text);
        let width = ctx.width as f32;
        let height = ctx.height as f32 - self.line_height; // reserve bottom row for status
        if let Some((text, path)) = rebuild_input {
            let mut buffer = Buffer::new(&mut ctx.text.font_system, self.metrics);
            buffer.set_size(&mut ctx.text.font_system, Some(width), Some(height));
            // hikari: resolve the language, highlight the visible text, paint
            // each span its Nord color. The span vec is a coverage-complete,
            // non-overlapping, sorted partition of `text` (the SpanSink
            // invariant), so each (slice, color) run is a valid set_rich_text
            // item. Offsets are self-consistent (highlight == render string).
            let base = Attrs::new().family(Family::Monospace);
            // hikari incremental (M2): reuse the per-path LineCache and re-lex
            // only the lines that changed since the last frame (the LineState
            // fixpoint). A language switch (path change) rebuilds the cache; a
            // scroll re-lexes the newly-visible window (graceful degrade). This
            // is byte-identical to the one-shot highlighter it replaces.
            if self.highlighter.as_ref().is_none_or(|(p, _)| p != &path) {
                self.highlighter =
                    Some((path.clone(), self.eco.incremental_highlighter_for_path(&path)));
            }
            let hl = &mut self
                .highlighter
                .as_mut()
                .expect("highlighter set immediately above")
                .1;
            let spans = hl.highlight(&text);
            let runs: Vec<(&str, Attrs)> = spans
                .iter()
                .filter_map(|s| {
                    text.get(s.span.range()).map(|slice| {
                        (slice, base.clone().color(hl_to_glyph(self.theme.color(s.class))))
                    })
                })
                .collect();
            buffer.set_rich_text(&mut ctx.text.font_system, runs, &base, Shaping::Advanced, None);
            buffer.shape_until_scroll(&mut ctx.text.font_system, false);
            self.cached_text = Some(buffer);
            self.last_gen = cur_gen;
        }
        let buffer = self
            .cached_text
            .as_ref()
            .expect("cached_text is built on the first frame (last_gen inits to u64::MAX)");

        // Status line — rendered as its own glyphon buffer. The mode is the
        // BORN fleet mode glyph (`ishou_tokens::EscribaSignals`) + escriba's
        // canonical uppercase mode label.
        let signals = EscribaSignals::prescribed();
        let status = format!(
            " {} {}  {}:{}  escriba v{} ",
            mode_glyph(&signals, mode).render(SignalMode::Glyph),
            mode.as_str(),
            cursor_line + 1,
            cursor_col + 1,
            env!("CARGO_PKG_VERSION")
        );
        let mut status_buf = Buffer::new(&mut ctx.text.font_system, self.metrics);
        status_buf.set_size(
            &mut ctx.text.font_system,
            Some(width),
            Some(self.line_height * 2.0),
        );
        status_buf.set_text(
            &mut ctx.text.font_system,
            &status,
            &Attrs::new().family(Family::Monospace),
            Shaping::Advanced,
        );
        status_buf.shape_until_scroll(&mut ctx.text.font_system, false);

        let status_color = chrome_glyph(palette.info);

        let text_areas = [
            TextArea {
                buffer,
                left: 8.0,
                top: 8.0,
                scale: 1.0,
                bounds: TextBounds {
                    left: 0,
                    top: 0,
                    right: ctx.width as i32,
                    bottom: (height as i32).max(0),
                },
                default_color: fg,
                custom_glyphs: &[],
            },
            TextArea {
                buffer: &status_buf,
                left: 8.0,
                top: (ctx.height as f32 - self.line_height - 4.0).max(0.0),
                scale: 1.0,
                bounds: TextBounds {
                    left: 0,
                    top: (ctx.height as i32 - self.line_height as i32 - 4).max(0),
                    right: ctx.width as i32,
                    bottom: ctx.height as i32,
                },
                default_color: status_color,
                custom_glyphs: &[],
            },
        ];

        if let Err(e) = ctx.text.prepare(
            &ctx.gpu.device,
            &ctx.gpu.queue,
            ctx.width,
            ctx.height,
            text_areas,
        ) {
            tracing::warn!(error = %e, "glyphon prepare failed");
            return clear_frame(ctx);
        }

        // ── 3. Encode frame. ───────────────────────────────────────────
        let mut encoder = ctx
            .gpu
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("escriba frame"),
            });
        {
            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("escriba main pass"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: ctx.surface_view,
                    resolve_target: None,
                    ops: wgpu::Operations {
                        load: wgpu::LoadOp::Clear(ground_bg()),
                        store: wgpu::StoreOp::Store,
                    },
                })],
                depth_stencil_attachment: None,
                timestamp_writes: None,
                occlusion_query_set: None,
            });
            if let Err(e) = ctx.text.render(&mut pass) {
                tracing::warn!(error = %e, "glyphon render failed");
            }
        }
        ctx.gpu.queue.submit(std::iter::once(encoder.finish()));
    }

    fn resize(&mut self, width: u32, height: u32) {
        if let Ok(mut s) = self.state.lock() {
            // Monospace cell width estimate — glyphon advance for the
            // Family::Monospace face is ≈ 0.6 × font_size. Used to derive a
            // visible-column count so the horizontal-scroll window tracks the
            // real window width (mirrors the visible-line derivation below).
            let cell_w = (self.font_size * 0.6).max(1.0);
            for w in &mut s.layout.windows {
                w.rect.width = width;
                w.rect.height = height;
                // Rough visible-line count from height / line_height.
                let lh = self.line_height.max(1.0);
                w.viewport.visible_lines = ((height as f32 / lh).max(1.0) as u32).saturating_sub(1);
                // Rough visible-column count from width / cell_width.
                w.viewport.visible_columns = (width as f32 / cell_w).max(1.0) as u32;
            }
        }
    }
}

/// The highlight registry escriba renders through: **tree-sitter grammars
/// (hikari-ts) take precedence** for the languages they cover, and the zero-dep
/// table backend fills every other language. So `.rs` gets real tree-sitter
/// highlighting while `.py` / `.lisp` / `.json` / … get the batteries-included
/// table lexer — and both flow through the same coverage-complete `HlClass`
/// partition. Registration order is load-bearing: `Ecosystem::resolve` returns
/// the first matching plugin, so tree-sitter (registered first) wins for its
/// languages; the table backend is skipped for any language tree-sitter already
/// covers (no duplicate). If the tree-sitter host fails to build, the table
/// backend covers everything — never a panic, never an empty registry.
fn build_ecosystem() -> Ecosystem {
    let mut eco = Ecosystem::new();
    let mut covered: Vec<Language> = Vec::new();
    if let Ok(host) = hikari_ts::TreeSitterHost::builtin() {
        for p in host.plugins() {
            covered.push(p.language());
            eco.register(p);
        }
    }
    for p in hikari_core::langs::builtins() {
        if !covered.contains(&p.language()) {
            eco.register(p);
        }
    }
    eco
}

/// Utility — clear the frame to Nord background. Used on error paths.
fn clear_frame(ctx: &mut RenderContext<'_>) {
    let mut encoder = ctx
        .gpu
        .device
        .create_command_encoder(&wgpu::CommandEncoderDescriptor {
            label: Some("escriba clear"),
        });
    {
        let _pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("escriba clear pass"),
            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                view: ctx.surface_view,
                resolve_target: None,
                ops: wgpu::Operations {
                    load: wgpu::LoadOp::Clear(ground_bg()),
                    store: wgpu::StoreOp::Store,
                },
            })],
            depth_stencil_attachment: None,
            timestamp_writes: None,
            occlusion_query_set: None,
        });
    }
    ctx.gpu.queue.submit(std::iter::once(encoder.finish()));
}

/// The editor ground as `wgpu::Color`, resolved from the fleet-prescribed
/// theme's `background` role. Gamma-correct: the sRGB token is promoted
/// through `ishou_tokens`' typed sRGB→linear path so it composites
/// correctly on the linear-storage surface.
fn ground_bg() -> wgpu::Color {
    let c = ChromePalette::prescribed().background;
    Srgb::from(c).to_linear().with_alpha(1.0).into()
}

/// ishou `Rgb` → glyphon `Color` (sRGB u8 RGBA, opaque). Theme-agnostic —
/// was `vellum_glyph`, back when the paint path was hardwired to Vellum.
fn chrome_glyph(c: Rgb) -> GlyphColor {
    GlyphColor::rgba(c.r, c.g, c.b, 0xFF)
}

/// hikari `Rgb` (sRGB u8) → glyphon `Color` (opaque) — the syntax-span paint.
fn hl_to_glyph(c: HlRgb) -> GlyphColor {
    GlyphColor::rgba(c.r, c.g, c.b, 0xFF)
}

/// Mode indicator color — used by higher-layer rendering paths that want a
/// glance-readable color. Named by ROLE so the hue follows the active theme:
/// Normal info, Insert success, Visual accent, Command warning.
#[must_use]
pub fn mode_color(mode: Mode) -> Rgb {
    let c = ChromePalette::prescribed();
    match mode {
        Mode::Insert => c.success,
        Mode::Command => c.warning,
        Mode::Visual | Mode::VisualLine => c.accent,
        Mode::Normal => c.info,
    }
}

/// The [`CursorShape`](escriba_core::CursorShape) the GPU backend should
/// draw for `mode`. Derived from the single typed `Mode::cursor_shape`
/// mapping shared with the TUI backend — so the GPU cursor (once it gains a
/// dedicated glyph; today the buffer text carries the caret) renders the
/// same shape the TUI does for any given mode. Exposed now so the shape is
/// a typed value at the GPU layer, not a renderer-local literal later.
#[must_use]
pub fn cursor_shape(mode: Mode) -> escriba_core::CursorShape {
    mode.cursor_shape()
}

/// Map an editor [`Mode`] to its fleet [`Signal`](ishou_tokens::Signal)
/// from [`EscribaSignals`].
///
/// `VisualLine` shares `mode_visual` with `Visual` — the fleet signal set
/// has one visual signal, matching how [`mode_color`] groups the two.
#[must_use]
pub fn mode_glyph(sig: &EscribaSignals, mode: Mode) -> &ishou_tokens::Signal {
    match mode {
        Mode::Normal => &sig.mode_normal,
        Mode::Insert => &sig.mode_insert,
        Mode::Visual | Mode::VisualLine => &sig.mode_visual,
        Mode::Command => &sig.mode_command,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use escriba_buffer::BufferSet;

    #[test]
    fn ground_is_the_prescribed_theme_promoted_to_linear() {
        let bg = ground_bg();
        // Was pinned to Vellum's warm parchment (night0 #16140E, r >= g >= b).
        // The prescribed theme is now Nord, whose ground is COOL (b >= r), so
        // the old warmth assertion was theme-specific and had to go. What is
        // actually invariant — and worth asserting — is that the ground is a
        // dark, opaque, gamma-correct promotion of the theme's own
        // background role.
        let want = Srgb::from(ChromePalette::prescribed().background)
            .to_linear()
            .with_alpha(1.0);
        let want: wgpu::Color = want.into();
        assert!((bg.r - want.r).abs() < 1e-6, "r {} != {}", bg.r, want.r);
        assert!((bg.g - want.g).abs() < 1e-6, "g {} != {}", bg.g, want.g);
        assert!((bg.b - want.b).abs() < 1e-6, "b {} != {}", bg.b, want.b);
        assert_eq!(bg.a, 1.0);
        // Dark ground: an editor background must stay well below mid-grey in
        // linear space whatever the theme.
        assert!(bg.r < 0.1 && bg.g < 0.1 && bg.b < 0.1, "ground is not dark: {bg:?}");
    }

    #[test]
    fn renderer_construction_is_cheap() {
        let mut bufs = BufferSet::new();
        let id = bufs.scratch("hello\n");
        let state = Arc::new(Mutex::new(EditorState::new_with_buffer(bufs, id)));
        let _r = GpuRenderer::new(state);
    }

    /// Phase 4: the render Ecosystem serves `.rs` from the **tree-sitter**
    /// backend (hikari-ts) and other languages from the table backend — both a
    /// coverage-complete `HlClass` partition. Proves real tree-sitter
    /// highlighting is wired into the live render path (not just the table lexer).
    #[test]
    fn ecosystem_uses_tree_sitter_for_rust_and_table_for_the_rest() {
        use hikari_core::{HlClass, Language};
        let eco = build_ecosystem();
        // .rs resolves to a grammar and produces real (non-Plain) classification.
        assert_eq!(eco.resolve("src/main.rs"), Language("rust"));
        let rs = eco
            .highlighter_for_path("src/main.rs")
            .highlight("fn main() { let x = 42; }");
        assert!(
            rs.iter().any(|s| s.class != HlClass::Plain),
            "rust must be really highlighted (tree-sitter or table)",
        );
        // Python is also served (tree-sitter, once hikari-ts ships that grammar;
        // the table backend covers it otherwise) — either way it classifies.
        assert_eq!(eco.resolve("app.py"), Language("python"));
        // A tree-sitter-uncovered language still resolves via the table backend.
        assert_eq!(eco.resolve("init.lisp"), Language("lisp"));
        // An unknown extension is still total (plain text, never a panic).
        assert_eq!(eco.resolve("notes.xyz"), hikari_core::PLAIN_TEXT);
    }

    #[test]
    fn mode_colors_differ_by_mode() {
        let n = mode_color(Mode::Normal);
        let i = mode_color(Mode::Insert);
        let v = mode_color(Mode::Visual);
        assert_ne!((n.r, n.g, n.b), (i.r, i.g, i.b));
        assert_ne!((n.r, n.g, n.b), (v.r, v.g, v.b));
    }

    #[test]
    fn cursor_shape_tracks_mode() {
        use escriba_core::CursorShape;
        assert_eq!(cursor_shape(Mode::Normal), CursorShape::Block);
        assert_eq!(cursor_shape(Mode::Command), CursorShape::Block);
        assert_eq!(cursor_shape(Mode::Insert), CursorShape::Bar);
        assert_eq!(cursor_shape(Mode::Visual), CursorShape::Underline);
        assert_eq!(cursor_shape(Mode::VisualLine), CursorShape::Underline);
    }

    /// Mode pills map to ROLES, not to one theme's hexes. This test used to
    /// pin the four Vellum values (`#94BBB8` …), which is precisely why it
    /// went red the moment the fleet theme moved — a test asserting a
    /// theme's spelling has to be rewritten on every theme change, and is
    /// no evidence the mapping is right. Asserting role identity instead
    /// survives the move AND still catches a mis-wired pill.
    #[test]
    fn mode_colors_are_role_pills() {
        let c = ChromePalette::prescribed();
        assert_eq!(mode_color(Mode::Normal).hex(), c.info.hex(), "Normal = info");
        assert_eq!(mode_color(Mode::Insert).hex(), c.success.hex(), "Insert = success");
        assert_eq!(mode_color(Mode::Visual).hex(), c.accent.hex(), "Visual = accent");
        assert_eq!(mode_color(Mode::Command).hex(), c.warning.hex(), "Command = warning");

        // The four pills must be mutually distinct, or the mode is not
        // glance-readable regardless of which theme is active.
        let mut seen = std::collections::BTreeSet::new();
        for m in [Mode::Normal, Mode::Insert, Mode::Visual, Mode::Command] {
            assert!(seen.insert(mode_color(m).hex()), "{m:?} duplicates another pill");
        }
    }

    /// Forcing function: the status-line mode glyphs are sourced from the
    /// fleet `EscribaSignals` vocabulary, not hand-picked literals. Pins
    /// the geometric `Glyph`-mode marks so drift in either escriba or
    /// ishou surfaces here.
    #[test]
    fn mode_glyphs_are_fleet_signals() {
        let sig = EscribaSignals::prescribed();
        assert_eq!(mode_glyph(&sig, Mode::Normal).render(SignalMode::Glyph), "◆");
        assert_eq!(mode_glyph(&sig, Mode::Insert).render(SignalMode::Glyph), "▸");
        assert_eq!(mode_glyph(&sig, Mode::Visual).render(SignalMode::Glyph), "▮");
        assert_eq!(
            mode_glyph(&sig, Mode::VisualLine).render(SignalMode::Glyph),
            "▮"
        );
        assert_eq!(
            mode_glyph(&sig, Mode::Command).render(SignalMode::Glyph),
            ":"
        );
    }

    /// Fleet convergence guard: escriba's GPU chrome paints whatever
    /// `ChromePalette::prescribed()` resolves, which is
    /// `FleetTheme::prescribed_default()` BY CONSTRUCTION — so this Guard
    /// cannot be satisfied by a stale hand-written constant.
    ///
    /// It previously hardcoded `FleetTheme::Vellum` to match a paint path
    /// hardwired to `VellumPalette::vellum()`. When the fleet moved its
    /// prescribed theme to PlemeDark (Nord) this went RED — correctly, since
    /// the GPU backend really was painting the wrong theme while the TUI
    /// face and the rest of the fleet (mado, tear, frostmourne, …) moved on.
    /// Smallest real editor state — a scratch buffer. The theming tests
    /// care about the palette, not the buffer, but GpuRenderer owns state.
    fn test_renderer() -> GpuRenderer {
        let mut bufs = escriba_buffer::BufferSet::new();
        let id = bufs.scratch("");
        GpuRenderer::new(Arc::new(Mutex::new(EditorState::new_with_buffer(bufs, id))))
    }

    #[test]
    fn default_theme_is_the_fleet_prescribed_nord() {
        // Nord is the default because the FLEET says so — asserted against
        // FleetTheme::prescribed_default(), never a hand-written "nord",
        // so a fleet re-point cannot leave escriba silently behind.
        let r = test_renderer();
        let want = ChromePalette::for_theme(ishou_tokens::FleetTheme::prescribed_default());
        assert_eq!(r.chrome().hex_tuple(), want.hex_tuple());
    }

    #[test]
    fn set_theme_actually_changes_what_is_painted() {
        // The wiring this exists to prove: before it, every paint site
        // called ChromePalette::prescribed() directly, so (deftheme :preset)
        // resolved to a real FleetTheme that NOTHING consumed. If set_theme
        // ever stops reaching the paint path, this fails.
        let mut r = test_renderer();
        let before = r.chrome().hex_tuple();
        r.set_theme(ishou_tokens::FleetTheme::Vellum);
        let after = r.chrome().hex_tuple();
        assert_ne!(
            before, after,
            "switching to Vellum must change the painted palette"
        );
        assert_eq!(
            after,
            ChromePalette::for_theme(ishou_tokens::FleetTheme::Vellum).hex_tuple()
        );
        // And it is reversible — a theme is a value, not a one-way latch.
        r.set_theme(ishou_tokens::FleetTheme::prescribed_default());
        assert_eq!(r.chrome().hex_tuple(), before);
    }

    #[test]
    fn escriba_gpu_chrome_converges_with_fleet() {
        use ishou_tokens::{FleetTheme, convergence::Guard};
        let chrome_theme = FleetTheme::prescribed_default();
        Guard::for_app("escriba-render").expect_theme(chrome_theme).run();
    }
}