roxlap_scene/

render.rs

//! Scene-level rendering — drives `roxlap_core::opticast::opticast`
//! across the grids of a [`Scene`].
//!
//! Two entry points:
//!
//! - [`render_scene_composed`] (recommended for multi-grid scenes):
//!   per grid, allocates a temporary framebuffer + zbuffer, runs
//!   opticast into the temp, then merges into the shared output via
//!   per-pixel min-z. Correctly composites overlapping grid output.
//! - [`render_scene`] (single-grid trusting caller): writes every
//!   grid directly into the shared rasterizer. For single-grid
//!   scenes this matches a direct opticast call byte-for-byte; for
//!   multi-grid it's last-grid-wins (sky writes from grid B
//!   overwrite grid A's hits). Useful for tests / single-grid
//!   sanity checks.
//!
//! ## S4B.2.e: Approach B multi-chunk dispatch
//!
//! Both APIs route per-grid rendering through
//! [`crate::Grid::chunk_xy_backing`] → [`roxlap_core::ChunkGrid`] →
//! [`roxlap_core::GridView::from_chunk_grid`] → `opticast`.
//! `opticast`'s prelude looks up the camera's chunk via
//! [`roxlap_core::GridView::chunk_at_xy`]; the grouscan column-step
//! swaps the active per-chunk `(slab_buf, column_offsets)` when
//! rays cross a chunk-XY boundary. The combined-world stitch
//! (Approach C, S4.0..S4.2) is no longer in the render path — the
//! lighting bake still uses it until S4B.4 lands a per-chunk bake.
//!
//! Per-grid rotation (S5) and per-grid LOD (S6) plug in at the
//! same dispatch point: rotate the world camera into grid-local
//! before the chunk-grid lookup, then dispatch coarse / fine /
//! billboard based on grid-camera distance.

// `fb` / `zb` (framebuffer / zbuffer) and the `_fb` / `_zb` suffixes
// throughout this module are voxlap-canonical pairs — drilling them
// apart with longer names just hurts readability.
#![allow(clippy::similar_names)]

use glam::DVec3;
use roxlap_core::dda::{render_dda_parallel, CpuLights, CpuPointLight, DdaEnv};
use roxlap_core::opticast::OpticastSettings;
use roxlap_core::sky::Sky;
use roxlap_core::Camera;
use roxlap_formats::color::Rgb;
use roxlap_formats::material::MaterialTable;

use crate::billboard::{self, BillboardCache, DEFAULT_RESOLUTION as BILLBOARD_RESOLUTION};
use crate::chunks;
use crate::lod::Lod;
use crate::occluder::SceneOccluder;
use crate::{GridId, GridTransform, Scene, CHUNK_SIZE_XY};
use roxlap_core::{CompositeOccluder, WorldOccluder, WorldShadowCtx};
use std::collections::HashMap;

/// Sentinel colour stamped into a `render_sky = false` grid's
/// temporary framebuffer wherever the rasterizer would have drawn
/// sky. After opticast, [`render_scene_composed`] walks the temp
/// buffer and resets `temp_zb` to [`f32::INFINITY`] for any pixel
/// still carrying this value — those pixels then always lose
/// [`compose_into`]'s min-z test and the underlying grid's sky
/// (or another grid's hit) wins.
///
/// Alpha byte is `0x00`. Voxlap voxel slabs carry an alpha-encoded
/// shade in `[0x00, 0x80]`, but a `0x00` alpha **with this exact
/// RGB pattern** is exceedingly unlikely to occur on a real hit
/// (the lit-voxel path produces alpha ≥ 0x40 in practice). Bit
/// pattern is also visually distinct (cyan-ish neon) if anything
/// ever leaks through to the screen, making the bug obvious.
const SKY_MASK_SENTINEL: u32 = 0x00_DE_AD_BE;

/// CPU fog + per-face shading config for the DDA backend, passed by
/// value into the scene render entry points (replaces the old
/// `&mut ScratchPool` parameter the voxlap path threaded fog through).
///
/// `max_scan_dist <= 0` disables fog (no distance blend). Otherwise the
/// DDA renderer linearly ramps a hit's colour toward [`Self::color`]
/// over `max_scan_dist` voxels. `side_shades` darkens each of the six
/// voxel faces — `[x-, x+, y-, y+, z-, z+]`.
#[derive(Debug, Clone, Copy, Default)]
pub struct CpuFog {
    /// Low-24-bit RGB fog colour.
    pub color: u32,
    /// Distance (voxels) at which fog is fully opaque; `<= 0` ⇒ fog OFF.
    pub max_scan_dist: i32,
    /// Per-face brightness reduction `[x-, x+, y-, y+, z-, z+]`.
    pub side_shades: [i8; 6],
}

/// Project a world-space [`Camera`] into a grid's local frame:
/// translate by `-transform.origin`, then apply
/// `transform.rotation.inverse()` to the position and the
/// orthonormal basis (`right` / `down` / `forward`).
///
/// Identity rotation collapses to pure translation, byte-identical
/// to the pre-S5 path (`DQuat::IDENTITY * v == v`). For a rotated
/// grid the rasterizer still sees an axis-aligned chunk grid —
/// rotation is invisible below this layer per PORTING-SCENE.md § S5.
///
/// The basis is rotated as a free vector (no translation
/// component); position is rotated about the grid origin.
fn world_camera_to_grid_local(camera: &Camera, transform: &GridTransform) -> Camera {
    let inv = transform.rotation.inverse();
    // SC — un-rotate into the grid frame, then divide the origin AND the
    // pinhole basis by the grid's world units per voxel so the whole
    // world ray `pos + t·(px·right + py·down + hz·forward)` maps into
    // voxel space; opticast then marches integer voxels and its depth
    // comes back in VOXEL units (the caller scales it back to world by
    // `voxel_world_size` before compositing). `vws == 1.0` is the pre-SC
    // path, bit-for-bit.
    let vws = transform.voxel_world_size;
    let world_offset = DVec3::from_array(camera.pos) - transform.origin;
    let local_pos = (inv * world_offset) / vws;
    let local_right = (inv * DVec3::from_array(camera.right)) / vws;
    let local_down = (inv * DVec3::from_array(camera.down)) / vws;
    let local_forward = (inv * DVec3::from_array(camera.forward)) / vws;
    Camera {
        pos: local_pos.to_array(),
        right: local_right.to_array(),
        down: local_down.to_array(),
        forward: local_forward.to_array(),
    }
}

/// SC — scale a rendered grid's depth buffer back to WORLD units so the
/// cross-grid min-z compose ([`compose_into`] / [`compose_rect`]) stays
/// world-comparable across grids of different scale.
///
/// The factor is **`voxel_world_size²`**, not `vws`. opticast writes
/// `depth = t · (dir·forward)` (`dda.rs`, perpendicular depth). With a
/// `world_camera_to_grid_local` camera whose whole pinhole basis is
/// divided by `vws`, the ray parameter `t` stays the world value, but
/// `dir·forward` shrinks by `vws²` (both `dir` and `forward` are
/// `/vws`) — so the written depth is `world / vws²`. Multiplying by
/// `vws²` recovers world. `INFINITY` (a miss / sky sentinel) stays
/// `INFINITY`. Only the grid's screen rect is touched. No-op — and
/// skipped entirely — at `vws == 1.0`.
fn scale_depth_rect(zb: &mut [f32], pitch_pixels: usize, rect: ScreenRect, voxel_world_size: f64) {
    if (voxel_world_size - 1.0).abs() <= f64::EPSILON {
        return;
    }
    #[allow(clippy::cast_possible_truncation)]
    let vws2 = (voxel_world_size * voxel_world_size) as f32;
    for y in rect.y0..rect.y1 {
        let row = y as usize * pitch_pixels;
        for d in &mut zb[row + rect.x0 as usize..row + rect.x1 as usize] {
            // INFINITY · vws² == INFINITY (vws > 0), so misses stay misses.
            *d *= vws2;
        }
    }
}

/// SC — the world→grid-local camera divides the whole pinhole basis by
/// `vws` (see [`world_camera_to_grid_local`]), so opticast writes
/// `depth = world / vws²` (see [`scale_depth_rect`]). Any WORLD distance
/// opticast compares against that depth must be divided by `vws²` so the
/// comparison fires at the intended world range.
///
/// This governs the two ray-*terminating* thresholds — the scan cutoff
/// (`max_scan_dist`, `depth > max_dist`) and the opaque-fog distance
/// (`fog_max_dist`, `depth >= fog_max_dist`). Both stop the ray, so
/// leaving them unscaled is **geometry-affecting**, not merely cosmetic: a
/// fine grid (`vws < 1`) would have its visible terrain clipped to
/// `range · vws²` — only 6 % of the intended distance at `vws = 0.25`.
///
/// (`mip_scan_dist` is a *scene-LOD-picker* input, not compared against the
/// depth buffer inside the ray, so it is not scaled here. It is also dead
/// config for the DDA backend — vws-aware projected-size LOD is an optional
/// future perf optimization, not a scale bug; see the SC.3 status.)
///
/// Identity — and byte-identical — at `vws == 1.0`.
fn scale_world_dist_f32(world_dist: f32, voxel_world_size: f64) -> f32 {
    if (voxel_world_size - 1.0).abs() <= f64::EPSILON {
        return world_dist;
    }
    #[allow(clippy::cast_possible_truncation)]
    let scaled = (f64::from(world_dist) / (voxel_world_size * voxel_world_size)) as f32;
    scaled
}

/// SC — [`scale_world_dist_f32`] for the integer `max_scan_dist` handed to
/// opticast. Rounds and clamps to `[1, i32::MAX]`. Identity at
/// `vws == 1.0` (byte-identical). The world-space grid distance cull uses
/// the *unscaled* `settings.max_scan_dist`, so only the copy passed to the
/// ray is rescaled here.
fn scale_scan_dist_i32(max_scan_dist: i32, voxel_world_size: f64) -> i32 {
    if (voxel_world_size - 1.0).abs() <= f64::EPSILON {
        return max_scan_dist;
    }
    #[allow(clippy::cast_possible_truncation)]
    let scaled = (f64::from(max_scan_dist) / (voxel_world_size * voxel_world_size))
        .round()
        .clamp(1.0, f64::from(i32::MAX)) as i32;
    scaled
}

/// SC.3 — a grid's bounding sphere in **world** space. [`billboard::grid_bounds`]
/// returns grid-local (voxel) units, so the world sphere scales the centre
/// AND radius by `voxel_world_size` (the centre is then rotated + translated
/// into world). Used by the per-frame distance cull, screen-rect projection,
/// billboard blit, and light-reach cull — all world-space. Identity — and
/// byte-identical — at `vws == 1.0`.
fn grid_world_bounds(grid: &crate::Grid) -> (DVec3, f64) {
    let b = billboard::grid_bounds(grid);
    let vws = grid.transform.voxel_world_size;
    let centre = grid.transform.origin + grid.transform.rotation * (b.centre * vws);
    (centre, b.radius * vws)
}

/// CPU.1 — transform world-space dynamic lights into a grid's local frame
/// (the same translate + inverse-rotation as [`world_camera_to_grid_local`]):
/// point positions are points (origin-relative + inverse-rotated); the sun
/// direction is a vector (inverse-rotated only). Point lights land in `scratch`
/// so the returned [`CpuLights`] can borrow them for the grid's render.
///
/// PF.7 (C4) — `grid_sphere` is the grid's world-space bounding sphere
/// `(centre, radius)`: a light whose reach-sphere can't touch it (with
/// slack for the shadow-bias sample offset) is dropped BEFORE the
/// transform, so the per-hit light loop never sees it. Conservative ⇒
/// byte-identical (a dropped light's `point_falloff` would be 0 at every
/// reachable sample anyway). `None` skips the cull.
fn grid_local_lights<'a>(
    world: &CpuLights<'_>,
    transform: &GridTransform,
    scratch: &'a mut Vec<CpuPointLight>,
    grid_sphere: Option<(DVec3, f64)>,
) -> CpuLights<'a> {
    scratch.clear();
    if !world.enabled {
        return CpuLights::default();
    }
    let inv = transform.rotation.inverse();
    let vws = transform.voxel_world_size;
    #[allow(clippy::cast_possible_truncation)]
    let sun_dir = if world.sun {
        let d = inv
            * DVec3::new(
                f64::from(world.sun_dir[0]),
                f64::from(world.sun_dir[1]),
                f64::from(world.sun_dir[2]),
            );
        [d.x as f32, d.y as f32, d.z as f32]
    } else {
        [0.0; 3]
    };
    // Shade samples sit on voxel surfaces inside the bounding sphere,
    // nudged up to `shadow_bias` along the normal — expand by that plus
    // a unit of float slack.
    let cull_slack = f64::from(world.shadow_bias) + 1.0;
    for p in world.points {
        if let Some((centre, radius)) = grid_sphere {
            let lp = DVec3::new(
                f64::from(p.pos[0]),
                f64::from(p.pos[1]),
                f64::from(p.pos[2]),
            );
            if (lp - centre).length() > f64::from(p.radius) + radius + cull_slack {
                continue;
            }
        }
        // SC — the shade evaluates falloff in the grid's VOXEL frame, so
        // the light's POSITION divides by `voxel_world_size` (a point)
        // and its RADIUS too (a world distance → voxel distance), so the
        // reach sphere stays the same world size. The cone axis is a
        // direction — scale-invariant (uniform scale), rotate only.
        let lp = (inv
            * (DVec3::new(
                f64::from(p.pos[0]),
                f64::from(p.pos[1]),
                f64::from(p.pos[2]),
            ) - transform.origin))
            / vws;
        // SL — the cone axis is a vector: inverse-rotate only (no origin).
        let sd = inv
            * DVec3::new(
                f64::from(p.spot_dir[0]),
                f64::from(p.spot_dir[1]),
                f64::from(p.spot_dir[2]),
            );
        #[allow(clippy::cast_possible_truncation)]
        scratch.push(CpuPointLight {
            pos: [lp.x as f32, lp.y as f32, lp.z as f32],
            color: p.color,
            intensity: p.intensity,
            #[allow(clippy::cast_possible_truncation)]
            radius: (f64::from(p.radius) / vws) as f32,
            casts_shadow: p.casts_shadow,
            spot_dir: [sd.x as f32, sd.y as f32, sd.z as f32],
            cos_inner: p.cos_inner,
            cos_outer: p.cos_outer,
        });
    }
    CpuLights {
        enabled: true,
        sun: world.sun,
        sun_dir,
        sun_color: world.sun_color,
        sun_intensity: world.sun_intensity,
        sun_casts_shadow: world.sun_casts_shadow,
        points: scratch.as_slice(),
        ambient: world.ambient,
        bands: world.bands,
        shadow_tint: world.shadow_tint,
        shadow_strength: world.shadow_strength,
        shadow_bias: world.shadow_bias,
        // SC.2 — `shadow_max_dist` is a WORLD distance (uniform across grids):
        // the sun shadow ray works in this grid's VOXEL frame, so divide by
        // vws to a voxel cap. `WorldShadow`'s ×vws lift (or a single-grid
        // `SamplerShadow`'s voxel march) then reaches `shadow_max_dist` world
        // units on every grid — a fine grid (vws<1) gets full world shadow
        // reach instead of `shadow_max_dist·vws`. Point-light shadows are
        // unaffected (they march to the light's actual `dist`, not this cap).
        // Byte-identical at vws == 1.0.
        #[allow(clippy::cast_possible_truncation)]
        shadow_max_dist: (f64::from(world.shadow_max_dist) / vws) as f32,
    }
}

/// Outcome of a [`render_scene`] / [`render_scene_composed`] call.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RenderOutcome {
    /// At least one grid produced a render.
    Rendered {
        /// Number of grids that were drawn.
        grids_drawn: usize,
    },
    /// No grid rendered — the scene was empty (no populated grids).
    Empty,
}

/// Render every grid in `scene` directly into `(fb, zb)` — no
/// per-grid temp buffer, no compose merge. For multi-grid scenes
/// this is last-grid-wins (later grids' opticast writes overwrite
/// earlier grids' pixels indiscriminately, including sky), so it's
/// only correct for single-grid scenes.
///
/// Use this when you have one grid and want the byte-stable
/// PR.3: pick the cheapest `GridView` constructor that matches the
/// grid's chunk layout.
///
/// Trivial-single-chunk grids (1 chunk at index `(0, 0, 0)`) bypass
/// the multi-chunk rasterizer path: `GridView::from_single_vxl`
/// leaves `chunk_grid = None`, so `phase_after_delete_kept_presync`
/// takes the cheaper single-chunk branch instead of doing
/// `chunk_at_xyz` + IVec2-equality + `Option::is_some` per
/// column-step. Markers / pickups / small ships qualify.
///
/// Multi-chunk grids (ground, larger ships) fall through to
/// `from_chunk_grid` with the supplied `ChunkGrid`.
fn single_chunk_fast_path<'a>(
    backing: &'a chunks::ChunkXyBacking<'a>,
    cg: &'a roxlap_core::ChunkGrid<'a>,
) -> roxlap_core::GridView<'a> {
    if backing.chunks_x == 1
        && backing.chunks_y == 1
        && backing.chunks_z == 1
        && backing.origin_chunk_xy == [0, 0]
        && backing.origin_chunk_z == 0
    {
        // chunk_xyz_backing populates each `Vec<Option<GridView>>`
        // slot via `GridView::from_single_vxl`, which leaves
        // `chunk_grid = None`. Reuse that directly.
        if let Some(single) = backing.chunks[0] {
            return single;
        }
    }
    roxlap_core::GridView::from_chunk_grid(cg, CHUNK_SIZE_XY)
}

