rlx_core/render/scenes/

fragment_field.rs

//! Fragment-field scene: a fullscreen Shadertoy-style domain-warped field,
//! colored through the shared palette LUT (ADR-0021). The first "generative-art"-
//! tier built-in and one of the two preset-driven systems (ADR-0002 layers 1-2).
//!
//! Its look is a set of named parameters — `warp`, `hue`, `zoom`, `glow`,
//! `flash`, plus the shared color knobs `color_span`/`color_center`/`saturation`
//! (Plan 0020) — that a preset binds to expressions over the audio analysis (Plan
//! 0003 Phase 5). With no preset the parameter defaults render a gentle idle
//! field. The scene reads no audio directly; all reactivity flows through the
//! parameter values.
//!
//! Color: the field level indexes a 256-entry gradient LUT (the preset's
//! `[palette]`, default `spectrum` = the exact prior cosine) instead of a
//! hardcoded `palette()`. `color_span` sets how much of the gradient the field
//! spans (replacing the old fixed `field*0.6`), `color_center`/`hue` slide the
//! window, and `saturation` desaturates toward luma — all bindable.

// Hot-path panic-denial pragma (Plan 0002 Phase 2, extended to scenes by Plan
// 0003 Phase 0). Runs every displayed frame.
#![deny(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::indexing_slicing,
    clippy::panic,
    clippy::unreachable
)]

use crate::render::gpu;

use super::common;
use super::{Phase, Scene};
use crate::dsp::AnalysisFrame;
use crate::render::palette::{self, Palette};
use crate::render::scenes::{ParamGroup, ParamKind, ParamSpec, default_of};

/// Parameter defaults — a calm idle field when nothing is bound.
const DEFAULT_WARP: f32 = default_of(PARAMS, "warp");
const DEFAULT_HUE: f32 = 0.0;
const DEFAULT_ZOOM: f32 = 1.0;
const DEFAULT_GLOW: f32 = default_of(PARAMS, "glow");
const DEFAULT_FLASH: f32 = default_of(PARAMS, "flash");
// Shared palette color knobs (ADR-0021). `color_span` = 0.6 + `color_center` = 0
// + `saturation` = 1 reproduce the prior look exactly (the old `field*0.6` sample
// with no desaturation).
const DEFAULT_COLOR_SPAN: f32 = default_of(PARAMS, "color_span");
const DEFAULT_COLOR_CENTER: f32 = default_of(PARAMS, "color_center");
/// The two rate parameters (ADR-0132), in units of the scene's own default
/// speed. `1.0` is what this scene has always animated at, so a preset that
/// binds neither renders exactly as before.
const DEFAULT_FIELD_SPEED: f32 = default_of(PARAMS, "field_speed");
const DEFAULT_FOLD_SPEED: f32 = default_of(PARAMS, "fold_speed");

const SHADER: &str = r#"
struct Params {
    // x: time (s), y: aspect, z: warp, w: hue
    a: vec4<f32>,
    // x: zoom, y: glow, z: flash, w: color_span
    b: vec4<f32>,
    // xy: pan (field-space offset, ADR-0018), z: color_center, w: saturation
    c: vec4<f32>,
    // x: palette_mix (A/B crossfade), y: occlude (ADR-0085),
    // z: palette_steps (integral, quantized CPU-side), w: palette_contour (ADR-0078)
    d: vec4<f32>,
    // x: fold phase, y: field phase (ADR-0132) — both INTEGRATED on the CPU
    // (`phase += rate * dt`) rather than derived here from `t * rate`. At a
    // constant rate a phase equals `rate * t`, so the defaults reproduce the
    // literals these replaced; what integration buys is that a rate BOUND TO
    // AUDIO bends the motion instead of teleporting it — at t = 100 s a
    // `warp_speed`-style multiply would move the phase fifty seconds in one
    // frame. z: palette_contour_style (integral, rounded CPU-side),
    // w: palette_contour_ink (ADR-0197)
    e: vec4<f32>,
}

