damascene_wgpu/

lib.rs

//! `wgpu` backend for custom Damascene hosts.
//!
//! Most applications should implement `damascene_core::App` and run it
//! through `damascene-winit-wgpu`. Use this crate directly when you are
//! writing your own host, embedding Damascene into an existing `wgpu`
//! renderer, or producing headless render artifacts.
//!
//! The public entry point is [`Runner`]. It owns:
//!
//! - GPU resources: pipelines, buffers, text atlas, and icon atlas.
//! - Backend-agnostic interaction state shared through
//!   `damascene_core::runtime::RunnerCore`.
//! - A snapshot of the last laid-out tree so input arriving between
//!   frames hit-tests against the geometry the user can see.
//!
//! # Custom host loop
//!
//! The runner does not own the device, queue, swapchain, window, or
//! event loop. A host creates those resources, forwards input into the
//! runner, builds a fresh `El` tree, prepares GPU buffers, and renders:
//!
//! ```ignore
//! use damascene_core::prelude::*;
//! use damascene_wgpu::Runner;
//!
//! let mut runner = Runner::new(&device, &queue, surface_format);
//! runner.set_surface_size(surface_width, surface_height);
//!
//! // Per frame:
//! app.before_build();
//! let theme = app.theme();
//! let mut tree = app.build(&damascene_core::BuildCx::new(&theme));
//! runner.set_hotkeys(app.hotkeys());
//! runner.set_theme(theme);
//! runner.prepare(&device, &queue, &mut tree, viewport, scale_factor);
//! runner.render(&device, &mut encoder, target_texture, target_view, None, load_op);
//! ```
//!
//! `prepare` is split from `render`/`draw` so all `queue.write_buffer`
//! calls and atlas uploads happen before render-pass recording, matching
//! `wgpu`'s expected order. Coordinates passed to pointer methods are
//! logical pixels; render targets are physical pixels, so pass the host
//! scale factor to [`Runner::prepare`].
//!
//! Use [`Runner::render`] when Damascene should own pass boundaries. This is
//! required for backdrop-sampling custom shaders. Use [`Runner::draw`]
//! only when you are already inside a host-owned pass and do not need
//! backdrop sampling.
//!
//! # Custom shaders
//!
//! Call [`Runner::register_shader`] with a name and WGSL source. The
//! shader's vertex/fragment must use the shared instance layout — see
//! `shaders/rounded_rect.wgsl` (in damascene-core) for the canonical
//! example. Bind the shader at a node via
//! `El::shader(ShaderBinding::custom(name).with(...))`. Per-instance
//! uniforms map to three generic `vec4` slots:
//!
//! | Uniform key | Slot (`@location`) | Accepted types |
//! |---|---|---|
//! | `vec_a` | 2 | `Color` (rgba 0..1) or `Vec4` |
//! | `vec_b` | 3 | `Color` or `Vec4` |
//! | `vec_c` | 4 | `Vec4` (or fall back to scalar `f32` packed in `.x`) |
//!
//! Stock `rounded_rect` reuses the same layout but reads its own named
//! uniforms (`fill`, `stroke`, `stroke_width`, `radius`, `shadow`).

mod icon;
mod image;
mod instance;
mod msaa;
mod pipeline;
mod scene;
mod surface;
mod text;

pub use crate::msaa::MsaaTarget;
pub use crate::surface::{WgpuAppTexture, app_texture};

use std::collections::{HashMap, HashSet};
// `web_time::Instant` is API-identical to `std::time::Instant` on
// native and uses `performance.now()` on wasm32 — std's `Instant::now()`
// panics in the browser because there is no monotonic clock there.
use web_time::Instant;

use wgpu::util::DeviceExt;

use damascene_core::event::{KeyChord, KeyModifiers, Pointer, UiEvent, UiKey};
use damascene_core::ir::TextAnchor;
use damascene_core::paint::{IconRunKind, PhysicalScissor, QuadInstance};
use damascene_core::runtime::{RecordedPaint, RunnerCore, TextRecorder};
use damascene_core::shader::{ShaderHandle, StockShader, stock_wgsl};
use damascene_core::state::{AnimationMode, UiState};
use damascene_core::text::atlas::RunStyle;
use damascene_core::theme::Theme;
use damascene_core::tree::{Color, El, Rect, TextWrap};
use damascene_core::vector::IconMaterial;

pub use damascene_core::paint::PaintItem;
pub use damascene_core::runtime::{LayoutPrepared, PointerMove, PrepareResult, PrepareTimings};

use crate::icon::IconPaint;
use crate::image::ImagePaint;
use crate::instance::set_scissor;
use crate::pipeline::{FrameUniforms, build_quad_pipeline};
use crate::scene::Scene3DPaint;
use crate::surface::SurfacePaint;
use crate::text::TextPaint;

/// Initial size for the dynamic instance buffer (grows as needed).
const INITIAL_INSTANCE_CAPACITY: usize = 256;

/// Wgpu runtime owned by the host. One instance per surface/format.
///
/// All backend-agnostic state — interaction state, paint-stream scratch,
/// per-stage layout/animation hooks — lives in `core: RunnerCore` and
/// is shared with the vulkano backend. The fields below are wgpu-specific
/// resources only.
pub struct Runner {
    target_format: wgpu::TextureFormat,
    sample_count: u32,
    /// Whether the adapter advertises `DownlevelFlags::MULTISAMPLED_SHADING`.
    /// Threaded through to [`build_quad_pipeline`] so stock and custom
    /// shaders that use `@interpolate(perspective, sample)` get
    /// downlevelled (qualifier stripped) on backends that don't support
    /// per-sample shading — notably WebGL2 and most browser WebGPU
    /// adapters. See [`Self::with_caps`] for the host-side query.
    per_sample_shading: bool,

    // Shared resources.
    pipeline_layout: wgpu::PipelineLayout,
    /// Pipeline layout for `samples_backdrop` custom shaders — adds
    /// `@group(1)` for the snapshot texture + sampler.
    backdrop_pipeline_layout: wgpu::PipelineLayout,
    quad_bind_group: wgpu::BindGroup,
    backdrop_bind_layout: wgpu::BindGroupLayout,
    backdrop_sampler: wgpu::Sampler,
    frame_buf: wgpu::Buffer,
    quad_vbo: wgpu::Buffer,
    instance_buf: wgpu::Buffer,
    instance_capacity: usize,

    // One pipeline per registered shader (stock + custom).
    pipelines: HashMap<ShaderHandle, wgpu::RenderPipeline>,
    // Custom shader names registered with `samples_backdrop=true`. The
    // paint scheduler queries this to insert pass boundaries before the
    // first backdrop-sampling draw.
    backdrop_shaders: HashSet<&'static str>,
    // Custom shader names registered with `samples_time=true`. Mirrors
    // `backdrop_shaders` but feeds `prepare_layout`'s continuous-redraw
    // scan instead of the paint scheduler.
    time_shaders: HashSet<&'static str>,

    // stock::text resources — atlas, page textures, glyph instances.
    text_paint: TextPaint,
    // stock::icon_line resources — vector icon stroke instances.
    icon_paint: IconPaint,
    // stock::image resources — per-image texture cache + instance buf.
    image_paint: ImagePaint,
    surface_paint: SurfacePaint,
    // stock::scene resources — geometry buffer cache, per-node offscreen
    // targets, scene pipelines. Renders DrawOp::Scene3D offscreen and
    // composites the resolved texture through the surface path.
    scene_paint: Scene3DPaint,

