teksilo_widgets/primitives/

image_widget.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! ImageWidget — displays a raster image (PNG, WebP) with a configurable
//! sizing policy, content-fit mode, and intra-box alignment.
//!
//! Unlike [`IconWidget`](super::icon_widget::IconWidget) which is designed
//! for small square tintable icons, `ImageWidget` handles arbitrary aspect
//! ratios and defaults to full-color rendering.
//!
//! # Sizing model
//!
//! Two independent concerns, mirroring Qt's `QLabel`/`QPixmap`, SwiftUI's
//! `Image`, and CSS's replaced-element model:
//!
//! 1. **Box size** — how big the widget's layout rectangle is.
//!    - [`width`](ImageWidget::width) / [`height`](ImageWidget::height) /
//!      [`size`](ImageWidget::size) pin a **fixed** logical extent. A pinned
//!      axis is *rigid*: it is reported as-is and is never scaled up to a
//!      parent's proposal (this is the SwiftUI `.frame(width:height:)` /
//!      Qt fixed-size behaviour). Pinning only one axis derives the other
//!      from the image's aspect ratio (CSS `width: Npx; height: auto`).
//!    - With no axis pinned the widget reports its **natural pixel size**.
//!      By default ([`resizable`](ImageWidget::resizable) `= true`) a
//!      constraining proposal scales that natural size down/up while
//!      preserving aspect ratio; `resizable(false)` locks it to the raw
//!      pixel dimensions (SwiftUI's default non-`.resizable()` image).
//! 2. **Content fit** — how the image pixels map into that box, via
//!    [`ImageFit`] (`Contain` / `Cover` / `Fill` / `ScaleDown` / `None`,
//!    the CSS `object-fit` set) plus
//!    [`alignment`](ImageWidget::alignment) (the CSS `object-position`
//!    equivalent) for where slack/overflow lands. Modes that overflow the
//!    box (`Cover`, and `None` on an oversized image) are clipped to the
//!    box so the image never bleeds past its layout rectangle.
//!
//! For a fixed 32×32 logo: `ImageWidget::new(icon).size(32.0, 32.0)` — the
//! box is exactly 32×32 and the artwork is letterboxed inside it
//! (`Contain`, the default).
//!
//! ```rust
//! # use teksilo_canvas::RasterIcon;
//! # use teksilo_widgets::primitives::image_widget::{ImageWidget, ImageFit};
//! # use teksilo_widgets::primitives::image_mask::ImageMaskShape;
//! // A 64×64 source pinned to a fixed 32×32 box, with no masking.
//! let icon = RasterIcon::from_raw(vec![255; 64 * 64 * 4], 64, 64);
//! let _logo = ImageWidget::new(&icon).size(32.0, 32.0);
//!
//! // Cover a square avatar slot and crop to a circle.
//! let _avatar = ImageWidget::new(&icon)
//!     .mask(ImageMaskShape::Circle)
//!     .fit(ImageFit::Cover)
//!     .alt("User avatar")
//!     .size(48.0, 48.0);
//! ```

use std::rc::Rc;
use std::sync::Arc;

use teksilo_canvas::live_image::{
    LiveImageDraw, LiveImageError, LiveImageSource, LiveImageWriter, LivePixelFormat, ScalingFilter,
};
use teksilo_canvas::{Canvas, RasterIcon, Rect, Size, SizeProposal};
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::build_context::BuildContext;
use teksilo_core::environment::LayoutDirection;
use teksilo_core::widget::{LayoutContext, PaintContext, Widget};
use teksilo_core::{LiveImageAttachment, LiveImageSignals, WidgetId};
use teksilo_tokens::Alignment;

use super::image_mask::{ImageMaskShape, apply_alpha_mask, center_crop_square};

/// How the image is fitted within its layout bounds: the CSS `object-fit`
/// set, shared with every widget that places a picture.
pub use teksilo_canvas::image_geometry::ImageFit;

/// A picture written once into a live source, and the writer that keeps
/// it: a source frees its pixels when its last writer drops.
pub(crate) struct CommittedImage {
    source: LiveImageSource,
    _writer: LiveImageWriter,
}

impl CommittedImage {
    /// Write `pixels` (`width × height`, RGBA8, tightly packed) once,
    /// moving the buffer in without a copy; the error when the source
    /// refuses it (a zero side, a short buffer, a side over its limit).
    pub(crate) fn commit(
        pixels: Vec<u8>,
        width: u32,
        height: u32,
    ) -> Result<Rc<Self>, LiveImageError> {
        let source = LiveImageSource::builder(LivePixelFormat::Rgba8)
            .label("image")
            .build();
        let writer = source.writer();
        writer
            .swap_frame(width, height, width as usize * 4, pixels)
            .map_err(|rejected| rejected.error)?;
        Ok(Rc::new(Self {
            source,
            _writer: writer,
        }))
    }

