ishou_render/

vellum.rs

//! Vellum render targets — the stylix base16/base24 schemes + an SVG
//! palette preview, all sourced from the BORN `VellumPalette` tokens.
//!
//! Unlike the legacy `stylix` renderer (which maps the Nord `TokenSet`),
//! these targets construct `VellumPalette::vellum()` internally — the
//! Vellum tokens are not part of the Nord `TokenSet`, they are their
//! own BORN source. The base16/base24 YAML is emitted through
//! `serde_yaml` over an `IndexMap` — TYPED EMISSION, no
//! string-concatenated YAML. The SVG preview is a brand-asset target
//! (one chip per token, in band order).
//!
//! Output (per base16 spec — <https://github.com/chriskempson/base16>):
//!
//! ```yaml
//! system: base16
//! name: Vellum
//! author: pleme-io (ishou)
//! variant: dark
//! slug: vellum
//! palette:
//!   base00: 16140e
//!   …
//! ```
//!
//! Hex values are **lowercase, unprefixed** — stylix passes them through
//! to GTK which expects six-char lowercase hex (no `#`).

use indexmap::IndexMap;
use ishou_tokens::{Rgb, VellumPalette};
use serde::Serialize;

/// Lowercase, unprefixed six-char hex — the stylix/base16 wire format.
fn slot_hex(rgb: Rgb) -> String {
    format!("{:02x}{:02x}{:02x}", rgb.r, rgb.g, rgb.b)
}

/// The base16/base24 scheme object serde_yaml serializes. `palette` is
/// an `IndexMap` so slot order is the authored slot order, not hash
/// order.
#[derive(Serialize)]
struct Scheme {
    system: &'static str,
    name: &'static str,
    author: &'static str,
    variant: &'static str,
    slug: &'static str,
    palette: IndexMap<String, String>,
}

fn scheme(system: &'static str, palette: IndexMap<String, String>) -> Scheme {
    Scheme {
        system,
        name: "Vellum",
        author: "pleme-io (ishou)",
        variant: "dark",
        slug: "vellum",
        palette,
    }
}

const HEADER: &str = "# Generated by ishou-render::vellum — DO NOT EDIT\n\
     # Source of truth: pleme-io/ishou/crates/ishou-tokens/src/vellum.rs\n\
     # Vellum — the fleet theme (warm aged-paper Nord-matte)\n";

/// Render the Vellum **base16** stylix scheme YAML.
///
/// Pure — `VellumPalette::vellum()` is deterministic, so this is too.
/// serde_yaml owns the escaping; the slot order is the canonical order.
#[must_use]
pub fn render_base16() -> String {
    let p = VellumPalette::vellum();
    let mut palette = IndexMap::new();
    for (slot, rgb) in p.base16() {
        palette.insert(slot.to_string(), slot_hex(rgb));
    }
    let body =
        serde_yaml::to_string(&scheme("base16", palette)).expect("Scheme is always serializable");
    format!("{HEADER}{body}")
}

