roxlap_core/

dda.rs

//! Per-pixel 3D-DDA + brickmap CPU renderer (Substage DDA).
//!
//! This is the clean-room replacement for the voxlap-derived
//! column-coherent opticast pipeline (`opticast` + `grouscan` +
//! `scan_loops`). Every pixel casts one independent ray, so none of
//! the column/row-coherence stitching artifacts of the 2.5D voxlap
//! renderer can occur (silhouette notch, floor hairlines, axis-aligned
//! mip beams, cross-chunk virtual-column complexity). See
//! `PORTING-DDA.md` for the full stage plan.
//!
//! **Stage status — DDA.6 (per-grid distance mip) + DDA.7 (tile
//! parallelism).** Each pixel casts one ray over the grid's full voxel
//! box ([`GridView::voxel_bounds`], spanning every chunk in XY **and**
//! Z) via a 3D-DDA (Amanatides–Woo). A uniform render mip (chosen per
//! grid by LOD distance, clamped by [`effective_mip`] to a level every
//! chunk has built) coarsens the cell size to `2^mip` mip-0 voxels and
//! samples mip-`mip` data — the ray stays in mip-0 units so depth and
//! fog are exact. `BrickMaps` (one occupancy map per populated chunk,
//! at the render mip) are built once per frame and shared immutably; a
//! `Sampler` resolves each cell to its chunk
//! ([`GridView::chunk_at_xyz`]) and brick-gates the
//! [`GridView::surface_color_mip`] slab walk, caching the current chunk
//! so air costs an O(1) bit test. [`render_dda_parallel`] splits the
//! frame into disjoint rayon bands — bit-identical to sequential since
//! pixels are independent. Hits are shaded by baked brightness
//! (`shade`) + [`DdaEnv::side_shades`] face tint, fogged toward
//! [`DdaEnv::fog_color`] (`apply_fog`); misses sample the
//! [`DdaEnv::sky`] panorama (`sample_sky`) or keep the solid pre-fill.
//!
//! Buffer conventions match the rest of the engine so this backend is
//! colour is packed `0x80RRGGBB`; depth is perpendicular distance from
//! the camera with **smaller = closer** (so the scene compositor's
//! min-z merge works directly on the z-buffer this writes).

use std::collections::HashMap;

use rayon::prelude::*;

use crate::camera_math::{self, CameraState};
use crate::grid_view::GridView;
use crate::opticast::OpticastSettings;
use crate::raster_target::RasterTarget;
use crate::sky::Sky;
use crate::Camera;
use roxlap_formats::material::{material_for_color, Material, MaterialTable};
use roxlap_formats::Rgb;

/// Per-frame environment for DDA shading (Substage DDA.5): a textured
/// sky panorama, distance fog, and per-face side shading.
///
/// [`DdaEnv::default`] disables all three — flat baked-brightness hits
/// and a caller-pre-filled solid sky — so the brickmap/dense equivalence
/// tests run against an unchanged pipeline.
#[derive(Clone, Copy)]
pub struct DdaEnv<'a> {
    /// Textured sky sampled per-ray-direction on a miss. `None` leaves
    /// the destination untouched (caller's solid sky pre-fill shows).
    pub sky: Option<&'a Sky>,
    /// Fog target colour (`0x__RRGGBB`); hits blend toward it with
    /// distance. Typically the sky colour so terrain fades into the sky.
    pub fog_color: u32,
    /// Depth at which fog is fully opaque. `<= 0` disables fog.
    pub fog_max_dist: f32,
    /// Per-face brightness reduction `[x-, x+, y-, y+, z-, z+]`, applied
    /// to the hit face (voxlap `setsideshades`). All-zero = off.
    pub side_shades: [i8; 6],
    /// TV: global voxel-material palette (id → opacity + blend mode). `None`
    /// keeps terrain fully opaque (the first-hit path, bit-identical).
    pub materials: Option<&'a MaterialTable>,
    /// TV: terrain colour→material map (`(rgb, material_id)`). A hit voxel's
    /// colour is looked up here for its material. **Empty** (the default) ⇒
    /// every voxel is opaque, so the march returns the first hit unchanged.
    pub terrain_materials: &'a [(Rgb, u8)],
    /// CPU.1 — dynamic lighting (stage DL on the CPU): sun + point lights +
    /// stylized cel/ramp, evaluated flat per voxel. Disabled by default ⇒ the
    /// hit uses the baked-byte `shade` path, byte-identical to pre-DL. Lights
    /// here are already in the grid's **local** frame (the scene renderer
    /// transforms them per grid). Shadows: see [`Self::world_shadow`].
    pub lights: CpuLights<'a>,
    /// XS.1 — when set, shadow rays test the **whole scene** (all grids +
    /// sprites) via this world-space occluder + the current grid's
    /// local→world transform, instead of the single-grid `SamplerShadow`.
    /// `None` ⇒ single-grid shadows (the direct `render_dda` path / tests).
    pub world_shadow: Option<WorldShadowCtx<'a>>,
    /// CA.0 — per-grid cutaway clip (stage CA), grid-local **absolute**
    /// voxel z (the same space as [`GridView::voxel_bounds`], spanning
    /// stacked chz chunks; z-down). `Some(z)` makes the renderer treat
    /// every cell with `z < z_clip` as air — the isometric "deck view"
    /// cut; `z_clip` itself is the first visible layer, whose top face
    /// renders as the cut surface (colour = the existing
    /// [`GridView::surface_color_mip`] run-top fallback). Render-only:
    /// simulation / collision / audio are untouched. `None` (the
    /// default) disables clipping — byte-identical to pre-CA renders.
    pub z_clip: Option<i32>,
    /// OC.0 — per-grid derived view cutout (stage OC): the screen-space
    /// "keyhole" through front walls for third-person play. Unlike
    /// [`Self::z_clip`] (grid state, "world as if removed") this is
    /// transient per-frame VIEW state: primary rays only — shadow
    /// marches, occluders, collision and gameplay raycasts never see
    /// it. `None` (the default) is byte-identical to pre-OC renders.
    pub cutout: Option<CpuCutout>,
    /// FW.2 — per-hit fog-of-war styling (stage FW). When set, each
    /// solid hit is classified by grid-local voxel into a
    /// [`FowVerdict`]: `Hide` cells read as air (the observer never saw
    /// them — the marcher continues, like [`Self::cutout`]); `Show`
    /// cells are dimmed / desaturated and may suppress the dynamic-light
    /// rig (memory renders the frozen BAKED look). Applied to the
    /// fog-of-war *twin* grid only (the scene renderer sets it per grid).
    /// `None` (the default) is byte-identical to pre-FW renders. See
    /// [`FowStyler`].
    pub fow: Option<&'a dyn FowStyler>,
}

/// FW.2 — how one hit cell is shown, from its fog-of-war state.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum FowVerdict {
    /// The observer never saw this cell — treat it as air (the marcher
    /// continues past it, so within-chunk unseen geometry the twin
    /// copied for a neighbour cell stays hidden).
    Hide,
    /// The observer knows this cell — shade and show it.
    Show {
        /// Whether the dynamic-light rig runs. `false` = the frozen
        /// BAKED look only (memory / heard: a live torch must not
        /// relight a remembered room).
        dynamic: bool,
        /// Brightness multiplier `0..=1` (the smooth FOV-edge / memory
        /// taper). `1.0` = full.
        dim: f32,
        /// Desaturation `0..=1`, lerp of RGB toward luma (cold memory).
        /// `0.0` = full colour.
        desaturate: f32,
    },
}

impl FowVerdict {
    /// `Show { dynamic: true, dim: 1, desaturate: 0 }` — a fully-visible
    /// cell rendered exactly as with no fog (the byte-identity anchor).
    pub const LIVE: Self = Self::Show {
        dynamic: true,
        dim: 1.0,
        desaturate: 0.0,
    };
}

/// FW.2 — per-cell fog-of-war classifier the DDA consults at each hit.
/// Implemented in `roxlap-scene` over a `FogOfWar` mask + the render
/// styling; kept as a trait here so `roxlap-core` needs no dependency
/// on the scene graph (mirrors how [`CpuLights`] borrows scene-built
/// data). Called once per resolved hit (mip-0 grid-local voxel coords).
///
/// `Send + Sync`: the per-tile DDA render fans out over rayon, so the
/// borrowed styler is shared across worker threads (read-only).
pub trait FowStyler: Send + Sync {
    /// Verdict for a hit at grid-local **mip-0** voxel `(x, y, z)`.
    fn verdict(&self, x: i32, y: i32, z: i32) -> FowVerdict;
}

/// FW.2 — apply a [`FowVerdict::Show`]'s dim + desaturate to a shaded
/// ARGB colour (high byte preserved). Identity when `dim == 1` and
/// `desaturate == 0`, so a fully-visible cell is bit-exact.
#[must_use]
pub fn fow_style(color: u32, dim: f32, desaturate: f32) -> u32 {
    if dim == 1.0 && desaturate == 0.0 {
        return color;
    }
    let hi = color & 0xff00_0000;
    let r = ((color >> 16) & 0xff) as f32;
    let g = ((color >> 8) & 0xff) as f32;
    let b = (color & 0xff) as f32;
    let luma = 0.299 * r + 0.587 * g + 0.114 * b;
    let mix = |c: f32| ((c + (luma - c) * desaturate) * dim).clamp(0.0, 255.0) as u32;
    hi | (mix(r) << 16) | (mix(g) << 8) | mix(b)
}

/// OC.0 — the view cutout as one grid's render pass consumes it, fully
/// derived by the facade each frame (stage OC; see
/// `FrameParams::view_cutout` in `roxlap-render`). A cell is hidden
/// iff ALL of: its CENTRE lies inside the view cone around the
/// eye→focus axis (the cone tapers across the feather band), its
/// eye distance is under the nearest character-column point's minus
/// [`margin`](Self::margin), and its grid-local z is above the focus
/// plane (`z < focus_z`, z-down) — walls between the camera and the
/// focus cut, the floor in front of the focus stays.
///
/// **Per-CELL, not per-pixel** (the OC.3 visual-pass round-2
/// redesign): the original rule gated each RAY by a screen-space
/// window, so a cell straddling the window edge rendered for the
/// outside pixels only — sub-cell fragments that read as ragged teeth
/// wherever the boundary crossed a floor or wall at a shallow angle.
/// Classifying whole cells by their centres makes the cut edge
/// cube-granular and spatially coherent, exactly like the CA clip's
/// edges.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct CpuCutout {
    /// The focus point in this grid's local frame, **voxel units**
    /// (the same space the ray origin lives in).
    pub focus_local: [f32; 3],
    /// Tangent of the cone's OUTER half-angle (nothing is cut outside
    /// it). The facade derives it from the keyhole's pixel radius and
    /// the frame's focal length (`radius_px / hz`), so it still means
    /// "a screen circle of ~radius_px around the projected focus".
    pub tan_outer: f32,
    /// Tangent of the full-reveal INNER half-angle
    /// (`(radius − feather)/hz`): between the two the reveal distance
    /// tapers linearly to zero, closing the keyhole into a smooth
    /// funnel. `== tan_outer` gives a hard edge.
    pub tan_inner: f32,
    /// How far short of the character COLUMN the reveal stops, in this
    /// grid's **voxel units** (world units `/vws`). The reveal surface
    /// hugs the column — the vertical segment at the focus xy between
    /// the focus plane ([`Self::focus_z`], the feet) and its mirror
    /// above the focus (the head): a cell is hidden while its eye
    /// distance is under the eye distance of the NEAREST column point
    /// at the cell's own height, minus this margin. A fixed
    /// eye-distance sphere through the focus (the previous rule) kept
    /// waist-down stumps of any obstacle the character stood right
    /// behind — below-chest cells in front sit FARTHER from an
    /// elevated eye than the chest itself.
    pub margin: f32,
    /// Grid-local **absolute** voxel z of the focus plane (mip-0,
    /// z-down, spanning stacked chz chunks — the same space as
    /// [`Self::z_clip`](DdaEnv::z_clip)); cells with `z < focus_z`
    /// qualify for hiding. At mip N the compare uses `focus_z >> mip`
    /// (arithmetic shift = floor), the CA.1 formula. This is the
    /// FIRST, cheap gate in the hit branch: `i32::MIN`-like sentinels
    /// keep the disabled cost at one never-true compare.
    pub focus_z: i32,
}

/// CPU.1 — one point light in a grid's local frame for the CPU renderer.
#[derive(Clone, Copy)]
pub struct CpuPointLight {
    /// Grid-local position (world/voxel units).
    pub pos: [f32; 3],
    /// Linear RGB, 0..1.
    pub color: [f32; 3],
    /// Scalar multiplier on `color` — the light's contribution is
    /// `albedo · color · intensity · N·L · falloff` per channel.
    /// `1.0` is nominal; values above it over-drive (the sum clamps at
    /// pack time).
    pub intensity: f32,
    /// Hard cutoff distance (world/voxel units).
    pub radius: f32,
    /// CPU.2 — whether this light casts a hard shadow (a shadow ray
    /// marches to the light through the grid's voxels). Mirrors the
    /// GPU's per-light `casts_shadow`; the renderer applies the same
    /// caster cap before building the CPU rig.
    pub casts_shadow: bool,
    /// SL — spot (cone) axis: grid-local unit direction the light shines
    /// **along**. Ignored for a pure point light (see [`Self::cos_outer`]).
    pub spot_dir: [f32; 3],
    /// SL — cosine of the inner cone half-angle (full brightness within it).
    pub cos_inner: f32,
    /// SL — cosine of the outer cone half-angle (zero past it; soft
    /// `smoothstep` between the two). `-1.0` (a 180° cone) ⇒ a pure point
    /// light: the cone mask is skipped entirely and the light is omnidirectional.
    pub cos_outer: f32,
}

/// CPU.1 — the per-frame dynamic-light environment for one grid (grid-local).
/// Mirror of the GPU `shade_lit` inputs. `enabled == false` (the default)
/// keeps the baked-byte path. CPU.2 adds hard voxel shadows (sun + flagged
/// point lights) via a per-(voxel,face) shadow march; `shadow_strength == 0`
/// (the [`Default`]) leaves the lighting diffuse-only.
#[derive(Clone, Copy, Default)]
pub struct CpuLights<'a> {
    /// Whether dynamic lighting is active this frame (else the baked path).
    pub enabled: bool,
    /// Whether the sun is present.
    pub sun: bool,
    /// Grid-local unit direction **to** the sun.
    pub sun_dir: [f32; 3],
    /// Sun colour, linear RGB 0..1.
    pub sun_color: [f32; 3],
    /// Scalar multiplier on `sun_color` (the sun term is
    /// `albedo · sun_color · sun_intensity · key`). `1.0` is nominal.
    pub sun_intensity: f32,
    /// CPU.2 — whether the sun casts a hard shadow.
    pub sun_casts_shadow: bool,
    /// Grid-local point lights.
    pub points: &'a [CpuPointLight],
    /// Ambient multiplier on the baked byte (smooth mode's fill).
    pub ambient: [f32; 3],
    /// Cel band count: 0 = smooth, ≥1 = quantize + gradient-map (stylized).
    pub bands: u32,
    /// Stylized ramp's cool unlit-end tint (used when `bands > 0`).
    pub shadow_tint: [f32; 3],
    /// CPU.2 — fraction of a caster's light removed where a shadow ray is
    /// occluded (`0` ⇒ shadows off, `1` ⇒ full black). A shadowed sample
    /// keeps `1 - shadow_strength` of that caster.
    pub shadow_strength: f32,
    /// CPU.2 — shadow-ray origin bias along the surface normal, voxel
    /// units (kills self-shadow acne). ~1.5 is a good default.
    pub shadow_bias: f32,
    /// CPU.2 — sun shadow-ray length cap, voxel units (point-light rays
    /// stop at the light instead).
    pub shadow_max_dist: f32,
}

impl Default for DdaEnv<'_> {
    fn default() -> Self {
        Self {
            sky: None,
            fog_color: 0,
            fog_max_dist: 0.0,
            side_shades: [0; 6],
            materials: None,
            terrain_materials: &[],
            lights: CpuLights::default(),
            world_shadow: None,
            z_clip: None,
            cutout: None,
            fow: None,
        }
    }
}

/// Per-pixel output target for the DDA renderer.
///
/// Abstracts "where does a ray hit go" so the traversal core stays
/// free of framebuffer mechanics. The production impl is
/// [`RasterSink`] (raw fb/zb pointers); tests use a recording sink.
/// Only *hits* are reported — misses (sky) leave the destination
/// untouched, matching the caller-pre-fills-sky convention.
pub trait PixelSink {
    /// Record a ray hit at framebuffer index `idx` (`py * pitch + px`)
    /// with packed ARGB `color` and perpendicular `dist` (smaller =
    /// closer).
    fn put(&mut self, idx: usize, color: u32, dist: f32);
}

/// [`PixelSink`] over a borrowed `(framebuffer, zbuffer)` pair.
///
/// Wraps a [`RasterTarget`] so the DDA path writes through the same
/// raw-pointer mechanism the scalar rasterizer uses — which keeps the
/// door open for the same strip/tile-disjoint parallel writes in
/// DDA.7.
pub struct RasterSink<'a> {
    target: RasterTarget<'a>,
    len: usize,
}

impl<'a> RasterSink<'a> {
    /// Build a sink from exclusive framebuffer + zbuffer borrows.
    /// Both slices must have the same length (the pixel count).
    #[must_use]
    pub fn new(framebuffer: &'a mut [u32], zbuffer: &'a mut [f32]) -> Self {
        debug_assert_eq!(framebuffer.len(), zbuffer.len());
        let len = framebuffer.len();
        Self {
            target: RasterTarget::new(framebuffer, zbuffer),
            len,
        }
    }
}

impl PixelSink for RasterSink<'_> {
    fn put(&mut self, idx: usize, color: u32, dist: f32) {
        if idx < self.len {
            // SAFETY: bounds checked above; single-threaded writer in
            // DDA.0 so the disjoint-write invariant holds trivially.
            unsafe {
                self.target.write_color(idx, color);
                self.target.write_depth(idx, dist);
            }
        }
    }
}

/// A resolved ray hit: surface colour + perpendicular distance.
#[derive(Debug, Clone, Copy)]
struct Hit {
    color: u32,
    dist: f32,
}

/// Test-only per-thread traversal counters for the perf bench.
#[cfg(test)]
pub(crate) mod prof {
    use std::cell::Cell;
    thread_local! {
        pub static CELLS: Cell<u64> = const { Cell::new(0) };
        pub static BRICKS: Cell<u64> = const { Cell::new(0) };
        pub static SURF: Cell<u64> = const { Cell::new(0) };
    }
    pub fn reset() {
        CELLS.with(|x| x.set(0));
        BRICKS.with(|x| x.set(0));
        SURF.with(|x| x.set(0));
    }
    pub fn read() -> (u64, u64, u64) {
        (
            CELLS.with(Cell::get),
            BRICKS.with(Cell::get),
            SURF.with(Cell::get),
        )
    }
}

/// Apply the voxel's baked directional brightness (Substage DDA.5).
///
/// Voxlap (and the GPU marcher, `grid_dda.wgsl`) store per-voxel
/// brightness in the colour's high byte on a `0..128` scale — `0x80`
/// is full brightness — written by `Grid::bake_lightmode` (estnorm
/// directional shading). The shaded channel is `c · a / 128`, so the
/// DDA matches the GPU look; an unbaked / full-bright voxel (`a =
/// 0x80`) passes through unchanged. Output alpha is normalised to
/// `0x80` (the standard "lit" flag; the present blit ignores it).
///
/// The renderer only *reads* the baked byte — it computes no normals
/// itself, so per-impact relight is free (re-bake the chunk and the
/// byte updates). The estnorm bake that produces the byte is the
/// voxlap-derived piece slated for a clean-room rewrite in DDA.10.
///
/// `bright_sub` is the per-face `side_shades` reduction (DDA.5): voxlap
/// subtracts it from the brightness byte before the multiply, so a
/// shaded face is uniformly darker. `0` = no side shading.
#[inline]
pub(crate) fn shade(color: u32, bright_sub: u32) -> u32 {
    let a = ((color >> 24) & 0xff).saturating_sub(bright_sub);
    let ch = |shift: u32| -> u32 { ((((color >> shift) & 0xff) * a) >> 7).min(255) };
    0x8000_0000 | (ch(16) << 16) | (ch(8) << 8) | ch(0)
}

/// EV.1 — shade an **emissive** voxel: the baked brightness byte, the
/// per-face side shade and the dynamic rig are all ignored; the albedo
/// is scaled by `(128 + (emissive >> 1)) / 128` on the same `>> 7`
/// fixed-point ladder as [`shade`] — ~1.0× at `emissive = 0..=1` up to
/// ~2.0× over-bright (channel-clamped) at `255`. Fog is applied by the
/// caller as for any other hit.
#[inline]
pub(crate) fn emissive_shade(color: u32, emissive: u8) -> u32 {
    let a = 128 + u32::from(emissive >> 1);
    let ch = |shift: u32| -> u32 { ((((color >> shift) & 0xff) * a) >> 7).min(255) };
    0x8000_0000 | (ch(16) << 16) | (ch(8) << 8) | ch(0)
}

// CPU.1 — cel quantization: snap a 0..1 factor to `bands + 1` levels.
#[inline]
fn cel_band(x: f32, bands: u32) -> f32 {
    let b = bands as f32;
    ((x * b).round() / b).clamp(0.0, 1.0)
}

// CPU.1 — point-light distance falloff (mirror of the GPU's): smooth
// quadratic from 1 at the light to 0 at `radius`, hard-cut beyond.
#[inline]
fn point_falloff(d: f32, radius: f32) -> f32 {
    let x = (1.0 - d / radius).clamp(0.0, 1.0);
    x * x
}

// SL — Hermite `smoothstep` (mirror of WGSL's), with a defined hard-edge case:
// when `edge0 == edge1` WGSL is undefined, so we step at the shared threshold.
#[inline]
fn smoothstep_scalar(edge0: f32, edge1: f32, x: f32) -> f32 {
    if edge1 <= edge0 {
        return if x < edge0 { 0.0 } else { 1.0 };
    }
    let t = ((x - edge0) / (edge1 - edge0)).clamp(0.0, 1.0);
    t * t * (3.0 - 2.0 * t)
}

// SL — spot (cone) angular mask (mirror of the shaders' `spot_cone`). `ldir` is
// the unit direction from the surface TO the light; `axis` the cone axis (the
// way the light shines). Returns 1.0 for a pure point light (`cos_outer <=
// -0.999`, the 180° degenerate); else a soft `smoothstep` from 0 at the outer
// half-angle to 1 at the inner (hard step when the two coincide).
#[inline]
fn spot_cone(ldir: [f32; 3], axis: [f32; 3], cos_inner: f32, cos_outer: f32) -> f32 {
    if cos_outer <= -0.999 {
        return 1.0;
    }
    let cd = -dot3(ldir, axis);
    smoothstep_scalar(cos_outer, cos_inner, cd)
}

// CPU.1 — face normal (grid-local) from the crossed axis + step: points back
// toward the incoming ray. `axis == 3` (entry voxel, no face) falls back to up
// (-z, voxlap z-down).
#[inline]
fn face_normal_cpu(axis: usize, step: [i32; 3]) -> [f32; 3] {
    let mut n = [0.0f32; 3];
    if axis < 3 {
        n[axis] = -(step[axis] as f32);
    } else {
        n[2] = -1.0;
    }
    n
}

#[inline]
fn dot3(a: [f32; 3], b: [f32; 3]) -> f32 {
    a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
}

/// CPU.2 — a hard-shadow occlusion test for the dynamic-lighting shade.
/// `occluded(origin, dir, max_t)` returns `true` if a solid voxel blocks
/// the segment from `origin` (grid-local, already biased off the surface)
/// in unit direction `dir` within `max_t` voxel units. Terrain hits pass
/// a [`SamplerShadow`] (marches the current grid only) or a
/// [`WorldShadow`] (cross-grid + sprites, XS.1/XS.2); sprites that don't
/// cast/receive shadows pass `None`.
pub(crate) trait ShadowTester {
    fn occluded(&mut self, origin: [f32; 3], dir: [f32; 3], max_t: f32) -> bool;
}

