rust_widgets 2.9.2

// SPDX-FileCopyrightText: Copyright (c) 2026 Mike Li/Mikewolfli/Wei Li(mikewolfli@163.com)
// SPDX-License-Identifier: MIT

//! CameraPreview widget — self-drawn simulated camera viewfinder preview.
//!
//! This is a simulated preview component: it never opens or reads from a real
//! camera device. It draws a stylized viewfinder (resolution label, camera id,
//! zoom/mirror indicators, crosshair, control overlay) and manages a local
//! active state. There is no video feed behind the widget; all visuals are
//! generated by the widget itself.

use alloc::sync::Arc;

use crate::core::{Color, HorizontalAlignment, Point, Rect};
use crate::event::{Event, EventHandler};
use crate::impl_widget_property_hooks;
use crate::property_names_of;
use crate::render::RenderContext;
use crate::signal::{GenericSignal, Signal1};
use crate::widget::capability::coercion::{expect_bool, expect_string};
use crate::widget::capability::properties_trait::{base_property_get, base_property_set};
use crate::widget::capability::types::{CapabilityAccessError, CapabilityValue};
use crate::widget::capability::WidgetProperties;
use crate::widget::metrics::role_font;
use crate::widget::{BaseWidget, Draw, Widget, WidgetKind};

/// The inactive viewfinder's fill.
///
/// The off-state viewport is the placeholder for a video surface, so it is a near-black that
/// does not follow the appearance — that is the `video-surface` exemption's subject. It is a
/// named constant because the "Camera Off" label is chrome drawn on it and must stay legible
/// against it, so both must read the same value.
const EMPTY_VIEWFINDER: Color = Color::rgba(50, 50, 60, 255);

/// The active viewfinder's fill, used when neither the style nor the theme names one.
///
/// A camera feed is judged against a neutral dark ground in every camera application, so the
/// stage keeps this cave-dark default rather than following the appearance. What *does* follow is
/// the ink drawn on it: the overlay labels are derived from whatever stage is painted, so a host
/// that sets a light stage through the style still gets legible annotation. It is a named
/// constant for the same reason as [`EMPTY_VIEWFINDER`] — the stage and its fallback must be one
/// value, not two that can drift.
const ACTIVE_VIEWFINDER: Color = Color::rgba(30, 30, 40, 255);

/// A frame that needed repacking, cropping or mirroring, kept between draws.
///
/// The key is the input buffer's identity plus the transform inputs. A new capture has a new
/// pointer, so only an unchanged frame reuses this buffer (L-P06).
struct ProcessedFrame {
    ptr: usize,
    len: usize,
    width: u32,
    height: u32,
    stride: u32,
    mirror: bool,
    zoom_bits: u32,
    data: Vec<u8>,
}

/// A camera device the host has made available.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CameraDevice {
    /// Device identifier passed back to [`CameraPreview::set_camera_id`].
    pub id: u32,
    /// Human-readable name shown to a user.
    pub label: String,
    /// Resolutions the device offers, as `(width, height)` pairs.
    pub resolutions: Vec<(u32, u32)>,
}

impl CameraDevice {
    /// A device with an id and a label.
    pub fn new(id: u32, label: impl Into<String>) -> Self {
        Self { id, label: label.into(), resolutions: Vec::new() }
    }
}

/// Pixel layout a capture device negotiated.
///
/// Only [`PixelFormat::Rgba8888`] is accepted by [`CameraPreview::set_frame`]: the control paints
/// RGBA bytes and does no colour conversion, so claiming to accept a packed YUV layout it cannot
/// convert would make a host hand it bytes that then drew as noise.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum PixelFormat {
    /// Tightly packed RGBA, 4 bytes per pixel.
    #[default]
    Rgba8888,
    /// Tightly packed BGRA, 4 bytes per pixel.
    Bgra8888,
    /// Semi-planar YUV 4:2:0.
    Nv12,
    /// Packed YUV 4:2:2.
    Yuy2,
}

/// A decoded camera frame supplied by the host.
///
/// The data is row-major in [`Self::format`] with `stride` bytes per row. A stride larger than
/// `width * 4` is allowed for a capture pipeline that pads rows. The widget never captures or
/// decodes anything itself; it paints what the host hands it. The buffer is shared rather than
/// copied: [`CameraPreview::set_frame_shared`] adopts an `Arc` with no pixel copy, so a host
/// double-buffering its capture does not pay a per-frame 640x480x4 copy on the UI thread.
#[derive(Debug, Clone)]
pub struct CameraFrame {
    /// Frame width in pixels.
    pub width: u32,
    /// Frame height in pixels.
    pub height: u32,
    /// Capture timestamp in milliseconds.
    pub pts_ms: u64,
    /// Pixel layout of `data`.
    pub format: PixelFormat,
    /// Bytes per row, including any padding. Must be at least `width * 4`.
    pub stride: u32,
    /// Pixel bytes, `stride * height` long.
    pub data: Arc<[u8]>,
}

impl CameraFrame {
    /// A tightly packed RGBA frame over a shared buffer.
    pub fn new(width: u32, height: u32, pts_ms: u64, data: Arc<[u8]>) -> Self {
        Self::from_shared(
            width,
            height,
            pts_ms,
            PixelFormat::Rgba8888,
            width.saturating_mul(4),
            data,
        )
    }

    /// A frame with an explicit layout over a shared buffer, with no pixel copy.
    pub fn from_shared(
        width: u32,
        height: u32,
        pts_ms: u64,
        format: PixelFormat,
        stride: u32,
        data: Arc<[u8]>,
    ) -> Self {
        Self { width, height, pts_ms, format, stride, data }
    }

    /// The byte length this frame requires for `height` rows at its declared stride.
    pub fn expected_len(&self) -> usize {
        self.stride as usize * self.height as usize
    }
}

