rlx_core/render/scenes/

mod.rs

//! Built-in scenes and the thin trait the renderer cycles through.
//!
//! Per ADR-0002 this stays crate-internal and minimal: it is the vocabulary
//! the future preset engine will drive, not a public extension point — no
//! plugin registration, no dynamic dispatch beyond what cycling needs.

// Hot-path panic-denial pragma (Plan 0002 Phase 2, extended to scenes by Plan
// 0003 Phase 0). Scene update/render run every displayed frame; a panic here
// is a visible crash mid-show.
#![deny(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::indexing_slicing,
    clippy::panic,
    clippy::unreachable
)]

pub mod analytic_field;
pub mod cellular;
pub(crate) mod common;
pub mod emitter;
pub mod fragment_field;
pub mod lines;
/// The shared mark-silhouette vocabulary the two particle scenes draw through
/// (ADR-0084). Crate-internal: it is arithmetic and a roster, not a scene.
pub(crate) mod marks;
pub mod particles;
pub mod plexus;
pub mod reaction_diffusion;
pub mod shape_collage;
pub mod shape_field;
pub mod swarm;
pub mod voxel;
pub mod warp_mesh;

use std::cell::RefCell;
use std::rc::Rc;

use crate::dsp::AnalysisFrame;
use crate::preset::SystemKind;
use crate::render::palette::Palette;

/// The `dt` (seconds) the C ABI's legacy `rlx_render` and the headless capture
/// primitives inject when a caller has no real elapsed time to supply — the
/// former fixed scene step, now demoted to a fallback (Plan 0014 Phase 2, ADR-0012).
/// The live frontends measure and inject real `dt` instead, so animation is
/// frame-rate-independent; capture uses this fixed value so a render is a pure
/// function of its inputs.
pub(crate) const FALLBACK_DT: f32 = 1.0 / 60.0;

/// What a parameter is **for** (ADR-0180 rule 2): whether its value carries an
/// integer meaning, which decides two things and nothing else — whether the
/// engine quantizes it before the scene sees it, and which of the generated
/// reference's two groups it prints under.
///
/// Orthogonal to `[hold]`: a hold reaches any bindable parameter whatever its
/// kind, and a kind quantizes whether or not the binding is held.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ParamKind {
    /// Continuous — every value in the range means something, and the scene
    /// reads the fraction. The default, and what every parameter was before
    /// kinds existed.
    #[default]
    Modal,
    /// Integer meaning: a mode number, a rule index, a count, a family. The
    /// engine rounds the post-smoothing value **once**, CPU-side, before
    /// `set_param`, so the scene is never handed 6.4 petals.
    Structural,
}

impl ParamKind {
    /// The name the generated reference and the exported schema print. Two
    /// readers, one spelling.
    pub fn as_str(self) -> &'static str {
        match self {
            ParamKind::Modal => "modal",
            ParamKind::Structural => "structural",
        }
    }

    /// `value` as the scene should receive it: rounded for a
    /// [`Structural`](Self::Structural) parameter, untouched for a
    /// [`Modal`](Self::Modal) one.
    ///
    /// **The last step before `set_param`**, after the hold has chosen which
    /// frame's value stands and the smoother has eased toward it — which is
    /// why a structural parameter that is *also* smoothed steps through the
    /// intervening integers rather than landing fractionally. An author who
    /// wants a clean jump leaves it out of `[smoothing]`.
    ///
    /// A non-finite value is passed through rather than rounded: `f32::round`
    /// leaves `NaN` alone anyway, and the scenes already guard their own
    /// inputs.
    pub fn quantize(self, value: f32) -> f32 {
        match self {
            ParamKind::Modal => value,
            ParamKind::Structural => value.round(),
        }
    }
}

/// What one named parameter is, as the engine declares it (ADR-0170).
///
/// A scene and an engine stage each declare their parameters as a `&[ParamSpec]`
/// rather than as a bare `&[&str]`. Three things read the same declaration: the
/// load-time check that a preset binding names something real, the constant a
/// scene applies at reset, and the generated reference table in
/// `presets/README.md`. Before this they were three copies, and only the names
/// were held together.
///
/// **The doc line is the definition; the roster's essay is the discussion.**
/// One sentence, saying what the parameter does — not restating its name.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ParamSpec {
    /// The name a preset binds, exactly as it is spelled in a `.toml`.
    pub name: &'static str,
    /// The value `reset_params` applies, and the one the reference prints.
    ///
    /// Read back out with [`default_of`], which resolves at compile time — so
    /// the scene's `DEFAULT_*` constants and this field are one number, not two.
    pub default: f32,
    /// The range that **reads**, for the table.
    ///
    /// Not a clamp and not a validation bound: it is what an author can expect
    /// to see a difference across. `None` where the parameter is unbounded or
    /// world-space, in which case the frame is the bound — inventing a number
    /// there would be a claim nothing holds.
    pub range: Option<[f32; 2]>,
    /// One sentence: what the parameter does.
    pub doc: &'static str,
    /// Whether the value carries an integer meaning (ADR-0180 rule 2).
    ///
    /// Read back out with [`kind_of`], and enforced by
    /// `declared_params_match_set_param` in `core/tests/suite/preset.rs`, which
    /// compares this against a hand-kept roster — a field nothing checks is a
    /// field that drifts.
    pub kind: ParamKind,
    /// Which of the five groups an editor files the parameter under (ADR-0256).
    pub group: ParamGroup,
    /// Whether the parameter is one of the few that most decide its system's
    /// look — listed first when its group is opened. One flag per declaration,
    /// not per preset: a parameter central to one preset is shown by the
    /// preset binding it.
    pub main: bool,
}

/// The group a parameter is filed under in an editor (ADR-0256), in the order
/// an editor lists them.
///
/// The engine-wide stages declare [`Post`](Self::Post), except the overall
/// exposure and the backdrop's brightness, which are [`Light`](Self::Light).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ParamGroup {
    /// What is drawn: form, count, mode, extent, framing.
    Shape,
    /// How it moves: speed, spin, drift, flow, anything over time.
    Motion,
    /// Hue, saturation, the palette and how the picture reads it.
    Colour,
    /// Brightness, glow, fade and the other amounts of light.
    Light,
    /// A pass over the finished frame: the backdrop, trails, mirroring,
    /// bloom, the ink remap.
    Post,
}

impl ParamGroup {
    /// Every group, in listing order.
    pub const ALL: [ParamGroup; 5] = [
        ParamGroup::Shape,
        ParamGroup::Motion,
        ParamGroup::Colour,
        ParamGroup::Light,
        ParamGroup::Post,
    ];

    /// The name the generated reference and the exported schema print.
    pub fn as_str(self) -> &'static str {
        match self {
            ParamGroup::Shape => "shape",
            ParamGroup::Motion => "motion",
            ParamGroup::Colour => "colour",
            ParamGroup::Light => "light",
            ParamGroup::Post => "post",
        }
    }
}

/// Byte-wise `str` equality, usable in a `const fn`.
///
/// `PartialEq` for `str` is not const, and this is only ever called at compile
/// time over rosters of a few dozen entries.
#[allow(
    clippy::indexing_slicing,
    reason = "compile-time only; a const fn cannot call `slice::get`, the bound is checked above each index, and a violation is a compile error"
)]
const fn str_eq(a: &str, b: &str) -> bool {
    let (a, b) = (a.as_bytes(), b.as_bytes());
    if a.len() != b.len() {
        return false;
    }
    let mut i = 0;
    while i < a.len() {
        if a[i] != b[i] {
            return false;
        }
        i += 1;
    }
    true
}

/// The default `name` is declared with, resolved **at compile time**.
///
/// This is what makes a scene's `DEFAULT_*` constant and its `ParamSpec` one
/// number rather than two copies of one: the constant is defined as a call to
/// this, so a default changed in the spec changes what `reset_params` applies,
/// and the generated table cannot state a value the engine does not use.
///
/// The linear scan costs nothing — it never runs at runtime — and a name with no
/// spec is a **compile error**, because a const-eval panic is.
#[allow(
    clippy::indexing_slicing,
    clippy::panic,
    reason = "compile-time only; the panic is the point, since a name no spec declares is then a compile error rather than anything a frame reaches"
)]
pub const fn default_of(specs: &[ParamSpec], name: &str) -> f32 {
    let mut i = 0;
    while i < specs.len() {
        if str_eq(specs[i].name, name) {
            return specs[i].default;
        }
        i += 1;
    }
    panic!("default_of: no ParamSpec declares that name");
}

/// The names in a spec roster, for the places that still want `&[&str]`.
///
/// Allocates, so it is for load-time validation and tests rather than a frame.
pub fn spec_names(specs: &[ParamSpec]) -> Vec<&'static str> {
    specs.iter().map(|spec| spec.name).collect()
}

/// Whether `name` is declared in `specs`. The load-time membership test.
pub fn declares(specs: &[ParamSpec], name: &str) -> bool {
    specs.iter().any(|spec| spec.name == name)
}

/// The [`ParamKind`] `name` is declared with in `specs`, or `None` where no
/// spec here declares it.
///
/// Load-time, like [`declares`]: the loader folds the answer onto the binding
/// so nothing per frame searches a roster by name (`[smoothing]`'s rule, for
/// its reason). A name no roster declares is already an ADR-0020 warning, and
/// an unclaimed binding reaches no scene, so its kind never matters.
pub fn kind_of(specs: &[ParamSpec], name: &str) -> Option<ParamKind> {
    specs
        .iter()
        .find(|spec| spec.name == name)
        .map(|spec| spec.kind)
}

/// Where one family-dependent parameter reads, on one family of a
/// family-bearing system (ADR-0180 rule 4).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FamilyRange {
    /// The family, spelled as a preset names it (`[curve] family = "..."`).
    pub family: &'static str,
    /// The range that reads on this family, in [`ParamSpec::range`]'s sense.
    /// `None` where the family **does not read the parameter at all** — the
    /// reference prints it as inert there rather than leaving it to be found.
    pub range: Option<[f32; 2]>,
}

/// A parameter whose meaning — and so whose reading range — depends on the
/// family its system draws.
///
/// The generated reference prints [`ranges`](Self::ranges) in place of the
/// single [`ParamSpec::range`], because one pair would be a claim nothing holds:
/// `parametric_curve`'s `n` reads `1..24` on a rose and `-8..8` on a
/// hypotrochoid. The spec's own range stays declared and is the one a family in
/// this list reads — the exported schema still carries one pair per parameter.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FamilyParam {
    /// The parameter, as its [`ParamSpec`] names it.
    pub name: &'static str,
    /// One entry per family of the system, in the system's roster order.
    pub ranges: &'static [FamilyRange],
}