/// Render the Vellum base16 scheme as a **Nix attrset** — the form that
/// costs no import-from-derivation.
///
/// ── ★ WHY THIS EXISTS AND THE YAML DOES NOT SUFFICE ──
/// stylix's `base16.nix` classifies its input with
/// `is-not-parsed = builtins.isAttrs scheme && !(scheme ? "yaml")`. The
/// fleet passed `{ yaml = <derivation>; }`, which sets `is-y2a-args`, so
/// stylix does `readFile <drv>` — an IFD. That forces a BUILD during
/// evaluation, and since the consumers are NixOS nodes the build is a
/// linux one: `nix eval .#nixosConfigurations.<node>` becomes impossible
/// from a Mac. The nixos-gnome-desktop profile's own comment records the
/// cost — the same IFD in the FONTS slot "made ggg's config UNEVALUABLE
/// from a Mac", which is why fonts were moved to a precomputed render and
/// why this is that move's missing twin.
///
/// A literal attrset takes the `is-not-parsed` branch instead: stylix
/// treats it as an already-parsed colour set and never reads a file. No
/// derivation, no build, no platform coupling.
///
/// Emitted through the typed `nix_ast` printer rather than by formatting
/// strings — `format!()` of Nix syntax is banned (theory/NIX-AST.md), and
/// the failure it prevents is silent: an unbalanced brace or a missing
/// semicolon ships as a file that parses to the wrong thing.
#[must_use]
pub fn render_base16_nix() -> String {
    use crate::nix_ast::{AttrEntry, NixFile, attrset, str_};

    let p = VellumPalette::vellum();
    let meta = scheme("base16", IndexMap::new());

    // The METADATA is not decoration — omitting it silently renames things.
    //
    // base16.nix's `input-meta` defaults every absent field:
    // `scheme`/`author` -> "untitled", `variant` -> "unspecified". Those
    // strings are interpolated into generated artefact NAMES —
    // `base16-${slug}` (fish), `"Base16 ${scheme-name}"` (zed),
    // `${slug}-gnome-shell-theme` — so a metadata-less attrset keeps every
    // colour byte-identical while turning `base16-vellum` into
    // `base16-untitled` and renaming a pile of store paths.
    //
    // `name` rather than `scheme`: base16.nix's
    // `convert-scheme-to-common-format` maps `name` -> `scheme`, and `name`
    // is what the YAML render beside this one already emits, so the two
    // stay spellable the same way.
    let mut entries: Vec<AttrEntry> = vec![
        AttrEntry::new("system", str_(meta.system)),
        AttrEntry::new("name", str_(meta.name)),
        AttrEntry::new("author", str_(meta.author)),
        AttrEntry::new("variant", str_(meta.variant)),
        AttrEntry::new("slug", str_(meta.slug)),
    ];
    entries.extend(
        p.base16()
            .into_iter()
            // Hex WITHOUT a leading `#`, matching the YAML this replaces —
            // stylix's own scheme format is bare hex, and a `#` here would
            // be a silent colour change rather than a parse error.
            .map(|(slot, rgb)| AttrEntry::new(slot, str_(slot_hex(rgb)))),
    );

    NixFile::new(
        [
            "Generated by ishou-render::vellum — DO NOT EDIT",
            "Source of truth: pleme-io/ishou/crates/ishou-tokens/src/vellum.rs",
            "",
            "Vellum base16 as an ALREADY-PARSED attrset. Consumed as:",
            "  stylix.base16Scheme = import ./rendered/stylix-base16-vellum.nix;",
            "",
            "The `{ yaml = <derivation>; }` form this replaces made stylix",
            "readFile a derivation — an IFD — which forced a linux build during",
            "evaluation and left every NixOS node unevaluable from a Mac.",
        ],
        attrset(entries),
    )
    .render()
}

/// Render the Vellum **base24** stylix scheme YAML (base16 + the
/// real two-tier brights, base10–17).
#[must_use]
pub fn render_base24() -> String {
    let p = VellumPalette::vellum();
    let mut palette = IndexMap::new();
    for (slot, rgb) in p.base24() {
        palette.insert(slot.to_string(), slot_hex(rgb));
    }
    let body =
        serde_yaml::to_string(&scheme("base24", palette)).expect("Scheme is always serializable");
    format!("{HEADER}{body}")
}

/// Render an SVG palette preview — one labelled chip per BORN token, in
/// band order. A brand-asset target for docs / design review.
#[must_use]
pub fn render_svg_palette() -> String {
    let p = VellumPalette::vellum();
    let entries = p.entries();
    let cols = 6usize;
    let chip = 96i32;
    let pad = 12i32;
    let label_h = 22i32;
    let rows = entries.len().div_ceil(cols) as i32;
    let width = cols as i32 * (chip + pad) + pad;
    let height = rows * (chip + label_h + pad) + pad;

    let mut chips = String::new();
    for (i, (name, rgb)) in entries.iter().enumerate() {
        let col = (i % cols) as i32;
        let row = (i / cols) as i32;
        let x = pad + col * (chip + pad);
        let y = pad + row * (chip + label_h + pad);
        let hex = rgb.hex();
        // Pick a readable label colour: light on dark chips, dark on
        // light chips, by computed luminance.
        let lum = 0.2126 * f64::from(rgb.r) + 0.7152 * f64::from(rgb.g) + 0.0722 * f64::from(rgb.b);
        let text_fill = if lum > 140.0 { "#16140E" } else { "#F4EFE2" };
        chips.push_str(&format!(
            "  <rect x=\"{x}\" y=\"{y}\" width=\"{chip}\" height=\"{chip}\" rx=\"8\" fill=\"{hex}\"/>\n  \
             <text x=\"{tx}\" y=\"{ty}\" font-family=\"monospace\" font-size=\"9\" fill=\"{text_fill}\">{hex}</text>\n  \
             <text x=\"{x}\" y=\"{ly}\" font-family=\"monospace\" font-size=\"10\" fill=\"#E2DBC8\">{name}</text>\n",
            tx = x + 6,
            ty = y + chip - 8,
            ly = y + chip + 15,
        ));
    }

    format!(
        "<!-- ishou Vellum palette preview (generated) -->\n\
         <svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 {width} {height}\" width=\"{width}\" height=\"{height}\">\n  \
         <rect width=\"{width}\" height=\"{height}\" fill=\"#16140E\"/>\n{chips}</svg>\n"
    )
}

