teksilo_render/

renderer.rs

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

use wgpu;

use teksilo_canvas::RenderFrame;
use teksilo_canvas::geometry::Transform2D;

use crate::blur::{BlurPipelines, BlurPool};
use crate::image_manager::ImageManager;
use crate::path_atlas::PathAtlas;
use crate::stream_buffer::StreamBuffers;
use crate::vertex::{AnimQuadVertex, QuadVertex, RectVertex, SdfVertex, ShadowVertex};

/// How many animated-quad slots the uniform buffer holds. Must match
/// the array size in `shaders/anim_procedural.wgsl`. Bumping this
/// requires updating the WGSL constant too (WGSL array sizes are
/// static). 128 × 64 B = 8 KiB — well within UBO caps.
const MAX_ANIM_SLOTS: usize = 128;

/// GPU renderer that draws a RenderFrame using seven shader pipelines.
pub struct Renderer {
    device: wgpu::Device,
    queue: wgpu::Queue,
    /// `max_texture_dimension_2d` of the device behind `device`.
    ///
    /// Cached because both atlases grow to a compiled-in ceiling that a
    /// downlevel device need not be able to allocate, and the glyph atlas is
    /// sized by the text backend rather than by this crate.
    max_texture_dimension: u32,
    rect_pipeline: wgpu::RenderPipeline,
    sdf_pipeline: wgpu::RenderPipeline,
    quad_pipeline: wgpu::RenderPipeline,
    shadow_pipeline: wgpu::RenderPipeline,
    /// Gradient-filled path pipeline (Tier 3) — draws `PathEntry`s whose
    /// `paint_data` is a gradient variant. Solid-filled paths keep using
    /// the lean `quad_pipeline` above; see `path_gradient_quad_verts` /
    /// `PathGradientVertex`. Shares its group(0) bind-group layout
    /// (texture + sampler) with `quad_pipeline`, so it binds the same
    /// `path_atlas_texture` bind group the solid path-quad batch uses.
    path_gradient_pipeline: wgpu::RenderPipeline,
    /// Procedural animated-quad pipeline — IndeterminateSweep,
    /// SpinnerArc and future Pulse / Shimmer kinds. Binds group 0 to a
    /// uniform buffer holding an array of `AnimParams` (one per slot).
    anim_proc_pipeline: wgpu::RenderPipeline,
    /// Sprite-atlas animated-quad pipeline — frame-cycling for
    /// `AnimatedQuadKind::SpriteCycle`. Shares the same uniform buffer
    /// as the procedural pipeline at group 0; group 1 carries the
    /// per-atlas texture bind group. Reuses the quad_pipeline's
    /// bind-group layout for group 1, so the bind groups that
    /// `ImageManager` builds for static images are also usable here
    /// without a second registration.
    anim_sprite_pipeline: wgpu::RenderPipeline,
    /// Uniform buffer backing both animated-quad pipelines' per-slot
    /// state. Rewritten wholesale at the top of each `render()` from
    /// `frame.anim_params`. Fixed size (`MAX_ANIM_SLOTS * 64 B`); the
    /// upload in `render()` truncates if it ever exceeds.
    anim_uniform_buffer: wgpu::Buffer,
    /// Bind group for the animated pipelines (group 0 on both).
    anim_uniform_bind_group: wgpu::BindGroup,
    atlas_texture: Option<AtlasTexture>,
    path_atlas: PathAtlas,
    path_atlas_texture: Option<AtlasTexture>,
    image_manager: ImageManager,
    /// Persistent per-pipeline streaming buffers. Resized on demand at
    /// the top of each `render()` call, then reused via `write_buffer`
    /// for every batch flush in that frame — replaces the historical
    /// per-flush `create_buffer_init` antipattern.
    streams: StreamBuffers,
    /// Dual-Kawase blur pipelines (downsample + upsample) and per-pass
    /// uniform buffer. Built once at construction; consumed by the
    /// `BeginBlurredSubtree` / `EndBlurredSubtree` handler in `render`.
    blur_pipelines: BlurPipelines,
    /// Recycled intermediate-texture pool for blur scopes. Begin-of-
    /// frame resets per-texture in-use flags; textures unused for
    /// several frames evict.
    blur_pool: BlurPool,
    /// Cached bind group layout for the quad pipeline's group(0)
    /// (texture + sampler). Used to build per-frame bind groups that
    /// expose blur-pool intermediates as image sources for the
    /// compositing blit at the end of each blur scope.
    quad_bind_group_layout: wgpu::BindGroupLayout,
    /// Sampler used by the blur composite blit. Linear filtering so
    /// the over-allocated bucket texture's used sub-rect samples
    /// cleanly when composited onto a non-aligned target rect.
    blur_composite_sampler: wgpu::Sampler,
}

struct AtlasTexture {
    texture: wgpu::Texture,
    bind_group: wgpu::BindGroup,
    width: u32,
    height: u32,
}

/// Active render target — the bottom of the stack is always the
/// surface; intermediates push above it for the duration of a blur
/// scope. Each entry tracks both the target's identity and per-target
/// state that survives across multiple segment passes against the
/// same target (e.g. when an inner blur scope ends and we re-open
/// the parent intermediate to draw additional commands).
struct ActiveTarget {
    /// `None` ⇒ surface (the caller-provided texture view).
    /// `Some(handle)` ⇒ a blur intermediate from `BlurPool`.
    intermediate: Option<crate::blur::AcquiredTexture>,
    /// Viewport dimensions for NDC conversion in this scope.
    viewport_w: u32,
    viewport_h: u32,
    /// `false` until the first segment pass against this target runs;
    /// controls whether the next pass uses Clear or Load.
    opened: bool,
    /// Blurred sub-tree results that nested scopes have queued for
    /// compositing into THIS target on its next segment open. Drained
    /// at the top of each segment.
    pending_composites: Vec<PendingComposite>,
    /// Scissor rects of the clips opened on THIS target, in its own device
    /// pixels; the top is the effective clip (each entry is already the
    /// intersection with the one below). Kept per target because an
    /// intermediate draws its subtree at its own origin: a clip opened on
    /// the surface is in the wrong space there, and still applies to the
    /// composite of the blurred result once the surface pass reopens.
    clip_stack: Vec<[u32; 4]>,
    /// Intermediate-only metadata, populated when `intermediate.is_some()`.
    /// Carried here (rather than in a separate `BlurScope` stack)
    /// because End needs to look these up after popping the target.
    blur_bounds: Option<teksilo_canvas::Rect>,
    blur_radius_logical: Option<f32>,
    used_w: Option<u32>,
    used_h: Option<u32>,
    bucket_w: Option<u32>,
    bucket_h: Option<u32>,
}

impl ActiveTarget {
    fn surface(viewport_w: u32, viewport_h: u32) -> Self {
        Self {
            intermediate: None,
            viewport_w,
            viewport_h,
            opened: false,
            pending_composites: Vec::new(),
            clip_stack: Vec::new(),
            blur_bounds: None,
            blur_radius_logical: None,
            used_w: None,
            used_h: None,
            bucket_w: None,
            bucket_h: None,
        }
    }
}

/// One blurred sub-tree result waiting to be composited into a parent
/// target's next render pass. Lives on `ActiveTarget::pending_composites`
/// for the parent target.
struct PendingComposite {
    blurred_texture: crate::blur::AcquiredTexture,
    used_w: u32,
    used_h: u32,
    bucket_w: u32,
    bucket_h: u32,
    bounds: teksilo_canvas::Rect,
}

