awsm-renderer 0.4.0

//! Texture management and GPU uploads.

use std::{collections::HashMap, sync::LazyLock};

use awsm_renderer_core::{
    buffers::{BufferDescriptor, BufferUsage},
    compare::CompareFunction,
    cubemap::{self, CubemapBytesLayout, CubemapFace},
    error::AwsmCoreError,
    image::ImageData,
    renderer::AwsmRendererWebGpu,
    sampler::{AddressMode, FilterMode, MipmapFilterMode, SamplerDescriptor},
    texture::{
        texture_pool::{TextureColorInfo, TexturePool, TexturePoolEntryInfo},
        TextureFormat,
    },
};
use indexmap::IndexSet;
use ordered_float::OrderedFloat;
use slotmap::{new_key_type, SecondaryMap, SlotMap};
use thiserror::Error;

use crate::{
    bind_groups::{BindGroupCreate, BindGroups},
    buffer::dynamic_uniform::DynamicUniformBuffer,
    error::AwsmError,
    render_passes::RenderPassInitContext,
    AwsmRenderer, AwsmRendererLogging,
};

static TEXTURE_TRANSFORM_BUFFER_USAGE: LazyLock<BufferUsage> =
    LazyLock::new(|| BufferUsage::new().with_storage().with_copy_dst());

/// Initial capacity for texture transform storage.
pub const TEXTURE_TRANSFORMS_INITIAL_CAPACITY: usize = 32; // 32 elements is a good starting point
/// Byte size for a single texture transform.
pub const TEXTURE_TRANSFORMS_BYTE_SIZE: usize = 32; // 32 bytes per texture transform (must match shader struct size)

/// A UV flow's offset at elapsed time `t`: `base + velocity * t` (recompute from
/// base, no drift). Shared by `advance_texture_flows` (real dt) and
/// `set_texture_flows_elapsed` (pinned absolute time, §7) so both agree.
fn flow_offset(base: [f32; 2], velocity: [f32; 2], t: f32) -> [f32; 2] {
    [base[0] + velocity[0] * t, base[1] + velocity[1] * t]
}

#[cfg(test)]
mod flow_tests {
    use super::flow_offset;

    fn close(a: [f32; 2], b: [f32; 2]) -> bool {
        (a[0] - b[0]).abs() < 1e-5 && (a[1] - b[1]).abs() < 1e-5
    }

    #[test]
    fn flow_offset_is_base_plus_velocity_times_time() {
        // Deterministic: same t → same offset; t scales linearly from base.
        assert!(close(flow_offset([0.1, 0.2], [0.3, 0.0], 0.0), [0.1, 0.2]));
        assert!(close(flow_offset([0.1, 0.2], [0.3, 0.0], 2.0), [0.7, 0.2]));
        assert!(close(
            flow_offset([0.0, 0.0], [0.3, -0.5], 2.0),
            [0.6, -1.0]
        ));
        // Idempotent at a fixed t (the §7 determinism property): bit-identical.
        assert_eq!(
            flow_offset([0.1, 0.2], [0.3, 0.0], 1.5),
            flow_offset([0.1, 0.2], [0.3, 0.0], 1.5),
        );
    }
}

impl AwsmRenderer {
    // this should ideally only be called after all the textures have been loaded
    /// Uploads texture pool data and refreshes dependent pipelines.
    ///
    /// On a cold PSO disk cache this is the biggest single phase of
    /// boot-time wall-clock by a wide margin: every render-pass that
    /// indexes into the texture pool (opaque + decal + transparent)
    /// has its shader text templated against the pool's
    /// `(arrays_len, samplers_len)`, so when the pool grows from 0
    /// to the real count, every existing PSO is invalidated and the
    /// driver has to compile every variant from scratch.
    ///
    /// Architecture: bind-group rebuilds run synchronously up front
    /// (no Dawn work), then a single `Shaders::ensure_keys` pools the
    /// opaque + decal + per-mesh-transparent shader cache keys, then
    /// a single `ComputePipelines::ensure_keys` pools opaque + decal
    /// pipeline cache keys, then a single
    /// `RenderPipelines::ensure_keys` pools the per-mesh transparent
    /// keys. Three awaits total instead of the previous six (per
    /// pass: one shader-batch + one pipeline-batch × three passes),
    /// each running its compiles in parallel through Dawn's pool.
    /// Read back a pooled texture as PNG bytes (GPU→CPU). Looks up the texture's
    /// array + layer + dimensions, copies that layer to a mappable buffer, and
    /// encodes a PNG (sRGB-corrected per the texture's upload colour space).
    /// Used by the editor's image-query seam to snapshot file/raster textures.
    #[cfg(feature = "texture-export")]
    pub async fn texture_png_bytes(
        &self,
        key: TextureKey,
    ) -> std::result::Result<Vec<u8>, AwsmError> {
        let (array_index, layer_index, srgb) = {
            let e = self.textures.get_entry(key)?;
            (e.array_index, e.layer_index, e.color.srgb_to_linear)
        };
        let (texture, width, height, format) = {
            let array = self
                .textures
                .pool
                .array_by_index(array_index)
                .ok_or(AwsmTextureError::TextureNotFound(key))?;
            let texture = array
                .gpu_texture
                .clone()
                .ok_or(AwsmTextureError::TextureNotFound(key))?;
            (texture, array.width, array.height, array.format)
        };
        let png = self
            .gpu
            .export_texture_as_png(
                &texture,
                width,
                height,
                layer_index as u32,
                format,
                None,
                false,
                Some(srgb),
            )
            .await?;
        Ok(png)
    }