    /// Its size; never zero, the source refused that.
    pub(crate) fn size(&self) -> (u32, u32) {
        self.source.size().unwrap_or((0, 0))
    }

    #[cfg(test)]
    pub(crate) fn source(&self) -> &LiveImageSource {
        &self.source
    }
}

/// `pixels` (`width × height`, RGBA8) centre-cropped to a square and masked
/// to `shape`, with the square's side. A buffer too short for its size is
/// returned as it is: the source refuses it when it is committed.
pub(crate) fn masked(
    pixels: Vec<u8>,
    width: u32,
    height: u32,
    shape: ImageMaskShape,
) -> (Vec<u8>, u32, u32) {
    let enough = (width as usize)
        .checked_mul(height as usize)
        .and_then(|n| n.checked_mul(4))
        .is_some_and(|needed| width > 0 && height > 0 && pixels.len() >= needed);
    if matches!(shape, ImageMaskShape::None) || !enough {
        return (pixels, width, height);
    }
    let tight = &pixels[..width as usize * height as usize * 4];
    let (mut cropped, side) = center_crop_square(tight, width, height);
    apply_alpha_mask(&mut cropped, side, side, shape);
    (cropped, side, side)
}

/// How an image's pixels reach the window.
enum Pixels {
    /// `new(&icon)` without a mask: one texture per icon and window, shared
    /// by every widget showing the icon, named after its identity.
    Shared { name: String, upload: Arc<[u8]> },
    /// `from_raw`, or masked: a live source written once at the first
    /// build, whose texture goes with the first frame that does not draw
    /// the widget.
    Owned(Owned),
}

#[derive(Default)]
struct Owned {
    /// The pixels until the first build commits them.
    pending: Option<Vec<u8>>,
    committed: Option<Rc<CommittedImage>>,
    signals: Option<LiveImageSignals>,
    attachment: Option<LiveImageAttachment>,
}

/// A widget that displays a raster image (PNG, WebP, or raw RGBA pixels) with configurable fit and alignment.
pub struct ImageWidget {
    pixels: Pixels,
    width: u32,
    height: u32,
    fit: ImageFit,
    /// Where the fitted image sits within the box when the active fit
    /// leaves slack (`Contain`/`ScaleDown`/`None` smaller than the box) or
    /// crops (`Cover`/`None` larger than the box). The CSS
    /// `object-position` analogue. Defaults to centered.
    alignment: Alignment,
    /// Optional fixed display size. A pinned axis is rigid — reported as-is
    /// and never scaled to a parent proposal. `None` means "derive": from
    /// the aspect ratio when the other axis is pinned, otherwise from the
    /// natural pixel dimensions.
    display_width: Option<f32>,
    display_height: Option<f32>,
    /// When no axis is pinned, whether a constraining proposal scales the
    /// natural size (`true`, the default) or the box stays locked to the
    /// raw pixel dimensions (`false`, SwiftUI's default non-resizable
    /// image). Has no effect once a dimension is pinned.
    resizable: bool,
    /// Accessibility description.
    alt: Option<String>,
    /// When true, hide from the accessibility tree entirely —
    /// appropriate for purely decorative images whose semantic
    /// content is already conveyed by adjacent text.
    a11y_hidden: bool,
}

impl ImageWidget {
    /// Create from a decoded [`RasterIcon`] (e.g., from `res!()`).
    ///
    /// The texture is named after the icon's identity, so every
    /// `ImageWidget` showing this icon (or a clone of it) in a window shares
    /// one texture, uploaded once.
    ///
    /// That texture, with its mip chain, stays on the GPU for the life of the
    /// window and is never freed, even once no widget shows the icon. Each
    /// distinct identity keeps one: a clone of the icon is the same identity,
    /// but the same bytes decoded again are a new one. Keep decoded images
    /// in an application cache and clone them, rather than decoding per
    /// widget or per realization: in a virtualized grid of runtime images
    /// such as album covers, a cover decoded each time its tile scrolls into
    /// view leaves one more texture behind each time. Pixels shown once, or
    /// that change, belong on [`from_raw`](Self::from_raw), whose texture
    /// goes with the widget; a [`mask`](Self::mask) takes that path too.
    pub fn new(icon: &RasterIcon) -> Self {
        Self {
            pixels: Pixels::Shared {
                name: format!("_img_{}", icon.texture_key()),
                upload: Arc::clone(icon.shared_pixels()),
            },
            width: icon.width(),
            height: icon.height(),
            fit: ImageFit::Contain,
            alignment: Alignment::CENTER,
            display_width: None,
            display_height: None,
            resizable: true,
            alt: None,
            a11y_hidden: false,
        }
    }