/// Camera preview widget — draws a simulated camera viewfinder area with controls.
///
/// Renders a self-drawn camera viewfinder and optional control overlay buttons.
/// Zoom, mirror/flip and preview start/stop only change local widget state and
/// redrawing; no real camera device is opened and no frames are captured.
pub struct CameraPreview {
    base: BaseWidget,
    /// Whether the camera preview is currently active.
    is_active: bool,
    /// Camera resolution as (width, height).
    resolution: (u32, u32),
    /// Camera device identifier.
    camera_id: u32,
    /// Whether the preview is mirrored (horizontally flipped).
    mirror_mode: bool,
    /// Whether control buttons are shown overlaid on the preview.
    show_controls: bool,
    /// Current zoom level (1.0 = normal).
    zoom_level: f32,
    /// The frame waiting for [`Self::present_frame`].
    back: Option<Arc<CameraFrame>>,
    /// The frame currently shown in the viewfinder.
    front: Option<Arc<CameraFrame>>,
    /// Emitted when the host reports a capture failure.
    pub error_occurred: Signal1<String>,
    /// Emitted when the host reports that camera permission was denied.
    pub permission_denied: GenericSignal,
    /// Emitted with the capture timestamp when the host delivers a frame.
    pub frame_available: Signal1<u64>,
    /// Emitted with the presented timestamp **in seconds** when a frame is swapped on screen.
    pub frame_presented: Signal1<f64>,
    /// Devices the host has enumerated.
    available_cameras: Vec<CameraDevice>,
    /// Pixel layout the capture device negotiated.
    pixel_format: PixelFormat,
    /// Requested capture rate in frames per second.
    target_fps: u32,
    /// Emitted when the negotiated format (or resolution) changes, as `(width, height)`.
    ///
    /// The resolution is the format pin both the readout and the painted frame share; a caller that
    /// also needs the pixel layout reads [`Self::pixel_format`].
    pub format_negotiated: Signal1<(u32, u32)>,
    /// The `WxH` readout, rebuilt when the resolution changes rather than every draw.
    resolution_text: String,
    /// The device caption, rebuilt when the camera id changes.
    camera_id_text: String,
    /// The zoom caption, rebuilt when the zoom level changes.
    zoom_text: String,
    /// The repacked/mirrored/cropped frame from the previous draw.
    processed: Option<ProcessedFrame>,
}

impl CameraPreview {
    /// Creates a new CameraPreview widget with the given geometry.
    pub fn new(geometry: Rect) -> Self {
        Self {
            base: BaseWidget::new(WidgetKind::CameraPreview, geometry, "CameraPreview"),
            is_active: false,
            resolution: (640, 480),
            camera_id: 0,
            mirror_mode: false,
            show_controls: true,
            zoom_level: 1.0,
            back: None,
            front: None,
            error_occurred: Signal1::new(),
            permission_denied: GenericSignal::new(),
            frame_available: Signal1::new(),
            frame_presented: Signal1::new(),
            available_cameras: Vec::new(),
            pixel_format: PixelFormat::Rgba8888,
            target_fps: 30,
            format_negotiated: Signal1::new(),
            resolution_text: "640x480".to_string(),
            camera_id_text: "Camera #0".to_string(),
            zoom_text: "1.0x".to_string(),
            processed: None,
        }
    }

    /// Starts the simulated camera preview.
    ///
    /// Only flips the local active flag and requests a redraw. No camera device
    /// is opened and no frames are captured; the "preview" shown is drawn by
    /// this widget itself.
    pub fn start_preview(&mut self) {
        self.is_active = true;
        self.base.request_redraw();
    }

    /// Stops the simulated camera preview (local state and redraw only).
    pub fn stop_preview(&mut self) {
        self.is_active = false;
        self.base.request_redraw();
    }

    /// Returns whether the camera preview is active.
    pub fn is_active(&self) -> bool {
        self.is_active
    }

    /// Toggles the simulated preview on/off (local state only).
    pub fn toggle_preview(&mut self) {
        if self.is_active {
            self.stop_preview();
        } else {
            self.start_preview();
        }
    }

    /// Sets the camera device identifier shown in the preview overlay.
    ///
    /// When the host has enumerated devices with [`Self::set_available_cameras`], the id is checked
    /// against that list: an unknown id leaves the current selection untouched, reports an error
    /// and returns `Err`, so a host can show "camera unavailable" instead of a preview labelled
    /// with a device that does not exist. With no enumeration the id is accepted as a label, which
    /// keeps the control usable before a host has discovered anything.
    pub fn set_camera_id(&mut self, id: u32) -> Result<(), String> {
        if !self.available_cameras.is_empty()
            && !self.available_cameras.iter().any(|device| device.id == id)
        {
            let message = format!("camera {id} is not among the enumerated devices");
            self.error_occurred.emit(message.clone());
            return Err(message);
        }
        if self.camera_id == id {
            return Ok(());
        }
        self.camera_id = id;
        self.camera_id_text = format!("Camera #{id}");
        // `draw` labels the preview with the device it shows, so the caption goes stale without
        // this.
        self.base.request_redraw();
        Ok(())
    }

    /// Replaces the host-enumerated camera list.
    pub fn set_available_cameras(&mut self, devices: Vec<CameraDevice>) {
        self.available_cameras = devices;
        self.base.request_redraw();
    }

    /// The devices the host has enumerated.
    pub fn available_cameras(&self) -> &[CameraDevice] {
        &self.available_cameras
    }

    /// The negotiated pixel layout.
    pub fn pixel_format(&self) -> PixelFormat {
        self.pixel_format
    }

    /// Records the negotiated pixel layout and announces it.
    ///
    /// This is the result of the host's format negotiation, not a request: the control does no
    /// conversion, so a non-RGBA layout only describes what the capture device is producing.
    pub fn set_pixel_format(&mut self, format: PixelFormat) {
        if self.pixel_format == format {
            return;
        }
        self.pixel_format = format;
        self.announce_format();
        self.base.request_redraw();
    }

    /// The requested capture rate in frames per second.
    pub fn target_fps(&self) -> u32 {
        self.target_fps
    }

    /// Sets the requested capture rate. Zero is raised to one.
    pub fn set_target_fps(&mut self, fps: u32) {
        let fps = fps.max(1);
        if self.target_fps == fps {
            return;
        }
        self.target_fps = fps;
        self.announce_format();
        self.base.request_redraw();
    }

