Explain runtime invariants and avoid redundant unwraps

crates/ferese-theme/src/gallery.rs

@@ -17,6 +17,10 @@ pub struct TileOptions {
     pub id: Id,
 }
 
+/// Shows a theme family using its validated appearance palettes.
+///
+/// # Panics
+/// The family must contain a usable palette with valid hexadecimal colors.
 pub fn tile<M: Clone + 'static>(
     family: &Family,
     options: TileOptions,
@@ -36,7 +40,9 @@ pub fn tile<M: Clone + 'static>(
     let label_color = family
         .palette(variant.unwrap_or(Appearance::Light))
         .or(family.dark.as_ref())
-        .map(|palette| crate::parse_color(&palette.text).unwrap())
+        .map(|palette| {
+            crate::parse_color(&palette.text).expect("theme family text is a validated color")
+        })
         .unwrap_or(palette.text);
     let mut caption = row([])
         .spacing(6)
@@ -141,7 +147,9 @@ fn preview_with_radius(
         std::sync::Mutex<std::collections::HashMap<String, (Family, icon::Handle)>>,
     > = std::sync::OnceLock::new();
     let cache = CACHE.get_or_init(Default::default);
-    let mut cache = cache.lock().unwrap();
+    let mut cache = cache
+        .lock()
+        .expect("theme preview cache must not be used after a mutator panics");
     if cache.get(&key).is_none_or(|(cached, _)| cached != family) {
         let handle = icon::from_svg_bytes(
             svg_with_radius(family, variant, active, selected, radius).into_bytes(),
@@ -207,7 +215,7 @@ fn svg_with_radius(
     result.push_str("<clipPath id=\"preview\"><polygon points=\"");
     for [x, y] in points {
         use std::fmt::Write as _;
-        write!(result, "{x:.4},{y:.4} ").unwrap();
+        write!(result, "{x:.4},{y:.4} ").expect("formatting into an owned String cannot fail");
     }
     result.push_str("\"/></clipPath></defs><g clip-path=\"url(#preview)\">");
     for appearance in [Appearance::Light, Appearance::Dark] {
@@ -263,10 +271,11 @@ fn svg_with_radius(
             .palette(active.unwrap_or(Appearance::Dark))
             .or(family.dark.as_ref())
             .or(family.light.as_ref())
-            .unwrap();
+            .expect("a theme family provides at least one appearance palette");
         let foreground = ferese_theme_model::hex(ferese_theme_model::readable(
             [1.; 4],
-            ferese_theme_model::rgba(&p.accent).unwrap(),
+            ferese_theme_model::rgba(&p.accent)
+                .expect("resolved theme colors must be valid hexadecimal RGBA"),
             4.5,
         ));
         result.push_str(&format!(r#"<circle cx="183" cy="16" r="10" fill="{}"/><path d="M178 16l3 3 6-6" fill="none" stroke="{foreground}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>"#, p.accent));

crates/ferese-theme/src/icons.rs

@@ -136,7 +136,10 @@ impl TintCache {
             .iter()
             .position(|entry| std::ptr::eq(entry.source, source) && entry.colors == colors)
         {
-            let entry = self.entries.remove(index).unwrap();
+            let entry = self
+                .entries
+                .remove(index)
+                .expect("the cache lookup identifies an existing icon entry");
             let handle = entry.handle.clone();
             self.entries.push_back(entry);
             return handle;
@@ -147,7 +150,11 @@ impl TintCache {
         if bytes <= TINT_CACHE_BYTES {
             while self.entries.len() >= TINT_CACHE_ENTRIES || self.bytes + bytes > TINT_CACHE_BYTES
             {
-                self.bytes -= self.entries.pop_front().unwrap().bytes;
+                self.bytes -= self
+                    .entries
+                    .pop_front()
+                    .expect("cache eviction requires an entry while over budget")
+                    .bytes;
             }
             self.bytes += bytes;
             self.entries.push_back(TintedIcon {

crates/ferese-theme/src/palette.rs

@@ -94,8 +94,18 @@ impl Palette {
                 stop.color.a = opacity;
             }
 
-            let from = crate::composite(candidate.stops[0].unwrap().color, self.sidebar);
-            let to = crate::composite(candidate.stops[1].unwrap().color, self.sidebar);
+            let from = crate::composite(
+                candidate.stops[0]
+                    .expect("the constructed linear gradient contains both endpoint stops")
+                    .color,
+                self.sidebar,
+            );
+            let to = crate::composite(
+                candidate.stops[1]
+                    .expect("the constructed linear gradient contains both endpoint stops")
+                    .color,
+                self.sidebar,
+            );
             let lower = Color::from_rgb(from.r.min(to.r), from.g.min(to.g), from.b.min(to.b));
             let upper = Color::from_rgb(from.r.max(to.r), from.g.max(to.g), from.b.max(to.b));
             let lightness = crate::luminance(foreground);

crates/ferese-theme/src/typography.rs

@@ -6,7 +6,10 @@ pub fn font(family: Option<&str>) -> cosmic::font::Font {
         return cosmic::font::default();
     };
     static FONTS: OnceLock<Mutex<HashMap<String, cosmic::font::Font>>> = OnceLock::new();
-    let mut fonts = FONTS.get_or_init(Default::default).lock().unwrap();
+    let mut fonts = FONTS
+        .get_or_init(Default::default)
+        .lock()
+        .expect("shared font cache must not be used after a mutator panics");
     if let Some(font) = fonts.get(family) {
         return *font;
     }