loam_app/

capture.rs

use std::fs::File;
use std::io::BufWriter;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU32, Ordering};
use std::sync::mpsc::{sync_channel, Receiver, SyncSender, TrySendError};
use std::sync::Arc;
use std::thread::{self, JoinHandle};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};

use anyhow::{anyhow, Context as _, Result};
use wgpu::{
    Buffer, BufferDescriptor, BufferUsages, CommandEncoder, Device, Extent3d, MapMode, Origin3d,
    PollType, TexelCopyBufferInfo, TexelCopyBufferLayout, TexelCopyTextureInfo, Texture,
    TextureAspect, TextureFormat,
};

pub use crate::capture_types::{
    CaptureFormat, CaptureRequest, CaptureStage, CaptureUnavailable, PaletteMode,
};

impl CaptureStage {
    fn wants_pre(self) -> bool {
        matches!(self, CaptureStage::Pre | CaptureStage::Both)
    }
    fn wants_post(self) -> bool {
        matches!(self, CaptureStage::Post | CaptureStage::Both)
    }
}

impl CaptureFormat {
    fn default_fps(self) -> Option<u16> {
        match self {
            CaptureFormat::Png => None,
            CaptureFormat::Gif | CaptureFormat::Apng => Some(30),
        }
    }

    fn supports_both_stages(self) -> bool {
        matches!(self, CaptureFormat::Png)
    }
}

const FPS_SLACK_DIVISOR: u32 = 8;

fn interval_elapsed(since_last: Duration, interval: Duration) -> bool {
    since_last + interval / FPS_SLACK_DIVISOR >= interval
}

pub(crate) struct Capture {
    default_dir: PathBuf,
    state: CaptureState,
    pending: Vec<JoinHandle<()>>,
}

enum CaptureState {
    Idle,
    OneShot {
        path_pre: Option<PathBuf>,
        path_post: Option<PathBuf>,
    },
    Sequence {
        stage: CaptureStage,
        writer: SequenceWriter,
        fps_interval: Option<Duration>,
        last_capture_time: Option<Instant>,
        frame_count: u32,
    },
}

enum SequenceWriter {
    Png {
        dir: PathBuf,
    },
    Gif {
        worker: GifWorker,
        path: PathBuf,
        default_delay_cs: u16,
        scale: Option<u32>,
        palette_mode: PaletteMode,
        warming: Option<WarmingState>,
        global_palette: Option<Arc<color_quant::NeuQuant>>,
    },
    Apng {
        worker: ApngWorker,
        path: PathBuf,
        scale: Option<u32>,
    },
}

struct WarmingState {
    buffer: Vec<WarmupFrame>,
    target_frames: u32,
}

struct WarmupFrame {
    rgba: Vec<u8>,
    width: u32,
    height: u32,
    captured_at: Instant,
}

// ~1 s at 30 fps; ~57 MB at 800x600, released after training.
const GIF_WARMUP_FRAMES: u32 = 30;

pub(crate) struct GifWorker {
    tx: Option<SyncSender<GifFrame>>,
    handle: Option<JoinHandle<()>>,
    dropped: Arc<AtomicU32>,
}

struct GifFrame {
    rgba: Vec<u8>,
    src_width: u32,
    src_height: u32,
    captured_at: Instant,
    default_delay_cs: u16,
    scale: Option<u32>,
    global_palette: Option<Arc<color_quant::NeuQuant>>,
}

// Bounds worker lag to ~270 ms at 30 fps.
const GIF_CHANNEL_CAPACITY: usize = 8;

impl GifWorker {
    fn spawn(path: PathBuf) -> Result<Self> {
        let (tx, rx) = sync_channel::<GifFrame>(GIF_CHANNEL_CAPACITY);
        let dropped = Arc::new(AtomicU32::new(0));
        let handle = thread::Builder::new()
            .name("loam-app::gif-encoder".into())
            .spawn(move || gif_encoder_loop(path, rx))
            .context("spawn gif encoder thread")?;
        Ok(Self {
            tx: Some(tx),
            handle: Some(handle),
            dropped,
        })
    }