    /// Announces `(width, height)` as the negotiated format.
    fn announce_format(&mut self) {
        self.format_negotiated.emit(self.resolution);
    }

    /// Returns the current camera device ID.
    pub fn camera_id(&self) -> u32 {
        self.camera_id
    }

    /// Sets the resolution label used by the simulated preview.
    ///
    /// Used for the on-screen "WxH" text; no capture pipeline exists.
    pub fn set_resolution(&mut self, w: u32, h: u32) {
        let resolution = (w.max(1), h.max(1));
        if self.resolution == resolution {
            return;
        }
        self.resolution = resolution;
        self.resolution_text = format!("{}x{}", resolution.0, resolution.1);
        self.processed = None;
        self.announce_format();
        self.base.request_redraw();
    }

    /// Returns the current camera resolution.
    pub fn resolution(&self) -> (u32, u32) {
        self.resolution
    }

    /// Enables or disables mirror mode (horizontal flip).
    pub fn set_mirror_mode(&mut self, mirrored: bool) {
        if self.mirror_mode == mirrored {
            return;
        }
        self.mirror_mode = mirrored;
        self.processed = None;
        self.base.request_redraw();
    }

    /// Returns whether mirror mode is enabled.
    pub fn is_mirror_mode(&self) -> bool {
        self.mirror_mode
    }

    /// Sets the zoom level (1.0 = normal, 2.0 = 2x, etc.).
    pub fn set_zoom(&mut self, level: f32) {
        let level = level.clamp(1.0, 10.0);
        if self.zoom_level == level {
            return;
        }
        self.zoom_level = level;
        self.zoom_text = format!("{level:.1}x");
        self.processed = None;
        self.base.request_redraw();
    }

    /// Supplies a decoded RGBA frame for the viewfinder.
    ///
    /// The frame's own dimensions become the preview's resolution, which is what makes
    /// [`Self::set_resolution`] a *format negotiation* rather than a label: the picture and the
    /// readout name the same size because both come from the frame that is on screen. Returns
    /// `Err` when the dimensions are empty or the byte count is not `width * height * 4`.
    pub fn set_frame(&mut self, width: u32, height: u32, data: &[u8]) -> Result<(), String> {
        let result = self.set_frame_bytes_shared(width, height, 0, Arc::from(data));
        if let Err(error) = &result {
            self.error_occurred.emit(error.clone());
        }
        result
    }

    /// Supplies a frame from a shared byte buffer, with no pixel copy.
    ///
    /// The buffer must hold `width * height * 4` RGBA bytes; the length is checked against the
    /// shared slice, not copied. Use [`Self::set_frame_shared`] when the caller already owns a
    /// whole [`CameraFrame`], which also carries the layout.
    pub fn set_frame_bytes_shared(
        &mut self,
        width: u32,
        height: u32,
        pts_ms: u64,
        data: Arc<[u8]>,
    ) -> Result<(), String> {
        self.set_frame_shared_with_format(
            width,
            height,
            pts_ms,
            self.pixel_format,
            width.saturating_mul(4),
            data,
        )
    }

    /// Adopts a whole [`CameraFrame`] through its existing `Arc`, with no pixel copy.
    ///
    /// This is the zero-copy contract a capture thread needs: it owns the frames, the UI thread
    /// validates the shared handle and stores that same allocation in the back slot. The frame's
    /// declared `format` and `stride` are honoured exactly as in
    /// [`Self::set_frame_shared_with_format`].
    pub fn set_frame_shared(&mut self, frame: Arc<CameraFrame>) -> Result<(), String> {
        self.validate_frame(&frame)?;
        self.publish_frame(frame);
        Ok(())
    }

    /// Checks a frame's layout and byte count without copying its pixels.
    fn validate_frame(&self, frame: &CameraFrame) -> Result<(), String> {
        if frame.width == 0 || frame.height == 0 {
            return Err("a camera frame needs non-zero dimensions".to_string());
        }
        if self.pixel_format != PixelFormat::Rgba8888 || frame.format != PixelFormat::Rgba8888 {
            return Err(format!(
                "the negotiated {:?} layout cannot be painted; this control accepts RGBA8888 frames",
                frame.format
            ));
        }
        let minimum = frame.width as usize * 4;
        if (frame.stride as usize) < minimum {
            return Err(format!(
                "a {}x{} RGBA frame needs a stride of at least {minimum} bytes, got {}",
                frame.width, frame.height, frame.stride
            ));
        }
        let expected = frame.expected_len();
        if frame.data.len() != expected {
            return Err(format!(
                "a {}x{} RGBA frame at stride {} needs {expected} bytes, got {}",
                frame.width,
                frame.height,
                frame.stride,
                frame.data.len()
            ));
        }
        Ok(())
    }

    /// Stores a validated frame in the back slot and announces it.
    fn publish_frame(&mut self, frame: Arc<CameraFrame>) {
        // Back slot, not front: a painter reading the front frame must never observe a partially
        // published capture. `present_frame` performs the swap.
        let resolution = (frame.width, frame.height);
        let negotiated = self.resolution != resolution;
        self.resolution = resolution;
        self.resolution_text = format!("{}x{}", resolution.0, resolution.1);
        self.processed = None;
        self.frame_available.emit(frame.pts_ms);
        self.back = Some(frame);
        if negotiated {
            self.announce_format();
        }
        self.base.request_redraw();
    }

    /// Supplies a frame with an explicit pixel layout and row stride.
    ///
    /// The capture-device entry point: a pipeline that pads rows (a 640-wide BGRA frame aligned
    /// to 64 bytes, say) declares its own `stride` here instead of repacking. `format` must match
    /// the negotiated [`Self::pixel_format`] and be one this control can paint; the row stride must
    /// be at least `width * 4` and the buffer exactly `stride * height` bytes.
    pub fn set_frame_shared_with_format(
        &mut self,
        width: u32,
        height: u32,
        pts_ms: u64,
        format: PixelFormat,
        stride: u32,
        data: Arc<[u8]>,
    ) -> Result<(), String> {
        let frame = Arc::new(CameraFrame::from_shared(width, height, pts_ms, format, stride, data));
        self.validate_frame(&frame)?;
        self.publish_frame(frame);
        Ok(())
    }