impl Renderer {
    /// Create a new renderer from an existing wgpu device and queue.
    pub fn new(
        device: wgpu::Device,
        queue: wgpu::Queue,
        surface_format: wgpu::TextureFormat,
    ) -> Self {
        // Read once, here: the atlases grow to a compiled-in ceiling that the
        // device may not be able to honour.
        let device_max_texture_dimension = device.limits().max_texture_dimension_2d;
        let rect_pipeline = create_rect_pipeline(&device, surface_format);
        let sdf_pipeline = create_sdf_pipeline(&device, surface_format);
        let quad_pipeline = create_quad_pipeline(&device, surface_format);
        // Must come after quad_pipeline — reuses its group(0) bind-group
        // layout (texture + sampler) so the path atlas's bind group
        // binds unchanged for both the solid and gradient path batches.
        let path_gradient_pipeline = create_path_gradient_pipeline(
            &device,
            surface_format,
            &quad_pipeline.get_bind_group_layout(0),
        );
        let shadow_pipeline = create_shadow_pipeline(&device, surface_format);
        let (anim_proc_pipeline, anim_uniform_buffer, anim_uniform_bind_group, anim_uniform_layout) =
            create_anim_proc_pipeline(&device, surface_format);
        // Reuse the quad pipeline's texture/sampler layout so bind
        // groups registered by `ImageManager` for static images work
        // equally well as the sprite animation's atlas binding.
        let quad_texture_layout = quad_pipeline.get_bind_group_layout(0);
        let anim_sprite_pipeline = create_anim_sprite_pipeline(
            &device,
            surface_format,
            &anim_uniform_layout,
            &quad_texture_layout,
        );

        let quad_bind_group_layout = quad_pipeline.get_bind_group_layout(0);
        let blur_pool = BlurPool::new(&device, surface_format);
        let blur_pipelines =
            BlurPipelines::new(&device, &blur_pool.bind_group_layout, surface_format);
        let blur_composite_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("blur_composite_sampler"),
            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::Nearest,
            ..Default::default()
        });

        Self {
            device,
            queue,
            max_texture_dimension: device_max_texture_dimension,
            rect_pipeline,
            sdf_pipeline,
            quad_pipeline,
            path_gradient_pipeline,
            shadow_pipeline,
            anim_proc_pipeline,
            anim_sprite_pipeline,
            anim_uniform_buffer,
            anim_uniform_bind_group,
            atlas_texture: None,
            path_atlas: {
                let mut atlas = PathAtlas::new(512, 512);
                atlas.cap_max_size(device_max_texture_dimension);
                atlas
            },
            path_atlas_texture: None,
            image_manager: ImageManager::new(),
            streams: StreamBuffers::new(),
            blur_pipelines,
            blur_pool,
            quad_bind_group_layout,
            blur_composite_sampler,
        }
    }

    /// Upload atlas texture data from the text backend.
    pub fn upload_atlas(&mut self, width: u32, height: u32, pixels: &[u8]) {
        if width == 0 || height == 0 {
            return;
        }
        // The glyph atlas is sized by the text backend, which has its own
        // compiled-in ceiling and no view of this device. Asking wgpu for a
        // texture past `max_texture_dimension_2d` is a validation error, i.e. a
        // crash — on precisely the downlevel hardware least able to report one.
        // Keeping the previous atlas loses newly-rasterized glyphs, which draws
        // as missing text: bad, but legible, and recoverable the moment the
        // backend evicts back under the cap.
        if width > self.max_texture_dimension || height > self.max_texture_dimension {
            eprintln!(
                "teksilo-render: glyph atlas {width}x{height} exceeds this device's \
                 max texture dimension ({}); skipping upload",
                self.max_texture_dimension
            );
            return;
        }

        let needs_recreate = self
            .atlas_texture
            .as_ref()
            .is_none_or(|t| t.width != width || t.height != height);

        if needs_recreate {
            let texture = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some("glyph_atlas"),
                size: wgpu::Extent3d {
                    width,
                    height,
                    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 = texture.create_view(&wgpu::TextureViewDescriptor::default());
            // Linear, not Nearest: glyph quads can be drawn under a scale
            // transform (SceneView zoom, Scale wrapper), where nearest
            // magnification turns texels into hard squares. Glyph origins
            // are fractional (shaping advances, scroll), so linear is NOT
            // automatically a no-op at identity — quads that map 1:1 onto
            // their atlas bitmap are pixel-snapped at vertex emission
            // (`QuadVertex::from_glyph_quad_transformed`), which makes
            // linear sampling exact there; only residually scaled quads
            // (mid-bucket zoom) actually filter. Safe for tinted text —
            // the monochrome shader path ignores sampled RGB — and the
            // 1px atlas gutter bounds bilinear bleed.
            let sampler = self.device.create_sampler(&wgpu::SamplerDescriptor {
                mag_filter: wgpu::FilterMode::Linear,
                min_filter: wgpu::FilterMode::Linear,
                ..Default::default()
            });

            let bind_group_layout = self.quad_pipeline.get_bind_group_layout(0);
            let bind_group = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some("atlas_bind_group"),
                layout: &bind_group_layout,
                entries: &[
                    wgpu::BindGroupEntry {
                        binding: 0,
                        resource: wgpu::BindingResource::TextureView(&view),
                    },
                    wgpu::BindGroupEntry {
                        binding: 1,
                        resource: wgpu::BindingResource::Sampler(&sampler),
                    },
                ],
            });

            self.atlas_texture = Some(AtlasTexture {
                texture,
                bind_group,
                width,
                height,
            });
        }

        if let Some(atlas) = &self.atlas_texture {
            self.queue.write_texture(
                wgpu::TexelCopyTextureInfo {
                    texture: &atlas.texture,
                    mip_level: 0,
                    origin: wgpu::Origin3d::ZERO,
                    aspect: wgpu::TextureAspect::All,
                },
                pixels,
                wgpu::TexelCopyBufferLayout {
                    offset: 0,
                    bytes_per_row: Some(width * 4),
                    rows_per_image: Some(height),
                },
                wgpu::Extent3d {
                    width,
                    height,
                    depth_or_array_layers: 1,
                },
            );
        }
    }

    /// Render a frame to the given surface texture view.
    pub fn render(
        &mut self,
        frame: &RenderFrame,
        view: &wgpu::TextureView,
        scale_factor: f32,
        viewport_width: u32,
        viewport_height: u32,
        clear_color: [f32; 4],
    ) {
        // Begin frame for path atlas LRU tracking
        self.path_atlas.begin_frame();
        // Reset blur intermediate-texture pool — marks every texture
        // available, evicts ones unused for too long.
        self.blur_pool.begin_frame();
        let blur_scopes = frame
            .draw_order
            .iter()
            .filter(|c| matches!(c, teksilo_canvas::DrawCommand::BeginBlurredSubtree { .. }))
            .count();
        self.blur_pipelines.params.begin_frame(
            &self.device,
            u32::try_from(blur_scopes)
                .unwrap_or(u32::MAX)
                .saturating_mul(crate::blur::PARAM_SLOTS_PER_SCOPE),
        );

        // Process pending images: upload textures for newly embedded resources
        for pending in &frame.pending_images {
            if !self.image_manager.contains(&pending.name) {
                let layout = self.quad_pipeline.get_bind_group_layout(0);
                self.image_manager.register_image(
                    &pending.name,
                    pending.width,
                    pending.height,
                    &pending.pixels,
                    &self.device,
                    &self.queue,
                    &layout,
                );
            }
        }

        // Pre-rasterize all paths in this frame into the path atlas. Cosmetic
        // (device-space) strokes must rasterize the body at the view zoom
        // active *where the path is drawn* so the border holds a constant
        // device-pixel width (see PathAtlas::lookup_or_rasterize). Zoom is only
        // known by replaying the transform commands, so we walk `draw_order`
        // with the same SetTransform / PushTransform / PopTransform bookkeeping
        // the main render loop uses and rasterize each path at its effective
        // zoom. `path_placements` is indexed by path index (one Path command per
        // entry). Logical strokes ignore the zoom; a path inside a blurred
        // subtree may get a slightly off zoom estimate (acceptably rare —
        // positioning is unaffected, only raster sharpness).
        let mut path_placements: Vec<Option<crate::path_atlas::PathPlacement>> =
            vec![None; frame.paths.len()];
        {
            let mut ptf_stack: Vec<Transform2D> = vec![Transform2D::IDENTITY];
            let mut ptf_current = Transform2D::IDENTITY;
            let device_t = |t: &Transform2D| Transform2D {
                m: [
                    t.m[0],
                    t.m[1],
                    t.m[2],
                    t.m[3],
                    t.m[4] * scale_factor,
                    t.m[5] * scale_factor,
                ],
            };
            for cmd in &frame.draw_order {
                match cmd {
                    teksilo_canvas::DrawCommand::SetTransform(t) => {
                        let stack_top = ptf_stack.last().copied().unwrap_or(Transform2D::IDENTITY);
                        ptf_current = device_t(t).then(&stack_top);
                    }
                    teksilo_canvas::DrawCommand::PushTransform(t) => {
                        let prev_top = ptf_stack.last().copied().unwrap_or(Transform2D::IDENTITY);
                        let new_top = device_t(t).then(&prev_top);
                        ptf_stack.push(new_top);
                        ptf_current = new_top;
                    }
                    teksilo_canvas::DrawCommand::PopTransform => {
                        if ptf_stack.len() > 1 {
                            ptf_stack.pop();
                        }
                        ptf_current = ptf_stack.last().copied().unwrap_or(Transform2D::IDENTITY);
                    }
                    teksilo_canvas::DrawCommand::Path(idx) => {
                        if let Some(entry) = frame.paths.get(*idx) {
                            // Uniform scale of the linear part = view zoom
                            // (no scale_factor — it lives only in the
                            // translation column, see SetTransform handling).
                            let zoom = ptf_current.m[0].hypot(ptf_current.m[1]);
                            // Snap the quad to whole device pixels only when
                            // nothing else is going to move it. Under the
                            // identity transform (every dock, menu, button
                            // and icon in a normal window — `PushTransform`
                            // is not even emitted for an identity) the mask
                            // can sample 1:1 and stay sharp; under a scale
                            // or a translate animation it cannot, and
                            // rounding would only make the path step between
                            // pixels. See `PathAtlas::lookup_or_rasterize`.
                            let snap = ptf_current == Transform2D::IDENTITY;
                            path_placements[*idx] = self.path_atlas.lookup_or_rasterize(
                                &entry.path,
                                &entry.stroke_style,
                                entry.fill_rule,
                                entry.bounds,
                                scale_factor,
                                zoom,
                                snap,
                            );
                        }
                    }
                    _ => {}
                }
            }
        }

        // Upload path atlas to GPU if dirty
        if self.path_atlas.is_dirty() {
            let (pw, ph) = self.path_atlas.size();
            self.upload_path_atlas(pw, ph, self.path_atlas.pixels().to_vec());
            self.path_atlas.mark_clean();
        }

        // Grow persistent streaming buffers to fit this frame's worst case.
        let counts = stream_quad_counts(frame);
        let StreamQuadCounts {
            rect: rect_quads,
            sdf: sdf_quads,
            quad: quad_quads,
            shadow: shadow_quads,
            anim_proc: anim_proc_quads,
            path_gradient: path_gradient_quads,
        } = counts;
        let max_quads = counts.max();

        self.streams.rect.ensure_capacity(
            &self.device,
            (rect_quads * 4 * std::mem::size_of::<RectVertex>()) as u64,
        );
        self.streams.sdf.ensure_capacity(
            &self.device,
            (sdf_quads * 4 * std::mem::size_of::<SdfVertex>()) as u64,
        );
        self.streams.quad.ensure_capacity(
            &self.device,
            (quad_quads * 4 * std::mem::size_of::<QuadVertex>()) as u64,
        );
        self.streams.shadow.ensure_capacity(
            &self.device,
            (shadow_quads * 4 * std::mem::size_of::<ShadowVertex>()) as u64,
        );
        self.streams.anim_proc.ensure_capacity(
            &self.device,
            (anim_proc_quads * 4 * std::mem::size_of::<AnimQuadVertex>()) as u64,
        );
        self.streams.path_gradient.ensure_capacity(
            &self.device,
            (path_gradient_quads * 4 * std::mem::size_of::<crate::vertex::PathGradientVertex>())
                as u64,
        );
        self.streams.index.ensure_capacity(
            &self.device,
            (max_quads * 6 * std::mem::size_of::<u32>()) as u64,
        );
        self.streams.reset();

        // Upload animated-quad per-slot state for this frame. Truncate
        // past MAX_ANIM_SLOTS — the registry allocates slots without a
        // ceiling and growing the buffer would require recreating
        // the bind group, so we just drop excess slots and warn in
        // debug builds. In practice, 128 is well beyond typical UIs.
        if !frame.anim_params.is_empty() {
            let n = frame.anim_params.len().min(MAX_ANIM_SLOTS);
            debug_assert!(
                frame.anim_params.len() <= MAX_ANIM_SLOTS,
                "AnimParams exceeds MAX_ANIM_SLOTS ({}); tail will be dropped",
                MAX_ANIM_SLOTS
            );
            let bytes: &[u8] = bytemuck::cast_slice(&frame.anim_params[..n]);
            self.queue.write_buffer(&self.anim_uniform_buffer, 0, bytes);
        }

        // Upload the full quad index pattern once — 6 u32s per quad, shared
        // across every quad-based pipeline this frame. u32 indices avoid the
        // u16 vertex-index ceiling (16 384 quads) for large batches.
        let index_data: Vec<u32> = crate::vertex::generate_quad_indices(max_quads);
        let index_binding = self
            .streams
            .index
            .write(&self.queue, bytemuck::cast_slice(&index_data));

        let mut encoder = self
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("teksilo_render"),
            });

        // Per-frame mutable viewport — overridden inside blur scopes
        // (the offscreen intermediate is sized differently from the
        // surface). Restored on `EndBlurredSubtree`.
        let mut viewport_width = viewport_width;
        let mut viewport_height = viewport_height;

        {
            let surface_clear_color = wgpu::Color {
                r: clear_color[0] as f64,
                g: clear_color[1] as f64,
                b: clear_color[2] as f64,
                a: clear_color[3] as f64,
            };

            // Target stack — bottom is the surface (never popped),
            // intermediates pushed on `BeginBlurredSubtree` and popped
            // on `EndBlurredSubtree`. The active target is always
            // `target_stack.last_mut()`. Each target carries:
            //   - opened: false until the first segment runs against
            //     it (controls Clear vs Load on the next open)
            //   - viewport dimensions for NDC conversion in this scope
            //   - pending_composites: blurred quads that nested scopes
            //     have queued for compositing into THIS target on its
            //     next segment
            let mut target_stack: Vec<ActiveTarget> =
                vec![ActiveTarget::surface(viewport_width, viewport_height)];

            // Opacity stack for nested opacity groups
            let mut opacity_stack: Vec<f32> = vec![1.0];
            let mut current_opacity: f32 = 1.0;

            // Blend mode stack
            let mut blend_stack: Vec<teksilo_canvas::BlendMode> = Vec::new();
            let mut current_blend = teksilo_canvas::BlendMode::Normal;
            let _ = current_blend; // used to track state for future pipeline switching

            // Transform stack — applied CPU-side to pixel positions before NDC conversion.
            // The stack tracks subtree-level transforms pushed by the render walker
            // (`PushTransform` / `PopTransform`); `current_transform` is always the
            // top of the stack composed with whatever the most recent `SetTransform`
            // command set within the current scope.
            let mut transform_stack: Vec<Transform2D> = vec![Transform2D::IDENTITY];
            let mut current_transform = Transform2D::IDENTITY;

            // --- Batched rendering ---
            // Accumulate vertices per pipeline, flush on state/pipeline changes.
            // This produces one GPU buffer + one draw call per contiguous batch
            // instead of two buffers per quad.
            let mut rect_batch: Vec<RectVertex> = Vec::new();
            let mut sdf_batch: Vec<SdfVertex> = Vec::new();
            let mut quad_batch: Vec<QuadVertex> = Vec::new();
            let mut shadow_batch: Vec<ShadowVertex> = Vec::new();
            let mut anim_proc_batch: Vec<AnimQuadVertex> = Vec::new();
            let mut path_gradient_batch: Vec<crate::vertex::PathGradientVertex> = Vec::new();

            // Which pipeline the current quad batch uses (glyph atlas or path atlas;
            // images draw individually with their own bind group).
            // Flushed when the bind group source changes.
            #[derive(Clone, Copy, PartialEq, Eq)]
            enum QuadSource {
                GlyphAtlas,
                PathAtlas,
            }
            let mut quad_source: Option<QuadSource> = None;

            // Flush helpers — each writes one batch into the persistent
            // stream buffer and issues one draw call. The index buffer was
            // written once at the top of `render()` and is shared.
            //
            // `$index_binding` is `Option<(&Buffer, u64 offset, u64 len)>`
            // — `None` only if the frame had zero quads, in which case
            // every batch is also empty and the flush is a no-op anyway.
            macro_rules! flush_stream {
                ($pass:expr, $queue:expr, $stream:expr, $pipeline:expr,
                 $batch:expr, $index_binding:expr) => {
                    if !$batch.is_empty() {
                        let bytes: &[u8] = bytemuck::cast_slice(&$batch);
                        if let (Some((vb, v_off, v_len)), Some((ib, _, _))) =
                            ($stream.write($queue, bytes), $index_binding)
                        {
                            let quads = ($batch.len() / 4) as u32;
                            let index_count = quads * 6;
                            let index_bytes = (index_count as u64) * 4;
                            $pass.set_pipeline($pipeline);
                            $pass.set_vertex_buffer(0, vb.slice(v_off..v_off + v_len));
                            $pass.set_index_buffer(
                                ib.slice(0..index_bytes),
                                wgpu::IndexFormat::Uint32,
                            );
                            $pass.draw_indexed(0..index_count, 0, 0..1);
                        }
                        $batch.clear();
                    }
                };
            }

            // Flush all pending batches (called on state changes).
            macro_rules! flush_all {
                ($pass:expr, $queue:expr, $streams:expr,
                 $rp:expr, $sp:expr, $qp:expr, $pgp:expr, $shp:expr,
                 $rb:expr, $sb:expr, $qb:expr, $pgb:expr, $shb:expr,
                 $atlas:expr, $path_atlas:expr, $qs:expr, $index_binding:expr) => {
                    flush_stream!($pass, $queue, &$streams.rect, $rp, $rb, $index_binding);
                    flush_stream!($pass, $queue, &$streams.sdf, $sp, $sb, $index_binding);
                    // Quad batch needs bind group
                    if !$qb.is_empty() {
                        let bg = match $qs {
                            Some(QuadSource::PathAtlas) => {
                                $path_atlas.as_ref().map(|a: &AtlasTexture| &a.bind_group)
                            }
                            _ => $atlas.as_ref().map(|a: &AtlasTexture| &a.bind_group),
                        };
                        if let (Some(bind_group), Some((ib, _, _))) = (bg, $index_binding) {
                            let bytes: &[u8] = bytemuck::cast_slice(&$qb);
                            if let Some((vb, v_off, v_len)) = $streams.quad.write($queue, bytes) {
                                let quads = ($qb.len() / 4) as u32;
                                let index_count = quads * 6;
                                let index_bytes = (index_count as u64) * 4;
                                $pass.set_pipeline($qp);
                                $pass.set_bind_group(0, bind_group, &[]);
                                $pass.set_vertex_buffer(0, vb.slice(v_off..v_off + v_len));
                                $pass.set_index_buffer(
                                    ib.slice(0..index_bytes),
                                    wgpu::IndexFormat::Uint32,
                                );
                                $pass.draw_indexed(0..index_count, 0, 0..1);
                            }
                        }
                        $qb.clear();
                    }
                    // Gradient-filled path batch. Binds the SAME path
                    // atlas texture bind group the solid path-quad batch
                    // above uses (`$path_atlas`) — the gradient pipeline
                    // reuses `quad_pipeline`'s group(0) layout, so the
                    // bind group is interchangeable.
                    if !$pgb.is_empty() {
                        if let (Some(bind_group), Some((ib, _, _))) = (
                            $path_atlas.as_ref().map(|a: &AtlasTexture| &a.bind_group),
                            $index_binding,
                        ) {
                            let bytes: &[u8] = bytemuck::cast_slice(&$pgb);
                            if let Some((vb, v_off, v_len)) =
                                $streams.path_gradient.write($queue, bytes)
                            {
                                let quads = ($pgb.len() / 4) as u32;
                                let index_count = quads * 6;
                                let index_bytes = (index_count as u64) * 4;
                                $pass.set_pipeline($pgp);
                                $pass.set_bind_group(0, bind_group, &[]);
                                $pass.set_vertex_buffer(0, vb.slice(v_off..v_off + v_len));
                                $pass.set_index_buffer(
                                    ib.slice(0..index_bytes),
                                    wgpu::IndexFormat::Uint32,
                                );
                                $pass.draw_indexed(0..index_count, 0, 0..1);
                            }
                        }
                        $pgb.clear();
                    }
                    flush_stream!($pass, $queue, &$streams.shadow, $shp, $shb, $index_binding);
                    // Animated-quad procedural batch. Unlike the shared
                    // atlas quad pipeline above, this always binds the
                    // same uniform bind group (per-slot state read by
                    // shader) so there's no source-switching. Accesses
                    // `self.anim_proc_pipeline` / `.anim_uniform_bind_group`
                    // and the local `anim_proc_batch` via macro hygiene —
                    // all three are in scope inside `render()` at every
                    // flush_all! call site.
                    if !anim_proc_batch.is_empty()
                        && let Some((ib, _, _)) = $index_binding
                    {
                        let bytes: &[u8] = bytemuck::cast_slice(&anim_proc_batch);
                        if let Some((vb, v_off, v_len)) = $streams.anim_proc.write($queue, bytes) {
                            let quads = (anim_proc_batch.len() / 4) as u32;
                            let index_count = quads * 6;
                            let index_bytes = (index_count as u64) * 4;
                            $pass.set_pipeline(&self.anim_proc_pipeline);
                            $pass.set_bind_group(0, &self.anim_uniform_bind_group, &[]);
                            $pass.set_vertex_buffer(0, vb.slice(v_off..v_off + v_len));
                            $pass.set_index_buffer(
                                ib.slice(0..index_bytes),
                                wgpu::IndexFormat::Uint32,
                            );
                            $pass.draw_indexed(0..index_count, 0, 0..1);
                        }
                        anim_proc_batch.clear();
                    }
                };
            }

            // Draw in painter's order. Outer loop iterates render
            // segments — one segment per `RenderPass`. A blur Begin/End
            // boundary opens a new segment. The pass lives in its own
            // scope so the encoder borrow is released at each boundary
            // (allowing the next pass open or any in-between Kawase
            // work on the encoder).
            let mut cmd_idx = 0;
            while cmd_idx <= frame.draw_order.len() {
                // Resolve current target. We `match` the intermediate
                // handle vs. surface here; the resulting `target_view`
                // lifetime ties to one of self.blur_pool / `view` arg.
                let (target_view, load_op): (&wgpu::TextureView, wgpu::LoadOp<wgpu::Color>) = {
                    let t = target_stack
                        .last_mut()
                        .expect("surface target always present");
                    let v: &wgpu::TextureView = match t.intermediate {
                        Some(h) => self.blur_pool.view(h),
                        None => view,
                    };
                    let lo = if t.opened {
                        wgpu::LoadOp::Load
                    } else if t.intermediate.is_none() {
                        wgpu::LoadOp::Clear(surface_clear_color)
                    } else {
                        wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT)
                    };
                    t.opened = true;
                    viewport_width = t.viewport_w;
                    viewport_height = t.viewport_h;
                    (v, lo)
                };

                // Drain pending composites — these are blurred sub-tree
                // results from nested blur scopes that finished while
                // we weren't drawing into THIS target. They paint first
                // in the new segment so subsequent commands stack on
                // top of the blurred quad.
                let composites_to_draw: Vec<PendingComposite> = std::mem::take(
                    &mut target_stack
                        .last_mut()
                        .expect("target_stack always has the surface target")
                        .pending_composites,
                );

                {
                    let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                        label: Some("teksilo_segment_pass"),
                        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                            view: target_view,
                            resolve_target: None,
                            ops: wgpu::Operations {
                                load: load_op,
                                store: wgpu::StoreOp::Store,
                            },
                            depth_slice: None,
                        })],
                        depth_stencil_attachment: None,
                        timestamp_writes: None,
                        occlusion_query_set: None,
                        multiview_mask: None,
                    });

                    // A new pass starts unscissored. Re-apply this
                    // target's open clip, which a blur boundary may have
                    // interrupted, before anything draws, the composites
                    // included: they belong to the clip they were opened
                    // under.
                    if let Some(&[x, y, w, h]) = target_stack
                        .last()
                        .expect("target_stack always has the surface target")
                        .clip_stack
                        .last()
                    {
                        pass.set_scissor_rect(x, y, w, h);
                    }

                    // Composite pending blurred sub-trees first.
                    for pc in &composites_to_draw {
                        composite_blur_quad(
                            &self.device,
                            &self.queue,
                            &mut pass,
                            &self.blur_pool,
                            &self.quad_pipeline,
                            &self.quad_bind_group_layout,
                            &self.blur_composite_sampler,
                            &self.streams.quad,
                            index_binding,
                            pc.blurred_texture,
                            pc.used_w,
                            pc.used_h,
                            pc.bucket_w,
                            pc.bucket_h,
                            pc.bounds,
                            scale_factor,
                            viewport_width,
                            viewport_height,
                        );
                        // The composite uses the quad pipeline with a
                        // fresh bind group → invalidate any cached
                        // glyph/path-atlas binding for the next quad
                        // batch.
                        quad_source = None;
                    }

                    let pass = &mut pass;

                    // Inner loop: process commands until we hit a blur
                    // boundary or run out.
                    while cmd_idx < frame.draw_order.len() {
                        let cmd = &frame.draw_order[cmd_idx];
                        if matches!(
                            cmd,
                            teksilo_canvas::DrawCommand::BeginBlurredSubtree { .. }
                                | teksilo_canvas::DrawCommand::EndBlurredSubtree
                        ) {
                            break;
                        }
                        match cmd {
                            teksilo_canvas::DrawCommand::Decoration(idx) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                let Some(rect) = frame.decorations.get(*idx) else {
                                    continue;
                                };
                                let verts = RectVertex::from_decoration(rect, scale_factor);
                                for v in &verts {
                                    let tp = apply_transform_pixel(v.position, &current_transform);
                                    rect_batch.push(RectVertex {
                                        position: pixel_to_ndc(tp, viewport_width, viewport_height),
                                        color: [
                                            v.color[0],
                                            v.color[1],
                                            v.color[2],
                                            v.color[3] * current_opacity,
                                        ],
                                    });
                                }
                            }
                            teksilo_canvas::DrawCommand::CosmeticLine(idx) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                let Some(line) = frame.cosmetic_lines.get(*idx) else {
                                    continue;
                                };
                                // Transform the endpoints (premultiplied by the
                                // HiDPI scale_factor) through the active
                                // transform, then apply a device-pixel thickness
                                // that does NOT scale with the transform's zoom.
                                let p0 = apply_transform_pixel(
                                    [line.from[0] * scale_factor, line.from[1] * scale_factor],
                                    &current_transform,
                                );
                                let p1 = apply_transform_pixel(
                                    [line.to[0] * scale_factor, line.to[1] * scale_factor],
                                    &current_transform,
                                );
                                let thickness = (line.width * scale_factor).max(1.0);
                                let half = thickness * 0.5;
                                let dx = p1[0] - p0[0];
                                let dy = p1[1] - p0[1];
                                let len = (dx * dx + dy * dy).sqrt();
                                if len < 1e-3 {
                                    continue;
                                }
                                // Perpendicular unit normal in device space.
                                let nx = -dy / len;
                                let ny = dx / len;
                                // Pixel-snap axis-aligned lines (edge-aligned
                                // center) for crispness; leave diagonals as-is.
                                let (mut a0, mut a1) = (p0, p1);
                                if dy.abs() < 0.5 {
                                    let cy = ((p0[1] + p1[1]) * 0.5 - half).round() + half;
                                    a0 = [p0[0], cy];
                                    a1 = [p1[0], cy];
                                } else if dx.abs() < 0.5 {
                                    let cx = ((p0[0] + p1[0]) * 0.5 - half).round() + half;
                                    a0 = [cx, p0[1]];
                                    a1 = [cx, p1[1]];
                                }
                                let lin = crate::vertex::srgb_to_linear_rgba(line.color);
                                let color = [lin[0], lin[1], lin[2], lin[3] * current_opacity];
                                let corners = [
                                    [a0[0] + nx * half, a0[1] + ny * half],
                                    [a1[0] + nx * half, a1[1] + ny * half],
                                    [a1[0] - nx * half, a1[1] - ny * half],
                                    [a0[0] - nx * half, a0[1] - ny * half],
                                ];
                                for pos in corners {
                                    rect_batch.push(RectVertex {
                                        position: pixel_to_ndc(
                                            pos,
                                            viewport_width,
                                            viewport_height,
                                        ),
                                        color,
                                    });
                                }
                            }
                            teksilo_canvas::DrawCommand::Shape(idx) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                let Some(shape) = frame.shapes.get(*idx) else {
                                    continue;
                                };
                                // Cosmetic (device-space) borders hold a
                                // constant device-pixel width under zoom: the
                                // body still scales via `current_transform`, but
                                // the SDF stroke param is divided by the active
                                // zoom (the uniform scale of the linear part,
                                // which carries no scale_factor — see
                                // SetTransform). Fills + logical strokes are
                                // unchanged.
                                let verts = if shape.stroke_space
                                    == teksilo_canvas::StrokeSpace::Device
                                    && shape.stroke_width > 0.0
                                {
                                    // Uniform scale of the linear part = view
                                    // zoom (no scale_factor — it lives only in
                                    // the translation column). `from_shape_quad_cosmetic`
                                    // applies the divide-by-zero floor.
                                    let zoom = current_transform.m[0].hypot(current_transform.m[1]);
                                    SdfVertex::from_shape_quad_cosmetic(shape, scale_factor, zoom)
                                } else {
                                    SdfVertex::from_shape_quad(shape, scale_factor)
                                };
                                for v in &verts {
                                    let tp = apply_transform_pixel(v.position, &current_transform);
                                    sdf_batch.push(SdfVertex {
                                        position: pixel_to_ndc(tp, viewport_width, viewport_height),
                                        color: [
                                            v.color[0],
                                            v.color[1],
                                            v.color[2],
                                            v.color[3] * current_opacity,
                                        ],
                                        ..*v
                                    });
                                }
                            }
                            teksilo_canvas::DrawCommand::Glyph(idx) => {
                                // Only flush when the quad source changes — consecutive
                                // glyphs batch into one draw call.
                                if quad_source != Some(QuadSource::GlyphAtlas) {
                                    flush_all!(
                                        pass,
                                        &self.queue,
                                        self.streams,
                                        &self.rect_pipeline,
                                        &self.sdf_pipeline,
                                        &self.quad_pipeline,
                                        &self.path_gradient_pipeline,
                                        &self.shadow_pipeline,
                                        rect_batch,
                                        sdf_batch,
                                        quad_batch,
                                        path_gradient_batch,
                                        shadow_batch,
                                        self.atlas_texture,
                                        self.path_atlas_texture,
                                        quad_source,
                                        index_binding
                                    );
                                    quad_source = Some(QuadSource::GlyphAtlas);
                                }
                                if let Some(atlas) = &self.atlas_texture {
                                    let Some(glyph) = frame.glyphs.get(*idx) else {
                                        continue;
                                    };
                                    // Transform is applied (and 1:1 quads
                                    // pixel-snapped) inside the constructor.
                                    let verts = QuadVertex::from_glyph_quad_transformed(
                                        glyph,
                                        scale_factor,
                                        atlas.width,
                                        atlas.height,
                                        &current_transform,
                                    );
                                    for v in &verts {
                                        quad_batch.push(QuadVertex {
                                            position: pixel_to_ndc(
                                                v.position,
                                                viewport_width,
                                                viewport_height,
                                            ),
                                            color: [
                                                v.color[0],
                                                v.color[1],
                                                v.color[2],
                                                v.color[3] * current_opacity,
                                            ],
                                            ..*v
                                        });
                                    }
                                }
                            }
                            teksilo_canvas::DrawCommand::Shadow(idx) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                let Some(shadow) = frame.shadows.get(*idx) else {
                                    continue;
                                };
                                let verts = ShadowVertex::from_shadow_quad(shadow, scale_factor);
                                for v in &verts {
                                    let tp = apply_transform_pixel(v.position, &current_transform);
                                    shadow_batch.push(ShadowVertex {
                                        position: pixel_to_ndc(tp, viewport_width, viewport_height),
                                        shadow_color: [
                                            v.shadow_color[0],
                                            v.shadow_color[1],
                                            v.shadow_color[2],
                                            v.shadow_color[3] * current_opacity,
                                        ],
                                        ..*v
                                    });
                                }
                            }
                            teksilo_canvas::DrawCommand::Image(idx) => {
                                // Images use per-image bind groups — flush and draw individually
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                let Some(image) = frame.images.get(*idx) else {
                                    continue;
                                };
                                self.draw_image(
                                    pass,
                                    image,
                                    scale_factor,
                                    viewport_width,
                                    viewport_height,
                                    current_opacity,
                                    &current_transform,
                                    index_binding,
                                );
                            }
                            teksilo_canvas::DrawCommand::Path(idx) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                if let Some(Some(placement)) = path_placements.get(*idx) {
                                    let Some(entry) = frame.paths.get(*idx) else {
                                        continue;
                                    };
                                    let Some(path_atlas) = self.path_atlas_texture.as_ref() else {
                                        continue;
                                    };
                                    if matches!(entry.paint_data, teksilo_canvas::PaintData::Solid)
                                    {
                                        // Solid fill or solid stroke: the lean
                                        // quad_pipeline, tinted by entry.color.
                                        // (A gradient *stroke* takes the branch
                                        // below — the pipeline choice follows the
                                        // paint, not fill-vs-stroke; the coverage
                                        // mask in the atlas is already whichever
                                        // one this entry rasterized.)
                                        quad_source = Some(QuadSource::PathAtlas);
                                        let verts = path_quad_verts(
                                            entry,
                                            placement,
                                            path_atlas.width,
                                            path_atlas.height,
                                            current_opacity,
                                            &current_transform,
                                        );
                                        for v in &verts {
                                            quad_batch.push(QuadVertex {
                                                position: pixel_to_ndc(
                                                    v.position,
                                                    viewport_width,
                                                    viewport_height,
                                                ),
                                                ..*v
                                            });
                                        }
                                    } else {
                                        // Gradient fill: the dedicated
                                        // path_gradient pipeline, which
                                        // samples the SAME atlas coverage
                                        // mask but computes an analytic
                                        // gradient color instead of a flat
                                        // tint.
                                        let verts = path_gradient_quad_verts(
                                            entry,
                                            placement,
                                            scale_factor,
                                            path_atlas.width,
                                            path_atlas.height,
                                            current_opacity,
                                            &current_transform,
                                        );
                                        for v in &verts {
                                            path_gradient_batch.push(
                                                crate::vertex::PathGradientVertex {
                                                    position: pixel_to_ndc(
                                                        v.position,
                                                        viewport_width,
                                                        viewport_height,
                                                    ),
                                                    ..*v
                                                },
                                            );
                                        }
                                    }
                                }
                            }
                            // --- State changes flush all batches ---
                            teksilo_canvas::DrawCommand::SetClip(rect) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                // Apply the current transform stack to the
                                // clip rect. Without this, a clip emitted
                                // inside a SceneView's view-transform scope
                                // (e.g. ScrollArea or nested SceneView as
                                // a heavyweight scene_rect widget) would
                                // mask the rendered content to the rect's
                                // PRE-transform position — the contents
                                // visually pan/zoom with the outer view but
                                // the clip mask stays fixed in screen
                                // space, "eating" the widget as the user
                                // pans or zooms out.
                                //
                                // Rotation-free transforms (the common case
                                // for SceneView pan + zoom) produce an
                                // axis-aligned transformed rect; for rotated
                                // transforms we take the AABB of the four
                                // corners, which over-clips slightly but
                                // remains correct for visibility.
                                //
                                // `current_transform` maps device pixels
                                // (its translation is already scaled), as
                                // for vertices: scale the rect first, then
                                // transform. Transforming the logical rect
                                // and scaling afterwards would scale the
                                // translation twice.
                                let device = |x: f32, y: f32| {
                                    apply_transform_pixel(
                                        [x * scale_factor, y * scale_factor],
                                        &current_transform,
                                    )
                                };
                                let p_tl = device(rect.x, rect.y);
                                let p_tr = device(rect.x + rect.width, rect.y);
                                let p_bl = device(rect.x, rect.y + rect.height);
                                let p_br = device(rect.x + rect.width, rect.y + rect.height);
                                let min_x = p_tl[0].min(p_tr[0]).min(p_bl[0]).min(p_br[0]);
                                let min_y = p_tl[1].min(p_tr[1]).min(p_bl[1]).min(p_br[1]);
                                let max_x = p_tl[0].max(p_tr[0]).max(p_bl[0]).max(p_br[0]);
                                let max_y = p_tl[1].max(p_tr[1]).max(p_bl[1]).max(p_br[1]);
                                let x = min_x.max(0.0) as u32;
                                let y = min_y.max(0.0) as u32;
                                let w = (max_x - min_x).ceil().max(0.0) as u32;
                                let h = (max_y - min_y).ceil().max(0.0) as u32;
                                // Clamp to viewport — wgpu requires x+w <= width, y+h <= height.
                                let x = x.min(viewport_width);
                                let y = y.min(viewport_height);
                                let w = w.min(viewport_width.saturating_sub(x));
                                let h = h.min(viewport_height.saturating_sub(y));
                                let clip_stack = &mut target_stack
                                    .last_mut()
                                    .expect("target_stack always has the surface target")
                                    .clip_stack;
                                let clipped = if let Some(&[cx, cy, cw, ch]) = clip_stack.last() {
                                    let ix = x.max(cx);
                                    let iy = y.max(cy);
                                    let ir = (x + w).min(cx + cw);
                                    let ib = (y + h).min(cy + ch);
                                    [ix, iy, ir.saturating_sub(ix), ib.saturating_sub(iy)]
                                } else {
                                    [x, y, w, h]
                                };
                                clip_stack.push(clipped);
                                pass.set_scissor_rect(
                                    clipped[0], clipped[1], clipped[2], clipped[3],
                                );
                            }
                            teksilo_canvas::DrawCommand::ClearClip => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                let clip_stack = &mut target_stack
                                    .last_mut()
                                    .expect("target_stack always has the surface target")
                                    .clip_stack;
                                clip_stack.pop();
                                if let Some(&[x, y, w, h]) = clip_stack.last() {
                                    pass.set_scissor_rect(x, y, w, h);
                                } else {
                                    pass.set_scissor_rect(0, 0, viewport_width, viewport_height);
                                }
                            }
                            teksilo_canvas::DrawCommand::SetOpacity(opacity) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                opacity_stack.push(current_opacity);
                                current_opacity *= opacity;
                            }
                            teksilo_canvas::DrawCommand::RestoreOpacity => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                current_opacity = opacity_stack.pop().unwrap_or(1.0);
                            }
                            teksilo_canvas::DrawCommand::Rasterized(_) => {}
                            teksilo_canvas::DrawCommand::AnimatedQuad(idx) => {
                                let Some(draw) = frame.animated_quads.get(*idx) else {
                                    continue;
                                };
                                // Flush every other pipeline first so painter's
                                // order is preserved across pipeline boundaries.
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                match &draw.class {
                                    teksilo_canvas::AnimatedQuadClass::Procedural => {
                                        let verts =
                                            AnimQuadVertex::from_animated_quad(draw, scale_factor);
                                        for v in &verts {
                                            let tp = apply_transform_pixel(
                                                v.position,
                                                &current_transform,
                                            );
                                            anim_proc_batch.push(AnimQuadVertex {
                                                position: pixel_to_ndc(
                                                    tp,
                                                    viewport_width,
                                                    viewport_height,
                                                ),
                                                uv: v.uv,
                                                slot: v.slot,
                                                _pad: v._pad,
                                            });
                                        }
                                    }
                                    teksilo_canvas::AnimatedQuadClass::Sprite { image_name } => {
                                        // Sprite quads need a per-atlas bind
                                        // group, so each draws individually —
                                        // same shape as the static Image path.
                                        // Typical scene has ~1 animated sprite
                                        // icon at a time, so batching is moot.
                                        let Some(atlas_bg) =
                                            self.image_manager.get_bind_group(image_name)
                                        else {
                                            continue;
                                        };
                                        let verts =
                                            AnimQuadVertex::from_animated_quad(draw, scale_factor);
                                        let mut ndc_verts = [AnimQuadVertex {
                                            position: [0.0; 2],
                                            uv: [0.0; 2],
                                            slot: 0,
                                            _pad: 0,
                                        };
                                            4];
                                        for (i, v) in verts.iter().enumerate() {
                                            let tp = apply_transform_pixel(
                                                v.position,
                                                &current_transform,
                                            );
                                            ndc_verts[i] = AnimQuadVertex {
                                                position: pixel_to_ndc(
                                                    tp,
                                                    viewport_width,
                                                    viewport_height,
                                                ),
                                                uv: v.uv,
                                                slot: v.slot,
                                                _pad: v._pad,
                                            };
                                        }
                                        let bytes: &[u8] = bytemuck::cast_slice(&ndc_verts);
                                        if let (Some((vb, v_off, v_len)), Some((ib, _, _))) = (
                                            self.streams.anim_proc.write(&self.queue, bytes),
                                            index_binding,
                                        ) {
                                            let index_bytes: u64 = 6 * 4;
                                            pass.set_pipeline(&self.anim_sprite_pipeline);
                                            pass.set_bind_group(
                                                0,
                                                &self.anim_uniform_bind_group,
                                                &[],
                                            );
                                            pass.set_bind_group(1, atlas_bg, &[]);
                                            pass.set_vertex_buffer(
                                                0,
                                                vb.slice(v_off..v_off + v_len),
                                            );
                                            pass.set_index_buffer(
                                                ib.slice(0..index_bytes),
                                                wgpu::IndexFormat::Uint32,
                                            );
                                            pass.draw_indexed(0..6, 0, 0..1);
                                        }
                                    }
                                }
                            }
                            teksilo_canvas::DrawCommand::SetBlendMode(mode) => {
                                blend_stack.push(current_blend);
                                current_blend = *mode;
                            }
                            teksilo_canvas::DrawCommand::RestoreBlendMode => {
                                current_blend = blend_stack
                                    .pop()
                                    .unwrap_or(teksilo_canvas::BlendMode::Normal);
                            }
                            teksilo_canvas::DrawCommand::SetTransform(t) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                // Widgets author transforms in logical pixels, but
                                // vertices arrive pre-multiplied by scale_factor (HiDPI
                                // device pixels). Scale the translation column so the
                                // pivot lands at the same physical point in either
                                // coordinate space.
                                let device_t = Transform2D {
                                    m: [
                                        t.m[0],
                                        t.m[1],
                                        t.m[2],
                                        t.m[3],
                                        t.m[4] * scale_factor,
                                        t.m[5] * scale_factor,
                                    ],
                                };
                                // Compose with the current transform-stack top so a
                                // widget's canvas-local transform respects any wrapper
                                // transform pushed by the render walker. With an
                                // identity stack top this is identical to the old
                                // "absolute" semantics — backwards compatible for any
                                // widget not under a transform scope.
                                let stack_top = transform_stack
                                    .last()
                                    .copied()
                                    .unwrap_or(Transform2D::IDENTITY);
                                current_transform = device_t.then(&stack_top);
                            }
                            teksilo_canvas::DrawCommand::PushTransform(t) => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                // See SetTransform: scale the translation column to
                                // device pixels before composing.
                                let device_t = Transform2D {
                                    m: [
                                        t.m[0],
                                        t.m[1],
                                        t.m[2],
                                        t.m[3],
                                        t.m[4] * scale_factor,
                                        t.m[5] * scale_factor,
                                    ],
                                };
                                let prev_top = transform_stack
                                    .last()
                                    .copied()
                                    .unwrap_or(Transform2D::IDENTITY);
                                let new_top = device_t.then(&prev_top);
                                transform_stack.push(new_top);
                                current_transform = new_top;
                            }
                            teksilo_canvas::DrawCommand::PopTransform => {
                                flush_all!(
                                    pass,
                                    &self.queue,
                                    self.streams,
                                    &self.rect_pipeline,
                                    &self.sdf_pipeline,
                                    &self.quad_pipeline,
                                    &self.path_gradient_pipeline,
                                    &self.shadow_pipeline,
                                    rect_batch,
                                    sdf_batch,
                                    quad_batch,
                                    path_gradient_batch,
                                    shadow_batch,
                                    self.atlas_texture,
                                    self.path_atlas_texture,
                                    quad_source,
                                    index_binding
                                );
                                quad_source = None;
                                if transform_stack.len() > 1 {
                                    transform_stack.pop();
                                }
                                current_transform = transform_stack
                                    .last()
                                    .copied()
                                    .unwrap_or(Transform2D::IDENTITY);
                            }
                            teksilo_canvas::DrawCommand::BeginBlurredSubtree { .. }
                            | teksilo_canvas::DrawCommand::EndBlurredSubtree => {
                                // Unreachable — the inner-loop guard above
                                // breaks before we enter the match for these.
                                unreachable!("blur boundaries are handled at the segment level");
                            }
                        }
                        cmd_idx += 1;
                    }

                    // End-of-segment flush.
                    flush_all!(
                        pass,
                        &self.queue,
                        self.streams,
                        &self.rect_pipeline,
                        &self.sdf_pipeline,
                        &self.quad_pipeline,
                        &self.path_gradient_pipeline,
                        &self.shadow_pipeline,
                        rect_batch,
                        sdf_batch,
                        quad_batch,
                        path_gradient_batch,
                        shadow_batch,
                        self.atlas_texture,
                        self.path_atlas_texture,
                        quad_source,
                        index_binding
                    );
                    quad_source = None;
                } // pass dropped here, encoder borrow released

                // Boundary handling. EOF, Begin, or End.
                if cmd_idx >= frame.draw_order.len() {
                    break;
                }
                match &frame.draw_order[cmd_idx] {
                    teksilo_canvas::DrawCommand::BeginBlurredSubtree { bounds, radius } => {
                        // Allocate intermediate sized to bounds × scale.
                        let device_w = (bounds.width * scale_factor).ceil().max(1.0) as u32;
                        let device_h = (bounds.height * scale_factor).ceil().max(1.0) as u32;
                        let intermediate = self.blur_pool.acquire(&self.device, device_w, device_h);
                        let (bucket_w, bucket_h) = self.blur_pool.dimensions(intermediate);

                        // Push a translation so the subtree renders at
                        // (0, 0) of the intermediate. Device-pixel
                        // translation since vertices arrive pre-scaled
                        // (see SetTransform handler for the same trick).
                        let translate = Transform2D {
                            m: [
                                1.0,
                                0.0,
                                0.0,
                                1.0,
                                -bounds.x * scale_factor,
                                -bounds.y * scale_factor,
                            ],
                        };
                        let prev_top = transform_stack
                            .last()
                            .copied()
                            .unwrap_or(Transform2D::IDENTITY);
                        let new_top = translate.then(&prev_top);
                        transform_stack.push(new_top);
                        current_transform = new_top;

                        target_stack.push(ActiveTarget {
                            intermediate: Some(intermediate),
                            viewport_w: bucket_w,
                            viewport_h: bucket_h,
                            opened: false,
                            pending_composites: Vec::new(),
                            clip_stack: Vec::new(),
                            blur_bounds: Some(*bounds),
                            blur_radius_logical: Some(*radius),
                            used_w: Some(device_w),
                            used_h: Some(device_h),
                            bucket_w: Some(bucket_w),
                            bucket_h: Some(bucket_h),
                        });
                    }
                    teksilo_canvas::DrawCommand::EndBlurredSubtree => {
                        let scope = target_stack
                            .pop()
                            .expect("EndBlurredSubtree without matching Begin");
                        debug_assert!(
                            scope.intermediate.is_some(),
                            "End popped the surface (impossible if walker is balanced)"
                        );
                        let intermediate = scope
                            .intermediate
                            .expect("blur scope intermediate set in BeginBlurredSubtree");
                        let bounds = scope
                            .blur_bounds
                            .expect("blur scope bounds set in BeginBlurredSubtree");
                        let radius = scope
                            .blur_radius_logical
                            .expect("blur scope radius set in BeginBlurredSubtree");
                        let used_w = scope
                            .used_w
                            .expect("blur scope used_w set in BeginBlurredSubtree");
                        let used_h = scope
                            .used_h
                            .expect("blur scope used_h set in BeginBlurredSubtree");
                        let bucket_w = scope
                            .bucket_w
                            .expect("blur scope bucket_w set in BeginBlurredSubtree");
                        let bucket_h = scope
                            .bucket_h
                            .expect("blur scope bucket_h set in BeginBlurredSubtree");

                        // Pop the translation pushed in Begin.
                        if transform_stack.len() > 1 {
                            transform_stack.pop();
                        }
                        current_transform = transform_stack
                            .last()
                            .copied()
                            .unwrap_or(Transform2D::IDENTITY);

                        // Run dual-Kawase. The chain begins its own
                        // sub-passes against pool textures — the outer
                        // segment's pass is already dropped.
                        let blurred = run_kawase_chain(
                            &self.device,
                            &self.queue,
                            &mut encoder,
                            &mut self.blur_pool,
                            &mut self.blur_pipelines,
                            intermediate,
                            used_w,
                            used_h,
                            bucket_w,
                            bucket_h,
                            radius * scale_factor,
                        );

                        // Schedule a composite into the parent target's
                        // next segment open.
                        target_stack
                            .last_mut()
                            .expect("target_stack always has the surface target")
                            .pending_composites
                            .push(PendingComposite {
                                blurred_texture: blurred.texture,
                                used_w: blurred.used_w,
                                used_h: blurred.used_h,
                                bucket_w: blurred.bucket_w,
                                bucket_h: blurred.bucket_h,
                                bounds,
                            });
                    }
                    _ => unreachable!("inner loop only breaks on Begin/End"),
                }
                cmd_idx += 1;
            }

            debug_assert!(
                target_stack.len() == 1,
                "target_stack not balanced at EOF — unmatched Begin/End in walker output"
            );
            // The remaining surface target may still have a pending
            // composite (an outermost blur scope ending at end-of-frame
            // with no further commands). Drain it in one final pass.
            let final_composites = std::mem::take(
                &mut target_stack
                    .last_mut()
                    .expect("target_stack always has the surface target")
                    .pending_composites,
            );
            if !final_composites.is_empty() {
                let surface = target_stack
                    .last_mut()
                    .expect("target_stack always has the surface target");
                let load_op = if surface.opened {
                    wgpu::LoadOp::Load
                } else {
                    wgpu::LoadOp::Clear(surface_clear_color)
                };
                surface.opened = true;
                let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                    label: Some("teksilo_final_composite_pass"),
                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                        view,
                        resolve_target: None,
                        ops: wgpu::Operations {
                            load: load_op,
                            store: wgpu::StoreOp::Store,
                        },
                        depth_slice: None,
                    })],
                    depth_stencil_attachment: None,
                    timestamp_writes: None,
                    occlusion_query_set: None,
                    multiview_mask: None,
                });
                for pc in &final_composites {
                    composite_blur_quad(
                        &self.device,
                        &self.queue,
                        &mut pass,
                        &self.blur_pool,
                        &self.quad_pipeline,
                        &self.quad_bind_group_layout,
                        &self.blur_composite_sampler,
                        &self.streams.quad,
                        index_binding,
                        pc.blurred_texture,
                        pc.used_w,
                        pc.used_h,
                        pc.bucket_w,
                        pc.bucket_h,
                        pc.bounds,
                        scale_factor,
                        viewport_width,
                        viewport_height,
                    );
                }
            } else if !target_stack
                .last()
                .expect("target_stack always has the surface target")
                .opened
            {
                // Empty frame — open one pass to apply the clear.
                let _ = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                    label: Some("teksilo_empty_clear_pass"),
                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                        view,
                        resolve_target: None,
                        ops: wgpu::Operations {
                            load: wgpu::LoadOp::Clear(surface_clear_color),
                            store: wgpu::StoreOp::Store,
                        },
                        depth_slice: None,
                    })],
                    depth_stencil_attachment: None,
                    timestamp_writes: None,
                    occlusion_query_set: None,
                    multiview_mask: None,
                });
            }
        }

        self.queue.submit(std::iter::once(encoder.finish()));
    }

    // draw_rect, draw_sdf, draw_quad, draw_shadow, draw_path_quad removed —
    // replaced by batched rendering in render().

    #[allow(clippy::too_many_arguments)]
    fn draw_image(
        &self,
        pass: &mut wgpu::RenderPass,
        image: &teksilo_canvas::ImageQuad,
        scale_factor: f32,
        viewport_width: u32,
        viewport_height: u32,
        opacity: f32,
        transform: &Transform2D,
        index_binding: Option<(&wgpu::Buffer, u64, u64)>,
    ) {
        let bind_group = match self.image_manager.get_bind_group(&image.name) {
            Some(bg) => bg,
            None => return,
        };

        let [x, y, w, h] = image.screen;
        let sx = x * scale_factor;
        let sy = y * scale_factor;
        let sw = w * scale_factor;
        let sh = h * scale_factor;

        // Tintable mode: image is an alpha mask tinted with the given color (flag=0).
        // Full-color mode: image RGB used directly (flag=1, existing behavior).
        let (color, flags) = if let Some(tint) = image.tint {
            // Tint colors are sRGB-encoded (from teksilo_tokens::Color) — linearize
            // for the Rgba8UnormSrgb surface, same as all other vertex colors.
            (
                crate::vertex::srgb_to_linear_rgba([tint[0], tint[1], tint[2], tint[3] * opacity]),
                0,
            )
        } else {
            (
                [1.0, 1.0, 1.0, opacity],
                crate::vertex::QUAD_FLAG_COLOR_GLYPH,
            )
        };

        let verts = [
            QuadVertex {
                position: [sx, sy],
                tex_coord: [0.0, 0.0],
                color,
                flags,
                _pad: 0,
            },
            QuadVertex {
                position: [sx + sw, sy],
                tex_coord: [1.0, 0.0],
                color,
                flags,
                _pad: 0,
            },
            QuadVertex {
                position: [sx + sw, sy + sh],
                tex_coord: [1.0, 1.0],
                color,
                flags,
                _pad: 0,
            },
            QuadVertex {
                position: [sx, sy + sh],
                tex_coord: [0.0, 1.0],
                color,
                flags,
                _pad: 0,
            },
        ];

        let ndc_verts: [QuadVertex; 4] = std::array::from_fn(|i| {
            let v = verts[i];
            let tp = apply_transform_pixel(v.position, transform);
            QuadVertex {
                position: pixel_to_ndc(tp, viewport_width, viewport_height),
                ..v
            }
        });

        // Reuse the persistent quad stream buffer instead of allocating
        // a fresh vertex buffer per image. Indices come from the shared
        // index stream populated at the top of `render()`.
        let bytes: &[u8] = bytemuck::cast_slice(&ndc_verts);
        let Some((vb, v_off, v_len)) = self.streams.quad.write(&self.queue, bytes) else {
            return;
        };
        let Some((ib, _, _)) = index_binding else {
            return;
        };

        pass.set_pipeline(&self.quad_pipeline);
        pass.set_bind_group(0, bind_group, &[]);
        pass.set_vertex_buffer(0, vb.slice(v_off..v_off + v_len));
        pass.set_index_buffer(ib.slice(0..24), wgpu::IndexFormat::Uint32);
        pass.draw_indexed(0..6, 0, 0..1);
    }

    /// Upload path atlas texture data.
    fn upload_path_atlas(&mut self, width: u32, height: u32, pixels: Vec<u8>) {
        if width == 0 || height == 0 {
            return;
        }

        let needs_recreate = self
            .path_atlas_texture
            .as_ref()
            .is_none_or(|t| t.width != width || t.height != height);

        if needs_recreate {
            let texture = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some("path_atlas"),
                size: wgpu::Extent3d {
                    width,
                    height,
                    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 = texture.create_view(&wgpu::TextureViewDescriptor::default());
            let sampler = self.device.create_sampler(&wgpu::SamplerDescriptor {
                mag_filter: wgpu::FilterMode::Linear,
                min_filter: wgpu::FilterMode::Linear,
                ..Default::default()
            });

            let bind_group_layout = self.quad_pipeline.get_bind_group_layout(0);
            let bind_group = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some("path_atlas_bind_group"),
                layout: &bind_group_layout,
                entries: &[
                    wgpu::BindGroupEntry {
                        binding: 0,
                        resource: wgpu::BindingResource::TextureView(&view),
                    },
                    wgpu::BindGroupEntry {
                        binding: 1,
                        resource: wgpu::BindingResource::Sampler(&sampler),
                    },
                ],
            });

            self.path_atlas_texture = Some(AtlasTexture {
                texture,
                bind_group,
                width,
                height,
            });
        }

        if let Some(atlas) = &self.path_atlas_texture {
            self.queue.write_texture(
                wgpu::TexelCopyTextureInfo {
                    texture: &atlas.texture,
                    mip_level: 0,
                    origin: wgpu::Origin3d::ZERO,
                    aspect: wgpu::TextureAspect::All,
                },
                &pixels,
                wgpu::TexelCopyBufferLayout {
                    offset: 0,
                    bytes_per_row: Some(width * 4),
                    rows_per_image: Some(height),
                },
                wgpu::Extent3d {
                    width,
                    height,
                    depth_or_array_layers: 1,
                },
            );
        }
    }

    pub fn device(&self) -> &wgpu::Device {
        &self.device
    }

    pub fn queue(&self) -> &wgpu::Queue {
        &self.queue
    }

    /// Register an image for rendering by name.
    pub fn register_image(&mut self, name: &str, width: u32, height: u32, pixels: &[u8]) {
        let layout = self.quad_pipeline.get_bind_group_layout(0);
        self.image_manager.register_image(
            name,
            width,
            height,
            pixels,
            &self.device,
            &self.queue,
            &layout,
        );
    }

    /// Remove a registered image.
    pub fn remove_image(&mut self, name: &str) {
        self.image_manager.remove(name);
    }
}