    pub(crate) async fn finalize_gpu_textures(&mut self) -> std::result::Result<(), AwsmError> {
        // Take the sampler-pool dirty bit *before* the pool write —
        // both bits feed the same rebuild gate below. Without this OR,
        // `ensure_sampler_in_pool` (cache-hit texture bound to a
        // not-yet-pooled sampler) would land in the set but the
        // texture-pool bind group + dependent pipeline layouts would
        // still reflect the old sampler count, so `sampler_index()`
        // would point past the end of the bound sampler array. The
        // editor's `MaterialDef` override + the particles_sync path
        // are the canonical callers.
        let sampler_pool_dirty = self.textures.take_sampler_pool_dirty();
        let pool_dirty = self
            .textures
            .write_gpu_texture_pool(&self.logging, &self.gpu)
            .await?;
        // A custom-material register/alpha-edit can need the masked variant
        // (re)built with no texture change (procedural cutout). Take the flag so
        // the rebuild below runs; with an unchanged pool the opaque/transparent
        // descriptors below are cache hits and only the new masked variant compiles.
        let force_masked = std::mem::take(&mut self.masked_dynamic_dirty);
        let was_dirty = pool_dirty || sampler_pool_dirty;

        if !was_dirty && !force_masked {
            return Ok(());
        }

        self.bind_groups.mark_create(BindGroupCreate::TexturePool);

        // -----------------------------------------------------------
        // Phase A — sync bind-group + pipeline-layout rebuild
        // -----------------------------------------------------------
        // Every pass that indexes into the texture pool needs its
        // bind-group + pipeline-layout cache entry rebuilt against
        // the new pool dimensions. These are pure hash registrations
        // — no Dawn compile work.
        let opaque_bind_groups = {
            let mut render_pass_ctx = RenderPassInitContext {
                gpu: &mut self.gpu,
                pipelines: &mut self.pipelines,
                shaders: &mut self.shaders,
                textures: &mut self.textures,
                render_texture_formats: &mut self.render_textures.formats,
                bind_group_layouts: &mut self.bind_group_layouts,
                pipeline_layouts: &mut self.pipeline_layouts,
                features: &self.features,
                anti_aliasing: &self.anti_aliasing,
                post_processing: &self.post_processing,
                prep_config: &self.prep_config,
                max_edge_budget: self.material_edge_buffers.as_ref().map(|b| b.max_edge_budget).unwrap_or(crate::render_passes::material_opaque::edge_buffers::DEFAULT_MAX_EDGE_BUDGET_DESKTOP),
            };
            self.render_passes
                .material_opaque
                .bind_groups
                .clone_because_texture_pool_changed(&mut render_pass_ctx)?
        };
        let transparent_bind_groups = {
            let mut render_pass_ctx = RenderPassInitContext {
                gpu: &mut self.gpu,
                pipelines: &mut self.pipelines,
                shaders: &mut self.shaders,
                textures: &mut self.textures,
                render_texture_formats: &mut self.render_textures.formats,
                bind_group_layouts: &mut self.bind_group_layouts,
                pipeline_layouts: &mut self.pipeline_layouts,
                features: &self.features,
                anti_aliasing: &self.anti_aliasing,
                post_processing: &self.post_processing,
                prep_config: &self.prep_config,
                max_edge_budget: self.material_edge_buffers.as_ref().map(|b| b.max_edge_budget).unwrap_or(crate::render_passes::material_opaque::edge_buffers::DEFAULT_MAX_EDGE_BUDGET_DESKTOP),
            };
            self.render_passes
                .material_transparent
                .bind_groups
                .clone_because_texture_pool_changed(&mut render_pass_ctx)?
        };
        let decal_bind_groups = if let Some(decal) = self.render_passes.material_decal.as_ref() {
            let mut render_pass_ctx = RenderPassInitContext {
                gpu: &mut self.gpu,
                pipelines: &mut self.pipelines,
                shaders: &mut self.shaders,
                textures: &mut self.textures,
                render_texture_formats: &mut self.render_textures.formats,
                bind_group_layouts: &mut self.bind_group_layouts,
                pipeline_layouts: &mut self.pipeline_layouts,
                features: &self.features,
                anti_aliasing: &self.anti_aliasing,
                post_processing: &self.post_processing,
                prep_config: &self.prep_config,
                max_edge_budget: self.material_edge_buffers.as_ref().map(|b| b.max_edge_budget).unwrap_or(crate::render_passes::material_opaque::edge_buffers::DEFAULT_MAX_EDGE_BUDGET_DESKTOP),
            };
            Some(
                decal
                    .bind_groups
                    .clone_because_texture_pool_changed(&mut render_pass_ctx)?,
            )
        } else {
            None
        };

        self.render_passes.material_opaque.bind_groups = opaque_bind_groups;
        self.render_passes.material_transparent.bind_groups = transparent_bind_groups;
        if let Some(new_bg) = decal_bind_groups {
            if let Some(decal) = self.render_passes.material_decal.as_mut() {
                decal.bind_groups = new_bg;
            }
        }
        // Transparent has no global pipeline set, just a layout key
        // that gets used by the per-mesh batch below — refresh it.
        self.render_passes
            .material_transparent
            .pipelines
            .refresh_pipeline_layout(
                &self.gpu,
                &mut self.bind_group_layouts,
                &mut self.pipeline_layouts,
                &self.render_passes.material_transparent.bind_groups,
            )?;

        // -----------------------------------------------------------
        // Phase B — collect every shader cache key across every pass
        // -----------------------------------------------------------
        use crate::render_passes::material_transparent::pipeline::TransparentMeshPipelineRequest;

        // Build one request per mesh. The previous OR-style dedup
        // ("skip if buffer_info OR material was already seen") was a
        // pre-existing bug — for mesh sets like (A,M1), (B,M2),
        // (A,M2), (B,M1) it skips the third / fourth pair even
        // though they produce different pipeline cache keys (e.g.
        // when M1 and M2 differ in `writes_depth`), leaving
        // those meshes with stale pipeline-key map entries after
        // the layout change. `Shaders::ensure_keys` and
        // `RenderPipelines::ensure_keys` both dedupe internally by
        // their cache keys, so the cost of sending all meshes is
        // just a couple of extra hash probes per mesh.
        let mut transparent_requests: Vec<TransparentMeshPipelineRequest> = Vec::new();
        for (mesh_key, mesh) in self.meshes.iter() {
            // Only transparent-pass meshes get a transparent pipeline — an
            // opaque (incl. opaque-dynamic) material can't compile against the
            // transparent fragment contract.
            if !self.materials.is_transparency_pass(mesh.material_key) {
                continue;
            }
            let buffer_info_key = self.meshes.buffer_info_key(mesh_key)?;
            let writes_depth = self.materials.transparent_writes_depth(mesh.material_key);
            let (base, pbr_features) = self.materials.transparent_variant(mesh.material_key);
            let dynamic_shader_id = matches!(base, crate::dynamic_materials::ShadingBase::Custom)
                .then(|| self.materials.shader_id(mesh.material_key));
            let dynamic_shader =
                dynamic_shader_id.and_then(|id| self.dynamic_materials.shader_info_for(id));
            let dynamic_vertex_shader =
                dynamic_shader_id.and_then(|id| self.dynamic_materials.vertex_shader_info_for(id));
            transparent_requests.push(TransparentMeshPipelineRequest {
                mesh,
                mesh_key,
                buffer_info_key,
                writes_depth,
                base,
                pbr_features,
                dynamic_shader_id,
                dynamic_shader,
                dynamic_vertex_shader,
            });
        }

        let mut all_shader_keys: Vec<crate::shaders::ShaderCacheKey> = Vec::new();
        {
            let mut render_pass_ctx = RenderPassInitContext {
                gpu: &mut self.gpu,
                pipelines: &mut self.pipelines,
                shaders: &mut self.shaders,
                textures: &mut self.textures,
                render_texture_formats: &mut self.render_textures.formats,
                bind_group_layouts: &mut self.bind_group_layouts,
                pipeline_layouts: &mut self.pipeline_layouts,
                features: &self.features,
                anti_aliasing: &self.anti_aliasing,
                post_processing: &self.post_processing,
                prep_config: &self.prep_config,
                max_edge_budget: self.material_edge_buffers.as_ref().map(|b| b.max_edge_budget).unwrap_or(crate::render_passes::material_opaque::edge_buffers::DEFAULT_MAX_EDGE_BUDGET_DESKTOP),
            };
            all_shader_keys.extend(
                crate::render_passes::material_opaque::pipeline::MaterialOpaquePipelines::build_shader_cache_keys(
                    &mut render_pass_ctx,
                    &self.render_passes.material_opaque.bind_groups,
                )?,
            );
            if let Some(decal) = self.render_passes.material_decal.as_ref() {
                all_shader_keys.extend(
                    crate::render_passes::material_decal::pipeline::MaterialDecalPipelines::build_shader_cache_keys(
                        &mut render_pass_ctx,
                        &decal.bind_groups,
                    )?,
                );
            }
        }
        all_shader_keys.extend(
            crate::render_passes::material_transparent::pipeline::MaterialTransparentPipelines::shader_cache_keys_for_requests(
                transparent_requests.iter(),
                &self.render_passes.material_transparent.bind_groups,
                &self.meshes.buffer_infos,
                &self.anti_aliasing,
            )?
            .into_iter()
            .map(crate::shaders::ShaderCacheKey::from),
        );

        // Single cross-pass shader compile batch.
        self.shaders.ensure_keys(&self.gpu, all_shader_keys).await?;

        // -----------------------------------------------------------
        // Phase C — build pipeline cache keys (shaders are warm)
        // -----------------------------------------------------------
        let (opaque_descs, decal_descs) = {
            let mut render_pass_ctx = RenderPassInitContext {
                gpu: &mut self.gpu,
                pipelines: &mut self.pipelines,
                shaders: &mut self.shaders,
                textures: &mut self.textures,
                render_texture_formats: &mut self.render_textures.formats,
                bind_group_layouts: &mut self.bind_group_layouts,
                pipeline_layouts: &mut self.pipeline_layouts,
                features: &self.features,
                anti_aliasing: &self.anti_aliasing,
                post_processing: &self.post_processing,
                prep_config: &self.prep_config,
                max_edge_budget: self.material_edge_buffers.as_ref().map(|b| b.max_edge_budget).unwrap_or(crate::render_passes::material_opaque::edge_buffers::DEFAULT_MAX_EDGE_BUDGET_DESKTOP),
            };
            let opaque_descs = crate::render_passes::material_opaque::pipeline::MaterialOpaquePipelines::build_descriptors(
                &mut render_pass_ctx,
                &self.render_passes.material_opaque.bind_groups,
            )
            .await?;
            let decal_descs = if let Some(decal) = self.render_passes.material_decal.as_ref() {
                Some(
                    crate::render_passes::material_decal::pipeline::MaterialDecalPipelines::build_descriptors(
                        &mut render_pass_ctx,
                        &decal.bind_groups,
                    )
                    .await?,
                )
            } else {
                None
            };
            (opaque_descs, decal_descs)
        };

        let transparent_pipeline_cache_keys = self
            .render_passes
            .material_transparent
            .pipelines
            .pipeline_cache_keys_for_requests(
                &self.gpu,
                transparent_requests.iter(),
                &mut self.shaders,
                &self.render_passes.material_transparent.bind_groups,
                &self.meshes.buffer_infos,
                &self.anti_aliasing,
                &self.render_textures.formats,
            )
            .await?;

        // -----------------------------------------------------------
        // Phase D — one batched compute + one batched render compile
        // -----------------------------------------------------------
        let opaque_pipeline_count = opaque_descs.pipeline_cache_keys.len();
        let mut compute_cache_keys = opaque_descs.pipeline_cache_keys.clone();
        if let Some(ref decal_descs) = decal_descs {
            compute_cache_keys.extend(decal_descs.pipeline_cache_keys.iter().cloned());
        }

        let compute_pipeline_keys = self
            .pipelines
            .compute
            .ensure_keys(
                &self.gpu,
                &self.shaders,
                &self.pipeline_layouts,
                compute_cache_keys,
            )
            .await?;

        let transparent_pipeline_keys = self
            .pipelines
            .render
            .ensure_keys(
                &self.gpu,
                &self.shaders,
                &self.pipeline_layouts,
                transparent_pipeline_cache_keys,
            )
            .await?;

        // -----------------------------------------------------------
        // Phase E — sync fold-up of resolved keys
        // -----------------------------------------------------------
        let (opaque_keys_slice, decal_keys_slice) =
            compute_pipeline_keys.split_at(opaque_pipeline_count);
        self.render_passes.material_opaque.pipelines =
            crate::render_passes::material_opaque::pipeline::MaterialOpaquePipelines::from_resolved(
                opaque_descs.slots,
                opaque_keys_slice.to_vec(),
            );
        if let (Some(decal_descs), Some(decal)) =
            (decal_descs, self.render_passes.material_decal.as_mut())
        {
            decal.pipelines =
                crate::render_passes::material_decal::pipeline::MaterialDecalPipelines::from_resolved(
                    decal_descs.is_msaa,
                    decal_keys_slice.to_vec(),
                );
        }
        let mesh_keys: Vec<_> = transparent_requests.iter().map(|r| r.mesh_key).collect();
        self.render_passes
            .material_transparent
            .pipelines
            .install_per_mesh_keys(mesh_keys, transparent_pipeline_keys);

        // -----------------------------------------------------------
        // Masked (alpha-tested) geometry — rebuild against the new pool
        // -----------------------------------------------------------
        // The masked group-0 carries the texture pool, so its layout changes
        // when the pool grows. Relayout the bind group + pipeline pool, then
        // (re)compile the built-in PBR masked variant (its base-color cutout
        // samples the pool), plus every registered MASK custom material that
        // carries a 2nd alpha-only WGSL window.
        {
            // Collect the registered MASK customs first (releases the
            // dynamic_materials borrow before the RenderPassInitContext below).
            let custom_masked: Vec<(
                awsm_renderer_materials::MaterialShaderId,
                crate::render_passes::geometry::shader::masked_cache_key::DynamicAlphaShaderInfo,
            )> = self
                .dynamic_materials
                .iter()
                .map(|(id, _)| id)
                .collect::<Vec<_>>()
                .into_iter()
                .filter_map(|id| {
                    self.dynamic_materials
                        .alpha_info_for(id)
                        .map(|info| (id, info))
                })
                .collect();

            // Collect the registered CUSTOM-VERTEX materials (those whose
            // registration carries a non-empty `wgsl_vertex`). Each gets one
            // custom-vertex geometry variant — strictly additive + opt-in: a
            // material with no `wgsl_vertex` never enters this list, so the
            // shared geometry path is byte-identical for everyone else.
            let custom_vertex: Vec<(
                awsm_renderer_materials::MaterialShaderId,
                crate::render_passes::geometry::shader::cache_key::DynamicVertexShaderInfo,
            )> = self
                .dynamic_materials
                .iter()
                .map(|(id, _)| id)
                .collect::<Vec<_>>()
                .into_iter()
                .filter_map(|id| {
                    self.dynamic_materials
                        .vertex_shader_info_for(id)
                        .map(|info| (id, info))
                })
                .collect();

            // Collect the COMBINED materials — those that are BOTH glTF MASK
            // (carry an alpha-only WGSL window) AND custom-vertex (carry a
            // `wgsl_vertex` body). Each gets one combined geometry + one combined
            // shadow variant so a Mask + custom-vertex material renders DISPLACED
            // AND alpha-cut (and casts a matching displaced + cutout shadow). A
            // material missing either body never enters this list (non-regression
            // — the plain masked / custom-vertex / solid paths are untouched).
            #[allow(clippy::type_complexity)]
            let custom_masked_vertex: Vec<(
                awsm_renderer_materials::MaterialShaderId,
                crate::render_passes::geometry::shader::cache_key::DynamicVertexShaderInfo,
                crate::render_passes::geometry::shader::masked_cache_key::DynamicAlphaShaderInfo,
            )> = self
                .dynamic_materials
                .iter()
                .map(|(id, _)| id)
                .collect::<Vec<_>>()
                .into_iter()
                .filter_map(|id| {
                    match (
                        self.dynamic_materials.vertex_shader_info_for(id),
                        self.dynamic_materials.alpha_info_for(id),
                    ) {
                        (Some(v), Some(a)) => Some((id, v, a)),
                        _ => None,
                    }
                })
                .collect();

            let new_masked_bg = {
                let mut ctx = RenderPassInitContext {
                    gpu: &mut self.gpu,
                    pipelines: &mut self.pipelines,
                    shaders: &mut self.shaders,
                    textures: &mut self.textures,
                    render_texture_formats: &mut self.render_textures.formats,
                    bind_group_layouts: &mut self.bind_group_layouts,
                    pipeline_layouts: &mut self.pipeline_layouts,
                    features: &self.features,
                    anti_aliasing: &self.anti_aliasing,
                    post_processing: &self.post_processing,
                    prep_config: &self.prep_config,
                max_edge_budget: self.material_edge_buffers.as_ref().map(|b| b.max_edge_budget).unwrap_or(crate::render_passes::material_opaque::edge_buffers::DEFAULT_MAX_EDGE_BUDGET_DESKTOP),
                };
                self.render_passes
                    .geometry
                    .masked_bind_group
                    .clone_because_texture_pool_changed(&mut ctx)?
            };
            self.render_passes.geometry.masked_bind_group = new_masked_bg;

            let mut ctx = RenderPassInitContext {
                gpu: &mut self.gpu,
                pipelines: &mut self.pipelines,
                shaders: &mut self.shaders,
                textures: &mut self.textures,
                render_texture_formats: &mut self.render_textures.formats,
                bind_group_layouts: &mut self.bind_group_layouts,
                pipeline_layouts: &mut self.pipeline_layouts,
                features: &self.features,
                anti_aliasing: &self.anti_aliasing,
                post_processing: &self.post_processing,
                prep_config: &self.prep_config,
                max_edge_budget: self.material_edge_buffers.as_ref().map(|b| b.max_edge_budget).unwrap_or(crate::render_passes::material_opaque::edge_buffers::DEFAULT_MAX_EDGE_BUDGET_DESKTOP),
            };
            self.render_passes.geometry.masked_pipelines.relayout(
                &mut ctx,
                &self.render_passes.geometry.masked_bind_group,
                &self.render_passes.geometry.bind_groups,
            )?;
            // Built-in MASK materials route alpha-tested-OPAQUE: PBR, Unlit,
            // Toon share the same header prefix (shader_id, alpha_mode,
            // alpha_cutoff, base_color_tex(5), base_color_factor(4)), so the
            // masked fragment's base-color path covers them with one WGSL —
            // only the cache-key shader_id differs. FlipBook gets its OWN
            // masked WGSL arm (the mask alpha is the time-varying atlas cell,
            // evaluated by the shared cell math the shaded material also runs).
            for (shader_id, base) in [
                (
                    awsm_renderer_materials::MaterialShaderId::PBR,
                    crate::dynamic_materials::ShadingBase::Pbr,
                ),
                (
                    awsm_renderer_materials::MaterialShaderId::UNLIT,
                    crate::dynamic_materials::ShadingBase::Unlit,
                ),
                (
                    awsm_renderer_materials::MaterialShaderId::TOON,
                    crate::dynamic_materials::ShadingBase::Toon,
                ),
                (
                    awsm_renderer_materials::MaterialShaderId::FLIPBOOK,
                    crate::dynamic_materials::ShadingBase::Flipbook,
                ),
            ] {
                let variant = crate::render_passes::geometry::masked_pipeline::MaskedVariant {
                    shader_id,
                    base,
                    dynamic_alpha: None,
                };
                self.render_passes
                    .geometry
                    .masked_pipelines
                    .ensure_variant(
                        &mut ctx,
                        &self.render_passes.geometry.masked_bind_group,
                        &variant,
                    )
                    .await?;
            }

            // Custom MASK materials — one masked variant each, emitting the
            // author's alpha-only fragment. Iterate by reference so the same
            // list feeds the masked-shadow build below.
            for (shader_id, info) in &custom_masked {
                let variant = crate::render_passes::geometry::masked_pipeline::MaskedVariant {
                    shader_id: *shader_id,
                    base: crate::dynamic_materials::ShadingBase::Custom,
                    dynamic_alpha: Some(info.clone()),
                };
                self.render_passes
                    .geometry
                    .masked_pipelines
                    .ensure_variant(
                        &mut ctx,
                        &self.render_passes.geometry.masked_bind_group,
                        &variant,
                    )
                    .await?;
            }

            // -------------------------------------------------------------
            // Custom-vertex geometry — rebuild against the new pool. The
            // custom-vertex variant reuses the masked group-0 bind group (its
            // `material_data_load` reads the `materials` buffer + samples the
            // texture pool the masked group declares), so its pipeline layout
            // also changes when the pool grows. Relayout the pool, then compile
            // one variant per registered custom-vertex material (non-instanced
            // shape; instanced custom-vertex is a follow-on). Mirrors the
            // masked-custom build above. The render path falls back to the plain
            // geometry pipeline until these land, so the mesh always draws.
            // -------------------------------------------------------------
            self.render_passes
                .geometry
                .custom_vertex_pipelines
                .relayout(
                    &mut ctx,
                    &self.render_passes.geometry.masked_bind_group,
                    &self.render_passes.geometry.bind_groups,
                )?;
            for (shader_id, info) in &custom_vertex {
                let variant =
                    crate::render_passes::geometry::custom_vertex_pipeline::CustomVertexVariant {
                        shader_id: *shader_id,
                        dynamic_vertex: info.clone(),
                        instancing_transforms: false,
                    };
                self.render_passes
                    .geometry
                    .custom_vertex_pipelines
                    .ensure_variant(
                        &mut ctx,
                        &self.render_passes.geometry.masked_bind_group,
                        &variant,
                    )
                    .await?;
            }

            // -------------------------------------------------------------
            // COMBINED masked + custom-vertex geometry — so a material that is
            // BOTH Mask AND custom-vertex renders DISPLACED *and* alpha-cut.
            // Reuses the masked group-0 bind group (same as the plain masked +
            // custom-vertex pools), so its layout also changes on a pool grow.
            // Relayout the pool, then compile one combined variant per registered
            // Mask + custom-vertex material (non-instanced shape). The render path
            // falls back via precedence to the plain custom-vertex / masked /
            // solid pipeline until these land, so the mesh always draws.
            // -------------------------------------------------------------
            self.render_passes
                .geometry
                .masked_custom_vertex_pipelines
                .relayout(
                    &mut ctx,
                    &self.render_passes.geometry.masked_bind_group,
                    &self.render_passes.geometry.bind_groups,
                )?;
            for (shader_id, vertex_info, alpha_info) in &custom_masked_vertex {
                let variant =
                    crate::render_passes::geometry::masked_custom_vertex_pipeline::MaskedCustomVertexVariant {
                        shader_id: *shader_id,
                        // A registered material with both a `wgsl_vertex` body and
                        // an alpha body is a dynamic (Custom) material; its MASK
                        // cutout takes the Custom alpha path.
                        base: crate::dynamic_materials::ShadingBase::Custom,
                        dynamic_vertex: vertex_info.clone(),
                        dynamic_alpha: Some(alpha_info.clone()),
                    };
                self.render_passes
                    .geometry
                    .masked_custom_vertex_pipelines
                    .ensure_variant(
                        &mut ctx,
                        &self.render_passes.geometry.masked_bind_group,
                        &variant,
                    )
                    .await?;
            }

            // -------------------------------------------------------------
            // Masked (alpha-tested) SHADOW casters — same per-shader-id pool,
            // for hole-shaped (cutout) shadows (B2). The masked-shadow group-0
            // carries the texture pool too, so relayout it against the new pool,
            // then compile the built-in PBR/Unlit/Toon variants (base-color
            // cutout) + every registered MASK custom (alpha-only WGSL). The
            // shadow render path falls back to the solid pipeline until these
            // land, so a masked caster always casts *some* shadow.
            // -------------------------------------------------------------
            let new_shadow_masked_bg = self
                .render_passes
                .shadow_masked
                .bind_group
                .clone_because_texture_pool_changed(&mut ctx)?;
            self.render_passes.shadow_masked.bind_group = new_shadow_masked_bg;
            self.render_passes.shadow_masked.pipelines.relayout(
                &mut ctx,
                &self.render_passes.shadow_masked.bind_group,
                &self.render_passes.geometry.bind_groups,
            )?;
            for (shader_id, base) in [
                (
                    awsm_renderer_materials::MaterialShaderId::PBR,
                    crate::dynamic_materials::ShadingBase::Pbr,
                ),
                (
                    awsm_renderer_materials::MaterialShaderId::UNLIT,
                    crate::dynamic_materials::ShadingBase::Unlit,
                ),
                (
                    awsm_renderer_materials::MaterialShaderId::TOON,
                    crate::dynamic_materials::ShadingBase::Toon,
                ),
                (
                    awsm_renderer_materials::MaterialShaderId::FLIPBOOK,
                    crate::dynamic_materials::ShadingBase::Flipbook,
                ),
            ] {
                let variant = crate::render_passes::shadow_masked::pipeline::MaskedShadowVariant {
                    shader_id,
                    base,
                    dynamic_alpha: None,
                };
                self.render_passes
                    .shadow_masked
                    .pipelines
                    .ensure_variant(
                        &mut ctx,
                        &self.render_passes.shadow_masked.bind_group,
                        &variant,
                    )
                    .await?;
            }
            for (shader_id, info) in &custom_masked {
                let variant = crate::render_passes::shadow_masked::pipeline::MaskedShadowVariant {
                    shader_id: *shader_id,
                    base: crate::dynamic_materials::ShadingBase::Custom,
                    dynamic_alpha: Some(info.clone()),
                };
                self.render_passes
                    .shadow_masked
                    .pipelines
                    .ensure_variant(
                        &mut ctx,
                        &self.render_passes.shadow_masked.bind_group,
                        &variant,
                    )
                    .await?;
            }

            // -------------------------------------------------------------
            // Custom-vertex SHADOW casters — so a custom-vertex material's
            // shadow is DISPLACED identically to its geometry (no detached /
            // smooth shadow). Same per-shader-id lazy pool as the masked-shadow
            // pass; reuses the (vertex-augmented) masked-shadow group-0 bind group
            // (its hook's `material_data_load` reads `materials` + samples the
            // pool the masked-shadow group declares — with VERTEX visibility), so
            // its layout also changes when the pool grows. Relayout the pool
            // against the just-rebuilt masked-shadow bind group, then compile one
            // variant per registered custom-vertex material (non-instanced shape;
            // instanced is a follow-on). The shadow render path falls back to the
            // solid pipeline until these land, so a custom-vertex caster always
            // casts *some* shadow (un-displaced). Strictly additive + opt-in: a
            // material with no `wgsl_vertex` never enters `custom_vertex`, so
            // shadows are byte-identical for everyone else (non-regression).
            // -------------------------------------------------------------
            self.render_passes.shadow_custom_vertex.pipelines.relayout(
                &mut ctx,
                &self.render_passes.shadow_masked.bind_group,
                &self.render_passes.geometry.bind_groups,
            )?;
            for (shader_id, info) in &custom_vertex {
                let variant =
                    crate::render_passes::shadow_custom_vertex::pipeline::ShadowCustomVertexVariant {
                        shader_id: *shader_id,
                        dynamic_vertex: info.clone(),
                    };
                self.render_passes
                    .shadow_custom_vertex
                    .pipelines
                    .ensure_variant(
                        &mut ctx,
                        &self.render_passes.shadow_masked.bind_group,
                        &variant,
                    )
                    .await?;
            }

            // -------------------------------------------------------------
            // COMBINED masked + custom-vertex SHADOW casters — so a material
            // that is BOTH Mask AND custom-vertex casts a DISPLACED *and* cutout
            // shadow. Same per-shader-id lazy pool as the masked-shadow +
            // custom-vertex-shadow passes; reuses the (vertex-augmented)
            // masked-shadow group-0 bind group, so its layout also changes on a
            // pool grow. Relayout the pool against the just-rebuilt masked-shadow
            // bind group, then compile one combined variant per registered Mask +
            // custom-vertex material (non-instanced shape). The shadow render path
            // falls back via precedence until these land, so a combined caster
            // always casts *some* shadow.
            // -------------------------------------------------------------
            self.render_passes
                .shadow_masked_custom_vertex
                .pipelines
                .relayout(
                    &mut ctx,
                    &self.render_passes.shadow_masked.bind_group,
                    &self.render_passes.geometry.bind_groups,
                )?;
            for (shader_id, vertex_info, alpha_info) in &custom_masked_vertex {
                let variant =
                    crate::render_passes::shadow_masked_custom_vertex::pipeline::ShadowMaskedCustomVertexVariant {
                        shader_id: *shader_id,
                        base: crate::dynamic_materials::ShadingBase::Custom,
                        dynamic_vertex: vertex_info.clone(),
                        dynamic_alpha: Some(alpha_info.clone()),
                    };
                self.render_passes
                    .shadow_masked_custom_vertex
                    .pipelines
                    .ensure_variant(
                        &mut ctx,
                        &self.render_passes.shadow_masked.bind_group,
                        &variant,
                    )
                    .await?;
            }
        }

        // Re-launch the compile for every currently-registered
        // scheduler material entry.
        //
        // The opaque-pipeline rebuild above only emits descriptors for
        // the `OpaquePipelineSlot::Empty*` slots (`MaterialOpaquePipelines::
        // shader_descriptors_and_layouts` passes `include_first_party:
        // false`), and `from_resolved` constructs the typed cache
        // from those slots wholesale — wiping any first-party /
        // dynamic material pipeline keys that were previously
        // compiled. That wipe is intentional: their underlying
        // shaders were compiled with the OLD `texture_pool_arrays_len`
        // template substitution, and the new `texture_pool_textures`
        // BGL doesn't match the OLD pipeline's layout, so reusing
        // those keys would either silently sample the
        // `default → vec4(0)` branch (the bug that motivated the
        // Stage 3 silhouette-quality fix in `53202fa`) or fail
        // outright at dispatch validation.
        //
        // Mirror that wipe on the edge_pipelines per-pass cache: the
        // edge_resolve shaders also depend on the OLD
        // `texture_pool_arrays_len`, and after the wipe above the
        // dispatch path skips the affected materials via the Option
        // guards on `get_compute_pipeline_key`. Without clearing
        // `edge_pipelines.per_shader` + the global skybox /
        // final_blend keys here too, edge dispatch would still hit
        // the OLD-pool-shape pipelines until the new ones land.
        self.render_passes
            .material_opaque
            .edge_pipelines
            .clear_dynamic_pipelines();

        // Force a recompile against the new texture-pool layout. A pool grow
        // doesn't change the bucket SET (dispatch_hash / count unchanged), so it
        // wouldn't trip `ensure_scene_pipelines`' layout-change detector on its
        // own — but it DOES invalidate every opaque/classify/edge pipeline
        // (their cache keys embed `texture_pool_arrays_len` /
        // `texture_pool_samplers_len`). Reset the ensure fingerprint so the
        // `ensure_scene_pipelines` later in THIS commit treats the pool change
        // as a layout change: it re-runs the buffer-relayout (idempotent — the
        // buffers are already the right size, so a no-op) + the cache-clear +
        // generation-bump (dropping any in-flight old-pool resolutions), then
        // recompiles every bucket against the new pool. `finalize_gpu_textures`
        // runs at the START of `commit_load`, so `mark_variants_dirty` here is
        // consumed by the commit's own `reconcile_material_variants`.
        self.last_ensured_bucket_layout = None;
        self.materials.mark_variants_dirty();

        // (Removed: the eager `edge_pipelines.ensure_compiled(...)` block that
        // used to recompile the full edge-resolve set HERE, against the new
        // texture-pool layout. Because `finalize_gpu_textures` runs several
        // times across a load (gltf populate, scene-loader, IBL/skybox batches),
        // that eager edge compile fired ~3× per load at a different
        // `texture_pool_arrays_len` each time — the TTFR recompile this design
        // deletes. The edge set now compiles exactly ONCE per load: the
        // `reset` above (`last_ensured_bucket_layout = None` +
        // `mark_variants_dirty`) forces `commit_load`'s single
        // `reconcile_material_variants` → `ensure_scene_pipelines` →
        // `launch_edge_resolve_compile` to rebuild it against the final pool.)

        Ok(())
    }