    /// Create from raw RGBA pixel data, `width × height`, tightly packed.
    ///
    /// The pixels are written once into a live source when the widget is
    /// first built, without a copy. The window's texture for them goes with
    /// the first frame that does not draw the widget (it was destroyed,
    /// scrolled out or parked), so GPU memory follows what is on screen,
    /// and comes back with one upload. Input the source refuses (a zero
    /// side, a buffer shorter than `width × height × 4`, a side over
    /// [`LiveImageSource::MAX_DIMENSION`]) draws nothing, and says so once
    /// on standard error.
    pub fn from_raw(pixels: Vec<u8>, width: u32, height: u32) -> Self {
        Self {
            pixels: Pixels::Owned(Owned {
                pending: Some(pixels),
                ..Owned::default()
            }),
            width,
            height,
            fit: ImageFit::Contain,
            alignment: Alignment::CENTER,
            display_width: None,
            display_height: None,
            resizable: true,
            alt: None,
            a11y_hidden: false,
        }
    }

    /// Show a picture already written once, which other widgets may show
    /// too: `Avatar` keeps one across the rebuilds that leave its image as
    /// it was.
    pub(crate) fn from_committed(image: Rc<CommittedImage>) -> Self {
        let (width, height) = image.size();
        Self {
            pixels: Pixels::Owned(Owned {
                committed: Some(image),
                ..Owned::default()
            }),
            width,
            height,
            fit: ImageFit::Contain,
            alignment: Alignment::CENTER,
            display_width: None,
            display_height: None,
            resizable: true,
            alt: None,
            a11y_hidden: false,
        }
    }

    /// Apply an anti-aliased alpha mask to the image at construction
    /// time. The pixels are first centre-cropped to the shorter side
    /// (so the mask shape is geometrically consistent regardless of
    /// the source aspect ratio), then their alpha channel is
    /// modulated by the mask coverage. RGB is preserved.
    ///
    /// `Cover` fit is the natural pairing — the masked square fills
    /// the avatar/thumbnail bounds and the masked-out corners stay
    /// transparent. `Contain` works but may letterbox. The default
    /// fit (`Contain`) is left unchanged so callers explicitly pick
    /// a fit when they apply a mask.
    ///
    /// The masked picture is the widget's own, written once into a live
    /// source as [`from_raw`](Self::from_raw)'s is: the icon's shared
    /// texture is left alone. `ImageMaskShape::None` is a no-op.
    pub fn mask(mut self, shape: ImageMaskShape) -> Self {
        if matches!(shape, ImageMaskShape::None) {
            return self;
        }
        let pixels = match std::mem::replace(&mut self.pixels, Pixels::Owned(Owned::default())) {
            Pixels::Shared { upload, .. } => upload.to_vec(),
            Pixels::Owned(Owned {
                pending: Some(pixels),
                ..
            }) => pixels,
            // Already committed: there is nothing left to crop.
            Pixels::Owned(owned) => {
                self.pixels = Pixels::Owned(owned);
                return self;
            }
        };
        let (masked, width, height) = masked(pixels, self.width, self.height, shape);
        self.pixels = Pixels::Owned(Owned {
            pending: Some(masked),
            ..Owned::default()
        });
        self.width = width;
        self.height = height;
        self
    }

    /// Set the content-fit mode — how the image pixels map into the box.
    /// See [`ImageFit`].
    pub fn fit(mut self, fit: ImageFit) -> Self {
        self.fit = fit;
        self
    }

    /// Set where the fitted image sits within the box when the active fit
    /// leaves slack or crops (the CSS `object-position` analogue). Defaults
    /// to [`Alignment::CENTER`]. Leading/Trailing resolve against the
    /// active layout direction (RTL-aware).
    pub fn alignment(mut self, alignment: Alignment) -> Self {
        self.alignment = alignment;
        self
    }

    /// Pin a fixed display width (in logical pixels). The width axis
    /// becomes rigid — reported as-is and never scaled to a parent
    /// proposal. With no height pinned, the height derives from the
    /// image's aspect ratio (CSS `width: Npx; height: auto`).
    pub fn width(mut self, w: f32) -> Self {
        self.display_width = Some(w);
        self
    }