    fn detach(mut self) -> JoinHandle<()> {
        self.tx.take();
        self.handle.take().expect("worker handle present")
    }

    fn try_send(&self, frame: GifFrame) {
        let Some(tx) = self.tx.as_ref() else { return };
        match tx.try_send(frame) {
            Ok(()) => {}
            Err(TrySendError::Full(_)) => {
                let count = self.dropped.fetch_add(1, Ordering::Relaxed) + 1;
                if count.is_power_of_two() {
                    tracing::warn!(
                        "capture: GIF encoder queue full; dropped {count} frame(s) so far"
                    );
                }
            }
            Err(TrySendError::Disconnected(_)) => {
                tracing::error!("capture: GIF encoder thread exited unexpectedly");
            }
        }
    }

    fn dropped(&self) -> u32 {
        self.dropped.load(Ordering::Relaxed)
    }
}

impl Drop for GifWorker {
    fn drop(&mut self) {
        // Fallback for a worker never detached, such as a panic unwinding through `Capture`.
        self.tx.take();
        if let Some(h) = self.handle.take() {
            let _ = h.join();
        }
    }
}

fn gif_encoder_loop(path: PathBuf, rx: Receiver<GifFrame>) {
    let mut encoder: Option<gif::Encoder<BufWriter<File>>> = None;
    let mut last_captured_at: Option<Instant> = None;
    for frame in rx {
        if let Err(e) = encode_one_frame(&path, &mut encoder, &mut last_captured_at, frame) {
            tracing::error!("capture: gif encode error: {e:#}");
            return;
        }
    }
    drop(encoder);
    tracing::info!("capture: gif file finalised at {}", path.display());
}

fn encode_one_frame(
    path: &Path,
    encoder: &mut Option<gif::Encoder<BufWriter<File>>>,
    last_captured_at: &mut Option<Instant>,
    frame: GifFrame,
) -> Result<()> {
    let (out_w, out_h) = scaled_dims(frame.src_width, frame.src_height, frame.scale)?;
    let w_u16: u16 = out_w.try_into().context("gif width > 65535")?;
    let h_u16: u16 = out_h.try_into().context("gif height > 65535")?;

    let enc = match encoder {
        Some(e) => e,
        None => {
            let file = File::create(path)
                .with_context(|| format!("create gif output {}", path.display()))?;
            let global_palette_bytes: Vec<u8> = frame
                .global_palette
                .as_ref()
                .map(|nq| nq.color_map_rgb())
                .unwrap_or_default();
            let mut e =
                gif::Encoder::new(BufWriter::new(file), w_u16, h_u16, &global_palette_bytes)
                    .context("init gif encoder")?;
            e.set_repeat(gif::Repeat::Infinite).context("gif repeat")?;
            tracing::info!(
                "capture: gif encoder opened {}x{} target {}cs/frame ({} fps); \
                 palette={}; actual delays computed from wall-clock per-frame",
                w_u16,
                h_u16,
                frame.default_delay_cs,
                if frame.default_delay_cs == 0 {
                    0
                } else {
                    100 / frame.default_delay_cs as u32
                },
                if frame.global_palette.is_some() {
                    "global (shared NeuQuant)"
                } else {
                    "per-frame"
                }
            );
            encoder.insert(e)
        }
    };

    let delay_cs = match *last_captured_at {
        None => frame.default_delay_cs,
        Some(prev) => {
            let ms = frame.captured_at.duration_since(prev).as_millis() as u64;
            let cs = (ms + 5) / 10;
            cs.clamp(1, u16::MAX as u64) as u16
        }
    };
    *last_captured_at = Some(frame.captured_at);

    let mut buf: Vec<u8> = if frame.scale.is_some() {
        let src: ::image::RgbaImage =
            ::image::ImageBuffer::from_raw(frame.src_width, frame.src_height, frame.rgba)
                .ok_or_else(|| {
                    anyhow!(
                        "RGBA size mismatch at {}x{}",
                        frame.src_width,
                        frame.src_height
                    )
                })?;
        let dst =
            ::image::imageops::resize(&src, out_w, out_h, ::image::imageops::FilterType::Lanczos3);
        dst.into_raw()
    } else {
        frame.rgba
    };

    let mut gif_frame = if let Some(nq) = &frame.global_palette {
        for px in buf.chunks_exact_mut(4) {
            if px[3] != 0 {
                px[3] = 0xFF;
            }
        }
        let mut indices = Vec::with_capacity((out_w as usize) * (out_h as usize));
        for px in buf.chunks_exact(4) {
            indices.push(nq.index_of(px) as u8);
        }
        gif::Frame {
            width: w_u16,
            height: h_u16,
            buffer: std::borrow::Cow::Owned(indices),
            palette: None,
            ..gif::Frame::default()
        }
    } else {
        // NeuQuant, Dekker (1994).
        gif::Frame::from_rgba_speed(w_u16, h_u16, &mut buf, 10)
    };
    gif_frame.delay = delay_cs;
    // `Background` disposal flashes between frames.
    gif_frame.dispose = gif::DisposalMethod::Any;
    enc.write_frame(&gif_frame).context("gif encode")?;
    Ok(())
}

