GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
//! Sparse, copy-on-write tiled surfaces in any [`PixelFormat`].
//!
//! A [`Surface`] is an infinite plane of 256×256 tiles. Missing tiles read as the surface's
//! default pixel (transparent for layers, white for "reveal all" masks). Tiles are `Arc`-shared,
//! so cloning a surface is O(tiles) and mutation copies only the touched tiles. That makes
//! undo snapshots, background jobs and autosave cheap.
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]

pub mod headroom;
mod interrupt;
pub use interrupt::{Cancelled, Interrupt};
pub mod scratch;
mod shift;
pub use shift::TranslateSteps;

use std::collections::BTreeMap;
use std::fmt;
use std::ops::{Bound, Deref, DerefMut};
use std::sync::{Arc, RwLockReadGuard, RwLockWriteGuard};

use photocraft_color::{ColorMode, PixelFormat, SampleType, read_sample, read_samples, write_sample};
use photocraft_geom::{Rect, TILE_SIZE, TileCoord};

/// The bytes a surface in `fmt` keeps for pixels written over `rect`: every tile the rect
/// touches, whole. Importers admit decoded pixels by their logical size; a narrow or scattered
/// rect stores up to `TILE_SIZE` times more, so admission charges this instead.
pub fn tile_storage_bytes(rect: Rect, fmt: &PixelFormat) -> u64 {
    stored_tiles_bytes(rect.tile_count(), fmt)
}

/// The bytes `tiles` whole tiles take in `fmt`.
pub fn stored_tiles_bytes(tiles: u64, fmt: &PixelFormat) -> u64 {
    tiles.saturating_mul((TILE_SIZE as u64).pow(2)).saturating_mul(fmt.bytes_per_pixel() as u64)
}

/// A checked surface allocation could not be represented or reserved.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum AllocationError {
    ScratchRead(String),
    SizeOverflow,
    NotEnoughMemory {
        bytes: usize,
    },
    /// The pixels given don't fill the region they are written to.
    LengthMismatch {
        expected: usize,
        got: usize,
    },
}

impl fmt::Display for AllocationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::ScratchRead(error) => write!(f, "scratch tile could not be read: {error}"),
            Self::SizeOverflow => f.write_str("requested surface allocation is too large"),
            Self::NotEnoughMemory { bytes } => write!(f, "not enough memory to allocate {} bytes", bytes),
            Self::LengthMismatch { expected, got } => write!(f, "{got} bytes of pixels given for a region that takes {expected}"),
        }
    }
}

impl std::error::Error for AllocationError {}

/// Failure to prepare an interruptible row write.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum RowWriteError {
    Allocation(AllocationError),
    Cancelled(Cancelled),
}

impl From<AllocationError> for RowWriteError {
    fn from(error: AllocationError) -> Self {
        Self::Allocation(error)
    }
}

impl fmt::Display for RowWriteError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Allocation(error) => write!(f, "{error}"),
            Self::Cancelled(error) => write!(f, "{error}"),
        }
    }
}

impl std::error::Error for RowWriteError {}
pub mod memory;
mod scratch_file;
pub mod spill;
pub mod stage_file;

/// One shared tile per pixel value (and tile size), for [`Surface::share_uniform_tiles`].
#[derive(Debug, Default)]
pub struct TileInterner {
    tiles: std::collections::HashMap<usize, std::collections::HashMap<Vec<u8>, Arc<Tile>>>,
}

impl TileInterner {
    /// Number of distinct uniform tiles held.
    pub fn len(&self) -> usize {
        self.tiles.values().map(|m| m.len()).sum()
    }

    /// `true` when no tile is held.
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }
}

/// Pixel storage for one tile: `TILE_SIZE² × bytes_per_pixel`, row-major, interleaved channels.
///
/// The bytes may live on the scratch disk ([`spill`]); [`Tile::bytes`] and [`Tile::bytes_mut`]
/// bring them back and keep them in memory while the returned guard lives. Take one guard per
/// tile, not per pixel, in hot loops.
pub struct Tile {
    cell: Arc<spill::Cell>,
}

impl Tile {
    /// Fill a new tile with one encoded pixel, reporting size or allocation failures.
    fn try_filled(format: &PixelFormat, pixel: &[u8]) -> Result<Self, AllocationError> {
        let n = (TILE_SIZE * TILE_SIZE) as usize;
        let bytes = n.checked_mul(format.bytes_per_pixel()).ok_or(AllocationError::SizeOverflow)?;
        let mut data = scratch::try_take_exact(bytes, 0u8).ok_or(AllocationError::NotEnoughMemory { bytes })?;
        if pixel.iter().any(|&b| b != 0) {
            // Fill the first row, then copy it to the other rows without another allocation.
            let row_len = TILE_SIZE as usize * format.bytes_per_pixel();
            let (row, rest) = data.split_at_mut(row_len);
            for px in row.chunks_exact_mut(pixel.len()) {
                px.copy_from_slice(pixel);
            }
            for dst in rest.chunks_exact_mut(row_len) {
                dst.copy_from_slice(row);
            }
        }
        Ok(Tile::from_vec(data))
    }

    /// Clone this tile's pixel buffer with a fallible reservation.
    pub fn try_clone(&self) -> Result<Self, AllocationError> {
        let source = self.try_bytes().map_err(AllocationError::ScratchRead)?;
        let bytes = source.len();
        let mut data = scratch::try_take_exact(bytes, 0u8).ok_or(AllocationError::NotEnoughMemory { bytes })?;
        data.copy_from_slice(&source);
        Ok(Tile::from_vec(data))
    }

    fn filled(format: &PixelFormat, pixel: &[u8]) -> Self {
        let row_len = TILE_SIZE as usize * format.bytes_per_pixel();
        let mut data = scratch::take_exact(row_len * TILE_SIZE as usize, 0u8);
        if pixel.iter().any(|&b| b != 0) {
            // One prebuilt row copied per tile row: 256 bulk copies instead of one
            // copy_from_slice per pixel.
            let mut row = Vec::with_capacity(row_len);
            for _ in 0..TILE_SIZE {
                row.extend_from_slice(pixel);
            }
            for out in data.chunks_mut(row_len) {
                out.copy_from_slice(&row);
            }
        }
        Tile::from_vec(data)
    }
    fn from_vec(data: Vec<u8>) -> Self {
        Tile { cell: spill::Cell::new(data) }
    }
    /// The tile's bytes (read back from the scratch disk if needed).
    pub fn bytes(&self) -> TileBytes<'_> {
        let guard = self.cell.read();
        let placeholder = if guard.is_none() { vec![0; self.len()] } else { Vec::new() };
        TileBytes(guard, placeholder)
    }
    pub fn bytes_mut(&mut self) -> TileBytesMut<'_> {
        let guard = self.cell.write();
        let placeholder = if guard.is_none() { vec![0; self.len()] } else { Vec::new() };
        TileBytesMut(guard, placeholder)
    }
    /// `Err` while this tile's scratch copy is unreadable (its bytes read as a placeholder).
    /// Free when no tile in the process has failed.
    pub fn scratch_health(&self) -> Result<(), String> {
        if !spill::any_failed() {
            return Ok(());
        }
        self.cell.read_error().map_or(Ok(()), Err)
    }
    /// Fallible pixel access for callers that can propagate a scratch read failure.
    pub fn try_bytes(&self) -> Result<TileBytes<'_>, String> {
        let bytes = self.bytes();
        match self.cell.read_error() {
            Some(error) => Err(error),
            None => Ok(bytes),
        }
    }
    /// Tile-local half-open bounds `(x0, y0, x1, y1)` of the pixels that differ from the encoded
    /// pixel `dp` (one pixel of the tile's format), or `None` when every pixel equals it (or `dp`
    /// is empty).
    pub fn content_bounds(&self, dp: &[u8]) -> Option<(u16, u16, u16, u16)> {
        let bpp = dp.len();
        if bpp == 0 {
            return None;
        }
        let ts = TILE_SIZE as usize;
        // A row of `dp`, compared block by block: an untouched row (most rows of a soft brush
        // stroke's tiles) costs a few slice compares instead of one per pixel. A pixel differs
        // where any of its bytes does, so the first and last differing bytes give the first and
        // last differing pixels.
        let blank = dp.repeat(ts);
        let (mut x0, mut y0, mut x1, mut y1) = (usize::MAX, usize::MAX, 0usize, 0usize);
        for (y, row) in self.bytes().chunks_exact(ts * bpp).enumerate() {
            let Some(first) = first_difference(row, &blank) else { continue };
            let Some(last) = last_difference(row, &blank) else { continue };
            x0 = x0.min(first / bpp);
            x1 = x1.max(last / bpp + 1);
            y0 = y0.min(y);
            y1 = y + 1;
        }
        (x0 != usize::MAX).then_some((x0 as u16, y0 as u16, x1 as u16, y1 as u16))
    }
    /// Byte length, without touching the pixels (they may be on disk).
    pub fn len(&self) -> usize {
        self.cell.len()
    }
    pub fn is_empty(&self) -> bool {
        self.cell.len() == 0
    }
}