/// Build 4 QuadVertex for a path entry (in pixel space, pre-NDC).
fn path_quad_verts(
    entry: &teksilo_canvas::PathEntry,
    placement: &crate::path_atlas::PathPlacement,
    atlas_width: u32,
    atlas_height: u32,
    opacity: f32,
    transform: &Transform2D,
) -> [QuadVertex; 4] {
    // The rect comes from the placement, never recomputed from
    // `entry.bounds` — the atlas baked its bitmap against this exact rect,
    // and a second derivation of it is how the two drifted apart before
    // (see `PathPlacement`).
    let region = &placement.region;
    let [sx, sy, sw, sh] = placement.device_rect;

    let aw = atlas_width.max(1) as f32;
    let ah = atlas_height.max(1) as f32;
    let u0 = region.x as f32 / aw;
    let v0 = region.y as f32 / ah;
    let u1 = (region.x + region.w) as f32 / aw;
    let v1 = (region.y + region.h) as f32 / ah;

    // The path atlas stores coverage in its alpha channel; the monochrome
    // quad path (`flags = 0`) tints with the vertex RGB and multiplies by
    // that coverage. The `Rgba8UnormSrgb` target expects linear RGB from the
    // shader, so linearize `entry.color` here exactly like every other
    // pipeline (rect / sdf / shadow / image) — otherwise paths render with a
    // gamma error against everything else.
    let lin = crate::vertex::srgb_to_linear_rgba(entry.color);
    let color = [lin[0], lin[1], lin[2], entry.color[3] * opacity];

    let positions = [
        apply_transform_pixel([sx, sy], transform),
        apply_transform_pixel([sx + sw, sy], transform),
        apply_transform_pixel([sx + sw, sy + sh], transform),
        apply_transform_pixel([sx, sy + sh], transform),
    ];
    let uvs = [[u0, v0], [u1, v0], [u1, v1], [u0, v1]];

    // The shader outputs `vertex.rgb * tex.a` for `flags = 0`, equivalent to
    // `linear_path_color * path_coverage`.
    [
        QuadVertex {
            position: positions[0],
            tex_coord: uvs[0],
            color,
            flags: 0,
            _pad: 0,
        },
        QuadVertex {
            position: positions[1],
            tex_coord: uvs[1],
            color,
            flags: 0,
            _pad: 0,
        },
        QuadVertex {
            position: positions[2],
            tex_coord: uvs[2],
            color,
            flags: 0,
            _pad: 0,
        },
        QuadVertex {
            position: positions[3],
            tex_coord: uvs[3],
            color,
            flags: 0,
            _pad: 0,
        },
    ]
}