/// matches-direct-opticast property — the test suite uses it as a
/// sanity check that the combined-world stitch + render harness
/// doesn't drift vs. a raw `opticast` call.
///
/// Caller pre-fills `fb` with the desired sky colour and `zb` with
/// any value (typically `0.0` matching the per-chunk renderer's
/// convention or `f32::INFINITY` for compose-friendly init); the
/// rasterizer overwrites both per pixel that gets a hit.
#[allow(clippy::too_many_arguments)]
pub fn render_scene(
    fb: &mut [u32],
    zb: &mut [f32],
    pitch_pixels: usize,
    width: u32,
    height: u32,
    fog: CpuFog,
    scene: &mut Scene,
    camera: &Camera,
    settings: &OpticastSettings,
    sky: Option<&Sky>,
) -> RenderOutcome {
    debug_assert_eq!(fb.len(), zb.len());
    let pixel_count = (width as usize) * (height as usize);
    debug_assert_eq!(fb.len(), pixel_count);

    let mut grids_drawn = 0usize;
    for (_id, grid) in scene.grids_mut() {
        // S4B.2.e: Approach B render path. World → grid-local
        // camera transform doesn't need a voxel-offset adjustment
        // anymore — Approach B's chunks live at their signed
        // (chx, chy) indices and `chunk_at_xy` handles negative-
        // index lookups natively.
        //
        // S5.0: per-grid arbitrary rotation. The local camera is
        // built by `world_camera_to_grid_local` — translation +
        // inverse-rotation of the basis. Identity rotation keeps
        // this byte-identical to the pre-S5 translate-only form.
        // DDA.7: refresh the cross-frame brick cache (needs `&mut grid`)
        // before borrowing the grid immutably for `backing`.
        let dda_mip = grid.ensure_dda_bricks(0);
        let Some(backing) = grid.chunk_xyz_backing() else {
            // Empty grid (no populated chz=0 chunks) — skip.
            continue;
        };
        let local_cam = world_camera_to_grid_local(camera, &grid.transform);
        let cg = roxlap_core::ChunkGrid {
            chunks: &backing.chunks,
            origin_chunk_xy: backing.origin_chunk_xy,
            origin_chunk_z: backing.origin_chunk_z,
            chunks_x: backing.chunks_x,
            chunks_y: backing.chunks_y,
            chunks_z: backing.chunks_z,
        };
        let grid_view = single_chunk_fast_path(&backing, &cg);
        // DDA backend. The direct path doesn't pre-fill, so seed sky
        // (black) + far depth here — DDA leaves misses untouched.
        for px in fb.iter_mut() {
            *px = 0;
        }
        for d in zb.iter_mut() {
            *d = f32::INFINITY;
        }
        let fog_on = fog.max_scan_dist > 0;
        // SC — opticast writes WORLD/vws² depth under a scaled basis, so the
        // ray-terminating world thresholds (scan cutoff + opaque fog) are
        // divided by vws² to fire at the intended world range. Identity at
        // vws == 1.0 (byte-identical). See `scale_world_dist_f32`.
        let vws = grid.transform.voxel_world_size;
        #[allow(clippy::cast_precision_loss)]
        let env = DdaEnv {
            sky,
            fog_color: if fog_on { fog.color } else { 0 },
            fog_max_dist: if fog_on {
                scale_world_dist_f32(fog.max_scan_dist.max(1) as f32, vws)
            } else {
                0.0
            },
            side_shades: fog.side_shades,
            // The direct (non-composed) path is opaque-only; terrain
            // materials flow through render_scene_composed_with_materials.
            materials: None,
            terrain_materials: &[],
            // The direct path is unlit (lighting flows through the composed
            // path); keep it on the baked-byte shade.
            lights: CpuLights::default(),
            world_shadow: None,
        };
        // Scan-cutoff copy (identity at vws == 1.0 → same &settings).
        let grid_settings;
        let ray_settings = if (vws - 1.0).abs() <= f64::EPSILON {
            settings
        } else {
            grid_settings = OpticastSettings {
                max_scan_dist: scale_scan_dist_i32(settings.max_scan_dist, vws),
                ..*settings
            };
            &grid_settings
        };
        render_dda_parallel(
            &local_cam,
            ray_settings,
            grid_view,
            fb,
            zb,
            pitch_pixels,
            &env,
            &grid.dda_brick_cache,
            dda_mip,
        );
        // SC — opticast wrote VOXEL-unit depth (the camera is voxel-frame);
        // scale it back to WORLD so the buffer is world-consistent (this
        // path clears + renders per grid, so only this grid's pixels are
        // present). No-op at vws == 1.0. INFINITY misses stay misses.
        if (vws - 1.0).abs() > f64::EPSILON {
            // world = written · vws² (see `scale_depth_rect`).
            #[allow(clippy::cast_possible_truncation)]
            let vws2 = (vws * vws) as f32;
            for d in zb.iter_mut() {
                *d *= vws2;
            }
        }
        grids_drawn += 1;
    }
    if grids_drawn == 0 {
        RenderOutcome::Empty
    } else {
        RenderOutcome::Rendered { grids_drawn }
    }
}

/// Per-pixel "min-z wins" merge of `(temp_fb, temp_zb)` into
/// `(shared_fb, shared_zb)`.
///
/// Voxlap's z-buffer convention: `z` = perpendicular distance from
/// camera; **smaller `z` = closer to camera**. This helper picks
/// the closer pixel per slot. Sky pixels emerge with a large `z`
/// (`scratch.skycast.dist`, set to `gxmax` or `i32::MAX` per
/// `phase_startsky`) so they always lose to any hit's finite
/// distance.
///
/// `temp_fb` / `temp_zb` are read-only inputs; both must have the
/// same length as `shared_fb` / `shared_zb` (debug-asserted).
pub fn compose_into(
    shared_fb: &mut [u32],
    shared_zb: &mut [f32],
    temp_fb: &[u32],
    temp_zb: &[f32],
) {
    debug_assert_eq!(shared_fb.len(), shared_zb.len());
    debug_assert_eq!(shared_fb.len(), temp_fb.len());
    debug_assert_eq!(shared_fb.len(), temp_zb.len());
    for i in 0..shared_fb.len() {
        if temp_zb[i] < shared_zb[i] {
            shared_fb[i] = temp_fb[i];
            shared_zb[i] = temp_zb[i];
        }
    }
}

/// Half-open screen rectangle `[x0, x1) × [y0, y1)` a grid's
/// projection is confined to — the scissor [`render_scene_composed`]
/// uses to render and compose each grid only within its screen
/// footprint instead of over the whole frame.
#[derive(Clone, Copy, Debug)]
struct ScreenRect {
    x0: u32,
    x1: u32,
    y0: u32,
    y1: u32,
}

impl ScreenRect {
    fn is_empty(self) -> bool {
        self.x0 >= self.x1 || self.y0 >= self.y1
    }
}

/// Project a world-space bounding sphere `(centre, radius)` to a
/// conservative screen rectangle under opticast's pinhole — focal `hz`,
/// principal point `(hx, hy)`, ray for pixel `(px, py)` being
/// `(px-hx)·right + (py-hy)·down + hz·forward` (camera_math). Returns:
///
/// - `Some(rect)` clamped to the viewport when the sphere is safely in
///   front of the camera. The rect may be **empty** (sphere off to one
///   side) → the grid can't appear, so the caller skips it entirely.
/// - `None` when the camera is inside or near the sphere (forward-depth
///   `z ≤ radius`), where a finite screen bound is unsafe → the caller
///   must render the grid full-frame.
///
/// Conservative on purpose (never clips a pixel the full render would
/// touch): the projected radius uses the over-estimate `hz·R/(z−R)`
/// (exact is `hz·R/√(z²−R²)`) and pads by `anginc + 1`, matching the
/// projection's `anginc` viewport padding.
fn project_sphere_to_screen(
    camera: &Camera,
    centre: DVec3,
    radius: f64,
    settings: &OpticastSettings,
) -> Option<ScreenRect> {
    let d = centre - DVec3::from_array(camera.pos);
    let z = d.dot(DVec3::from_array(camera.forward));
    if z <= radius {
        return None; // camera inside / in front of the sphere shell
    }
    let x = d.dot(DVec3::from_array(camera.right));
    let y = d.dot(DVec3::from_array(camera.down));
    let (hx, hy, hz) = (
        f64::from(settings.hx),
        f64::from(settings.hy),
        f64::from(settings.hz),
    );
    let sr = hz * radius / (z - radius); // over-estimated screen radius
    let sx = hx + x / z * hz;
    let sy = hy + y / z * hz;
    let pad = f64::from(settings.anginc) + 1.0;
    let (xres, yres) = (f64::from(settings.xres), f64::from(settings.yres));
    let clamp = |v: f64, hi: f64| v.clamp(0.0, hi);
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Some(ScreenRect {
        x0: clamp((sx - sr - pad).floor(), xres) as u32,
        x1: clamp((sx + sr + pad).ceil(), xres) as u32,
        y0: clamp((sy - sr - pad).floor(), yres) as u32,
        y1: clamp((sy + sr + pad).ceil(), yres) as u32,
    })
}

/// Fill each `rect` row of a `u32` buffer (row stride `pitch`) with
/// `val` — the scissored analogue of `slice.fill(val)`.
fn fill_rect_u32(buf: &mut [u32], pitch: usize, rect: ScreenRect, val: u32) {
    for y in rect.y0..rect.y1 {
        let row = y as usize * pitch;
        buf[row + rect.x0 as usize..row + rect.x1 as usize].fill(val);
    }
}

/// Fill each `rect` row of an `f32` buffer (row stride `pitch`) with `val`.
fn fill_rect_f32(buf: &mut [f32], pitch: usize, rect: ScreenRect, val: f32) {
    for y in rect.y0..rect.y1 {
        let row = y as usize * pitch;
        buf[row + rect.x0 as usize..row + rect.x1 as usize].fill(val);
    }
}

/// Min-z compose `temp_*` into `fb`/`zb` over `rect` only — the
/// scissored analogue of [`compose_into`]. A `temp` pixel wins where its
/// `z` is strictly smaller than the destination's.
///
/// PF.7 (C6) — rayon rows: a memory-bandwidth loop repeated per grid per
/// frame; rows are disjoint (`par_chunks_mut` of both destinations),
/// sources read-only. Bit-identical.
fn compose_rect(
    fb: &mut [u32],
    zb: &mut [f32],
    temp_fb: &[u32],
    temp_zb: &[f32],
    pitch: usize,
    rect: ScreenRect,
) {
    use rayon::prelude::*;
    let (y0, y1) = (rect.y0 as usize, rect.y1 as usize);
    let (x0, x1) = (rect.x0 as usize, rect.x1 as usize);
    if y0 >= y1 {
        return;
    }
    // The last row may be short of a full `pitch` when the buffer is
    // exactly `width*height` — clamp the slice end.
    let end = (y1 * pitch).min(fb.len());
    fb[y0 * pitch..end]
        .par_chunks_mut(pitch)
        .zip(zb[y0 * pitch..end].par_chunks_mut(pitch))
        .enumerate()
        .for_each(|(dy, (frow, zrow))| {
            let row = (y0 + dy) * pitch;
            for x in x0..x1 {
                if temp_zb[row + x] < zrow[x] {
                    zrow[x] = temp_zb[row + x];
                    frow[x] = temp_fb[row + x];
                }
            }
        });
}

/// PF.7 (C6) — reusable scratch for the composed scene render: the
/// per-grid temp framebuffer/z-buffer pair (was two full-frame `vec!`
/// allocations + initialising writes per call — ≈7.4 MB at 720p, ×16
/// under 4×SSAA), the per-grid light scratch, and the phase-A mip map.
/// Own one per renderer and pass it to
/// [`render_scene_composed_with_materials_scratch`]; the buffers grow to
/// the frame size on first use and are reused verbatim afterwards (every
/// pixel the render reads is filled per grid first, so no per-frame
/// clear is needed).
#[derive(Default)]
pub struct SceneRenderScratch {
    temp_fb: Vec<u32>,
    temp_zb: Vec<f32>,
    lights: Vec<CpuPointLight>,
    eff_mips: HashMap<GridId, u32>,
}

/// Render every grid in `scene` with per-grid temporary buffers +
/// z-buffer composition. The canonical multi-grid scene render
/// path.
///
/// Algorithm:
/// 1. Caller pre-fills `fb` with the desired sky colour and `zb`
///    with [`f32::INFINITY`] (so any rendered pixel wins the
///    initial composition).
/// 2. For each grid, allocate a temporary `(temp_fb, temp_zb)` of
///    the same size, pre-fill them with sky / `INFINITY`, and run
///    `opticast` into them via a `ScalarRasterizer` over the
///    temporary buffers AND the grid's combined-world view (S4.0).
/// 3. Merge the temporary buffers into the shared `(fb, zb)` via
///    [`compose_into`] — closer pixels (smaller `z`) win.
///
/// Pixel correctness across overlapping grids: sky pixels emerge
/// with `z` = `gxmax` / `i32::MAX` (a very large value), so they
/// always lose to any hit. Hits compete on actual perpendicular
/// distance — the closer grid's surface is what gets composited.
///
/// `pitch_pixels` is the framebuffer's row stride in pixels (×4 for
/// bytes). `width` × `height` must equal `fb.len()` /
/// `zb.len()`. `sky` is the optional textured sky resource the
/// rasterizer threads through to `phase_startsky`; `None` ⇒ solid
/// `pool.skycast` fill.
///
/// **Heap allocation per call:** two `Vec` allocations per grid (a
/// temp framebuffer and zbuffer). For repeated frame rendering an
/// owned scratch struct that pre-allocates these is the obvious
/// optimisation; deferred until profiling shows it matters.
#[allow(clippy::too_many_arguments)]
pub fn render_scene_composed(
    fb: &mut [u32],
    zb: &mut [f32],
    pitch_pixels: usize,
    width: u32,
    height: u32,
    fog: CpuFog,
    scene: &mut Scene,
    camera: &Camera,
    settings: &OpticastSettings,
    sky_color: u32,
    sky: Option<&Sky>,
) -> RenderOutcome {
    render_scene_composed_scissored(
        fb,
        zb,
        pitch_pixels,
        width,
        height,
        fog,
        scene,
        camera,
        settings,
        sky_color,
        sky,
        true,
        None,
        &[],
        CpuLights::default(),
        None,
        &mut SceneRenderScratch::default(),
    )
}

/// [`render_scene_composed`] with TV terrain materials: `materials` is the
/// global palette and `terrain_materials` the colour→material map; together
/// they make matching-colour terrain voxels translucent (front-to-back
/// composited). An empty map / `None` palette renders identically to
/// [`render_scene_composed`].
#[allow(clippy::too_many_arguments)]
pub fn render_scene_composed_with_materials(
    fb: &mut [u32],
    zb: &mut [f32],
    pitch_pixels: usize,
    width: u32,
    height: u32,
    fog: CpuFog,
    scene: &mut Scene,
    camera: &Camera,
    settings: &OpticastSettings,
    sky_color: u32,
    sky: Option<&Sky>,
    materials: Option<&MaterialTable>,
    terrain_materials: &[(Rgb, u8)],
    lights: CpuLights<'_>,
    // XS.2 — sprite-cast shadow occluder (so sprites darken terrain). `None` ⇒
    // grids-only shadows.
    sprite_occluder: Option<&dyn WorldOccluder>,
) -> RenderOutcome {
    render_scene_composed_scissored(
        fb,
        zb,
        pitch_pixels,
        width,
        height,
        fog,
        scene,
        camera,
        settings,
        sky_color,
        sky,
        true,
        materials,
        terrain_materials,
        lights,
        sprite_occluder,
        &mut SceneRenderScratch::default(),
    )
}