/// The family-dependent parameters of the roster `label` names — as
/// `export::param_rosters` labels it — or nothing, for a system whose
/// parameters read the same on every family it draws.
pub fn family_params(label: &str) -> &'static [FamilyParam] {
    match label {
        "parametric_curve" => lines::parametric::FAMILY_PARAMS,
        "lsystem" => lines::lsystem::FAMILY_PARAMS,
        "analytic_field" => analytic_field::FAMILY_PARAMS,
        "cellular" => cellular::FAMILY_PARAMS,
        "plexus" => plexus::FAMILY_PARAMS,
        "attractor" => particles::FAMILY_PARAMS,
        "voxel" => voxel::FAMILY_PARAMS,
        _ => &[],
    }
}

/// One integrated animation phase — the only way a bindable rate advances
/// anything in this engine (ADR-0135, finishing the rule ADR-0132 stated).
///
/// **A rate multiplier has to be integrated to be a rate at all.** A phase
/// computed as `time * rate` lets a rate bound to audio retroactively rescale
/// *all* elapsed time on every frame: at t = 100 s a swing from `1.0` to `1.5`
/// moves the phase by fifty seconds in a single frame — the figure snaps to a
/// new position rather than accelerating toward it, on a lane whose whole
/// method is binding parameters to audio. Integrated, the same swing bends the
/// motion.
///
/// [`step`](Self::step) is the **only** mutator, and there is deliberately no
/// `Add`/`AddAssign`/`Deref`/`DerefMut` impl. The constraint is the value: with
/// one, a scene could write `phase + self.rate * self.time` and compile, which
/// is exactly the door this type exists to close.
///
/// # No constant scale is folded into the accumulation
///
/// A scene carrying its own fixed rate — the attractor's `SPIN_RATE` — applies
/// it where the phase is **read**, never inside the sum. The accumulator is then
/// `Σ (rate · dt)` with `rate` at its `1.0` default, i.e. `Σ dt` term for term:
/// bit-for-bit the same summation the renderer performs for its own clock, so
/// the integrated form reproduces the multiply it replaced *exactly* and no
/// golden baseline moves. Folding a `0.18` in would sum `0.18 · dt` instead and
/// drift in the last bits of every capture.
///
/// # It steps where this frame's rate has landed
///
/// The per-frame order is `reset_params` → `set_param` → `set_time` → `advance`
/// → `update` (`core/src/render/evaluate.rs`), so by the time either
/// [`Scene::advance`] or [`Scene::update`] runs, *this* frame's rate is the one
/// the scene holds. A scene may step a phase in either; the roster's rate
/// scenes store the `dt` `advance` hands them and step in `update`. The trap is
/// the sequence itself: moving `advance` back ahead of the bindings would make a
/// step taken there integrate the last frame's rate.
///
/// The type is arithmetic with no device in it, which is what keeps every rate
/// in the engine testable on the CPU without rendering anything.
#[derive(Clone, Copy, Default, Debug, PartialEq)]
pub(crate) struct Phase(f32);

impl Phase {
    /// One frame's integration, at *this* frame's rate.
    pub(crate) fn step(&mut self, rate: f32, dt: f32) {
        self.0 += rate * dt;
    }

    /// The accumulated phase, in rate-scaled seconds. A scene with its own
    /// constant scale applies it here, on the read.
    pub(crate) fn get(self) -> f32 {
        self.0
    }
}

/// Declarative structural config a scene consumes once at preset load
/// (ADR-0007): **not** expressions — the family / grammar / tiling the sampler
/// or generator builds from. Delivered through the optional
/// `Scene::configure` hook, off the hot path. This is
/// the shared structural-config enum for every scene that has one: the line
/// scenes' curve/L-system/star variants, plus the compute-particle attractor
/// family (Plan 0016) — it lives here rather than in `lines/` so `lines` never has to name a
/// `particles` type (Plan 0031 Phase 6).
#[derive(Debug, Clone)]
pub enum GeneratorConfig {
    /// A parametric curve: which family to sample.
    Curve {
        /// The curve family (Maurer rose, ...).
        family: lines::CurveFamily,
    },
    /// An L-system: a grammar the generator expands and turtle-walks at load,
    /// caching one segment buffer per depth.
    LSystem {
        /// The starting string.
        axiom: String,
        /// Production rules `(predecessor, successor)`.
        rules: Vec<(char, String)>,
        /// Turn angle in degrees for `+`/`-`.
        angle_deg: f32,
        /// Iterations to precompute (`1..=max_depth`), clamped to
        /// [`lines::MAX_LSYSTEM_DEPTH`] at load.
        max_depth: u32,
        /// Reserved seed for future stochastic rules; deterministic today.
        seed: u64,
        /// Which turtle walks the expansion, from `[generator] turtle`
        /// (ADR-0258). `Flat` is the default and the plane walk.
        turtle: lines::turtle::TurtleMode,
        /// How the figure grows, from `[generator] growth`: `Fixed`, the
        /// default, caches every depth; `Endless` walks a stream into a ring.
        growth: lines::lsystem::Growth,
        /// How many segments an endless figure keeps, from `[generator]
        /// trail`, validated at load against the stream's length and held to
        /// the tier's cap by the scene. Inert on a fixed figure.
        trail: u32,
        /// How many of an endless figure's newest segments its follow point is
        /// the centroid of, from `[generator] follow_window`. Inert on a fixed
        /// figure.
        follow_window: u32,
    },
    /// A Hankin star pattern: an `n`-fold star rosette built at load, with a few
    /// contact-angle variants a beat can switch between — and, since ADR-0079,
    /// an optional ring ornament drawn inside it.
    Star {
        /// Star order `n` (from the tiling), e.g. 6 or 12. **`0` means no
        /// interlace at all** (`tiling = "none"`), which the loader accepts only
        /// alongside a non-empty `rings` roster — the ornament drawn alone.
        order: u32,
        /// Contact angle in degrees; variants are precomputed around it.
        contact_angle_deg: f32,
        /// The `[generator] rings` roster (ADR-0079): concentric rings of
        /// repeated motifs filling the interior the rosette leaves hollow. Empty
        /// — the default, and what an absent `rings` key means — is exactly the
        /// pre-Plan-0065 scene.
        rings: Vec<lines::star::RingSpec>,
    },
    /// A GPU compute-particle attractor (Plan 0016): which strange-attractor map
    /// the compute step iterates. Not a line scene — reuses this shared enum so
    /// the family rides the existing `configure` hook (no new trait method).
    Particles {
        /// The attractor family (De Jong, Clifford, Thomas, Lorenz, or one of
        /// the IFS figures).
        family: particles::AttractorFamily,
        /// The figure the bindable `morph` param travels **towards** (ADR-0075),
        /// from `[particles] morph_to`. `None` — the default — pins the figure,
        /// so `morph` is inert.
        ///
        /// IFS-only, and validated as such at load: `morph_to` on a map family
        /// is a load error rather than a silent no-op, because the author asked
        /// for something the engine cannot do.
        morph_to: Option<particles::ifs::IfsFigure>,
        /// How much of the tier's particle budget is actually drawn (ADR-0069)
        /// — a count against the tier's anchor for a trace and a fraction of
        /// the target-scaled budget for a cloud, the band between them resolved
        /// by `active_particles` (ADR-0195) —
        /// validated at load into
        /// [`MIN_PARTICLE_DENSITY`](particles::MIN_PARTICLE_DENSITY)`..=1.0`.
        /// Structural, not bindable: an eased integer count would re-decide the
        /// picture every frame. `1.0` is the whole budget and the default.
        density: f32,
        /// The **tuple path** the bindable `morph` param walks along on a map
        /// family (ADR-0093), as `(from, to)` roster indices from
        /// `[particles] tuple_from` / `tuple_to`. `None` — the default — means
        /// there is no path and `morph` is inert, exactly as `morph_to` does for
        /// the IFS.
        ///
        /// **Both ends are structural on purpose.** The walk's framing is
        /// measured across it at load, which is thousands of map iterations; a
        /// path whose near end came from the per-frame `tuple` param would have
        /// to re-measure inside the frame loop every time that param moved.
        ///
        /// Map-family-only, and validated as such at load — the IFS reaches its
        /// own figure-to-figure travel through `morph_to` instead, and a tuple
        /// path on an IFS is a load error rather than a silent no-op.
        tuple_path: Option<(u32, u32)>,
    },
    /// The spectrum readout's `[spectrum]` table (Plan 0034 / ADR-0036): how many
    /// elements the frequency axis is divided into, how they are laid out, and how
    /// fast each one follows its band. All three are structure rather than
    /// expression — they are fixed for as long as the preset is loaded — so they
    /// ride the existing `configure` hook like every other declarative config.
    Spectrum {
        /// Element count, validated at load into
        /// `2..=`[`SPECTRUM_BINS`](crate::dsp::SPECTRUM_BINS).
        elements: usize,
        /// Which figure the elements form.
        layout: lines::SpectrumLayout,
        /// Per-element temporal easing in **seconds**, applied on the injected
        /// real `dt` — the same [`Easing`](crate::preset::Easing) the `[smoothing]`
        /// table uses, deliberately reused rather than a second vocabulary
        /// (ADR-0035).
        easing: crate::preset::Easing,
    },
    /// The warp mesh's `[mesh]` table (Plan 0100 / ADR-0113): the grid, in
    /// cells, that the per-vertex program is evaluated over.
    ///
    /// Structural for `[curve] family`'s reason — the vertex and index buffers
    /// are built from it, so an eased grid would rebuild them mid-frame — and
    /// **clamped to the tier at both consumers** rather than at load, since the
    /// loader does not know which tier will render the preset
    /// ([`warp_mesh::clamp_grid`]).
    WarpMesh {
        /// Requested cells, `(x, y)`, validated at load into
        /// [`MIN_MESH`](warp_mesh::MIN_MESH)`..=`[`MAX_MESH`](warp_mesh::MAX_MESH).
        mesh: (u32, u32),
        /// The compiled EEL2 programs a **converted** preset carries, from a
        /// `[milk]` table (Plan 0100 Phase 2 / ADR-0113). `None` — a
        /// hand-authored `warp_mesh` preset — drives the mesh from the ordinary
        /// `[params]` and `[per_vertex]` bindings instead, and executes no VM at
        /// all.
        ///
        /// Boxed because it is much the largest thing this enum carries and every
        /// other variant would pay for it by value.
        milk: Option<Box<crate::milk::MilkBundle>>,
        /// The salt the bundle's `rand()` draws under (ADR-0051).
        ///
        /// **The preset's `pinned_salt`, always** — its declared numeric seed, or
        /// `0` where it declared `seed = "random"`. So a bundle is a pure
        /// function of its inputs in the live app as well as in the harness,
        /// which is stronger than ADR-0051 requires and costs nothing: per-run
        /// variety is opt-in through `seed = "random"`, and no *converted* preset
        /// declares one. A hand-written bundle that does gets the pinned
        /// behaviour, and that is stated rather than discovered.
        salt: u32,
    },
    /// The shape field's `[path]` table (ADR-0107): an authored silhouette, as a
    /// closed contour parsed once at load from inline SVG path data.
    ///
    /// The one variant here carrying **geometry** rather than a selector or a
    /// size. It rides `configure` for the reason every other structural table
    /// does — it is fixed for as long as the preset is loaded — and a
    /// `shape_field` preset declaring no table gets `None` and draws the closed
    /// `marks` roster exactly as it did before paths existed.
    Path {
        /// The contour, normalized into `[-1, 1]` and resampled to the arity
        /// `[path] samples` asked for. `None` — a `shape_field` preset that
        /// declares no table — is what makes this config **always `Some`**: it
        /// is handed over on every preset switch precisely so `configure` runs
        /// and clears the outgoing preset's contour, the same reason the
        /// attractor's and the spectrum's configs are unconditional.
        shape: Option<crate::preset::path::PathShape>,
        /// The silhouette the bindable `morph` param travels **towards**, from
        /// `[path] morph_to`. `None` — the default — pins the figure, so `morph`
        /// is inert, exactly as the attractor's own `morph_to` does.
        ///
        /// Already **aligned** to `shape` at load: same arity, same winding, and
        /// the cyclic start that minimises total displacement (ADR-0107). The
        /// render layer interpolates the two point lists and re-derives none of
        /// that, which is what keeps an `O(N^2)` search off the frame.
        morph_to: Option<crate::preset::path::PathShape>,
    },
    /// The analytic field's `[field]` table (ADR-0180 rule 1): which closed-form
    /// family the pass draws. Always `Some` for that system, so `configure` runs
    /// on every preset switch and the outgoing preset's family never survives
    /// into the incoming one.
    Field(analytic_field::FieldConfig),
    /// The cellular system's `[cellular]` table (ADR-0180 rule 1): which
    /// automaton runs, on how large a grid, and the salt its seeding draws from.
    /// Always `Some` for that system, so `configure` runs on every preset switch
    /// and the incoming preset starts from its own seed.
    Cellular(cellular::CellularConfig),
    /// The plexus system's `[plexus]` table (ADR-0257): the layout, the point
    /// count and the seed. Always `Some` for that system, so `configure` runs on
    /// every preset switch and the incoming preset starts from its own points.
    Plexus(plexus::PlexusConfig),
    /// The waterfall's `[waterfall]` table (ADR-0180 rule 1): the band count,
    /// the row count, the push period and the per-band easing. Always `Some`
    /// for that system, so `configure` runs on every preset switch and the
    /// incoming preset starts from an empty ring.
    Waterfall(lines::waterfall::WaterfallConfig),
    /// The voxel system's `[voxel]` table (ADR-0268): the grid, the rule list,
    /// the seed ball and the edge rule, with the salt its seeding draws from.
    /// Always `Some` for that system, so `configure` runs on every preset
    /// switch and the incoming preset starts from its own seed.
    Voxel(voxel::VoxelConfig),
}