/// Build 4 [`PathGradientVertex`](crate::vertex::PathGradientVertex)es for a
/// gradient-filled path entry (in pixel space, pre-NDC). Same
/// bounds/atlas-UV/position math as [`path_quad_verts`] (the solid-path
/// counterpart) — the actual encoding lives on
/// `PathGradientVertex::from_path_entry` (mirrors the shared
/// `encode_paint_data`/`encode_stops` helpers used by [`SdfVertex`]); this
/// wrapper exists so the call site in `render()` reads symmetrically with
/// `path_quad_verts`.
fn path_gradient_quad_verts(
    entry: &teksilo_canvas::PathEntry,
    placement: &crate::path_atlas::PathPlacement,
    scale_factor: f32,
    atlas_width: u32,
    atlas_height: u32,
    current_opacity: f32,
    transform: &Transform2D,
) -> [crate::vertex::PathGradientVertex; 4] {
    crate::vertex::PathGradientVertex::from_path_entry(
        entry,
        placement,
        scale_factor,
        atlas_width,
        atlas_height,
        current_opacity,
        transform,
    )
}

fn pixel_to_ndc(pixel: [f32; 2], viewport_width: u32, viewport_height: u32) -> [f32; 2] {
    let x = (pixel[0] / viewport_width as f32) * 2.0 - 1.0;
    let y = 1.0 - (pixel[1] / viewport_height as f32) * 2.0; // flip Y
    [x, y]
}