/// XS.1 — a **world-space** occlusion oracle over the whole scene (all grids,
/// and sprites in XS.2). Implemented in `roxlap-scene` (it needs the grid /
/// sprite stores); the CPU DDA reaches it through [`DdaEnv::world_shadow`] so
/// shadow rays cross grid + object boundaries instead of stopping at the
/// current grid. `occluded_world(origin, dir, max_t)` is in **world** voxel
/// units: `true` iff any solid voxel anywhere blocks the segment.
///
/// SC.2 — `origin` is **f64**: a scaled scene puts a fine grid's voxels at
/// large world coordinates, and each occluder re-projects the ray into its
/// own voxel frame (dividing by that grid's `vws`), so the world origin must
/// keep full precision through the lift. `dir` stays f32 (a unit-ish
/// direction); implementations narrow to f32 only at their voxel-frame entry.
///
/// `Sync` because [`DdaEnv`] (which borrows it) is shared across the
/// rayon strip workers in [`render_dda_parallel`]; the occluder is a
/// read-only borrow of the scene, so this holds.
pub trait WorldOccluder: Sync {
    /// `true` iff any solid voxel in the scene blocks the segment from
    /// world-space `origin` (f64) in unit direction `dir` within `max_t`
    /// world voxel units.
    fn occluded_world(&self, origin: [f64; 3], dir: [f32; 3], max_t: f32) -> bool;
}

/// XS.1 — per-grid context for a cross-scene shadow query: the scene-wide
/// [`WorldOccluder`] plus the **current grid's** local→world transform, so a
/// grid-local shadow ray (the frame `shade_dynamic` works in) can be lifted
/// to world space before the scene-wide test. `cols[i]` is the world-space
/// image of grid-local axis `i` (the grid rotation's columns); `origin` is the
/// grid's world origin.
#[derive(Clone, Copy)]
pub struct WorldShadowCtx<'a> {
    /// The scene-wide occlusion oracle every lifted shadow ray is
    /// tested against.
    pub occluder: &'a dyn WorldOccluder,
    /// The current grid's world-space origin — the translation part of
    /// its local→world transform (added to rotated positions;
    /// directions skip it). SC.2 — **f64**: kept full-precision so a
    /// scaled grid's large world coordinates survive the lift (see
    /// [`WorldOccluder`]).
    pub origin: [f64; 3],
    /// Columns of the grid's local→world rotation: `cols[i]` is the
    /// world-space image of grid-local axis `i`. Kept **orthonormal** (pure
    /// rotation) — the grid's voxel scale rides in `voxel_world_size`, not
    /// folded into the columns.
    pub cols: [[f32; 3]; 3],
    /// SC.2 — the caster grid's `voxel_world_size` (world units per voxel).
    /// The shade works in the grid's voxel frame, so lifting a shadow ray to
    /// world scales the local **position** and **direction** by this (a
    /// voxel offset becomes `vws` world units). `1.0` for an unscaled grid
    /// (byte-identical to XS.1) and for already-world-space sprites.
    pub voxel_world_size: f32,
}

impl<'a> WorldShadowCtx<'a> {
    /// Identity transform — for shading already in world space (sprites): the
    /// grid-local ray IS the world ray.
    #[must_use]
    pub fn identity(occluder: &'a dyn WorldOccluder) -> Self {
        Self {
            occluder,
            origin: [0.0; 3],
            cols: [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
            voxel_world_size: 1.0,
        }
    }
}

/// XS.2 — a [`WorldOccluder`] that ORs two others (e.g. the grid occluder +
/// the sprite occluder), so a single shadow query covers both. `true` if
/// either blocks the ray.
pub struct CompositeOccluder<'a> {
    /// First occluder — queried first (short-circuits `b` on a hit).
    pub a: &'a dyn WorldOccluder,
    /// Second occluder — queried only when `a` reports no hit.
    pub b: &'a dyn WorldOccluder,
}

impl WorldOccluder for CompositeOccluder<'_> {
    fn occluded_world(&self, origin: [f64; 3], dir: [f32; 3], max_t: f32) -> bool {
        self.a.occluded_world(origin, dir, max_t) || self.b.occluded_world(origin, dir, max_t)
    }
}

/// XS.1 — [`ShadowTester`] that lifts a grid-local shadow ray to world space
/// (via [`WorldShadowCtx`]) and queries the scene-wide [`WorldOccluder`], so
/// occlusion crosses grid + sprite boundaries. Sprites (already world-space)
/// use an identity [`WorldShadowCtx`] (see [`WorldShadowCtx::identity`]).
pub(crate) struct WorldShadow<'a> {
    pub ctx: WorldShadowCtx<'a>,
}

impl ShadowTester for WorldShadow<'_> {
    fn occluded(&mut self, origin: [f32; 3], dir: [f32; 3], max_t: f32) -> bool {
        let c = &self.ctx.cols;
        // SC.2 — the shade works in the caster grid's VOXEL frame. Lift to
        // world: a voxel offset becomes `vws` world units, so the local
        // position scales by vws before rotate+translate, and the ray
        // direction scales by vws too (the world segment then covers
        // `t · vws` world units — `max_t` is a caster-voxel distance). The
        // occluder side divides back out by its own vws, so a grid shadowing
        // ITSELF is scale-invariant and vws==1.0 is byte-identical to XS.1.
        let s = self.ctx.voxel_world_size;
        let l = [origin[0] * s, origin[1] * s, origin[2] * s];
        // world = grid_origin + R · (local · vws) (R columns = `cols`). The
        // rotated-local term is small (voxel offset), so it's summed in f32;
        // the large `origin` stays f64 so `wo` keeps full world precision.
        let wo = [
            self.ctx.origin[0] + f64::from(c[0][0] * l[0] + c[1][0] * l[1] + c[2][0] * l[2]),
            self.ctx.origin[1] + f64::from(c[0][1] * l[0] + c[1][1] * l[1] + c[2][1] * l[2]),
            self.ctx.origin[2] + f64::from(c[0][2] * l[0] + c[1][2] * l[1] + c[2][2] * l[2]),
        ];
        // dir rotates then scales by vws (skips the origin translation).
        let wd = [
            (c[0][0] * dir[0] + c[1][0] * dir[1] + c[2][0] * dir[2]) * s,
            (c[0][1] * dir[0] + c[1][1] * dir[1] + c[2][1] * dir[2]) * s,
            (c[0][2] * dir[0] + c[1][2] * dir[1] + c[2][2] * dir[2]) * s,
        ];
        self.ctx.occluder.occluded_world(wo, wd, max_t)
    }
}

/// CPU.1 — dynamic-lighting shade for a terrain voxel (the CPU mirror of the
/// GPU `shade_lit`): raw albedo × (ambient/AO + sun + point lights), evaluated
/// **flat per voxel** (at the voxel centre, so a whole face reads one tone —
/// the retro look). `bands > 0` quantizes (cel) and gradient-maps the sun key
/// from `shadow_tint` (cool) to the sun colour (warm). **No shadows.** Returns
/// a packed `0x80RRGGBB` colour (same convention as [`shade`]).
fn shade_lit_cpu(
    color: u32,
    bright_sub: u32,
    axis: usize,
    step: [i32; 3],
    cellc: [i32; 3],
    cell_size: f32,
    l: &CpuLights<'_>,
    shadow: Option<&mut dyn ShadowTester>,
) -> u32 {
    let a_b = ((color >> 24) & 0xff).saturating_sub(bright_sub);
    let ao = a_b as f32 / 128.0;
    let albedo = [
        ((color >> 16) & 0xff) as f32 / 255.0,
        ((color >> 8) & 0xff) as f32 / 255.0,
        (color & 0xff) as f32 / 255.0,
    ];
    let n = face_normal_cpu(axis, step);
    // Voxel centre (grid-local) — flat per-voxel sample point.
    let center = [
        (cellc[0] as f32 + 0.5) * cell_size,
        (cellc[1] as f32 + 0.5) * cell_size,
        (cellc[2] as f32 + 0.5) * cell_size,
    ];
    shade_dynamic(albedo, ao, n, center, l, shadow)
}

/// CPU.1/DL.7 — the shared dynamic-lighting core (terrain + sprites): raw
/// `albedo` × (ambient/AO + sun + point lights), sampled **flat per voxel**
/// at `sample` with surface normal `n`. `bands > 0` quantizes (cel) and
/// gradient-maps the sun key from `shadow_tint` (cool) to the sun colour
/// (warm). **No shadows** (GPU-only). Returns a packed `0x80RRGGBB` colour.
pub(crate) fn shade_dynamic(
    albedo: [f32; 3],
    ao: f32,
    n: [f32; 3],
    sample: [f32; 3],
    l: &CpuLights<'_>,
    shadow: Option<&mut dyn ShadowTester>,
) -> u32 {
    let styled = l.bands > 0;
    // CPU.2 — shadow ray origin: bias off the surface along the normal to
    // avoid self-shadow acne (shared by every caster). Light kept in
    // shadow = `1 - shadow_strength` (1.0 ⇒ shadows effectively off).
    let mut shadow = shadow;
    let shadow_origin = [
        sample[0] + n[0] * l.shadow_bias,
        sample[1] + n[1] * l.shadow_bias,
        sample[2] + n[2] * l.shadow_bias,
    ];
    let in_shadow = 1.0 - l.shadow_strength;

    // Sun key (0..1): N·L × shadow factor.
    let sun_key = if l.sun {
        let ndl = dot3(n, l.sun_dir).max(0.0);
        if ndl > 0.0 && l.sun_casts_shadow {
            let occ = shadow
                .as_deref_mut()
                .is_some_and(|s| s.occluded(shadow_origin, l.sun_dir, l.shadow_max_dist));
            if occ {
                ndl * in_shadow
            } else {
                ndl
            }
        } else {
            ndl
        }
    } else {
        0.0
    };

    // Base term: ambient + sun. Smooth = additive; stylized = gradient map.
    let mut lit = if styled {
        let key = cel_band(sun_key, l.bands);
        let m = |i: usize| {
            let warm = l.sun_color[i] * l.sun_intensity;
            (l.shadow_tint[i] + (warm - l.shadow_tint[i]) * key) * ao
        };
        [albedo[0] * m(0), albedo[1] * m(1), albedo[2] * m(2)]
    } else {
        let base = |i: usize| {
            albedo[i] * l.ambient[i] * ao + albedo[i] * l.sun_color[i] * l.sun_intensity * sun_key
        };
        [base(0), base(1), base(2)]
    };

    // Point lights (flat per voxel). CPU.2 — a flagged caster's shadow ray
    // marches to the light; an occluded sample keeps `in_shadow` of it.
    for p in l.points {
        let d3 = [
            p.pos[0] - sample[0],
            p.pos[1] - sample[1],
            p.pos[2] - sample[2],
        ];
        // PF.7 (C4) — squared-distance reject first: the sqrt only runs
        // for lights actually within radius (same thresholds squared).
        let d2 = d3[0] * d3[0] + d3[1] * d3[1] + d3[2] * d3[2];
        if d2 < p.radius * p.radius && d2 > 1e-8 {
            let dist = d2.sqrt();
            let inv = 1.0 / dist;
            let ldir = [d3[0] * inv, d3[1] * inv, d3[2] * inv];
            let ndl = dot3(n, ldir).max(0.0);
            // SL — spot cone mask (1.0 for a pure point light). Computed
            // before the shadow march so an off-cone spot skips it entirely.
            let cone = spot_cone(ldir, p.spot_dir, p.cos_inner, p.cos_outer);
            if ndl > 0.0 && cone > 0.0 {
                // Shadow ray marches from the surface to the light (`dist`).
                let sh = if p.casts_shadow
                    && shadow
                        .as_deref_mut()
                        .is_some_and(|s| s.occluded(shadow_origin, ldir, dist))
                {
                    in_shadow
                } else {
                    1.0
                };
                let mut f = ndl * point_falloff(dist, p.radius) * cone * sh;
                if styled {
                    f = cel_band(f, l.bands);
                }
                for i in 0..3 {
                    lit[i] += albedo[i] * p.color[i] * p.intensity * f;
                }
            }
        }
    }

    let pack = |v: f32| -> u32 { (v.clamp(0.0, 1.0) * 255.0) as u32 };
    0x8000_0000 | (pack(lit[0]) << 16) | (pack(lit[1]) << 8) | pack(lit[2])
}

/// Blend `color` toward `env.fog_color` by perpendicular `depth`
/// (linear, fully fogged at `env.fog_max_dist`). No-op when fog is
/// disabled (`fog_max_dist <= 0`).
#[inline]
fn apply_fog(color: u32, depth: f32, env: &DdaEnv<'_>) -> u32 {
    if env.fog_max_dist <= 0.0 {
        return color;
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    let f = ((depth / env.fog_max_dist).clamp(0.0, 1.0) * 256.0) as u32; // 0..256
    let g = 256 - f;
    let fog = env.fog_color;
    let mix = |shift: u32| -> u32 {
        let src = (color >> shift) & 0xff;
        let dst = (fog >> shift) & 0xff;
        ((src * g + dst * f) >> 8).min(255)
    };
    0x8000_0000 | (mix(16) << 16) | (mix(8) << 8) | mix(0)
}

/// Composite premultiplied `accum` (+ remaining `trans`) over a packed
/// background colour → packed `0x80RRGGBB`.
#[inline]
fn composite_over(accum: [f32; 3], trans: f32, bg: u32) -> u32 {
    let b = rgb_to_f32(bg);
    f32_to_rgb([
        accum[0] + trans * b[0],
        accum[1] + trans * b[1],
        accum[2] + trans * b[2],
    ])
}

/// Finalize a translucent terrain ray that exited the grid (sky). Returns
/// `None` when nothing was accumulated (the opaque first-hit path — the
/// caller's sky handling stands, bit-identical), else the accumulated
/// layers composited over the sky at `dist`.
#[inline]
fn finalize_exit(
    touched: bool,
    accum: [f32; 3],
    trans: f32,
    env: &DdaEnv<'_>,
    dir: [f32; 3],
    dist: f32,
) -> Option<Hit> {
    if !touched {
        return None;
    }
    let bg = match env.sky {
        Some(s) => sample_sky(s, dir),
        None => 0x8000_0000 | (env.fog_color & 0x00ff_ffff),
    };
    Some(Hit {
        color: composite_over(accum, trans, bg),
        dist,
    })
}

/// Unpack `0x__RRGGBB` to `0..1` float channels (RGB; the high byte is
/// dropped — it has already been folded into the colour by `shade`/`fog`).
#[inline]
#[allow(clippy::cast_precision_loss)]
fn rgb_to_f32(c: u32) -> [f32; 3] {
    [
        ((c >> 16) & 0xff) as f32 / 255.0,
        ((c >> 8) & 0xff) as f32 / 255.0,
        (c & 0xff) as f32 / 255.0,
    ]
}

/// Repack `0..1` float channels (clamped) into `0x80RRGGBB`.
#[inline]
#[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
fn f32_to_rgb(c: [f32; 3]) -> u32 {
    let q = |v: f32| (v.clamp(0.0, 1.0) * 255.0 + 0.5) as u32;
    0x8000_0000 | (q(c[0]) << 16) | (q(c[1]) << 8) | q(c[2])
}

/// Sample the sky panorama in ray direction `dir` (need not be
/// normalised), returning a packed `0x80RRGGBB` colour.
///
/// Clean-room equirectangular mapping (not voxlap's `lng`/`lat` asm
/// search): the texture's x axis is elevation (`asin` of the vertical
/// component), the y axis is azimuth (`atan2` around the vertical). A
/// `ysiz == 1` panorama (e.g. [`Sky::blue_gradient`]) is a pure
/// horizon→zenith gradient.
#[allow(
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss,
    clippy::cast_precision_loss
)]
fn sample_sky(sky: &Sky, dir: [f32; 3]) -> u32 {
    let len = (dir[0] * dir[0] + dir[1] * dir[1] + dir[2] * dir[2]).sqrt();
    if len < 1e-9 {
        return 0x8000_0000;
    }
    let d = [dir[0] / len, dir[1] / len, dir[2] / len];
    let xsiz_full = sky.lat.len().max(1) as i32; // original column count
    let pi = std::f32::consts::PI;
    // Elevation → x, matching the GPU `sky_color` (scene_dda.wgsl): z is
    // down, so `acos(-z)` is 0 at the zenith (looking up) and π at the nadir
    // (looking down); `/π` puts the zenith at x=0 and the nadir at x=xsiz.
    let elev01 = (-d[2]).clamp(-1.0, 1.0).acos() / pi; // 0 (up) .. 1 (down)
    let x = (elev01 * xsiz_full as f32) as i32;
    let x = x.clamp(0, xsiz_full - 1);
    // Azimuth → y (wrapped).
    let y = if sky.ysiz <= 1 {
        0
    } else {
        let az = d[1].atan2(d[0]); // -pi..pi
        let yf = ((az / (pi * 2.0)) + 0.5) * sky.ysiz as f32;
        (yf as i32).rem_euclid(sky.ysiz)
    };
    let idx = (y * xsiz_full + x) as usize;
    let px = sky.pixels.get(idx).copied().unwrap_or(0) as u32;
    0x8000_0000 | (px & 0x00ff_ffff)
}

/// Fill the panorama [`Sky`] into every **background** pixel — one whose
/// z-buffer entry is still `+∞` (no grid/terrain hit). The per-grid DDA only
/// samples the sky inside each grid's screen rect (and only its sky-owning
/// grid); pixels outside any grid — most of a sprite/effect-only view, or the
/// margins around a small world grid — would otherwise keep the caller's flat
/// clear colour. This paints the real panorama there while leaving terrain
/// (finite z) and composited translucent pixels untouched. The z-buffer is
/// not modified. `cam`/`settings` are the same per-frame projection the
/// renderer used.
#[allow(clippy::cast_possible_truncation)]
pub fn render_sky_fill(
    fb: &mut [u32],
    zb: &[f32],
    pitch_pixels: usize,
    width: u32,
    height: u32,
    cam: &CameraState,
    settings: &OpticastSettings,
    sky: &Sky,
) {
    // PF.7 (C6) — rayon rows: this was a full-frame single-threaded pass
    // with an `acos` + `atan2` per background pixel (an entire serial
    // frame on sky-dominant views). Rows are disjoint (`by_ref` chunks of
    // the framebuffer); `zb` is read-only. Bit-identical.
    fb.par_chunks_mut(pitch_pixels)
        .take(height as usize)
        .enumerate()
        .for_each(|(py, frow)| {
            let row = py * pitch_pixels;
            #[allow(clippy::cast_possible_truncation)]
            let py = py as u32;
            for px in 0..width {
                let idx = row + px as usize;
                if zb[idx].is_finite() {
                    continue; // a grid/terrain hit owns this pixel
                }
                let (_origin, dir) = pixel_ray(cam, settings, px, py);
                frow[px as usize] = sample_sky(sky, dir);
            }
        });
}

/// World-space ray for screen pixel `(px, py)` under opticast's
/// pinhole: origin is the camera position, direction is
/// `(px - hx)·right + (py - hy)·down + hz·forward`.
///
/// This is the exact ray `camera_math::derive` bakes into its corner
/// vectors (`corn[0]` is `pixel (0, 0)`'s direction), so the DDA
/// renderer samples the same rays the voxlap path's frustum is built
/// from. The direction is **not** normalised — callers that need a
/// unit ray (and a true Euclidean distance) normalise themselves;
/// DDA.1 will track perpendicular distance via the forward-projection
/// instead, matching the engine's z-buffer convention.
#[must_use]
pub fn pixel_ray(
    cs: &CameraState,
    settings: &OpticastSettings,
    px: u32,
    py: u32,
) -> ([f32; 3], [f32; 3]) {
    // u32 → f32 is exact for any realistic screen coordinate.
    #[allow(clippy::cast_precision_loss)]
    let sx = px as f32 - settings.hx;
    #[allow(clippy::cast_precision_loss)]
    let sy = py as f32 - settings.hy;
    let dir = [
        sx * cs.right[0] + sy * cs.down[0] + settings.hz * cs.forward[0],
        sx * cs.right[1] + sy * cs.down[1] + settings.hz * cs.forward[1],
        sx * cs.right[2] + sy * cs.down[2] + settings.hz * cs.forward[2],
    ];
    (cs.pos, dir)
}

/// Ray ↔ axis-aligned box `[lo, hi]` slab test. Returns the
/// `(t_enter, t_exit)` parameter interval along `dir` (already clamped
/// so `t_enter >= 0`, i.e. a camera inside the box starts at `t = 0`),
/// or `None` if the ray misses the box. `dir` need not be normalised —
/// `t` is in units of `|dir|`.
pub(crate) fn intersect_aabb(
    o: [f32; 3],
    dir: [f32; 3],
    lo: [f32; 3],
    hi: [f32; 3],
) -> Option<(f32, f32)> {
    let mut t0 = 0.0f32;
    let mut t1 = f32::INFINITY;
    for a in 0..3 {
        if dir[a].abs() < 1e-9 {
            // Ray parallel to this slab — must already be inside it.
            if o[a] < lo[a] || o[a] > hi[a] {
                return None;
            }
        } else {
            let inv = 1.0 / dir[a];
            let mut ta = (lo[a] - o[a]) * inv;
            let mut tb = (hi[a] - o[a]) * inv;
            if ta > tb {
                core::mem::swap(&mut ta, &mut tb);
            }
            t0 = t0.max(ta);
            t1 = t1.min(tb);
            if t0 > t1 {
                return None;
            }
        }
    }
    Some((t0, t1))
}

/// Brick edge length in voxels — one occupancy bit per `BRICK³` block.
const BRICK: i32 = 8;

/// Per-chunk brick occupancy map for two-level DDA empty-space skip
/// (Substage DDA.3).
///
/// One bit per `BRICK³` block of the active chunk, set iff any voxel in
/// the block is solid. The ray steps the coarse brick grid (8× longer
/// strides) and only descends into a per-voxel walk inside occupied
/// bricks, so a ray through open air crosses ~`length / 8` empty bricks
/// instead of `length` air voxels — each of which would otherwise walk
/// the column slab chain via `surface_color`.
///
/// Built per frame from a [`GridView`] in [`render_dda`]. A persistent
/// per-chunk cache with edit-driven invalidation (locked decision #2 in
/// `PORTING-DDA.md`) is a later perf refinement.
#[derive(Debug)]
pub(crate) struct BrickMap {
    /// Brick counts along x / y / z (one entry per `BRICK³` cells).
    nb: [i32; 3],
    /// Brick occupancy bitset; brick `(bx, by, bz)` is bit
    /// `(bz * nb[1] + by) * nb[0] + bx`.
    bits: Vec<u64>,
    /// Super-brick counts (one entry per `BRICK³` *bricks* = `SUPER³`
    /// cells), `ceil(nb / BRICK)`.
    ns: [i32; 3],
    /// Super-brick occupancy (DDA.7 perf): a coarse level so a ray
    /// through open air above the terrain skips `SUPER` cells per outer
    /// step instead of `BRICK`. A super-brick is set iff any child brick
    /// is set.
    super_bits: Vec<u64>,
}

/// Super-brick edge in cells (`BRICK` bricks per axis).
const SUPER: i32 = BRICK * BRICK;

impl BrickMap {
    /// Scan every mip-`mip` column of `grid`, building brick + super-
    /// brick occupancy. `mip` must be `< grid.mip_count()`.
    #[allow(clippy::cast_possible_wrap, clippy::cast_sign_loss)]
    fn build(grid: &GridView<'_>, mip: u32) -> Self {
        let vsid_m = (grid.vsid >> mip).max(1) as i32;
        let z_m = (crate::grid_view::CHUNK_SIZE_Z >> mip).max(1) as i32;
        let nb = [
            (vsid_m + BRICK - 1) / BRICK,
            (vsid_m + BRICK - 1) / BRICK,
            (z_m + BRICK - 1) / BRICK,
        ];
        let ns = [
            (nb[0] + BRICK - 1) / BRICK,
            (nb[1] + BRICK - 1) / BRICK,
            (nb[2] + BRICK - 1) / BRICK,
        ];
        let count = (nb[0] * nb[1] * nb[2]) as usize;
        let scount = (ns[0] * ns[1] * ns[2]) as usize;
        let mut bits = vec![0u64; count.div_ceil(64)];
        let mut super_bits = vec![0u64; scount.div_ceil(64)];
        for y in 0..vsid_m {
            for x in 0..vsid_m {
                let (bx, by) = (x / BRICK, y / BRICK);
                grid.for_each_run_mip(x as u32, y as u32, mip, |top, bot| {
                    for bz in (top / BRICK)..=((bot - 1) / BRICK) {
                        let idx = ((bz * nb[1] + by) * nb[0] + bx) as usize;
                        bits[idx / 64] |= 1u64 << (idx % 64);
                        let sidx =
                            (((bz / BRICK) * ns[1] + by / BRICK) * ns[0] + bx / BRICK) as usize;
                        super_bits[sidx / 64] |= 1u64 << (sidx % 64);
                    }
                });
            }
        }
        Self {
            nb,
            bits,
            ns,
            super_bits,
        }
    }