impl GeneratorConfig {
    /// How many elements a per-element binding should be evaluated for under this
    /// config, or `0` when the system has no per-element surface (Plan 0034 Phase
    /// 4). Read once at preset load to size the render layer's scratch.
    ///
    /// The count lives here rather than on `Scene` because it is **preset data**:
    /// it comes off the `[spectrum]` table, not out of the scene's state, and the
    /// renderer already holds the preset.
    pub fn element_count(&self) -> usize {
        match self {
            GeneratorConfig::Spectrum { elements, .. } => *elements,
            GeneratorConfig::Curve { .. }
            | GeneratorConfig::LSystem { .. }
            | GeneratorConfig::Star { .. }
            | GeneratorConfig::Particles { .. }
            | GeneratorConfig::WarpMesh { .. }
            | GeneratorConfig::Path { .. }
            | GeneratorConfig::Field(_)
            | GeneratorConfig::Cellular(_)
            | GeneratorConfig::Plexus(_)
            | GeneratorConfig::Waterfall(_)
            | GeneratorConfig::Voxel(_) => 0,
        }
    }
}

/// Which construction hit the segment cap, for the surfaced message.
///
/// An enum rather than a `String` because one of the two producers is **per
/// frame**: with a `String`, an audio-driven `mirror_order` sitting over the cap
/// builds a fresh `format!("mirror x{order}")` on every single frame for as long
/// as it stayed there — a heap allocation on the hot path (Plan 0031 Phase 4).
/// The formatting now happens only in [`Display`](std::fmt::Display), i.e. only
/// when something actually prints it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OverflowContext {
    /// An N-fold geometry mirror replicated past the cap — per frame, from the
    /// `mirror_order` param (Plan 0018 Phase 4).
    Mirror(u32),
    /// An L-system depth expanded past the cap — once, at preset load.
    Depth(u32),
    /// An escape-time `iterations` budget asked for past the tier's
    /// [`field_iterations`](crate::render::TierConfig::field_iterations) —
    /// per frame, since the budget is bindable. Carries what was asked; the
    /// [`CapOverflow`] carries the cap it was clamped to.
    ///
    /// Not a truncation of geometry but a clamp of a structural parameter, and
    /// the one case where the tier changes a preset's picture rather than its
    /// density (ADR-0045) — which is exactly why it must not be silent.
    Iterations(u32),
    /// A cellular `[cellular] grid` asked for past the tier's
    /// [`cellular_grid`](crate::render::TierConfig::cellular_grid) — once, at
    /// preset load, since the grid is structural. Carries what was asked.
    ///
    /// A clamp of content, like [`Iterations`](Self::Iterations): a pattern is
    /// a fixed number of cells, so a smaller grid draws every pattern larger.
    Grid(u32),
    /// A `larger_than_life` `radius` asked for past the tier's
    /// [`cellular_radius`](crate::render::TierConfig::cellular_radius) — per
    /// frame, since the radius is bindable. Carries what was asked.
    Radius(u32),
    /// A `[plexus] points` asked for past the tier's
    /// [`plexus_points`](crate::render::TierConfig::plexus_points) — at preset
    /// load, since the count is structural. Carries what was asked. A clamp of
    /// content: fewer points is a sparser network.
    Points(u32),
    /// A plexus graph that linked more pairs than the tier's
    /// [`plexus_edges`](crate::render::TierConfig::plexus_edges) — per frame,
    /// since `link_distance` is bindable. Carries how many linked; the surplus
    /// is dropped in index order.
    Edges(u32),
    /// An `aperture` asked for past the tier's
    /// [`max_coc_px`](crate::render::TierConfig::max_coc_px) — per frame, since
    /// `aperture` is bindable. Carries the aperture, in whole pixels: the blur
    /// of the far field, which the drawn blur stops short of.
    ///
    /// **Not the widest blur the lens draws.** In front of the focal plane the
    /// circle of confusion grows without bound as depth shrinks, so a close
    /// camera saturates the cap on every tier with any aperture at all; that
    /// saturation is the lens's ceiling, not an overflow, and is never
    /// announced (ADR-0257).
    Blur(u32),
    /// A space curve's `samples` asked for past the tier's
    /// [`seg3d_segments`](crate::render::TierConfig::seg3d_segments) — per
    /// frame, since `samples` is bindable. Carries what was asked. A clamp of
    /// content: the curve is walked from fewer points, so it is coarser.
    Samples(u32),
    /// A `[waterfall] rows` asked for past what the tier's
    /// [`seg3d_segments`](crate::render::TierConfig::seg3d_segments) draws at the
    /// preset's band count — at preset load, since the count is structural.
    /// Carries the rows asked and the segments one row costs (`elements - 1`);
    /// the [`CapOverflow`] carries the segment cap. A clamp of content: the
    /// landscape keeps less of the music.
    Rows(u32, u32),
    /// An endless L-system's `[generator] trail` asked for past the tier's
    /// cap for its turtle — [`seg3d_segments`](crate::render::TierConfig::seg3d_segments)
    /// in space, [`max_segments`](crate::render::TierConfig::max_segments) on
    /// the plane — at preset load, since the trail is structural. A clamp of
    /// content: the vine keeps fewer segments behind its tip.
    Trail {
        /// The trail asked for.
        asked: u32,
        /// Whether the figure walks in space, which names the cap that bit.
        space: bool,
    },
    /// A `[voxel] grid` asked for past the tier's
    /// [`voxel_grid`](crate::render::TierConfig::voxel_grid) — once, at preset
    /// load, since the grid is structural. Carries what was asked. A clamp of
    /// content: a structure is a fixed number of cells, so a smaller cube draws
    /// every structure larger.
    Voxels(u32),
}

impl std::fmt::Display for OverflowContext {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // These renderings are the user-visible text ADR-0007 requires stay
        // informative; the shell prints them verbatim. Do not reword them
        // without meaning to change what an operator sees.
        match self {
            OverflowContext::Mirror(order) => write!(f, "mirror x{order}"),
            OverflowContext::Depth(depth) => write!(f, "depth {depth}"),
            OverflowContext::Iterations(asked) => write!(f, "iterations {asked}"),
            OverflowContext::Grid(asked) => write!(f, "grid {asked}"),
            OverflowContext::Radius(asked) => write!(f, "radius {asked}"),
            OverflowContext::Points(asked) => write!(f, "points {asked}"),
            OverflowContext::Edges(linked) => write!(f, "{linked} links"),
            OverflowContext::Blur(asked) => write!(f, "an aperture of {asked} px"),
            OverflowContext::Samples(asked) => write!(f, "samples {asked}"),
            OverflowContext::Rows(asked, _) => write!(f, "rows {asked}"),
            OverflowContext::Trail { asked, .. } => write!(f, "trail {asked}"),
            OverflowContext::Voxels(asked) => write!(f, "grid {asked}"),
        }
    }
}

/// Reported when building a line scene's geometry hit the segment cap and
/// truncated. The cap must never be a silent cut (ADR-0007 Risks), so it travels
/// to the frontend two ways: out of `Scene::configure` at preset load, and off
/// `Scene::mirror_overflow` for the per-frame mirror. `None` is the normal case
/// where geometry fit.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CapOverflow {
    /// How many draw segments were dropped at the cap.
    pub dropped: usize,
    /// Where the drop happened, for the surfaced message.
    pub context: OverflowContext,
    /// **The cap that bit**, carried rather than read from a constant: it is a
    /// tier value now (Plan 0044), so the same preset overflows at 20 000
    /// segments on the floor and not at all at 60 000 on rich. A message naming a
    /// cap the run was not using would be worse than no message.
    pub cap: usize,
}