/// Apply a 2D affine transform to pixel coordinates.
fn apply_transform_pixel(pixel: [f32; 2], transform: &Transform2D) -> [f32; 2] {
    let [a, b, c, d, tx, ty] = transform.m;
    [
        a * pixel[0] + c * pixel[1] + tx,
        b * pixel[0] + d * pixel[1] + ty,
    ]
}

/// Result of running the dual-Kawase chain on a `BlurScope`'s
/// intermediate. The returned texture is the final upsampled level —
/// it shares the same bucket-size convention as the input (only
/// `(used_w, used_h)` of `(bucket_w, bucket_h)` holds rendered
/// content), so the caller maps UVs as `used / bucket`.
struct KawaseResult {
    texture: crate::blur::AcquiredTexture,
    used_w: u32,
    used_h: u32,
    bucket_w: u32,
    bucket_h: u32,
}

/// Run a dual-Kawase blur chain on `source`. The chain depth is chosen
/// from the requested radius; each pass halves (downsample) or doubles
/// (upsample) the active region's size. Returns the final upsampled
/// texture handle (which may be the input handle itself if the chain
/// is a single round-trip).
#[allow(clippy::too_many_arguments)]
fn run_kawase_chain(
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    encoder: &mut wgpu::CommandEncoder,
    pool: &mut crate::blur::BlurPool,
    pipelines: &mut crate::blur::BlurPipelines,
    source: crate::blur::AcquiredTexture,
    used_w: u32,
    used_h: u32,
    bucket_w: u32,
    bucket_h: u32,
    radius_device_px: f32,
) -> KawaseResult {
    let levels = crate::blur::kawase_levels(radius_device_px);

    // Track the chain as (handle, used_w, used_h, bucket_w, bucket_h).
    // Each downsample halves used_w/h; the bucket size we sample from
    // is the *previous* level's bucket.
    let mut current = (source, used_w, used_h, bucket_w, bucket_h);

    // Upsample needs to know all intermediate bucket sizes so we can
    // walk back up. Stash one entry per chain level (input + each
    // downsample target).
    let mut chain: Vec<(crate::blur::AcquiredTexture, u32, u32, u32, u32)> =
        Vec::with_capacity(levels as usize + 1);
    chain.push(current);

    // Per-pass kernel offset multiplier. Bjørge's reference uses 0.5
    // for both passes; the actual blur radius this produces is
    // proportional to `2^levels * 0.5`, which roughly matches the
    // requested Gaussian-equivalent radius for typical UI values.
    const KERNEL_OFFSET: f32 = 0.5;

    // Downsample chain: source → mip1 → mip2 → ...
    for _ in 0..levels {
        let (src_handle, src_used_w, src_used_h, src_bucket_w, src_bucket_h) = current;
        let dst_used_w = (src_used_w / 2).max(1);
        let dst_used_h = (src_used_h / 2).max(1);
        let dst = pool.acquire(device, dst_used_w, dst_used_h);
        let (dst_bucket_w, dst_bucket_h) = pool.dimensions(dst);

        // Build per-pass uniforms: source-bucket UV-offset.
        let params = crate::blur::BlurParams {
            offset: crate::blur::kawase_offset(src_bucket_w, src_bucket_h, KERNEL_OFFSET),
        };
        let params_offset = pipelines.params.push(queue, &params);
        let bind_group = pool.make_bind_group(device, src_handle, pipelines.params.buffer());

        run_kawase_pass(
            encoder,
            &pipelines.down,
            &bind_group,
            params_offset,
            pool.view(dst),
            dst_used_w,
            dst_used_h,
            "kawase_down_pass",
        );

        current = (dst, dst_used_w, dst_used_h, dst_bucket_w, dst_bucket_h);
        chain.push(current);
    }

    // Upsample chain: mipN → mipN-1 → ... → mip0 (a fresh allocation;
    // we don't write back into the source texture because some Kawase
    // implementations rely on the source bucket's content surviving).
    for level in (0..levels).rev() {
        let (src_handle, _src_used_w, _src_used_h, src_bucket_w, src_bucket_h) = current;
        let target = chain[level as usize];
        let dst_used_w = target.1;
        let dst_used_h = target.2;
        let dst = pool.acquire(device, dst_used_w, dst_used_h);
        let (dst_bucket_w, dst_bucket_h) = pool.dimensions(dst);

        let params = crate::blur::BlurParams {
            offset: crate::blur::kawase_offset(src_bucket_w, src_bucket_h, KERNEL_OFFSET),
        };
        let params_offset = pipelines.params.push(queue, &params);
        let bind_group = pool.make_bind_group(device, src_handle, pipelines.params.buffer());

        run_kawase_pass(
            encoder,
            &pipelines.up,
            &bind_group,
            params_offset,
            pool.view(dst),
            dst_used_w,
            dst_used_h,
            "kawase_up_pass",
        );

        current = (dst, dst_used_w, dst_used_h, dst_bucket_w, dst_bucket_h);
    }

    KawaseResult {
        texture: current.0,
        used_w: current.1,
        used_h: current.2,
        bucket_w: current.3,
        bucket_h: current.4,
    }
}

/// Run one full-screen-triangle Kawase pass. The viewport is set to
/// `(used_w, used_h)` — the destination bucket may be larger but we
/// only write the upper-left sub-rect that the next pass will sample
/// from.
#[allow(clippy::too_many_arguments)]
fn run_kawase_pass(
    encoder: &mut wgpu::CommandEncoder,
    pipeline: &wgpu::RenderPipeline,
    bind_group: &wgpu::BindGroup,
    params_offset: u32,
    target_view: &wgpu::TextureView,
    used_w: u32,
    used_h: u32,
    label: &str,
) {
    let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
        label: Some(label),
        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
            view: target_view,
            resolve_target: None,
            ops: wgpu::Operations {
                load: wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT),
                store: wgpu::StoreOp::Store,
            },
            depth_slice: None,
        })],
        depth_stencil_attachment: None,
        timestamp_writes: None,
        occlusion_query_set: None,
        multiview_mask: None,
    });
    pass.set_pipeline(pipeline);
    pass.set_bind_group(0, bind_group, &[params_offset]);
    // Full-screen triangle covers the whole viewport — restricting the
    // viewport to the used sub-rect keeps the over-allocated bucket
    // clean and (more importantly) limits the fragment work.
    pass.set_viewport(0.0, 0.0, used_w as f32, used_h as f32, 0.0, 1.0);
    pass.draw(0..3, 0..1);
}

/// Composite the final blurred intermediate onto the parent target as
/// a textured quad at `bounds` (logical pixels). Uses the same quad
/// pipeline as static images: builds 4 vertices in NDC with image
/// flag set, binds the intermediate texture + sampler, and issues one
/// indexed draw.
///
/// `index_binding` is the per-frame index buffer (the first 6 u32s
/// already encode the standard quad index pattern, so we slice 24
/// bytes off the front).
#[allow(clippy::too_many_arguments)]
fn composite_blur_quad(
    device: &wgpu::Device,
    queue: &wgpu::Queue,
    pass: &mut wgpu::RenderPass<'_>,
    pool: &crate::blur::BlurPool,
    quad_pipeline: &wgpu::RenderPipeline,
    quad_bind_group_layout: &wgpu::BindGroupLayout,
    sampler: &wgpu::Sampler,
    quad_stream: &crate::stream_buffer::StreamBuffer,
    index_binding: Option<(&wgpu::Buffer, u64, u64)>,
    blurred: crate::blur::AcquiredTexture,
    used_w: u32,
    used_h: u32,
    bucket_w: u32,
    bucket_h: u32,
    bounds: teksilo_canvas::Rect,
    scale_factor: f32,
    viewport_width: u32,
    viewport_height: u32,
) {
    let view = pool.view(blurred);
    let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
        label: Some("blur_composite_bind_group"),
        layout: quad_bind_group_layout,
        entries: &[
            wgpu::BindGroupEntry {
                binding: 0,
                resource: wgpu::BindingResource::TextureView(view),
            },
            wgpu::BindGroupEntry {
                binding: 1,
                resource: wgpu::BindingResource::Sampler(sampler),
            },
        ],
    });

    // Vertex positions in device pixels, converted to NDC.
    let sx = bounds.x * scale_factor;
    let sy = bounds.y * scale_factor;
    let sw = bounds.width * scale_factor;
    let sh = bounds.height * scale_factor;

    // UVs map the used sub-rect inside the bucket. The bucket's
    // upper-left holds the rendered content; the rest is the
    // cleared-to-transparent padding from the bucket's allocation.
    let u_max = used_w as f32 / bucket_w as f32;
    let v_max = used_h as f32 / bucket_h as f32;

    // Image flag (bit 0 = 1 → fragment shader uses tex.rgb directly).
    let flags = 1u32;
    let color = [1.0, 1.0, 1.0, 1.0];

    let p_tl = pixel_to_ndc([sx, sy], viewport_width, viewport_height);
    let p_tr = pixel_to_ndc([sx + sw, sy], viewport_width, viewport_height);
    let p_br = pixel_to_ndc([sx + sw, sy + sh], viewport_width, viewport_height);
    let p_bl = pixel_to_ndc([sx, sy + sh], viewport_width, viewport_height);

    let verts: [QuadVertex; 4] = [
        QuadVertex {
            position: p_tl,
            tex_coord: [0.0, 0.0],
            color,
            flags,
            _pad: 0,
        },
        QuadVertex {
            position: p_tr,
            tex_coord: [u_max, 0.0],
            color,
            flags,
            _pad: 0,
        },
        QuadVertex {
            position: p_br,
            tex_coord: [u_max, v_max],
            color,
            flags,
            _pad: 0,
        },
        QuadVertex {
            position: p_bl,
            tex_coord: [0.0, v_max],
            color,
            flags,
            _pad: 0,
        },
    ];

    // Caller has already sized `quad_stream` for the worst-case quad
    // count *including composites* (see render()'s up-front sizing).
    // The index buffer's first 6 u32s = `[0, 1, 2, 0, 2, 3]` (the
    // standard quad pattern), reused here.
    let _ = device; // device is only used for bind-group creation above
    let Some((vb, v_off, v_len)) = quad_stream.write(queue, bytemuck::cast_slice(&verts)) else {
        return;
    };
    let Some((ib, _, _)) = index_binding else {
        return;
    };
    let composite_index_bytes: u64 = 6 * std::mem::size_of::<u32>() as u64;

    pass.set_pipeline(quad_pipeline);
    pass.set_bind_group(0, &bind_group, &[]);
    pass.set_viewport(
        0.0,
        0.0,
        viewport_width as f32,
        viewport_height as f32,
        0.0,
        1.0,
    );
    pass.set_vertex_buffer(0, vb.slice(v_off..v_off + v_len));
    pass.set_index_buffer(
        ib.slice(0..composite_index_bytes),
        wgpu::IndexFormat::Uint32,
    );
    pass.draw_indexed(0..6, 0, 0..1);
}

// --- Pipeline creation ---