    /// Updates one face of a cubemap texture in-place from raw bytes.
    pub fn update_cubemap_texture_face(
        &self,
        texture_key: CubemapTextureKey,
        face: CubemapFace,
        mip_level: u32,
        width: u32,
        height: u32,
        data: &[u8],
        layout: CubemapBytesLayout,
    ) -> crate::error::Result<()> {
        let texture = self.textures.get_cubemap(texture_key)?;
        cubemap::update_texture_face(
            &self.gpu, texture, face, mip_level, width, height, data, layout,
        )?;
        Ok(())
    }

    /// Updates all six faces of a cubemap texture in-place from one contiguous byte buffer.
    ///
    /// Data must be packed in face order: +X, -X, +Y, -Y, +Z, -Z.
    pub fn update_cubemap_texture_all_faces(
        &self,
        texture_key: CubemapTextureKey,
        mip_level: u32,
        width: u32,
        height: u32,
        data: &[u8],
        layout: CubemapBytesLayout,
    ) -> crate::error::Result<()> {
        let texture = self.textures.get_cubemap(texture_key)?;
        cubemap::update_texture_all_faces(
            &self.gpu, texture, mip_level, width, height, data, layout,
        )?;
        Ok(())
    }

    /// Removes a pool texture. Consumers should ensure no live material
    /// still binds `key` (i.e. trigger a re-resolve cascade before
    /// calling), then drop their cached handle. Returns `true` if the
    /// key existed; `false` if it was already gone.
    pub fn remove_texture(&mut self, key: TextureKey) -> bool {
        self.textures.remove(key)
    }