impl std::fmt::Display for CapOverflow {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Pinning the top tier is offered only where it would lift the cap: on
        // Rich it is the cap that bit, and a remedy naming the tier the run is
        // already on sends the operator nowhere.
        let pin = if self.top_tier_lifts() {
            ", or pin --tier rich"
        } else {
            ""
        };
        match self.context {
            // A clamp, not a cut: nothing is dropped, the picture is drawn at
            // the cap, and the operator is told which lever gets it back.
            OverflowContext::Iterations(_) => write!(
                f,
                "{} is past this quality tier's cap of {}; drawn at {} instead, so the \
                 set's boundary resolves less detail than the preset asked for \
                 (ask for {} or fewer{pin})",
                self.context, self.cap, self.cap, self.cap
            ),
            OverflowContext::Grid(_) => write!(
                f,
                "{} is past this quality tier's cap of {}; the automaton runs on a {}-cell \
                 grid instead, so every pattern draws larger than the preset asked \
                 (ask for {} or fewer{pin})",
                self.context, self.cap, self.cap, self.cap
            ),
            OverflowContext::Radius(_) => write!(
                f,
                "{} is past this quality tier's cap of {}; the neighbourhood is drawn at {} \
                 instead, which runs a different rule than the preset asked \
                 (ask for {} or fewer{pin})",
                self.context, self.cap, self.cap, self.cap
            ),
            OverflowContext::Points(_) => write!(
                f,
                "{} is past this quality tier's cap of {}; the network is drawn with {} \
                 points instead, so it is sparser than the preset asked \
                 (ask for {} or fewer{pin})",
                self.context, self.cap, self.cap, self.cap
            ),
            OverflowContext::Edges(_) => write!(
                f,
                "{} exceeded this quality tier's {}-link cap (dropped {}); lower \
                 link_distance or the point count{pin}",
                self.context, self.cap, self.dropped
            ),
            OverflowContext::Blur(_) => write!(
                f,
                "{} is past this quality tier's cap of {} px; drawn at {} px instead, so \
                 the background is sharper than the preset asked \
                 (ask for {} or fewer{pin})",
                self.context, self.cap, self.cap, self.cap
            ),
            OverflowContext::Samples(_) => write!(
                f,
                "{} is past this quality tier's cap of {}; the space curve is walked from {} \
                 points instead, so it is coarser than the preset asked \
                 (ask for {} or fewer{pin})",
                self.context, self.cap, self.cap, self.cap
            ),
            // `cap` is in segments; the rows kept are the whole rows it holds.
            OverflowContext::Rows(_, per_row) => {
                let kept = self.cap / per_row.max(1) as usize;
                write!(
                    f,
                    "{} is past this quality tier's {}-segment cap at this band count; the \
                     landscape keeps {kept} rows instead, so it shows less of the music than \
                     the preset asked (ask for {kept} or fewer, or fewer elements{pin})",
                    self.context, self.cap
                )
            }
            OverflowContext::Trail { .. } => write!(
                f,
                "{} is past this quality tier's cap of {}; the vine keeps {} segments \
                 instead, so less of it trails behind its tip than the preset asked \
                 (ask for {} or fewer{pin})",
                self.context, self.cap, self.cap, self.cap
            ),
            OverflowContext::Voxels(_) => write!(
                f,
                "{} is past this quality tier's cap of {}; the automaton runs in a {}-cell \
                 cube instead, so every structure draws larger than the preset asked \
                 (ask for {} or fewer{pin})",
                self.context, self.cap, self.cap, self.cap
            ),
            OverflowContext::Mirror(_) | OverflowContext::Depth(_) => write!(
                f,
                "geometry exceeded the {}-segment cap at {} (dropped {} segment(s)); \
                 reduce the structure or its depth",
                self.cap, self.context, self.dropped
            ),
        }
    }
}

impl CapOverflow {
    /// Whether the top tier's cap for this context is above the one that bit,
    /// so that pinning it would draw more of what the preset asked.
    ///
    /// Read off [`TierConfig::RICH`](crate::render::TierConfig::RICH) rather
    /// than carried, so no producer has to know which tier it runs on: a cap
    /// below Rich's can only have come from a lower tier, and a cap equal to it
    /// is the top tier's own.
    pub fn top_tier_lifts(&self) -> bool {
        let rich = crate::render::TierConfig::RICH;
        let top = match self.context {
            OverflowContext::Mirror(_) | OverflowContext::Depth(_) => rich.max_segments,
            OverflowContext::Iterations(_) => rich.field_iterations as usize,
            OverflowContext::Grid(_) => rich.cellular_grid as usize,
            OverflowContext::Radius(_) => rich.cellular_radius as usize,
            OverflowContext::Points(_) => rich.plexus_points as usize,
            OverflowContext::Edges(_) => rich.plexus_edges as usize,
            OverflowContext::Blur(_) => rich.max_coc_px as usize,
            OverflowContext::Samples(_) | OverflowContext::Rows(..) => rich.seg3d_segments as usize,
            OverflowContext::Trail { space: true, .. } => rich.seg3d_segments as usize,
            OverflowContext::Trail { space: false, .. } => rich.max_segments,
            OverflowContext::Voxels(_) => rich.voxel_grid as usize,
        };
        self.cap < top
    }

    /// The clearing of this overflow, worded in the same terms its onset was.
    ///
    /// Three of the five contexts clamp a structural parameter rather than
    /// cutting geometry, so one sentence cannot speak for all five: what came
    /// back is an iteration budget, a grid or a neighbourhood, not geometry and
    /// not segments. The shell holds the overflow that last bit and renders this
    /// off it, which keeps every word of the pair in this file.
    pub fn recovered(&self) -> Recovered<'_> {
        Recovered(self)
    }
}

/// The recovery sentence for a [`CapOverflow`], as a [`Display`](std::fmt::Display)
/// adapter rather than a `String` — the same reason [`OverflowContext`] is an
/// enum: formatting happens only where something prints.
pub struct Recovered<'a>(&'a CapOverflow);

impl std::fmt::Display for Recovered<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // User-visible text the shell prints verbatim, like the onset above.
        // No wildcard arm: a sixth context must choose its own sentence rather
        // than inherit one that does not describe it.
        let cap = self.0.cap;
        match self.0.context {
            OverflowContext::Mirror(_) | OverflowContext::Depth(_) => {
                write!(f, "geometry is back within this tier's {cap}-segment cap")
            }
            OverflowContext::Iterations(_) => write!(
                f,
                "the iteration budget is back within this tier's cap of {cap}"
            ),
            OverflowContext::Grid(_) => {
                write!(f, "the grid is back within this tier's cap of {cap}")
            }
            OverflowContext::Radius(_) => {
                write!(
                    f,
                    "the neighbourhood is back within this tier's cap of {cap}"
                )
            }
            OverflowContext::Points(_) => {
                write!(f, "the point count is back within this tier's cap of {cap}")
            }
            OverflowContext::Edges(_) => {
                write!(f, "the links are back within this tier's cap of {cap}")
            }
            OverflowContext::Blur(_) => {
                write!(f, "the aperture is back within this tier's cap of {cap} px")
            }
            OverflowContext::Samples(_) => {
                write!(
                    f,
                    "the sample count is back within this tier's cap of {cap}"
                )
            }
            OverflowContext::Rows(_, per_row) => {
                let kept = cap / per_row.max(1) as usize;
                write!(
                    f,
                    "the row count is back within this tier's cap of {kept} rows"
                )
            }
            OverflowContext::Trail { .. } => {
                write!(f, "the trail is back within this tier's cap of {cap}")
            }
            OverflowContext::Voxels(_) => {
                write!(f, "the grid is back within this tier's cap of {cap}")
            }
        }
    }
}

/// A scene that binds a parameter **per mesh vertex** (Plan 0100 Phase 1,
/// ADR-0113).
///
/// Reached through [`Scene::as_per_vertex_bound`], whose default is `None`
/// (ADR-0238): a `[per_vertex]` table aimed at a scene that has no vertices is
/// an absence the caller can act on, rather than a no-op body that returns and
/// leaves no trace. The loader already warns that such a table is inert.
pub(crate) trait PerVertexBound {
    /// Apply one named parameter as a per-vertex series: `values` holds one
    /// evaluation of the binding per mesh vertex, in row-major order from the
    /// top-left, `(meshx + 1) * (meshy + 1)` long.
    ///
    /// The per-element channel one axis up, and deliberately just as narrow: it
    /// carries `(name, &[f32])` in one direction and returns nothing.
    ///
    /// The slice borrows the renderer's scratch, sized at preset load from the
    /// same [`clamp_grid`](warp_mesh::clamp_grid) the scene uses, so nothing
    /// here allocates.
    fn set_per_vertex(&mut self, name: &str, values: &[f32]);
}

/// A scene that binds a parameter **per element** (Plan 0034 Phase 4,
/// ADR-0036).
///
/// Reached through [`Scene::as_series_bound`], whose default is `None`
/// (ADR-0238). A scene without a per-element surface does not silently swallow
/// the series: the caller takes element 0 through
/// [`Scene::set_param`](Scene::set_param) instead, which is the `index = 0`
/// reading the binding would have got outside a per-element evaluation.
pub(crate) trait SeriesBound {
    /// Apply one named parameter as a per-element series, in element order.
    /// Reached only for a binding whose expression names `index`.
    ///
    /// **This is the whole channel, and it is deliberately this narrow.** It
    /// carries `(name, &[f32])` in one direction and returns nothing. A scene
    /// cannot ask the preset layer for anything, cannot see the expression, and
    /// cannot learn which preset is loaded — so this is `set_param` with a
    /// slice, not an inversion in which scenes read presets. The slice borrows
    /// the renderer's scratch, which is sized at preset load, so nothing here
    /// allocates.
    ///
    /// A name this scene has no per-element row for is the implementor's own
    /// fallback, not the caller's: only the scene knows which of its parameters
    /// vary across elements.
    fn set_param_series(&mut self, name: &str, values: &[f32]);
}

/// A scene keeping a feedback field a probe can read **before** that scene's
/// present pass.
///
/// **`#[cfg(test)]`, and that gate is the whole justification.** ADR-0002 keeps
/// the scene seam thin and a real widening of it is ADR-worthy; this does not
/// exist in a shipped build, so the extension seam is unchanged. It exists
/// because Plan 0111 Phase 2's bisect requires its five seams to be read from
/// **one run** — same signal, same hop, same size, same adapter — and a
/// `Box<dyn Scene>` cannot otherwise be asked for the one quantity that sits
/// upstream of everything the bisect covers. Measuring seam A on a
/// separately-driven scene would satisfy the arithmetic and quietly break that
/// requirement.
#[cfg(test)]
pub(crate) trait FeedbackSource {
    /// The field, or `None` when this scene's GPU resources have not been built
    /// yet — so the outer [`Option`] says "no such capability" and the inner one
    /// says "not yet".
    fn feedback_field(&self) -> Option<&wgpu::Texture>;
}