fn create_rect_pipeline(
    device: &wgpu::Device,
    format: wgpu::TextureFormat,
) -> wgpu::RenderPipeline {
    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
        label: Some("rect_shader"),
        source: wgpu::ShaderSource::Wgsl(include_str!("shaders/rect.wgsl").into()),
    });

    let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("rect_pipeline_layout"),
        bind_group_layouts: &[],
        immediate_size: 0,
    });

    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
        label: Some("rect_pipeline"),
        layout: Some(&layout),
        vertex: wgpu::VertexState {
            module: &shader,
            entry_point: Some("vs_main"),
            buffers: &[Some(wgpu::VertexBufferLayout {
                array_stride: std::mem::size_of::<RectVertex>() as u64,
                step_mode: wgpu::VertexStepMode::Vertex,
                attributes: &[
                    wgpu::VertexAttribute {
                        offset: 0,
                        shader_location: 0,
                        format: wgpu::VertexFormat::Float32x2,
                    },
                    wgpu::VertexAttribute {
                        offset: 8,
                        shader_location: 1,
                        format: wgpu::VertexFormat::Float32x4,
                    },
                ],
            })],
            compilation_options: Default::default(),
        },
        fragment: Some(wgpu::FragmentState {
            module: &shader,
            entry_point: Some("fs_main"),
            targets: &[Some(wgpu::ColorTargetState {
                format,
                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                write_mask: wgpu::ColorWrites::ALL,
            })],
            compilation_options: Default::default(),
        }),
        primitive: wgpu::PrimitiveState {
            topology: wgpu::PrimitiveTopology::TriangleList,
            ..Default::default()
        },
        depth_stencil: None,
        multisample: wgpu::MultisampleState::default(),
        multiview_mask: None,
        cache: None,
    })
}

fn create_sdf_pipeline(device: &wgpu::Device, format: wgpu::TextureFormat) -> wgpu::RenderPipeline {
    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
        label: Some("sdf_shader"),
        source: wgpu::ShaderSource::Wgsl(include_str!("shaders/sdf.wgsl").into()),
    });

    let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("sdf_pipeline_layout"),
        bind_group_layouts: &[],
        immediate_size: 0,
    });

    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
        label: Some("sdf_pipeline"),
        layout: Some(&layout),
        vertex: wgpu::VertexState {
            module: &shader,
            entry_point: Some("vs_main"),
            buffers: &[Some(wgpu::VertexBufferLayout {
                array_stride: std::mem::size_of::<SdfVertex>() as u64,
                step_mode: wgpu::VertexStepMode::Vertex,
                attributes: &[
                    wgpu::VertexAttribute {
                        offset: 0,
                        shader_location: 0,
                        format: wgpu::VertexFormat::Float32x2, // position
                    },
                    wgpu::VertexAttribute {
                        offset: 8,
                        shader_location: 1,
                        format: wgpu::VertexFormat::Float32x2, // local_uv
                    },
                    wgpu::VertexAttribute {
                        offset: 16,
                        shader_location: 2,
                        format: wgpu::VertexFormat::Float32x4, // color
                    },
                    wgpu::VertexAttribute {
                        offset: 32,
                        shader_location: 3,
                        format: wgpu::VertexFormat::Float32x4, // corner_radii
                    },
                    wgpu::VertexAttribute {
                        offset: 48,
                        shader_location: 4,
                        format: wgpu::VertexFormat::Float32x4, // shape_params
                    },
                    wgpu::VertexAttribute {
                        offset: 64,
                        shader_location: 5,
                        format: wgpu::VertexFormat::Float32x4, // gradient_geo
                    },
                    wgpu::VertexAttribute {
                        offset: 80,
                        shader_location: 6,
                        format: wgpu::VertexFormat::Float32x4, // gradient_color0
                    },
                    wgpu::VertexAttribute {
                        offset: 96,
                        shader_location: 7,
                        format: wgpu::VertexFormat::Float32x4, // gradient_color1
                    },
                    wgpu::VertexAttribute {
                        offset: 112,
                        shader_location: 8,
                        format: wgpu::VertexFormat::Float32x4, // gradient_color2
                    },
                    wgpu::VertexAttribute {
                        offset: 128,
                        shader_location: 9,
                        format: wgpu::VertexFormat::Float32x4, // gradient_color3
                    },
                    wgpu::VertexAttribute {
                        offset: 144,
                        shader_location: 10,
                        format: wgpu::VertexFormat::Float32x4, // gradient_offsets
                    },
                ],
            })],
            compilation_options: Default::default(),
        },
        fragment: Some(wgpu::FragmentState {
            module: &shader,
            entry_point: Some("fs_main"),
            targets: &[Some(wgpu::ColorTargetState {
                format,
                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                write_mask: wgpu::ColorWrites::ALL,
            })],
            compilation_options: Default::default(),
        }),
        primitive: wgpu::PrimitiveState {
            topology: wgpu::PrimitiveTopology::TriangleList,
            ..Default::default()
        },
        depth_stencil: None,
        multisample: wgpu::MultisampleState::default(),
        multiview_mask: None,
        cache: None,
    })
}

fn create_quad_pipeline(
    device: &wgpu::Device,
    format: wgpu::TextureFormat,
) -> wgpu::RenderPipeline {
    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
        label: Some("quad_shader"),
        source: wgpu::ShaderSource::Wgsl(include_str!("shaders/quad.wgsl").into()),
    });

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

    let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("quad_pipeline_layout"),
        bind_group_layouts: &[Some(&bind_group_layout)],
        immediate_size: 0,
    });

    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
        label: Some("quad_pipeline"),
        layout: Some(&layout),
        vertex: wgpu::VertexState {
            module: &shader,
            entry_point: Some("vs_main"),
            buffers: &[Some(wgpu::VertexBufferLayout {
                array_stride: std::mem::size_of::<QuadVertex>() as u64,
                step_mode: wgpu::VertexStepMode::Vertex,
                attributes: &[
                    wgpu::VertexAttribute {
                        offset: 0,
                        shader_location: 0,
                        format: wgpu::VertexFormat::Float32x2, // position
                    },
                    wgpu::VertexAttribute {
                        offset: 8,
                        shader_location: 1,
                        format: wgpu::VertexFormat::Float32x2, // tex_coord
                    },
                    wgpu::VertexAttribute {
                        offset: 16,
                        shader_location: 2,
                        format: wgpu::VertexFormat::Float32x4, // color
                    },
                    wgpu::VertexAttribute {
                        offset: 32,
                        shader_location: 3,
                        format: wgpu::VertexFormat::Uint32, // flags (bit 0 = color glyph)
                    },
                ],
            })],
            compilation_options: Default::default(),
        },
        fragment: Some(wgpu::FragmentState {
            module: &shader,
            entry_point: Some("fs_main"),
            targets: &[Some(wgpu::ColorTargetState {
                format,
                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                write_mask: wgpu::ColorWrites::ALL,
            })],
            compilation_options: Default::default(),
        }),
        primitive: wgpu::PrimitiveState {
            topology: wgpu::PrimitiveTopology::TriangleList,
            ..Default::default()
        },
        depth_stencil: None,
        multisample: wgpu::MultisampleState::default(),
        multiview_mask: None,
        cache: None,
    })
}

/// Build the gradient-filled path pipeline (Tier 3, gradient paint
/// only). Reuses `texture_bind_group_layout` — the SAME group(0) layout
/// the `quad_pipeline` exposes (texture + sampler) — as its own group 0,
/// so the path atlas's bind group (built once, shared with the solid
/// path quad batch) binds unchanged for both pipelines.
fn create_path_gradient_pipeline(
    device: &wgpu::Device,
    format: wgpu::TextureFormat,
    texture_bind_group_layout: &wgpu::BindGroupLayout,
) -> wgpu::RenderPipeline {
    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
        label: Some("path_gradient_shader"),
        source: wgpu::ShaderSource::Wgsl(include_str!("shaders/path_gradient.wgsl").into()),
    });

    let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("path_gradient_pipeline_layout"),
        bind_group_layouts: &[Some(texture_bind_group_layout)],
        immediate_size: 0,
    });

    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
        label: Some("path_gradient_pipeline"),
        layout: Some(&layout),
        vertex: wgpu::VertexState {
            module: &shader,
            entry_point: Some("vs_main"),
            buffers: &[Some(wgpu::VertexBufferLayout {
                array_stride: std::mem::size_of::<crate::vertex::PathGradientVertex>() as u64,
                step_mode: wgpu::VertexStepMode::Vertex,
                attributes: &[
                    wgpu::VertexAttribute {
                        offset: 0,
                        shader_location: 0,
                        format: wgpu::VertexFormat::Float32x2, // position
                    },
                    wgpu::VertexAttribute {
                        offset: 8,
                        shader_location: 1,
                        format: wgpu::VertexFormat::Float32x2, // tex_coord
                    },
                    wgpu::VertexAttribute {
                        offset: 16,
                        shader_location: 2,
                        format: wgpu::VertexFormat::Float32x2, // local_uv
                    },
                    wgpu::VertexAttribute {
                        offset: 24,
                        shader_location: 3,
                        format: wgpu::VertexFormat::Uint32, // paint_type
                    },
                    // Offset 28 (_pad: u32) is skipped — no attribute.
                    wgpu::VertexAttribute {
                        offset: 32,
                        shader_location: 4,
                        format: wgpu::VertexFormat::Float32x4, // gradient_geo
                    },
                    wgpu::VertexAttribute {
                        offset: 48,
                        shader_location: 5,
                        format: wgpu::VertexFormat::Float32x4, // gradient_color0
                    },
                    wgpu::VertexAttribute {
                        offset: 64,
                        shader_location: 6,
                        format: wgpu::VertexFormat::Float32x4, // gradient_color1
                    },
                    wgpu::VertexAttribute {
                        offset: 80,
                        shader_location: 7,
                        format: wgpu::VertexFormat::Float32x4, // gradient_color2
                    },
                    wgpu::VertexAttribute {
                        offset: 96,
                        shader_location: 8,
                        format: wgpu::VertexFormat::Float32x4, // gradient_color3
                    },
                    wgpu::VertexAttribute {
                        offset: 112,
                        shader_location: 9,
                        format: wgpu::VertexFormat::Float32x4, // gradient_offsets
                    },
                ],
            })],
            compilation_options: Default::default(),
        },
        fragment: Some(wgpu::FragmentState {
            module: &shader,
            entry_point: Some("fs_main"),
            targets: &[Some(wgpu::ColorTargetState {
                format,
                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                write_mask: wgpu::ColorWrites::ALL,
            })],
            compilation_options: Default::default(),
        }),
        primitive: wgpu::PrimitiveState {
            topology: wgpu::PrimitiveTopology::TriangleList,
            ..Default::default()
        },
        depth_stencil: None,
        multisample: wgpu::MultisampleState::default(),
        multiview_mask: None,
        cache: None,
    })
}

fn create_shadow_pipeline(
    device: &wgpu::Device,
    format: wgpu::TextureFormat,
) -> wgpu::RenderPipeline {
    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
        label: Some("shadow_shader"),
        source: wgpu::ShaderSource::Wgsl(include_str!("shaders/shadow.wgsl").into()),
    });

    let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("shadow_pipeline_layout"),
        bind_group_layouts: &[],
        immediate_size: 0,
    });

    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
        label: Some("shadow_pipeline"),
        layout: Some(&layout),
        vertex: wgpu::VertexState {
            module: &shader,
            entry_point: Some("vs_main"),
            buffers: &[Some(wgpu::VertexBufferLayout {
                array_stride: std::mem::size_of::<ShadowVertex>() as u64,
                step_mode: wgpu::VertexStepMode::Vertex,
                attributes: &[
                    wgpu::VertexAttribute {
                        offset: 0,
                        shader_location: 0,
                        format: wgpu::VertexFormat::Float32x2, // position
                    },
                    wgpu::VertexAttribute {
                        offset: 8,
                        shader_location: 1,
                        format: wgpu::VertexFormat::Float32x2, // local_uv
                    },
                    wgpu::VertexAttribute {
                        offset: 16,
                        shader_location: 2,
                        format: wgpu::VertexFormat::Float32x4, // shadow_color
                    },
                    wgpu::VertexAttribute {
                        offset: 32,
                        shader_location: 3,
                        format: wgpu::VertexFormat::Float32x4, // corner_radii
                    },
                    wgpu::VertexAttribute {
                        offset: 48,
                        shader_location: 4,
                        format: wgpu::VertexFormat::Float32x4, // shadow_params
                    },
                    wgpu::VertexAttribute {
                        offset: 64,
                        shader_location: 5,
                        format: wgpu::VertexFormat::Float32x4, // shape_offset
                    },
                ],
            })],
            compilation_options: Default::default(),
        },
        fragment: Some(wgpu::FragmentState {
            module: &shader,
            entry_point: Some("fs_main"),
            targets: &[Some(wgpu::ColorTargetState {
                format,
                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                write_mask: wgpu::ColorWrites::ALL,
            })],
            compilation_options: Default::default(),
        }),
        primitive: wgpu::PrimitiveState {
            topology: wgpu::PrimitiveTopology::TriangleList,
            ..Default::default()
        },
        depth_stencil: None,
        multisample: wgpu::MultisampleState::default(),
        multiview_mask: None,
        cache: None,
    })
}

/// Per-pipeline quad counts for one frame's stream-buffer sizing.
///
/// Upper bound per pipeline = `quads * 4 vertices` because every
/// drawable produces exactly 4 vertices. Every count here must match
/// what the draw walk actually writes into the corresponding
/// [`StreamBuffer`](crate::stream_buffer::StreamBuffer) — an
/// undercount overflows the buffer at write time (debug assert +
/// dropped draws; see `StreamBuffer::write`). Kept as a pure function
/// of the frame so the accounting is unit-testable headlessly (the
/// GPU path has no headless coverage).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct StreamQuadCounts {
    pub rect: usize,
    pub sdf: usize,
    pub quad: usize,
    pub shadow: usize,
    pub anim_proc: usize,
    /// Gradient-filled path quads (Tier 3, `path_gradient_pipeline`).
    /// Split out of `quad` — see `stream_quad_counts`.
    pub path_gradient: usize,
}

impl StreamQuadCounts {
    /// The largest per-pipeline count — sizes the shared index buffer
    /// so one index stream serves all pipelines.
    pub fn max(&self) -> usize {
        self.rect
            .max(self.sdf)
            .max(self.quad)
            .max(self.shadow)
            .max(self.anim_proc)
            .max(self.path_gradient)
    }
}

/// Count the quads each pipeline's stream buffer must hold for `frame`.
///
/// - `rect` draws both `DrawCommand::Decoration` (Tier-1 rects) AND
///   `DrawCommand::CosmeticLine` (each hairline emits one 4-vertex quad
///   through the same rect stream — see the CosmeticLine arm in the
///   draw walk).
/// - `quad` covers glyphs, SOLID-filled paths, images, plus one
///   composite-blit quad per blur scope (`BeginBlurredSubtree`), emitted
///   on End. Gradient-filled paths are split out into `path_gradient`
///   instead (see below) — they draw through a different pipeline.
/// - `anim_proc` covers BOTH animated-quad classes: `Procedural` quads
///   batch into `anim_proc_batch`, but `Sprite` quads ALSO write their
///   4 vertices into the same `streams.anim_proc` buffer (one
///   individually-bound draw each). Counting only `Procedural` here
///   undersized the buffer whenever a sprite-animated icon was on
///   screen, overflowing the stream at write time.
/// - `path_gradient` covers `PathEntry`s whose `paint_data` is a
///   gradient variant (`LinearGradient`/`RadialGradient`/`ConicGradient`)
///   — drawn by the dedicated `path_gradient_pipeline` instead of the
///   shared `quad_pipeline`. Solid paths (`PaintData::Solid`, including
///   every stroke) stay counted under `quad`.
pub(crate) fn stream_quad_counts(frame: &RenderFrame) -> StreamQuadCounts {
    let composite_quads = frame
        .draw_order
        .iter()
        .filter(|c| matches!(c, teksilo_canvas::DrawCommand::BeginBlurredSubtree { .. }))
        .count();
    let gradient_paths = frame
        .paths
        .iter()
        .filter(|p| !matches!(p.paint_data, teksilo_canvas::PaintData::Solid))
        .count();
    let solid_paths = frame.paths.len() - gradient_paths;
    StreamQuadCounts {
        rect: frame.decorations.len() + frame.cosmetic_lines.len(),
        sdf: frame.shapes.len(),
        quad: frame.glyphs.len() + solid_paths + frame.images.len() + composite_quads,
        shadow: frame.shadows.len(),
        anim_proc: frame.animated_quads.len(),
        path_gradient: gradient_paths,
    }
}