    /// Regenerates mipmaps for an existing cubemap texture.
    pub async fn regenerate_cubemap_texture_mipmaps(
        &self,
        texture_key: CubemapTextureKey,
        mip_levels: u32,
    ) -> crate::error::Result<()> {
        let texture = self.textures.get_cubemap(texture_key)?;
        cubemap::regenerate_texture_mipmaps(&self.gpu, texture, mip_levels).await?;
        Ok(())
    }
}

/// Texture pool, samplers, and texture transforms.
pub struct Textures {
    pub pool: TexturePool<TextureKey>,
    pub pool_sampler_set: IndexSet<SamplerKey>,
    pub texture_transform_identity_offset: usize,
    pool_textures: SlotMap<TextureKey, TexturePoolEntryInfo<TextureKey>>,
    cubemaps: SlotMap<CubemapTextureKey, web_sys::GpuTexture>,
    samplers: SlotMap<SamplerKey, web_sys::GpuSampler>,
    sampler_cache: HashMap<SamplerCacheKey, SamplerKey>,
    // We keep a mirror of the sampler address modes so that materials can adjust UVs manually when
    sampler_address_modes: SecondaryMap<SamplerKey, (Option<AddressMode>, Option<AddressMode>)>,
    // Stores the CPU-side `TextureTransform` per key (not just `()`), so an
    // animation track can read-modify-write a single component (offset / scale /
    // rotation) while preserving the others. The GPU bytes live in
    // `texture_transforms_buffer`; this is the authoritative struct mirror.
    texture_transforms: SlotMap<TextureTransformKey, TextureTransform>,
    // UV-flow (auto-scroll) state per transform key. `advance_texture_flows(dt)`
    // (driven each frame by `update_animations`) accumulates `velocity * elapsed`
    // into the transform's offset (recompute-from-`base_offset`, so no drift).
    // Empty unless a binding declares `TextureRef.flow` — zero per-frame cost
    // otherwise. (B3 — texture flow over the B1 UV transform.)
    texture_flows: SecondaryMap<TextureTransformKey, TextureFlow>,
    // Pooled scratch for the per-frame flow flush — reused (capacity retained)
    // so an active UV flow does NOT heap-allocate every frame in the render hot
    // path. Borrowed out via `mem::take` while `update_texture_transform` needs
    // `&mut self`. Empty/cap-0 until the first flow ticks.
    texture_flow_scratch: Vec<(TextureTransformKey, [f32; 2])>,
    texture_transforms_buffer: DynamicUniformBuffer<TextureTransformKey>,
    texture_transforms_gpu_dirty: bool,
    pub(crate) texture_transforms_gpu_buffer: web_sys::GpuBuffer,
    texture_transforms_uploader: crate::buffer::mapped_uploader::MappedUploader,
    /// Set when `pool_sampler_set` mutates without an accompanying
    /// pool-array `gpu_dirty` flip (i.e. `ensure_sampler_in_pool` or
    /// `add_image` inserting a sampler that wasn't already present).
    /// `finalize_gpu_textures` ORs this with the pool-write dirty bit
    /// when deciding whether to rebuild material bind groups /
    /// pipeline layouts — without it, a new sampler would land in the
    /// set but `sampler_index()` would point past the end of the
    /// previously-cached bind group's sampler array.
    sampler_pool_dirty: bool,
}