impl Clone for Tile {
    fn clone(&self) -> Self {
        match self.try_bytes() {
            Ok(bytes) => {
                let mut data = scratch::take_exact(bytes.len(), 0u8);
                data.copy_from_slice(&bytes);
                Tile::from_vec(data)
            }
            // Preserve the original backing; the transaction will reject this poisoned tile.
            Err(_) => Tile { cell: self.cell.clone() },
        }
    }
}

impl PartialEq for Tile {
    fn eq(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.cell, &other.cell) || (self.len() == other.len() && *self.bytes() == *other.bytes())
    }
}

impl Eq for Tile {}

impl std::fmt::Debug for Tile {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Tile").field("len", &self.len()).finish_non_exhaustive()
    }
}

/// Read guard over a tile's bytes; derefs to `[u8]`.
pub struct TileBytes<'a>(RwLockReadGuard<'a, Option<Vec<u8>>>, Vec<u8>);

impl Deref for TileBytes<'_> {
    type Target = [u8];
    fn deref(&self) -> &[u8] {
        self.0.as_deref().unwrap_or(&self.1)
    }
}

/// Write guard over a tile's bytes; derefs to `[u8]`.
pub struct TileBytesMut<'a>(RwLockWriteGuard<'a, Option<Vec<u8>>>, Vec<u8>);

impl Deref for TileBytesMut<'_> {
    type Target = [u8];
    fn deref(&self) -> &[u8] {
        self.0.as_deref().unwrap_or(&self.1)
    }
}

impl DerefMut for TileBytesMut<'_> {
    fn deref_mut(&mut self) -> &mut [u8] {
        self.0.as_deref_mut().unwrap_or(&mut self.1)
    }
}

/// Bytes compared at once while looking for a difference in a tile row.
const DIFF_BLOCK: usize = 64;

/// Index of the first byte where `a` and `b` (the same length) differ.
fn first_difference(a: &[u8], b: &[u8]) -> Option<usize> {
    let (k, (x, y)) = a.chunks(DIFF_BLOCK).zip(b.chunks(DIFF_BLOCK)).enumerate().find(|(_, (x, y))| x != y)?;
    x.iter().zip(y).position(|(p, q)| p != q).map(|i| k * DIFF_BLOCK + i)
}

/// Index of the last byte where `a` and `b` (the same length) differ.
fn last_difference(a: &[u8], b: &[u8]) -> Option<usize> {
    let (k, (x, y)) = a.chunks(DIFF_BLOCK).zip(b.chunks(DIFF_BLOCK)).enumerate().rfind(|(_, (x, y))| x != y)?;
    x.iter().zip(y).rposition(|(p, q)| p != q).map(|i| k * DIFF_BLOCK + i)
}

/// Where [`Surface::prune_batch`] resumes: after the last tile it visited.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct PruneCursor {
    after: Option<TileCoord>,
    done: bool,
}

impl PruneCursor {
    /// True once every tile has been visited.
    pub fn is_done(&self) -> bool {
        self.done
    }
}

#[derive(Clone, Debug)]
pub struct Surface {
    format: PixelFormat,
    default_pixel: Box<[u8]>,
    tiles: BTreeMap<TileCoord, Arc<Tile>>,
}

/// Use stack storage when it fits, otherwise reuse a dynamically sized sample buffer.
fn sample_buffer<'a>(channels: usize, stack: &'a mut [f32], heap: &'a mut Vec<f32>) -> &'a mut [f32] {
    if let Some(samples) = stack.get_mut(..channels) {
        samples
    } else {
        heap.resize(channels, 0.0);
        heap
    }
}

/// Tiles of one pixel value met while moving a surface ([`Surface::translated`]): each scanned
/// once, and one tile kept per value so the targets share it.
#[derive(Default)]
struct UniformTiles {
    /// Per source tile (by address): the index of its value's tile in `canonical`, or `None`.
    of: std::collections::HashMap<usize, Option<usize>>,
    canonical: Vec<Arc<Tile>>,
}

impl UniformTiles {
    /// The tile to share for a target reading window `r` of `s`, when every tile under it holds
    /// one and the same pixel value (`r` must lie on existing tiles).
    fn window(&self, s: &Surface, r: Rect) -> Option<Arc<Tile>> {
        let mut found = None;
        for c in r.tiles() {
            let t = s.tiles.get(&c)?;
            let k = (*self.of.get(&(Arc::as_ptr(t) as usize))?)?;
            if found.is_some_and(|f| f != k) {
                return None;
            }
            found = Some(k);
        }
        self.canonical.get(found?).cloned()
    }

    fn value_of(&mut self, t: &Arc<Tile>, bpp: usize) -> Option<usize> {
        let key = Arc::as_ptr(t) as usize;
        if let Some(k) = self.of.get(&key) {
            return *k;
        }
        let bytes = t.try_bytes().ok()?;
        let mut px = bytes.chunks_exact(bpp);
        let k = px.next().filter(|p0| px.all(|p| p == *p0)).map(|p0| {
            match self.canonical.iter().position(|c| c.try_bytes().is_ok_and(|bytes| bytes.get(..bpp) == Some(p0))) {
                Some(k) => k,
                None => {
                    self.canonical.push(t.clone());
                    self.canonical.len() - 1
                }
            }
        });
        self.of.insert(key, k);
        k
    }
}

impl PartialEq for Surface {
    fn eq(&self, other: &Self) -> bool {
        self.format == other.format && self.default_pixel == other.default_pixel && self.tiles == other.tiles
    }
}