/// Build the procedural-animation pipeline plus its per-slot uniform
/// buffer, bind group, and bind-group layout. The layout is returned
/// so the sprite pipeline can reuse it as its `group 0`. Buffer is
/// sized for [`MAX_ANIM_SLOTS`] × `size_of::<teksilo_canvas::AnimParams>()`;
/// the per-frame upload in `render()` truncates writes past that cap.
fn create_anim_proc_pipeline(
    device: &wgpu::Device,
    format: wgpu::TextureFormat,
) -> (
    wgpu::RenderPipeline,
    wgpu::Buffer,
    wgpu::BindGroup,
    wgpu::BindGroupLayout,
) {
    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
        label: Some("anim_procedural_shader"),
        source: wgpu::ShaderSource::Wgsl(include_str!("shaders/anim_procedural.wgsl").into()),
    });

    let buffer_size = (MAX_ANIM_SLOTS * std::mem::size_of::<teksilo_canvas::AnimParams>()) as u64;
    let anim_uniform_buffer = device.create_buffer(&wgpu::BufferDescriptor {
        label: Some("anim_uniform_buffer"),
        size: buffer_size,
        usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
        mapped_at_creation: false,
    });

    let bind_group_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
        label: Some("anim_uniform_bind_group_layout"),
        entries: &[wgpu::BindGroupLayoutEntry {
            binding: 0,
            visibility: wgpu::ShaderStages::FRAGMENT,
            ty: wgpu::BindingType::Buffer {
                ty: wgpu::BufferBindingType::Uniform,
                has_dynamic_offset: false,
                min_binding_size: None,
            },
            count: None,
        }],
    });

    let anim_uniform_bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
        label: Some("anim_uniform_bind_group"),
        layout: &bind_group_layout,
        entries: &[wgpu::BindGroupEntry {
            binding: 0,
            resource: anim_uniform_buffer.as_entire_binding(),
        }],
    });

    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("anim_proc_pipeline_layout"),
        bind_group_layouts: &[Some(&bind_group_layout)],
        immediate_size: 0,
    });

    let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
        label: Some("anim_proc_pipeline"),
        layout: Some(&pipeline_layout),
        vertex: wgpu::VertexState {
            module: &shader,
            entry_point: Some("vs_main"),
            buffers: &[Some(anim_quad_vertex_layout())],
            compilation_options: Default::default(),
        },
        fragment: Some(wgpu::FragmentState {
            module: &shader,
            entry_point: Some("fs_main"),
            targets: &[Some(wgpu::ColorTargetState {
                format,
                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                write_mask: wgpu::ColorWrites::ALL,
            })],
            compilation_options: Default::default(),
        }),
        primitive: wgpu::PrimitiveState {
            topology: wgpu::PrimitiveTopology::TriangleList,
            ..Default::default()
        },
        depth_stencil: None,
        multisample: wgpu::MultisampleState::default(),
        multiview_mask: None,
        cache: None,
    });

    (
        pipeline,
        anim_uniform_buffer,
        anim_uniform_bind_group,
        bind_group_layout,
    )
}

/// Build the sprite-atlas animation pipeline. Shares group 0 (the
/// per-slot uniform buffer) with the procedural pipeline; adds group
/// 1 = sprite atlas texture + sampler, resolved per-draw via
/// `ImageManager::get_bind_group(image_name)`. Returns the pipeline
/// and the texture bind-group layout (so `ImageManager` can register
/// images under the same layout).
fn create_anim_sprite_pipeline(
    device: &wgpu::Device,
    format: wgpu::TextureFormat,
    uniform_layout: &wgpu::BindGroupLayout,
    texture_layout: &wgpu::BindGroupLayout,
) -> wgpu::RenderPipeline {
    let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
        label: Some("anim_sprite_shader"),
        source: wgpu::ShaderSource::Wgsl(include_str!("shaders/anim_sprite.wgsl").into()),
    });

    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some("anim_sprite_pipeline_layout"),
        bind_group_layouts: &[Some(uniform_layout), Some(texture_layout)],
        immediate_size: 0,
    });

    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
        label: Some("anim_sprite_pipeline"),
        layout: Some(&pipeline_layout),
        vertex: wgpu::VertexState {
            module: &shader,
            entry_point: Some("vs_main"),
            buffers: &[Some(anim_quad_vertex_layout())],
            compilation_options: Default::default(),
        },
        fragment: Some(wgpu::FragmentState {
            module: &shader,
            entry_point: Some("fs_main"),
            targets: &[Some(wgpu::ColorTargetState {
                format,
                blend: Some(wgpu::BlendState::ALPHA_BLENDING),
                write_mask: wgpu::ColorWrites::ALL,
            })],
            compilation_options: Default::default(),
        }),
        primitive: wgpu::PrimitiveState {
            topology: wgpu::PrimitiveTopology::TriangleList,
            ..Default::default()
        },
        depth_stencil: None,
        multisample: wgpu::MultisampleState::default(),
        multiview_mask: None,
        cache: None,
    })
}

/// Vertex buffer layout shared by both animated-quad pipelines.
fn anim_quad_vertex_layout() -> wgpu::VertexBufferLayout<'static> {
    const ATTRS: [wgpu::VertexAttribute; 3] = [
        wgpu::VertexAttribute {
            offset: 0,
            shader_location: 0,
            format: wgpu::VertexFormat::Float32x2,
        },
        wgpu::VertexAttribute {
            offset: 8,
            shader_location: 1,
            format: wgpu::VertexFormat::Float32x2,
        },
        wgpu::VertexAttribute {
            offset: 16,
            shader_location: 2,
            format: wgpu::VertexFormat::Uint32,
        },
    ];
    wgpu::VertexBufferLayout {
        array_stride: std::mem::size_of::<AnimQuadVertex>() as u64,
        step_mode: wgpu::VertexStepMode::Vertex,
        attributes: &ATTRS,
    }
}

#[cfg(test)]
mod tests {
    use teksilo_canvas::RenderFrame;
    use teksilo_canvas::render_frame::{DrawCommand, GlyphQuad, PaintData, ShapeKind, ShapeQuad};

    use super::*;

    #[test]
    fn stream_quad_counts_includes_sprite_anim_quads() {
        // Regression test for the anim_proc undercount: Sprite-class
        // animated quads write 4 vertices into the SAME stream buffer
        // as Procedural ones (each sprite draws individually, but the
        // bytes land in `streams.anim_proc`). Sizing for Procedural
        // only overflowed the stream whenever a sprite-animated icon
        // was on screen.
        use teksilo_canvas::render_frame::{AnimatedQuadClass, AnimatedQuadDraw};

        let mut frame = RenderFrame::new();
        for slot in 0..3 {
            frame.animated_quads.push(AnimatedQuadDraw {
                screen: [0.0, 0.0, 10.0, 10.0],
                slot,
                class: AnimatedQuadClass::Procedural,
            });
        }
        for slot in 3..5 {
            frame.animated_quads.push(AnimatedQuadDraw {
                screen: [0.0, 0.0, 10.0, 10.0],
                slot,
                class: AnimatedQuadClass::Sprite {
                    image_name: "icon".to_string(),
                },
            });
        }
        frame.glyphs.push(GlyphQuad {
            screen: [0.0, 0.0, 8.0, 8.0],
            atlas: [0.0, 0.0, 2.0, 2.0],
            color: [1.0; 4],
            is_color: false,
        });

        let counts = stream_quad_counts(&frame);
        assert_eq!(
            counts.anim_proc, 5,
            "anim_proc stream must be sized for BOTH Procedural and Sprite quads"
        );
        assert_eq!(counts.quad, 1);
        assert_eq!(counts.rect, 0);
        assert_eq!(counts.sdf, 0);
        assert_eq!(counts.shadow, 0);
        assert_eq!(counts.max(), 5, "index buffer sizes to the largest stream");
    }

    #[test]
    fn stream_quad_counts_splits_solid_and_gradient_paths() {
        // C4.5: gradient-filled paths draw through a different pipeline
        // (`path_gradient_pipeline`) than solid-filled ones (which stay
        // on `quad_pipeline`), so the two must size DIFFERENT stream
        // buffers — undercounting either overflows its `StreamBuffer`
        // at write time (see `StreamBuffer::write`'s debug_assert).
        use teksilo_canvas::render_frame::PathEntry;
        use teksilo_canvas::{FillRule, GradientStop, Path, StrokeStyle};
        use teksilo_tokens::Color;

        let mut frame = RenderFrame::new();
        frame.paths.push(PathEntry {
            path: Path::new(),
            color: [1.0, 0.0, 0.0, 1.0],
            stroke_style: StrokeStyle::solid(0.0),
            fill_rule: FillRule::Winding,
            bounds: [0.0, 0.0, 10.0, 10.0],
            paint_data: PaintData::Solid,
        });
        frame.paths.push(PathEntry {
            path: Path::new(),
            color: [1.0, 1.0, 1.0, 1.0],
            stroke_style: StrokeStyle::solid(0.0),
            fill_rule: FillRule::Winding,
            bounds: [0.0, 0.0, 20.0, 20.0],
            paint_data: PaintData::LinearGradient {
                start: [0.0, 0.0],
                end: [20.0, 0.0],
                stops: vec![
                    GradientStop {
                        offset: 0.0,
                        color: Color::RED,
                    },
                    GradientStop {
                        offset: 1.0,
                        color: Color::BLUE,
                    },
                ],
            },
        });

        let counts = stream_quad_counts(&frame);
        assert_eq!(counts.quad, 1, "the solid path counts toward quad");
        assert_eq!(
            counts.path_gradient, 1,
            "the gradient path counts toward path_gradient, not quad"
        );
        assert_eq!(counts.rect, 0);
        assert_eq!(counts.sdf, 0);
        assert_eq!(counts.shadow, 0);
        assert_eq!(counts.anim_proc, 0);
        assert_eq!(counts.max(), 1);
    }

    #[test]
    fn gradient_path_renders_nonflat_on_gpu() {
        // #12 end-to-end GPU verification: a gradient-filled Tier-3 path must
        // flush through the dedicated `path_gradient` pipeline and produce a
        // real gradient (not a flat tint) on an actual device — and without
        // tripping `StreamBuffer::write`'s capacity debug_assert. This is the
        // one property headless-CPU tests structurally cannot prove; it needs
        // a real device + pixel readback.
        use teksilo_canvas::render_frame::PathEntry;
        use teksilo_canvas::{FillRule, GradientStop, Path, Rect, StrokeStyle};
        use teksilo_tokens::Color;

        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_gradient_path_device"),
        ) else {
            return; // no GPU adapter (headless CI) — skip.
        };

        // A filled 30×30 square, horizontally red (left) → blue (right).
        let path = Path::rect(Rect::new(1.0, 1.0, 30.0, 30.0));
        let bounds = path.bounds();
        let mut frame = RenderFrame::new();
        frame.paths.push(PathEntry {
            path,
            color: [1.0, 1.0, 1.0, 1.0],
            stroke_style: StrokeStyle::solid(0.0),
            fill_rule: FillRule::Winding,
            bounds: [bounds.x, bounds.y, bounds.width, bounds.height],
            paint_data: PaintData::LinearGradient {
                start: [bounds.x, bounds.y],
                end: [bounds.x + bounds.width, bounds.y],
                stops: vec![
                    GradientStop {
                        offset: 0.0,
                        color: Color::RED,
                    },
                    GradientStop {
                        offset: 1.0,
                        color: Color::BLUE,
                    },
                ],
            },
        });
        frame.draw_order.push(DrawCommand::Path(0));

        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("teksilo_render_gradient_path_target"),
            size: wgpu::Extent3d {
                width: 32,
                height: 32,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8UnormSrgb,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());

        // Reaching here without a panic means the gradient batch flushed
        // without a `StreamBuffer` capacity overflow (the debug_assert the
        // count-split guards).
        renderer.render(&frame, &view, 1.0, 32, 32, [0.0, 0.0, 0.0, 0.0]);

        let pixels = crate::test_support::read_texture_rgba(&device, &queue, &texture, 32, 32);
        let px = |x: usize, y: usize| {
            let i = (y * 32 + x) * 4;
            [pixels[i], pixels[i + 1], pixels[i + 2], pixels[i + 3]]
        };
        // Sample a row through the middle: near the red edge and the blue edge.
        let left = px(4, 16);
        let right = px(27, 16);

