fix(assets): make icon preloading work at all, and asset failures visible

Three defects that all end the same way: a hole in the video and no diagnostic.

- Icon preloading could never work. The painter keyed its cache on the
  oversampled render size, the preloader on the target size — for a 40x40
  icon one wrote `80x80` and the other read `40x40`, so the keys could not
  collide at any size. The mechanism meant to stop N render threads hitting
  the network in parallel added a wasted download and rasterization, then
  let every thread fetch anyway. The preloader also rasterized without the
  oversample, so fixing the key alone would have turned a useless preload
  into a harmful one: the painter would finally find a bitmap, at half the
  resolution. Both sites now go through one `icon_cache_key`, which applies
  the oversample and builds the key — the drift is no longer expressible.
- Icons had no disk cache and failed silently at every level. There is now a
  cache on disk, following the pattern `google_fonts.rs` already uses in this
  crate, and an unresolvable icon fails the preload instead of leaving a gap.
- Video frame extraction failed silently too: a missing or failing ffmpeg
  produced an entirely empty video with no warning. PR #151 had already
  hardened the *audio* extraction of embedded videos in this same crate,
  with an availability probe and a warning emitted once; that discipline is
  now extended to the frame path, which had been left behind.

Warnings added here are deduplicated: `prepare_scene` runs per frame, so an
unguarded one would print over a thousand times on a 1200-frame render.

Author: LeadcodeDev

crates/rustmotion-components/src/icon.rs

@@ -5,7 +5,7 @@ use skia_safe::{Canvas, ColorType, ImageInfo, Paint, Rect, SamplingOptions};
 use rustmotion_core::css::CssStyle;
 use rustmotion_core::engine::animator::AnimatedProperties;
 use rustmotion_core::engine::layout_pass::BoxLayout;
-use rustmotion_core::engine::renderer::{asset_cache, fetch_icon_svg};
+use rustmotion_core::engine::renderer::{asset_cache, fetch_icon_svg, icon_cache_key};
 use rustmotion_core::schema::TimelineStep;
 use rustmotion_core::traits::{PaintCtx, Painter, TimingConfig};
 
@@ -38,22 +38,36 @@ impl Painter for Icon {
         _ctx: &PaintCtx,
     ) {
         let color = self.style.color_str_or("#FFFFFF");
-        // Oversample 2× so the rasterized SVG stays crisp under sub-pixel
-        // positioning and minor scale animations. Skia's high-quality
-        // sampling downscales to layout size without softening edges.
-        const OVERSAMPLE: u32 = 2;
         let target_w = (layout.width as u32).max(1);
         let target_h = (layout.height as u32).max(1);
-        let render_w = target_w * OVERSAMPLE;
-        let render_h = target_h * OVERSAMPLE;
-
-        let cache_key = format!("icon:{}:{}:{}x{}", self.icon, color, render_w, render_h);
+        // Oversampling (crisp edges under sub-pixel positioning / scale
+        // animation) and the cache key are computed together by
+        // `icon_cache_key` — see its doc for why that matters (issue #166):
+        // this used to be a local `const OVERSAMPLE` here plus an
+        // independent `format!` in `preload.rs`'s prefetcher, and the two
+        // could never agree.
+        let (render_w, render_h, cache_key) = icon_cache_key(&self.icon, color, target_w, target_h);
 
         let cache = asset_cache();
         let img = if let Some(cached) = cache.get(&cache_key) {
             cached.clone()
         } else {
             let Ok(svg_data) = fetch_icon_svg(&self.icon, color, render_w, render_h) else {
+                // Preload (issue #167 item 2) already hard-fails when an
+                // icon cannot be resolved via disk cache or network, so this
+                // branch is defense in depth (paint_content can run without
+                // a preceding prefetch, or the layout-derived target size
+                // here can differ from the preloader's style-based
+                // estimate, producing a genuine cache miss). Guarded so a
+                // single offline/typo'd icon does not spam once per frame
+                // over a render that can be 1000+ frames long.
+                if crate::warn_once_for(&format!("icon-fetch-failed:{}", self.icon)) {
+                    eprintln!(
+                        "Warning: icon '{}' could not be loaded (checked the disk cache and \
+                         the network) — nothing will be painted for it.",
+                        self.icon
+                    );
+                }
                 return;
             };
 
@@ -100,3 +114,100 @@ impl Painter for Icon {
         );
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn base_ctx() -> PaintCtx {
+        PaintCtx {
+            time: 0.0,
+            scene_duration: 1.0,
+            frame_index: 0,
+            fps: 30,
+            video_width: 100,
+            video_height: 100,
+            stagger_offset: 0.0,
+        }
+    }
+
+    fn solid_image() -> skia_safe::Image {
+        let px = [255u8, 0, 255, 255];
+        let mut data = Vec::with_capacity(4 * 4);
+        for _ in 0..4 {
+            data.extend_from_slice(&px);
+        }
+        let img_info = ImageInfo::new(
+            (2, 2),
+            ColorType::RGBA8888,
+            skia_safe::AlphaType::Premul,
+            None,
+        );
+        let skia_data = skia_safe::Data::new_copy(&data);
+        skia_safe::images::raster_from_data(&img_info, skia_data, 2 * 4).expect("sentinel image")
+    }
+
+    /// Regression for issue #166: proves the painter's cache-key formula is
+    /// literally `icon_cache_key`. Pre-populate `asset_cache()` under the
+    /// exact key `preload.rs`'s prefetcher now computes for a 40×40 target,
+    /// then confirm the painter finds and paints it — instead of falling
+    /// through to `fetch_icon_svg` for a nonsense icon id (which pre-fix, on
+    /// a key mismatch, is exactly what would have happened every time).
+    #[test]
+    fn painter_finds_the_entry_preload_would_have_written() {
+        let icon = Icon {
+            icon: "test-suite:icon-cache-key-agreement".to_string(),
+            timing: Default::default(),
+            style: CssStyle::default(),
+            timeline: Vec::new(),
+            stagger: None,
+        };
+        let target_w = 40u32;
+        let target_h = 40u32;
+        let color = icon.style.color_str_or("#FFFFFF");
+        let (_, _, key) = icon_cache_key(&icon.icon, color, target_w, target_h);
+
+        asset_cache().insert(key.clone(), solid_image());
+
+        let layout = BoxLayout {
+            width: target_w as f32,
+            height: target_h as f32,
+            ..Default::default()
+        };
+        let ctx = base_ctx();
+        let props = AnimatedProperties::default();
+        let mut surface =
+            skia_safe::surfaces::raster_n32_premul((target_w as i32, target_h as i32)).unwrap();
+        {
+            let canvas = surface.canvas();
+            icon.paint_content(canvas, &layout, &props, &ctx);
+        }
+
+        // Cleanup so this entry does not leak into other tests sharing the
+        // process-global asset_cache.
+        asset_cache().remove(&key);
+
+        let snapshot = surface.image_snapshot();
+        let info = ImageInfo::new(
+            (target_w as i32, target_h as i32),
+            ColorType::RGBA8888,
+            skia_safe::AlphaType::Premul,
+            None,
+        );
+        let mut buf = vec![0u8; (target_w * target_h * 4) as usize];
+        let ok = snapshot.read_pixels(
+            &info,
+            &mut buf,
+            (target_w * 4) as usize,
+            skia_safe::IPoint::new(0, 0),
+            skia_safe::image::CachingHint::Disallow,
+        );
+        assert!(ok, "pixel read should succeed");
+        let has_ink = buf.chunks(4).any(|px| px[3] > 0);
+        assert!(
+            has_ink,
+            "painter must have found and painted the cache entry preload.rs would have \
+             written under the same key — if the keys disagree, nothing paints"
+        );
+    }
+}

crates/rustmotion-components/src/video.rs

@@ -82,8 +82,26 @@ impl Painter for Video {
             }
         }
 