    /// Lazily-allocated snapshot of the color target, sized to match
    /// the current target on each `render()`. Backdrop-sampling
    /// shaders read this via `@group(1)` after Pass A.
    snapshot: Option<SnapshotTexture>,
    /// Bind group binding the snapshot view + sampler. Rebuilt each
    /// time the snapshot texture is reallocated.
    backdrop_bind_group: Option<wgpu::BindGroup>,

    /// Wall-clock origin for the `time` field in `FrameUniforms`.
    /// `prepare()` writes `(now - start_time).as_secs_f32()`.
    start_time: Instant,

    // Backend-agnostic state shared with damascene-vulkano: interaction
    // state, paint-stream scratch (quad_scratch / runs / paint_items),
    // viewport_px, last_tree, the 13 input plumbing methods.
    core: RunnerCore,
}

struct SnapshotTexture {
    texture: wgpu::Texture,
    extent: (u32, u32),
}

struct PaintRecorder<'a> {
    text: &'a mut TextPaint,
    icons: &'a mut IconPaint,
    images: &'a mut ImagePaint,
    surfaces: &'a mut SurfacePaint,
    scenes: &'a mut Scene3DPaint,
    device: &'a wgpu::Device,
    queue: &'a wgpu::Queue,
}

impl TextRecorder for PaintRecorder<'_> {
    fn record(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        style: &damascene_core::text::atlas::RunStyle,
        text: &str,
        size: f32,
        line_height: f32,
        wrap: TextWrap,
        anchor: TextAnchor,
        scale_factor: f32,
    ) -> std::ops::Range<usize> {
        self.text.record(
            rect,
            scissor,
            style,
            text,
            size,
            line_height,
            wrap,
            anchor,
            scale_factor,
        )
    }

    fn record_runs(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        runs: &[(String, RunStyle)],
        size: f32,
        line_height: f32,
        wrap: TextWrap,
        anchor: TextAnchor,
        scale_factor: f32,
    ) -> std::ops::Range<usize> {
        self.text.record_runs(
            rect,
            scissor,
            runs,
            size,
            line_height,
            wrap,
            anchor,
            scale_factor,
        )
    }

    fn record_icon(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        source: &damascene_core::icons::svg::IconSource,
        color: Color,
        _size: f32,
        stroke_width: f32,
        _scale_factor: f32,
    ) -> RecordedPaint {
        RecordedPaint::Icon(
            self.icons
                .record(rect, scissor, source, color, stroke_width),
        )
    }

    fn record_image(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        image: &damascene_core::image::Image,
        tint: Option<Color>,
        radius: damascene_core::tree::Corners,
        _fit: damascene_core::image::ImageFit,
        _scale_factor: f32,
    ) -> std::ops::Range<usize> {
        self.images
            .record(self.device, self.queue, rect, scissor, image, tint, radius)
    }

    fn record_app_texture(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        texture: &damascene_core::surface::AppTexture,
        alpha: damascene_core::surface::SurfaceAlpha,
        transform: damascene_core::affine::Affine2,
        _scale_factor: f32,
    ) -> std::ops::Range<usize> {
        self.surfaces
            .record(self.device, rect, scissor, texture, alpha, transform)
    }

    fn record_vector(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        asset: &damascene_core::vector::VectorAsset,
        render_mode: damascene_core::vector::VectorRenderMode,
        _scale_factor: f32,
    ) -> std::ops::Range<usize> {
        self.icons.record_vector(rect, scissor, asset, render_mode)
    }

    fn record_scene3d(
        &mut self,
        rect: Rect,
        scissor: Option<PhysicalScissor>,
        id: &str,
        scene: &std::sync::Arc<damascene_core::scene::Scene3DData>,
        scale_factor: f32,
    ) -> std::ops::Range<usize> {
        self.scenes
            .record(self.device, rect, scissor, id, scene, scale_factor)
    }
}

impl Runner {
    /// Create a runner for the given target color format. The host
    /// passes its swapchain/render-target format here so pipelines and
    /// the glyph atlas are built compatible.
    pub fn new(
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        target_format: wgpu::TextureFormat,
    ) -> Self {
        Self::with_sample_count(device, queue, target_format, 1)
    }

    /// Like [`Self::new`], but builds all pipelines with `sample_count`
    /// MSAA samples. The host must provide a matching multisampled
    /// render target and a single-sample resolve target. `sample_count`
    /// of 1 is the non-MSAA default.
    ///
    /// Defaults `per_sample_shading` to `true` — appropriate for native
    /// adapters, where `DownlevelFlags::MULTISAMPLED_SHADING` is the norm.
    /// Web/WebGL2 hosts must instead route through [`Self::with_caps`]
    /// and pass the actual cap from the adapter, otherwise stock
    /// pipelines fail naga validation on shader-module creation.
    pub fn with_sample_count(
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        target_format: wgpu::TextureFormat,
        sample_count: u32,
    ) -> Self {
        Self::with_caps(device, queue, target_format, sample_count, true)
    }