    /// Swaps the waiting frame into the viewfinder and announces it as `frame_presented`.
    ///
    /// Returns `false` when no new frame is waiting. The explicit swap is what makes the two
    /// slots meaningful: a capture thread can publish frame N+1 while the painter is still
    /// reading frame N, and the next present changes what is on screen without copying pixels.
    pub fn present_frame(&mut self) -> bool {
        let Some(frame) = self.back.take() else {
            return false;
        };
        let pts = frame.pts_ms;
        self.front = Some(frame);
        self.frame_presented.emit(pts as f64 / 1000.0);
        self.base.request_redraw();
        true
    }

    /// Removes the host frame, returning the viewfinder to its simulated drawing.
    pub fn clear_frame(&mut self) {
        self.front = None;
        self.back = None;
        self.processed = None;
        self.base.request_redraw();
    }

    /// Returns the frame currently shown in the viewfinder, if any.
    pub fn frame(&self) -> Option<&CameraFrame> {
        self.front.as_deref()
    }

    /// Returns the frame waiting for the next [`Self::present_frame`], if any.
    pub fn pending_frame(&self) -> Option<&CameraFrame> {
        self.back.as_deref()
    }

    /// Reports a capture failure to the host's listeners.
    pub fn report_error(&mut self, message: impl Into<String>) {
        self.error_occurred.emit(message.into());
    }

    /// Reports that camera permission was denied, which is its own state rather than a
    /// generic error: a host normally shows different remediation for the two.
    pub fn report_permission_denied(&mut self) {
        self.permission_denied.emit();
    }

    /// Returns the current zoom level.
    pub fn zoom_level(&self) -> f32 {
        self.zoom_level
    }

    /// Zooms in by one step.
    pub fn zoom_in(&mut self) {
        self.set_zoom(self.zoom_level + 0.5);
    }

    /// Zooms out by one step.
    pub fn zoom_out(&mut self) {
        self.set_zoom(self.zoom_level - 0.5);
    }

    /// Makes the control overlay visible.
    pub fn show_controls(&mut self) {
        self.show_controls = true;
        self.base.request_redraw();
    }

    /// Hides the control overlay.
    pub fn hide_controls(&mut self) {
        self.show_controls = false;
        self.base.request_redraw();
    }

    /// Returns whether controls are currently visible.
    pub fn controls_visible(&self) -> bool {
        self.show_controls
    }

    /// The zoom-in button's rectangle, shared by the paint path and the hit test.
    fn zoom_in_rect(&self, rect: Rect) -> Rect {
        Rect::new(rect.x + rect.width as i32 - 42, rect.y + 6, 36, 36)
    }

    /// The zoom-out button's rectangle, shared by the paint path and the hit test.
    fn zoom_out_rect(&self, rect: Rect) -> Rect {
        Rect::new(rect.x + rect.width as i32 - 42, rect.y + 46, 36, 36)
    }

    /// Repacks, crops and mirrors the frame when the current transform needs it.
    ///
    /// Returns whether [`Self::processed`] holds the pixels to paint. A tightly packed frame at
    /// 1.0x with mirroring off is the fast path and needs no buffer at all. The result is cached
    /// by buffer identity and transform inputs, so the steady state -- a still frame at a fixed
    /// zoom -- does no pixel work (L-P06).
    fn ensure_processed(&mut self, frame: &CameraFrame) -> bool {
        let tight = frame.width as usize * 4;
        let identity = !self.mirror_mode
            && (self.zoom_level - 1.0).abs() < f32::EPSILON
            && frame.stride as usize == tight;
        if identity {
            return false;
        }
        let ptr = frame.data.as_ptr() as usize;
        let len = frame.data.len();
        let zoom_bits = self.zoom_level.to_bits();
        let reusable = matches!(
            self.processed.as_ref(),
            Some(cached)
                if cached.ptr == ptr
                    && cached.len == len
                    && cached.width == frame.width
                    && cached.height == frame.height
                    && cached.stride == frame.stride
                    && cached.mirror == self.mirror_mode
                    && cached.zoom_bits == zoom_bits
        );
        if reusable {
            return true;
        }

        let width = frame.width;
        let height = frame.height;
        let zoom = self.zoom_level.max(1.0) as f64;
        let crop_width = ((width as f64 / zoom).round() as u32).clamp(1, width.max(1));
        let crop_height = ((height as f64 / zoom).round() as u32).clamp(1, height.max(1));
        let crop_x = (width.saturating_sub(crop_width)) / 2;
        let crop_y = (height.saturating_sub(crop_height)) / 2;
        let mut data = crate::compat::vec![0u8; tight * height as usize];
        for row in 0..height {
            let source_y = crop_y + (row as u64 * crop_height as u64 / height.max(1) as u64) as u32;
            let source_row = source_y as usize * frame.stride as usize;
            for column in 0..width {
                let inner = (column as u64 * crop_width as u64 / width.max(1) as u64) as u32;
                let source_x = if self.mirror_mode {
                    crop_x + crop_width.saturating_sub(1).saturating_sub(inner)
                } else {
                    crop_x + inner
                };
                let from = source_row + source_x as usize * 4;
                let to = row as usize * tight + column as usize * 4;
                if let Some(pixel) = frame.data.get(from..from + 4) {
                    data[to..to + 4].copy_from_slice(pixel);
                }
            }
        }
        self.processed = Some(ProcessedFrame {
            ptr,
            len,
            width,
            height,
            stride: frame.stride,
            mirror: self.mirror_mode,
            zoom_bits,
            data,
        });
        true
    }
}

impl Widget for CameraPreview {
    fn base(&self) -> &BaseWidget {
        &self.base
    }
    fn set_state_theme_hook(&mut self) {
        crate::style::reapply_active_theme_state(self);
    }
    fn base_mut(&mut self) -> &mut BaseWidget {
        &mut self.base
    }

    fn size_hint(&self) -> crate::core::Size {
        crate::core::Size::new(320, 240)
    }