@group(0) @binding(0) var<uniform> params: Params;
// The gradient LUTs sit in their own bind group (group 1), so this pipeline's
// layout stays distinct from the screen-space kaleidoscope's single 3-entry
// [uniform, texture, sampler] group — two byte-identical layouts mis-render when
// they coexist on the DX12 WARP software adapter (the same quirk the shared line
// renderer and the lazy feedback scenes work around; a WARP reading, unverified
// on lavapipe as of 2026-10-06). Two LUTs (A/B) for the `palette_mix`
// crossfade; one shared sampler.
@group(1) @binding(0) var lut_a: texture_2d<f32>;
@group(1) @binding(1) var lut_b: texture_2d<f32>;
@group(1) @binding(2) var lut_samp: sampler;

// Shared `saturation` (mirrors core/src/render/palette.rs::desaturate verbatim):
// scale chroma around Rec. 601 luma. 1.0 unchanged, 0.0 grayscale.
fn apply_saturation(c: vec3<f32>, s: f32) -> vec3<f32> {
    let luma = dot(c, vec3<f32>(0.299, 0.587, 0.114));
    return vec3<f32>(luma) + (c - vec3<f32>(luma)) * s;
}

// Shared `palette_steps` (mirrors core/src/render/palette.rs::band_coord
// verbatim, ADR-0078): snap the palette coordinate to a band centre before the
// LUT read. Below 1.5 steps it is the exact identity, not a one-band degenerate.
fn band_coord(t: f32, steps: f32) -> f32 {
    if (steps < 1.5) {
        return t;
    }
    return (floor(t * steps) + 0.5) / steps;
}

// Shared `palette_contour` (ADR-0078 / ADR-0133; the WGSL is the implementation,
// copied verbatim at each fragment-stage site — palette.rs has no CPU
// counterpart to be canonical, since `fwidth` exists only here).
//
// Darkens within one PIXEL of a band edge, so the line has the same weight where
// the field is shallow and where it is steep — AND ONLY WHERE THE INK ACTUALLY
// CHANGES (ADR-0133). It samples the two band centres either side of the nearest
// edge and returns unchanged when they resolve to the same colour within half a
// code value, which is below the LUT's own 8-bit quantization. On a smooth
// palette two distinct centres always differ by at least one code value, so
// every edge draws exactly as it did at any `palette_steps`; inside a plateau
// the LUT is literally constant and the samples are bit-equal, so the line
// vanishes there and survives at the run boundaries. One rule, both behaviours,
// no new parameter.
//
// The two LUTs, the sampler and `palette_mix` are EXPLICIT parameters rather
// than module-scope globals this happens to find: all six sites name them the
// same today, so implicit capture would compile — and would silently bind the
// shared function to whatever a future site called its textures.
//
// `textureSampleLevel`, not `textureSample`: the LUT has one mip, and an
// explicit LOD keeps these reads free of the uniformity requirement that a
// sample after a conditional return would otherwise carry.
//
// **What the line is drawn in is `style`** (ADR-0197): `0` the soft darkening
// above, `1` a hard darkening over the same footprint, `2` a soft line in the
// palette's own colour at `ink_t` and `3` a hard one. `style` arrives rounded to
// a whole number from the CPU (`palette::band_contour_style`), so the equality
// comparisons below are exact. The `style < 0.5` arm is the expression that
// shipped before the other three existed, which is what keeps every golden still.
fn band_contour_ink(
    col: vec3<f32>,
    t: f32,
    steps: f32,
    amount: f32,
    style: f32,
    ink_t: f32,
    lut_a: texture_2d<f32>,
    lut_b: texture_2d<f32>,
    lut_samp: sampler,
    mix_ab: f32,
) -> vec3<f32> {
    let f = t * steps;
    let w = max(fwidth(f), 1e-5);
    if (steps < 1.5 || amount <= 0.0) {
        return col;
    }
    let n = round(f);
    let m = clamp(mix_ab, 0.0, 1.0);
    let lo = mix(
        textureSampleLevel(lut_a, lut_samp, vec2<f32>((n - 0.5) / steps, 0.5), 0.0).rgb,
        textureSampleLevel(lut_b, lut_samp, vec2<f32>((n - 0.5) / steps, 0.5), 0.0).rgb,
        m
    );
    let hi = mix(
        textureSampleLevel(lut_a, lut_samp, vec2<f32>((n + 0.5) / steps, 0.5), 0.0).rgb,
        textureSampleLevel(lut_b, lut_samp, vec2<f32>((n + 0.5) / steps, 0.5), 0.0).rgb,
        m
    );
    if (all(abs(hi - lo) < vec3<f32>(0.5 / 255.0))) {
        return col;
    }
    let d = min(fract(f), 1.0 - fract(f));
    if (style < 0.5) {
        return col * (1.0 - clamp(amount, 0.0, 1.0) * (1.0 - smoothstep(0.0, w, d)));
    }
    let hard = style == 1.0 || style == 3.0;
    let cover = select(1.0 - smoothstep(0.0, w, d), f32(d < w), hard);
    let ink_lut = mix(
        textureSampleLevel(lut_a, lut_samp, vec2<f32>(ink_t, 0.5), 0.0).rgb,
        textureSampleLevel(lut_b, lut_samp, vec2<f32>(ink_t, 0.5), 0.0).rgb,
        m
    );
    let ink = select(vec3<f32>(0.0), ink_lut, style >= 2.0);
    return mix(col, ink, clamp(amount, 0.0, 1.0) * cover);
}