/// [`render_scene_composed_with_materials`] with a caller-owned
/// [`SceneRenderScratch`] (PF.7) — the per-frame render path: the temp
/// buffer pair and per-grid scratch are reused across frames instead of
/// re-allocated per call.
#[allow(clippy::too_many_arguments)]
pub fn render_scene_composed_with_materials_scratch(
    fb: &mut [u32],
    zb: &mut [f32],
    pitch_pixels: usize,
    width: u32,
    height: u32,
    fog: CpuFog,
    scene: &mut Scene,
    camera: &Camera,
    settings: &OpticastSettings,
    sky_color: u32,
    sky: Option<&Sky>,
    materials: Option<&MaterialTable>,
    terrain_materials: &[(Rgb, u8)],
    lights: CpuLights<'_>,
    sprite_occluder: Option<&dyn WorldOccluder>,
    scratch: &mut SceneRenderScratch,
) -> RenderOutcome {
    render_scene_composed_scissored(
        fb,
        zb,
        pitch_pixels,
        width,
        height,
        fog,
        scene,
        camera,
        settings,
        sky_color,
        sky,
        true,
        materials,
        terrain_materials,
        lights,
        sprite_occluder,
        scratch,
    )
}

/// Backing implementation of [`render_scene_composed`] with the
/// per-grid screen-AABB scissor toggleable. `scissor = true` is the
/// production path; the regression test renders the same scene with
/// `false` (full-frame per grid, the pre-scissor behaviour) and asserts
/// the framebuffer is byte-identical — the scissor must be a pure
/// speed-up, never change a pixel.
#[allow(clippy::too_many_arguments, clippy::too_many_lines)]
fn render_scene_composed_scissored(
    fb: &mut [u32],
    zb: &mut [f32],
    pitch_pixels: usize,
    width: u32,
    height: u32,
    fog: CpuFog,
    scene: &mut Scene,
    camera: &Camera,
    settings: &OpticastSettings,
    sky_color: u32,
    sky: Option<&Sky>,
    scissor: bool,
    materials: Option<&MaterialTable>,
    terrain_materials: &[(Rgb, u8)],
    // CPU.1 — world-space dynamic lights, transformed per grid in the loop.
    lights: CpuLights<'_>,
    // XS.2 — world-space occluder for sprite volumes (so sprites cast shadows
    // onto terrain). Composited with the per-frame grid occluder. `None` ⇒
    // grids only.
    sprite_occluder: Option<&dyn WorldOccluder>,
    // PF.7 — caller-owned reusable buffers (see [`SceneRenderScratch`]).
    scratch: &mut SceneRenderScratch,
) -> RenderOutcome {
    debug_assert_eq!(fb.len(), zb.len());
    let pixel_count = (width as usize) * (height as usize);
    debug_assert_eq!(fb.len(), pixel_count);

    let mut grids_drawn = 0usize;
    // PF.7 (C6) — size (don't clear) the temp pair: every pixel the
    // render reads inside a grid's rect is `fill_rect_*`-initialised for
    // that grid first, and `compose_rect` reads only within the rect, so
    // stale contents outside are never observed. This removes two
    // full-frame allocations AND their initialising writes per call.
    let scratch = &mut *scratch;
    scratch.temp_fb.resize(pixel_count, 0);
    scratch.temp_zb.resize(pixel_count, f32::INFINITY);
    let temp_fb = &mut scratch.temp_fb[..pixel_count];
    let temp_zb = &mut scratch.temp_zb[..pixel_count];

    // XS.1 — phase A (`&mut`): materialise the per-frame caches the render
    // reads — DDA brick caches (Near/Mid) and Far-tier billboard impostors —
    // and record each grid's effective DDA mip. Hoisting these out of the
    // render loop lets phase B run over `&Scene` immutably, so the cross-grid
    // shadow occluder (which also borrows the scene) can coexist with it.
    let cam_world = DVec3::from_array(camera.pos);
    let eff_mips = &mut scratch.eff_mips;
    eff_mips.clear();
    for (id, grid) in scene.grids_mut() {
        let lod = grid.select_lod(cam_world);
        if lod == Lod::Far {
            if !grid.chunks.is_empty() && grid.billboards.is_none() {
                let cache = BillboardCache::build(grid, BILLBOARD_RESOLUTION);
                grid.billboards = Some(cache);
            }
            continue; // Far blits an impostor; no brick cache / mip needed.
        }
        let req = match lod {
            Lod::Mid => grid
                .lod_thresholds
                .mid_mip_levels
                .map_or(0, |n| n.saturating_sub(1)),
            Lod::Near | Lod::Far => 0,
        };
        eff_mips.insert(id, grid.ensure_dda_bricks(req));
    }

    // Reborrow immutably for phase B + the shadow occluder.
    let scene: &Scene = scene;

    // XS.1 — cross-grid hard shadows: build the world-space scene occluder
    // once when shadows are actually active (a caster flagged + non-zero
    // strength), so the shadow ray at a terrain hit tests every grid, not
    // just the one it hit. `None` ⇒ the single-grid `SamplerShadow` path.
    let shadows_on = lights.enabled
        && lights.shadow_strength > 0.0
        && (lights.sun_casts_shadow || lights.points.iter().any(|p| p.casts_shadow));
    let grid_occ = shadows_on
        .then(|| SceneOccluder::build(scene))
        .filter(|o| !o.is_empty());
    // XS.2 — combine the grid occluder with the sprite occluder (sprites cast
    // onto terrain). `composite_store` backs the borrow when both are present.
    let composite_store;
    let active_occluder: Option<&dyn WorldOccluder> = if shadows_on {
        match (grid_occ.as_ref(), sprite_occluder) {
            (Some(g), Some(s)) => {
                composite_store = CompositeOccluder { a: g, b: s };
                Some(&composite_store)
            }
            (Some(g), None) => Some(g),
            (None, Some(s)) => Some(s),
            (None, None) => None,
        }
    } else {
        None
    };

    for (grid_id, grid) in scene.grids() {
        // S6.0/S6.1: per-grid LOD tier dispatch. The picker keys
        // off the grid's `lod_thresholds` and the world-space
        // camera. Default thresholds are `always_near` so every
        // grid lands on `Lod::Near` and the framebuffer stays
        // byte-identical to the pre-S6 path.
        //
        // S6.1: `Mid` applies the grid's `mid_mip_levels` /
        // `mid_mip_scan_dist` overrides (if `Some`) on top of the
        // base settings, biasing the grid into coarser mips. With
        // both `None`, Mid renders identically to Near (graceful
        // degrade — callers opt into the Mid plumbing via
        // `LodThresholds::from_radius_with_mid_mip`).
        //
        // S6.3: `Far` skips the opticast path entirely — render
        // dispatches into the billboard impostor blit (below). The
        // LOD enum is computed before `chunk_xyz_backing` because
        // the Far branch needs `&mut grid` for the lazy cache
        // populate, which conflicts with the `&grid` lifetime
        // backing's tied to.
        let lod = grid.select_lod(DVec3::from_array(camera.pos));

        if lod == Lod::Far {
            // S6.3: Far-tier billboard blit. The impostor cache was built in
            // phase A (above); this immutable pass only reads it.
            //
            // Empty grids have nothing to impostor; skip.
            if grid.chunks.is_empty() {
                continue;
            }
            // Grid bounds → world-space centre + radius (SC.3 folds in vws).
            let (centre_world, world_radius) = grid_world_bounds(grid);
            // Query direction = unit vector from grid centre TO
            // camera, in grid-local space (snapshots' `view_dir`s
            // live in that frame).
            let cam_pos = DVec3::from_array(camera.pos);
            let centre_to_cam_world = cam_pos - centre_world;
            let ctc_len = centre_to_cam_world.length();
            if !ctc_len.is_finite() || ctc_len < 1e-9 {
                // Camera essentially at grid centre — pick_nearest
                // is ill-defined. Skip; a future frame at a
                // resolvable pose will render normally.
                continue;
            }
            let query_dir_world = centre_to_cam_world / ctc_len;
            let query_dir_local = grid.transform.rotation.inverse() * query_dir_world;
            // Cache was populated in phase A for non-empty Far grids; if it's
            // somehow absent, skip (a future frame re-enters Far and builds).
            let Some(cache) = grid.billboards.as_ref() else {
                continue;
            };
            // pick_nearest only returns None for empty caches; the phase-A
            // build produced a 26-snapshot cache so this resolves.
            let Some(snapshot) = cache.pick_nearest(query_dir_local) else {
                continue;
            };
            billboard::billboard_blit_into(
                fb,
                zb,
                pitch_pixels,
                width,
                height,
                snapshot,
                centre_world,
                world_radius,
                camera,
                settings,
            );
            grids_drawn += 1;
            continue;
        }

        // S4B.2.e: Approach B render path. See `render_scene`'s
        // body for the camera transform + ChunkGrid construction
        // commentary; the only difference is this writes to
        // (temp_fb, temp_zb) and composes via `compose_into`.
        // S5.0: per-grid rotation flows via the shared helper.
        //
        // DDA.7: refresh the cross-frame brick cache (needs `&mut grid`)
        // before the immutable `backing` borrow. Render mip by LOD tier:
        // Near = full detail, Mid = coarser (clamped to built mips).
        // Mid tier: coarsen by the grid's `mid_mip_levels` override
        // (a level count → uniform DDA mip `n-1`). No override ⇒ mip
        // 0, i.e. byte-identical to Near (the override is opt-in).
        // Effective DDA mip: the brick cache was ensured in phase A; reuse the
        // mip it resolved (Near/Mid grids are recorded; default 0 otherwise).
        let dda_eff_mip = eff_mips.get(&grid_id).copied().unwrap_or(0);
        let Some(backing) = grid.chunk_xyz_backing() else {
            continue;
        };

        // Out-of-range early-out: skip the per-grid opticast pass
        // when the grid's bounding sphere is entirely beyond
        // `max_scan_dist`. Each opticast call walks ~width*height
        // rays even when no ray reaches a voxel, so far-away marker
        // pillars / pickups otherwise cost ~9 ms each at the bench
        // pose. Safe: if the closest point of the sphere is past
        // max_scan_dist, no ray can possibly reach the grid, so
        // dropping the opticast pass is byte-identical.
        //
        // `grid_bounds` walks `grid.chunks.keys()`; for the ground's
        // ~1024 chunks it costs ~10 µs amortised against the ~50 ms
        // it might save by culling 4-of-5 markers in the live demo.
        let (centre_world, world_radius) = grid_world_bounds(grid);
        let cam_pos = DVec3::from_array(camera.pos);
        let dist_to_centre = (centre_world - cam_pos).length();
        if dist_to_centre - world_radius > f64::from(settings.max_scan_dist) {
            continue;
        }

        // Per-grid screen-space scissor: confine this grid's opticast +
        // temp reset + compose to the true screen rect its projection
        // spans, and skip the grid entirely when it projects fully
        // off-screen on either axis. `project_sphere_to_screen` is
        // conservative (over-estimates the footprint), so the rendered
        // pixels stay byte-identical to the full-frame path — only the
        // work shrinks.
        //
        // PF.13 (C7) — the horizontal extent now clips the render too.
        // The historical full-width-only constraint guarded the deleted
        // voxlap radar's column-indexed `angstart` (never reset per
        // grid, so x-clipping read stale entries at extreme poses); the
        // DDA renderer's pixels are fully independent, so the x band is
        // as safe as the long-proven y band. Small grids (markers,
        // pickups, ships) stop paying full-width rows of render + fill
        // + compose. `None` (camera inside/near the sphere) renders
        // full-frame; `scissor = false` disables it all for the
        // byte-identity regression test.
        let full_rect = ScreenRect {
            x0: 0,
            x1: width,
            y0: 0,
            y1: height,
        };
        let rect = if scissor {
            match project_sphere_to_screen(camera, centre_world, world_radius, settings) {
                // Off-screen on either axis → the grid can't appear.
                Some(r) if r.is_empty() => continue,
                Some(r) => r,
                None => full_rect,
            }
        } else {
            full_rect
        };

        // S5.2-followup: per-grid sky opt-out. Grids with
        // `render_sky = false` (e.g. a rotating ship) must not
        // contribute sky pixels — the grid-local sky lookup
        // rotates with the grid and visibly fights the world's
        // sky during compose. Implementation: stamp a sentinel
        // colour into temp_fb everywhere the rasterizer would
        // paint sky, then walk the buffer post-opticast and
        // mark sentinel pixels as `INFINITY` in temp_zb so
        // [`compose_into`]'s min-z test always drops them.
        let owns_sky = grid.render_sky;
        let local_sky_color = if owns_sky {
            sky_color
        } else {
            SKY_MASK_SENTINEL
        };

        // Reset temp to sky / INFINITY so each grid starts fresh —
        // only within the grid's screen rect (opticast writes nothing
        // outside it, and the rect-limited compose reads nothing there).
        fill_rect_u32(temp_fb, pitch_pixels, rect, local_sky_color);
        fill_rect_f32(temp_zb, pitch_pixels, rect, f32::INFINITY);

        let local_cam = world_camera_to_grid_local(camera, &grid.transform);
        let cg = roxlap_core::ChunkGrid {
            chunks: &backing.chunks,
            origin_chunk_xy: backing.origin_chunk_xy,
            origin_chunk_z: backing.origin_chunk_z,
            chunks_x: backing.chunks_x,
            chunks_y: backing.chunks_y,
            chunks_z: backing.chunks_z,
        };
        let grid_view = single_chunk_fast_path(&backing, &cg);

        // Build the per-grid settings by layering three opt-in
        // overrides on top of the caller's `settings`:
        //
        //   1. (S6.1) `lod_thresholds.mid_mip_levels` /
        //      `mid_mip_scan_dist` — applied iff `lod == Mid`.
        //      Biases the grid into coarser mips via the existing
        //      multi-mip path. None ⇒ Mid degrades to Near's
        //      settings (graceful).
        //   2. (S5.2-followup) `Grid::mip_levels_override` — global
        //      per-grid cap applied at ALL tiers. Preserves the
        //      ship anti-axis-aligned-beam workaround through Mid
        //      tier (so a rotating ship pinned at mip-0 stays at
        //      mip-0 even when distant).
        //
        // Layer order: Mid overrides first, then global cap. Both
        // mip_levels overrides are clamped to `[1, base.mip_levels]`
        // since the base is the maximum the renderer can use
        // (chunk's `chunk_mips`-min logic inside scalar_rasterizer
        // applies further per-chunk).
        let per_grid_settings;
        let active_settings = {
            let base_mip_levels = settings.mip_levels;
            let base_mip_scan = settings.mip_scan_dist;
            let lod_mip_levels = match lod {
                Lod::Mid => grid.lod_thresholds.mid_mip_levels,
                Lod::Near | Lod::Far => None,
            };
            let lod_mip_scan = match lod {
                Lod::Mid => grid.lod_thresholds.mid_mip_scan_dist,
                Lod::Near | Lod::Far => None,
            };
            let global_mip_cap = grid.mip_levels_override;
            let needs_override =
                lod_mip_levels.is_some() || lod_mip_scan.is_some() || global_mip_cap.is_some();
            if needs_override {
                // Resolve mip_levels: start with base, apply LOD
                // override (clamped to base), then apply global cap.
                let mut mip_levels =
                    lod_mip_levels.map_or(base_mip_levels, |n| n.clamp(1, base_mip_levels));
                if let Some(cap) = global_mip_cap {
                    mip_levels = mip_levels.min(cap.clamp(1, base_mip_levels));
                }
                // Resolve mip_scan_dist: LOD override clamps to
                // `min(base, override)` — the override only makes
                // transitions kick in CLOSER, never farther. The
                // renderer floors at 4 internally so we don't
                // bottom-clamp here.
                let mip_scan_dist = lod_mip_scan.map_or(base_mip_scan, |d| base_mip_scan.min(d));
                per_grid_settings = OpticastSettings {
                    mip_levels,
                    mip_scan_dist,
                    ..*settings
                };
                &per_grid_settings
            } else {
                settings
            }
        };

        // PF.13 (C7) — 2D scissor: restrict the render to the grid's
        // true screen rect. The y strip is the long-proven path; the x
        // band joins it now that the radar-era `angstart` fragility is
        // gone (see the rect computation above). Byte-identical to the
        // full frame when the rect is `0..width × 0..height`.
        // SC — the scan cutoff (`max_scan_dist`) is a WORLD distance the ray
        // compares against its WORLD/vws² depth, so it is divided by vws² for
        // the ray to reach the intended world range (a fine grid would
        // otherwise be clipped short). Identity at vws == 1.0 (byte-identical).
        // The world-space distance cull above uses the *unscaled* setting.
        let vws = grid.transform.voxel_world_size;
        let mut scissored = (*active_settings)
            .with_y_range(rect.y0, rect.y1)
            .with_x_range(rect.x0, rect.x1);
        scissored.max_scan_dist = scale_scan_dist_i32(scissored.max_scan_dist, vws);
        // DDA backend. temp_fb / temp_zb are already pre-filled with
        // sky / INFINITY for this grid's rect, so a miss with no
        // textured sky yields the correct solid sky.
        //
        // Fog is config-driven: on iff the caller set `max_scan_dist > 0`
        // in `fog`. Off → no blend, so exact-colour tests and unfogged
        // hosts are unaffected. Linear ramp toward the configured fog
        // colour over `max_scan_dist`. Sky texture is suppressed for
        // `!owns_sky` grids so the textured-sky branch doesn't bypass
        // the sentinel.
        let fog_on = fog.max_scan_dist > 0;
        // CPU.1 — transform the world lights into this grid's local frame
        // (the reused point scratch lives for the grid's render below).
        // PF.7 — lights that can't reach the grid's bounding sphere are
        // culled (`bounds`/`centre_world` computed for the distance cull
        // above).
        let local_lights = grid_local_lights(
            &lights,
            &grid.transform,
            &mut scratch.lights,
            Some((centre_world, world_radius)),
        );
        // XS.1 — cross-grid shadows: hand the shade the scene-wide occluder
        // plus this grid's local→world transform, so a grid-local shadow ray
        // is lifted to world space and tested against every grid. `cols[i]`
        // is the world image of grid-local axis `i` (the rotation's columns).
        let world_shadow = active_occluder.map(|occ| {
            let r = grid.transform.rotation;
            let col = |v: DVec3| {
                let w = r * v;
                [w.x as f32, w.y as f32, w.z as f32]
            };
            let o = grid.transform.origin;
            #[allow(clippy::cast_possible_truncation)]
            WorldShadowCtx {
                occluder: occ,
                // SC.2 — keep the grid world origin at full f64 precision.
                origin: [o.x, o.y, o.z],
                cols: [col(DVec3::X), col(DVec3::Y), col(DVec3::Z)],
                // SC.2 — caster vws: the shade's grid-local voxel ray scales
                // to world by this before the scene-wide occlusion test.
                voxel_world_size: grid.transform.voxel_world_size as f32,
            }
        });
        #[allow(clippy::cast_precision_loss)]
        let env = DdaEnv {
            sky: if owns_sky { sky } else { None },
            fog_color: if fog_on { fog.color } else { 0 },
            // SC — opaque-fog distance also terminates the ray, so it is
            // divided by vws² alongside the scan cutoff (identity at vws==1.0).
            fog_max_dist: if fog_on {
                scale_world_dist_f32(fog.max_scan_dist.max(1) as f32, vws)
            } else {
                0.0
            },
            side_shades: fog.side_shades,
            materials,
            terrain_materials,
            lights: local_lights,
            world_shadow,
        };
        // Effective render mip + brick cache were prepared above
        // (DDA.6 uniform per-grid mip, DDA.7 cross-frame cache).
        render_dda_parallel(
            &local_cam,
            &scissored,
            grid_view,
            temp_fb,
            temp_zb,
            pitch_pixels,
            &env,
            &grid.dda_brick_cache,
            dda_eff_mip,
        );
        // SC — voxel-unit depth → world, so the cross-grid min-z compose
        // below is world-comparable across grids of different scale.
        // No-op at vws == 1.0 (byte-identical).
        scale_depth_rect(temp_zb, pitch_pixels, rect, grid.transform.voxel_world_size);

        if !owns_sky {
            // Mask sentinel pixels so compose drops them — only within
            // the grid's rect (opticast wrote nothing outside it).
            for y in rect.y0..rect.y1 {
                let row = y as usize * pitch_pixels;
                for i in row + rect.x0 as usize..row + rect.x1 as usize {
                    if temp_fb[i] == SKY_MASK_SENTINEL {
                        temp_zb[i] = f32::INFINITY;
                    }
                }
            }
        }

        compose_rect(fb, zb, temp_fb, temp_zb, pitch_pixels, rect);
        grids_drawn += 1;
    }

    if grids_drawn == 0 {
        RenderOutcome::Empty
    } else {
        RenderOutcome::Rendered { grids_drawn }
    }
}

