repose_render_wgpu/

lib.rs

use std::borrow::Cow;
use std::collections::HashMap;
use std::num::NonZero;
#[cfg(feature = "winit-surface")]
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::sync::Arc;

use repose_core::color::{ChromaSiting, ColorInfo, PixelFormat};
use repose_core::request_frame;
use repose_core::{
    Brush, FontStyle, GlyphRasterConfig, PresentModePref, RenderBackend, Scene, SceneNode,
    StrokeCap, Transform, Vec2,
};
use wgpu::Instance;

mod slug;

mod commands;
pub use commands::apply_render_commands;

pub mod offscreen;

mod callback;
pub use callback::{Callback, CallbackResources, ScreenDescriptor, WgpuCallback};

mod depth_composite;
pub use depth_composite::DepthComposite;

#[derive(Clone)]
struct UploadRing {
    buf: wgpu::Buffer,
    cap: u64,
    head: u64,
    usage: wgpu::BufferUsages,
}

impl UploadRing {
    fn new(device: &wgpu::Device, label: &str, cap: u64, usage: wgpu::BufferUsages) -> Self {
        let buf = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some(label),
            size: cap,
            usage,
            mapped_at_creation: false,
        });
        Self {
            buf,
            cap,
            head: 0,
            usage,
        }
    }

    fn reset(&mut self) {
        self.head = 0;
    }

    fn grow_to_fit(&mut self, device: &wgpu::Device, needed: u64) {
        let start = (self.head + 3) & !3;
        let aligned_needed = (needed + 3) & !3;
        // Need start + needed within cap, accounting for alignment padding
        if start + needed <= self.cap {
            return;
        }
        let required = start + needed;
        let mut new_cap = required.next_power_of_two().max(self.cap * 2).max(256);
        new_cap = (new_cap + 3) & !3;
        if new_cap < aligned_needed {
            new_cap = aligned_needed.next_power_of_two();
        }
        self.buf = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("upload ring (grown)"),
            size: new_cap,
            usage: self.usage,
            mapped_at_creation: false,
        });
        self.cap = new_cap;
        if start + needed > self.cap {
            self.head = 0;
        }
    }

    fn alloc_write(&mut self, queue: &wgpu::Queue, bytes: &[u8]) -> (u64, u64) {
        let len = bytes.len() as u64;
        let start = (self.head + 3) & !3; // align to 4
        let end = start + len;
        if end > self.cap {
            // Instead of panicking, grow and reset
            log::error!(
                "UploadRing overflow: start={start} len={len} cap={} - growing",
                self.cap
            );
            if len > self.cap {
                // Need larger buffer; create via grow_to_fit side-effect not available here (no device)
                // Fallback: truncate write to avoid UB, return dummy range
                return (0, 0);
            }
            // Wrap to beginning if alignment pushed us over
            let wrapped_start = 0;
            let wrapped_end = len;
            if wrapped_end <= self.cap {
                queue.write_buffer(&self.buf, wrapped_start, bytes);
                self.head = wrapped_end;
                return (wrapped_start, len);
            }
            return (0, 0);
        }
        queue.write_buffer(&self.buf, start, bytes);
        self.head = end;
        (start, len)
    }
}

struct InstancedPipe<I: bytemuck::Pod> {
    ring: UploadRing,
    _marker: std::marker::PhantomData<I>,
}

impl<I: bytemuck::Pod> InstancedPipe<I> {
    fn new(ring: UploadRing) -> Self {
        Self {
            ring,
            _marker: std::marker::PhantomData,
        }
    }

    fn upload(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        data: &[I],
    ) -> Option<(u64, u32)> {
        if data.is_empty() {
            return None;
        }
        let bytes = bytemuck::cast_slice(data);
        self.ring.grow_to_fit(device, bytes.len() as u64);
        let (off, wrote) = self.ring.alloc_write(queue, bytes);
        if wrote as usize != bytes.len() {
            log::error!(
                "upload skipped: batch {}B exceeds ring {}B",
                bytes.len(),
                self.ring.cap
            );
            return None;
        }
        Some((off, data.len() as u32))
    }

    fn reset(&mut self) {
        self.ring.reset();
    }
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct Globals {
    ndc_to_px: [f32; 2],
    _pad: [f32; 2],
}

fn make_globals(target_w: f32, target_h: f32) -> Globals {
    Globals {
        ndc_to_px: [target_w * 0.5, target_h * 0.5],
        _pad: [0.0, 0.0],
    }
}

pub struct WgpuSceneRenderer {
    pub device: wgpu::Device,
    pub queue: wgpu::Queue,
    pub output_format: wgpu::TextureFormat,
    pub output_width: u32,
    pub output_height: u32,
    /// Pixels per point (DPI scale) for `ScreenDescriptor` / `PaintCallbackInfo`.
    pub pixels_per_point: f32,

    // Render pipelines. Two sets: one for the MSAA surface pass, one for
    // graphics-layer render-to-texture passes (sample_count = 1).
    surface_pipes: Pipelines,
    layer_pipes: Pipelines,

    // Instanced draw rings
    rects: InstancedPipe<RectInstance>,
    borders: InstancedPipe<BorderInstance>,
    ellipses: InstancedPipe<EllipseInstance>,
    ellipse_borders: InstancedPipe<EllipseBorderInstance>,
    arcs: InstancedPipe<ArcInstance>,
    glyph_mask: InstancedPipe<GlyphInstance>,
    glyph_color: InstancedPipe<GlyphInstance>,

    // Image bind layouts and shared sampler
    image_bind_layout_rgba: wgpu::BindGroupLayout,
    image_bind_layout_nv12: wgpu::BindGroupLayout,
    image_sampler: wgpu::Sampler,
    layer_sampler: wgpu::Sampler,
    layer_sampler_linear: wgpu::Sampler,

    // Blur composite ring (for graphics-layer drop shadows)
    blur_ring: UploadRing,

    text_bind_layout: wgpu::BindGroupLayout,

    // Stencil clip ring
    clip_ring: UploadRing,

    // Projective layer-composite ring (one ProjectiveInstance per flattened
    // perspective subtree)
    projective_ring: UploadRing,

    // Tessellated vector glyph pipeline (always enabled)
    slug_enabled: bool,
    slug_ring: UploadRing,
    slug_cache: slug::GlyphSlugCache,

    // Instanced NV12 ring
    nv12: InstancedPipe<Nv12Instance>,

    // Tessellated vector mesh rendering (host-provided, e.g. lyon output).
    mesh_verts: UploadRing,
    mesh_indices: UploadRing,
    mesh_uniform_buf: wgpu::Buffer,
    mesh_bind_layout: wgpu::BindGroupLayout,
    mesh_bind: wgpu::BindGroup,
    mesh_uniform_head: u64,
    /// CPU mirror of the active vector-clip stack: (voff, vcnt, ioff, icnt,
    /// uoff, difference) of each pushed mask so `PopVectorClip` can re-draw
    /// it to decrement the stencil.
    mesh_clip_stack: Vec<(u64, u32, u64, u32, u64, bool)>,

    /// Translator-owned flatten layer ids used by the previous frame;
    /// drained from the layer pool at the start of each translation (they
    /// are single-frame by construction).
    flatten_layer_ids: Vec<u32>,

    msaa_samples: u32,

    // Depth-stencil target
    depth_stencil_tex: wgpu::Texture,
    depth_stencil_view: wgpu::TextureView,

    // Optional MSAA color target
    msaa_tex: Option<wgpu::Texture>,
    msaa_view: Option<wgpu::TextureView>,

    globals_buf: wgpu::Buffer,
    globals_bind: wgpu::BindGroup,

    // Glyph atlas
    atlas_mask: AtlasA8,
    atlas_color: AtlasRGBA,

    // Image management
    next_image_handle: u64,
    images: HashMap<u64, ImageTex>,
    retained: HashMap<u64, RetainedImage>,

    // A8 coverage-tile management (host-rasterized masks composited tinted;
    // no retained CPU copies — tiles are immutable and re-registered).
    next_coverage_handle: u64,
    coverages: HashMap<u64, CoverageTex>,

    // Eviction stats
    frame_index: u64,
    image_bytes_total: u64,
    image_evict_after_frames: u64,
    image_budget_bytes: u64,

    // Graphics layer pool. Maps `SceneNode::BeginLayer::layer_id` to a
    // cached offscreen render target.
    layer_pool: HashMap<u32, LayerTarget>,

    // Linear working-space mode (default off -> fast playback path).
    // When enabled, the scene is rendered into an Rgba16Float intermediate
    // texture, then a final full-screen pass applies the display OETF.
    working_space: bool,
    ws_tex: Option<wgpu::Texture>,
    ws_view: Option<wgpu::TextureView>,
    ws_bind: Option<wgpu::BindGroup>,
    display_pipeline: Option<wgpu::RenderPipeline>,
    display_layout: Option<wgpu::BindGroupLayout>,

    pub callback_resources: CallbackResources,
}

pub struct WgpuSurfaceBackend {
    pub surface: Option<wgpu::Surface<'static>>,
    pub surface_config: Option<wgpu::SurfaceConfiguration>,
    pub renderer: WgpuSceneRenderer,
}

impl std::ops::Deref for WgpuSurfaceBackend {
    type Target = WgpuSceneRenderer;
    fn deref(&self) -> &Self::Target {
        &self.renderer
    }
}
impl std::ops::DerefMut for WgpuSurfaceBackend {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.renderer
    }
}

#[cfg(feature = "winit-surface")]
pub type WgpuBackend = WgpuSurfaceBackend;

impl Drop for WgpuSceneRenderer {
    fn drop(&mut self) {
        let _ = self.device.poll(wgpu::PollType::Poll);
        #[cfg(not(target_arch = "wasm32"))]
        {
            let _ = self.device.poll(wgpu::PollType::Wait {
                submission_index: None,
                timeout: Some(std::time::Duration::from_millis(100)),
            });
        }
    }
}

#[derive(Clone)]
struct LayerTarget {
    view: wgpu::TextureView,
    bind: wgpu::BindGroup,
    bind_linear: wgpu::BindGroup,
    depth_stencil_view: wgpu::TextureView,
    width: u32,
    height: u32,
    rect_px: (f32, f32, f32, f32),
}

/// Identifies which render target a `Pass` draws into.
#[derive(Clone, Copy)]
enum PassTarget {
    Surface,
    Layer(u32),
}

/// A bundle of render pipelines for a single sample-count target. Created
/// twice: once with `sample_count = msaa_samples` for the surface pass, and
/// once with `sample_count = 1` for graphics-layer render-to-texture passes
/// (where MSAA is wasted).
struct Pipelines {
    rects: wgpu::RenderPipeline,
    borders: wgpu::RenderPipeline,
    ellipses: wgpu::RenderPipeline,
    ellipse_borders: wgpu::RenderPipeline,
    arcs: wgpu::RenderPipeline,
    text_mask: wgpu::RenderPipeline,
    text_color: wgpu::RenderPipeline,
    image_rgba: wgpu::RenderPipeline,
    /// Tinted A8 coverage composite (`coverage.wgsl`): same vertex
    /// attributes and bind groups as the text/color path, sampling a
    /// single-channel tile registered with `register_coverage_a8`.
    coverage: wgpu::RenderPipeline,
    image_nv12: wgpu::RenderPipeline,
    blur: wgpu::RenderPipeline,
    blur_content: wgpu::RenderPipeline,
    clip_bin: wgpu::RenderPipeline,
    clip_dec: wgpu::RenderPipeline,
    slug: Option<wgpu::RenderPipeline>,
    /// Tessellated vector mesh (fill/stroke). Uses an `Equal` stencil compare
    /// so world content is correctly masked to the active `PushVectorClip`
    /// shape (outside any clip the stencil is 0 == ref 0, so it draws).
    mesh: wgpu::RenderPipeline,
    /// Screen-space overlay meshes: `LessEqual` compare so they always draw
    /// regardless of any active vector clip.
    mesh_overlay: wgpu::RenderPipeline,
    /// Stencil increment for vector clips.
    mesh_clip_inc: wgpu::RenderPipeline,
    /// Stencil decrement for vector clips.
    mesh_clip_dec: wgpu::RenderPipeline,
    /// Projective layer composite (perspective flattening): samples a
    /// graphics-layer texture through a 2D projective map. Drawn with a
    /// `ProjectiveInstance` from `projective_ring`.
    projective_layer: wgpu::RenderPipeline,
}

impl Pipelines {
    fn create(
        device: &wgpu::Device,
        format: wgpu::TextureFormat,
        sample_count: u32,
        globals_layout: &wgpu::BindGroupLayout,
        text_bind_layout: &wgpu::BindGroupLayout,
        image_bind_layout_nv12: &wgpu::BindGroupLayout,
        clip_pipeline_layout: &wgpu::PipelineLayout,
        stencil_for_content: &wgpu::DepthStencilState,
        stencil_for_clip_inc: &wgpu::DepthStencilState,
        stencil_for_clip_dec: &wgpu::DepthStencilState,
        clip_color_target: &wgpu::ColorTargetState,
        clip_vertex_layout: &wgpu::VertexBufferLayout,
        mesh_bind_layout: &wgpu::BindGroupLayout,
    ) -> Self {
        let msaa_state = wgpu::MultisampleState {
            count: sample_count,
            mask: !0,
            alpha_to_coverage_enabled: false,
        };

        macro_rules! make_content_pipeline {
            ($name:ident, $shader:literal, $inst_type:ty, $attrs:expr) => {
                let shader_module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
                    label: Some(concat!($shader, ".wgsl")),
                    source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!(concat!(
                        "shaders/", $shader, ".wgsl"
                    )))),
                });
                let pipeline_layout =
                    device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                        label: Some(concat!($shader, " pipeline layout")),
                        bind_group_layouts: &[Some(globals_layout)],
                        immediate_size: 0,
                    });
                let $name = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                    label: Some(concat!($shader, " pipeline")),
                    layout: Some(&pipeline_layout),
                    vertex: wgpu::VertexState {
                        module: &shader_module,
                        entry_point: Some("vs_main"),
                        buffers: &[Some(wgpu::VertexBufferLayout {
                            array_stride: std::mem::size_of::<$inst_type>() as u64,
                            step_mode: wgpu::VertexStepMode::Instance,
                            attributes: $attrs,
                        })],
                        compilation_options: wgpu::PipelineCompilationOptions::default(),
                    },
                    fragment: Some(wgpu::FragmentState {
                        module: &shader_module,
                        entry_point: Some("fs_main"),
                        targets: &[Some(wgpu::ColorTargetState {
                            format,
                            blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                            write_mask: wgpu::ColorWrites::ALL,
                        })],
                        compilation_options: wgpu::PipelineCompilationOptions::default(),
                    }),
                    primitive: wgpu::PrimitiveState::default(),
                    depth_stencil: Some(stencil_for_content.clone()),
                    multisample: msaa_state,
                    multiview_mask: None,
                    cache: None,
                });
            };
        }

        let rect_attrs: &[wgpu::VertexAttribute] = &[
            wgpu::VertexAttribute {
                shader_location: 0,
                offset: 0,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 1,
                offset: 16,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 2,
                offset: 32,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 3,
                offset: 36,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 4,
                offset: 48,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 5,
                offset: 64,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 6,
                offset: 80,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 7,
                offset: 88,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 8,
                offset: 96,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 9,
                offset: 112,
                format: wgpu::VertexFormat::Float32x4,
            },
        ];
        let border_attrs: &[wgpu::VertexAttribute] = &[
            wgpu::VertexAttribute {
                shader_location: 0,
                offset: 0,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 1,
                offset: 16,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 2,
                offset: 32,
                format: wgpu::VertexFormat::Float32,
            },
            wgpu::VertexAttribute {
                shader_location: 3,
                offset: 36,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 4,
                offset: 48,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 5,
                offset: 52,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 6,
                offset: 68,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 7,
                offset: 84,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 8,
                offset: 92,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 9,
                offset: 100,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 10,
                offset: 116,
                format: wgpu::VertexFormat::Float32x4,
            },
        ];
        let ellipse_attrs: &[wgpu::VertexAttribute] = &[
            wgpu::VertexAttribute {
                shader_location: 0,
                offset: 0,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 1,
                offset: 16,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 2,
                offset: 20,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 3,
                offset: 32,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 4,
                offset: 48,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 5,
                offset: 64,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 6,
                offset: 72,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 7,
                offset: 80,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 8,
                offset: 96,
                format: wgpu::VertexFormat::Float32x4,
            },
        ];
        let ellipse_border_attrs: &[wgpu::VertexAttribute] = &[
            wgpu::VertexAttribute {
                shader_location: 0,
                offset: 0,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 1,
                offset: 16,
                format: wgpu::VertexFormat::Float32,
            },
            wgpu::VertexAttribute {
                shader_location: 2,
                offset: 20,
                format: wgpu::VertexFormat::Float32,
            },
            wgpu::VertexAttribute {
                shader_location: 3,
                offset: 24,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 4,
                offset: 28,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 5,
                offset: 32,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 6,
                offset: 48,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 7,
                offset: 64,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 8,
                offset: 72,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 9,
                offset: 80,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 10,
                offset: 96,
                format: wgpu::VertexFormat::Float32x4,
            },
        ];

        make_content_pipeline!(rects, "rect", RectInstance, rect_attrs);
        make_content_pipeline!(borders, "border", BorderInstance, border_attrs);
        make_content_pipeline!(ellipses, "ellipse", EllipseInstance, ellipse_attrs);
        make_content_pipeline!(
            ellipse_borders,
            "ellipse_border",
            EllipseBorderInstance,
            ellipse_border_attrs
        );

        let arc_attrs: &[wgpu::VertexAttribute] = &[
            wgpu::VertexAttribute {
                shader_location: 0,
                offset: 0,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 1,
                offset: 16,
                format: wgpu::VertexFormat::Float32,
            },
            wgpu::VertexAttribute {
                shader_location: 2,
                offset: 20,
                format: wgpu::VertexFormat::Float32,
            },
            wgpu::VertexAttribute {
                shader_location: 3,
                offset: 24,
                format: wgpu::VertexFormat::Float32,
            },
            wgpu::VertexAttribute {
                shader_location: 4,
                offset: 28,
                format: wgpu::VertexFormat::Float32,
            },
            wgpu::VertexAttribute {
                shader_location: 5,
                offset: 32,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 6,
                offset: 36,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 7,
                offset: 48,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 8,
                offset: 64,
                format: wgpu::VertexFormat::Float32x4,
            },
            wgpu::VertexAttribute {
                shader_location: 9,
                offset: 80,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 10,
                offset: 88,
                format: wgpu::VertexFormat::Float32x2,
            },
            wgpu::VertexAttribute {
                shader_location: 11,
                offset: 96,
                format: wgpu::VertexFormat::Uint32,
            },
            wgpu::VertexAttribute {
                shader_location: 12,
                offset: 100,
                format: wgpu::VertexFormat::Float32,
            },
            wgpu::VertexAttribute {
                shader_location: 13,
                offset: 112,
                format: wgpu::VertexFormat::Float32x4,
            },
        ];

        make_content_pipeline!(arcs, "arc", ArcInstance, arc_attrs);

        // Text (mask)
        let text_mask_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("text.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!("shaders/text.wgsl"))),
        });
        // Text (color)
        let text_color_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("text_color.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!(
                "shaders/text_color.wgsl"
            ))),
        });
        let text_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("text pipeline layout"),
            bind_group_layouts: &[Some(globals_layout), Some(text_bind_layout)],
            immediate_size: 0,
        });
        let glyph_vertex = wgpu::VertexBufferLayout {
            array_stride: std::mem::size_of::<GlyphInstance>() as u64,
            step_mode: wgpu::VertexStepMode::Instance,
            attributes: &[
                wgpu::VertexAttribute {
                    shader_location: 0,
                    offset: 0,
                    format: wgpu::VertexFormat::Float32x4,
                },
                wgpu::VertexAttribute {
                    shader_location: 1,
                    offset: 16,
                    format: wgpu::VertexFormat::Float32x4,
                },
                wgpu::VertexAttribute {
                    shader_location: 2,
                    offset: 32,
                    format: wgpu::VertexFormat::Float32x4,
                },
                wgpu::VertexAttribute {
                    shader_location: 3,
                    offset: 48,
                    format: wgpu::VertexFormat::Float32x4,
                },
            ],
        };
        let text_mask = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("text pipeline (mask)"),
            layout: Some(&text_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &text_mask_shader,
                entry_point: Some("vs_main"),
                buffers: &[Some(glyph_vertex.clone())],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &text_mask_shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_content.clone()),
            multisample: msaa_state,
            multiview_mask: None,
            cache: None,
        });
        let text_color = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("text pipeline (color)"),
            layout: Some(&text_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &text_color_shader,
                entry_point: Some("vs_main"),
                buffers: &[Some(glyph_vertex.clone())],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &text_color_shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_content.clone()),
            multisample: msaa_state,
            multiview_mask: None,
            cache: None,
        });
        // image_rgba reuses the text color pipeline (same vertex/bindings).
        let image_rgba = text_color.clone();

        // Tinted A8 coverage composite. Same vertex attributes (GlyphInstance)
        // and bind groups (globals + texture/sampler) as the text color path,
        // sampling R8 tiles uploaded via `register_coverage_a8`.
        let coverage_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("coverage.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!("shaders/coverage.wgsl"))),
        });
        let coverage = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("coverage pipeline (tinted a8)"),
            layout: Some(&text_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &coverage_shader,
                entry_point: Some("vs_main"),
                buffers: &[Some(glyph_vertex.clone())],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &coverage_shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_content.clone()),
            multisample: msaa_state,
            multiview_mask: None,
            cache: None,
        });

        // Blur composite pipeline (graphics-layer drop shadow)
        let blur_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("blur_shadow.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!(
                "shaders/blur_shadow.wgsl"
            ))),
        });
        let blur_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("blur pipeline layout"),
            bind_group_layouts: &[Some(globals_layout), Some(text_bind_layout)],
            immediate_size: 0,
        });
        let blur = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("blur pipeline"),
            layout: Some(&blur_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &blur_shader,
                entry_point: Some("vs_main"),
                buffers: &[Some(wgpu::VertexBufferLayout {
                    array_stride: std::mem::size_of::<BlurInstance>() as u64,
                    step_mode: wgpu::VertexStepMode::Instance,
                    attributes: &[
                        wgpu::VertexAttribute {
                            shader_location: 0,
                            offset: 0,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 1,
                            offset: 16,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 2,
                            offset: 32,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 3,
                            offset: 48,
                            format: wgpu::VertexFormat::Float32x2,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 4,
                            offset: 56,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                    ],
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &blur_shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_content.clone()),
            multisample: msaa_state,
            multiview_mask: None,
            cache: None,
        });

        // Content blur pipeline (full RGBA gaussian blur)
        let blur_content_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("blur_content.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!(
                "shaders/blur_content.wgsl"
            ))),
        });
        let blur_content = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("blur content pipeline"),
            layout: Some(&blur_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &blur_content_shader,
                entry_point: Some("vs_main"),
                buffers: &[Some(wgpu::VertexBufferLayout {
                    array_stride: std::mem::size_of::<BlurInstance>() as u64,
                    step_mode: wgpu::VertexStepMode::Instance,
                    attributes: &[
                        wgpu::VertexAttribute {
                            shader_location: 0,
                            offset: 0,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 1,
                            offset: 16,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 2,
                            offset: 32,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 3,
                            offset: 48,
                            format: wgpu::VertexFormat::Float32x2,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 4,
                            offset: 56,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                    ],
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &blur_content_shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_content.clone()),
            multisample: msaa_state,
            multiview_mask: None,
            cache: None,
        });

        // NV12 Image Pipeline
        let image_nv12_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("image_nv12.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!(
                "shaders/image_nv12.wgsl"
            ))),
        });
        let image_nv12_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("image nv12 pipeline layout"),
            bind_group_layouts: &[Some(globals_layout), Some(image_bind_layout_nv12)],
            immediate_size: 0,
        });
        let image_nv12 = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("image nv12 pipeline"),
            layout: Some(&image_nv12_layout),
            vertex: wgpu::VertexState {
                module: &image_nv12_shader,
                entry_point: Some("vs_main"),
                buffers: &[Some(wgpu::VertexBufferLayout {
                    array_stride: std::mem::size_of::<Nv12Instance>() as u64,
                    step_mode: wgpu::VertexStepMode::Instance,
                    attributes: &[
                        wgpu::VertexAttribute {
                            shader_location: 0,
                            offset: 0,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 1,
                            offset: 16,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 2,
                            offset: 32,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 3,
                            offset: 48,
                            format: wgpu::VertexFormat::Float32,
                        },
                        wgpu::VertexAttribute {
                            shader_location: 4,
                            offset: 52,
                            format: wgpu::VertexFormat::Float32x4,
                        },
                    ],
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &image_nv12_shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_content.clone()),
            multisample: msaa_state,
            multiview_mask: None,
            cache: None,
        });

        // Clipping
        let clip_shader_bin = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("clip_round_rect_bin.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!(
                "shaders/clip_round_rect_bin.wgsl"
            ))),
        });
        let clip_bin = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("clip pipeline (bin)"),
            layout: Some(clip_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &clip_shader_bin,
                entry_point: Some("vs_main"),
                buffers: &[Some(clip_vertex_layout.clone())],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &clip_shader_bin,
                entry_point: Some("fs_main"),
                targets: &[Some(clip_color_target.clone())],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_clip_inc.clone()),
            multisample: wgpu::MultisampleState {
                count: sample_count,
                mask: !0,
                alpha_to_coverage_enabled: false,
            },
            multiview_mask: None,
            cache: None,
        });
        let clip_dec = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("clip pipeline (dec)"),
            layout: Some(clip_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &clip_shader_bin,
                entry_point: Some("vs_main"),
                buffers: &[Some(clip_vertex_layout.clone())],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &clip_shader_bin,
                entry_point: Some("fs_main"),
                targets: &[Some(clip_color_target.clone())],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_clip_dec.clone()),
            multisample: wgpu::MultisampleState {
                count: sample_count,
                mask: !0,
                alpha_to_coverage_enabled: false,
            },
            multiview_mask: None,
            cache: None,
        });

        let slug = Some(slug::create_pipeline(
            device,
            format,
            sample_count,
            stencil_for_content,
        ));

        // Tessellated vector mesh pipeline (host-supplied vertex/index data).
        let mesh_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("mesh.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!("shaders/mesh.wgsl"))),
        });
        let mesh_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("mesh pipeline layout"),
            bind_group_layouts: &[Some(globals_layout), Some(mesh_bind_layout)],
            immediate_size: 0,
        });
        let mesh_vertex_layout = wgpu::VertexBufferLayout {
            array_stride: std::mem::size_of::<MeshVertex>() as u64,
            step_mode: wgpu::VertexStepMode::Vertex,
            attributes: &[
                wgpu::VertexAttribute {
                    shader_location: 0,
                    offset: 0,
                    format: wgpu::VertexFormat::Float32x2,
                },
                wgpu::VertexAttribute {
                    shader_location: 1,
                    offset: 8,
                    format: wgpu::VertexFormat::Float32x4,
                },
                wgpu::VertexAttribute {
                    shader_location: 2,
                    offset: 24,
                    format: wgpu::VertexFormat::Float32x2,
                },
            ],
        };
        let make_mesh_pipeline =
            |label: &str, depth: &wgpu::DepthStencilState, color: &wgpu::ColorTargetState| {
                device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                    label: Some(label),
                    layout: Some(&mesh_pipeline_layout),
                    vertex: wgpu::VertexState {
                        module: &mesh_shader,
                        entry_point: Some("vs_main"),
                        buffers: &[Some(mesh_vertex_layout.clone())],
                        compilation_options: wgpu::PipelineCompilationOptions::default(),
                    },
                    fragment: Some(wgpu::FragmentState {
                        module: &mesh_shader,
                        entry_point: Some("fs_main"),
                        targets: &[Some(color.clone())],
                        compilation_options: wgpu::PipelineCompilationOptions::default(),
                    }),
                    primitive: wgpu::PrimitiveState {
                        topology: wgpu::PrimitiveTopology::TriangleList,
                        ..Default::default()
                    },
                    depth_stencil: Some(depth.clone()),
                    multisample: msaa_state,
                    multiview_mask: None,
                    cache: None,
                })
            };
        let mesh_color_target = wgpu::ColorTargetState {
            format,
            blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
            write_mask: wgpu::ColorWrites::ALL,
        };
        let mut stencil_for_mesh = stencil_for_content.clone();
        stencil_for_mesh.stencil.front.compare = wgpu::CompareFunction::Equal;
        stencil_for_mesh.stencil.back.compare = wgpu::CompareFunction::Equal;
        let mesh = make_mesh_pipeline("mesh pipeline", &stencil_for_mesh, &mesh_color_target);
        let mesh_overlay = make_mesh_pipeline(
            "mesh overlay pipeline",
            stencil_for_content,
            &mesh_color_target,
        );
        let mesh_clip_inc = make_mesh_pipeline(
            "mesh clip (inc) pipeline",
            stencil_for_clip_inc,
            clip_color_target,
        );
        let mesh_clip_dec = make_mesh_pipeline(
            "mesh clip (dec) pipeline",
            stencil_for_clip_dec,
            clip_color_target,
        );

        // Projective layer composite (perspective flattening). Same
        // bind groups as the text/image path (globals + layer texture), with
        // per-instance projected corners. Like `image_rgba` it draws into the
        // parent target, so it shares the content stencil state.
        let projective_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("projective_layer.wgsl"),
            source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!(
                "shaders/projective_layer.wgsl"
            ))),
        });
        let projective_pipeline_layout =
            device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                label: Some("projective layer pipeline layout"),
                bind_group_layouts: &[Some(globals_layout), Some(text_bind_layout)],
                immediate_size: 0,
            });
        let projective_vertex_layout = wgpu::VertexBufferLayout {
            array_stride: std::mem::size_of::<ProjectiveInstance>() as u64,
            step_mode: wgpu::VertexStepMode::Instance,
            attributes: &[
                wgpu::VertexAttribute {
                    shader_location: 0,
                    offset: 0,
                    format: wgpu::VertexFormat::Float32x2,
                },
                wgpu::VertexAttribute {
                    shader_location: 1,
                    offset: 8,
                    format: wgpu::VertexFormat::Float32x2,
                },
                wgpu::VertexAttribute {
                    shader_location: 2,
                    offset: 16,
                    format: wgpu::VertexFormat::Float32x2,
                },
                wgpu::VertexAttribute {
                    shader_location: 3,
                    offset: 24,
                    format: wgpu::VertexFormat::Float32x2,
                },
                wgpu::VertexAttribute {
                    shader_location: 4,
                    offset: 32,
                    format: wgpu::VertexFormat::Float32x4,
                },
                wgpu::VertexAttribute {
                    shader_location: 5,
                    offset: 48,
                    format: wgpu::VertexFormat::Float32x4,
                },
                wgpu::VertexAttribute {
                    shader_location: 6,
                    offset: 64,
                    format: wgpu::VertexFormat::Float32,
                },
            ],
        };
        let projective_layer = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("projective layer composite pipeline"),
            layout: Some(&projective_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &projective_shader,
                entry_point: Some("vs_main"),
                buffers: &[Some(projective_vertex_layout)],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &projective_shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: wgpu::PipelineCompilationOptions::default(),
            }),
            primitive: wgpu::PrimitiveState::default(),
            depth_stencil: Some(stencil_for_content.clone()),
            multisample: msaa_state,
            multiview_mask: None,
            cache: None,
        });

        Self {
            rects,
            borders,
            ellipses,
            ellipse_borders,
            arcs,
            text_mask,
            text_color,
            image_rgba,
            image_nv12,
            coverage,
            blur,
            blur_content,
            clip_bin,
            clip_dec,
            slug,
            mesh,
            mesh_overlay,
            mesh_clip_inc,
            mesh_clip_dec,
            projective_layer,
        }
    }
}