@fragment
fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
    let t = params.a.x;
    let aspect = params.a.y;
    let warp = params.a.z;
    let hue = params.a.w;
    let zoom = params.b.x;
    let glow = params.b.y;
    let flash = params.b.z;
    let color_span = params.b.w;
    let pan = params.c.xy;
    let color_center = params.c.z;
    let saturation = params.c.w;
    let palette_mix = params.d.x;
    let palette_steps = params.d.z;
    let palette_contour = params.d.w;
    let fold_phase = params.e.x;
    let field_phase = params.e.y;
    let palette_contour_style = params.e.z;
    let palette_contour_ink = params.e.w;

    var uv = in.ndc;
    uv.x = uv.x * aspect;

    // Iterated sine-fold domain warp, scaled by zoom and folded by warp; `pan`
    // slides the sampled field window (the shared ViewTransform, ADR-0018). The
    // vignette below stays screen-anchored (uses unshifted `uv`).
    var p = uv * zoom + pan;
    // The fold's two rates keep their designed 0.7 : 0.6 quadrature ratio; what
    // `fold_speed` scales is the phase they share, so slowing the fold does not
    // flatten it the way `warp` does (ADR-0132).
    for (var i = 0; i < 5; i = i + 1) {
        let fi = f32(i);
        p = p + warp * vec2<f32>(
            sin(p.y * 1.5 + fold_phase * 0.7 + fi),
            cos(p.x * 1.5 - fold_phase * 0.6 + fi)
        ) / (fi + 1.0);
    }

    let field = 0.5 + 0.5 * sin(p.x + p.y + field_phase * 0.5);
    // Field level indexes the gradient LUT: `color_span` sets the spanned range
    // (was a fixed 0.6), `color_center`/`hue` slide the window. Linear-filtered,
    // repeat-addressed (a hue rotation wraps like the cosine wheel).
    let coord = field * color_span + color_center + hue;
    // Hard bands, then the contour drawn from the SAME coordinate (ADR-0078), so
    // the dark line follows the field's iso-lines and reads as structure rather
    // than as an outline of the picture's brightness.
    let banded = band_coord(coord, palette_steps);
    // Sample both palettes and crossfade by `palette_mix` (0 = A, 1 = B). When a
    // preset declares no [palette_b] the two LUTs are identical, so mix is a no-op.
    let ca = textureSample(lut_a, lut_samp, vec2<f32>(banded, 0.5)).rgb;
    let cb = textureSample(lut_b, lut_samp, vec2<f32>(banded, 0.5)).rgb;
    var col = mix(ca, cb, clamp(palette_mix, 0.0, 1.0));
    col = band_contour_ink(
        col, coord, palette_steps, palette_contour, palette_contour_style,
        palette_contour_ink, lut_a, lut_b, lut_samp, palette_mix
    );
    col = apply_saturation(col, saturation);

    let r = length(uv);
    col = col * (glow * (1.0 - 0.25 * r));
    col = col + vec3<f32>(flash * 0.12);

    // Alpha is `occlude` (`params.d.y`). The field covers every pixel, which is the
    // coverage it honestly has (ADR-0056), and `occlude` scales how much backdrop
    // survives underneath it (ADR-0085): the fold resolves `field + bg * (1 -
    // occlude)`, so at 1 the field replaces the backdrop and at 0 the backdrop adds
    // through at full strength. The renderer hands a value other than a literal 1.0
    // only when the scene draws straight onto the destination — with a post stage
    // routed, or the `over` junction live, the scene renders into a scratch and the
    // chain's last fold owns the seam instead.
    return vec4<f32>(col, params.d.y);
}
"#;

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct Params {
    a: [f32; 4],
    b: [f32; 4],
    c: [f32; 4],
    d: [f32; 4],
    e: [f32; 4],
}

