@bornengine/engine 0.4.16

package/native/shared/src/renderer/hiz.rs

@@ -0,0 +1,269 @@
+//! Hi-Z (hierarchical linear-depth) pyramid build: a linearize pass
+//! into mip 0 followed by min-downsample passes. Consumed by SSAO/SSR
+//! ray-march acceleration and (via the max-reduce in occlusion.rs) the
+//! occlusion-culling grid. Split out of renderer/mod.rs (2000-line file
+//! policy); pipelines and the mip chain stay fields on [`Renderer`].
+
+use super::formats::HIZ_MIP_COUNT;
+use super::formats::halton;
+use super::{HizDownsampleParams, HizLinearizeParams, SsaoBlurParams, SsaoParams};
+use super::Renderer;
+
+impl Renderer {
+    pub(super) fn record_hiz_chain(
+        &mut self,
+        encoder: &mut wgpu::CommandEncoder,
+        profiler: &mut crate::profiler::Profiler,
+        half_w: u32,
+        half_h: u32,
+        p22: f32,
+        p32: f32,
+    ) {
+        // --- Hi-Z build: linearize depth into mip 0 -----------------
+        let lin_params = HizLinearizeParams {
+            params: [1.0 / half_w as f32, 1.0 / half_h as f32, p22, p32],
+            size: [half_w, half_h, 0, 0],
+        };
+        self.queue.write_buffer(&self.hiz_linearize_uniform_buffer, 0, bytemuck::bytes_of(&lin_params));
+        if self.hiz_linearize_bg_cache.is_none() {
+            self.hiz_linearize_bg_cache = Some(self.device.create_bind_group(&wgpu::BindGroupDescriptor {
+                label: Some("hiz_linearize_bg"),
+                layout: &self.hiz_linearize_layout,
+                entries: &[
+                    wgpu::BindGroupEntry { binding: 0, resource: self.hiz_linearize_uniform_buffer.as_entire_binding() },
+                    wgpu::BindGroupEntry { binding: 1, resource: wgpu::BindingResource::TextureView(&self.depth_view) },
+                    wgpu::BindGroupEntry { binding: 2, resource: wgpu::BindingResource::Sampler(&self.ssao_depth_sampler) },
+                    wgpu::BindGroupEntry { binding: 3, resource: wgpu::BindingResource::TextureView(&self.hiz_views[0]) },
+                ],
+            }));
+        }
+        {
+            let bg = self.hiz_linearize_bg_cache.as_ref().unwrap();
+            let ts = profiler.compute_pass_timestamp_writes("hiz_linearize_pass");
+            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
+                label: Some("hiz_linearize_pass"),
+                timestamp_writes: ts,
+            });
+            pass.set_pipeline(&self.hiz_linearize_pipeline);
+            pass.set_bind_group(0, bg, &[]);
+            pass.dispatch_workgroups((half_w + 7) / 8, (half_h + 7) / 8, 1);
+        }
+
+        // --- Hi-Z build: downsample mip i -> mip i+1 ----------------
+        for i in 0..(HIZ_MIP_COUNT - 1) as usize {
+            let dst_w = (half_w >> (i + 1)).max(1);
+            let dst_h = (half_h >> (i + 1)).max(1);
+            let ds_params = HizDownsampleParams {
+                size: [dst_w, dst_h, 0, 0],
+            };
+            self.queue.write_buffer(&self.hiz_downsample_uniform_buffers[i], 0, bytemuck::bytes_of(&ds_params));
+            if self.hiz_downsample_bg_cache[i].is_none() {
+                self.hiz_downsample_bg_cache[i] = Some(self.device.create_bind_group(&wgpu::BindGroupDescriptor {
+                    label: Some("hiz_downsample_bg"),
+                    layout: &self.hiz_downsample_layout,
+                    entries: &[
+                        wgpu::BindGroupEntry { binding: 0, resource: self.hiz_downsample_uniform_buffers[i].as_entire_binding() },
+                        wgpu::BindGroupEntry { binding: 1, resource: wgpu::BindingResource::TextureView(&self.hiz_views[i]) },
+                        wgpu::BindGroupEntry { binding: 2, resource: wgpu::BindingResource::TextureView(&self.hiz_views[i + 1]) },
+                    ],
+                }));
+            }
+            let bg = self.hiz_downsample_bg_cache[i].as_ref().unwrap();
+            let ts_label: &'static str = match i {
+                0 => "hiz_downsample_pass_1",
+                1 => "hiz_downsample_pass_2",
+                2 => "hiz_downsample_pass_3",
+                _ => "hiz_downsample_pass_4",
+            };
+            let ts = profiler.compute_pass_timestamp_writes(ts_label);
+            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
+                label: Some(ts_label),
+                timestamp_writes: ts,
+            });
+            pass.set_pipeline(&self.hiz_downsample_pipeline);
+            pass.set_bind_group(0, bg, &[]);
+            pass.dispatch_workgroups((dst_w + 7) / 8, (dst_h + 7) / 8, 1);
+        }
+
+    }
+}
+
+impl Renderer {
+    /// SSAO bilateral blur (depth-guided, edge-preserving) when SSAO is
+    /// on, or a white-clear of the blur RT when it's off so the
+    /// composite samples "no occlusion". Split from
+    /// end_frame_with_scene (2000-line file policy).
+    pub(super) fn record_ssao_blur(
+        &mut self,
+        encoder: &mut wgpu::CommandEncoder,
+        surf_w: u32,
+        surf_h: u32,
+    ) {
+    // ============================================================
+    // SSAO bilateral blur: smooth the noisy GTAO output while
+    // preserving depth edges (depth-guided bilateral filter).
+    // Reads ssao_rt → writes ssao_blur_rt.
+    // ============================================================
+    // PT: when the path tracer owns the frame it computes real
+    // occlusion by tracing — screen-space AO on top double-darkens
+    // every crevice. Route compose to "no occlusion" (white clear
+    // below) for those frames.
+    if self.ssao_enabled && !self.pt_owns_frame() {
+        // texel_size is the size of one SSAO RT texel (half-res).
+        let ao_w = (surf_w / 2).max(1) as f32;
+        let ao_h = (surf_h / 2).max(1) as f32;
+        let bp = SsaoBlurParams {
+            params: [1.0 / ao_w, 1.0 / ao_h, 0.05, 0.0],
+        };
+        self.queue.write_buffer(&self.ssao_blur_uniform_buffer, 0, bytemuck::bytes_of(&bp));
+
+        if self.ssao_blur_bg_cache.is_none() {
+            self.ssao_blur_bg_cache = Some(self.device.create_bind_group(&wgpu::BindGroupDescriptor {
+                label: Some("ssao_blur_bg"),
+                layout: &self.ssao_blur_layout,
+                entries: &[
+                    wgpu::BindGroupEntry { binding: 0, resource: self.ssao_blur_uniform_buffer.as_entire_binding() },
+                    wgpu::BindGroupEntry { binding: 1, resource: wgpu::BindingResource::TextureView(&self.ssao_rt_view) },
+                    wgpu::BindGroupEntry { binding: 2, resource: wgpu::BindingResource::Sampler(&self.composite_sampler) },
+                    wgpu::BindGroupEntry { binding: 3, resource: wgpu::BindingResource::TextureView(&self.depth_view) },
+                    wgpu::BindGroupEntry { binding: 4, resource: wgpu::BindingResource::Sampler(&self.ssao_depth_sampler) },
+                ],
+            }));
+        }
+        let bg = self.ssao_blur_bg_cache.as_ref().unwrap();
+
+        let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+            label: Some("ssao_blur_pass"),
+            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
+                view: &self.ssao_blur_rt_view,
+                resolve_target: None,
+                depth_slice: None,
+                ops: wgpu::Operations {
+                    load: wgpu::LoadOp::Clear(wgpu::Color::WHITE),
+                    store: wgpu::StoreOp::Store,
+                },
+            })],
+            depth_stencil_attachment: None,
+            timestamp_writes: None,
+            occlusion_query_set: None,
+            multiview_mask: None,
+        });
+        pass.set_pipeline(&self.ssao_blur_pipeline);
+        pass.set_bind_group(0, bg, &[]);
+        pass.draw(0..3, 0..1);
+    } else {
+        // SSAO disabled — clear the blur RT to WHITE so the
+        // composite pass samples "no occlusion". Cheaper than a
+        // full blur pass; the clear is the only GPU work.
+        encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
+            label: Some("ssao_blur_disabled_clear"),
+            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
+                view: &self.ssao_blur_rt_view,
+                resolve_target: None,
+                depth_slice: None,
+                ops: wgpu::Operations {
+                    load: wgpu::LoadOp::Clear(wgpu::Color::WHITE),
+                    store: wgpu::StoreOp::Store,
+                },
+            })],
+            depth_stencil_attachment: None,
+            timestamp_writes: None,
+            occlusion_query_set: None,
+            multiview_mask: None,
+        });
+    }
+    }
+}
+
+impl Renderer {
+    /// GTAO compute dispatch (half-res, Hi-Z-accelerated, temporal EMA
+    /// ping-pong). Caller guards on `ssao_enabled` and passes the
+    /// projection terms. Split from end_frame_with_scene.
+    #[allow(clippy::too_many_arguments)]
+    pub(super) fn record_gtao(
+        &mut self,
+        encoder: &mut wgpu::CommandEncoder,
+        profiler: &mut crate::profiler::Profiler,
+        half_w: u32,
+        half_h: u32,
+        p00: f32,
+        p11: f32,
+        p20: f32,
+        p21: f32,
+    ) {
+        let p22 = self.current_proj_matrix[2][2];
+        let p32 = self.current_proj_matrix[3][2];
+        // --- SSAO (compute GTAO, samples Hi-Z pyramid) --------------
+        let ld = self.lighting_uniforms.light_dir;
+        let v = &self.current_view_matrix;
+        let light_dir_vs = [
+            v[0][0]*ld[0] + v[1][0]*ld[1] + v[2][0]*ld[2],
+            v[0][1]*ld[0] + v[1][1]*ld[1] + v[2][1]*ld[2],
+            v[0][2]*ld[0] + v[1][2]*ld[1] + v[2][2]*ld[2],
+            0.0,
+        ];
+        // Temporal accumulation: ping-pong history textures.
+        // `write_idx` is the current-frame output; `read_idx` the
+        // previous frame's result. First 4 frames force alpha=1
+        // so the initial clear never contaminates the signal.
+        let write_idx = self.ssao_history_idx;
+        let read_idx = 1 - write_idx;
+        let frame_phase = self.ssao_history_frame % 4;
+        let force_refresh = if self.ssao_history_frame < 4 { 1u32 } else { 0u32 };
+        // 4-frame EMA: alpha = 1/4 = 0.25 gives equal weight to
+        // each of the 4 phases at steady state.
+        let alpha = 0.25_f32;
+        // Halton-5 rotation: uncorrelated with TAA's base-2/3 jitter
+        // so the two noise patterns don't resonate.
+        let halton5 = halton(self.ssao_history_frame + 1, 5);
+        let sp = SsaoParams {
+            params: [
+                1.0 / half_w as f32,
+                1.0 / half_h as f32,
+                self.ssao_radius,
+                self.ssao_strength,
+            ],
+            proj_row01: [p00, p11, p20, p21],
+            proj_z: [p22, p32, 1.0 / p00, 1.0 / p11],
+            light_dir_vs,
+            size: [half_w, half_h, frame_phase, force_refresh],
+            temporal: [alpha, halton5, 0.0, 0.0],
+        };
+        self.queue.write_buffer(&self.ssao_uniform_buffer, 0, bytemuck::bytes_of(&sp));
+
+        if self.ssao_bg_cache[write_idx].is_none() {
+            self.ssao_bg_cache[write_idx] = Some(self.device.create_bind_group(&wgpu::BindGroupDescriptor {
+                label: Some("ssao_bg"),
+                layout: &self.ssao_layout,
+                entries: &[
+                    wgpu::BindGroupEntry { binding: 0, resource: self.ssao_uniform_buffer.as_entire_binding() },
+                    wgpu::BindGroupEntry { binding: 1, resource: wgpu::BindingResource::TextureView(&self.ssao_rt_view) },
+                    wgpu::BindGroupEntry { binding: 2, resource: wgpu::BindingResource::Sampler(&self.hiz_sampler) },
+                    wgpu::BindGroupEntry { binding: 3, resource: wgpu::BindingResource::TextureView(&self.hiz_views[0]) },
+                    wgpu::BindGroupEntry { binding: 4, resource: wgpu::BindingResource::TextureView(&self.hiz_views[1]) },
+                    wgpu::BindGroupEntry { binding: 5, resource: wgpu::BindingResource::TextureView(&self.hiz_views[2]) },
+                    wgpu::BindGroupEntry { binding: 6, resource: wgpu::BindingResource::TextureView(&self.hiz_views[3]) },
+                    wgpu::BindGroupEntry { binding: 7, resource: wgpu::BindingResource::TextureView(&self.hiz_views[4]) },
+                    wgpu::BindGroupEntry { binding: 8, resource: wgpu::BindingResource::TextureView(&self.velocity_rt_view) },
+                    wgpu::BindGroupEntry { binding: 9, resource: wgpu::BindingResource::TextureView(&self.ssao_history_views[read_idx]) },
+                    wgpu::BindGroupEntry { binding: 10, resource: wgpu::BindingResource::Sampler(&self.composite_sampler) },
+                    wgpu::BindGroupEntry { binding: 11, resource: wgpu::BindingResource::TextureView(&self.ssao_history_views[write_idx]) },
+                ],
+            }));
+        }
+        let bg = self.ssao_bg_cache[write_idx].as_ref().unwrap();
+
+        let ssao_ts = profiler.compute_pass_timestamp_writes("ssao_pass");
+        let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
+            label: Some("ssao_pass"),
+            timestamp_writes: ssao_ts,
+        });
+        pass.set_pipeline(&self.ssao_pipeline);
+        pass.set_bind_group(0, bg, &[]);
+        pass.dispatch_workgroups((half_w + 7) / 8, (half_h + 7) / 8, 1);
+
+        // Flip ping-pong indices for the next frame.
+        self.ssao_history_idx = read_idx;
+        self.ssao_history_frame = self.ssao_history_frame.wrapping_add(1);
+    }
+}