pub(crate) struct ApngWorker {
    tx: Option<SyncSender<ApngFrame>>,
    handle: Option<JoinHandle<()>>,
    frame_count: Arc<AtomicU32>,
}

struct ApngFrame {
    rgba: Vec<u8>,
    src_width: u32,
    src_height: u32,
    captured_at: Instant,
    scale: Option<u32>,
}

// In-flight capacity only; the memory ceiling is the worker's internal Vec.
const APNG_CHANNEL_CAPACITY: usize = 16;

impl ApngWorker {
    fn spawn(path: PathBuf) -> Result<Self> {
        let (tx, rx) = sync_channel::<ApngFrame>(APNG_CHANNEL_CAPACITY);
        let frame_count = Arc::new(AtomicU32::new(0));
        let frame_count_for_worker = frame_count.clone();
        let handle = thread::Builder::new()
            .name("loam-app::apng-encoder".into())
            .spawn(move || apng_encoder_loop(path, rx, frame_count_for_worker))
            .context("spawn apng encoder thread")?;
        Ok(Self {
            tx: Some(tx),
            handle: Some(handle),
            frame_count,
        })
    }

    fn try_send(&self, frame: ApngFrame) {
        let Some(tx) = self.tx.as_ref() else { return };
        if let Err(TrySendError::Disconnected(_)) = tx.try_send(frame) {
            tracing::error!("capture: apng encoder thread exited unexpectedly");
        }
    }

    fn frame_count(&self) -> u32 {
        self.frame_count.load(Ordering::Relaxed)
    }

    fn detach(mut self) -> JoinHandle<()> {
        self.tx.take();
        self.handle.take().expect("worker handle present")
    }
}

impl Drop for ApngWorker {
    fn drop(&mut self) {
        self.tx.take();
        if let Some(h) = self.handle.take() {
            let _ = h.join();
        }
    }
}

fn apng_encoder_loop(path: PathBuf, rx: Receiver<ApngFrame>, frame_count: Arc<AtomicU32>) {
    let mut frames: Vec<ApngFrame> = Vec::new();
    for frame in rx {
        frames.push(frame);
        frame_count.store(frames.len() as u32, Ordering::Relaxed);
    }
    if frames.is_empty() {
        tracing::info!("capture: apng stopped before any frames captured; no file written");
        return;
    }
    if let Err(e) = write_apng(&path, frames) {
        tracing::error!("capture: apng write failed: {e:#}");
        return;
    }
    tracing::info!("capture: apng file finalised at {}", path.display());
}