/// A segment of the frame that draws into a single render target.
struct Pass {
    target: PassTarget,
    /// The initial scissor to apply to the rpass when it is opened.
    initial_scissor: (u32, u32, u32, u32),
    /// `None` means `LoadOp::Load` (resume existing content);
    /// `Some(c)` means `LoadOp::Clear(c)`.
    clear_color: Option<[f32; 4]>,
    cmds: Vec<Cmd>,
}

/// One translator-flattened perspective layer (see
/// `push_perspective_layer`): the projective map and everything needed to
/// restore the parent target on the matching pop.
struct FlattenRecord {
    /// `transform_stack.len()` before this flatten pushed its two entries
    /// (stripped affine + layer-local shift).
    stack_len: usize,
    layer_id: u32,
    /// Full projective map (row-major 3x3): affine ancestors over the
    /// perspective node, in parent-target coordinates.
    map: [f32; 9],
    /// Layer rect in the parent target's coordinates.
    layer_rect: repose_core::Rect,
    saved_scissor: Vec<repose_core::Rect>,
    saved_root: repose_core::Rect,
    saved_size: (f32, f32),
}

/// First translator-owned flatten layer id. Producer ids start at 1 per
/// scene, so this range never collides; ids are drained from the layer pool
/// after each frame, so reuse across frames is safe.
const FLATTEN_ID_BASE: u32 = 0xF000_0000;

#[allow(non_snake_case)]
enum Cmd {
    ClipPush {
        off: u64,
        cnt: u32,
        scissor: (u32, u32, u32, u32),
        difference: bool,
        rounded: bool,
    },
    ClipPop {
        off: u64,
        cnt: u32,
        scissor: (u32, u32, u32, u32),
        difference: bool,
    },
    Rect {
        off: u64,
        cnt: u32,
    },
    Border {
        off: u64,
        cnt: u32,
    },
    Ellipse {
        off: u64,
        cnt: u32,
    },
    EllipseBorder {
        off: u64,
        cnt: u32,
    },
    Arc {
        off: u64,
        cnt: u32,
    },
    GlyphsMask {
        off: u64,
        cnt: u32,
    },
    GlyphsColor {
        off: u64,
        cnt: u32,
    },
    GlyphsVector {
        off: u64,
        cnt: u32,
    },
    ImageRgba {
        off: u64,
        cnt: u32,
        handle: u64,
    },
    /// Composite a tinted A8 coverage tile (`SceneNode::Coverage`). The
    /// instance lives in `self.glyph_color.ring` (a `GlyphInstance`); the
    /// bind comes from the coverage registry.
    Coverage {
        off: u64,
        cnt: u32,
        handle: u64,
    },
    ImageNv12 {
        off: u64,
        cnt: u32,
        handle: u64,
    },
    /// Composite a previously-rendered graphics layer back into the
    /// current target as a textured quad. The quad's vertex buffer
    /// lives in `self.glyph_color.ring` (a `GlyphInstance`).
    CompositeLayer {
        off: u64,
        cnt: u32,
        layer_id: u32,
    },
    /// Composite a blurred drop shadow of a previously-rendered graphics
    /// layer. The quad's vertex buffer lives in `self.blur_ring` (a
    /// `BlurInstance`).
    CompositeShadow {
        off: u64,
        cnt: u32,
        layer_id: u32,
    },
    /// Apply gaussian blur to a layer and composite the blurred result.
    /// Uses the `blur_content` pipeline (full RGBA blur).
    CompositeBlur {
        off: u64,
        cnt: u32,
        layer_id: u32,
    },
    /// Composite a flattened perspective layer through its projective map.
    /// The instance lives in `self.projective_ring` (a `ProjectiveInstance`
    /// with CPU-projected NDC corners); sampled from the layer's texture
    /// with perspective-correct UVs by the `projective_layer` pipeline.
    CompositeProjective {
        off: u64,
        cnt: u32,
        layer_id: u32,
    },
    /// Draw a tessellated vector mesh (solid or gradient paint).
    VectorMesh {
        voff: u64,
        vcnt: u32,
        ioff: u64,
        icnt: u32,
        uoff: u64,
    },
    /// Draw a screen-space overlay mesh (identity transform, device pixels).
    VectorOverlay {
        voff: u64,
        vcnt: u32,
        ioff: u64,
        icnt: u32,
        uoff: u64,
    },
    /// Increment the stencil buffer with a tessellated vector mask.
    /// `difference` marks an inverse (`\iclip`-style) mask: content draws
    /// *outside* it. The counting still balances (push increments, pop
    /// decrements); only the depth bookkeeping differs (see executor).
    VectorClipPush {
        voff: u64,
        vcnt: u32,
        ioff: u64,
        icnt: u32,
        uoff: u64,
        scissor: (u32, u32, u32, u32),
        difference: bool,
    },
    /// Decrement the stencil buffer with the matching vector mask.
    VectorClipPop {
        voff: u64,
        vcnt: u32,
        ioff: u64,
        icnt: u32,
        uoff: u64,
        scissor: (u32, u32, u32, u32),
        difference: bool,
    },
    Callback {
        rect: repose_core::Rect,
        payload: repose_core::PaintCallbackPayload,
    },
}

/// A registered A8 coverage tile: single-channel mask sampled as coverage
/// by `SceneNode::Coverage`. Tiles are immutable; producers re-register on
/// geometry change and `remove_coverage` stale handles (unused tiles also
/// age out via the image eviction policy).
struct CoverageTex {
    // Held to keep the GPU texture alive (freed on remove/evict).
    #[allow(dead_code)]
    tex: wgpu::Texture,
    bind: wgpu::BindGroup,
    w: u32,
    h: u32,
    last_used_frame: u64,
    bytes: u64,
}

enum ImageTex {
    Rgba {
        tex: wgpu::Texture,
        bind: wgpu::BindGroup,
        w: u32,
        h: u32,
        format: wgpu::TextureFormat,
        last_used_frame: u64,
        bytes: u64,
    },
    /// For a user-provided texture view.
    User {
        bind: wgpu::BindGroup,
        w: u32,
        h: u32,
        last_used_frame: u64,
        bytes: u64,
    },
    Nv12 {
        tex_y: wgpu::Texture,
        tex_uv: wgpu::Texture,
        bind: wgpu::BindGroup,
        yuv_buf: wgpu::Buffer,
        w: u32,
        h: u32,
        color_info: ColorInfo,
        last_used_frame: u64,
        bytes: u64,
    },
}

#[derive(Clone)]
struct RetainedImage {
    w: u32,
    h: u32,
    format: wgpu::TextureFormat,
    rgba: Vec<u8>,
}

struct AtlasA8 {
    tex: wgpu::Texture,
    view: wgpu::TextureView,
    sampler: wgpu::Sampler,
    size: u32,
    next_x: u32,
    next_y: u32,
    row_h: u32,
    map: HashMap<(repose_text::GlyphKey, u32), GlyphInfo>,
}

struct AtlasRGBA {
    tex: wgpu::Texture,
    view: wgpu::TextureView,
    sampler: wgpu::Sampler,
    size: u32,
    next_x: u32,
    next_y: u32,
    row_h: u32,
    map: HashMap<(repose_text::GlyphKey, u32), GlyphInfo>,
}

#[derive(Clone, Copy)]
struct GlyphInfo {
    u0: f32,
    v0: f32,
    u1: f32,
    v1: f32,
    w: f32,
    h: f32,
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct RectInstance {
    xywh: [f32; 4],
    radii: [f32; 4],
    brush_type: u32,
    grad_kind: u32,
    _pad: [f32; 2],
    color0: [f32; 4],
    color1: [f32; 4],
    grad_p0: [f32; 2],
    grad_p1: [f32; 2],
    tile_mode: u32,
    _pad2: [f32; 3],
    fwd_mat: [f32; 4],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct BorderInstance {
    xywh: [f32; 4],
    radii: [f32; 4],
    stroke: f32,
    brush_type: u32,
    _pad: [f32; 2],
    grad_kind: u32,
    color0: [f32; 4],
    color1: [f32; 4],
    grad_p0: [f32; 2],
    grad_p1: [f32; 2],
    tile_mode: u32,
    _pad2: [f32; 3],
    fwd_mat: [f32; 4],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct EllipseInstance {
    xywh: [f32; 4],
    brush_type: u32,
    grad_kind: u32,
    _pad: [f32; 2],
    color0: [f32; 4],
    color1: [f32; 4],
    grad_p0: [f32; 2],
    grad_p1: [f32; 2],
    tile_mode: u32,
    _pad2: [f32; 3],
    fwd_mat: [f32; 4],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct EllipseBorderInstance {
    xywh: [f32; 4],
    stroke: f32,
    pad: f32,
    brush_type: u32,
    grad_kind: u32,
    color0: [f32; 4],
    color1: [f32; 4],
    grad_p0: [f32; 2],
    grad_p1: [f32; 2],
    tile_mode: u32,
    _pad2: [f32; 3],
    fwd_mat: [f32; 4],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct ArcInstance {
    xywh: [f32; 4],
    start_angle: f32,
    sweep_angle: f32,
    stroke: f32,
    pad: f32,
    brush_type: u32,
    grad_kind: u32,
    _pad0: [f32; 2],
    color0: [f32; 4],
    color1: [f32; 4],
    grad_p0: [f32; 2],
    grad_p1: [f32; 2],
    tile_mode: u32,
    cap: f32, // 0=Butt, 1=Round, 2=Square
    _pad1: [f32; 2],
    fwd_mat: [f32; 4],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct GlyphInstance {
    xywh: [f32; 4],
    uv: [f32; 4],
    color: [f32; 4],
    fwd_mat: [f32; 4],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct BlurInstance {
    xywh: [f32; 4],
    uv: [f32; 4],
    color: [f32; 4],
    blur_uv: [f32; 2],
    fwd_mat: [f32; 4],
}

/// Projective layer-composite instance: the four layer-rect corners projected
/// to NDC (`c0..c3`, counter-clockwise from top-left) with their homogeneous
/// `w`, the layer-texture uv bounds, and a group alpha. Matches
/// `projective_layer.wgsl` (offsets: c0@0 c1@8 c2@16 c3@24 uv@32 w@48
/// alpha@64; stride 80).
#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct ProjectiveInstance {
    c0: [f32; 2],
    c1: [f32; 2],
    c2: [f32; 2],
    c3: [f32; 2],
    uv: [f32; 4],
    w: [f32; 4],
    alpha: f32,
    _pad: [f32; 3],
}

/// CPU-computed Y′CbCr -> R′G′B′ transform uploaded as a uniform buffer.
/// Layout matches the WGSL `YuvTransform` struct (4 × vec4<f32>).
#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct YuvTransformRaw {
    row0: [f32; 4],
    row1: [f32; 4],
    row2: [f32; 4],
    b: [f32; 4],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct Nv12Instance {
    xywh: [f32; 4],
    uv: [f32; 4],
    color: [f32; 4], // tint
    uv_x_offset: f32,
    fwd_mat: [f32; 4],
    _pad: [f32; 1],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct ClipInstance {
    xywh: [f32; 4],
    radii: [f32; 4],
    fwd_mat: [f32; 4],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct MeshVertex {
    pos: [f32; 2],
    color: [f32; 4],
    uv: [f32; 2],
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct MeshUniform {
    m0: [f32; 4],
    m1: [f32; 4],
    paint: [u32; 4],
    color0: [f32; 4],
    color1: [f32; 4],
    grad_start: [f32; 2],
    _p3: [f32; 2],
    grad_end: [f32; 2],
    _p4: [f32; 2],
}

/// Dynamic uniform slots are aligned to 256 bytes by wgpu.
const MESH_UNIFORM_SLOT: u64 = 256;
const MESH_UNIFORM_CAP: u64 = 4 * 1024 * 1024;

impl MeshUniform {
    fn identity() -> Self {
        Self {
            m0: [1.0, 0.0, 0.0, 0.0],
            m1: [0.0, 1.0, 0.0, 0.0],
            paint: [0; 4],
            color0: [0.0; 4],
            color1: [0.0; 4],
            grad_start: [0.0; 2],
            _p3: [0.0; 2],
            grad_end: [0.0; 2],
            _p4: [0.0; 2],
        }
    }
}

fn mesh_uniform_from_paint(affine: [f32; 6], paint: &repose_core::PaintDesc) -> MeshUniform {
    let (paint_type, paint_kind, color0, color1, grad_start, grad_end) = match paint {
        repose_core::PaintDesc::Solid => (0u32, 0u32, [0.0; 4], [0.0; 4], [0.0; 2], [0.0; 2]),
        repose_core::PaintDesc::Linear {
            start,
            end,
            start_color,
            end_color,
        } => (
            1u32,
            0u32,
            start_color.to_linear(),
            end_color.to_linear(),
            [start.x, start.y],
            [end.x, end.y],
        ),
        repose_core::PaintDesc::Radial {
            center,
            radius,
            start_color,
            end_color,
        } => (
            1u32,
            1u32,
            start_color.to_linear(),
            end_color.to_linear(),
            [center.x, center.y],
            [radius.max(0.0), 0.0],
        ),
        repose_core::PaintDesc::Sweep {
            center,
            start_color,
            end_color,
        } => (
            1u32,
            2u32,
            start_color.to_linear(),
            end_color.to_linear(),
            [center.x, center.y],
            [0.0, 0.0],
        ),
        _ => (0u32, 0u32, [0.0; 4], [0.0; 4], [0.0; 2], [0.0; 2]),
    };
    MeshUniform {
        m0: [affine[0], affine[1], affine[2], 0.0],
        m1: [affine[3], affine[4], affine[5], 0.0],
        paint: [paint_type, paint_kind, 0, 0],
        color0,
        color1,
        grad_start,
        _p3: [0.0; 2],
        grad_end,
        _p4: [0.0; 2],
    }
}

fn combine_mesh_affine(current: &Transform, mesh: [f32; 6]) -> [f32; 6] {
    let cm = current.linear();
    let (cm00, cm01, cm10, cm11) = (cm[0], cm[1], cm[2], cm[3]);
    let mm00 = mesh[0];
    let mm01 = mesh[1];
    let mm10 = mesh[2];
    let mm11 = mesh[3];
    let mtx = mesh[4];
    let mty = mesh[5];
    let r00 = cm00 * mm00 + cm01 * mm10;
    let r01 = cm00 * mm01 + cm01 * mm11;
    let r10 = cm10 * mm00 + cm11 * mm10;
    let r11 = cm10 * mm01 + cm11 * mm11;
    let tx = cm00 * mtx + cm01 * mty + current.translate_x;
    let ty = cm10 * mtx + cm11 * mty + current.translate_y;
    // Canonical slot order consumed by `MeshUniform`/shader and `mesh_aabb`:
    // [A, B, tx, C, D, ty] where world = [[A,B],[C,D]] * local + (tx, ty).
    [r00, r01, tx, r10, r11, ty]
}

fn mesh_aabb(mesh: &repose_core::VectorMeshData, affine: [f32; 6]) -> repose_core::Rect {
    let mut min_x = f32::MAX;
    let mut min_y = f32::MAX;
    let mut max_x = f32::MIN;
    let mut max_y = f32::MIN;
    for v in mesh.vertices.iter() {
        let x = affine[0] * v.pos[0] + affine[1] * v.pos[1] + affine[2];
        let y = affine[3] * v.pos[0] + affine[4] * v.pos[1] + affine[5];
        min_x = min_x.min(x);
        min_y = min_y.min(y);
        max_x = max_x.max(x);
        max_y = max_y.max(y);
    }
    let w = (max_x - min_x).max(0.0);
    let h = (max_y - min_y).max(0.0);
    if !min_x.is_finite() || !min_y.is_finite() {
        return repose_core::Rect {
            x: 0.0,
            y: 0.0,
            w: 0.0,
            h: 0.0,
        };
    }
    repose_core::Rect {
        x: min_x,
        y: min_y,
        w,
        h,
    }
}

fn swash_to_a8_coverage(content: repose_text::SwashContent, data: &[u8]) -> Option<Vec<u8>> {
    match content {
        repose_text::SwashContent::Mask => Some(data.to_vec()),
        repose_text::SwashContent::SubpixelMask => {
            let mut out = Vec::with_capacity(data.len() / 4);
            for px in data.as_chunks::<4>().0 {
                let r = px[0];
                let g = px[1];
                let b = px[2];
                out.push(r.max(g).max(b));
            }
            Some(out)
        }
        repose_text::SwashContent::Color => None,
    }
}

impl WgpuSceneRenderer {
    pub fn from_device(
        device: wgpu::Device,
        queue: wgpu::Queue,
        output_format: wgpu::TextureFormat,
        msaa_samples: u32,
    ) -> Self {
        let globals_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("globals layout"),
            entries: &[wgpu::BindGroupLayoutEntry {
                binding: 0,
                visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
                ty: wgpu::BindingType::Buffer {
                    ty: wgpu::BufferBindingType::Uniform,
                    has_dynamic_offset: false,
                    min_binding_size: None,
                },
                count: None,
            }],
        });

        let globals_buf = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("globals buf"),
            size: std::mem::size_of::<Globals>() as u64,
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });

        let globals_bind = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("globals bind"),
            layout: &globals_layout,
            entries: &[wgpu::BindGroupEntry {
                binding: 0,
                resource: globals_buf.as_entire_binding(),
            }],
        });

        let ds_format = wgpu::TextureFormat::Depth24PlusStencil8;

        let stencil_for_content = wgpu::DepthStencilState {
            format: ds_format,
            depth_write_enabled: Some(false),
            depth_compare: Some(wgpu::CompareFunction::Always),
            stencil: wgpu::StencilState {
                front: wgpu::StencilFaceState {
                    // Equal (not LessEqual): inverse (`Difference`) vector
                    // masks work by keeping the depth while incrementing the
                    // masked pixels, so content must test exact equality.
                    // Outcomes match LessEqual everywhere except pre-existing
                    // stencil leaks, which now fail visibly instead of
                    // drawing through (unbalanced clips already warn).
                    compare: wgpu::CompareFunction::Equal,
                    fail_op: wgpu::StencilOperation::Keep,
                    depth_fail_op: wgpu::StencilOperation::Keep,
                    pass_op: wgpu::StencilOperation::Keep,
                },
                back: wgpu::StencilFaceState {
                    compare: wgpu::CompareFunction::Equal,
                    fail_op: wgpu::StencilOperation::Keep,
                    depth_fail_op: wgpu::StencilOperation::Keep,
                    pass_op: wgpu::StencilOperation::Keep,
                },
                read_mask: 0xFF,
                write_mask: 0x00,
            },
            bias: wgpu::DepthBiasState::default(),
        };

        let stencil_for_clip_inc = wgpu::DepthStencilState {
            format: ds_format,
            depth_write_enabled: Some(false),
            depth_compare: Some(wgpu::CompareFunction::Always),
            stencil: wgpu::StencilState {
                front: wgpu::StencilFaceState {
                    compare: wgpu::CompareFunction::Equal,
                    fail_op: wgpu::StencilOperation::Keep,
                    depth_fail_op: wgpu::StencilOperation::Keep,
                    pass_op: wgpu::StencilOperation::IncrementClamp,
                },
                back: wgpu::StencilFaceState {
                    compare: wgpu::CompareFunction::Equal,
                    fail_op: wgpu::StencilOperation::Keep,
                    depth_fail_op: wgpu::StencilOperation::Keep,
                    pass_op: wgpu::StencilOperation::IncrementClamp,
                },
                read_mask: 0xFF,
                write_mask: 0xFF,
            },
            bias: wgpu::DepthBiasState::default(),
        };

        let stencil_for_clip_dec = wgpu::DepthStencilState {
            format: ds_format,
            depth_write_enabled: Some(false),
            depth_compare: Some(wgpu::CompareFunction::Always),
            stencil: wgpu::StencilState {
                front: wgpu::StencilFaceState {
                    compare: wgpu::CompareFunction::Equal,
                    fail_op: wgpu::StencilOperation::Keep,
                    depth_fail_op: wgpu::StencilOperation::Keep,
                    pass_op: wgpu::StencilOperation::DecrementClamp,
                },
                back: wgpu::StencilFaceState {
                    compare: wgpu::CompareFunction::Equal,
                    fail_op: wgpu::StencilOperation::Keep,
                    depth_fail_op: wgpu::StencilOperation::Keep,
                    pass_op: wgpu::StencilOperation::DecrementClamp,
                },
                read_mask: 0xFF,
                write_mask: 0xFF,
            },
            bias: wgpu::DepthBiasState::default(),
        };

        let _multisample_state = wgpu::MultisampleState {
            count: msaa_samples,
            mask: !0,
            alpha_to_coverage_enabled: false,
        };

        // PIPELINES

        // Single shared sampler for images/text
        let image_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("image/text sampler"),
            address_mode_u: wgpu::AddressMode::ClampToEdge,
            address_mode_v: wgpu::AddressMode::ClampToEdge,
            mag_filter: wgpu::FilterMode::Linear,
            min_filter: wgpu::FilterMode::Linear,
            mipmap_filter: wgpu::MipmapFilterMode::Linear,
            ..Default::default()
        });

        // linear filtering only blurs them; nearest keeps the blit crisp.
        let layer_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("layer nearest sampler"),
            address_mode_u: wgpu::AddressMode::ClampToEdge,
            address_mode_v: wgpu::AddressMode::ClampToEdge,
            mag_filter: wgpu::FilterMode::Nearest,
            min_filter: wgpu::FilterMode::Nearest,
            mipmap_filter: wgpu::MipmapFilterMode::Nearest,
            ..Default::default()
        });