    /// Pin a fixed display height (in logical pixels). The height axis
    /// becomes rigid. With no width pinned, the width derives from the
    /// image's aspect ratio.
    pub fn height(mut self, h: f32) -> Self {
        self.display_height = Some(h);
        self
    }

    /// Pin both display width and height (in logical pixels). The box is
    /// exactly this size, rigid on both axes; the image content is fitted
    /// inside it via the [`fit`](Self::fit) mode. This is the
    /// fixed-size-logo case — `.size(32.0, 32.0)`.
    pub fn size(mut self, w: f32, h: f32) -> Self {
        self.display_width = Some(w);
        self.display_height = Some(h);
        self
    }

    /// Control whether, with no axis pinned, a constraining parent
    /// proposal scales the natural pixel size (`true`, the default) or the
    /// box stays locked to the raw pixel dimensions (`false`). Equivalent
    /// to opting out of SwiftUI's `.resizable()`. No effect once a
    /// dimension is pinned via [`width`](Self::width) /
    /// [`height`](Self::height) / [`size`](Self::size).
    pub fn resizable(mut self, resizable: bool) -> Self {
        self.resizable = resizable;
        self
    }

    /// Set the accessibility alt text.
    pub fn alt(mut self, text: impl Into<String>) -> Self {
        self.alt = Some(text.into());
        self
    }

    /// Mark this image as decorative — hidden from the accessibility
    /// tree. Use when the image's semantic content is already conveyed
    /// by adjacent text (e.g. a hero image next to its caption). ARIA
    /// equivalent of `alt=""` / `role="presentation"`.
    pub fn a11y_hidden(mut self) -> Self {
        self.a11y_hidden = true;
        self
    }

    /// Natural aspect ratio (width / height).
    fn aspect_ratio(&self) -> f32 {
        if self.height == 0 {
            1.0
        } else {
            self.width as f32 / self.height as f32
        }
    }

    /// Compute the image rectangle within `bounds` for the active fit mode,
    /// positioned by [`alignment`](Self::alignment). `rtl` flips the
    /// horizontal Leading/Trailing axis.
    fn fitted_rect(&self, bounds: Rect, rtl: bool) -> Rect {
        self.fit.fitted_rect(
            Size::new(self.width as f32, self.height as f32),
            bounds,
            self.alignment,
            rtl,
        )
    }
}

impl std::fmt::Debug for ImageWidget {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let path = match &self.pixels {
            Pixels::Shared { .. } => "shared",
            Pixels::Owned(_) => "owned",
        };
        f.debug_struct("ImageWidget")
            .field("width", &self.width)
            .field("height", &self.height)
            .field("fit", &self.fit)
            .field("pixels", &path)
            .finish()
    }
}

impl Widget for ImageWidget {
    /// An owned picture is committed to its source at the first build, and
    /// every build attaches it in the widget's window.
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        let Pixels::Owned(owned) = &mut self.pixels else {
            return vec![];
        };
        if owned.committed.is_none()
            && let Some(pixels) = owned.pending.take()
        {
            let bytes = pixels.len();
            match CommittedImage::commit(pixels, self.width, self.height) {
                Ok(image) => owned.committed = Some(image),
                Err(error) => eprintln!(
                    "teksilo: an image of {}x{} with {bytes} bytes of pixels was refused \
                     ({error}): it draws nothing",
                    self.width, self.height
                ),
            }
        }
        if let Some(image) = &owned.committed {
            let signals = owned
                .signals
                .get_or_insert_with(|| LiveImageSignals::new(&image.source));
            owned.attachment = Some(ctx.attach_live_image(&image.source, signals));
        }
        vec![]
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        _ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        let ar = self.aspect_ratio();