/// Fullscreen domain-warped fragment field, driven by named preset parameters.
pub struct FragmentFieldScene {
    /// The pipeline, the uniform buffer, the 256×1 gradient LUT pair (A/B) the
    /// fragment samples + crossfades for colour (ADR-0021), and the two bind
    /// groups. The LUT group is **group 1**, separate from the uniform group, so
    /// this pipeline's layout does not match the kaleidoscope's.
    gpu: gpu::FullscreenScene,
    /// Shared scene clock (seconds), set by the renderer each frame.
    time: f32,
    /// This frame's elapsed real time, stored by `advance` and consumed by
    /// `update`, where the phases step against this frame's bound rates
    /// (ADR-0132).
    dt: f32,
    /// The integrated fold and field phases ([`Phase`]). **These are the scene's
    /// only state**: everything else here is derived from `time` and the
    /// parameters, so a capture's reproducibility now depends on the scene being
    /// rebuilt with the preset as well as on the clock resetting
    /// (`reset_for_capture` does both).
    ///
    /// They stay two accumulators rather than one, because each follows its own
    /// rate: `fold_speed` and `field_speed` are separately bindable.
    fold_phase: Phase,
    field_phase: Phase,
    /// Animation rates, in units of the scene's default speed (ADR-0132).
    field_speed: f32,
    fold_speed: f32,
    warp: f32,
    /// The shared palette knobs (ADR-0021). This scene has no `brightness`.
    colour: common::PaletteParams,
    /// The shared view transform (ADR-0018): `pan_*` offset the sampled field
    /// window, on top of `zoom`.
    pan: common::PanParams,
    zoom: f32,
    glow: f32,
    flash: f32,
    color_span: f32,
    color_center: f32,
    /// How much of this field's (total) coverage the backdrop resolves against
    /// (ADR-0085). Set by the renderer every frame through
    /// [`Scene::set_occlude`](super::Scene::set_occlude) — **not** a named param,
    /// so it is not reset by `reset_params`.
    occlude: f32,
}