    /// Reports this widget as the object that paints it.
    ///
    /// `CameraPreview` implements `Draw`, so `Some(self)` is total and cannot be
    /// wrong.
    fn as_draw_mut(&mut self) -> Option<&mut dyn crate::widget::Draw> {
        Some(self)
    }

    /// Resolves a published event name to the signal this widget actually emits.
    ///
    /// `error_occurred` carries the host's message as a `String`, the same shape
    /// the capability declares. `permission_denied` is a unit signal and is
    /// reported as `Null`, which is the honest value for an event that reports
    /// nothing beyond the fact that it happened.
    fn event_signal_dyn(&self, name: &str) -> Option<crate::signal::EventSignalRef> {
        use crate::signal::EventSignalRef;
        match name {
            "error_occurred" => {
                Some(EventSignalRef::mapped("error_occurred", &self.error_occurred, |v| {
                    CapabilityValue::String(v.clone())
                }))
            }
            "permission_denied" => {
                Some(EventSignalRef::unit("permission_denied", &self.permission_denied))
            }
            "frame_available" => {
                Some(EventSignalRef::mapped("frame_available", &self.frame_available, |v| {
                    CapabilityValue::UInt(*v)
                }))
            }
            "frame_presented" => {
                Some(EventSignalRef::mapped("frame_presented", &self.frame_presented, |v| {
                    CapabilityValue::Float(*v)
                }))
            }
            "format_negotiated" => Some(EventSignalRef::mapped(
                "format_negotiated",
                &self.format_negotiated,
                |(width, height)| {
                    CapabilityValue::Tuple(crate::compat::Vec::from([
                        CapabilityValue::UInt(*width as u64),
                        CapabilityValue::UInt(*height as u64),
                    ]))
                },
            )),
            _ => None,
        }
    }

    impl_widget_property_hooks!();
}

/// `CameraPreview`'s property contract.
///
/// Read/write semantics are carried over unchanged from the centralised
/// `access_read_media.in.rs` / `access_write_media.in.rs` dispatch: `is_active`
/// maps onto `start_preview` / `stop_preview`.
impl WidgetProperties for CameraPreview {
    fn get(&self, name: &str) -> Result<CapabilityValue, CapabilityAccessError> {
        match name {
            "is_active" => Ok(CapabilityValue::Bool(self.is_active())),
            "pixel_format" => Ok(CapabilityValue::String(format!("{:?}", self.pixel_format()))),
            "target_fps" => Ok(CapabilityValue::UInt(self.target_fps() as u64)),
            "camera_id" => Ok(CapabilityValue::UInt(self.camera_id() as u64)),
            _ => base_property_get(self, name),
        }
    }

    fn set(&mut self, name: &str, value: CapabilityValue) -> Result<(), CapabilityAccessError> {
        match name {
            "is_active" => {
                if expect_bool(value)? {
                    self.start_preview();
                } else {
                    self.stop_preview();
                }
                Ok(())
            }
            "pixel_format" => {
                let format = match expect_string(value)?.to_ascii_lowercase().as_str() {
                    "rgba8888" | "rgba" => PixelFormat::Rgba8888,
                    "bgra8888" | "bgra" => PixelFormat::Bgra8888,
                    "nv12" => PixelFormat::Nv12,
                    "yuy2" => PixelFormat::Yuy2,
                    _ => return Err(CapabilityAccessError::TypeMismatch),
                };
                self.set_pixel_format(format);
                Ok(())
            }
            "target_fps" => {
                let fps = match value {
                    CapabilityValue::UInt(fps) => fps.min(u32::MAX as u64) as u32,
                    _ => return Err(CapabilityAccessError::TypeMismatch),
                };
                self.set_target_fps(fps);
                Ok(())
            }
            "camera_id" => {
                let id = match value {
                    CapabilityValue::UInt(id) => id.min(u32::MAX as u64) as u32,
                    _ => return Err(CapabilityAccessError::TypeMismatch),
                };
                self.set_camera_id(id).map_err(|_| CapabilityAccessError::OutOfRange)
            }
            _ => base_property_set(self, name, value),
        }
    }

    fn property_names(&self) -> &'static [&'static str] {
        property_names_of![
            "is_active",
            "pixel_format",
            "target_fps",
            "camera_id",
            BASE_PROPERTY_NAMES
        ]
    }
}