        let size = match (self.display_width, self.display_height) {
            // Both axes pinned → rigid box. The proposal cannot override an
            // explicit size; the image content is fitted inside via `fit`.
            (Some(w), Some(h)) => Size::new(w, h),
            // One axis pinned → the other derives from the aspect ratio
            // (CSS `width: Npx; height: auto`). Still rigid.
            (Some(w), None) => Size::new(w, w / ar),
            (None, Some(h)) => Size::new(h * ar, h),
            // Neither pinned → natural pixel size, scaled to a constraining
            // proposal only when `resizable` (the default).
            (None, None) => {
                let natural_w = self.width as f32;
                let natural_h = self.height as f32;
                if !self.resizable {
                    Size::new(natural_w, natural_h)
                } else {
                    match (proposal.width, proposal.height) {
                        // Both constrained: fit within, preserving aspect ratio
                        (Some(pw), Some(ph)) => {
                            let scale = (pw / natural_w).min(ph / natural_h);
                            Size::new(natural_w * scale, natural_h * scale)
                        }
                        // Width constrained: compute height from aspect ratio
                        (Some(pw), None) => Size::new(pw, pw / ar),
                        // Height constrained: compute width from aspect ratio
                        (None, Some(ph)) => Size::new(ph * ar, ph),
                        // Unconstrained: natural size
                        (None, None) => Size::new(natural_w, natural_h),
                    }
                }
            }
        };
        size.into()
    }

    fn paint(&self, bounds: Rect, canvas: &mut Canvas, ctx: &PaintContext) {
        let rtl = matches!(ctx.layout_direction, LayoutDirection::RightToLeft);
        let rect = self.fitted_rect(bounds, rtl);
        let (name, upload) = match &self.pixels {
            Pixels::Shared { name, upload } => (name, upload),
            Pixels::Owned(owned) => {
                // The window's texture holds the pixels; the frame carries
                // the attachment. `Cover` and an oversized `None` are cut
                // to the box by texture coordinates, and a thumbnail drawn
                // small samples the mip chain the window builds.
                if let Some(attachment) = &owned.attachment {
                    canvas.draw_live_image(
                        attachment.consumer(),
                        &LiveImageDraw::new(rect, bounds).filter(ScalingFilter::Trilinear),
                    );
                }
                return;
            }
        };
        // Queuing shares the pixels; the check spares the name's allocation.
        if !canvas.has_pending_image(name) {
            canvas.ensure_shared_image_registered(
                name,
                self.width,
                self.height,
                Arc::clone(upload),
            );
        }

        // Modes that overflow the box (`Cover`, or `None` on an oversized
        // image) must not bleed past the widget's layout rectangle. Clip
        // to `bounds` only when the fitted rect actually exceeds it — the
        // renderer intersects this with any ancestor clip and pops it
        // cleanly, so it composes with ScrollAreas etc. `Contain` /
        // `ScaleDown` / a within-box image never overflow, so they skip the
        // clip commands entirely.
        const EPS: f32 = 0.01;
        let overflows = rect.x < bounds.x - EPS
            || rect.y < bounds.y - EPS
            || rect.x + rect.width > bounds.x + bounds.width + EPS
            || rect.y + rect.height > bounds.y + bounds.height + EPS;
        if overflows {
            canvas.set_clip(bounds);
            canvas.draw_image(rect, name);
            canvas.clear_clip();
        } else {
            canvas.draw_image(rect, name);
        }
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        if self.a11y_hidden {
            builder.set_hidden();
            return;
        }
        debug_assert!(
            self.alt.is_some(),
            "ImageWidget has no alt text — call .alt(\"…\") for meaningful images or .a11y_hidden() for decorative ones"
        );
        builder.set_role(teksilo_core::accesskit::Role::Image);
        if let Some(ref alt) = self.alt {
            builder.set_name(alt);
        }
    }
}

#[cfg(test)]
impl ImageWidget {
    /// The shared texture's name, for an unmasked icon.
    fn shared_name(&self) -> Option<&str> {
        match &self.pixels {
            Pixels::Shared { name, .. } => Some(name),
            Pixels::Owned(_) => None,
        }
    }