        // Linear taps for Gaussian blur/shadow passes; nearest is kept for
        // the sharp 1:1 layer composite.
        let layer_sampler_linear = device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("layer linear sampler"),
            address_mode_u: wgpu::AddressMode::ClampToEdge,
            address_mode_v: wgpu::AddressMode::ClampToEdge,
            mag_filter: wgpu::FilterMode::Linear,
            min_filter: wgpu::FilterMode::Linear,
            mipmap_filter: wgpu::MipmapFilterMode::Linear,
            ..Default::default()
        });

        // Layout for Text / RGBA Images (Texture + Sampler)
        let text_bind_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("text/rgba bind layout"),
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Texture {
                        multisampled: false,
                        view_dimension: wgpu::TextureViewDimension::D2,
                        sample_type: wgpu::TextureSampleType::Float { filterable: true },
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
                    count: None,
                },
            ],
        });
        // We reuse this for RGBA images for simplicity, or create a distinct one
        let image_bind_layout_rgba = text_bind_layout.clone();

        // Layout for NV12 Images (TextureY + TextureUV + Sampler + YuvTransform uniform)
        let image_bind_layout_nv12 =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("image bind layout nv12"),
                entries: &[
                    // Y plane
                    wgpu::BindGroupLayoutEntry {
                        binding: 0,
                        visibility: wgpu::ShaderStages::FRAGMENT,
                        ty: wgpu::BindingType::Texture {
                            multisampled: false,
                            view_dimension: wgpu::TextureViewDimension::D2,
                            sample_type: wgpu::TextureSampleType::Float { filterable: true },
                        },
                        count: None,
                    },
                    // UV plane
                    wgpu::BindGroupLayoutEntry {
                        binding: 1,
                        visibility: wgpu::ShaderStages::FRAGMENT,
                        ty: wgpu::BindingType::Texture {
                            multisampled: false,
                            view_dimension: wgpu::TextureViewDimension::D2,
                            sample_type: wgpu::TextureSampleType::Float { filterable: true },
                        },
                        count: None,
                    },
                    // Sampler
                    wgpu::BindGroupLayoutEntry {
                        binding: 2,
                        visibility: wgpu::ShaderStages::FRAGMENT,
                        ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
                        count: None,
                    },
                    // YUV transform uniform buffer
                    wgpu::BindGroupLayoutEntry {
                        binding: 3,
                        visibility: wgpu::ShaderStages::FRAGMENT,
                        ty: wgpu::BindingType::Buffer {
                            ty: wgpu::BufferBindingType::Uniform,
                            has_dynamic_offset: false,
                            min_binding_size: None,
                        },
                        count: None,
                    },
                ],
            });

        // Clipping layout
        let clip_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("clip pipeline layout"),
            bind_group_layouts: &[Some(&globals_layout)],
            immediate_size: 0,
        });
        let clip_vertex_layout = wgpu::VertexBufferLayout {
            array_stride: std::mem::size_of::<ClipInstance>() as u64,
            step_mode: wgpu::VertexStepMode::Instance,
            attributes: &[
                wgpu::VertexAttribute {
                    shader_location: 0,
                    offset: 0,
                    format: wgpu::VertexFormat::Float32x4,
                },
                wgpu::VertexAttribute {
                    shader_location: 1,
                    offset: 16,
                    format: wgpu::VertexFormat::Float32x4,
                },
                wgpu::VertexAttribute {
                    shader_location: 2,
                    offset: 32,
                    format: wgpu::VertexFormat::Float32x4,
                },
            ],
        };
        let clip_color_target = wgpu::ColorTargetState {
            format: output_format,
            blend: None,
            write_mask: wgpu::ColorWrites::empty(),
        };

        // Bind layout for per-draw vector mesh uniforms (dynamic offset).
        let mesh_bind_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("mesh uniform layout"),
            entries: &[wgpu::BindGroupLayoutEntry {
                binding: 0,
                visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
                ty: wgpu::BindingType::Buffer {
                    ty: wgpu::BufferBindingType::Uniform,
                    has_dynamic_offset: true,
                    min_binding_size: NonZero::new(MESH_UNIFORM_SLOT),
                },
                count: None,
            }],
        });
        let mesh_uniform_buf = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("mesh uniform buffer"),
            size: MESH_UNIFORM_CAP,
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        let mesh_bind = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("mesh uniform bind"),
            layout: &mesh_bind_layout,
            entries: &[wgpu::BindGroupEntry {
                binding: 0,
                resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
                    buffer: &mesh_uniform_buf,
                    offset: 0,
                    size: NonZero::new(MESH_UNIFORM_SLOT),
                }),
            }],
        });

        // Two sets of pipelines: one for the MSAA surface pass, one for layer
        // render-to-texture passes (sample_count = 1).
        let surface_pipes = Pipelines::create(
            &device,
            output_format,
            msaa_samples,
            &globals_layout,
            &text_bind_layout,
            &image_bind_layout_nv12,
            &clip_pipeline_layout,
            &stencil_for_content,
            &stencil_for_clip_inc,
            &stencil_for_clip_dec,
            &clip_color_target,
            &clip_vertex_layout,
            &mesh_bind_layout,
        );
        let layer_pipes = Pipelines::create(
            &device,
            output_format,
            1,
            &globals_layout,
            &text_bind_layout,
            &image_bind_layout_nv12,
            &clip_pipeline_layout,
            &stencil_for_content,
            &stencil_for_clip_inc,
            &stencil_for_clip_dec,
            &clip_color_target,
            &clip_vertex_layout,
            &mesh_bind_layout,
        );

        // Vector glyph rendering always available with tessellation+MSAA approach.
        let slug_enabled = true;

        // Blur composite ring (for graphics-layer drop shadows)
        let blur_ring = UploadRing::new(
            &device,
            "blur ring",
            1024 * 1024,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );

        // Atlases
        let atlas_mask = init_atlas_mask(&device);
        let atlas_color = init_atlas_color(&device);

        // Upload rings
        let ring_rect = UploadRing::new(
            &device,
            "ring rect",
            1 << 20,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_border = UploadRing::new(
            &device,
            "ring border",
            1 << 20,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_ellipse = UploadRing::new(
            &device,
            "ring ellipse",
            1 << 20,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_ellipse_border = UploadRing::new(
            &device,
            "ring ellipse border",
            1 << 20,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_arc = UploadRing::new(
            &device,
            "ring arc",
            1 << 20,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_glyph_mask = UploadRing::new(
            &device,
            "ring glyph mask",
            1 << 20,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_glyph_color = UploadRing::new(
            &device,
            "ring glyph color",
            1 << 20,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_slug = UploadRing::new(
            &device,
            "ring slug",
            1 << 22,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_clip = UploadRing::new(
            &device,
            "ring clip",
            1 << 16,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_projective = UploadRing::new(
            &device,
            "ring projective",
            1 << 16,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_nv12 = UploadRing::new(
            &device,
            "ring nv12",
            1 << 20,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_mesh_verts = UploadRing::new(
            &device,
            "ring mesh verts",
            1 << 22,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let ring_mesh_indices = UploadRing::new(
            &device,
            "ring mesh indices",
            1 << 22,
            wgpu::BufferUsages::INDEX | wgpu::BufferUsages::COPY_DST,
        );

        // Placeholder textures
        let depth_stencil_tex = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("temp ds"),
            size: wgpu::Extent3d {
                width: 1,
                height: 1,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Depth24PlusStencil8,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            view_formats: &[],
        });
        let depth_stencil_view =
            depth_stencil_tex.create_view(&wgpu::TextureViewDescriptor::default());

        let mut renderer = WgpuSceneRenderer {
            device,
            queue,
            output_format,
            output_width: 0,
            output_height: 0,
            pixels_per_point: 1.0,

            surface_pipes,
            layer_pipes,

            rects: InstancedPipe::new(ring_rect),
            borders: InstancedPipe::new(ring_border),
            ellipses: InstancedPipe::new(ring_ellipse),
            ellipse_borders: InstancedPipe::new(ring_ellipse_border),
            arcs: InstancedPipe::new(ring_arc),
            glyph_mask: InstancedPipe::new(ring_glyph_mask),
            glyph_color: InstancedPipe::new(ring_glyph_color),

            text_bind_layout,

            image_bind_layout_rgba,
            image_bind_layout_nv12,
            image_sampler,
            layer_sampler,
            layer_sampler_linear,

            blur_ring,

            slug_enabled,
            slug_ring: ring_slug,
            slug_cache: slug::GlyphSlugCache::new(),

            clip_ring: ring_clip,

            nv12: InstancedPipe::new(ring_nv12),

            mesh_verts: ring_mesh_verts,
            mesh_indices: ring_mesh_indices,
            mesh_uniform_buf,
            mesh_bind_layout,
            mesh_bind,
            mesh_uniform_head: 0,
            mesh_clip_stack: Vec::new(),

            projective_ring: ring_projective,
            flatten_layer_ids: Vec::new(),

            msaa_samples,
            depth_stencil_tex,
            depth_stencil_view,
            msaa_tex: None,
            msaa_view: None,
            globals_bind,
            globals_buf,

            atlas_mask,
            atlas_color,

            next_image_handle: 1,
            images: HashMap::new(),
            retained: HashMap::new(),

            next_coverage_handle: 1,
            coverages: HashMap::new(),

            frame_index: 0,
            image_bytes_total: 0,
            image_evict_after_frames: 600,         // ~10s @ 60fps
            image_budget_bytes: 512 * 1024 * 1024, // 512 MB
            layer_pool: HashMap::new(),

            working_space: false,
            ws_tex: None,
            ws_view: None,
            ws_bind: None,
            display_pipeline: None,
            display_layout: None,

            callback_resources: CallbackResources::default(),
        };

        renderer.recreate_msaa_and_depth_stencil();
        renderer
    }
}

impl WgpuSurfaceBackend {
    #[cfg(feature = "winit-surface")]
    pub async fn new_async(
        window: Arc<winit::window::Window>,
    ) -> anyhow::Result<WgpuSurfaceBackend> {
        Self::new_async_with_options(window, 4, PresentModePref::Auto).await
    }

    /// Create a windowed surface backend, honoring the requested MSAA sample
    /// count (falling back to the largest supported count <= `msaa_samples`).
    #[cfg(feature = "winit-surface")]
    pub async fn new_async_with_msaa(
        window: Arc<winit::window::Window>,
        msaa_samples: u32,
    ) -> anyhow::Result<WgpuSurfaceBackend> {
        Self::new_async_with_options(window, msaa_samples, PresentModePref::Auto).await
    }

    /// Create a windowed surface backend, honoring the requested MSAA sample
    /// count and present-mode preference.
    #[cfg(feature = "winit-surface")]
    pub async fn new_async_with_options(
        window: Arc<winit::window::Window>,
        msaa_samples: u32,
        present_mode: PresentModePref,
    ) -> anyhow::Result<WgpuSurfaceBackend> {
        let instance: Instance = if cfg!(target_arch = "wasm32") {
            let mut desc = wgpu::InstanceDescriptor::new_without_display_handle();
            desc.backends = wgpu::Backends::BROWSER_WEBGPU | wgpu::Backends::GL;
            wgpu::util::new_instance_with_webgpu_detection(desc).await
        } else {
            wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle())
        };

        let surface = instance.create_surface(window.clone())?;

        let adapter = instance
            .request_adapter(&wgpu::RequestAdapterOptions {
                power_preference: wgpu::PowerPreference::HighPerformance,
                compatible_surface: Some(&surface),
                force_fallback_adapter: false,
                apply_limit_buckets: false,
            })
            .await
            .map_err(|e| anyhow::anyhow!("No suitable adapter: {e:?}"))?;

        let limits = adapter.limits();

        #[cfg(target_os = "linux")]
        let features = {
            let af = adapter.features();
            let mut f = wgpu::Features::empty();
            if af.contains(wgpu::Features::VULKAN_EXTERNAL_MEMORY_FD) {
                f |= wgpu::Features::VULKAN_EXTERNAL_MEMORY_FD;
            }
            if af.contains(wgpu::Features::VULKAN_EXTERNAL_MEMORY_DMA_BUF) {
                f |= wgpu::Features::VULKAN_EXTERNAL_MEMORY_DMA_BUF;
            }
            f
        };
        #[cfg(not(target_os = "linux"))]
        let features = wgpu::Features::empty();

        let (device, queue) = adapter
            .request_device(&wgpu::DeviceDescriptor {
                label: Some("repose-rs device"),
                required_features: features,
                required_limits: limits,
                experimental_features: wgpu::ExperimentalFeatures::disabled(),
                memory_hints: wgpu::MemoryHints::default(),
                trace: wgpu::Trace::Off,
            })
            .await
            .map_err(|e| anyhow::anyhow!("request_device failed: {e:?}"))?;

        let size = window.inner_size();

        let caps = surface.get_capabilities(&adapter);

        let (format, view_format) = if cfg!(target_arch = "wasm32")
            && adapter
                .get_downlevel_capabilities()
                .flags
                .contains(wgpu::DownlevelFlags::SURFACE_VIEW_FORMATS)
        {
            let non_srgb = caps
                .formats
                .iter()
                .copied()
                .find(|f| !f.is_srgb())
                .unwrap_or(caps.formats[0]);
            (non_srgb, Some(non_srgb.add_srgb_suffix()))
        } else if cfg!(target_arch = "wasm32") {
            let fmt = caps
                .formats
                .iter()
                .copied()
                .find(|f| f.is_srgb())
                .unwrap_or(caps.formats[0]);
            (fmt, None)
        } else {
            let fmt = caps
                .formats
                .iter()
                .copied()
                .find(|f| f.is_srgb())
                .unwrap_or(caps.formats[0]);
            (fmt, None)
        };

        let present_mode = pick_present_mode(&caps, present_mode);
        let alpha_mode = caps.alpha_modes[0];

        let render_format = view_format.unwrap_or(format);
        let msaa_samples = pick_surface_msaa(&adapter, format, msaa_samples);
        let renderer = WgpuSceneRenderer::from_device(device, queue, render_format, msaa_samples);

        let view_formats = view_format.into_iter().collect::<Vec<_>>();

        let config = wgpu::SurfaceConfiguration {
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            format,
            width: size.width.max(1),
            height: size.height.max(1),
            present_mode,
            alpha_mode,
            color_space: wgpu::SurfaceColorSpace::Auto,
            view_formats,
            desired_maximum_frame_latency: 1,
        };
        surface.configure(&renderer.device, &config);

        Ok(WgpuSurfaceBackend {
            surface: Some(surface),
            surface_config: Some(config),
            renderer,
        })
    }

    #[cfg(all(feature = "winit-surface", not(target_arch = "wasm32")))]
    pub fn new(window: Arc<winit::window::Window>) -> anyhow::Result<WgpuSurfaceBackend> {
        pollster::block_on(Self::new_async(window))
    }

    #[cfg(all(feature = "winit-surface", not(target_arch = "wasm32")))]
    pub fn new_with_msaa(
        window: Arc<winit::window::Window>,
        msaa_samples: u32,
    ) -> anyhow::Result<WgpuSurfaceBackend> {
        pollster::block_on(Self::new_async_with_msaa(window, msaa_samples))
    }

    #[cfg(all(feature = "winit-surface", not(target_arch = "wasm32")))]
    pub fn new_with_options(
        window: Arc<winit::window::Window>,
        msaa_samples: u32,
        present_mode: PresentModePref,
    ) -> anyhow::Result<WgpuSurfaceBackend> {
        pollster::block_on(Self::new_async_with_options(
            window,
            msaa_samples,
            present_mode,
        ))
    }

    #[cfg(all(feature = "winit-surface", target_arch = "wasm32"))]
    pub fn new(_window: Arc<winit::window::Window>) -> anyhow::Result<WgpuSurfaceBackend> {
        anyhow::bail!("Use WgpuSurfaceBackend::new_async(window).await on wasm32")
    }

    #[cfg(all(feature = "winit-surface", target_arch = "wasm32"))]
    pub fn new_with_msaa(
        _window: Arc<winit::window::Window>,
        _msaa_samples: u32,
    ) -> anyhow::Result<WgpuSurfaceBackend> {
        anyhow::bail!("Use WgpuSurfaceBackend::new_async_with_msaa(window, msaa).await on wasm32")
    }

    #[cfg(all(feature = "winit-surface", target_arch = "wasm32"))]
    pub fn new_with_options(
        _window: Arc<winit::window::Window>,
        _msaa_samples: u32,
        _present_mode: PresentModePref,
    ) -> anyhow::Result<WgpuSurfaceBackend> {
        anyhow::bail!(
            "Use WgpuSurfaceBackend::new_async_with_options(window, msaa, mode).await on wasm32"
        )
    }
}

/// Pick the swapchain present mode honoring `pref`, falling back to an "auto"
/// Fifo-first selection when the preferred mode is unavailable.
fn pick_present_mode(caps: &wgpu::SurfaceCapabilities, pref: PresentModePref) -> wgpu::PresentMode {
    let auto = || {
        caps.present_modes
            .iter()
            .copied()
            .find(|m| *m == wgpu::PresentMode::Fifo)
            .or_else(|| {
                caps.present_modes
                    .iter()
                    .copied()
                    .find(|m| *m == wgpu::PresentMode::Mailbox)
            })
            .unwrap_or(wgpu::PresentMode::Immediate)
    };
    match pref {
        PresentModePref::Auto => auto(),
        PresentModePref::Fifo if caps.present_modes.contains(&wgpu::PresentMode::Fifo) => {
            wgpu::PresentMode::Fifo
        }
        PresentModePref::Mailbox if caps.present_modes.contains(&wgpu::PresentMode::Mailbox) => {
            wgpu::PresentMode::Mailbox
        }
        PresentModePref::Immediate
            if caps.present_modes.contains(&wgpu::PresentMode::Immediate) =>
        {
            wgpu::PresentMode::Immediate
        }
        _ => auto(),
    }
}

/// Pick the MSAA sample count for the surface pass, honoring `requested` and
/// falling back to the largest supported count <= it.
pub fn pick_surface_msaa(
    adapter: &wgpu::Adapter,
    format: wgpu::TextureFormat,
    requested: u32,
) -> u32 {
    let requested = requested.max(1);
    let color_feat = adapter.get_texture_format_features(format);
    let depth_feat = adapter.get_texture_format_features(wgpu::TextureFormat::Depth24PlusStencil8);
    let supported = |n: u32| {
        color_feat.flags.sample_count_supported(n)
            && color_feat
                .flags
                .contains(wgpu::TextureFormatFeatureFlags::MULTISAMPLE_RESOLVE)
            && depth_feat.flags.sample_count_supported(n)
    };
    let mut candidates = vec![requested];
    for n in [8, 4, 2, 1] {
        if n < requested {
            candidates.push(n);
        }
    }
    let chosen = candidates.into_iter().find(|&n| supported(n)).unwrap_or(1);
    if chosen != requested {
        log::info!("requested MSAA x{requested}, using x{chosen}");
    }
    chosen
}

impl WgpuSceneRenderer {
    // Image API

    pub fn set_image_from_bytes(
        &mut self,
        handle: u64,
        data: &[u8],
        srgb: bool,
    ) -> anyhow::Result<()> {
        let img = image::load_from_memory(data)?;
        let rgba = img.to_rgba8();
        let (w, h) = rgba.dimensions();
        self.set_image_rgba8(handle, w, h, &rgba, srgb)
    }

    pub fn set_image_rgba8(
        &mut self,
        handle: u64,
        w: u32,
        h: u32,
        rgba: &[u8],
        srgb: bool,
    ) -> anyhow::Result<()> {
        let expected = (w as usize) * (h as usize) * 4;
        if rgba.len() < expected {
            return Err(anyhow::anyhow!(
                "RGBA buffer too small: {} < {}",
                rgba.len(),
                expected
            ));
        }

        let format = if srgb {
            wgpu::TextureFormat::Rgba8UnormSrgb
        } else {
            wgpu::TextureFormat::Rgba8Unorm
        };

        let needs_recreate = match self.images.get(&handle) {
            Some(ImageTex::Rgba {
                w: cw,
                h: ch,
                format: cf,
                ..
            }) => *cw != w || *ch != h || *cf != format,
            _ => true,
        };

        if needs_recreate {
            self.remove_image(handle);

            let (tex, bind) = self.create_rgba_tex(w, h, format);
            let bytes = (w as u64) * (h as u64) * 4;
            self.image_bytes_total += bytes;

            self.images.insert(
                handle,
                ImageTex::Rgba {
                    tex,
                    bind,
                    w,
                    h,
                    format,
                    last_used_frame: self.frame_index,
                    bytes,
                },
            );
        }

        self.retained.insert(
            handle,
            RetainedImage {
                w,
                h,
                format,
                rgba: rgba[..expected].to_vec(),
            },
        );

        let tex = match self.images.get(&handle) {
            Some(ImageTex::Rgba { tex, .. }) => tex,
            _ => unreachable!(),
        };

        self.queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: tex,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &rgba[..expected],
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(4 * w),
                rows_per_image: Some(h),
            },
            wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
        );

        // Ensure budget limits
        self.evict_budget_excess();

        Ok(())
    }

    /// Create (but do not populate) the GPU texture, view and bind group for an
    /// RGBA image. Pixels are written separately via `write_texture`.
    fn create_rgba_tex(
        &self,
        w: u32,
        h: u32,
        format: wgpu::TextureFormat,
    ) -> (wgpu::Texture, wgpu::BindGroup) {
        let tex = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some("user image rgba"),
            size: wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format,
            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
            view_formats: &[],
        });
        let view = tex.create_view(&wgpu::TextureViewDescriptor::default());

        let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("image bind rgba"),
            layout: &self.image_bind_layout_rgba,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.image_sampler),
                },
            ],
        });

        (tex, bind)
    }

    /// Register an externally-created `wgpu::TextureView` as an image (zero-copy).
    pub fn register_native_texture(
        &mut self,
        view: &wgpu::TextureView,
        width: u32,
        height: u32,
    ) -> u64 {
        let handle = self.next_image_handle;
        self.next_image_handle += 1;
        let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("user native image"),
            layout: &self.image_bind_layout_rgba,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.image_sampler),
                },
            ],
        });
        self.images.insert(
            handle,
            ImageTex::User {
                bind,
                w: width,
                h: height,
                last_used_frame: self.frame_index,
                bytes: 0,
            },
        );
        handle
    }

    /// Like `register_native_texture` but with custom sampler descriptor.
    pub fn register_native_texture_with_sampler(
        &mut self,
        view: &wgpu::TextureView,
        sampler_desc: wgpu::SamplerDescriptor<'_>,
        width: u32,
        height: u32,
    ) -> u64 {
        let handle = self.next_image_handle;
        self.next_image_handle += 1;
        let sampler = self.device.create_sampler(&sampler_desc);
        let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("user native image sampleropts"),
            layout: &self.image_bind_layout_rgba,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&sampler),
                },
            ],
        });
        self.images.insert(
            handle,
            ImageTex::User {
                bind,
                w: width,
                h: height,
                last_used_frame: self.frame_index,
                bytes: 0,
            },
        );
        handle
    }

    /// Update an existing native texture handle with a new view (reuse handle).
    pub fn update_native_texture(&mut self, handle: u64, view: &wgpu::TextureView) {
        let Some(entry) = self.images.get_mut(&handle) else {
            log::warn!("update_native_texture: handle {handle} not found");
            return;
        };
        let w = match entry {
            ImageTex::User { w, .. } => *w,
            ImageTex::Rgba { w, .. } => *w,
            _ => {
                log::warn!("update_native_texture: handle {handle} is not rgba/user");
                return;
            }
        };
        let h = match entry {
            ImageTex::User { h, .. } => *h,
            ImageTex::Rgba { h, .. } => *h,
            _ => 0,
        };
        let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("user native image update"),
            layout: &self.image_bind_layout_rgba,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.image_sampler),
                },
            ],
        });
        *entry = ImageTex::User {
            bind,
            w,
            h,
            last_used_frame: self.frame_index,
            bytes: 0,
        };
    }

    pub fn set_image_nv12(
        &mut self,
        handle: u64,
        w: u32,
        h: u32,
        y: &[u8],
        uv: &[u8],
        color_info: ColorInfo,
    ) -> anyhow::Result<()> {
        let y_expected = (w as usize) * (h as usize);
        let uv_w = w.div_ceil(2);
        let uv_h = h.div_ceil(2);
        let uv_expected = (uv_w as usize) * (uv_h as usize) * 2;

        if y.len() < y_expected {
            return Err(anyhow::anyhow!("Y plane too small"));
        }
        if uv.len() < uv_expected {
            return Err(anyhow::anyhow!("UV plane too small"));
        }

        let needs_recreate = match self.images.get(&handle) {
            Some(ImageTex::Nv12 { w: ww, h: hh, .. }) => *ww != w || *hh != h,
            _ => true,
        };

        // Compute the YUV->RGB transform on the CPU.
        let yuv = color_info.to_yuv_transform();
        let yuv_raw = YuvTransformRaw {
            row0: [yuv.m[0][0], yuv.m[0][1], yuv.m[0][2], 0.0],
            row1: [yuv.m[1][0], yuv.m[1][1], yuv.m[1][2], 0.0],
            row2: [yuv.m[2][0], yuv.m[2][1], yuv.m[2][2], 0.0],
            b: [yuv.b[0], yuv.b[1], yuv.b[2], 0.0],
        };

        if needs_recreate {
            self.remove_image(handle);

            let tex_y = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some("nv12 Y"),
                size: wgpu::Extent3d {
                    width: w,
                    height: h,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format: wgpu::TextureFormat::R8Unorm,
                usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
                view_formats: &[],
            });
            let view_y = tex_y.create_view(&wgpu::TextureViewDescriptor::default());

            let tex_uv = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some("nv12 UV"),
                size: wgpu::Extent3d {
                    width: uv_w,
                    height: uv_h,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format: wgpu::TextureFormat::Rg8Unorm,
                usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
                view_formats: &[],
            });
            let view_uv = tex_uv.create_view(&wgpu::TextureViewDescriptor::default());

            // Create a uniform buffer for the YUV transform (per-image).
            let yuv_buf = self.device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("nv12 yuv transform"),
                size: std::mem::size_of::<YuvTransformRaw>() as u64,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });

            // Write initial transform.
            self.queue
                .write_buffer(&yuv_buf, 0, bytemuck::bytes_of(&yuv_raw));

            let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some("nv12 bind"),
                layout: &self.image_bind_layout_nv12,
                entries: &[
                    wgpu::BindGroupEntry {
                        binding: 0,
                        resource: wgpu::BindingResource::TextureView(&view_y),
                    },
                    wgpu::BindGroupEntry {
                        binding: 1,
                        resource: wgpu::BindingResource::TextureView(&view_uv),
                    },
                    wgpu::BindGroupEntry {
                        binding: 2,
                        resource: wgpu::BindingResource::Sampler(&self.image_sampler),
                    },
                    wgpu::BindGroupEntry {
                        binding: 3,
                        resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
                            buffer: &yuv_buf,
                            offset: 0,
                            size: None,
                        }),
                    },
                ],
            });

            let bytes = (w as u64) * (h as u64)
                + (uv_w as u64) * (uv_h as u64) * 2
                + std::mem::size_of::<YuvTransformRaw>() as u64;
            self.image_bytes_total += bytes;

            self.images.insert(
                handle,
                ImageTex::Nv12 {
                    tex_y,
                    tex_uv,
                    bind,
                    yuv_buf,
                    w,
                    h,
                    color_info,
                    last_used_frame: self.frame_index,
                    bytes,
                },
            );
        } else {
            // Re-use existing textures; just update the YUV transform if needed.
            if let Some(ImageTex::Nv12 { yuv_buf, .. }) = self.images.get(&handle) {
                self.queue
                    .write_buffer(yuv_buf, 0, bytemuck::bytes_of(&yuv_raw));
            }
        }

        let (tex_y, tex_uv, _bind) = match self.images.get(&handle) {
            Some(ImageTex::Nv12 {
                tex_y,
                tex_uv,
                bind,
                ..
            }) => (tex_y, tex_uv, bind),
            _ => return Err(anyhow::anyhow!("Handle is not NV12")),
        };

        self.queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: tex_y,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &y[..y_expected],
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(w),
                rows_per_image: Some(h),
            },
            wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
        );

        self.queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: tex_uv,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &uv[..uv_expected],
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(2 * uv_w),
                rows_per_image: Some(uv_h),
            },
            wgpu::Extent3d {
                width: uv_w,
                height: uv_h,
                depth_or_array_layers: 1,
            },
        );

        self.evict_budget_excess();
        Ok(())
    }

    pub fn set_image_planes(
        &mut self,
        handle: u64,
        w: u32,
        h: u32,
        pixel_format: PixelFormat,
        planes: &[&[u8]],
        color_info: ColorInfo,
    ) -> anyhow::Result<()> {
        match pixel_format {
            PixelFormat::Nv12 => {
                let y = planes.first().ok_or(anyhow::anyhow!("missing Y plane"))?;
                let uv = planes.get(1).ok_or(anyhow::anyhow!("missing UV plane"))?;
                self.set_image_nv12(handle, w, h, y, uv, color_info)
            }
            PixelFormat::P010 => {
                let y = planes.first().ok_or(anyhow::anyhow!("missing Y plane"))?;
                let uv = planes.get(1).ok_or(anyhow::anyhow!("missing UV plane"))?;
                self.set_image_p010(handle, w, h, y, uv, color_info)
            }
            PixelFormat::I420 | PixelFormat::I444 => Err(anyhow::anyhow!(
                "I420/I444 not implemented and unlikely -> cheap to convert to NV12 (better for the GPU too)"
            )),
            PixelFormat::Rgba => {
                let rgba = planes
                    .first()
                    .ok_or(anyhow::anyhow!("missing RGBA plane"))?;
                self.set_image_rgba8(handle, w, h, rgba, false)
            }
        }
    }

    fn set_image_p010(
        &mut self,
        handle: u64,
        w: u32,
        h: u32,
        y: &[u8],
        uv: &[u8],
        color_info: ColorInfo,
    ) -> anyhow::Result<()> {
        let uv_w = w.div_ceil(2);
        let uv_h = h.div_ceil(2);

        let y_expected = (w as usize) * (h as usize) * 2;
        let uv_expected = (uv_w as usize) * (uv_h as usize) * 4;

        if y.len() < y_expected {
            return Err(anyhow::anyhow!("P010 Y plane too small"));
        }
        if uv.len() < uv_expected {
            return Err(anyhow::anyhow!("P010 UV plane too small"));
        }

        // P010 reuses the NV12 pipeline (same bind group layout -> wgpu
        // abstracts the storage format so R16Unorm/Rg16Unorm are
        // filterable float textures just like R8Unorm/Rg8Unorm).
        let needs_recreate = match self.images.get(&handle) {
            Some(ImageTex::Nv12 { w: ww, h: hh, .. }) => *ww != w || *hh != h,
            _ => true,
        };

        let yuv = color_info.to_yuv_transform();
        let yuv_raw = YuvTransformRaw {
            row0: [yuv.m[0][0], yuv.m[0][1], yuv.m[0][2], 0.0],
            row1: [yuv.m[1][0], yuv.m[1][1], yuv.m[1][2], 0.0],
            row2: [yuv.m[2][0], yuv.m[2][1], yuv.m[2][2], 0.0],
            b: [yuv.b[0], yuv.b[1], yuv.b[2], 0.0],
        };

        if needs_recreate {
            self.remove_image(handle);

            let tex_y = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some("p010 Y"),
                size: wgpu::Extent3d {
                    width: w,
                    height: h,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format: wgpu::TextureFormat::R16Unorm,
                usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
                view_formats: &[],
            });
            let view_y = tex_y.create_view(&wgpu::TextureViewDescriptor::default());

            let tex_uv = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some("p010 UV"),
                size: wgpu::Extent3d {
                    width: uv_w,
                    height: uv_h,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format: wgpu::TextureFormat::Rg16Unorm,
                usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
                view_formats: &[],
            });
            let view_uv = tex_uv.create_view(&wgpu::TextureViewDescriptor::default());

            let yuv_buf = self.device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("p010 yuv transform"),
                size: std::mem::size_of::<YuvTransformRaw>() as u64,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            self.queue
                .write_buffer(&yuv_buf, 0, bytemuck::bytes_of(&yuv_raw));

            let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some("p010 bind"),
                layout: &self.image_bind_layout_nv12,
                entries: &[
                    wgpu::BindGroupEntry {
                        binding: 0,
                        resource: wgpu::BindingResource::TextureView(&view_y),
                    },
                    wgpu::BindGroupEntry {
                        binding: 1,
                        resource: wgpu::BindingResource::TextureView(&view_uv),
                    },
                    wgpu::BindGroupEntry {
                        binding: 2,
                        resource: wgpu::BindingResource::Sampler(&self.image_sampler),
                    },
                    wgpu::BindGroupEntry {
                        binding: 3,
                        resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
                            buffer: &yuv_buf,
                            offset: 0,
                            size: None,
                        }),
                    },
                ],
            });

            let bytes = (w as u64) * (h as u64) * 2
                + (uv_w as u64) * (uv_h as u64) * 4
                + std::mem::size_of::<YuvTransformRaw>() as u64;
            self.image_bytes_total += bytes;

            self.images.insert(
                handle,
                ImageTex::Nv12 {
                    tex_y,
                    tex_uv,
                    bind,
                    yuv_buf,
                    w,
                    h,
                    color_info,
                    last_used_frame: self.frame_index,
                    bytes,
                },
            );
        } else {
            if let Some(ImageTex::Nv12 { yuv_buf, .. }) = self.images.get(&handle) {
                self.queue
                    .write_buffer(yuv_buf, 0, bytemuck::bytes_of(&yuv_raw));
            }
        }

        let (tex_y, tex_uv, _bind) = match self.images.get(&handle) {
            Some(ImageTex::Nv12 {
                tex_y,
                tex_uv,
                bind,
                ..
            }) => (tex_y, tex_uv, bind),
            _ => return Err(anyhow::anyhow!("Handle is not P010/NV12")),
        };

        self.queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: tex_y,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &y[..y_expected],
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(w * 2),
                rows_per_image: Some(h),
            },
            wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
        );
        self.queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: tex_uv,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &uv[..uv_expected],
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(uv_w * 4),
                rows_per_image: Some(uv_h),
            },
            wgpu::Extent3d {
                width: uv_w,
                height: uv_h,
                depth_or_array_layers: 1,
            },
        );

        self.evict_budget_excess();
        Ok(())
    }

    #[cfg(target_os = "linux")]
    pub fn set_image_dmabuf(
        &mut self,
        handle: u64,
        w: u32,
        h: u32,
        fds: Vec<std::os::unix::io::OwnedFd>,
        modifier: u64,
        strides: Vec<u32>,
        offsets: Vec<u64>,
        color_info: ColorInfo,
    ) -> anyhow::Result<()> {
        log::info!(
            "set_image_dmabuf handle={handle} {}x{} fds={} modifier=0x{modifier:x}",
            w,
            h,
            fds.len()
        );

        self.remove_image(handle);

        let yuv = color_info.to_yuv_transform();
        let yuv_raw = YuvTransformRaw {
            row0: [yuv.m[0][0], yuv.m[0][1], yuv.m[0][2], 0.0],
            row1: [yuv.m[1][0], yuv.m[1][1], yuv.m[1][2], 0.0],
            row2: [yuv.m[2][0], yuv.m[2][1], yuv.m[2][2], 0.0],
            b: [yuv.b[0], yuv.b[1], yuv.b[2], 0.0],
        };

        if fds.len() != 2 {
            return Err(anyhow::anyhow!(
                "unsupported fd count {} - need exactly 2 for separate Y/UV planes",
                fds.len()
            ));
        }

        let uv_w = w.div_ceil(2);
        let uv_h = h.div_ceil(2);

        let hal_y_desc = wgpu::hal::TextureDescriptor {
            label: Some("dmabuf y"),
            size: wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::R8Unorm,
            usage: wgpu::wgt::TextureUses::RESOURCE,
            memory_flags: wgpu::hal::MemoryFlags::empty(),
            view_formats: vec![],
        };
        let hal_uv_desc = wgpu::hal::TextureDescriptor {
            label: Some("dmabuf uv"),
            size: wgpu::Extent3d {
                width: uv_w,
                height: uv_h,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rg8Unorm,
            usage: wgpu::wgt::TextureUses::RESOURCE,
            memory_flags: wgpu::hal::MemoryFlags::empty(),
            view_formats: vec![],
        };

        let wgpu_y_desc = wgpu::TextureDescriptor {
            label: Some("dmabuf y"),
            size: wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::R8Unorm,
            usage: wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        };
        let wgpu_uv_desc = wgpu::TextureDescriptor {
            label: Some("dmabuf uv"),
            size: wgpu::Extent3d {
                width: uv_w,
                height: uv_h,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rg8Unorm,
            usage: wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        };

        let (tex_y, view_y, tex_uv, view_uv) = unsafe {
            let hal_guard = self
                .device
                .as_hal::<wgpu::hal::vulkan::Api>()
                .ok_or_else(|| {
                    log::warn!("as_hal::<vulkan::Api> returned None");
                    anyhow::anyhow!("Device is not Vulkan")
                })?;

            let mut fds = fds;
            let uv_fd = fds.remove(1);
            let y_fd = fds.remove(0);

            let yt = hal_guard
                .texture_from_dmabuf_fd(y_fd, &hal_y_desc, modifier, strides[0] as u64, offsets[0])
                .map_err(|e| anyhow::anyhow!("import Y dmabuf: {e:?}"))?;
            log::info!("imported Y dmabuf OK");

            let uvt = hal_guard
                .texture_from_dmabuf_fd(
                    uv_fd,
                    &hal_uv_desc,
                    modifier,
                    strides[1] as u64,
                    offsets[1],
                )
                .map_err(|e| anyhow::anyhow!("import UV dmabuf: {e:?}"))?;
            log::info!("imported UV dmabuf OK");

            drop(hal_guard);

            let tex_y = self
                .device
                .create_texture_from_hal::<wgpu::hal::vulkan::Api>(
                    yt,
                    &wgpu_y_desc,
                    wgpu::wgt::TextureUses::UNINITIALIZED,
                );
            let view_y = tex_y.create_view(&wgpu::TextureViewDescriptor::default());

            let tex_uv = self
                .device
                .create_texture_from_hal::<wgpu::hal::vulkan::Api>(
                    uvt,
                    &wgpu_uv_desc,
                    wgpu::wgt::TextureUses::UNINITIALIZED,
                );
            let view_uv = tex_uv.create_view(&wgpu::TextureViewDescriptor::default());

            (tex_y, view_y, tex_uv, view_uv)
        };

        let yuv_buf = self.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("dmabuf yuv transform"),
            size: std::mem::size_of::<YuvTransformRaw>() as u64,
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        self.queue
            .write_buffer(&yuv_buf, 0, bytemuck::bytes_of(&yuv_raw));

        let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("dmabuf nv12 bind"),
            layout: &self.image_bind_layout_nv12,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&view_y),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::TextureView(&view_uv),
                },
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: wgpu::BindingResource::Sampler(&self.image_sampler),
                },
                wgpu::BindGroupEntry {
                    binding: 3,
                    resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
                        buffer: &yuv_buf,
                        offset: 0,
                        size: None,
                    }),
                },
            ],
        });

        let bytes = (w as u64) * (h as u64)
            + (uv_w as u64) * (uv_h as u64) * 2
            + std::mem::size_of::<YuvTransformRaw>() as u64;

        self.images.insert(
            handle,
            ImageTex::Nv12 {
                tex_y,
                tex_uv,
                bind,
                yuv_buf,
                w,
                h,
                color_info,
                last_used_frame: self.frame_index,
                bytes,
            },
        );

        self.evict_budget_excess();
        Ok(())
    }

    pub fn remove_image(&mut self, handle: u64) {
        if let Some(img) = self.images.remove(&handle) {
            let b = match &img {
                ImageTex::Rgba { bytes, .. } => *bytes,
                ImageTex::Nv12 { bytes, .. } => *bytes,
                ImageTex::User { bytes, .. } => *bytes,
            };
            self.image_bytes_total = self.image_bytes_total.saturating_sub(b);
        }
        self.retained.remove(&handle);
    }

    fn evict_image_gpu(&mut self, handle: u64) -> u64 {
        let Some(img) = self.images.remove(&handle) else {
            return 0;
        };
        let b = match &img {
            ImageTex::Rgba { bytes, .. } => *bytes,
            ImageTex::Nv12 { bytes, .. } => *bytes,
            ImageTex::User { bytes, .. } => *bytes,
        };
        self.image_bytes_total = self.image_bytes_total.saturating_sub(b);
        b
    }

    fn revive_retained_image(&mut self, handle: u64) -> bool {
        if self.images.contains_key(&handle) {
            return true;
        }
        let Some(r) = self.retained.get(&handle).cloned() else {
            return false;
        };
        let (tex, bind) = self.create_rgba_tex(r.w, r.h, r.format);

        self.queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: &tex,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &r.rgba,
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(4 * r.w),
                rows_per_image: Some(r.h),
            },
            wgpu::Extent3d {
                width: r.w,
                height: r.h,
                depth_or_array_layers: 1,
            },
        );

        let bytes = (r.w as u64) * (r.h as u64) * 4;
        self.image_bytes_total += bytes;
        self.images.insert(
            handle,
            ImageTex::Rgba {
                tex,
                bind,
                w: r.w,
                h: r.h,
                format: r.format,
                last_used_frame: self.frame_index,
                bytes,
            },
        );
        true
    }

    fn resolve_image_for_draw(&mut self, handle: u64) -> Option<(u32, u32, bool)> {
        if let Some(t) = self.images.get_mut(&handle) {
            return match t {
                ImageTex::Rgba {
                    w,
                    h,
                    last_used_frame,
                    ..
                } => {
                    *last_used_frame = self.frame_index;
                    Some((*w, *h, false))
                }
                ImageTex::User {
                    w,
                    h,
                    last_used_frame,
                    ..
                } => {
                    *last_used_frame = self.frame_index;
                    Some((*w, *h, false))
                }
                ImageTex::Nv12 {
                    w,
                    h,
                    last_used_frame,
                    ..
                } => {
                    *last_used_frame = self.frame_index;
                    Some((*w, *h, true))
                }
            };
        }
        if self.revive_retained_image(handle)
            && let Some(ImageTex::Rgba {
                w,
                h,
                last_used_frame,
                ..
            }) = self.images.get_mut(&handle)
        {
            *last_used_frame = self.frame_index;
            return Some((*w, *h, false));
        }
        None
    }

    // Legacy support from Step 1 instructions (temporary until platform render logic is fully swapped)
    pub fn register_image_from_bytes(&mut self, data: &[u8], srgb: bool) -> u64 {
        let handle = self.next_image_handle;
        self.next_image_handle += 1;
        if let Err(e) = self.set_image_from_bytes(handle, data, srgb) {
            log::error!("Failed to register image: {e}");
        }
        handle
    }

    /// Register raw RGBA8 pixels (`w * h * 4` bytes) as an image, returning
    /// its handle for `SceneNode::Image`. Used by CPU-rasterized overlays
    /// (e.g. subtitle bitmap layers) that have no encoded image bytes.
    /// Pass `srgb = true` for sRGB overlays composited over video.
    pub fn register_image_rgba8(&mut self, w: u32, h: u32, rgba: &[u8], srgb: bool) -> u64 {
        let handle = self.next_image_handle;
        self.next_image_handle += 1;
        if let Err(e) = self.set_image_rgba8(handle, w, h, rgba, srgb) {
            log::error!("Failed to register image: {e}");
        }
        handle
    }

    /// Register an 8-bit coverage tile (`w * h` bytes, 0 = empty, 255 =
    /// fully covered) for `SceneNode::Coverage`, returning its handle.
    /// Coverage tiles are immutable: re-register on geometry change and
    /// `remove_coverage` handles you no longer emit (stale tiles also age
    /// out under the image eviction policy).
    pub fn register_coverage_a8(&mut self, w: u32, h: u32, coverage: &[u8]) -> u64 {
        let expected = (w as usize) * (h as usize);
        if coverage.len() < expected || w == 0 || h == 0 {
            log::error!("Coverage buffer too small: {} < {expected}", coverage.len());
            return 0;
        }
        let handle = self.next_coverage_handle;
        self.next_coverage_handle += 1;

        let tex = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some("coverage tile a8"),
            size: wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::R8Unorm,
            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
            view_formats: &[],
        });
        let view = tex.create_view(&wgpu::TextureViewDescriptor::default());
        let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("coverage bind a8"),
            layout: &self.image_bind_layout_rgba,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.image_sampler),
                },
            ],
        });
        self.queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: &tex,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &coverage[..expected],
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(w),
                rows_per_image: Some(h),
            },
            wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
        );
        let bytes = (w as u64) * (h as u64);
        self.image_bytes_total += bytes;
        self.coverages.insert(
            handle,
            CoverageTex {
                tex,
                bind,
                w,
                h,
                last_used_frame: self.frame_index,
                bytes,
            },
        );
        self.evict_budget_excess();
        handle
    }

    /// Remove a coverage tile registered with [`register_coverage_a8`](Self::register_coverage_a8).
    pub fn remove_coverage(&mut self, handle: u64) {
        if let Some(tile) = self.coverages.remove(&handle) {
            self.image_bytes_total = self.image_bytes_total.saturating_sub(tile.bytes);
        }
    }

    /// Tile dimensions, marking the handle used (keeps it alive under the
    /// eviction policy). Returns `None` for unknown handles.
    pub fn coverage_dimensions(&mut self, handle: u64) -> Option<(u32, u32)> {
        if let Some(tile) = self.coverages.get_mut(&handle) {
            tile.last_used_frame = self.frame_index;
            return Some((tile.w, tile.h));
        }
        None
    }

    fn evict_unused_images(&mut self) {
        let now = self.frame_index;
        let evict_after = self.image_evict_after_frames;

        // Time based eviction. Eviction only frees GPU memory: retained RGBA
        // sources stay so the image can be lazily re-uploaded when drawn again.
        let mut to_evict = Vec::new();
        for (h, t) in self.images.iter() {
            let last = match t {
                ImageTex::Rgba {
                    last_used_frame, ..
                } => *last_used_frame,
                ImageTex::User {
                    last_used_frame, ..
                } => *last_used_frame,
                ImageTex::Nv12 {
                    last_used_frame, ..
                } => *last_used_frame,
            };
            if now.saturating_sub(last) > evict_after {
                to_evict.push(*h);
            }
        }
        for h in to_evict {
            if self.retained.contains_key(&h) {
                self.evict_image_gpu(h);
            } else {
                self.remove_image(h);
            }
        }

        // Coverage tiles have no retained CPU copies: age-out removes them.
        let mut stale = Vec::new();
        for (h, t) in self.coverages.iter() {
            if now.saturating_sub(t.last_used_frame) > evict_after {
                stale.push(*h);
            }
        }
        for h in stale {
            self.remove_coverage(h);
        }

        self.evict_budget_excess();
    }

    fn evict_budget_excess(&mut self) {
        if self.image_bytes_total <= self.image_budget_bytes {
            return;
        }
        // Collect (handle, last_used, bytes)
        let mut candidates: Vec<(u64, u64, u64)> = self
            .images
            .iter()
            .map(|(h, t)| {
                let (last, bytes) = match t {
                    ImageTex::Rgba {
                        last_used_frame,
                        bytes,
                        ..
                    } => (*last_used_frame, *bytes),
                    ImageTex::User {
                        last_used_frame,
                        bytes,
                        ..
                    } => (*last_used_frame, *bytes),
                    ImageTex::Nv12 {
                        last_used_frame,
                        bytes,
                        ..
                    } => (*last_used_frame, *bytes),
                };
                (*h, last, bytes)
            })
            .collect();

        // Sort by last_used ascending (LRU first)
        candidates.sort_by_key(|k| k.1);

        let now = self.frame_index;
        for (h, last, _bytes) in candidates {
            if self.image_bytes_total <= self.image_budget_bytes {
                break;
            }
            // Don't evict something used this frame
            if last == now {
                continue;
            }
            if self.retained.contains_key(&h) {
                self.evict_image_gpu(h);
            } else {
                self.remove_image(h);
            }
        }
    }

    /// Set pixels per point (DPI scale) for callback `ScreenDescriptor` / `PaintCallbackInfo`.
    pub fn set_pixels_per_point(&mut self, ppp: f32) {
        self.pixels_per_point = ppp.clamp(0.5, 8.0);
    }

    /// Enable or disable linear working-space rendering.
    /// When enabled, the scene is rendered into an Rgba16Float intermediate
    /// and a final full-screen pass applies the display OETF.
    pub fn set_working_space(&mut self, enabled: bool) {
        if enabled == self.working_space {
            return;
        }
        self.working_space = enabled;
        if enabled {
            self.ensure_display_pipeline();
            self.recreate_working_space_texture();
        } else {
            self.ws_tex = None;
            self.ws_view = None;
            self.ws_bind = None;
        }
    }

    fn ensure_display_pipeline(&mut self) {
        if self.display_pipeline.is_some() {
            return;
        }

        let layout = self
            .device
            .create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("display transform layout"),
                entries: &[
                    wgpu::BindGroupLayoutEntry {
                        binding: 0,
                        visibility: wgpu::ShaderStages::FRAGMENT,
                        ty: wgpu::BindingType::Texture {
                            multisampled: false,
                            view_dimension: wgpu::TextureViewDimension::D2,
                            sample_type: wgpu::TextureSampleType::Float { filterable: true },
                        },
                        count: None,
                    },
                    wgpu::BindGroupLayoutEntry {
                        binding: 1,
                        visibility: wgpu::ShaderStages::FRAGMENT,
                        ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
                        count: None,
                    },
                ],
            });
        self.display_layout = Some(layout);

        let shader = self
            .device
            .create_shader_module(wgpu::ShaderModuleDescriptor {
                label: Some("display_transform.wgsl"),
                source: wgpu::ShaderSource::Wgsl(Cow::Borrowed(include_str!(
                    "shaders/display_transform.wgsl"
                ))),
            });

        let pipeline_layout = self
            .device
            .create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                label: Some("display transform pipeline layout"),
                bind_group_layouts: &[None, self.display_layout.as_ref()],
                immediate_size: 0,
            });

        let pipeline = self
            .device
            .create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                label: Some("display transform pipeline"),
                layout: Some(&pipeline_layout),
                vertex: wgpu::VertexState {
                    module: &shader,
                    entry_point: Some("vs_main"),
                    buffers: &[],
                    compilation_options: wgpu::PipelineCompilationOptions::default(),
                },
                fragment: Some(wgpu::FragmentState {
                    module: &shader,
                    entry_point: Some("fs_main"),
                    targets: &[Some(wgpu::ColorTargetState {
                        format: self.output_format,
                        blend: None,
                        write_mask: wgpu::ColorWrites::ALL,
                    })],
                    compilation_options: wgpu::PipelineCompilationOptions::default(),
                }),
                primitive: wgpu::PrimitiveState::default(),
                depth_stencil: None,
                multisample: wgpu::MultisampleState::default(),
                multiview_mask: None,
                cache: None,
            });
        self.display_pipeline = Some(pipeline);
    }

    /// Resize the render target dimensions.
    ///
    /// Recreates MSAA, depth-stencil, and working-space textures to match the
    /// new size..
    pub fn resize(&mut self, width: u32, height: u32) {
        self.output_width = width;
        self.output_height = height;
        self.recreate_msaa_and_depth_stencil();
        self.recreate_working_space_texture();
    }

    fn recreate_working_space_texture(&mut self) {
        if !self.working_space {
            return;
        }
        let w = self.output_width.max(1);
        let h = self.output_height.max(1);

        let tex = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some("working space"),
            size: wgpu::Extent3d {
                width: w,
                height: h,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba16Float,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        });
        let view = tex.create_view(&wgpu::TextureViewDescriptor::default());

        let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("working space bind"),
            layout: self.display_layout.as_ref().unwrap(),
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.image_sampler),
                },
            ],
        });

        self.ws_tex = Some(tex);
        self.ws_view = Some(view);
        self.ws_bind = Some(bind);
    }

    fn recreate_msaa_and_depth_stencil(&mut self) {
        if self.msaa_samples > 1 {
            let tex = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some("msaa color"),
                size: wgpu::Extent3d {
                    width: self.output_width.max(1),
                    height: self.output_height.max(1),
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: self.msaa_samples,
                dimension: wgpu::TextureDimension::D2,
                format: self.output_format,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                view_formats: &[],
            });
            let view = tex.create_view(&wgpu::TextureViewDescriptor::default());
            self.msaa_tex = Some(tex);
            self.msaa_view = Some(view);
        } else {
            self.msaa_tex = None;
            self.msaa_view = None;
        }

        self.depth_stencil_tex = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some("depth-stencil (stencil clips)"),
            size: wgpu::Extent3d {
                width: self.output_width.max(1),
                height: self.output_height.max(1),
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: self.msaa_samples,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Depth24PlusStencil8,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            view_formats: &[],
        });
        self.depth_stencil_view = self
            .depth_stencil_tex
            .create_view(&wgpu::TextureViewDescriptor::default());
    }

    fn get_or_create_layer(
        &mut self,
        layer_id: u32,
        width: u32,
        height: u32,
        rect: repose_core::Rect,
    ) {
        let needs_alloc = match self.layer_pool.get(&layer_id) {
            Some(lt) => lt.width != width || lt.height != height,
            None => true,
        };
        if !needs_alloc {
            if let Some(lt) = self.layer_pool.get_mut(&layer_id) {
                lt.rect_px = (rect.x, rect.y, rect.w, rect.h);
            }
            return;
        }
        let tex = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some("graphics layer"),
            size: wgpu::Extent3d {
                width: width.max(1),
                height: height.max(1),
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: self.output_format,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        });
        let view = tex.create_view(&wgpu::TextureViewDescriptor::default());
        let bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("layer bind"),
            layout: &self.image_bind_layout_rgba,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.layer_sampler),
                },
            ],
        });
        let bind_linear = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("layer bind linear"),
            layout: &self.image_bind_layout_rgba,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.layer_sampler_linear),
                },
            ],
        });
        let depth_stencil_tex = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some("graphics layer depth-stencil"),
            size: wgpu::Extent3d {
                width: width.max(1),
                height: height.max(1),
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Depth24PlusStencil8,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            view_formats: &[],
        });
        let depth_stencil_view =
            depth_stencil_tex.create_view(&wgpu::TextureViewDescriptor::default());
        self.layer_pool.insert(
            layer_id,
            LayerTarget {
                view,
                bind,
                bind_linear,
                depth_stencil_view,
                width,
                height,
                rect_px: (rect.x, rect.y, rect.w, rect.h),
            },
        );
    }

    fn atlas_bind_group_mask(&self) -> wgpu::BindGroup {
        self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("atlas bind"),
            layout: &self.text_bind_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&self.atlas_mask.view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.atlas_mask.sampler),
                },
            ],
        })
    }

    fn atlas_bind_group_color(&self) -> wgpu::BindGroup {
        self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("atlas bind color"),
            layout: &self.text_bind_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&self.atlas_color.view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.atlas_color.sampler),
                },
            ],
        })
    }

    fn upload_glyph_mask(&mut self, key: repose_text::GlyphKey, px: f32) -> Option<GlyphInfo> {
        let keyp = (key, px.to_bits());
        if let Some(info) = self.atlas_mask.map.get(&keyp) {
            return Some(*info);
        }

        let gb = repose_text::rasterize(key, px)?;
        if gb.w == 0 || gb.h == 0 || gb.data.is_empty() {
            return None;
        }

        let coverage = swash_to_a8_coverage(gb.content, &gb.data)?;

        let w = gb.w.max(1);
        let h = gb.h.max(1);

        if !self.alloc_space_mask(w, h) {
            self.grow_mask_and_rebuild();
        }
        if !self.alloc_space_mask(w, h) {
            return None;
        }
        let x = self.atlas_mask.next_x;
        let y = self.atlas_mask.next_y;
        self.atlas_mask.next_x += w + 1;
        self.atlas_mask.row_h = self.atlas_mask.row_h.max(h + 1);

        let layout = wgpu::TexelCopyBufferLayout {
            offset: 0,
            bytes_per_row: Some(w),
            rows_per_image: Some(h),
        };
        let size = wgpu::Extent3d {
            width: w,
            height: h,
            depth_or_array_layers: 1,
        };
        self.queue.write_texture(
            wgpu::TexelCopyTextureInfoBase {
                texture: &self.atlas_mask.tex,
                mip_level: 0,
                origin: wgpu::Origin3d { x, y, z: 0 },
                aspect: wgpu::TextureAspect::All,
            },
            &coverage,
            layout,
            size,
        );

        let info = GlyphInfo {
            u0: x as f32 / self.atlas_mask.size as f32,
            v0: y as f32 / self.atlas_mask.size as f32,
            u1: (x + w) as f32 / self.atlas_mask.size as f32,
            v1: (y + h) as f32 / self.atlas_mask.size as f32,
            w: w as f32,
            h: h as f32,
        };
        self.atlas_mask.map.insert(keyp, info);
        Some(info)
    }

    fn upload_glyph_color(&mut self, key: repose_text::GlyphKey, px: f32) -> Option<GlyphInfo> {
        let keyp = (key, px.to_bits());
        if let Some(info) = self.atlas_color.map.get(&keyp) {
            return Some(*info);
        }
        let gb = repose_text::rasterize(key, px)?;
        if !matches!(gb.content, repose_text::SwashContent::Color) {
            return None;
        }
        let w = gb.w.max(1);
        let h = gb.h.max(1);
        if !self.alloc_space_color(w, h) {
            self.grow_color_and_rebuild();
        }
        if !self.alloc_space_color(w, h) {
            return None;
        }
        let x = self.atlas_color.next_x;
        let y = self.atlas_color.next_y;
        self.atlas_color.next_x += w + 1;
        self.atlas_color.row_h = self.atlas_color.row_h.max(h + 1);

        let layout = wgpu::TexelCopyBufferLayout {
            offset: 0,
            bytes_per_row: Some(w * 4),
            rows_per_image: Some(h),
        };
        let size = wgpu::Extent3d {
            width: w,
            height: h,
            depth_or_array_layers: 1,
        };
        self.queue.write_texture(
            wgpu::TexelCopyTextureInfoBase {
                texture: &self.atlas_color.tex,
                mip_level: 0,
                origin: wgpu::Origin3d { x, y, z: 0 },
                aspect: wgpu::TextureAspect::All,
            },
            &gb.data,
            layout,
            size,
        );
        let info = GlyphInfo {
            u0: x as f32 / self.atlas_color.size as f32,
            v0: y as f32 / self.atlas_color.size as f32,
            u1: (x + w) as f32 / self.atlas_color.size as f32,
            v1: (y + h) as f32 / self.atlas_color.size as f32,
            w: w as f32,
            h: h as f32,
        };
        self.atlas_color.map.insert(keyp, info);
        Some(info)
    }

    fn alloc_space_mask(&mut self, w: u32, h: u32) -> bool {
        if self.atlas_mask.next_x + w + 1 >= self.atlas_mask.size {
            self.atlas_mask.next_x = 1;
            self.atlas_mask.next_y += self.atlas_mask.row_h + 1;
            self.atlas_mask.row_h = 0;
        }
        if self.atlas_mask.next_y + h + 1 >= self.atlas_mask.size {
            return false;
        }
        true
    }

    fn grow_mask_and_rebuild(&mut self) {
        let new_size = (self.atlas_mask.size * 2).min(4096);
        if new_size == self.atlas_mask.size {
            return;
        }
        let tex = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some("glyph atlas A8 (grown)"),
            size: wgpu::Extent3d {
                width: new_size,
                height: new_size,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::R8Unorm,
            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
            view_formats: &[],
        });
        self.atlas_mask.tex = tex;
        self.atlas_mask.view = self
            .atlas_mask
            .tex
            .create_view(&wgpu::TextureViewDescriptor::default());
        self.atlas_mask.size = new_size;
        self.atlas_mask.next_x = 1;
        self.atlas_mask.next_y = 1;
        self.atlas_mask.row_h = 0;
        let keys: Vec<(repose_text::GlyphKey, u32)> = self.atlas_mask.map.keys().copied().collect();
        self.atlas_mask.map.clear();
        for (k, px_bits) in keys {
            let _ = self.upload_glyph_mask(k, f32::from_bits(px_bits));
        }
    }

    fn alloc_space_color(&mut self, w: u32, h: u32) -> bool {
        if self.atlas_color.next_x + w + 1 >= self.atlas_color.size {
            self.atlas_color.next_x = 1;
            self.atlas_color.next_y += self.atlas_color.row_h + 1;
            self.atlas_color.row_h = 0;
        }
        if self.atlas_color.next_y + h + 1 >= self.atlas_color.size {
            return false;
        }
        true
    }

    fn grow_color_and_rebuild(&mut self) {
        let new_size = (self.atlas_color.size * 2).min(4096);
        if new_size == self.atlas_color.size {
            return;
        }
        let tex = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some("glyph atlas RGBA (grown)"),
            size: wgpu::Extent3d {
                width: new_size,
                height: new_size,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8UnormSrgb,
            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
            view_formats: &[],
        });
        self.atlas_color.tex = tex;
        self.atlas_color.view = self
            .atlas_color
            .tex
            .create_view(&wgpu::TextureViewDescriptor::default());
        self.atlas_color.size = new_size;
        self.atlas_color.next_x = 1;
        self.atlas_color.next_y = 1;
        self.atlas_color.row_h = 0;
        let keys: Vec<(repose_text::GlyphKey, u32)> =
            self.atlas_color.map.keys().copied().collect();
        self.atlas_color.map.clear();
        for (k, px_bits) in keys {
            let _ = self.upload_glyph_color(k, f32::from_bits(px_bits));
        }
    }
}