fn write_apng(path: &Path, frames: Vec<ApngFrame>) -> Result<()> {
    let (out_w, out_h) = scaled_dims(frames[0].src_width, frames[0].src_height, frames[0].scale)?;
    let file =
        File::create(path).with_context(|| format!("create apng output {}", path.display()))?;
    let mut encoder = png::Encoder::new(BufWriter::new(file), out_w, out_h);
    encoder.set_color(png::ColorType::Rgba);
    encoder.set_depth(png::BitDepth::Eight);
    // num_plays=0 loops infinitely.
    encoder
        .set_animated(frames.len() as u32, 0)
        .context("apng set_animated")?;
    let mut writer = encoder.write_header().context("apng write_header")?;

    let mut last_captured_at: Option<Instant> = None;
    for frame in frames {
        let (fw, fh) = scaled_dims(frame.src_width, frame.src_height, frame.scale)?;
        if fw != out_w || fh != out_h {
            return Err(anyhow!(
                "apng frame dims {fw}x{fh} != first frame {out_w}x{out_h}"
            ));
        }
        let rgba = if frame.scale.is_some() {
            let src: ::image::RgbaImage =
                ::image::ImageBuffer::from_raw(frame.src_width, frame.src_height, frame.rgba)
                    .ok_or_else(|| {
                        anyhow!(
                            "RGBA size mismatch at {}x{}",
                            frame.src_width,
                            frame.src_height
                        )
                    })?;
            ::image::imageops::resize(&src, out_w, out_h, ::image::imageops::FilterType::Lanczos3)
                .into_raw()
        } else {
            frame.rgba
        };

        // The first frame has no gap; 33 ms is ~30 fps.
        let delay_ms = match last_captured_at {
            None => 33u16,
            Some(prev) => {
                let ms = frame.captured_at.duration_since(prev).as_millis();
                ms.min(u16::MAX as u128).max(1) as u16
            }
        };
        last_captured_at = Some(frame.captured_at);

        writer
            .set_frame_delay(delay_ms, 1000)
            .context("apng set_frame_delay")?;
        writer
            .write_image_data(&rgba)
            .context("apng write_image_data")?;
    }
    writer.finish().context("apng finish")?;
    Ok(())
}

impl Capture {
    pub(crate) fn new() -> Self {
        Self {
            default_dir: PathBuf::from("captures"),
            state: CaptureState::Idle,
            pending: Vec::new(),
        }
    }

    fn reap_finished(&mut self) {
        let mut still_running = Vec::with_capacity(self.pending.len());
        for h in self.pending.drain(..) {
            if h.is_finished() {
                let _ = h.join();
            } else {
                still_running.push(h);
            }
        }
        self.pending = still_running;
    }

    pub(crate) fn apply_requests(&mut self, requests: Vec<CaptureRequest>) -> Vec<String> {
        let mut log = Vec::new();
        for req in requests {
            match req {
                CaptureRequest::OneShot { stage, dir, name } => {
                    let dir = dir.unwrap_or_else(|| self.default_dir.clone());
                    let name = name.unwrap_or_else(default_name);
                    let path_pre = stage
                        .wants_pre()
                        .then(|| dir.join(format!("{name}_pre.png")));
                    let path_post = stage
                        .wants_post()
                        .then(|| dir.join(format!("{name}_post.png")));
                    self.state = CaptureState::OneShot {
                        path_pre,
                        path_post,
                    };
                    log.push(format!("capture: one-shot queued ({stage:?})"));
                }
                CaptureRequest::StartSequence {
                    format,
                    stage,
                    dir,
                    name,
                    fps,
                    scale,
                    palette,
                } => match self.start_sequence(format, stage, dir, name, fps, scale, palette) {
                    Ok(msg) => log.push(msg),
                    Err(e) => log.push(format!("capture: failed to start sequence: {e:#}")),
                },
                CaptureRequest::Stop => self.stop(&mut log),
                CaptureRequest::Toggle {
                    format,
                    stage,
                    dir,
                    name,
                    fps,
                    scale,
                    palette,
                } => {
                    if matches!(self.state, CaptureState::Sequence { .. }) {
                        self.stop(&mut log);
                    } else {
                        match self.start_sequence(format, stage, dir, name, fps, scale, palette) {
                            Ok(msg) => log.push(msg),
                            Err(e) => log.push(format!("capture: failed to start sequence: {e:#}")),
                        }
                    }
                }
            }
        }
        log
    }