/// A scene with a feedback accumulation of **its own**, which takes a preset's
/// `[feedback]` table (ADR-0048).
///
/// # One vocabulary, two buffers
///
/// **This is the routing contract, and it is worth stating plainly because it
/// will surprise someone.** The `fb_*` params and that table are consumed by
/// *two* sinks: the engine [`Trails`](crate::render::trails::Trails) stage,
/// which transforms the accumulation every scene composites through, and the
/// attractor scene's own internal trail field, which is what reaches here. A
/// preset may have **both** active at once — an attractor with `trails` on —
/// and then a single `fb_rotate` turns *both* accumulations, each about its own
/// buffer. Neither transforms the other's, and neither transforms the present
/// deposit: the transform applies to the past.
///
/// That is a deliberate design (ADR-0048's Alternative D was to give the engine
/// stage the vocabulary and leave the attractor out), and the reason it is safe
/// is that the two answer the same param names with the same arithmetic —
/// [`feedback::Transform`](crate::render::feedback::Transform) and one shared
/// WGSL snippet, not two implementations that must agree.
pub(crate) trait FeedbackSink {
    /// Take the active preset's `[feedback]` table. Invoked **once at preset
    /// load, off the hot path**, like [`Scene::configure`] and
    /// [`Scene::set_palette`]: a warp kind is a shader path, not a scalar.
    fn set_feedback(&mut self, cfg: crate::render::feedback::FeedbackConfig);
}

/// One visual. `update` advances state from the analysis frame; `render` draws
/// with the state it has.
///
/// Both built-in systems (fragment field, swarm) are preset-driven and
/// implement the named-parameter surface — `set_time`, `reset_params`,
/// `set_param` — that the preset layer evaluates into per frame (ADR-0002). The
/// trait carries no-op defaults so a future non-parametric scene need not.
///
/// # Capabilities are declared, not defaulted
///
/// A surface only some scenes have is a narrow trait of its own, reached
/// through an `as_*` accessor here whose default is `None` (ADR-0238). The
/// difference from a defaulted method is what the seam can *say*: a caller
/// asking a scene for a capability it lacks gets an absence it can act on
/// rather than a body that returns having done nothing.
pub(crate) trait Scene {
    fn name(&self) -> &'static str;
    fn update(&mut self, frame: &AnalysisFrame);
    fn render(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
    );

    /// The pixel size of the target **this scene renders into this frame**
    /// (ADR-0030). That is *not* always the surface: the composite chain routes
    /// the scene into the first active post stage's input, which is a fixed
    /// internal grid for the trails and kaleidoscope stages and the surface
    /// otherwise, so the only correct value is the one the chain reports back
    /// (`PostChain::begin`).
    /// A scene that accumulates into an internal offscreen field sizes that field
    /// from here, so it matches its target instead of upscaling from a fixed grid
    /// or supersampling into a smaller offscreen; every other scene ignores it.
    ///
    /// **Called unconditionally every frame**, immediately before
    /// [`render`](Self::render) — it is named for what it carries, not for an
    /// event, and there is no resize event behind it. So ADR-0030 condition 2
    /// binds every implementor: **compare against what you already built and do
    /// nothing when unchanged**, and never allocate or build GPU resources here.
    /// The attractor records the requested grid and lets the next `render` notice
    /// the difference.
    ///
    /// Default no-op, in the same spirit as [`advance`](Self::advance): the
    /// renderer already holds the size in `draw_frame`, and `Scene` is a `dyn`
    /// trait, so this is the only channel that reaches a scene with it (Plan 0027
    /// Phase 2, the third and first hot-path widening — ADR-0030).
    fn set_target_size(&mut self, _width: u32, _height: u32) {}

    /// How much of the renderer's grid scale (ADR-0245) the size handed to
    /// [`set_target_size`](Self::set_target_size) does **not** already carry —
    /// the fraction a scene sizing an internal field of its own still applies.
    ///
    /// The value depends on the frame's route, which is why it cannot ride
    /// `configure`: into a post stage the target is that stage's grid, already
    /// scaled, and this is `1.0`; straight into the destination the target is
    /// the display's own size and this is the whole scale. A field sized from the
    /// target alone would therefore be drawn at the square of the scale whenever
    /// a stage is active.
    ///
    /// **Called unconditionally every frame**, immediately before
    /// `set_target_size`, and under the same ADR-0030 obligations: record the
    /// value and compare, never build or allocate here. Default no-op — only the
    /// attractor has a field to size.
    fn set_grid_scale(&mut self, _scale: crate::render::tier::GridScale) {}

    /// How much of this scene's coverage the **backdrop** resolves against, for
    /// the frame it is about to render (ADR-0085). `1.0` is coverage-as-occlusion
    /// — what every frame did before `occlude` existed — and `0.0` is light that
    /// adds without covering.
    ///
    /// **Called unconditionally every frame**, immediately before
    /// [`render`](Self::render), in the same spirit as
    /// [`set_target_size`](Self::set_target_size). The renderer hands a literal
    /// `1.0` whenever a post stage is active, because then the scene draws into a
    /// scratch offscreen with no backdrop under it and the chain's last stage owns
    /// the seam instead — a scene must never apply this twice.
    ///
    /// Only a scene that **presents premultiplied over the backdrop** (ADR-0026 —
    /// the reaction-diffusion, cellular, attractor and warp-mesh presents, and the
    /// fragment-field, analytic-field, shape-field and shape-collage fullscreen
    /// fields) has anything to do here. Such a scene writes `occlude` into its
    /// alpha and its present pipeline blends `PREMULTIPLIED_ALPHA_BLENDING`, so
    /// the backdrop resolves as `scene + bg * (1 - occlude)`; at the literal `1.0`
    /// that blend is exactly a replace. The additive families draw through
    /// [`gpu::ADDITIVE_LIGHT_SATURATING_COVERAGE`](crate::render::gpu::ADDITIVE_LIGHT_SATURATING_COVERAGE),
    /// whose colour destination factor is `One`: with no stage active their light
    /// already adds to the backdrop rather than replacing it, so there is no
    /// occlusion at that seam for this to scale. Default no-op.
    fn set_occlude(&mut self, _occlude: f32) {}

    /// This scene as a [`FeedbackSource`], or `None` — which is every scene but
    /// the warp mesh.
    #[cfg(test)]
    fn as_feedback_source(&self) -> Option<&dyn FeedbackSource> {
        None
    }

    /// Advance simulation state by `dt` real seconds (Plan 0014 Phase 2). The
    /// renderer injects the elapsed time each frame; a feedback scene steps its
    /// fixed-timestep accumulator here and a CPU-integrated scene (the swarm)
    /// scales its motion by `dt`, so both look identical over wall-clock time on
    /// any refresh rate. Stateless, purely `time`-driven scenes ignore it.
    ///
    /// **Called after this frame's parameters are applied** — after
    /// [`reset_params`](Self::reset_params), every binding, the live overrides
    /// and the per-vertex table, and after [`set_time`](Self::set_time) —
    /// and immediately before [`update`](Self::update). A value a scene reads
    /// here is the one this frame bound, so a rate may be integrated in
    /// `advance` or in `update` and both are correct (ADR-0198).
    ///
    /// **`dt` is finite and strictly positive.** The renderer guarantees it,
    /// substituting [`FALLBACK_DT`] for a degenerate delta before this is called
    /// (ADR-0152), so an implementor may store it, integrate it, or divide by it
    /// without checking. **Do not re-check it per scene**: the guarantee is
    /// invisible from inside a scene, and this sentence is the whole of what
    /// stands between a shell's raw delta and every accumulator behind this
    /// trait — a second copy at one site makes it a rule enforced by a list of
    /// sites again, which is the failure the seam exists to end.
    fn advance(&mut self, _dt: f32) {}

    /// Set the shared scene clock (seconds). The renderer owns the single clock
    /// so an expression's `time` and the system's animation never diverge.
    fn set_time(&mut self, _time: f32) {}
    /// Reset every named parameter to its default (called each frame before the
    /// active preset's bindings are applied, so unbound params don't leak).
    fn reset_params(&mut self) {}
    /// Apply one named parameter; unknown names are ignored.
    fn set_param(&mut self, _name: &str, _value: f32) {}

    /// This scene as a [`SeriesBound`], or `None` — which is every scene but the
    /// spectrum readout.
    ///
    /// The caller degrades a series to element 0 on `None`, so a scene that
    /// never opts in behaves byte-for-byte as it did when that fallback was a
    /// default body here.
    fn as_series_bound(&mut self) -> Option<&mut dyn SeriesBound> {
        None
    }

    /// This scene as a [`PerVertexBound`], or `None` — which is every scene but
    /// the warp mesh.
    ///
    /// Unlike [`as_series_bound`](Self::as_series_bound) there is no degrading
    /// on `None`: a per-vertex series varies over space and its first element is
    /// the top-left corner, which is not a sensible whole-scene reading of
    /// anything. The caller stops evaluating the table instead.
    fn as_per_vertex_bound(&mut self) -> Option<&mut dyn PerVertexBound> {
        None
    }

    /// Consume a preset's declarative structural config (ADR-0007). Invoked
    /// **once at preset load, off the hot path** — a generator builds and caches
    /// its geometry here; a parametric scene records its family. Default no-op,
    /// so non-line scenes (fragment field, swarm) never implement it. The one
    /// optional widening of this trait ADR-0007 sanctions — keep it to this.
    ///
    /// Returns [`Some`](lines::CapOverflow) when building the geometry hit the
    /// segment cap and truncated, so the frontend can surface it — the cap is
    /// never a silent cut (ADR-0007 Risks). `None` means it fit (the norm).
    fn configure(&mut self, _cfg: &lines::GeneratorConfig) -> Option<lines::CapOverflow> {
        None
    }

    /// Consume a preset's baked color [`Palette`] (ADR-0021). Invoked **once at
    /// preset load, off the hot path** — a shader-colored scene stores the baked
    /// LUT and uploads it to its 256×1 texture (or samples it on the CPU) on the
    /// next frame; a non-colored scene (the line scenes) ignores it. Default
    /// no-op. The second and last thin off-hot-path widening of this trait after
    /// ADR-0007's [`configure`](Scene::configure).
    fn set_palette(&mut self, _palette: &Palette) {}

    /// This scene as a [`FeedbackSink`], or `None` — which is every scene but
    /// the attractor.
    fn as_feedback_sink(&mut self) -> Option<&mut dyn FeedbackSink> {
        None
    }

    /// The per-frame cap overflow, if this frame hit one: the line scenes'
    /// geometry mirror (Plan 0018 Phase 4) when its N-fold replication exceeded
    /// the segment cap and truncated, the analytic field's escape-time budget
    /// when a bound `iterations` passed the tier's cap and was clamped, or the
    /// cellular system's `radius` likewise. Reuses the ADR-0007
    /// [`CapOverflow`](lines::CapOverflow) so the frontend surfaces any of them
    /// — a cap is never silent. Default `None`.
    fn mirror_overflow(&self) -> Option<&lines::CapOverflow> {
        None
    }
}