    /// Whether brick `b` is in range and holds any solid voxel.
    #[inline]
    #[allow(clippy::cast_sign_loss)]
    fn occupied(&self, b: [i32; 3]) -> bool {
        if b[0] < 0
            || b[0] >= self.nb[0]
            || b[1] < 0
            || b[1] >= self.nb[1]
            || b[2] < 0
            || b[2] >= self.nb[2]
        {
            return false;
        }
        let idx = ((b[2] * self.nb[1] + b[1]) * self.nb[0] + b[0]) as usize;
        (self.bits[idx / 64] >> (idx % 64)) & 1 != 0
    }

    /// Whether super-brick `s` is in range and holds any solid voxel.
    #[inline]
    #[allow(clippy::cast_sign_loss)]
    fn occupied_super(&self, s: [i32; 3]) -> bool {
        if s[0] < 0
            || s[0] >= self.ns[0]
            || s[1] < 0
            || s[1] >= self.ns[1]
            || s[2] < 0
            || s[2] >= self.ns[2]
        {
            return false;
        }
        let idx = ((s[2] * self.ns[1] + s[1]) * self.ns[0] + s[0]) as usize;
        (self.super_bits[idx / 64] >> (idx % 64)) & 1 != 0
    }
}

/// Per-axis 3D-DDA stepping state for a cell size of `cell` voxels.
/// `t_max[a]` is the ray parameter at which the next `a`-boundary is
/// crossed; `t_delta[a]` is the parameter increment per cell. An
/// axis-parallel component gets `t_max = t_delta = +inf` so it's never
/// chosen as the stepping axis.
pub(crate) fn dda_setup(
    origin: [f32; 3],
    dir: [f32; 3],
    cell: [i32; 3],
    cell_size: f32,
) -> ([i32; 3], [f32; 3], [f32; 3]) {
    let mut step = [0i32; 3];
    let mut t_max = [f32::INFINITY; 3];
    let mut t_delta = [f32::INFINITY; 3];
    for a in 0..3 {
        if dir[a] > 1e-9 {
            step[a] = 1;
            #[allow(clippy::cast_precision_loss)]
            let boundary = (cell[a] + 1) as f32 * cell_size;
            t_max[a] = (boundary - origin[a]) / dir[a];
            t_delta[a] = cell_size / dir[a];
        } else if dir[a] < -1e-9 {
            step[a] = -1;
            #[allow(clippy::cast_precision_loss)]
            let boundary = cell[a] as f32 * cell_size;
            t_max[a] = (boundary - origin[a]) / dir[a];
            t_delta[a] = -cell_size / dir[a];
        }
    }
    (step, t_max, t_delta)
}

/// Index of the axis with the smallest `t_max` (the next boundary the
/// ray crosses).
#[inline]
pub(crate) fn min_axis(t_max: [f32; 3]) -> usize {
    if t_max[0] <= t_max[1] && t_max[0] <= t_max[2] {
        0
    } else if t_max[1] <= t_max[2] {
        1
    } else {
        2
    }
}

/// Persistent, cross-frame brick occupancy cache (Substage DDA.7
/// perf). Keyed by `(chunk x, y, z, mip)` with the chunk's edit
/// `version`; an entry is reused until its chunk's version changes, so a
/// static / streamed-once world pays **zero** brick-build cost after the
/// first frame (the per-frame rebuild was the dominant DDA cost).
///
/// Owned by the caller across frames (the scene's `Grid`), populated
/// single-threaded via [`Self::ensure`], then borrowed immutably by the
/// parallel render bands.
#[derive(Debug, Default)]
pub struct BrickCache {
    maps: HashMap<(i32, i32, i32, u32), (u64, BrickMap)>,
}

impl BrickCache {
    /// An empty cache (same as [`Default`]). Entries appear via
    /// [`ensure`](Self::ensure) as chunks are first rendered.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Ensure a current mip-`mip` brick map exists for `chunk` (built
    /// from `view`); rebuilds only when the cached `version` differs.
    pub fn ensure(&mut self, chunk: [i32; 3], mip: u32, version: u64, view: &GridView<'_>) {
        let key = (chunk[0], chunk[1], chunk[2], mip);
        let stale = self.maps.get(&key).is_none_or(|(v, _)| *v != version);
        if stale {
            self.maps.insert(key, (version, BrickMap::build(view, mip)));
        }
    }

    #[inline]
    fn get(&self, chunk: [i32; 3], mip: u32) -> Option<&BrickMap> {
        self.maps
            .get(&(chunk[0], chunk[1], chunk[2], mip))
            .map(|(_, m)| m)
    }

    /// Drop cached entries whose chunk fails `keep` — bounds memory as
    /// streaming evicts chunks. Called once per frame by the scene.
    pub fn retain_chunks(&mut self, keep: impl Fn([i32; 3]) -> bool) {
        self.maps.retain(|k, _| keep([k.0, k.1, k.2]));
    }

    /// PF.9 — occupancy of the `BRICK`³ block containing chunk-local
    /// mip-`mip` cell `cell` of `chunk`. `None` when no map is cached for
    /// that (chunk, mip) — the caller must fall back to dense stepping.
    /// `Some(false)` guarantees the whole 8³ block holds no solid voxel,
    /// so an external shadow march may skip it wholesale.
    #[must_use]
    pub fn brick_occupied_at(&self, chunk: [i32; 3], mip: u32, cell: [i32; 3]) -> Option<bool> {
        self.get(chunk, mip)
            .map(|m| m.occupied([cell[0] >> 3, cell[1] >> 3, cell[2] >> 3]))
    }

    /// PF.9 — like [`Self::brick_occupied_at`] for the `SUPER`³ (64³ at
    /// mip 0) super-brick level.
    #[must_use]
    pub fn super_occupied_at(&self, chunk: [i32; 3], mip: u32, cell: [i32; 3]) -> Option<bool> {
        self.get(chunk, mip)
            .map(|m| m.occupied_super([cell[0] >> 6, cell[1] >> 6, cell[2] >> 6]))
    }
}

/// Build a throwaway [`BrickCache`] covering every populated chunk of
/// `grid` at the effective mip — for the sequential [`render_dda`] /
/// tests, where no persistent cache is threaded in. Returns
/// `(cache, effective_mip)`.
#[allow(clippy::cast_possible_wrap)]
fn local_cache(grid: &GridView<'_>, requested_mip: u32) -> (BrickCache, u32) {
    let mip = effective_mip(grid, requested_mip);
    let mut cache = BrickCache::new();
    if let Some(cg) = grid.chunk_grid {
        for dz in 0..cg.chunks_z as i32 {
            for dy in 0..cg.chunks_y as i32 {
                for dx in 0..cg.chunks_x as i32 {
                    let slot = ((dz * cg.chunks_y as i32 + dy) * cg.chunks_x as i32 + dx) as usize;
                    if let Some(Some(view)) = cg.chunks.get(slot) {
                        let ch = [
                            cg.origin_chunk_xy[0] + dx,
                            cg.origin_chunk_xy[1] + dy,
                            cg.origin_chunk_z + dz,
                        ];
                        cache.ensure(ch, mip, 0, view);
                    }
                }
            }
        }
    } else {
        cache.ensure([0, 0, 0], mip, 0, grid);
    }
    (cache, mip)
}

/// Clamp a requested render mip to one every populated chunk actually
/// has built — so the uniform-mip traversal never under-samples a chunk
/// that lacks the requested level (which would punch holes). `0` short-
/// circuits (always available).
#[must_use]
pub fn effective_mip(grid: &GridView<'_>, requested: u32) -> u32 {
    if requested == 0 {
        return 0;
    }
    let mut m = requested;
    if let Some(cg) = grid.chunk_grid {
        for c in cg.chunks.iter().flatten() {
            m = m.min(c.mip_count().saturating_sub(1));
        }
    } else {
        m = m.min(grid.mip_count().saturating_sub(1));
    }
    m
}

/// Cross-chunk voxel sampler (Substage DDA.4 / DDA.7).
///
/// Resolves a grid-local voxel coordinate to the chunk that owns it
/// (via [`GridView::chunk_at_xyz`]) and answers the DDA's per-voxel hit
/// query — brick-gated [`GridView::surface_color`]. It borrows the
/// shared immutable [`BrickMaps`] and caches the **current chunk**
/// (`cur_*`: view + brick-map reference): a ray usually stays in one
/// chunk for many voxels, so the per-voxel cost is a single index
/// compare + an O(1) brick bit test — no hashing, no mutation. Holding
/// only shared borrows, a `Sampler` is cheap to spin up per render band.
///
/// Single-chunk grids are the degenerate case: every voxel maps to
/// chunk `[0, 0, 0]` (= the view itself).
struct Sampler<'a> {
    grid: GridView<'a>,
    bricks: &'a BrickCache,
    /// Effective render mip (DDA.6). Traversal cells are mip-`mip`
    /// cells; sampling reads mip-`mip` data.
    mip: u32,
    /// Chunk size in mip-`mip` cells is a power of two; store it as
    /// `log2` (shift) + `size - 1` (mask) so [`Self::locate`] splits a
    /// cell into `(chunk, in-chunk)` with a shift + an `&` per axis
    /// instead of a signed `div_euclid` — the dominant per-cell cost.
    /// Arithmetic `>>` floors toward -∞ (= `div_euclid` for a positive
    /// power-of-two divisor) and `& mask` gives the non-negative
    /// remainder (= `rem_euclid`) even for negative cells (two's
    /// complement), so results are identical to the division form.
    xy_shift: u32,
    xy_mask: i32,
    z_shift: u32,
    z_mask: i32,
    /// CA.1 — cutaway clip plane in **mip-cells** (`z_clip >> mip`;
    /// arithmetic shift = floor, matching the GPU formula). Cells with
    /// `c[2] < z_clip_mip` read as air. `i32::MIN` = disabled: no real
    /// cell index is ever below it, so the gate is branch-cheap with
    /// no `Option` unwrap per cell.
    z_clip_mip: i32,
    cur_ch: [i32; 3],
    cur_view: Option<GridView<'a>>,
    cur_brick: Option<&'a BrickMap>,
    has_cur: bool,
}

impl<'a> Sampler<'a> {
    fn new(grid: GridView<'a>, bricks: &'a BrickCache, mip: u32, z_clip: Option<i32>) -> Self {
        let cs_xy = (grid.chunk_size_xy >> mip).max(1);
        let cs_z = (crate::grid_view::CHUNK_SIZE_Z >> mip).max(1);
        debug_assert!(
            cs_xy.is_power_of_two() && cs_z.is_power_of_two(),
            "chunk dims must be powers of two for the shift/mask split"
        );
        #[allow(clippy::cast_possible_wrap)]
        Self {
            grid,
            bricks,
            mip,
            xy_shift: cs_xy.trailing_zeros(),
            xy_mask: cs_xy as i32 - 1,
            z_shift: cs_z.trailing_zeros(),
            z_mask: cs_z as i32 - 1,
            // CA.1 — mip-0 voxel z → mip-cells. Arithmetic `>>` floors
            // toward -∞ (clip planes can be negative on stacked-chz
            // grids), the same formula the GPU marcher uses — CA.3's
            // parity gate depends on the two staying identical.
            z_clip_mip: z_clip.map_or(i32::MIN, |z| z >> mip),
            cur_ch: [0; 3],
            cur_view: None,
            cur_brick: None,
            has_cur: false,
        }
    }

    /// Refresh the current-chunk cache (view + brick map) for `ch`.
    fn select_chunk(&mut self, ch: [i32; 3]) {
        if self.has_cur && self.cur_ch == ch {
            return;
        }
        self.cur_view = self.grid.chunk_at_xyz(ch);
        self.cur_brick = self.bricks.get(ch, self.mip);
        self.cur_ch = ch;
        self.has_cur = true;
    }

    /// Split a grid-local **mip-`mip` cell** index into `(chunk index,
    /// in-chunk mip-cell)` via shift + mask (see field docs). Chunk
    /// indices are mip-independent; only the per-chunk resolution
    /// shrinks with mip.
    #[allow(clippy::cast_sign_loss)]
    fn locate(&self, c: [i32; 3]) -> ([i32; 3], [u32; 3]) {
        let ch = [
            c[0] >> self.xy_shift,
            c[1] >> self.xy_shift,
            c[2] >> self.z_shift,
        ];
        let loc = [
            (c[0] & self.xy_mask) as u32,
            (c[1] & self.xy_mask) as u32,
            (c[2] & self.z_mask) as u32,
        ];
        (ch, loc)
    }

    /// Hit colour for grid-local mip-cell `c`, or `None` for air / empty
    /// chunk / uncoloured bedrock. Brick-gated so air inside a populated
    /// chunk costs only a bit test, not a slab walk.
    #[allow(clippy::cast_possible_wrap)]
    fn hit(&mut self, c: [i32; 3]) -> Option<u32> {
        #[cfg(test)]
        prof::SURF.with(|x| x.set(x.get() + 1));
        // CA.1 — cutaway: cells above the clip plane (z-down, so
        // `z < z_clip`) read as air. `c[2]` is the grid-local ABSOLUTE
        // mip-cell z (spanning stacked chz chunks) — testing the
        // in-chunk `loc[2]` alone would pass on 1-chunk fixtures and
        // break on multi-deck ships. Shadow marches share this gate
        // via [`SamplerShadow`], so hidden decks stop casting too.
        if c[2] < self.z_clip_mip {
            return None;
        }
        let (ch, loc) = self.locate(c);
        self.select_chunk(ch);
        let occupied = self.cur_brick.is_some_and(|bm| {
            bm.occupied([
                loc[0] as i32 / BRICK,
                loc[1] as i32 / BRICK,
                loc[2] as i32 / BRICK,
            ])
        });
        if !occupied {
            return None;
        }
        self.cur_view?
            .surface_color_mip(loc[0], loc[1], loc[2], self.mip)
            .map(|c| c.0)
    }

    /// Chunk size in mip-cells along XY / Z (always a power of two).
    #[inline]
    fn cells_per_chunk_xy(&self) -> i32 {
        1 << self.xy_shift
    }
    #[inline]
    fn cells_per_chunk_z(&self) -> i32 {
        1 << self.z_shift
    }

    /// Whether the brick at brick-index `brick` (in `BRICK`-mip-cell
    /// units) holds any solid voxel. Used by the outer brick-DDA to skip
    /// empty space `BRICK` cells at a time. Assumes bricks nest within
    /// chunks (caller gates on [`Self::cells_per_chunk_xy`]`>= BRICK`).
    #[allow(clippy::cast_sign_loss)]
    fn brick_occupied(&mut self, brick: [i32; 3]) -> bool {
        // First mip-cell of the brick (BRICK = 8 → `<< 3`).
        let c0 = [brick[0] << 3, brick[1] << 3, brick[2] << 3];
        let ch = [
            c0[0] >> self.xy_shift,
            c0[1] >> self.xy_shift,
            c0[2] >> self.z_shift,
        ];
        self.select_chunk(ch);
        self.cur_brick.is_some_and(|bm| {
            bm.occupied([
                (c0[0] & self.xy_mask) >> 3,
                (c0[1] & self.xy_mask) >> 3,
                (c0[2] & self.z_mask) >> 3,
            ])
        })
    }

    /// Whether the super-brick at super-index `s` (in `SUPER`-mip-cell
    /// units) holds any solid voxel. Outer-most empty-space skip (steps
    /// `SUPER` cells). Assumes super-bricks nest in chunks (caller gates
    /// on `cells_per_chunk >= SUPER`).
    #[allow(clippy::cast_sign_loss)]
    fn super_occupied(&mut self, s: [i32; 3]) -> bool {
        // First mip-cell of the super-brick (SUPER = 64 → `<< 6`).
        let c0 = [s[0] << 6, s[1] << 6, s[2] << 6];
        let ch = [
            c0[0] >> self.xy_shift,
            c0[1] >> self.xy_shift,
            c0[2] >> self.z_shift,
        ];
        self.select_chunk(ch);
        self.cur_brick.is_some_and(|bm| {
            bm.occupied_super([
                (c0[0] & self.xy_mask) >> 6,
                (c0[1] & self.xy_mask) >> 6,
                (c0[2] & self.z_mask) >> 6,
            ])
        })
    }
}

/// CPU.2 — safety cap on a shadow ray's voxel steps (the `shadow_max_dist`
/// / light-distance bound is the real limit; this only backstops a
/// degenerate ray). Mirrors the GPU `shadow_max_steps`.
const SHADOW_MAX_STEPS: u32 = 1024;

/// CPU.2 — [`ShadowTester`] backed by the render [`Sampler`]: a hard-shadow
/// occlusion march over the grid's mip-`mip` voxels. The march reuses the
/// same `sampler.hit()` occupancy the primary ray uses (so a shadow ray is
/// blocked by the same surfaces the camera sees) and the same `[lo_c, hi_c)`
/// voxel-box bounds, stepping a standard 3D-DDA until it hits a solid cell
/// (occluded), leaves the box / exceeds `max_t` (lit), or hits the step cap.
struct SamplerShadow<'s, 'a, 'f> {
    sampler: &'s mut Sampler<'a>,
    cell_size: f32,
    lo_c: [i32; 3],
    hi_c: [i32; 3],
    /// FW.2 review #1 — the fog-of-war styler (if any): a solid cell the
    /// observer never saw (`Hide`) must NOT block a shadow ray, or its
    /// silhouette leaks as a shadow shape on visible geometry. Same
    /// classifier the primary ray uses, so shadows and vision agree.
    fow: Option<&'f dyn FowStyler>,
}

impl ShadowTester for SamplerShadow<'_, '_, '_> {
    #[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
    fn occluded(&mut self, origin: [f32; 3], dir: [f32; 3], max_t: f32) -> bool {
        let cs = self.cell_size;
        // PF.9 (C3) — the shadow march gets the primary ray's empty-space
        // skip: fast-forward across empty super-bricks / bricks (skipping
        // an EMPTY box can never hide an occluder). The step budget is
        // consumed in Manhattan cell distance — exactly what the dense
        // walk would have spent crossing the same span — so the
        // `SHADOW_MAX_STEPS` truncation fires at the identical point and
        // hit/no-hit stays bit-compatible with the pre-skip march.
        let has_super =
            self.sampler.cells_per_chunk_xy() >= SUPER && self.sampler.cells_per_chunk_z() >= SUPER;
        let has_brick =
            self.sampler.cells_per_chunk_xy() >= BRICK && self.sampler.cells_per_chunk_z() >= BRICK;
        let mut cellc = [
            (origin[0] / cs).floor() as i32,
            (origin[1] / cs).floor() as i32,
            (origin[2] / cs).floor() as i32,
        ];
        let (step, mut t_max, t_delta) = dda_setup(origin, dir, cellc, cs);
        let inv = [
            if step[0] != 0 { 1.0 / dir[0] } else { 0.0 },
            if step[1] != 0 { 1.0 / dir[1] } else { 0.0 },
            if step[2] != 0 { 1.0 / dir[2] } else { 0.0 },
        ];
        let mut t_curr = 0.0f32;
        let mut used = 0u32;
        while used < SHADOW_MAX_STEPS {
            if cellc[0] < self.lo_c[0]
                || cellc[0] >= self.hi_c[0]
                || cellc[1] < self.lo_c[1]
                || cellc[1] >= self.hi_c[1]
                || cellc[2] < self.lo_c[2]
                || cellc[2] >= self.hi_c[2]
            {
                return false; // left the voxel box → no occluder ahead
            }
            if t_curr > max_t {
                return false; // past the cap / the light → unshadowed
            }
            // Empty-space skip (mirrors `cell_walk_skip`'s landing logic:
            // the exit axis is pinned to the integer boundary cell so the
            // next box's entry cell is always visited densely).
            let skip_shift = if has_super
                && !self
                    .sampler
                    .super_occupied([cellc[0] >> 6, cellc[1] >> 6, cellc[2] >> 6])
            {
                Some(6u32)
            } else if has_brick
                && !self
                    .sampler
                    .brick_occupied([cellc[0] >> 3, cellc[1] >> 3, cellc[2] >> 3])
            {
                Some(3u32)
            } else {
                None
            };
            if let Some(sh) = skip_shift {
                let mut best_t = f32::INFINITY;
                let mut best_axis = 3usize;
                let mut plane = [0i32; 3];
                for a in 0..3 {
                    if step[a] == 0 {
                        continue;
                    }
                    let idx = cellc[a] >> sh;
                    plane[a] = if step[a] > 0 {
                        (idx + 1) << sh
                    } else {
                        idx << sh
                    };
                    let tb = (plane[a] as f32 * cs - origin[a]) * inv[a];
                    if tb < best_t {
                        best_t = tb;
                        best_axis = a;
                    }
                }
                if best_axis == 3 {
                    return false;
                }
                // Landing mirrors `cell_walk_skip`: exit axis pinned to
                // the boundary cell, other axes advanced by exact
                // crossing counts from t-differences (position
                // reconstruction is ill-conditioned at large t).
                let mut nc = cellc;
                for a in 0..3 {
                    if a == best_axis || step[a] == 0 || t_max[a] > best_t {
                        continue;
                    }
                    #[allow(clippy::cast_possible_truncation)]
                    let k = ((best_t - t_max[a]) / t_delta[a]) as i32 + 1;
                    nc[a] += k * step[a];
                    t_max[a] += k as f32 * t_delta[a];
                }
                nc[best_axis] = if step[best_axis] > 0 {
                    plane[best_axis]
                } else {
                    plane[best_axis] - 1
                };
                t_max[best_axis] = best_t + t_delta[best_axis];
                // Budget: the dense walk would have spent one step per
                // cell (Manhattan distance). If it runs out inside the
                // empty box the dense walk would have returned `false`
                // there — nothing solid to find inside it.
                let crossed =
                    cellc[0].abs_diff(nc[0]) + cellc[1].abs_diff(nc[1]) + cellc[2].abs_diff(nc[2]);
                if used.saturating_add(crossed) >= SHADOW_MAX_STEPS {
                    return false;
                }
                used += crossed;
                cellc = nc;
                t_curr = best_t.max(t_curr);
                continue;
            }
            if self.sampler.hit(cellc).is_some() && !self.fow_hidden(cellc) {
                return true; // a surface (that the observer knows) blocks the ray
            }
            let axis = min_axis(t_max);
            t_curr = t_max[axis];
            cellc[axis] += step[axis];
            t_max[axis] += t_delta[axis];
            used += 1;
        }
        false
    }
}

impl SamplerShadow<'_, '_, '_> {
    /// FW.2 review #1 — is `cellc` (mip-cell index) a fog-Hidden cell?
    /// A Hidden solid casts no shadow (unseen geometry stays invisible,
    /// including its shadow silhouette). Sampled at the coarse cell's
    /// centre, matching the primary ray's lookup.
    #[inline]
    fn fow_hidden(&self, cellc: [i32; 3]) -> bool {
        let Some(styler) = self.fow else {
            return false;
        };
        let mip = self.sampler.mip;
        let half = (1i32 << mip) >> 1;
        matches!(
            styler.verdict(
                (cellc[0] << mip) + half,
                (cellc[1] << mip) + half,
                (cellc[2] << mip) + half,
            ),
            FowVerdict::Hide
        )
    }
}