    #[allow(clippy::too_many_arguments)]
    fn start_sequence(
        &mut self,
        format: CaptureFormat,
        mut stage: CaptureStage,
        dir: Option<PathBuf>,
        name: Option<String>,
        fps: Option<u16>,
        scale: Option<u32>,
        palette: PaletteMode,
    ) -> Result<String> {
        let dir = dir.unwrap_or_else(|| self.default_dir.clone());
        let name = name.unwrap_or_else(default_name);
        let fps = fps.or_else(|| format.default_fps());

        if !format.supports_both_stages() && stage == CaptureStage::Both {
            stage = CaptureStage::Post;
        }

        let writer = match format {
            CaptureFormat::Png => {
                let dir = dir.join(&name);
                std::fs::create_dir_all(&dir)
                    .with_context(|| format!("create png sequence dir {}", dir.display()))?;
                SequenceWriter::Png { dir }
            }
            CaptureFormat::Gif => {
                let path = dir.join(format!("{name}.gif"));
                if let Some(parent) = path.parent() {
                    std::fs::create_dir_all(parent)
                        .with_context(|| format!("create gif parent dir {}", parent.display()))?;
                }
                let default_delay_cs = fps_to_centiseconds(fps.unwrap_or(30));
                let worker = GifWorker::spawn(path.clone())?;
                let warming = match palette {
                    PaletteMode::Local => None,
                    PaletteMode::Global => Some(WarmingState {
                        buffer: Vec::with_capacity(GIF_WARMUP_FRAMES as usize),
                        target_frames: GIF_WARMUP_FRAMES,
                    }),
                };
                SequenceWriter::Gif {
                    worker,
                    path,
                    default_delay_cs,
                    scale,
                    palette_mode: palette,
                    warming,
                    global_palette: None,
                }
            }
            CaptureFormat::Apng => {
                let path = dir.join(format!("{name}.apng"));
                if let Some(parent) = path.parent() {
                    std::fs::create_dir_all(parent)
                        .with_context(|| format!("create apng parent dir {}", parent.display()))?;
                }
                let worker = ApngWorker::spawn(path.clone())?;
                SequenceWriter::Apng {
                    worker,
                    path,
                    scale,
                }
            }
        };

        let fps_interval = fps.map(|f| Duration::from_secs_f64(1.0 / f.max(1) as f64));
        self.state = CaptureState::Sequence {
            stage,
            writer,
            fps_interval,
            last_capture_time: None,
            frame_count: 0,
        };
        Ok(format!(
            "capture: sequence started ({format:?}, {stage:?}, fps={}, palette={palette:?})",
            fps.map(|f| f.to_string())
                .unwrap_or_else(|| "unlimited".into())
        ))
    }

    fn stop(&mut self, log: &mut Vec<String>) {
        self.reap_finished();
        let state = std::mem::replace(&mut self.state, CaptureState::Idle);
        match state {
            CaptureState::Sequence {
                writer,
                frame_count,
                ..
            } => match writer {
                SequenceWriter::Png { dir } => {
                    log.push(format!(
                        "capture: PNG sequence stopped, {frame_count} frame(s) at {}",
                        dir.display()
                    ));
                }
                SequenceWriter::Gif {
                    worker,
                    path,
                    default_delay_cs,
                    scale,
                    warming,
                    ..
                } => {
                    if let Some(mut w) = warming {
                        if !w.buffer.is_empty() {
                            tracing::info!(
                                "capture: stopped during warmup ({} frame(s)); \
                                 training palette on partial buffer",
                                w.buffer.len()
                            );
                            let nq = Arc::new(train_global_palette(&w.buffer));
                            for f in w.buffer.drain(..) {
                                worker.try_send(GifFrame {
                                    rgba: f.rgba,
                                    src_width: f.width,
                                    src_height: f.height,
                                    captured_at: f.captured_at,
                                    default_delay_cs,
                                    scale,
                                    global_palette: Some(nq.clone()),
                                });
                            }
                        }
                    }
                    let dropped = worker.dropped();
                    let handle = worker.detach();
                    self.pending.push(handle);
                    let drop_note = if dropped > 0 {
                        format!(", {dropped} dropped under backpressure")
                    } else {
                        String::new()
                    };
                    log.push(format!(
                        "capture: GIF stream stopped, {frame_count} frame(s){drop_note} \
                         encoding in background -> {}",
                        path.display()
                    ));
                }
                SequenceWriter::Apng { worker, path, .. } => {
                    let buffered = worker.frame_count();
                    let handle = worker.detach();
                    self.pending.push(handle);
                    log.push(format!(
                        "capture: APNG stream stopped, {buffered} frame(s) buffered; \
                         assembling and writing in background -> {}",
                        path.display()
                    ));
                }
            },
            CaptureState::OneShot { .. } => {
                log.push("capture: pending one-shot cancelled".into());
            }
            CaptureState::Idle => {
                log.push("capture: stop with no active session (no-op)".into());
            }
        }
    }