/// Cache key for samplers.
#[derive(Default, Debug, Clone, PartialEq, Eq)]
pub struct SamplerCacheKey {
    pub address_mode_u: Option<AddressMode>,
    pub address_mode_v: Option<AddressMode>,
    pub address_mode_w: Option<AddressMode>,
    pub compare: Option<CompareFunction>,
    pub lod_min_clamp: Option<OrderedFloat<f32>>,
    pub lod_max_clamp: Option<OrderedFloat<f32>>,
    pub max_anisotropy: Option<u16>,
    pub mag_filter: Option<FilterMode>,
    pub min_filter: Option<FilterMode>,
    pub mipmap_filter: Option<MipmapFilterMode>,
}

impl SamplerCacheKey {
    /// Returns true if anisotropy is allowed with the current filters.
    pub fn allowed_ansiotropy(&self) -> bool {
        match (self.min_filter, self.mag_filter, self.mipmap_filter) {
            (Some(FilterMode::Nearest), _, _)
            | (_, Some(FilterMode::Nearest), _)
            | (_, _, Some(MipmapFilterMode::Nearest)) => false,
            _ => true,
        }
    }
}

impl std::hash::Hash for SamplerCacheKey {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.address_mode_u.map(|x| x as u32).hash(state);
        self.address_mode_v.map(|x| x as u32).hash(state);
        self.address_mode_w.map(|x| x as u32).hash(state);
        self.compare.map(|x| x as u32).hash(state);
        self.lod_min_clamp.hash(state);
        self.lod_max_clamp.hash(state);
        self.max_anisotropy.hash(state);
        self.mag_filter.map(|x| x as u32).hash(state);
        self.min_filter.map(|x| x as u32).hash(state);
        self.mipmap_filter.map(|x| x as u32).hash(state);
    }
}