/// Walk mip-cells along the ray within `[lo_c, hi_c)` and return the
/// first solid hit, with leak-free empty-space skipping (DDA.7 redux).
///
/// **Why one continuous DDA, not nested level-walks.** The previous
/// design ran an outer brick/super DDA that *jumped* whole bricks and
/// only descended into occupied ones. Stepping a coarse cell at a time
/// lets the ray slip diagonally **past an occupied coarse cell it only
/// touches at a shared edge/corner** — a leak that showed as bright
/// sky seams across thin diagonal walls (the cave-demo report). Here a
/// *single* cell-granularity DDA carries the exact `(cellc, t_max)`
/// state for the whole ray; it only ever **fast-forwards across an
/// empty super-brick / brick**, where skipping cannot miss anything.
/// The exit axis lands on the integer box-boundary cell (no float
/// re-floor on the critical axis), so the entry cell of the next —
/// possibly occupied — box is always visited densely. Result: hits are
/// bit-identical to the dense per-cell reference, with the empty-space
/// speed-up retained.
///
/// `cell_size` is the mip-cell edge in mip-0 voxels (`1 << mip`);
/// `fwd_dot = dir·forward` → perpendicular depth.
#[allow(
    clippy::too_many_arguments,
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss,
    clippy::cast_precision_loss
)]
fn cell_walk_skip(
    origin: [f32; 3],
    dir: [f32; 3],
    fwd_dot: f32,
    sampler: &mut Sampler<'_>,
    lo_c: [i32; 3],
    hi_c: [i32; 3],
    cell_size: f32,
    t_enter: f32,
    t_exit: f32,
    max_dist: f32,
    env: &DdaEnv<'_>,
) -> Option<Hit> {
    let has_super = sampler.cells_per_chunk_xy() >= SUPER && sampler.cells_per_chunk_z() >= SUPER;
    let has_brick = sampler.cells_per_chunk_xy() >= BRICK && sampler.cells_per_chunk_z() >= BRICK;
    // OC.1 — the cutout's focus plane in mip-cells (arithmetic `>> mip`
    // floors — CA.1's exact formula; the OC.2 parity gate pins this
    // against the GPU kernel's pair). `i32::MIN` when no cutout: no
    // real cell index is ever below it, mirroring `z_clip_mip` — the
    // whole per-cell cone test below stays behind this one compare.
    let cut_z_mip = env.cutout.map_or(i32::MIN, |c| c.focus_z >> sampler.mip);
    // FW.2 — mip shift + half-cell offset to turn a hit's mip-cell index
    // into the mip-0 grid-local voxel at the coarse cell's CENTRE for the
    // fog-of-war lookup (review #2: sampling the low corner let a coarse
    // cell straddling a deck ceiling classify as out-of-band → leak, and
    // a Visible cell with an Unseen corner pop). Copied out so the
    // per-hit `.filter` closure captures the values, not `sampler`.
    let fow_mip_shift = sampler.mip;
    let fow_mip_half = (1i32 << fow_mip_shift) >> 1;
    // OC.1 — the keyhole cone axis: eye → focus, unit, grid-local.
    // Ray-invariant (`origin` is the camera for every primary ray),
    // computed once per ray for free. A focus at the eye degenerates
    // to "cut nothing" (the facade's margin fold prevents it anyway).
    let cut_axis = env.cutout.map_or([0.0; 3], |c| {
        let d = [
            c.focus_local[0] - origin[0],
            c.focus_local[1] - origin[1],
            c.focus_local[2] - origin[2],
        ];
        let len = (d[0] * d[0] + d[1] * d[1] + d[2] * d[2]).sqrt();
        if len > 1e-6 {
            [d[0] / len, d[1] / len, d[2] / len]
        } else {
            [0.0; 3]
        }
    });

    let start = t_enter + 1e-4;
    let p = [
        origin[0] + dir[0] * start,
        origin[1] + dir[1] * start,
        origin[2] + dir[2] * start,
    ];
    let mut cellc = [
        ((p[0] / cell_size).floor() as i32).clamp(lo_c[0], hi_c[0] - 1),
        ((p[1] / cell_size).floor() as i32).clamp(lo_c[1], hi_c[1] - 1),
        ((p[2] / cell_size).floor() as i32).clamp(lo_c[2], hi_c[2] - 1),
    ];
    let (step, mut t_max, t_delta) = dda_setup(origin, dir, cellc, cell_size);
    // Reciprocal direction → the per-skip box-boundary t and the t_max
    // refresh use multiplies instead of divisions (the dominant skip
    // cost). `0.0` where `step == 0` (that axis' t_max stays +∞).
    let inv = [
        if step[0] != 0 { 1.0 / dir[0] } else { 0.0 },
        if step[1] != 0 { 1.0 / dir[1] } else { 0.0 },
        if step[2] != 0 { 1.0 / dir[2] } else { 0.0 },
    ];
    let mut t_curr = t_enter;
    let mut last_axis = 3usize;
    // World ray length per ray-parameter unit; divided by `cell_size` it turns
    // a cell's `t` span into its path length in voxel units (Volumetric weight).
    let dir_len = (dir[0] * dir[0] + dir[1] * dir[1] + dir[2] * dir[2]).sqrt();
    // PF.7 (C4) — hoisted out of the hit block: "does anything cast a
    // shadow?" is ray-invariant, and the O(lights) `any()` scan ran per
    // hit (per translucent layer on glass/water rays).
    let shadow_casts = env.lights.enabled
        && env.lights.shadow_strength > 0.0
        && (env.lights.sun_casts_shadow || env.lights.points.iter().any(|p| p.casts_shadow));

    // TV: front-to-back translucent accumulation. While no translucent voxel
    // is hit (`touched` stays false) every return is unchanged — the opaque
    // world renders bit-identically. `prev_*` drive per-span compositing (one
    // alpha layer per contiguous solid run or material change).
    let mut accum = [0.0f32; 3];
    let mut trans = 1.0f32;
    let mut touched = false;
    let mut prev_solid = false;
    let mut prev_mat = 0u8;

    // Each iteration either advances ≥1 cell (dense) or ≥1 box (skip),
    // so the total cell span bounds the loop.
    let span = (hi_c[0] - lo_c[0]) + (hi_c[1] - lo_c[1]) + (hi_c[2] - lo_c[2]);
    let max_steps = span.max(0) as usize + 16;
    for _ in 0..max_steps {
        if cellc[0] < lo_c[0]
            || cellc[0] >= hi_c[0]
            || cellc[1] < lo_c[1]
            || cellc[1] >= hi_c[1]
            || cellc[2] < lo_c[2]
            || cellc[2] >= hi_c[2]
        {
            return finalize_exit(touched, accum, trans, env, dir, max_dist);
        }
        let depth = t_curr * fwd_dot;
        if depth > max_dist || t_curr > t_exit {
            return finalize_exit(touched, accum, trans, env, dir, max_dist);
        }
        // Fog is fully opaque at `fog_max_dist`: nothing beyond is
        // visible, so stop the ray there and return the fog colour
        // rather than traversing (and skip/step-counting) to the far box
        // wall. Both correct and the dominant perf win for foggy worlds —
        // it caps every ray's length at the fog distance.
        if env.fog_max_dist > 0.0 && depth >= env.fog_max_dist {
            let fog = 0x8000_0000 | (env.fog_color & 0x00ff_ffff);
            let color = if touched {
                composite_over(accum, trans, fog)
            } else {
                fog
            };
            return Some(Hit {
                color,
                dist: env.fog_max_dist,
            });
        }

        // Empty-space skip: a whole empty super-brick, else an empty
        // brick. Skipping only empty boxes can never miss a surface.
        let skip_shift = if has_super
            && !sampler.super_occupied([cellc[0] >> 6, cellc[1] >> 6, cellc[2] >> 6])
        {
            Some(6u32)
        } else if has_brick
            && !sampler.brick_occupied([cellc[0] >> 3, cellc[1] >> 3, cellc[2] >> 3])
        {
            Some(3u32)
        } else {
            None
        };
        if let Some(sh) = skip_shift {
            #[cfg(test)]
            prof::BRICKS.with(|x| x.set(x.get() + 1));
            // Nearest box boundary along the ray (in cell units).
            let mut best_t = f32::INFINITY;
            let mut best_axis = 3usize;
            let mut plane = [0i32; 3];
            for a in 0..3 {
                if step[a] == 0 {
                    continue;
                }
                let idx = cellc[a] >> sh;
                plane[a] = if step[a] > 0 {
                    (idx + 1) << sh
                } else {
                    idx << sh
                };
                let tb = (plane[a] as f32 * cell_size - origin[a]) * inv[a];
                if tb < best_t {
                    best_t = tb;
                    best_axis = a;
                }
            }
            if best_axis == 3 {
                return finalize_exit(touched, accum, trans, env, dir, max_dist);
            }
            // Land just across the boundary. The exit axis is pinned to
            // the integer boundary cell; the OTHER axes advance by their
            // exact crossing COUNT, derived from t-DIFFERENCES (t_max vs
            // best_t) — well-conditioned at any camera distance. (The
            // old landing re-floored an absolute position `origin +
            // dir·(best_t + 1e-4)`: at tele-camera distances (t ≈
            // 1000+) the reconstruction's cancellation noise ≈ 2·ulp(t)
            // exceeds the fixed nudge, landing rays one cell off
            // sideways — dark seam lines / sky pinholes along brick
            // boundaries on distant mip-0 geometry, the CA.5 report.)
            let mut nc = cellc;
            for a in 0..3 {
                if a == best_axis || step[a] == 0 || t_max[a] > best_t {
                    continue;
                }
                // Crossings of axis `a` at t ≤ best_t: t_max[a] is the
                // next one, spaced t_delta[a] apart.
                #[allow(clippy::cast_possible_truncation)]
                let k = ((best_t - t_max[a]) / t_delta[a]) as i32 + 1;
                nc[a] += k * step[a];
                t_max[a] += k as f32 * t_delta[a];
            }
            nc[best_axis] = if step[best_axis] > 0 {
                plane[best_axis]
            } else {
                plane[best_axis] - 1
            };
            t_max[best_axis] = best_t + t_delta[best_axis];
            // The skip crossed a box boundary; if that takes the ray out
            // of the grid box it has exited (sky) — return rather than
            // clamping back in-bounds, which would spin at the edge.
            if nc[0] < lo_c[0]
                || nc[0] >= hi_c[0]
                || nc[1] < lo_c[1]
                || nc[1] >= hi_c[1]
                || nc[2] < lo_c[2]
                || nc[2] >= hi_c[2]
            {
                return finalize_exit(touched, accum, trans, env, dir, max_dist);
            }
            cellc = nc;
            // t_max was advanced per axis above (crossing counts), so
            // it is already consistent with the landing cell — no
            // position-based refresh (that reconstruction is exactly
            // the noise source this landing avoids).
            t_curr = best_t.max(t_curr);
            last_axis = best_axis;
            prev_solid = false; // skipped empty space → next hit starts a run
            continue;
        }

        // Occupied brick: dense per-cell surface test.
        #[cfg(test)]
        prof::CELLS.with(|x| x.set(x.get() + 1));
        // OC.1 — keyhole hide rule (view cutout), decided per CELL by
        // its centre (whole cubes in or out — no sub-cell fragments;
        // see [`CpuCutout`]): a HIT cell above the focus plane whose
        // centre lies inside the tapered eye→focus cone closer than
        // the character column reads as air for this PRIMARY ray only
        // (`SamplerShadow` shares `sampler.hit`, so shadows still see
        // the wall — a view aid, not CA's "world as if removed").
        // Order matters twice: the occupancy/surface test runs FIRST,
        // so the cone math (two sqrt) prices only actual solid hits —
        // never the far more numerous marched air cells above the
        // plane; and inside the filter the z compare leads, never-true
        // when the cutout is off (`cut_z_mip == i32::MIN`).
        // OC keyhole hide + FW.2 fog verdict, both evaluated only on a
        // solid hit (inside the `.filter`, after the occupancy test — the
        // "price the rule on real hits only" pattern). Review perf #2 —
        // the KEYHOLE is checked first: its cheap `cut_z_mip` gate
        // short-circuits (never-true when the cutout is off), so a hit
        // the keyhole discards never pays the fog verdict's dyn-call +
        // band scan + tile lookup. The fog verdict runs only for cells
        // the keyhole keeps, and carries into the shade branch via
        // `fow_verdict`.
        let mut fow_verdict = FowVerdict::LIVE;
        let cell_hit = sampler.hit(cellc).filter(|_| {
            let keyhole_hides = cellc[2] < cut_z_mip
                && env.cutout.is_some_and(|c| {
                    #[allow(clippy::cast_precision_loss)]
                    let pc = [
                        (cellc[0] as f32 + 0.5) * cell_size,
                        (cellc[1] as f32 + 0.5) * cell_size,
                        (cellc[2] as f32 + 0.5) * cell_size,
                    ];
                    let d = [pc[0] - origin[0], pc[1] - origin[1], pc[2] - origin[2]];
                    let along = d[0] * cut_axis[0] + d[1] * cut_axis[1] + d[2] * cut_axis[2];
                    if along <= 0.0 {
                        return false; // behind the eye
                    }
                    let d2 = d[0] * d[0] + d[1] * d[1] + d[2] * d[2];
                    let tan_c = ((d2 - along * along).max(0.0)).sqrt() / along;
                    // Radial taper: full reveal inside the inner cone,
                    // linear to zero at the outer cone (a hard edge when
                    // the two coincide — the subnormal-free max keeps the
                    // degenerate division finite).
                    let s = ((c.tan_outer - tan_c)
                        / (c.tan_outer - c.tan_inner).max(f32::MIN_POSITIVE))
                    .clamp(0.0, 1.0);
                    // Column-hugging reveal (see [`CpuCutout::margin`]):
                    // reference = the nearest character-column point at
                    // the cell's own height — the plane z (feet) mirrored
                    // around the focus gives the column top (head).
                    #[allow(clippy::cast_precision_loss)]
                    let plane = c.focus_z as f32;
                    let top = 2.0 * c.focus_local[2] - plane;
                    let rz = pc[2].clamp(top.min(plane), top.max(plane));
                    let dr = [
                        c.focus_local[0] - origin[0],
                        c.focus_local[1] - origin[1],
                        rz - origin[2],
                    ];
                    let ref_dist = (dr[0] * dr[0] + dr[1] * dr[1] + dr[2] * dr[2]).sqrt();
                    d2.sqrt() < (ref_dist - c.margin).max(0.0) * s
                });
            if keyhole_hides {
                return false;
            }
            if let Some(styler) = env.fow {
                let v = styler.verdict(
                    (cellc[0] << fow_mip_shift) + fow_mip_half,
                    (cellc[1] << fow_mip_shift) + fow_mip_half,
                    (cellc[2] << fow_mip_shift) + fow_mip_half,
                );
                fow_verdict = v;
                if matches!(v, FowVerdict::Hide) {
                    return false;
                }
            }
            true
        });
        if let Some(color) = cell_hit {
            let bright_sub = side_shade_sub(env, last_axis, step);
            // PF.7 (C4) — one colour→material scan per hit: resolve the id
            // and the material together. EV.1 hoisted this above the shade
            // so the emissive branch can bypass lighting entirely; with no
            // terrain material map the result is `OPAQUE` (emissive 0) and
            // every path below is bit-identical to the pre-material code.
            let (m, mat_id) = match env.materials {
                Some(table) if !env.terrain_materials.is_empty() => {
                    let id = material_for_color(env.terrain_materials, color);
                    (table.get(id), id)
                }
                _ => (Material::OPAQUE, 0),
            };
            // CPU.1 — dynamic lighting (flat per voxel) when a rig is active;
            // else the baked-byte `shade` path (byte-identical). CPU.2 — a
            // sun/point shadow march reuses this same `sampler` (occupancy +
            // box bounds); only built when a caster is actually flagged so
            // the no-shadow rig stays march-free. EV.1 — an emissive
            // material outranks both: full-bright albedo, no face shade,
            // no rig, no shadow march.
            // FW.2 — memory / heard cells suppress only the DYNAMIC rig
            // (a live torch never relights a remembered room), then dim +
            // desaturate below. Emissive is INTRINSIC to the material and
            // survives (a crystal the player saw glowing is remembered
            // glowing — dimmed — not as dark rock, and its baked halo on
            // the surrounding walls stays consistent: FW.2 review #6).
            // `Show { dynamic: true }` (visible, and the no-fow default
            // `LIVE`) keeps the full path bit-identical.
            let fow_dynamic = match fow_verdict {
                FowVerdict::Show { dynamic, .. } => dynamic,
                FowVerdict::Hide => true, // unreachable: Hide was filtered out
            };
            let shaded = if m.emissive > 0 {
                emissive_shade(color, m.emissive)
            } else if fow_dynamic && env.lights.enabled {
                let casts = shadow_casts;
                // Pick the shadow oracle: the scene-wide one (cross-grid +
                // sprites, XS.1) when present, else the single-grid Sampler;
                // `None` when no caster is flagged, so the rig stays
                // march-free. The two testers live in branch-local slots so
                // exactly one is borrowed for the `shade_lit_cpu` call.
                let mut world_sh;
                let mut sampler_sh;
                let tester: Option<&mut dyn ShadowTester> = if !casts {
                    None
                } else if let Some(ctx) = env.world_shadow {
                    world_sh = WorldShadow { ctx };
                    Some(&mut world_sh)
                } else {
                    sampler_sh = SamplerShadow {
                        sampler: &mut *sampler,
                        cell_size,
                        lo_c,
                        hi_c,
                        fow: env.fow,
                    };
                    Some(&mut sampler_sh)
                };
                shade_lit_cpu(
                    color,
                    bright_sub,
                    last_axis,
                    step,
                    cellc,
                    cell_size,
                    &env.lights,
                    tester,
                )
            } else {
                shade(color, bright_sub)
            };
            // FW.2 — the memory / FOV-edge taper on the surface colour,
            // BEFORE distance fog (fog is atmospheric, applied to the
            // styled surface). Identity for a full-visible cell.
            let styled = match fow_verdict {
                FowVerdict::Show {
                    dim, desaturate, ..
                } => fow_style(shaded, dim, desaturate),
                FowVerdict::Hide => shaded,
            };
            let lit = apply_fog(styled, depth.max(0.0), env);
            if m.is_opaque() {
                // Opaque surface: the background. Return the first hit verbatim
                // when nothing translucent preceded it (bit-identical), else
                // composite the accumulated layers over it.
                let color = if touched {
                    composite_over(accum, trans, lit)
                } else {
                    lit
                };
                return Some(Hit {
                    color,
                    dist: depth.max(0.0),
                });
            }
            let a = f32::from(m.alpha) / 255.0;
            if matches!(m.mode, roxlap_formats::material::BlendMode::Volumetric) {
                // Per-cell Beer–Lambert: opacity weighted by the ray's path
                // length through this voxel (so a filled volume thickens
                // smoothly with depth, a sliver contributes ≈0). Occludes.
                let t_exit = t_max[min_axis(t_max)];
                let seg_len = (t_exit - t_curr).max(0.0) * dir_len / cell_size;
                let eff_a = 1.0 - (1.0 - a).powf(seg_len);
                let c = rgb_to_f32(lit);
                accum[0] += trans * eff_a * c[0];
                accum[1] += trans * eff_a * c[1];
                accum[2] += trans * eff_a * c[2];
                trans *= 1.0 - eff_a;
                touched = true;
                prev_mat = mat_id;
                if trans < 1.0 / 256.0 {
                    return Some(Hit {
                        color: f32_to_rgb(accum),
                        dist: depth.max(0.0),
                    });
                }
            } else if !prev_solid || mat_id != prev_mat {
                // AlphaBlend / Additive: one alpha layer per solid-run entry or
                // material change (per-span — avoids the voxel-grid striping
                // through a thick glass/water slab; thickness-independent).
                let c = rgb_to_f32(lit);
                accum[0] += trans * a * c[0];
                accum[1] += trans * a * c[1];
                accum[2] += trans * a * c[2];
                if !matches!(m.mode, roxlap_formats::material::BlendMode::Additive) {
                    trans *= 1.0 - a; // AlphaBlend occludes; Additive does not.
                }
                touched = true;
                prev_mat = mat_id;
                if trans < 1.0 / 256.0 {
                    return Some(Hit {
                        color: f32_to_rgb(accum),
                        dist: depth.max(0.0),
                    });
                }
            }
            prev_solid = true;
        } else {
            prev_solid = false;
        }
        let axis = min_axis(t_max);
        last_axis = axis;
        t_curr = t_max[axis];
        cellc[axis] += step[axis];
        t_max[axis] += t_delta[axis];
    }
    None
}

/// Per-face brightness reduction for the hit face. `axis` is the axis
/// the ray crossed to enter the hit voxel (`3` = entry voxel, no face);
/// `step[axis]` gives the crossing direction. Maps to the
/// `[x-, x+, y-, y+, z-, z+]` `side_shades` entry of the face the ray
/// looks at (a `+step` crossing enters through the low / `-` face).
#[inline]
fn side_shade_sub(env: &DdaEnv<'_>, axis: usize, step: [i32; 3]) -> u32 {
    if axis >= 3 {
        return 0;
    }
    let face = axis * 2 + usize::from(step[axis] < 0);
    env.side_shades[face].max(0) as u32
}

/// Cast one ray into the grid and return the first solid hit.
///
/// **DDA.4:** cross-chunk per-pixel 3D-DDA over the grid's full voxel
/// box ([`GridView::voxel_bounds`], spanning every chunk in XY **and**
/// Z). The [`Sampler`] resolves each stepped voxel to its chunk and
/// brick-gates the slab walk. Cross-chunk look-down (the case the
/// voxlap renderer needed the whole virtual-column stack for) falls out
/// of the box simply spanning `chunks_z` along Z.
fn cast_ray(
    origin: [f32; 3],
    dir: [f32; 3],
    forward: [f32; 3],
    sampler: &mut Sampler<'_>,
    settings: &OpticastSettings,
    env: &DdaEnv<'_>,
) -> Option<Hit> {
    let (lo_i, hi_i) = sampler.grid.voxel_bounds();
    #[allow(clippy::cast_precision_loss)]
    let lo_f = [lo_i[0] as f32, lo_i[1] as f32, lo_i[2] as f32];
    #[allow(clippy::cast_precision_loss)]
    let hi_f = [hi_i[0] as f32, hi_i[1] as f32, hi_i[2] as f32];
    let (t_enter, t_exit) = intersect_aabb(origin, dir, lo_f, hi_f)?;
    let fwd_dot = dir[0] * forward[0] + dir[1] * forward[1] + dir[2] * forward[2];
    #[allow(clippy::cast_precision_loss)]
    let max_dist = settings.max_scan_dist.max(1) as f32;
    let cell = 1i32 << sampler.mip;
    let cell_size = cell as f32;
    let lo_c = [
        lo_i[0].div_euclid(cell),
        lo_i[1].div_euclid(cell),
        lo_i[2].div_euclid(cell),
    ];
    let hi_c = [
        hi_i[0].div_euclid(cell),
        hi_i[1].div_euclid(cell),
        hi_i[2].div_euclid(cell),
    ];
    cell_walk_skip(
        origin, dir, fwd_dot, sampler, lo_c, hi_c, cell_size, t_enter, t_exit, max_dist, env,
    )
}

/// Render one grid into `sink` with per-pixel 3D-DDA.
///
/// `camera` is the grid-local pose, `settings`
/// ([`OpticastSettings`]) carries the projection + viewport (including
/// the `y_start..y_end` strip bound), and `grid` is the per-frame
/// [`GridView`] borrow. `pitch_pixels` is the framebuffer
/// row stride in pixels (matches `ScalarRasterizer::new`'s argument).
///
/// On a miss, a textured sky ([`DdaEnv::sky`]) is sampled per ray
/// direction and written at `+inf` depth; with no textured sky the miss
/// writes nothing, so the caller's solid sky pre-fill shows (the
/// `render_scene_composed` path pre-fills it).
pub fn render_dda(
    camera: &Camera,
    settings: &OpticastSettings,
    grid: GridView<'_>,
    pitch_pixels: usize,
    env: &DdaEnv<'_>,
    mip: u32,
    sink: &mut impl PixelSink,
) {
    let cs = camera_math::derive(
        camera,
        settings.xres,
        settings.yres,
        settings.hx,
        settings.hy,
        settings.hz,
    );

    // Sequential path builds a throwaway per-call cache (tests / single
    // grid). The parallel path takes a persistent cross-frame cache.
    let (cache, mip) = local_cache(&grid, mip);
    let mut sampler = Sampler::new(grid, &cache, mip, env.z_clip);

    for py in settings.y_start..settings.y_end {
        let row = py as usize * pitch_pixels;
        for px in settings.x_start..settings.x_end {
            if let Some((color, dist)) = pixel_result(&cs, settings, &mut sampler, env, px, py) {
                sink.put(row + px as usize, color, dist);
            }
        }
    }
}

/// Resolve one pixel: a shaded + fogged hit colour, a sampled textured
/// sky on a miss, or `None` (miss with no textured sky → caller's
/// pre-fill stands). Shared by the sequential ([`render_dda`]) and
/// parallel ([`render_dda_parallel`]) drivers. The OC keyhole needs no
/// per-pixel work here: the hide rule classifies whole CELLS in the
/// hit branch (see [`CpuCutout`]).
#[inline]
fn pixel_result(
    cs: &CameraState,
    settings: &OpticastSettings,
    sampler: &mut Sampler<'_>,
    env: &DdaEnv<'_>,
    px: u32,
    py: u32,
) -> Option<(u32, f32)> {
    let (origin, dir) = pixel_ray(cs, settings, px, py);
    if let Some(hit) = cast_ray(origin, dir, cs.forward, sampler, settings, env) {
        Some((hit.color, hit.dist))
    } else {
        env.sky.map(|sky| (sample_sky(sky, dir), f32::INFINITY))
    }
}