        assert!(
            left[3] > 200 && right[3] > 200,
            "gradient square not covered (coverage-mask atlas broken): left={left:?} right={right:?}"
        );
        // Left red-dominant, right blue-dominant, ends clearly different — a
        // real interpolated gradient, not a single flat tint.
        assert!(
            left[0] as i32 > left[2] as i32 + 40,
            "left edge must be red-dominant, got {left:?}"
        );
        assert!(
            right[2] as i32 > right[0] as i32 + 40,
            "right edge must be blue-dominant, got {right:?}"
        );
        assert!(
            (left[0] as i32 - right[0] as i32).abs() > 60,
            "gradient looks flat (shader not sampling the gradient): left={left:?} right={right:?}"
        );
    }

    #[test]
    fn gradient_path_partial_alpha_preserved() {
        // Regression for washed-out gradient fills: a gradient stop's alpha
        // must survive the path_gradient pipeline. Render a horizontal
        // green→green gradient whose LEFT stop is opaque (a=1.0) and RIGHT
        // stop is a=0.4, over a TRANSPARENT clear so the read-back alpha IS
        // the fill's alpha (no gamma/compositing confound). Left must stay
        // ~opaque, right must read ~0.4 (not ~0.24).
        use teksilo_canvas::render_frame::PathEntry;
        use teksilo_canvas::{FillRule, GradientStop, Path, Rect, StrokeStyle};
        use teksilo_tokens::Color;

        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_partial_alpha_device"),
        ) else {
            return;
        };

        let path = Path::rect(Rect::new(0.0, 0.0, 32.0, 32.0));
        let bounds = path.bounds();
        let mut frame = RenderFrame::new();
        frame.paths.push(PathEntry {
            path,
            color: [1.0, 1.0, 1.0, 1.0],
            stroke_style: StrokeStyle::solid(0.0),
            fill_rule: FillRule::Winding,
            bounds: [bounds.x, bounds.y, bounds.width, bounds.height],
            paint_data: PaintData::LinearGradient {
                start: [0.0, 0.0],
                end: [32.0, 0.0],
                stops: vec![
                    GradientStop {
                        offset: 0.0,
                        color: Color::from_rgba(0.0, 0.62, 0.45, 1.0),
                    },
                    GradientStop {
                        offset: 1.0,
                        color: Color::from_rgba(0.0, 0.62, 0.45, 0.4),
                    },
                ],
            },
        });
        frame.draw_order.push(DrawCommand::Path(0));

        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("partial_alpha_target"),
            size: wgpu::Extent3d {
                width: 32,
                height: 32,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8UnormSrgb,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
        renderer.render(&frame, &view, 1.0, 32, 32, [0.0, 0.0, 0.0, 0.0]);

        let px = crate::test_support::read_texture_rgba(&device, &queue, &texture, 32, 32);
        let alpha = |x: usize| px[(16 * 32 + x) * 4 + 3];
        let (left, right) = (alpha(2), alpha(29));
        // Diagnostic — surfaced on failure.
        assert!(
            left >= 240,
            "opaque (a=1.0) end must stay opaque, got {left} (/255)"
        );
        assert!(
            (90..=115).contains(&right),
            "a=0.4 stop must read ~102/255, got {right} — a value near ~61 means the \
             pipeline under-renders gradient stop alpha (washed-out fills)"
        );
    }

    #[test]
    fn glyph_quad_renders_over_shape_in_offscreen_target() {
        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_test_device"),
        ) else {
            return;
        };

        renderer.upload_atlas(
            2,
            2,
            &[
                255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
            ],
        );

        let mut frame = RenderFrame::new();
        frame.shapes.push(ShapeQuad {
            screen: [4.0, 4.0, 24.0, 24.0],
            color: [0.2, 0.6, 0.9, 1.0],
            shape: ShapeKind::RoundedRect,
            stroke_width: 0.0,
            stroke_space: teksilo_canvas::StrokeSpace::Logical,
            corner_radii: [0.0; 4],
            paint_data: PaintData::Solid,
        });
        frame.draw_order.push(DrawCommand::Shape(0));

        frame.glyphs.push(GlyphQuad {
            screen: [10.0, 10.0, 8.0, 8.0],
            atlas: [0.0, 0.0, 2.0, 2.0],
            color: [1.0, 1.0, 1.0, 1.0],
            is_color: false,
        });
        frame.draw_order.push(DrawCommand::Glyph(0));

        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("teksilo_render_test_target"),
            size: wgpu::Extent3d {
                width: 32,
                height: 32,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8UnormSrgb,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());

        renderer.render(&frame, &view, 1.0, 32, 32, [0.0, 0.0, 0.0, 0.0]);

        let pixels = crate::test_support::read_texture_rgba(&device, &queue, &texture, 32, 32);
        let center = ((14 * 32 + 14) * 4) as usize;
        let blue_only = [
            pixels[center],
            pixels[center + 1],
            pixels[center + 2],
            pixels[center + 3],
        ];

        assert!(
            blue_only[0] > 200 && blue_only[1] > 200 && blue_only[2] > 200,
            "expected glyph pixel to be visible over shape, got {:?}",
            blue_only
        );
    }

    #[test]
    fn fractional_origin_glyph_renders_pixel_exact() {
        // Regression test for the linear-sampler blur / bottom-row crop:
        // glyph origins are fractional (shaping advances, scroll), and
        // with a bilinear atlas sampler an unsnapped 1:1 quad feathers
        // every edge and fades its last bitmap row into the transparent
        // atlas gutter (visibly cropping the bottom of "c"/"e"). The
        // pixel snap in `from_glyph_quad_transformed` must land the quad
        // on the integer grid so linear sampling is exact: interior
        // pixels fully opaque, surrounding pixels fully transparent.
        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_snap_test_device"),
        ) else {
            return;
        };

        // 4×4 atlas: a 3×3 fully-opaque white glyph bitmap at (0,0); the
        // remaining row/column transparent (the allocator's 1px gutter).
        let mut atlas = [0u8; 4 * 4 * 4];
        for y in 0..3 {
            for x in 0..3 {
                let i = (y * 4 + x) * 4;
                atlas[i..i + 4].copy_from_slice(&[255, 255, 255, 255]);
            }
        }
        renderer.upload_atlas(4, 4, &atlas);

        let mut frame = RenderFrame::new();
        // Fractional origin; the snap lands it at (10, 11).
        frame.glyphs.push(GlyphQuad {
            screen: [10.4, 10.6, 3.0, 3.0],
            atlas: [0.0, 0.0, 3.0, 3.0],
            color: [1.0, 1.0, 1.0, 1.0],
            is_color: false,
        });
        frame.draw_order.push(DrawCommand::Glyph(0));

        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("teksilo_render_snap_test_target"),
            size: wgpu::Extent3d {
                width: 32,
                height: 32,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8UnormSrgb,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());

        renderer.render(&frame, &view, 1.0, 32, 32, [0.0, 0.0, 0.0, 0.0]);

        let pixels = crate::test_support::read_texture_rgba(&device, &queue, &texture, 32, 32);
        let alpha = |x: usize, y: usize| pixels[(y * 32 + x) * 4 + 3];

        // Interior pixels exactly opaque — in particular the BOTTOM row
        // (y = 13), the one the unsnapped bilinear kernel used to fade
        // into the gutter.
        for y in 11..14 {
            for x in 10..13 {
                assert_eq!(
                    alpha(x, y),
                    255,
                    "interior pixel ({x},{y}) must be fully opaque — \
                     bilinear edge feathering means the snap did not fire"
                );
            }
        }
        // The one-pixel ring around the quad exactly transparent — no
        // feathered halo on any side.
        for y in 10..15 {
            for x in 9..14 {
                let inside = (10..13).contains(&x) && (11..14).contains(&y);
                if !inside {
                    assert_eq!(
                        alpha(x, y),
                        0,
                        "ring pixel ({x},{y}) must be untouched — \
                         the snapped quad must not bleed past its bitmap"
                    );
                }
            }
        }
    }

    /// The same guarantee for Tier-3 paths, which did not have it.
    ///
    /// Every SVG icon in an app is a path, and a path's quad used to be
    /// derived from `entry.bounds × scale_factor` while its bitmap was baked
    /// on its own integer grid. `Rect::expand` alone puts a line-style 16 dp
    /// icon's bounds on a half pixel, so the two disagreed by half a texel
    /// and the linear sampler smeared every stroke: a 1 px hairline peaked
    /// at 48 % coverage instead of 100 %, and a dashed ring's sub-pixel gaps
    /// closed up into a grey haze.
    ///
    /// A 1 px vertical stroke must therefore land as exactly one fully
    /// opaque column with nothing either side of it.
    #[test]
    fn fractional_origin_path_renders_pixel_exact() {
        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_path_snap_test_device"),
        ) else {
            return;
        };

        // A hairline centred on x = 8.5, so it covers exactly device column
        // 8. Its stroke-expanded bounds start at x = 7.5: the half pixel.
        let mut path = teksilo_canvas::Path::new();
        path.move_to(teksilo_canvas::Point::new(8.5, 4.0));
        path.line_to(teksilo_canvas::Point::new(8.5, 12.0));
        let stroke_style = teksilo_canvas::StrokeStyle::solid(1.0);
        let bounds = path.bounds().expand(stroke_style.width);
        assert_eq!(bounds.x, 7.5, "the half-pixel origin this test is about");

        let mut frame = RenderFrame::new();
        frame.paths.push(teksilo_canvas::PathEntry {
            path,
            color: [1.0, 1.0, 1.0, 1.0],
            stroke_style,
            fill_rule: teksilo_canvas::FillRule::Winding,
            bounds: bounds.to_array(),
            paint_data: teksilo_canvas::PaintData::Solid,
        });
        frame.draw_order.push(DrawCommand::Path(0));

        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("teksilo_render_path_snap_test_target"),
            size: wgpu::Extent3d {
                width: 32,
                height: 32,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8UnormSrgb,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());

        renderer.render(&frame, &view, 1.0, 32, 32, [0.0, 0.0, 0.0, 0.0]);

        let pixels = crate::test_support::read_texture_rgba(&device, &queue, &texture, 32, 32);
        let alpha = |x: usize, y: usize| pixels[(y * 32 + x) * 4 + 3];

        for y in 5..11 {
            assert_eq!(
                alpha(8, y),
                255,
                "the hairline's own column must be fully inked at y={y} — \
                 anything less means the quad was resampled off the pixel grid"
            );
            for x in [6, 7, 9, 10] {
                assert_eq!(
                    alpha(x, y),
                    0,
                    "({x},{y}) must be untouched — a 1 px stroke that leaks \
                     into its neighbours is the blur this snap removes"
                );
            }
        }
    }

    /// Render `frame` into a fresh 64×32 `Rgba8UnormSrgb` target cleared to
    /// transparent and read it back.
    fn render_to_pixels(
        renderer: &mut Renderer,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        frame: &RenderFrame,
    ) -> Vec<u8> {
        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("teksilo_render_blur_isolation_target"),
            size: wgpu::Extent3d {
                width: 64,
                height: 32,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8UnormSrgb,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
        renderer.render(frame, &view, 1.0, 64, 32, [0.0, 0.0, 0.0, 0.0]);
        crate::test_support::read_texture_rgba(device, queue, &texture, 64, 32)
    }

    /// Append a blur scope over `bounds` holding one opaque white square.
    fn push_blurred_square(
        frame: &mut RenderFrame,
        bounds: teksilo_canvas::Rect,
        radius: f32,
        square: teksilo_canvas::Rect,
    ) {
        frame
            .draw_order
            .push(DrawCommand::BeginBlurredSubtree { bounds, radius });
        let idx = frame.decorations.len();
        frame.decorations.push(teksilo_canvas::DecorationRect {
            rect: square.to_array(),
            color: [1.0, 1.0, 1.0, 1.0],
            kind: teksilo_canvas::DecorationKind::WidgetBackground,
        });
        frame.draw_order.push(DrawCommand::Decoration(idx));
        frame.draw_order.push(DrawCommand::EndBlurredSubtree);
    }

    #[test]
    fn a_blur_scope_does_not_take_the_kernel_of_a_later_one() {
        use teksilo_canvas::Rect;
        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_blur_isolation_device"),
        ) else {
            return; // no GPU adapter (headless CI) — skip.
        };

        // Scope A: 32 px wide, radius 6 → a 3-level chain.
        let a_bounds = Rect::new(0.0, 0.0, 32.0, 32.0);
        let a_square = Rect::new(12.0, 12.0, 8.0, 8.0);
        let mut alone = RenderFrame::new();
        push_blurred_square(&mut alone, a_bounds, 6.0, a_square);

        // The same scope followed by B: 16 px wide, radius 2 → a 1-level
        // chain whose passes sample a smaller texture, so a shared uniform
        // would hand A a kernel offset twice as wide.
        let mut followed = RenderFrame::new();
        push_blurred_square(&mut followed, a_bounds, 6.0, a_square);
        push_blurred_square(
            &mut followed,
            Rect::new(40.0, 8.0, 16.0, 16.0),
            2.0,
            Rect::new(44.0, 12.0, 8.0, 8.0),
        );

        let a_alone = render_to_pixels(&mut renderer, &device, &queue, &alone);
        let a_followed = render_to_pixels(&mut renderer, &device, &queue, &followed);
        let region = |pixels: &[u8]| -> Vec<u8> {
            (0..32)
                .flat_map(|y| pixels[y * 64 * 4..(y * 64 + 32) * 4].to_vec())
                .collect()
        };
        assert!(
            region(&a_alone).iter().any(|&b| b != 0),
            "scope A must have drawn something"
        );
        assert_eq!(
            region(&a_alone),
            region(&a_followed),
            "scope A must blur the same whatever blur scope follows it in the frame"
        );
    }

    #[test]
    fn each_kawase_pass_gets_its_own_parameter_slot() {
        let Some((_renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_blur_slots_device"),
        ) else {
            return; // no GPU adapter (headless CI) — skip.
        };
        let mut arena = crate::blur::KawaseParamArena::new(&device);
        // More passes than the initial capacity, so the buffer grows.
        let passes = crate::blur::PARAM_SLOTS_PER_SCOPE + 3;
        arena.begin_frame(&device, passes);
        let offsets: Vec<u32> = (0..passes)
            .map(|i| {
                let v = i as f32;
                arena.push(
                    &queue,
                    &crate::blur::BlurParams {
                        offset: [v, v + 0.5, 0.0, 0.0],
                    },
                )
            })
            .collect();
        let stride = arena.slot_stride();
        for (i, offset) in offsets.iter().enumerate() {
            assert_eq!(u64::from(*offset), stride * i as u64);
            assert_eq!(
                u64::from(*offset) % u64::from(device.limits().min_uniform_buffer_offset_alignment),
                0,
                "dynamic offsets must respect the device alignment"
            );
        }

        let size = arena.buffer().size();
        let readback = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("blur_params_readback"),
            size,
            usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        let mut encoder =
            device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: None });
        encoder.copy_buffer_to_buffer(arena.buffer(), 0, &readback, 0, size);
        queue.submit(Some(encoder.finish()));
        readback.slice(..).map_async(wgpu::MapMode::Read, |_| {});
        device
            .poll(wgpu::PollType::Wait {
                submission_index: None,
                timeout: None,
            })
            .expect("poll");
        let bytes = readback
            .slice(..)
            .get_mapped_range()
            .expect("mapped readback")
            .to_vec();
        for (i, offset) in offsets.iter().enumerate() {
            let at = *offset as usize;
            let slot: &[f32] = bytemuck::cast_slice(&bytes[at..at + 16]);
            assert_eq!(slot, &[i as f32, i as f32 + 0.5, 0.0, 0.0], "slot {i}");
        }
    }

    /// Render `frame` at `scale` into a `w`×`h` target cleared to
    /// transparent, returning a pixel reader.
    fn render_scaled(
        renderer: &mut Renderer,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        frame: &RenderFrame,
        scale: f32,
        (w, h): (u32, u32),
    ) -> impl Fn(u32, u32) -> [u8; 4] {
        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("teksilo_render_clip_target"),
            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::Rgba8UnormSrgb,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
        renderer.render(frame, &view, scale, w, h, [0.0, 0.0, 0.0, 0.0]);
        let pixels = crate::test_support::read_texture_rgba(device, queue, &texture, w, h);
        move |x, y| {
            let i = ((y * w + x) * 4) as usize;
            [pixels[i], pixels[i + 1], pixels[i + 2], pixels[i + 3]]
        }
    }

    fn push_white_rect(frame: &mut RenderFrame, rect: teksilo_canvas::Rect) {
        let idx = frame.decorations.len();
        frame.decorations.push(teksilo_canvas::DecorationRect {
            rect: rect.to_array(),
            color: [1.0, 1.0, 1.0, 1.0],
            kind: teksilo_canvas::DecorationKind::WidgetBackground,
        });
        frame.draw_order.push(DrawCommand::Decoration(idx));
    }

    #[test]
    fn a_clip_under_a_translation_lands_where_the_content_does_at_fractional_scale() {
        use teksilo_canvas::Rect;
        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_clip_translate_device"),
        ) else {
            return; // no GPU adapter (headless CI) — skip.
        };
        // A scope translated by 10 logical px clips a 40 px wide white rect to
        // its first 20 px. At scale 1.5 the content starts at device x = 15,
        // so the visible band is device x 15..45.
        let mut frame = RenderFrame::new();
        frame
            .draw_order
            .push(DrawCommand::PushTransform(Transform2D::translate(
                10.0, 0.0,
            )));
        frame
            .draw_order
            .push(DrawCommand::SetClip(Rect::new(0.0, 0.0, 20.0, 20.0)));
        push_white_rect(&mut frame, Rect::new(0.0, 0.0, 40.0, 20.0));
        frame.draw_order.push(DrawCommand::ClearClip);
        frame.draw_order.push(DrawCommand::PopTransform);

        let px = render_scaled(&mut renderer, &device, &queue, &frame, 1.5, (96, 40));
        assert_eq!(px(17, 10)[3], 255, "inside the clip, near its leading edge");
        assert_eq!(
            px(43, 10)[3],
            255,
            "inside the clip, near its trailing edge"
        );
        assert_eq!(px(47, 10)[3], 0, "past the clip's trailing edge");
        assert_eq!(px(12, 10)[3], 0, "before the content starts");
    }

    #[test]
    fn a_clip_still_applies_after_a_blur_scope_reopens_the_pass() {
        use teksilo_canvas::Rect;
        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_clip_after_blur_device"),
        ) else {
            return; // no GPU adapter (headless CI) — skip.
        };
        // A clip to x < 20 holds a blur scope and, after it, a full-width
        // white rect. The rect must stay clipped although the blur scope
        // ended the pass the clip was set on.
        let mut frame = RenderFrame::new();
        frame
            .draw_order
            .push(DrawCommand::SetClip(Rect::new(0.0, 0.0, 20.0, 32.0)));
        push_blurred_square(
            &mut frame,
            Rect::new(0.0, 0.0, 16.0, 16.0),
            2.0,
            Rect::new(4.0, 4.0, 8.0, 8.0),
        );
        push_white_rect(&mut frame, Rect::new(0.0, 20.0, 64.0, 12.0));
        frame.draw_order.push(DrawCommand::ClearClip);

        let px = render_scaled(&mut renderer, &device, &queue, &frame, 1.0, (64, 32));
        assert_eq!(px(10, 26)[3], 255, "inside the clip");
        assert_eq!(px(40, 26)[3], 0, "outside the clip");
    }

    #[test]
    fn a_clip_set_before_a_blur_scope_does_not_clip_inside_its_intermediate() {
        use teksilo_canvas::Rect;
        let Some((mut renderer, device, queue)) = pollster::block_on(
            crate::test_support::create_test_renderer("teksilo_render_clip_into_blur_device"),
        ) else {
            return; // no GPU adapter (headless CI) — skip.
        };
        // The clip (x 30..64) covers the right half of a blur scope placed at
        // x 30. Inside the intermediate the scope draws at its own origin, so
        // the surface-space clip rect (x >= 30) must not be applied there: it
        // would cut away everything left of intermediate x 30, here the whole
        // white square at intermediate x 2..14.
        let mut frame = RenderFrame::new();
        frame
            .draw_order
            .push(DrawCommand::SetClip(Rect::new(30.0, 0.0, 34.0, 32.0)));
        push_blurred_square(
            &mut frame,
            Rect::new(30.0, 0.0, 16.0, 16.0),
            2.0,
            Rect::new(32.0, 2.0, 12.0, 12.0),
        );
        frame.draw_order.push(DrawCommand::ClearClip);

        let px = render_scaled(&mut renderer, &device, &queue, &frame, 1.0, (64, 32));
        assert!(
            px(38, 8)[3] > 128,
            "the blurred square shows at the centre of the scope, got {:?}",
            px(38, 8)
        );
    }
}