/// Per-key UV-flow state: a `[u,v]` velocity (UV/sec) accumulated into the
/// transform's offset, recomputed from `base_offset` each frame so it can't drift.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct TextureFlow {
    /// The offset the flow accumulates ON TOP of (the binding's authored offset).
    pub base_offset: [f32; 2],
    /// UV-units per second.
    pub velocity: [f32; 2],
    /// Seconds accumulated since the flow was (re)set.
    pub elapsed: f32,
}

/// Texture transform parameters.
#[derive(Debug, Clone, PartialEq)]
pub struct TextureTransform {
    pub offset: [f32; 2],
    pub origin: [f32; 2],
    pub rotation: f32,
    pub scale: [f32; 2],
}

impl TextureTransform {
    /// Returns an identity transform.
    pub fn identity() -> Self {
        Self {
            offset: [0.0, 0.0],
            origin: [0.0, 0.0],
            rotation: 0.0,
            scale: [1.0, 1.0],
        }
    }

    /// Packs the transform into GPU bytes.
    pub fn as_gpu_bytes(&self) -> [u8; TEXTURE_TRANSFORMS_BYTE_SIZE] {
        let mut bytes = [0u8; TEXTURE_TRANSFORMS_BYTE_SIZE];

        let sx = self.scale[0];
        let sy = self.scale[1];
        let ox = self.offset[0];
        let oy = self.offset[1];
        let px = self.origin[0];
        let py = self.origin[1];

        let c = self.rotation.cos();
        let s = self.rotation.sin();

        // M = R * S
        // glTF rotation matrix (counter-clockwise, with V pointing down):
        // [ cos   sin ] * [ sx  0  ]   =   [ cos*sx   sin*sy ]
        // [ -sin  cos ]   [ 0   sy ]       [ -sin*sx  cos*sy ]
        let m00 = c * sx;
        let m01 = s * sy;
        let m10 = -s * sx;
        let m11 = c * sy;

        // B = offset + origin - M * origin
        let mx_px = m00 * px + m01 * py;
        let my_py = m10 * px + m11 * py;

        let bx = ox + px - mx_px;
        let by = oy + py - my_py;

        bytes[0..4].copy_from_slice(&m00.to_le_bytes());
        bytes[4..8].copy_from_slice(&m01.to_le_bytes());
        bytes[8..12].copy_from_slice(&m10.to_le_bytes());
        bytes[12..16].copy_from_slice(&m11.to_le_bytes());
        bytes[16..20].copy_from_slice(&bx.to_le_bytes());
        bytes[20..24].copy_from_slice(&by.to_le_bytes());

        bytes
    }
}

impl Textures {
    /// Live GPU-texture-resource counts `(pool_textures, cubemaps, samplers)` for
    /// leak diagnostics (surfaced via `memory_stats`). `memory_stats` historically
    /// counted only pipelines/shaders/transforms/meshes — textures were a blind
    /// spot, yet "Destroyed texture" GPU-validation spam + Chrome "aw snap" point
    /// at texture/sampler accumulation. A growing count under add/delete churn of
    /// textured materials / imported models signals a leak.
    pub fn resource_counts(&self) -> (usize, usize, usize) {
        (
            self.pool_textures.len(),
            self.cubemaps.len(),
            self.samplers.len(),
        )
    }

    /// Creates texture storage and GPU buffers.
    pub fn new(gpu: &AwsmRendererWebGpu) -> Result<Self> {
        let samplers = SlotMap::with_key();
        let sampler_cache = HashMap::new();
        let sampler_address_modes = SecondaryMap::new();

        let texture_transforms_gpu_buffer = gpu.create_buffer(
            &BufferDescriptor::new(
                Some("Texture Transforms"),
                TEXTURE_TRANSFORMS_INITIAL_CAPACITY * TEXTURE_TRANSFORMS_BYTE_SIZE,
                *TEXTURE_TRANSFORM_BUFFER_USAGE,
            )
            .into(),
        )?;
        let mut texture_transforms_buffer = DynamicUniformBuffer::new(
            TEXTURE_TRANSFORMS_INITIAL_CAPACITY,
            TEXTURE_TRANSFORMS_BYTE_SIZE,
            None,
            Some("Texture Transforms".to_string()),
        );

        let mut texture_transforms = SlotMap::with_key();

        let texture_transform_identity_offset = {
            let transform = TextureTransform::identity();
            let key = texture_transforms.insert(transform.clone());

            texture_transforms_buffer.update(key, &transform.as_gpu_bytes());

            texture_transforms_buffer
                .offset(key)
                .expect("just inserted key must have offset")
        };

        Ok(Self {
            pool: TexturePool::new(),
            pool_sampler_set: IndexSet::new(),
            pool_textures: SlotMap::with_key(),
            cubemaps: SlotMap::with_key(),
            texture_transforms,
            texture_flows: SecondaryMap::new(),
            texture_flow_scratch: Vec::new(),
            texture_transforms_buffer,
            texture_transforms_gpu_buffer,
            texture_transforms_gpu_dirty: true,
            texture_transform_identity_offset,
            samplers,
            sampler_cache,
            sampler_address_modes,
            texture_transforms_uploader: crate::buffer::mapped_uploader::MappedUploader::new(
                "Texture Transforms",
            ),
            sampler_pool_dirty: false,
        })
    }

    /// Mapped-ring upload telemetry for the texture transforms buffer.
    pub fn texture_transforms_upload_stats(
        &self,
    ) -> crate::buffer::mapped_staging_ring::UploadStats {
        self.texture_transforms_uploader.stats()
    }

    /// Adds an image to the texture pool and returns its key.
    pub fn add_image(
        &mut self,
        image_data: ImageData,
        texture_format: TextureFormat,
        sampler_key: SamplerKey,
        color: TextureColorInfo,
    ) -> Result<TextureKey> {
        let key = self.pool_textures.try_insert_with_key(|key| {
            self.pool.add_image(key, image_data, texture_format, color);
            self.pool
                .entry(key)
                .ok_or(AwsmTextureError::TextureNotFound(key))
        })?;

        // `add_image` always flips the pool-array `gpu_dirty` bit, so
        // a *new* sampler insertion here will get picked up by the
        // standard `finalize_gpu_textures` rebuild path regardless of
        // `sampler_pool_dirty`. We still flip the flag so the
        // bookkeeping stays consistent with `ensure_sampler_in_pool`
        // — and so the rebuild gate is correct even if a future
        // change to `pool.add_image` ever skips the array dirty flag.
        if self.pool_sampler_set.insert(sampler_key) {
            self.sampler_pool_dirty = true;
        }

        Ok(key)
    }

    /// Adds a texture from raw RGBA8 bytes by packing them through a synchronous
    /// `OffscreenCanvas` → `ImageBitmap` round-trip and inserting via the
    /// standard pool path. Caller is responsible for triggering
    /// `AwsmRenderer::finalize_gpu_textures()` after a batch of additions so
    /// the new bitmaps actually upload to the GPU.
    pub fn add_image_rgba_raw(
        &mut self,
        rgba_bytes: &[u8],
        width: u32,
        height: u32,
        sampler_key: SamplerKey,
        color: TextureColorInfo,
    ) -> Result<TextureKey> {
        use wasm_bindgen::JsCast;
        let expected_len = (width as usize)
            .checked_mul(height as usize)
            .and_then(|n| n.checked_mul(4))
            .ok_or_else(|| {
                AwsmTextureError::ImageBitmapCreate(format!(
                    "rgba dims overflow: width={width} height={height}"
                ))
            })?;
        if rgba_bytes.len() != expected_len {
            return Err(AwsmTextureError::ImageBitmapCreate(format!(
                "rgba length mismatch: got {} bytes, want {expected_len} (width={width} height={height})",
                rgba_bytes.len()
            )));
        }

        let canvas = web_sys::OffscreenCanvas::new(width, height)
            .map_err(|e| AwsmTextureError::ImageBitmapCreate(format!("{e:?}")))?;
        let ctx_obj = canvas
            .get_context("2d")
            .map_err(|e| AwsmTextureError::ImageBitmapCreate(format!("get_context: {e:?}")))?
            .ok_or_else(|| {
                AwsmTextureError::ImageBitmapCreate("2d context unavailable".to_string())
            })?;
        let ctx: web_sys::OffscreenCanvasRenderingContext2d = ctx_obj.dyn_into().map_err(|_| {
            AwsmTextureError::ImageBitmapCreate("cast OffscreenCanvas 2d context".to_string())
        })?;

        // The FFI binding accepts `Clamped<&[u8]>`; web-sys will copy the
        // slice into a Wasm-side Uint8ClampedArray when constructing the
        // ImageData.
        let image_data = web_sys::ImageData::new_with_u8_clamped_array_and_sh(
            wasm_bindgen::Clamped(rgba_bytes),
            width,
            height,
        )
        .map_err(|e| AwsmTextureError::ImageBitmapCreate(format!("ImageData::new: {e:?}")))?;
        ctx.put_image_data(&image_data, 0, 0)
            .map_err(|e| AwsmTextureError::ImageBitmapCreate(format!("put_image_data: {e:?}")))?;
        let bitmap = canvas
            .transfer_to_image_bitmap()
            .map_err(|e| AwsmTextureError::ImageBitmapCreate(format!("transfer: {e:?}")))?;

        self.add_image(
            ImageData::Bitmap {
                image: bitmap,
                options: None,
            },
            TextureFormat::Rgba8unorm,
            sampler_key,
            color,
        )
    }