    /// The pixels an owned picture commits at its first build.
    fn pending_pixels(&self) -> Option<&[u8]> {
        match &self.pixels {
            Pixels::Owned(owned) => owned.pending.as_deref(),
            Pixels::Shared { .. } => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use teksilo_core::widget_tree::WidgetTree;

    #[test]
    fn natural_size() {
        let icon = RasterIcon::from_raw(vec![255; 400], 10, 10);
        let mut tree = WidgetTree::new();
        let img = tree.add(ImageWidget::new(&icon));
        tree.layout(SizeProposal::unspecified());
        let b = tree.bounds(img);
        assert!((b.width - 10.0).abs() < 0.01);
        assert!((b.height - 10.0).abs() < 0.01);
    }

    #[test]
    fn explicit_display_size() {
        let icon = RasterIcon::from_raw(vec![255; 400], 10, 10);
        let mut tree = WidgetTree::new();
        let img = tree.add(ImageWidget::new(&icon).size(200.0, 100.0));
        tree.layout(SizeProposal::unspecified());
        let b = tree.bounds(img);
        assert!((b.width - 200.0).abs() < 0.01);
        assert!((b.height - 100.0).abs() < 0.01);
    }

    #[test]
    fn size_that_fits_preserves_aspect_ratio() {
        let icon = RasterIcon::from_raw(vec![255; 800], 20, 10); // 2:1 aspect
        let widget = ImageWidget::new(&icon);
        let theme = teksilo_core::presets::intui::light();
        let ctx = LayoutContext::for_testing(&theme);
        // Width constrained to 100, no height constraint → 100x50
        let size = widget
            .layout_response(
                SizeProposal {
                    width: Some(100.0),
                    height: None,
                },
                &ctx,
            )
            .size;
        assert!((size.width - 100.0).abs() < 0.5, "width: {}", size.width);
        assert!((size.height - 50.0).abs() < 0.5, "height: {}", size.height);
    }

    #[test]
    fn paints_image_quad() {
        let icon = RasterIcon::from_raw(vec![255; 400], 10, 10);
        let mut tree = WidgetTree::new();
        tree.add(ImageWidget::new(&icon));
        tree.layout(SizeProposal::exact(10.0, 10.0));
        let frame = tree.render();
        assert!(!frame.images.is_empty(), "should render an image");
        assert!(frame.images[0].tint.is_none(), "should be full-color");
    }

    #[test]
    fn pending_image_registered() {
        let icon = RasterIcon::from_raw(vec![255; 400], 10, 10);
        let mut tree = WidgetTree::new();
        tree.add(ImageWidget::new(&icon));
        tree.layout(SizeProposal::exact(10.0, 10.0));
        let frame = tree.render();
        assert!(
            !frame.pending_images.is_empty(),
            "should register pending image"
        );
    }

    #[test]
    fn new_names_its_texture_after_the_icon_identity() {
        let icon = RasterIcon::from_raw(vec![255; 16], 2, 2);
        let a = ImageWidget::new(&icon);
        let clone = icon.clone();
        let b = ImageWidget::new(&clone);
        let expected = format!("_img_{}", icon.texture_key());
        assert_eq!(a.shared_name(), Some(expected.as_str()));
        assert_eq!(
            a.shared_name(),
            b.shared_name(),
            "a clone shares the original's texture"
        );

        // An icon with the same dimensions allocated after the first one is
        // dropped (often at the same address) must not reuse its texture.
        let first_name = {
            let first = Box::new(RasterIcon::from_raw(vec![255; 16], 2, 2));
            ImageWidget::new(&first).shared_name().map(str::to_owned)
        };
        let second = Box::new(RasterIcon::from_raw(vec![0; 16], 2, 2));
        assert_ne!(
            ImageWidget::new(&second).shared_name().map(str::to_owned),
            first_name
        );
    }

    #[test]
    fn from_raw_widgets_each_own_a_source() {
        // Two raw images of the same size and different bytes used to alias
        // on a per-size texture name, so one silently showed the other's
        // pixels. Each now owns a live source: two quads, two sources, and
        // nothing on the shared path.
        let mut tree = WidgetTree::new();
        tree.add(
            crate::primitives::HStack::new()
                .child(ImageWidget::from_raw(vec![255; 16], 2, 2))
                .child(ImageWidget::from_raw(vec![0; 16], 2, 2)),
        );
        tree.layout(SizeProposal::exact(100.0, 50.0));
        let frame = tree.render();
        assert_eq!(frame.live_images.len(), 2);
        assert!(
            !frame.live_images[0]
                .consumer
                .source()
                .ptr_eq(frame.live_images[1].consumer.source())
        );
        assert!(frame.images.is_empty() && frame.pending_images.is_empty());
    }

    #[test]
    fn fixed_size_is_rigid_against_constraining_proposal() {
        // Regression: a pinned `.size(32, 32)` must stay 32×32 no matter
        // what the parent proposes. The old layout path treated the
        // explicit size as a "natural size" and scaled it up to a
        // width-constraining proposal — a 512px source logo placed in a
        // wide title bar ballooned to the bar's full width.
        let icon = RasterIcon::from_raw(vec![255; 512 * 512 * 4], 512, 512);
        let widget = ImageWidget::new(&icon).size(32.0, 32.0);
        let theme = teksilo_core::presets::intui::light();
        let ctx = LayoutContext::for_testing(&theme);
        // Wide width proposal, no height constraint — the VStack-cross-axis
        // case that triggered the skribisto bug.
        let size = widget
            .layout_response(
                SizeProposal {
                    width: Some(600.0),
                    height: None,
                },
                &ctx,
            )
            .size;
        assert!((size.width - 32.0).abs() < 0.01, "width: {}", size.width);
        assert!((size.height - 32.0).abs() < 0.01, "height: {}", size.height);
    }

    #[test]
    fn single_axis_pin_derives_other_from_aspect_ratio() {
        let icon = RasterIcon::from_raw(vec![255; 40 * 10 * 4], 40, 10); // 4:1
        let theme = teksilo_core::presets::intui::light();
        let ctx = LayoutContext::for_testing(&theme);
        // Width pinned to 200 → height = 200 / 4 = 50, ignoring proposal.
        let w_pinned = ImageWidget::new(&icon)
            .width(200.0)
            .layout_response(SizeProposal::exact(999.0, 999.0), &ctx)
            .size;
        assert!((w_pinned.width - 200.0).abs() < 0.01);
        assert!(
            (w_pinned.height - 50.0).abs() < 0.01,
            "h: {}",
            w_pinned.height
        );
        // Height pinned to 20 → width = 20 * 4 = 80.
        let h_pinned = ImageWidget::new(&icon)
            .height(20.0)
            .layout_response(SizeProposal::exact(999.0, 999.0), &ctx)
            .size;
        assert!(
            (h_pinned.width - 80.0).abs() < 0.01,
            "w: {}",
            h_pinned.width
        );
        assert!((h_pinned.height - 20.0).abs() < 0.01);
    }

    #[test]
    fn resizable_false_locks_natural_pixel_size() {
        let icon = RasterIcon::from_raw(vec![255; 64 * 64 * 4], 64, 64);
        let theme = teksilo_core::presets::intui::light();
        let ctx = LayoutContext::for_testing(&theme);
        // Default (resizable) scales to a constraining proposal.
        let scaled = ImageWidget::new(&icon)
            .layout_response(SizeProposal::exact(16.0, 16.0), &ctx)
            .size;
        assert!((scaled.width - 16.0).abs() < 0.01);
        // resizable(false) ignores the proposal and keeps 64×64.
        let locked = ImageWidget::new(&icon)
            .resizable(false)
            .layout_response(SizeProposal::exact(16.0, 16.0), &ctx)
            .size;
        assert!((locked.width - 64.0).abs() < 0.01, "w: {}", locked.width);
        assert!((locked.height - 64.0).abs() < 0.01);
    }

    #[test]
    fn contain_centers_inside_a_wider_box() {
        // 1:1 image in a 200×100 box → 100×100 letterboxed, centered.
        let icon = RasterIcon::from_raw(vec![255; 10 * 10 * 4], 10, 10);
        let widget = ImageWidget::new(&icon).fit(ImageFit::Contain);
        let r = widget.fitted_rect(Rect::new(0.0, 0.0, 200.0, 100.0), false);
        assert!((r.width - 100.0).abs() < 0.01);
        assert!((r.height - 100.0).abs() < 0.01);
        assert!((r.x - 50.0).abs() < 0.01, "x: {}", r.x); // (200-100)/2
        assert!((r.y - 0.0).abs() < 0.01);
    }

    #[test]
    fn alignment_positions_content_within_box() {
        use teksilo_tokens::{HAlignment, VAlignment};
        let icon = RasterIcon::from_raw(vec![255; 10 * 10 * 4], 10, 10);
        let widget = ImageWidget::new(&icon)
            .fit(ImageFit::Contain)
            .alignment(Alignment {
                horizontal: HAlignment::Trailing,
                vertical: VAlignment::Bottom,
            });
        let r = widget.fitted_rect(Rect::new(0.0, 0.0, 200.0, 100.0), false);
        // 100×100 pushed to bottom-trailing: x = 200-100, y = 100-100.
        assert!((r.x - 100.0).abs() < 0.01, "x: {}", r.x);
        assert!((r.y - 0.0).abs() < 0.01, "y: {}", r.y);
        // RTL flips Trailing to the left edge.
        let r_rtl = widget.fitted_rect(Rect::new(0.0, 0.0, 200.0, 100.0), true);
        assert!((r_rtl.x - 0.0).abs() < 0.01, "rtl x: {}", r_rtl.x);
    }

    #[test]
    fn fit_none_draws_at_natural_pixel_size() {
        let icon = RasterIcon::from_raw(vec![255; 20 * 20 * 4], 20, 20);
        let widget = ImageWidget::new(&icon).fit(ImageFit::None);
        // In a 8×8 box the natural 20×20 image overflows; rect stays 20×20.
        let r = widget.fitted_rect(Rect::new(0.0, 0.0, 8.0, 8.0), false);
        assert!((r.width - 20.0).abs() < 0.01);
        assert!((r.height - 20.0).abs() < 0.01);
        // Centered → negative offset (overflows on all sides).
        assert!((r.x - (-6.0)).abs() < 0.01, "x: {}", r.x); // (8-20)/2
    }

    #[test]
    fn cover_overflow_is_clipped_to_bounds() {
        // A 2:1 image covering a square box overflows horizontally and must
        // be clipped — the frame should carry a SetClip/ClearClip pair.
        let icon = RasterIcon::from_raw(vec![255; 20 * 10 * 4], 20, 10);
        let mut tree = WidgetTree::new();
        tree.add(
            ImageWidget::new(&icon)
                .size(50.0, 50.0)
                .fit(ImageFit::Cover),
        );
        tree.layout(SizeProposal::exact(50.0, 50.0));
        let frame = tree.render();
        let has_set_clip = frame
            .draw_order
            .iter()
            .any(|c| matches!(c, teksilo_canvas::DrawCommand::SetClip(_)));
        let has_clear_clip = frame
            .draw_order
            .iter()
            .any(|c| matches!(c, teksilo_canvas::DrawCommand::ClearClip));
        assert!(has_set_clip, "Cover overflow should emit SetClip");
        assert!(has_clear_clip, "Cover overflow should emit ClearClip");
    }

    #[test]
    fn contain_within_box_emits_no_clip() {
        // Contain never overflows, so no clip commands are emitted.
        let icon = RasterIcon::from_raw(vec![255; 10 * 10 * 4], 10, 10);
        let mut tree = WidgetTree::new();
        tree.add(
            ImageWidget::new(&icon)
                .size(50.0, 50.0)
                .fit(ImageFit::Contain),
        );
        tree.layout(SizeProposal::exact(50.0, 50.0));
        let frame = tree.render();
        let has_set_clip = frame
            .draw_order
            .iter()
            .any(|c| matches!(c, teksilo_canvas::DrawCommand::SetClip(_)));
        assert!(!has_set_clip, "Contain should not clip");
    }

    #[test]
    fn mask_circle_alpha_zero_at_corners() {
        // The reusable `.mask(Circle)` modifier — anywhere a photo
        // needs a circular crop, not just inside Avatar.
        let icon = RasterIcon::from_raw(vec![255; 32 * 32 * 4], 32, 32);
        let widget = ImageWidget::from_raw(icon.pixels().to_vec(), icon.width(), icon.height())
            .mask(ImageMaskShape::Circle);
        // After cropping to a square (already 32×32 here) and
        // masking, corner pixels have alpha 0.
        let stride = (widget.width * 4) as usize;
        let pixels = widget.pending_pixels().expect("masked pixels");
        let top_left_alpha = pixels[3];
        let top_right_alpha = pixels[stride - 1];
        assert_eq!(top_left_alpha, 0);
        assert_eq!(top_right_alpha, 0);
        // Centre pixel still opaque.
        let center_idx = (((widget.height / 2) * widget.width + widget.width / 2) * 4 + 3) as usize;
        assert_eq!(pixels[center_idx], 255);
    }

    #[test]
    fn mask_none_is_passthrough() {
        let original = vec![123, 45, 67, 200, 8, 9, 10, 200];
        let widget = ImageWidget::from_raw(original.clone(), 2, 1).mask(ImageMaskShape::None);
        assert_eq!(widget.pending_pixels(), Some(original.as_slice()));
        // And an unmasked icon stays on the shared path.
        let icon = RasterIcon::from_raw(original.clone(), 2, 1);
        assert!(
            ImageWidget::new(&icon)
                .mask(ImageMaskShape::None)
                .shared_name()
                .is_some()
        );
    }

    #[test]
    fn mask_crops_non_square_to_square() {
        // 8×4 source → centre-cropped to 4×4 inscribed circle.
        let pixels = vec![255; 8 * 4 * 4];
        let widget = ImageWidget::from_raw(pixels, 8, 4).mask(ImageMaskShape::Circle);
        assert_eq!(widget.width, 4);
        assert_eq!(widget.height, 4);
    }

    #[test]
    fn a_masked_icon_owns_its_pixels_and_leaves_the_shared_texture() {
        // The masked widget must not draw through the icon's shared
        // texture, which holds the unmasked pixels.
        let icon = RasterIcon::from_raw(vec![255; 16 * 16 * 4], 16, 16);
        let unmasked = ImageWidget::new(&icon);
        let masked = ImageWidget::new(&icon).mask(ImageMaskShape::Circle);
        assert!(unmasked.shared_name().is_some());
        assert!(masked.shared_name().is_none());
        assert!(masked.pending_pixels().is_some());
    }
}