/// Tile-parallel [`render_dda`] writing straight into `(fb, zb)`.
///
/// DDA pixels are independent, so the framebuffer splits into disjoint
/// horizontal bands rendered concurrently (rayon) — **bit-identical**
/// to the sequential render regardless of thread count, unlike voxlap's
/// per-strip discretisation. Each band spins up its own lightweight
/// `Sampler` over the shared, immutable `cache`.
///
/// `cache` must already hold current brick maps for every chunk at
/// `mip` (populate via [`BrickCache::ensure`]); `mip` is the effective
/// render mip ([`effective_mip`]). `(fb, zb)` use the standard
/// conventions (`0x80RRGGBB`; z = perp distance, smaller = closer); a
/// miss writes nothing unless [`DdaEnv::sky`] is set. `pitch_pixels` is
/// the row stride.
#[allow(clippy::cast_possible_truncation, clippy::too_many_arguments)]
pub fn render_dda_parallel(
    camera: &Camera,
    settings: &OpticastSettings,
    grid: GridView<'_>,
    fb: &mut [u32],
    zb: &mut [f32],
    pitch_pixels: usize,
    env: &DdaEnv<'_>,
    cache: &BrickCache,
    mip: u32,
) {
    debug_assert_eq!(fb.len(), zb.len());
    let (y0, y1) = (settings.y_start, settings.y_end);
    if y1 <= y0 {
        return;
    }
    let cs = camera_math::derive(
        camera,
        settings.xres,
        settings.yres,
        settings.hx,
        settings.hy,
        settings.hz,
    );
    let target = RasterTarget::new(fb, zb);

    // PF.7 (C5) — small fixed bands + rayon work-stealing instead of one
    // equal band per thread: sky-heavy rows finish instantly while
    // horizon/terrain rows dominate, so an equal split left threads idle
    // for the tail of every frame. 8 rows amortises the per-band
    // `Sampler` construction while staying fine-grained enough to
    // balance. Bit-identical (pixels are independent; rows disjoint).
    let band = 8u32;
    let bands: Vec<(u32, u32)> = (y0..y1)
        .step_by(band as usize)
        .map(|s| (s, (s + band).min(y1)))
        .collect();

    bands.par_iter().for_each(|&(by0, by1)| {
        let mut sampler = Sampler::new(grid, cache, mip, env.z_clip);
        for py in by0..by1 {
            let row = py as usize * pitch_pixels;
            for px in settings.x_start..settings.x_end {
                if let Some((color, dist)) = pixel_result(&cs, settings, &mut sampler, env, px, py)
                {
                    let idx = row + px as usize;
                    // SAFETY: bands cover disjoint row ranges, so writes
                    // never alias across threads; `idx` is in-bounds for
                    // a `pitch * height`-sized buffer.
                    unsafe {
                        target.write_color(idx, color);
                        target.write_depth(idx, dist);
                    }
                }
            }
        }
    });
}

/// Dense per-voxel reference cast for a **single-chunk** grid: walks
/// every voxel of `[0, vsid)² × [0, CHUNK_SIZE_Z)` calling
/// [`GridView::surface_color`] directly — no brick gate, no chunk
/// resolution. The equivalence oracle the brickmap + sampler
/// [`cast_ray`] is checked against in tests.
#[cfg(test)]
#[allow(clippy::cast_precision_loss, clippy::cast_possible_truncation)]
fn cast_ray_reference(
    origin: [f32; 3],
    dir: [f32; 3],
    forward: [f32; 3],
    grid: &GridView<'_>,
    settings: &OpticastSettings,
) -> Option<Hit> {
    let nx = grid.vsid as f32;
    let nz = f32::from(u16::try_from(crate::grid_view::CHUNK_SIZE_Z).unwrap_or(256));
    #[allow(clippy::cast_possible_wrap)]
    let n_i = [
        grid.vsid as i32,
        grid.vsid as i32,
        crate::grid_view::CHUNK_SIZE_Z as i32,
    ];
    let (t_enter, t_exit) = intersect_aabb(origin, dir, [0.0; 3], [nx, nx, nz])?;
    let fwd_dot = dir[0] * forward[0] + dir[1] * forward[1] + dir[2] * forward[2];
    let max_dist = settings.max_scan_dist.max(1) as f32;

    let start = t_enter + 1e-4;
    let p = [
        origin[0] + dir[0] * start,
        origin[1] + dir[1] * start,
        origin[2] + dir[2] * start,
    ];
    let mut voxel = [
        (p[0].floor() as i32).clamp(0, n_i[0] - 1),
        (p[1].floor() as i32).clamp(0, n_i[1] - 1),
        (p[2].floor() as i32).clamp(0, n_i[2] - 1),
    ];
    let (step, mut t_max, t_delta) = dda_setup(origin, dir, voxel, 1.0);
    let mut t_curr = t_enter;
    let max_steps = (n_i[0] + n_i[1] + n_i[2]) as usize + 8;
    for _ in 0..max_steps {
        if voxel[0] < 0
            || voxel[0] >= n_i[0]
            || voxel[1] < 0
            || voxel[1] >= n_i[1]
            || voxel[2] < 0
            || voxel[2] >= n_i[2]
        {
            return None;
        }
        let depth = t_curr * fwd_dot;
        if depth > max_dist || t_curr > t_exit {
            return None;
        }
        #[allow(clippy::cast_sign_loss)]
        if let Some(color) = grid.surface_color(voxel[0] as u32, voxel[1] as u32, voxel[2] as u32) {
            return Some(Hit {
                color: shade(color.0, 0),
                dist: depth.max(0.0),
            });
        }
        let axis = min_axis(t_max);
        t_curr = t_max[axis];
        voxel[axis] += step[axis];
        t_max[axis] += t_delta[axis];
    }
    None
}

#[cfg(test)]
mod tests {
    use super::*;
    use roxlap_formats::VoxColor;

    // CPU.1 — luminance of a packed colour's low-24-bit RGB.
    fn lum(p: u32) -> u32 {
        (p & 0xff) + ((p >> 8) & 0xff) + ((p >> 16) & 0xff)
    }

    #[test]
    fn cel_band_quantizes_and_collapses() {
        // Two distinct factors round to the same band at bands=2.
        assert_eq!(cel_band(0.8, 2), cel_band(0.9, 2));
        assert!((cel_band(0.8, 2) - 1.0).abs() < 1e-6);
        // ...but a low factor lands on a different band.
        assert_ne!(cel_band(0.3, 2), cel_band(0.8, 2));
    }

    #[test]
    fn shade_lit_cpu_sun_lights_by_facing() {
        // Grey voxel (brightness 0x80 = full ambient). Floor top face: hit via
        // a +z step (axis 2) ⇒ normal points up (-z).
        let color = 0x80_80_80_80;
        let step = [0, 0, 1];
        let base = CpuLights {
            enabled: true,
            sun: true,
            sun_color: [1.0; 3],
            sun_intensity: 1.0,
            ambient: [0.2; 3],
            ..CpuLights::default()
        };
        let facing = CpuLights {
            sun_dir: [0.0, 0.0, -1.0],
            ..base
        }; // toward sun = up
        let back = CpuLights {
            sun_dir: [0.0, 0.0, 1.0],
            ..base
        }; // sun below the face
        let lit = shade_lit_cpu(color, 0, 2, step, [0, 0, 0], 1.0, &facing, None);
        let dark = shade_lit_cpu(color, 0, 2, step, [0, 0, 0], 1.0, &back, None);
        assert!(
            lum(lit) > lum(dark),
            "sun facing the surface must brighten it: {lit:#08x} vs {dark:#08x}",
        );
    }

    #[test]
    fn shade_dynamic_spot_cone_masks_off_axis() {
        // Surface at the origin, up-facing normal (-z, voxlap z-down); a light
        // 10 units "above" it (at -z). No ambient/AO ⇒ only the light shows.
        let albedo = [0.5, 0.5, 0.5];
        let n = [0.0, 0.0, -1.0];
        let sample = [0.0, 0.0, 0.0];
        let inner = 10.0f32.to_radians().cos();
        let outer = 15.0f32.to_radians().cos();
        let shade = |spot_dir: [f32; 3], cos_inner: f32, cos_outer: f32| {
            let pts = [CpuPointLight {
                pos: [0.0, 0.0, -10.0],
                color: [1.0; 3],
                intensity: 1.0,
                radius: 64.0,
                casts_shadow: false,
                spot_dir,
                cos_inner,
                cos_outer,
            }];
            let l = CpuLights {
                enabled: true,
                ambient: [0.0; 3],
                points: &pts,
                ..CpuLights::default()
            };
            shade_dynamic(albedo, 0.0, n, sample, &l, None)
        };
        // A pure point light (cos_outer = -1) ignores the axis entirely.
        let point = shade([0.0, 0.0, 1.0], -1.0, -1.0);
        // A spot whose axis shines straight down onto the surface (on-axis).
        let on_axis = shade([0.0, 0.0, 1.0], inner, outer);
        // Same spot aimed sideways ⇒ the surface is outside the cone.
        let off_axis = shade([1.0, 0.0, 0.0], inner, outer);

        // On-axis (cd == 1) is fully inside the cone ⇒ identical to a point.
        assert_eq!(
            on_axis, point,
            "on-axis spot must equal the point light: {on_axis:#08x} vs {point:#08x}",
        );
        // Off-axis is masked to zero ⇒ only the (zero) ambient remains.
        assert!(
            lum(on_axis) > lum(off_axis),
            "off-axis spot must be darker: {on_axis:#08x} vs {off_axis:#08x}",
        );
        assert_eq!(lum(off_axis), 0, "off-cone spot contributes nothing");
    }

    #[test]
    fn shade_lit_cpu_cel_terraces_sun() {
        // Two sun elevations with distinct N·L (0.8 / 0.9) collapse to one
        // band at bands=2 ⇒ identical stylized colour; smooth (bands=0) differs.
        let color = 0x80_80_80_80;
        let step = [0, 0, 1];
        let mk = |zc: f32, bands: u32| {
            let n = (1.0f32 - zc * zc).sqrt();
            CpuLights {
                enabled: true,
                sun: true,
                sun_dir: [n, 0.0, -zc], // ndl on the up face = zc
                sun_color: [1.0; 3],
                sun_intensity: 1.0,
                ambient: [0.1; 3],
                bands,
                ..CpuLights::default()
            }
        };
        let smooth_a = shade_lit_cpu(color, 0, 2, step, [0, 0, 0], 1.0, &mk(0.8, 0), None);
        let smooth_b = shade_lit_cpu(color, 0, 2, step, [0, 0, 0], 1.0, &mk(0.9, 0), None);
        assert_ne!(smooth_a, smooth_b, "smooth diffuse must vary with N·L");
        let cel_a = shade_lit_cpu(color, 0, 2, step, [0, 0, 0], 1.0, &mk(0.8, 2), None);
        let cel_b = shade_lit_cpu(color, 0, 2, step, [0, 0, 0], 1.0, &mk(0.9, 2), None);
        assert_eq!(
            cel_a, cel_b,
            "cel banding must terrace both N·L to one level"
        );
    }

    /// CPU.2 — the shadow application math (independent of the march): an
    /// occluded sun-lit sample keeps only `1 - shadow_strength` of the sun
    /// key, and `shadow_strength == 0` makes shadows invisible.
    #[test]
    fn shade_dynamic_sun_shadow_darkens() {
        struct Mock(bool);
        impl ShadowTester for Mock {
            fn occluded(&mut self, _: [f32; 3], _: [f32; 3], _: f32) -> bool {
                self.0
            }
        }
        let l = CpuLights {
            enabled: true,
            sun: true,
            sun_dir: [0.0, 0.0, -1.0], // up = toward the sun
            sun_color: [1.0; 3],
            sun_intensity: 1.0,
            sun_casts_shadow: true,
            ambient: [0.2; 3],
            shadow_strength: 0.7,
            shadow_bias: 1.5,
            shadow_max_dist: 64.0,
            ..CpuLights::default()
        };
        let albedo = [0.8; 3];
        let n = [0.0, 0.0, -1.0]; // up face, faces the sun
        let s = [0.5, 0.5, 0.5];
        let lit = shade_dynamic(albedo, 1.0, n, s, &l, Some(&mut Mock(false)));
        let shadowed = shade_dynamic(albedo, 1.0, n, s, &l, Some(&mut Mock(true)));
        assert!(
            lum(shadowed) < lum(lit),
            "an occluded sun face must darken: shadowed={shadowed:#08x} lit={lit:#08x}",
        );
        // strength 0 ⇒ no visible shadow even when occluded.
        let l0 = CpuLights {
            shadow_strength: 0.0,
            ..l
        };
        assert_eq!(
            shade_dynamic(albedo, 1.0, n, s, &l0, Some(&mut Mock(true))),
            shade_dynamic(albedo, 1.0, n, s, &l0, Some(&mut Mock(false))),
            "shadow_strength 0 ⇒ shadows invisible",
        );
    }

