qualia_core_db/render/gpu/

mod.rs

//! Cross-platform WebGPU viewport for the Qualia renderer SDK.
//!
//! Phenomenal viewport: projector (depth write) → ambient → optional T2 Kawase bloom.

use crate::gpu_context::{
    ambient_draw_instances, global_vram_ledger, universe_orchestrator, ComputeUniverse,
    OperationalMode,
};
use crate::render::camera::CameraState;
use crate::render::navigation::PICK_SENTINEL;
use crate::render::pga::{motor_to_mat4_col, Motor};
use crate::render::physics::{Aabb, Admission, Joint};
use crate::render::standpoint::spectator_default;
use crate::render::telemetry::{
    AmbientUniforms, ObserverStandpoint, ParticleInstance, SystemTelemetry,
};
use crate::shaders::viewport::{AMBIENT_WGSL, BLOOM_WGSL, MESH_WGSL, PROJECTOR_WGSL};
use crate::tensor::buffer_export::{
    read_tensor_at, tensor_node_count, TENSOR_HEADER_BYTES, TENSOR_STRIDE,
};

use std::sync::Arc;
use wgpu::util::DeviceExt;

/// Static ambient SSBO capacity — draw count is throttled per `VramLedger` mode.
const MAX_AMBIENT_INSTANCES: usize = 50_000;
const HDR_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba16Float;
const BLOOM_THRESHOLD: f32 = 1.0;
const BLOOM_INTENSITY: f32 = 1.15;
const BLOOM_STRENGTH: f32 = 0.85;
const BLOOM_EXPOSURE: f32 = 1.05;
const KAWASE_OFFSETS: [f32; 4] = [1.0, 2.0, 4.0, 8.0];

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct BloomParamsGpu {
    threshold: f32,
    intensity: f32,
    offset: f32,
    _pad: f32,
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct CompositeParamsGpu {
    exposure: f32,
    bloom_strength: f32,
    _pad0: f32,
    _pad1: f32,
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct BloomUniformBlock {
    bloom: BloomParamsGpu,
    composite: CompositeParamsGpu,
}

/// HDR scene target + half-res Kawase ping-pong (allocated only in `OperationalMode::Full`).
struct BloomChain {
    hdr_texture: wgpu::Texture,
    hdr_view: wgpu::TextureView,
    blur_a: wgpu::Texture,
    blur_a_view: wgpu::TextureView,
    blur_b: wgpu::Texture,
    blur_b_view: wgpu::TextureView,
    dummy_view: wgpu::TextureView,
    sampler: wgpu::Sampler,
    uniform_buf: wgpu::Buffer,
    bind_layout: wgpu::BindGroupLayout,
    extract_pipeline: wgpu::RenderPipeline,
    kawase_pipeline: wgpu::RenderPipeline,
    composite_pipeline: wgpu::RenderPipeline,
    half_width: u32,
    half_height: u32,
    vram_bytes: u64,
}

impl BloomChain {
    /// HDR scene target extent in pixels.
    pub(super) fn hdr_extent(&self) -> (u32, u32) {
        (self.hdr_texture.width(), self.hdr_texture.height())
    }

    /// Half-resolution Kawase ping-pong extent.
    pub(super) fn blur_extent(&self) -> (u32, u32) {
        (self.half_width, self.half_height)
    }

    /// Keep texture handles alive for resize validation / VRAM accounting.
    pub(super) fn texture_handles(&self) -> (&wgpu::Texture, &wgpu::Texture, &wgpu::Texture) {
        (&self.hdr_texture, &self.blur_a, &self.blur_b)
    }
}

/// WebGPU phenomenal viewport — tensor projector + ambient particles.
/// GPU buffers for an imported triangle mesh (Phase 1.2). Positions are model-space `f32x3`
/// (already centred + scaled to the orbit frame by the caller); `index_count` is `triangles * 3`.
struct MeshGpu {
    vertex_buf: wgpu::Buffer,
    color_buf: wgpu::Buffer,
    index_buf: wgpu::Buffer,
    index_count: u32,
}

pub struct PortalGpu {
    device: Arc<wgpu::Device>,
    queue: Arc<wgpu::Queue>,
    surface: Option<wgpu::Surface<'static>>,
    config: Option<wgpu::SurfaceConfiguration>,
    offscreen_texture: Option<wgpu::Texture>,
    readback_buf: Option<wgpu::Buffer>,
    readback_bytes_per_row: u32,
    color_format: wgpu::TextureFormat,
    depth_texture: wgpu::Texture,
    depth_view: wgpu::TextureView,
    picking_texture: wgpu::Texture,
    picking_view: wgpu::TextureView,
    picking_pipeline: wgpu::RenderPipeline,
    pick_staging_buf: wgpu::Buffer,
    pending_pick: Option<(u32, u32)>,
    pick_copy_submitted: bool,
    pick_result: Option<u32>,
    ambient_pipeline: wgpu::RenderPipeline,
    projector_pipeline: wgpu::RenderPipeline,
    ambient_pipeline_hdr: Option<wgpu::RenderPipeline>,
    projector_pipeline_hdr: Option<wgpu::RenderPipeline>,
    mesh_pipeline: wgpu::RenderPipeline,
    mesh_pipeline_hdr: Option<wgpu::RenderPipeline>,
    mesh: Option<MeshGpu>,
    model_buf: wgpu::Buffer,
    mesh_model_bind: wgpu::BindGroup,
    artefact_joint: Option<Joint>,
    /// Sim-time at which the current joint was engaged; the joint is driven by *elapsed* time
    /// (`time − artefact_t0`), not absolute sim-time, so a slide/spin always starts from rest when
    /// armed (set lazily on the first frame after `set_artefact_joint`).
    artefact_t0: Option<f32>,
    mesh_base_aabb: Option<Aabb>,
    artefact_world: Option<Aabb>,
    last_admitted: Motor,
    last_refused: bool,
    bloom: Option<BloomChain>,
    ambient_bind_group_layout: wgpu::BindGroupLayout,
    ambient_bind_group: wgpu::BindGroup,
    projector_camera_layout: wgpu::BindGroupLayout,
    projector_tensor_layout: wgpu::BindGroupLayout,
    projector_camera_bind: wgpu::BindGroup,
    projector_tensor_bind: Option<wgpu::BindGroup>,
    uniform_buf: wgpu::Buffer,
    telemetry_buf: wgpu::Buffer,
    camera_buf: wgpu::Buffer,
    observer_buf: wgpu::Buffer,
    camera: CameraState,
    observer: ObserverStandpoint,
    particle_buf: wgpu::Buffer,
    tensor_raw_buf: Option<wgpu::Buffer>,
    tensor_node_count: u32,
    particle_count: u32,
    /// Whether the ambient particle field is drawn. **Off by default** — the field is a random
    /// decorative cloud (`generate_particles`, `epistemic_q = 0`) unless a Tensor10D is uploaded,
    /// which sets this true because the particles then ARE the epistemic nodes. The mixer's "ambient"
    /// channel toggles it explicitly.
    ambient_enabled: bool,
    width: u32,
    height: u32,
}

impl PortalGpu {
    /// Build a native offscreen renderer on QualiaDB's process-wide shared GPU device.
    ///
    /// The output target is linear `Rgba8Unorm`. Call [`Self::render`] and then
    /// [`Self::read_rgba8_into`] to retrieve tightly packed pixels into a caller-owned buffer.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn new_offscreen(width: u32, height: u32, particle_cap: usize) -> Result<Self, String> {
        let shared = crate::gpu_context::shared_gpu();
        pollster::block_on(Self::from_device(
            Arc::new(shared.device.clone()),
            Arc::new(shared.queue.clone()),
            width.max(1),
            height.max(1),
            wgpu::TextureFormat::Rgba8Unorm,
            None,
            None,
            particle_cap,
        ))
    }

    /// Build a native **surface** renderer that draws directly to a window's GPU swapchain.
    ///
    /// This is the native desktop path — no PNG round-trip, no webview `<img>`. The surface
    /// is created from a raw window handle (HWND on Windows) and frames are presented directly
    /// to the OS swapchain.
    ///
    /// The surface format is chosen from the adapter's capabilities (sRGB preferred).
    /// Call [`Self::render`] to draw a frame; the swapchain present is automatic.
    #[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
    pub fn new_surface(
        hwnd: isize,
        width: u32,
        height: u32,
        particle_cap: usize,
    ) -> Result<Self, String> {
        use raw_window_handle::{
            RawDisplayHandle, RawWindowHandle, Win32WindowHandle, WindowsDisplayHandle,
        };

        // Create a DEDICATED instance/adapter/device for the surface renderer.
        // The shared GPU context is optimised for compute (LLM inference) and its
        // adapter may not support presentation to an HWND (e.g. Vulkan without a
        // VkSurfaceKHR, or a compute-only adapter). A dedicated instance ensures
        // the surface, adapter, and device are all from the same wgpu instance and
        // the adapter is picked with surface compatibility.
        let mut desc = wgpu::InstanceDescriptor::new_without_display_handle();
        desc.backends = wgpu::Backends::all();
        let instance = wgpu::Instance::new(desc);

        let win32_handle =
            Win32WindowHandle::new(std::num::NonZeroIsize::new(hwnd).ok_or("invalid HWND (zero)")?);
        let raw_window = RawWindowHandle::Win32(win32_handle);
        let raw_display = RawDisplayHandle::Windows(WindowsDisplayHandle::new());

        let surface = unsafe {
            instance
                .create_surface_unsafe(wgpu::SurfaceTargetUnsafe::RawHandle {
                    raw_display_handle: Some(raw_display),
                    raw_window_handle: raw_window,
                })
                .map_err(|e| format!("create_surface from HWND: {e:?}"))?
        };

        // Request an adapter that supports the surface
        let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
            power_preference: wgpu::PowerPreference::HighPerformance,
            compatible_surface: Some(&surface),
            ..Default::default()
        }))
        .map_err(|e| format!("Failed to find wgpu adapter for surface: {e}"))?;

        let caps = surface.get_capabilities(&adapter);
        if caps.formats.is_empty() {
            return Err(format!(
                "Surface supports no formats — adapter backend {:?} may not support presentation to HWND",
                adapter.get_info().backend
            ));
        }
        let format = caps
            .formats
            .iter()
            .copied()
            .find(|f| f.is_srgb())
            .unwrap_or(caps.formats[0]);

        let (device, queue) = pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor {
            label: Some("Webizen GPU Surface"),
            required_features: wgpu::Features::empty(),
            required_limits: wgpu::Limits::downlevel_defaults(),
            memory_hints: wgpu::MemoryHints::default(),
            ..Default::default()
        }))
        .map_err(|e| format!("Failed to request device for surface: {e}"))?;

        let device = Arc::new(device);
        let queue = Arc::new(queue);

        let config = wgpu::SurfaceConfiguration {
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            format,
            width: width.max(1),
            height: height.max(1),
            present_mode: wgpu::PresentMode::Fifo,
            alpha_mode: caps
                .alpha_modes
                .first()
                .copied()
                .unwrap_or(wgpu::CompositeAlphaMode::Auto),
            view_formats: vec![],
            desired_maximum_frame_latency: 2,
            // wgpu 30: surfaces declare their colour space; Auto preserves the
            // pre-30 (implicit sRGB/linear-by-format) behaviour.
            color_space: wgpu::SurfaceColorSpace::Auto,
        };

        surface.configure(&device, &config);

        pollster::block_on(Self::from_device(
            device,
            queue,
            width.max(1),
            height.max(1),
            format,
            Some(surface),
            Some(config),
            particle_cap,
        ))
    }

    /// Async WebGPU init — awaits `request_adapter` / `request_device` (the browser main thread
    /// cannot block). Native callers use the `try_new` wrapper above.
    #[cfg(all(target_arch = "wasm32", feature = "portal"))]
    pub async fn try_new_async(
        canvas: &web_sys::HtmlCanvasElement,
        particle_cap: usize,
    ) -> Result<Self, String> {
        let width = canvas.width().max(1);
        let height = canvas.height().max(1);

        let mut instance_desc = wgpu::InstanceDescriptor::new_without_display_handle();
        instance_desc.backends = wgpu::Backends::BROWSER_WEBGPU;
        let instance = wgpu::Instance::new(instance_desc);

        let surface = instance
            .create_surface(wgpu::SurfaceTarget::Canvas(canvas.clone()))
            .map_err(|e| format!("surface: {e}"))?;

        let adapter = instance
            .request_adapter(&wgpu::RequestAdapterOptions {
                power_preference: wgpu::PowerPreference::LowPower,
                compatible_surface: Some(&surface),
                // `..Default::default()` covers force_fallback_adapter (false) and
                // wgpu 30's apply_limit_buckets, and stays robust to future fields.
                ..Default::default()
            })
            .await
            .map_err(|e| format!("no WebGPU adapter: {e}"))?;

        let (device, queue) = adapter
            .request_device(&wgpu::DeviceDescriptor {
                label: Some("qualia-portal-gpu"),
                required_features: wgpu::Features::empty(),
                // Request exactly the adapter's advertised limits. `Limits::default()`
                // under wgpu 30 asks for desktop-tier limits that a browser WebGPU
                // adapter does not grant, so `request_device` would fail device
                // validation. `adapter.limits()` never over-requests and still preserves
                // the non-zero storage-buffer limits the portal pipelines need (unlike
                // `downlevel_webgl2_defaults`, which zeroes them and blacks out the view).
                required_limits: adapter.limits(),
                ..Default::default()
            })
            .await
            .map_err(|e| format!("device: {e}"))?;

        let caps = surface.get_capabilities(&adapter);
        let format = caps
            .formats
            .iter()
            .copied()
            .find(|f| f.is_srgb())
            .unwrap_or(caps.formats[0]);

        let config = wgpu::SurfaceConfiguration {
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            format,
            width,
            height,
            present_mode: wgpu::PresentMode::Fifo,
            alpha_mode: caps.alpha_modes[0],
            view_formats: vec![],
            desired_maximum_frame_latency: 2,
            // wgpu 30: Auto preserves pre-30 colour-space behaviour.
            color_space: wgpu::SurfaceColorSpace::Auto,
        };
        surface.configure(&device, &config);

        Self::from_device(
            Arc::new(device),
            Arc::new(queue),
            width,
            height,
            format,
            Some(surface),
            Some(config),
            particle_cap,
        )
        .await
    }

    async fn from_device(
        device: Arc<wgpu::Device>,
        queue: Arc<wgpu::Queue>,
        width: u32,
        height: u32,
        format: wgpu::TextureFormat,
        surface: Option<wgpu::Surface<'static>>,
        config: Option<wgpu::SurfaceConfiguration>,
        particle_cap: usize,
    ) -> Result<Self, String> {
        let particle_count = particle_cap.clamp(256, MAX_AMBIENT_INSTANCES);

        // Capture deferred pipeline/shader creation errors on both Dawn and native backends.
        let error_scope = device.push_error_scope(wgpu::ErrorFilter::Validation);

        let (depth_texture, depth_view) = create_depth_texture(&device, width, height);
        let (picking_texture, picking_view) = create_picking_texture(&device, width, height);
        let offscreen_texture = if surface.is_none() {
            Some(create_offscreen_texture(&device, format, width, height))
        } else {
            None
        };
        let readback_bytes_per_row = padded_bytes_per_row(width);
        let readback_buf = if surface.is_none() {
            Some(create_readback_buffer(
                &device,
                readback_bytes_per_row,
                height,
            ))
        } else {
            None
        };

        let particles = generate_particles(particle_count);
        let particle_buf = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("portal-particles"),
            contents: bytemuck::cast_slice(&particles),
            usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
        });

        let uniform_buf = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("portal-ambient-uniforms"),
            contents: bytemuck::bytes_of(&AmbientUniforms {
                time: 0.0,
                view_width: width as f32,
                view_height: height as f32,
                _padding: 0.0,
            }),
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
        });

        let telemetry_buf = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("portal-telemetry"),
            contents: bytemuck::bytes_of(&SystemTelemetry::default()),
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
        });

        let camera = CameraState::default();
        let aspect = width as f32 / height.max(1) as f32;
        let camera_uniform = camera.to_uniform(aspect, false);
        let camera_buf = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("portal-camera"),
            contents: bytemuck::bytes_of(&camera_uniform),
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
        });

        let session_nonce = crate::render::standpoint::generate_session_nonce();
        let observer = spectator_default(session_nonce);
        let observer_buf = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("portal-observer"),
            contents: bytemuck::bytes_of(&observer),
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
        });

        let ambient_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("portal-ambient"),
            source: wgpu::ShaderSource::Wgsl(AMBIENT_WGSL.into()),
        });

        let projector_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("portal-projector"),
            source: wgpu::ShaderSource::Wgsl(PROJECTOR_WGSL.into()),
        });

        let mesh_shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("portal-mesh"),
            source: wgpu::ShaderSource::Wgsl(MESH_WGSL.into()),
        });

        let ambient_bind_group_layout =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("portal-ambient-layout"),
                entries: &ambient_bind_entries(),
            });

        let ambient_bind_group = make_ambient_bind_group(
            &device,
            &ambient_bind_group_layout,
            &uniform_buf,
            &telemetry_buf,
            &camera_buf,
            &observer_buf,
            &particle_buf,
        );

        let projector_camera_layout =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("portal-projector-camera-layout"),
                entries: &[
                    uniform_128_bind_entry(0, wgpu::ShaderStages::VERTEX),
                    uniform_128_bind_entry(1, wgpu::ShaderStages::VERTEX_FRAGMENT),
                ],
            });

        let projector_tensor_layout =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("portal-projector-tensor-layout"),
                entries: &[tensor_storage_bind_entry()],
            });

        let projector_camera_bind = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("portal-projector-camera-bind"),
            layout: &projector_camera_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: camera_buf.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: observer_buf.as_entire_binding(),
                },
            ],
        });

        let depth_state = depth_stencil_state(wgpu::TextureFormat::Depth32Float);

        let ambient_pipeline_layout =
            device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                label: Some("portal-ambient-pipeline-layout"),
                bind_group_layouts: &[Some(&ambient_bind_group_layout)],
                immediate_size: 0,
            });

        let projector_pipeline_layout =
            device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                label: Some("portal-projector-pipeline-layout"),
                bind_group_layouts: &[
                    Some(&projector_camera_layout),
                    Some(&projector_tensor_layout),
                ],
                immediate_size: 0,
            });

        let ambient_pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("portal-ambient-pipeline"),
            layout: Some(&ambient_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &ambient_shader,
                entry_point: Some("vertex_main"),
                compilation_options: Default::default(),
                buffers: &[],
            },
            fragment: Some(wgpu::FragmentState {
                module: &ambient_shader,
                entry_point: Some("fragment_main"),
                compilation_options: Default::default(),
                targets: &[Some(color_target_state(format))],
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                ..Default::default()
            },
            depth_stencil: Some(depth_stencil_state_read_only()),
            multisample: wgpu::MultisampleState::default(),
            multiview_mask: None,
            cache: None,
        });

        let projector_pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("portal-projector-pipeline"),
            layout: Some(&projector_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &projector_shader,
                entry_point: Some("vertex_main"),
                compilation_options: Default::default(),
                buffers: &[],
            },
            fragment: Some(wgpu::FragmentState {
                module: &projector_shader,
                entry_point: Some("fragment_main"),
                compilation_options: Default::default(),
                targets: &[Some(color_target_state(format))],
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                ..Default::default()
            },
            depth_stencil: Some(depth_state.clone()),
            multisample: wgpu::MultisampleState::default(),
            multiview_mask: None,
            cache: None,
        });

        // Per-artefact model transform (Phase 2 kinematic joint), group 1 of the mesh pipeline.
        const IDENTITY_MAT4: [[f32; 4]; 4] = [
            [1.0, 0.0, 0.0, 0.0],
            [0.0, 1.0, 0.0, 0.0],
            [0.0, 0.0, 1.0, 0.0],
            [0.0, 0.0, 0.0, 1.0],
        ];
        let model_buf = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("portal-mesh-model"),
            contents: bytemuck::cast_slice(&IDENTITY_MAT4),
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
        });
        let mesh_model_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("portal-mesh-model-layout"),
            entries: &[wgpu::BindGroupLayoutEntry {
                binding: 0,
                visibility: wgpu::ShaderStages::VERTEX,
                ty: wgpu::BindingType::Buffer {
                    ty: wgpu::BufferBindingType::Uniform,
                    has_dynamic_offset: false,
                    min_binding_size: std::num::NonZeroU64::new(64),
                },
                count: None,
            }],
        });
        let mesh_model_bind = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("portal-mesh-model-bind"),
            layout: &mesh_model_layout,
            entries: &[wgpu::BindGroupEntry {
                binding: 0,
                resource: model_buf.as_entire_binding(),
            }],
        });

        // Triangle-mesh pipeline (Phase 1.2). Reuses the projector camera bind layout (mesh shader
        // declares only camera@0, a valid subset); one f32x3 vertex buffer at slot 0; cull disabled
        // (imported meshes carry inconsistent winding). HDR variant built in the bloom block below.
        let mesh_pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("portal-mesh-pipeline-layout"),
            bind_group_layouts: &[Some(&projector_camera_layout), Some(&mesh_model_layout)],
            immediate_size: 0,
        });
        let mesh_vertex_layout = wgpu::VertexBufferLayout {
            array_stride: 12,
            step_mode: wgpu::VertexStepMode::Vertex,
            attributes: &[wgpu::VertexAttribute {
                format: wgpu::VertexFormat::Float32x3,
                offset: 0,
                shader_location: 0,
            }],
        };
        let mesh_color_layout = wgpu::VertexBufferLayout {
            array_stride: 16,
            step_mode: wgpu::VertexStepMode::Vertex,
            attributes: &[wgpu::VertexAttribute {
                format: wgpu::VertexFormat::Float32x4,
                offset: 0,
                shader_location: 1,
            }],
        };
        let mesh_pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("portal-mesh-pipeline"),
            layout: Some(&mesh_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &mesh_shader,
                entry_point: Some("vertex_main"),
                compilation_options: Default::default(),
                buffers: &[
                    Some(mesh_vertex_layout.clone()),
                    Some(mesh_color_layout.clone()),
                ],
            },
            fragment: Some(wgpu::FragmentState {
                module: &mesh_shader,
                entry_point: Some("fragment_main"),
                compilation_options: Default::default(),
                targets: &[Some(color_target_state(format))],
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                cull_mode: None,
                ..Default::default()
            },
            depth_stencil: Some(depth_state.clone()),
            multisample: wgpu::MultisampleState::default(),
            multiview_mask: None,
            cache: None,
        });

        let picking_pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("portal-picking-pipeline"),
            layout: Some(&projector_pipeline_layout),
            vertex: wgpu::VertexState {
                module: &projector_shader,
                entry_point: Some("vertex_main"),
                compilation_options: Default::default(),
                buffers: &[],
            },
            fragment: Some(wgpu::FragmentState {
                module: &projector_shader,
                entry_point: Some("picking_fragment_main"),
                compilation_options: Default::default(),
                targets: &[Some(picking_color_target_state())],
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                ..Default::default()
            },
            depth_stencil: Some(depth_state.clone()),
            multisample: wgpu::MultisampleState::default(),
            multiview_mask: None,
            cache: None,
        });

        let pick_staging_buf = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("portal-pick-staging"),
            size: 4,
            usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });

        let bloom_wanted = portal_bloom_enabled() && probe_hdr_format(&device);
        let (ambient_pipeline_hdr, projector_pipeline_hdr, mesh_pipeline_hdr, bloom) =
            if bloom_wanted {
                let ambient_hdr = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                    label: Some("portal-ambient-hdr"),
                    layout: Some(&ambient_pipeline_layout),
                    vertex: wgpu::VertexState {
                        module: &ambient_shader,
                        entry_point: Some("vertex_main"),
                        compilation_options: Default::default(),
                        buffers: &[],
                    },
                    fragment: Some(wgpu::FragmentState {
                        module: &ambient_shader,
                        entry_point: Some("fragment_main"),
                        compilation_options: Default::default(),
                        targets: &[Some(hdr_color_target_state())],
                    }),
                    primitive: wgpu::PrimitiveState {
                        topology: wgpu::PrimitiveTopology::TriangleList,
                        ..Default::default()
                    },
                    depth_stencil: Some(depth_stencil_state_read_only()),
                    multisample: wgpu::MultisampleState::default(),
                    multiview_mask: None,
                    cache: None,
                });
                let projector_hdr =
                    device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                        label: Some("portal-projector-hdr"),
                        layout: Some(&projector_pipeline_layout),
                        vertex: wgpu::VertexState {
                            module: &projector_shader,
                            entry_point: Some("vertex_main"),
                            compilation_options: Default::default(),
                            buffers: &[],
                        },
                        fragment: Some(wgpu::FragmentState {
                            module: &projector_shader,
                            entry_point: Some("fragment_main"),
                            compilation_options: Default::default(),
                            targets: &[Some(hdr_color_target_state())],
                        }),
                        primitive: wgpu::PrimitiveState {
                            topology: wgpu::PrimitiveTopology::TriangleList,
                            ..Default::default()
                        },
                        depth_stencil: Some(depth_state.clone()),
                        multisample: wgpu::MultisampleState::default(),
                        multiview_mask: None,
                        cache: None,
                    });
                let mesh_hdr = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                    label: Some("portal-mesh-hdr"),
                    layout: Some(&mesh_pipeline_layout),
                    vertex: wgpu::VertexState {
                        module: &mesh_shader,
                        entry_point: Some("vertex_main"),
                        compilation_options: Default::default(),
                        buffers: &[
                            Some(mesh_vertex_layout.clone()),
                            Some(mesh_color_layout.clone()),
                        ],
                    },
                    fragment: Some(wgpu::FragmentState {
                        module: &mesh_shader,
                        entry_point: Some("fragment_main"),
                        compilation_options: Default::default(),
                        targets: &[Some(hdr_color_target_state())],
                    }),
                    primitive: wgpu::PrimitiveState {
                        topology: wgpu::PrimitiveTopology::TriangleList,
                        cull_mode: None,
                        ..Default::default()
                    },
                    depth_stencil: Some(depth_state.clone()),
                    multisample: wgpu::MultisampleState::default(),
                    multiview_mask: None,
                    cache: None,
                });
                let bloom = create_bloom_chain(&device, width, height, format);
                (
                    Some(ambient_hdr),
                    Some(projector_hdr),
                    Some(mesh_hdr),
                    bloom,
                )
            } else {
                (None, None, None, None)
            };

        let mut render_bytes = (particle_count * std::mem::size_of::<ParticleInstance>()) as u64;
        if let Some(ref chain) = bloom {
            render_bytes += chain.vram_bytes;
        }
        global_vram_ledger().record_render(render_bytes);

        // Surface otherwise-silent deferred pipeline/shader creation errors. Dawn (WebGPU) is far
        // stricter than the native backends, so a pipeline that builds on desktop can be invalid in
        // the browser and silently render nothing; log it instead of leaving a black viewport.
        //
        // On wasm we CANNOT await this pop under wgpu 30.0.0: `GPUDevice.popErrorScope()` resolves
        // to `GPUError | null`, and on the (common) no-error path it returns JS `null`. wgpu's
        // `future_pop_error_scope` feeds that through `JsOption::into_option()`, which — since
        // wasm-bindgen 0.2.123 — treats `null` as a *present* value (only `undefined` is absent).
        // So a null (no error) becomes `Some(null)`, wgpu calls `Error::from_js(null)`, and
        // webgpu.rs:85 panics `"Unexpected error"`, aborting the module before the canvas ever
        // renders. Dropping the guard still pops the scope (discarding any captured error) but
        // never polls that buggy future, so it cannot panic. Tracked in
        // docs/WGPU_UPSTREAM_TRACKING.md for a proper soft-fork of `future_pop_error_scope`.
        #[cfg(not(target_arch = "wasm32"))]
        {
            let scope_err = error_scope.pop().await;
            if let Some(err) = scope_err {
                return Err(format!("renderer pipeline/shader creation failed: {err}"));
            }
        }
        #[cfg(target_arch = "wasm32")]
        drop(error_scope);

        Ok(Self {
            device,
            queue,
            surface,
            config,
            offscreen_texture,
            readback_buf,
            readback_bytes_per_row,
            color_format: format,
            depth_texture,
            depth_view,
            picking_texture,
            picking_view,
            picking_pipeline,
            pick_staging_buf,
            pending_pick: None,
            pick_copy_submitted: false,
            pick_result: None,
            ambient_pipeline,
            projector_pipeline,
            ambient_pipeline_hdr,
            projector_pipeline_hdr,
            mesh_pipeline,
            mesh_pipeline_hdr,
            mesh: None,
            model_buf,
            mesh_model_bind,
            artefact_joint: None,
            artefact_t0: None,
            mesh_base_aabb: None,
            artefact_world: None,
            last_admitted: Motor::identity(),
            last_refused: false,
            bloom,
            ambient_bind_group_layout,
            ambient_bind_group,
            projector_camera_layout,
            projector_tensor_layout,
            projector_camera_bind,
            projector_tensor_bind: None,
            uniform_buf,
            telemetry_buf,
            camera_buf,
            observer_buf,
            camera,
            observer,
            particle_buf,
            tensor_raw_buf: None,
            tensor_node_count: 0,
            particle_count: particle_count as u32,
            ambient_enabled: false,
            width,
            height,
        })
    }

    /// Enable/disable the ambient particle field draw. Off by default (a plain mesh/anatomy view has
    /// no use for the decorative random cloud); a Tensor10D upload turns it on since the particles then
    /// encode epistemic nodes. The mixer's "ambient" channel drives this.
    pub fn set_ambient_enabled(&mut self, on: bool) {
        self.ambient_enabled = on;
    }

    pub fn upload_tensor_buffer(&mut self, bytes: &[u8]) -> Result<u32, String> {
        let (header, _) =
            crate::tensor::buffer_export::parse_header(bytes).map_err(|e| e.to_string())?;
        let count = header.node_count;
        if count == 0 {
            return Ok(0);
        }

        let particles = particles_from_tensor(bytes, MAX_AMBIENT_INSTANCES)?;
        let instance_count = particles.len() as u32;

        let particle_buf = self
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("portal-tensor-particles"),
                contents: bytemuck::cast_slice(&particles),
                usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
            });

        // Upload the SOA *body* only (skip the 32-byte header). WebGPU requires storage-buffer
        // binding offsets to be a multiple of minStorageBufferOffsetAlignment (256), so we cannot
        // bind at offset 32 the way native backends allow — start the buffer at the first record
        // and bind at offset 0.
        let body = bytes
            .get(TENSOR_HEADER_BYTES..)
            .ok_or_else(|| "tensor buffer shorter than header".to_string())?;
        let tensor_raw_buf = self
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("portal-tensor-raw-soa"),
                contents: body,
                usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
            });

        self.ambient_bind_group = make_ambient_bind_group(
            &self.device,
            &self.ambient_bind_group_layout,
            &self.uniform_buf,
            &self.telemetry_buf,
            &self.camera_buf,
            &self.observer_buf,
            &particle_buf,
        );

        self.projector_camera_bind = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("portal-projector-camera-bind"),
            layout: &self.projector_camera_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: self.camera_buf.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: self.observer_buf.as_entire_binding(),
                },
            ],
        });

        self.projector_tensor_bind = Some(make_projector_tensor_bind_group(
            &self.device,
            &self.projector_tensor_layout,
            &tensor_raw_buf,
            count,
        )?);

        let particle_bytes = (particles.len() * std::mem::size_of::<ParticleInstance>()) as u64;
        global_vram_ledger().record_render(particle_bytes);
        global_vram_ledger().record_tensor(bytes.len() as u64);

        self.particle_buf = particle_buf;
        self.tensor_raw_buf = Some(tensor_raw_buf);
        self.tensor_node_count = count;
        self.particle_count = instance_count.max(1);
        // The particle field now carries real tensor nodes (not the decorative random cloud) — show it.
        self.ambient_enabled = true;

        Ok(count)
    }

    pub fn tensor_node_count(&self) -> u32 {
        self.tensor_node_count
    }

    /// Drive the loaded mesh by a kinematic joint (Phase 2). `None` freezes it at identity.
    pub fn set_artefact_joint(&mut self, joint: Option<Joint>) {
        self.artefact_joint = joint;
        self.artefact_t0 = None; // re-engage from rest: the slide/spin starts at elapsed t = 0
        self.last_admitted = Motor::identity();
        self.last_refused = false;
    }

    /// Constrain the artefact to a world bound; a joint pose that would leave it is refused
    /// (the artefact holds at the last admitted pose). `None` = unconstrained.
    pub fn set_artefact_world(&mut self, world: Option<Aabb>) {
        self.artefact_world = world;
    }

    /// Whether last frame's proposed joint pose was deterministically refused (clamped at the bound).
    pub fn artefact_refused(&self) -> bool {
        self.last_refused
    }

    /// Resolve this frame's per-artefact model transform: the joint pose at `time`, gated through
    /// the admission policy (refuse out-of-world → hold the last admitted pose), then write it.
    fn update_model(&mut self, time: f32) {
        let proposed = match self.artefact_joint {
            // Drive by *elapsed* time since the joint was engaged, not absolute sim-time, so a slide
            // always starts from rest when armed (the t0 is latched on this first post-arm frame).
            Some(j) => {
                let t0 = *self.artefact_t0.get_or_insert(time);
                j.motor_at(time - t0)
            }
            None => Motor::identity(),
        };
        let motor = match (self.mesh_base_aabb, self.artefact_world) {
            (Some(base), Some(world)) => {
                match Admission::new(0.0, Some(world)).admit(&base, proposed, [1.0, 1.0, 1.0]) {
                    Ok(_) => {
                        self.last_refused = false;
                        self.last_admitted = proposed;
                        proposed
                    }
                    Err(_) => {
                        self.last_refused = true;
                        self.last_admitted // deterministic refusal: hold at the boundary
                    }
                }
            }
            _ => {
                self.last_refused = false;
                proposed
            }
        };
        let model = motor_to_mat4_col(motor);
        self.queue
            .write_buffer(&self.model_buf, 0, bytemuck::cast_slice(&model));
    }

    pub fn has_tensor_buffer(&self) -> bool {
        self.tensor_raw_buf.is_some()
    }

    /// Upload an imported triangle mesh (Phase 1.2). `positions` are model-space `f32x3` (the caller
    /// centres + scales them to the orbit frame); `indices` is a flat triangle list (`tris * 3`).
    /// Returns the triangle count; clears any prior mesh when empty.
    pub fn upload_mesh(&mut self, positions: &[[f32; 3]], indices: &[u32]) -> u32 {
        self.upload_mesh_colored(positions, &[], indices)
    }

    /// Upload a triangle mesh with per-vertex linear RGBA colours. When `colors` is empty the
    /// engine's neutral blue-grey material is used; any non-empty slice must match `positions`.
    pub fn upload_mesh_colored(
        &mut self,
        positions: &[[f32; 3]],
        colors: &[[f32; 4]],
        indices: &[u32],
    ) -> u32 {
        if positions.is_empty() || indices.len() < 3 {
            self.mesh = None;
            return 0;
        }
        if !colors.is_empty() && colors.len() != positions.len() {
            self.mesh = None;
            return 0;
        }
        let default_colors;
        let colors = if colors.is_empty() {
            default_colors = vec![[0.50, 0.60, 0.82, 1.0]; positions.len()];
            default_colors.as_slice()
        } else {
            colors
        };
        let vertex_buf = self
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("portal-mesh-verts"),
                contents: bytemuck::cast_slice(positions),
                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
            });
        let color_buf = self
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("portal-mesh-colors"),
                contents: bytemuck::cast_slice(colors),
                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
            });
        let index_buf = self
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("portal-mesh-indices"),
                contents: bytemuck::cast_slice(indices),
                usage: wgpu::BufferUsages::INDEX | wgpu::BufferUsages::COPY_DST,
            });
        let index_count = indices.len() as u32;
        self.mesh = Some(MeshGpu {
            vertex_buf,
            color_buf,
            index_buf,
            index_count,
        });
        self.mesh_base_aabb = Aabb::from_points(positions); // for Phase 2 admission
        self.last_admitted = Motor::identity();
        self.last_refused = false;
        index_count / 3
    }

    /// Whether a mesh surface is resident.
    pub fn has_mesh(&self) -> bool {
        self.mesh.is_some()
    }

    pub fn set_camera(&mut self, yaw: f32, pitch: f32, zoom: f32) {
        self.camera = CameraState { yaw, pitch, zoom }.clamped();
    }

    pub fn set_standpoint(&mut self, observer: ObserverStandpoint) {
        self.observer = observer;
    }

    pub fn observer_standpoint(&self) -> ObserverStandpoint {
        self.observer
    }

    pub fn camera_state(&self) -> CameraState {
        self.camera
    }

    /// Configured surface/depth size. The swapchain texture follows the canvas backing store,
    /// so callers compare this to `canvas.width()/height()` and `resize()` on divergence —
    /// otherwise color and depth attachments mismatch and the render pass fails validation.
    pub fn surface_size(&self) -> (u32, u32) {
        (self.width, self.height)
    }

    pub fn resize(&mut self, width: u32, height: u32) {
        if width == 0 || height == 0 {
            return;
        }
        self.width = width;
        self.height = height;
        if let (Some(surface), Some(config)) = (self.surface.as_ref(), self.config.as_mut()) {
            config.width = width;
            config.height = height;
            surface.configure(&self.device, config);
        } else {
            self.offscreen_texture = Some(create_offscreen_texture(
                &self.device,
                self.color_format,
                width,
                height,
            ));
            self.readback_bytes_per_row = padded_bytes_per_row(width);
            self.readback_buf = Some(create_readback_buffer(
                &self.device,
                self.readback_bytes_per_row,
                height,
            ));
        }
        let (depth_texture, depth_view) = create_depth_texture(&self.device, width, height);
        let (picking_texture, picking_view) = create_picking_texture(&self.device, width, height);
        self.depth_texture = depth_texture;
        self.depth_view = depth_view;
        self.picking_texture = picking_texture;
        self.picking_view = picking_view;
        self.sync_bloom_targets();
    }

    /// Reconcile HDR bloom textures with current `VramLedger` operational mode.
    pub fn sync_bloom_targets(&mut self) {
        if portal_bloom_enabled() && probe_hdr_format(&self.device) {
            let bloom =
                create_bloom_chain(&self.device, self.width, self.height, self.color_format);
            if let Some(ref chain) = bloom {
                let (hw, hh) = chain.hdr_extent();
                let (bw, bh) = chain.blur_extent();
                debug_assert_eq!(hw, self.width);
                debug_assert_eq!(hh, self.height);
                debug_assert_eq!(bw, (self.width / 2).max(1));
                debug_assert_eq!(bh, (self.height / 2).max(1));
                let _ = chain.texture_handles();
            }
            let bloom_bytes = bloom.as_ref().map(|b| b.vram_bytes).unwrap_or(0);
            let particle_bytes =
                (self.particle_count as usize * std::mem::size_of::<ParticleInstance>()) as u64;
            global_vram_ledger().record_render(particle_bytes + bloom_bytes);
            self.bloom = bloom;
        } else {
            let particle_bytes =
                (self.particle_count as usize * std::mem::size_of::<ParticleInstance>()) as u64;
            global_vram_ledger().record_render(particle_bytes);
            self.bloom = None;
        }
    }

    fn write_camera_uniform(&self, time: f32) {
        let aspect = self.width as f32 / self.height.max(1) as f32;
        let mut uniform = self
            .camera
            .to_uniform(aspect, self.tensor_raw_buf.is_some());
        uniform._padding[0] = time;
        self.queue
            .write_buffer(&self.camera_buf, 0, bytemuck::bytes_of(&uniform));
    }

    fn write_observer_uniform(&self) {
        self.queue
            .write_buffer(&self.observer_buf, 0, bytemuck::bytes_of(&self.observer));
    }

    pub fn queue_pick(&mut self, x: f32, y: f32) {
        let px = x.round().max(0.0) as u32;
        let py = y.round().max(0.0) as u32;
        self.pending_pick = Some((
            px.min(self.width.saturating_sub(1)),
            py.min(self.height.saturating_sub(1)),
        ));
        self.pick_copy_submitted = false;
        self.pick_result = None;
    }

    pub fn poll_pick_readback(&mut self) -> Option<u32> {
        if let Some(idx) = self.pick_result.take() {
            return Some(idx);
        }
        if !self.pick_copy_submitted {
            return None;
        }
        let slice = self.pick_staging_buf.slice(..);
        let (tx, rx) = std::sync::mpsc::channel();
        slice.map_async(wgpu::MapMode::Read, move |result| {
            let _ = tx.send(result);
        });
        let _ = self.device.poll(wgpu::PollType::wait_indefinitely());
        if !matches!(rx.try_recv(), Ok(Ok(()))) {
            return None;
        }
        let mapped = slice
            .get_mapped_range()
            .expect("wgpu buffer map_range failed");
        let raw = if mapped.len() >= 4 {
            Some(u32::from_le_bytes(mapped[0..4].try_into().unwrap()))
        } else {
            None
        };
        drop(mapped);
        self.pick_staging_buf.unmap();
        self.pick_copy_submitted = false;
        raw.filter(|&id| id != PICK_SENTINEL)
    }

    fn record_picking_pass(&self, encoder: &mut wgpu::CommandEncoder) {
        let Some(tensor_bind) = self.projector_tensor_bind.as_ref() else {
            return;
        };
        let count = self.tensor_node_count;
        if count == 0 {
            return;
        }

        let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("portal-picking-pass"),
            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                view: &self.picking_view,
                depth_slice: None,
                resolve_target: None,
                ops: wgpu::Operations {
                    load: wgpu::LoadOp::Clear(wgpu::Color {
                        r: PICK_SENTINEL as f64,
                        g: 0.0,
                        b: 0.0,
                        a: 1.0,
                    }),
                    store: wgpu::StoreOp::Store,
                },
            })],
            depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                view: &self.depth_view,
                depth_ops: Some(wgpu::Operations {
                    load: wgpu::LoadOp::Clear(1.0),
                    store: wgpu::StoreOp::Store,
                }),
                stencil_ops: None,
            }),
            occlusion_query_set: None,
            multiview_mask: None,
            timestamp_writes: None,
        });
        pass.set_pipeline(&self.picking_pipeline);
        pass.set_bind_group(0, &self.projector_camera_bind, &[]);
        pass.set_bind_group(1, tensor_bind, &[]);
        pass.draw(0..6, 0..count);
    }

    fn record_pick_copy(&mut self, encoder: &mut wgpu::CommandEncoder) {
        let Some((px, py)) = self.pending_pick.take() else {
            return;
        };
        let py = self.height.saturating_sub(1) - py;
        encoder.copy_texture_to_buffer(
            wgpu::TexelCopyTextureInfo {
                texture: &self.picking_texture,
                mip_level: 0,
                origin: wgpu::Origin3d { x: px, y: py, z: 0 },
                aspect: wgpu::TextureAspect::All,
            },
            wgpu::TexelCopyBufferInfo {
                buffer: &self.pick_staging_buf,
                layout: wgpu::TexelCopyBufferLayout {
                    offset: 0,
                    bytes_per_row: Some(4),
                    rows_per_image: Some(1),
                },
            },
            wgpu::Extent3d {
                width: 1,
                height: 1,
                depth_or_array_layers: 1,
            },
        );
        self.pick_copy_submitted = true;
    }

    pub fn render(&mut self, time: f32, telemetry: &SystemTelemetry) -> Result<(), String> {
        let uniforms = AmbientUniforms {
            time,
            view_width: self.width as f32,
            view_height: self.height as f32,
            _padding: 0.0,
        };
        self.queue
            .write_buffer(&self.uniform_buf, 0, bytemuck::bytes_of(&uniforms));
        self.queue
            .write_buffer(&self.telemetry_buf, 0, bytemuck::bytes_of(telemetry));
        self.write_camera_uniform(time);
        self.write_observer_uniform();
        self.update_model(time);

        // A browser target acquires a swapchain frame; a native/headless target keeps a reusable
        // COPY_SRC texture. The draw graph below is identical for both.
        let surface_frame = if let Some(surface) = self.surface.as_ref() {
            match surface.get_current_texture() {
                wgpu::CurrentSurfaceTexture::Success(t)
                | wgpu::CurrentSurfaceTexture::Suboptimal(t) => Some(t),
                other => return Err(format!("surface frame unavailable: {other:?}")),
            }
        } else {
            None
        };

        // On the web backend the swapchain texture tracks the canvas backing store, which can
        // diverge from the size our depth/picking/bloom targets were built at (device-pixel ratio,
        // layout settle, a ResizeObserver resizing in CSS pixels without a matching `resize()`).
        // A depth attachment whose dimensions don't match the colour attachment fails render-pass
        // validation, the whole frame is dropped, and the viewport stays black. Reconcile every
        // attachment to the *actual* acquired texture before recording any pass.
        if let Some(frame) = surface_frame.as_ref() {
            let fw = frame.texture.width();
            let fh = frame.texture.height();
            if fw > 0 && fh > 0 && (fw, fh) != (self.width, self.height) {
                self.width = fw;
                self.height = fh;
                if let Some(config) = self.config.as_mut() {
                    config.width = fw;
                    config.height = fh;
                }
                let (depth_texture, depth_view) = create_depth_texture(&self.device, fw, fh);
                let (picking_texture, picking_view) = create_picking_texture(&self.device, fw, fh);
                self.depth_texture = depth_texture;
                self.depth_view = depth_view;
                self.picking_texture = picking_texture;
                self.picking_view = picking_view;
                self.sync_bloom_targets();
                self.write_camera_uniform(time);
            }
        }

        let view = if let Some(frame) = surface_frame.as_ref() {
            frame
                .texture
                .create_view(&wgpu::TextureViewDescriptor::default())
        } else {
            self.offscreen_texture
                .as_ref()
                .ok_or_else(|| "renderer has no output target".to_string())?
                .create_view(&wgpu::TextureViewDescriptor::default())
        };

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

        self.record_picking_pass(&mut encoder);

        let use_bloom = self.bloom.is_some()
            && self.ambient_pipeline_hdr.is_some()
            && self.projector_pipeline_hdr.is_some()
            && portal_bloom_enabled();

        if use_bloom {
            let bloom = self.bloom.as_ref().expect("bloom chain");
            let ambient_hdr = self.ambient_pipeline_hdr.as_ref().expect("ambient hdr");
            let projector_hdr = self.projector_pipeline_hdr.as_ref().expect("projector hdr");
            let mesh_hdr = self.mesh_pipeline_hdr.as_ref();

            {
                let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                    label: Some("portal-hdr-scene"),
                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                        view: &bloom.hdr_view,
                        depth_slice: None,
                        resolve_target: None,
                        ops: wgpu::Operations {
                            load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
                            store: wgpu::StoreOp::Store,
                        },
                    })],
                    depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                        view: &self.depth_view,
                        depth_ops: Some(wgpu::Operations {
                            load: wgpu::LoadOp::Clear(1.0),
                            store: wgpu::StoreOp::Store,
                        }),
                        stencil_ops: None,
                    }),
                    occlusion_query_set: None,
                    multiview_mask: None,
                    timestamp_writes: None,
                });

                if let (Some(mesh), Some(mesh_pipe)) = (self.mesh.as_ref(), mesh_hdr) {
                    pass.set_pipeline(mesh_pipe);
                    pass.set_bind_group(0, &self.projector_camera_bind, &[]);
                    pass.set_bind_group(1, &self.mesh_model_bind, &[]);
                    pass.set_vertex_buffer(0, mesh.vertex_buf.slice(..));
                    pass.set_vertex_buffer(1, mesh.color_buf.slice(..));
                    pass.set_index_buffer(mesh.index_buf.slice(..), wgpu::IndexFormat::Uint32);
                    pass.draw_indexed(0..mesh.index_count, 0, 0..1);
                }

                if let (Some(tensor_bind), count) =
                    (self.projector_tensor_bind.as_ref(), self.tensor_node_count)
                {
                    if count > 0 {
                        pass.set_pipeline(projector_hdr);
                        pass.set_bind_group(0, &self.projector_camera_bind, &[]);
                        pass.set_bind_group(1, tensor_bind, &[]);
                        pass.draw(0..6, 0..count);
                    }
                }

                pass.set_pipeline(ambient_hdr);
                pass.set_bind_group(0, &self.ambient_bind_group, &[]);
                let ambient_draw = ambient_draw_instances(self.particle_count);
                if self.ambient_enabled && ambient_draw > 0 {
                    pass.draw(0..6, 0..ambient_draw);
                }
            }

            run_bloom_passes(&mut encoder, bloom, &self.queue, &self.device, &view);
        } else {
            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("portal-phenomenal-pass"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: &view,
                    depth_slice: None,
                    resolve_target: None,
                    ops: wgpu::Operations {
                        load: wgpu::LoadOp::Clear(wgpu::Color {
                            r: 0.03,
                            g: 0.05,
                            b: 0.08,
                            a: 1.0,
                        }),
                        store: wgpu::StoreOp::Store,
                    },
                })],
                depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                    view: &self.depth_view,
                    depth_ops: Some(wgpu::Operations {
                        load: wgpu::LoadOp::Clear(1.0),
                        store: wgpu::StoreOp::Store,
                    }),
                    stencil_ops: None,
                }),
                occlusion_query_set: None,
                multiview_mask: None,
                timestamp_writes: None,
            });

            if let Some(mesh) = self.mesh.as_ref() {
                pass.set_pipeline(&self.mesh_pipeline);
                pass.set_bind_group(0, &self.projector_camera_bind, &[]);
                pass.set_bind_group(1, &self.mesh_model_bind, &[]);
                pass.set_vertex_buffer(0, mesh.vertex_buf.slice(..));
                pass.set_vertex_buffer(1, mesh.color_buf.slice(..));
                pass.set_index_buffer(mesh.index_buf.slice(..), wgpu::IndexFormat::Uint32);
                pass.draw_indexed(0..mesh.index_count, 0, 0..1);
            }

            if let (Some(tensor_bind), count) =
                (self.projector_tensor_bind.as_ref(), self.tensor_node_count)
            {
                if count > 0 {
                    pass.set_pipeline(&self.projector_pipeline);
                    pass.set_bind_group(0, &self.projector_camera_bind, &[]);
                    pass.set_bind_group(1, tensor_bind, &[]);
                    pass.draw(0..6, 0..count);
                }
            }

            pass.set_pipeline(&self.ambient_pipeline);
            pass.set_bind_group(0, &self.ambient_bind_group, &[]);
            let ambient_draw = ambient_draw_instances(self.particle_count);
            if self.ambient_enabled && ambient_draw > 0 {
                pass.draw(0..6, 0..ambient_draw);
            }
        }

        self.record_pick_copy(&mut encoder);
        self.queue.submit(std::iter::once(encoder.finish()));
        if let Some(frame) = surface_frame {
            // wgpu 30: SurfaceTexture::present() removed → Queue::present(frame).
            self.queue.present(frame);
        }
        Ok(())
    }

    /// Number of bytes required by [`Self::read_rgba8_into`].
    pub fn required_rgba8_bytes(&self) -> usize {
        self.width as usize * self.height as usize * 4
    }

    /// Read the most recently rendered native offscreen frame into tightly packed RGBA8 bytes.
    ///
    /// This is deliberately caller-buffered: no `Vec` is created in the renderer. Browser surface
    /// instances return an error because their swapchain images are presented, not retained.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn read_rgba8_into(&self, out: &mut [u8]) -> Result<usize, String> {
        let need = self.required_rgba8_bytes();
        if out.len() < need {
            return Err(format!(
                "RGBA8 output buffer too small: need {need}, got {}",
                out.len()
            ));
        }
        let texture = self
            .offscreen_texture
            .as_ref()
            .ok_or_else(|| "RGBA8 readback requires an offscreen renderer".to_string())?;
        let staging = self
            .readback_buf
            .as_ref()
            .ok_or_else(|| "offscreen readback buffer is unavailable".to_string())?;

        let mut encoder = self
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("qualia-render-readback-encoder"),
            });
        encoder.copy_texture_to_buffer(
            wgpu::TexelCopyTextureInfo {
                texture,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            wgpu::TexelCopyBufferInfo {
                buffer: staging,
                layout: wgpu::TexelCopyBufferLayout {
                    offset: 0,
                    bytes_per_row: Some(self.readback_bytes_per_row),
                    rows_per_image: Some(self.height),
                },
            },
            wgpu::Extent3d {
                width: self.width,
                height: self.height,
                depth_or_array_layers: 1,
            },
        );
        self.queue.submit(std::iter::once(encoder.finish()));

        let slice = staging.slice(..);
        let (tx, rx) = std::sync::mpsc::channel();
        slice.map_async(wgpu::MapMode::Read, move |result| {
            let _ = tx.send(result);
        });
        let _ = self.device.poll(wgpu::PollType::wait_indefinitely());
        rx.recv()
            .map_err(|e| format!("RGBA8 readback callback failed: {e}"))?
            .map_err(|e| format!("RGBA8 buffer map failed: {e}"))?;

        let mapped = slice
            .get_mapped_range()
            .expect("wgpu buffer map_range failed");
        let tight_row = self.width as usize * 4;
        let padded_row = self.readback_bytes_per_row as usize;
        for row in 0..self.height as usize {
            let src = &mapped[row * padded_row..row * padded_row + tight_row];
            let dst = &mut out[row * tight_row..(row + 1) * tight_row];
            dst.copy_from_slice(src);
        }
        drop(mapped);
        staging.unmap();
        Ok(need)
    }

    pub fn particle_count(&self) -> u32 {
        self.particle_count
    }
}