    /// Inserts a texture transform and returns its key.
    pub fn insert_texture_transform(
        &mut self,
        transform: &TextureTransform,
    ) -> TextureTransformKey {
        let key = self.texture_transforms.insert(transform.clone());
        let bytes = transform.as_gpu_bytes();
        self.texture_transforms_buffer.update(key, &bytes);
        self.texture_transforms_gpu_dirty = true;
        key
    }
    /// Updates an existing texture transform (CPU mirror + GPU bytes).
    pub fn update_texture_transform(
        &mut self,
        key: TextureTransformKey,
        transform: &TextureTransform,
    ) {
        if let Some(slot) = self.texture_transforms.get_mut(key) {
            *slot = transform.clone();
        }
        let bytes = transform.as_gpu_bytes();
        self.texture_transforms_buffer.update(key, &bytes);
        self.texture_transforms_gpu_dirty = true;
    }

    /// The current CPU-side transform for `key` (the read half of the
    /// read-modify-write an animation track does on one component).
    pub fn get_texture_transform(&self, key: TextureTransformKey) -> Option<&TextureTransform> {
        self.texture_transforms.get(key)
    }

    /// Register (or clear) UV flow for a transform key — `velocity` in UV-units/sec
    /// accumulated onto `base_offset` each frame by [`Self::advance_texture_flows`].
    /// `velocity == [0,0]` clears the flow (and snaps the offset back to base).
    pub fn set_texture_flow(
        &mut self,
        key: TextureTransformKey,
        base_offset: [f32; 2],
        velocity: [f32; 2],
    ) {
        if velocity == [0.0, 0.0] {
            self.texture_flows.remove(key);
            if let Some(t) = self.texture_transforms.get(key).cloned() {
                let mut t = t;
                if t.offset != base_offset {
                    t.offset = base_offset;
                    self.update_texture_transform(key, &t);
                }
            }
            return;
        }
        self.texture_flows.insert(
            key,
            TextureFlow {
                base_offset,
                velocity,
                elapsed: 0.0,
            },
        );
    }

    /// Advance every registered UV flow by `dt` seconds: `offset = base_offset +
    /// velocity * elapsed` (recompute-from-base, no drift), re-uploading the
    /// touched transforms. Called each frame from `update_animations`; a no-op
    /// when nothing flows.
    pub fn advance_texture_flows(&mut self, dt: f32) {
        if self.texture_flows.is_empty() {
            return;
        }
        for (_key, flow) in self.texture_flows.iter_mut() {
            flow.elapsed += dt;
        }
        self.flush_texture_flow_offsets();
    }

    /// Pin every UV flow to an ABSOLUTE elapsed time `t` (instead of integrating
    /// real `dt`): `offset = base_offset + velocity * t`. Used when the renderer's
    /// time source is pinned (`set_frame_time`, §7) so a flow scroll is
    /// **deterministic** for temporal screenshots — re-capturing at the same `t`
    /// yields the same offset. Idempotent; a no-op when nothing flows.
    pub fn set_texture_flows_elapsed(&mut self, t: f32) {
        if self.texture_flows.is_empty() {
            return;
        }
        for (_key, flow) in self.texture_flows.iter_mut() {
            flow.elapsed = t;
        }
        self.flush_texture_flow_offsets();
    }

    /// Recompute every flow's offset from its (already-updated) `elapsed` and
    /// re-upload the touched transforms. Splitting the offset compute from the
    /// `update_texture_transform` (which needs `&mut self`) needs a temporary —
    /// it reuses the pooled `texture_flow_scratch` (`mem::take`, capacity
    /// retained) so an active flow does NOT allocate every frame.
    fn flush_texture_flow_offsets(&mut self) {
        let mut updates = std::mem::take(&mut self.texture_flow_scratch);
        updates.clear();
        updates.extend(self.texture_flows.iter().map(|(key, flow)| {
            (
                key,
                flow_offset(flow.base_offset, flow.velocity, flow.elapsed),
            )
        }));
        for &(key, offset) in &updates {
            if let Some(mut t) = self.texture_transforms.get(key).cloned() {
                t.offset = offset;
                self.update_texture_transform(key, &t);
            }
        }
        self.texture_flow_scratch = updates;
    }

    /// Removes a texture transform.
    pub fn remove_texture_transform(&mut self, key: TextureTransformKey) {
        self.texture_transforms.remove(key);
        self.texture_flows.remove(key);
        self.texture_transforms_buffer.remove(key);
        self.texture_transforms_gpu_dirty = true;
    }

    /// Returns the byte offset for a texture transform.
    pub fn get_texture_transform_offset(&self, key: TextureTransformKey) -> Option<usize> {
        self.texture_transforms_buffer.offset(key)
    }

    /// Returns the slot index for a texture transform.
    pub fn get_texture_transform_slot_index(&self, key: TextureTransformKey) -> Option<usize> {
        self.texture_transforms_buffer.slot_index(key)
    }

    /// Inserts a cubemap texture and returns its key.
    pub fn insert_cubemap(&mut self, texture: web_sys::GpuTexture) -> CubemapTextureKey {
        self.cubemaps.insert(texture)
    }

    /// Returns a cubemap texture by key.
    pub fn get_cubemap(&self, key: CubemapTextureKey) -> Result<&web_sys::GpuTexture> {
        self.cubemaps
            .get(key)
            .ok_or(AwsmTextureError::CubemapTextureNotFound(key))
    }

    async fn write_gpu_texture_pool(
        &mut self,
        logging: &AwsmRendererLogging,
        gpu: &AwsmRendererWebGpu,
    ) -> Result<bool> {
        let _maybe_span_guard = if logging.render_timings.sub_frame() {
            Some(tracing::span!(tracing::Level::INFO, "Textures GPU write").entered())
        } else {
            None
        };

        self.pool.write_gpu(gpu).await.map_err(|e| e.into())
    }

    /// Writes texture transform data to the GPU if dirty.
    pub fn write_texture_transforms_gpu(
        &mut self,
        logging: &AwsmRendererLogging,
        gpu: &AwsmRendererWebGpu,
        bind_groups: &mut BindGroups,
    ) -> Result<()> {
        if self.texture_transforms_gpu_dirty {
            let _maybe_span_guard = if logging.render_timings.sub_frame() {
                Some(tracing::span!(tracing::Level::INFO, "Texture Transforms GPU write").entered())
            } else {
                None
            };

            let mut resized = false;
            if let Some(new_size) = self.texture_transforms_buffer.take_gpu_needs_resize() {
                self.texture_transforms_gpu_buffer = gpu.create_buffer(
                    &BufferDescriptor::new(
                        Some("Texture Transforms"),
                        new_size,
                        *TEXTURE_TRANSFORM_BUFFER_USAGE,
                    )
                    .into(),
                )?;

                bind_groups.mark_create(BindGroupCreate::TextureTransformsResize);
                resized = true;
            }

            if resized {
                self.texture_transforms_buffer.clear_dirty_ranges();
                gpu.write_buffer(
                    &self.texture_transforms_gpu_buffer,
                    None,
                    self.texture_transforms_buffer.raw_slice(),
                    None,
                    None,
                )?;
            } else {
                let ranges = self.texture_transforms_buffer.take_dirty_ranges();
                self.texture_transforms_uploader.write_dirty_ranges(
                    gpu,
                    &self.texture_transforms_gpu_buffer,
                    self.texture_transforms_buffer.raw_slice().len(),
                    self.texture_transforms_buffer.raw_slice(),
                    &ranges,
                )?;
            }

            self.texture_transforms_gpu_dirty = false;
        }
        Ok(())
    }