// ─── skim / fzf `--color` string ────────────────────────────────────────────

/// Resolve a Vellum token to its **uppercase** `#RRGGBB` hex — the skim
/// `--color` wire format mirrors the hand-authored `skim-tab::NORD_COLORS`,
/// which uses uppercase hex.
fn tok(p: &VellumPalette, name: &str) -> String {
    p.get(name)
        .unwrap_or_else(|| panic!("vellum token `{name}` missing"))
        .hex()
}

/// Render the skim/fzf `--color=k:v,…` string from the BORN `VellumPalette`.
///
/// Byte-equivalent to the hand-authored `pleme-io/skim-tab::NORD_COLORS`:
/// every colour resolves from a typed token, the `:bold`/`:underlined`
/// attribute suffixes are the picker's fixed UX contract. The role→token
/// map is the single source of truth — change a Vellum token and every
/// picker on the fleet follows.
///
/// Role → token:
/// - `fg`      → `snow1`        (base05, the text fg)
/// - `bg`      → `night0`       (base00, the parchment ground)
/// - `hl`      → `ice_cyan`     (base0C, match highlight) `:bold:underlined`
/// - `fg+`     → `snow3`        (base07, selected-line fg) `:bold`
/// - `bg+`     → `night2`       (the selected-line surface)
/// - `hl+`     → `cyan_bright`  (ANSI-14, selected-match) `:bold:underlined`
/// - `info`    → `shadow0`      (the dim ANSI-8 tier)
/// - `prompt`  → `aurora_green` (base0B, the prompt)
/// - `pointer` → `green_bright` (the cursor/green signature)
/// - `marker`  → `solar_magenta`(base0E, multi-select)
/// - `spinner` → `ice_steel`    (base0D)
/// - `header`  → `ice_steel`    (base0D)
/// - `border`  → `shadow0`      (the dim tier)
/// - `query`   → `snow3`        (base07) `:bold`
#[must_use]
pub fn render_skim() -> String {
    let p = VellumPalette::vellum();
    // (key, token, attr-suffix) — order is the skim-tab authored order.
    let rows: [(&str, &str, &str); 14] = [
        ("fg", "snow1", ""),
        ("bg", "night0", ""),
        ("hl", "ice_cyan", ":bold:underlined"),
        ("fg+", "snow3", ":bold"),
        ("bg+", "night2", ""),
        ("hl+", "cyan_bright", ":bold:underlined"),
        ("info", "shadow0", ""),
        ("prompt", "aurora_green", ""),
        ("pointer", "green_bright", ""),
        ("marker", "solar_magenta", ""),
        ("spinner", "ice_steel", ""),
        ("header", "ice_steel", ""),
        ("border", "shadow0", ""),
        ("query", "snow3", ":bold"),
    ];
    rows.iter()
        .map(|(key, token, attr)| format!("{key}:{}{attr}", tok(&p, token)))
        .collect::<Vec<_>>()
        .join(",")
}

// ─── escriba theme lisp ──────────────────────────────────────────────────────

/// A `(defhighlight …)` row — a group plus the typed token roles it paints.
/// `link` is mutually exclusive with the colour/attr fields (escriba's
/// `HighlightSpec` honours `link` first).
struct HiRow {
    group: &'static str,
    /// fg token name (resolved through `VellumPalette::get`), or `""`.
    fg: &'static str,
    /// bg token name, or `""`.
    bg: &'static str,
    bold: bool,
    italic: bool,
    /// `:link "<group>"` — when set, colour fields are skipped.
    link: &'static str,
}