/// Packed brush fields shared by the shape instances (border, ellipse,
/// ellipse border, arc). Gradient endpoints are shape-local px; the shaders
/// recenter `(0,0)` at the shape top-left. Radial packs `center` into
/// `grad_p0` and `radius` into `grad_p1.x`; sweep packs `center` into
/// `grad_p0`.
///
/// `rect` is the shape's scene-space bounds (only used for the solid
/// fallback path) and `transform` the accumulated scene transform.
/// Endpoints are converted from shape-local px through the inverse linear
/// part so rotation and uniform scale cancel against the shader's
/// un-rotation. Non-uniform scale and shear distort the gradient the same
/// way they distort the shape (the shader un-rotates but cannot un-scale
/// pixels).
fn brush_to_shape_fields(
    brush: &Brush,
    _rect: &repose_core::Rect,
    transform: &Transform,
) -> (u32, u32, [f32; 4], [f32; 4], [f32; 2], [f32; 2], u32) {
    let to_local = |p: Vec2| {
        let m = transform.linear();
        let det = m[0] * m[3] - m[1] * m[2];
        if det.abs() < 1e-12 {
            return [p.x, p.y];
        }
        [
            (m[3] * p.x - m[1] * p.y) / det,
            (-m[2] * p.x + m[0] * p.y) / det,
        ]
    };
    match brush {
        Brush::Solid(c) => (
            0u32,
            0u32,
            c.to_linear(),
            [0.0; 4],
            [0.0; 2],
            [0.0; 2],
            0u32,
        ),
        Brush::Linear {
            start,
            end,
            start_color,
            end_color,
        } => (
            1u32,
            0u32,
            start_color.to_linear(),
            end_color.to_linear(),
            to_local(*start),
            to_local(*end),
            0u32,
        ),
        Brush::Radial {
            center,
            radius,
            start_color,
            end_color,
        } => (
            1u32,
            1u32,
            start_color.to_linear(),
            end_color.to_linear(),
            to_local(*center),
            [radius.max(0.0), 0.0],
            0u32,
        ),
        Brush::Sweep {
            center,
            start_color,
            end_color,
        } => (
            1u32,
            2u32,
            start_color.to_linear(),
            end_color.to_linear(),
            to_local(*center),
            [0.0, 0.0],
            0u32,
        ),
        _ => (0u32, 0u32, [0.0; 4], [0.0; 4], [0.0; 2], [0.0; 2], 0u32),
    }
}