#[cfg(test)]
#[allow(clippy::float_cmp)]
mod tests {
    use super::*;
    use crate::{GridTransform, Scene, CHUNK_SIZE_XY};
    use glam::{DVec3, IVec3};
    use roxlap_core::opticast::OpticastSettings;
    use roxlap_core::{Camera, Engine};
    use roxlap_formats::color::VoxColor;

    const XRES: u32 = 320;
    const YRES: u32 = 200;

    /// Build a single-grid scene at the given world origin with a
    /// recognisable shape inside its chunk (0, 0, 0): a 16-voxel
    /// box plus a 6-radius sphere. Returns `(scene, grid_id)`.
    fn build_one_grid_scene(world_origin: DVec3) -> (Scene, crate::GridId) {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(world_origin));
        let grid = scene.grid_mut(id).unwrap();
        // Box covering [40..56]³ in chunk-local coords.
        grid.set_rect(
            IVec3::new(40, 40, 40),
            IVec3::new(55, 55, 55),
            Some(VoxColor(0x80_88_88_88)),
        );
        // Sphere at (80, 80, 80) radius 6.
        grid.set_sphere(IVec3::new(80, 80, 80), 6, Some(VoxColor(0x80_22_aa_22)));
        (scene, id)
    }

    fn camera_at(pos: [f64; 3]) -> Camera {
        // Look +y axis; voxlap z-down convention. Right-handed:
        // right × down == forward.
        Camera {
            pos,
            right: [-1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        }
    }

    /// Spin up an engine + framebuffers ready for one `render_scene`
    /// pass. `_pool_vsid` is retained for call-site compatibility but
    /// the DDA backend needs no pre-sized scratch pool.
    fn render_setup(_pool_vsid: u32) -> (Engine, Vec<u32>, Vec<f32>) {
        let engine = Engine::new();
        let sky = engine.sky_color();
        let pixel_count = (XRES as usize) * (YRES as usize);
        let framebuffer = vec![sky; pixel_count];
        let zbuffer = vec![0.0f32; pixel_count];
        (engine, framebuffer, zbuffer)
    }

    /// Render `scene` via [`render_scene`] (single-grid no-compose
    /// path) and return the resulting framebuffer.
    fn render_via_scene(scene: &mut Scene, camera: &Camera) -> Vec<u32> {
        let (_engine, mut fb, mut zb) = render_setup(CHUNK_SIZE_XY);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            CpuFog::default(),
            scene,
            camera,
            &settings,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        fb
    }

    /// XS.1 — cross-grid hard shadows: a block in grid **B** casts a sun
    /// shadow onto the floor of grid **A**. Renders the two-grid scene with
    /// the sun shadow-casting vs not; the shadow only exists if the shadow
    /// ray from A's floor crossed into B, so the shadowed render must be
    /// strictly (and non-trivially) darker.
    #[test]
    fn cross_grid_sun_shadow_darkens_other_grid() {
        // Grid A: a wide floor at world z∈[60,62]. Grid B (same origin): a
        // 10-tall block at x∈[50,60]. Sun grazes from +x and above, so B's
        // shadow lands on A's floor at x≈[40,50] — visible to a straight-down
        // camera (B itself occludes only x∈[50,60]).
        let mut scene = Scene::new();
        let a = scene.add_grid(GridTransform::at(DVec3::ZERO));
        scene.grid_mut(a).unwrap().set_rect(
            IVec3::new(30, 30, 60),
            IVec3::new(90, 90, 62),
            Some(VoxColor(0x80_88_88_88)),
        );
        let b = scene.add_grid(GridTransform::at(DVec3::ZERO));
        scene.grid_mut(b).unwrap().set_rect(
            IVec3::new(50, 50, 40),
            IVec3::new(60, 60, 50),
            Some(VoxColor(0x80_60_60_60)),
        );

        // Straight-down camera over the floor (voxlap z-down ⇒ forward +z).
        let cam = Camera {
            pos: [55.0, 55.0, 6.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let inv = 1.0f32 / 2.0f32.sqrt();
        let base = CpuLights {
            enabled: true,
            sun: true,
            sun_dir: [inv, 0.0, -inv], // to-sun: +x and up
            sun_color: [1.0; 3],
            sun_intensity: 1.0,
            ambient: [0.3; 3],
            shadow_strength: 0.85,
            shadow_bias: 1.5,
            shadow_max_dist: 128.0,
            ..CpuLights::default()
        };
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let mut sum_lum = |lights: CpuLights| -> u64 {
            let n = (XRES as usize) * (YRES as usize);
            let mut fb = vec![0u32; n];
            let mut zb = vec![f32::INFINITY; n];
            render_scene_composed_scissored(
                &mut fb,
                &mut zb,
                XRES as usize,
                XRES,
                YRES,
                CpuFog::default(),
                &mut scene,
                &cam,
                &settings,
                0x0011_2233,
                None,
                false,
                None,
                &[],
                lights,
                None,
                &mut SceneRenderScratch::default(),
            );
            fb.iter()
                .map(|&p| u64::from((p & 0xff) + ((p >> 8) & 0xff) + ((p >> 16) & 0xff)))
                .sum()
        };
        let lit = sum_lum(CpuLights {
            sun_casts_shadow: false,
            ..base
        });
        let shadowed = sum_lum(CpuLights {
            sun_casts_shadow: true,
            ..base
        });
        assert!(
            shadowed < lit,
            "B's shadow must darken A's floor: shadowed={shadowed} lit={lit}"
        );
        assert!(
            (lit - shadowed) * 200 > lit,
            "cross-grid shadow should remove >0.5% of total luminance: lit={lit} shadowed={shadowed}"
        );
    }

    #[test]
    fn sc2_sun_shadow_cap_is_world_uniform() {
        // SC.2 finding #1 — `shadow_max_dist` is a WORLD distance. The sun
        // shadow ray marches the grid's VOXEL frame, so the per-grid cap is
        // `shadow_max_dist / vws`: a fine grid (vws<1) then reaches MORE
        // voxels (= the same world distance), a coarse grid fewer. Without
        // this a global cap gives `shadow_max_dist·vws` world reach — a
        // flying vws=0.25 grid would only see occluders within 1/4 the range.
        let world = CpuLights {
            enabled: true,
            sun: true,
            shadow_max_dist: 40.0,
            ..CpuLights::default()
        };
        let mut scratch = Vec::new();
        // vws == 1.0: unchanged (byte-identical to pre-SC).
        let unit = grid_local_lights(&world, &GridTransform::identity(), &mut scratch, None);
        assert!((unit.shadow_max_dist - 40.0).abs() < 1e-3);
        // vws == 0.5 (fine grid): the voxel cap doubles → same 40 world units.
        let fine = grid_local_lights(
            &world,
            &GridTransform::at_scale(DVec3::ZERO, 0.5),
            &mut scratch,
            None,
        );
        assert!(
            (fine.shadow_max_dist - 80.0).abs() < 1e-3,
            "vws=0.5 sun cap must be 40/0.5 = 80 voxels (40 world): got {}",
            fine.shadow_max_dist
        );
        // vws == 4.0 (coarse grid): the voxel cap quarters → same 40 world.
        let coarse = grid_local_lights(
            &world,
            &GridTransform::at_scale(DVec3::ZERO, 4.0),
            &mut scratch,
            None,
        );
        assert!(
            (coarse.shadow_max_dist - 10.0).abs() < 1e-3,
            "vws=4.0 sun cap must be 40/4 = 10 voxels (40 world): got {}",
            coarse.shadow_max_dist
        );
    }

    #[test]
    fn sc2_scaled_grid_casts_world_correct_shadow() {
        // SC.2 — a SCALED occluder grid must drop its shadow at the same WORLD
        // place as the equivalent unscaled block. Grid B at vws 2.0 with a
        // block at local [25,25,20]..[29,29,24] fills world [50,60)×[50,60)×
        // [40,50) — the identical world box the unscaled [50,50,40]..[59,59,49]
        // block fills. Its shadow on A's unscaled floor must MATCH the
        // unscaled reference, not merely darken. Without the occluder-side
        // /vws the world shadow ray (x≈55) would miss B's voxel AABB
        // (x∈[25,30]) entirely → zero shadow (scaled_delta ≈ 0 fails).
        let cam = Camera {
            pos: [55.0, 55.0, 6.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let inv = 1.0f32 / 2.0f32.sqrt();
        let base = CpuLights {
            enabled: true,
            sun: true,
            sun_dir: [inv, 0.0, -inv], // to-sun: +x and up
            sun_color: [1.0; 3],
            sun_intensity: 1.0,
            ambient: [0.3; 3],
            shadow_strength: 0.85,
            shadow_bias: 1.5,
            shadow_max_dist: 128.0,
            ..CpuLights::default()
        };
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);

        // Render A (unscaled floor) + B (block at `b_vws`), return luminance.
        let render_lum = |b_vws: f64, b_lo: IVec3, b_hi: IVec3, casts: bool| -> u64 {
            let mut scene = Scene::new();
            let a = scene.add_grid(GridTransform::at(DVec3::ZERO));
            scene.grid_mut(a).unwrap().set_rect(
                IVec3::new(30, 30, 60),
                IVec3::new(90, 90, 62),
                Some(VoxColor(0x80_88_88_88)),
            );
            let b = scene.add_grid(GridTransform::at_scale(DVec3::ZERO, b_vws));
            scene
                .grid_mut(b)
                .unwrap()
                .set_rect(b_lo, b_hi, Some(VoxColor(0x80_60_60_60)));
            let n = (XRES as usize) * (YRES as usize);
            let mut fb = vec![0u32; n];
            let mut zb = vec![f32::INFINITY; n];
            render_scene_composed_scissored(
                &mut fb,
                &mut zb,
                XRES as usize,
                XRES,
                YRES,
                CpuFog::default(),
                &mut scene,
                &cam,
                &settings,
                0x0011_2233,
                None,
                false,
                None,
                &[],
                CpuLights {
                    sun_casts_shadow: casts,
                    ..base
                },
                None,
                &mut SceneRenderScratch::default(),
            );
            fb.iter()
                .map(|&p| u64::from((p & 0xff) + ((p >> 8) & 0xff) + ((p >> 16) & 0xff)))
                .sum()
        };

        let unscaled_lo = IVec3::new(50, 50, 40);
        let unscaled_hi = IVec3::new(59, 59, 49);
        let scaled_lo = IVec3::new(25, 25, 20);
        let scaled_hi = IVec3::new(29, 29, 24);
        let lit = render_lum(1.0, unscaled_lo, unscaled_hi, false);
        let ref_shadow = render_lum(1.0, unscaled_lo, unscaled_hi, true);
        let scaled_shadow = render_lum(2.0, scaled_lo, scaled_hi, true);

        assert!(ref_shadow < lit, "sanity: the unscaled block must shadow A");
        assert!(
            scaled_shadow < lit,
            "the scaled occluder must cast a shadow — a missing occluder-side \
             /vws makes the world ray miss its voxel AABB: scaled={scaled_shadow} lit={lit}"
        );
        // World-correctness: the scaled block fills the identical world box, so
        // its shadow footprint tracks the unscaled reference (only voxel edge
        // quantization differs). A mis-scaled ray would land elsewhere / miss.
        let ref_delta = lit - ref_shadow;
        let scaled_delta = lit - scaled_shadow;
        assert!(
            scaled_delta * 10 > ref_delta * 7 && scaled_delta * 7 < ref_delta * 10,
            "scaled shadow must match the unscaled world shadow within ~30% \
             (world-placement check): ref_delta={ref_delta} scaled_delta={scaled_delta}"
        );
    }

    // ---- S5.0: world_camera_to_grid_local helper ----

    /// Identity rotation: pos translates by `-origin`; basis is
    /// untouched. This is the byte-identical-to-pre-S5 contract.
    #[test]
    fn world_camera_to_grid_local_identity_rotation_translates_pos_only() {
        let camera = Camera {
            pos: [110.0, 220.0, 330.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };
        let transform = GridTransform::at(DVec3::new(100.0, 200.0, 300.0));
        let local = super::world_camera_to_grid_local(&camera, &transform);
        // Basis must be bit-for-bit unchanged for the identity case.
        assert_eq!(local.right, camera.right);
        assert_eq!(local.down, camera.down);
        assert_eq!(local.forward, camera.forward);
        // Pos translates by `-origin`.
        for (got, want) in local.pos.iter().zip([10.0, 20.0, 30.0].iter()) {
            assert!((got - want).abs() < 1e-12, "pos got={got} want={want}");
        }
    }

    /// 90° rotation about +Z: grid-local `+x` aligns with world `+y`.
    /// World camera at `(0, 10, 0)` looking world `+y` lives in
    /// grid-local at `(10, 0, 0)` looking grid-local `+x`.
    #[test]
    fn world_camera_to_grid_local_90deg_z_rotates_basis_and_pos() {
        use glam::DQuat;
        let camera = Camera {
            pos: [0.0, 10.0, 0.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };
        let transform = GridTransform {
            origin: DVec3::ZERO,
            rotation: DQuat::from_rotation_z(std::f64::consts::FRAC_PI_2),
            voxel_world_size: 1.0,
        };
        let local = super::world_camera_to_grid_local(&camera, &transform);
        // World +y == grid-local +x.
        let approx_eq =
            |a: [f64; 3], b: [f64; 3]| a.iter().zip(b.iter()).all(|(x, y)| (x - y).abs() < 1e-9);
        assert!(
            approx_eq(local.pos, [10.0, 0.0, 0.0]),
            "pos={:?} expected ~(10, 0, 0)",
            local.pos
        );
        // World +x (right) maps to grid-local -y.
        assert!(
            approx_eq(local.right, [0.0, -1.0, 0.0]),
            "right={:?} expected ~(0, -1, 0)",
            local.right
        );
        // World +z (down) is unchanged — it's the rotation axis.
        assert!(
            approx_eq(local.down, [0.0, 0.0, 1.0]),
            "down={:?} expected ~(0, 0, 1)",
            local.down
        );
        // World +y (forward) maps to grid-local +x.
        assert!(
            approx_eq(local.forward, [1.0, 0.0, 0.0]),
            "forward={:?} expected ~(1, 0, 0)",
            local.forward
        );
    }

    /// Basis orthonormality + handedness both survive the
    /// inverse-rotation transform. Property: any unit-quaternion
    /// conjugation preserves the input basis's orthonormality AND
    /// its handedness (rotations are orientation-preserving).
    #[test]
    fn world_camera_to_grid_local_preserves_basis_orthonormality() {
        use glam::DQuat;
        // Right-handed voxlap basis (`right × down == forward`):
        // looking +y, right = -x makes the cross product land on +y.
        let camera = Camera {
            pos: [3.0, -5.0, 7.0],
            right: [-1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };
        let transform = GridTransform {
            origin: DVec3::new(1.0, 2.0, 3.0),
            rotation: DQuat::from_axis_angle(glam::DVec3::new(0.3, 0.8, 0.5).normalize(), 0.7),
            voxel_world_size: 1.0,
        };
        let local = super::world_camera_to_grid_local(&camera, &transform);
        let r = DVec3::from_array(local.right);
        let d = DVec3::from_array(local.down);
        let f = DVec3::from_array(local.forward);
        // Norms ≈ 1.
        for v in [r, d, f] {
            assert!(
                (v.length_squared() - 1.0).abs() < 1e-12,
                "basis vec {v:?} not unit length"
            );
        }
        // Orthogonality.
        assert!(r.dot(d).abs() < 1e-12, "right·down = {}", r.dot(d));
        assert!(r.dot(f).abs() < 1e-12, "right·forward = {}", r.dot(f));
        assert!(d.dot(f).abs() < 1e-12, "down·forward = {}", d.dot(f));
        // Right-handed: right × down == forward (voxlap convention).
        let cross = r.cross(d);
        assert!(
            (cross - f).length() < 1e-12,
            "right×down={cross:?} forward={f:?}"
        );
    }

    // ---- S5.1: rotated-grid render correctness ----

    /// Build a single-grid scene at the given transform with a
    /// marker box near one corner of chunk (0, 0, 0). Returns the
    /// scene and the marker colour. Picking a single chunk + small
    /// box keeps the test compact while still exercising the gline
    /// + grouscan path through the rotated frame.
    fn build_one_grid_marker_scene(transform: GridTransform) -> (Scene, crate::GridId, u32) {
        let mut scene = Scene::new();
        let id = scene.add_grid(transform);
        let grid = scene.grid_mut(id).unwrap();
        // Bright marker box at chunk-local (40..56, 40..56, 40..56).
        grid.set_rect(
            IVec3::new(40, 40, 40),
            IVec3::new(55, 55, 55),
            Some(VoxColor(0x80_55_aa_22)), // distinctive green
        );
        (scene, id, 0x80_55_aa_22)
    }

    /// Pin S5.1's central equivalence: rotating both the grid and the
    /// camera by the SAME rotation around the grid's origin must
    /// leave the rendered framebuffer unchanged — the grid-local
    /// camera pose collapses to the same values in both scenarios.
    ///
    /// We use `DQuat::from_xyzw(0.0, 0.0, 1.0, 0.0)`, the
    /// 180°-around-Z unit quaternion. This rotation acts on vectors
    /// as `(x, y, z) → (-x, -y, z)`, which only multiplies f64
    /// components by 0 or ±1 — bit-exact under glam's standard quat
    /// conjugation formula. Other angles (e.g. 90°) would introduce
    /// sub-1e-15 noise from sin/cos, breaking byte-identity at
    /// chunk / voxel boundaries.
    #[test]
    fn s5_1_180deg_z_rotated_grid_byte_identical_to_axis_aligned() {
        use glam::DQuat;
        // Right-handed voxlap basis (right × down == forward).
        let axis_aligned_camera = Camera {
            pos: [40.0, -20.0, 50.0],
            right: [-1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };
        // R_z(180°): (x, y, z) → (-x, -y, z).
        let rotated_camera = Camera {
            pos: [-40.0, 20.0, 50.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, -1.0, 0.0],
        };
        // Sanity: prove the exact-arithmetic rotation lands on the
        // baseline. If glam ever changes its quat*vec formula in a
        // way that loses exactness here, the next two assertions
        // catch it before the framebuffer comparison.
        let q = DQuat::from_xyzw(0.0, 0.0, 1.0, 0.0);
        let rot_pos = q * DVec3::from_array(axis_aligned_camera.pos);
        let rot_fwd = q * DVec3::from_array(axis_aligned_camera.forward);
        assert_eq!(rot_pos.to_array(), rotated_camera.pos);
        assert_eq!(rot_fwd.to_array(), rotated_camera.forward);

        let (mut scene_a, _, _) = build_one_grid_marker_scene(GridTransform::identity());
        let fb_a = render_via_scene(&mut scene_a, &axis_aligned_camera);

        let (mut scene_b, _, _) = build_one_grid_marker_scene(GridTransform {
            origin: DVec3::ZERO,
            rotation: q,
            voxel_world_size: 1.0,
        });
        let fb_b = render_via_scene(&mut scene_b, &rotated_camera);

        assert_eq!(
            fb_a, fb_b,
            "rotating both grid and camera by R about the grid origin must leave the framebuffer unchanged"
        );
    }

    /// 45° smoke test: rotated grid renders to something non-trivial
    /// without panicking. No equivalence assertion (45° quat math is
    /// approximate at f64 level; that path is exercised structurally,
    /// not bit-exactly). Camera is placed at a fixed world pose where
    /// — under the rotation — the marker box stays inside the view
    /// frustum.
    #[test]
    fn s5_1_45deg_z_rotated_grid_renders_marker() {
        use glam::DQuat;
        let rotation = DQuat::from_rotation_z(std::f64::consts::FRAC_PI_4);
        let (mut scene, _, marker) = build_one_grid_marker_scene(GridTransform {
            origin: DVec3::ZERO,
            rotation,
            voxel_world_size: 1.0,
        });

        // World position of the marker's centre. Grid-local
        // (47.5, 47.5, 47.5) → world `rotation * (47.5, 47.5, 47.5)`.
        // R_z(45°): (47.5, 47.5, 47.5) → (0, 67.18, 47.5) (the x/y
        // components combine into a single +y vector at √2 * 47.5).
        let marker_world = rotation * DVec3::new(47.5, 47.5, 47.5);
        // Camera 80 units south of the marker on the world Y axis,
        // looking +y at the same z. RH basis.
        let camera = Camera {
            pos: [marker_world.x, marker_world.y - 80.0, marker_world.z],
            right: [-1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };

        let (_engine, mut fb, mut zb) = render_setup(CHUNK_SIZE_XY);
        let fog = CpuFog::default();
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let marker_count = fb.iter().filter(|&&p| p == marker).count();
        assert!(
            marker_count > 50,
            "45°-rotated marker box should be visible — got {marker_count} marker pixels"
        );
    }

    // ---- S5.2-followup: per-grid render_sky opt-out ----

    /// Two-grid scene where grid B sits behind grid A along +y;
    /// grid A is opaque only in the centre of the framebuffer, so
    /// the camera's view through grid A is mostly "ray miss". When
    /// `A.render_sky = false`, the pixels around A's silhouette
    /// must remain whatever grid B (or the shared pre-fill)
    /// painted — NOT A's grid-local sky colour. This pins the
    /// sentinel-mask path: without it, A's sky would write into
    /// the composed framebuffer wherever its sky-z happened to win
    /// the min-z race with B's sky-z.
    #[test]
    fn render_sky_false_drops_grid_sky_pixels() {
        use crate::{GridId, GridTransform};

        // Grid B (far, sky owner) — a wide floor of distinct
        // colour spanning chunk-local x/y so most rays land on it.
        let mut scene = Scene::new();
        let _b_id: GridId = scene.add_grid(GridTransform::at(DVec3::new(0.0, 600.0, 0.0)));
        // Find grid B's id (HashMap iteration; we only just added
        // one grid, so its id is whichever the iterator yields).
        let b_id = scene.grids().next().unwrap().0;
        scene.grid_mut(b_id).unwrap().set_rect(
            IVec3::new(0, 0, 100),
            IVec3::new(127, 127, 110),
            Some(VoxColor(0x80_22_88_22)), // green floor
        );

        // Grid A (near, sky disabled) — a SMALL marker box that
        // covers only a fraction of the screen. Most pixels of A's
        // local render are sky.
        let a_id = scene.add_grid(GridTransform::at(DVec3::new(0.0, 200.0, 0.0)));
        scene.grid_mut(a_id).unwrap().set_rect(
            IVec3::new(60, 60, 60),
            IVec3::new(67, 67, 67),
            Some(VoxColor(0x80_aa_22_22)), // red cube
        );
        scene.grid_mut(a_id).unwrap().render_sky = false;

        let unique_sky: u32 = 0xFF_AB_CD_EF;
        let (_engine, fog, _) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![unique_sky; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([64.0, 0.0, 100.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            unique_sky,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 2 });

        // The sentinel must never appear in the composed output —
        // every sentinel pixel must have been masked out before
        // compose. If any leak through, the test catches it.
        let leaked = fb
            .iter()
            .filter(|&&p| p == super::SKY_MASK_SENTINEL)
            .count();
        assert_eq!(
            leaked, 0,
            "SKY_MASK_SENTINEL leaked into composed framebuffer ({leaked} pixels)"
        );
        // Grid A's hit (red cube) must still render — render_sky=false
        // only affects sky pixels, not hits.
        let red_count = fb.iter().filter(|&&p| p == 0x80_aa_22_22).count();
        assert!(
            red_count > 0,
            "red cube from sky-disabled grid A is missing — render_sky=false should only mask sky"
        );
        // Grid B's floor must be visible past grid A's silhouette
        // (the sky-disabled grid doesn't hide B's render).
        let green_count = fb.iter().filter(|&&p| p == 0x80_22_88_22).count();
        assert!(
            green_count > 0,
            "grid B's floor invisible — grid A's masked sky may have overwritten it"
        );
    }

    /// Identity-rotation, single-grid scene with `render_sky = false`
    /// must produce a sentinel-free framebuffer. Sanity test for the
    /// trivial 1-grid case (no second grid to compose against).
    #[test]
    fn render_sky_false_single_grid_no_sentinel_leak() {
        let (mut scene, id, _) = build_one_grid_marker_scene(GridTransform::identity());
        scene.grid_mut(id).unwrap().render_sky = false;
        let unique_sky: u32 = 0xFF_12_34_56;
        let (_engine, fog, _) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![unique_sky; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([64.0, 0.0, 64.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            unique_sky,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let leaked = fb
            .iter()
            .filter(|&&p| p == super::SKY_MASK_SENTINEL)
            .count();
        assert_eq!(leaked, 0, "SKY_MASK_SENTINEL leaked ({leaked} pixels)");
        // Pixels that would have been the grid's sky now show
        // through to the pre-fill (unique_sky).
        let prefill_count = fb.iter().filter(|&&p| p == unique_sky).count();
        assert!(
            prefill_count > 0,
            "no pre-fill pixels survived — render_sky=false should leave non-hit pixels untouched"
        );
    }

    // DDA.9: `render_scene_at_origin_matches_direct_opticast` and
    // `render_scene_translated_grid_matches_grid_local_opticast` were
    // removed — they asserted the scene render byte-matches voxlap
    // `opticast`, which no longer holds now that the scene's CPU backend
    // is the DDA renderer (different, intentionally non-bit-exact). The
    // grid-local camera transform they also exercised is covered by the
    // `stacked_*` / two-grid composition tests below.

    #[test]
    fn empty_scene_returns_empty_outcome() {
        let mut scene = Scene::new();
        let (_engine, mut fb, mut zb) = render_setup(CHUNK_SIZE_XY);
        let fog = CpuFog::default();
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera_at([0.0, 0.0, 0.0]),
            &settings,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Empty);
    }

    // ---- S3.1 / S4.0: render_scene_composed + 2-grid composition ----

    /// Build a 2-grid scene with two distinguishable boxes placed
    /// side-by-side in world space along the camera's right axis.
    /// Each grid holds one chunk (`(0, 0, 0)`) containing a single
    /// 16-voxel box with a uniquely-coloured surface so the
    /// composited framebuffer is partitionable by colour.
    fn build_two_grid_side_by_side() -> (Scene, u32, u32) {
        let mut scene = Scene::new();
        // Grid 0 at world (0, 200, 0): box centred chunk-local (64, 64, 100).
        let g0 = scene.add_grid(GridTransform::at(DVec3::new(0.0, 200.0, 0.0)));
        scene.grid_mut(g0).unwrap().set_rect(
            IVec3::new(56, 56, 92),
            IVec3::new(71, 71, 107),
            Some(VoxColor(0x80_88_22_22)), // dark red
        );
        // Grid 1 at world (200, 200, 0): box centred chunk-local (64, 64, 100).
        let _g1 = scene.add_grid(GridTransform::at(DVec3::new(200.0, 200.0, 0.0)));
        // Borrow-checker dance: re-borrow grid 1 mutably.
        let g1_id = scene
            .grids()
            .filter(|(id, _)| *id != g0)
            .map(|(id, _)| id)
            .next()
            .unwrap();
        scene.grid_mut(g1_id).unwrap().set_rect(
            IVec3::new(56, 56, 92),
            IVec3::new(71, 71, 107),
            Some(VoxColor(0x80_22_22_88)), // dark blue
        );
        (scene, 0x80_88_22_22, 0x80_22_22_88)
    }

    /// Engine + default (off) fog config + sky colour for the
    /// composed-render tests. `_pool_vsid` retained for call-site
    /// compatibility; the DDA backend needs no scratch pool.
    fn make_composed_pool(_pool_vsid: u32) -> (Engine, CpuFog, u32) {
        let engine = Engine::new();
        let sky_color = engine.sky_color();
        (engine, CpuFog::default(), sky_color)
    }

    fn pixel_count(width: u32, height: u32) -> usize {
        (width as usize) * (height as usize)
    }

    #[test]
    fn compose_into_takes_smaller_z() {
        let mut shared_fb = vec![0xff_ff_ff_ff_u32; 4];
        let mut shared_zb = vec![10.0f32; 4];
        let temp_fb = [0xaa_aa_aa_aa, 0x11_22_33_44, 0x55_66_77_88, 0xde_ad_be_ef];
        let temp_zb = [5.0f32, 20.0, 10.0, f32::INFINITY];
        compose_into(&mut shared_fb, &mut shared_zb, &temp_fb, &temp_zb);
        // i=0: 5 < 10 → take temp.
        assert_eq!(shared_fb[0], 0xaa_aa_aa_aa);
        assert_eq!(shared_zb[0], 5.0);
        // i=1: 20 > 10 → keep shared.
        assert_eq!(shared_fb[1], 0xff_ff_ff_ff);
        assert_eq!(shared_zb[1], 10.0);
        // i=2: 10 == 10 → keep shared (`<` not `<=`).
        assert_eq!(shared_fb[2], 0xff_ff_ff_ff);
        // i=3: INFINITY > 10 → keep shared.
        assert_eq!(shared_fb[3], 0xff_ff_ff_ff);
    }

    #[test]
    fn render_scene_composed_two_grids_both_visible() {
        // Camera positioned to see both grids' boxes. Grid 0's box
        // at world (~64, ~264, ~100); grid 1's box at world
        // (~264, ~264, ~100). Camera at world (160, 100, 100)
        // looking +y centres both in view.
        let (mut scene, red, blue) = build_two_grid_side_by_side();
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];

        let camera = camera_at([160.0, 100.0, 100.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 2 });

        // Both colours should appear somewhere in the framebuffer.
        let red_count = fb.iter().filter(|&&p| p == red).count();
        let blue_count = fb.iter().filter(|&&p| p == blue).count();
        assert!(
            red_count > 0,
            "no red pixels: grid 0 (red box) not visible after compose"
        );
        assert!(
            blue_count > 0,
            "no blue pixels: grid 1 (blue box) not visible after compose"
        );
    }

    /// The per-grid screen scissor (vertical band + lateral/vertical
    /// off-screen cull + rect-limited memory passes) must be a pure
    /// speed-up: rendering a multi-grid scene with it on
    /// (`render_scene_composed`) must produce a **byte-identical**
    /// framebuffer to rendering each grid full-frame
    /// (`scissor = false`). Includes a third grid placed off the left
    /// edge but within scan distance, so the lateral cull (scissor on)
    /// vs a sky-only full render (scissor off) must still agree pixel
    /// for pixel.
    #[test]
    fn scissor_render_is_byte_identical_to_full_frame() {
        let (mut scene, red, blue) = build_two_grid_side_by_side();
        // Third grid far to the +x side at the camera's depth: within
        // max_scan_dist (so the distance cull doesn't fire) but its box
        // projects off the left screen edge → screen-culled with the
        // scissor, sky-only when rendered full-frame.
        let g2 = scene.add_grid(GridTransform::at(DVec3::new(700.0, 130.0, 0.0)));
        let g2_id = scene
            .grids()
            .map(|(id, _)| id)
            .max_by_key(|id| id.raw())
            .unwrap();
        let _ = g2;
        scene.grid_mut(g2_id).unwrap().set_rect(
            IVec3::new(56, 56, 92),
            IVec3::new(71, 71, 107),
            Some(VoxColor(0x80_22_88_22)), // green — must never appear (off-screen)
        );

        let camera = camera_at([160.0, 100.0, 100.0]);
        let render = |scene: &mut Scene, scissor: bool| -> Vec<u32> {
            let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
            let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
            let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
            let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
            render_scene_composed_scissored(
                &mut fb,
                &mut zb,
                XRES as usize,
                XRES,
                YRES,
                fog,
                scene,
                &camera,
                &settings,
                sky_color,
                None,
                scissor,
                None,
                &[],
                CpuLights::default(),
                None,
                &mut SceneRenderScratch::default(),
            );
            fb
        };

        let scissored = render(&mut scene, true);
        let full = render(&mut scene, false);
        assert_eq!(
            scissored, full,
            "the screen scissor changed the framebuffer — it must be a pure speed-up",
        );
        // Sanity: the scene actually drew content (not a vacuous all-sky
        // match), and the off-screen green grid never appears.
        assert!(scissored.iter().any(|&p| p == red || p == blue));
        assert!(
            !scissored.contains(&0x80_22_88_22),
            "off-screen grid leaked pixels",
        );
    }

    #[test]
    fn render_scene_composed_grid_a_in_front_of_grid_b() {
        // Two grids stacked along +y so grid A (closer) occludes
        // grid B (farther). After composition only grid A's colour
        // should appear on the overlap.
        let mut scene = Scene::new();
        let g_a = scene.add_grid(GridTransform::at(DVec3::new(0.0, 50.0, 0.0)));
        scene.grid_mut(g_a).unwrap().set_rect(
            IVec3::new(56, 56, 92),
            IVec3::new(71, 71, 107),
            Some(VoxColor(0x80_aa_00_00)), // red
        );
        let _g_b = scene.add_grid(GridTransform::at(DVec3::new(0.0, 200.0, 0.0)));
        let g_b_id = scene
            .grids()
            .filter(|(id, _)| *id != g_a)
            .map(|(id, _)| id)
            .next()
            .unwrap();
        scene.grid_mut(g_b_id).unwrap().set_rect(
            IVec3::new(56, 56, 92),
            IVec3::new(71, 71, 107),
            Some(VoxColor(0x80_00_00_aa)), // blue
        );

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];

        // Camera at (64, -10, 100) looking +y — both boxes line up
        // along the camera's forward axis.
        let camera = camera_at([64.0, -10.0, 100.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 2 });

        // Red (closer grid) should be visible. Blue (farther grid)
        // may peek around the edges but the central pixels should
        // be red where both boxes project.
        let red_count = fb.iter().filter(|&&p| p == 0x80_aa_00_00).count();
        assert!(
            red_count > 0,
            "expected red pixels (closer box should win z-test)"
        );

        // Reverse the registration order (force grid B drawn first)
        // and verify that's irrelevant — composition is commutative.
        let mut scene2 = Scene::new();
        let g_b2 = scene2.add_grid(GridTransform::at(DVec3::new(0.0, 200.0, 0.0)));
        scene2.grid_mut(g_b2).unwrap().set_rect(
            IVec3::new(56, 56, 92),
            IVec3::new(71, 71, 107),
            Some(VoxColor(0x80_00_00_aa)),
        );
        let g_a2 = scene2.add_grid(GridTransform::at(DVec3::new(0.0, 50.0, 0.0)));
        scene2.grid_mut(g_a2).unwrap().set_rect(
            IVec3::new(56, 56, 92),
            IVec3::new(71, 71, 107),
            Some(VoxColor(0x80_aa_00_00)),
        );

        let mut fb2 = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb2 = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let outcome2 = render_scene_composed(
            &mut fb2,
            &mut zb2,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene2,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome2, RenderOutcome::Rendered { grids_drawn: 2 });
        assert_eq!(
            fb, fb2,
            "composition should be order-independent — same scene in different add order should produce identical output"
        );
    }

    #[test]
    fn sc1_scaled_grid_composites_by_world_depth() {
        // SC.1 — two grids at the same origin, boxes on the SAME world
        // column but different scale, so the raw-written and world depth
        // metrics DISAGREE. Camera at y=-10; perpendicular world depth to a
        // box's near face is `world_y_near + 10`:
        //  - grid B (vws 1.0): box world y-near = 92 → written depth 102
        //    (vws==1 so raw == world).
        //  - grid A (vws 2.0): box world y-near = 104 → world depth 114, but
        //    opticast writes `world / vws² = 114 / 4 ≈ 28.5` (the scaled
        //    basis shrinks `dir·forward` by vws²). `scale_depth_rect` then
        //    multiplies by vws² = 4 → 114.
        // Correct (world depth): A (114) is FARTHER than B (102) → the
        // world-nearer BLUE box wins.
        // Broken (no `scale_depth_rect`): A's raw 28.5 < B's 102 → RED wins.
        // (This test only pins the ORDER; `sc1_scaled_grid_depth_is_world`
        // pins the exact vws² factor by asserting the world depth value.)
        let red = 0x80_aa_00_00;
        let blue = 0x80_00_00_aa;
        let mut scene = Scene::new();
        // Grid B, unscaled, nearer in world.
        let b = scene.add_grid(GridTransform::at(DVec3::ZERO));
        scene.grid_mut(b).unwrap().set_rect(
            IVec3::new(56, 92, 92),
            IVec3::new(71, 107, 107),
            Some(VoxColor(blue)),
        );
        // Grid A, vws 2.0, farther in world (local coords = world / 2).
        let a = scene.add_grid(GridTransform::at_scale(DVec3::ZERO, 2.0));
        scene.grid_mut(a).unwrap().set_rect(
            IVec3::new(28, 52, 50),
            IVec3::new(35, 57, 57),
            Some(VoxColor(red)),
        );

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([64.0, -10.0, 100.0]); // looks +y
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 2 });

        let centre = (YRES / 2) as usize * XRES as usize + (XRES / 2) as usize;
        assert_eq!(
            fb[centre], blue,
            "the world-nearer unscaled grid must win the depth test; RED here \
             means the scaled grid's depth wasn't converted to world units"
        );
    }

    #[test]
    fn sc1_scaled_grid_depth_is_world() {
        // SC.1 — render ONLY a scaled grid (vws 2.0) and assert the composited
        // depth buffer holds the WORLD perpendicular depth, pinning the vws²
        // factor exactly (the ordering test above only bounds it below).
        //
        // Box A local y 52..57 → world y-near = 52·2 = 104. Camera at y=-10
        // looks +y, centre ray horizontal, so the world perpendicular depth is
        // 104 - (-10) = 114. opticast writes world/vws² = 114/4 ≈ 28.5;
        // `scale_depth_rect` (×vws²) recovers 114. Wrong factors miss badly:
        // no scale → 28.5, ×vws → 57, ×vws³ → 228. Only ×vws² lands on 114.
        let red = 0x80_aa_00_00;
        let mut scene = Scene::new();
        let a = scene.add_grid(GridTransform::at_scale(DVec3::ZERO, 2.0));
        // Local box centred on the camera column (world x 56..70 → centre 63,
        // world z 100..114 → centre 107) so the centre ray hits the interior.
        scene.grid_mut(a).unwrap().set_rect(
            IVec3::new(28, 52, 50),
            IVec3::new(35, 57, 57),
            Some(VoxColor(red)),
        );

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([63.0, -10.0, 107.0]); // looks +y, hits box A
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });

        let centre = (YRES / 2) as usize * XRES as usize + (XRES / 2) as usize;
        assert_eq!(fb[centre], red, "centre ray should hit the scaled box");
        let depth = zb[centre];
        assert!(
            (depth - 114.0).abs() <= 3.0,
            "expected WORLD perpendicular depth ≈ 114 (pins the vws² factor); \
             got {depth} — 28.5 means no scale, 57 means ×vws, 228 means ×vws³"
        );
    }

    #[test]
    fn sc3_fine_grid_renders_beyond_unscaled_range() {
        // SC.1/SC.3 finding — the ray-terminating scan cutoff is a WORLD
        // distance divided by vws² (opticast writes depth = world/vws²). This
        // is the ONE vws<1 test that exercises the clip the fix removes: a
        // fine grid (vws=0.5) with geometry PAST `max_scan_dist·vws²` but
        // within `max_scan_dist` world. Without the /vws² scale the ray stops
        // at `max_scan_dist·vws²` (25 world here) and the box (world y≈50) is
        // clipped to sky; with it the ray reaches 100 world and the box draws.
        let red = 0x80_aa_00_00;
        let mut scene = Scene::new();
        // vws=0.5: local (·) → world (·)/2. Box near face local y=100 →
        // world y=50; local x/z 28..36 → world 14..18 (centre 16).
        let g = scene.add_grid(GridTransform::at_scale(DVec3::ZERO, 0.5));
        scene.grid_mut(g).unwrap().set_rect(
            IVec3::new(28, 100, 28),
            IVec3::new(36, 110, 36),
            Some(VoxColor(red)),
        );

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        // Camera in world coords, looking +y at the box.
        let camera = camera_at([16.0, 0.0, 16.0]);
        // max_scan_dist = 100 WORLD. Unscaled reach at vws=0.5 would be
        // 100·0.25 = 25 world (box at 50 clipped); scaled reach is 100.
        let mut settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        settings.max_scan_dist = 100;
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let centre = (YRES / 2) as usize * XRES as usize + (XRES / 2) as usize;
        assert_eq!(
            fb[centre], red,
            "fine grid's box at world y≈50 (> max_scan_dist·vws²=25) must \
             render; sky here means the scan cutoff wasn't scaled by vws²"
        );
    }

    // ---- S6.1: Mid-tier mip overrides ----

    /// Build a multi-mip-friendly grid: solid floor spanning the
    /// whole chunk at z=100..254 + `generate_mips(3)`. This is the
    /// same setup `vxl_generate_mips_on_set_voxel_chunk_renders`
    /// uses and is known to render at `mip_levels = 3,
    /// mip_scan_dist = 32`.
    ///
    /// Returns `(scene, grid_id)`. The Mid test sets the camera
    /// inside the chunk so chunk-local rays reach the floor at
    /// short distances; that lets the Mid override use
    /// `mip_scan_dist = 16` without busting the ray budget
    /// (`mip_scan_dist * 2^(mip_levels-1) = 16 * 4 = 64` covers the
    /// distance from camera to floor).
    fn build_mip_visible_grid(world_origin: DVec3) -> (Scene, crate::GridId) {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(world_origin));
        let grid = scene.grid_mut(id).unwrap();
        // Solid floor across the entire chunk at z=100..254.
        grid.set_rect(
            IVec3::new(0, 0, 100),
            IVec3::new(127, 127, 254),
            Some(VoxColor(0x80_88_88_88)),
        );
        // Build the per-chunk mip ladder so `gmipnum` can grow past 1.
        grid.chunk_mut(IVec3::ZERO).unwrap().generate_mips(3);
        (scene, id)
    }

    /// Render `scene` via composed path with `mip_levels = 3,
    /// mip_scan_dist = 32` — same values the working
    /// `vxl_generate_mips_on_set_voxel_chunk_renders` test uses.
    /// Returns the framebuffer.
    fn render_with_multi_mip(scene: &mut Scene, camera: &Camera) -> Vec<u32> {
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let mut settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        settings.mip_levels = 3;
        settings.mip_scan_dist = 32;
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            scene,
            camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        fb
    }

    // DDA.9: `s6_1_mid_overrides_produce_different_framebuffer_than_near`
    // was removed. It encoded voxlap's mip-*transition* semantics
    // (mid_mip_levels=Some(1) caps in-grid mip transitions, differing
    // from Near's mip0→1→2 distance ramp). The DDA renderer uses a
    // *uniform* per-grid mip (no in-grid transition), so Some(1) → mip 0
    // = identical to Near. DDA mip coarsening is covered by
    // `roxlap_core::dda` `mip_render_is_coarse_but_complete`; the LOD-Mid
    // wiring by `s6_1_mid_without_overrides_byte_identical_to_near`.

    /// Mid tier with `mid_mip_levels = None` AND
    /// `mid_mip_scan_dist = None` must produce a byte-identical
    /// framebuffer to Near. This is the graceful-degrade contract
    /// — callers can opt into the Mid plumbing without committing
    /// to a mip override and stay byte-stable.
    #[test]
    fn s6_1_mid_without_overrides_byte_identical_to_near() {
        let camera = camera_at([64.0, 0.0, 64.0]);

        // Scene A: default thresholds → Near.
        let (mut scene_a, _) = build_mip_visible_grid(DVec3::ZERO);
        let fb_near = render_with_multi_mip(&mut scene_a, &camera);

        // Scene B: thresholds force Mid but no mip overrides set.
        let (mut scene_b, b_id) = build_mip_visible_grid(DVec3::ZERO);
        scene_b.grid_mut(b_id).unwrap().lod_thresholds = crate::LodThresholds {
            r_near: 0.0,
            r_mid: f64::INFINITY,
            mid_mip_levels: None,
            mid_mip_scan_dist: None,
        };
        let lod = scene_b
            .grid(b_id)
            .unwrap()
            .select_lod(DVec3::from_array(camera.pos));
        assert_eq!(lod, Lod::Mid);
        let fb_mid = render_with_multi_mip(&mut scene_b, &camera);

        // Byte-identical: Mid with no overrides degrades cleanly.
        assert_eq!(
            fb_near, fb_mid,
            "Mid with both overrides=None must byte-match Near"
        );
    }

    // DDA.9: `s6_1_global_mip_cap_survives_mid_tier` was removed. It
    // pinned voxlap's `mip_levels_override` global cap composing with the
    // Mid override — the ship anti-axis-aligned-beam workaround. The DDA
    // renderer has no axis-aligned mip beam (honest per-cell traversal),
    // so the workaround / global cap is obsolete and the DDA path doesn't
    // consult `mip_levels_override`.

    // ---- S6.3: Far-tier billboard blit ----

    /// Force Far tier via `r_near = 0, r_mid = 0`: any non-zero
    /// camera-to-grid distance lands on `Lod::Far`. Renders a small
    /// grid at world (0, 200, 0) with default-radius thresholds
    /// turned all-Far. The composed framebuffer must contain
    /// non-sky pixels from the impostor blit.
    #[test]
    fn s6_3_far_tier_blits_non_sky_pixels() {
        let (mut scene, id) = build_one_grid_scene(DVec3::new(0.0, 200.0, 0.0));
        scene.grid_mut(id).unwrap().lod_thresholds = crate::LodThresholds {
            r_near: 0.0,
            r_mid: 0.0,
            mid_mip_levels: None,
            mid_mip_scan_dist: None,
        };

        let camera = camera_at([64.0, 0.0, 100.0]);
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });

        // Sanity: picker actually picked Far.
        let lod = scene
            .grid(id)
            .unwrap()
            .select_lod(DVec3::from_array(camera.pos));
        assert_eq!(lod, Lod::Far);

        // Impostor must paint at least some non-sky pixels.
        let non_sky = fb.iter().filter(|&&p| p != sky_color).count();
        assert!(
            non_sky > 0,
            "Far-tier render produced no non-sky pixels — billboard blit not firing"
        );
    }

    /// Lazy populate: cache starts `None`, becomes `Some` after the
    /// first Far render.
    #[test]
    fn s6_3_far_render_lazily_populates_cache() {
        let (mut scene, id) = build_one_grid_scene(DVec3::new(0.0, 200.0, 0.0));
        scene.grid_mut(id).unwrap().lod_thresholds = crate::LodThresholds {
            r_near: 0.0,
            r_mid: 0.0,
            mid_mip_levels: None,
            mid_mip_scan_dist: None,
        };
        assert!(scene.grid(id).unwrap().billboards.is_none());

        let camera = camera_at([64.0, 0.0, 100.0]);
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let _ = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        let cache = scene
            .grid(id)
            .unwrap()
            .billboards
            .as_ref()
            .expect("Far render should have populated billboards");
        assert_eq!(cache.len(), 26);
    }

    /// Edit invalidates the cache; a subsequent Far render rebuilds.
    #[test]
    fn s6_3_edit_invalidates_then_far_render_rebuilds() {
        let (mut scene, id) = build_one_grid_scene(DVec3::new(0.0, 200.0, 0.0));
        scene.grid_mut(id).unwrap().lod_thresholds = crate::LodThresholds {
            r_near: 0.0,
            r_mid: 0.0,
            mid_mip_levels: None,
            mid_mip_scan_dist: None,
        };
        let camera = camera_at([64.0, 0.0, 100.0]);
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);

        // First Far render → cache built.
        let mut fb1 = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb1 = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let _ = render_scene_composed(
            &mut fb1,
            &mut zb1,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert!(scene.grid(id).unwrap().billboards.is_some());

        // Edit invalidates.
        scene
            .grid_mut(id)
            .unwrap()
            .set_voxel(IVec3::new(70, 70, 70), Some(VoxColor(0x80_aa_aa_22)));
        assert!(scene.grid(id).unwrap().billboards.is_none());

        // Second Far render rebuilds.
        let mut fb2 = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb2 = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let _ = render_scene_composed(
            &mut fb2,
            &mut zb2,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert!(scene.grid(id).unwrap().billboards.is_some());
    }

    /// Hybrid scene: one Near grid + one Far grid. Both must render
    /// visibly; the Far grid via blit, the Near grid via opticast.
    /// Sanity check that the two paths cohabit one
    /// `render_scene_composed` call.
    #[test]
    fn s6_3_near_and_far_grids_in_same_scene() {
        let mut scene = Scene::new();
        // Grid A: stays Near (default thresholds). Solid box at
        // world (-30..-20, 190..210, 50..70).
        let a_id = scene.add_grid(GridTransform::at(DVec3::new(-100.0, 200.0, 0.0)));
        scene.grid_mut(a_id).unwrap().set_rect(
            IVec3::new(70, 0, 50),
            IVec3::new(85, 15, 70),
            Some(VoxColor(0x80_22_88_22)), // green
        );
        // Grid B: forced Far. Box at world (~100, 200, 100).
        let b_id = scene.add_grid(GridTransform::at(DVec3::new(100.0, 200.0, 0.0)));
        scene.grid_mut(b_id).unwrap().set_rect(
            IVec3::new(0, 0, 80),
            IVec3::new(20, 20, 110),
            Some(VoxColor(0x80_aa_22_22)), // red
        );
        scene.grid_mut(b_id).unwrap().lod_thresholds = crate::LodThresholds {
            r_near: 0.0,
            r_mid: 0.0,
            mid_mip_levels: None,
            mid_mip_scan_dist: None,
        };

        let camera = camera_at([0.0, 0.0, 80.0]);
        // Confirm A is Near, B is Far for this pose.
        assert_eq!(
            scene
                .grid(a_id)
                .unwrap()
                .select_lod(DVec3::from_array(camera.pos)),
            Lod::Near
        );
        assert_eq!(
            scene
                .grid(b_id)
                .unwrap()
                .select_lod(DVec3::from_array(camera.pos)),
            Lod::Far
        );

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 2 });

        // Each grid should contribute visible pixels.
        let non_sky = fb.iter().filter(|&&p| p != sky_color).count();
        assert!(
            non_sky > 20,
            "hybrid scene produced too few non-sky pixels ({non_sky}); one tier may have failed"
        );
    }

    /// Empty grid at Far tier: skipped silently (no panic, no
    /// allocation), `billboards` stays `None`.
    #[test]
    fn s6_3_empty_grid_at_far_is_skipped() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::new(100.0, 200.0, 0.0)));
        scene.grid_mut(id).unwrap().lod_thresholds = crate::LodThresholds {
            r_near: 0.0,
            r_mid: 0.0,
            mid_mip_levels: None,
            mid_mip_scan_dist: None,
        };

        let camera = camera_at([0.0, 0.0, 100.0]);
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        // No grids contributed.
        assert_eq!(outcome, RenderOutcome::Empty);
        // Cache must NOT have been built for an empty grid.
        assert!(scene.grid(id).unwrap().billboards.is_none());
        // Framebuffer unchanged.
        assert!(fb.iter().all(|&p| p == sky_color));
    }

    // ---- S6.0: LOD picker wired but every tier falls through to Near ----

    /// Threshold-invariance: a grid rendered with the S6 derived
    /// thresholds (`from_radius` of the actual bounding sphere) must
    /// produce a framebuffer byte-identical to the same grid with
    /// default `always_near` thresholds, because S6.0 takes the
    /// `Near` arm of the match for all three tiers. This is the
    /// regression test for the S6.0 contract.
    #[test]
    fn render_scene_composed_lod_threshold_invariance() {
        // Scene A: default thresholds (always_near).
        let (mut scene_a, _a_id) = build_one_grid_scene(DVec3::new(0.0, 200.0, 0.0));
        let cam = camera_at([64.0, 0.0, 100.0]);
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb_a = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb_a = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome_a = render_scene_composed(
            &mut fb_a,
            &mut zb_a,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene_a,
            &cam,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome_a, RenderOutcome::Rendered { grids_drawn: 1 });

        // Scene B: thresholds derived from the grid's bounding
        // radius. At this camera distance the grid lands on Mid or
        // Far; if S6.0 ever stops falling through to Near, this test
        // catches the divergence.
        let (mut scene_b, b_id) = build_one_grid_scene(DVec3::new(0.0, 200.0, 0.0));
        let radius = scene_b.grid(b_id).unwrap().bounding_radius();
        assert!(
            radius > 0.0,
            "bounding_radius should be > 0 for a populated grid"
        );
        scene_b.grid_mut(b_id).unwrap().lod_thresholds = crate::LodThresholds::from_radius(radius);
        // Sanity: the camera is far enough that the picker no longer
        // returns Near (otherwise the invariance test would be vacuous).
        let lod = scene_b
            .grid(b_id)
            .unwrap()
            .select_lod(DVec3::from_array(cam.pos));
        assert_ne!(
            lod,
            Lod::Near,
            "camera should land in Mid or Far for derived thresholds — got {lod:?}",
        );

        let mut fb_b = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb_b = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let outcome_b = render_scene_composed(
            &mut fb_b,
            &mut zb_b,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene_b,
            &cam,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome_b, RenderOutcome::Rendered { grids_drawn: 1 });

        // Byte-identity is the S6.0 contract — Mid/Far still take
        // the Near arm.
        assert_eq!(
            fb_a, fb_b,
            "S6.0 framebuffer must be byte-identical regardless of LOD thresholds"
        );
    }

    #[test]
    fn render_scene_composed_empty_scene_returns_empty() {
        let mut scene = Scene::new();
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([0.0, 0.0, 0.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Empty);
        // fb should be unchanged (still all sky).
        assert!(fb.iter().all(|&p| p == sky_color));
    }

    /// FNV-1a 64-bit hash. Same offset/prime as the
    /// `roxlap-oracle::fnv1a64` helper used by the wasm-render
    /// goldens; pinning a render hash here is the same flavour of
    /// regression catch.
    fn fnv1a64(data: &[u8]) -> u64 {
        let mut h: u64 = 0xcbf2_9ce4_8422_2325;
        for &b in data {
            h ^= u64::from(b);
            h = h.wrapping_mul(0x0000_0100_0000_01b3);
        }
        h
    }

    // ---- S4.0 cross-chunk smoke test ----

    /// Two-chunk-wide grid: a recognisable shape spans the chunk
    /// boundary at `virtual_x = 128`. The render must not have a
    /// horizontal seam line at the boundary.
    #[test]
    fn render_scene_two_chunk_x_grid_no_seam() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::new(0.0, 200.0, 0.0)));
        let g = scene.grid_mut(id).unwrap();
        // 100-voxel-tall stripe spanning x=[120..136] across the
        // x=128 chunk seam at z=200, y=[60..68]. After bake-free
        // render, every column in the stripe paints the same colour
        // at the same z; a seam at x=128 would show as missing
        // pixels in the column at virtual_x=128 / 129 / ...
        g.set_rect(
            IVec3::new(120, 60, 200),
            IVec3::new(136, 67, 215),
            Some(VoxColor(0x80_aa_55_22)),
        );
        // Sanity: ensure both chunks were materialised.
        assert_eq!(g.chunk_count(), 2);

        // Render with a camera positioned to look at the stripe
        // straight on. Stripe at world (120..136, 260..268, 200..215).
        // Camera at (128, 100, 207) looking +y centres on it.
        let (_engine, fog, sky_color) = make_composed_pool(2 * CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([128.0, 100.0, 207.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });

        // Stripe colour should appear in roughly the centre of the
        // framebuffer. A chunk-edge seam would manifest as a thin
        // sky-coloured vertical line splitting the stripe in two.
        let stripe = 0x80_aa_55_22;
        let stripe_count = fb.iter().filter(|&&p| p == stripe).count();
        assert!(
            stripe_count > 200,
            "stripe rendered too few pixels ({stripe_count}) — chunks may not be stitching"
        );

        // Walk the centre row left-to-right looking for a sky-pixel
        // gap inside a stripe run. A gap 1+ pixels wide flags a
        // chunk-edge seam.
        let centre_y = (YRES / 2) as usize;
        let row_start = centre_y * (XRES as usize);
        let row = &fb[row_start..row_start + (XRES as usize)];
        let mut in_stripe = false;
        let mut seam_gaps = 0usize;
        for &px in row {
            if px == stripe {
                in_stripe = true;
            } else if in_stripe && px == sky_color {
                // Stripe ended; if we re-enter it on this row that's
                // a seam.
                if row.iter().skip_while(|&&p| p != px).any(|&p| p == stripe) {
                    // Look ahead for any further stripe pixel.
                    seam_gaps += 1;
                }
                in_stripe = false;
            }
        }
        // We allow seam_gaps to count the legitimate "stripe ended,
        // didn't restart" transition once; more than that means
        // multiple disjoint runs on the row → seam.
        assert!(
            seam_gaps <= 1,
            "centre row has {seam_gaps} disjoint stripe runs — expected 1 (chunk-edge seam suspected)"
        );
    }

    // DDA.9: the voxlap-era mip regression tests here
    // (`vxl_generate_mips_on_set_voxel_chunk_renders` + the byte-exact
    // 2-chunk opticast pin) were removed — they drove voxlap `opticast` +
    // `ScalarRasterizer` directly, a path no longer reachable from this
    // consumer crate. The DDA mip ladder + multi-mip render is covered by
    // `render_with_mips_present_still_renders_mip0` and the
    // `stacked_*_multi_mip` tests below.

    /// Mip-0 preservation when mips are generated on the combined
    /// view but `mip_levels = 1` in the rasterizer's settings.
    /// Confirms `generate_mips` only APPENDS data — mip-0
    /// prefix is unchanged.
    #[test]
    fn render_with_mips_present_still_renders_mip0() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        scene.grid_mut(id).unwrap().set_rect(
            IVec3::new(40, 40, 40),
            IVec3::new(55, 55, 55),
            Some(VoxColor(0x80_88_88_88)),
        );
        // S4B.4.a: force mip-1..mip-2 generation on the single
        // chunk directly (the Grid's combined-view cache API was
        // removed). The chunk's own Vxl::generate_mips builds its
        // own mip tables and the renderer happens to render through
        // them via Approach B's chunk_at_xy lookup.
        {
            let grid = scene.grid_mut(id).unwrap();
            let chunk = grid.chunks.get_mut(&IVec3::ZERO).unwrap();
            chunk.generate_mips(3);
        }

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([64.0, 0.0, 64.0]);
        // mip_scan_dist huge → renderer never transitions past mip-0
        // so this test pins mip-0 correctness only.
        let mut settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        settings.mip_scan_dist = 100_000;
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let non_sky = fb.iter().filter(|&&p| p != sky_color).count();
        assert!(
            non_sky > 0,
            "render of single-grid scene with mips present rendered all-sky: mip-0 may be corrupted by generate_mips"
        );
    }

    #[test]
    fn render_scene_two_chunk_x_grid_hash_is_stable() {
        // Frozen 2026-05-10 at S4.0 landing on x86_64.
        // DDA.9: re-frozen to the DDA renderer's output (was the
        // voxlap-opticast golden 0x215e_d66d_7359_4725).
        const GOLDEN: u64 = 0x492e_c4bb_718f_d7e5;
        // Same scene shape as `render_scene_two_chunk_x_grid_no_seam`
        // — kept distinct so the hash assertion doesn't share its
        // setup with the structural seam check.
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::new(0.0, 200.0, 0.0)));
        scene.grid_mut(id).unwrap().set_rect(
            IVec3::new(120, 60, 200),
            IVec3::new(136, 67, 215),
            Some(VoxColor(0x80_aa_55_22)),
        );
        let (_engine, fog, sky_color) = make_composed_pool(2 * CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([128.0, 100.0, 207.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });

        let bytes: Vec<u8> = fb.iter().flat_map(|p| p.to_ne_bytes()).collect();
        let hash = fnv1a64(&bytes);
        if GOLDEN == SENTINEL {
            // First-run capture mode — print the hash so the
            // developer can paste it into GOLDEN above.
            eprintln!("render_scene_two_chunk_x_grid_hash_is_stable: capture hash = 0x{hash:016x}");
            panic!("GOLDEN is the SENTINEL placeholder — paste 0x{hash:016x} into GOLDEN above");
        }
        assert_eq!(
            hash, GOLDEN,
            "2-chunk render hash drifted: expected 0x{GOLDEN:016x}, got 0x{hash:016x}"
        );
    }

    /// Sentinel for first-run hash capture in
    /// [`render_scene_two_chunk_x_grid_hash_is_stable`]. Replace
    /// `GOLDEN`'s definition with the printed value once captured.
    const SENTINEL: u64 = 0xDEAD_BEEF_DEAD_BEEF;

    /// S4B.6.c: stacked-grid scaffold — camera in chz=1 (= world
    /// z=256..511) of a 2-chunk-tall grid should render its own
    /// chunk's terrain. Verifies cf seed + slab-byte reads + chunk-
    /// XY swaps all use world-z consistently.
    ///
    /// Cross-chunk look-down (= camera in chz=0 sees terrain in
    /// chz=1) needs cf z range extension at air-gap-lookup time;
    /// that's a follow-up to S4B.6.c.
    #[test]
    fn stacked_two_chunk_z_camera_in_chz1_sees_own_chunk_floor() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        // chz=0: all-air (materialised so chunk_xyz_backing enumerates).
        g.ensure_chunk(IVec3::new(0, 0, 0));
        // chz=1: floor at local z=50 (= world z=306).
        g.set_rect(
            IVec3::new(60, 60, 306),
            IVec3::new(72, 72, 310),
            Some(VoxColor(0x80_33_66_99)),
        );
        assert!(g.chunk(IVec3::new(0, 0, 1)).is_some());

        let (_engine, fog, sky_color) = make_composed_pool(2 * CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        // Camera at world (66, 66, 280) — directly above the
        // floor at world z=306. Look STRAIGHT DOWN (z increases =
        // down in voxlap z-down).
        let camera = Camera {
            pos: [66.0, 66.0, 280.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let floor_count = fb.iter().filter(|&&p| p == 0x80_33_66_99).count();
        assert!(
            floor_count > 100,
            "camera at chz=1 with floor in same chunk should see it — got {floor_count} floor pixels"
        );
    }

    /// S4B.6.e: cross-chunk look-down. Camera in chz=0's all-air
    /// chunk should see chz=1's floor below it. This was deferred
    /// from S4B.6.c because the cf seed's z range capped at the
    /// camera-chunk's bedrock (world z=255); S4B.6.e extends the
    /// air-gap walk in `camera_chunk_air_gap` to step into the
    /// next chunk down when the camera's column is all-air-bedrock,
    /// and the rasterizer routes state.column / slab_buf to the
    /// chunk holding the real floor via `seed_chunk_z`.
    #[test]
    fn stacked_two_chunk_z_camera_in_chz0_sees_chz1_floor() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        // chz=0: all-air. Materialised so chunk_xyz_backing
        // enumerates it.
        g.ensure_chunk(IVec3::new(0, 0, 0));
        // chz=1: floor at world z=306..310 (= local z=50..54).
        g.set_rect(
            IVec3::new(60, 60, 306),
            IVec3::new(72, 72, 310),
            Some(VoxColor(0x80_77_aa_44)),
        );
        assert!(g.chunk(IVec3::new(0, 0, 1)).is_some());

        let (_engine, fog, sky_color) = make_composed_pool(2 * CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        // Camera at world (66, 66, 100) — in chz=0's all-air
        // chunk. Look STRAIGHT DOWN (z+) toward chz=1's floor at
        // world z=306.
        let camera = Camera {
            pos: [66.0, 66.0, 100.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let floor_count = fb.iter().filter(|&&p| p == 0x80_77_aa_44).count();
        assert!(
            floor_count > 50,
            "camera in chz=0 air-gap should see chz=1 floor via cross-chunk look-down — got {floor_count} floor pixels"
        );
    }

    /// S4B.6.l KNOWN LIMITATION → RESOLVED by VC.5 (2026-05-31).
    /// Camera at chz=0 with all-air-bedrock at the camera's own
    /// XY column (seed_chz=1 via cross-chunk look-down). A DIFFERENT
    /// XY column has chz=0 content (= a distant mountain entirely
    /// inside chz=0). Pre-VC.5 the chunk-XY swap read chz=1 chunks
    /// across the DDA, so the chz=0 mountain was invisible. VC.5's
    /// multi-chz column-step install stitches every chz layer at the
    /// new XY column; the chz=0 mountain renders correctly.
    ///
    /// VC.0 pin (2026-05-31): re-enabled (was `#[ignore]`'d). VC.5
    /// flipped it from failing (mountain_chz0 = 0) to passing.
    #[test]
    fn stacked_chz0_distant_mountain_visible_from_chz0_camera() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        // chz=0 mountain at a column DISTANT from the camera —
        // entirely in chz=0 (world z=100..200), so chz=1 at the
        // same XY is all-air-bedrock.
        g.set_rect(
            IVec3::new(100, 100, 100),
            IVec3::new(124, 124, 200),
            Some(VoxColor(0x80_aa_55_22)), // distinct brown
        );
        // chz=1 hills filling the floor at world z=336..360 across
        // the chunk EXCEPT a hole around the mountain XY (so the
        // mountain doesn't sit on a green tower).
        g.set_rect(
            IVec3::new(0, 0, 336),
            IVec3::new(128, 128, 360),
            Some(VoxColor(0x80_22_88_44)),
        );
        g.set_rect(IVec3::new(100, 100, 336), IVec3::new(124, 124, 360), None);
        // Materialise chz=0 + chz=1 (chz=0 has the mountain; chz=1
        // has the hills).
        assert!(g.chunk(IVec3::new(0, 0, 0)).is_some());
        assert!(g.chunk(IVec3::new(0, 0, 1)).is_some());

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        // Camera at (40, 40, 60) — chz=0 air, FAR from the mountain
        // XY (100..124, 100..124). Yaw=π/4 (look toward +x+y =
        // mountain direction), pitch=0.72 rad (≈ 41° down) so the
        // ray bisecting the screen aims at the chz=0 mountain centre
        // ≈ (112, 112, 150).
        let camera = Camera::from_yaw_pitch([40.0, 40.0, 60.0], std::f64::consts::FRAC_PI_4, 0.72);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let mountain_count = fb.iter().filter(|&&p| p == 0x80_aa_55_22).count();
        let hill_count = fb.iter().filter(|&&p| p == 0x80_22_88_44).count();
        eprintln!("chz0-distant-mountain: mountain_chz0={mountain_count} hill_chz1={hill_count}");
        // chz=1 hills are reachable via seed-time cross-chunk
        // look-down.
        assert!(
            hill_count > 50,
            "expected chz=1 hills via cross-chunk look-down — got {hill_count}"
        );
        // The proper-fix assertion: chz=0 distant mountain SHOULD be
        // visible. Currently fails — pins the limitation.
        assert!(
            mountain_count > 50,
            "expected chz=0 distant mountain visible — got {mountain_count} (S4B.6.l limitation)"
        );
    }

    /// S4B.6.h: mid-render chunk-Z handoff. Camera column has
    /// content in chz=0 (= a mountain at the camera's XY) so
    /// seed-time cross-chunk look-down does NOT fire — seed_chz=0.
    /// As rays DDA across the scene, they visit XY columns where
    /// chz=0 is all-air-bedrock. Mid-render handoff should swap
    /// state to chz=1's column at those XY positions and reveal
    /// hill content sitting under the camera's chz=0 layer.
    ///
    /// This is the "tall mountains breaching chunk-Z boundary"
    /// case the demo aims for.
    #[test]
    fn mid_render_handoff_reveals_chz1_hills_under_mountain_camera() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        // chz=0: a small "mountain peak" at the camera's XY.
        // Mountain at world z=150..200 — solid block.
        g.set_rect(
            IVec3::new(60, 60, 150),
            IVec3::new(72, 72, 200),
            Some(VoxColor(0x80_88_44_22)), // brown mountain
        );
        // chz=1: hills at world z=336..360 across the WHOLE chunk
        // (so DDA rays hit them when chz=0 is air).
        g.set_rect(
            IVec3::new(0, 0, 336),
            IVec3::new(128, 128, 360),
            Some(VoxColor(0x80_22_88_44)), // green hills
        );
        // Carve a hole in chz=1's hill at the mountain's footprint
        // so the mountain doesn't appear to "float" on green.
        g.set_rect(IVec3::new(60, 60, 336), IVec3::new(72, 72, 360), None);
        assert!(g.chunk(IVec3::new(0, 0, 0)).is_some());
        assert!(g.chunk(IVec3::new(0, 0, 1)).is_some());

        let (_engine, fog, sky_color) = make_composed_pool(2 * CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        // Camera at world (66, 66, 100) — directly above the
        // mountain peak (at z=150). Camera column has the
        // mountain in chz=0. Look straight down.
        let camera = Camera {
            pos: [66.0, 66.0, 100.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let mountain_count = fb.iter().filter(|&&p| p == 0x80_88_44_22).count();
        let hill_count = fb.iter().filter(|&&p| p == 0x80_22_88_44).count();
        // Verify the hills render at approximately the correct
        // world-z by sampling the z-buffer at hill pixels. Camera
        // at z=100 looking straight down; hills at world z=336.
        // Expected depth = 236 for directly-below pixels. If
        // state.z1 stays stuck at the mountain peak's z=150 the
        // hills would render with depth ≈ 50 → orders of magnitude
        // off.
        let mut hill_depths: Vec<f32> = fb
            .iter()
            .zip(zb.iter())
            .filter_map(|(&p, &d)| if p == 0x80_22_88_44 { Some(d) } else { None })
            .collect();
        hill_depths.sort_by(|a, b| a.partial_cmp(b).unwrap());
        let median_hill_depth = hill_depths[hill_depths.len() / 2];
        eprintln!(
            "mid-render handoff: mountain={mountain_count} hill={hill_count} median_hill_depth={median_hill_depth:.1}"
        );
        assert!(
            mountain_count > 50,
            "should see mountain peak via chz=0 — got {mountain_count} mountain pixels"
        );
        assert!(
            hill_count > 50,
            "should see chz=1 hills via mid-render handoff — got {hill_count} hill pixels"
        );
        assert!(
            (median_hill_depth - 236.0).abs() < 80.0,
            "hill median depth should be ≈236 (camera→z=336); got {median_hill_depth:.1} — state.z1 may be stale at the mountain peak's z"
        );
    }

    /// S4B.6.g: cross-chunk look-down under multi-mip. Same scene
    /// as `stacked_two_chunk_z_camera_in_chz0_sees_chz1_floor` but
    /// with `mip_levels=2, mip_scan_dist=16` so the rasterizer
    /// transitions to mip-1 well within the chz=1 terrain. Locks in
    /// the slab_z_at mip-N offset fix (= `chunk_world_z_base >>
    /// gmipcnt`). Pre-fix produced a green / brown "wall in a circle
    /// around the camera" because mip-1 rendered the floor at
    /// world-z ≈ 178 instead of 306.
    #[test]
    fn stacked_two_chunk_z_camera_in_chz0_sees_chz1_floor_multi_mip() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        g.ensure_chunk(IVec3::new(0, 0, 0));
        g.set_rect(
            IVec3::new(60, 60, 306),
            IVec3::new(72, 72, 310),
            Some(VoxColor(0x80_77_aa_44)),
        );
        assert!(g.chunk(IVec3::new(0, 0, 1)).is_some());

        let (_engine, fog, sky_color) = make_composed_pool(2 * CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = Camera {
            pos: [66.0, 66.0, 100.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let mut settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        settings.mip_levels = 2;
        settings.mip_scan_dist = 16;
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let floor_count = fb.iter().filter(|&&p| p == 0x80_77_aa_44).count();
        assert!(
            floor_count > 50,
            "multi-mip cross-chunk look-down should still see chz=1 floor — got {floor_count} floor pixels"
        );
    }

    /// S4B.6.d: 3-chunk-tall stack stresses the widened gylookup
    /// (`(chunks_z * 512) >> mip + 4` per mip). Pre-S4B.6.d, gylookup
    /// was hardcoded at `(512 >> mip) + 4`, which would OOB or alias
    /// for any z > 511. This test renders a floor at world z=562
    /// (= chz=2, local z=50) with the camera at world z=540, looking
    /// straight down. Multi-mip is on so we exercise the mip slide
    /// path in `phase_remiporend` that scales `advance` by chunks_z.
    #[test]
    fn stacked_three_chunk_z_camera_in_chz2_sees_own_chunk_floor_multi_mip() {
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        // Materialise chz=0 + chz=1 so chunk_xyz_backing enumerates
        // the full stack.
        g.ensure_chunk(IVec3::new(0, 0, 0));
        g.ensure_chunk(IVec3::new(0, 0, 1));
        // chz=2: floor at world z=562..566 (= local z=50..54).
        g.set_rect(
            IVec3::new(60, 60, 562),
            IVec3::new(72, 72, 566),
            Some(VoxColor(0x80_aa_55_22)),
        );
        assert!(g.chunk(IVec3::new(0, 0, 2)).is_some());

        let (_engine, fog, sky_color) = make_composed_pool(2 * CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = Camera {
            pos: [66.0, 66.0, 540.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        // Multi-mip on to exercise the gylookup-slide path.
        let mut settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        settings.mip_levels = 2;
        settings.mip_scan_dist = 16;
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let floor_count = fb.iter().filter(|&&p| p == 0x80_aa_55_22).count();
        assert!(
            floor_count > 100,
            "camera at chz=2 with floor in same chunk should see it — got {floor_count} floor pixels"
        );
    }

    // ---- S7.4: render integration with streaming ----

    /// Floor-stamping generator for S7.4 render tests. Produces a
    /// 10-voxel-thick floor at the bottom of every chunk it
    /// generates (chunk-local `z = 230..239`, all xy). Visible as
    /// a green stripe along the bottom of the framebuffer when
    /// the camera looks +y across populated chunks.
    #[derive(Debug)]
    struct FloorGenerator;

    impl crate::ChunkGenerator for FloorGenerator {
        fn generate(&self, _chunk_idx: IVec3) -> roxlap_formats::vxl::Vxl {
            // Lean on `Grid::ensure_chunk` for the empty-chunk
            // builder, then carve a floor via `set_rect`. Detach
            // the chunk from the temporary grid and return it.
            let mut tmp = crate::Grid::new(GridTransform::identity());
            tmp.ensure_chunk(IVec3::ZERO);
            let mut vxl = tmp.chunks.remove(&IVec3::ZERO).unwrap();
            #[allow(clippy::cast_possible_wrap)]
            roxlap_formats::edit::set_rect(
                &mut vxl,
                glam::IVec3::new(0, 0, 230).into(),
                glam::IVec3::new((CHUNK_SIZE_XY - 1) as i32, (CHUNK_SIZE_XY - 1) as i32, 239)
                    .into(),
                Some(VoxColor(0x80_22_aa_22)),
            );
            vxl
        }
    }

    #[test]
    fn render_scene_composed_unpumped_streaming_grid_renders_all_sky() {
        // S7.4(a): a grid with a generator + active stream radius
        // but no pump_streaming call has zero chunks. The render
        // walks the grid (chunk_xyz_backing returns None for an
        // empty chunk map → grid is skipped), framebuffer stays
        // sky.
        use std::sync::Arc;
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        g.set_generator(Some(Arc::new(FloorGenerator)));
        g.stream_radius = crate::StreamRadius::new(300.0, 600.0);
        assert!(g.chunks.is_empty(), "no pump yet → no chunks");

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        // Camera at (64, -100, 200) looking +y so it would see
        // chunks ahead once they exist.
        let camera = camera_at([64.0, -100.0, 200.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let _ = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        // Empty grid path skips opticast → framebuffer untouched.
        assert!(
            fb.iter().all(|&p| p == sky_color),
            "unpumped streaming grid must render as all sky"
        );
    }

    #[test]
    fn render_scene_composed_picks_up_streamed_chunks_after_sync_pump() {
        // S7.4(a): once the streaming pump installs chunks, the
        // next render shows them. Using pump_streaming_sync for
        // deterministic timing — pump_streaming (async) lands
        // the same way modulo a frame of latency.
        use std::sync::Arc;
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        g.set_generator(Some(Arc::new(FloorGenerator)));
        // Cover chunks ahead of the camera (y=0, y=128, y=256).
        g.stream_radius = crate::StreamRadius::new(300.0, 600.0);

        // Render BEFORE pump: zero floor pixels.
        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        let camera = camera_at([64.0, -100.0, 200.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let _ = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        let pre_floor = fb.iter().filter(|&&p| p == 0x80_22_aa_22).count();
        assert_eq!(pre_floor, 0, "pre-pump frame has no streamed chunks");

        // Pump synchronously — `world_pos` matches the camera so
        // chunks ahead of it (within r_active = 300) stream in.
        scene.pump_streaming_sync(DVec3::new(64.0, -100.0, 200.0));
        let g = scene.grid(id).unwrap();
        assert!(
            !g.chunks.is_empty(),
            "pump should have streamed at least one chunk"
        );

        // Render AFTER pump: the floor should now be visible. Reset
        // the framebuffer to sky first.
        fb.iter_mut().for_each(|p| *p = sky_color);
        zb.iter_mut().for_each(|z| *z = f32::INFINITY);
        let outcome = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        assert_eq!(outcome, RenderOutcome::Rendered { grids_drawn: 1 });
        let post_floor = fb.iter().filter(|&&p| p == 0x80_22_aa_22).count();
        assert!(
            post_floor > 100,
            "post-pump frame should show the streamed floor — got {post_floor} green pixels"
        );
    }

    #[test]
    fn render_scene_composed_partial_streaming_renders_pending_chunks_as_air() {
        // S7.4(a): mixed state — some r_active chunks are
        // materialised, others are still pending (not in
        // `chunks`). The render must treat pending chunks as
        // implicit-air. Verified by stamping one chunk via the
        // generator + skipping the others, then confirming the
        // framebuffer has fewer floor pixels than the
        // fully-pumped baseline.
        use std::sync::Arc;
        let mut scene = Scene::new();
        let id = scene.add_grid(GridTransform::at(DVec3::ZERO));
        let g = scene.grid_mut(id).unwrap();
        g.set_generator(Some(Arc::new(FloorGenerator)));
        // r_active must be set so the later pump_streaming_sync
        // sanity-check actually streams more chunks in.
        g.stream_radius = crate::StreamRadius::new(400.0, 800.0);

        // Materialise ONLY chunk (0, 0, 0) manually via the
        // sync helper — leave (0, 1, 0), (0, 2, 0) absent.
        let installed = g.ensure_chunk_generated(IVec3::ZERO);
        assert!(installed, "manual install of one chunk");
        assert_eq!(g.chunks.len(), 1);
        // Make sure (0, 1, 0), (0, 2, 0) are NOT present.
        assert!(g.chunk(IVec3::new(0, 1, 0)).is_none());
        assert!(g.chunk(IVec3::new(0, 2, 0)).is_none());

        let (_engine, fog, sky_color) = make_composed_pool(CHUNK_SIZE_XY);
        let mut fb = vec![sky_color; pixel_count(XRES, YRES)];
        let mut zb = vec![f32::INFINITY; pixel_count(XRES, YRES)];
        // Camera inside chunk (0, 0, 0); looking +y means the
        // floor of (0, 0, 0) gets rendered until the ray walks
        // off the chunk into implicit-air space at y=128. No
        // floor pixels past that distance.
        let camera = camera_at([64.0, 32.0, 200.0]);
        let settings = OpticastSettings::for_oracle_framebuffer(XRES, YRES);
        let _ = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        let floor_pixels = fb.iter().filter(|&&p| p == 0x80_22_aa_22).count();
        // Visible floor inside chunk (0,0,0); pending neighbours
        // contribute nothing. The number isn't pinned exactly —
        // it just needs to be non-zero (we have content) and
        // less than what a fully-streamed scene would produce.
        assert!(
            floor_pixels > 0,
            "should see at least some floor from the loaded chunk"
        );
        // Sanity: stream the missing chunks; verify the floor
        // pixel count goes up.
        scene.pump_streaming_sync(DVec3::new(64.0, 32.0, 200.0));
        assert!(scene.grid(id).unwrap().chunk_count() >= 2);
        fb.iter_mut().for_each(|p| *p = sky_color);
        zb.iter_mut().for_each(|z| *z = f32::INFINITY);
        let _ = render_scene_composed(
            &mut fb,
            &mut zb,
            XRES as usize,
            XRES,
            YRES,
            fog,
            &mut scene,
            &camera,
            &settings,
            sky_color,
            None,
        );
        let floor_pixels_full = fb.iter().filter(|&&p| p == 0x80_22_aa_22).count();
        assert!(
            floor_pixels_full > floor_pixels,
            "fully-streamed scene should show more floor than partial: \
             partial={floor_pixels} full={floor_pixels_full}"
        );
    }
}