// Phase 0.2a: render/gpu submodules (bloom post-pass, resource builders, particle field).
mod bloom;
mod particles;
mod resources;
use bloom::*;
pub use particles::particle_cap_for_mode;
use particles::*;
use resources::*;

#[cfg(all(test, not(target_arch = "wasm32")))]
mod tests {
    use super::*;
    use crate::tensor::buffer_export::{write_tensor_buffer, TensorBufferHeader};
    use crate::tensor::Tensor10D;

    #[test]
    fn offscreen_size_contract_is_caller_buffered() {
        assert_eq!(padded_bytes_per_row(1), wgpu::COPY_BYTES_PER_ROW_ALIGNMENT);
        assert_eq!(padded_bytes_per_row(64), 256);
        assert_eq!(padded_bytes_per_row(65), 512);
    }

    #[test]
    #[serial_test::serial(gpu)]
    fn native_offscreen_renders_tensor_and_mesh_on_shared_gpu() {
        if !crate::wgsl_forge::test_gpu_available() {
            return;
        }
        let mut renderer =
            PortalGpu::new_offscreen(96, 96, 256).expect("native offscreen renderer");

        let tensors = [
            Tensor10D::ground_truth(0.0, 0.0, -0.35, 0.0, 0.0, 0.0, 1.0, 0.0, 0.2),
            Tensor10D::ground_truth(0.0, 0.0, 0.35, 0.0, 0.1, 0.0, 1.0, 0.0, 0.8),
        ];
        let mut tensor_bytes = vec![0u8; TensorBufferHeader::total_bytes(tensors.len())];
        write_tensor_buffer(&tensors, &mut tensor_bytes).expect("tensor export");
        assert_eq!(
            renderer
                .upload_tensor_buffer(&tensor_bytes)
                .expect("tensor upload"),
            2
        );
        assert_eq!(
            renderer.upload_mesh(
                &[[-0.6, -0.5, 0.2], [0.6, -0.5, 0.2], [0.0, 0.6, 0.2]],
                &[0, 1, 2],
            ),
            1
        );

        renderer
            .render(0.25, &SystemTelemetry::default())
            .expect("offscreen draw");
        let mut rgba = vec![0u8; renderer.required_rgba8_bytes()];
        assert_eq!(
            renderer
                .read_rgba8_into(&mut rgba)
                .expect("offscreen readback"),
            rgba.len()
        );
        assert!(
            rgba.chunks_exact(4)
                .any(|px| px != [8, 13, 20, 255] && px[3] != 0),
            "expected projected tensor, mesh, or ambient pixels over the clear colour"
        );
    }
}