fn brush_to_instance_fields(brush: &Brush) -> (u32, [f32; 4], [f32; 4], [f32; 2], [f32; 2]) {
    match brush {
        Brush::Solid(c) => (
            0u32,
            c.to_linear(),
            [0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0],
            [0.0, 1.0],
        ),
        Brush::Linear {
            start,
            end,
            start_color,
            end_color,
        } => (
            1u32,
            start_color.to_linear(),
            end_color.to_linear(),
            [start.x, start.y],
            [end.x, end.y],
        ),
        Brush::Radial { start_color, .. } => (
            0u32,
            start_color.to_linear(),
            [0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0],
            [0.0, 1.0],
        ),
        Brush::Sweep { start_color, .. } => (
            0u32,
            start_color.to_linear(),
            [0.0, 0.0, 0.0, 0.0],
            [0.0, 0.0],
            [0.0, 1.0],
        ),
        _ => (0u32, [0.0; 4], [0.0; 4], [0.0; 2], [0.0; 2]),
    }
}

/// Fallback color when a [`Brush`] reaches a solid-only path (glyph atlas
/// uploads for gradient text). Uses the gradient's start color.
#[allow(dead_code)]
fn brush_to_solid_color(brush: &Brush) -> [f32; 4] {
    match brush {
        Brush::Solid(c) => c.to_linear(),
        Brush::Linear { start_color, .. } => start_color.to_linear(),
        Brush::Radial { start_color, .. } => start_color.to_linear(),
        Brush::Sweep { start_color, .. } => start_color.to_linear(),
        _ => [0.0; 4],
    }
}

fn init_atlas_mask(device: &wgpu::Device) -> AtlasA8 {
    let size = 1024u32;
    let tex = device.create_texture(&wgpu::TextureDescriptor {
        label: Some("glyph atlas A8"),
        size: wgpu::Extent3d {
            width: size,
            height: size,
            depth_or_array_layers: 1,
        },
        mip_level_count: 1,
        sample_count: 1,
        dimension: wgpu::TextureDimension::D2,
        format: wgpu::TextureFormat::R8Unorm,
        usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
        view_formats: &[],
    });
    let view = tex.create_view(&wgpu::TextureViewDescriptor::default());
    let sampler = device.create_sampler(&wgpu::SamplerDescriptor {
        label: Some("glyph atlas sampler A8"),
        address_mode_u: wgpu::AddressMode::ClampToEdge,
        address_mode_v: wgpu::AddressMode::ClampToEdge,
        address_mode_w: wgpu::AddressMode::ClampToEdge,
        mag_filter: wgpu::FilterMode::Linear,
        min_filter: wgpu::FilterMode::Linear,
        mipmap_filter: wgpu::MipmapFilterMode::Linear,
        ..Default::default()
    });

    AtlasA8 {
        tex,
        view,
        sampler,
        size,
        next_x: 1,
        next_y: 1,
        row_h: 0,
        map: HashMap::new(),
    }
}

fn init_atlas_color(device: &wgpu::Device) -> AtlasRGBA {
    let size = 1024u32;
    let tex = device.create_texture(&wgpu::TextureDescriptor {
        label: Some("glyph atlas RGBA"),
        size: wgpu::Extent3d {
            width: size,
            height: size,
            depth_or_array_layers: 1,
        },
        mip_level_count: 1,
        sample_count: 1,
        dimension: wgpu::TextureDimension::D2,
        format: wgpu::TextureFormat::Rgba8UnormSrgb,
        usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
        view_formats: &[],
    });
    let view = tex.create_view(&wgpu::TextureViewDescriptor::default());
    let sampler = device.create_sampler(&wgpu::SamplerDescriptor {
        label: Some("glyph atlas sampler RGBA"),
        address_mode_u: wgpu::AddressMode::ClampToEdge,
        address_mode_v: wgpu::AddressMode::ClampToEdge,
        address_mode_w: wgpu::AddressMode::ClampToEdge,
        mag_filter: wgpu::FilterMode::Linear,
        min_filter: wgpu::FilterMode::Linear,
        mipmap_filter: wgpu::MipmapFilterMode::Linear,
        ..Default::default()
    });
    AtlasRGBA {
        tex,
        view,
        sampler,
        size,
        next_x: 1,
        next_y: 1,
        row_h: 0,
        map: HashMap::new(),
    }
}

#[cfg(feature = "winit-surface")]
impl RenderBackend for WgpuSurfaceBackend {
    fn configure_surface(&mut self, width: u32, height: u32) {
        if width == 0 || height == 0 {
            return;
        }
        self.renderer.output_width = width;
        self.renderer.output_height = height;
        if let Some(ref mut config) = self.surface_config {
            config.width = width;
            config.height = height;
        }
        if let (Some(surface), Some(config)) = (self.surface.as_ref(), self.surface_config.as_ref())
        {
            surface.configure(&self.renderer.device, config);
        }
        self.renderer.recreate_msaa_and_depth_stencil();
        self.renderer.recreate_working_space_texture();
    }

    fn frame(&mut self, scene: &Scene, _glyph_cfg: GlyphRasterConfig) {
        let surface = self.surface.as_ref().expect("WgpuSurfaceBackend::frame() requires a surface (use from_device + render_to_view instead)");
        let surface_config = self
            .surface_config
            .as_ref()
            .expect("surface_config required for frame()");

        self.renderer.frame_index = self.renderer.frame_index.wrapping_add(1);
        self.renderer.slug_cache.next_frame();

        if self.renderer.output_width == 0 || self.renderer.output_height == 0 {
            return;
        }

        let mut retries = 0u32;
        const MAX_RETRIES: u32 = 4;
        let frame = loop {
            match surface.get_current_texture() {
                wgpu::CurrentSurfaceTexture::Success(f) => break f,
                wgpu::CurrentSurfaceTexture::Suboptimal(f) => {
                    log::warn!("suboptimal surface; reconfiguring");
                    surface.configure(&self.renderer.device, surface_config);
                    break f;
                }
                wgpu::CurrentSurfaceTexture::Outdated => {
                    retries += 1;
                    if retries >= MAX_RETRIES {
                        log::warn!(
                            "surface outdated persisted after {MAX_RETRIES} retries; skipping frame"
                        );
                        return;
                    }
                    log::warn!("surface outdated; reconfiguring");
                    surface.configure(&self.renderer.device, surface_config);
                }
                wgpu::CurrentSurfaceTexture::Lost => {
                    retries += 1;
                    if retries >= MAX_RETRIES {
                        log::warn!(
                            "surface lost persisted after {MAX_RETRIES} retries; skipping frame"
                        );
                        return;
                    }
                    log::warn!("surface lost; reconfiguring");
                    surface.configure(&self.renderer.device, surface_config);
                }
                wgpu::CurrentSurfaceTexture::Timeout | wgpu::CurrentSurfaceTexture::Occluded => {
                    request_frame();
                    return;
                }
                wgpu::CurrentSurfaceTexture::Validation => {
                    retries += 1;
                    if retries >= MAX_RETRIES {
                        log::warn!(
                            "surface validation persisted after {MAX_RETRIES} retries; skipping frame"
                        );
                        return;
                    }
                    surface.configure(&self.renderer.device, surface_config);
                }
            }
        };

        let swap_view = if let Some(view_format) = self
            .surface_config
            .as_ref()
            .and_then(|c| c.view_formats.iter().find(|f| f.is_srgb()).copied())
        {
            frame.texture.create_view(&wgpu::TextureViewDescriptor {
                format: Some(view_format),
                ..Default::default()
            })
        } else {
            frame
                .texture
                .create_view(&wgpu::TextureViewDescriptor::default())
        };
        let mut encoder =
            self.renderer
                .device
                .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                    label: Some("frame encoder"),
                });

        let clear_color = Some([
            scene.clear_color.0 as f64 / 255.0,
            scene.clear_color.1 as f64 / 255.0,
            scene.clear_color.2 as f64 / 255.0,
            scene.clear_color.3 as f64 / 255.0,
        ]);

        self.renderer
            .render_scene_to_encoder(scene, &mut encoder, &swap_view, clear_color);

        //NOTE: The WebGL HAL present path (fullscreen triangle / blit) does not
        // restore gl.colorMask. Hence this is needed to prevent frames from going transparent.
        {
            let _reset = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("webgl color_mask reset before present"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: &swap_view,
                    resolve_target: None,
                    ops: wgpu::Operations {
                        load: wgpu::LoadOp::Load,
                        store: wgpu::StoreOp::Store,
                    },
                    depth_slice: None,
                })],
                depth_stencil_attachment: None,
                timestamp_writes: None,
                occlusion_query_set: None,
                multiview_mask: None,
            });
        }

        self.renderer
            .queue
            .submit(std::iter::once(encoder.finish()));
        if let Err(e) = catch_unwind(AssertUnwindSafe(|| self.renderer.queue.present(frame))) {
            log::warn!("queue.present panicked: {:?}", e);
        }
    }
}

impl WgpuSceneRenderer {
    /// Open a translator-owned flatten layer for a perspective `PushTransform`.
    ///
    /// True perspective cannot ride the affine instance fast path, so the
    /// subtree renders flat into an offscreen layer and is composited back
    /// projectively on the matching pop (CSS-style flattening). The layer
    /// rect is the currently visible scissor in this target: content outside
    /// it is invisible in the parent, so clipping it in the layer changes
    /// nothing. Children keep the node's affine part on the stack (so
    /// `combine` stays affine-only) plus a layer-local shift, exactly like
    /// producer-owned blur layers — which is exact under rigid ancestors
    /// (translations commute) and the documented layer contract otherwise.
    #[allow(clippy::too_many_arguments)]
    fn push_perspective_layer(
        &mut self,
        node: Transform,
        top: Transform,
        transform_stack: &mut Vec<Transform>,
        scissor_stack: &mut Vec<repose_core::Rect>,
        root_clip_rect: &mut repose_core::Rect,
        current_target_size: &mut (f32, f32),
        current_pass: &mut Pass,
        passes: &mut Vec<Pass>,
        target_stack: &mut Vec<PassTarget>,
        flatten_stack: &mut Vec<FlattenRecord>,
        id_head: &mut u32,
        ids_used: &mut Vec<u32>,
    ) {
        // Full projective map: affine ancestors over the node's map.
        // Ancestors are affine by construction (perspective always flattens
        // at push, and only stripped affines reach the stack).
        let map =
            Transform::compose_projective(&top.projective_matrix(), &node.projective_matrix());
        let scr = scissor_stack.last().copied().unwrap_or(*root_clip_rect);
        let w = scr.w.ceil().max(1.0);
        let h = scr.h.ceil().max(1.0);
        let layer_rect = repose_core::Rect {
            x: scr.x,
            y: scr.y,
            w,
            h,
        };
        // Translator-owned ids live far above producer ids (which start at 1
        // per scene) and are drained from the pool after each frame.
        let layer_id = *id_head;
        *id_head = id_head.wrapping_add(1);
        ids_used.push(layer_id);

        let stack_len = transform_stack.len();
        // Children render with the ancestors' map only: the node's own
        // affine part lives in `map` and applies once, at composite time.
        // (Pushing the stripped affine here too would foreshorten twice.)
        transform_stack.push(top);
        transform_stack.push(Transform::translate(-layer_rect.x, -layer_rect.y));

        let saved_scissor = std::mem::replace(
            scissor_stack,
            vec![repose_core::Rect {
                x: 0.0,
                y: 0.0,
                w,
                h,
            }],
        );
        let saved_root = std::mem::replace(
            root_clip_rect,
            repose_core::Rect {
                x: 0.0,
                y: 0.0,
                w,
                h,
            },
        );
        let saved_size = std::mem::replace(current_target_size, (w, h));
        let prev_target = current_pass.target;
        let saved = std::mem::replace(
            current_pass,
            Pass {
                target: PassTarget::Layer(layer_id),
                initial_scissor: (0, 0, w as u32, h as u32),
                clear_color: Some([0.0, 0.0, 0.0, 0.0]),
                cmds: Vec::new(),
            },
        );
        passes.push(saved);
        target_stack.push(prev_target);
        self.get_or_create_layer(layer_id, w as u32, h as u32, layer_rect);
        *current_target_size = (w, h);
        flatten_stack.push(FlattenRecord {
            stack_len,
            layer_id,
            map,
            layer_rect,
            saved_scissor,
            saved_root,
            saved_size,
        });
    }

