Skip to main content

max / makeover

77.6 KB · 2201 lines History Blame Raw
1 //! Shared theme loading + intent resolution for TOML-based theme files.
2 //!
3 //! Used by GoingsOn, Balanced Breakfast (Tauri apps), audiofiles (egui), and the
4 //! MNW web server. Themes are authored by **intent** ("human design"): colors are
5 //! declared by role (surface / content / action / status / line / category), not
6 //! by hue. This crate is the single place that resolves an authored theme into a
7 //! full set of intent tokens — including the derived interactive states
8 //! (hover/active/selection/row-stripe/contrast) that each app used to recompute
9 //! itself — and emits them as CSS variables or RGB tuples.
10 //!
11 //! Theme file shape:
12 //! ```text
13 //! [meta]
14 //! name = "Nord"
15 //! variant = "dark" # or "light"
16 //!
17 //! [surface] # container backgrounds by role/elevation
18 //! page = "#2e3440"; raised = "#3b4252"; sunken = "#434c5e"; overlay = "#3b4252"
19 //!
20 //! [content] # text/ink by emphasis
21 //! primary = "#d8dee9"; secondary = "#e5e9f0"; muted = "#616e88"
22 //!
23 //! [action] # interactive / brand color
24 //! primary = "#81a1c1"
25 //!
26 //! [status] # state semantics
27 //! danger = "#bf616a"; success = "#a3be8c"; warning = "#ebcb8b"; info = "#88c0d0"
28 //!
29 //! [line]
30 //! border = "#4c566a"
31 //!
32 //! [category] # distinct decorative colors for tags/badges/charts
33 //! one = "#bf616a"; two = "#a3be8c"; three = "#81a1c1"
34 //! four = "#ebcb8b"; five = "#b48ead"; six = "#88c0d0"
35 //! ```
36
37 // Color-space math: single-letter channel names (r/g/b/l/m/s) and the published
38 // high-precision OKLab/sRGB matrix constants are the domain vocabulary here.
39 #![allow(clippy::many_single_char_names, clippy::unreadable_literal)]
40
41 use serde::Serialize;
42 use std::collections::{BTreeMap, HashMap};
43 use std::path::{Path, PathBuf};
44
45 /// The color sections an authored theme may declare.
46 pub const COLOR_SECTIONS: &[&str] = &["surface", "content", "action", "status", "line", "category"];
47
48 /// Theme metadata parsed from the `[meta]` section.
49 #[derive(Debug, Clone, Serialize)]
50 #[serde(rename_all = "camelCase")]
51 pub struct ThemeMeta {
52 pub id: String,
53 pub name: String,
54 pub variant: String,
55 pub is_custom: bool,
56 }
57
58 /// A loaded theme: metadata plus the authored colors, flattened to dotted keys
59 /// (e.g. `"surface.page"`, `"status.danger"`, `"category.one"`).
60 #[derive(Debug, Serialize)]
61 #[serde(rename_all = "camelCase")]
62 pub struct ThemeColors {
63 pub meta: ThemeMeta,
64 pub colors: HashMap<String, String>,
65 }
66
67 // ============================================================================
68 // Color math — perceptual (OKLab) derivations + WCAG contrast.
69 //
70 // Interactive states (hover/active/selection/surfaces) are derived in OKLab so
71 // equal steps look equal across every theme's hues (Ottosson 2020; the modern
72 // CIELAB). Text-on-color is picked by the WCAG 2.x contrast ratio, not a naive
73 // luminance threshold, so the choice actually meets AA where achievable.
74 // This is the single source of truth shared by every product.
75 // ============================================================================
76
77 /// An sRGB color. Hex round-trips losslessly.
78 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
79 pub struct Rgb {
80 pub r: u8,
81 pub g: u8,
82 pub b: u8,
83 }
84
85 impl Rgb {
86 /// Parse `#rgb` or `#rrggbb` (case-insensitive). Returns `None` otherwise.
87 pub fn from_hex(s: &str) -> Option<Rgb> {
88 let h = s.strip_prefix('#')?;
89 let (r, g, b) = match h.len() {
90 6 => (
91 u8::from_str_radix(&h[0..2], 16).ok()?,
92 u8::from_str_radix(&h[2..4], 16).ok()?,
93 u8::from_str_radix(&h[4..6], 16).ok()?,
94 ),
95 3 => {
96 let d = |c: &str| u8::from_str_radix(c, 16).ok().map(|v| v * 17);
97 (d(&h[0..1])?, d(&h[1..2])?, d(&h[2..3])?)
98 }
99 _ => return None,
100 };
101 Some(Rgb { r, g, b })
102 }
103
104 /// Lowercase `#rrggbb`.
105 pub fn to_hex(self) -> String {
106 format!("#{:02x}{:02x}{:02x}", self.r, self.g, self.b)
107 }
108
109 pub fn tuple(self) -> (u8, u8, u8) {
110 (self.r, self.g, self.b)
111 }
112 }
113
114 /// A color in OKLab (perceptually uniform): `l` lightness in [0,1], `a`/`b` opponent axes.
115 #[derive(Clone, Copy, Debug)]
116 pub struct Oklab {
117 pub l: f32,
118 pub a: f32,
119 pub b: f32,
120 }
121
122 fn srgb_to_linear(c: u8) -> f32 {
123 let c = c as f32 / 255.0;
124 if c <= 0.04045 {
125 c / 12.92
126 } else {
127 ((c + 0.055) / 1.055).powf(2.4)
128 }
129 }
130
131 fn linear_to_srgb(c: f32) -> u8 {
132 let c = c.clamp(0.0, 1.0);
133 let v = if c <= 0.0031308 {
134 c * 12.92
135 } else {
136 1.055 * c.powf(1.0 / 2.4) - 0.055
137 };
138 (v * 255.0).round().clamp(0.0, 255.0) as u8
139 }
140
141 impl Rgb {
142 /// Convert to OKLab (Ottosson's sRGB matrices).
143 ///
144 /// The matrix coefficients are quoted at their published precision so they
145 /// can be diffed against the reference. `f32` rounds them at compile time;
146 /// truncating the literals would only make them harder to check.
147 #[allow(clippy::excessive_precision)]
148 pub fn to_oklab(self) -> Oklab {
149 let (r, g, b) = (
150 srgb_to_linear(self.r),
151 srgb_to_linear(self.g),
152 srgb_to_linear(self.b),
153 );
154 let l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
155 let m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
156 let s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
157 let (l_, m_, s_) = (l.cbrt(), m.cbrt(), s.cbrt());
158 Oklab {
159 l: 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_,
160 a: 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_,
161 b: 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_,
162 }
163 }
164
165 /// Convert from OKLab back to the nearest in-gamut sRGB.
166 ///
167 /// Published precision, as in [`Rgb::to_oklab`].
168 #[allow(clippy::excessive_precision)]
169 pub fn from_oklab(c: Oklab) -> Rgb {
170 let l_ = c.l + 0.3963377774 * c.a + 0.2158037573 * c.b;
171 let m_ = c.l - 0.1055613458 * c.a - 0.0638541728 * c.b;
172 let s_ = c.l - 0.0894841775 * c.a - 1.2914855480 * c.b;
173 let (l, m, s) = (l_ * l_ * l_, m_ * m_ * m_, s_ * s_ * s_);
174 Rgb {
175 r: linear_to_srgb(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
176 g: linear_to_srgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
177 b: linear_to_srgb(-0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s),
178 }
179 }
180 }
181
182 /// WCAG 2.x relative luminance of an sRGB color.
183 fn rel_luminance(c: Rgb) -> f32 {
184 0.2126 * srgb_to_linear(c.r) + 0.7152 * srgb_to_linear(c.g) + 0.0722 * srgb_to_linear(c.b)
185 }
186
187 /// WCAG 2.x contrast ratio between two colors, in [1, 21].
188 pub fn wcag_contrast(a: Rgb, b: Rgb) -> f32 {
189 let (la, lb) = (rel_luminance(a), rel_luminance(b));
190 let (hi, lo) = if la >= lb { (la, lb) } else { (lb, la) };
191 (hi + 0.05) / (lo + 0.05)
192 }
193
194 /// Pick black or white for legible text on `bg`, by the higher WCAG contrast
195 /// ratio (so the choice meets AA wherever the background allows it).
196 pub fn readable_on(bg: Rgb) -> Rgb {
197 let white = Rgb {
198 r: 255,
199 g: 255,
200 b: 255,
201 };
202 let black = Rgb { r: 0, g: 0, b: 0 };
203 if wcag_contrast(white, bg) >= wcag_contrast(black, bg) {
204 white
205 } else {
206 black
207 }
208 }
209
210 /// Shift OKLab lightness by `delta` (perceptually uniform). Positive lightens.
211 pub fn lighten(c: Rgb, delta: f32) -> Rgb {
212 let mut lab = c.to_oklab();
213 lab.l = (lab.l + delta).clamp(0.0, 1.0);
214 Rgb::from_oklab(lab)
215 }
216
217 /// Shift OKLab lightness down by `delta` (perceptually uniform).
218 pub fn darken(c: Rgb, delta: f32) -> Rgb {
219 lighten(c, -delta)
220 }
221
222 /// Interpolate between `a` and `b` by `t` in [0,1] in OKLab (perceptual blend).
223 pub fn mix(a: Rgb, b: Rgb, t: f32) -> Rgb {
224 let (x, y) = (a.to_oklab(), b.to_oklab());
225 Rgb::from_oklab(Oklab {
226 l: x.l + (y.l - x.l) * t,
227 a: x.a + (y.a - x.a) * t,
228 b: x.b + (y.b - x.b) * t,
229 })
230 }
231
232 // ============================================================================
233 // Low-color terminals
234 // ============================================================================
235
236 /// The 16 colors an ANSI terminal addresses by index, in the PC/VGA
237 /// arrangement the Linux console and most emulators start from.
238 ///
239 /// 0-7 are the normal colors and 8-15 the bright ones. Index 7 is a light gray
240 /// rather than white, which is the entry a themed surface usually lands on, and
241 /// index 15 is the true white.
242 ///
243 /// Emulators let the user repaint all sixteen, so this is the standard
244 /// arrangement rather than a promise about any one terminal. The Linux console
245 /// keeps it, which is the case that matters: a console app cannot fall back to
246 /// 24-bit color there.
247 pub const ANSI_16: [Rgb; 16] = [
248 Rgb {
249 r: 0x00,
250 g: 0x00,
251 b: 0x00,
252 },
253 Rgb {
254 r: 0xaa,
255 g: 0x00,
256 b: 0x00,
257 },
258 Rgb {
259 r: 0x00,
260 g: 0xaa,
261 b: 0x00,
262 },
263 Rgb {
264 r: 0xaa,
265 g: 0x55,
266 b: 0x00,
267 },
268 Rgb {
269 r: 0x00,
270 g: 0x00,
271 b: 0xaa,
272 },
273 Rgb {
274 r: 0xaa,
275 g: 0x00,
276 b: 0xaa,
277 },
278 Rgb {
279 r: 0x00,
280 g: 0xaa,
281 b: 0xaa,
282 },
283 Rgb {
284 r: 0xaa,
285 g: 0xaa,
286 b: 0xaa,
287 },
288 Rgb {
289 r: 0x55,
290 g: 0x55,
291 b: 0x55,
292 },
293 Rgb {
294 r: 0xff,
295 g: 0x55,
296 b: 0x55,
297 },
298 Rgb {
299 r: 0x55,
300 g: 0xff,
301 b: 0x55,
302 },
303 Rgb {
304 r: 0xff,
305 g: 0xff,
306 b: 0x55,
307 },
308 Rgb {
309 r: 0x55,
310 g: 0x55,
311 b: 0xff,
312 },
313 Rgb {
314 r: 0xff,
315 g: 0x55,
316 b: 0xff,
317 },
318 Rgb {
319 r: 0x55,
320 g: 0xff,
321 b: 0xff,
322 },
323 Rgb {
324 r: 0xff,
325 g: 0xff,
326 b: 0xff,
327 },
328 ];
329
330 /// The 256 colors an xterm-compatible terminal addresses by index, so that
331 /// entry `i` is what the terminal paints for `38;5;i`.
332 ///
333 /// Three regions, and they are not equally trustworthy. 0-15 are the [`ANSI_16`]
334 /// system colors, which every emulator lets the user repaint. 16-231 are a
335 /// 6x6x6 RGB cube and 232-255 a 24-step gray ramp, and those 240 are fixed.
336 ///
337 /// So a color whose whole job is to be told apart from another should quantize
338 /// against [`ANSI_240`] rather than against this table: a match landing in the
339 /// low sixteen is a match against a color the user may have moved.
340 pub const ANSI_256: [Rgb; 256] = build_ansi_256();
341
342 /// The fixed region of [`ANSI_256`]: the 6x6x6 cube and the gray ramp, without
343 /// the sixteen repaintable system colors.
344 ///
345 /// Quantizing against this returns an index into *this* slice; add
346 /// [`ANSI_240_OFFSET`] to get the index the terminal wants.
347 pub const ANSI_240: &[Rgb] = ANSI_256.split_at(16).1;
348
349 /// What to add to an [`ANSI_240`] index to get an [`ANSI_256`] one.
350 pub const ANSI_240_OFFSET: usize = 16;
351
352 const fn build_ansi_256() -> [Rgb; 256] {
353 let mut table = [Rgb { r: 0, g: 0, b: 0 }; 256];
354
355 let mut i = 0;
356 while i < 16 {
357 table[i] = ANSI_16[i];
358 i += 1;
359 }
360
361 // The cube's six levels are not evenly spaced. The step from black to the
362 // first is more than twice any later one, which is xterm's arrangement
363 // rather than a choice available here, and it is why the darkest tones a
364 // theme can reach on 256 colors come from the gray ramp instead.
365 const LEVELS: [u8; 6] = [0, 95, 135, 175, 215, 255];
366 let mut r = 0;
367 while r < 6 {
368 let mut g = 0;
369 while g < 6 {
370 let mut b = 0;
371 while b < 6 {
372 table[16 + 36 * r + 6 * g + b] = Rgb {
373 r: LEVELS[r],
374 g: LEVELS[g],
375 b: LEVELS[b],
376 };
377 b += 1;
378 }
379 g += 1;
380 }
381 r += 1;
382 }
383
384 // 8 to 238 in steps of 10. Neither end is black or white; both of those are
385 // in the cube, so the ramp is 24 steps of gray between them rather than 24
386 // steps of the whole range.
387 let mut k = 0;
388 while k < 24 {
389 let v = 8 + 10 * k as u8;
390 table[232 + k as usize] = Rgb { r: v, g: v, b: v };
391 k += 1;
392 }
393
394 table
395 }
396
397 /// The contrast ratio two colors must clear to read as separate areas.
398 ///
399 /// WCAG 2.x asks 3:1 of user interface components and graphics, which is what
400 /// a border, a rule, or a focus ring is. Text wants more, and a caller drawing
401 /// text can ask for more by checking [`wcag_contrast`] itself.
402 pub const DISTINCT: f32 = 3.0;
403
404 /// Perceptual distance between two colors, for choosing the closest of a set.
405 fn oklab_distance(a: Rgb, b: Rgb) -> f32 {
406 let (x, y) = (a.to_oklab(), b.to_oklab());
407 ((x.l - y.l).powi(2) + (x.a - y.a).powi(2) + (x.b - y.b).powi(2)).sqrt()
408 }
409
410 /// Index of the entry in `palette` that looks most like `c`.
411 ///
412 /// OKLab distance rather than distance in sRGB, for the same reason [`mix`]
413 /// interpolates there: sRGB's numbers are not spaced the way seeing is, so a
414 /// nearest match computed in it picks visibly wrong entries in the mid tones.
415 ///
416 /// # Panics
417 ///
418 /// If `palette` is empty.
419 pub fn quantize(c: Rgb, palette: &[Rgb]) -> usize {
420 assert!(!palette.is_empty(), "a palette needs at least one color");
421 let mut best = 0;
422 let mut best_distance = f32::INFINITY;
423 for (index, entry) in palette.iter().enumerate() {
424 let distance = oklab_distance(c, *entry);
425 if distance < best_distance {
426 best = index;
427 best_distance = distance;
428 }
429 }
430 best
431 }
432
433 /// Index of the entry in `palette` closest to `fg` that still reads against
434 /// `bg`.
435 ///
436 /// [`quantize`] answers about one color at a time, and two colors that differ
437 /// can quantize to the same entry: a themed page and a border drawn on it are
438 /// often a few steps apart in a 24-bit theme and land together on a 16-color
439 /// terminal, leaving one flat area where there was a frame. Alloy's console
440 /// showed exactly this, and it is not a contrived pairing: a light page and the
441 /// mid-tone border derived from it both land on index 7.
442 ///
443 /// So the background is quantized first, because what the border must be
444 /// distinguished from is the entry the terminal will actually paint, not the
445 /// color the theme asked for. Then the nearest entry to `fg` clearing
446 /// [`DISTINCT`] against it wins. When nothing clears it, the entry that gets
447 /// furthest does: at that point the palette cannot honor the design, and the
448 /// most legible approximation beats the closest invisible one.
449 ///
450 /// Only for colors whose whole job is to be told apart from their background.
451 /// Applied to every token it would push a deliberately quiet one until it
452 /// shouted.
453 ///
454 /// # Panics
455 ///
456 /// If `palette` is empty.
457 pub fn quantize_against(fg: Rgb, bg: Rgb, palette: &[Rgb]) -> usize {
458 assert!(!palette.is_empty(), "a palette needs at least one color");
459 let shown = palette[quantize(bg, palette)];
460
461 let mut order: Vec<usize> = (0..palette.len()).collect();
462 order.sort_by(|a, b| {
463 oklab_distance(fg, palette[*a]).total_cmp(&oklab_distance(fg, palette[*b]))
464 });
465
466 order
467 .iter()
468 .copied()
469 .find(|index| wcag_contrast(palette[*index], shown) >= DISTINCT)
470 .unwrap_or_else(|| {
471 order
472 .iter()
473 .copied()
474 .max_by(|a, b| {
475 wcag_contrast(palette[*a], shown).total_cmp(&wcag_contrast(palette[*b], shown))
476 })
477 .expect("the palette is not empty")
478 })
479 }
480
481 // ============================================================================
482 // Intent resolution
483 // ============================================================================
484
485 /// Authored base intents: (TOML dotted source key, canonical token key).
486 /// These are read straight from the theme; the token key is the CSS-var stem
487 /// (`--{token}`) and the `rgb()` lookup key.
488 pub const BASE_INTENTS: &[(&str, &str)] = &[
489 ("surface.page", "surface-page"),
490 ("surface.raised", "surface-raised"),
491 ("surface.sunken", "surface-sunken"),
492 ("surface.overlay", "surface-overlay"),
493 ("content.primary", "content"),
494 ("content.secondary", "content-secondary"),
495 ("content.muted", "content-muted"),
496 ("action.primary", "action"),
497 ("status.danger", "danger"),
498 ("status.success", "success"),
499 ("status.warning", "warning"),
500 ("status.info", "info"),
501 ("line.border", "border"),
502 ("category.one", "category-one"),
503 ("category.two", "category-two"),
504 ("category.three", "category-three"),
505 ("category.four", "category-four"),
506 ("category.five", "category-five"),
507 ("category.six", "category-six"),
508 ];
509
510 /// A fully resolved intent layer: every token key → concrete `#rrggbb`.
511 /// Includes both authored base intents and the computed derived intents.
512 #[derive(Debug, Clone, Serialize)]
513 #[serde(rename_all = "camelCase")]
514 pub struct SemanticTokens {
515 pub meta: ThemeMeta,
516 /// token-key → resolved hex. Stable, deterministic ordering.
517 pub intents: BTreeMap<String, String>,
518 }
519
520 impl SemanticTokens {
521 /// Resolved hex for a token key, if present.
522 pub fn hex(&self, key: &str) -> Option<&str> {
523 self.intents.get(key).map(String::as_str)
524 }
525
526 /// Resolved RGB tuple for a token key (for egui / native consumers).
527 pub fn rgb(&self, key: &str) -> Option<(u8, u8, u8)> {
528 self.intents
529 .get(key)
530 .and_then(|h| Rgb::from_hex(h))
531 .map(Rgb::tuple)
532 }
533 }
534
535 /// Resolve an authored theme into the full intent token set.
536 ///
537 /// 1. Copy each present base intent from the authored colors.
538 /// 2. Compute the derived interactive states from the base intents, using the
539 /// same math the apps used to apply individually (so output is identical).
540 ///
541 /// Each derived token is emitted only when its source intents exist, mirroring
542 /// the skip-missing behavior of the rest of the crate.
543 pub fn resolve(theme: &ThemeColors) -> SemanticTokens {
544 let mut intents: BTreeMap<String, String> = BTreeMap::new();
545
546 // 1. Base intents (authored). Copy only values that parse as a hex color and
547 // re-emit them in canonical `#rrggbb` form, so an authored value can never
548 // carry arbitrary bytes into the emitted CSS (the resolved tokens are inlined
549 // raw into a `<style>` block by the web server). A malformed value is skipped,
550 // mirroring the skip-missing behavior for absent intents.
551 for (src, token) in BASE_INTENTS {
552 if let Some(rgb) = theme.colors.get(*src).and_then(|v| Rgb::from_hex(v)) {
553 intents.insert((*token).to_string(), rgb.to_hex());
554 }
555 }
556
557 // Helper: parse an already-resolved token to Rgb.
558 let get = |m: &BTreeMap<String, String>, k: &str| m.get(k).and_then(|h| Rgb::from_hex(h));
559
560 // 2. Derived intents — perceptual (OKLab) steps + WCAG-picked text.
561 // Lightness deltas are in OKLab L units; mix ratios interpolate in OKLab.
562 let mut derived: Vec<(String, Rgb)> = Vec::new();
563 if let Some(action) = get(&intents, "action") {
564 derived.push(("action-hover".into(), lighten(action, 0.05)));
565 derived.push(("content-on-action".into(), readable_on(action)));
566 derived.push(("focus-ring".into(), action));
567 }
568 if let Some(page) = get(&intents, "surface-page") {
569 // Modal scrim: a near-black tone carrying a faint hint of the theme's
570 // hue, at 50% alpha. Anchored very dark (OKLab L=0.08) so it dims the
571 // page on light *and* dark themes. Emitted as rgba (not a flat hex), so
572 // it is inserted directly rather than through the hex loop below.
573 let mut o = page.to_oklab();
574 o.l = 0.08;
575 let s = Rgb::from_oklab(o);
576 intents.insert(
577 "overlay".into(),
578 format!("rgba({}, {}, {}, 0.5)", s.r, s.g, s.b),
579 );
580 }
581 if let Some(raised) = get(&intents, "surface-raised") {
582 // The two edges of a bevel: a raised control is lit from the top left,
583 // so its top and left edges take `bevel-light` and its bottom and right
584 // edges `bevel-dark`. Inverting the pair gives a pressed state and an
585 // inset well, which is what makes the idiom cheap for a consumer.
586 //
587 // Derived here rather than composed per-app because the two webviews
588 // could do it in `color-mix()` and audiofiles, which is egui, could not.
589 // Geometry (thickness, radius, which side gets which) stays app-side.
590 //
591 // The deltas are asymmetric because the eye is: an equal step down reads
592 // as a smaller change than the same step up, so the shadow is cut deeper
593 // than the highlight is raised.
594 //
595 // A face already at the top of the ramp cannot hold a highlight — the
596 // lightening clamps and the control bevels on two sides without ever
597 // resolving as lit. That is a property of the theme, not of this
598 // derivation; `bevel_edges_are_distinct_from_their_face` names the
599 // shipped themes it currently bites.
600 derived.push(("bevel-light".into(), lighten(raised, 0.14)));
601 derived.push(("bevel-dark".into(), darken(raised, 0.18)));
602 }
603 if let Some(sunken) = get(&intents, "surface-sunken") {
604 derived.push(("hover-surface".into(), sunken));
605 }
606 if let Some(border) = get(&intents, "border") {
607 derived.push(("border-strong".into(), darken(border, 0.05)));
608 }
609
610 for (token, rgb) in derived {
611 intents.insert(token, rgb.to_hex());
612 }
613
614 SemanticTokens {
615 meta: theme.meta.clone(),
616 intents,
617 }
618 }
619
620 /// Emit the resolved intent layer as CSS declarations (no selector), one
621 /// ` --token: #hex;` line each, in deterministic (BTreeMap) order.
622 pub fn intent_css_declarations(tokens: &SemanticTokens) -> String {
623 let mut out = String::new();
624 for (token, hex) in &tokens.intents {
625 out.push_str(" --");
626 out.push_str(token);
627 out.push_str(": ");
628 out.push_str(hex);
629 out.push_str(";\n");
630 }
631 out
632 }
633
634 /// Emit the resolved intent layer as a `:root { … }` block — the single TOML →
635 /// CSS mapping every web surface injects.
636 pub fn intent_css_vars(tokens: &SemanticTokens) -> String {
637 format!(":root {{\n{}}}\n", intent_css_declarations(tokens))
638 }
639
640 // ============================================================================
641 // Loading / parsing
642 // ============================================================================
643
644 /// Validate a theme ID contains only safe characters (alphanumeric, hyphens, underscores).
645 pub fn validate_theme_id(id: &str) -> Result<(), String> {
646 if !id
647 .chars()
648 .all(|c| c.is_alphanumeric() || c == '-' || c == '_')
649 {
650 return Err(format!("Invalid theme ID: {id}"));
651 }
652 Ok(())
653 }
654
655 /// Parse the `[meta]` section into `ThemeMeta`.
656 ///
657 /// Falls back to the file ID as the name and `"dark"` as the variant.
658 pub fn parse_meta(id: &str, table: &toml::Table, is_custom: bool) -> ThemeMeta {
659 let meta = table.get("meta").and_then(|m| m.as_table());
660 let name = meta
661 .and_then(|m| m.get("name"))
662 .and_then(|v| v.as_str())
663 .unwrap_or(id)
664 .to_string();
665 let variant = meta
666 .and_then(|m| m.get("variant"))
667 .and_then(|v| v.as_str())
668 .unwrap_or("dark")
669 .to_string();
670
671 ThemeMeta {
672 id: id.to_string(),
673 name,
674 variant,
675 is_custom,
676 }
677 }
678
679 // ============================================================================
680 // Choosing a theme.
681 //
682 // The file half of this crate was always shared; the *selection* half was not,
683 // and four apps re-rolled it four ways. GoingsOn stores a "system" sentinel in
684 // localStorage, Balanced Breakfast treats an absent value as follow-the-system
685 // and hardcodes two theme ids as its light/dark pair, audiofiles keeps the id
686 // in a synced SQLite table, and the Alloy console parses COLORFGBG. They also
687 // disagreed about what a variant string means: this crate defaults a missing
688 // one to "dark" while alloy_tui parsed an unrecognized one as light.
689 //
690 // What cannot be shared is the store — localStorage, a synced config table and
691 // a TOML file are genuinely different places. What can be shared, and is here,
692 // is the *meaning*: one vocabulary for variants, one encoding for "what did the
693 // user choose", and one rule for turning that into an id that exists.
694 // ============================================================================
695
696 /// A theme's kind, as declared by `meta.variant`.
697 ///
698 /// Three, not two: one shipped theme is `high-contrast`, and an app that
699 /// matched on light-or-dark alone would quietly file it under the wrong one.
700 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
701 #[serde(rename_all = "kebab-case")]
702 pub enum Variant {
703 Light,
704 Dark,
705 HighContrast,
706 }
707
708 impl Variant {
709 /// The spelling used in a theme file and in [`ThemeMeta::variant`].
710 #[must_use]
711 pub const fn as_str(self) -> &'static str {
712 match self {
713 Variant::Light => "light",
714 Variant::Dark => "dark",
715 Variant::HighContrast => "high-contrast",
716 }
717 }
718
719 /// Read a variant string, or `None` if it names none of them.
720 #[must_use]
721 pub fn parse(raw: &str) -> Option<Self> {
722 match raw {
723 "light" => Some(Variant::Light),
724 "dark" => Some(Variant::Dark),
725 "high-contrast" => Some(Variant::HighContrast),
726 _ => None,
727 }
728 }
729 }
730
731 impl std::fmt::Display for Variant {
732 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
733 f.write_str(self.as_str())
734 }
735 }
736
737 /// Anything unrecognized reads as dark, which is what [`parse_meta`] already
738 /// does with a missing one. Consumers that guessed light for an unknown string
739 /// were disagreeing with the crate that produced it.
740 impl From<&str> for Variant {
741 fn from(raw: &str) -> Self {
742 Variant::parse(raw).unwrap_or(Variant::Dark)
743 }
744 }
745
746 impl ThemeMeta {
747 /// This theme's variant as a value rather than a string.
748 #[must_use]
749 pub fn kind(&self) -> Variant {
750 Variant::from(self.variant.as_str())
751 }
752 }
753
754 /// The spelling of "follow whatever the system is doing", in every store.
755 pub const FOLLOW: &str = "system";
756
757 /// What the user chose, as opposed to what is being rendered.
758 ///
759 /// The distinction is the whole point: `Follow` is a standing instruction that
760 /// resolves differently as the ambient mode changes, and a `Fixed` id is an
761 /// answer that does not. An app that stored only the rendered id could not tell
762 /// the two apart the next time the system flipped to dark.
763 #[derive(Debug, Clone, PartialEq, Eq, Default)]
764 pub enum ThemeSelection {
765 /// Track the ambient light/dark mode.
766 #[default]
767 Follow,
768 /// Always this theme.
769 Fixed(String),
770 }
771
772 impl ThemeSelection {
773 /// Read a stored selection. An empty or absent value is [`Follow`], which
774 /// is what an app with nothing saved yet should do.
775 ///
776 /// [`Follow`]: ThemeSelection::Follow
777 #[must_use]
778 pub fn parse(raw: Option<&str>) -> Self {
779 match raw.map(str::trim) {
780 None | Some("" | FOLLOW) => ThemeSelection::Follow,
781 Some(id) => ThemeSelection::Fixed(id.to_string()),
782 }
783 }
784
785 /// The string to persist, whatever the store is.
786 #[must_use]
787 pub fn as_str(&self) -> &str {
788 match self {
789 ThemeSelection::Follow => FOLLOW,
790 ThemeSelection::Fixed(id) => id,
791 }
792 }
793
794 /// Turn a selection into a theme id that exists.
795 ///
796 /// `ambient` is the light/dark mode the app learned however it can: a
797 /// `prefers-color-scheme` media query, an OS appearance API, `COLORFGBG`
798 /// from a terminal. `available` is what [`list_themes_from_dirs`] found.
799 ///
800 /// A `Fixed` id that is no longer on disk falls through to the same path as
801 /// `Follow` rather than being returned anyway. Themes are deletable in
802 /// three of the four apps, and handing back an id that will fail to load
803 /// only moves the error somewhere less helpful.
804 ///
805 /// The fallback chain is: the app's own default for the ambient mode if it
806 /// is installed, then any installed theme of that variant, then the app's
807 /// default regardless. The last step means this always returns something,
808 /// and an app with no theme directory at all gets the id it ships with and
809 /// the load error it would have had anyway.
810 #[must_use]
811 pub fn resolve(
812 &self,
813 ambient: Variant,
814 defaults: &ThemeDefaults,
815 available: &[ThemeMeta],
816 ) -> String {
817 let installed = |id: &str| available.iter().any(|meta| meta.id == id);
818
819 if let ThemeSelection::Fixed(id) = self
820 && installed(id)
821 {
822 return id.clone();
823 }
824
825 let preferred = defaults.for_variant(ambient);
826 if installed(preferred) {
827 return preferred.to_string();
828 }
829 available
830 .iter()
831 .find(|meta| meta.kind() == ambient)
832 .map_or_else(|| preferred.to_string(), |meta| meta.id.clone())
833 }
834 }
835
836 impl std::fmt::Display for ThemeSelection {
837 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
838 f.write_str(self.as_str())
839 }
840 }
841
842 /// The themes an app falls back to, one per ambient mode.
843 ///
844 /// App-specific on purpose: which theme is "the app's own" is the app's
845 /// identity, not this crate's business. What is shared is everything around it.
846 #[derive(Debug, Clone)]
847 pub struct ThemeDefaults {
848 light: String,
849 dark: String,
850 high_contrast: Option<String>,
851 }
852
853 impl ThemeDefaults {
854 pub fn new(light: impl Into<String>, dark: impl Into<String>) -> Self {
855 Self {
856 light: light.into(),
857 dark: dark.into(),
858 high_contrast: None,
859 }
860 }
861
862 /// Name a theme for a high-contrast ambient mode. Without one, that mode
863 /// falls back to the dark default, which is the safer of the two to read.
864 #[must_use]
865 pub fn high_contrast(mut self, id: impl Into<String>) -> Self {
866 self.high_contrast = Some(id.into());
867 self
868 }
869
870 #[must_use]
871 pub fn for_variant(&self, variant: Variant) -> &str {
872 match variant {
873 Variant::Light => &self.light,
874 Variant::Dark => &self.dark,
875 Variant::HighContrast => self.high_contrast.as_ref().unwrap_or(&self.dark),
876 }
877 }
878 }
879
880 // ============================================================================
881 // Where themes are looked for.
882 //
883 // Four apps built this vector by hand, two of them byte-for-byte identically,
884 // and one of them built it backwards: the Alloy console pushed the user's own
885 // directory first, under a comment saying "highest precedence first", when both
886 // consumers of the vector resolve *last* wins. A user's custom theme lost to
887 // the packaged one of the same id.
888 //
889 // Hence a builder that names the tiers rather than a function taking a vector.
890 // The precedence is stated once, here, and a caller cannot express it backwards
891 // because the order is not theirs to choose.
892 // ============================================================================
893
894 /// Builds the search path [`load_theme`] and [`list_themes_from_dirs`] take.
895 ///
896 /// Tiers are added in whatever order is convenient and always end up in
897 /// precedence order: the user's own themes win, then whatever the system
898 /// ships, then whatever the app bundles.
899 ///
900 /// A directory that does not exist is dropped rather than carried, so callers
901 /// can offer every tier they might have without checking each one.
902 #[derive(Debug, Default, Clone)]
903 pub struct ThemeDirs {
904 bundled: Vec<PathBuf>,
905 system: Vec<PathBuf>,
906 custom: Option<PathBuf>,
907 }
908
909 impl ThemeDirs {
910 #[must_use]
911 pub fn new() -> Self {
912 Self::default()
913 }
914
915 /// Themes the app ships with. Lowest precedence.
916 ///
917 /// Takes more than one because a Tauri app has two: the bundled resource
918 /// directory in production, and the tree `build.rs` materialized for a
919 /// `cargo run` that has no resource directory at all.
920 #[must_use]
921 pub fn bundled(mut self, dir: Option<PathBuf>) -> Self {
922 self.bundled.extend(dir);
923 self
924 }
925
926 /// Themes the machine ships, from an image or a package. Overrides bundled.
927 #[must_use]
928 pub fn system(mut self, dir: Option<PathBuf>) -> Self {
929 self.system.extend(dir);
930 self
931 }
932
933 /// The user's own themes. Highest precedence, and the only tier flagged
934 /// custom, which is what makes them exportable and deletable.
935 #[must_use]
936 pub fn custom(mut self, dir: Option<PathBuf>) -> Self {
937 self.custom = dir;
938 self
939 }
940
941 /// The search path, lowest precedence first.
942 #[must_use]
943 pub fn build(self) -> Vec<(PathBuf, bool)> {
944 let mut dirs = Vec::new();
945 for dir in self.bundled.into_iter().chain(self.system) {
946 if dir.is_dir() {
947 dirs.push((dir, false));
948 }
949 }
950 if let Some(dir) = self.custom
951 && dir.is_dir()
952 {
953 dirs.push((dir, true));
954 }
955 dirs
956 }
957 }
958
959 /// Extract the intent color sections into a flat `HashMap` with dotted keys
960 /// like `"surface.page"`, `"status.danger"`, `"category.one"`.
961 pub fn extract_colors(table: &toml::Table) -> HashMap<String, String> {
962 let mut colors = HashMap::new();
963 for section in COLOR_SECTIONS {
964 if let Some(sect) = table.get(*section).and_then(|s| s.as_table()) {
965 for (key, val) in sect {
966 if let Some(color) = val.as_str() {
967 colors.insert(format!("{section}.{key}"), color.to_string());
968 }
969 }
970 }
971 }
972 colors
973 }
974
975 /// Scan directories for `.toml` theme files and return metadata for each.
976 ///
977 /// Directories are checked in order; later entries override earlier ones by ID.
978 /// Each entry in `dirs` is `(path, is_custom)`.
979 pub fn list_themes_from_dirs(dirs: &[(PathBuf, bool)]) -> Vec<ThemeMeta> {
980 let mut seen: HashMap<String, ThemeMeta> = HashMap::new();
981
982 for (dir, is_custom) in dirs {
983 let Ok(entries) = std::fs::read_dir(dir) else {
984 continue;
985 };
986
987 for entry in entries {
988 let Ok(entry) = entry else {
989 continue;
990 };
991 let path = entry.path();
992 if path.extension().and_then(|e| e.to_str()) != Some("toml") {
993 continue;
994 }
995
996 let id = path
997 .file_stem()
998 .and_then(|s| s.to_str())
999 .unwrap_or_default()
1000 .to_string();
1001
1002 let Ok(content) = std::fs::read_to_string(&path) else {
1003 continue;
1004 };
1005 let table: toml::Table = match content.parse() {
1006 Ok(t) => t,
1007 Err(_) => continue,
1008 };
1009
1010 seen.insert(id.clone(), parse_meta(&id, &table, *is_custom));
1011 }
1012 }
1013
1014 let mut themes: Vec<ThemeMeta> = seen.into_values().collect();
1015 themes.sort_by(|a, b| a.name.cmp(&b.name));
1016 themes
1017 }
1018
1019 /// Find a theme file by ID in the given directories.
1020 ///
1021 /// Checks directories in reverse order so the highest-priority directory wins.
1022 /// Returns `(path, is_custom)` or `None` if not found.
1023 pub fn find_theme_path(dirs: &[(PathBuf, bool)], id: &str) -> Option<(PathBuf, bool)> {
1024 let filename = format!("{id}.toml");
1025
1026 for (dir, is_custom) in dirs.iter().rev() {
1027 let path = dir.join(&filename);
1028 if path.is_file() {
1029 return Some((path, *is_custom));
1030 }
1031 }
1032
1033 None
1034 }
1035
1036 /// Parse a complete theme (metadata + colors) from raw TOML content, with no
1037 /// filesystem access. For callers that embed themes at compile time.
1038 pub fn parse_theme_str(id: &str, content: &str, is_custom: bool) -> Result<ThemeColors, String> {
1039 validate_theme_id(id)?;
1040 let table: toml::Table = content
1041 .parse()
1042 .map_err(|e| format!("Failed to parse theme '{id}': {e}"))?;
1043 let meta = parse_meta(id, &table, is_custom);
1044 let colors = extract_colors(&table);
1045 Ok(ThemeColors { meta, colors })
1046 }
1047
1048 /// Load a complete theme (metadata + colors) by ID from the given directories.
1049 pub fn load_theme(dirs: &[(PathBuf, bool)], id: &str) -> Result<ThemeColors, String> {
1050 validate_theme_id(id)?;
1051
1052 let (path, is_custom) =
1053 find_theme_path(dirs, id).ok_or_else(|| format!("Theme '{id}' not found"))?;
1054
1055 let content = std::fs::read_to_string(&path)
1056 .map_err(|e| format!("Failed to read {}: {}", path.display(), e))?;
1057
1058 let table: toml::Table = content
1059 .parse()
1060 .map_err(|e| format!("Failed to parse {}: {}", path.display(), e))?;
1061
1062 let meta = parse_meta(id, &table, is_custom);
1063 let colors = extract_colors(&table);
1064
1065 Ok(ThemeColors { meta, colors })
1066 }
1067
1068 /// Load a theme and resolve it to the full intent token set in one step.
1069 pub fn load_semantic(dirs: &[(PathBuf, bool)], id: &str) -> Result<SemanticTokens, String> {
1070 Ok(resolve(&load_theme(dirs, id)?))
1071 }
1072
1073 /// Import a theme TOML file into the custom themes directory.
1074 ///
1075 /// Validates that the file is parseable TOML with at least one intent color
1076 /// section, then copies it to `custom_dir/{id}.toml`. Returns the theme metadata.
1077 pub fn import_theme(source_path: &Path, custom_dir: &Path) -> Result<ThemeMeta, String> {
1078 let content = std::fs::read_to_string(source_path)
1079 .map_err(|e| format!("Failed to read {}: {}", source_path.display(), e))?;
1080
1081 let table: toml::Table = content.parse().map_err(|e| format!("Invalid TOML: {e}"))?;
1082
1083 let has_colors = COLOR_SECTIONS
1084 .iter()
1085 .any(|s| table.get(*s).and_then(|v| v.as_table()).is_some());
1086 if !has_colors {
1087 return Err(format!(
1088 "Theme file must have at least one color section ({})",
1089 COLOR_SECTIONS.join(", ")
1090 ));
1091 }
1092
1093 let id = source_path
1094 .file_stem()
1095 .and_then(|s| s.to_str())
1096 .ok_or("Invalid file name")?
1097 .to_string();
1098 validate_theme_id(&id)?;
1099
1100 std::fs::create_dir_all(custom_dir)
1101 .map_err(|e| format!("Failed to create {}: {}", custom_dir.display(), e))?;
1102
1103 let dest = custom_dir.join(format!("{id}.toml"));
1104 std::fs::copy(source_path, &dest).map_err(|e| format!("Failed to copy theme: {e}"))?;
1105
1106 Ok(parse_meta(&id, &table, true))
1107 }
1108
1109 /// Delete a custom theme by ID.
1110 ///
1111 /// Only operates on `custom_dir` — bundled themes are not deletable through
1112 /// this entry point.
1113 pub fn delete_theme(custom_dir: &Path, id: &str) -> Result<(), String> {
1114 validate_theme_id(id)?;
1115
1116 let path = custom_dir.join(format!("{id}.toml"));
1117 if !path.is_file() {
1118 return Err(format!("Custom theme '{id}' not found"));
1119 }
1120
1121 std::fs::remove_file(&path).map_err(|e| format!("Failed to delete {}: {}", path.display(), e))
1122 }
1123
1124 /// A four-color preview for theme thumbnails: the representative swatch from
1125 /// each of the principal roles.
1126 #[derive(Debug, Clone, Serialize)]
1127 #[serde(rename_all = "camelCase")]
1128 pub struct ThemePreview {
1129 pub meta: ThemeMeta,
1130 /// Page background (`surface.page`).
1131 pub background: Option<String>,
1132 /// Body text (`content.primary`).
1133 pub foreground: Option<String>,
1134 /// Brand/interactive color (`action.primary`).
1135 pub accent: Option<String>,
1136 /// Divider/outline color (`line.border`).
1137 pub border: Option<String>,
1138 }
1139
1140 fn color_at(table: &toml::Table, section: &str, key: &str) -> Option<String> {
1141 table
1142 .get(section)
1143 .and_then(|s| s.as_table())
1144 .and_then(|s| s.get(key))
1145 .and_then(|v| v.as_str())
1146 .map(std::string::ToString::to_string)
1147 }
1148
1149 /// Load just the preview swatches for a theme — for UI thumbnails.
1150 pub fn load_theme_preview(dirs: &[(PathBuf, bool)], id: &str) -> Result<ThemePreview, String> {
1151 validate_theme_id(id)?;
1152
1153 let (path, is_custom) =
1154 find_theme_path(dirs, id).ok_or_else(|| format!("Theme '{id}' not found"))?;
1155
1156 let content = std::fs::read_to_string(&path)
1157 .map_err(|e| format!("Failed to read {}: {}", path.display(), e))?;
1158
1159 let table: toml::Table = content
1160 .parse()
1161 .map_err(|e| format!("Failed to parse {}: {}", path.display(), e))?;
1162
1163 Ok(ThemePreview {
1164 meta: parse_meta(id, &table, is_custom),
1165 background: color_at(&table, "surface", "page"),
1166 foreground: color_at(&table, "content", "primary"),
1167 accent: color_at(&table, "action", "primary"),
1168 border: color_at(&table, "line", "border"),
1169 })
1170 }
1171
1172 /// Export a theme to a user-chosen path.
1173 pub fn export_theme(dirs: &[(PathBuf, bool)], id: &str, dest_path: &Path) -> Result<(), String> {
1174 validate_theme_id(id)?;
1175
1176 let (source, _) = find_theme_path(dirs, id).ok_or_else(|| format!("Theme '{id}' not found"))?;
1177
1178 std::fs::copy(&source, dest_path).map_err(|e| format!("Failed to export theme: {e}"))?;
1179
1180 Ok(())
1181 }
1182
1183 /// The themes this crate ships, embedded at compile time.
1184 ///
1185 /// `include_dir` is an implementation detail: the public API hands back plain
1186 /// `(id, toml_source)` pairs, so how the data is embedded can change without
1187 /// a breaking release.
1188 static EMBEDDED: include_dir::Dir<'static> =
1189 include_dir::include_dir!("$CARGO_MANIFEST_DIR/themes");
1190
1191 /// The themes this crate ships, as `(id, toml_source)` pairs.
1192 ///
1193 /// This is the path-free way to reach the bundled set, for consumers that
1194 /// cannot rely on a directory existing at runtime: a crate pulled from
1195 /// crates.io lives in a registry checkout whose location is not knowable at
1196 /// compile time, so `include_dir!` and asset-bundling globs in the depending
1197 /// crate have nothing stable to point at. Embedding here and re-exporting the
1198 /// contents gives them one source of truth without a path.
1199 ///
1200 /// Ordering follows the embedded directory and is not guaranteed; collect and
1201 /// sort by id where a stable order matters (a theme picker, say).
1202 pub fn embedded_themes() -> impl Iterator<Item = (&'static str, &'static str)> {
1203 EMBEDDED.files().filter_map(|file| {
1204 let path = file.path();
1205 if path.extension().and_then(|e| e.to_str()) != Some("toml") {
1206 return None;
1207 }
1208 let id = path.file_stem()?.to_str()?;
1209 Some((id, file.contents_utf8()?))
1210 })
1211 }
1212
1213 /// The theme directory this crate ships, for use as a build-from-source
1214 /// fallback.
1215 ///
1216 /// Resolves against `makeover`'s own manifest directory, fixed at compile
1217 /// time, so it works from a path dependency and from a cargo git checkout
1218 /// alike. Installed systems should put their packaged theme directory ahead
1219 /// of this in the search path; this is the entry that keeps `cargo run` in a
1220 /// fresh clone from coming up with no themes at all.
1221 ///
1222 /// Returns `None` when the directory is absent — a cargo cache that has been
1223 /// cleaned, or a vendored copy that dropped the data — so callers degrade to
1224 /// their remaining search path rather than failing.
1225 pub fn bundled_themes_dir() -> Option<PathBuf> {
1226 let themes = Path::new(env!("CARGO_MANIFEST_DIR")).join("themes");
1227 if themes.is_dir() { Some(themes) } else { None }
1228 }
1229
1230 #[cfg(test)]
1231 mod tests {
1232 use super::*;
1233 use std::fs;
1234
1235 // ---- id validation ----
1236
1237 #[test]
1238 fn validate_theme_id_alphanumeric() {
1239 assert!(validate_theme_id("darkmode").is_ok());
1240 assert!(validate_theme_id("Theme123").is_ok());
1241 }
1242
1243 #[test]
1244 fn validate_theme_id_hyphens_underscores() {
1245 assert!(validate_theme_id("dark-mode").is_ok());
1246 assert!(validate_theme_id("my_theme_v2").is_ok());
1247 }
1248
1249 #[test]
1250 fn validate_theme_id_rejects_path_traversal() {
1251 assert!(validate_theme_id("../etc/passwd").is_err());
1252 assert!(validate_theme_id("foo/bar").is_err());
1253 assert!(validate_theme_id("theme.toml").is_err());
1254 }
1255
1256 // ---- low-color terminals ----
1257
1258 #[test]
1259 fn the_ansi_palette_is_sixteen_distinct_colors() {
1260 let mut seen: Vec<(u8, u8, u8)> = ANSI_16.iter().map(|c| c.tuple()).collect();
1261 seen.sort_unstable();
1262 seen.dedup();
1263 assert_eq!(seen.len(), 16);
1264 }
1265
1266 #[test]
1267 fn quantize_picks_the_obvious_entry() {
1268 let black = Rgb { r: 0, g: 0, b: 0 };
1269 let white = Rgb {
1270 r: 255,
1271 g: 255,
1272 b: 255,
1273 };
1274 assert_eq!(quantize(black, &ANSI_16), 0);
1275 assert_eq!(quantize(white, &ANSI_16), 15);
1276 }
1277
1278 // Nearest-entry quantization is per-color, so two colors a theme keeps
1279 // apart can arrive as one. These two are both closest to the palette's
1280 // light gray, and a border drawn in one on a page painted the other is not
1281 // drawn at all.
1282 #[test]
1283 fn two_colors_can_quantize_to_one_entry() {
1284 let page = Rgb::from_hex("#a8a8a8").unwrap();
1285 let border = Rgb::from_hex("#b4b4b4").unwrap();
1286
1287 assert_eq!(quantize(page, &ANSI_16), quantize(border, &ANSI_16));
1288 assert!(quantize_against(border, page, &ANSI_16) != quantize(page, &ANSI_16));
1289 }
1290
1291 #[test]
1292 fn quantize_against_keeps_the_border_off_the_page() {
1293 let page = Rgb::from_hex("#e4ded6").unwrap();
1294 let border = Rgb::from_hex("#7f786d").unwrap();
1295
1296 let shown_page = ANSI_16[quantize(page, &ANSI_16)];
1297 let shown_border = ANSI_16[quantize_against(border, page, &ANSI_16)];
1298
1299 assert!(
1300 wcag_contrast(shown_border, shown_page) >= DISTINCT,
1301 "border {} on page {} is {:.2}:1",
1302 shown_border.to_hex(),
1303 shown_page.to_hex(),
1304 wcag_contrast(shown_border, shown_page)
1305 );
1306 }
1307
1308 // A color that already reads against its background is left where it is,
1309 // so this can be applied without redesigning what already worked.
1310 #[test]
1311 fn quantize_against_leaves_a_readable_color_alone() {
1312 let page = Rgb::from_hex("#e4ded6").unwrap();
1313 let text = Rgb::from_hex("#1a1816").unwrap();
1314
1315 assert_eq!(
1316 quantize_against(text, page, &ANSI_16),
1317 quantize(text, &ANSI_16)
1318 );
1319 }
1320
1321 // With nothing in the palette to satisfy the request, the most legible
1322 // entry is the answer. Returning the nearest one would return the
1323 // background itself, which is the failure this function exists to avoid.
1324 #[test]
1325 fn an_impossible_palette_gets_the_most_legible_entry() {
1326 let page = Rgb::from_hex("#ffffff").unwrap();
1327 let border = Rgb::from_hex("#fefefe").unwrap();
1328 let palette = [
1329 Rgb::from_hex("#ffffff").unwrap(),
1330 Rgb::from_hex("#fdfdfd").unwrap(),
1331 ];
1332
1333 let chosen = palette[quantize_against(border, page, &palette)];
1334 assert_eq!(chosen.to_hex(), "#fdfdfd");
1335 }
1336
1337 // ---- meta ----
1338
1339 #[test]
1340 fn parse_meta_with_name_and_variant() {
1341 let table: toml::Table = "[meta]\nname = \"Nord\"\nvariant = \"light\"\n"
1342 .parse()
1343 .unwrap();
1344 let meta = parse_meta("nord", &table, false);
1345 assert_eq!(meta.id, "nord");
1346 assert_eq!(meta.name, "Nord");
1347 assert_eq!(meta.variant, "light");
1348 assert!(!meta.is_custom);
1349 }
1350
1351 #[test]
1352 fn parse_meta_defaults_to_id_and_dark() {
1353 let table: toml::Table = "".parse().unwrap();
1354 let meta = parse_meta("fallback", &table, true);
1355 assert_eq!(meta.name, "fallback");
1356 assert_eq!(meta.variant, "dark");
1357 assert!(meta.is_custom);
1358 }
1359
1360 // ---- color math (formulas must match the apps they came from) ----
1361
1362 #[test]
1363 fn rgb_hex_roundtrip() {
1364 assert_eq!(
1365 Rgb::from_hex("#6196FF").unwrap(),
1366 Rgb {
1367 r: 0x61,
1368 g: 0x96,
1369 b: 0xff
1370 }
1371 );
1372 assert_eq!(
1373 Rgb::from_hex("#abc").unwrap(),
1374 Rgb {
1375 r: 0xaa,
1376 g: 0xbb,
1377 b: 0xcc
1378 }
1379 );
1380 assert_eq!(
1381 Rgb {
1382 r: 0x61,
1383 g: 0x96,
1384 b: 0xff
1385 }
1386 .to_hex(),
1387 "#6196ff"
1388 );
1389 assert!(Rgb::from_hex("not-a-color").is_none());
1390 }
1391
1392 #[test]
1393 fn oklab_roundtrips_within_tolerance() {
1394 for hex in ["#6196ff", "#2e3440", "#ffffff", "#000000", "#c0392b"] {
1395 let c = Rgb::from_hex(hex).unwrap();
1396 let back = Rgb::from_oklab(c.to_oklab());
1397 // Gamut round-trip is near-exact (±1 per channel from rounding).
1398 assert!((c.r as i16 - back.r as i16).abs() <= 1, "{hex} r");
1399 assert!((c.g as i16 - back.g as i16).abs() <= 1, "{hex} g");
1400 assert!((c.b as i16 - back.b as i16).abs() <= 1, "{hex} b");
1401 }
1402 }
1403
1404 #[test]
1405 fn wcag_contrast_known_pairs() {
1406 let white = Rgb {
1407 r: 255,
1408 g: 255,
1409 b: 255,
1410 };
1411 let black = Rgb { r: 0, g: 0, b: 0 };
1412 assert!((wcag_contrast(white, black) - 21.0).abs() < 0.01);
1413 assert!((wcag_contrast(white, white) - 1.0).abs() < 0.01);
1414 }
1415
1416 #[test]
1417 fn readable_on_picks_by_wcag() {
1418 assert_eq!(
1419 readable_on(Rgb {
1420 r: 255,
1421 g: 255,
1422 b: 255
1423 }),
1424 Rgb { r: 0, g: 0, b: 0 }
1425 );
1426 assert_eq!(
1427 readable_on(Rgb { r: 0, g: 0, b: 0 }),
1428 Rgb {
1429 r: 255,
1430 g: 255,
1431 b: 255
1432 }
1433 );
1434 // A light blue action -> black text reads better.
1435 let action = Rgb::from_hex("#6196ff").unwrap();
1436 assert_eq!(readable_on(action), Rgb { r: 0, g: 0, b: 0 });
1437 }
1438
1439 #[test]
1440 fn lighten_darken_move_oklab_lightness() {
1441 let c = Rgb::from_hex("#6196ff").unwrap();
1442 let l0 = c.to_oklab().l;
1443 assert!(lighten(c, 0.05).to_oklab().l > l0);
1444 assert!(darken(c, 0.05).to_oklab().l < l0);
1445 }
1446
1447 #[test]
1448 fn mix_endpoints_and_midpoint() {
1449 let a = Rgb::from_hex("#000000").unwrap();
1450 let b = Rgb::from_hex("#6196ff").unwrap();
1451 assert_eq!(mix(a, b, 0.0), a);
1452 assert_eq!(mix(a, b, 1.0), b);
1453 // Midpoint sits between the endpoints in OKLab lightness.
1454 let mid = mix(a, b, 0.5).to_oklab().l;
1455 assert!(mid > a.to_oklab().l && mid < b.to_oklab().l);
1456 }
1457
1458 // ---- extract + resolve ----
1459
1460 fn nord_toml() -> &'static str {
1461 r##"
1462 [meta]
1463 name = "Nord"
1464 variant = "dark"
1465
1466 [surface]
1467 page = "#2e3440"
1468 raised = "#3b4252"
1469 sunken = "#434c5e"
1470 overlay = "#3b4252"
1471
1472 [content]
1473 primary = "#d8dee9"
1474 secondary = "#e5e9f0"
1475 muted = "#616e88"
1476
1477 [action]
1478 primary = "#81a1c1"
1479
1480 [status]
1481 danger = "#bf616a"
1482 success = "#a3be8c"
1483 warning = "#ebcb8b"
1484 info = "#88c0d0"
1485
1486 [line]
1487 border = "#4c566a"
1488
1489 [category]
1490 one = "#bf616a"
1491 two = "#a3be8c"
1492 three = "#81a1c1"
1493 four = "#ebcb8b"
1494 five = "#b48ead"
1495 six = "#88c0d0"
1496 "##
1497 }
1498
1499 #[test]
1500 fn extract_colors_reads_intent_sections() {
1501 let table: toml::Table = nord_toml().parse().unwrap();
1502 let colors = extract_colors(&table);
1503 assert_eq!(colors.get("surface.page").unwrap(), "#2e3440");
1504 assert_eq!(colors.get("content.primary").unwrap(), "#d8dee9");
1505 assert_eq!(colors.get("action.primary").unwrap(), "#81a1c1");
1506 assert_eq!(colors.get("status.danger").unwrap(), "#bf616a");
1507 assert_eq!(colors.get("line.border").unwrap(), "#4c566a");
1508 assert_eq!(colors.get("category.five").unwrap(), "#b48ead");
1509 assert_eq!(colors.len(), 19);
1510 }
1511
1512 #[test]
1513 fn resolve_base_intents_passthrough() {
1514 let theme = parse_theme_str("nord", nord_toml(), false).unwrap();
1515 let t = resolve(&theme);
1516 assert_eq!(t.hex("surface-page"), Some("#2e3440"));
1517 assert_eq!(t.hex("content"), Some("#d8dee9")); // content.primary -> content
1518 assert_eq!(t.hex("content-muted"), Some("#616e88"));
1519 assert_eq!(t.hex("action"), Some("#81a1c1"));
1520 assert_eq!(t.hex("danger"), Some("#bf616a"));
1521 assert_eq!(t.hex("border"), Some("#4c566a"));
1522 assert_eq!(t.hex("category-five"), Some("#b48ead"));
1523 }
1524
1525 #[test]
1526 fn resolve_derived_intents() {
1527 let theme = parse_theme_str("nord", nord_toml(), false).unwrap();
1528 let t = resolve(&theme);
1529 let action = Rgb::from_hex("#81a1c1").unwrap();
1530 let page = Rgb::from_hex("#2e3440").unwrap();
1531 let _ = page;
1532 assert_eq!(
1533 t.hex("action-hover").unwrap(),
1534 lighten(action, 0.05).to_hex()
1535 );
1536 assert_eq!(
1537 t.hex("content-on-action").unwrap(),
1538 readable_on(action).to_hex()
1539 );
1540 assert_eq!(t.hex("focus-ring"), Some("#81a1c1"));
1541 assert_eq!(t.hex("hover-surface"), Some("#434c5e")); // = surface.sunken
1542 // Pruned by the usage audit (0 consumers): action-active, the *-surface
1543 // tints, selection, row-stripe. Apps that need them derive inline via
1544 // the shared mix().
1545 assert!(t.hex("action-active").is_none());
1546 assert!(t.hex("danger-surface").is_none());
1547 assert!(t.hex("selection").is_none());
1548 assert!(t.hex("row-stripe").is_none());
1549 }
1550
1551 #[test]
1552 fn resolve_bevel_intents() {
1553 let theme = parse_theme_str("nord", nord_toml(), false).unwrap();
1554 let t = resolve(&theme);
1555 let raised = Rgb::from_hex("#3b4252").unwrap();
1556 assert_eq!(
1557 t.hex("bevel-light").unwrap(),
1558 lighten(raised, 0.14).to_hex()
1559 );
1560 assert_eq!(t.hex("bevel-dark").unwrap(), darken(raised, 0.18).to_hex());
1561 }
1562
1563 // A bevel is two edges around one face, so both edges have to be visibly off
1564 // that face or the control never resolves as lit. The lightening clamps at
1565 // the top of the ramp, which means a theme authoring a white raised surface
1566 // gets a highlight identical to the surface it is meant to sit on.
1567 //
1568 // The list is asserted rather than merely reported so that changing a theme
1569 // has to come here and say so. Shrinking it is the fix; growing it is a
1570 // regression in the theme, not in this derivation.
1571 #[test]
1572 fn bevel_edges_are_distinct_from_their_face() {
1573 const CANNOT_BEVEL: &[&str] = &["audiofiles", "neobrute", "oxocarbon-light"];
1574
1575 let mut degenerate: Vec<String> = Vec::new();
1576 for (id, source) in embedded_themes() {
1577 let theme = parse_theme_str(id, source, false).unwrap();
1578 let t = resolve(&theme);
1579 let Some(raised) = t.hex("surface-raised") else {
1580 continue;
1581 };
1582 let light = t.hex("bevel-light").expect("raised implies bevel-light");
1583 let dark = t.hex("bevel-dark").expect("raised implies bevel-dark");
1584 if light == raised || dark == raised {
1585 degenerate.push(id.to_string());
1586 }
1587 }
1588 degenerate.sort();
1589
1590 assert_eq!(
1591 degenerate, CANNOT_BEVEL,
1592 "themes whose raised surface cannot hold both bevel edges"
1593 );
1594 }
1595
1596 // What the bevel pair does on a sixteen-color terminal, measured across the
1597 // shipped set rather than assumed. Two results, both load-bearing for a
1598 // consumer that has to render one there.
1599 //
1600 // Exactly one edge survives, never both. A raised face quantizes onto one of
1601 // the palette's three grays, and the palette is too coarse to hold anything
1602 // between that entry and its neighbour, so whichever edge is pushed toward
1603 // the end of the ramp the face already sits on lands back on the face. Light
1604 // themes and most dark ones keep the shadow and lose the highlight; a face
1605 // that quantizes to black keeps the highlight and loses the shadow.
1606 //
1607 // So a low-color consumer draws the single edge it can render, on the side
1608 // the palette left it, rather than a bevel that resolves on two sides.
1609 //
1610 // And `quantize_against` is the wrong function for this pair, though it is
1611 // the right one for a border. It answers "nearest entry that clears DISTINCT
1612 // against the background", which has no notion of direction, so both edges
1613 // are pushed onto the same contrasting entry and the bevel inverts on one
1614 // side. Plain `quantize` keeps them apart and in the right order.
1615 #[test]
1616 fn a_sixteen_color_terminal_gets_one_bevel_edge_and_not_two() {
1617 for (id, source) in embedded_themes() {
1618 let theme = parse_theme_str(id, source, false).unwrap();
1619 let t = resolve(&theme);
1620 let (Some(face), Some(light), Some(dark)) = (
1621 t.hex("surface-raised").and_then(Rgb::from_hex),
1622 t.hex("bevel-light").and_then(Rgb::from_hex),
1623 t.hex("bevel-dark").and_then(Rgb::from_hex),
1624 ) else {
1625 continue;
1626 };
1627
1628 let face_index = quantize(face, &ANSI_16);
1629 let light_survives = quantize(light, &ANSI_16) != face_index;
1630 let dark_survives = quantize(dark, &ANSI_16) != face_index;
1631 assert!(
1632 light_survives != dark_survives,
1633 "{id}: expected exactly one bevel edge to survive 16 colors, \
1634 highlight {light_survives} shadow {dark_survives}"
1635 );
1636
1637 // Direction-blind, so it collapses the pair it is asked to separate.
1638 assert_eq!(
1639 quantize_against(light, face, &ANSI_16),
1640 quantize_against(dark, face, &ANSI_16),
1641 "{id}: quantize_against is expected to be unusable for a bevel pair"
1642 );
1643 }
1644 }
1645
1646 // 256 colors is where the bevel starts working. At 16 every shipped theme
1647 // loses an edge; here all but the five whose raised surface sits at the very
1648 // top of the ramp keep both, and those five fail for the reason they fail in
1649 // truecolor rather than for a palette reason.
1650 //
1651 // Three of them cannot bevel at any depth, so they are the
1652 // `bevel_edges_are_distinct_from_their_face` set. The other two are new here:
1653 // they hold a highlight in 24-bit, but not one wide enough to survive
1654 // rounding onto the cube.
1655 #[test]
1656 fn two_hundred_fifty_six_colors_keep_both_bevel_edges() {
1657 const LOSES_AN_EDGE: &[&str] = &[
1658 "audiofiles",
1659 "gruvbox-light",
1660 "neobrute",
1661 "oxocarbon-light",
1662 "rosepine-dawn",
1663 ];
1664
1665 let mut lost: Vec<String> = Vec::new();
1666 for (id, source) in embedded_themes() {
1667 let theme = parse_theme_str(id, source, false).unwrap();
1668 let t = resolve(&theme);
1669 let (Some(face), Some(light), Some(dark)) = (
1670 t.hex("surface-raised").and_then(Rgb::from_hex),
1671 t.hex("bevel-light").and_then(Rgb::from_hex),
1672 t.hex("bevel-dark").and_then(Rgb::from_hex),
1673 ) else {
1674 continue;
1675 };
1676
1677 // Against the fixed region, which is what a consumer should use: a
1678 // match in the low sixteen is a match against a repaintable color.
1679 let f = quantize(face, ANSI_240);
1680 let l = quantize(light, ANSI_240);
1681 let d = quantize(dark, ANSI_240);
1682 if l == f || d == f || l == d {
1683 lost.push(id.to_string());
1684 }
1685 }
1686 lost.sort();
1687
1688 assert_eq!(
1689 lost, LOSES_AN_EDGE,
1690 "themes that cannot hold a two-tone bevel on a 256-color terminal"
1691 );
1692 }
1693
1694 #[test]
1695 fn the_256_table_has_its_three_regions() {
1696 // Index is the escape-sequence index, so the low sixteen must match.
1697 assert_eq!(ANSI_256[..16], ANSI_16);
1698 // The cube's corners, at both ends and one interior level.
1699 assert_eq!(ANSI_256[16].tuple(), (0, 0, 0));
1700 assert_eq!(ANSI_256[231].tuple(), (255, 255, 255));
1701 assert_eq!(ANSI_256[16 + 36 * 2 + 6 * 3 + 4].tuple(), (135, 175, 215));
1702 // The gray ramp runs 8 to 238 and contains neither black nor white.
1703 assert_eq!(ANSI_256[232].tuple(), (8, 8, 8));
1704 assert_eq!(ANSI_256[255].tuple(), (238, 238, 238));
1705 // The fixed region is the table minus the repaintable colors.
1706 assert_eq!(ANSI_240.len(), 240);
1707 assert_eq!(ANSI_240[0], ANSI_256[ANSI_240_OFFSET]);
1708 }
1709
1710 #[test]
1711 fn resolve_overlay_is_dark_translucent_scrim() {
1712 let theme = parse_theme_str("nord", nord_toml(), false).unwrap();
1713 let t = resolve(&theme);
1714 let overlay = t.hex("overlay").unwrap();
1715 assert!(
1716 overlay.starts_with("rgba("),
1717 "overlay is translucent: {overlay}"
1718 );
1719 assert!(overlay.ends_with(", 0.5)"));
1720 // The scrim tone is anchored very dark regardless of theme.
1721 let inner = overlay
1722 .trim_start_matches("rgba(")
1723 .trim_end_matches(", 0.5)");
1724 let parts: Vec<u8> = inner.split(", ").map(|p| p.parse().unwrap()).collect();
1725 let scrim = Rgb {
1726 r: parts[0],
1727 g: parts[1],
1728 b: parts[2],
1729 };
1730 assert!(scrim.to_oklab().l < 0.2, "scrim must be near-black");
1731 }
1732
1733 #[test]
1734 fn resolve_drops_non_hex_base_intent() {
1735 // A base intent that isn't a hex color must never reach the resolved
1736 // token set (it would otherwise be inlined verbatim into a <style>
1737 // block). Skipped like a missing intent; valid siblings survive.
1738 let theme = parse_theme_str(
1739 "x",
1740 "[surface]\npage = \"</style><script>alert(1)</script>\"\n[content]\nprimary = \"#111111\"\n",
1741 false,
1742 )
1743 .unwrap();
1744 let t = resolve(&theme);
1745 assert!(
1746 t.hex("surface-page").is_none(),
1747 "non-hex base intent leaked"
1748 );
1749 assert_eq!(t.hex("content").unwrap(), "#111111");
1750 // The injected markup appears in no resolved value.
1751 assert!(!t.intents.values().any(|v| v.contains('<')));
1752 }
1753
1754 #[test]
1755 fn resolve_skips_derived_when_source_missing() {
1756 // No [action] => no action-derived tokens.
1757 let theme = parse_theme_str(
1758 "x",
1759 "[surface]\npage = \"#000000\"\n[line]\nborder = \"#222222\"\n",
1760 false,
1761 )
1762 .unwrap();
1763 let t = resolve(&theme);
1764 assert!(t.hex("action").is_none());
1765 assert!(t.hex("action-hover").is_none());
1766 assert!(t.hex("selection").is_none());
1767 assert_eq!(
1768 t.hex("border-strong").unwrap(),
1769 darken(Rgb::from_hex("#222222").unwrap(), 0.05).to_hex()
1770 );
1771 }
1772
1773 #[test]
1774 fn rgb_accessor_for_native_consumers() {
1775 let theme = parse_theme_str("nord", nord_toml(), false).unwrap();
1776 let t = resolve(&theme);
1777 assert_eq!(t.rgb("action"), Some((0x81, 0xa1, 0xc1)));
1778 assert_eq!(t.rgb("nonexistent"), None);
1779 }
1780
1781 // ---- css emit ----
1782
1783 #[test]
1784 fn intent_css_vars_wraps_root_and_includes_tokens() {
1785 let theme = parse_theme_str("nord", nord_toml(), false).unwrap();
1786 let css = intent_css_vars(&resolve(&theme));
1787 assert!(css.starts_with(":root {\n"));
1788 assert!(css.contains(" --surface-page: #2e3440;\n"));
1789 assert!(css.contains(" --danger: #bf616a;\n"));
1790 assert!(css.contains(" --action-hover: "));
1791 assert!(css.trim_end().ends_with('}'));
1792 }
1793
1794 // ---- loading / fs ----
1795
1796 #[test]
1797 fn load_and_resolve_round_trip() {
1798 let dir = tempfile::tempdir().unwrap();
1799 fs::write(dir.path().join("nord.toml"), nord_toml()).unwrap();
1800 let dirs = vec![(dir.path().to_path_buf(), false)];
1801 let t = load_semantic(&dirs, "nord").unwrap();
1802 assert_eq!(t.meta.name, "Nord");
1803 assert_eq!(t.hex("action"), Some("#81a1c1"));
1804 }
1805
1806 #[test]
1807 fn load_theme_rejects_invalid_id() {
1808 assert!(load_theme(&[], "../evil").is_err());
1809 }
1810
1811 fn meta(id: &str, variant: &str) -> ThemeMeta {
1812 ThemeMeta {
1813 id: id.to_string(),
1814 name: id.to_string(),
1815 variant: variant.to_string(),
1816 is_custom: false,
1817 }
1818 }
1819
1820 fn defaults() -> ThemeDefaults {
1821 ThemeDefaults::new("flatwhite", "nord")
1822 }
1823
1824 // The three the shipped themes actually declare.
1825 #[test]
1826 fn every_shipped_variant_parses() {
1827 assert_eq!(Variant::parse("light"), Some(Variant::Light));
1828 assert_eq!(Variant::parse("dark"), Some(Variant::Dark));
1829 assert_eq!(Variant::parse("high-contrast"), Some(Variant::HighContrast));
1830 assert_eq!(Variant::parse("sepia"), None);
1831 }
1832
1833 // parse_meta already defaults a *missing* variant to dark, so an
1834 // unrecognized one reading as light would have the crate disagreeing with
1835 // itself. alloy_tui did exactly that before this existed.
1836 #[test]
1837 fn an_unrecognized_variant_reads_the_way_a_missing_one_does() {
1838 assert_eq!(Variant::from("sepia"), Variant::Dark);
1839 assert_eq!(Variant::from(""), Variant::Dark);
1840
1841 let missing: toml::Table = "[meta]\nname = \"X\"\n".parse().unwrap();
1842 assert_eq!(parse_meta("x", &missing, false).kind(), Variant::Dark);
1843 }
1844
1845 #[test]
1846 fn a_selection_round_trips_through_any_store() {
1847 for (stored, expect) in [
1848 (Some("system"), ThemeSelection::Follow),
1849 (None, ThemeSelection::Follow),
1850 (Some(""), ThemeSelection::Follow),
1851 (Some(" "), ThemeSelection::Follow),
1852 (Some("nord"), ThemeSelection::Fixed("nord".into())),
1853 ] {
1854 let parsed = ThemeSelection::parse(stored);
1855 assert_eq!(parsed, expect, "{stored:?}");
1856 assert_eq!(
1857 ThemeSelection::parse(Some(parsed.as_str())),
1858 expect,
1859 "what is written reads back as what was meant",
1860 );
1861 }
1862 }
1863
1864 // Nothing saved is follow-the-system, which is what Balanced Breakfast
1865 // expressed as an absent value and GoingsOn as a sentinel. Both are now the
1866 // same thing.
1867 #[test]
1868 fn nothing_chosen_yet_is_follow() {
1869 assert_eq!(ThemeSelection::default(), ThemeSelection::Follow);
1870 }
1871
1872 #[test]
1873 fn a_fixed_selection_wins_when_its_theme_is_installed() {
1874 let available = [meta("nord", "dark"), meta("flatwhite", "light")];
1875 let fixed = ThemeSelection::Fixed("nord".into());
1876 assert_eq!(
1877 fixed.resolve(Variant::Light, &defaults(), &available),
1878 "nord",
1879 "a chosen theme is not overridden by the ambient mode",
1880 );
1881 }
1882
1883 // Themes are deletable in three of the four apps. Handing back an id that
1884 // will fail to load only moves the error somewhere less helpful.
1885 #[test]
1886 fn a_fixed_selection_whose_theme_is_gone_falls_back() {
1887 let available = [meta("nord", "dark"), meta("flatwhite", "light")];
1888 let fixed = ThemeSelection::Fixed("deleted".into());
1889 assert_eq!(
1890 fixed.resolve(Variant::Light, &defaults(), &available),
1891 "flatwhite",
1892 );
1893 }
1894
1895 #[test]
1896 fn follow_picks_the_apps_default_for_the_ambient_mode() {
1897 let available = [meta("nord", "dark"), meta("flatwhite", "light")];
1898 let follow = ThemeSelection::Follow;
1899 assert_eq!(
1900 follow.resolve(Variant::Dark, &defaults(), &available),
1901 "nord",
1902 );
1903 assert_eq!(
1904 follow.resolve(Variant::Light, &defaults(), &available),
1905 "flatwhite",
1906 );
1907 }
1908
1909 // The behaviour Balanced Breakfast could not have: following the system
1910 // into a theme the user installed, when the app's own default is absent.
1911 #[test]
1912 fn follow_uses_any_installed_theme_of_the_right_variant() {
1913 let available = [meta("solarized-light", "light"), meta("mine", "dark")];
1914 assert_eq!(
1915 ThemeSelection::Follow.resolve(Variant::Dark, &defaults(), &available),
1916 "mine",
1917 "the app's `nord` is not installed, but a dark theme is",
1918 );
1919 }
1920
1921 // Always returns something: an app with no theme directory gets the id it
1922 // ships with, and the load error it would have had anyway.
1923 #[test]
1924 fn an_empty_catalog_still_names_the_apps_default() {
1925 assert_eq!(
1926 ThemeSelection::Follow.resolve(Variant::Dark, &defaults(), &[]),
1927 "nord",
1928 );
1929 }
1930
1931 #[test]
1932 fn high_contrast_falls_back_to_dark_unless_named() {
1933 let plain = defaults();
1934 assert_eq!(plain.for_variant(Variant::HighContrast), "nord");
1935
1936 let named = defaults().high_contrast("sharp");
1937 assert_eq!(named.for_variant(Variant::HighContrast), "sharp");
1938 }
1939
1940 // The bug this builder exists to prevent: the Alloy console pushed the
1941 // user's directory first under a comment reading "highest precedence
1942 // first", when both consumers of this vector resolve last-wins. A custom
1943 // theme lost to the packaged one of the same id.
1944 #[test]
1945 fn the_users_own_themes_outrank_everything() {
1946 let root = tempfile::tempdir().unwrap();
1947 let make = |name: &str| {
1948 let dir = root.path().join(name);
1949 std::fs::create_dir_all(&dir).unwrap();
1950 dir
1951 };
1952 let (bundled, system, custom) = (make("bundled"), make("system"), make("custom"));
1953
1954 let dirs = ThemeDirs::new()
1955 .custom(Some(custom.clone()))
1956 .bundled(Some(bundled.clone()))
1957 .system(Some(system.clone()))
1958 .build();
1959
1960 assert_eq!(
1961 dirs,
1962 vec![(bundled, false), (system, false), (custom.clone(), true)],
1963 "lowest precedence first, whatever order the tiers were added in",
1964 );
1965 assert!(dirs.last().unwrap().1, "only the user's tier is custom");
1966
1967 // And the ordering means what the consumers think it means.
1968 for dir in dirs.iter().map(|(dir, _)| dir) {
1969 std::fs::write(dir.join("shared.toml"), "[meta]\nname = \"x\"\n").unwrap();
1970 }
1971 assert_eq!(
1972 find_theme_path(&dirs, "shared").unwrap().0,
1973 custom.join("shared.toml"),
1974 "the user's copy is the one that loads",
1975 );
1976 }
1977
1978 #[test]
1979 fn a_directory_that_does_not_exist_is_dropped() {
1980 let root = tempfile::tempdir().unwrap();
1981 let real = root.path().join("real");
1982 std::fs::create_dir_all(&real).unwrap();
1983
1984 let dirs = ThemeDirs::new()
1985 .bundled(Some(root.path().join("nope")))
1986 .system(None)
1987 .custom(Some(real.clone()))
1988 .build();
1989
1990 assert_eq!(dirs, vec![(real, true)]);
1991 }
1992
1993 // A Tauri app has two bundled tiers: the resource dir in production and the
1994 // tree build.rs materialized for a dev run with no resource dir.
1995 #[test]
1996 fn more_than_one_bundled_tier_is_allowed() {
1997 let root = tempfile::tempdir().unwrap();
1998 let (first, second) = (root.path().join("a"), root.path().join("b"));
1999 std::fs::create_dir_all(&first).unwrap();
2000 std::fs::create_dir_all(&second).unwrap();
2001
2002 let dirs = ThemeDirs::new()
2003 .bundled(Some(first.clone()))
2004 .bundled(Some(second.clone()))
2005 .build();
2006 assert_eq!(dirs, vec![(first, false), (second, false)]);
2007 }
2008
2009 #[test]
2010 fn list_themes_from_dirs_finds_toml_files() {
2011 let dir = tempfile::tempdir().unwrap();
2012 fs::write(dir.path().join("t.toml"), "[meta]\nname = \"T\"\n").unwrap();
2013 fs::write(dir.path().join("x.txt"), "ignored").unwrap();
2014 let dirs = vec![(dir.path().to_path_buf(), false)];
2015 let themes = list_themes_from_dirs(&dirs);
2016 assert_eq!(themes.len(), 1);
2017 assert_eq!(themes[0].id, "t");
2018 }
2019
2020 #[test]
2021 fn find_theme_path_reverse_priority() {
2022 let d1 = tempfile::tempdir().unwrap();
2023 let d2 = tempfile::tempdir().unwrap();
2024 fs::write(d1.path().join("s.toml"), "[meta]\n").unwrap();
2025 fs::write(d2.path().join("s.toml"), "[meta]\n").unwrap();
2026 let dirs = vec![
2027 (d1.path().to_path_buf(), false),
2028 (d2.path().to_path_buf(), true),
2029 ];
2030 let (path, is_custom) = find_theme_path(&dirs, "s").unwrap();
2031 assert!(is_custom);
2032 assert_eq!(path, d2.path().join("s.toml"));
2033 }
2034
2035 #[test]
2036 fn import_theme_valid_and_rejects_empty() {
2037 let src_dir = tempfile::tempdir().unwrap();
2038 let custom_dir = tempfile::tempdir().unwrap();
2039
2040 let good = src_dir.path().join("my-theme.toml");
2041 fs::write(&good, "[surface]\npage = \"#1a1b26\"\n").unwrap();
2042 let meta = import_theme(&good, custom_dir.path()).unwrap();
2043 assert_eq!(meta.id, "my-theme");
2044 assert!(custom_dir.path().join("my-theme.toml").exists());
2045
2046 let empty = src_dir.path().join("empty.toml");
2047 fs::write(&empty, "[meta]\nname = \"E\"\n").unwrap();
2048 assert!(import_theme(&empty, custom_dir.path()).is_err());
2049 }
2050
2051 #[test]
2052 fn import_theme_rejects_invalid_toml() {
2053 let src_dir = tempfile::tempdir().unwrap();
2054 let custom_dir = tempfile::tempdir().unwrap();
2055 let src = src_dir.path().join("bad.toml");
2056 fs::write(&src, "this is not [valid toml [[[").unwrap();
2057 assert!(import_theme(&src, custom_dir.path()).is_err());
2058 }
2059
2060 #[test]
2061 fn delete_theme_removes_and_guards() {
2062 let custom = tempfile::tempdir().unwrap();
2063 let path = custom.path().join("doomed.toml");
2064 fs::write(&path, "[surface]\npage = \"#000\"\n").unwrap();
2065 delete_theme(custom.path(), "doomed").unwrap();
2066 assert!(!path.exists());
2067 assert!(delete_theme(custom.path(), "../etc/passwd").is_err());
2068 assert!(delete_theme(custom.path(), "ghost").is_err());
2069 }
2070
2071 #[test]
2072 fn export_theme_copies_file() {
2073 let src_dir = tempfile::tempdir().unwrap();
2074 let dest_dir = tempfile::tempdir().unwrap();
2075 let content = "[meta]\nname = \"E\"\n[surface]\npage = \"#ffffff\"\n";
2076 fs::write(src_dir.path().join("e.toml"), content).unwrap();
2077 let dirs = vec![(src_dir.path().to_path_buf(), false)];
2078 let dest = dest_dir.path().join("out.toml");
2079 export_theme(&dirs, "e", &dest).unwrap();
2080 assert_eq!(fs::read_to_string(&dest).unwrap(), content);
2081 assert!(export_theme(&dirs, "missing", &dest).is_err());
2082 }
2083
2084 #[test]
2085 fn load_theme_preview_returns_role_swatches() {
2086 let dir = tempfile::tempdir().unwrap();
2087 fs::write(dir.path().join("nord.toml"), nord_toml()).unwrap();
2088 let dirs = vec![(dir.path().to_path_buf(), false)];
2089 let p = load_theme_preview(&dirs, "nord").unwrap();
2090 assert_eq!(p.background.as_deref(), Some("#2e3440")); // surface.page
2091 assert_eq!(p.foreground.as_deref(), Some("#d8dee9")); // content.primary
2092 assert_eq!(p.accent.as_deref(), Some("#81a1c1")); // action.primary
2093 assert_eq!(p.border.as_deref(), Some("#4c566a")); // line.border
2094 }
2095
2096 #[test]
2097 fn bundled_themes_dir_resolves_to_shipped_themes() {
2098 // The crate ships its themes, so this must resolve in-tree and the
2099 // Akari defaults the console falls back to must be present.
2100 let dir = bundled_themes_dir().expect("makeover ships a themes/ directory");
2101 assert!(dir.join("akari-dawn.toml").is_file());
2102 assert!(dir.join("akari-night.toml").is_file());
2103 }
2104
2105 #[test]
2106 fn every_theme_is_accounted_for_in_third_party_notices() {
2107 // Attribution is a redistribution obligation, not a nicety: adding a
2108 // theme without a notice entry silently ships someone's work
2109 // uncredited. Fail here instead.
2110 let notices = std::fs::read_to_string(
2111 Path::new(env!("CARGO_MANIFEST_DIR")).join("THIRD-PARTY-NOTICES.md"),
2112 )
2113 .expect("THIRD-PARTY-NOTICES.md must exist");
2114 let missing: Vec<&str> = embedded_themes()
2115 .map(|(id, _)| id)
2116 .filter(|id| !notices.contains(*id))
2117 .collect();
2118 assert!(
2119 missing.is_empty(),
2120 "themes missing from THIRD-PARTY-NOTICES.md: {missing:?}"
2121 );
2122 }
2123
2124 #[test]
2125 fn adapted_themes_carry_inline_attribution() {
2126 // Each adapted file must name its upstream in-file, so the credit
2127 // survives someone copying a single .toml out of the crate.
2128 const ORIGINALS: [&str; 5] = [
2129 "makenotwork",
2130 "goingson",
2131 "audiofiles",
2132 "high-contrast",
2133 "neobrute",
2134 ];
2135 for (id, source) in embedded_themes() {
2136 if ORIGINALS.contains(&id) {
2137 continue;
2138 }
2139 assert!(
2140 source.contains("adapted from"),
2141 "adapted theme `{id}` is missing its inline attribution header"
2142 );
2143 }
2144 }
2145
2146 #[test]
2147 fn embedded_themes_match_the_directory() {
2148 // The embedded copy and themes/ are two views of one source. If they
2149 // ever disagree, path-based and path-free consumers render different
2150 // theme sets, which is exactly the drift shipping the data was meant
2151 // to prevent.
2152 let dir = bundled_themes_dir().unwrap();
2153 let mut on_disk: Vec<String> = std::fs::read_dir(&dir)
2154 .unwrap()
2155 .filter_map(|e| {
2156 let path = e.ok()?.path();
2157 if path.extension()? != "toml" {
2158 return None;
2159 }
2160 Some(path.file_stem()?.to_str()?.to_string())
2161 })
2162 .collect();
2163 let mut embedded: Vec<String> = embedded_themes().map(|(id, _)| id.to_string()).collect();
2164 on_disk.sort();
2165 embedded.sort();
2166 assert_eq!(embedded, on_disk, "embedded theme set drifted from themes/");
2167 }
2168
2169 #[test]
2170 fn every_embedded_theme_parses() {
2171 // Guards the path-free consumers (MNW server, the Tauri build steps)
2172 // the same way every_shipped_theme_loads guards the path-based ones.
2173 let mut count = 0;
2174 for (id, source) in embedded_themes() {
2175 parse_theme_str(id, source, false)
2176 .unwrap_or_else(|e| panic!("embedded theme `{id}` failed to parse: {e}"));
2177 count += 1;
2178 }
2179 assert!(count >= 30, "expected the full theme set, got {count}");
2180 }
2181
2182 #[test]
2183 fn every_shipped_theme_loads() {
2184 // Guards the data, not just the loader: a malformed or truncated
2185 // .toml in themes/ is a shipping bug, and it should fail here rather
2186 // than at a user's first launch.
2187 let dir = bundled_themes_dir().unwrap();
2188 let dirs = vec![(dir.clone(), false)];
2189 let themes = list_themes_from_dirs(&dirs);
2190 assert!(
2191 themes.len() >= 30,
2192 "expected the full theme set, got {}",
2193 themes.len()
2194 );
2195 for meta in &themes {
2196 load_theme(&dirs, &meta.id)
2197 .unwrap_or_else(|e| panic!("shipped theme `{}` failed to load: {e}", meta.id));
2198 }
2199 }
2200 }
2201