impl FragmentFieldScene {
    /// Build the scene's pipeline and uniform buffer on `device`.
    pub fn new(device: &wgpu::Device, surface_format: wgpu::TextureFormat) -> Self {
        let shader = gpu::fullscreen_shader(
            device,
            "fragment-field-shader",
            gpu::FULLSCREEN_VS_NDC,
            SHADER,
        );
        let parts =
            gpu::FullscreenParts::new(device, "fragment-field", std::mem::size_of::<Params>());
        let uniform_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("fragment-field-uniform-layout"),
            entries: &[gpu::uniform(0, wgpu::ShaderStages::FRAGMENT)],
        });
        // The LUT texture + sampler live in their own group (group 1) — see the
        // WGSL note: keeping this pipeline's layout distinct from the
        // kaleidoscope's avoids the DX12 WARP identical-layout mis-render
        // (unverified on lavapipe as of 2026-10-06).
        let lut_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("fragment-field-lut-layout"),
            entries: &[
                gpu::texture(0, true),
                gpu::texture(1, true),
                gpu::sampler(2),
            ],
        });
        let uniform_bg = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("fragment-field-uniform-bg"),
            layout: &uniform_layout,
            entries: &[wgpu::BindGroupEntry {
                binding: 0,
                resource: parts.uniforms().as_entire_binding(),
            }],
        });
        let lut_bg = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("fragment-field-lut-bg"),
            layout: &lut_layout,
            entries: &parts.luts().bind_entries(0, 1, 2),
        });

        Self {
            gpu: parts.finish(
                device,
                &shader,
                &[&uniform_layout, &lut_layout],
                uniform_bg,
                Some(lut_bg),
                surface_format,
                wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING,
                "fragment-field",
            ),
            time: 0.0,
            dt: crate::render::scenes::FALLBACK_DT,
            fold_phase: Phase::default(),
            field_phase: Phase::default(),
            field_speed: DEFAULT_FIELD_SPEED,
            fold_speed: DEFAULT_FOLD_SPEED,
            warp: DEFAULT_WARP,
            colour: common::PaletteParams::new(DEFAULT_HUE, common::DEFAULT_BRIGHTNESS),
            pan: common::PanParams::default(),
            zoom: DEFAULT_ZOOM,
            glow: DEFAULT_GLOW,
            flash: DEFAULT_FLASH,
            color_span: DEFAULT_COLOR_SPAN,
            color_center: DEFAULT_COLOR_CENTER,
            occlude: crate::render::post::DEFAULT_OCCLUDE,
        }
    }
}

/// The parameter names this scene consumes — the vocabulary a preset binding
/// is checked against at load, so a typo is warned about instead of silently
/// doing nothing (ADR-0020). **Keep in sync with `set_param` below**; the
/// `declared_params_match_set_param` guard in `core/tests/suite/preset.rs` fails if
/// the two drift.
pub const PARAMS: &[ParamSpec] = &[
    ParamSpec {
        name: "warp",
        default: 0.4,
        range: Some([0.0, 1.5]),
        doc: "Amplitude of the domain fold; 0 flattens the field into plain bands.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: true,
    },
    ParamSpec {
        name: "field_speed",
        default: 1.0,
        range: Some([0.0, 4.0]),
        doc: "How fast the field itself drifts, as a multiple of its base rate.",
        kind: ParamKind::Modal,
        group: ParamGroup::Motion,
        main: true,
    },
    ParamSpec {
        name: "fold_speed",
        default: 1.0,
        range: Some([0.0, 4.0]),
        doc: "How fast the fold turns, independently of the field's own drift.",
        kind: ParamKind::Modal,
        group: ParamGroup::Motion,
        main: false,
    },
    crate::render::scenes::common::hue(DEFAULT_HUE),
    crate::render::scenes::common::field_zoom(DEFAULT_ZOOM),
    ParamSpec {
        name: "glow",
        default: 0.7,
        range: Some([0.0, 2.0]),
        doc: "Overall light the field emits, before the composite sees it.",
        kind: ParamKind::Modal,
        group: ParamGroup::Light,
        main: true,
    },
    ParamSpec {
        name: "flash",
        default: 0.0,
        range: Some([0.0, 1.0]),
        doc: "Lifts the whole field toward white, for a beat-driven blink.",
        kind: ParamKind::Modal,
        group: ParamGroup::Light,
        main: false,
    },
    crate::render::scenes::common::PAN_X,
    crate::render::scenes::common::PAN_Y,
    ParamSpec {
        name: "color_span",
        default: 0.6,
        range: Some([0.0, 1.0]),
        doc: "How much of the palette the field's range covers; 0 is one flat colour.",
        kind: ParamKind::Modal,
        group: ParamGroup::Colour,
        main: false,
    },
    ParamSpec {
        name: "color_center",
        default: 0.0,
        range: Some([-1.0, 1.0]),
        doc: "Shifts which part of the field's range lands in the middle of the palette.",
        kind: ParamKind::Modal,
        group: ParamGroup::Colour,
        main: false,
    },
    crate::render::scenes::common::SATURATION,
    crate::render::scenes::common::PALETTE_MIX,
    crate::render::scenes::common::PALETTE_STEPS,
    crate::render::scenes::common::PALETTE_CONTOUR,
    crate::render::scenes::common::PALETTE_CONTOUR_STYLE,
    crate::render::scenes::common::PALETTE_CONTOUR_INK,
];