impl HiRow {
    const fn fg(group: &'static str, fg: &'static str) -> Self {
        Self {
            group,
            fg,
            bg: "",
            bold: false,
            italic: false,
            link: "",
        }
    }
    const fn bg(group: &'static str, bg: &'static str) -> Self {
        Self {
            group,
            fg: "",
            bg,
            bold: false,
            italic: false,
            link: "",
        }
    }
    const fn fg_bg(group: &'static str, fg: &'static str, bg: &'static str) -> Self {
        Self {
            group,
            fg,
            bg,
            bold: false,
            italic: false,
            link: "",
        }
    }
    const fn link(group: &'static str, link: &'static str) -> Self {
        Self {
            group,
            fg: "",
            bg: "",
            bold: false,
            italic: false,
            link,
        }
    }
    const fn b(mut self) -> Self {
        self.bold = true;
        self
    }
    const fn i(mut self) -> Self {
        self.italic = true;
        self
    }
}

/// Lowercase, `#`-prefixed six-char hex — escriba's `defpalette` /
/// `defhighlight` wire format (the hand-authored `vellum.lisp` uses
/// lowercase hex).
fn lc_hex(p: &VellumPalette, name: &str) -> String {
    let h = tok(p, name); // "#RRGGBB" uppercase
    format!("#{}", h[1..].to_ascii_lowercase())
}

/// A typed `(defX :k v …)` line writer — one keyword/value pair per
/// emitted slot, joined with single spaces, wrapped in parens. Keeps the
/// emission off ad-hoc concatenation (TYPED EMISSION).
fn lisp_form(head: &str, kvs: &[(&str, String)]) -> String {
    use std::fmt::Write as _;
    let mut s = String::new();
    write!(s, "({head}").expect("write to String");
    for (k, v) in kvs {
        write!(s, " {k} {v}").expect("write to String");
    }
    s.push(')');
    s
}