    pub(crate) fn wants_pre(&self) -> bool {
        match &self.state {
            CaptureState::Idle => false,
            CaptureState::OneShot { path_pre, .. } => path_pre.is_some(),
            CaptureState::Sequence { stage, .. } => stage.wants_pre(),
        }
    }

    pub(crate) fn wants_post(&self) -> bool {
        match &self.state {
            CaptureState::Idle => false,
            CaptureState::OneShot { path_post, .. } => path_post.is_some(),
            CaptureState::Sequence { stage, .. } => stage.wants_post(),
        }
    }

    pub(crate) fn should_capture(&self, now: Instant) -> bool {
        match &self.state {
            CaptureState::Idle => false,
            CaptureState::OneShot { .. } => true,
            CaptureState::Sequence {
                fps_interval,
                last_capture_time,
                ..
            } => match (fps_interval, last_capture_time) {
                (None, _) => true,
                (Some(_), None) => true,
                (Some(interval), Some(last)) => {
                    interval_elapsed(now.duration_since(*last), *interval)
                }
            },
        }
    }

    pub(crate) fn consume_frame(
        &mut self,
        is_pre: bool,
        rgba: Vec<u8>,
        width: u32,
        height: u32,
        captured_at: Instant,
    ) -> Result<()> {
        match &mut self.state {
            CaptureState::Idle => Ok(()),
            CaptureState::OneShot {
                path_pre,
                path_post,
            } => {
                let path = if is_pre {
                    path_pre.take()
                } else {
                    path_post.take()
                };
                if let Some(path) = path {
                    write_png_bytes(&path, &rgba, width, height)?;
                    tracing::info!("capture: wrote {}", path.display());
                }
                Ok(())
            }
            CaptureState::Sequence {
                writer,
                frame_count,
                ..
            } => writer.write_frame(is_pre, *frame_count, rgba, width, height, captured_at),
        }
    }

    fn join_pending(&mut self) {
        for h in self.pending.drain(..) {
            let _ = h.join();
        }
    }

    pub(crate) fn advance_frame(&mut self, now: Instant) {
        match &mut self.state {
            CaptureState::OneShot {
                path_pre,
                path_post,
            } => {
                if path_pre.is_none() && path_post.is_none() {
                    self.state = CaptureState::Idle;
                }
            }
            CaptureState::Sequence {
                last_capture_time,
                frame_count,
                ..
            } => {
                *last_capture_time = Some(now);
                *frame_count = frame_count.saturating_add(1);
            }
            CaptureState::Idle => {}
        }
    }
}

impl Drop for Capture {
    fn drop(&mut self) {
        self.stop(&mut Vec::new());
        self.join_pending();
    }
}