package/native/shared/src/renderer/hot_reload.rs

@@ -0,0 +1,390 @@
+//! Phase 6 — material WGSL hot reload.
+//!
+//! When a game compiles a material via `compile_material_from_file`,
+//! the source path is registered here, the parent directory is added
+//! to a `notify` recursive watcher, and a worker thread funnels
+//! file-changed events into a `mpsc::Receiver` that the main thread
+//! drains once per frame from `Renderer::end_frame_with_scene`.
+//!
+//! Recompilation happens on the main thread (wgpu's `Device` is
+//! `!Send` for our purposes here): each pending event re-reads the
+//! file from disk, runs the same `compile_material` it originally
+//! used, and replaces the entry in `MaterialSystem::pipelines` at the
+//! same handle index. Existing draws keep working — they look up by
+//! handle, never by `&MaterialPipeline`.
+//!
+//! Failures (parse errors, validation) are logged but don't kill the
+//! game — the previous pipeline stays bound until the file is edited
+//! again to something valid.
+
+use std::collections::{HashMap, HashSet};
+use std::path::PathBuf;
+use std::sync::mpsc::{channel, Receiver, Sender};
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+
+use super::material_pipeline::{Bucket, FragmentProfile};
+
+/// What we remember about each file-backed material so we can
+/// rebuild it when the file changes.
+#[derive(Clone)]
+pub struct FileMaterialDesc {
+    pub path:             PathBuf,
+    pub profile:          FragmentProfile,
+    pub bucket:           Bucket,
+    pub reads_scene:      bool,
+    /// EN-001 — preserved across reloads so a file-backed instanced
+    /// material continues to opt into the per-instance vertex layout
+    /// after hot reload.
+    pub wants_instancing: bool,
+}
+
+pub struct MaterialHotReload {
+    /// Path → handle (1-based). Multiple handles per path possible if
+    /// the same file is compiled into multiple buckets — rare, but
+    /// supported via `Vec<u32>`.
+    by_path: HashMap<PathBuf, Vec<u32>>,
+    /// Handle (1-based, used as Vec<Option<…>> idx via -1) → desc.
+    /// Indexed parallel to `MaterialSystem::pipelines`.
+    descriptors: HashMap<u32, FileMaterialDesc>,
+    /// Cross-thread channel from the watcher's worker into the main
+    /// thread's per-frame poll. Use Mutex<Receiver> because the
+    /// renderer is held behind `&mut self` from many places.
+    rx: Mutex<Receiver<PathBuf>>,
+    _tx: Sender<PathBuf>,
+    /// Holding the watcher in the struct keeps the worker alive.
+    /// `Option` because creation is fallible and we want a clean
+    /// fallback (no hot reload) if `notify` errors at startup.
+    #[cfg(all(not(target_arch = "wasm32"), feature = "hot-reload"))]
+    _watcher: Option<notify::RecommendedWatcher>,
+    /// Last-seen change time per path — `notify` fires multiple
+    /// events for one save (truncate + write + close on macOS).
+    /// Coalesce within `DEBOUNCE_WINDOW`.
+    last_event: Mutex<HashMap<PathBuf, Instant>>,
+    /// Directories already passed to `watcher.watch` — repeatedly
+    /// adding the same dir is fine but creates duplicate events.
+    #[cfg(all(not(target_arch = "wasm32"), feature = "hot-reload"))]
+    watched_dirs: Mutex<Vec<PathBuf>>,
+}
+
+const DEBOUNCE_WINDOW: Duration = Duration::from_millis(120);
+
+impl MaterialHotReload {
+    pub fn new() -> Self {
+        let (tx, rx) = channel::<PathBuf>();
+
+        // Watcher is on by default — even in release builds, since
+        // our daily dev cycle uses --release for perf. Shipped game
+        // binaries can opt out two ways:
+        //   - runtime: set `BLOOM_NO_HOT_RELOAD=1`, short-circuits the
+        //     watcher thread (compile_material_from_file still works,
+        //     drain_pending just always returns empty)
+        //   - compile-time: build with `--no-default-features` (or
+        //     without the `hot-reload` feature), which drops `notify`
+        //     from the dep tree entirely (EN-008)
+        #[cfg(all(not(target_arch = "wasm32"), feature = "hot-reload"))]
+        let watcher = if std::env::var("BLOOM_NO_HOT_RELOAD").map(|v| v == "1").unwrap_or(false) {
+            None
+        } else {
+            use notify::{Event, EventKind};
+            let tx_clone = tx.clone();
+            let cb = move |res: Result<Event, notify::Error>| {
+                if let Ok(ev) = res {
+                    if matches!(ev.kind, EventKind::Modify(_) | EventKind::Create(_)) {
+                        for p in ev.paths {
+                            let _ = tx_clone.send(p);
+                        }
+                    }
+                }
+            };
+            match notify::recommended_watcher(cb) {
+                Ok(w) => Some(w),
+                Err(e) => {
+                    eprintln!("[hot_reload] failed to start file watcher: {e:?}");
+                    None
+                }
+            }
+        };
+
+        Self {
+            by_path: HashMap::new(),
+            descriptors: HashMap::new(),
+            rx: Mutex::new(rx),
+            _tx: tx,
+            #[cfg(all(not(target_arch = "wasm32"), feature = "hot-reload"))]
+            _watcher: watcher,
+            last_event: Mutex::new(HashMap::new()),
+            #[cfg(all(not(target_arch = "wasm32"), feature = "hot-reload"))]
+            watched_dirs: Mutex::new(Vec::new()),
+        }
+    }
+
+    /// Called by the FFI `compile_material_from_file` after a successful
+    /// initial compile. Records the path → handle mapping and starts
+    /// watching the file's parent directory.
+    pub fn register(&mut self, handle: u32, desc: FileMaterialDesc) {
+        let path = desc.path.clone();
+        self.by_path.entry(path.clone()).or_default().push(handle);
+        self.descriptors.insert(handle, desc);
+        self.ensure_dir_watched(&path);
+    }
+
+    /// Drain pending file-change events. Returns the unique set of
+    /// (handle, descriptor) pairs that need recompilation this frame.
+    /// `notify` fires multiple events per save; we coalesce within a
+    /// 120 ms window.
+    pub fn drain_pending(&self) -> Vec<(u32, FileMaterialDesc)> {
+        let mut paths: Vec<PathBuf> = Vec::new();
+        if let Ok(rx) = self.rx.lock() {
+            while let Ok(p) = rx.try_recv() {
+                paths.push(p);
+            }
+        }
+        if paths.is_empty() { return Vec::new(); }
+
+        let now = Instant::now();
+        let mut last = self.last_event.lock().expect("hot_reload poisoned");
+        let mut out: Vec<(u32, FileMaterialDesc)> = Vec::new();
+        let mut seen: HashSet<u32> = HashSet::new();
+        for raw in paths {
+            // Resolve canonically so the keys we matched on register
+            // line up with the events. notify on macOS sometimes
+            // returns the realpath, sometimes the symlink path.
+            let p = std::fs::canonicalize(&raw).unwrap_or(raw);
+            if let Some(t) = last.get(&p) {
+                if now.duration_since(*t) < DEBOUNCE_WINDOW { continue; }
+            }
+            last.insert(p.clone(), now);
+            if let Some(handles) = self.by_path.get(&p) {
+                for h in handles {
+                    if seen.insert(*h) {
+                        if let Some(d) = self.descriptors.get(h) {
+                            out.push((*h, d.clone()));
+                        }
+                    }
+                }
+            }
+        }
+        out
+    }
+
+    /// Test-only: push a path through the channel as if `notify` had
+    /// fired a Modify event. Lets unit tests exercise the drain +
+    /// debounce logic without a real file system.
+    #[cfg(test)]
+    pub fn test_inject_event(&self, path: PathBuf) {
+        let _ = self._tx.send(path);
+    }
+
+    fn ensure_dir_watched(&mut self, path: &std::path::Path) {
+        #[cfg(all(not(target_arch = "wasm32"), feature = "hot-reload"))]
+        {
+            use notify::{RecursiveMode, Watcher};
+            let dir = match path.parent() {
+                Some(d) => match std::fs::canonicalize(d) {
+                    Ok(c) => c,
+                    Err(_) => return,
+                },
+                None => return,
+            };
+            let mut watched = self.watched_dirs.lock().expect("hot_reload poisoned");
+            if watched.contains(&dir) { return; }
+            if let Some(w) = self._watcher.as_mut() {
+                if let Err(e) = w.watch(&dir, RecursiveMode::NonRecursive) {
+                    eprintln!("[hot_reload] failed to watch {dir:?}: {e:?}");
+                    return;
+                }
+                watched.push(dir);
+            }
+        }
+        #[cfg(any(target_arch = "wasm32", not(feature = "hot-reload")))]
+        {
+            let _ = path;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::renderer::material_pipeline::{Bucket, FragmentProfile};
+
+    fn desc(path: &str) -> FileMaterialDesc {
+        FileMaterialDesc {
+            path:             PathBuf::from(path),
+            profile:          FragmentProfile::Translucent,
+            bucket:           Bucket::Refractive,
+            reads_scene:      true,
+            wants_instancing: false,
+        }
+    }
+
+    #[test]
+    fn drain_returns_registered_handle_for_event_path() {
+        let mut hr = MaterialHotReload::new();
+        let p = PathBuf::from("/tmp/bloom_test_water.wgsl");
+        hr.register(7, FileMaterialDesc {
+            path:             p.clone(),
+            profile:          FragmentProfile::Translucent,
+            bucket:           Bucket::Refractive,
+            reads_scene:      true,
+            wants_instancing: false,
+        });
+        // canonicalize() in drain_pending falls back to the raw path
+        // when the file doesn't exist, so this resolves to itself.
+        hr.test_inject_event(p.clone());
+        let pending = hr.drain_pending();
+        assert_eq!(pending.len(), 1);
+        assert_eq!(pending[0].0, 7);
+        assert_eq!(pending[0].1.path, p);
+    }
+
+    #[test]
+    fn drain_dedups_within_debounce_window() {
+        let mut hr = MaterialHotReload::new();
+        let p = PathBuf::from("/tmp/bloom_test_dedup.wgsl");
+        hr.register(3, desc("/tmp/bloom_test_dedup.wgsl"));
+        // notify on macOS fires multiple events per save; same path
+        // 5x within the 120 ms window must collapse to one drain.
+        for _ in 0..5 {
+            hr.test_inject_event(p.clone());
+        }
+        let pending = hr.drain_pending();
+        assert_eq!(pending.len(), 1, "debounce should collapse 5 events to 1");
+    }
+
+    #[test]
+    fn drain_returns_distinct_handles_for_distinct_paths() {
+        let mut hr = MaterialHotReload::new();
+        let p1 = PathBuf::from("/tmp/bloom_test_a.wgsl");
+        let p2 = PathBuf::from("/tmp/bloom_test_b.wgsl");
+        hr.register(1, desc("/tmp/bloom_test_a.wgsl"));
+        hr.register(2, desc("/tmp/bloom_test_b.wgsl"));
+        hr.test_inject_event(p1);
+        hr.test_inject_event(p2);
+        let pending = hr.drain_pending();
+        assert_eq!(pending.len(), 2);
+        let mut handles: Vec<u32> = pending.iter().map(|(h, _)| *h).collect();
+        handles.sort();
+        assert_eq!(handles, vec![1, 2]);
+    }
+
+    #[test]
+    fn drain_ignores_unregistered_paths() {
+        let hr = MaterialHotReload::new();
+        hr.test_inject_event(PathBuf::from("/tmp/never_registered.wgsl"));
+        let pending = hr.drain_pending();
+        assert!(pending.is_empty());
+    }
+
+    #[test]
+    fn empty_channel_drains_to_empty_vec() {
+        let hr = MaterialHotReload::new();
+        assert!(hr.drain_pending().is_empty());
+    }
+
+    /// EN-006 — end-to-end hot-reload: register a real on-disk file,
+    /// inject an event for its canonical path, then verify
+    /// `drain_pending` surfaces the descriptor with the same handle.
+    /// Exercises the path-canonicalisation + by_path lookup that the
+    /// purely-synthetic tests above bypass (their paths don't exist on
+    /// disk, so canonicalize is a no-op fallback).
+    #[test]
+    fn end_to_end_disk_file_drain_returns_descriptor() {
+        let mut tmp = std::env::temp_dir();
+        let unique = format!(
+            "bloom_hotreload_e2e_{}_{}.wgsl",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|d| d.as_nanos())
+                .unwrap_or(0),
+        );
+        tmp.push(unique);
+        std::fs::write(&tmp, "// initial contents\n").expect("write tmp wgsl");
+        let canonical = std::fs::canonicalize(&tmp).expect("canonicalize tmp");
+
+        let mut hr = MaterialHotReload::new();
+        hr.register(
+            42,
+            FileMaterialDesc {
+                path:             canonical.clone(),
+                profile:          FragmentProfile::Translucent,
+                bucket:           Bucket::Refractive,
+                reads_scene:      true,
+                wants_instancing: false,
+            },
+        );
+
+        // Simulate a "file changed" event identical to what the notify
+        // worker would push. The drain path canonicalises the inbound
+        // event path before lookup; the registered key is already
+        // canonical, so the two line up.
+        hr.test_inject_event(canonical.clone());
+        let pending = hr.drain_pending();
+        assert_eq!(pending.len(), 1, "registered descriptor surfaced exactly once");
+        assert_eq!(pending[0].0, 42);
+        assert_eq!(pending[0].1.path, canonical);
+        assert_eq!(pending[0].1.bucket, Bucket::Refractive);
+        assert!(pending[0].1.reads_scene);
+
+        // A subsequent edit (rewrite) injected after the debounce window
+        // re-fires for the same handle. We don't actually wait the full
+        // 120 ms here — the synthetic test_inject_event path bypasses
+        // notify entirely; we just rotate the cache by clearing it
+        // through a fresh inject after manual sleep.
+        std::thread::sleep(DEBOUNCE_WINDOW + std::time::Duration::from_millis(10));
+        std::fs::write(&tmp, "// updated contents\n").expect("rewrite tmp wgsl");
+        hr.test_inject_event(canonical.clone());
+        let pending2 = hr.drain_pending();
+        assert_eq!(pending2.len(), 1, "post-debounce edit drains again");
+        assert_eq!(pending2[0].0, 42);
+
+        let _ = std::fs::remove_file(&tmp);
+    }
+
+    /// EN-006 — full notify path. Registers a file, writes to it, waits
+    /// past the debounce window, drains. Skipped by default because
+    /// macOS FSEvents has variable latency (sometimes >500 ms after
+    /// open) which makes this flaky in CI; run locally with
+    /// `cargo test --release -- --ignored real_notify_fires_after_disk_write`
+    /// to validate the end-to-end watcher wiring.
+    #[test]
+    #[ignore]
+    fn real_notify_fires_after_disk_write() {
+        let mut tmp = std::env::temp_dir();
+        let unique = format!(
+            "bloom_hotreload_notify_{}_{}.wgsl",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|d| d.as_nanos())
+                .unwrap_or(0),
+        );
+        tmp.push(unique);
+        std::fs::write(&tmp, "// v1\n").expect("write tmp wgsl");
+        let canonical = std::fs::canonicalize(&tmp).expect("canonicalize tmp");
+
+        let mut hr = MaterialHotReload::new();
+        hr.register(99, FileMaterialDesc {
+            path:             canonical.clone(),
+            profile:          FragmentProfile::Opaque,
+            bucket:           Bucket::Opaque,
+            reads_scene:      false,
+            wants_instancing: false,
+        });
+
+        // Give the OS a moment to register the watch, then rewrite and
+        // wait past the debounce.
+        std::thread::sleep(std::time::Duration::from_millis(200));
+        std::fs::write(&tmp, "// v2\n").expect("rewrite tmp wgsl");
+        std::thread::sleep(DEBOUNCE_WINDOW + std::time::Duration::from_millis(400));
+
+        let pending = hr.drain_pending();
+        assert!(
+            pending.iter().any(|(h, _)| *h == 99),
+            "notify should have fired for {:?}", canonical,
+        );
+        let _ = std::fs::remove_file(&tmp);
+    }
+}