/// Render the escriba Vellum theme `*.lisp` — a `(deftheme …)` +
/// `(defpalette …)` + the `(defhighlight …)` forms over escriba's
/// `CANONICAL_GROUPS`, all sourced from the BORN `VellumPalette`.
///
/// Mirrors `pleme-io/escriba/escriba/configs/vellum.lisp` so escriba can
/// later `include` the generated file. Every colour resolves through a
/// typed token; the diff backgrounds use the byte-exact GLASS blend
/// tokens (`*_glass`), so they can never drift from the blend recipes.
#[must_use]
pub fn render_escriba_lisp() -> String {
    use std::fmt::Write as _;
    let p = VellumPalette::vellum();

    let mut out = String::new();
    out.push_str(
        "; escriba — Vellum theme (the fleet default)\n\
         ; Generated by ishou-render::vellum::render_escriba_lisp — DO NOT EDIT\n\
         ; Source of truth: pleme-io/ishou/crates/ishou-tokens/src/vellum.rs\n\
         ; Vellum — warm aged-paper Nord-matte; every hex is a BORN ishou token.\n\n",
    );

    // ─ Theme select ─
    writeln!(
        out,
        "{}",
        lisp_form("deftheme", &[(":preset", "\"vellum\"".to_string())])
    )
    .expect("write");
    out.push('\n');

    // ─ Palette — base16 slots, lowercase hex. base02 carries night2
    //   (the escriba lisp's selected-line surface), NOT the violet
    //   selection blend — matching the hand-authored file. ─
    let palette_kvs: Vec<(&str, String)> = vec![
        (":name", "\"vellum\"".to_string()),
        (":base00", format!("\"{}\"", lc_hex(&p, "night0"))),
        (":base01", format!("\"{}\"", lc_hex(&p, "night1"))),
        (":base02", format!("\"{}\"", lc_hex(&p, "night2"))),
        (":base03", format!("\"{}\"", lc_hex(&p, "shadow1"))),
        (":base04", format!("\"{}\"", lc_hex(&p, "snow0"))),
        (":base05", format!("\"{}\"", lc_hex(&p, "snow1"))),
        (":base06", format!("\"{}\"", lc_hex(&p, "snow2"))),
        (":base07", format!("\"{}\"", lc_hex(&p, "snow3"))),
        (":base08", format!("\"{}\"", lc_hex(&p, "aurora_red"))),
        (":base09", format!("\"{}\"", lc_hex(&p, "ember"))),
        (":base0a", format!("\"{}\"", lc_hex(&p, "first_light"))),
        (":base0b", format!("\"{}\"", lc_hex(&p, "aurora_green"))),
        (":base0c", format!("\"{}\"", lc_hex(&p, "ice_cyan"))),
        (":base0d", format!("\"{}\"", lc_hex(&p, "ice_steel"))),
        (":base0e", format!("\"{}\"", lc_hex(&p, "solar_magenta"))),
        (":base0f", format!("\"{}\"", lc_hex(&p, "dusk_bronze"))),
    ];
    writeln!(out, "{}", lisp_form("defpalette", &palette_kvs)).expect("write");
    out.push('\n');

    // ─ Highlights — group → token-role map. Mirrors the hand-authored
    //   vellum.lisp group set (escriba's CANONICAL_GROUPS + the
    //   tree-sitter overrides). ─
    let rows: &[HiRow] = &[
        // Syntax
        HiRow::fg_bg("Normal", "snow1", "night0"),
        HiRow::fg("Comment", "shadow1").i(),
        HiRow::fg("String", "aurora_green"),
        HiRow::fg("Number", "solar_magenta"),
        HiRow::fg("Boolean", "solar_magenta"),
        HiRow::fg("Function", "ice_steel").b(),
        HiRow::fg("Keyword", "solar_magenta").i(),
        HiRow::fg("Statement", "solar_magenta"),
        HiRow::fg("Conditional", "solar_magenta"),
        HiRow::fg("Repeat", "solar_magenta"),
        HiRow::fg("Operator", "solar_magenta"),
        HiRow::fg("Type", "first_light"),
        HiRow::fg("Structure", "first_light"),
        HiRow::fg("Identifier", "snow1"),
        HiRow::fg("Constant", "ember"),
        HiRow::fg("PreProc", "ember"),
        HiRow::fg("Macro", "ember"),
        HiRow::fg("Special", "first_light"),
        // UI
        HiRow::bg("CursorLine", "night1"),
        HiRow::bg("CursorColumn", "night1"),
        HiRow::fg("LineNr", "shadow1"),
        HiRow::bg("SignColumn", "night0"),
        HiRow::bg("Visual", "night2"),
        HiRow::bg("VisualNOS", "night2"),
        HiRow::fg_bg("Search", "night0", "first_light"),
        HiRow::fg_bg("IncSearch", "night0", "ember").b(),
        HiRow::fg("MatchParen", "ember").b(),
        HiRow::fg_bg("StatusLine", "snow1", "night1"),
        HiRow::fg_bg("StatusLineNC", "shadow1", "night0"),
        HiRow::fg_bg("TabLine", "shadow1", "night0"),
        HiRow::bg("TabLineFill", "night0"),
        HiRow::fg_bg("TabLineSel", "night0", "ice_cyan").b(),
        HiRow::fg("VertSplit", "night3"),
        HiRow::fg_bg("Pmenu", "snow1", "night1"),
        HiRow::fg_bg("PmenuSel", "night0", "ice_cyan").b(),
        HiRow::bg("PmenuSbar", "night1"),
        HiRow::bg("PmenuThumb", "shadow1"),
        HiRow::fg_bg("NormalFloat", "snow1", "night1"),
        HiRow::fg_bg("FloatBorder", "ice_steel", "night1"),
        // Diagnostics
        HiRow::fg("DiagnosticError", "aurora_red").b(),
        HiRow::fg("DiagnosticWarn", "first_light"),
        HiRow::fg("DiagnosticInfo", "ice_cyan"),
        HiRow::fg("DiagnosticHint", "aurora_green"),
        // Git (gitsigns parity) + diff backgrounds (the GLASS blends)
        HiRow::fg("GitSignsAdd", "aurora_green"),
        HiRow::fg("GitSignsChange", "first_light"),
        HiRow::fg("GitSignsDelete", "aurora_red"),
        HiRow::bg("DiffAdd", "green_glass"),
        HiRow::bg("DiffChange", "amber_glass"),
        HiRow::bg("DiffDelete", "red_glass"),
        HiRow::bg("DiffText", "steel_glass"),
        // Tree-sitter semantic overrides
        HiRow::link("@function.call", "Function"),
        HiRow::link("@variable", "Identifier"),
        HiRow::fg("@parameter", "snow1").i(),
        HiRow::fg("@comment.todo", "first_light").b(),
        HiRow::fg("@comment.note", "ice_cyan").b(),
        HiRow::fg("@comment.warning", "ember").b(),
    ];

    for r in rows {
        let mut kvs: Vec<(&str, String)> = vec![(":group", format!("\"{}\"", r.group))];
        if r.link.is_empty() {
            if !r.fg.is_empty() {
                kvs.push((":fg", format!("\"{}\"", lc_hex(&p, r.fg))));
            }
            if !r.bg.is_empty() {
                kvs.push((":bg", format!("\"{}\"", lc_hex(&p, r.bg))));
            }
            if r.bold {
                kvs.push((":bold", "#t".to_string()));
            }
            if r.italic {
                kvs.push((":italic", "#t".to_string()));
            }
        } else {
            kvs.push((":link", format!("\"{}\"", r.link)));
        }
        writeln!(out, "{}", lisp_form("defhighlight", &kvs)).expect("write");
    }

    out
}