    /// Removes a texture from the pool + slotmap. Returns `true` if the
    /// key existed; `false` if it was already gone. The pool recycles
    /// the freed layer slot for the next matching add — see
    /// [`TexturePool::remove`] for the invariants. Callers are
    /// responsible for ensuring no live material still binds this key
    /// (the renderer doesn't trace texture → material refs).
    pub fn remove(&mut self, key: TextureKey) -> bool {
        if self.pool.remove(key).is_some() {
            self.pool_textures.remove(key);
            true
        } else {
            false
        }
    }

    /// Returns pool entry info for a texture key.
    pub fn get_entry(&self, key: TextureKey) -> Result<&TexturePoolEntryInfo<TextureKey>> {
        self.pool_textures
            .get(key)
            .ok_or(AwsmTextureError::TextureNotFound(key))
    }

    /// Returns a sampler key, inserting if missing.
    pub fn get_sampler_key(
        &mut self,
        gpu: &AwsmRendererWebGpu,
        cache_key: SamplerCacheKey,
    ) -> Result<SamplerKey> {
        if let Some(sampler_key) = self.sampler_cache.get(&cache_key) {
            return Ok(*sampler_key);
        }

        create_sampler_key(
            gpu,
            cache_key,
            &mut self.samplers,
            &mut self.sampler_cache,
            &mut self.sampler_address_modes,
        )
    }

    /// Register `sampler_key` in `pool_sampler_set` if it's not already
    /// there, marking the sampler-pool dirty bit so the next
    /// `finalize_gpu_textures` call rebuilds the texture-pool bind
    /// group + dependent pipeline layouts. Returns `true` when the
    /// insertion was new (and therefore a rebuild is required), `false`
    /// when the sampler was already in the pool.
    ///
    /// `add_image` already inserts the sampler that was passed at upload
    /// time, but a sampler that's only ever bound to a *cache-hit*
    /// texture (the editor's MaterialDef override path resolving a
    /// renderer-gltf-seeded `TextureKey`) wouldn't reach `add_image` —
    /// it'd silently fail `sampler_index` lookup at draw time and the
    /// shader would `SkipTexture` (rendering the material's base-color
    /// factor alone, i.e. pure white for a `[1,1,1,1]` default).
    ///
    /// Call this from any path that binds an existing `TextureKey` to
    /// a new sampler that wasn't previously in the pool, then ensure
    /// `AwsmRenderer::finalize_gpu_textures()` runs at the batch end
    /// — both the editor (`instance_batcher`, `particles_sync`) and
    /// the glTF populate path already do so unconditionally, which is
    /// why this returns `bool` rather than triggering a rebuild
    /// itself: the rebuild is async + expensive and should stay
    /// batched.
    pub fn ensure_sampler_in_pool(&mut self, sampler_key: SamplerKey) -> bool {
        let inserted = self.pool_sampler_set.insert(sampler_key);
        if inserted {
            self.sampler_pool_dirty = true;
        }
        inserted
    }

    /// Consume the sampler-pool dirty bit. `finalize_gpu_textures`
    /// ORs the returned value with the pool-write dirty bit when
    /// deciding whether to rebuild material bind groups + pipeline
    /// layouts.
    pub(crate) fn take_sampler_pool_dirty(&mut self) -> bool {
        std::mem::take(&mut self.sampler_pool_dirty)
    }

    /// Returns a sampler by key.
    pub fn get_sampler(&self, key: SamplerKey) -> Result<&web_sys::GpuSampler> {
        self.samplers
            .get(key)
            .ok_or(AwsmTextureError::SamplerNotFound(key))
    }

    /// Returns cached sampler address modes.
    pub fn sampler_address_modes(
        &self,
        key: SamplerKey,
    ) -> (Option<AddressMode>, Option<AddressMode>) {
        self.sampler_address_modes
            .get(key)
            .copied()
            .unwrap_or((None, None))
    }
}

fn create_sampler_key(
    gpu: &AwsmRendererWebGpu,
    cache_key: SamplerCacheKey,
    samplers: &mut SlotMap<SamplerKey, web_sys::GpuSampler>,
    sampler_cache: &mut HashMap<SamplerCacheKey, SamplerKey>,
    sampler_address_modes: &mut SecondaryMap<
        SamplerKey,
        (Option<AddressMode>, Option<AddressMode>),
    >,
) -> Result<SamplerKey> {
    let descriptor = SamplerDescriptor {
        label: None,
        address_mode_u: cache_key.address_mode_u,
        address_mode_v: cache_key.address_mode_v,
        address_mode_w: cache_key.address_mode_w,
        compare: cache_key.compare,
        lod_min_clamp: cache_key.lod_min_clamp.map(|x| x.into_inner()),
        lod_max_clamp: cache_key.lod_max_clamp.map(|x| x.into_inner()),
        max_anisotropy: cache_key.max_anisotropy,
        mag_filter: cache_key.mag_filter,
        min_filter: cache_key.min_filter,
        mipmap_filter: cache_key.mipmap_filter,
    };

    // tracing::info!("address_mode_u: {address_mode_u:?}, address_mode_v: {address_mode_v:?}, address_mode_w: {address_mode_w:?}, compare: {compare:?}, lod_min_clamp: {lod_min_clamp:?}, lod_max_clamp: {lod_max_clamp:?}, max_anisotropy: {max_anisotropy:?}, mag_filter: {mag_filter:?}, min_filter: {min_filter:?}, mipmap_filter: {mipmap_filter:?}",
    //     address_mode_u = cache_key.address_mode_u,
    //     address_mode_v = cache_key.address_mode_v,
    //     address_mode_w = cache_key.address_mode_w,
    //     compare = cache_key.compare,
    //     lod_min_clamp = cache_key.lod_min_clamp,
    //     lod_max_clamp = cache_key.lod_max_clamp,
    //     max_anisotropy = cache_key.max_anisotropy,
    //     mag_filter = cache_key.mag_filter,
    //     min_filter = cache_key.min_filter,
    //     mipmap_filter = cache_key.mipmap_filter,
    // );

    let sampler = gpu.create_sampler(Some(&descriptor.into()));

    let key = samplers.insert(sampler);
    let address_mode_u = cache_key.address_mode_u;
    let address_mode_v = cache_key.address_mode_v;
    sampler_cache.insert(cache_key, key);
    // Persist the original (U,V) wrap modes so that shader-side helpers can reproduce the
    sampler_address_modes.insert(key, (address_mode_u, address_mode_v));

    Ok(key)
}

// `TextureKey`, `TextureTransformKey`, `SamplerKey` moved to
// `awsm-renderer-core::keys` so the `awsm-renderer-materials` crate can reference
// them without depending on `awsm-renderer`. Re-exported here for backward
// compat with existing callers that import via `awsm_renderer`.
pub use awsm_renderer_core::keys::{SamplerKey, TextureKey, TextureTransformKey};

impl awsm_renderer_materials::TextureContext for Textures {
    fn pool_array_by_index(
        &self,
        index: usize,
    ) -> Option<&awsm_renderer_core::texture::texture_pool::TexturePoolArray<TextureKey>> {
        self.pool.array_by_index(index)
    }

    fn texture_entry(&self, key: TextureKey) -> Option<&TexturePoolEntryInfo<TextureKey>> {
        self.pool_textures.get(key)
    }

    fn sampler_index(&self, key: SamplerKey) -> Option<u32> {
        self.pool_sampler_set.get_index_of(&key).map(|i| i as u32)
    }

    fn sampler_address_modes(&self, key: SamplerKey) -> (Option<AddressMode>, Option<AddressMode>) {
        self.sampler_address_modes
            .get(key)
            .copied()
            .unwrap_or((None, None))
    }

    fn texture_transform_offset(&self, key: TextureTransformKey) -> Option<usize> {
        self.get_texture_transform_offset(key)
    }

    fn texture_transform_identity_offset(&self) -> usize {
        self.texture_transform_identity_offset
    }
}

new_key_type! {
    /// Opaque key for cubemap textures.
    pub struct CubemapTextureKey;
}

/// Result type for texture operations.
pub type Result<T> = std::result::Result<T, AwsmTextureError>;

/// Texture-related errors.
#[derive(Error, Debug)]
pub enum AwsmTextureError {
    #[error("[texture] {0:?}")]
    Core(#[from] AwsmCoreError),

    #[error("[texture] pool failure")]
    Pool,

    #[error("[texture] sampler not found: {0:?}")]
    SamplerNotFound(SamplerKey),

    #[error("[texture] texture not found: {0:?}")]
    TextureNotFound(TextureKey),

    #[error("[texture] subemap texture not found: {0:?}")]
    CubemapTextureNotFound(CubemapTextureKey),

    #[error("[texture] no clamp sampler found in mega-texture")]
    NoClampSamplerInMegaTexture,

    #[error("[texture] runtime image bitmap creation failed: {0}")]
    ImageBitmapCreate(String),
}