-        let Ok(frame_data) = extract_video_frame(&self.src, source_time, width, height) else {
-            return;
+        let frame_data = match extract_video_frame(&self.src, source_time, width, height) {
+            Ok(data) => data,
+            Err(e) => {
+                // Item 3 (issue #167): decoding failures (ffmpeg missing, or
+                // this specific frame failing) used to be a silent `return`
+                // — a video component would render entirely blank with no
+                // trace anywhere. `paint_content` runs once per frame, so
+                // the warning is deduplicated per `src` via `warn_once_for`
+                // (the same guard `lib.rs` already uses for exactly this
+                // per-frame-call-site problem) instead of printing the same
+                // line a thousand times over a render.
+                if crate::warn_once_for(&format!("video-frame:{}", self.src)) {
+                    eprintln!(
+                        "Warning: video '{}' could not be decoded: {e}. This component will \
+                         render nothing for the remainder of the video.",
+                        self.src
+                    );
+                }
+                return;
+            }
         };
         let skia_data = skia_safe::Data::new_copy(&frame_data);
         if let Some(img) = skia_safe::Image::from_encoded(skia_data) {
@@ -93,3 +111,76 @@ impl Painter for Video {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rustmotion_core::engine::animator::AnimatedProperties;
+    use rustmotion_core::engine::layout_pass::BoxLayout;
+    use rustmotion_core::traits::PaintCtx;
+
+    fn base_ctx() -> PaintCtx {
+        PaintCtx {
+            time: 0.0,
+            scene_duration: 1.0,
+            frame_index: 0,
+            fps: 30,
+            video_width: 100,
+            video_height: 100,
+            stagger_offset: 0.0,
+        }
+    }
+
+    /// A failed frame extraction (bad src, or no ffmpeg) must be reported,
+    /// not swallowed. Pre-fix, `paint_content` never calls `warn_once_for`
+    /// on this path at all, so the slot for this exact src stays unclaimed
+    /// ("first sighting" == true) forever — this is the observable half of
+    /// total silence we can assert on without capturing stderr.
+    #[test]
+    fn a_failed_frame_extraction_must_claim_its_warn_once_slot() {
+        let missing_src = std::env::temp_dir().join(format!(
+            "rustmotion-video-test-missing-{}-{}.mp4",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos(),
+        ));
+        let _ = std::fs::remove_file(&missing_src);
+        let src_str = missing_src.to_str().unwrap().to_string();
+
+        let video = Video {
+            src: src_str.clone(),
+            trim_start: None,
+            trim_end: None,
+            playback_rate: None,
+            fit: Default::default(),
+            volume: 1.0,
+            loop_video: None,
+            timing: Default::default(),
+            style: CssStyle::default(),
+            timeline: Vec::new(),
+            stagger: None,
+        };
+        let layout = BoxLayout {
+            width: 40.0,
+            height: 40.0,
+            ..Default::default()
+        };
+        let ctx = base_ctx();
+        let props = AnimatedProperties::default();
+        let mut surface = skia_safe::surfaces::raster_n32_premul((40, 40)).unwrap();
+        {
+            let canvas = surface.canvas();
+            video.paint_content(canvas, &layout, &props, &ctx);
+        }
+
+        let key = format!("video-frame:{}", src_str);
+        assert!(
+            !crate::warn_once_for(&key),
+            "paint_content must have claimed this warning slot on the failed extraction \
+             path — it is still unclaimed (first sighting), meaning nothing warned about \
+             the failure"
+        );
+    }
+}