/// Converts the `data` span covering one tile into that tile's bytes.
fn write_tile(t: &mut Tile, tc: TileCoord, r: Rect, data: &[f32], w: usize, n: usize, sample: SampleType) {
    let tr = tc.rect().intersect(&r);
    // Convert contiguous channel samples a row at a time. Dispatching on depth here removes the
    // per-pixel channel loop and lets the compiler vectorise conversion.
    let span = tr.width() as usize * n;
    let mut target = t.bytes_mut();
    for y in tr.y0..tr.y1 {
        let o = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * n;
        let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
        let src = &data[o..o + span];
        let bytes = sample.bytes();
        let dst = &mut target[base * bytes..(base + span) * bytes];
        match sample {
            SampleType::U8 => {
                for (d, v) in dst.iter_mut().zip(src) {
                    *d = (v.clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
                }
            }
            SampleType::U16 => {
                for (d, v) in dst.as_chunks_mut::<2>().0.iter_mut().zip(src) {
                    let q = (v.clamp(0.0, 1.0) * 65535.0 + 0.5) as u16;
                    d.copy_from_slice(&q.to_ne_bytes());
                }
            }
            SampleType::F32 => {
                for (d, v) in dst.as_chunks_mut::<4>().0.iter_mut().zip(src) {
                    d.copy_from_slice(&v.to_ne_bytes());
                }
            }
        }
    }
}

/// Converts the tiles of a region write. A tile holds no state another tile reads, so the tiles
/// are converted on all cores; each writes only its own bytes, in the same arithmetic.
#[cfg(not(target_arch = "wasm32"))]
fn convert_tiles(tiles: &mut [(TileCoord, Arc<Tile>)], r: Rect, data: &[f32], w: usize, n: usize, sample: SampleType) {
    use rayon::prelude::*;
    tiles.par_iter_mut().for_each(|(tc, t)| write_tile(Arc::make_mut(t), *tc, r, data, w, n, sample));
}

/// Serial counterpart, for the web build (there are no threads to spread tiles over).
#[cfg(target_arch = "wasm32")]
fn convert_tiles(tiles: &mut [(TileCoord, Arc<Tile>)], r: Rect, data: &[f32], w: usize, n: usize, sample: SampleType) {
    for (tc, t) in tiles.iter_mut() {
        write_tile(Arc::make_mut(t), *tc, r, data, w, n, sample);
    }
}

/// Copies the rows of `r` (interleaved `bytes`, `w` px wide, `bpp` bytes per pixel) into one
/// tile, first copying it fallibly when an undo snapshot still shares it.
fn copy_tile(tc: TileCoord, t: &mut Arc<Tile>, r: Rect, bytes: &[u8], w: usize, bpp: usize) -> Result<(), AllocationError> {
    if Arc::get_mut(t).is_none() {
        *t = Arc::new(t.try_clone()?);
    }
    let t = Arc::get_mut(t).ok_or(AllocationError::SizeOverflow)?;
    let mut target = t.bytes_mut();
    let tr = tc.rect().intersect(&r);
    let span = tr.width() as usize * bpp;
    for y in tr.y0..tr.y1 {
        let src = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * bpp;
        let dst = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * bpp;
        let (Some(d), Some(s)) = (target.get_mut(dst..dst + span), bytes.get(src..src + span)) else { return Err(AllocationError::SizeOverflow) };
        d.copy_from_slice(s);
    }
    Ok(())
}

/// The tiles of an interleaved write, on all cores: each writes only its own bytes.
#[cfg(not(target_arch = "wasm32"))]
fn copy_tiles(tiles: &mut [(TileCoord, Arc<Tile>)], r: Rect, bytes: &[u8], w: usize, bpp: usize) -> Result<(), AllocationError> {
    use rayon::prelude::*;
    tiles.par_iter_mut().try_for_each(|(tc, t)| copy_tile(*tc, t, r, bytes, w, bpp))
}

/// Serial counterpart, for the web build.
#[cfg(target_arch = "wasm32")]
fn copy_tiles(tiles: &mut [(TileCoord, Arc<Tile>)], r: Rect, bytes: &[u8], w: usize, bpp: usize) -> Result<(), AllocationError> {
    tiles.iter_mut().try_for_each(|(tc, t)| copy_tile(*tc, t, r, bytes, w, bpp))
}

/// Fills one tile of [`Surface::try_write_rows_with`]: makes it writable, then calls `fill` for
/// each row of `r` inside it.
fn fill_tile<F, C, E>(slot: &mut (TileCoord, Option<Arc<Tile>>), r: Rect, format: &PixelFormat, default_pixel: &[u8], fill: &F, check: &C) -> Result<(), E>
where
    F: Fn(i32, i32, &mut [u8]) + Sync,
    C: Fn() -> Result<(), E> + Sync,
    E: From<AllocationError> + Send,
{
    check()?;
    let (tc, tile) = slot;
    match tile {
        None => *tile = Some(Arc::new(Tile::try_filled(format, default_pixel)?)),
        Some(t) => {
            if Arc::get_mut(t).is_none() {
                *t = Arc::new(t.try_clone()?);
            }
        }
    }
    let data = tile.as_mut().and_then(Arc::get_mut).ok_or(AllocationError::SizeOverflow)?;
    let mut data = data.bytes_mut();
    let bpp = format.bytes_per_pixel();
    let tr = tc.rect().intersect(&r);
    let span = tr.width() as usize * bpp;
    for y in tr.y0..tr.y1 {
        check()?;
        let row = (y - tc.ty * TILE_SIZE) as usize * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize;
        if let Some(dst) = row.checked_mul(bpp).and_then(|o| data.get_mut(o..o.checked_add(span)?)) {
            fill(y, tr.x0, dst);
        }
    }
    Ok(())
}

#[cfg(not(target_arch = "wasm32"))]
fn fill_tiles<F, C, E>(tiles: &mut [(TileCoord, Option<Arc<Tile>>)], r: Rect, format: &PixelFormat, default_pixel: &[u8], fill: &F, check: &C) -> Result<(), E>
where
    F: Fn(i32, i32, &mut [u8]) + Sync,
    C: Fn() -> Result<(), E> + Sync,
    E: From<AllocationError> + Send,
{
    use rayon::prelude::*;
    tiles.par_iter_mut().try_for_each(|slot| fill_tile(slot, r, format, default_pixel, fill, check))
}

/// Serial counterpart, for the web build.
#[cfg(target_arch = "wasm32")]
fn fill_tiles<F, C, E>(tiles: &mut [(TileCoord, Option<Arc<Tile>>)], r: Rect, format: &PixelFormat, default_pixel: &[u8], fill: &F, check: &C) -> Result<(), E>
where
    F: Fn(i32, i32, &mut [u8]) + Sync,
    C: Fn() -> Result<(), E> + Sync,
    E: From<AllocationError> + Send,
{
    tiles.iter_mut().try_for_each(|slot| fill_tile(slot, r, format, default_pixel, fill, check))
}

fn decode_tile_row_rgba(fmt: &PixelFormat, t: &[u8], base: usize, dst: &mut [[f32; 4]], row: &mut Vec<f32>) {
    let n = fmt.channels();
    match (fmt.mode, fmt.sample, fmt.alpha) {
        (ColorMode::Rgb, SampleType::U8, true) => {
            let src = &t[base..base + dst.len() * 4];
            for (d, s) in dst.iter_mut().zip(src.as_chunks::<4>().0) {
                *d = [s[0] as f32 / 255.0, s[1] as f32 / 255.0, s[2] as f32 / 255.0, s[3] as f32 / 255.0];
            }
        }
        (ColorMode::Grayscale, SampleType::U8, true) => {
            let src = &t[base..base + dst.len() * 2];
            for (d, s) in dst.iter_mut().zip(src.as_chunks::<2>().0) {
                let g = s[0] as f32 / 255.0;
                *d = [g, g, g, s[1] as f32 / 255.0];
            }
        }
        (ColorMode::Rgb, SampleType::U16, true) => {
            let byte_base = base * 2;
            let src = &t[byte_base..byte_base + dst.len() * 8];
            for (d, s) in dst.iter_mut().zip(src.as_chunks::<8>().0) {
                *d = [
                    u16::from_ne_bytes([s[0], s[1]]) as f32 / 65535.0,
                    u16::from_ne_bytes([s[2], s[3]]) as f32 / 65535.0,
                    u16::from_ne_bytes([s[4], s[5]]) as f32 / 65535.0,
                    u16::from_ne_bytes([s[6], s[7]]) as f32 / 65535.0,
                ];
            }
        }
        (ColorMode::Grayscale, SampleType::U16, true) => {
            let byte_base = base * 2;
            let src = &t[byte_base..byte_base + dst.len() * 4];
            for (d, s) in dst.iter_mut().zip(src.as_chunks::<4>().0) {
                let g = u16::from_ne_bytes([s[0], s[1]]) as f32 / 65535.0;
                *d = [g, g, g, u16::from_ne_bytes([s[2], s[3]]) as f32 / 65535.0];
            }
        }
        (ColorMode::Cmyk, SampleType::U8, _) => {
            // Identical ink bytes share the exact ICC result; alpha is independent.
            let mut previous: Option<([u8; 4], [f32; 3])> = None;
            let src = &t[base..base + dst.len() * n];
            for (d, s) in dst.iter_mut().zip(src.chunks_exact(n)) {
                let ink = [s[0], s[1], s[2], s[3]];
                let rgb = match previous {
                    Some((key, rgb)) if key == ink => rgb,
                    _ => {
                        let rgb = photocraft_color::convert::cmyk_to_rgb(ink.map(|v| v as f32 / 255.0));
                        previous = Some((ink, rgb));
                        rgb
                    }
                };
                *d = [rgb[0], rgb[1], rgb[2], s.get(4).map_or(1.0, |v| *v as f32 / 255.0)];
            }
        }
        _ => {
            // The row's samples in one pass, then its colour model resolved once:
            // RGB and grey take their channels as `to_rgba` does, other models go
            // through it.
            row.resize(dst.len() * n, 0.0);
            read_samples(t, fmt.sample, base, row);
            let a = |s: &[f32], i: usize| if fmt.alpha { s[i] } else { 1.0 };
            let pixels = dst.iter_mut().zip(row.chunks_exact(n));
            match fmt.mode {
                ColorMode::Rgb => pixels.for_each(|(d, s)| *d = [s[0], s[1], s[2], a(s, 3)]),
                ColorMode::Grayscale | ColorMode::Bitmap | ColorMode::Duotone => pixels.for_each(|(d, s)| *d = [s[0], s[0], s[0], a(s, 1)]),
                _ => pixels.for_each(|(d, s)| *d = to_rgba(fmt, s)),
            }
        }
    }
}

impl Surface {
    /// Reads a region into a newly allocated buffer, returning an error instead of aborting if
    /// the requested pixel buffer cannot be represented or reserved.
    pub fn try_read_region(&self, r: Rect) -> Result<Vec<f32>, AllocationError> {
        let len = (r.width() as usize).checked_mul(r.height() as usize).and_then(|n| n.checked_mul(self.channels())).ok_or(AllocationError::SizeOverflow)?;
        let bytes = len.checked_mul(std::mem::size_of::<f32>()).ok_or(AllocationError::SizeOverflow)?;
        let mut out = scratch::try_take_exact(len, 0.0f32).ok_or(AllocationError::NotEnoughMemory { bytes })?;
        let generation = spill::read_error_generation();
        self.read_region_into(r, &mut out);
        spill::check_since(generation).map_err(AllocationError::ScratchRead)?;
        self.region_health(r).map_err(AllocationError::ScratchRead)?;
        Ok(out)
    }

    /// `Err` if any stored tile of this surface is unreadable. Free when no tile in the
    /// process has failed.
    pub fn scratch_health(&self) -> Result<(), String> {
        if !spill::any_failed() {
            return Ok(());
        }
        self.tiles.values().try_for_each(|t| t.scratch_health())
    }

    /// [`Surface::scratch_health`] for the tiles overlapping `r` only.
    pub fn region_health(&self, r: Rect) -> Result<(), String> {
        if !spill::any_failed() {
            return Ok(());
        }
        r.tiles().filter_map(|c| self.tiles.get(&c)).try_for_each(|t| t.scratch_health())
    }

    /// Reads a region as encoded interleaved bytes with fallible allocation.
    pub fn try_to_interleaved(&self, r: Rect) -> Result<Vec<u8>, AllocationError> {
        let bpp = self.format.bytes_per_pixel();
        let len = (r.width() as usize).checked_mul(r.height() as usize).and_then(|n| n.checked_mul(bpp)).ok_or(AllocationError::SizeOverflow)?;
        let mut out = Vec::new();
        out.try_reserve_exact(len).map_err(|_| AllocationError::NotEnoughMemory { bytes: len })?;
        out.resize(len, 0);
        let w = r.width() as usize;
        for tc in r.tiles() {
            let tr = tc.rect().intersect(&r);
            let span = tr.width() as usize * bpp;
            for y in tr.y0..tr.y1 {
                let dst = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * bpp;
                match self.tiles.get(&tc) {
                    Some(t) => {
                        let src = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * bpp;
                        out[dst..dst + span].copy_from_slice(&t.try_bytes().map_err(AllocationError::ScratchRead)?[src..src + span]);
                    }
                    None => {
                        for px in out[dst..dst + span].chunks_exact_mut(bpp) {
                            px.copy_from_slice(&self.default_pixel);
                        }
                    }
                }
            }
        }
        Ok(out)
    }

    /// Transparent/zero surface.
    pub fn new(format: PixelFormat) -> Self {
        Self { format, default_pixel: vec![0u8; format.bytes_per_pixel()].into_boxed_slice(), tiles: BTreeMap::new() }
    }

    /// Surface whose untouched pixels read as `pixel` (normalised channel values).
    pub fn with_default(format: PixelFormat, pixel: &[f32]) -> Self {
        let mut s = Self::new(format);
        encode_pixel(&format, pixel, &mut s.default_pixel);
        s
    }

    pub fn format(&self) -> PixelFormat {
        self.format
    }
    pub fn channels(&self) -> usize {
        self.format.channels()
    }
    pub fn tile_count(&self) -> usize {
        self.tiles.len()
    }
    pub fn tiles(&self) -> impl Iterator<Item = (&TileCoord, &Arc<Tile>)> {
        self.tiles.iter()
    }
    pub fn tile(&self, c: TileCoord) -> Option<&Arc<Tile>> {
        self.tiles.get(&c)
    }
    pub fn default_pixel(&self) -> Vec<f32> {
        decode_pixel(&self.format, &self.default_pixel)
    }

    /// Decode the default pixel, using dynamic storage only when the stack buffer is too small.
    fn default_samples<'a>(&self, stack: &'a mut [f32], heap: &'a mut Vec<f32>) -> &'a mut [f32] {
        let px = sample_buffer(self.channels(), stack, heap);
        for (i, v) in px.iter_mut().enumerate() {
            *v = read_sample(&self.default_pixel, self.format.sample, i);
        }
        px
    }

    /// Mutable access to a tile, allocating it (filled with the default pixel) or un-sharing it.
    pub fn tile_mut(&mut self, c: TileCoord) -> &mut Tile {
        let fmt = self.format;
        let dp = &self.default_pixel;
        let arc = self.tiles.entry(c).or_insert_with(|| Arc::new(Tile::filled(&fmt, dp)));
        Arc::make_mut(arc)
    }

    /// Fallible counterpart to [`Surface::tile_mut`]. Pixel storage is reserved before changing
    /// the surface, and a shared tile is copied only after its replacement has been allocated.
    pub fn try_tile_mut(&mut self, c: TileCoord) -> Result<&mut Tile, AllocationError> {
        if let Some(tile) = self.tiles.get(&c) {
            drop(tile.try_bytes().map_err(AllocationError::ScratchRead)?);
        }
        if !self.tiles.contains_key(&c) {
            let tile = Arc::new(Tile::try_filled(&self.format, &self.default_pixel)?);
            self.tiles.insert(c, tile);
        } else if self.tiles.get_mut(&c).is_some_and(|t| Arc::get_mut(t).is_none()) {
            let original = self.tiles.remove(&c).ok_or(AllocationError::SizeOverflow)?;
            let tile = match Arc::try_unwrap(original) {
                // Weak cache references must not force a pixel-buffer copy.
                Ok(tile) => tile,
                Err(original) => match original.try_clone() {
                    Ok(tile) => tile,
                    Err(error) => {
                        self.tiles.insert(c, original);
                        return Err(error);
                    }
                },
            };
            self.tiles.insert(c, Arc::new(tile));
        }
        self.tiles.get_mut(&c).and_then(Arc::get_mut).ok_or(AllocationError::SizeOverflow)
    }

    /// Writes a region using fallible pixel-tile allocations. Callers that need transactional
    /// document updates should perform this on their staged document copy and commit on success.
    pub fn try_write_region(&mut self, r: Rect, data: &[f32]) -> Result<(), AllocationError> {
        let n = self.channels();
        let sample = self.format.sample;
        let expected = (r.width() as usize).checked_mul(r.height() as usize).and_then(|v| v.checked_mul(n)).ok_or(AllocationError::SizeOverflow)?;
        if data.len() != expected {
            return Err(AllocationError::SizeOverflow);
        }
        for tc in r.tiles() {
            let tr = tc.rect().intersect(&r);
            let t = self.try_tile_mut(tc)?;
            let mut target = t.bytes_mut();
            let span = tr.width() as usize * n;
            for y in tr.y0..tr.y1 {
                let src = (((y - r.y0) as usize) * r.width() as usize + (tr.x0 - r.x0) as usize) * n;
                let dst = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
                for (i, v) in data[src..src + span].iter().enumerate() {
                    write_sample(&mut target, sample, dst + i, *v);
                }
            }
        }
        Ok(())
    }

    /// Tile rects that differ between `self` and `other`: tiles present in only one, or holding
    /// a different (copied-on-write) tile. Compares pointers, never pixels, so it is cheap and
    /// never reads spilled tiles back. `None` when the format or default pixel differ (every
    /// pixel may read differently).
    pub fn changed_rect(&self, other: &Surface) -> Option<Rect> {
        if self.format != other.format || self.default_pixel != other.default_pixel {
            return None;
        }
        let mut r = Rect::EMPTY;
        for (c, t) in &self.tiles {
            if other.tiles.get(c).is_none_or(|o| !Arc::ptr_eq(t, o)) {
                r = r.union(&c.rect());
            }
        }
        for c in other.tiles.keys() {
            if !self.tiles.contains_key(c) {
                r = r.union(&c.rect());
            }
        }
        Some(r)
    }

    /// Coarse bounds: union of allocated tile rects.
    pub fn tile_bounds(&self) -> Rect {
        self.tiles.keys().fold(Rect::EMPTY, |r, c| r.union(&c.rect()))
    }

    /// Exact bounds of pixels that differ from the default pixel.
    pub fn content_bounds(&self) -> Rect {
        if self.tiles.is_empty() {
            return Rect::EMPTY;
        }
        // Scan tiles from the outside of the tile grid inwards; a tile lying entirely inside the
        // bounds found so far cannot extend them and is skipped (so a full-canvas selection scans
        // roughly its outer ring of tiles instead of every pixel).
        let (mut gx0, mut gy0, mut gx1, mut gy1) = (i32::MAX, i32::MAX, i32::MIN, i32::MIN);
        for c in self.tiles.keys() {
            (gx0, gy0, gx1, gy1) = (gx0.min(c.tx), gy0.min(c.ty), gx1.max(c.tx), gy1.max(c.ty));
        }
        let mut order: Vec<(&TileCoord, &Arc<Tile>)> = self.tiles.iter().collect();
        order.sort_by_key(|(c, _)| (c.tx - gx0).min(gx1 - c.tx).min(c.ty - gy0).min(gy1 - c.ty));
        let mut out = Rect::EMPTY;
        for (c, t) in order {
            let origin = c.rect();
            if !out.is_empty() && out.contains_rect(&origin) {
                continue;
            }
            if let Some((x0, y0, x1, y1)) = t.content_bounds(&self.default_pixel) {
                out = out.union(&Rect::new(x0.into(), y0.into(), x1.into(), y1.into()).translate(origin.x0, origin.y0));
            }
        }
        out
    }

    /// Makes every tile that holds one pixel value throughout share the interner's tile for that
    /// value: a white background, an opaque mask or a solid fill then costs one tile however
    /// large it is, and across every surface that shares `interner`. Tiles are copy-on-write, so
    /// editing one splits it off again. Returns the bytes no longer held by this surface alone.
    pub fn share_uniform_tiles(&mut self, interner: &mut TileInterner) -> usize {
        let bpp = self.format.bytes_per_pixel();
        let mut saved = 0;
        for t in self.tiles.values_mut() {
            let Ok(bytes) = t.try_bytes() else { continue };
            let mut px = bytes.chunks_exact(bpp);
            let Some(p0) = px.next() else { continue };
            if !px.all(|p| p == p0) {
                continue;
            }
            let p0 = p0.to_vec();
            drop(bytes);
            let shared = interner.tiles.entry(t.len()).or_default().entry(p0).or_insert_with(|| t.clone());
            if !Arc::ptr_eq(shared, t) {
                saved += t.len();
                *t = shared.clone();
            }
        }
        saved
    }

    /// Drop tiles that are entirely the default pixel.
    pub fn prune(&mut self) {
        let dp = self.default_pixel.as_ref();
        let bpp = dp.len();
        self.tiles.retain(|_, t| t.bytes().chunks_exact(bpp).any(|px| px != dp));
    }

    /// A [`PruneCursor`] for [`Surface::prune_batch`], which drops the same tiles as [`Surface::prune`]
    /// a batch at a time (for a caller that must not block: the web build has no threads).
    pub fn prune_cursor(&self) -> PruneCursor {
        PruneCursor::default()
    }

    /// Drops the tiles that are entirely the default pixel, visiting at most `max` tiles in
    /// coordinate order and resuming after them on the next call; returns true when every tile
    /// has been visited (and so [`Surface::prune`] has nothing left to drop). A `max` of zero
    /// visits one tile. The scan reads the live tile map from the cursor on: a tile inserted at or
    /// before the last visited coordinate is not visited, one inserted after it is (and dropped
    /// when it holds only the default pixel, which reads the same as an absent tile).
    pub fn prune_batch(&mut self, cursor: &mut PruneCursor, max: usize) -> bool {
        if cursor.done {
            return true;
        }
        let dp = self.default_pixel.as_ref();
        let bpp = dp.len();
        let max = max.max(1);
        let keys: Vec<TileCoord> = match cursor.after {
            None => self.tiles.keys().take(max).copied().collect(),
            Some(after) => self.tiles.range((Bound::Excluded(after), Bound::Unbounded)).take(max).map(|(c, _)| *c).collect(),
        };
        for c in &keys {
            if self.tiles.get(c).is_some_and(|t| !t.bytes().chunks_exact(bpp).any(|px| px != dp)) {
                self.tiles.remove(c);
            }
        }
        let Some(last) = keys.last().copied() else {
            cursor.done = true;
            return true;
        };
        cursor.after = Some(last);
        cursor.done = keys.len() < max || self.tiles.range((Bound::Excluded(last), Bound::Unbounded)).next().is_none();
        cursor.done
    }

    #[inline]
    fn locate(&self, x: i32, y: i32) -> (TileCoord, usize) {
        let c = TileCoord::containing(x, y);
        let lx = x.rem_euclid(TILE_SIZE) as usize;
        let ly = y.rem_euclid(TILE_SIZE) as usize;
        (c, (ly * TILE_SIZE as usize + lx) * self.format.channels())
    }

    /// Read one pixel as normalised channel values (`channels()` floats).
    pub fn pixel(&self, x: i32, y: i32) -> Vec<f32> {
        let mut out = vec![0.0; self.channels()];
        self.read_pixel(x, y, &mut out);
        out
    }

    pub fn read_pixel(&self, x: i32, y: i32, out: &mut [f32]) {
        let (c, base) = self.locate(x, y);
        let n = self.channels();
        match self.tiles.get(&c) {
            Some(t) => {
                let data = t.bytes();
                for (i, o) in out.iter_mut().enumerate().take(n) {
                    *o = read_sample(&data, self.format.sample, base + i);
                }
            }
            None => {
                for (i, o) in out.iter_mut().enumerate().take(n) {
                    *o = read_sample(&self.default_pixel, self.format.sample, i);
                }
            }
        }
    }

    pub fn write_pixel(&mut self, x: i32, y: i32, px: &[f32]) {
        let (c, base) = self.locate(x, y);
        let n = self.channels();
        let sample = self.format.sample;
        let mut t = self.tile_mut(c).bytes_mut();
        for (i, v) in px.iter().enumerate().take(n) {
            write_sample(&mut t, sample, base + i, *v);
        }
    }

    /// One channel of one pixel, without allocating.
    #[inline]
    pub fn sample_channel(&self, x: i32, y: i32, c: usize) -> f32 {
        let (tc, base) = self.locate(x, y);
        match self.tiles.get(&tc) {
            Some(t) => read_sample(&t.bytes(), self.format.sample, base + c),
            None => read_sample(&self.default_pixel, self.format.sample, c),
        }
    }

    /// Channel `c` at `(x0 + i·step, y)` for `i in 0..out.len()`, looking each tile up once per run
    /// (much faster than per-sample [`Surface::sample_channel`] for strided scans).
    /// Steps below 1 read consecutive pixels; positions beyond `i32::MAX` read the default pixel.
    pub fn sample_row_strided(&self, y: i32, x0: i32, step: i32, c: usize, out: &mut [f32]) {
        let step = i64::from(step.max(1));
        let dp = read_sample(&self.default_pixel, self.format.sample, c);
        let n = self.format.channels();
        let ty = y.div_euclid(TILE_SIZE);
        let ly = y.rem_euclid(TILE_SIZE) as usize;
        let mut i = 0;
        let mut x = i64::from(x0);
        while i < out.len() {
            if x > i64::from(i32::MAX) {
                out[i..].fill(dp);
                break;
            }
            let tx = x.div_euclid(i64::from(TILE_SIZE));
            // Samples that fall in this tile.
            let tile_end = (tx + 1) * i64::from(TILE_SIZE);
            let count = (((tile_end - x) + step - 1) / step).max(1) as usize;
            let count = count.min(out.len() - i);
            let end = i + count;
            match self.tiles.get(&TileCoord { tx: tx as i32, ty }) {
                None => out[i..end].fill(dp),
                Some(t) => {
                    let data = t.bytes();
                    for (k, o) in out[i..end].iter_mut().enumerate() {
                        let lx = (x + k as i64 * step - tx * i64::from(TILE_SIZE)) as usize;
                        *o = read_sample(&data, self.format.sample, (ly * TILE_SIZE as usize + lx) * n + c);
                    }
                }
            }
            i = end;
            x += count as i64 * step;
        }
    }

    /// [`Surface::read_region`] into a reusable buffer (resized to fit).
    pub fn read_region_into(&self, r: Rect, out: &mut Vec<f32>) {
        let n = self.channels();
        let w = r.width() as usize;
        out.clear();
        out.resize(w * r.height() as usize * n, 0.0);
        self.read_samples_into(r, out);
    }

    /// Copy samples into a zero-initialized buffer sized for `r`.
    fn read_samples_into(&self, r: Rect, out: &mut [f32]) {
        let n = self.channels();
        let w = r.width() as usize;
        let mut stack = [0.0; 8];
        let mut heap = Vec::new();
        let dp = self.default_samples(&mut stack, &mut heap);
        let zero = self.default_pixel.iter().all(|&b| b == 0);
        for tc in r.tiles() {
            let tr = tc.rect().intersect(&r);
            let guard = self.tiles.get(&tc).map(|t| t.bytes());
            if guard.is_none() && zero {
                continue;
            }
            let tile = guard.as_deref();
            for y in tr.y0..tr.y1 {
                let o = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * n;
                let span = tr.width() as usize * n;
                let Some(dst) = out.get_mut(o..o + span) else { continue };
                match tile {
                    Some(t) => {
                        let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
                        read_samples(t, self.format.sample, base, dst);
                    }
                    None if n == 1 => dst.fill(dp[0]),
                    None => {
                        for px in dst.chunks_exact_mut(n) {
                            px.copy_from_slice(dp);
                        }
                    }
                }
            }
        }
    }

    /// Reads `r` as straight RGBA floats (converting from the surface's
    /// model) into `out` (`w*h` entries), without per-pixel allocation.
    /// Fast paths for RGB(A) and gray(A) at 8/16/32 bits read tile bytes
    /// directly; missing tiles are filled with the default pixel.
    pub fn read_rgba_into(&self, r: Rect, out: &mut [[f32; 4]]) {
        let w = r.width() as usize;
        debug_assert_eq!(out.len(), w * r.height() as usize);
        let fmt = self.format;
        let n = fmt.channels();
        let mut stack = [0.0; 8];
        let mut heap = Vec::new();
        let dp = to_rgba(&fmt, self.default_samples(&mut stack, &mut heap));
        let mut row = Vec::new();
        for tc in r.tiles() {
            let tr = tc.rect().intersect(&r);
            let guard = self.tiles.get(&tc).map(|t| t.bytes());
            let tile = guard.as_deref();
            for y in tr.y0..tr.y1 {
                let o = ((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize;
                let dst = &mut out[o..o + tr.width() as usize];
                let Some(t) = tile else {
                    dst.fill(dp);
                    continue;
                };
                let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
                decode_tile_row_rgba(&fmt, t, base, dst, &mut row);
            }
        }
    }

    /// Reads `r` as straight 8-bit RGBA into `out` (`w*h` entries). RGBA8 surfaces copy tile bytes
    /// directly; other formats convert while holding the same tile read guard.
    pub fn read_rgba8_into(&self, r: Rect, out: &mut [[u8; 4]]) {
        let w = r.width() as usize;
        debug_assert_eq!(out.len(), w * r.height() as usize);
        let fmt = self.format;
        let rgba8 = matches!((fmt.mode, fmt.sample, fmt.alpha), (ColorMode::Rgb, SampleType::U8, true));
        let q = |v: f32| (v.clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
        let mut stack = [0.0; 8];
        let mut heap = Vec::new();
        let dp = to_rgba(&fmt, self.default_samples(&mut stack, &mut heap));
        let dp8 = [q(dp[0]), q(dp[1]), q(dp[2]), q(dp[3])];
        let mut px = [0.0f32; 8];
        for tc in r.tiles() {
            let tr = tc.rect().intersect(&r);
            let guard = self.tiles.get(&tc).map(|t| t.bytes());
            let tile = guard.as_deref();
            for y in tr.y0..tr.y1 {
                let o = ((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize;
                let dst = &mut out[o..o + tr.width() as usize];
                match tile {
                    None => dst.fill(dp8),
                    Some(t) if rgba8 => {
                        let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * 4;
                        let len = dst.len();
                        for (d, s) in dst.iter_mut().zip(t[base..base + len * 4].as_chunks::<4>().0) {
                            *d = [s[0], s[1], s[2], s[3]];
                        }
                    }
                    Some(t) => {
                        // A second read lock could deadlock behind an eviction writer.
                        let n = fmt.channels();
                        let base = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * n;
                        for (i, d) in dst.iter_mut().enumerate() {
                            for (c, v) in px.iter_mut().enumerate().take(n) {
                                *v = read_sample(t, fmt.sample, base + i * n + c);
                            }
                            let p = to_rgba(&fmt, &px[..n]);
                            *d = [q(p[0]), q(p[1]), q(p[2]), q(p[3])];
                        }
                    }
                }
            }
        }
    }

    /// `true` if any allocated tile intersects `r` (else `r` reads as the
    /// default pixel everywhere).
    pub fn has_tiles_in(&self, r: Rect) -> bool {
        r.tiles().any(|tc| self.tiles.contains_key(&tc))
    }

    /// Read a rectangle as interleaved normalised floats (`w*h*channels`).
    pub fn read_region(&self, r: Rect) -> Vec<f32> {
        let n = self.channels();
        let w = r.width() as usize;
        let mut out = scratch::take(w * r.height() as usize * n, 0.0f32);
        self.read_samples_into(r, &mut out);
        out
    }

    /// Write interleaved normalised floats into a rectangle, on the calling thread.
    ///
    /// This never enters Rayon, so it is safe inside a `OnceLock` initializer or any other
    /// section that must not run another Rayon job on its stack. [`Surface::write_region_par`]
    /// writes the same bytes on all cores.
    pub fn write_region(&mut self, r: Rect, data: &[f32]) {
        let n = self.channels();
        let w = r.width() as usize;
        assert_eq!(data.len(), w * r.height() as usize * n, "region data length mismatch");
        let sample = self.format.sample;
        for tc in r.tiles() {
            write_tile(self.tile_mut(tc), tc, r, data, w, n, sample);
        }
    }

    /// [`Surface::write_region`] with the tiles converted on all cores (serially on the web).
    ///
    /// This enters Rayon: while it waits for its tiles, the calling worker may run any other
    /// queued Rayon job. Callers inside a `OnceLock` initializer or another section that must
    /// not do that use [`Surface::write_region`].
    pub fn write_region_par(&mut self, r: Rect, data: &[f32]) {
        let n = self.channels();
        let w = r.width() as usize;
        assert_eq!(data.len(), w * r.height() as usize * n, "region data length mismatch");
        let sample = self.format.sample;
        // The tiles are disjoint, so converting them in any order (and on any thread) writes
        // exactly the same bytes. `take_tiles` gives the missing tiles as one shared
        // default-filled tile, copied per tile by `Arc::make_mut` in `convert_tiles`.
        let mut tiles = self.take_tiles(r);
        convert_tiles(&mut tiles, r, data, w, n, sample);
        self.put_tiles(tiles);
    }

    /// Take the tiles covering `r` out of the surface (missing ones filled with the default
    /// pixel), so they can be edited elsewhere, e.g. in parallel: `Arc::unwrap_or_clone` copies a
    /// tile only if an undo snapshot still shares it. Give them back with [`Surface::put_tiles`].
    pub fn take_tiles(&mut self, r: Rect) -> Vec<(TileCoord, Arc<Tile>)> {
        let fmt = self.format;
        let mut blank: Option<Arc<Tile>> = None;
        r.tiles()
            .map(|c| {
                let t = self.tiles.remove(&c).unwrap_or_else(|| blank.get_or_insert_with(|| Arc::new(Tile::filled(&fmt, &self.default_pixel))).clone());
                (c, t)
            })
            .collect()
    }

    /// Fallible counterpart to [`Surface::take_tiles`]. Reserves the complete result and any
    /// default tile before removing a tile, so a reservation failure leaves the surface intact.
    pub fn try_take_tiles(&mut self, r: Rect) -> Result<Vec<(TileCoord, Arc<Tile>)>, AllocationError> {
        // Counted in u64 and checked before narrowing: on 32-bit targets the grid of a sparse
        // surface's bounds can pass `usize` (and visiting it to count it takes just as long).
        let count = usize::try_from(r.tile_count()).map_err(|_| AllocationError::SizeOverflow)?;
        let bytes = count.checked_mul(std::mem::size_of::<(TileCoord, Arc<Tile>)>()).ok_or(AllocationError::SizeOverflow)?;
        let mut out = Vec::new();
        out.try_reserve_exact(count).map_err(|_| AllocationError::NotEnoughMemory { bytes })?;
        let has_missing = r.tiles().any(|c| !self.tiles.contains_key(&c));
        let blank = if has_missing { Some(Arc::new(Tile::try_filled(&self.format, &self.default_pixel)?)) } else { None };
        for c in r.tiles() {
            let tile = self.tiles.remove(&c).or_else(|| blank.clone());
            if let Some(tile) = tile {
                out.push((c, tile));
            }
        }
        Ok(out)
    }

    /// Put tiles back (see [`Surface::take_tiles`]); each replaces the tile at its coordinate.
    pub fn put_tiles(&mut self, tiles: impl IntoIterator<Item = (TileCoord, Arc<Tile>)>) {
        for (c, t) in tiles {
            self.tiles.insert(c, t);
        }
    }

    /// A tile filled with the default pixel (what a missing tile reads as), allocated fallibly.
    pub fn try_default_tile(&self) -> Result<Tile, AllocationError> {
        Tile::try_filled(&self.format, &self.default_pixel)
    }

    /// A tile of this surface's format filled with `px` (normalised channel values). Sharing one
    /// across many coordinates fills them without copying (tiles are copy-on-write).
    pub fn solid_tile(&self, px: &[f32]) -> Arc<Tile> {
        let mut enc = vec![0u8; self.format.bytes_per_pixel()];
        encode_pixel(&self.format, px, &mut enc);
        Arc::new(Tile::filled(&self.format, &enc))
    }

    /// The default pixel's encoded bytes.
    pub fn default_bytes(&self) -> &[u8] {
        &self.default_pixel
    }

    /// Fill a rectangle with one pixel value.
    pub fn fill_rect(&mut self, r: Rect, px: &[f32]) {
        let n = self.channels();
        let mut enc = vec![0u8; self.format.bytes_per_pixel()];
        encode_pixel(&self.format, &px[..n], &mut enc);
        let bpp = enc.len();
        // Fully covered tiles share one Arc: a solid fill costs one tile however large `r` is,
        // and copy-on-write splits a tile off when it is edited (#705).
        let mut full: Option<Arc<Tile>> = None;
        for tc in r.tiles() {
            let tr = tc.rect().intersect(&r);
            if tr == tc.rect() {
                let fmt = self.format;
                let t = full.get_or_insert_with(|| Arc::new(Tile::filled(&fmt, &enc)));
                self.tiles.insert(tc, t.clone());
                continue;
            }
            let mut t = self.tile_mut(tc).bytes_mut();
            for y in tr.y0..tr.y1 {
                let ly = (y - tc.ty * TILE_SIZE) as usize;
                let lx0 = (tr.x0 - tc.tx * TILE_SIZE) as usize;
                let lx1 = (tr.x1 - tc.tx * TILE_SIZE) as usize;
                let row = &mut t[(ly * TILE_SIZE as usize + lx0) * bpp..(ly * TILE_SIZE as usize + lx1) * bpp];
                for p in row.chunks_exact_mut(bpp) {
                    p.copy_from_slice(&enc);
                }
            }
        }
    }

    /// Build from interleaved *encoded* bytes of `format` covering `r`.
    pub fn from_interleaved(format: PixelFormat, r: Rect, bytes: &[u8]) -> Self {
        let mut s = Surface::new(format);
        s.write_interleaved(r, bytes);
        s
    }

    /// Write interleaved encoded bytes (same format as the surface) into `r`.
    pub fn write_interleaved(&mut self, r: Rect, bytes: &[u8]) {
        let bpp = self.format.bytes_per_pixel();
        let w = r.width() as usize;
        assert_eq!(bytes.len(), w * r.height() as usize * bpp, "interleaved length mismatch");
        for tc in r.tiles() {
            let tr = tc.rect().intersect(&r);
            let mut t = self.tile_mut(tc).bytes_mut();
            let span = tr.width() as usize * bpp;
            for y in tr.y0..tr.y1 {
                let src = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * bpp;
                let dst = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * bpp;
                t[dst..dst + span].copy_from_slice(&bytes[src..src + span]);
            }
        }
    }

    /// Fallible counterpart to [`Surface::write_interleaved`], writing the tiles on all cores
    /// (native targets): a length that doesn't match `r` is [`AllocationError::LengthMismatch`],
    /// not a panic, and a tile that can't be allocated stops the write with
    /// [`AllocationError::NotEnoughMemory`] (the tiles written so far keep their new pixels).
    ///
    /// This enters Rayon, as [`Surface::write_region_par`] does.
    pub fn try_write_interleaved(&mut self, r: Rect, bytes: &[u8]) -> Result<(), AllocationError> {
        let bpp = self.format.bytes_per_pixel();
        let w = r.width() as usize;
        let expected = w.checked_mul(r.height() as usize).and_then(|v| v.checked_mul(bpp)).ok_or(AllocationError::SizeOverflow)?;
        if bytes.len() != expected {
            return Err(AllocationError::LengthMismatch { expected, got: bytes.len() });
        }
        let mut tiles = self.try_take_tiles(r)?;
        let written = copy_tiles(&mut tiles, r, bytes, w, bpp);
        self.put_tiles(tiles);
        written
    }

    /// Fills `r` row by row, straight into the tiles: `fill(y, x0, dst)` writes the pixels of row
    /// `y` from column `x0` into `dst`, the tile's bytes for that span (`dst.len()` is a whole
    /// number of pixels in the surface's format). Lets a caller convert from its own buffer
    /// without staging a copy of the region first.
    ///
    /// Tiles are filled on all cores (serially on the web), so `fill` must not depend on call
    /// order. Missing tiles start as the default pixel; existing tiles are copied fallibly so
    /// the surface is unchanged if preparation fails. An empty `r` writes nothing.
    ///
    /// Like [`Surface::write_region_par`] this enters Rayon, so don't call it from a `OnceLock`
    /// initializer.
    pub fn try_write_rows_with<F>(&mut self, r: Rect, fill: F) -> Result<(), AllocationError>
    where
        F: Fn(i32, i32, &mut [u8]) + Sync,
    {
        self.try_prepare_rows(r, |tiles, format, default_pixel| fill_tiles(tiles, r, format, default_pixel, &fill, &|| Ok(())))
    }

    /// Interruptible row write. Cancellation or allocation failure leaves the surface unchanged.
    /// Checks run before each tile and row; already running callbacks may finish after cancellation.
    pub fn try_write_rows_with_interrupt<F>(&mut self, r: Rect, ctl: &Interrupt, fill: F) -> Result<(), RowWriteError>
    where
        F: Fn(i32, i32, &mut [u8]) + Sync,
    {
        self.try_prepare_rows(r, |tiles, format, default_pixel| {
            fill_tiles(tiles, r, format, default_pixel, &fill, &|| ctl.check().map_err(RowWriteError::Cancelled))
        })
    }

    fn try_prepare_rows<F, E>(&mut self, r: Rect, prepare: F) -> Result<(), E>
    where
        F: FnOnce(&mut [(TileCoord, Option<Arc<Tile>>)], &PixelFormat, &[u8]) -> Result<(), E>,
        E: From<AllocationError>,
    {
        if r.is_empty() {
            return Ok(());
        }
        let count = usize::try_from(r.tile_count()).map_err(|_| AllocationError::SizeOverflow)?;
        let bytes = count.checked_mul(std::mem::size_of::<(TileCoord, Option<Arc<Tile>>)>()).ok_or(AllocationError::SizeOverflow)?;
        let mut tiles: Vec<(TileCoord, Option<Arc<Tile>>)> = Vec::new();
        tiles.try_reserve_exact(count).map_err(|_| AllocationError::NotEnoughMemory { bytes })?;
        tiles.extend(r.tiles().map(|c| (c, self.tiles.get(&c).cloned())));
        prepare(&mut tiles, &self.format, &self.default_pixel)?;
        for (c, tile) in tiles {
            if let Some(tile) = tile {
                if let Some(existing) = self.tiles.get_mut(&c) {
                    *existing = tile;
                } else {
                    self.tiles.insert(c, tile);
                }
            }
        }
        Ok(())
    }

    /// Read `r` as interleaved encoded bytes in the surface's format.
    pub fn to_interleaved(&self, r: Rect) -> Vec<u8> {
        let bpp = self.format.bytes_per_pixel();
        let w = r.width() as usize;
        let mut out = scratch::take(w * r.height() as usize * bpp, 0u8);
        for tc in r.tiles() {
            let tr = tc.rect().intersect(&r);
            let span = tr.width() as usize * bpp;
            for y in tr.y0..tr.y1 {
                let dst = (((y - r.y0) as usize) * w + (tr.x0 - r.x0) as usize) * bpp;
                match self.tiles.get(&tc).map(|t| t.bytes()) {
                    Some(t) => {
                        let src = (((y - tc.ty * TILE_SIZE) as usize) * TILE_SIZE as usize + (tr.x0 - tc.tx * TILE_SIZE) as usize) * bpp;
                        out[dst..dst + span].copy_from_slice(&t[src..src + span]);
                    }
                    None => {
                        for p in out[dst..dst + span].chunks_exact_mut(bpp) {
                            p.copy_from_slice(&self.default_pixel);
                        }
                    }
                }
            }
        }
        out
    }

    /// The surface moved by whole pixels: its encoded samples copied tile to tile (no float
    /// round trip, no intermediate buffer); moves by whole tiles share the tiles themselves, and
    /// a target tile read entirely from tiles of one single pixel value shares one such tile (the
    /// inside of a solid fill stays one copy-on-write tile however often it moves). A tile it
    /// copies that ends up holding only the default pixel isn't stored.
    /// `content` must hold every pixel that isn't the default one (`content_bounds`, say): only
    /// tiles it reaches are kept.
    pub fn translated(&self, dx: i32, dy: i32, content: Rect) -> Surface {
        let mut out = Surface { format: self.format, default_pixel: self.default_pixel.clone(), tiles: BTreeMap::new() };
        let sources = || self.tiles.iter().filter(move |(c, _)| !c.rect().intersect(&content).is_empty());
        if dx % TILE_SIZE == 0 && dy % TILE_SIZE == 0 {
            let (tx, ty) = (dx / TILE_SIZE, dy / TILE_SIZE);
            out.tiles = sources().map(|(c, t)| (TileCoord::new(c.tx.saturating_add(tx), c.ty.saturating_add(ty)), t.clone())).collect();
            return out;
        }
        let mut builder = shift::ShiftBuilder::new(self, dx, dy, content);
        for (_, t) in sources() {
            builder.scan(t);
        }
        let targets = builder.targets(self);
        let build_target = |dc: TileCoord| builder.build(self, dc);
        #[cfg(not(target_arch = "wasm32"))]
        {
            use rayon::prelude::*;
            out.tiles = targets.into_par_iter().filter_map(build_target).collect();
        }
        #[cfg(target_arch = "wasm32")]
        {
            out.tiles = targets.into_iter().filter_map(build_target).collect();
        }
        out
    }

    /// Applies `f` to every colour sample (not alpha), including the default pixel: a tone-curve
    /// change such as linearising when a document becomes 32-bit.
    pub fn map_color(&mut self, f: impl Fn(f32) -> f32) {
        let format = self.format;
        let color = format.mode.color_channels();
        let n = format.channels();
        let mut dp = decode_pixel(&format, &self.default_pixel);
        for v in dp.iter_mut().take(color) {
            *v = f(*v);
        }
        encode_pixel(&format, &dp, &mut self.default_pixel);
        let coords: Vec<TileCoord> = self.tiles.keys().copied().collect();
        let px_count = (TILE_SIZE * TILE_SIZE) as usize;
        // A tile shared by several coordinates (a filled background) is mapped once and stays
        // shared (#4531). Keys are the original tiles, all alive until their coordinates are
        // reached, so a freed address can't be mistaken for another original.
        let mut done: std::collections::HashMap<*const Tile, Arc<Tile>> = std::collections::HashMap::new();
        for c in coords {
            let Some(key) = self.tiles.get(&c).map(Arc::as_ptr) else { continue };
            if let Some(mapped) = done.get(&key) {
                self.tiles.insert(c, mapped.clone());
                continue;
            }
            let tile = self.tile_mut(c);
            let mut bytes = tile.bytes_mut();
            for i in 0..px_count {
                for k in 0..color {
                    let at = i * n + k;
                    let v = read_sample(&bytes, format.sample, at);
                    write_sample(&mut bytes, format.sample, at, f(v));
                }
            }
            drop(bytes);
            if let Some(mapped) = self.tiles.get(&c) {
                done.insert(key, mapped.clone());
            }
        }
    }

    /// Convert to another pixel format (depth and/or model; colour models via [`convert_pixel`]).
    pub fn convert(&self, to: PixelFormat) -> Surface {
        let mut out = Surface::with_default(to, &convert_pixel(&self.format, &to, &self.default_pixel()));
        let from_n = self.channels();
        let mut src = vec![0.0f32; from_n];
        // Each distinct tile converts once; coordinates sharing it share the result (#4531).
        let mut done: std::collections::HashMap<*const Tile, Arc<Tile>> = std::collections::HashMap::new();
        for (c, t) in &self.tiles {
            if let Some(converted) = done.get(&Arc::as_ptr(t)) {
                out.tiles.insert(*c, converted.clone());
                continue;
            }
            let source = t.bytes();
            let mut dst = out.tile_mut(*c).bytes_mut();
            let px_count = (TILE_SIZE * TILE_SIZE) as usize;
            for i in 0..px_count {
                for (k, v) in src.iter_mut().enumerate() {
                    *v = read_sample(&source, self.format.sample, i * from_n + k);
                }
                let px = convert_pixel(&self.format, &to, &src);
                for (k, v) in px.iter().enumerate() {
                    write_sample(&mut dst, to.sample, i * to.channels() + k, *v);
                }
            }
            drop(dst);
            if let Some(converted) = out.tiles.get(c) {
                done.insert(Arc::as_ptr(t), converted.clone());
            }
        }
        out
    }

    /// Convert a surface while reserving each replacement tile fallibly.
    pub fn try_convert(&self, to: PixelFormat) -> Result<Surface, AllocationError> {
        let mut out = Surface::with_default(to, &convert_pixel(&self.format, &to, &self.default_pixel()));
        let from_n = self.channels();
        let mut src = Vec::new();
        src.try_reserve_exact(from_n).map_err(|_| AllocationError::NotEnoughMemory { bytes: from_n * std::mem::size_of::<f32>() })?;
        src.resize(from_n, 0.0f32);
        let mut done: std::collections::HashMap<*const Tile, Arc<Tile>> = std::collections::HashMap::new();
        for (c, t) in &self.tiles {
            if let Some(converted) = done.get(&Arc::as_ptr(t)) {
                out.tiles.insert(*c, converted.clone());
                continue;
            }
            let dst = out.try_tile_mut(*c)?;
            let source_bytes = t.try_bytes().map_err(AllocationError::ScratchRead)?;
            let mut dest_bytes = dst.bytes_mut();
            let px_count = (TILE_SIZE * TILE_SIZE) as usize;
            for i in 0..px_count {
                for (k, v) in src.iter_mut().enumerate() {
                    *v = read_sample(&source_bytes, self.format.sample, i * from_n + k);
                }
                let px = convert_pixel(&self.format, &to, &src);
                for (k, v) in px.iter().enumerate() {
                    write_sample(&mut dest_bytes, to.sample, i * to.channels() + k, *v);
                }
            }
            drop(dest_bytes);
            if let Some(converted) = out.tiles.get(c) {
                done.insert(Arc::as_ptr(t), converted.clone());
            }
        }
        Ok(out)
    }

    /// Composite-friendly RGBA read (converts from the surface's model).
    pub fn rgba(&self, x: i32, y: i32) -> [f32; 4] {
        let mut p = [0.0f32; 5];
        self.read_pixel(x, y, &mut p);
        to_rgba(&self.format, &p)
    }
}

/// Encode normalised floats into one pixel's bytes.
pub fn encode_pixel(format: &PixelFormat, px: &[f32], out: &mut [u8]) {
    for (i, v) in px.iter().enumerate().take(format.channels()) {
        write_sample(out, format.sample, i, *v);
    }
}

pub fn decode_pixel(format: &PixelFormat, bytes: &[u8]) -> Vec<f32> {
    (0..format.channels()).map(|i| read_sample(bytes, format.sample, i)).collect()
}

/// Convert one pixel between formats via sRGB RGBA (CMYK through the built-in CMYK profile;
/// the engine's mode conversions use the document's profiles instead).
pub fn convert_pixel(from: &PixelFormat, to: &PixelFormat, px: &[f32]) -> Vec<f32> {
    if from.mode == to.mode {
        let n = from.mode.color_channels();
        let mut out: Vec<f32> = px[..n].to_vec();
        if to.alpha {
            out.push(if from.alpha { px[n] } else { 1.0 });
        }
        return out;
    }
    let rgba = to_rgba(from, px);
    from_rgba(to, rgba)
}

pub fn to_rgba(format: &PixelFormat, px: &[f32]) -> [f32; 4] {
    let n = format.mode.color_channels();
    let a = if format.alpha { px[n] } else { 1.0 };
    let rgb = match format.mode {
        ColorMode::Grayscale | ColorMode::Bitmap | ColorMode::Duotone => [px[0]; 3],
        ColorMode::Cmyk => photocraft_color::convert::cmyk_to_rgb([px[0], px[1], px[2], px[3]]),
        ColorMode::Lab => photocraft_color::convert::lab_to_srgb([px[0] * 100.0, px[1] * 255.0 - 128.0, px[2] * 255.0 - 128.0]),
        _ => [px[0], px[1], px[2]],
    };
    [rgb[0], rgb[1], rgb[2], a]
}

pub fn from_rgba(format: &PixelFormat, rgba: [f32; 4]) -> Vec<f32> {
    let rgb = [rgba[0], rgba[1], rgba[2]];
    let mut out: Vec<f32> = match format.mode {
        ColorMode::Grayscale | ColorMode::Bitmap | ColorMode::Duotone => vec![photocraft_color::convert::rgb_to_gray(rgb)],
        ColorMode::Cmyk => photocraft_color::convert::rgb_to_cmyk(rgb).to_vec(),
        ColorMode::Lab => {
            let l = photocraft_color::convert::srgb_to_lab(rgb);
            vec![l[0] / 100.0, (l[1] + 128.0) / 255.0, (l[2] + 128.0) / 255.0]
        }
        _ => rgb.to_vec(),
    };
    if format.alpha {
        out.push(rgba[3]);
    }
    out
}

/// [`from_rgba`] without allocating: writes `format.channels()` values into
/// `out` and returns how many were written.
#[inline]
pub fn from_rgba_into(format: &PixelFormat, rgba: [f32; 4], out: &mut [f32]) -> usize {
    let rgb = [rgba[0], rgba[1], rgba[2]];
    let n = match format.mode {
        ColorMode::Grayscale | ColorMode::Bitmap | ColorMode::Duotone => {
            out[0] = photocraft_color::convert::rgb_to_gray(rgb);
            1
        }
        ColorMode::Cmyk => {
            out[..4].copy_from_slice(&photocraft_color::convert::rgb_to_cmyk(rgb));
            4
        }
        ColorMode::Lab => {
            let l = photocraft_color::convert::srgb_to_lab(rgb);
            out[..3].copy_from_slice(&[l[0] / 100.0, (l[1] + 128.0) / 255.0, (l[2] + 128.0) / 255.0]);
            3
        }
        _ => {
            out[..3].copy_from_slice(&rgb);
            3
        }
    };
    if format.alpha {
        out[n] = rgba[3];
        n + 1
    } else {
        n
    }
}

/// A simple owned RGBA8 image, used for display and thumbnails.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Rgba8Image {
    pub width: u32,
    pub height: u32,
    pub pixels: Vec<u8>,
}

impl Rgba8Image {
    pub fn new(width: u32, height: u32) -> Self {
        Self { width, height, pixels: vec![0; width as usize * height as usize * 4] }
    }
}

/// Is this sample type able to hold values above 1.0 (HDR)?
pub fn is_hdr(sample: SampleType) -> bool {
    matches!(sample, SampleType::F32)
}

#[cfg(test)]
mod tests;

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

    #[test]
    fn sparse_missing_tiles_read_the_default_after_a_shift() {
        let mut s = Surface::with_default(PixelFormat::GRAY8, &[1.0]);
        s.fill_rect(Rect::new(0, 0, 10, 10), &[0.0]);
        s.fill_rect(Rect::new(600, 0, 610, 10), &[0.0]);
        let t = s.translated(5, 0, Rect::new(0, 0, 768, 256));
        assert_eq!(t.pixel(305, 20), vec![1.0]);
    }

    /// The rewrite must not change output: the misaligned path is compared against a
    /// straightforward reference gather (read each pixel, write it shifted) over randomized
    /// formats, default pixels, sparse tiles and shifts that cross tile boundaries.
    #[test]
    fn randomized_shifts_match_a_reference_gather() {
        let mut rng: u64 = 0x1234_5678_9abc_def0;
        let mut next = move || {
            rng ^= rng << 13;
            rng ^= rng >> 7;
            rng ^= rng << 17;
            rng
        };
        for case in 0..200u32 {
            let fmt = [PixelFormat::RGBA8, PixelFormat::RGBA16, PixelFormat::RGBA32F, PixelFormat::GRAY8, PixelFormat::GRAYA8][(next() % 5) as usize];
            let def: Vec<f32> = (0..fmt.channels()).map(|i| if case % 3 == 0 { 0.0 } else { ((i + case as usize) % 7) as f32 / 6.0 }).collect();
            let mut s = Surface::with_default(fmt, &def);
            // Sparse content: a few small patches at random positions.
            for _ in 0..(1 + next() % 4) {
                let x = (next() % 1600) as i32 - 800;
                let y = (next() % 1200) as i32 - 600;
                let w = 1 + (next() % 90) as i32;
                let h = 1 + (next() % 70) as i32;
                let v: Vec<f32> = (0..fmt.channels()).map(|i| ((i as u64 + next()) % 251) as f32 / 250.0).collect();
                s.fill_rect(Rect::new(x, y, x + w, y + h), &v);
            }
            let content = Rect::new(-900, -700, 1700, 1300);
            let (dx, dy) = ((next() % 1200) as i32 - 600, (next() % 900) as i32 - 450);
            let t = s.translated(dx, dy, content);
            // Reference: every pixel of the moved extent reads the source at (x-dx, y-dy),
            // inside the content, through the surface's default-aware reader.
            for _ in 0..64 {
                let x = (next() % 1500) as i32 - 750 + dx;
                let y = (next() % 1100) as i32 - 550 + dy;
                if !content.translate(dx, dy).contains(x, y) {
                    continue;
                }
                let want = if content.contains(x - dx, y - dy) { s.pixel(x - dx, y - dy) } else { s.default_pixel() };
                let got = t.pixel(x, y);
                assert_eq!(got, want, "case {case} fmt {fmt:?} shift ({dx},{dy}) at ({x},{y})");
            }
        }
    }
}