impl SequenceWriter {
    fn write_frame(
        &mut self,
        is_pre: bool,
        frame_idx: u32,
        rgba: Vec<u8>,
        width: u32,
        height: u32,
        captured_at: Instant,
    ) -> Result<()> {
        match self {
            SequenceWriter::Png { dir } => {
                let label = if is_pre { "pre" } else { "post" };
                let path = dir.join(format!("{label}_{frame_idx:06}.png"));
                write_png_bytes(&path, &rgba, width, height)?;
                Ok(())
            }
            SequenceWriter::Gif {
                worker,
                default_delay_cs,
                scale,
                palette_mode,
                warming,
                global_palette,
                ..
            } => {
                match *palette_mode {
                    PaletteMode::Local => {
                        worker.try_send(GifFrame {
                            rgba,
                            src_width: width,
                            src_height: height,
                            captured_at,
                            default_delay_cs: *default_delay_cs,
                            scale: *scale,
                            global_palette: None,
                        });
                    }
                    PaletteMode::Global => {
                        if let Some(w) = warming.as_mut() {
                            w.buffer.push(WarmupFrame {
                                rgba,
                                width,
                                height,
                                captured_at,
                            });
                            if w.buffer.len() as u32 >= w.target_frames {
                                let nq = Arc::new(train_global_palette(&w.buffer));
                                tracing::info!(
                                    "capture: gif global palette trained from {} frames",
                                    w.buffer.len()
                                );
                                for f in w.buffer.drain(..) {
                                    worker.try_send(GifFrame {
                                        rgba: f.rgba,
                                        src_width: f.width,
                                        src_height: f.height,
                                        captured_at: f.captured_at,
                                        default_delay_cs: *default_delay_cs,
                                        scale: *scale,
                                        global_palette: Some(nq.clone()),
                                    });
                                }
                                *global_palette = Some(nq);
                                *warming = None;
                            }
                        } else if let Some(nq) = global_palette.as_ref() {
                            worker.try_send(GifFrame {
                                rgba,
                                src_width: width,
                                src_height: height,
                                captured_at,
                                default_delay_cs: *default_delay_cs,
                                scale: *scale,
                                global_palette: Some(nq.clone()),
                            });
                        } else {
                            tracing::error!(
                                "capture: gif global mode lost palette state (frame dropped)"
                            );
                        }
                    }
                }
                Ok(())
            }
            SequenceWriter::Apng { worker, scale, .. } => {
                worker.try_send(ApngFrame {
                    rgba,
                    src_width: width,
                    src_height: height,
                    captured_at,
                    scale: *scale,
                });
                Ok(())
            }
        }
    }
}

fn train_global_palette(buffer: &[WarmupFrame]) -> color_quant::NeuQuant {
    // Stride 16 feeds ~110 K samples at 800x600 over 30 frames.
    const STRIDE: usize = 16;
    let mut samples: Vec<u8> = Vec::new();
    for frame in buffer {
        for px in frame.rgba.chunks_exact(4).step_by(STRIDE) {
            // Opaque alpha is normalized so NeuQuant's 4D metric is not biased.
            samples.push(px[0]);
            samples.push(px[1]);
            samples.push(px[2]);
            samples.push(if px[3] != 0 { 0xFF } else { 0 });
        }
    }
    color_quant::NeuQuant::new(10, 256, &samples)
}

fn scaled_dims(width: u32, height: u32, scale: Option<u32>) -> Result<(u32, u32)> {
    let Some(target_w) = scale else {
        return Ok((width, height));
    };
    if target_w == 0 || width == 0 || height == 0 {
        return Err(anyhow!(
            "invalid scale: target_w={target_w}, src={width}x{height}"
        ));
    }
    let h = ((target_w as u64 * height as u64 + (width as u64) / 2) / width as u64) as u32;
    Ok((target_w, h.max(1)))
}

fn fps_to_centiseconds(fps: u16) -> u16 {
    // A zero-delay GIF frame is rejected.
    let cs = (100.0_f32 / fps.max(1) as f32).round() as u16;
    cs.max(1)
}

fn default_name() -> String {
    let unix = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    format!("capture_{unix}")
}

// Row-major RGBA8, already R/B-swapped from BGRA sources.
pub(crate) struct RawImage {
    pub width: u32,
    pub height: u32,
    pub rgba: Vec<u8>,
}

pub(crate) struct TextureReadback {
    buffer: Buffer,
    width: u32,
    height: u32,
    unpadded_bpr: u32,
    padded_bpr: u32,
    format: TextureFormat,
}