impl Draw for CameraPreview {
    fn draw(&mut self, context: &mut RenderContext) {
        let rect = self.geometry();
        let w = rect.width as i32;
        let h = rect.height as i32;

        if w <= 0 || h <= 0 {
            return;
        }

        // ── Viewfinder chrome ────────────────────────────────────────────
        //
        // The overlay ink and the viewfinder fill are **chrome**: a resolution readout, a camera
        // id, a zoom label and a crosshair are annotations *about* the picture, not the picture.
        // They were eight hardcoded `rgba(2xx,2xx,2xx)` values, so a light appearance produced
        // white-on-near-white labels — measured at **1.15:1**, i.e. invisible — with nothing
        // reported, and a theme switch moved nothing but the page behind them. This is the same
        // defect shape `image_gallery`'s stage overlay had.
        //
        // The active viewfinder stays dark on purpose: a camera feed is judged against a neutral
        // dark ground, and every camera app does this. So the *stage* keeps its dark default,
        // while the ink on it is derived from that stage — which is what keeps the escape hatch
        // the old literals were reaching for (a light stage still gets legible ink) without the
        // theme being unable to move anything.
        let style = self.base.style();
        // The overlay text uses the control's **role fonts**, so the theme face and the user's
        // text scale reach it. They were `Font::new("sans-serif", …)` built before the style
        // was even read.
        let small_font = role_font(style, 11.0);
        let normal_font = role_font(style, 13.0);
        let theme = crate::style::resolved_theme_style_shared("camera_preview");
        // A host that gave the control an explicit colour wins; otherwise the dark stage default.
        let viewfinder = style
            .background_color
            .or_else(|| theme.as_ref().and_then(|t| t.background_color))
            .unwrap_or(ACTIVE_VIEWFINDER);
        // One step from the stage toward its own contrast colour, so the overlay is legible on
        // whatever stage is painted. On the default stage this is the old near-white.
        let stage_ink = viewfinder.contrast_color();
        let label_ink = viewfinder.blend(&stage_ink, 0.78);
        let strong_ink = viewfinder.blend(&stage_ink, 0.86);
        let crosshair_ink = viewfinder.blend(&stage_ink, 0.55);

        if self.is_active {
            // Draw active camera view — dark viewfinder area
            context.fill_rect(rect, viewfinder);

            // The host's frame is painted at its own pixel size, centred and clipped to the
            // preview. Content, not chrome: it is the caller's picture and is never recoloured.
            // Mirroring and zoom are pixel operations (not labels), and the repacked result is
            // cached between draws (MW-03 / L-P06).
            if let Some(frame) = self.front.clone() {
                let dx = rect.x + (w - frame.width as i32) / 2;
                let dy = rect.y + (h - frame.height as i32) / 2;
                context.push_clip(rect.x, rect.y, rect.width, rect.height);
                let needs_processing = self.ensure_processed(&frame);
                let pixels: &[u8] = match self.processed.as_ref() {
                    Some(processed) if needs_processing => &processed.data,
                    _ => frame.data.as_ref(),
                };
                context.draw_image(dx.max(0), dy.max(0), frame.width, frame.height, pixels);
                context.pop_clip();
            }

            // Draw resolution info text. The captions are cached on their setters; this path
            // only borrows them (L-P03).
            context.draw_text(
                Point::new(rect.x + 6, rect.y + 14),
                &self.resolution_text,
                &small_font,
                label_ink,
                HorizontalAlignment::Left,
            );

            // Draw camera ID
            context.draw_text(
                Point::new(rect.x + 6, rect.y + h - 10),
                &self.camera_id_text,
                &small_font,
                label_ink,
                HorizontalAlignment::Left,
            );

            // Draw zoom level indicator
            context.draw_text(
                Point::new(rect.x + w - 40, rect.y + 14),
                &self.zoom_text,
                &normal_font,
                strong_ink,
                HorizontalAlignment::Left,
            );

            // Draw mirror indicator
            if self.mirror_mode {
                context.draw_text(
                    Point::new(rect.x + w / 2 - 20, rect.y + h - 10),
                    "MIRROR",
                    &small_font,
                    viewfinder.blend(&stage_ink, 0.68),
                    HorizontalAlignment::Left,
                );
            }

            // Draw a subtle crosshair
            let cx = rect.x + w / 2;
            let cy = rect.y + h / 2;
            let crosshair_color = crosshair_ink;
            context.draw_line(Point::new(cx, cy - 15), Point::new(cx, cy + 15), crosshair_color);
            context.draw_line(Point::new(cx - 15, cy), Point::new(cx + 15, cy), crosshair_color);

            // Draw border indicating active preview
            let border_color = Color::rgba(0, 200, 50, 200);
            context.draw_rect_stroke(rect, border_color, 2);

            // Draw control overlay if visible
            if self.show_controls {
                // Top-right corner controls background
                let control_bg = Rect::new(rect.x + w - 44, rect.y + 4, 40, 80);
                context.fill_rect(control_bg, Color::rgba(0, 0, 0, 120));

                // Draw zoom +/- buttons. The rectangles come from the same helpers the hit test
                // uses, so the visible button and its click target cannot drift apart (MW-03).
                let zoom_in_btn = self.zoom_in_rect(rect);
                context.fill_rect(zoom_in_btn, Color::rgba(255, 255, 255, 80));
                let zoom_out_btn = self.zoom_out_rect(rect);
                context.fill_rect(zoom_out_btn, Color::rgba(255, 255, 255, 80));
                let glyph_ink = strong_ink;
                let plus_center = zoom_in_btn.center();
                context.draw_line(
                    Point::new(plus_center.x - 7, plus_center.y),
                    Point::new(plus_center.x + 7, plus_center.y),
                    glyph_ink,
                );
                context.draw_line(
                    Point::new(plus_center.x, plus_center.y - 7),
                    Point::new(plus_center.x, plus_center.y + 7),
                    glyph_ink,
                );
                let minus_center = zoom_out_btn.center();
                context.draw_line(
                    Point::new(minus_center.x - 7, minus_center.y),
                    Point::new(minus_center.x + 7, minus_center.y),
                    glyph_ink,
                );
            }

            // Draw a green "recording" dot indicator
            let dot_size = 8;
            let dot_rect = Rect::new(rect.x + 6, rect.y + 6, dot_size, dot_size);
            context.fill_rect(dot_rect, Color::rgba(0, 255, 0, 255));
        } else {
            // Draw inactive camera view — dark gray with camera icon placeholder. The colour is
            // named because the label over it is derived from it, so the two cannot drift.
            context.fill_rect(rect, EMPTY_VIEWFINDER);

            // Draw a simple camera icon placeholder (rounded rectangle shape)
            let icon_w = 48u32;
            let icon_h = 36u32;
            let icon_x = rect.x + (w - icon_w as i32) / 2;
            let icon_y = rect.y + (h - icon_h as i32) / 2 - 10;
            let icon_rect = Rect::new(icon_x, icon_y, icon_w, icon_h);
            context.fill_rounded_rect(icon_rect, 6, Color::rgba(100, 100, 120, 200));

            // Lens circle
            let lens_center_x = icon_x + icon_w as i32 / 2;
            let lens_center_y = icon_y + icon_h as i32 / 2;
            let lens_rect = Rect::new(lens_center_x - 8, lens_center_y - 8, 16, 16);
            context.fill_rounded_rect(lens_rect, 8, Color::rgba(70, 70, 90, 255));

            // Flash dot
            let flash_rect = Rect::new(icon_x + icon_w as i32 - 10, icon_y + 4, 6, 6);
            context.fill_rounded_rect(flash_rect, 3, Color::rgba(200, 200, 200, 150));

            // "Camera Off" label. The viewport's near-black is the *content* placeholder — that
            // is what the `video-surface` exemption covers — but this label is chrome: it states
            // the state rather than being the frame, so it is held legible against the surface it
            // is painted on. The literal `rgba(150,150,160,200)` composited to `128,128,138` on
            // that `50,50,60` and measured 3.24:1, under the 4.5:1 body-text floor.
            let empty_surface = EMPTY_VIEWFINDER;
            context.draw_text(
                Point::new(rect.x + w / 2 - 30, rect.y + h / 2 + 20),
                "Camera Off",
                &normal_font,
                empty_surface.contrast_color().with_alpha(200),
                HorizontalAlignment::Left,
            );

            // Border
            context.draw_rect_stroke(rect, Color::rgba(100, 100, 110, 200), 1);
        }
    }
}