impl Scene for FragmentFieldScene {
    fn name(&self) -> &'static str {
        "fragment field"
    }

    fn set_time(&mut self, time: f32) {
        self.time = time;
    }

    fn advance(&mut self, dt: f32) {
        // Stored, not integrated: `update` steps both phases, so the scene has
        // one integration site (ADR-0132).
        self.dt = dt;
    }

    fn set_occlude(&mut self, occlude: f32) {
        self.occlude = occlude;
    }

    fn set_palette(&mut self, palette: &Palette) {
        // Store the baked LUT; `render` uploads it (deferred so scenes with lazy
        // GPU resources share this seam). Cheap array copy, off the hot path.
        self.gpu.set_palette(palette);
    }

    fn reset_params(&mut self) {
        // The two rates reset with every other param; the PHASES do not — they
        // are state, and resetting them each frame would be the multiply this
        // ADR exists to remove.
        self.field_speed = DEFAULT_FIELD_SPEED;
        self.fold_speed = DEFAULT_FOLD_SPEED;
        self.warp = DEFAULT_WARP;
        self.colour.reset();
        self.pan.reset();
        self.zoom = DEFAULT_ZOOM;
        self.glow = DEFAULT_GLOW;
        self.flash = DEFAULT_FLASH;
        self.color_span = DEFAULT_COLOR_SPAN;
        self.color_center = DEFAULT_COLOR_CENTER;
    }

    fn set_param(&mut self, name: &str, value: f32) {
        // The shared param blocks first, this scene's own names after
        // (`scenes::common`).
        if self.colour.set(name, value) || self.pan.set(name, value) {
            return;
        }
        match name {
            "warp" => self.warp = value,
            "field_speed" => self.field_speed = value,
            "fold_speed" => self.fold_speed = value,
            "zoom" => self.zoom = value,
            "glow" => self.glow = value,
            "flash" => self.flash = value,
            "color_span" => self.color_span = value,
            "color_center" => self.color_center = value,
            _ => {}
        }
    }

    fn update(&mut self, _frame: &AnalysisFrame) {
        // Fully parameter-driven; the analysis reaches this scene only through
        // the preset expressions bound to its parameters. The one thing that
        // happens here is the phase integration, which runs after `set_param`
        // so it uses this frame's rates (ADR-0132).
        self.fold_phase.step(self.fold_speed, self.dt);
        self.field_phase.step(self.field_speed, self.dt);
    }

    fn render(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
    ) {
        // Upload the active palette LUTs (A + B) if a preset switch changed them
        // (off the hot path — once per switch, not per frame).
        self.gpu.flush_palette(queue);

        let params = Params {
            a: [self.time, aspect.max(0.1), self.warp, self.colour.hue],
            b: [self.zoom, self.glow, self.flash, self.color_span],
            c: [
                self.pan.x,
                self.pan.y,
                self.color_center,
                self.colour.saturation,
            ],
            d: [
                self.colour.mix,
                self.occlude,
                palette::band_steps(self.colour.steps),
                palette::band_contour(self.colour.contour),
            ],
            e: [
                self.fold_phase.get(),
                self.field_phase.get(),
                palette::band_contour_style(self.colour.contour_style),
                self.colour.contour_ink,
            ],
        };
        self.gpu.write_uniform(queue, &params);

        // Load over the engine backdrop (ADR-0018). The present blends
        // premultiplied-OVER with alpha `occlude`, so the backdrop resolves as
        // `field + bg * (1 - occlude)`: covered at 1 (exactly a replace), added
        // to at 0.
        self.gpu
            .draw(encoder, "fragment-field-pass", view, wgpu::LoadOp::Load);
    }
}

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

    /// The property ADR-0132 exists for, and the one a `time * rate` multiply
    /// fails: a rate change moves the phase by `rate * dt` **whatever the
    /// elapsed scene time**. Under a multiply the same change at t = 100 s
    /// would move the picture fifty seconds in one frame — a teleport, on a lane
    /// whose whole method is binding parameters to audio.
    #[test]
    fn a_rate_change_advances_the_phase_by_rate_times_dt_at_any_elapsed_time() {
        let dt = 1.0 / 60.0;
        let (mut fold, mut field) = (Phase::default(), Phase::default());
        // Run a long way out, so a multiply-by-elapsed-time would be obvious.
        for _ in 0..6_000 {
            fold.step(1.0, dt);
            field.step(1.0, dt);
        }
        let elapsed = fold.get();
        assert!(
            elapsed > 99.0,
            "the fixture must be far from t = 0: {elapsed}"
        );

        // Now the preset's binding moves, as an audio-bound rate does.
        let before = fold.get();
        fold.step(1.5, dt);
        let fold_step = fold.get() - before;
        assert!(
            (fold_step - 1.5 * dt).abs() < 1e-4,
            "the fold advanced {fold_step}, not {} — scaling with elapsed time is the defect",
            1.5 * dt
        );

        // And each accumulator carries its own rate: the pair is not welded.
        let field_before = field.get();
        field.step(0.25, dt);
        // Tolerance is above the f32 ulp at this magnitude (~7.6e-6 near 100),
        // which is the accumulation cost ADR-0132 accepts.
        assert!(
            (field.get() - field_before - 0.25 * dt).abs() < 1e-4,
            "the field phase must follow field_speed alone: moved {}",
            field.get() - field_before
        );
    }

    /// At a constant rate the integrated phase equals `rate * t` — which is why
    /// every shipped preset, all of which leave both parameters at their `1.0`
    /// default, renders unchanged. Asserted rather than assumed, because it is
    /// what makes moving no golden a property rather than an observation.
    #[test]
    fn a_constant_rate_integrates_to_rate_times_elapsed_time() {
        let dt = 1.0 / 60.0;
        for rate in [1.0f32, 0.4, 2.5] {
            let mut phase = Phase::default();
            let mut clock = 0.0f32;
            for _ in 0..600 {
                phase.step(rate, dt);
                clock += dt;
            }
            assert!(
                (phase.get() - rate * clock).abs() < 1e-3,
                "rate {rate}: integrated {} against {}",
                phase.get(),
                rate * clock
            );
        }
    }

    /// The default is exactly `1.0` on both, so the phase is bit-identical to
    /// the clock the three shader literals read — the capture path
    /// accumulates `time` the same way, one `FALLBACK_DT` per frame.
    #[test]
    fn the_default_rates_make_the_phase_the_clock() {
        assert_eq!(DEFAULT_FIELD_SPEED, 1.0);
        assert_eq!(DEFAULT_FOLD_SPEED, 1.0);

        let dt = crate::render::scenes::FALLBACK_DT;
        let (mut fold, mut field) = (Phase::default(), Phase::default());
        let mut clock = 0.0f32;
        for _ in 0..240 {
            fold.step(DEFAULT_FOLD_SPEED, dt);
            field.step(DEFAULT_FIELD_SPEED, dt);
            clock += dt;
        }
        assert_eq!(
            fold.get(),
            clock,
            "at rate 1.0 the accumulation must be bit-identical to the clock's"
        );
        assert_eq!(field.get(), clock);
    }
}