/// The registry: every built-in scene, **keyed by the [`SystemKind`] it drives**,
/// in [`SystemKind::ALL`] order. All scenes are created up front so switching
/// mid-show is a lookup, never a hitch.
///
/// The keying is the point: the renderer addresses a scene by the kind its preset
/// names, so a scene cannot silently end up in the wrong slot. Nothing here is
/// positional — reordering [`SystemKind::ALL`] reorders construction and nothing
/// else.
pub(crate) fn create_all(
    device: &wgpu::Device,
    surface_format: wgpu::TextureFormat,
    tier: &crate::render::TierConfig,
    budget: crate::render::SampleBudget,
) -> Vec<(SystemKind, Box<dyn Scene>)> {
    // One shared line renderer for every line scene (ADR-0007: "one line
    // renderer"). A single instanced-quad pipeline + segment buffer, borrowed by
    // whichever line scene is active — only one draws per frame. (Two separate
    // line pipelines with byte-identical vertex layouts also mis-render on the
    // DX12 WARP software adapter, a WARP reading unverified on lavapipe as of
    // 2026-10-06; one renderer avoids it.)
    // `new_with_arcs`, not `new`: `star_pattern`'s circular motifs are one arc
    // instance each (ADR-0098), and the arc buffer holds
    // `max_segments` because the two kinds share **one** budget — everything
    // that passes `build_rings`'s cap check must reach the GPU, or a cap would
    // be silently cutting geometry, which ADR-0007 forbids.
    // `new_split_with_arcs`: any of the four line systems may ask for the
    // opacity-preserving seam through `stroke_blend` (ADR-0138), and the
    // pipelines are built here rather than when a preset first selects one —
    // building a GPU resource mid-run changes what a later pass resolves to on
    // the DX12 software adapter (a WARP reading, unverified on lavapipe as of
    // 2026-10-06).
    let line_renderer = Rc::new(RefCell::new(lines::LineRenderer::new_split_with_arcs(
        device,
        surface_format,
        tier.max_segments,
        tier.max_segments,
        "lines",
    )));
    SystemKind::ALL
        .iter()
        .map(|&kind| {
            (
                kind,
                create(
                    kind,
                    device,
                    surface_format,
                    &mut || line_renderer.clone(),
                    tier,
                    budget,
                ),
            )
        })
        .collect()
}

/// A scene constructed **for one preset's `[layer]`** (ADR-0090 point 4, Plan
/// 0076 Phase 2), never taken from the roster — which is what makes same-system
/// pairs legal and keeps two dissolving sides' layers from sharing anything.
/// The stateful families duplicate their GPU state by construction: their
/// constructors are already self-contained (a second reaction-diffusion
/// ping-pong field, a second particle buffer), so this is the same exhaustive
/// [`create`] the roster uses, differing only in where a line scene gets its
/// renderer.
///
/// # The `LineRenderer` answer, recorded (the Phase 2 discovery duty)
///
/// **A layer line scene gets its own `LineRenderer`; the shared one is not
/// shareable between two live line draws in one frame.** `LineRenderer::draw`
/// uploads its instance and uniform buffers through `Queue::write_buffer`, and
/// queued writes are applied before the submission's passes execute — so two
/// draws through one renderer in one frame would both rasterize the *second*
/// draw's segments under the second draw's uniforms. Making it shareable would
/// need a partitioned instance buffer and per-draw uniform slots — a redesign
/// of the idiom, not constructor plumbing — so duplication is the answer, at
/// one pipeline plus one `max_segments` instance buffer per layered line
/// preset.
///
/// The duplicate is built **only when the layer is a line system**: a
/// fragment/swarm/particle layer pays no line pipeline, and WARP's documented
/// sensitivity to coexisting identical pipeline layouts (ADR-0058 / Plan 0053)
/// is only ever exercised by a preset that actually declares a line layer.
/// (That sensitivity is a WARP reading, unverified on lavapipe as of
/// 2026-10-06.)
pub(crate) fn create_layer_scene(
    kind: SystemKind,
    device: &wgpu::Device,
    surface_format: wgpu::TextureFormat,
    tier: &crate::render::TierConfig,
    budget: crate::render::SampleBudget,
) -> Box<dyn Scene> {
    create(
        kind,
        device,
        surface_format,
        &mut || {
            // Arcs too — a `[layer]` may be a `star_pattern`, and a layer that
            // could not draw them would render a mandala with its circles
            // missing rather than fail.
            Rc::new(RefCell::new(lines::LineRenderer::new_split_with_arcs(
                device,
                surface_format,
                tier.max_segments,
                tier.max_segments,
                "layer-lines",
            )))
        },
        tier,
        budget,
    )
}

/// Whether two systems' scenes share mutable GPU state, so **one frame must not
/// render both**.
///
/// Two facts make this true, and only one of them is obvious. The roster is keyed
/// by kind, so the same kind is literally the same `Box<dyn Scene>`. Less
/// obviously, the three **line** scenes deliberately share one `LineRenderer` —
/// "borrowed by whichever line scene is active, only one draws per frame" (see
/// [`create_all`]) — so two *different* line kinds are just as unrenderable in one
/// frame as one kind twice.
///
/// Plan 0023's dual-live dissolve is the first caller: it composites two presets
/// in a single frame, which is exactly what this forbids. A pair that shares
/// resources falls back to the frozen snapshot.
///
/// **This is a statement about the roster's instances only.** A `[layer]`
/// scene ([`create_layer_scene`], Plan 0076 Phase 2) is constructed per preset
/// and shares nothing with the roster or with another preset's layer by
/// construction — so a preset's own main-plus-layer pair never consults this,
/// whatever the two systems are.
pub(crate) fn shares_resources(a: SystemKind, b: SystemKind) -> bool {
    a == b || (kind_info(a).shares_line_renderer && kind_info(b).shares_line_renderer)
}

/// The render-side static facts about a [`SystemKind`] — what is true of the
/// *kind*, as opposed to what a built scene can be asked (ADR-0238 part 3).
///
/// These stay kind facts because they are asked where no scene exists:
/// [`shares_resources`] is consulted about a **roster preset** whose scene may
/// never have been constructed, which is why no accessor on `Scene` can replace
/// it. They stay in `render/` because each is a render implementation detail
/// and none belongs in the preset schema.
pub(crate) struct SceneKindInfo {
    /// Whether this kind draws through the roster's one shared
    /// [`LineRenderer`](lines::LineRenderer) — "borrowed by whichever line scene
    /// is active, only one draws per frame" (see [`create_all`]). So two
    /// *different* line kinds are as unrenderable in one frame as one kind
    /// twice.
    pub(crate) shares_line_renderer: bool,
}

/// The static facts about `kind`, in **one exhaustive table** with no wildcard
/// arm, like [`create`] itself: a new system fails to compile here until
/// someone says which side of every fact it is on.
///
/// The next such fact is a **field on [`SceneKindInfo`]**, not a fifteenth
/// fourteen-arm match of its own — that accumulation is what ADR-0238 part 3
/// ended.
pub(crate) fn kind_info(kind: SystemKind) -> SceneKindInfo {
    // `waterfall` is a line system that answers `false`: it draws through a
    // `seg3d` renderer of its own and never borrows the shared 2D one.
    let shares_line_renderer = match kind {
        SystemKind::ParametricCurve
        | SystemKind::LSystem
        | SystemKind::StarPattern
        | SystemKind::Spectrum => true,
        SystemKind::FragmentField
        | SystemKind::Swarm
        | SystemKind::ReactionDiffusion
        | SystemKind::Attractor
        | SystemKind::Emitter
        | SystemKind::ShapeField
        | SystemKind::WarpMesh
        | SystemKind::ShapeCollage
        | SystemKind::AnalyticField
        | SystemKind::Cellular
        | SystemKind::Plexus
        | SystemKind::Waterfall
        | SystemKind::Voxel => false,
    };
    SceneKindInfo {
        shares_line_renderer,
    }
}

/// Build the scene a [`SystemKind`] drives.
///
/// An **exhaustive** `match` with no wildcard arm — the same guard the golden
/// drift fixtures use: adding a variant fails to compile here until its scene is
/// constructed, so a new system cannot ship unbuilt or wired to the wrong scene.
///
/// `line_renderer` is a **source**, called only by the line arms: the roster
/// hands out clones of its one shared renderer, a layer construction builds a
/// fresh one on demand ([`create_layer_scene`]) — and a non-line kind builds
/// none at all.
fn create(
    kind: SystemKind,
    device: &wgpu::Device,
    surface_format: wgpu::TextureFormat,
    line_renderer: &mut dyn FnMut() -> Rc<RefCell<lines::LineRenderer>>,
    tier: &crate::render::TierConfig,
    budget: crate::render::SampleBudget,
) -> Box<dyn Scene> {
    match kind {
        SystemKind::FragmentField => Box::new(fragment_field::FragmentFieldScene::new(
            device,
            surface_format,
        )),
        SystemKind::Swarm => Box::new(swarm::SwarmScene::new(
            device,
            surface_format,
            tier.swarm_particles,
            tier.swarm_max_coc_px.min(tier.max_coc_px) as f32,
        )),
        SystemKind::ParametricCurve => Box::new(lines::ParametricCurveScene::new(
            line_renderer(),
            tier.max_segments,
            device,
            surface_format,
            tier.seg3d_segments as usize,
            tier.max_coc_px as f32,
        )),
        SystemKind::LSystem => Box::new(lines::LSystemScene::new(
            line_renderer(),
            tier.max_segments,
            device,
            surface_format,
            tier.seg3d_segments as usize,
            tier.max_coc_px as f32,
        )),
        SystemKind::StarPattern => Box::new(lines::StarPatternScene::new(
            line_renderer(),
            tier.max_segments,
        )),
        SystemKind::ReactionDiffusion => Box::new(reaction_diffusion::ReactionDiffusionScene::new(
            device,
            surface_format,
        )),
        SystemKind::Attractor => Box::new(create_attractor(device, surface_format, tier, budget)),
        SystemKind::Spectrum => Box::new(lines::SpectrumScene::new(
            line_renderer(),
            tier.max_segments,
        )),
        SystemKind::Emitter => Box::new(emitter::EmitterScene::new(
            device,
            surface_format,
            tier.emitter_objects,
        )),
        SystemKind::ShapeField => {
            Box::new(shape_field::ShapeFieldScene::new(device, surface_format))
        }
        SystemKind::WarpMesh => Box::new(warp_mesh::WarpMeshScene::new(
            device,
            surface_format,
            tier.mesh_grid,
            tier.max_segments,
        )),
        SystemKind::ShapeCollage => Box::new(shape_collage::ShapeCollageScene::new(
            device,
            surface_format,
            tier.collage_elements,
        )),
        SystemKind::AnalyticField => Box::new(analytic_field::AnalyticFieldScene::new(
            device,
            surface_format,
            tier.field_iterations,
        )),
        SystemKind::Cellular => Box::new(cellular::CellularScene::new(
            device,
            surface_format,
            tier.cellular_radius,
            tier.cellular_grid,
            tier.cellular_route_rate,
        )),
        SystemKind::Plexus => Box::new(plexus::PlexusScene::new(
            device,
            surface_format,
            tier.plexus_points as usize,
            tier.plexus_edges as usize,
            tier.max_coc_px as f32,
        )),
        SystemKind::Waterfall => Box::new(lines::WaterfallScene::new(
            device,
            surface_format,
            tier.seg3d_segments as usize,
            tier.max_coc_px as f32,
        )),
        SystemKind::Voxel => Box::new(voxel::VoxelScene::new(
            device,
            surface_format,
            tier.voxel_grid,
            tier.voxel_march_scale,
            tier.voxel_march_cap,
        )),
    }
}