#[cfg(test)]
mod tests {

    /// The nix attrset and the YAML scheme are the SAME palette.
    ///
    /// They are two renders of one source, and the whole point of the nix
    /// one is that consumers can switch to it — so a divergence would be a
    /// silent colour change on every fleet desktop, visible to nobody until
    /// someone noticed their terminal looked wrong.
    #[test]
    fn the_nix_render_carries_the_same_palette_as_the_yaml() {
        let yaml = super::render_base16();
        let nixs = super::render_base16_nix();
        for (slot, rgb) in VellumPalette::vellum().base16() {
            let hex = super::slot_hex(rgb);
            assert!(
                yaml.contains(&format!("{slot}: {hex}")),
                "yaml missing {slot}"
            );
            assert!(
                nixs.contains(&format!("{slot} = \"{hex}\";")),
                "nix missing {slot}"
            );
        }
    }

    /// The scheme's IDENTITY survives the YAML -> attrset move.
    ///
    /// base16.nix defaults every absent metadata field — `scheme`/`author`
    /// to "untitled", `variant` to "unspecified" — and those strings are
    /// interpolated into generated artefact NAMES (`base16-${slug}`,
    /// `"Base16 ${scheme-name}"`, `${slug}-gnome-shell-theme`). So a
    /// metadata-less attrset is not a smaller scheme; it is an ANONYMOUS
    /// one, byte-identical in colour and renaming a pile of store paths.
    /// Nothing breaks, which is exactly why nothing would have caught it.
    #[test]
    fn the_nix_render_keeps_the_scheme_identity_not_just_the_colours() {
        let out = super::render_base16_nix();
        for (k, v) in [
            ("system", "base16"),
            ("name", "Vellum"),
            ("author", "pleme-io (ishou)"),
            ("variant", "dark"),
            ("slug", "vellum"),
        ] {
            assert!(
                out.contains(&format!("{k} = \"{v}\";")),
                "missing {k}; without it base16.nix names the scheme \"untitled\""
            );
        }
    }

    /// stylix decides how to read a scheme with
    /// `is-not-parsed = builtins.isAttrs scheme && !(scheme ? "yaml")`.
    /// The whole IFD-avoidance rests on this file being a bare attrset with
    /// no `yaml` key — a `yaml = ` anywhere in it would silently restore
    /// the readFile path and the linux build with it.
    #[test]
    fn the_nix_render_is_a_bare_attrset_with_no_yaml_key() {
        let out = super::render_base16_nix();
        let body: String = out.lines().filter(|l| !l.starts_with('#')).collect();
        assert!(
            body.trim_start().starts_with('{'),
            "must be an attrset: {body}"
        );
        assert!(
            !body.contains("yaml"),
            "a `yaml` key would put stylix back on the IFD path"
        );
        // A lambda would make it `import path { … }`, not `import path`.
        assert!(!body.contains(':'), "must not be a function: {body}");
    }
    use super::*;

    #[test]
    fn base16_is_deterministic() {
        assert_eq!(render_base16(), render_base16());
    }

    #[test]
    fn skim_string_is_deterministic() {
        assert_eq!(render_skim(), render_skim());
    }