    /// Close a flatten layer: restore the parent target and composite the
    /// layer texture through the recorded projective map.
    #[allow(clippy::too_many_arguments)]
    fn pop_perspective_layer(
        &mut self,
        rec: FlattenRecord,
        scissor_stack: &mut Vec<repose_core::Rect>,
        root_clip_rect: &mut repose_core::Rect,
        current_target_size: &mut (f32, f32),
        current_pass: &mut Pass,
        passes: &mut Vec<Pass>,
        target_stack: &mut Vec<PassTarget>,
    ) {
        *scissor_stack = rec.saved_scissor;
        *root_clip_rect = rec.saved_root;
        *current_target_size = rec.saved_size;
        let saved = std::mem::replace(
            current_pass,
            Pass {
                target: target_stack.pop().unwrap_or(PassTarget::Surface),
                initial_scissor: (0, 0, self.output_width, self.output_height),
                clear_color: None,
                cmds: Vec::new(),
            },
        );
        passes.push(saved);

        // Project the layer-rect corners (parent space) to NDC in the
        // resumed (parent) target, keeping each corner's homogeneous w for
        // perspective-correct sampling.
        let (tw, th) = rec.saved_size;
        let r = rec.layer_rect;
        let corners = [
            (r.x, r.y),
            (r.x + r.w, r.y),
            (r.x + r.w, r.y + r.h),
            (r.x, r.y + r.h),
        ];
        let mut ndc = [[0.0f32; 2]; 4];
        let mut ws = [1.0f32; 4];
        let mut all_behind = true;
        for (i, (x, y)) in corners.iter().enumerate() {
            let w_raw = rec.map[6] * x + rec.map[7] * y + rec.map[8];
            let w = if w_raw.abs() < 1e-6 {
                if w_raw < 0.0 { -1e-6 } else { 1e-6 }
            } else {
                w_raw
            };
            if w > 0.0 {
                all_behind = false;
            }
            let px = (rec.map[0] * x + rec.map[1] * y + rec.map[2]) / w;
            let py = (rec.map[3] * x + rec.map[4] * y + rec.map[5]) / w;
            ndc[i] = [px / tw * 2.0 - 1.0, 1.0 - py / th * 2.0];
            ws[i] = w;
        }
        if all_behind {
            // Entire subtree behind the viewer: nothing to composite (the
            // layer pass still ran, but its output is correctly discarded).
            return;
        }
        let layer = self.layer_pool.get(&rec.layer_id).expect("flatten layer");
        let uv_u1 = layer.rect_px.2 / layer.width.max(1) as f32;
        let uv_v1 = layer.rect_px.3 / layer.height.max(1) as f32;
        let inst = ProjectiveInstance {
            c0: ndc[0],
            c1: ndc[1],
            c2: ndc[2],
            c3: ndc[3],
            uv: [0.0, 0.0, uv_u1, uv_v1],
            w: ws,
            alpha: 1.0,
            _pad: [0.0; 3],
        };
        self.projective_ring.grow_to_fit(
            &self.device,
            std::mem::size_of::<ProjectiveInstance>() as u64,
        );
        let bytes = bytemuck::bytes_of(&inst);
        let (off, _) = self.projective_ring.alloc_write(&self.queue, bytes);
        current_pass.cmds.push(Cmd::CompositeProjective {
            off,
            cnt: 1,
            layer_id: rec.layer_id,
        });
    }

    fn upload_mesh_geometry(&mut self, mesh: &repose_core::VectorMeshData) -> (u64, u32, u64, u32) {
        let verts: Vec<MeshVertex> = mesh
            .vertices
            .iter()
            .map(|v| MeshVertex {
                pos: v.pos,
                color: v.color,
                uv: v.uv,
            })
            .collect();
        let vbytes = bytemuck::cast_slice(&verts);
        self.mesh_verts
            .grow_to_fit(&self.device, vbytes.len() as u64);
        let (voff, _) = self.mesh_verts.alloc_write(&self.queue, vbytes);
        let ibytes = bytemuck::cast_slice(&mesh.indices);
        self.mesh_indices
            .grow_to_fit(&self.device, ibytes.len() as u64);
        let (ioff, _) = self.mesh_indices.alloc_write(&self.queue, ibytes);
        (voff, verts.len() as u32, ioff, mesh.indices.len() as u32)
    }

    fn alloc_mesh_uniform(&mut self, u: MeshUniform) -> u64 {
        if self.mesh_uniform_head + MESH_UNIFORM_SLOT > MESH_UNIFORM_CAP {
            log::warn!("mesh uniform buffer overflow; regenerating");
            self.recreate_mesh_uniform_buffer();
        }
        let slot = self.mesh_uniform_head;
        self.queue
            .write_buffer(&self.mesh_uniform_buf, slot, bytemuck::bytes_of(&u));
        self.mesh_uniform_head = slot + MESH_UNIFORM_SLOT;
        slot
    }