pub(crate) fn record_texture_rgba(
    device: &Device,
    encoder: &mut CommandEncoder,
    texture: &Texture,
    width: u32,
    height: u32,
    format: TextureFormat,
) -> Result<TextureReadback> {
    let unpadded_bpr = width.checked_mul(4).context("width * 4 overflows u32")?;
    let padded_bpr = unpadded_bpr.next_multiple_of(256);
    let buffer_size = (padded_bpr as u64) * (height as u64);

    let buffer = device.create_buffer(&BufferDescriptor {
        label: Some("loam-app::capture-staging"),
        size: buffer_size,
        usage: BufferUsages::COPY_DST | BufferUsages::MAP_READ,
        mapped_at_creation: false,
    });

    encoder.copy_texture_to_buffer(
        TexelCopyTextureInfo {
            texture,
            mip_level: 0,
            origin: Origin3d::ZERO,
            aspect: TextureAspect::All,
        },
        TexelCopyBufferInfo {
            buffer: &buffer,
            layout: TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(padded_bpr),
                rows_per_image: None,
            },
        },
        Extent3d {
            width,
            height,
            depth_or_array_layers: 1,
        },
    );
    Ok(TextureReadback {
        buffer,
        width,
        height,
        unpadded_bpr,
        padded_bpr,
        format,
    })
}

impl TextureReadback {
    pub(crate) fn read(self, device: &Device) -> Result<RawImage> {
        let Self {
            buffer,
            width,
            height,
            unpadded_bpr,
            padded_bpr,
            format,
        } = self;

        let slice = buffer.slice(..);
        let (mapped_tx, mapped_rx) = std::sync::mpsc::channel();
        slice.map_async(MapMode::Read, move |result| {
            let _ = mapped_tx.send(result);
        });
        device
            .poll(PollType::Wait {
                submission_index: None,
                timeout: None,
            })
            .context("device.poll on capture readback failed")?;

        mapped_rx
            .recv()
            .context("capture map callback dropped")?
            .context("capture buffer mapping failed")?;
        let data = slice.get_mapped_range();
        let mut rgba = Vec::with_capacity((unpadded_bpr * height) as usize);
        for row in 0..height as usize {
            let start = row * padded_bpr as usize;
            let end = start + unpadded_bpr as usize;
            rgba.extend_from_slice(&data[start..end]);
        }
        drop(data);
        buffer.unmap();

        if format_is_bgra(format) {
            for px in rgba.chunks_exact_mut(4) {
                px.swap(0, 2);
            }
        }

        Ok(RawImage {
            width,
            height,
            rgba,
        })
    }
}

fn format_is_bgra(format: TextureFormat) -> bool {
    matches!(
        format,
        TextureFormat::Bgra8Unorm | TextureFormat::Bgra8UnormSrgb
    )
}

fn write_png_bytes(path: &Path, rgba: &[u8], width: u32, height: u32) -> Result<()> {
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)
            .with_context(|| format!("create capture dir {}", parent.display()))?;
    }
    ::image::save_buffer_with_format(
        path,
        rgba,
        width,
        height,
        ::image::ColorType::Rgba8,
        ::image::ImageFormat::Png,
    )
    .with_context(|| format!("write png {}", path.display()))?;
    Ok(())
}

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

    #[test]
    fn a_frame_a_hair_early_is_taken_and_one_a_half_period_early_is_not() {
        let interval = Duration::from_micros(33_333);
        assert!(interval_elapsed(interval, interval));
        assert!(interval_elapsed(
            interval - Duration::from_micros(200),
            interval
        ));
        assert!(interval_elapsed(interval * 2, interval));

        assert!(!interval_elapsed(interval / 2, interval));
        assert!(!interval_elapsed(Duration::ZERO, interval));
    }

    #[test]
    fn scaled_dims_preserves_aspect_ratio() {
        assert_eq!(scaled_dims(1920, 1080, Some(720)).unwrap(), (720, 405));
        assert_eq!(scaled_dims(1024, 1024, Some(512)).unwrap(), (512, 512));
        assert_eq!(scaled_dims(1080, 1920, Some(360)).unwrap(), (360, 640));
        assert_eq!(scaled_dims(800, 600, None).unwrap(), (800, 600));
        assert_eq!(scaled_dims(10000, 1, Some(100)).unwrap(), (100, 1));
    }

    #[test]
    fn scaled_dims_rejects_zero_target() {
        assert!(scaled_dims(1920, 1080, Some(0)).is_err());
        assert!(scaled_dims(0, 1080, Some(720)).is_err());
        assert!(scaled_dims(1920, 0, Some(720)).is_err());
    }
}