    #[test]
    fn skim_string_matches_the_authored_vellum_string() {
        // The exact byte sequence `pleme-io/skim-tab::NORD_COLORS` ships
        // (joined with `,` — no trailing newline). Generated from the
        // typed Vellum tokens.
        let expected = "\
fg:#E2DBC8,\
bg:#16140E,\
hl:#94BBB8:bold:underlined,\
fg+:#F4EFE2:bold,\
bg+:#2B2820,\
hl+:#A6CBC8:bold:underlined,\
info:#6E6857,\
prompt:#A9BB8C,\
pointer:#ADD7A3,\
marker:#B8A1B9,\
spinner:#99AABE,\
header:#99AABE,\
border:#6E6857,\
query:#F4EFE2:bold";
        assert_eq!(render_skim(), expected, "skim --color string drifted");
    }

    #[test]
    fn escriba_lisp_is_deterministic() {
        assert_eq!(render_escriba_lisp(), render_escriba_lisp());
    }

    #[test]
    fn escriba_lisp_has_palette_and_key_highlights() {
        let out = render_escriba_lisp();
        // defpalette base00 = night0, lowercase.
        assert!(
            out.contains("(defpalette :name \"vellum\" :base00 \"#16140e\""),
            "defpalette base00 missing/drifted:\n{out}"
        );
        // A handful of canonical groups, exact emitted lines.
        for line in [
            "(defhighlight :group \"Normal\" :fg \"#e2dbc8\" :bg \"#16140e\")",
            "(defhighlight :group \"Comment\" :fg \"#90897b\" :italic #t)",
            "(defhighlight :group \"String\" :fg \"#a9bb8c\")",
            "(defhighlight :group \"Function\" :fg \"#99aabe\" :bold #t)",
            "(defhighlight :group \"DiffAdd\" :bg \"#4d543e\")",
            "(defhighlight :group \"@function.call\" :link \"Function\")",
        ] {
            assert!(out.contains(line), "missing line `{line}`\n{out}");
        }
        // Every CANONICAL group label appears as an emitted group.
        for g in [
            "Normal",
            "Comment",
            "String",
            "Number",
            "Boolean",
            "Function",
            "Keyword",
            "Statement",
            "Type",
            "Constant",
            "Special",
            "Visual",
            "Search",
            "DiagnosticError",
            "GitSignsAdd",
        ] {
            assert!(
                out.contains(&format!(":group \"{g}\"")),
                "missing group {g}\n{out}"
            );
        }
    }

    #[test]
    fn base16_has_all_16_slots_lowercase_unprefixed() {
        let out = render_base16();
        for slot in [
            "base00", "base01", "base02", "base03", "base04", "base05", "base06", "base07",
            "base08", "base09", "base0A", "base0B", "base0C", "base0D", "base0E", "base0F",
        ] {
            assert!(out.contains(slot), "missing {slot}");
        }
        // base00 is night0 (#16140E → 16140e), unprefixed lc.
        assert!(out.contains("16140e"), "base00 night0 missing:\n{out}");
        // No leading `#` on any value (would break GTK theme-gen).
        assert!(!out.contains(": #"), "found prefixed hex:\n{out}");
    }

    #[test]
    fn base16_slots_match_the_born_palette() {
        let p = VellumPalette::vellum();
        let out = render_base16();
        for (slot, rgb) in p.base16() {
            let want = format!("{slot}: {}", slot_hex(rgb));
            assert!(
                out.contains(&want),
                "slot {slot} drifted; want `{want}`\n{out}"
            );
        }
    }

    #[test]
    fn base24_has_the_real_brights() {
        let out = render_base24();
        // base14 = green_bright (#ADD7A3), base12 = red_bright (#D49088).
        assert!(
            out.contains("base14: add7a3"),
            "base14 green_bright:\n{out}"
        );
        assert!(out.contains("base12: d49088"), "base12 red_bright:\n{out}");
        assert!(out.contains("system: base24"), "wrong system tag:\n{out}");
    }

    #[test]
    fn svg_palette_is_deterministic_and_covers_every_token() {
        let a = render_svg_palette();
        assert_eq!(a, render_svg_palette());
        let p = VellumPalette::vellum();
        for (name, _) in p.entries() {
            assert!(a.contains(name), "svg missing token {name}");
        }
    }
}