    /// CPU.2 — the actual [`SamplerShadow`] march casts a sun shadow through
    /// the grid: a wall on a floor, lit by a grazing sun, darkens the floor
    /// in the wall's shadow. Total scene luminance with shadows enabled is
    /// strictly less than with them off (shadows only ever subtract), and
    /// the gap is non-trivial (a real shadow, not FP noise).
    #[test]
    fn sampler_shadow_march_casts_sun_shadow() {
        // Floor at z>=60; a thin wall at x==32 rising from the floor (z 30..60).
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |x, _y, z| {
            if z >= 60 {
                Some(VoxColor(0x80_80_80_80)) // floor
            } else if x == 32 && (30..60).contains(&z) {
                Some(VoxColor(0x80_70_70_70)) // wall (distinct so it's not a dead branch)
            } else {
                None
            }
        });
        let grid = GridView::from_single_vxl(&vxl);
        // Straight-down camera over the floor (voxlap z-down: forward = +z).
        let cam = Camera {
            pos: [32.0, 32.0, 6.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        // Sun grazing from +x and above ⇒ the wall shadows the floor at x<32.
        let inv = 1.0f32 / 2.0f32.sqrt();
        let base = CpuLights {
            enabled: true,
            sun: true,
            sun_dir: [inv, 0.0, -inv],
            sun_color: [1.0; 3],
            sun_intensity: 1.0,
            ambient: [0.25; 3],
            shadow_strength: 0.8,
            shadow_bias: 1.5,
            shadow_max_dist: 128.0,
            ..CpuLights::default()
        };
        let (w, h) = (96u32, 96u32);
        let lit_env = DdaEnv {
            lights: CpuLights {
                sun_casts_shadow: false,
                ..base
            },
            ..DdaEnv::default()
        };
        let shadow_env = DdaEnv {
            lights: CpuLights {
                sun_casts_shadow: true,
                ..base
            },
            ..DdaEnv::default()
        };
        let (fb_lit, _) = render_brickmap_env(grid, &cam, w, h, &lit_env);
        let (fb_sh, _) = render_brickmap_env(grid, &cam, w, h, &shadow_env);
        let sum: fn(&[u32]) -> u64 = |fb| fb.iter().map(|&p| u64::from(lum(p))).sum();
        let lit_sum = sum(&fb_lit);
        let sh_sum = sum(&fb_sh);
        assert!(
            sh_sum < lit_sum,
            "the wall's shadow must darken the floor: shadow_sum={sh_sum} lit_sum={lit_sum}",
        );
        // Non-trivial: at least a few % of the lit total was removed.
        assert!(
            (lit_sum - sh_sum) * 50 > lit_sum,
            "shadow should remove >2% of total luminance: lit={lit_sum} shadow={sh_sum}",
        );
    }

    /// CA.2 — "world as if removed": a clipped-away deck neither
    /// renders NOR casts sun shadows. The render of a roofed fixture
    /// with the roof clipped must be byte-identical to a fixture with
    /// no roof at all (same camera, same shadowing sun) — primary rays
    /// (CA.1) and the [`SamplerShadow`] march (this substage) both see
    /// air above the plane, even though the roof's bricks are still
    /// occupancy-occupied.
    #[test]
    fn cutaway_hidden_deck_neither_renders_nor_shadows() {
        const ROOF: VoxColor = VoxColor(0x80_A0_50_20);
        const FLOOR: VoxColor = VoxColor(0x80_80_80_80);
        let roofed = roxlap_formats::vxl::Vxl::from_dense(64, |_, _, z| {
            if z == 20 {
                Some(ROOF)
            } else if z >= 60 {
                Some(FLOOR)
            } else {
                None
            }
        });
        let roofless =
            roxlap_formats::vxl::Vxl::from_dense(64, |_, _, z| (z >= 60).then_some(FLOOR));
        let g_roofed = GridView::from_single_vxl(&roofed);
        let g_roofless = GridView::from_single_vxl(&roofless);
        let cam = Camera {
            pos: [32.0, 32.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 lights = CpuLights {
            enabled: true,
            sun: true,
            sun_dir: [inv, 0.0, -inv],
            sun_color: [1.0; 3],
            sun_intensity: 1.0,
            sun_casts_shadow: true,
            ambient: [0.25; 3],
            shadow_strength: 0.8,
            shadow_bias: 1.5,
            shadow_max_dist: 128.0,
            ..CpuLights::default()
        };
        let (w, h) = (64u32, 64u32);
        let env_clipped = DdaEnv {
            lights,
            z_clip: Some(40),
            ..DdaEnv::default()
        };
        let env_plain = DdaEnv {
            lights,
            ..DdaEnv::default()
        };
        let (fb_clip, zb_clip) = render_brickmap_env(g_roofed, &cam, w, h, &env_clipped);
        let (fb_ref, zb_ref) = render_brickmap_env(g_roofless, &cam, w, h, &env_plain);
        assert_eq!(
            fb_clip, fb_ref,
            "clipped roof must render AND shadow exactly like no roof"
        );
        assert_eq!(zb_clip, zb_ref);
        // Negative control: unclipped, the camera sees the roof instead.
        let (fb_roof, _) = render_brickmap_env(g_roofed, &cam, w, h, &env_plain);
        assert_ne!(fb_roof, fb_ref, "unclipped roof must be visible");
    }

    /// Recording sink: collects `(idx, color, dist)` puts for tests.
    #[derive(Default)]
    struct Recorder {
        puts: Vec<(usize, u32, f32)>,
    }
    impl PixelSink for Recorder {
        fn put(&mut self, idx: usize, color: u32, dist: f32) {
            self.puts.push((idx, color, dist));
        }
    }

    fn oracle_camera() -> Camera {
        // Identity-basis camera at origin: ray math is integer-exact.
        Camera {
            pos: [0.0, 0.0, 0.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        }
    }

    /// Render `grid` from `camera` into a `w × h` framebuffer and
    /// return the per-pixel hit mask (`true` where a ray hit a voxel).
    fn render_mask(grid: GridView<'_>, camera: &Camera, w: u32, h: u32) -> Vec<bool> {
        let n = (w as usize) * (h as usize);
        let mut fb = vec![0u32; n]; // sky sentinel = 0
        let mut zb = vec![f32::INFINITY; n];
        let settings = OpticastSettings::for_oracle_framebuffer(w, h);
        {
            let mut sink = RasterSink::new(&mut fb, &mut zb);
            render_dda(
                camera,
                &settings,
                grid,
                w as usize,
                &DdaEnv::default(),
                0,
                &mut sink,
            );
        }
        fb.iter().map(|&c| c != 0).collect()
    }

    /// A silhouette is "row-convex" if every framebuffer row's hit
    /// pixels form a single contiguous run (no interior gap). The
    /// voxlap silhouette notch is exactly such an interior gap, so this
    /// is the headline DDA.1 acceptance check.
    fn rows_have_no_holes(mask: &[bool], w: u32, h: u32) -> bool {
        let w = w as usize;
        for y in 0..h as usize {
            let row = &mask[y * w..(y + 1) * w];
            let first = row.iter().position(|&b| b);
            let last = row.iter().rposition(|&b| b);
            if let (Some(f), Some(l)) = (first, last) {
                if row[f..=l].iter().any(|&b| !b) {
                    return false;
                }
            }
        }
        true
    }

    /// Same contiguity check down each column.
    fn cols_have_no_holes(mask: &[bool], w: u32, h: u32) -> bool {
        let w = w as usize;
        let h = h as usize;
        for x in 0..w {
            let col: Vec<bool> = (0..h).map(|y| mask[y * w + x]).collect();
            let first = col.iter().position(|&b| b);
            let last = col.iter().rposition(|&b| b);
            if let (Some(f), Some(l)) = (first, last) {
                if col[f..=l].iter().any(|&b| !b) {
                    return false;
                }
            }
        }
        true
    }

    /// The principal-point pixel `(hx, hy)` looks straight down the
    /// forward axis, scaled by `hz`.
    #[test]
    fn center_pixel_ray_is_forward() {
        let settings = OpticastSettings::for_oracle_framebuffer(640, 480);
        let cs = camera_math::derive(&oracle_camera(), 640, 480, 320.0, 240.0, 320.0);
        // hx = hy = 320 / 240 → use the exact principal point.
        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
        let (origin, dir) = pixel_ray(&cs, &settings, settings.hx as u32, settings.hy as u32);
        assert_eq!(origin, [0.0, 0.0, 0.0]);
        // hz·forward = 320·[0,1,0].
        assert_eq!(
            dir.map(f32::to_bits),
            [0.0f32, 320.0, 0.0].map(f32::to_bits)
        );
    }

    /// Pixel `(0, 0)`'s ray equals `camera_math`'s `corn[0]` — proving
    /// the DDA renderer samples the same rays the voxlap frustum is
    /// built from.
    #[test]
    fn corner_pixel_ray_matches_camera_corn0() {
        let settings = OpticastSettings::for_oracle_framebuffer(640, 480);
        let cs = camera_math::derive(&oracle_camera(), 640, 480, 320.0, 240.0, 320.0);
        let (_origin, dir) = pixel_ray(&cs, &settings, 0, 0);
        assert_eq!(dir.map(f32::to_bits), cs.corn[0].map(f32::to_bits));
    }

    /// The renderer's independent slab decoder
    /// ([`GridView::voxel_color`]) must agree with the reference
    /// [`roxlap_formats::vxl::Vxl::voxel_color`] for every cell —
    /// including a column with an air gap, which exercises the
    /// ceiling-colour-list branch.
    #[test]
    fn gridview_voxel_color_matches_reference() {
        // Two solid runs per column separated by air → ceiling list.
        let vxl = roxlap_formats::vxl::Vxl::from_dense(8, |x, _, z| {
            let lo = (10..=12).contains(&z);
            let hi = (40..=42).contains(&z);
            (lo || hi).then_some(VoxColor(0x80_10_20_30 + x))
        });
        let grid = GridView::from_single_vxl(&vxl);
        for x in 0..8 {
            for y in 0..8 {
                for z in 0..64 {
                    assert_eq!(
                        grid.voxel_color(x, y, z),
                        vxl.voxel_color(x, y, z),
                        "mismatch at ({x},{y},{z})"
                    );
                }
            }
        }
    }

    /// An all-air grid produces no hits (every ray misses).
    #[test]
    fn empty_grid_no_hits() {
        let vxl = roxlap_formats::vxl::Vxl::empty(64);
        let grid = GridView::from_single_vxl(&vxl);
        let settings = OpticastSettings::for_oracle_framebuffer(64, 48);
        let mut rec = Recorder::default();
        render_dda(
            &oracle_camera(),
            &settings,
            grid,
            64,
            &DdaEnv::default(),
            0,
            &mut rec,
        );
        assert!(rec.puts.is_empty(), "all-air grid must produce no hits");
    }

    /// Camera above a solid floor, looking straight down: every ray
    /// hits, the recovered colour is the floor colour, and the centre
    /// pixel's depth ≈ the camera's height above the floor.
    #[test]
    fn floor_seen_from_above() {
        const FLOOR_Z: u32 = 40;
        const FLOOR_COL: VoxColor = VoxColor(0x80_30_60_90);
        let vxl =
            roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| (z >= FLOOR_Z).then_some(FLOOR_COL));
        let grid = GridView::from_single_vxl(&vxl);

        // Eye above the floor (z is down), looking down (+z).
        let cam = Camera {
            pos: [16.0, 16.0, 10.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(48, 48);
        let mut rec = Recorder::default();
        render_dda(&cam, &settings, grid, 48, &DdaEnv::default(), 0, &mut rec);

        assert!(!rec.puts.is_empty(), "floor must be visible");
        // Centre pixel looks straight down → depth ≈ FLOOR_Z - eye_z.
        let centre = 24usize * 48 + 24;
        let hit = rec
            .puts
            .iter()
            .find(|(idx, _, _)| *idx == centre)
            .expect("centre ray must hit the floor");
        assert_eq!(hit.1 & 0x00ff_ffff, FLOOR_COL.0 & 0x00ff_ffff);
        let expected = (FLOOR_Z as f32) - 10.0;
        assert!(
            (hit.2 - expected).abs() < 1.5,
            "centre depth {} not ≈ {}",
            hit.2,
            expected
        );
    }

    /// DDA.2: a camera looking at the horizon splits the frame into
    /// sky (upward rays miss → no write) and floor (downward rays hit).
    /// The top of the frame must be mostly sky, the bottom mostly
    /// floor.
    #[test]
    fn horizon_splits_sky_and_floor() {
        const FLOOR_Z: u32 = 40;
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |_, _, z| {
            (z >= FLOOR_Z).then_some(VoxColor(0x80_44_66_88))
        });
        let grid = GridView::from_single_vxl(&vxl);

        // At z=30 (above the z=40 floor), looking +y horizontally,
        // down = +z. Upward rays (low py) escape through the box top
        // (z=0) → sky; downward rays (high py) strike the floor.
        let cam = Camera {
            pos: [32.0, 4.0, 30.0],
            right: [-1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };
        let (w, h) = (64u32, 64u32);
        let mask = render_mask(grid, &cam, w, h);

        let count_band = |y0: usize, y1: usize| -> usize {
            (y0 * w as usize..y1 * w as usize)
                .filter(|&i| mask[i])
                .count()
        };
        let top = count_band(0, h as usize / 4);
        let bottom = count_band(3 * h as usize / 4, h as usize);
        assert!(mask.iter().any(|&b| b), "floor must be visible");
        assert!(mask.iter().any(|&b| !b), "sky must be visible");
        assert!(
            bottom > top,
            "bottom band ({bottom}) should hit more floor than top band ({top})"
        );
    }

    /// Render `grid` from `camera` with the dense reference cast (no
    /// brickmap), returning `(colour, depth)` buffers.
    fn render_reference(
        grid: GridView<'_>,
        camera: &Camera,
        w: u32,
        h: u32,
    ) -> (Vec<u32>, Vec<f32>) {
        let n = (w as usize) * (h as usize);
        let mut fb = vec![0u32; n];
        let mut zb = vec![f32::INFINITY; n];
        let settings = OpticastSettings::for_oracle_framebuffer(w, h);
        let cs = camera_math::derive(camera, w, h, settings.hx, settings.hy, settings.hz);
        for py in 0..h {
            for px in 0..w {
                let (o, d) = pixel_ray(&cs, &settings, px, py);
                if let Some(hit) = cast_ray_reference(o, d, cs.forward, &grid, &settings) {
                    let i = (py * w + px) as usize;
                    fb[i] = hit.color;
                    zb[i] = hit.dist;
                }
            }
        }
        (fb, zb)
    }

    /// Render `grid` from `camera` via the production brickmap path.
    fn render_brickmap(
        grid: GridView<'_>,
        camera: &Camera,
        w: u32,
        h: u32,
    ) -> (Vec<u32>, Vec<f32>) {
        render_brickmap_env(grid, camera, w, h, &DdaEnv::default())
    }

    /// As [`render_brickmap`] but with an explicit [`DdaEnv`] (fog /
    /// textured sky / side shades).
    fn render_brickmap_env(
        grid: GridView<'_>,
        camera: &Camera,
        w: u32,
        h: u32,
        env: &DdaEnv<'_>,
    ) -> (Vec<u32>, Vec<f32>) {
        let n = (w as usize) * (h as usize);
        let mut fb = vec![0u32; n];
        let mut zb = vec![f32::INFINITY; n];
        let settings = OpticastSettings::for_oracle_framebuffer(w, h);
        {
            let mut sink = RasterSink::new(&mut fb, &mut zb);
            render_dda(camera, &settings, grid, w as usize, env, 0, &mut sink);
        }
        (fb, zb)
    }

    /// Regression for the cave-demo "bright sky seams" report: the
    /// empty-space-skip walk must not leak past an occupied box the ray
    /// only grazes at a shared edge/corner. A 1-voxel-thick diagonal
    /// wall (`x+y==64`, voxels edge-connected) with air on both sides is
    /// the canonical case. The production skip walk must hit exactly the
    /// same pixels as the dense per-cell reference — zero divergence.
    #[test]
    fn no_sky_leak_through_diagonal_wall() {
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |x, y, z| {
            ((x + y == 64) && (2..62).contains(&z)).then_some(VoxColor(0x80_40_80_60))
        });
        let grid = GridView::from_single_vxl(&vxl);
        let (w, h) = (160u32, 160u32);
        let c = [10.0, 10.0, 32.0];
        let poses = [
            Camera::from_yaw_pitch(c, 0.785, 0.0),
            Camera::from_yaw_pitch(c, 0.6, 0.1),
            Camera::from_yaw_pitch(c, 0.95, -0.1),
            Camera::from_yaw_pitch(c, 0.785, 0.3),
            Camera::from_yaw_pitch(c, 0.5, 0.0),
        ];
        for (i, cam) in poses.iter().enumerate() {
            let (fb_b, _) = render_brickmap(grid, cam, w, h);
            let (fb_r, _) = render_reference(grid, cam, w, h);
            let leak = (0..(w * h) as usize)
                .filter(|&k| (fb_b[k] != 0) != (fb_r[k] != 0))
                .count();
            assert_eq!(leak, 0, "pose {i}: {leak} px diverge from dense reference");
        }
    }

    /// TV terrain transparency: a glass-coloured voxel slab in front of an
    /// opaque floor. With no terrain material map the glass is an opaque first
    /// hit; with the map it becomes translucent and the floor tints through.
    #[test]
    fn terrain_glass_tints_floor_behind() {
        let glass = VoxColor(0x80_40_C0_E0); // cyan
        let floor = VoxColor(0x80_C0_40_40); // red
        let vxl = roxlap_formats::vxl::Vxl::from_dense(16, |_, _, z| {
            if z == 4 {
                Some(glass)
            } else if z >= 10 {
                Some(floor)
            } else {
                None
            }
        });
        let grid = GridView::from_single_vxl(&vxl);
        // Camera above the grid looking straight down (+z), centred.
        let cam = Camera {
            pos: [8.0, 8.0, 0.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (32u32, 32u32);
        let centre = (h / 2 * w + w / 2) as usize;

        // Opaque: the glass voxel stops the ray (no terrain materials).
        let (fb_op, _) = render_brickmap(grid, &cam, w, h);
        assert_eq!(
            fb_op[centre] & 0x00ff_ffff,
            0x0040_C0E0,
            "opaque glass first-hit"
        );

        // Translucent: glass colour → material 1 (alpha-blend).
        let mut table = MaterialTable::new();
        table.set(1, Material::alpha_blend(128));
        let env = DdaEnv {
            materials: Some(&table),
            terrain_materials: &[(glass.rgb_part(), 1)],
            lights: CpuLights::default(),
            ..DdaEnv::default()
        };
        let (fb_tr, _) = render_brickmap_env(grid, &cam, w, h, &env);
        assert_ne!(
            fb_tr[centre], fb_op[centre],
            "glass should composite over the floor, not stay opaque"
        );
        let r_op = (fb_op[centre] >> 16) & 0xff; // glass red ≈ 0x40
        let r_tr = (fb_tr[centre] >> 16) & 0xff; // + floor red bleeds in
        assert!(
            r_tr > r_op,
            "floor red tints through the glass (op={r_op:02x} tr={r_tr:02x})"
        );
    }

    /// EV.1 — an emissive terrain voxel renders at over-bright albedo,
    /// ignoring the baked brightness byte, per-face side shades and the
    /// dynamic light rig.
    #[test]
    fn terrain_emissive_ignores_lighting() {
        let crystal = VoxColor(0x40_20_60_80); // deliberately DIM baked byte 0x40
        let vxl =
            roxlap_formats::vxl::Vxl::from_dense(
                16,
                |_, _, z| if z >= 4 { Some(crystal) } else { None },
            );
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [8.0, 8.0, 0.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (32u32, 32u32);
        let centre = (h / 2 * w + w / 2) as usize;

        // Control: the baked 0x40 byte halves the albedo.
        let (fb_dim, _) = render_brickmap(grid, &cam, w, h);
        assert_eq!(
            fb_dim[centre] & 0x00ff_ffff,
            0x0010_3040,
            "baked byte 0x40 = albedo/2"
        );

        // Emissive: glow(255) ⇒ ×255/128 over-bright, per-channel clamp.
        let mut table = MaterialTable::new();
        table.set(1, Material::glow(255));
        let base = DdaEnv {
            materials: Some(&table),
            terrain_materials: &[(crystal.rgb_part(), 1)],
            ..DdaEnv::default()
        };
        let (fb_em, _) = render_brickmap_env(grid, &cam, w, h, &base);
        assert_eq!(
            fb_em[centre] & 0x00ff_ffff,
            0x003f_bfff,
            "glow(255) ≈ 2× albedo (0x20,0x60,0x80 → 0x3f,0xbf,0xff)"
        );

        // Max side shades: a normal voxel darkens, an emissive one must not.
        let shaded_env = DdaEnv {
            side_shades: [64; 6],
            ..DdaEnv::default()
        };
        let (fb_ss_plain, _) = render_brickmap_env(grid, &cam, w, h, &shaded_env);
        assert_ne!(
            fb_ss_plain[centre], fb_dim[centre],
            "control: side shades darken a non-emissive voxel"
        );
        let em_ss = DdaEnv {
            side_shades: [64; 6],
            ..base
        };
        let (fb_em_ss, _) = render_brickmap_env(grid, &cam, w, h, &em_ss);
        assert_eq!(
            fb_em_ss[centre], fb_em[centre],
            "side shades must not touch an emissive voxel"
        );

        // Dynamic rig active (no sun, zero ambient ⇒ a normal voxel goes
        // black): the emissive voxel is rig-independent.
        let em_rig = DdaEnv {
            lights: CpuLights {
                enabled: true,
                ..CpuLights::default()
            },
            ..base
        };
        let (fb_em_rig, _) = render_brickmap_env(grid, &cam, w, h, &em_rig);
        assert_eq!(
            fb_em_rig[centre], fb_em[centre],
            "the dynamic rig must not touch an emissive voxel"
        );
    }

    /// TV terrain Volumetric: a **filled** grey smoke volume over a red floor.
    /// Beer–Lambert opacity grows with the ray's path length, so a deeper smoke
    /// column shows more of its own colour (green channel rises toward the
    /// smoke grey) — thickness-dependent, unlike per-span AlphaBlend.
    #[test]
    fn terrain_volumetric_thickness_deepens_opacity() {
        let smoke = VoxColor(0x80_90_90_90); // grey
        let floor = VoxColor(0x80_C0_20_20); // red (low green)
                                             // Centre green channel for a smoke column `depth` voxels deep (filled),
                                             // floor at z>=12, camera looking straight down.
        let green_at = |depth: u32| -> u32 {
            let vxl = roxlap_formats::vxl::Vxl::from_dense(16, |_, _, z| {
                if (4..4 + depth).contains(&z) {
                    Some(smoke)
                } else if z >= 12 {
                    Some(floor)
                } else {
                    None
                }
            });
            let grid = GridView::from_single_vxl(&vxl);
            let cam = Camera {
                pos: [8.0, 8.0, 0.0],
                right: [1.0, 0.0, 0.0],
                down: [0.0, 1.0, 0.0],
                forward: [0.0, 0.0, 1.0],
            };
            let (w, h) = (32u32, 32u32);
            let mut table = MaterialTable::new();
            table.set(1, Material::volumetric(80));
            let env = DdaEnv {
                materials: Some(&table),
                terrain_materials: &[(smoke.rgb_part(), 1)],
                lights: CpuLights::default(),
                ..DdaEnv::default()
            };
            let (fb, _) = render_brickmap_env(grid, &cam, w, h, &env);
            (fb[(h / 2 * w + w / 2) as usize] >> 8) & 0xff
        };
        let shallow = green_at(1);
        let deep = green_at(7);
        assert!(
            deep > shallow,
            "deeper Volumetric smoke shows more of its grey (deep g={deep:02x} > shallow g={shallow:02x})"
        );
    }

    /// DDA.5: distance fog blends a hit toward the fog colour. A far
    /// floor pixel is closer to the fog colour than a near one.
    #[test]
    fn distance_fog_blends_toward_fog_color() {
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |_, _, z| {
            (z >= 40).then_some(VoxColor(0x80_FF_FF_FF))
        });
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [32.0, 2.0, 38.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };
        let env = DdaEnv {
            sky: None,
            fog_color: 0x00_00_00_00, // black fog → distance darkens
            fog_max_dist: 64.0,
            side_shades: [0; 6],
            materials: None,
            terrain_materials: &[],
            lights: CpuLights::default(),
            world_shadow: None,
            z_clip: None,
            cutout: None,
            fow: None,
        };
        let (w, h) = (64u32, 64u32);
        let (fog, _) = render_brickmap_env(grid, &cam, w, h, &env);
        let (nofog, zb) = render_brickmap(grid, &cam, w, h);
        let (idx, depth) = zb.iter().enumerate().filter(|(_, z)| z.is_finite()).fold(
            (0usize, 0.0f32),
            |acc, (i, &z)| {
                if z > acc.1 {
                    (i, z)
                } else {
                    acc
                }
            },
        );
        assert!(depth > 20.0, "need a deep pixel to test fog (got {depth})");
        let lum = |c: u32| (c & 0xff) + ((c >> 8) & 0xff) + ((c >> 16) & 0xff);
        assert!(
            lum(fog[idx]) < lum(nofog[idx]),
            "fogged pixel {:08x} not darker than {:08x}",
            fog[idx],
            nofog[idx]
        );
    }

    /// DDA.5: with a textured sky, miss pixels are filled from the sky
    /// panorama (direction-dependent) instead of left at the pre-fill.
    #[test]
    fn textured_sky_fills_misses() {
        let sky = crate::sky::Sky::blue_gradient();
        let vxl = roxlap_formats::vxl::Vxl::empty(32); // all air → all miss
        let grid = GridView::from_single_vxl(&vxl);
        let env = DdaEnv {
            sky: Some(&sky),
            fog_color: 0,
            fog_max_dist: 0.0,
            side_shades: [0; 6],
            materials: None,
            terrain_materials: &[],
            lights: CpuLights::default(),
            world_shadow: None,
            z_clip: None,
            cutout: None,
            fow: None,
        };
        let cam = Camera::from_yaw_pitch([16.0, 16.0, 128.0], 0.3, -0.4);
        let (w, h) = (48u32, 48u32);
        let (fb, _) = render_brickmap_env(grid, &cam, w, h, &env);
        assert!(fb.iter().all(|&c| c >> 24 == 0x80), "all misses sky-filled");
        let top = fb[0];
        let bottom = fb[(h - 1) as usize * w as usize];
        assert_ne!(top, bottom, "sky gradient should vary with elevation");
    }

    /// Sky elevation orientation matches the GPU `sky_color` (acos(-z)/π):
    /// looking **up** (−z) samples panorama column 0 (zenith), looking
    /// **down** (+z) samples the last column (nadir). Regression for the
    /// CPU up/down inversion.
    #[test]
    fn sky_elevation_zenith_at_column_zero() {
        let mut pixels = vec![0i32; 8];
        pixels[0] = 0x0011_1111; // zenith marker
        pixels[7] = 0x0099_9999; // nadir marker
        let sky = crate::sky::Sky::from_pixels(pixels, 8, 1);
        let up = sample_sky(&sky, [0.0, 0.0, -1.0]); // −z is up
        let down = sample_sky(&sky, [0.0, 0.0, 1.0]); // +z is down
        assert_eq!(
            up & 0x00ff_ffff,
            0x0011_1111,
            "looking up → column 0 (zenith)"
        );
        assert_eq!(
            down & 0x00ff_ffff,
            0x0099_9999,
            "looking down → last column (nadir)"
        );
    }

    /// `render_sky_fill` paints the panorama for a **gridless** view — the
    /// same per-pixel sky sample the miss-ray path uses, with no grid present
    /// (the CPU empty-scene background, matching the GPU).
    #[test]
    fn sky_fill_paints_panorama_gridless() {
        let sky = crate::sky::Sky::blue_gradient();
        let cam = Camera::from_yaw_pitch([0.0, 0.0, 0.0], 0.3, -0.4);
        let (w, h) = (48u32, 48u32);
        let cs = crate::camera_math::derive(&cam, w, h, 24.0, 24.0, 24.0);
        let settings = crate::opticast::OpticastSettings::for_oracle_framebuffer(w, h);
        let mut fb = vec![0u32; (w * h) as usize];
        // All-background z-buffer (+∞) → every pixel gets the sky.
        let zb = vec![f32::INFINITY; (w * h) as usize];
        render_sky_fill(&mut fb, &zb, w as usize, w, h, &cs, &settings, &sky);
        assert!(
            fb.iter().all(|&c| c >> 24 == 0x80),
            "every pixel sky-filled with the brightness byte set"
        );
        let top = fb[0];
        let bottom = fb[(h - 1) as usize * w as usize];
        assert_ne!(top, bottom, "sky gradient should vary with elevation");
        // A finite-z (terrain) pixel is left untouched.
        let mut fb2 = vec![0x1234_5678u32; (w * h) as usize];
        let mut zb2 = vec![f32::INFINITY; (w * h) as usize];
        zb2[0] = 10.0; // pretend a terrain hit at pixel 0
        render_sky_fill(&mut fb2, &zb2, w as usize, w, h, &cs, &settings, &sky);
        assert_eq!(fb2[0], 0x1234_5678, "finite-z pixel is not overwritten");
    }

    /// DDA.5: side shading darkens the hit face by its `side_shades`
    /// entry. A top-facing floor (ray crosses +z to enter) gets the
    /// `z-` face reduction (index 4).
    #[test]
    fn side_shades_darken_hit_face() {
        let vxl = roxlap_formats::vxl::Vxl::from_dense(16, |_, _, z| {
            (z >= 8).then_some(VoxColor(0x80_FF_FF_FF))
        });
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [8.0, 8.0, 2.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let centre = 16 * 32 + 16;
        let (plain, _) = render_brickmap(grid, &cam, 32, 32);
        let env = DdaEnv {
            sky: None,
            fog_color: 0,
            fog_max_dist: 0.0,
            side_shades: [0, 0, 0, 0, 0x40, 0],
            materials: None,
            terrain_materials: &[],
            lights: CpuLights::default(),
            world_shadow: None,
            z_clip: None,
            cutout: None,
            fow: None,
        };
        let (shaded, _) = render_brickmap_env(grid, &cam, 32, 32, &env);
        let lum = |c: u32| (c & 0xff) + ((c >> 8) & 0xff) + ((c >> 16) & 0xff);
        assert!(
            lum(shaded[centre]) < lum(plain[centre]),
            "side-shaded face {:08x} not darker than {:08x}",
            shaded[centre],
            plain[centre]
        );
    }

    /// The two-level brick-skip cast closely approximates the dense
    /// per-voxel reference. The outer brick DDA re-seeds the inner cell
    /// walk at each occupied brick, so a few silhouette-boundary pixels
    /// jitter by one voxel (different hit cell → different colour/depth)
    /// — visually invisible, and the gain is ~`BRICK`× fewer air steps.
    /// Assert the divergence is tiny: coverage (hit/sky mask) is nearly
    /// identical and only a small fraction of pixels differ. (The
    /// thread-invariance guarantee is the separate, exact
    /// `parallel_matches_sequential`.)
    #[test]
    fn brickmap_approximates_dense_reference() {
        // Rolling heightmap + a floating block (air above and below).
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |x, y, z| {
            let surf = 30 + ((x / 5 + y / 7) % 11);
            let ground = z >= surf;
            let block = (20..=24).contains(&z) && (10..20).contains(&x) && (40..50).contains(&y);
            (ground || block).then_some(VoxColor(0x80_30_50_70 + (x ^ y) % 0x40))
        });
        let grid = GridView::from_single_vxl(&vxl);

        let (w, h) = (80u32, 80u32);
        let poses = [
            Camera::orbit(0.6, 0.5, 90.0, [32.0, 32.0, 40.0]),
            Camera::orbit(2.1, 0.2, 70.0, [32.0, 32.0, 35.0]),
            Camera::orbit(-1.0, 0.9, 120.0, [32.0, 32.0, 45.0]),
        ];
        let n = (w * h) as usize;
        for (i, cam) in poses.iter().enumerate() {
            let (fb_b, zb_b) = render_brickmap(grid, cam, w, h);
            let (fb_r, _zb_r) = render_reference(grid, cam, w, h);
            // Coverage (hit vs sky) must match almost exactly.
            let cov_b = fb_b.iter().filter(|&&c| c != 0).count();
            let cov_r = fb_r.iter().filter(|&&c| c != 0).count();
            assert!(cov_b > 200, "pose {i} rendered ~empty (cov {cov_b})");
            let cov_diff = cov_b.abs_diff(cov_r);
            assert!(
                cov_diff * 100 <= n, // < 1 % of pixels flip hit↔sky
                "pose {i} coverage diverged: brick {cov_b} vs dense {cov_r}"
            );
            // Colour diffs (boundary-voxel jitter) must be a small slice.
            let diffs = fb_b.iter().zip(&fb_r).filter(|(a, b)| a != b).count();
            assert!(
                diffs * 100 <= n * 3, // < 3 % of pixels differ
                "pose {i} too many pixel diffs vs dense: {diffs}/{n}"
            );
            // Depth must be sane (finite where hit), not wildly off.
            for k in 0..n {
                if fb_b[k] != 0 {
                    assert!(zb_b[k].is_finite(), "pose {i} px {k} non-finite depth");
                }
            }
        }
    }

    /// DDA.5: a voxel's baked brightness byte darkens its colour. A
    /// half-bright voxel (`a = 0x40`) renders at roughly half RGB; a
    /// full-bright one (`a = 0x80`) is unchanged.
    #[test]
    fn baked_brightness_darkens_color() {
        // Half brightness: alpha 0x40 (64/128). White RGB → ~mid grey.
        let dim = roxlap_formats::vxl::Vxl::from_dense(16, |_, _, z| {
            (z >= 8).then_some(VoxColor(0x40_FF_FF_FF))
        });
        let grid = GridView::from_single_vxl(&dim);
        let cam = Camera {
            pos: [8.0, 8.0, 2.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (fb, _) = render_brickmap(grid, &cam, 32, 32);
        let centre = 16 * 32 + 16;
        // 0xFF * 64 >> 7 = 127 per channel; alpha normalised to 0x80.
        assert_eq!(fb[centre], 0x80_7F_7F_7F, "got {:08x}", fb[centre]);

        // Full brightness passes RGB through unchanged.
        let full = roxlap_formats::vxl::Vxl::from_dense(16, |_, _, z| {
            (z >= 8).then_some(VoxColor(0x80_FF_FF_FF))
        });
        let gridf = GridView::from_single_vxl(&full);
        let (fbf, _) = render_brickmap(gridf, &cam, 32, 32);
        assert_eq!(fbf[centre], 0x80_FF_FF_FF, "got {:08x}", fbf[centre]);
    }

    /// DDA.4 headline gate: cross-chunk look-down. A camera in an
    /// all-air upper chunk (chz=0) looking straight down must see the
    /// floor in the *lower* stacked chunk (chz=1), through the chunk-Z
    /// boundary. This is exactly the case the voxlap renderer needed the
    /// whole virtual-column stack (S4B.6.j / VC) for; the DDA gets it
    /// for free from the outer box spanning `chunks_z`.
    #[test]
    fn cross_chunk_lookdown_sees_lower_stacked_floor() {
        const FLOOR_LOCAL_Z: u32 = 40;
        const FLOOR_COL: VoxColor = VoxColor(0x80_22_88_44);
        let upper = roxlap_formats::vxl::Vxl::empty(32); // all air + bedrock
        let lower = roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| {
            (z >= FLOOR_LOCAL_Z).then_some(FLOOR_COL)
        });
        let v_up = GridView::from_single_vxl(&upper);
        let v_lo = GridView::from_single_vxl(&lower);
        // Z-stack: index (dz*chunks_y+dy)*chunks_x+dx → [upper, lower].
        let chunks = [Some(v_up), Some(v_lo)];
        let cg = crate::ChunkGrid {
            chunks: &chunks,
            origin_chunk_xy: [0, 0],
            origin_chunk_z: 0,
            chunks_x: 1,
            chunks_y: 1,
            chunks_z: 2,
        };
        let grid = GridView::from_chunk_grid(&cg, 32);

        // Camera in the upper chunk (world z=100), looking straight down.
        let cam = Camera {
            pos: [16.0, 16.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 (w, h) = (48u32, 48u32);
        let (fb, zb) = render_brickmap(grid, &cam, w, h);
        let centre = 24 * 48 + 24;
        assert!(
            fb[centre] & 0x00ff_ffff == FLOOR_COL.0 & 0x00ff_ffff,
            "centre ray must reach the lower-chunk floor (got {:08x})",
            fb[centre]
        );
        // Floor world-z = 256 + 40 = 296; camera z = 100 → depth ≈ 196.
        let expected = 296.0 - 100.0;
        assert!(
            (zb[centre] - expected).abs() < 2.0,
            "look-down depth {} not ≈ {expected}",
            zb[centre]
        );
    }

    /// CA.1 — render with only a cutaway clip set (rest of the env
    /// default).
    fn render_clip(
        grid: GridView<'_>,
        camera: &Camera,
        w: u32,
        h: u32,
        z_clip: Option<i32>,
    ) -> (Vec<u32>, Vec<f32>) {
        let env = DdaEnv {
            z_clip,
            ..DdaEnv::default()
        };
        render_brickmap_env(grid, camera, w, h, &env)
    }

    /// CA.1 golden — a 3-deck fixture: the clip hides whole decks and
    /// the look-down ray lands on the first floor at-or-below the
    /// plane, with exact colour + depth.
    #[test]
    fn cutaway_clip_reveals_lower_decks() {
        const DECK_A: VoxColor = VoxColor(0x80_C0_30_30); // z = 60
        const DECK_B: VoxColor = VoxColor(0x80_30_C0_30); // z = 120
        const DECK_C: VoxColor = VoxColor(0x80_30_30_C0); // z = 180
        let vxl = roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| match z {
            60 => Some(DECK_A),
            120 => Some(DECK_B),
            180 => Some(DECK_C),
            _ => None,
        });
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [16.0, 16.0, 10.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (32u32, 32u32);
        let centre = (h / 2 * w + w / 2) as usize;
        // (clip, expected floor colour, expected floor z)
        let cases = [
            (None, DECK_A, 60.0),
            (Some(100), DECK_B, 120.0), // deck boundary: A hidden
            (Some(120), DECK_B, 120.0), // z_clip itself stays visible
            (Some(121), DECK_C, 180.0), // one past → B hidden too
        ];
        for (clip, col, z) in cases {
            let (fb, zb) = render_clip(grid, &cam, w, h, clip);
            assert_eq!(
                fb[centre], col.0,
                "clip {clip:?}: expected {:08x}, got {:08x}",
                col.0, fb[centre]
            );
            let expected = z - 10.0;
            assert!(
                (zb[centre] - expected).abs() < 1.0,
                "clip {clip:?}: depth {} not ≈ {expected}",
                zb[centre]
            );
        }
    }

    /// CA.1 — cutting through a SOLID run: the cut face renders with
    /// the run's top-surface colour (the [`GridView::surface_color_mip`]
    /// interior fallback — decision 3 of the CA entry doc), not black
    /// and not the colour of some other voxel.
    #[test]
    fn cutaway_cut_face_uses_run_top_colour() {
        // Solid from z=100 down; every voxel gets a z-derived colour,
        // but RLE only STORES surface colours — the run top is z=100.
        let col_at = |z: u32| VoxColor(0x8000_0000 | (0x40 + z));
        let vxl =
            roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| (z >= 100).then_some(col_at(z)));
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [16.0, 16.0, 10.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (32u32, 32u32);
        let centre = (h / 2 * w + w / 2) as usize;
        // Unclipped: the real top face at z=100, its own colour.
        let (fb, zb) = render_clip(grid, &cam, w, h, None);
        assert_eq!(fb[centre], col_at(100).0);
        assert!((zb[centre] - 90.0).abs() < 1.0);
        // Clipped mid-run: the cut face at z=150 falls back to the run
        // top's colour (interior voxels are colourless in voxlap RLE).
        let (fb, zb) = render_clip(grid, &cam, w, h, Some(150));
        assert_eq!(
            fb[centre],
            col_at(100).0,
            "cut face must reuse the run-top colour, got {:08x}",
            fb[centre]
        );
        assert!(
            (zb[centre] - 140.0).abs() < 1.0,
            "cut face depth {} not ≈ 140",
            zb[centre]
        );
    }

    /// CA.1 — the clip compares the grid-local ABSOLUTE voxel z, not
    /// the in-chunk local z: on a stacked-chz grid a plane inside chz=1
    /// (`z_clip > 255`) must hide the chz=0 deck yet keep the deeper
    /// chz=1 floor. An in-chunk-z bug (`loc[2] < clip`, always true for
    /// clip > 255) would render all-sky here.
    #[test]
    fn cutaway_clip_is_absolute_z_on_stacked_chunks() {
        const UPPER_COL: VoxColor = VoxColor(0x80_C0_C0_30); // abs z = 40
        const LOWER_COL: VoxColor = VoxColor(0x80_30_C0_C0); // abs z = 296
        let upper =
            roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| (z == 40).then_some(UPPER_COL));
        let lower =
            roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| (z >= 40).then_some(LOWER_COL));
        let v_up = GridView::from_single_vxl(&upper);
        let v_lo = GridView::from_single_vxl(&lower);
        let chunks = [Some(v_up), Some(v_lo)];
        let cg = crate::ChunkGrid {
            chunks: &chunks,
            origin_chunk_xy: [0, 0],
            origin_chunk_z: 0,
            chunks_x: 1,
            chunks_y: 1,
            chunks_z: 2,
        };
        let grid = GridView::from_chunk_grid(&cg, 32);
        let cam = Camera {
            pos: [16.0, 16.0, 10.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (32u32, 32u32);
        let centre = (h / 2 * w + w / 2) as usize;
        // Unclipped: the chz=0 deck at abs z=40.
        let (fb, zb) = render_clip(grid, &cam, w, h, None);
        assert_eq!(fb[centre], UPPER_COL.0);
        assert!((zb[centre] - 30.0).abs() < 1.0);
        // Clip inside chz=1: the chz=0 deck vanishes, the chz=1 floor
        // (abs z = 256 + 40 = 296 ≥ 290) stays.
        let (fb, zb) = render_clip(grid, &cam, w, h, Some(290));
        assert_eq!(
            fb[centre], LOWER_COL.0,
            "expected the chz=1 floor, got {:08x}",
            fb[centre]
        );
        assert!(
            (zb[centre] - 286.0).abs() < 1.0,
            "depth {} not ≈ 286",
            zb[centre]
        );
    }

    /// CA.1 — pins the mip formula `z_clip >> mip` (floor). At mip 1
    /// with `z_clip = 101` the plane rounds DOWN to mip-cell 50 (voxels
    /// 100..102), so the surface at z=100 stays visible — the accepted
    /// coarse-mip bleed. A round-up formula would hide that cell and
    /// the depth would jump to 102. CPU and GPU must share this exact
    /// formula (CA.3 parity gate).
    #[test]
    fn cutaway_clip_mip_formula_floors() {
        let mut vxl = roxlap_formats::vxl::Vxl::from_dense(64, |_, _, z| {
            (z >= 100).then_some(VoxColor(0x80_80_80_80))
        });
        vxl.generate_mips(2);
        assert!(vxl.mip_count() >= 2, "need mip 1 built");
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [32.0, 32.0, 10.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (32u32, 32u32);
        let n = (w as usize) * (h as usize);
        let centre = (h / 2 * w + w / 2) as usize;
        let mut fb = vec![0u32; n];
        let mut zb = vec![f32::INFINITY; n];
        let settings = OpticastSettings::for_oracle_framebuffer(w, h);
        let env = DdaEnv {
            z_clip: Some(101),
            ..DdaEnv::default()
        };
        {
            let mut sink = RasterSink::new(&mut fb, &mut zb);
            render_dda(&cam, &settings, grid, w as usize, &env, 1, &mut sink);
        }
        assert_ne!(fb[centre], 0, "mip-1 clipped surface must still hit");
        assert!(
            (zb[centre] - 90.0).abs() < 1.5,
            "mip-cell 50 (voxel z=100) must be the first visible layer \
             (floor formula); depth {} not ≈ 90",
            zb[centre]
        );
    }

    /// CA.1 standing gate — `z_clip = None` and a no-op clip (nothing
    /// above the plane) are byte-identical to the unclipped render.
    #[test]
    fn cutaway_clip_disabled_is_byte_identical() {
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |x, y, z| {
            let surf = 28 + ((x / 4 + y / 6) % 13);
            (z >= surf).then_some(VoxColor(0x80_40_60_80 + (x ^ y) % 0x30))
        });
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera::orbit(0.8, 0.55, 100.0, [32.0, 32.0, 40.0]);
        let (w, h) = (96u32, 96u32);
        let (fb_base, zb_base) = render_brickmap(grid, &cam, w, h);
        let (fb_none, zb_none) = render_clip(grid, &cam, w, h, None);
        assert_eq!(fb_base, fb_none, "z_clip=None must not change a pixel");
        assert_eq!(zb_base, zb_none);
        // `z < 0` hides nothing on a chz≥0 grid — still byte-identical
        // (pins the strict `<` comparison).
        let (fb_zero, zb_zero) = render_clip(grid, &cam, w, h, Some(0));
        assert_eq!(fb_base, fb_zero, "no-op clip must not change a pixel");
        assert_eq!(zb_base, zb_zero);
    }

    /// OC.1 — render with only a view cutout set (rest of the env
    /// default).
    fn render_cutout(
        grid: GridView<'_>,
        camera: &Camera,
        w: u32,
        h: u32,
        cutout: Option<CpuCutout>,
    ) -> (Vec<u32>, Vec<f32>) {
        let env = DdaEnv {
            cutout,
            ..DdaEnv::default()
        };
        render_brickmap_env(grid, camera, w, h, &env)
    }

    /// OC.1 — the wall-between-camera-and-focus fixture: a front wall
    /// at y=20 and a room back wall at y=48, camera at y=4 looking +y.
    const CUT_WALL: VoxColor = VoxColor(0x80_C0_40_40);
    const CUT_BACK: VoxColor = VoxColor(0x80_40_C0_40);
    fn keyhole_fixture() -> roxlap_formats::vxl::Vxl {
        roxlap_formats::vxl::Vxl::from_dense(64, |_, y, _| match y {
            20 => Some(CUT_WALL),
            48 => Some(CUT_BACK),
            _ => None,
        })
    }
    fn keyhole_camera() -> Camera {
        Camera {
            pos: [32.0, 4.0, 128.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        }
    }

    /// OC.1 golden — the keyhole reveals the room behind the front
    /// wall for cells inside the view cone; outside the cone the wall
    /// column is intact; cells at/below the focus plane stay even
    /// inside the cone (the floor rule).
    #[test]
    fn cutout_reveals_wall_inside_window_only() {
        let vxl = keyhole_fixture();
        let grid = GridView::from_single_vxl(&vxl);
        let cam = keyhole_camera();
        let (w, h) = (32u32, 32u32);
        let centre = (h / 2 * w + w / 2) as usize;
        // Cone straight down the +y view axis (focus ahead of the
        // wall), hard edge, reveal past the wall (dist ≈ 16.5) but
        // short of the back wall (≈ 44.5); focus plane below the
        // whole wall span the centre ray crosses (z ≈ 128).
        let cut = CpuCutout {
            focus_local: [32.0, 30.0, 128.0],
            tan_outer: 0.25,
            tan_inner: 0.25,
            margin: 2.0,
            focus_z: 200,
        };
        let (fb, zb) = render_cutout(grid, &cam, w, h, Some(cut));
        assert_eq!(
            fb[centre], CUT_BACK.0,
            "cone centre must see through the wall, got {:08x}",
            fb[centre]
        );
        assert!(
            (zb[centre] - 44.0).abs() < 1.0,
            "revealed depth {} not ≈ 44 (the back wall)",
            zb[centre]
        );
        // Outside the cone (pixel (2,16) hits wall cells ~14 voxels
        // off-axis: tan ≈ 0.85 > 0.25): the wall is untouched.
        let outside = (h / 2 * w + 2) as usize;
        assert_eq!(
            fb[outside], CUT_WALL.0,
            "outside the cone the wall must stay, got {:08x}",
            fb[outside]
        );
        assert!((zb[outside] - 16.0).abs() < 1.0);
        // Focus plane above the centre ray's z (128 ≮ 100): the wall
        // stays even inside the cone — the floor-in-front rule.
        let below = CpuCutout {
            focus_z: 100,
            ..cut
        };
        let (fb, zb) = render_cutout(grid, &cam, w, h, Some(below));
        assert_eq!(
            fb[centre], CUT_WALL.0,
            "cells at/below the focus plane must stay, got {:08x}",
            fb[centre]
        );
        assert!((zb[centre] - 16.0).abs() < 1.0);
    }

    /// OC.1 — the feather tapers the REVEAL DISTANCE across the cone
    /// band (visual-pass redesign — no dither): the cut edge is
    /// spatially COHERENT (per screen row, the revealed pixels form
    /// one contiguous run — no teeth), deterministic frame-to-frame,
    /// and strictly narrower than the same cone with a hard edge
    /// (pinning that the taper really scales the reveal down).
    #[test]
    fn cutout_feather_tapers_reveal_radially() {
        let vxl = keyhole_fixture();
        let grid = GridView::from_single_vxl(&vxl);
        let cam = keyhole_camera();
        let (w, h) = (64u32, 64u32);
        let tapered = CpuCutout {
            focus_local: [32.0, 30.0, 128.0],
            tan_outer: 0.9,
            tan_inner: 0.3,
            margin: 2.0,
            focus_z: 200,
        };
        let (fb, _) = render_cutout(grid, &cam, w, h, Some(tapered));
        let (fb2, _) = render_cutout(grid, &cam, w, h, Some(tapered));
        assert_eq!(fb, fb2, "the feather taper must be deterministic");
        // Per-row coherence on the axis row: BACK pixels form ONE
        // contiguous run (whole-cell classification — the ragged
        // per-pixel teeth the redesign removed would break this).
        let row = (h / 2) as usize * w as usize;
        let flags: Vec<bool> = (0..w as usize)
            .map(|px| fb[row + px] == CUT_BACK.0)
            .collect();
        let first = flags.iter().position(|&b| b);
        let last = flags.iter().rposition(|&b| b);
        let (Some(first), Some(last)) = (first, last) else {
            panic!("axis row must contain revealed pixels");
        };
        assert!(
            flags[first..=last].iter().all(|&b| b),
            "revealed run must be contiguous (no teeth): {flags:?}"
        );
        assert!(
            flags.iter().any(|&b| !b),
            "the taper must keep wall pixels on the axis row"
        );
        // The taper cuts a strictly SMALLER hole than a hard edge at
        // the same outer cone.
        let hard = CpuCutout {
            tan_inner: 0.9,
            ..tapered
        };
        let (fb_hard, _) = render_cutout(grid, &cam, w, h, Some(hard));
        let count = |fb: &[u32]| fb.iter().filter(|&&p| p == CUT_BACK.0).count();
        let (n_taper, n_hard) = (count(&fb), count(&fb_hard));
        assert!(
            0 < n_taper && n_taper < n_hard,
            "taper must shrink the hole: tapered {n_taper} vs hard {n_hard}"
        );
    }

    /// OC.1 — the reveal surface hugs the character COLUMN (the
    /// visual-pass round-4 rule): a full-height pillar the character
    /// stands right behind is cut in its ENTIRETY, boots to head — a
    /// fixed eye-distance sphere through the chest (the previous rule)
    /// kept the pillar's below-chest cells, which sit FARTHER from the
    /// elevated eye than the chest itself, leaving a waist-high stump
    /// hiding the character.
    #[test]
    fn cutout_pillar_in_front_cuts_down_to_the_feet() {
        const PILLAR: VoxColor = VoxColor(0x80_C0_C0_20);
        const FLOOR: VoxColor = VoxColor(0x80_60_60_60);
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |x, y, z| {
            if z >= 132 {
                Some(FLOOR)
            } else if (31..=33).contains(&x) && (24..=25).contains(&y) && (120..130).contains(&z) {
                // A body-height pillar right in front of the focus (one
                // voxel OFF the floor: resting on it would merge the
                // runs, and the cut face under the footprint would
                // legitimately show the run-top = pillar colour).
                Some(PILLAR)
            } else {
                None
            }
        });
        let grid = GridView::from_single_vxl(&vxl);
        // Elevated shoulder eye behind; the character column ahead at
        // (32, 30), feet on the floor (plane 132), head at 120.
        let cam = Camera {
            pos: [32.0, 4.0, 112.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };
        let cut = CpuCutout {
            focus_local: [32.0, 30.0, 126.0],
            tan_outer: 1.0,
            tan_inner: 1.0,
            margin: 2.0,
            focus_z: 132,
        };
        let (w, h) = (64u32, 64u32);
        let count = |fb: &[u32], c: VoxColor| fb.iter().filter(|&&p| p == c.0).count();
        // Uncut: the pillar is visible.
        let (fb, _) = render_cutout(grid, &cam, w, h, None);
        assert!(count(&fb, PILLAR) > 0, "uncut pillar must be visible");
        // Cut: the WHOLE pillar melts (no waist-high stump), while the
        // floor at/below the plane stays.
        let (fb, _) = render_cutout(grid, &cam, w, h, Some(cut));
        assert_eq!(
            count(&fb, PILLAR),
            0,
            "the pillar must cut down to the feet, not stop at the chest"
        );
        assert!(count(&fb, FLOOR) > 0, "the floor must survive the cut");
    }

    /// OC.1 — the focus plane compares the grid-local ABSOLUTE voxel z
    /// on stacked-chz grids (the CA.1 absolute-z pin, cutout edition):
    /// a focus plane inside chz=1 hides the wall span above it there.
    #[test]
    fn cutout_focus_plane_is_absolute_z_on_stacked_chunks() {
        // chz=0 empty; chz=1 carries the wall pair (abs z 256..512).
        let upper = roxlap_formats::vxl::Vxl::from_dense(32, |_, _, _| None);
        let lower = roxlap_formats::vxl::Vxl::from_dense(32, |_, y, _| match y {
            20 => Some(CUT_WALL),
            28 => Some(CUT_BACK),
            _ => None,
        });
        let v_up = GridView::from_single_vxl(&upper);
        let v_lo = GridView::from_single_vxl(&lower);
        let chunks = [Some(v_up), Some(v_lo)];
        let cg = crate::ChunkGrid {
            chunks: &chunks,
            origin_chunk_xy: [0, 0],
            origin_chunk_z: 0,
            chunks_x: 1,
            chunks_y: 1,
            chunks_z: 2,
        };
        let grid = GridView::from_chunk_grid(&cg, 32);
        let cam = Camera {
            pos: [16.0, 4.0, 300.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 0.0, 1.0],
            forward: [0.0, 1.0, 0.0],
        };
        let (w, h) = (32u32, 32u32);
        let centre = (h / 2 * w + w / 2) as usize;
        let cut = CpuCutout {
            focus_local: [16.0, 25.0, 300.0],
            tan_outer: 1.0,
            tan_inner: 1.0,
            margin: 2.0,
            focus_z: 320, // abs voxel z inside chz=1
        };
        let (fb, zb) = render_cutout(grid, &cam, w, h, Some(cut));
        assert_eq!(
            fb[centre], CUT_BACK.0,
            "abs-z focus plane must hide the chz=1 wall, got {:08x}",
            fb[centre]
        );
        assert!((zb[centre] - 24.0).abs() < 1.0);
        // Plane above the ray's abs z (300 ≮ 280): nothing hides. An
        // in-chunk-z bug (300 & 255 = 44 < 280) would still cut here.
        let above = CpuCutout {
            focus_z: 280,
            ..cut
        };
        let (fb, _) = render_cutout(grid, &cam, w, h, Some(above));
        assert_eq!(
            fb[centre], CUT_WALL.0,
            "focus plane above the ray must keep the wall, got {:08x}",
            fb[centre]
        );
    }

    /// OC.1 — pins the mip formula `focus_z >> mip` (floor), the CA.1
    /// formula verbatim: at mip 1 with `focus_z = 101` the plane
    /// rounds DOWN to mip-cell 50 (voxels 100..102), so the surface at
    /// z=100 stays visible — the accepted coarse-mip bleed. CPU and
    /// GPU must share this exact formula (the OC.2 parity gate).
    #[test]
    fn cutout_focus_plane_mip_formula_floors() {
        let mut vxl = roxlap_formats::vxl::Vxl::from_dense(64, |_, _, z| {
            (z >= 100).then_some(VoxColor(0x80_80_80_80))
        });
        vxl.generate_mips(2);
        assert!(vxl.mip_count() >= 2, "need mip 1 built");
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [32.0, 32.0, 10.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (32u32, 32u32);
        let n = (w as usize) * (h as usize);
        let centre = (h / 2 * w + w / 2) as usize;
        let mut fb = vec![0u32; n];
        let mut zb = vec![f32::INFINITY; n];
        let settings = OpticastSettings::for_oracle_framebuffer(w, h);
        let env = DdaEnv {
            cutout: Some(CpuCutout {
                focus_local: [32.0, 32.0, 120.0],
                tan_outer: 4.0, // whole frustum inside the cone
                tan_inner: 4.0,
                margin: 0.0,
                focus_z: 101,
            }),
            ..DdaEnv::default()
        };
        {
            let mut sink = RasterSink::new(&mut fb, &mut zb);
            render_dda(&cam, &settings, grid, w as usize, &env, 1, &mut sink);
        }
        assert_ne!(fb[centre], 0, "mip-1 cut surface must still hit");
        assert!(
            (zb[centre] - 90.0).abs() < 1.5,
            "mip-cell 50 (voxel z=100) must stay visible (floor \
             formula); depth {} not ≈ 90",
            zb[centre]
        );
    }

    /// OC.1 standing gate — `cutout = None`, a zero-radius window and
    /// a zero-reveal cutout are all byte-identical to the plain render
    /// (decision 8: disabled ⇒ byte-identical; pins both "off" folds).
    #[test]
    fn cutout_disabled_is_byte_identical() {
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |x, y, z| {
            let surf = 28 + ((x / 4 + y / 6) % 13);
            (z >= surf).then_some(VoxColor(0x80_40_60_80 + (x ^ y) % 0x30))
        });
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera::orbit(0.8, 0.55, 100.0, [32.0, 32.0, 40.0]);
        let (w, h) = (96u32, 96u32);
        let (fb_base, zb_base) = render_brickmap(grid, &cam, w, h);
        let (fb_none, zb_none) = render_cutout(grid, &cam, w, h, None);
        assert_eq!(fb_base, fb_none, "cutout=None must not change a pixel");
        assert_eq!(zb_base, zb_none);
        // Zero-width cone: no cell centre is ever inside it.
        let no_cone = CpuCutout {
            focus_local: [32.0, 32.0, 40.0],
            tan_outer: 0.0,
            tan_inner: 0.0,
            margin: 0.0,
            focus_z: i32::MAX,
        };
        let (fb, zb) = render_cutout(grid, &cam, w, h, Some(no_cone));
        assert_eq!(fb_base, fb, "a zero cone must not change a pixel");
        assert_eq!(zb_base, zb);
        // Zero reveal (the facade's behind-camera fold): cell
        // distances are non-negative, so nothing hides.
        let no_reveal = CpuCutout {
            focus_local: [32.0, 32.0, 40.0],
            tan_outer: 10.0,
            tan_inner: 10.0,
            margin: 1.0e6,
            focus_z: i32::MAX,
        };
        let (fb, zb) = render_cutout(grid, &cam, w, h, Some(no_reveal));
        assert_eq!(fb_base, fb, "zero reveal must not change a pixel");
        assert_eq!(zb_base, zb);
    }

    /// OC.1 — the cutout is a VIEW aid, not world removal (non-goal in
    /// the entry doc): a roof hidden by the keyhole still casts its
    /// sun shadow onto the floor below — the exact opposite of the CA
    /// clip's "world as if removed" gate above.
    #[test]
    fn cutout_hidden_roof_still_casts_shadows() {
        const ROOF: VoxColor = VoxColor(0x80_A0_50_20);
        const FLOOR: VoxColor = VoxColor(0x80_80_80_80);
        let roofed = roxlap_formats::vxl::Vxl::from_dense(64, |_, _, z| {
            if z == 20 {
                Some(ROOF)
            } else if z >= 60 {
                Some(FLOOR)
            } else {
                None
            }
        });
        let roofless =
            roxlap_formats::vxl::Vxl::from_dense(64, |_, _, z| (z >= 60).then_some(FLOOR));
        let g_roofed = GridView::from_single_vxl(&roofed);
        let g_roofless = GridView::from_single_vxl(&roofless);
        let cam = Camera {
            pos: [32.0, 32.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 lights = CpuLights {
            enabled: true,
            sun: true,
            sun_dir: [inv, 0.0, -inv],
            sun_color: [1.0; 3],
            sun_intensity: 1.0,
            sun_casts_shadow: true,
            ambient: [0.25; 3],
            shadow_strength: 0.8,
            shadow_bias: 1.5,
            shadow_max_dist: 128.0,
            ..CpuLights::default()
        };
        let (w, h) = (64u32, 64u32);
        // Cone over the whole frustum; reveal past the farthest roof
        // cell (corner distance ≈ 47) but short of the floor's z-gate
        // anyway (floor z=60 ≥ plane 50 keeps it); plane between them.
        let cut = CpuCutout {
            focus_local: [32.0, 32.0, 46.0],
            tan_outer: 10.0,
            tan_inner: 10.0,
            margin: 1.0,
            focus_z: 50,
        };
        let env_cut = DdaEnv {
            lights,
            cutout: Some(cut),
            ..DdaEnv::default()
        };
        let env_plain = DdaEnv {
            lights,
            ..DdaEnv::default()
        };
        let (fb_cut, zb_cut) = render_brickmap_env(g_roofed, &cam, w, h, &env_cut);
        let (fb_ref, zb_ref) = render_brickmap_env(g_roofless, &cam, w, h, &env_plain);
        // Same geometry visible (the floor)…
        assert_eq!(zb_cut, zb_ref, "the cutout must reveal the same floor");
        // …but the hidden roof still shadows it: the cut render is
        // strictly darker than the roofless reference.
        let sum: fn(&[u32]) -> u64 = |fb| {
            fb.iter()
                .map(|&p| u64::from((p & 0xff) + ((p >> 8) & 0xff) + ((p >> 16) & 0xff)))
                .sum()
        };
        let (dark, light) = (sum(&fb_cut), sum(&fb_ref));
        assert!(
            dark < light,
            "hidden roof must keep shadowing the floor: cut={dark} roofless={light}"
        );
    }

    /// DDA.4: a floor spanning two side-by-side chunks (chunks_x=2)
    /// renders continuously across the chunk-XY seam — hits on both
    /// sides, no gap column.
    #[test]
    fn cross_chunk_xy_floor_is_seamless() {
        let mk = || {
            roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| {
                (z >= 20).then_some(VoxColor(0x80_50_50_50))
            })
        };
        let (c0, c1) = (mk(), mk());
        let v0 = GridView::from_single_vxl(&c0);
        let v1 = GridView::from_single_vxl(&c1);
        let chunks = [Some(v0), Some(v1)];
        let cg = crate::ChunkGrid {
            chunks: &chunks,
            origin_chunk_xy: [0, 0],
            origin_chunk_z: 0,
            chunks_x: 2,
            chunks_y: 1,
            chunks_z: 1,
        };
        let grid = GridView::from_chunk_grid(&cg, 32);

        // High above the seam (x=32), looking straight down.
        let cam = Camera {
            pos: [32.0, 16.0, 4.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (64u32, 64u32);
        let mask = render_mask(grid, &cam, w, h);
        // Both the left chunk (screen left) and right chunk (screen
        // right) must show floor on the centre row.
        let row = (h / 2) as usize * w as usize;
        let left = (0..w as usize / 2).filter(|&x| mask[row + x]).count();
        let right = (w as usize / 2..w as usize)
            .filter(|&x| mask[row + x])
            .count();
        assert!(
            left > 5 && right > 5,
            "seam not continuous: left={left} right={right}"
        );
    }

    /// Render `grid` from `camera` at render `mip` and return the hit
    /// mask.
    fn render_mask_mip(grid: GridView<'_>, camera: &Camera, w: u32, h: u32, mip: u32) -> Vec<bool> {
        let n = (w as usize) * (h as usize);
        let mut fb = vec![0u32; n];
        let mut zb = vec![f32::INFINITY; n];
        let settings = OpticastSettings::for_oracle_framebuffer(w, h);
        {
            let mut sink = RasterSink::new(&mut fb, &mut zb);
            render_dda(
                camera,
                &settings,
                grid,
                w as usize,
                &DdaEnv::default(),
                mip,
                &mut sink,
            );
        }
        fb.iter().map(|&c| c != 0).collect()
    }

    /// DDA.6: rendering a mip-built grid at a coarse mip stays complete
    /// (hole-free silhouette) with roughly the same screen coverage as
    /// mip 0 — LOD coarsens detail, it doesn't punch holes or shrink the
    /// shape. (DDA has no axis-aligned mip beam — the artifact is
    /// structurally impossible with honest per-cell traversal.)
    #[test]
    fn mip_render_is_coarse_but_complete() {
        let mut vxl = roxlap_formats::vxl::Vxl::from_dense(64, |x, y, z| {
            let surf = 24 + ((x / 3 + y / 5) % 17);
            (z >= surf).then_some(VoxColor(0x80_50_70_90))
        });
        vxl.generate_mips(4);
        assert!(vxl.mip_count() >= 3, "need mips built for this test");
        let grid = GridView::from_single_vxl(&vxl);
        let (w, h) = (96u32, 96u32);
        let cam = Camera::orbit(0.7, 0.6, 110.0, [32.0, 32.0, 36.0]);

        let m0 = render_mask_mip(grid, &cam, w, h, 0);
        let m2 = render_mask_mip(grid, &cam, w, h, 2);

        let c0 = m0.iter().filter(|&&b| b).count();
        let c2 = m2.iter().filter(|&&b| b).count();
        assert!(c0 > 200 && c2 > 200, "both mips visible (c0={c0} c2={c2})");
        // Coverage within ~30 % — a coarse-mip silhouette closely tracks
        // the fine one (LOD coarsens detail, it doesn't lose the shape).
        // (Terrain silhouettes are non-convex — sky shows through
        // valleys — so a hole-free invariant doesn't apply here; that's
        // the convex single-voxel test's job.)
        let ratio = c2 as f32 / c0 as f32;
        assert!(
            (0.7..1.4).contains(&ratio),
            "mip-2 coverage {c2} vs mip-0 {c0} (ratio {ratio:.2}) diverged"
        );
    }

    /// Headless perf bench (run: `cargo test -p roxlap-core --release
    /// dda::tests::bench_terrain -- --ignored --nocapture`). Single-
    /// thread `render_dda` over a hilly chunk at a horizon pose; prints
    /// ms/frame + per-frame traversal counters (cells / bricks /
    /// surface_color calls) to locate the bottleneck.
    #[test]
    #[ignore = "perf benchmark — run explicitly with --ignored"]
    fn bench_terrain() {
        use std::time::Instant;
        // Multi-chunk grid like the demo: NC×NC chunks of 128, hills.
        const NC: i32 = 6;
        let cs = crate::grid_view::CHUNK_SIZE_Z; // 256, but vsid is 128
        let _ = cs;
        let mut vxls: Vec<roxlap_formats::vxl::Vxl> = Vec::new();
        for cy in 0..NC {
            for cx in 0..NC {
                let (ox, oy) = (cx * 128, cy * 128);
                let mut v = roxlap_formats::vxl::Vxl::from_dense(128, |x, y, z| {
                    let (gx, gy) = (ox + x as i32, oy + y as i32);
                    let surf = 90 + ((gx / 7 + gy / 9).rem_euclid(40)) + ((gx / 23).rem_euclid(20));
                    (z as i32 >= surf).then_some(VoxColor(0x80_50_70_90 + (x ^ y) % 0x30))
                });
                v.generate_mips(4);
                vxls.push(v);
            }
        }
        let views: Vec<Option<GridView>> = vxls
            .iter()
            .map(|v| Some(GridView::from_single_vxl(v)))
            .collect();
        let cg = crate::ChunkGrid {
            chunks: &views,
            origin_chunk_xy: [0, 0],
            origin_chunk_z: 0,
            chunks_x: NC as u32,
            chunks_y: NC as u32,
            chunks_z: 1,
        };
        let grid = GridView::from_chunk_grid(&cg, 128);

        let (w, h) = (960u32, 600u32);
        let mut settings = OpticastSettings::for_oracle_framebuffer(w, h);
        settings.max_scan_dist = 512;
        let n = (w * h) as usize;
        let mut fb = vec![0u32; n];
        let mut zb = vec![f32::INFINITY; n];
        let centre = [f64::from(NC * 128) / 2.0, f64::from(NC * 128) / 2.0, 60.0];

        // Two poses: eye-level toward horizon (long rays) + looking down
        // at nearby terrain (short rays, demo-typical).
        let poses = [
            (
                "horizon",
                Camera::from_yaw_pitch([20.0, 20.0, 40.0], 0.6, 0.15),
            ),
            ("down", Camera::orbit(0.7, 1.0, 130.0, centre)),
        ];
        for (name, cam) in poses {
            {
                let mut sink = RasterSink::new(&mut fb, &mut zb);
                prof::reset();
                render_dda(
                    &cam,
                    &settings,
                    grid,
                    w as usize,
                    &DdaEnv::default(),
                    0,
                    &mut sink,
                );
            }
            let (cells, bricks, surf) = prof::read();
            let iters = 6;
            let t0 = Instant::now();
            for _ in 0..iters {
                let mut sink = RasterSink::new(&mut fb, &mut zb);
                render_dda(
                    &cam,
                    &settings,
                    grid,
                    w as usize,
                    &DdaEnv::default(),
                    0,
                    &mut sink,
                );
            }
            let ms = t0.elapsed().as_secs_f64() * 1000.0 / f64::from(iters);
            let hits = fb.iter().filter(|&&c| c != 0).count();
            eprintln!(
                "[{name}] {w}x{h} 1-thread: {ms:.1} ms | hits={hits}/{n} | per-px: cells={:.1} bricks={:.1} surf={:.1}",
                cells as f64 / n as f64,
                bricks as f64 / n as f64,
                surf as f64 / n as f64,
            );
        }
    }

    /// DDA.7: the tile-parallel driver is bit-identical to the
    /// sequential one — DDA pixels are independent, so banding can't
    /// change a pixel.
    #[test]
    fn parallel_matches_sequential() {
        let vxl = roxlap_formats::vxl::Vxl::from_dense(64, |x, y, z| {
            let surf = 28 + ((x / 4 + y / 6) % 13);
            (z >= surf).then_some(VoxColor(0x80_40_60_80 + (x ^ y) % 0x30))
        });
        let grid = GridView::from_single_vxl(&vxl);
        let (w, h) = (96u32, 96u32);
        let cam = Camera::orbit(0.8, 0.55, 100.0, [32.0, 32.0, 40.0]);
        let env = DdaEnv {
            sky: None,
            fog_color: 0x00_20_30_40,
            fog_max_dist: 120.0,
            side_shades: [0, 0, 0, 0, 0x30, 0x10],
            materials: None,
            terrain_materials: &[],
            lights: CpuLights::default(),
            world_shadow: None,
            z_clip: None,
            cutout: None,
            fow: None,
        };

        let (seq_fb, seq_zb) = render_brickmap_env(grid, &cam, w, h, &env);

        let n = (w * h) as usize;
        let mut par_fb = vec![0u32; n];
        let mut par_zb = vec![f32::INFINITY; n];
        let settings = OpticastSettings::for_oracle_framebuffer(w, h);
        let (cache, mip) = local_cache(&grid, 0);
        render_dda_parallel(
            &cam,
            &settings,
            grid,
            &mut par_fb,
            &mut par_zb,
            w as usize,
            &env,
            &cache,
            mip,
        );
        assert!(par_fb == seq_fb, "parallel colour differs from sequential");
        assert!(
            par_zb
                .iter()
                .zip(&seq_zb)
                .all(|(a, b)| a.to_bits() == b.to_bits()),
            "parallel depth differs from sequential"
        );
    }

    /// DDA.2 correctness: a heightmap column's interior is solid even
    /// though voxlap only stores a colour for its surface. `voxel_color`
    /// returns `None` for an interior voxel, but `surface_color` must
    /// return the run's surface colour — otherwise oblique rays striking
    /// a cliff *side* would pass straight through (see-through terrain).
    #[test]
    fn cliff_side_is_solid_not_see_through() {
        const TOP_Z: u32 = 50;
        const COL: VoxColor = VoxColor(0x80_77_88_99);
        let vxl = roxlap_formats::vxl::Vxl::from_dense(8, |_, _, z| (z >= TOP_Z).then_some(COL));
        let grid = GridView::from_single_vxl(&vxl);

        // Surface voxel: coloured directly.
        assert_eq!(grid.voxel_color(4, 4, TOP_Z), Some(COL));
        // Interior voxel: voxlap stores no colour …
        assert_eq!(grid.voxel_color(4, 4, 150), None);
        // … but it is solid, and surface_color bleeds the run-top colour
        // down the cliff face → a real hit, not see-through.
        assert_eq!(grid.surface_color(4, 4, 150), Some(COL));
        // Bedrock-style air above the surface stays air.
        assert_eq!(grid.surface_color(4, 4, 10), None);
    }

    /// DDA.2: a camera embedded in solid material hits its own voxel
    /// immediately — every ray reports a hit (no skip / no garbage).
    #[test]
    fn camera_inside_solid_hits_everywhere() {
        let vxl = roxlap_formats::vxl::Vxl::from_dense(16, |_, _, _| Some(VoxColor(0x80_55_55_55)));
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [8.0, 8.0, 128.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let (w, h) = (32u32, 32u32);
        let mask = render_mask(grid, &cam, w, h);
        assert!(
            mask.iter().all(|&b| b),
            "every ray must hit when the camera is inside solid"
        );
    }

    /// Headline DDA.1 gate: a single solid voxel viewed obliquely
    /// projects to a convex silhouette with **no interior holes** —
    /// the artifact class (`tiny_grid_1x1x1` silhouette notch) the
    /// voxlap renderer cannot avoid. DDA casts independent per-pixel
    /// rays, so the silhouette is hole-free by construction.
    #[test]
    fn single_voxel_silhouette_has_no_notch() {
        const C: VoxColor = VoxColor(0x80_FF_80_40);
        let vxl = roxlap_formats::vxl::Vxl::from_dense(16, |x, y, z| {
            (x == 8 && y == 8 && z == 8).then_some(C)
        });
        let grid = GridView::from_single_vxl(&vxl);

        // Orbit the voxel centre obliquely so all three faces show and
        // the silhouette is a sizeable hexagon (dist 4 → ~12 px wide).
        let cam = Camera::orbit(0.7, 0.6, 4.0, [8.5, 8.5, 8.5]);
        let (w, h) = (96u32, 96u32);
        let mask = render_mask(grid, &cam, w, h);

        let hits = mask.iter().filter(|&&b| b).count();
        assert!(
            hits > 30,
            "silhouette too small to be meaningful: {hits} px"
        );
        assert!(
            rows_have_no_holes(&mask, w, h),
            "row-interior gap in single-voxel silhouette (notch)"
        );
        assert!(
            cols_have_no_holes(&mask, w, h),
            "column-interior gap in single-voxel silhouette (notch)"
        );
    }

    // ---- FW.2: fog-of-war styling ----

    struct FixedStyler(FowVerdict);
    impl FowStyler for FixedStyler {
        fn verdict(&self, _x: i32, _y: i32, _z: i32) -> FowVerdict {
            self.0
        }
    }

    #[test]
    fn fow_style_dims_and_desaturates() {
        // Identity when dim=1, desat=0.
        assert_eq!(fow_style(0x80_40_80_C0, 1.0, 0.0), 0x80_40_80_C0);
        // Half dim halves each channel, high byte preserved.
        assert_eq!(fow_style(0x80_40_80_C0, 0.5, 0.0), 0x80_20_40_60);
        // Full desaturate → all channels equal the luma.
        let g = fow_style(0x80_40_80_C0, 1.0, 1.0);
        assert_eq!((g >> 16) & 0xff, g & 0xff);
        assert_eq!((g >> 8) & 0xff, g & 0xff);
        assert_eq!(g & 0xff00_0000, 0x8000_0000);
    }

    /// A flat floor; camera looking down. The three stylers exercise the
    /// hit path.
    fn floor_scene() -> (roxlap_formats::vxl::Vxl, Camera, u32, u32) {
        let vxl = roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| {
            (z >= 20).then_some(VoxColor(0x80_40_80_C0))
        });
        let cam = Camera {
            pos: [16.0, 16.0, 5.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        (vxl, cam, 48, 48)
    }

    #[test]
    fn fow_hide_makes_geometry_vanish() {
        let (vxl, cam, w, h) = floor_scene();
        let grid = GridView::from_single_vxl(&vxl);
        let (base, _) = render_brickmap(grid, &cam, w, h);
        assert!(base.iter().any(|&p| p != 0), "baseline must draw the floor");

        let styler = FixedStyler(FowVerdict::Hide);
        let env = DdaEnv {
            fow: Some(&styler),
            ..DdaEnv::default()
        };
        let (hidden, _) = render_brickmap_env(grid, &cam, w, h, &env);
        assert!(
            hidden.iter().all(|&p| p == 0),
            "every Hide cell must read as air (sky)"
        );
    }

    #[test]
    fn fow_dim_desaturate_matches_helper() {
        let (vxl, cam, w, h) = floor_scene();
        let grid = GridView::from_single_vxl(&vxl);
        let (base, _) = render_brickmap(grid, &cam, w, h);

        let styler = FixedStyler(FowVerdict::Show {
            dynamic: true,
            dim: 0.5,
            desaturate: 0.4,
        });
        let env = DdaEnv {
            fow: Some(&styler),
            ..DdaEnv::default()
        };
        let (styled, _) = render_brickmap_env(grid, &cam, w, h, &env);
        for k in 0..(w * h) as usize {
            if base[k] != 0 {
                assert_eq!(styled[k], fow_style(base[k], 0.5, 0.4), "pixel {k}");
            }
        }
    }

    /// A `dynamic: false` verdict (memory) must render the BAKED look
    /// even with a dynamic sun in the rig — a live light never relights
    /// a remembered room.
    #[test]
    fn fow_memory_skips_dynamic_lights() {
        let (vxl, cam, w, h) = floor_scene();
        let grid = GridView::from_single_vxl(&vxl);
        // A red point light just above the floor → an obvious red tint
        // the baked look does not have.
        let pt = [CpuPointLight {
            pos: [16.0, 16.0, 18.0],
            color: [1.0, 0.0, 0.0],
            intensity: 5.0,
            radius: 40.0,
            casts_shadow: false,
            spot_dir: [0.0, 0.0, 0.0],
            cos_inner: -1.0,
            cos_outer: -1.0,
        }];
        let lights = CpuLights {
            enabled: true,
            points: &pt,
            ..CpuLights::default()
        };
        // Baked (no rig) reference.
        let (baked, _) = render_brickmap(grid, &cam, w, h);
        // Lit reference — the rig changes the floor colour.
        let lit_env = DdaEnv {
            lights,
            ..DdaEnv::default()
        };
        let (lit, _) = render_brickmap_env(grid, &cam, w, h, &lit_env);
        assert_ne!(lit, baked, "the sun rig must change the floor");

        // Memory styler + the same rig → the baked look, not the lit one.
        let styler = FixedStyler(FowVerdict::Show {
            dynamic: false,
            dim: 1.0,
            desaturate: 0.0,
        });
        let mem_env = DdaEnv {
            lights,
            fow: Some(&styler),
            ..DdaEnv::default()
        };
        let (mem, _) = render_brickmap_env(grid, &cam, w, h, &mem_env);
        assert_eq!(mem, baked, "memory must skip the dynamic rig (baked look)");
    }

    /// Styler that hides one column `(x)` (an "unseen wall") and shows
    /// everything else — for the shadow-leak test.
    struct HideColumnStyler {
        wall_x: i32,
    }
    impl FowStyler for HideColumnStyler {
        fn verdict(&self, x: i32, _y: i32, _z: i32) -> FowVerdict {
            if x == self.wall_x {
                FowVerdict::Hide
            } else {
                FowVerdict::LIVE
            }
        }
    }

    /// Review #1 — an unseen (Hide) wall must cast NO shadow. With a
    /// sun rig the wall shadows a strip of floor; hiding the wall via the
    /// fog must both remove the wall AND its shadow (else the silhouette
    /// leaks).
    #[test]
    fn fow_hidden_wall_casts_no_shadow() {
        const FLOOR: VoxColor = VoxColor(0x80_80_80_80);
        const WALL: VoxColor = VoxColor(0x80_40_40_40);
        let wall_x = 16;
        // Floor at z=30; a tall wall column standing up from the floor.
        let vxl = roxlap_formats::vxl::Vxl::from_dense(32, |x, y, z| {
            if z >= 30 {
                Some(FLOOR)
            } else if x as i32 == wall_x && y == 16 && (18..30).contains(&z) {
                Some(WALL)
            } else {
                None
            }
        });
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [16.0, 16.0, 4.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        // Sun slanted along +x so the wall shadows floor at x > wall_x.
        let lights = CpuLights {
            enabled: true,
            sun: true,
            sun_dir: [-0.7, 0.0, -0.7],
            sun_color: [1.0, 1.0, 1.0],
            sun_intensity: 1.0,
            sun_casts_shadow: true,
            shadow_strength: 1.0,
            shadow_bias: 1.5,
            shadow_max_dist: 64.0,
            ..CpuLights::default()
        };
        let (w, h) = (48u32, 48u32);
        // A: wall present, all-LIVE (its shadow lands on the floor).
        let live = HideColumnStyler { wall_x: -999 };
        let env_a = DdaEnv {
            lights,
            fow: Some(&live),
            ..DdaEnv::default()
        };
        let (fb_a, _) = render_brickmap_env(grid, &cam, w, h, &env_a);
        // B: the wall is Hidden by fog → gone, and casts no shadow.
        let hide = HideColumnStyler { wall_x };
        let env_b = DdaEnv {
            lights,
            fow: Some(&hide),
            ..DdaEnv::default()
        };
        let (fb_b, _) = render_brickmap_env(grid, &cam, w, h, &env_b);

        let lum = |c: u32| ((c >> 16) & 0xff) + ((c >> 8) & 0xff) + (c & 0xff);
        let total: u64 = (0..(w * h) as usize)
            .map(|k| u64::from(lum(fb_b[k])).saturating_sub(u64::from(lum(fb_a[k]))))
            .sum();
        // Hiding the wall removes its shadow → the floor is strictly
        // brighter overall in B than A.
        assert!(
            total > 0,
            "hiding the wall must lift its shadow off the floor (Δlum {total})"
        );
    }

    /// Review #6 — an emissive material is INTRINSIC and survives in
    /// memory: a remembered glowing crystal renders glowing (dimmed),
    /// not as dark baked rock. `dynamic: false` (memory) only suppresses
    /// the dynamic light rig, never the emissive full-bright.
    #[test]
    fn fow_memory_keeps_emissive() {
        const GLOW: VoxColor = VoxColor(0x80_20_FF_80);
        let vxl = roxlap_formats::vxl::Vxl::from_dense(32, |_, _, z| (z >= 20).then_some(GLOW));
        let grid = GridView::from_single_vxl(&vxl);
        let cam = Camera {
            pos: [16.0, 16.0, 5.0],
            right: [1.0, 0.0, 0.0],
            down: [0.0, 1.0, 0.0],
            forward: [0.0, 0.0, 1.0],
        };
        let mut table = MaterialTable::new();
        table.set(1, roxlap_formats::material::Material::glow(255));
        let terrain = [(GLOW.rgb_part(), 1u8)];
        let (w, h) = (48u32, 48u32);

        // Live (visible) emissive.
        let live = FixedStyler(FowVerdict::LIVE);
        let env_live = DdaEnv {
            materials: Some(&table),
            terrain_materials: &terrain,
            fow: Some(&live),
            ..DdaEnv::default()
        };
        let (fb_live, _) = render_brickmap_env(grid, &cam, w, h, &env_live);
        // Memory (dynamic off, dim 1, desat 0) — must ALSO glow.
        let mem = FixedStyler(FowVerdict::Show {
            dynamic: false,
            dim: 1.0,
            desaturate: 0.0,
        });
        let env_mem = DdaEnv {
            materials: Some(&table),
            terrain_materials: &terrain,
            fow: Some(&mem),
            ..DdaEnv::default()
        };
        let (fb_mem, _) = render_brickmap_env(grid, &cam, w, h, &env_mem);
        assert_eq!(
            fb_mem, fb_live,
            "memory must keep the emissive glow (dim 1 == the live emissive look)"
        );
        // And that glow is brighter than the plain baked look (emissive
        // actually did something).
        let baked = FixedStyler(FowVerdict::Show {
            dynamic: false,
            dim: 1.0,
            desaturate: 0.0,
        });
        let env_baked = DdaEnv {
            fow: Some(&baked),
            ..DdaEnv::default()
        };
        let (fb_baked, _) = render_brickmap_env(grid, &cam, w, h, &env_baked);
        let lum = |c: u32| ((c >> 16) & 0xff) + ((c >> 8) & 0xff) + (c & 0xff);
        let centre = (24 * 48 + 24) as usize;
        assert!(
            lum(fb_mem[centre]) > lum(fb_baked[centre]),
            "emissive memory ({:08x}) must be brighter than baked ({:08x})",
            fb_mem[centre],
            fb_baked[centre]
        );
    }

    /// `fow = None` is byte-identical to the pre-FW render.
    #[test]
    fn fow_disabled_byte_identical() {
        let (vxl, cam, w, h) = floor_scene();
        let grid = GridView::from_single_vxl(&vxl);
        let (base, _) = render_brickmap(grid, &cam, w, h);
        // A LIVE styler (dim=1, desat=0, dynamic) also reproduces base.
        let styler = FixedStyler(FowVerdict::LIVE);
        let env = DdaEnv {
            fow: Some(&styler),
            ..DdaEnv::default()
        };
        let (live, _) = render_brickmap_env(grid, &cam, w, h, &env);
        assert_eq!(live, base, "a fully-visible cell must be bit-identical");
    }
}