/// The attractor scene [`create`] builds, as its concrete type.
///
/// **The ceiling choice lives here and nowhere else** (ADR-0140): a window gets
/// the tier's live cap, a headless render its offline one. Named rather than
/// inlined into the factory arm so a test can build exactly what the factory
/// builds and read the resolved budget off it, without restating the choice it
/// is asserting about.
fn create_attractor(
    device: &wgpu::Device,
    surface_format: wgpu::TextureFormat,
    tier: &crate::render::TierConfig,
    budget: crate::render::SampleBudget,
) -> particles::AttractorScene {
    particles::AttractorScene::new(
        device,
        surface_format,
        tier.attractor_particles,
        match budget {
            crate::render::SampleBudget::Live => tier.attractor_particles_live_ceiling,
            crate::render::SampleBudget::Offline => tier.attractor_particles_offline_ceiling,
        },
        tier.attractor_trail_cap,
        tier.max_coc_px as f32,
    )
}

/// Tiny deterministic RNG (splitmix64) so visual randomness is explicitly
/// seeded (NFR 6) without pulling a rand crate.
pub(crate) struct SeededRng(u64);

impl SeededRng {
    pub(crate) fn new(seed: u64) -> Self {
        Self(seed)
    }

    fn next_u64(&mut self) -> u64 {
        self.0 = self.0.wrapping_add(0x9E37_79B9_7F4A_7C15);
        let mut z = self.0;
        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
        z ^ (z >> 31)
    }

    /// Uniform in [0, 1).
    pub(crate) fn next_f32(&mut self) -> f32 {
        (self.next_u64() >> 40) as f32 / (1u64 << 24) as f32
    }

    /// Uniform in [lo, hi).
    pub(crate) fn range(&mut self, lo: f32, hi: f32) -> f32 {
        lo + (hi - lo) * self.next_f32()
    }
}

#[cfg(test)]
mod tests {
    //! The scene-keying contract (Plan 0030 Phase 3), and the parameter-kind
    //! quantizer declared beside it. Test asserts panic freely; this is not the
    //! render path.
    #![allow(clippy::panic, clippy::expect_used)]

    use super::{CapOverflow, OverflowContext, ParamKind, Scene, create_all, create_attractor};
    use crate::preset::SystemKind;
    use crate::render::context::{RenderContext, RenderError};

    /// **`pin --tier rich` is offered only where Rich would lift the cap.** At
    /// a cap below the top tier's the remedy names it; at the top tier's own
    /// cap it does not, in every context that offers it.
    #[test]
    fn the_tier_remedy_is_offered_only_below_the_top_tier() {
        let rich = crate::render::TierConfig::RICH;
        for (context, top) in [
            (
                OverflowContext::Iterations(5000),
                rich.field_iterations as usize,
            ),
            (OverflowContext::Grid(4096), rich.cellular_grid as usize),
            (OverflowContext::Radius(40), rich.cellular_radius as usize),
            (OverflowContext::Points(9000), rich.plexus_points as usize),
            (OverflowContext::Edges(90_000), rich.plexus_edges as usize),
            (OverflowContext::Blur(30), rich.max_coc_px as usize),
            (
                OverflowContext::Samples(90_000),
                rich.seg3d_segments as usize,
            ),
            (OverflowContext::Rows(900, 63), rich.seg3d_segments as usize),
            (
                OverflowContext::Trail {
                    asked: 90_000,
                    space: true,
                },
                rich.seg3d_segments as usize,
            ),
            (
                OverflowContext::Trail {
                    asked: 90_000,
                    space: false,
                },
                rich.max_segments,
            ),
            (OverflowContext::Voxels(512), rich.voxel_grid as usize),
        ] {
            let below = CapOverflow {
                dropped: 1,
                context,
                cap: top / 2,
            };
            assert!(
                below.to_string().contains("pin --tier rich"),
                "{context} under a lower tier's cap: {below}"
            );
            let at_top = CapOverflow {
                dropped: 1,
                context,
                cap: top,
            };
            assert!(
                !at_top.to_string().contains("--tier"),
                "{context} at the top tier's cap: {at_top}"
            );
        }
    }

    /// **Each context's recovery is worded in that context's own terms.** Three
    /// of the five clamp a structural parameter rather than cutting geometry, so
    /// a line telling an operator that "geometry is back within the segment cap"
    /// after an iteration, grid or radius clamp names something that never
    /// overflowed.
    #[test]
    fn each_overflow_context_recovers_in_its_own_words() {
        for (context, word) in [
            (OverflowContext::Mirror(8), "geometry"),
            (OverflowContext::Depth(9), "geometry"),
            (OverflowContext::Iterations(600), "iteration budget"),
            (OverflowContext::Grid(512), "grid"),
            (OverflowContext::Radius(7), "neighbourhood"),
            (OverflowContext::Points(900), "point count"),
            (OverflowContext::Edges(30_000), "links"),
            (OverflowContext::Blur(30), "aperture"),
            (OverflowContext::Samples(30_000), "sample count"),
            // One segment a row, so the rows kept are the 20000 asserted below.
            (OverflowContext::Rows(30_000, 1), "row count"),
            (
                OverflowContext::Trail {
                    asked: 30_000,
                    space: true,
                },
                "trail",
            ),
            (OverflowContext::Voxels(512), "grid"),
        ] {
            let overflow = CapOverflow {
                dropped: 0,
                context,
                cap: 20_000,
            };
            let text = overflow.recovered().to_string();
            assert!(
                text.contains(word),
                "{context}'s recovery does not name {word}: {text}"
            );
            assert!(
                text.contains("20000"),
                "{context}'s recovery does not carry the cap that bit: {text}"
            );
            let structural = matches!(
                context,
                OverflowContext::Iterations(_)
                    | OverflowContext::Grid(_)
                    | OverflowContext::Radius(_)
                    | OverflowContext::Points(_)
                    | OverflowContext::Edges(_)
                    | OverflowContext::Blur(_)
                    | OverflowContext::Samples(_)
                    | OverflowContext::Rows(..)
                    | OverflowContext::Trail { .. }
                    | OverflowContext::Voxels(_)
            );
            if structural {
                assert!(
                    !text.contains("segment") && !text.contains("geometry"),
                    "{context} is a clamp of a structural parameter, and its recovery \
                     still speaks of geometry: {text}"
                );
            }
        }
    }

    /// `Structural` rounds and `Modal` does not — the whole of what a kind
    /// changes about a value.
    ///
    /// **Nothing else can see this work or fail.** The engine's `Structural`
    /// roster is confined to parameters whose scene already clamps and rounds
    /// the value itself, so `quantize` composes to the identity everywhere it
    /// currently runs and no rendered assertion distinguishes it from being
    /// absent (design-backlog 0197). This covers it directly instead.
    #[test]
    fn a_structural_kind_rounds_and_a_modal_one_hands_the_value_through() {
        // Rust rounds a half AWAY FROM ZERO, and a scene indexing a closed
        // roster with the result depends on which way 6.5 goes, so the
        // direction is pinned here rather than assumed.
        for (value, rounded) in [
            (6.4_f32, 6.0_f32),
            (6.5, 7.0),
            (6.6, 7.0),
            (-6.4, -6.0),
            (-6.5, -7.0),
            (3.0, 3.0),
            (0.0, 0.0),
        ] {
            assert_eq!(
                ParamKind::Structural.quantize(value),
                rounded,
                "Structural must round {value}"
            );
            assert_eq!(
                ParamKind::Modal.quantize(value),
                value,
                "Modal must hand {value} through untouched"
            );
        }

        // The property behind the table, over a sweep that lands on no integer
        // by construction: a Structural value equals its own round, and
        // quantizing it again moves nothing.
        for i in -400..400 {
            let value = i as f32 * 0.0137;
            let q = ParamKind::Structural.quantize(value);
            assert_eq!(q, q.round(), "Structural produced the non-integral {q}");
            assert_eq!(
                ParamKind::Structural.quantize(q),
                q,
                "quantizing an already-quantized {q} moved it"
            );
            assert_eq!(
                ParamKind::Modal.quantize(value),
                value,
                "Modal moved {value}"
            );
        }

        // A non-finite value survives, which is what the type's own doc claims:
        // `f32::round` has no special case for one and neither does this.
        assert!(ParamKind::Structural.quantize(f32::NAN).is_nan());
        assert_eq!(ParamKind::Structural.quantize(f32::INFINITY), f32::INFINITY);
        assert_eq!(
            ParamKind::Structural.quantize(f32::NEG_INFINITY),
            f32::NEG_INFINITY
        );
    }