impl EventHandler for CameraPreview {
    fn handle_event(&mut self, event: &Event) {
        if !self.base.is_enabled() {
            return;
        }
        match event {
            Event::MousePress { pos, button, .. } => {
                if *button != 1 || !self.geometry().contains_point(*pos) {
                    return;
                }
                let rect = self.geometry();
                if self.show_controls {
                    if self.zoom_in_rect(rect).contains_point(*pos) {
                        self.zoom_in();
                        return;
                    }
                    if self.zoom_out_rect(rect).contains_point(*pos) {
                        self.zoom_out();
                        return;
                    }
                }
                // The press must land on the preview. Discarding the position meant a
                // click anywhere in the window started or stopped the camera -- a
                // side-effecting device action taken on an unrelated click.
                self.toggle_preview();
            }
            _ => {
                self.base.handle_event(event);
            }
        }
    }
}

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

    /// Both published names must resolve, and an unpublished one must not.
    #[test]
    fn published_camera_events_resolve_to_signals() {
        let preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        for name in [
            "error_occurred",
            "permission_denied",
            "frame_available",
            "frame_presented",
            "format_negotiated",
        ] {
            assert!(preview.event_signal_dyn(name).is_some(), "{name} must resolve");
        }
        assert!(preview.event_signal_dyn("no_such_event").is_none());
    }

    #[test]
    fn a_shared_frame_is_adopted_without_copying_and_announced() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        preview.start_preview();
        let seen = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(u64::MAX));
        let s = seen.clone();
        preview.frame_available.connect(move |pts: std::sync::Arc<u64>| {
            s.store(*pts, std::sync::atomic::Ordering::SeqCst);
        });
        let buffer: std::sync::Arc<[u8]> = std::sync::Arc::from(vec![7u8; 4 * 4 * 4]);
        let frame = std::sync::Arc::new(CameraFrame::new(4, 4, 33, std::sync::Arc::clone(&buffer)));
        let frame_handle = std::sync::Arc::clone(&frame);
        preview.set_frame_shared(frame_handle).expect("a matching shared frame is accepted");
        assert_eq!(seen.load(std::sync::atomic::Ordering::SeqCst), 33);
        assert!(preview.frame().is_none(), "a capture waits for an explicit present");
        assert!(preview.present_frame(), "the present swaps the waiting frame in");
        let stored = preview.frame().expect("the frame was stored");
        assert!(
            std::sync::Arc::ptr_eq(&stored.data, &buffer),
            "the control must store the host's handle, not a copy"
        );
        assert_eq!(stored.stride, 16);
        assert_eq!(stored.format, PixelFormat::Rgba8888);
    }

    #[test]
    fn adopting_a_whole_shared_frame_is_zero_copy() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        let data: std::sync::Arc<[u8]> = std::sync::Arc::from(vec![3u8; 4 * 4 * 4]);
        let frame = std::sync::Arc::new(CameraFrame::new(4, 4, 12, std::sync::Arc::clone(&data)));
        let handle = std::sync::Arc::clone(&frame);
        preview.set_frame_shared(handle).expect("a well-formed shared frame is adopted");
        assert_eq!(
            std::sync::Arc::strong_count(&frame),
            2,
            "the control stores the caller's frame handle, not a re-wrapped copy"
        );
        assert!(preview.present_frame());
        let stored = preview.frame().expect("the frame is on screen");
        assert!(std::sync::Arc::ptr_eq(&stored.data, &data));
        assert_eq!(stored.format, PixelFormat::Rgba8888);
        assert_eq!(stored.stride, 16);
    }

    #[test]
    fn presenting_swaps_the_back_slot_and_announces_seconds() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        preview.start_preview();
        let presented = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let p = std::sync::Arc::clone(&presented);
        preview.frame_presented.connect(move |pts: std::sync::Arc<f64>| {
            p.lock().unwrap().push(*pts);
        });

        let first: std::sync::Arc<[u8]> = std::sync::Arc::from(vec![1u8; 4 * 4 * 4]);
        preview
            .set_frame_shared(std::sync::Arc::new(CameraFrame::new(4, 4, 250, first)))
            .expect("the first frame is accepted");
        let second: std::sync::Arc<[u8]> = std::sync::Arc::from(vec![2u8; 4 * 4 * 4]);
        preview
            .set_frame_shared(std::sync::Arc::new(CameraFrame::new(4, 4, 500, second)))
            .expect("the second frame is accepted");

        assert!(preview.frame().is_none(), "nothing is on screen before the first present");
        assert_eq!(preview.pending_frame().map(|frame| frame.pts_ms), Some(500));
        assert!(preview.present_frame());
        assert_eq!(preview.frame().map(|frame| frame.pts_ms), Some(500));
        assert!(preview.pending_frame().is_none(), "the back slot is consumed by the swap");
        assert!(!preview.present_frame(), "a second present has nothing to swap");
        assert_eq!(*presented.lock().unwrap(), vec![0.5], "the signal carries seconds");
    }

    #[test]
    fn a_padded_stride_is_honoured() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        let stride = 32u32;
        let data: std::sync::Arc<[u8]> = std::sync::Arc::from(vec![0u8; stride as usize * 4]);
        preview
            .set_frame_shared_with_format(4, 4, 0, PixelFormat::Rgba8888, stride, data)
            .expect("a padded row stride is a valid layout");
        assert!(preview.present_frame());
        assert_eq!(preview.frame().map(|frame| frame.stride), Some(stride));
    }

    #[test]
    fn enumeration_and_format_negotiation_are_reported() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        let formats = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let f = formats.clone();
        preview.format_negotiated.connect(move |value: std::sync::Arc<(u32, u32)>| {
            f.lock().unwrap().push(*value);
        });
        preview.set_available_cameras(vec![CameraDevice::new(1, "Front")]);
        assert_eq!(preview.available_cameras().len(), 1);
        assert!(preview.set_camera_id(9).is_err(), "an unknown device is refused");
        assert_eq!(preview.camera_id(), 0, "a refused switch leaves the selection alone");
        preview.set_camera_id(1).expect("the enumerated device is accepted");
        assert_eq!(preview.camera_id(), 1);

        preview.set_pixel_format(PixelFormat::Bgra8888);
        preview.set_target_fps(60);
        assert!(!formats.lock().unwrap().is_empty(), "each negotiation is announced");
        assert_eq!(
            *formats.lock().unwrap().last().expect("a negotiation"),
            (640, 480),
            "the event carries the negotiated resolution"
        );
        let data = vec![0u8; 4 * 4 * 4];
        assert!(
            preview.set_frame(4, 4, &data).is_err(),
            "a layout the painter cannot interpret is refused rather than decoded as RGBA"
        );
    }

    #[test]
    fn camera_preview_default_state() {
        let cp = CameraPreview::new(Rect::new(0, 0, 320, 240));
        assert!(!cp.is_active());
        assert_eq!(cp.camera_id(), 0);
        assert_eq!(cp.resolution(), (640, 480));
        assert!(!cp.is_mirror_mode());
        assert!(cp.controls_visible());
        assert!((cp.zoom_level() - 1.0).abs() < f32::EPSILON);
        assert_eq!(cp.kind(), WidgetKind::CameraPreview);
    }

    #[test]
    fn camera_preview_toggle() {
        let mut cp = CameraPreview::new(Rect::new(0, 0, 320, 240));
        assert!(!cp.is_active());
        cp.start_preview();
        assert!(cp.is_active());
        cp.stop_preview();
        assert!(!cp.is_active());
        cp.toggle_preview();
        assert!(cp.is_active());
        cp.toggle_preview();
        assert!(!cp.is_active());
    }

    #[test]
    fn camera_preview_zoom() {
        let mut cp = CameraPreview::new(Rect::new(0, 0, 320, 240));
        assert!((cp.zoom_level() - 1.0).abs() < f32::EPSILON);
        cp.zoom_in();
        assert!((cp.zoom_level() - 1.5).abs() < f32::EPSILON);
        cp.zoom_in();
        assert!((cp.zoom_level() - 2.0).abs() < f32::EPSILON);
        cp.zoom_out();
        assert!((cp.zoom_level() - 1.5).abs() < f32::EPSILON);
        cp.set_zoom(5.0);
        assert!((cp.zoom_level() - 5.0).abs() < f32::EPSILON);
    }

    #[test]
    fn camera_preview_camera_id_and_resolution() {
        let mut cp = CameraPreview::new(Rect::new(0, 0, 320, 240));
        cp.set_camera_id(2).expect("with no enumeration any id is a label");
        assert_eq!(cp.camera_id(), 2);
        cp.set_resolution(1920, 1080);
        assert_eq!(cp.resolution(), (1920, 1080));
    }

    #[test]
    fn camera_preview_mirror_and_controls() {
        let mut cp = CameraPreview::new(Rect::new(0, 0, 320, 240));
        assert!(!cp.is_mirror_mode());
        cp.set_mirror_mode(true);
        assert!(cp.is_mirror_mode());
        assert!(cp.controls_visible());
        cp.hide_controls();
        assert!(!cp.controls_visible());
        cp.show_controls();
        assert!(cp.controls_visible());
    }

    #[test]
    fn camera_preview_click_toggles() {
        let mut cp = CameraPreview::new(Rect::new(0, 0, 320, 240));
        assert!(!cp.is_active());
        cp.handle_event(&Event::MousePress { pos: Point::new(10, 10), button: 1, modifiers: 0 });
        assert!(cp.is_active());
        cp.handle_event(&Event::MousePress { pos: Point::new(10, 10), button: 1, modifiers: 0 });
        assert!(!cp.is_active());
    }

    #[test]
    fn setting_the_camera_id_repaints() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 200, 200));
        let seen = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
        preview.base.redraw_requested.connect({
            let seen = std::sync::Arc::clone(&seen);
            move || {
                seen.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
            }
        });

        preview.set_camera_id(4).expect("no enumeration means the id is a label");
        assert_eq!(
            seen.load(std::sync::atomic::Ordering::SeqCst),
            1,
            "the caption names the device, so it is painted"
        );
        preview.set_camera_id(4).expect("the same label");
        assert_eq!(
            seen.load(std::sync::atomic::Ordering::SeqCst),
            1,
            "the same id is not a change"
        );
    }

    #[test]
    fn a_host_frame_negotiates_the_resolution_and_paints() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        preview.start_preview();
        let data = vec![200u8; 4 * 4 * 4];
        preview.set_frame(4, 4, &data).expect("a matching byte count is accepted");
        assert_eq!(preview.resolution(), (4, 4));
        assert!(preview.present_frame(), "the frame is swapped on screen");
        assert_eq!(preview.frame().map(|frame| frame.width), Some(4));
        let svg = crate::widget::svg::render_to_svg(&mut preview);
        assert!(svg.starts_with("<svg"));
    }

    #[test]
    fn a_malformed_frame_is_refused_rather_than_painted() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        assert!(preview.set_frame(2, 2, &[0u8; 8]).is_err());
        assert!(preview.frame().is_none());
    }

    #[test]
    fn permission_is_reported_as_its_own_state() {
        let mut preview = CameraPreview::new(Rect::new(0, 0, 320, 240));
        let denied = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
        let d = denied.clone();
        preview.permission_denied.connect(move || {
            d.store(true, std::sync::atomic::Ordering::SeqCst);
        });
        preview.report_permission_denied();
        assert!(denied.load(std::sync::atomic::Ordering::SeqCst));
    }
}