    /// Like [`Self::with_sample_count`], but with the `per_sample_shading`
    /// downlevel cap supplied explicitly. Hosts that target backends
    /// without `DownlevelFlags::MULTISAMPLED_SHADING` (WebGL2, most
    /// browser WebGPU) read the flag off the adapter and pass it here:
    ///
    /// ```ignore
    /// let caps = adapter.get_downlevel_capabilities();
    /// let pss = caps.flags.contains(wgpu::DownlevelFlags::MULTISAMPLED_SHADING);
    /// Runner::with_caps(&device, &queue, format, sample_count, pss)
    /// ```
    ///
    /// When `false`, every pipeline (stock and later-registered custom)
    /// has `@interpolate(perspective, sample)` rewritten to
    /// `@interpolate(perspective)` before WGSL compilation. The shader
    /// then interpolates at pixel centre instead of per MSAA sample —
    /// MSAA coverage still works at `sample_count > 1`; only the
    /// per-sub-sample brightness pass is skipped, slightly thickening
    /// the AA band on curved SDF edges.
    pub fn with_caps(
        device: &wgpu::Device,
        _queue: &wgpu::Queue,
        target_format: wgpu::TextureFormat,
        sample_count: u32,
        per_sample_shading: bool,
    ) -> Self {
        // ---- Shared resources ----
        let frame_buf = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("damascene_wgpu::frame_uniforms"),
            size: std::mem::size_of::<FrameUniforms>() as u64,
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });

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

        let quad_bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("damascene_wgpu::frame_bind_group"),
            layout: &frame_bind_layout,
            entries: &[wgpu::BindGroupEntry {
                binding: 0,
                resource: frame_buf.as_entire_binding(),
            }],
        });

        let quad_vbo = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("damascene_wgpu::quad_vbo"),
            // Triangle strip: 4 corners, uv 0..1.
            contents: bytemuck::cast_slice::<f32, u8>(&[0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0]),
            usage: wgpu::BufferUsages::VERTEX,
        });

        let instance_buf = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("damascene_wgpu::instance_buf"),
            size: (INITIAL_INSTANCE_CAPACITY * std::mem::size_of::<QuadInstance>()) as u64,
            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });

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

        // ---- Backdrop sampling resources ----
        //
        // Custom shaders that opt into backdrop sampling (registered
        // via `register_shader_with(..samples_backdrop=true)`) get a
        // pipeline layout with `@group(1)` for the snapshot texture
        // and sampler. The bind group is rebuilt whenever the
        // snapshot is (re)allocated.
        let backdrop_bind_layout =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("damascene_wgpu::backdrop_bind_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 backdrop_pipeline_layout =
            device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                label: Some("damascene_wgpu::backdrop_pipeline_layout"),
                bind_group_layouts: &[Some(&frame_bind_layout), Some(&backdrop_bind_layout)],
                immediate_size: 0,
            });
        let backdrop_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("damascene_wgpu::backdrop_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()
        });

        // Build stock rect-shaped pipelines up-front; custom shaders are
        // added on demand by the host.
        let mut pipelines = HashMap::new();
        let rr_pipeline = build_quad_pipeline(
            device,
            &pipeline_layout,
            target_format,
            sample_count,
            "stock::rounded_rect",
            stock_wgsl::ROUNDED_RECT,
            per_sample_shading,
        );
        pipelines.insert(ShaderHandle::Stock(StockShader::RoundedRect), rr_pipeline);

        let spinner_pipeline = build_quad_pipeline(
            device,
            &pipeline_layout,
            target_format,
            sample_count,
            "stock::spinner",
            stock_wgsl::SPINNER,
            per_sample_shading,
        );
        pipelines.insert(ShaderHandle::Stock(StockShader::Spinner), spinner_pipeline);

        let skeleton_pipeline = build_quad_pipeline(
            device,
            &pipeline_layout,
            target_format,
            sample_count,
            "stock::skeleton",
            stock_wgsl::SKELETON,
            per_sample_shading,
        );
        pipelines.insert(
            ShaderHandle::Stock(StockShader::Skeleton),
            skeleton_pipeline,
        );

        let progress_indeterminate_pipeline = build_quad_pipeline(
            device,
            &pipeline_layout,
            target_format,
            sample_count,
            "stock::progress_indeterminate",
            stock_wgsl::PROGRESS_INDETERMINATE,
            per_sample_shading,
        );
        pipelines.insert(
            ShaderHandle::Stock(StockShader::ProgressIndeterminate),
            progress_indeterminate_pipeline,
        );

        // Text pipeline + atlas (replaces glyphon).
        let text_paint = TextPaint::new(device, target_format, sample_count, &frame_bind_layout);
        let icon_paint = IconPaint::new(device, target_format, sample_count, &frame_bind_layout);
        let image_paint = ImagePaint::new(device, target_format, sample_count, &frame_bind_layout);
        let surface_paint =
            SurfacePaint::new(device, target_format, sample_count, &frame_bind_layout);
        let scene_paint = Scene3DPaint::new(
            device,
            target_format,
            sample_count,
            &frame_bind_layout,
            damascene_core::paint::DEFAULT_WORKING_COLOR_SPACE,
        );

        let mut core = RunnerCore::new();
        core.quad_scratch = Vec::with_capacity(INITIAL_INSTANCE_CAPACITY);

        Self {
            target_format,
            sample_count,
            per_sample_shading,
            pipeline_layout,
            backdrop_pipeline_layout,
            quad_bind_group,
            backdrop_bind_layout,
            backdrop_sampler,
            frame_buf,
            quad_vbo,
            instance_buf,
            instance_capacity: INITIAL_INSTANCE_CAPACITY,
            pipelines,
            backdrop_shaders: HashSet::new(),
            time_shaders: HashSet::new(),
            text_paint,
            icon_paint,
            image_paint,
            surface_paint,
            scene_paint,
            snapshot: None,
            backdrop_bind_group: None,
            start_time: Instant::now(),
            core,
        }
    }

    /// Tell the runner the swapchain texture size in physical pixels.
    /// Call this once after `surface.configure(...)` and again on every
    /// `WindowEvent::Resized`. The runner uses this as the canonical
    /// `viewport_px` for scissor math; without it, the value is derived
    /// from `viewport.w * scale_factor`, which can drift by one pixel
    /// when `scale_factor` is fractional and trip wgpu's
    /// `set_scissor_rect` validation.
    pub fn set_surface_size(&mut self, width: u32, height: u32) {
        self.core.set_surface_size(width, height);
    }

    /// Set the color space the renderer composites in. Hosts call this
    /// once after negotiating a surface format with the display server
    /// (see `damascene-winit-wgpu`) and before the first frame. Updates the
    /// shared quad path (via `RunnerCore`) and this backend's text /
    /// icon / image color recorders so every color crosses the working-
    /// space boundary consistently.
    ///
    /// The working space must match how the swapchain interprets the
    /// pixels the renderer writes: `SRGB_LINEAR` for an `*_unorm_srgb`
    /// surface (the default), `SCRGB_LINEAR` / `DISPLAY_P3_LINEAR` for
    /// an `Rgba16Float` surface, etc.
    pub fn set_working_color_space(&mut self, space: damascene_core::color::ColorSpace) {
        self.core.set_working_color_space(space);
        self.text_paint.set_working_color_space(space);
        self.icon_paint.set_working_color_space(space);
        self.image_paint.set_working_color_space(space);
        self.scene_paint.set_working_color_space(space);
    }

    /// The color space the renderer currently composites in.
    pub fn working_color_space(&self) -> damascene_core::color::ColorSpace {
        self.core.working_color_space()
    }

    /// Set the theme used to resolve implicit widget surfaces to shaders.
    /// Pre-rasterize printable ASCII for the bundled default faces
    /// (Inter Variable + JetBrains Mono Variable). Pays the ~40ms
    /// one-time MSDF-generation cost up-front so the first frame that
    /// introduces each character doesn't take a 20-30ms paint hit.
    /// Hosts that interactively render UI text (the showcase, custom
    /// apps, etc.) should call this once after constructing the
    /// `Runner` and before the first frame; headless fixtures that
    /// render only static content can skip it. MSDF keys are
    /// size-independent so each character is rasterized exactly once
    /// and reused for every size + weight afterwards.
    pub fn warm_default_glyphs(&mut self) {
        self.text_paint.warm_default_glyphs();
    }

    pub fn set_theme(&mut self, theme: Theme) {
        self.icon_paint.set_material(theme.icon_material());
        self.core.set_theme(theme);
    }

    pub fn theme(&self) -> &Theme {
        self.core.theme()
    }

    /// Select the stock material used by the vector-icon painter.
    /// Prefer [`Theme::with_icon_material`] for app-level routing; this
    /// remains useful for low-level render fixtures.
    pub fn set_icon_material(&mut self, material: IconMaterial) {
        self.icon_paint.set_material(material);
    }

    pub fn icon_material(&self) -> IconMaterial {
        self.icon_paint.material()
    }

    /// Register a custom shader. `name` is the same string passed to
    /// `damascene_core::shader::ShaderBinding::custom`; nodes bound to it
    /// via [`El::shader`](damascene_core::tree::El) paint through this
    /// pipeline.
    ///
    /// The WGSL source must use the shared `(rect, vec_a, vec_b, vec_c)`
    /// instance layout and the `FrameUniforms` bind group described in
    /// the module docs. Compilation happens at register time — invalid
    /// WGSL panics here, not mid-frame.
    ///
    /// Re-registering the same name replaces the previous pipeline
    /// (useful for hot-reload during development).
    pub fn register_shader(&mut self, device: &wgpu::Device, name: &'static str, wgsl: &str) {
        self.register_shader_with(device, name, wgsl, false, false);
    }

    /// Register a custom shader, with opt-in flags for backdrop
    /// sampling and time-driven motion.
    ///
    /// `samples_backdrop=true` schedules the shader's draws into
    /// Pass B (after a snapshot of Pass A's rendered content) and
    /// binds the snapshot texture as `@group(2) binding=0`
    /// (`backdrop_tex`) plus a sampler at `binding=1`
    /// (`backdrop_smp`). See `docs/SHADER_VISION.md` §"Backdrop
    /// sampling architecture". Backdrop depth is capped at 1.
    ///
    /// `samples_time=true` declares that the shader's output depends
    /// on `frame.time`. The runtime ORs this into
    /// [`PrepareResult::needs_redraw`] for any frame that has at
    /// least one node bound to the shader, so the host idle loop
    /// keeps ticking without a per-El opt-in. Stock shaders self-
    /// report through [`damascene_core::shader::StockShader::is_continuous`];
    /// this flag is the same signal for app-registered WGSL.
    pub fn register_shader_with(
        &mut self,
        device: &wgpu::Device,
        name: &'static str,
        wgsl: &str,
        samples_backdrop: bool,
        samples_time: bool,
    ) {
        let label = format!("custom::{name}");
        let layout = if samples_backdrop {
            &self.backdrop_pipeline_layout
        } else {
            &self.pipeline_layout
        };
        let pipeline = build_quad_pipeline(
            device,
            layout,
            self.target_format,
            self.sample_count,
            &label,
            wgsl,
            self.per_sample_shading,
        );
        self.pipelines.insert(ShaderHandle::Custom(name), pipeline);
        if samples_backdrop {
            self.backdrop_shaders.insert(name);
        } else {
            self.backdrop_shaders.remove(name);
        }
        if samples_time {
            self.time_shaders.insert(name);
        } else {
            self.time_shaders.remove(name);
        }
    }

    /// Borrow the internal [`UiState`] — primarily for headless fixtures
    /// that want to look up a node's rect after `prepare` (e.g., to
    /// simulate a pointer at a specific button's center).
    pub fn ui_state(&self) -> &UiState {
        self.core.ui_state()
    }

    /// One-line diagnostic snapshot of interactive state — passes through
    /// to [`UiState::debug_summary`]. Intended for per-frame logging
    /// (e.g., `console.log` from the wasm host while debugging hover /
    /// animation glitches).
    pub fn debug_summary(&self) -> String {
        self.core.debug_summary()
    }

    /// Return the most recently laid-out rectangle for a keyed node.
    ///
    /// Call after [`Self::prepare`]. This is the host-composition hook:
    /// reserve a keyed Damascene element in the UI tree, ask for its rect
    /// here, then record host-owned rendering into that region using the
    /// same encoder / render flow that surrounds Damascene's pass.
    pub fn rect_of_key(&self, key: &str) -> Option<Rect> {
        self.core.rect_of_key(key)
    }

    /// Lay out the tree, resolve to draw ops, and upload per-frame
    /// buffers (quad instances + glyph atlas). Must be called before
    /// [`Self::draw`] and outside of any render pass.
    ///
    /// `viewport` is in **logical** pixels — the units the layout pass
    /// works in. `scale_factor` is the HiDPI multiplier (1.0 on a
    /// regular display, 2.0 on most modern HiDPI, can be fractional).
    /// The host's render-pass target should be sized at physical pixels
    /// (`viewport × scale_factor`); the runner maps logical → physical
    /// internally so layout, fonts, and SDF math stay device-independent.
    pub fn prepare(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        root: &mut El,
        viewport: Rect,
        scale_factor: f32,
    ) -> PrepareResult {
        let mut timings = PrepareTimings::default();

        // Install any scene depth maps that finished reading back (a frame
        // or two late) so this frame's `draw_ops` can occlude scene-anchored
        // labels behind geometry. Done before `prepare_layout` runs the
        // draw-op pass. Stale maps for scenes that left the tree are GC'd.
        let ready_depth = self.scene_paint.collect_depth_maps(device);
        if !ready_depth.is_empty() {
            let depth_maps = self.core.ui_state.scene_depth_mut();
            for (id, map) in ready_depth {
                depth_maps.insert(id, map);
            }
        }
        self.core
            .ui_state
            .scene_depth_mut()
            .retain(|id, _| self.scene_paint.has_target(id));

        // Layout + state apply + animation tick + draw_ops resolution.
        // Writes timings.layout + timings.draw_ops. The closure feeds
        // the runtime's continuous-redraw scan: any node bound to a
        // shader registered with `samples_time=true` keeps the host
        // loop ticking even when no animation is settling.
        let time_shaders = &self.time_shaders;
        let LayoutPrepared {
            ops,
            mut needs_redraw,
            mut next_layout_redraw_in,
            next_paint_redraw_in,
        } = self
            .core
            .prepare_layout(
                root,
                viewport,
                scale_factor,
                &mut timings,
                |handle| match handle {
                    ShaderHandle::Custom(name) => time_shaders.contains(name),
                    ShaderHandle::Stock(_) => false,
                },
            );

        // Paint stream: pack quads, record text, preserve z-order. The
        // closure is the wgpu-specific "is this shader registered?"
        // query (different pipeline types per backend prevent moving the
        // check itself into core).
        self.text_paint.frame_begin();
        self.icon_paint.frame_begin();
        self.image_paint.frame_begin();
        self.surface_paint.frame_begin();
        self.scene_paint.frame_begin();
        let pipelines = &self.pipelines;
        let backdrop_shaders = &self.backdrop_shaders;
        let mut recorder = PaintRecorder {
            text: &mut self.text_paint,
            icons: &mut self.icon_paint,
            images: &mut self.image_paint,
            surfaces: &mut self.surface_paint,
            scenes: &mut self.scene_paint,
            device,
            queue,
        };
        self.core.prepare_paint(
            &ops,
            |shader| pipelines.contains_key(shader),
            |shader| match shader {
                ShaderHandle::Custom(name) => backdrop_shaders.contains(name),
                ShaderHandle::Stock(_) => false,
            },
            &mut recorder,
            scale_factor,
            &mut timings,
        );

        // GPU upload — wgpu-specific. Resize the instance buffer if
        // needed, then write quad_scratch + frame uniforms + flush text
        // atlas dirty regions. Wrapped in its own scope so the
        // `prepare::gpu_upload` span doesn't bleed into the subsequent
        // `snapshot` call (which carries its own span).
        {
            damascene_core::profile_span!("prepare::gpu_upload");
            let t_paint_end = Instant::now();
            if self.core.quad_scratch.len() > self.instance_capacity {
                let new_cap = self.core.quad_scratch.len().next_power_of_two();
                self.instance_buf = device.create_buffer(&wgpu::BufferDescriptor {
                    label: Some("damascene_wgpu::instance_buf (resized)"),
                    size: (new_cap * std::mem::size_of::<QuadInstance>()) as u64,
                    usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
                    mapped_at_creation: false,
                });
                self.instance_capacity = new_cap;
            }
            if !self.core.quad_scratch.is_empty() {
                queue.write_buffer(
                    &self.instance_buf,
                    0,
                    bytemuck::cast_slice(&self.core.quad_scratch),
                );
            }
            self.text_paint.flush(device, queue);
            self.icon_paint.flush(device, queue);
            self.image_paint.flush(device, queue);
            self.surface_paint.flush(device, queue);
            self.scene_paint.flush(device, queue);
            // Pin time to 0 in Settled mode so headless fixtures rendering
            // a time-driven shader (e.g. stock::spinner) stay byte-identical
            // run-to-run, the same way `Animation::settle()` makes the
            // spring/tween path deterministic for SVG/PNG snapshots.
            let time = match self.core.ui_state().animation_mode() {
                damascene_core::AnimationMode::Settled => 0.0,
                damascene_core::AnimationMode::Live => {
                    (Instant::now() - self.start_time).as_secs_f32()
                }
            };
            let frame = FrameUniforms {
                viewport: [viewport.w, viewport.h],
                time,
                scale_factor,
            };
            queue.write_buffer(&self.frame_buf, 0, bytemuck::bytes_of(&frame));
            timings.gpu_upload = Instant::now() - t_paint_end;
        }

        // Snapshot the laid-out tree for next-frame hit-testing.
        self.core.snapshot(root, &mut timings);

        // Move resolved ops into the core's cache so a subsequent
        // paint-only frame can reuse them without re-running layout.
        self.core.last_ops = ops;

        // Damascene renders lazily, but the label-occlusion depth read-back needs
        // a few frames to resolve. Keep frames coming until every labelled
        // scene has a depth map matching its current pose — otherwise a
        // capture started in `render` would sit unmapped after the camera
        // settles and the labels would never appear. Settled + current scenes
        // (and label-free ones) report `false`, so lazy idle is preserved.
        //
        // This must drive `next_layout_redraw_in`, not just `needs_redraw`:
        // hosts schedule the next frame off the deadline lanes (the winit
        // host ignores `needs_redraw`), and it must be the *layout* lane, not
        // the paint lane — the paint-only `repaint` path skips
        // `collect_depth_maps`, so only a full `prepare` advances the readback.
        if self.scene_paint.occlusion_unsettled() {
            needs_redraw = true;
            next_layout_redraw_in = Some(std::time::Duration::ZERO);
        }

        let next_redraw_in = match (next_layout_redraw_in, next_paint_redraw_in) {
            (Some(a), Some(b)) => Some(a.min(b)),
            (Some(d), None) | (None, Some(d)) => Some(d),
            (None, None) => None,
        };
        PrepareResult {
            needs_redraw,
            next_redraw_in,
            next_layout_redraw_in,
            next_paint_redraw_in,
            timings,
        }
    }

    /// Paint-only frame: rerun [`RunnerCore::prepare_paint_cached`] +
    /// GPU upload + frame-uniform write against the cached ops from
    /// the most recent [`Self::prepare`] call. Skips rebuild + layout
    /// + draw_ops + snapshot — only `frame.time` advances.
    ///
    /// Hosts call this when [`PrepareResult::next_paint_redraw_in`]
    /// fires (a time-driven shader needs another frame) and no input
    /// has been processed since the last full prepare. Input always
    /// upgrades to the full `prepare(...)` path.
    ///
    /// `viewport` and `scale_factor` must match the values passed to
    /// the most recent `prepare(...)` — a resize must go through the
    /// full layout path. Returns the same shape of [`PrepareResult`]
    /// for diagnostic continuity, with both deadlines re-computed
    /// from the cached signals: `next_layout_redraw_in` is `None` (we
    /// didn't re-evaluate), and `next_paint_redraw_in` is whatever
    /// the cached ops still report. The host owns the layout
    /// deadline across paint-only frames.
    pub fn repaint(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        viewport: Rect,
        scale_factor: f32,
    ) -> PrepareResult {
        let mut timings = PrepareTimings::default();

        self.text_paint.frame_begin();
        self.icon_paint.frame_begin();
        self.image_paint.frame_begin();
        self.surface_paint.frame_begin();
        self.scene_paint.frame_begin();
        let pipelines = &self.pipelines;
        let backdrop_shaders = &self.backdrop_shaders;
        let mut recorder = PaintRecorder {
            text: &mut self.text_paint,
            icons: &mut self.icon_paint,
            images: &mut self.image_paint,
            surfaces: &mut self.surface_paint,
            scenes: &mut self.scene_paint,
            device,
            queue,
        };
        self.core.prepare_paint_cached(
            |shader| pipelines.contains_key(shader),
            |shader| match shader {
                ShaderHandle::Custom(name) => backdrop_shaders.contains(name),
                ShaderHandle::Stock(_) => false,
            },
            &mut recorder,
            scale_factor,
            &mut timings,
        );

        // Same GPU-upload block as prepare(); time advances even though
        // ops are unchanged so time-driven shaders animate.
        {
            damascene_core::profile_span!("repaint::gpu_upload");
            let t_paint_end = Instant::now();
            if self.core.quad_scratch.len() > self.instance_capacity {
                let new_cap = self.core.quad_scratch.len().next_power_of_two();
                self.instance_buf = device.create_buffer(&wgpu::BufferDescriptor {
                    label: Some("damascene_wgpu::instance_buf (resized)"),
                    size: (new_cap * std::mem::size_of::<QuadInstance>()) as u64,
                    usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
                    mapped_at_creation: false,
                });
                self.instance_capacity = new_cap;
            }
            if !self.core.quad_scratch.is_empty() {
                queue.write_buffer(
                    &self.instance_buf,
                    0,
                    bytemuck::cast_slice(&self.core.quad_scratch),
                );
            }
            self.text_paint.flush(device, queue);
            self.icon_paint.flush(device, queue);
            self.image_paint.flush(device, queue);
            self.surface_paint.flush(device, queue);
            self.scene_paint.flush(device, queue);
            let time = match self.core.ui_state().animation_mode() {
                AnimationMode::Settled => 0.0,
                AnimationMode::Live => (Instant::now() - self.start_time).as_secs_f32(),
            };
            let frame = FrameUniforms {
                viewport: [viewport.w, viewport.h],
                time,
                scale_factor,
            };
            queue.write_buffer(&self.frame_buf, 0, bytemuck::bytes_of(&frame));
            timings.gpu_upload = Instant::now() - t_paint_end;
        }

        // Re-evaluate the paint lane against the cached ops so the host
        // can re-arm the deadline. Cheap (one scan over already-resolved
        // ops). The layout lane is left as `None`: we didn't re-run
        // `prepare_layout`, so we have no fresh signal to report — the
        // host's previously-set layout deadline still stands.
        let time_shaders = &self.time_shaders;
        let next_paint_redraw_in = self.core.scan_continuous_shaders(|handle| match handle {
            ShaderHandle::Custom(name) => time_shaders.contains(name),
            ShaderHandle::Stock(_) => false,
        });
        PrepareResult {
            needs_redraw: next_paint_redraw_in.is_some(),
            next_redraw_in: next_paint_redraw_in,
            next_layout_redraw_in: None,
            next_paint_redraw_in,
            timings,
        }
    }

    // ---- Input plumbing ----
    //
    // The host (winit-side) calls these from its event loop.
    // Coordinates are **logical pixels** — divide winit's physical
    // PhysicalPosition by the window scale factor before handing them in.

    /// Update pointer position and recompute the hovered key.
    /// Returns the new hovered key, if any (host can use it for cursor
    /// styling or to decide whether to call `request_redraw`).
    /// Pointer moved to `p.x, p.y` (logical px). Returns the events to
    /// dispatch via `App::on_event` plus a `needs_redraw` flag — see
    /// [`PointerMove`] for why hosts must gate `request_redraw` on
    /// the flag. The hovered node is updated on `ui_state().hovered`
    /// regardless. Mouse-only hosts can construct `p` via
    /// [`Pointer::moving`].
    pub fn pointer_moved(&mut self, p: Pointer) -> PointerMove {
        self.core.pointer_moved(p)
    }

    /// Pointer left the window — clear hover/press. Returns a
    /// `PointerLeave` event for the previously hovered target (when
    /// there was one); hosts should route the events through
    /// `App::on_event` like the other pointer entry points.
    pub fn pointer_left(&mut self) -> Vec<damascene_core::UiEvent> {
        self.core.pointer_left()
    }

    /// File is being dragged over the window. Hosts call this from
    /// `winit::WindowEvent::HoveredFile` (one call per file). Returns
    /// the `FileHovered` event routed to the keyed leaf at the cursor
    /// (or window-level if outside any keyed surface).
    pub fn file_hovered(
        &mut self,
        path: std::path::PathBuf,
        x: f32,
        y: f32,
    ) -> Vec<damascene_core::UiEvent> {
        self.core.file_hovered(path, x, y)
    }

    /// File hover ended without a drop — hosts call this from
    /// `winit::WindowEvent::HoveredFileCancelled`. Window-level event
    /// (not routed); apps clear any drop-zone affordance.
    pub fn file_hover_cancelled(&mut self) -> Vec<damascene_core::UiEvent> {
        self.core.file_hover_cancelled()
    }

    /// File was dropped on the window. Hosts call this from
    /// `winit::WindowEvent::DroppedFile` (one call per file).
    pub fn file_dropped(
        &mut self,
        path: std::path::PathBuf,
        x: f32,
        y: f32,
    ) -> Vec<damascene_core::UiEvent> {
        self.core.file_dropped(path, x, y)
    }

    /// Whether a primary press at `(x, y)` (logical px) would land
    /// on a node that opted into `capture_keys` — the marker the
    /// library uses for text-input-style widgets. Hosts query this
    /// from a DOM pointerdown handler to decide whether to focus
    /// a hidden textarea (so the soft keyboard can open in the
    /// user-gesture context). See
    /// [`RunnerCore::would_press_focus_text_input`] for details.
    pub fn would_press_focus_text_input(&self, x: f32, y: f32) -> bool {
        self.core.would_press_focus_text_input(x, y)
    }

    /// Whether the currently focused node is a text-input-style
    /// widget (i.e. has `capture_keys` set). Hosts mirror this each
    /// frame into platform affordances such as the on-screen
    /// keyboard or IME compose-window placement.
    pub fn focused_captures_keys(&self) -> bool {
        self.core.focused_captures_keys()
    }

    /// Pointer pressed at `p.x, p.y` (logical px) for `p.button`. For
    /// `Primary`, records the pressed key for press-visual feedback,
    /// updates focus, and returns a `PointerDown` event so widgets that
    /// need to react at down-time (text input selection anchor,
    /// draggable handles) can do so. For `Secondary` / `Middle`, records
    /// on a side channel and returns `None`. The actual click event
    /// fires on `pointer_up`. Mouse-only hosts can construct `p` via
    /// [`Pointer::mouse`].
    pub fn pointer_down(&mut self, p: Pointer) -> Vec<UiEvent> {
        self.core.pointer_down(p)
    }

    /// Replace the tracked modifier mask. Hosts call this from their
    /// platform's "modifiers changed" hook so subsequent pointer
    /// events (PointerDown, Drag, Click, …) stamp the current mask
    /// into `UiEvent.modifiers`.
    pub fn set_modifiers(&mut self, modifiers: KeyModifiers) {
        self.core.ui_state.set_modifiers(modifiers);
    }

    /// Pointer released at `p.x, p.y` for `p.button`. Returns the
    /// events the host should dispatch in order: for `Primary`, always
    /// a `PointerUp` (when there was a corresponding down) followed
    /// by an optional `Click` (when the up landed on the down's
    /// node). For `Secondary` / `Middle`, an optional `SecondaryClick`
    /// / `MiddleClick` on the same-node match. Mouse-only hosts can
    /// construct `p` via [`Pointer::mouse`].
    pub fn pointer_up(&mut self, p: Pointer) -> Vec<UiEvent> {
        self.core.pointer_up(p)
    }

    pub fn key_down(&mut self, key: UiKey, modifiers: KeyModifiers, repeat: bool) -> Vec<UiEvent> {
        self.core.key_down(key, modifiers, repeat)
    }

    /// Forward an OS-composed text-input string (winit's keyboard event
    /// `.text` field, or an `Ime::Commit`) to the focused element as a
    /// `TextInput` event.
    pub fn text_input(&mut self, text: String) -> Option<UiEvent> {
        self.core.text_input(text)
    }

    /// Replace the hotkey registry. Call once per frame, after `app.build()`,
    /// passing `app.hotkeys()` so chords stay in sync with state.
    pub fn set_hotkeys(&mut self, hotkeys: Vec<(KeyChord, String)>) {
        self.core.set_hotkeys(hotkeys);
    }

    /// Push the app's current selection to the runtime so the painter
    /// can draw highlight bands. Hosts call this once per frame
    /// alongside [`Self::set_hotkeys`].
    pub fn set_selection(&mut self, selection: damascene_core::selection::Selection) {
        self.core.set_selection(selection);
    }

    /// Resolve the runtime's current selection to a text payload from
    /// the most recently laid-out tree. See
    /// [`RunnerCore::selected_text`] — virtual-list rows are realized
    /// during layout, so a freshly built app tree would miss them and
    /// a `Ctrl+C` lookup that walked it would silently come back empty.
    pub fn selected_text(&self) -> Option<String> {
        self.core.selected_text()
    }

    /// Resolve an explicit [`damascene_core::selection::Selection`] against
    /// the last laid-out tree. See [`RunnerCore::selected_text_for`].
    pub fn selected_text_for(
        &self,
        selection: &damascene_core::selection::Selection,
    ) -> Option<String> {
        self.core.selected_text_for(selection)
    }

    /// Queue toast specs onto the runtime's toast stack. Hosts call
    /// this once per frame with `app.drain_toasts()`. Each spec is
    /// stamped with a monotonic id and an `expires_at` deadline
    /// (`now + ttl`); the next `prepare` call drops expired entries
    /// and synthesizes a `toast_stack` floating layer over the rest.
    pub fn push_toasts(&mut self, specs: Vec<damascene_core::toast::ToastSpec>) {
        self.core.push_toasts(specs);
    }

    /// Programmatically dismiss a toast by id. Useful for cancelling
    /// long-TTL toasts when an external condition resolves (e.g.,
    /// "reconnecting…" turning into "connected").
    pub fn dismiss_toast(&mut self, id: u64) {
        self.core.dismiss_toast(id);
    }

    /// Queue programmatic focus requests by widget key. Hosts call
    /// this once per frame with `app.drain_focus_requests()`. Each
    /// key is resolved during the next `prepare` against the rebuilt
    /// focus order; unmatched keys drop silently.
    pub fn push_focus_requests(&mut self, keys: Vec<String>) {
        self.core.push_focus_requests(keys);
    }

    /// Queue programmatic scroll-to-row requests targeting virtual
    /// lists by key. Hosts call this once per frame with
    /// `app.drain_scroll_requests()`. Each request is consumed during
    /// the next `prepare` by the layout pass for the matching list,
    /// where viewport height and row heights are known. Unmatched
    /// list keys and out-of-range row indices drop silently.
    pub fn push_scroll_requests(&mut self, requests: Vec<damascene_core::scroll::ScrollRequest>) {
        self.core.push_scroll_requests(requests);
    }

    /// Switch animation pacing. Default is [`AnimationMode::Live`].
    /// Headless render binaries should call this with
    /// [`AnimationMode::Settled`] so a single-frame snapshot reflects
    /// the post-animation visual without depending on integrator timing.
    pub fn set_animation_mode(&mut self, mode: AnimationMode) {
        self.core.set_animation_mode(mode);
    }

    /// Apply a wheel delta in **logical** pixels at `(x, y)`. Routes to
    /// the deepest scrollable container under the cursor in the last
    /// laid-out tree. Returns `true` if the event landed on a scrollable
    /// (host should `request_redraw` so the next frame applies the new
    /// offset).
    pub fn pointer_wheel(&mut self, x: f32, y: f32, dy: f32) -> bool {
        self.core.pointer_wheel(x, y, dy)
    }

    /// Build a routed wheel event for the keyed target under `(x, y)`.
    ///
    /// Dispatch this before [`Self::pointer_wheel`]; if the app
    /// consumes the event, skip the fallback scroll call.
    pub fn pointer_wheel_event(
        &mut self,
        x: f32,
        y: f32,
        dx: f32,
        dy: f32,
    ) -> Option<damascene_core::UiEvent> {
        self.core.pointer_wheel_event(x, y, dx, dy)
    }

    /// Drain time-driven input events whose deadline has passed (touch
    /// long-press today; later: hold-to-repeat, etc.). Hosts call this
    /// once per frame before dispatching pointer events. `now` is
    /// `web_time::Instant` rather than `std::time::Instant` so the
    /// signature compiles on wasm32 — `web_time` aliases to std on
    /// native, so existing native callers passing `Instant::now()`
    /// from std still work. See [`damascene_core::RunnerCore::poll_input`].
    pub fn poll_input(&mut self, now: web_time::Instant) -> Vec<damascene_core::UiEvent> {
        self.core.poll_input(now)
    }

    /// Record draws into the host-managed render pass. Call after
    /// [`Self::prepare`]. Paint order follows the draw-op stream.
    ///
    /// **No backdrop sampling.** This entry point cannot honor pass
    /// boundaries (the host owns the pass lifetime), so any
    /// `BackdropSnapshot` items in the paint stream are no-ops and any
    /// shader bound with `samples_backdrop=true` reads an undefined
    /// backdrop binding. Use [`Self::render`] for backdrop-aware
    /// rendering.
    pub fn draw<'pass>(&'pass self, pass: &mut wgpu::RenderPass<'pass>) {
        self.draw_items(pass, &self.core.paint_items);
    }

    /// Record draws into a host-supplied encoder, owning pass
    /// lifetimes ourselves so backdrop-sampling shaders can sample a
    /// snapshot of Pass A's content.
    ///
    /// The host hands us:
    /// - the encoder (we record into it),
    /// - the color target's `wgpu::Texture` (used as `copy_src` when
    ///   we snapshot it; must include `COPY_SRC` in its usage flags),
    /// - the corresponding `wgpu::TextureView` (we attach it to every
    ///   render pass we begin), and
    /// - the `LoadOp` to use on the *first* pass — `Clear(color)` to
    ///   clear behind us, `Load` to composite onto whatever was
    ///   already in the target.
    ///
    /// Multi-pass schedule when the paint stream contains a
    /// `BackdropSnapshot`:
    ///
    /// 1. Pass A — every paint item before the snapshot, with the
    ///    caller-supplied `LoadOp`.
    /// 2. `copy_texture_to_texture` — target → snapshot.
    /// 3. Pass B — paint items from the snapshot onward, with
    ///    `LoadOp::Load` so Pass A's pixels remain underneath.
    ///
    /// Without a snapshot, this collapses to a single pass and is
    /// equivalent to [`Self::draw`] called inside a host-managed
    /// pass with the same `LoadOp`.
    pub fn render(
        &mut self,
        device: &wgpu::Device,
        encoder: &mut wgpu::CommandEncoder,
        target_tex: &wgpu::Texture,
        target_view: &wgpu::TextureView,
        msaa_view: Option<&wgpu::TextureView>,
        load_op: wgpu::LoadOp<wgpu::Color>,
    ) {
        // When MSAA is in use, the actual color attachment is the
        // multisampled view and `target_view` becomes its resolve
        // target. `target_tex` is always the resolved (single-sample)
        // texture, so the snapshot copy below works whether MSAA is on
        // or not — the resolve happens at end-of-Pass-A.
        let attachment_view = msaa_view.unwrap_or(target_view);
        let resolve_target = msaa_view.map(|_| target_view);

        // Phase 1: render every recorded 3D scene into its own offscreen
        // target. Passes can't nest, so this is encoded on `encoder` ahead
        // of the main composite pass (same discipline as BackdropSnapshot).
        // The `PaintItem::Scene3D` arm below then composites the resolved
        // textures into the main pass.
        if self.scene_paint.has_runs() {
            self.scene_paint.encode_offscreen(encoder);
            // Capture each label-bearing scene's depth into its read-back
            // buffer (the depth is still alive from the pass above). The
            // map + CPU read happens next frame in `prepare`.
            self.scene_paint.encode_depth_capture(device, encoder);
        }

        // Locate the (at most one) snapshot boundary.
        let split_at = self
            .core
            .paint_items
            .iter()
            .position(|p| matches!(p, PaintItem::BackdropSnapshot));

        if let Some(idx) = split_at {
            self.ensure_snapshot(device, target_tex);
            // Pass A
            {
                let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                    label: Some("damascene_wgpu::pass_a"),
                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                        view: attachment_view,
                        resolve_target,
                        depth_slice: None,
                        ops: wgpu::Operations {
                            load: load_op,
                            store: wgpu::StoreOp::Store,
                        },
                    })],
                    depth_stencil_attachment: None,
                    timestamp_writes: None,
                    occlusion_query_set: None,
                    multiview_mask: None,
                });
                self.draw_items(&mut pass, &self.core.paint_items[..idx]);
            }
            // Snapshot copy. Target must support COPY_SRC; snapshot
            // texture (created in `ensure_snapshot`) supports COPY_DST
            // + TEXTURE_BINDING.
            let snapshot = self.snapshot.as_ref().expect("snapshot ensured");
            encoder.copy_texture_to_texture(
                wgpu::TexelCopyTextureInfo {
                    texture: target_tex,
                    mip_level: 0,
                    origin: wgpu::Origin3d::ZERO,
                    aspect: wgpu::TextureAspect::All,
                },
                wgpu::TexelCopyTextureInfo {
                    texture: &snapshot.texture,
                    mip_level: 0,
                    origin: wgpu::Origin3d::ZERO,
                    aspect: wgpu::TextureAspect::All,
                },
                wgpu::Extent3d {
                    width: snapshot.extent.0,
                    height: snapshot.extent.1,
                    depth_or_array_layers: 1,
                },
            );
            // Pass B
            {
                let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                    label: Some("damascene_wgpu::pass_b"),
                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                        view: attachment_view,
                        resolve_target,
                        depth_slice: None,
                        ops: wgpu::Operations {
                            load: wgpu::LoadOp::Load,
                            store: wgpu::StoreOp::Store,
                        },
                    })],
                    depth_stencil_attachment: None,
                    timestamp_writes: None,
                    occlusion_query_set: None,
                    multiview_mask: None,
                });
                // Skip the snapshot item itself; it's a marker, not a draw.
                self.draw_items(&mut pass, &self.core.paint_items[idx + 1..]);
            }
        } else {
            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("damascene_wgpu::pass"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: attachment_view,
                    resolve_target,
                    depth_slice: None,
                    ops: wgpu::Operations {
                        load: load_op,
                        store: wgpu::StoreOp::Store,
                    },
                })],
                depth_stencil_attachment: None,
                timestamp_writes: None,
                occlusion_query_set: None,
                multiview_mask: None,
            });
            self.draw_items(&mut pass, &self.core.paint_items);
        }
    }

    /// (Re)allocate the snapshot texture to match `target_tex`'s
    /// extent + format. Idempotent when the size matches; rebuilds the
    /// `backdrop_bind_group` whenever the snapshot is recreated.
    fn ensure_snapshot(&mut self, device: &wgpu::Device, target_tex: &wgpu::Texture) {
        let extent = target_tex.size();
        let want = (extent.width, extent.height);
        if let Some(s) = &self.snapshot
            && s.extent == want
        {
            return;
        }
        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("damascene_wgpu::backdrop_snapshot"),
            size: wgpu::Extent3d {
                width: want.0,
                height: want.1,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: self.target_format,
            usage: wgpu::TextureUsages::COPY_DST | wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
        let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("damascene_wgpu::backdrop_bind_group"),
            layout: &self.backdrop_bind_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.backdrop_sampler),
                },
            ],
        });
        self.snapshot = Some(SnapshotTexture {
            texture,
            extent: want,
        });
        self.backdrop_bind_group = Some(bind_group);
    }

    /// Walk a slice of `PaintItem`s into the given pass. Helper shared
    /// by [`Self::draw`] and [`Self::render`]. `BackdropSnapshot`
    /// items are no-ops here; `render()` handles them by splitting
    /// the slice before passing to this helper.
    fn draw_items<'pass>(
        &'pass self,
        pass: &mut wgpu::RenderPass<'pass>,
        items: &'pass [PaintItem],
    ) {
        let full = PhysicalScissor {
            x: 0,
            y: 0,
            w: self.core.viewport_px.0,
            h: self.core.viewport_px.1,
        };
        for item in items {
            match *item {
                PaintItem::QuadRun(index) => {
                    let run = &self.core.runs[index];
                    set_scissor(pass, run.scissor, full);
                    pass.set_bind_group(0, &self.quad_bind_group, &[]);
                    let is_backdrop_shader = matches!(
                        run.handle,
                        ShaderHandle::Custom(name) if self.backdrop_shaders.contains(name)
                    );
                    if is_backdrop_shader && let Some(bg) = &self.backdrop_bind_group {
                        pass.set_bind_group(1, bg, &[]);
                    }
                    pass.set_vertex_buffer(0, self.quad_vbo.slice(..));
                    pass.set_vertex_buffer(1, self.instance_buf.slice(..));
                    let pipeline = self
                        .pipelines
                        .get(&run.handle)
                        .expect("run handle has no pipeline (bug in prepare)");
                    pass.set_pipeline(pipeline);
                    pass.draw(0..4, run.first..run.first + run.count);
                }
                PaintItem::Text(index) => {
                    let run = self.text_paint.run(index);
                    set_scissor(pass, run.scissor, full);
                    pass.set_pipeline(self.text_paint.pipeline_for(run.kind));
                    pass.set_bind_group(0, &self.quad_bind_group, &[]);
                    // Highlight runs use a frame-uniform-only pipeline.
                    // Glyph kinds bind the active atlas page at group 1.
                    if !matches!(run.kind, crate::text::TextRunKind::Highlight) {
                        pass.set_bind_group(
                            1,
                            self.text_paint.page_bind_group(run.kind, run.page),
                            &[],
                        );
                    }
                    pass.set_vertex_buffer(0, self.quad_vbo.slice(..));
                    pass.set_vertex_buffer(1, self.text_paint.instance_buf_for(run.kind).slice(..));
                    pass.draw(0..4, run.first..run.first + run.count);
                }
                PaintItem::IconRun(index) | PaintItem::Vector(index) => {
                    // `PaintItem::Vector` is structurally identical to
                    // `PaintItem::IconRun` — both index into the same
                    // `IconPaint::runs` Vec since `record_vector`
                    // appends there too. The variant is kept distinct
                    // for paint-stream provenance (icon vs app vector)
                    // but the dispatch is the same.
                    let run = self.icon_paint.run(index);
                    set_scissor(pass, run.scissor, full);
                    match run.kind {
                        IconRunKind::Tess => {
                            pass.set_pipeline(self.icon_paint.tess_pipeline(run.material));
                            pass.set_bind_group(0, &self.quad_bind_group, &[]);
                            pass.set_vertex_buffer(0, self.icon_paint.tess_vertex_buf().slice(..));
                            pass.draw(run.first..run.first + run.count, 0..1);
                        }
                        IconRunKind::Msdf => {
                            pass.set_pipeline(self.icon_paint.msdf_pipeline());
                            pass.set_bind_group(0, &self.quad_bind_group, &[]);
                            pass.set_bind_group(
                                1,
                                self.icon_paint.msdf_page_bind_group(run.page),
                                &[],
                            );
                            pass.set_vertex_buffer(0, self.quad_vbo.slice(..));
                            pass.set_vertex_buffer(
                                1,
                                self.icon_paint.msdf_instance_buf().slice(..),
                            );
                            pass.draw(0..4, run.first..run.first + run.count);
                        }
                    }
                }
                PaintItem::Image(index) => {
                    let run = self.image_paint.run(index);
                    set_scissor(pass, run.scissor, full);
                    pass.set_pipeline(self.image_paint.pipeline());
                    pass.set_bind_group(0, &self.quad_bind_group, &[]);
                    pass.set_bind_group(1, self.image_paint.bind_group_for_run(run), &[]);
                    pass.set_vertex_buffer(0, self.quad_vbo.slice(..));
                    pass.set_vertex_buffer(1, self.image_paint.instance_buf().slice(..));
                    pass.draw(0..4, run.first..run.first + run.count);
                }
                PaintItem::AppTexture(index) => {
                    let run = self.surface_paint.run(index);
                    set_scissor(pass, run.scissor, full);
                    pass.set_pipeline(self.surface_paint.pipeline_for(run.alpha));
                    pass.set_bind_group(0, &self.quad_bind_group, &[]);
                    pass.set_bind_group(1, self.surface_paint.bind_group_for_run(run), &[]);
                    pass.set_vertex_buffer(0, self.quad_vbo.slice(..));
                    pass.set_vertex_buffer(1, self.surface_paint.instance_buf().slice(..));
                    pass.draw(0..4, run.first..run.first + run.count);
                }
                PaintItem::Scene3D(index) => {
                    // The scene already rendered + resolved offscreen in
                    // phase 1; composite that texture over the rect via the
                    // stock surface pipeline (premultiplied).
                    let run = self.scene_paint.run(index);
                    set_scissor(pass, run.scissor, full);
                    pass.set_pipeline(self.scene_paint.composite_pipeline());
                    pass.set_bind_group(0, &self.quad_bind_group, &[]);
                    pass.set_bind_group(1, self.scene_paint.composite_bind_group(run), &[]);
                    pass.set_vertex_buffer(0, self.quad_vbo.slice(..));
                    pass.set_vertex_buffer(1, self.scene_paint.composite_instance_buf().slice(..));
                    pass.draw(0..4, run.composite_instance..run.composite_instance + 1);
                }
                PaintItem::BackdropSnapshot => {
                    // Marker only — `render()` splits the slice on
                    // these and never includes one in a draw range.
                }
            }
        }
    }
}