    /// The scene each system is *supposed* to drive, written independently of the
    /// factory so the two can disagree. This is the mapping the old magic-index
    /// `system_slot` lookup could never assert: it named a position, and nothing
    /// checked the position held the right scene.
    fn expected_scene_name(system: SystemKind) -> &'static str {
        match system {
            SystemKind::FragmentField => "fragment field",
            SystemKind::ShapeField => "shape field",
            SystemKind::Swarm => "swarm",
            SystemKind::ParametricCurve => "parametric curve",
            SystemKind::LSystem => "l-system",
            SystemKind::StarPattern => "star pattern",
            SystemKind::ReactionDiffusion => "reaction diffusion",
            SystemKind::Attractor => "attractor",
            SystemKind::Spectrum => "spectrum",
            SystemKind::Emitter => "emitter",
            SystemKind::WarpMesh => "warp mesh",
            SystemKind::ShapeCollage => "shape collage",
            SystemKind::AnalyticField => "analytic field",
            SystemKind::Cellular => "cellular",
            SystemKind::Plexus => "plexus",
            SystemKind::Waterfall => "waterfall",
            SystemKind::Voxel => "voxel",
        }
    }

    /// **The factory is what chooses the ceiling**, and the two choices resolve
    /// different budgets at the same target (ADR-0140).
    ///
    /// Read off the scene rather than recomputed: this is the wiring under test,
    /// so a recomputation of the law here would pass with the factory handing
    /// both modes the same number. [`create_attractor`] is the factory's own
    /// ceiling choice, reached for its concrete type because the budget is a
    /// property of this scene and not of the `Scene` seam (ADR-0238).
    /// 1920x1080 is the size the whole plan is about — nine times the
    /// reference — and it is past the live ceiling and under the offline one,
    /// which is what makes the two answers differ.
    ///
    /// No frame is rendered: `set_target_size` is CPU arithmetic, so this costs
    /// one scene build on the software adapter and nothing else.
    #[test]
    fn the_render_path_resolves_a_larger_budget_than_a_window_does() {
        use crate::render::{SampleBudget, TierConfig};

        let ctx = match RenderContext::new_headless(64, 64, true) {
            Ok(ctx) => ctx,
            Err(RenderError::RequestAdapter(_)) => {
                eprintln!("skipped: no GPU adapter on this runner (ADR-0016)");
                return;
            }
            Err(e) => panic!("headless context build failed: {e}"),
        };

        let resolved = |budget: SampleBudget, tier: &TierConfig, w: u32, h: u32| -> Option<u32> {
            let mut scene = create_attractor(&ctx.device, ctx.surface_format(), tier, budget);
            // Before a target size reaches it, a scene has no resolved budget to
            // report - which is the distinction the `None` carries.
            assert_eq!(scene.sample_budget(), None);
            scene.set_target_size(w, h);
            scene.sample_budget()
        };

        let rich = TierConfig::RICH;
        assert_eq!(
            resolved(SampleBudget::Offline, &rich, 1920, 1080),
            Some(1_350_000),
            "a render at 1080p must reach the law's own value, not the live cap"
        );
        assert_eq!(
            resolved(SampleBudget::Live, &rich, 1920, 1080),
            Some(rich.attractor_particles_live_ceiling),
            "a window at 1080p is held at the live ceiling"
        );

        // Deposits per output pixel, stated as sample arithmetic (an image
        // statistic would be the wrong instrument - the ones this repo has are
        // themselves resolution-bound). The render reaches the 640x360
        // reference density exactly; today's flat count delivers a ninth of it.
        const PX: u32 = 1920 * 1080;
        let render = 1_350_000_f64 / f64::from(PX);
        let reference =
            f64::from(rich.attractor_particles) / f64::from(crate::render::REFERENCE_PX);
        assert!(
            (render - reference).abs() < 1e-9,
            "a 1080p render deposits {render} samples per pixel against the reference {reference}"
        );
        assert_eq!(1_350_000 / rich.attractor_particles, 9);

        // And the small captures are untouched at BOTH ceilings, which is the
        // half that keeps every baseline where it is.
        for tier in [TierConfig::FLOOR, TierConfig::RICH] {
            for budget in [SampleBudget::Live, SampleBudget::Offline] {
                assert_eq!(
                    resolved(budget, &tier, 128, 128),
                    Some(tier.attractor_particles),
                    "{:?}/{budget:?} moved the golden suite's count",
                    tier.tier
                );
            }
        }
    }

    /// **At a full grid scale the budget is today's at every size this suite
    /// names** (ADR-0245), and a fraction is what moves it.
    ///
    /// "Before" is the density law against the target alone —
    /// [`attractor_budget`](crate::render::attractor_budget) of `w * h`, the
    /// expression the scene evaluated before the grid scale existed — and
    /// "after" is read off the factory's scene with the scale handed to it the
    /// way the composite hands it. Every tier and both ceilings, because the
    /// floor's live ceiling is its anchor and would pass whatever the law did:
    /// the rich rows are where a count could move.
    ///
    /// The half-scale row is the non-vacuity: a 1080p field at 0.5 holds a
    /// quarter of the target's texels, so the rich live budget falls from its
    /// ceiling to 2.25x the anchor.
    #[test]
    fn a_full_grid_scale_resolves_todays_budget_at_every_suite_size() {
        use crate::render::tier::GridScale;
        use crate::render::{SampleBudget, TierConfig, attractor_budget};

        let ctx = match RenderContext::new_headless(64, 64, true) {
            Ok(ctx) => ctx,
            Err(RenderError::RequestAdapter(_)) => {
                eprintln!("skipped: no GPU adapter on this runner (ADR-0016)");
                return;
            }
            Err(e) => panic!("headless context build failed: {e}"),
        };

        for tier in [TierConfig::FLOOR, TierConfig::RICH] {
            for budget in [SampleBudget::Live, SampleBudget::Offline] {
                let ceiling = match budget {
                    SampleBudget::Live => tier.attractor_particles_live_ceiling,
                    SampleBudget::Offline => tier.attractor_particles_offline_ceiling,
                };
                for (w, h) in [(128, 128), (640, 360), (1920, 1080)] {
                    let before = attractor_budget(tier.attractor_particles, w * h, ceiling);
                    let mut scene =
                        create_attractor(&ctx.device, ctx.surface_format(), &tier, budget);
                    scene.set_grid_scale(GridScale::FULL);
                    scene.set_target_size(w, h);
                    assert_eq!(
                        scene.sample_budget(),
                        Some(before),
                        "{:?}/{budget:?} at {w}x{h}: the full-scale budget moved",
                        tier.tier
                    );
                }
            }
        }

        let rich = TierConfig::RICH;
        let mut scene =
            create_attractor(&ctx.device, ctx.surface_format(), &rich, SampleBudget::Live);
        scene.set_grid_scale(GridScale::new(0.5).expect("in range"));
        scene.set_target_size(1920, 1080);
        assert_eq!(
            scene.sample_budget(),
            Some(337_500),
            "a half-scale 1080p field holds 518 400 texels, 2.25x the reference"
        );
    }

    /// **The built scene draws a trace's anchor count out of an unchanged
    /// budget** (ADR-0195), at 1920x1080 under both ceilings.
    ///
    /// The sibling above pins the budget; this pins what is drawn out of it, and
    /// the pair is the statement that only the drawn count moved. Read off the
    /// scene for that test's reason — a recomputation here would pass with
    /// `configure` never reaching `active_count` at all, which is one of the two
    /// call sites that has to pass the anchor.
    ///
    /// No frame is rendered: both accessors are CPU arithmetic.
    #[test]
    fn a_trace_preset_draws_its_anchor_count_at_1080p() {
        use crate::render::{SampleBudget, TierConfig};

        let ctx = match RenderContext::new_headless(64, 64, true) {
            Ok(ctx) => ctx,
            Err(RenderError::RequestAdapter(_)) => {
                eprintln!("skipped: no GPU adapter on this runner (ADR-0016)");
                return;
            }
            Err(e) => panic!("headless context build failed: {e}"),
        };

        // `density = 0.02` is the shipped trace value — `attractor_lorenzknot`
        // and `fragment_sumi`'s layer among them.
        const DENSITY: f32 = 0.02;
        let rich = TierConfig::RICH;

        for (budget, expected) in [
            (SampleBudget::Live, rich.attractor_particles_live_ceiling),
            (SampleBudget::Offline, 1_350_000),
        ] {
            let mut scene = create_attractor(&ctx.device, ctx.surface_format(), &rich, budget);
            // The preset switch order: `configure` carries the density, and the
            // first frame's `set_target_size` carries the target.
            scene.configure(&super::lines::GeneratorConfig::Particles {
                family: crate::render::scenes::particles::AttractorFamily::Thomas,
                density: DENSITY,
                morph_to: None,
                tuple_path: None,
            });
            scene.set_target_size(1920, 1080);

            assert_eq!(
                scene.active_sample_count(),
                Some(3_000),
                "{budget:?} at 1080p Rich draws the anchor's count for a trace"
            );
            assert_eq!(
                scene.sample_budget(),
                Some(expected),
                "{budget:?} at 1080p Rich resolves an unchanged budget"
            );
            // Non-vacuity: the budget is what the old expression took the
            // fraction of, and it is nine times (or four times) the count above.
            assert_ne!((expected as f32 * DENSITY).round() as u32, 3_000);
        }
    }

    /// Every `SystemKind::ALL` entry builds the scene that kind is supposed to
    /// drive, and the roster covers exactly the roster — so transposing two
    /// factory arms — which silently points every preset of one system at
    /// another's scene — fails here.
    ///
    /// Needs a GPU adapter to build the scenes, so it skips on runners without
    /// one (ADR-0016).
    #[test]
    fn every_kind_builds_the_scene_it_drives() {
        let ctx = match RenderContext::new_headless(64, 64, true) {
            Ok(ctx) => ctx,
            Err(RenderError::RequestAdapter(_)) => {
                eprintln!("skipped: no GPU adapter on this runner (ADR-0016)");
                return;
            }
            Err(e) => panic!("headless context build failed: {e}"),
        };

        let scenes = create_all(
            &ctx.device,
            ctx.surface_format(),
            &crate::render::TierConfig::FLOOR,
            crate::render::SampleBudget::Live,
        );

        let kinds: Vec<SystemKind> = scenes.iter().map(|(kind, _)| *kind).collect();
        assert_eq!(
            kinds,
            SystemKind::ALL.to_vec(),
            "the roster is exactly SystemKind::ALL, in its order"
        );

        for (kind, scene) in &scenes {
            assert_eq!(
                scene.name(),
                expected_scene_name(*kind),
                "system {} must drive its own scene",
                kind.as_str()
            );
        }
    }

    /// The **freeze veto** a dual-live dissolve rests on (Plan 0023 Phase 4): a
    /// pair of systems that would have to render one mutable object twice in a
    /// frame must report shared resources, so the governor never upgrades it.
    ///
    /// GPU-free — this is the mapping, not the rendering. It closes the half the
    /// governor's own test has to assume: `dual_live_eligible` is asserted to
    /// refuse a shared pair, and here is what makes a pair shared.
    #[test]
    fn a_pair_that_cannot_render_twice_reports_shared_resources() {
        // Same kind is the same `Box<dyn Scene>` — the same-scene case that must
        // always freeze, whatever the frame budget says.
        for kind in SystemKind::ALL {
            assert!(
                super::shares_resources(kind, kind),
                "{} against itself is one scene object",
                kind.as_str()
            );
        }

        // Two *different* line systems are just as unrenderable together: they
        // borrow one shared `LineRenderer` (see `create_all`).
        let lines = [
            SystemKind::ParametricCurve,
            SystemKind::LSystem,
            SystemKind::StarPattern,
            SystemKind::Spectrum,
        ];
        for a in lines {
            for b in lines {
                assert!(
                    super::shares_resources(a, b),
                    "{} and {} share the line renderer",
                    a.as_str(),
                    b.as_str()
                );
            }
        }

        // Everything else holds independent state, so a dissolve between them may
        // run both sides live.
        let independent = [
            SystemKind::FragmentField,
            SystemKind::Swarm,
            SystemKind::ReactionDiffusion,
            SystemKind::Attractor,
            SystemKind::Emitter,
            SystemKind::ShapeField,
            SystemKind::WarpMesh,
            SystemKind::ShapeCollage,
            SystemKind::AnalyticField,
            SystemKind::Cellular,
            SystemKind::Plexus,
            SystemKind::Waterfall,
        ];
        for (i, a) in independent.iter().enumerate() {
            for b in independent.iter().skip(i + 1).chain(lines.iter()) {
                assert!(
                    !super::shares_resources(*a, *b),
                    "{} and {} hold independent GPU state",
                    a.as_str(),
                    b.as_str()
                );
            }
        }
    }
}