    fn recreate_mesh_uniform_buffer(&mut self) {
        let new_cap = self.mesh_uniform_head + MESH_UNIFORM_SLOT;
        self.mesh_uniform_buf = self.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("mesh uniform buffer"),
            size: new_cap,
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        self.mesh_bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("mesh uniform bind"),
            layout: &self.mesh_bind_layout,
            entries: &[wgpu::BindGroupEntry {
                binding: 0,
                resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
                    buffer: &self.mesh_uniform_buf,
                    offset: 0,
                    size: NonZero::new(MESH_UNIFORM_SLOT),
                }),
            }],
        });
        self.mesh_uniform_head = 0;
    }

    #[allow(clippy::too_many_arguments)]
    fn emit_vector_mesh(
        &mut self,
        current_transform: &Transform,
        mesh: &repose_core::VectorMeshData,
        transform: [f32; 6],
        paint: &repose_core::PaintDesc,
        cmds: &mut Vec<Cmd>,
    ) {
        let affine = combine_mesh_affine(current_transform, transform);
        let (voff, vcnt, ioff, icnt) = self.upload_mesh_geometry(mesh);
        let uoff = self.alloc_mesh_uniform(mesh_uniform_from_paint(affine, paint));
        cmds.push(Cmd::VectorMesh {
            voff,
            vcnt,
            ioff,
            icnt,
            uoff,
        });
    }

    pub fn render_scene_to_encoder(
        &mut self,
        scene: &Scene,
        encoder: &mut wgpu::CommandEncoder,
        target_view: &wgpu::TextureView,
        clear_color_override: Option<[f64; 4]>,
    ) {
        /// AABB of a rect under the *plain affine* part of a transform
        /// (linear + translation, no origin re-pivot).
        fn affine_aabb(transform: &Transform, rect: &repose_core::Rect) -> repose_core::Rect {
            let m = transform.linear();
            let (tx, ty) = (transform.translate_x, transform.translate_y);
            let corners = [
                (rect.x, rect.y),
                (rect.x + rect.w, rect.y),
                (rect.x, rect.y + rect.h),
                (rect.x + rect.w, rect.y + rect.h),
            ];
            let mut min_x = f32::MAX;
            let mut min_y = f32::MAX;
            let mut max_x = f32::MIN;
            let mut max_y = f32::MIN;
            for (x, y) in corners {
                let wx = m[0] * x + m[1] * y + tx;
                let wy = m[2] * x + m[3] * y + ty;
                min_x = min_x.min(wx);
                min_y = min_y.min(wy);
                max_x = max_x.max(wx);
                max_y = max_y.max(wy);
            }
            repose_core::Rect {
                x: min_x,
                y: min_y,
                w: (max_x - min_x).max(0.0),
                h: (max_y - min_y).max(0.0),
            }
        }

        fn to_ndc(x: f32, y: f32, w: f32, h: f32, fb_w: f32, fb_h: f32) -> [f32; 4] {
            let x0 = (x / fb_w) * 2.0 - 1.0;
            let y0 = 1.0 - (y / fb_h) * 2.0;
            let x1 = ((x + w) / fb_w) * 2.0 - 1.0;
            let y1 = 1.0 - ((y + h) / fb_h) * 2.0;
            let min_x = x0.min(x1);
            let min_y = y0.min(y1);
            let w_ndc = (x1 - x0).abs();
            let h_ndc = (y1 - y0).abs();
            [min_x, min_y, w_ndc, h_ndc]
        }

        /// Convert a local-space rect + transform to NDC center-based position+size
        /// plus the forward rotation/shear 2x2 (row-major `[m00, m01, m10, m11]`,
        /// scale-free: scale rides in the NDC size). Shaders apply it to quad
        /// corners and its adjugate/determinant inverse to sample positions.
        fn rect_to_instance_ndc(
            rect: repose_core::Rect,
            transform: &Transform,
            fb_w: f32,
            fb_h: f32,
        ) -> ([f32; 4], [f32; 4]) {
            let cx = rect.x + rect.w * 0.5;
            let cy = rect.y + rect.h * 0.5;

            let m = transform.linear();
            let tx = m[0] * cx + m[1] * cy + transform.translate_x;
            let ty = m[2] * cx + m[3] * cy + transform.translate_y;

            let ndc_cx = (tx / fb_w) * 2.0 - 1.0;
            let ndc_cy = 1.0 - (ty / fb_h) * 2.0;
            // NDC size (after scale only, no rotation - rotation is done in shader)
            let ndc_w = (rect.w * transform.scale_x / fb_w) * 2.0;
            let ndc_h = (rect.h * transform.scale_y / fb_h) * 2.0;

            ([ndc_cx, ndc_cy, ndc_w, ndc_h], forward_rs_mat(transform))
        }

        /// Forward rotation+shear 2x2 (row-major, scale-free) for instance
        /// attributes. Identity for untransformed content; degenerate shear
        /// (only from absurd inputs) falls back to identity.
        fn forward_rs_mat(transform: &Transform) -> [f32; 4] {
            let c = transform.rotate.cos();
            let s = transform.rotate.sin();
            let (hx, hy) = (transform.shear_x, transform.shear_y);
            let m = [c - s * hy, c * hx - s, s + c * hy, s * hx + c];
            if (m[0] * m[3] - m[1] * m[2]).abs() < 1e-6 {
                return [1.0, 0.0, 0.0, 1.0];
            }
            m
        }

        fn to_scissor(r: &repose_core::Rect, fb_w: u32, fb_h: u32) -> (u32, u32, u32, u32) {
            let mut x = r.x.floor() as i64;
            let mut y = r.y.floor() as i64;
            let fb_wi = fb_w as i64;
            let fb_hi = fb_h as i64;
            x = x.clamp(0, fb_wi.saturating_sub(1));
            y = y.clamp(0, fb_hi.saturating_sub(1));
            let w_req = r.w.ceil().max(1.0) as i64;
            let h_req = r.h.ceil().max(1.0) as i64;
            let w = (w_req).min(fb_wi - x).max(1);
            let h = (h_req).min(fb_hi - y).max(1);
            (x as u32, y as u32, w as u32, h as u32)
        }

        let fb_w = self.output_width as f32;
        let fb_h = self.output_height as f32;

        let mut passes: Vec<Pass> = Vec::with_capacity(1);
        let clear_color = clear_color_override.unwrap_or_else(|| {
            // Scene clear colors are sRGB bytes like every other `Color`;
            // linearize so the sRGB target re-encodes them exactly (passing
            // raw bytes double-encoded: (10,20,30) read back (56,79,96)).
            let lin = scene.clear_color.to_linear();
            [lin[0] as f64, lin[1] as f64, lin[2] as f64, lin[3] as f64]
        });
        let mut current_pass: Pass = Pass {
            target: PassTarget::Surface,
            initial_scissor: (0, 0, self.output_width, self.output_height),
            clear_color: Some([
                clear_color[0] as f32,
                clear_color[1] as f32,
                clear_color[2] as f32,
                clear_color[3] as f32,
            ]),
            cmds: Vec::with_capacity(scene.nodes.len()),
        };
        let mut target_stack: Vec<PassTarget> = Vec::new();
        let mut layer_alphas: Vec<(u32, f32, (u32, u32, u32, u32))> = Vec::new();
        let mut layer_blurs: Vec<(u32, f32, f32)> = Vec::new();
        let mut current_target_size: (f32, f32) = (fb_w, fb_h);

        struct Batch {
            rects: Vec<RectInstance>,
            borders: Vec<BorderInstance>,
            ellipses: Vec<EllipseInstance>,
            e_borders: Vec<EllipseBorderInstance>,
            arcs: Vec<ArcInstance>,
            masks: Vec<GlyphInstance>,
            colors: Vec<GlyphInstance>,
            nv12s: Vec<Nv12Instance>,
        }

        impl Batch {
            fn new() -> Self {
                Self {
                    rects: vec![],
                    borders: vec![],
                    ellipses: vec![],
                    e_borders: vec![],
                    arcs: vec![],
                    masks: vec![],
                    colors: vec![],
                    nv12s: vec![],
                }
            }

            fn is_empty(&self) -> bool {
                self.rects.is_empty()
                    && self.borders.is_empty()
                    && self.ellipses.is_empty()
                    && self.e_borders.is_empty()
                    && self.arcs.is_empty()
                    && self.masks.is_empty()
                    && self.colors.is_empty()
                    && self.nv12s.is_empty()
            }

            fn flush(
                &mut self,
                pipes: (
                    &mut InstancedPipe<RectInstance>,
                    &mut InstancedPipe<BorderInstance>,
                    &mut InstancedPipe<EllipseInstance>,
                    &mut InstancedPipe<EllipseBorderInstance>,
                    &mut InstancedPipe<ArcInstance>,
                ),
                glyph_pipes: (
                    &mut InstancedPipe<GlyphInstance>,
                    &mut InstancedPipe<GlyphInstance>,
                ),
                nv12_pipe: &mut InstancedPipe<Nv12Instance>,
                device: &wgpu::Device,
                queue: &wgpu::Queue,
                cmds: &mut Vec<Cmd>,
            ) {
                let (rects, borders, ellipses, e_borders, arcs) = pipes;
                let (masks, colors) = glyph_pipes;

                macro_rules! flush_one {
                    ($buf:ident, $pipe:expr, $variant:ident) => {
                        if !self.$buf.is_empty() {
                            if let Some((off, cnt)) = $pipe.upload(device, queue, &self.$buf) {
                                cmds.push(Cmd::$variant { off, cnt });
                            }
                            self.$buf.clear();
                        }
                    };
                }

                flush_one!(rects, rects, Rect);
                flush_one!(borders, borders, Border);
                flush_one!(ellipses, ellipses, Ellipse);
                flush_one!(e_borders, e_borders, EllipseBorder);
                flush_one!(arcs, arcs, Arc);
                flush_one!(masks, masks, GlyphsMask);
                flush_one!(colors, colors, GlyphsColor);

                if !self.nv12s.is_empty() {
                    if let Some((off, cnt)) = nv12_pipe.upload(device, queue, &self.nv12s) {
                        let _ = (off, cnt);
                    }
                    self.nv12s.clear();
                }
            }
        }

        self.rects.reset();
        self.borders.reset();
        self.ellipses.reset();
        self.ellipse_borders.reset();
        self.arcs.reset();
        self.glyph_mask.reset();
        self.glyph_color.reset();
        self.clip_ring.reset();
        self.blur_ring.reset();
        self.nv12.reset();

        self.slug_ring.reset();
        self.mesh_verts.reset();
        self.mesh_indices.reset();
        self.mesh_uniform_head = 0;
        self.mesh_clip_stack.clear();
        self.projective_ring.reset();
        // Translator-owned flatten layers are single-frame by construction:
        // drop last frame's textures before translating (their composites
        // were submitted last frame, so GPU-side refs are independent).
        for id in self.flatten_layer_ids.drain(..) {
            self.layer_pool.remove(&id);
        }
        let mut batch = Batch::new();
        let mut slug_verts_local: Vec<slug::TessVertex> = Vec::new();
        let mut transform_stack: Vec<Transform> = vec![Transform::identity()];
        let mut flatten_stack: Vec<FlattenRecord> = Vec::new();
        let mut flatten_id_head: u32 = FLATTEN_ID_BASE;
        let mut flatten_ids_used: Vec<u32> = Vec::new();
        let mut scissor_stack: Vec<repose_core::Rect> = Vec::with_capacity(8);
        // NOTE: Records the clip instance range + flags of each active rounded-rect clip
        // so PopClip can re-stamp the stencil with a decrement pass (mirroring
        // VectorClipPop). Keys: (off, cnt, difference, rounded).
        let mut clip_cmd_stack: Vec<(u64, u32, bool)> = Vec::with_capacity(8);
        let mut root_clip_rect = repose_core::Rect {
            x: 0.0,
            y: 0.0,
            w: fb_w,
            h: fb_h,
        };
        let mut saved_scissor_stack: Vec<repose_core::Rect> = Vec::new();
        let mut saved_root_clip_rect = root_clip_rect;

        let mut current_prim: Option<&'static str> = None;

        macro_rules! flush_if_prim_changed {
            ($prim:literal, $pipe:expr) => {
                if current_prim != Some($prim) {
                    flush_batch!();
                    current_prim = Some($prim);
                }
            };
        }

        macro_rules! flush_batch {
            () => {
                if !batch.is_empty() {
                    batch.flush(
                        (
                            &mut self.rects,
                            &mut self.borders,
                            &mut self.ellipses,
                            &mut self.ellipse_borders,
                            &mut self.arcs,
                        ),
                        (&mut self.glyph_mask, &mut self.glyph_color),
                        &mut self.nv12,
                        &self.device,
                        &self.queue,
                        &mut current_pass.cmds,
                    )
                }
            };
        }
        for node in &scene.nodes {
            let t_identity = Transform::identity();
            let current_transform = transform_stack.last().unwrap_or(&t_identity);

            match node {
                SceneNode::Rect {
                    rect,
                    brush,
                    radius,
                } => {
                    flush_if_prim_changed!("rect", &self.rects);
                    let (ndc, fwd_mat) = rect_to_instance_ndc(
                        *rect,
                        current_transform,
                        current_target_size.0,
                        current_target_size.1,
                    );
                    let (brush_type, grad_kind, color0, color1, grad_p0, grad_p1, tile_mode) =
                        brush_to_shape_fields(brush, rect, current_transform);
                    batch.rects.push(RectInstance {
                        xywh: ndc,
                        radii: radius.map(|r| r.0),
                        brush_type,
                        grad_kind,
                        _pad: [0.0; 2],
                        color0,
                        color1,
                        grad_p0,
                        grad_p1,
                        tile_mode,
                        _pad2: [0.0; 3],
                        fwd_mat,
                    });
                }
                SceneNode::Border {
                    rect,
                    brush,
                    width,
                    radius,
                } => {
                    flush_if_prim_changed!("border", &self.borders);
                    let (ndc, fwd_mat) = rect_to_instance_ndc(
                        *rect,
                        current_transform,
                        current_target_size.0,
                        current_target_size.1,
                    );
                    let (brush_type, grad_kind, color0, color1, grad_p0, grad_p1, tile_mode) =
                        brush_to_shape_fields(brush, rect, current_transform);
                    batch.borders.push(BorderInstance {
                        xywh: ndc,
                        radii: radius.map(|r| r.0),
                        stroke: width.0,
                        brush_type,
                        _pad: [0.0; 2],
                        grad_kind,
                        color0,
                        color1,
                        grad_p0,
                        grad_p1,
                        tile_mode,
                        _pad2: [0.0; 3],
                        fwd_mat,
                    });
                }
                SceneNode::Ellipse { rect, brush } => {
                    flush_if_prim_changed!("ellipse", &self.ellipses);
                    let (ndc, fwd_mat) = rect_to_instance_ndc(
                        *rect,
                        current_transform,
                        current_target_size.0,
                        current_target_size.1,
                    );
                    let (brush_type, grad_kind, color0, color1, grad_p0, grad_p1, tile_mode) =
                        brush_to_shape_fields(brush, rect, current_transform);
                    batch.ellipses.push(EllipseInstance {
                        xywh: ndc,
                        brush_type,
                        grad_kind,
                        _pad: [0.0; 2],
                        color0,
                        color1,
                        grad_p0,
                        grad_p1,
                        tile_mode,
                        _pad2: [0.0; 3],
                        fwd_mat,
                    });
                }
                SceneNode::EllipseBorder { rect, brush, width } => {
                    flush_if_prim_changed!("ellipse_border", &self.ellipse_borders);
                    let (ndc, fwd_mat) = rect_to_instance_ndc(
                        *rect,
                        current_transform,
                        current_target_size.0,
                        current_target_size.1,
                    );
                    let pad_px = width.0 * 0.5 + 2.0;
                    let pad = (pad_px / current_target_size.0) * 2.0;
                    let (brush_type, grad_kind, color0, color1, grad_p0, grad_p1, tile_mode) =
                        brush_to_shape_fields(brush, rect, current_transform);
                    batch.e_borders.push(EllipseBorderInstance {
                        xywh: ndc,
                        stroke: width.0,
                        pad,
                        brush_type,
                        grad_kind,
                        color0,
                        color1,
                        grad_p0,
                        grad_p1,
                        tile_mode,
                        _pad2: [0.0; 3],
                        fwd_mat,
                    });
                }
                SceneNode::Arc {
                    rect,
                    start_angle,
                    sweep_angle,
                    stroke_width,
                    brush,
                    cap,
                } => {
                    flush_if_prim_changed!("arc", &self.arcs);
                    let (ndc, fwd_mat) = rect_to_instance_ndc(
                        *rect,
                        current_transform,
                        current_target_size.0,
                        current_target_size.1,
                    );
                    let pad_px = stroke_width.0 * 0.5 + 2.0;
                    let pad = (pad_px / current_target_size.0) * 2.0;
                    let cap_val = match cap {
                        StrokeCap::Butt => 0.0,
                        StrokeCap::Round => 1.0,
                        StrokeCap::Square => 2.0,
                    };
                    let (brush_type, grad_kind, color0, color1, grad_p0, grad_p1, tile_mode) =
                        brush_to_shape_fields(brush, rect, current_transform);
                    batch.arcs.push(ArcInstance {
                        xywh: ndc,
                        start_angle: *start_angle,
                        sweep_angle: *sweep_angle,
                        stroke: stroke_width.0,
                        pad,
                        brush_type,
                        grad_kind,
                        _pad0: [0.0; 2],
                        color0,
                        color1,
                        grad_p0,
                        grad_p1,
                        tile_mode,
                        cap: cap_val,
                        _pad1: [0.0; 2],
                        fwd_mat,
                    });
                }
                SceneNode::Text {
                    rect,
                    text,
                    color,
                    size,
                    font_family,
                    text_align: _,
                    font_weight,
                    font_style,
                    text_decoration,
                    letter_spacing,
                    line_height: _,
                    extra_style,
                    url: _,
                    font_variation_settings,
                } => {
                    flush_batch!(); // flush any prior primitives

                    let px = size.0;
                    let lh_ratio = rect.h / px;
                    let fw = font_weight.0;
                    let fs = if *font_style == FontStyle::Italic {
                        1
                    } else {
                        0
                    };
                    let shaped = repose_text::shape_line(
                        text.as_ref(),
                        px,
                        lh_ratio,
                        *font_family,
                        fw,
                        fs,
                        letter_spacing.0,
                        font_variation_settings.as_deref(),
                    );
                    let baseline_y = shaped.first().map(|g| rect.y + g.y);

                    let fwd = forward_rs_mat(current_transform);
                    let has_linear = fwd != [1.0, 0.0, 0.0, 1.0];

                    let lin = current_transform.linear();
                    let tr_x = current_transform.translate_x;
                    let tr_y = current_transform.translate_y;

                    let make_glyph_instance =
                        |gx: f32, gy: f32, gw: f32, gh: f32| -> ([f32; 4], [f32; 4]) {
                            if has_linear {
                                let gc_x = gx + gw * 0.5;
                                let gc_y = gy + gh * 0.5;
                                let wc_x = lin[0] * gc_x + lin[1] * gc_y + tr_x;
                                let wc_y = lin[2] * gc_x + lin[3] * gc_y + tr_y;
                                let ww = gw * current_transform.scale_x;
                                let wh = gh * current_transform.scale_y;
                                let ex = fwd[0].abs() * ww * 0.5 + fwd[1].abs() * wh * 0.5;
                                let ey = fwd[2].abs() * ww * 0.5 + fwd[3].abs() * wh * 0.5;
                                let ndc_tl = to_ndc(
                                    wc_x - ex,
                                    wc_y - ey,
                                    ex * 2.0,
                                    ey * 2.0,
                                    current_target_size.0,
                                    current_target_size.1,
                                );
                                let ndc = [
                                    ndc_tl[0] + ndc_tl[2] * 0.5,
                                    ndc_tl[1] + ndc_tl[3] * 0.5,
                                    ndc_tl[2],
                                    ndc_tl[3],
                                ];
                                (ndc, fwd)
                            } else {
                                let (sx, sy) = if current_transform.scale_x == 1.0
                                    && current_transform.scale_y == 1.0
                                {
                                    (gx.round(), gy.round())
                                } else {
                                    (gx, gy)
                                };
                                rect_to_instance_ndc(
                                    repose_core::Rect {
                                        x: sx,
                                        y: sy,
                                        w: gw,
                                        h: gh,
                                    },
                                    current_transform,
                                    current_target_size.0,
                                    current_target_size.1,
                                )
                            }
                        };

                    let baseline_shift_y: f32 = px * extra_style.baseline_shift.0;

                    let (
                        draws_fill,
                        is_stroke,
                        stroke_width,
                        stroke_cap,
                        stroke_join,
                        stroke_miter,
                        stroke_path_effect,
                    ) = match &extra_style.draw_style {
                        repose_core::DrawStyle::Stroke {
                            width,
                            cap,
                            join,
                            miter,
                            path_effect,
                        } => (
                            false,
                            true,
                            *width,
                            *cap,
                            *join,
                            *miter,
                            path_effect.clone(),
                        ),
                        repose_core::DrawStyle::FillAndStroke {
                            width,
                            cap,
                            join,
                            miter,
                            path_effect,
                        } => (true, true, *width, *cap, *join, *miter, path_effect.clone()),
                        _ => (
                            true,
                            false,
                            0.0,
                            repose_core::StrokeCap::Butt,
                            repose_core::StrokeJoin::Miter,
                            4.0,
                            None,
                        ),
                    };
                    let stroke_tess_key = if is_stroke {
                        Some(slug::StrokeTessKey::new(
                            stroke_width,
                            stroke_cap,
                            stroke_join,
                            stroke_miter,
                            &stroke_path_effect,
                        ))
                    } else {
                        None
                    };

                    for sg in shaped {
                        let gx = rect.x + sg.x + sg.bearing_x;
                        let gy = rect.y + sg.y - sg.bearing_y + baseline_shift_y;

                        // Vector glyph path: tessellated geometry with MSAA.
                        if self.slug_enabled {
                            let ck = repose_text::lookup_cache_key(sg.key, sg.px);
                            if let Some(ref ck) = ck {
                                // Check if cached.
                                let need_tessellate = self.slug_cache.get(ck).is_none_or(|g| {
                                    (draws_fill && g.fill_vertices.is_none())
                                        || (is_stroke
                                            && !g
                                                .stroke_variants
                                                .contains_key(stroke_tess_key.as_ref().unwrap()))
                                });
                                if need_tessellate {
                                    if let Some((ck2, commands)) =
                                        repose_text::lookup_and_extract_outline(sg.key, sg.px)
                                    {
                                        let font_size_px = f32::from_bits(ck2.font_size_bits);
                                        if draws_fill {
                                            self.slug_cache.get_or_insert(
                                                ck2,
                                                font_size_px,
                                                &commands,
                                            );
                                        }
                                        if is_stroke {
                                            self.slug_cache.get_or_insert_stroke(
                                                ck2,
                                                font_size_px,
                                                &commands,
                                                stroke_width,
                                                stroke_cap,
                                                stroke_join,
                                                stroke_miter,
                                                &stroke_path_effect,
                                            );
                                        }
                                    }
                                } else {
                                    self.slug_cache.touch(ck);
                                }
                            }
                            if let Some(entry) = ck.as_ref().and_then(|ck| self.slug_cache.get(ck))
                            {
                                let ox = rect.x + sg.x;
                                let oy = rect.y + sg.y + baseline_shift_y;
                                let scx = current_transform.scale_x;
                                let scy = current_transform.scale_y;
                                let ttx = current_transform.translate_x;
                                let tty = current_transform.translate_y;

                                let tf = |x: f32, y: f32| -> (f32, f32) {
                                    if has_linear {
                                        (
                                            lin[0] * x + lin[1] * y + ttx,
                                            lin[2] * x + lin[3] * y + tty,
                                        )
                                    } else {
                                        (x * scx + ttx, y * scy + tty)
                                    }
                                };

                                let tw = current_target_size.0;
                                let th = current_target_size.1;

                                let mut emit = |verts: &[[f32; 2]]| {
                                    for &v in verts {
                                        let (sx, sy) = tf(ox + v[0] * px, oy - v[1] * px);
                                        let ndc_x = sx / tw * 2.0 - 1.0;
                                        let ndc_y = -(sy / th) * 2.0 + 1.0;
                                        slug_verts_local.push(slug::TessVertex {
                                            ndc_pos: [ndc_x, ndc_y],
                                            color: color.to_linear(),
                                        });
                                    }
                                };
                                if draws_fill {
                                    emit(entry.fill_vertices.as_deref().unwrap_or(&[]));
                                }
                                if is_stroke {
                                    let key = stroke_tess_key.as_ref().unwrap();
                                    emit(
                                        entry
                                            .stroke_variants
                                            .get(key)
                                            .map(|v| v.as_slice())
                                            .unwrap_or(&[]),
                                    );
                                }

                                if !draws_fill {
                                    // Stroke glyphs cannot use atlas fallback...
                                    continue;
                                }
                                continue;
                            }
                        }

                        if !draws_fill {
                            // Don't use atlas fallback for strokes too
                            continue;
                        }

                        if let Some(info) = self.upload_glyph_color(sg.key, sg.px) {
                            let (ndc, fwd_mat) = make_glyph_instance(gx, gy, info.w, info.h);
                            batch.colors.push(GlyphInstance {
                                xywh: ndc,
                                uv: [info.u0, info.v1, info.u1, info.v0],
                                color: color.to_linear(),
                                fwd_mat,
                            });
                        } else if let Some(info) = self.upload_glyph_mask(sg.key, sg.px) {
                            let (ndc, fwd_mat) = make_glyph_instance(gx, gy, info.w, info.h);
                            batch.masks.push(GlyphInstance {
                                xywh: ndc,
                                uv: [info.u0, info.v1, info.u1, info.v0],
                                color: color.to_linear(),
                                fwd_mat,
                            });
                        }
                    }

                    // Upload slug vertices if any
                    if !slug_verts_local.is_empty() {
                        let bytes = bytemuck::cast_slice(&slug_verts_local);
                        self.slug_ring.grow_to_fit(&self.device, bytes.len() as u64);
                        let (off, _) = self.slug_ring.alloc_write(&self.queue, bytes);
                        current_pass.cmds.push(Cmd::GlyphsVector {
                            off,
                            cnt: slug_verts_local.len() as u32,
                        });
                        slug_verts_local.clear();
                    }

                    // Text decoration: underline / strikethrough
                    if (text_decoration.underline || text_decoration.strikethrough)
                        && let Some(baseline_y) = baseline_y
                    {
                        flush_batch!();
                        current_prim = Some("rect");
                        let deco_color = text_decoration.color.unwrap_or(*color);
                        let thickness = (px * 0.07).max(1.0);

                        if text_decoration.underline {
                            let dy = baseline_y + px * 0.1;
                            let (ndc, fwd_mat) = rect_to_instance_ndc(
                                repose_core::Rect {
                                    x: rect.x,
                                    y: dy,
                                    w: rect.w,
                                    h: thickness,
                                },
                                current_transform,
                                current_target_size.0,
                                current_target_size.1,
                            );
                            batch.rects.push(RectInstance {
                                xywh: ndc,
                                radii: [0.0; 4],
                                brush_type: 0,
                                grad_kind: 0,
                                _pad: [0.0; 2],
                                color0: deco_color.to_linear(),
                                color1: [0.0; 4],
                                grad_p0: [0.0; 2],
                                grad_p1: [0.0; 2],
                                tile_mode: 0,
                                _pad2: [0.0; 3],
                                fwd_mat,
                            });
                        }
                        if text_decoration.strikethrough {
                            let sy = baseline_y - px * 0.3;
                            let (ndc, fwd_mat) = rect_to_instance_ndc(
                                repose_core::Rect {
                                    x: rect.x,
                                    y: sy,
                                    w: rect.w,
                                    h: thickness,
                                },
                                current_transform,
                                current_target_size.0,
                                current_target_size.1,
                            );
                            batch.rects.push(RectInstance {
                                xywh: ndc,
                                radii: [0.0; 4],
                                brush_type: 0,
                                grad_kind: 0,
                                _pad: [0.0; 2],
                                color0: deco_color.to_linear(),
                                color1: [0.0; 4],
                                grad_p0: [0.0; 2],
                                grad_p1: [0.0; 2],
                                tile_mode: 0,
                                _pad2: [0.0; 3],
                                fwd_mat,
                            });
                        }
                    }
                }
                SceneNode::Image {
                    rect,
                    handle,
                    tint,
                    fit,
                } => {
                    flush_batch!();

                    // Update usage timestamp for eviction, lazily re-uploading
                    // evicted RGBA images from their retained source.
                    let (img_w, img_h, is_nv12) = match self.resolve_image_for_draw(*handle) {
                        Some(wh) => wh,
                        None => {
                            log::warn!("Image handle {} not found", handle);
                            continue;
                        }
                    };

                    let src_w = img_w as f32;
                    let src_h = img_h as f32;

                    let dst_w = rect.w.max(0.0);
                    let dst_h = rect.h.max(0.0);
                    if dst_w <= 0.0 || dst_h <= 0.0 {
                        continue;
                    }

                    let (draw_rect, uv_rect) = match fit {
                        repose_core::view::ImageFit::Contain => {
                            let scale = (dst_w / src_w).min(dst_h / src_h);
                            let w = src_w * scale;
                            let h = src_h * scale;
                            (
                                repose_core::Rect {
                                    x: rect.x + (dst_w - w) * 0.5,
                                    y: rect.y + (dst_h - h) * 0.5,
                                    w,
                                    h,
                                },
                                [0.0, 1.0, 1.0, 0.0],
                            )
                        }
                        repose_core::view::ImageFit::Cover => {
                            let scale = (dst_w / src_w).max(dst_h / src_h);
                            let content_w = src_w * scale;
                            let content_h = src_h * scale;
                            let overflow_x = (content_w - dst_w) * 0.5;
                            let overflow_y = (content_h - dst_h) * 0.5;
                            let u0 = (overflow_x / content_w).clamp(0.0, 1.0);
                            let v0 = (overflow_y / content_h).clamp(0.0, 1.0);
                            let u1 = ((overflow_x + dst_w) / content_w).clamp(0.0, 1.0);
                            let v1 = ((overflow_y + dst_h) / content_h).clamp(0.0, 1.0);
                            (*rect, [u0, 1.0 - v0, u1, 1.0 - v1])
                        }
                        repose_core::view::ImageFit::FitWidth => {
                            let scale = dst_w / src_w;
                            (
                                repose_core::Rect {
                                    x: rect.x,
                                    y: rect.y + (dst_h - src_h * scale) * 0.5,
                                    w: dst_w,
                                    h: src_h * scale,
                                },
                                [0.0, 1.0, 1.0, 0.0],
                            )
                        }
                        repose_core::view::ImageFit::FitHeight => {
                            let scale = dst_h / src_h;
                            (
                                repose_core::Rect {
                                    x: rect.x + (dst_w - src_w * scale) * 0.5,
                                    y: rect.y,
                                    w: src_w * scale,
                                    h: dst_h,
                                },
                                [0.0, 1.0, 1.0, 0.0],
                            )
                        }
                        repose_core::view::ImageFit::FillBounds => (*rect, [0.0, 1.0, 1.0, 0.0]),
                        repose_core::view::ImageFit::Inside => {
                            let scale = (dst_w / src_w).min(dst_h / src_h).min(1.0);
                            let w = src_w * scale;
                            let h = src_h * scale;
                            (
                                repose_core::Rect {
                                    x: rect.x + (dst_w - w) * 0.5,
                                    y: rect.y + (dst_h - h) * 0.5,
                                    w,
                                    h,
                                },
                                [0.0, 1.0, 1.0, 0.0],
                            )
                        }
                        repose_core::view::ImageFit::None => {
                            (
                                repose_core::Rect {
                                    x: rect.x,
                                    y: rect.y,
                                    w: src_w.min(dst_w),
                                    h: src_h.min(dst_h),
                                },
                                // If larger than dst, crop top-left of source:
                                [
                                    0.0,
                                    1.0,
                                    (dst_w / src_w).min(1.0),
                                    1.0 - (dst_h / src_h).min(1.0),
                                ],
                            )
                        }
                        _ => continue,
                    };

                    let (ndc_center, fwd_mat) = rect_to_instance_ndc(
                        draw_rect,
                        current_transform,
                        current_target_size.0,
                        current_target_size.1,
                    );

                    if is_nv12 {
                        let uv_x_offset = if let Some(ImageTex::Nv12 { w, color_info, .. }) =
                            self.images.get(handle)
                        {
                            match color_info.chroma_siting {
                                ChromaSiting::Center | ChromaSiting::TopLeft => 0.0,
                                ChromaSiting::Left => -1.0 / *w as f32,
                            }
                        } else {
                            0.0
                        };

                        let inst = Nv12Instance {
                            xywh: ndc_center,
                            uv: uv_rect,
                            color: tint.to_linear(),
                            uv_x_offset,
                            fwd_mat,
                            _pad: [0.0],
                        };
                        if let Some((off, _)) = self.nv12.upload(&self.device, &self.queue, &[inst])
                        {
                            current_pass.cmds.push(Cmd::ImageNv12 {
                                off,
                                cnt: 1,
                                handle: *handle,
                            });
                        }
                    } else {
                        // RGBA uses GlyphInstance struct (reused pipeline)
                        let inst = GlyphInstance {
                            xywh: ndc_center,
                            uv: uv_rect,
                            color: tint.to_linear(),
                            fwd_mat,
                        };
                        if let Some((off, _)) =
                            self.glyph_color.upload(&self.device, &self.queue, &[inst])
                        {
                            current_pass.cmds.push(Cmd::ImageRgba {
                                off,
                                cnt: 1,
                                handle: *handle,
                            });
                        }
                    }
                }
                SceneNode::Coverage {
                    rect,
                    handle,
                    color,
                } => {
                    flush_batch!();
                    // Unknown handles are skipped (same policy as images);
                    // the lookup also marks the tile used for eviction.
                    let Some((tile_w, tile_h)) = self.coverage_dimensions(*handle) else {
                        log::warn!("Coverage handle {handle} not found");
                        continue;
                    };
                    // The tile composites at its registered size; `rect`
                    // positions its top-left.
                    let draw_rect = repose_core::Rect {
                        x: rect.x,
                        y: rect.y,
                        w: tile_w as f32,
                        h: tile_h as f32,
                    };
                    let (ndc_center, fwd_mat) = rect_to_instance_ndc(
                        draw_rect,
                        current_transform,
                        current_target_size.0,
                        current_target_size.1,
                    );
                    let inst = GlyphInstance {
                        xywh: ndc_center,
                        uv: [0.0, 1.0, 1.0, 0.0],
                        color: color.to_linear(),
                        fwd_mat,
                    };
                    if let Some((off, _)) =
                        self.glyph_color.upload(&self.device, &self.queue, &[inst])
                    {
                        current_pass.cmds.push(Cmd::Coverage {
                            off,
                            cnt: 1,
                            handle: *handle,
                        });
                    }
                }
                SceneNode::PushClip { rect, radius, op } => {
                    flush_batch!(); // flush content before entering clip

                    let is_diff = matches!(op, repose_core::ClipOp::Difference);

                    let t_identity = Transform::identity();
                    let current_transform = transform_stack.last().unwrap_or(&t_identity);
                    let transformed = affine_aabb(current_transform, rect);

                    let top = scissor_stack.last().copied().unwrap_or(root_clip_rect);
                    let next_scissor = if is_diff {
                        top
                    } else {
                        intersect(top, transformed)
                    };
                    scissor_stack.push(next_scissor);
                    let scissor = to_scissor(
                        &next_scissor,
                        current_target_size.0 as u32,
                        current_target_size.1 as u32,
                    );

                    let clip_ndc_tl = to_ndc(
                        transformed.x,
                        transformed.y,
                        transformed.w,
                        transformed.h,
                        current_target_size.0,
                        current_target_size.1,
                    );
                    let inst = ClipInstance {
                        xywh: [
                            clip_ndc_tl[0] + clip_ndc_tl[2] * 0.5,
                            clip_ndc_tl[1] + clip_ndc_tl[3] * 0.5,
                            clip_ndc_tl[2],
                            clip_ndc_tl[3],
                        ],
                        radii: radius.map(|r| r.0),
                        fwd_mat: [1.0, 0.0, 0.0, 1.0],
                    };
                    let bytes = bytemuck::bytes_of(&inst);
                    self.clip_ring.grow_to_fit(&self.device, bytes.len() as u64);
                    let (off, _) = self.clip_ring.alloc_write(&self.queue, bytes);

                    let rounded = radius.iter().any(|&r| r.0 > 0.5);

                    current_pass.cmds.push(Cmd::ClipPush {
                        off,
                        cnt: 1,
                        scissor,
                        difference: is_diff,
                        rounded,
                    });
                    clip_cmd_stack.push((off, 1, is_diff));
                }
                SceneNode::PopClip => {
                    flush_batch!();

                    if !scissor_stack.is_empty() {
                        scissor_stack.pop();
                    } else {
                        log::warn!("PopClip with empty stack");
                    }

                    let top = scissor_stack.last().copied().unwrap_or(root_clip_rect);
                    let scissor = to_scissor(
                        &top,
                        current_target_size.0 as u32,
                        current_target_size.1 as u32,
                    );
                    let (off, cnt, difference) = clip_cmd_stack.pop().unwrap_or((0, 0, false));
                    current_pass.cmds.push(Cmd::ClipPop {
                        off,
                        cnt,
                        scissor,
                        difference,
                    });
                }
                SceneNode::Shadow {
                    rect,
                    radius,
                    elevation: _,
                    color,
                } => {
                    flush_if_prim_changed!("rect", &self.rects);
                    let (ndc, fwd_mat) = rect_to_instance_ndc(
                        *rect,
                        current_transform,
                        current_target_size.0,
                        current_target_size.1,
                    );
                    let (brush_type, color0, _color1, _grad_p0, _grad_p1) =
                        brush_to_instance_fields(&Brush::Solid(*color));
                    batch.rects.push(RectInstance {
                        xywh: ndc,
                        radii: radius.map(|r| r.0),
                        brush_type,
                        grad_kind: 0,
                        _pad: [0.0; 2],
                        color0,
                        color1: [0.0; 4],
                        grad_p0: [0.0; 2],
                        grad_p1: [0.0; 2],
                        tile_mode: 0,
                        _pad2: [0.0; 3],
                        fwd_mat,
                    });
                }
                SceneNode::PushTransform { transform } => {
                    flush_batch!(); // flush before transform change
                    if transform.has_perspective() {
                        // True perspective cannot ride the affine fast path:
                        // flatten the subtree into an offscreen layer and
                        // composite it back projectively (CSS-style). See
                        // `push_perspective_layer`.
                        let top = *transform_stack.last().unwrap_or(&t_identity);
                        self.push_perspective_layer(
                            *transform,
                            top,
                            &mut transform_stack,
                            &mut scissor_stack,
                            &mut root_clip_rect,
                            &mut current_target_size,
                            &mut current_pass,
                            &mut passes,
                            &mut target_stack,
                            &mut flatten_stack,
                            &mut flatten_id_head,
                            &mut flatten_ids_used,
                        );
                    } else {
                        let combined = current_transform.combine(transform);
                        transform_stack.push(combined);
                    }
                }
                SceneNode::PopTransform => {
                    flush_batch!(); // flush before transform change
                    if let Some(rec) = flatten_stack.last() {
                        // A flatten level closes when the stack is back to the
                        // two entries this flatten pushed (stripped transform +
                        // layer-local shift); deeper plain pushes close first.
                        if transform_stack.len() == rec.stack_len + 2 {
                            let rec = flatten_stack.pop().expect("checked above");
                            transform_stack.pop();
                            transform_stack.pop();
                            self.pop_perspective_layer(
                                rec,
                                &mut scissor_stack,
                                &mut root_clip_rect,
                                &mut current_target_size,
                                &mut current_pass,
                                &mut passes,
                                &mut target_stack,
                            );
                            continue;
                        }
                    }
                    transform_stack.pop();
                }
                SceneNode::BeginLayer {
                    rect,
                    layer_id,
                    alpha,
                    blur_radius_x,
                    blur_radius_y,
                    rectangle_edge: _,
                } => {
                    flush_batch!();
                    // Layer rect is already snapped to whole pixels in layout;
                    // round() keeps any bypass of that snap consistent.
                    let w = (rect.w.round().max(1.0)) as u32;
                    let h = (rect.h.round().max(1.0)) as u32;
                    saved_scissor_stack =
                        std::mem::replace(&mut scissor_stack, Vec::with_capacity(8));
                    saved_root_clip_rect = std::mem::replace(
                        &mut root_clip_rect,
                        repose_core::Rect {
                            x: 0.0,
                            y: 0.0,
                            w: w as f32,
                            h: h as f32,
                        },
                    );
                    scissor_stack.push(root_clip_rect);
                    // Close out the current pass, start a new one for the layer.
                    let prev_target = current_pass.target;
                    let prev_scissor = current_pass.initial_scissor;
                    let saved = std::mem::replace(
                        &mut current_pass,
                        Pass {
                            target: PassTarget::Layer(*layer_id),
                            initial_scissor: (0, 0, w, h),
                            clear_color: Some([0.0, 0.0, 0.0, 0.0]),
                            cmds: Vec::new(),
                        },
                    );
                    passes.push(saved);
                    target_stack.push(prev_target);
                    let _ = prev_scissor; // initial_scissor of resumed pass is restored at EndLayer
                    // Get or create the layer's offscreen texture now so that
                    // subsequent scissor ops / draws have a valid target.
                    self.get_or_create_layer(*layer_id, w, h, *rect);
                    current_target_size = (w as f32, h as f32);
                    layer_alphas.push((*layer_id, *alpha, current_pass.initial_scissor));
                    // Store blur info for post-processing after EndLayer
                    if blur_radius_x.0 > 0.0 || blur_radius_y.0 > 0.0 {
                        layer_blurs.push((*layer_id, blur_radius_x.0, blur_radius_y.0));
                    }
                }
                SceneNode::EndLayer { layer_id } => {
                    flush_batch!();
                    scissor_stack = std::mem::take(&mut saved_scissor_stack);
                    root_clip_rect = saved_root_clip_rect;
                    // Finish the layer's pass, start a new one on the previous target.
                    let saved = std::mem::replace(
                        &mut current_pass,
                        Pass {
                            target: target_stack.pop().unwrap_or(PassTarget::Surface),
                            initial_scissor: (0, 0, self.output_width, self.output_height),
                            clear_color: None, // LoadOp::Load - don't wipe earlier surface content
                            cmds: Vec::new(),
                        },
                    );
                    passes.push(saved);
                    current_target_size = (fb_w, fb_h);
                    // Issue a composite quad for the just-finished layer in the new pass.
                    if let Some((_, layer_alpha, _)) = layer_alphas
                        .iter()
                        .find(|(id, _, _)| id == layer_id)
                        .copied()
                    {
                        let layer = self.layer_pool.get(layer_id).expect("layer target");
                        let ndc_tl = to_ndc(
                            layer.rect_px.0,
                            layer.rect_px.1,
                            layer.rect_px.2,
                            layer.rect_px.3,
                            fb_w,
                            fb_h,
                        );
                        let uv_u1 = layer.rect_px.2 / layer.width.max(1) as f32;
                        let uv_v1 = layer.rect_px.3 / layer.height.max(1) as f32;
                        // Check if this layer needs content blur
                        let blur_px_val = layer_blurs
                            .iter()
                            .find(|(id, _, _)| id == layer_id)
                            .map(|(_, bx, by)| (*bx, *by));
                        if let Some((blur_x, blur_y)) =
                            blur_px_val.filter(|(bx, by)| *bx > 0.0 || *by > 0.0)
                        {
                            // Content blur: draw blurred version using the blur_content pipeline
                            let bw_uv = (blur_x * 1.5) / layer.width.max(1) as f32;
                            let bh_uv = (blur_y * 1.5) / layer.height.max(1) as f32;
                            let inst = BlurInstance {
                                xywh: [
                                    ndc_tl[0] + ndc_tl[2] * 0.5,
                                    ndc_tl[1] + ndc_tl[3] * 0.5,
                                    ndc_tl[2],
                                    ndc_tl[3],
                                ],
                                uv: [0.0, 0.0, uv_u1, uv_v1],
                                color: [1.0, 1.0, 1.0, layer_alpha],
                                blur_uv: [bw_uv, bh_uv],
                                fwd_mat: [1.0, 0.0, 0.0, 1.0],
                            };
                            self.blur_ring.grow_to_fit(
                                &self.device,
                                std::mem::size_of::<BlurInstance>() as u64,
                            );
                            let bytes = bytemuck::bytes_of(&inst);
                            let (off, _) = self.blur_ring.alloc_write(&self.queue, bytes);
                            current_pass.cmds.push(Cmd::CompositeBlur {
                                off,
                                cnt: 1,
                                layer_id: *layer_id,
                            });
                        } else {
                            // Normal sharp composite
                            let inst = GlyphInstance {
                                xywh: [
                                    ndc_tl[0] + ndc_tl[2] * 0.5,
                                    ndc_tl[1] + ndc_tl[3] * 0.5,
                                    ndc_tl[2],
                                    ndc_tl[3],
                                ],
                                uv: [0.0, uv_v1, uv_u1, 0.0],
                                color: [1.0, 1.0, 1.0, layer_alpha],
                                fwd_mat: [1.0, 0.0, 0.0, 1.0],
                            };
                            if let Some((off, cnt)) =
                                self.glyph_color.upload(&self.device, &self.queue, &[inst])
                            {
                                current_pass.cmds.push(Cmd::CompositeLayer {
                                    off,
                                    cnt,
                                    layer_id: *layer_id,
                                });
                            }
                        }
                    }
                }
                SceneNode::CompositeShadow {
                    layer_id,
                    blur_px,
                    offset_px,
                    color,
                } => {
                    flush_batch!();
                    if let Some(layer) = self.layer_pool.get(layer_id).cloned() {
                        // Shadow rect = layer rect + offset.
                        let sx = layer.rect_px.0 + offset_px.0.0;
                        let sy = layer.rect_px.1 + offset_px.1.0;
                        let sw = layer.rect_px.2;
                        let sh = layer.rect_px.3;
                        // The blur in UV space is 1.5 * blur_px / texture_size
                        // (the 1.5 matches the 3x3 Gaussian span).
                        let bw_uv = (blur_px.0 * 1.5) / layer.width.max(1) as f32;
                        let bh_uv = (blur_px.0 * 1.5) / layer.height.max(1) as f32;
                        let shadow_u1 = layer.rect_px.2 / layer.width.max(1) as f32;
                        let shadow_v1 = layer.rect_px.3 / layer.height.max(1) as f32;
                        let ndc_tl = to_ndc(sx, sy, sw, sh, fb_w, fb_h);
                        let inst = BlurInstance {
                            xywh: [
                                ndc_tl[0] + ndc_tl[2] * 0.5,
                                ndc_tl[1] + ndc_tl[3] * 0.5,
                                ndc_tl[2],
                                ndc_tl[3],
                            ],
                            uv: [0.0, 0.0, shadow_u1, shadow_v1],
                            color: [
                                color.0 as f32 / 255.0,
                                color.1 as f32 / 255.0,
                                color.2 as f32 / 255.0,
                                color.3 as f32 / 255.0,
                            ],
                            blur_uv: [bw_uv, bh_uv],
                            fwd_mat: [1.0, 0.0, 0.0, 1.0],
                        };
                        self.blur_ring
                            .grow_to_fit(&self.device, std::mem::size_of::<BlurInstance>() as u64);
                        let bytes = bytemuck::bytes_of(&inst);
                        let (off, _) = self.blur_ring.alloc_write(&self.queue, bytes);
                        current_pass.cmds.push(Cmd::CompositeShadow {
                            off,
                            cnt: 1,
                            layer_id: *layer_id,
                        });
                    }
                }
                SceneNode::VectorMesh {
                    mesh,
                    transform,
                    paint,
                    clip: _,
                    blend: _,
                } => {
                    flush_batch!();
                    let t_identity = Transform::identity();
                    let current_transform = transform_stack.last().unwrap_or(&t_identity);
                    self.emit_vector_mesh(
                        current_transform,
                        mesh,
                        *transform,
                        paint,
                        &mut current_pass.cmds,
                    );
                }
                SceneNode::VectorOverlay { meshes } => {
                    flush_batch!();
                    for m in meshes.iter() {
                        let (voff, vcnt, ioff, icnt) = self.upload_mesh_geometry(m);
                        let uoff = self.alloc_mesh_uniform(MeshUniform::identity());
                        current_pass.cmds.push(Cmd::VectorOverlay {
                            voff,
                            vcnt,
                            ioff,
                            icnt,
                            uoff,
                        });
                    }
                }
                SceneNode::PushVectorClip { mesh, op } => {
                    flush_batch!();
                    let difference = matches!(op, repose_core::ClipOp::Difference);
                    let t_identity = Transform::identity();
                    let current_transform = transform_stack.last().unwrap_or(&t_identity);
                    let affine =
                        combine_mesh_affine(current_transform, [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]);
                    let aabb = mesh_aabb(mesh, affine);
                    let top = scissor_stack.last().copied().unwrap_or(root_clip_rect);
                    // An intersect mask can only remove pixels, so the scissor
                    // tightens; a difference mask removes the *inside*, so the
                    // scissor stays (content outside the mask must still draw).
                    let next = if difference {
                        top
                    } else {
                        intersect(top, aabb)
                    };
                    scissor_stack.push(next);
                    let scissor = to_scissor(
                        &next,
                        current_target_size.0 as u32,
                        current_target_size.1 as u32,
                    );
                    let (voff, vcnt, ioff, icnt) = self.upload_mesh_geometry(mesh);
                    let uoff = self.alloc_mesh_uniform(mesh_uniform_from_paint(
                        affine,
                        &repose_core::PaintDesc::Solid,
                    ));
                    current_pass.cmds.push(Cmd::VectorClipPush {
                        voff,
                        vcnt,
                        ioff,
                        icnt,
                        uoff,
                        scissor,
                        difference,
                    });
                    self.mesh_clip_stack
                        .push((voff, vcnt, ioff, icnt, uoff, difference));
                }
                SceneNode::PopVectorClip => {
                    flush_batch!();
                    if !scissor_stack.is_empty() {
                        scissor_stack.pop();
                    } else {
                        log::warn!("PopVectorClip with empty scissor stack");
                    }
                    if let Some((voff, vcnt, ioff, icnt, uoff, difference)) =
                        self.mesh_clip_stack.pop()
                    {
                        let top = scissor_stack.last().copied().unwrap_or(root_clip_rect);
                        let scissor = to_scissor(
                            &top,
                            current_target_size.0 as u32,
                            current_target_size.1 as u32,
                        );
                        current_pass.cmds.push(Cmd::VectorClipPop {
                            voff,
                            vcnt,
                            ioff,
                            icnt,
                            uoff,
                            scissor,
                            difference,
                        });
                    } else {
                        log::warn!("PopVectorClip with empty clip stack");
                    }
                }
                SceneNode::Callback { rect, payload } => {
                    flush_batch!();
                    let t = transform_stack
                        .last()
                        .copied()
                        .unwrap_or(Transform::identity());
                    let transformed = affine_aabb(&t, rect);
                    current_pass.cmds.push(Cmd::Callback {
                        rect: transformed,
                        payload: payload.clone(),
                    });
                }
                _ => {}
            }
        }

        flush_batch!();

        {
            let mut seen: std::collections::HashSet<usize> = std::collections::HashSet::new();
            let mut prepare_list: Vec<Arc<Callback>> = Vec::new();
            for node in &scene.nodes {
                if let SceneNode::Callback { payload, .. } = node
                    && payload.downcast_ref::<Callback>().is_some()
                {
                    let ptr = Arc::as_ptr(payload) as *const () as usize;
                    if seen.insert(ptr)
                        && let Ok(cb_arc) = payload.clone().downcast::<Callback>()
                    {
                        prepare_list.push(cb_arc);
                    }
                }
            }
            if !prepare_list.is_empty() {
                let screen_desc = ScreenDescriptor {
                    size_in_pixels: [self.output_width, self.output_height],
                    pixels_per_point: self.pixels_per_point,
                    target_format: self.output_format,
                    sample_count: self.msaa_samples.max(1),
                };
                let mut user_cmd_bufs: Vec<wgpu::CommandBuffer> = Vec::new();
                for cb in &prepare_list {
                    user_cmd_bufs.extend(cb.0.prepare(
                        &self.device,
                        &self.queue,
                        encoder,
                        &screen_desc,
                        &mut self.callback_resources,
                    ));
                }
                for cb in &prepare_list {
                    user_cmd_bufs.extend(cb.0.finish_prepare(
                        &self.device,
                        &self.queue,
                        encoder,
                        &screen_desc,
                        &mut self.callback_resources,
                    ));
                }
                // NOTE: For now submit immediately via queue
                // so they execute before main render pass.
                if !user_cmd_bufs.is_empty() {
                    self.queue.submit(user_cmd_bufs);
                }
            }
        }

        // Push the final pass.
        passes.push(current_pass);

        let globals_bytes = std::mem::size_of::<Globals>() as u64;
        let globals_staging = self.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("globals staging"),
            size: (passes.len().max(1) as u64) * globals_bytes,
            usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::COPY_SRC,
            mapped_at_creation: false,
        });
        for (i, pass) in passes.iter().enumerate() {
            let (target_w, target_h) = match pass.target {
                PassTarget::Surface => (fb_w, fb_h),
                PassTarget::Layer(layer_id) => {
                    let lt = self.layer_pool.get(&layer_id);
                    (
                        lt.map_or(fb_w, |l| l.width as f32),
                        lt.map_or(fb_h, |l| l.height as f32),
                    )
                }
            };
            self.queue.write_buffer(
                &globals_staging,
                (i as u64) * globals_bytes,
                bytemuck::bytes_of(&make_globals(target_w, target_h)),
            );
        }

        let bind_mask = self.atlas_bind_group_mask();
        let bind_color = self.atlas_bind_group_color();
        let mut clip_depth: u32 = 0;
        let mut clip_depth_stack: Vec<u32> = Vec::new();

        for (pass_index, pass) in std::mem::take(&mut passes).into_iter().enumerate() {
            let (color_view, resolve_target, depth_stencil_view, is_layer) = match pass.target {
                PassTarget::Surface => {
                    let swap_view = target_view.clone();
                    let use_ws = self.working_space && self.ws_view.is_some();
                    let (color, resolve) = if use_ws {
                        let ws_view = self.ws_view.as_ref().unwrap();
                        if let Some(msaa_view) = &self.msaa_view {
                            // MSAA resolves to working-space texture
                            (msaa_view.clone(), Some(ws_view.clone()))
                        } else {
                            // Direct render to working-space texture
                            (ws_view.clone(), None)
                        }
                    } else if let Some(msaa_view) = &self.msaa_view {
                        (msaa_view.clone(), Some(swap_view))
                    } else {
                        (swap_view, None)
                    };
                    (color, resolve, self.depth_stencil_view.clone(), false)
                }
                PassTarget::Layer(layer_id) => {
                    if let Some(lt) = self.layer_pool.get(&layer_id) {
                        (lt.view.clone(), None, lt.depth_stencil_view.clone(), true)
                    } else {
                        log::warn!("missing layer target {layer_id}");
                        continue;
                    }
                }
            };

            encoder.copy_buffer_to_buffer(
                &globals_staging,
                (pass_index as u64) * globals_bytes,
                &self.globals_buf,
                0,
                globals_bytes,
            );

            if is_layer {
                clip_depth_stack.push(clip_depth);
                clip_depth = 0;
            }

            let (tw, th) = match pass.target {
                PassTarget::Surface => (self.output_width, self.output_height),
                PassTarget::Layer(layer_id) => self
                    .layer_pool
                    .get(&layer_id)
                    .map(|l| (l.width, l.height))
                    .unwrap_or((self.output_width, self.output_height)),
            };
            let initial_scissor = clamp_scissor(
                pass.initial_scissor.0,
                pass.initial_scissor.1,
                pass.initial_scissor.2,
                pass.initial_scissor.3,
                tw,
                th,
            );

            let pipes: &Pipelines = if is_layer {
                &self.layer_pipes
            } else {
                &self.surface_pipes
            };

            let mut rpass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("pass"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: &color_view,
                    resolve_target: resolve_target.as_ref(),
                    ops: wgpu::Operations {
                        load: match pass.clear_color {
                            Some(c) => wgpu::LoadOp::Clear(wgpu::Color {
                                r: c[0] as f64,
                                g: c[1] as f64,
                                b: c[2] as f64,
                                a: c[3] as f64,
                            }),
                            None => wgpu::LoadOp::Load,
                        },
                        store: wgpu::StoreOp::Store,
                    },
                    depth_slice: None,
                })],
                depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                    view: &depth_stencil_view,
                    depth_ops: None,
                    stencil_ops: Some(wgpu::Operations {
                        load: if is_layer || pass.clear_color.is_some() {
                            wgpu::LoadOp::Clear(0)
                        } else {
                            wgpu::LoadOp::Load
                        },
                        store: wgpu::StoreOp::Store,
                    }),
                }),
                timestamp_writes: None,
                occlusion_query_set: None,
                multiview_mask: None,
            });

            rpass.set_bind_group(0, &self.globals_bind, &[]);
            rpass.set_stencil_reference(clip_depth);
            rpass.set_scissor_rect(
                initial_scissor.0,
                initial_scissor.1,
                initial_scissor.2,
                initial_scissor.3,
            );

            macro_rules! draw_simple {
                ($pipeline:expr, $ring:expr, $inst:ty, $off:ident, $n:ident) => {{
                    rpass.set_pipeline($pipeline);
                    let bytes = ($n as u64) * std::mem::size_of::<$inst>() as u64;
                    rpass.set_vertex_buffer(0, $ring.buf.slice($off..$off + bytes));
                    rpass.draw(0..6, 0..$n);
                }};
            }

            macro_rules! draw_with_bind {
                ($pipeline:expr, $ring:expr, $inst:ty, $bind:expr, $off:ident, $n:ident) => {{
                    rpass.set_pipeline($pipeline);
                    rpass.set_bind_group(1, $bind, &[]);
                    let bytes = ($n as u64) * std::mem::size_of::<$inst>() as u64;
                    rpass.set_vertex_buffer(0, $ring.buf.slice($off..$off + bytes));
                    rpass.draw(0..6, 0..$n);
                }};
            }

            macro_rules! draw_indexed_mesh {
                ($pipeline:expr, $uoff:ident, $voff:ident, $vcnt:ident, $ioff:ident, $icnt:ident) => {{
                    rpass.set_pipeline($pipeline);
                    rpass.set_bind_group(1, &self.mesh_bind, &[$uoff as u32]);
                    let vbytes = ($vcnt as u64) * std::mem::size_of::<MeshVertex>() as u64;
                    rpass.set_vertex_buffer(0, self.mesh_verts.buf.slice($voff..$voff + vbytes));
                    let ibytes = ($icnt as u64) * std::mem::size_of::<u32>() as u64;
                    rpass.set_index_buffer(
                        self.mesh_indices.buf.slice($ioff..$ioff + ibytes),
                        wgpu::IndexFormat::Uint32,
                    );
                    rpass.draw_indexed(0..$icnt, 0, 0..1);
                }};
            }

            for cmd in pass.cmds {
                match cmd {
                    Cmd::ClipPush {
                        off,
                        cnt: n,
                        scissor,
                        difference,
                        rounded: _,
                    } => {
                        let scissor =
                            clamp_scissor(scissor.0, scissor.1, scissor.2, scissor.3, tw, th);
                        rpass.set_scissor_rect(scissor.0, scissor.1, scissor.2, scissor.3);
                        rpass.set_stencil_reference(clip_depth);

                        if difference {
                            rpass.set_pipeline(&pipes.clip_dec);
                        } else {
                            // Deliberately whole-pixel (bin) gating at every
                            // sample count. Clipped content blends with its
                            // own smooth AA identically on all samples, while
                            // alpha-to-coverage gates per-sample and leaves a
                            // GPU-sample-pattern-dependent bright rim along
                            // rounded corners at fractional geometry. MSAA
                            // still smooths every content edge inside the
                            // clip region.
                            rpass.set_pipeline(&pipes.clip_bin);
                        }

                        let bytes = (n as u64) * std::mem::size_of::<ClipInstance>() as u64;
                        rpass.set_vertex_buffer(0, self.clip_ring.buf.slice(off..off + bytes));
                        rpass.draw(0..6, 0..n);

                        if !difference {
                            clip_depth = (clip_depth + 1).min(255);
                            rpass.set_stencil_reference(clip_depth);
                        }
                    }

                    Cmd::ClipPop {
                        off,
                        cnt: n,
                        scissor,
                        difference,
                    } => {
                        let scissor =
                            clamp_scissor(scissor.0, scissor.1, scissor.2, scissor.3, tw, th);
                        rpass.set_scissor_rect(scissor.0, scissor.1, scissor.2, scissor.3);

                        if !difference && n > 0 {
                            rpass.set_stencil_reference(clip_depth);
                            rpass.set_pipeline(&pipes.clip_dec);
                            let bytes = (n as u64) * std::mem::size_of::<ClipInstance>() as u64;
                            rpass.set_vertex_buffer(0, self.clip_ring.buf.slice(off..off + bytes));
                            rpass.draw(0..6, 0..n);
                            clip_depth = clip_depth.saturating_sub(1);
                        } else if !difference {
                            clip_depth = clip_depth.saturating_sub(1);
                        }
                        rpass.set_stencil_reference(clip_depth);
                    }

                    Cmd::Rect { off, cnt: n } => {
                        draw_simple!(&pipes.rects, self.rects.ring, RectInstance, off, n);
                    }

                    Cmd::Border { off, cnt: n } => {
                        draw_simple!(&pipes.borders, self.borders.ring, BorderInstance, off, n);
                    }

                    Cmd::GlyphsMask { off, cnt: n } => {
                        draw_with_bind!(
                            &pipes.text_mask,
                            self.glyph_mask.ring,
                            GlyphInstance,
                            &bind_mask,
                            off,
                            n
                        );
                    }

                    Cmd::GlyphsColor { off, cnt: n } => {
                        draw_with_bind!(
                            &pipes.text_color,
                            self.glyph_color.ring,
                            GlyphInstance,
                            &bind_color,
                            off,
                            n
                        );
                    }

                    Cmd::GlyphsVector { off, cnt: n } => {
                        if let Some(slug_pipe) = pipes.slug.as_ref() {
                            rpass.set_pipeline(slug_pipe);
                            let bytes = (n as u64) * std::mem::size_of::<slug::TessVertex>() as u64;
                            rpass.set_vertex_buffer(0, self.slug_ring.buf.slice(off..off + bytes));
                            rpass.draw(0..n, 0..1);
                        }
                    }

                    Cmd::ImageRgba {
                        off,
                        cnt: n,
                        handle,
                    } => {
                        let bind_opt = match self.images.get(&handle) {
                            Some(ImageTex::Rgba { bind, .. }) => Some(bind),
                            Some(ImageTex::User { bind, .. }) => Some(bind),
                            _ => None,
                        };
                        if let Some(bind) = bind_opt {
                            draw_with_bind!(
                                &pipes.image_rgba,
                                self.glyph_color.ring,
                                GlyphInstance,
                                bind,
                                off,
                                n
                            );
                        }
                    }
                    Cmd::Coverage {
                        off,
                        cnt: n,
                        handle,
                    } => {
                        if let Some(tile) = self.coverages.get(&handle) {
                            draw_with_bind!(
                                &pipes.coverage,
                                self.glyph_color.ring,
                                GlyphInstance,
                                &tile.bind,
                                off,
                                n
                            );
                        }
                    }

                    Cmd::ImageNv12 {
                        off,
                        cnt: n,
                        handle,
                    } => {
                        if let Some(ImageTex::Nv12 { bind, .. }) = self.images.get(&handle) {
                            draw_with_bind!(
                                &pipes.image_nv12,
                                self.nv12.ring,
                                Nv12Instance,
                                bind,
                                off,
                                n
                            );
                        }
                    }

                    Cmd::Ellipse { off, cnt: n } => {
                        draw_simple!(&pipes.ellipses, self.ellipses.ring, EllipseInstance, off, n);
                    }

                    Cmd::EllipseBorder { off, cnt: n } => {
                        draw_simple!(
                            &pipes.ellipse_borders,
                            self.ellipse_borders.ring,
                            EllipseBorderInstance,
                            off,
                            n
                        );
                    }

                    Cmd::Arc { off, cnt: n } => {
                        draw_simple!(&pipes.arcs, self.arcs.ring, ArcInstance, off, n);
                    }

                    Cmd::CompositeLayer {
                        off,
                        cnt: n,
                        layer_id,
                    } => {
                        if let Some(lt) = self.layer_pool.get(&layer_id).cloned() {
                            draw_with_bind!(
                                &pipes.image_rgba,
                                self.glyph_color.ring,
                                GlyphInstance,
                                &lt.bind,
                                off,
                                n
                            );
                        }
                    }
                    Cmd::CompositeShadow {
                        off,
                        cnt: n,
                        layer_id,
                    } => {
                        if let Some(lt) = self.layer_pool.get(&layer_id).cloned() {
                            draw_with_bind!(
                                &pipes.blur,
                                self.blur_ring,
                                BlurInstance,
                                &lt.bind_linear,
                                off,
                                n
                            );
                        }
                    }
                    Cmd::CompositeBlur {
                        off,
                        cnt: n,
                        layer_id,
                    } => {
                        if let Some(lt) = self.layer_pool.get(&layer_id).cloned() {
                            draw_with_bind!(
                                &pipes.blur_content,
                                self.blur_ring,
                                BlurInstance,
                                &lt.bind_linear,
                                off,
                                n
                            );
                        }
                    }
                    Cmd::CompositeProjective {
                        off,
                        cnt: n,
                        layer_id,
                    } => {
                        if let Some(lt) = self.layer_pool.get(&layer_id).cloned() {
                            // The layer texture is sampled with the rgba
                            // (non-linear-filter) binding, like the sharp
                            // composite path.
                            draw_with_bind!(
                                &pipes.projective_layer,
                                self.projective_ring,
                                ProjectiveInstance,
                                &lt.bind,
                                off,
                                n
                            );
                        }
                    }

                    Cmd::VectorMesh {
                        voff,
                        vcnt,
                        ioff,
                        icnt,
                        uoff,
                    } => {
                        draw_indexed_mesh!(&pipes.mesh, uoff, voff, vcnt, ioff, icnt);
                    }

                    Cmd::VectorOverlay {
                        voff,
                        vcnt,
                        ioff,
                        icnt,
                        uoff,
                    } => {
                        draw_indexed_mesh!(&pipes.mesh_overlay, uoff, voff, vcnt, ioff, icnt);
                    }

                    Cmd::VectorClipPush {
                        voff,
                        vcnt,
                        ioff,
                        icnt,
                        uoff,
                        scissor,
                        difference,
                    } => {
                        let scissor =
                            clamp_scissor(scissor.0, scissor.1, scissor.2, scissor.3, tw, th);
                        rpass.set_scissor_rect(scissor.0, scissor.1, scissor.2, scissor.3);
                        rpass.set_stencil_reference(clip_depth);
                        draw_indexed_mesh!(&pipes.mesh_clip_inc, uoff, voff, vcnt, ioff, icnt);
                        if !difference {
                            clip_depth = (clip_depth + 1).min(255);
                            rpass.set_stencil_reference(clip_depth);
                        }
                        // Difference masks increment without bumping the depth:
                        // content keeps testing `Equal(depth)`, which now fails
                        // exactly inside the mask. Exact for a lone mask and
                        // for a mask inside intersect clips.
                    }

                    Cmd::VectorClipPop {
                        voff,
                        vcnt,
                        ioff,
                        icnt,
                        uoff,
                        scissor,
                        difference,
                    } => {
                        // Decrement the mask while the stencil reference is
                        // still at the depth it was incremented to, so the
                        // equal-compare fires; then step the clip depth down.
                        // A difference mask incremented *above* the depth, so
                        // test depth+1 and leave the depth unchanged.
                        if difference {
                            rpass.set_stencil_reference((clip_depth + 1).min(255));
                        } else {
                            rpass.set_stencil_reference(clip_depth);
                        }
                        let scissor =
                            clamp_scissor(scissor.0, scissor.1, scissor.2, scissor.3, tw, th);
                        rpass.set_scissor_rect(scissor.0, scissor.1, scissor.2, scissor.3);
                        draw_indexed_mesh!(&pipes.mesh_clip_dec, uoff, voff, vcnt, ioff, icnt);
                        if !difference {
                            clip_depth = clip_depth.saturating_sub(1);
                        }
                        rpass.set_stencil_reference(clip_depth);
                    }

                    Cmd::Callback { rect, payload } => {
                        if let Some(cb) = payload.downcast_ref::<Callback>() {
                            let vp_x = rect.x.floor().max(0.0);
                            let vp_y = rect.y.floor().max(0.0);
                            let vp_w = rect.w.ceil().max(1.0);
                            let vp_h = rect.h.ceil().max(1.0);
                            if vp_w > 0.0 && vp_h > 0.0 {
                                rpass.set_viewport(vp_x, vp_y, vp_w, vp_h, 0.0, 1.0);
                                let info = repose_core::PaintCallbackInfo {
                                    viewport: rect,
                                    clip_rect: rect,
                                    pixels_per_point: self.pixels_per_point,
                                    screen_size_px: [tw, th],
                                };
                                let rpass_static: &mut wgpu::RenderPass<'static> = unsafe {
                                    std::mem::transmute::<
                                        &mut wgpu::RenderPass<'_>,
                                        &mut wgpu::RenderPass<'static>,
                                    >(&mut rpass)
                                };
                                cb.0.paint(info, rpass_static, &self.callback_resources);
                                rpass.set_viewport(0.0, 0.0, tw as f32, th as f32, 0.0, 1.0);
                                rpass.set_bind_group(0, &self.globals_bind, &[]);
                                rpass.set_stencil_reference(clip_depth);
                            }
                        } else {
                            log::warn!("Unknown paint callback payload");
                        }
                    }
                }
            }
            if is_layer {
                clip_depth = clip_depth_stack.pop().unwrap_or(0);
            }
        }

        // frame's ids so the next translation drains their textures.
        self.flatten_layer_ids = flatten_ids_used;

        // Display pass: linear working space -> sRGB OETF -> swapchain
        if self.working_space
            && let (Some(_ws_view), Some(ws_bind), Some(display_pipeline)) =
                (&self.ws_view, &self.ws_bind, &self.display_pipeline)
        {
            let swap_view = target_view.clone();
            let mut display_pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("display transform"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: &swap_view,
                    resolve_target: None,
                    ops: wgpu::Operations {
                        load: wgpu::LoadOp::Load,
                        store: wgpu::StoreOp::Store,
                    },
                    depth_slice: None,
                })],
                depth_stencil_attachment: None,
                timestamp_writes: None,
                occlusion_query_set: None,
                multiview_mask: None,
            });
            display_pass.set_pipeline(display_pipeline);
            display_pass.set_bind_group(1, ws_bind, &[]);
            display_pass.draw(0..3, 0..1);
        }

        // Frame end maintenance: Evict unused images
        self.evict_unused_images();
    }

    /// Render a scene into an externally-provided texture view.
    /// Use this when embedding Repose in a host that owns the GPU.
    /// The host is responsible for submitting the encoder and handling present.
    pub fn render_to_view(
        &mut self,
        scene: &Scene,
        encoder: &mut wgpu::CommandEncoder,
        target_view: &wgpu::TextureView,
        width: u32,
        height: u32,
        clear_color: Option<[f64; 4]>,
    ) {
        self.resize(width, height);

        self.frame_index = self.frame_index.wrapping_add(1);
        self.slug_cache.next_frame();

        if width == 0 || height == 0 {
            return;
        }

        self.render_scene_to_encoder(scene, encoder, target_view, clear_color);
    }
}

fn clamp_scissor(x: u32, y: u32, w: u32, h: u32, tw: u32, th: u32) -> (u32, u32, u32, u32) {
    let x = x.min(tw.saturating_sub(1));
    let y = y.min(th.saturating_sub(1));
    let w = w.min(tw.saturating_sub(x)).max(1);
    let h = h.min(th.saturating_sub(y)).max(1);
    (x, y, w, h)
}

fn intersect(a: repose_core::Rect, b: repose_core::Rect) -> repose_core::Rect {
    let x0 = a.x.max(b.x);
    let y0 = a.y.max(b.y);
    let x1 = (a.x + a.w).min(b.x + b.w);
    let y1 = (a.y + a.h).min(b.y + b.h);
    repose_core::Rect {
        x: x0,
        y: y0,
        w: (x1 - x0).max(0.0),
        h: (y1 - y0).max(0.0),
    }
}