rlx_core/render/scenes/lines/

parametric.rs

//! Parametric-curve scene: a pure `t -> (x, y)` curve resampled every frame
//! into the shared [`LineRenderer`] (ADR-0007 parametric build model). Phase 1
//! is hardcoded to one Maurer rose that gently rotates on the deterministic
//! scene clock; Phase 2 makes the curve family and every named parameter
//! preset-driven so audio can sweep it live.
//!
//! ## The colour axis: **position along the traced path** (ADR-0059)
//!
//! This scene honours `[palette]` / `[palette_b]` / `palette_mix` / `hue_spread`
//! / `saturation` through the shared `ColorRamp`, and the axis its generator
//! makes meaningful is **how far along the walk a chord sits**: `0` at the first
//! sampled point, `1` at the last. On a Maurer rose that is the drawn-stroke
//! reading — the web is one continuous walk, so the ramp travels along it the way
//! a pen would.
//!
//! **Normalized over `samples`, not over the revealed prefix.** `draw_progress`
//! is a reveal, so a chord's place on the curve is a property of the curve; if
//! the divisor were the drawn count, a per-beat `draw_progress` would drag every
//! chord's colour with it and the figure would re-tint rather than draw itself
//! on. Revealing half the curve therefore shows the palette's first half.
//!
//! `hue_spread = 0` collapses the ramp to the single `hue` this scene has always
//! drawn, so the surface is a strict superset.

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

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

use super::super::common;
use super::super::{FALLBACK_DT, Phase, Scene};
use super::biarc::Piece;
use super::renderer::{
    ArcInstance, LineRenderer, Segment3dInstance, SegmentInstance, StrokeMetric, joined_chord,
};
use super::{
    CapOverflow, ColorRamp, CurveFamily, GeneratorConfig, MirrorSpec, OverflowContext,
    ViewTransform, curves, replicate_mirror,
};
use crate::dsp::AnalysisFrame;
use crate::render::camera::{self, CameraParams};
use crate::render::palette::Palette;
use crate::render::scenes::{
    FamilyParam, FamilyRange, ParamGroup, ParamKind, ParamSpec, default_of,
};

// Parameter defaults — a calm, whole, slowly turning rose when nothing is bound.
const DEFAULT_N: f32 = default_of(PARAMS, "n");
const DEFAULT_D: f32 = default_of(PARAMS, "d");
// Shape params (ADR-0029): both no-ops by default, so an unbound rose is the
// plain `sin(n*theta)` curve — `phase` adds inside the sine, `radial_offset`
// adds to the radius.
const DEFAULT_PHASE: f32 = default_of(PARAMS, "phase");
const DEFAULT_RADIAL_OFFSET: f32 = default_of(PARAMS, "radial_offset");
// The family levers: each is read by one family and inert on the rest.
const DEFAULT_PEN: f32 = default_of(PARAMS, "pen");
const DEFAULT_SYM: f32 = default_of(PARAMS, "sym");
const DEFAULT_SHARPNESS: f32 = default_of(PARAMS, "sharpness");
const DEFAULT_LOBE: f32 = default_of(PARAMS, "lobe");
const DEFAULT_DECAY: f32 = default_of(PARAMS, "decay");
const DEFAULT_TUBE: f32 = default_of(PARAMS, "tube");
const DEFAULT_M: f32 = default_of(PARAMS, "m");
const DEFAULT_PHASE_Z: f32 = default_of(PARAMS, "phase_z");
const DEFAULT_SAMPLES: f32 = default_of(PARAMS, "samples");
const DEFAULT_THICKNESS: f32 = 2.0;
const DEFAULT_HUE: f32 = 0.6;
/// Colour surface (ADR-0021 / ADR-0059), at the value that reproduces the single
/// flat `hue` this scene drew before the palette reached it: no ramp along the path.
/// The palette-A-alone and unmodified-saturation halves of that rest in
/// `scenes::common`, which every system shares them with.
const DEFAULT_HUE_SPREAD: f32 = 0.0;
const DEFAULT_SPIN: f32 = default_of(PARAMS, "spin");
const DEFAULT_SCALE: f32 = 0.9;
const DEFAULT_BRIGHTNESS: f32 = 1.0;
/// The line renderer's **per-segment falloff** multiplier (Plan 0038 Phase 1) —
/// not a post-process bloom. `1.0` is the value every line scene passed as a
/// literal before it was bound, so the default is exactly today's look.
const DEFAULT_GLOW: f32 = 1.0;
const DEFAULT_DRAW_PROGRESS: f32 = 1.0;
// Shared view transform (ADR-0018): identity by default, so an unbound preset is
// unchanged.
const DEFAULT_ZOOM: f32 = 1.0;
// Geometry mirror (Phase 4): identity by default (one copy, no reflection).
const DEFAULT_MIRROR_ORDER: f32 = 1.0;
const DEFAULT_MIRROR_REFLECT: f32 = 0.0;

/// A parametric line curve of any [`CurveFamily`], sampled per frame and driven
/// by named preset parameters over the audio analysis.
pub struct ParametricCurveScene {
    /// The single line renderer, shared with the other line scenes (ADR-0007:
    /// "one line renderer"). Only the active scene draws in a frame, so the
    /// shared pipeline + buffer are never contended.
    renderer: Rc<RefCell<LineRenderer>>,
    /// Reused draw buffer — the mirrored geometry actually rendered. Preallocated
    /// to the cap so replication never allocates on the hot path.
    segments: Vec<SegmentInstance>,
    /// Reused buffer for the single (pre-mirror) sampled curve, replicated into
    /// [`segments`](Self::segments) by [`replicate_mirror`]. Preallocated.
    single_buf: Vec<SegmentInstance>,
    /// [`segments`](Self::segments)' arc half, and its pre-mirror source — the
    /// G1 chain a **smooth** walk is fitted to (ADR-0098, Plan 0087 Phase 5).
    /// Both empty for a chord web, which is every shipped `d`, so that preset
    /// draws exactly the segment batch it always did.
    arcs: Vec<ArcInstance>,
    single_arcs: Vec<ArcInstance>,
    /// The fit's three scratch buffers: the sampled walk, the chain it fits,
    /// and each piece's place along the walk. Fields rather than locals because
    /// the fit runs every frame and must not allocate (ADR-0007's parametric
    /// build model gives it no load moment to run at).
    points: Vec<[f32; 2]>,
    pieces: Vec<Piece>,
    walk: Vec<f32>,
    /// The active tier's segment ceiling
    /// ([`TierConfig::max_segments`](crate::render::TierConfig::max_segments)),
    /// resolved once at construction (Plan 0044). A field rather than a constant
    /// so the tier can raise it; the buffers above are preallocated to it, which
    /// is what keeps the per-frame replication allocation-free.
    max_segments: usize,
    /// Set when this frame's mirror replication overflowed the segment cap
    /// (ADR-0007: never a silent cut); `None` when it fit.
    mirror_overflow: Option<CapOverflow>,
    /// Which curve family to sample, chosen at preset load via `configure`.
    family: CurveFamily,
    /// This frame's elapsed real time, stored by [`advance`](Scene::advance) and
    /// consumed by [`update`](Scene::update), which steps the rotation against
    /// this frame's bound `spin`.
    dt: f32,
    /// The integrated rotation ([`Phase`]). **This scene does not read the
    /// shared clock at all**, and has no `set_time`: the figure's rotation was
    /// the clock's only reader here, and a rate has to be integrated rather than
    /// multiplied against elapsed time (ADR-0135).
    spin_phase: Phase,
    /// The preset's baked colour LUT (ADR-0021), sampled on the CPU per chord.
    /// Defaults to the engine cosine, which is the ramp this scene coloured
    /// through before the palette reached it.
    palette: Palette,
    n: f32,
    d: f32,
    phase: f32,
    radial_offset: f32,
    pen: f32,
    sym: f32,
    sharpness: f32,
    lobe: f32,
    decay: f32,
    samples: f32,
    thickness: f32,
    /// The shared palette knobs (ADR-0021).
    colour: common::PaletteParams,
    /// The shared view transform (ADR-0018).
    pan: common::PanParams,
    hue_spread: f32,
    spin: f32,
    scale: f32,
    glow: f32,
    softness: f32,
    /// Whether this figure draws through the **opacity-preserving** seam
    /// rather than the additive one, from `stroke_blend` (ADR-0138).
    ///
    /// At or above [`OPAQUE_BLEND`](super::OPAQUE_BLEND) the whole batch
    /// composites over: a stroke laid on another replaces the interior of what
    /// it covers instead of summing with it, so a quantized palette keeps its
    /// plateaus. Below it the batch is additive light. `0` is the default, so a
    /// preset that does not bind this draws exactly what it drew.
    stroke_blend: f32,
    draw_progress: f32,
    zoom: f32,
    mirror_order: f32,
    mirror_reflect: f32,
    tube: f32,
    m: f32,
    phase_z: f32,

    /// The space families' own renderer (ADR-0258): the `seg3d` pipeline and
    /// an instance buffer of the tier's
    /// [`seg3d_segments`](crate::render::TierConfig::seg3d_segments), built
    /// with the scene so a frame that switches to a space family allocates
    /// nothing. The shared 2D renderer above has no `seg3d` pipeline.
    lines3d: LineRenderer,
    /// The tier's `seg3d_segments`: the most chords a space walk draws.
    seg3d_cap: usize,
    /// The tier's cap on the circle of confusion, in pixels.
    max_coc: f32,
    /// The render target's size in pixels, handed in every frame.
    target: (u32, u32),
    /// The shared camera block, live on the space families only.
    camera: CameraParams,
    /// `hue_axis`: the space families' palette axis, path `0` to depth `1`.
    hue_axis: f32,
    /// This frame's space walk in world units, preallocated to
    /// `seg3d_cap + 1` (a walk has one more point than chords).
    points3d: Vec<[f32; 3]>,
    /// Whether [`points3d`](Self::points3d) closes on itself.
    closed3d: bool,
    /// The bounding radius of the whole space figure, which `focus` is
    /// normalized across.
    extent3d: f32,
    /// The `samples` this frame's space walk was taken at, after the cap:
    /// the colour ramp's divisor.
    samples3d: usize,
    /// Reused 3D instance buffer, preallocated to `seg3d_cap`.
    instances3d: Vec<Segment3dInstance>,
}

impl ParametricCurveScene {
    /// Build the scene over the shared line renderer, preallocating its segment
    /// buffer to the cap, and the space families' own `seg3d` renderer with
    /// `seg3d_cap` instances and blur held to `max_coc` pixels — the tier's
    /// caps.
    pub fn new(
        renderer: Rc<RefCell<LineRenderer>>,
        max_segments: usize,
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        seg3d_cap: usize,
        max_coc: f32,
    ) -> Self {
        Self {
            lines3d: LineRenderer::new_3d(device, surface_format, seg3d_cap, "parametric-3d"),
            seg3d_cap,
            max_coc,
            target: (1, 1),
            camera: CameraParams::default(),
            hue_axis: DEFAULT_HUE_AXIS,
            points3d: Vec::with_capacity(seg3d_cap + 1),
            closed3d: false,
            extent3d: 1.0,
            samples3d: 0,
            instances3d: Vec::with_capacity(seg3d_cap),
            tube: DEFAULT_TUBE,
            m: DEFAULT_M,
            phase_z: DEFAULT_PHASE_Z,
            renderer,
            segments: Vec::with_capacity(max_segments),
            single_buf: Vec::with_capacity(max_segments),
            // The four fit buffers reserve nothing here. Every preset in the
            // shipped library is a chord web, `maurer_rose_pieces` declines the
            // fit before it fills any of them, and at Rich's `max_segments`
            // preallocating all four costs 96 B x 60,000 = 5,760,000 B that is
            // never written. They are reserved on the first frame that actually
            // takes the fitted path — see `reserve_fit_buffers`.
            arcs: Vec::new(),
            single_arcs: Vec::new(),
            pieces: Vec::new(),
            walk: Vec::new(),
            // `points` is the exception and stays preallocated: the walk is
            // written into it on **every** frame, fitted or not.
            //
            // `max_segments + 1`, not `max_segments`. `maurer_rose_pieces`
            // pushes `drawn + 1` points for `drawn` chords — the walk has one
            // more point than it has segments — and `drawn` reaches
            // `max_segments` when a preset binds `samples` at the cap. One short
            // is a reallocation inside a path whose own doc says it is
            // allocation-free.
            points: Vec::with_capacity(max_segments + 1),
            max_segments,
            mirror_overflow: None,
            family: CurveFamily::MaurerRose,
            dt: FALLBACK_DT,
            spin_phase: Phase::default(),
            // Replaced by the preset's palette on the next switch; the default
            // is the engine cosine, so an unconfigured scene still colours.
            palette: Palette::default_spectrum(),
            n: DEFAULT_N,
            d: DEFAULT_D,
            phase: DEFAULT_PHASE,
            radial_offset: DEFAULT_RADIAL_OFFSET,
            pen: DEFAULT_PEN,
            sym: DEFAULT_SYM,
            sharpness: DEFAULT_SHARPNESS,
            lobe: DEFAULT_LOBE,
            decay: DEFAULT_DECAY,
            samples: DEFAULT_SAMPLES,
            thickness: DEFAULT_THICKNESS,
            colour: common::PaletteParams::new(DEFAULT_HUE, DEFAULT_BRIGHTNESS),
            pan: common::PanParams::default(),
            hue_spread: DEFAULT_HUE_SPREAD,
            spin: DEFAULT_SPIN,
            scale: DEFAULT_SCALE,
            glow: DEFAULT_GLOW,
            softness: super::DEFAULT_SOFTNESS,
            stroke_blend: super::ADDITIVE_BLEND,
            draw_progress: DEFAULT_DRAW_PROGRESS,
            zoom: DEFAULT_ZOOM,
            mirror_order: DEFAULT_MIRROR_ORDER,
            mirror_reflect: DEFAULT_MIRROR_REFLECT,
        }
    }
}

impl ParametricCurveScene {
    /// Give the four fit buffers their steady-state capacity, on the first frame
    /// that actually fits a curve.
    ///
    /// **Why not at load, the way `star.rs` sizes its arc buffers.** A star's
    /// roster is structural: the preset declares its circular motifs, so the
    /// count is known at `configure`. Whether a Maurer walk fits is not declared
    /// — it is read off the walk, per frame, and `d` is an expression that can
    /// cross `curves::SMOOTH_CORNER_SHARE` mid-show.
    /// [`curves::maurer_rose_pieces`] states it: the decision cannot be made at
    /// load, only from the walk in hand.
    ///
    /// So the shape is lazy rather than eager. A chord-web preset — every one in
    /// the shipped library — never reaches here and commits nothing. A preset
    /// that fits pays **one** growth on its first fitted frame and is
    /// allocation-free from the second, which is the property the per-frame path
    /// documents. `reserve_exact`, because these settle at a known ceiling and
    /// have no reason to carry a doubling's slack.
    fn reserve_fit_buffers(&mut self) {
        let cap = self.max_segments;
        if self.pieces.capacity() < cap {
            let extra = cap.saturating_sub(self.pieces.len());
            self.pieces.reserve_exact(extra);
        }
        if self.walk.capacity() < cap {
            let extra = cap.saturating_sub(self.walk.len());
            self.walk.reserve_exact(extra);
        }
        if self.single_arcs.capacity() < cap {
            let extra = cap.saturating_sub(self.single_arcs.len());
            self.single_arcs.reserve_exact(extra);
        }
        if self.arcs.capacity() < cap {
            let extra = cap.saturating_sub(self.arcs.len());
            self.arcs.reserve_exact(extra);
        }
    }

    /// Split the fitted chain into the two instance buffers the renderer draws,
    /// colouring each piece by **where it sits along the walk**.
    ///
    /// The walk position is what the fit reports, not the piece's index: a
    /// piece spans as many samples as the budget allowed, so the `k`th piece is
    /// not the `k`th chord and an index would run the palette at the wrong rate
    /// — visibly, wherever the fit's pieces are uneven, which is everywhere a
    /// rose's curvature changes. `samples` stays the divisor for the reason
    /// [`color_along_path`] gives: a chord's place on the curve belongs to the
    /// curve, so a `draw_progress` reveal draws the gradient on rather than
    /// re-tinting it.
    fn split_pieces(
        &mut self,
        samples: usize,
        ramp: ColorRamp,
        color: [f32; 3],
        width: f32,
        closed: bool,
    ) {
        self.single_buf.clear();
        self.single_arcs.clear();
        let span = samples.saturating_sub(1).max(1) as f32;
        for (k, piece) in self.pieces.iter().enumerate() {
            let color = self
                .walk
                .get(k)
                .map_or(color, |at| ramp.at(&self.palette, at / span));
            match *piece {
                Piece::Arc {
                    centre,
                    radius,
                    start,
                    sweep,
                } => self.single_arcs.push(ArcInstance {
                    centre,
                    radius,
                    angle_start: start,
                    angle_sweep: sweep,
                    color,
                    width,
                }),
                Piece::Line { a, b } => {
                    // A chain is a chain (ADR-0158): every piece but the walk's
                    // two ends continues a neighbour, across a corner as much
                    // as along a curve — the extension is what covers the wedge
                    // between two strokes, and a corner is where there is one.
                    //
                    // An open walk's two outer ends are free; a closed one
                    // wraps, and its first piece continues its last.
                    let (ext_a, ext_b) = Piece::chain_extensions(&self.pieces, k, width, closed);
                    self.single_buf.push(SegmentInstance {
                        a,
                        b,
                        color,
                        width,
                        alpha: 1.0,
                        ext_a,
                        ext_b,
                    });
                }
            }
        }
    }

    /// The colour ramp this frame's palette knobs describe.
    fn ramp(&self) -> ColorRamp {
        ColorRamp {
            hue: self.colour.hue,
            hue_spread: self.hue_spread,
            palette_mix: self.colour.mix,
            palette_steps: self.colour.steps,
            saturation: self.colour.saturation,
            brightness: self.colour.brightness,
        }
    }

    /// The walk's parameters at `samples` points, turned by `rotation`, with
    /// the sampler's flat `color` and stroke `width`.
    fn curve_params(
        &self,
        samples: usize,
        rotation: f32,
        color: [f32; 3],
        width: f32,
    ) -> curves::CurveParams {
        curves::CurveParams {
            n: self.n,
            d: self.d,
            phase: self.phase,
            radial_offset: self.radial_offset,
            samples,
            scale: self.scale,
            rotation,
            draw_progress: self.draw_progress,
            color,
            width,
            levers: curves::Levers {
                pen: self.pen,
                sym: self.sym,
                sharpness: self.sharpness,
                lobe: self.lobe,
                decay: self.decay,
                tube: self.tube,
                m: self.m,
                phase_z: self.phase_z,
            },
        }
    }

    /// A space family's frame (ADR-0258): the walk in 3D, at `samples` held to
    /// the `seg3d` cap. No rotation, no fit and no mirror reach it, and the
    /// flat buffers are emptied so nothing 2D is drawn beside it.
    ///
    /// **The cap is announced, not silent** (ADR-0045): unlike the flat path's
    /// backstop it is a tier value a bound `samples` can reach, so a clamp
    /// is reported through [`OverflowContext::Samples`] for the frame it bit.
    fn update_space(&mut self, arm: curves::FamilyArm3d) {
        let (samples, overflow) = space_samples(self.samples, self.seg3d_cap);
        let params = self.curve_params(samples, 0.0, [0.0; 3], 0.0);
        self.closed3d = (arm.sample)(&params, &mut self.points3d);
        self.extent3d = (arm.extent)(&params);
        self.samples3d = samples;
        self.segments.clear();
        self.arcs.clear();
        self.mirror_overflow = overflow;
    }

    /// Draw the space walk through the shared camera: each chord clipped
    /// against the near plane, culled when wholly off one edge of the frame,
    /// coloured by its place along the walk (ADR-0059), or toward its depth by
    /// `hue_axis` ([`space_coordinate`]), and stroked `thickness` pixels wide at
    /// the focal plane.
    fn render_space(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
    ) {
        // The aspect is the render target's, handed in here (ADR-0037).
        let frame = self.camera.frame(
            aspect,
            self.zoom,
            [self.pan.x, self.pan.y],
            self.target,
            self.extent3d,
            self.max_coc,
        );
        if self.mirror_overflow.is_none() {
            self.mirror_overflow = frame.blur;
        }
        let ramp = self.ramp();
        let width = if self.thickness.is_finite() {
            self.thickness.max(0.0)
        } else {
            DEFAULT_THICKNESS
        };
        // The full walk's chord count is the divisor, as on the flat path
        // (`color_along_path`), so a reveal draws the gradient on.
        let span = self.samples3d.saturating_sub(1).max(1) as f32;

        let mut instances = std::mem::take(&mut self.instances3d);
        instances.clear();
        let palette = &self.palette;
        space_chords(
            &frame,
            &self.points3d,
            self.closed3d,
            span,
            self.hue_axis,
            |chord| {
                instances.push(Segment3dInstance {
                    a: chord.a,
                    b: chord.b,
                    color: ramp.at(palette, chord.u),
                    width,
                    alpha: 1.0,
                    prev: chord.prev,
                    next: chord.next,
                    skirt: 0.0,
                });
            },
        );
        self.lines3d.draw_3d(
            queue,
            encoder,
            view,
            &frame,
            self.glow,
            self.softness,
            &instances,
        );
        self.instances3d = instances;
    }
}

/// One chord of a space walk as [`space_chords`] hands it to the draw: the
/// joined, near-clipped endpoints and the palette coordinate it is coloured
/// at, plus, for a test, its index `k` on the walk.
#[derive(Clone, Copy, Debug)]
pub(crate) struct SpaceChord {
    #[cfg(test)]
    pub(crate) k: usize,
    pub(crate) prev: [f32; 3],
    pub(crate) a: [f32; 3],
    pub(crate) b: [f32; 3],
    pub(crate) next: [f32; 3],
    pub(crate) u: f32,
}

/// Every drawn chord of the space walk `points` through `frame`, in walk
/// order: each chord joined to its neighbours and clipped against the near
/// plane ([`joined_chord`]), culled when wholly off one edge of the frame, and
/// given its palette coordinate -- its place `k / span` along the walk, moved
/// toward the depth of its **clipped** midpoint by `hue_axis`
/// ([`space_coordinate`]). `span` is the full walk's chord count, so a reveal
/// draws the gradient on rather than re-tinting it.
pub(crate) fn space_chords(
    frame: &camera::CameraFrame,
    points: &[[f32; 3]],
    closed: bool,
    span: f32,
    hue_axis: f32,
    mut emit: impl FnMut(SpaceChord),
) {
    let n = points.len();
    let chords = if closed { n } else { n.saturating_sub(1) };
    for k in 0..chords {
        let (Some(&pa), Some(&pb)) = (points.get(k), points.get((k + 1) % n)) else {
            continue;
        };
        // The walk is one polyline (ADR-0263): every chord joins the one
        // before and after it, and a closed walk wraps, so only an open
        // walk's two outer ends are free.
        let before = if k > 0 {
            points.get(k - 1).copied()
        } else if closed {
            points.last().copied()
        } else {
            None
        };
        let after = if k + 2 < n || closed {
            points.get((k + 2) % n).copied()
        } else {
            None
        };
        let Some([prev, a, b, next]) = joined_chord(&frame.view, before, pa, pb, after) else {
            continue;
        };
        if frame.view.outside(a, b, frame.margin) {
            continue;
        }
        let along = k as f32 / span;
        let u = if hue_axis > 0.0 {
            let mid = [
                0.5 * (a[0] + b[0]),
                0.5 * (a[1] + b[1]),
                0.5 * (a[2] + b[2]),
            ];
            space_coordinate(along, frame.volume_depth(frame.view.depth(mid)), hue_axis)
        } else {
            along
        };
        emit(SpaceChord {
            #[cfg(test)]
            k,
            prev,
            a,
            b,
            next,
            u,
        });
    }
}

/// A space chord's palette coordinate under `hue_axis` (ADR-0263): `along`, its
/// place on the walk (ADR-0059), moved toward `depth01`, its place across the
/// volume's depth, by `hue_axis` clamped to `[0, 1]`. At `1` the coordinate is
/// the depth alone, so two chords at one depth share a colour wherever they
/// sit on the walk. A non-finite `hue_axis` is `0`.
pub(crate) fn space_coordinate(along: f32, depth01: f32, hue_axis: f32) -> f32 {
    let h = if hue_axis.is_finite() {
        hue_axis.clamp(0.0, 1.0)
    } else {
        0.0
    };
    if h >= 1.0 {
        return depth01;
    }
    along + (depth01 - along) * h
}

/// A bound `samples` held to a space walk's `cap`, and the overflow to
/// announce when the cap bit. A negative or `NaN` value walks nothing.
pub(crate) fn space_samples(samples: f32, cap: usize) -> (usize, Option<CapOverflow>) {
    let asked = samples.max(0.0) as usize;
    if asked <= cap {
        return (asked, None);
    }
    (
        cap,
        Some(CapOverflow {
            dropped: asked - cap,
            context: OverflowContext::Samples(u32::try_from(asked).unwrap_or(u32::MAX)),
            cap,
        }),
    )
}

/// Colour each chord by **how far along the traced path it sits** (ADR-0059's
/// axis for this generator): chord `i` of a `samples`-point walk is at
/// `i / (samples - 1)`, so the ramp runs from the walk's first point to its last.
///
/// `samples` is the **full** curve's chord count, not `segs.len()`. Those differ
/// whenever `draw_progress` reveals a prefix, and the full count is the right
/// divisor: a chord's place on the curve belongs to the curve, so a per-beat
/// reveal draws the gradient on rather than re-tinting every chord it already
/// drew. A degenerate `samples` (0 or 1) leaves the whole figure at `u = 0`,
/// which is the flat `hue` — never a divide by zero.
pub(crate) fn color_along_path(
    segs: &mut [SegmentInstance],
    palette: &Palette,
    ramp: ColorRamp,
    samples: usize,
) {
    let span = samples.saturating_sub(1).max(1) as f32;
    for (i, seg) in segs.iter_mut().enumerate() {
        seg.color = ramp.at(palette, i as f32 / span);
    }
}

/// Parameter vocabulary — see [`fragment_field::PARAMS`](crate::render::scenes::fragment_field::PARAMS).
/// **Keep in sync with `set_param` below.**
pub const PARAMS: &[ParamSpec] = &[
    ParamSpec {
        name: "n",
        default: 6.0,
        range: Some([1.0, 24.0]),
        doc: "The figure's first number, read as a real value per family: the rose's petal \
               number, the two Lissajous figures' and the harmonograph's x frequency, the \
               hypotrochoid's signed radius ratio, the knot's whole turns round its axis.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: true,
    },
    ParamSpec {
        name: "d",
        default: 71.0,
        range: Some([1.0, 360.0]),
        doc: "The figure's second number, per family: the rose's sampling step in degrees, the \
               two Lissajous figures' and the harmonograph's y frequency, the hypotrochoid's \
               cusp count, the superformula's lobe skew, the knot's whole turns through its hole.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: true,
    },
    ParamSpec {
        name: "phase",
        default: 0.0,
        range: Some([0.0, 1.0]),
        doc: "Offsets where the figure starts: inside the rose's sine, between the two Lissajous \
               figures' and the harmonograph's x and y axes, and at the hypotrochoid's pen.",
        kind: ParamKind::Modal,
        group: ParamGroup::Motion,
        main: false,
    },
    ParamSpec {
        name: "radial_offset",
        default: 0.0,
        range: Some([-1.0, 1.0]),
        doc: "Pushes every point out from the centre, opening the figure into a ring.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: false,
    },
    ParamSpec {
        name: "pen",
        default: 1.0,
        range: Some([0.0, 2.0]),
        doc: "How far the tracing point sits from the rolling circle's centre, in rolling radii: \
               1 draws cusps, less rounds them off, more throws them into loops.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: false,
    },
    ParamSpec {
        name: "sym",
        default: 5.0,
        range: Some([1.0, 24.0]),
        doc: "How many lobes the figure repeats around its centre, as a whole number.",
        kind: ParamKind::Structural,
        group: ParamGroup::Shape,
        main: false,
    },
    ParamSpec {
        name: "sharpness",
        default: 1.0,
        range: Some([0.1, 20.0]),
        doc: "How pointed the lobes are: low draws a spiky star, high rounds the figure toward a \
               circle.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: false,
    },
    ParamSpec {
        name: "lobe",
        default: 1.0,
        range: Some([0.1, 10.0]),
        doc: "How the lobes swell between their tips: low pinches them thin, high fills them \
               into a polygon.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: false,
    },
    ParamSpec {
        name: "decay",
        default: 0.1,
        range: Some([0.0, 0.5]),
        doc: "How fast the pendulums die away along the trace: 0 closes the figure, more spirals \
               it inward.",
        kind: ParamKind::Modal,
        group: ParamGroup::Light,
        main: false,
    },
    ParamSpec {
        name: "tube",
        default: 0.4,
        range: Some([0.05, 0.9]),
        doc: "How far a knot's strand winds out from the torus's core circle, as a fraction of \
               that circle's radius.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: false,
    },
    ParamSpec {
        name: "m",
        default: 1.0,
        range: Some([0.0, 12.0]),
        doc: "The depth axis's frequency on a 3D Lissajous figure; 0 with phase_z at 0 lays it \
               flat.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: false,
    },
    ParamSpec {
        name: "phase_z",
        default: 0.25,
        range: Some([0.0, 1.0]),
        doc: "Offsets the depth axis of a 3D Lissajous figure against the other two, as a \
               fraction of a turn.",
        kind: ParamKind::Modal,
        group: ParamGroup::Motion,
        main: false,
    },
    ParamSpec {
        name: "samples",
        default: 361.0,
        range: Some([16.0, 2048.0]),
        doc: "How many points the curve is drawn from; fewer reads as a polygon. Truncated, so \
               a rise adds its next point on arrival.",
        kind: ParamKind::Modal,
        group: ParamGroup::Shape,
        main: false,
    },
    crate::render::scenes::lines::thickness(DEFAULT_THICKNESS),
    crate::render::scenes::common::hue(DEFAULT_HUE),
    crate::render::scenes::lines::hue_spread(DEFAULT_HUE_SPREAD),
    crate::render::scenes::common::SATURATION,
    crate::render::scenes::common::PALETTE_MIX,
    crate::render::scenes::common::PALETTE_STEPS,
    crate::render::scenes::common::PALETTE_CONTOUR,
    ParamSpec {
        name: "spin",
        default: 0.1,
        range: Some([-2.0, 2.0]),
        doc: "Turns per second the whole figure rotates by.",
        kind: ParamKind::Modal,
        group: ParamGroup::Motion,
        main: true,
    },
    crate::render::scenes::lines::scale(DEFAULT_SCALE),
    crate::render::scenes::common::brightness(DEFAULT_BRIGHTNESS),
    crate::render::scenes::lines::GLOW,
    crate::render::scenes::lines::SOFTNESS,
    STROKE_BLEND,
    crate::render::scenes::lines::DRAW_PROGRESS,
    crate::render::scenes::common::zoom(DEFAULT_ZOOM),
    crate::render::scenes::common::PAN_X,
    crate::render::scenes::common::PAN_Y,
    MIRROR_ORDER,
    MIRROR_REFLECT,
    YAW,
    PITCH,
    DISTANCE,
    FOV,
    FOCUS,
    APERTURE,
    FOG,
    SOLID,
    HUE_AXIS,
];

// The shared specs whose reading depends on the family, re-declared with a doc
// line of this system's own. The editor schema keys a family row by the whole
// declaration, so one shared with another system would print this system's
// families on that system's hover. Default, range and kind stay the shared
// block's, so only the wording can differ.
const STROKE_BLEND: ParamSpec = ParamSpec {
    doc: "Moves a flat figure's stroke from additive light toward opaque paint, so crossings \
          stop brightening.",
    ..crate::render::scenes::lines::STROKE_BLEND
};
const MIRROR_ORDER: ParamSpec = ParamSpec {
    doc: "Repeats a flat figure this many times around the centre; 1 draws it once.",
    ..crate::render::scenes::lines::MIRROR_ORDER
};
const MIRROR_REFLECT: ParamSpec = ParamSpec {
    doc: "Alternates a flat figure's repeats into mirror images rather than plain rotations.",
    ..crate::render::scenes::lines::MIRROR_REFLECT
};
const YAW: ParamSpec = ParamSpec {
    doc: "Turns the camera around a space curve, in radians; bind it to a slow clock to orbit.",
    ..camera::YAW
};
const PITCH: ParamSpec = ParamSpec {
    doc: "Raises the camera above a space curve, in radians; negative looks up from below.",
    ..camera::PITCH
};
const DISTANCE: ParamSpec = ParamSpec {
    doc: "How far the camera sits from a space curve's centre; nearer exaggerates the \
          perspective.",
    ..camera::DISTANCE
};
const FOV: ParamSpec = ParamSpec {
    doc: "The camera's vertical field of view onto a space curve, in radians; zoom divides it.",
    ..camera::FOV
};
const FOCUS: ParamSpec = ParamSpec {
    doc: "Where the focal plane sits in a space curve's depth: 0 at its nearest point, 1 at its \
          farthest.",
    ..camera::FOCUS
};
const APERTURE: ParamSpec = ParamSpec {
    doc: "The blur of a space curve's far side, in pixels; strokes nearer than the focal plane \
          blur more, up to the tier's cap. 0 keeps every stroke sharp, and wider costs fill.",
    ..camera::APERTURE
};
const FOG: ParamSpec = ParamSpec {
    doc: "Fades a space curve toward black with depth: at 1 its farthest point is black and its \
          nearest keeps its light. 0 is off.",
    ..camera::FOG
};
const SOLID: ParamSpec = ParamSpec {
    doc: "1 paints a space curve's near strands over its far ones, so it reads as an object and \
          crossings stop brightening; 0 is the additive glow. Solid sorts every chord by depth \
          each frame.",
    ..camera::SOLID
};

/// `hue_axis`: which axis a space curve's palette runs along (ADR-0263) — `0`
/// the path (ADR-0059), `1` the depth across the volume, and a mix between.
const HUE_AXIS: ParamSpec = ParamSpec {
    name: "hue_axis",
    default: 0.0,
    range: Some([0.0, 1.0]),
    doc: "Moves a space curve's colour from running along its path (0) to running with depth \
          (1), nearest first; between mixes the two.",
    kind: ParamKind::Modal,
    group: ParamGroup::Colour,
    main: false,
};
const DEFAULT_HUE_AXIS: f32 = default_of(PARAMS, "hue_axis");

/// One row of [`FAMILY_PARAMS`], its ranges in [`CurveFamily::ALL`]'s order:
/// the rose, the Lissajous, the hypotrochoid, the superformula, the
/// harmonograph, the torus knot, the 3D Lissajous. `None` is a family that
/// does not read the parameter.
macro_rules! per_family {
    ($name:expr; $rose:expr, $lissajous:expr, $hypotrochoid:expr, $superformula:expr, $harmonograph:expr, $torus_knot:expr, $lissajous_3d:expr $(,)?) => {
        FamilyParam {
            name: $name,
            ranges: &[
                FamilyRange {
                    family: "maurer_rose",
                    range: $rose,
                },
                FamilyRange {
                    family: "lissajous",
                    range: $lissajous,
                },
                FamilyRange {
                    family: "hypotrochoid",
                    range: $hypotrochoid,
                },
                FamilyRange {
                    family: "superformula",
                    range: $superformula,
                },
                FamilyRange {
                    family: "harmonograph",
                    range: $harmonograph,
                },
                FamilyRange {
                    family: "torus_knot",
                    range: $torus_knot,
                },
                FamilyRange {
                    family: "lissajous_3d",
                    range: $lissajous_3d,
                },
            ],
        }
    };
}

/// A row read by the space families only (ADR-0258): the camera block, inert
/// on every flat family.
macro_rules! space_only {
    ($spec:expr) => {
        per_family!($spec.name; None, None, None, None, None, $spec.range, $spec.range)
    };
}

/// A row read by the flat families only: what `seg3d` does not draw (ADR-0258)
/// — the mirror, the opaque `stroke_blend` path and the in-plane `spin` —
/// declared with its spec range on every flat family and inert on the space
/// ones.
macro_rules! flat_only {
    ($spec:expr) => {
        per_family!($spec.name; $spec.range, $spec.range, $spec.range, $spec.range, $spec.range, None, None)
    };
}

/// Every parameter whose meaning depends on the curve family, with the range
/// that reads on each (ADR-0180 rule 4) — what the generated reference prints in
/// place of the one range [`PARAMS`] declares, and the list that makes an inert
/// parameter visibly inert.
///
/// A parameter missing from here reads the same on every family. Each entry's
/// [`ParamSpec::range`] is one of its families' ranges, and the families are
/// [`CurveFamily::ALL`] by name and in order — both held by this module's tests.
pub const FAMILY_PARAMS: &[FamilyParam] = &[
    per_family!("n";
        Some([1.0, 24.0]), Some([1.0, 12.0]), Some([-8.0, 8.0]), None, Some([1.0, 12.0]),
        Some([1.0, 12.0]), Some([1.0, 12.0])),
    per_family!("d";
        Some([1.0, 360.0]), Some([1.0, 12.0]), Some([1.0, 24.0]), Some([0.25, 4.0]), Some([1.0, 12.0]),
        Some([1.0, 12.0]), Some([1.0, 12.0])),
    per_family!("phase";
        Some([0.0, 1.0]), Some([0.0, 1.0]), Some([0.0, 1.0]), None, Some([0.0, 1.0]), None,
        Some([0.0, 1.0])),
    per_family!("radial_offset"; Some([-1.0, 1.0]), None, None, None, None, None, None),
    per_family!("pen"; None, None, Some([0.0, 2.0]), None, None, None, None),
    per_family!("sym"; None, None, None, Some([1.0, 24.0]), None, None, None),
    per_family!("sharpness"; None, None, None, Some([0.1, 20.0]), None, None, None),
    per_family!("lobe"; None, None, None, Some([0.1, 10.0]), None, None, None),
    per_family!("decay"; None, None, None, None, Some([0.0, 0.5]), None, None),
    per_family!("tube"; None, None, None, None, None, Some([0.05, 0.9]), None),
    per_family!("m"; None, None, None, None, None, None, Some([0.0, 12.0])),
    per_family!("phase_z"; None, None, None, None, None, None, Some([0.0, 1.0])),
    per_family!("spin";
        Some([-2.0, 2.0]), Some([-2.0, 2.0]), Some([-2.0, 2.0]), Some([-2.0, 2.0]),
        Some([-2.0, 2.0]), None, None),
    flat_only!(STROKE_BLEND),
    flat_only!(MIRROR_ORDER),
    flat_only!(MIRROR_REFLECT),
    space_only!(YAW),
    space_only!(PITCH),
    space_only!(DISTANCE),
    space_only!(FOV),
    space_only!(FOCUS),
    space_only!(APERTURE),
    space_only!(FOG),
    space_only!(SOLID),
    space_only!(HUE_AXIS),
];

impl Scene for ParametricCurveScene {
    fn name(&self) -> &'static str {
        "parametric curve"
    }

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

    fn reset_params(&mut self) {
        self.n = DEFAULT_N;
        self.d = DEFAULT_D;
        self.phase = DEFAULT_PHASE;
        self.radial_offset = DEFAULT_RADIAL_OFFSET;
        self.pen = DEFAULT_PEN;
        self.sym = DEFAULT_SYM;
        self.sharpness = DEFAULT_SHARPNESS;
        self.lobe = DEFAULT_LOBE;
        self.decay = DEFAULT_DECAY;
        self.samples = DEFAULT_SAMPLES;
        self.thickness = DEFAULT_THICKNESS;
        self.colour.reset();
        self.pan.reset();
        self.hue_spread = DEFAULT_HUE_SPREAD;
        self.spin = DEFAULT_SPIN;
        self.scale = DEFAULT_SCALE;
        self.glow = DEFAULT_GLOW;
        self.softness = super::DEFAULT_SOFTNESS;
        self.stroke_blend = super::ADDITIVE_BLEND;
        self.draw_progress = DEFAULT_DRAW_PROGRESS;
        self.zoom = DEFAULT_ZOOM;
        self.mirror_order = DEFAULT_MIRROR_ORDER;
        self.mirror_reflect = DEFAULT_MIRROR_REFLECT;
        self.tube = DEFAULT_TUBE;
        self.m = DEFAULT_M;
        self.phase_z = DEFAULT_PHASE_Z;
        self.hue_axis = DEFAULT_HUE_AXIS;
        self.camera.reset();
    }

    fn set_target_size(&mut self, width: u32, height: u32) {
        self.target = (width, height);
    }

    fn set_param(&mut self, name: &str, value: f32) {
        // The shared param blocks first, this scene's own names after
        // (`scenes::common`, `render::camera`).
        if self.colour.set(name, value) || self.pan.set(name, value) || self.camera.set(name, value)
        {
            return;
        }
        match name {
            "n" => self.n = value,
            "d" => self.d = value,
            "phase" => self.phase = value,
            "radial_offset" => self.radial_offset = value,
            "pen" => self.pen = value,
            "sym" => self.sym = value,
            "sharpness" => self.sharpness = value,
            "lobe" => self.lobe = value,
            "decay" => self.decay = value,
            "tube" => self.tube = value,
            "m" => self.m = value,
            "phase_z" => self.phase_z = value,
            "hue_axis" => self.hue_axis = value,
            "samples" => self.samples = value,
            "thickness" => self.thickness = value,
            "hue_spread" => self.hue_spread = value,
            "spin" => self.spin = value,
            "scale" => self.scale = value,
            "glow" => self.glow = value,
            "softness" => self.softness = value,
            "stroke_blend" => self.stroke_blend = value,
            "draw_progress" => self.draw_progress = value,
            "zoom" => self.zoom = value,
            "mirror_order" => self.mirror_order = value,
            "mirror_reflect" => self.mirror_reflect = value,
            _ => {}
        }
    }

    fn set_palette(&mut self, palette: &Palette) {
        self.palette = palette.clone();
    }

    fn configure(&mut self, cfg: &GeneratorConfig) -> Option<CapOverflow> {
        // A curve preset records its family here (off the hot path). Every other
        // variant belongs to a sibling scene and is not named: matching only
        // this one is what keeps a new variant from editing four scenes that do
        // not use it, and `GeneratorConfig::element_count` is the one place that
        // still has to acknowledge every variant.
        if let GeneratorConfig::Curve { family } = cfg {
            self.family = *family;
        }
        // No load-time truncation: the parametric sampler builds nothing here.
        // Its only cap is a per-frame `samples` clamp in `update` (see there).
        None
    }

    fn mirror_overflow(&self) -> Option<&CapOverflow> {
        self.mirror_overflow.as_ref()
    }

    fn update(&mut self, _frame: &AnalysisFrame) {
        if let Some(arm) = curves::arm3d(self.family) {
            self.update_space(arm);
            return;
        }
        // Per-frame defensive clamp: a huge `samples` can never overrun the
        // preallocated buffer (ADR-0007 cap is explicit). Unlike the generator
        // scenes' load-time build, `samples` is an expression evaluated every
        // frame, so there is no "load" moment to surface a truncation at, and a
        // sane curve preset (samples in the hundreds) never approaches the cap —
        // the clamp is a safety backstop, not a structural cut worth reporting.
        let samples = (self.samples.max(0.0) as usize).min(self.max_segments);
        self.spin_phase.step(self.spin, self.dt);
        let rotation = self.spin_phase.get();
        let ramp = self.ramp();
        // The sampler paints the whole web in the walk's starting colour; the
        // pass below walks it along the path. Keeping the sampler colour-agnostic
        // is what leaves the curve maths free of any palette knowledge.
        let color = ramp.at(&self.palette, 0.0);
        let width = super::half_width(self.thickness);

        let params = self.curve_params(samples, rotation, color, width);

        // Sample the single curve, then replicate it under the geometry mirror.
        // At the default identity spec this is a 1:1 copy, so an un-mirrored
        // preset is unchanged.
        //
        // **Two primitives, one walk.** A walk the family's verdict calls a
        // curve — every Lissajous, and a Maurer rose at a small angular step —
        // is fitted to a G1 arc chain and drawn without a tangent break
        // anywhere. A walk it declines — a Maurer chord web — takes the
        // family's polyline instead: the chords **are** that figure, and an arc
        // through two of them would be drawing something else. The family is
        // named only inside `curves`, so a new one never edits this scene.
        let fit = curves::fit_walk(
            self.family,
            params,
            &mut self.points,
            &mut self.pieces,
            &mut self.walk,
        );
        if fit.fitted {
            self.reserve_fit_buffers();
            self.split_pieces(samples, ramp, color, width, fit.closed);
        } else {
            (curves::arm(self.family).polyline)(
                &params,
                &self.points,
                fit.closed,
                &mut self.single_buf,
            );
            self.single_arcs.clear();
            color_along_path(&mut self.single_buf, &self.palette, ramp, samples);
        }
        let mirror = MirrorSpec::from_params(self.mirror_order, self.mirror_reflect);
        if mirror.is_identity() {
            // Identity spec: replication would copy the whole segment set into a
            // second buffer to produce exactly what it was given. Swap instead —
            // O(1), and both buffers were preallocated to `max_segments`, so
            // neither can grow later. `maurer_rose` clears before it fills, so
            // whatever lands back in `single_buf` is overwritten next frame.
            debug_assert!(
                self.single_buf.len() <= self.max_segments,
                "the sampler already clamps to the cap, so identity cannot truncate"
            );
            std::mem::swap(&mut self.single_buf, &mut self.segments);
            std::mem::swap(&mut self.single_arcs, &mut self.arcs);
            self.mirror_overflow = None;
            return;
        }
        let dropped = replicate_mirror(
            &self.single_buf,
            mirror,
            self.max_segments,
            &mut self.segments,
        );
        // The arcs replicate under the same spec and against their own share of
        // the cap: whatever the segments left. One budget over both kinds, the
        // way `star_pattern` charges them (ADR-0098).
        let arc_cap = self.max_segments.saturating_sub(self.segments.len());
        let arc_dropped = replicate_mirror(&self.single_arcs, mirror, arc_cap, &mut self.arcs);
        let dropped = dropped + arc_dropped;
        self.mirror_overflow = (dropped > 0).then_some(CapOverflow {
            dropped,
            context: OverflowContext::Mirror(mirror.order),
            cap: self.max_segments,
        });
    }

    fn render(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
    ) {
        if self.family.is_space() {
            self.render_space(queue, encoder, view, aspect);
            return;
        }
        // Segments carry brightness in their colour; `glow` is the renderer's
        // separate per-segment falloff multiplier (Plan 0038 Phase 1).
        let xform = ViewTransform {
            zoom: self.zoom,
            pan: [self.pan.x, self.pan.y],
            _pad: 0.0,
        };
        let mut renderer = self.renderer.borrow_mut();
        if self.stroke_blend >= super::OPAQUE_BLEND {
            renderer.draw_opaque(
                queue,
                encoder,
                view,
                aspect,
                self.glow,
                self.softness,
                StrokeMetric::World,
                xform,
                &self.segments,
                &self.arcs,
            );
        } else {
            renderer.draw_arcs(
                queue,
                encoder,
                view,
                aspect,
                self.glow,
                self.softness,
                StrokeMetric::World,
                xform,
                &self.segments,
                &self.arcs,
            );
        }
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::indexing_slicing)]

    use super::*;

    const SAMPLES: usize = 240;

    /// The two allocation claims behind this scene's buffer sizing, asserted on
    /// the sampler rather than on the struct — `Vec::new().capacity() == 0` is a
    /// tautology, and what actually matters is what the walk writes.
    ///
    /// **One: a chord web fills none of the fit buffers.** `pieces` and `walk`
    /// are written only when `maurer_rose_pieces` fits the walk to an arc chain,
    /// and every `d` in the shipped library webs. Preallocating them — and the
    /// two arc buffers they feed — to `max_segments` committed Rust heap that is
    /// never written: 96 B x `max_segments`, which at Rich's 60,000 is
    /// 5,760,000 B on top of the buffers that are used.
    ///
    /// **Two: `points` needs `drawn + 1`.** A polyline has one more point than it
    /// has chords, and `drawn` reaches `max_segments` when a preset binds
    /// `samples` at the per-frame clamp. At a capacity of exactly `max_segments`
    /// the last push reallocates, inside a path whose own doc block calls itself
    /// allocation-free.
    #[test]
    fn the_walk_writes_one_more_point_than_it_has_chords_and_a_web_fits_nothing() {
        let web = curves::CurveParams {
            n: 6.0,
            // A shipped-shape chord web: `maurer_rose_pieces` declines this.
            d: 71.0,
            phase: 0.0,
            radial_offset: 0.0,
            samples: SAMPLES,
            scale: 0.9,
            rotation: 0.0,
            draw_progress: 1.0,
            color: [1.0, 1.0, 1.0],
            width: 0.01,
            levers: curves::Levers::default(),
        };

        let mut points = Vec::with_capacity(SAMPLES + 1);
        let mut pieces = Vec::new();
        let mut walk = Vec::new();

        let fitted = curves::maurer_rose_pieces(web, &mut points, &mut pieces, &mut walk);

        assert!(!fitted, "d = 71 is a chord web and declines the fit");
        assert!(
            pieces.is_empty() && walk.is_empty(),
            "a declined fit writes neither buffer, so reserving for them commits \
             heap nothing ever touches"
        );
        assert_eq!(
            pieces.capacity(),
            0,
            "and it does not even grow them: reserving nothing costs nothing"
        );
        assert_eq!(walk.capacity(), 0);

        // The walk itself is always written, fit or no fit, and it is one longer
        // than the chord count.
        assert_eq!(
            points.len(),
            SAMPLES + 1,
            "the walk has one more point than it has chords"
        );
        assert_eq!(
            points.capacity(),
            SAMPLES + 1,
            "so a capacity of `samples` exactly would have reallocated on the \
             final push"
        );
    }

    /// **A fitted chain's `Line` pieces reach their corners, and its two outer
    /// ends stay free** (ADR-0158) — this scene's own joint rule, on
    /// `curve_ionwake`'s rose, which is the figure the fitted path exists for.
    ///
    /// # Why the tangent and not a third point
    ///
    /// A `Line` piece's neighbour in a fitted chain is usually an **arc**, which
    /// has no third vertex to take a direction from — its direction at the joint
    /// is its tangent there. So the rule is stated on tangents, and this asserts
    /// it against `acos` of the same two tangents, which is the other route to
    /// the interior angle.
    ///
    /// # The G1 half is the load-bearing one
    ///
    /// Wherever the fit kept the chain tangent-continuous the two tangents are
    /// equal and the miter is exactly the flat half-width — so a fitted rose
    /// strokes its smooth runs at exactly the length it always did, and only the
    /// breaks the fit made at real corners move. Both halves are asserted:
    /// vacuity here would be a chain with no corner in it at all.
    #[test]
    fn a_fitted_chains_line_pieces_reach_their_corners_and_its_ends_stay_free() {
        use crate::render::scenes::lines::MITER_SLACK;
        use std::f32::consts::PI;

        const W: f32 = 0.01;

        let rose = curves::CurveParams {
            n: 5.0,
            // `curve_ionwake`'s rose: a curve, so `maurer_rose_pieces` takes it.
            d: 2.0,
            phase: 0.0,
            radial_offset: 0.0,
            samples: SAMPLES,
            scale: 0.9,
            rotation: 0.0,
            draw_progress: 1.0,
            color: [1.0, 1.0, 1.0],
            width: W,
            levers: curves::Levers::default(),
        };
        let (mut points, mut pieces, mut at) = (Vec::new(), Vec::new(), Vec::new());
        assert!(
            curves::maurer_rose_pieces(rose, &mut points, &mut pieces, &mut at),
            "a d = 2 rose must be fitted, or this fixture tests nothing"
        );

        // The two outer ends of an open chain are free.
        let last = pieces.len() - 1;
        assert_eq!(
            Piece::chain_extensions(&pieces, 0, W, false).0,
            0.0,
            "the walk's first end has no neighbour to join"
        );
        assert_eq!(
            Piece::chain_extensions(&pieces, last, W, false).1,
            0.0,
            "nor its last"
        );

        let mut straight = 0usize;
        let mut cornered = 0usize;
        for k in 0..pieces.len() {
            let (ext_a, ext_b) = Piece::chain_extensions(&pieces, k, W, false);
            for (side, got, incoming, outgoing) in [
                (
                    "a",
                    ext_a,
                    k.checked_sub(1).map(|j| pieces[j].end_tangent()),
                    Some(pieces[k].start_tangent()),
                ),
                (
                    "b",
                    ext_b,
                    Some(pieces[k].end_tangent()),
                    pieces.get(k + 1).map(|p| p.start_tangent()),
                ),
            ] {
                let (Some(d1), Some(d2)) = (incoming, outgoing) else {
                    continue; // a free end, asserted above
                };
                // The interior angle by `acos` of the turn, where the producer
                // takes a square root of the half-angle identity.
                let turn = (d1[0] * d2[0] + d1[1] * d2[1]).clamp(-1.0, 1.0).acos();
                let want = W / ((PI - turn) * 0.5).sin();
                assert!(
                    (got - want).abs() <= want * MITER_SLACK,
                    "piece {k}'s `{side}` joint carries {got} against the {want} \
                     its {}-degree turn asks for",
                    turn.to_degrees()
                );
                if turn < 1e-4 {
                    straight += 1;
                    assert!(
                        (got - W).abs() <= W * MITER_SLACK,
                        "piece {k}'s `{side}` joint is G1, so its miter must be \
                         exactly the flat half-width {W}, got {got}"
                    );
                } else {
                    cornered += 1;
                }
            }
        }
        assert!(
            straight > 0 && cornered > 0,
            "this chain holds {straight} tangent-continuous joints and \
             {cornered} corners — it must hold some of each, or one of the two \
             halves above was never exercised"
        );
    }

    /// [`FAMILY_PARAMS`] is a statement about the engine, so it is held to the
    /// engine: each row names a declared parameter once, lists **every** curve
    /// family by the name a preset uses and in roster order, and carries a
    /// spec range that is one of its families' — so the one pair the exported
    /// schema keeps is a range some family genuinely reads.
    ///
    /// And each lever that only one family reads is inert everywhere else,
    /// which is what the rows for `pen`, `sym`, `sharpness`, `lobe`, `decay`,
    /// `tube`, `m` and `phase_z` claim: asserted on the sampler, by moving the
    /// lever on every family that the table calls inert and finding the walk
    /// unmoved.
    #[test]
    fn the_family_table_is_the_roster_and_its_inert_cells_are_inert() {
        let families: Vec<&str> = CurveFamily::ALL.iter().map(|f| f.as_str()).collect();
        assert_eq!(
            families,
            [
                "maurer_rose",
                "lissajous",
                "hypotrochoid",
                "superformula",
                "harmonograph",
                "torus_knot",
                "lissajous_3d"
            ],
            "the roster the macro's seven columns are written against"
        );
        let mut seen = Vec::new();
        for row in FAMILY_PARAMS {
            assert!(!seen.contains(&row.name), "`{}` has two rows", row.name);
            seen.push(row.name);
            let spec = PARAMS
                .iter()
                .find(|spec| spec.name == row.name)
                .unwrap_or_else(|| panic!("`{}` is not a declared parameter", row.name));
            let listed: Vec<&str> = row.ranges.iter().map(|r| r.family).collect();
            assert_eq!(listed, families, "`{}` must list every family", row.name);
            assert!(
                row.ranges.iter().any(|r| r.range == spec.range),
                "`{}`'s spec range {:?} is no family's range",
                row.name,
                spec.range
            );
        }

        let levers = curves::Levers::default();
        let moved = |name: &str| -> curves::Levers {
            let mut l = levers;
            match name {
                "pen" => l.pen = 1.7,
                "sym" => l.sym = 9.0,
                "sharpness" => l.sharpness = 7.0,
                "lobe" => l.lobe = 4.0,
                "decay" => l.decay = 0.3,
                "tube" => l.tube = 0.7,
                "m" => l.m = 3.0,
                "phase_z" => l.phase_z = 0.6,
                other => panic!("no lever called `{other}`"),
            }
            l
        };
        // A flat walk lifted to `z = 0`, or a space family's own 3D walk.
        let walk = |family: CurveFamily, levers: curves::Levers| -> Vec<[f32; 3]> {
            let p = curves::CurveParams {
                n: 3.0,
                d: 2.0,
                phase: 0.0,
                radial_offset: 0.0,
                samples: 200,
                scale: 0.9,
                rotation: 0.0,
                draw_progress: 1.0,
                color: [1.0; 3],
                width: 0.01,
                levers,
            };
            if let Some(arm) = curves::arm3d(family) {
                let mut points = Vec::new();
                (arm.sample)(&p, &mut points);
                return points;
            }
            let (mut points, mut pieces, mut at) = (Vec::new(), Vec::new(), Vec::new());
            curves::fit_walk(family, p, &mut points, &mut pieces, &mut at);
            points.iter().map(|&[x, y]| [x, y, 0.0]).collect()
        };
        let mut inert_checked = 0;
        const LEVERS: [&str; 8] = [
            "pen",
            "sym",
            "sharpness",
            "lobe",
            "decay",
            "tube",
            "m",
            "phase_z",
        ];
        for name in LEVERS {
            let row = FAMILY_PARAMS
                .iter()
                .find(|row| row.name == name)
                .unwrap_or_else(|| panic!("`{name}` has no family row"));
            for (cell, family) in row.ranges.iter().zip(CurveFamily::ALL) {
                let (before, after) = (walk(family, levers), walk(family, moved(name)));
                if cell.range.is_none() {
                    assert_eq!(
                        before, after,
                        "`{name}` moved the {} it is inert on",
                        cell.family
                    );
                    inert_checked += 1;
                } else {
                    assert_ne!(
                        before, after,
                        "`{name}` did not move the {} it reads on",
                        cell.family
                    );
                }
            }
        }
        assert_eq!(
            inert_checked,
            LEVERS.len() * (CurveFamily::ALL.len() - 1),
            "each lever is inert on every family but its own"
        );
    }

    /// `spin` integrates rather than multiplying the clock (ADR-0135), and at a
    /// constant rate the two agree — which is what makes "no golden moves" a
    /// property of the arithmetic rather than of the tolerance. Every fixture
    /// binding this scene's `spin` binds a constant.
    #[test]
    fn a_constant_spin_integrates_to_the_multiply_it_replaced() {
        let dt = FALLBACK_DT;
        for rate in [DEFAULT_SPIN, 0.0, 0.4, -0.25] {
            let mut phase = Phase::default();
            let mut time = 0.0f32;
            for _ in 0..600 {
                phase.step(rate, dt);
                time += dt;
            }
            assert!(
                (phase.get() - rate * time).abs() < 1e-3,
                "rate {rate}: integrated {} against the multiply's {}",
                phase.get(),
                rate * time
            );
        }
    }

    /// ...and the property the multiply failed: a `spin` that MOVES advances the
    /// rotation by `spin * dt` whatever the elapsed time. Under `spin * time` the
    /// same change at t = 100 s swings the figure through fifty seconds of
    /// rotation in one frame.
    #[test]
    fn a_spin_change_bends_the_rotation_instead_of_teleporting_it() {
        let dt = FALLBACK_DT;
        let mut phase = Phase::default();
        let mut time = 0.0f32;
        for _ in 0..6_000 {
            phase.step(DEFAULT_SPIN, dt);
            time += dt;
        }
        assert!(time > 99.0, "the fixture must be far from t = 0: {time}");

        let before = phase.get();
        phase.step(1.5, dt);
        let step = phase.get() - before;
        assert!(
            (step - 1.5 * dt).abs() < 1e-4,
            "the rotation advanced {step}, not {}",
            1.5 * dt
        );
        // What the multiply would have done, on the record rather than described.
        let teleport = (1.5 - DEFAULT_SPIN) * time;
        assert!(
            teleport > 100.0,
            "the multiply's one-frame jump at this elapsed time was {teleport} rad"
        );
    }

    fn ramp(hue_spread: f32) -> ColorRamp {
        ColorRamp {
            hue: DEFAULT_HUE,
            hue_spread,
            palette_mix: common::DEFAULT_PALETTE_MIX,
            palette_steps: crate::render::palette::DEFAULT_PALETTE_STEPS,
            saturation: common::DEFAULT_SATURATION,
            brightness: DEFAULT_BRIGHTNESS,
        }
    }

    fn curve(samples: usize, draw_progress: f32, hue_spread: f32) -> Vec<SegmentInstance> {
        let mut out = Vec::with_capacity(samples + 1);
        curves::maurer_rose(
            curves::CurveParams {
                n: DEFAULT_N,
                d: DEFAULT_D,
                phase: DEFAULT_PHASE,
                radial_offset: DEFAULT_RADIAL_OFFSET,
                samples,
                scale: DEFAULT_SCALE,
                rotation: 0.0,
                draw_progress,
                color: [0.0; 3],
                width: 0.01,
                levers: curves::Levers::default(),
            },
            &mut out,
        );
        color_along_path(
            &mut out,
            &Palette::default_spectrum(),
            ramp(hue_spread),
            samples,
        );
        out
    }

    /// Plan 0054 Phase 2 done-when 2 (ADR-0059). The claim is not "colours vary"
    /// — it is that the ramp runs **along the direction of travel**, so the
    /// walk's first chord and its last carry different colours and the walk
    /// between them never doubles back on a colour it already used.
    #[test]
    fn the_spread_colours_the_curve_along_its_direction_of_travel() {
        let swept = curve(SAMPLES, 1.0, 0.5);
        assert_eq!(swept.len(), SAMPLES, "one chord per sample");
        assert_ne!(
            swept[0].color,
            swept[SAMPLES - 1].color,
            "the path's start and end must differ — that is the whole claim"
        );

        // Monotone along the walk. `hue_spread = 0.5` stays inside one traverse
        // of the palette, so the ramp is a strictly advancing sample coordinate
        // and no two chords may share a colour.
        for k in 1..swept.len() {
            assert_ne!(
                swept[k].color,
                swept[k - 1].color,
                "chord {k} repeated chord {}'s colour, so the ramp is not \
                 advancing along the path",
                k - 1
            );
        }
    }

    /// The other half of the superset claim: `hue_spread = 0` is one flat colour
    /// across the whole web — exactly what this scene drew before ADR-0059.
    #[test]
    fn zero_spread_is_one_flat_colour_along_the_whole_path() {
        let flat = curve(SAMPLES, 1.0, 0.0);
        for (k, seg) in flat.iter().enumerate() {
            assert_eq!(seg.color, flat[0].color, "chord {k} must carry the one hue");
        }
    }

    /// The divisor is the **full** curve, not the revealed prefix. A per-beat
    /// `draw_progress` therefore draws the gradient on rather than re-tinting the
    /// chords it already drew — which is what a reveal should look like, and the
    /// bug the obvious `segs.len()` divisor would have shipped.
    #[test]
    fn the_reveal_draws_the_gradient_on_rather_than_re_tinting_it() {
        let full = curve(SAMPLES, 1.0, 0.5);
        let half = curve(SAMPLES, 0.5, 0.5);
        assert!(
            !half.is_empty() && half.len() < full.len(),
            "the probe must actually reveal a prefix"
        );
        for (k, seg) in half.iter().enumerate() {
            assert_eq!(
                seg.color, full[k].color,
                "chord {k} changed colour when the reveal shortened"
            );
        }
        // ...and the revealed half really has only travelled part of the ramp.
        assert_ne!(
            half[half.len() - 1].color,
            full[full.len() - 1].color,
            "a half-drawn curve must not already show the ramp's far end"
        );
    }

    /// **At `hue_axis = 1` a knot is coloured by depth alone** (ADR-0263): over
    /// every chord [`space_chords`] hands the draw for a (2, 3) torus knot seen
    /// from an oblique camera, the palette coordinate is the depth of the chord
    /// it actually emits, so two chords at one depth share a coordinate however
    /// far apart they sit on the walk, and two at different depths do not. At
    /// `0` the coordinate is the walk position, bit for bit. A chord the near
    /// plane cuts holds the coordinate to the **clipped** chord's depth, so a
    /// swapped or unclipped depth inside the seam reads differently here.
    #[test]
    fn a_full_hue_axis_colours_a_knot_by_depth_alone() {
        let arm = curves::arm3d(CurveFamily::TorusKnot).unwrap_or_else(|| panic!("a space family"));
        let samples = 480;
        let params = curves::CurveParams {
            n: 2.0,
            d: 3.0,
            phase: 0.0,
            radial_offset: 0.0,
            samples,
            scale: 0.9,
            rotation: 0.0,
            draw_progress: 1.0,
            color: [0.0; 3],
            width: 0.0,
            levers: curves::Levers {
                tube: 0.35,
                ..curves::Levers::default()
            },
        };
        let mut points = Vec::new();
        let closed = (arm.sample)(&params, &mut points);
        assert!(closed && points.len() > 100, "a closed knot walk");
        let span = samples.saturating_sub(1).max(1) as f32;
        let frame_at = |distance: f32| {
            CameraParams {
                yaw: 0.4,
                pitch: 0.7,
                distance,
                ..CameraParams::default()
            }
            .frame(
                16.0 / 9.0,
                1.0,
                [0.0, 0.0],
                (1280, 720),
                (arm.extent)(&params),
                16.0,
            )
        };
        let emitted = |frame: &camera::CameraFrame, hue_axis: f32| {
            let mut out = Vec::new();
            space_chords(frame, &points, closed, span, hue_axis, |c| out.push(c));
            out
        };
        // The depth the draw should colour a chord by: its emitted midpoint's.
        let depth_of = |frame: &camera::CameraFrame, c: &SpaceChord| {
            let mid = [
                0.5 * (c.a[0] + c.b[0]),
                0.5 * (c.a[1] + c.b[1]),
                0.5 * (c.a[2] + c.b[2]),
            ];
            frame.volume_depth(frame.view.depth(mid))
        };

        let frame = frame_at(3.2);
        let by_path = emitted(&frame, 0.0);
        let by_depth = emitted(&frame, 1.0);
        assert_eq!(by_path.len(), points.len(), "every chord is drawn");
        for c in &by_path {
            assert_eq!(
                c.u.to_bits(),
                (c.k as f32 / span).to_bits(),
                "chord {}",
                c.k
            );
        }
        for c in &by_depth {
            assert_eq!(
                c.u.to_bits(),
                depth_of(&frame, c).to_bits(),
                "chord {} is coloured by its own depth",
                c.k
            );
        }
        // Depth runs near to far: the chord nearest the camera takes the lowest
        // coordinate and the farthest the highest, which a swapped depth inverts.
        let nearest = by_depth
            .iter()
            .min_by(|x, y| frame.view.depth(x.a).total_cmp(&frame.view.depth(y.a)))
            .unwrap_or_else(|| panic!("chords"));
        let farthest = by_depth
            .iter()
            .max_by(|x, y| frame.view.depth(x.a).total_cmp(&frame.view.depth(y.a)))
            .unwrap_or_else(|| panic!("chords"));
        assert!(
            nearest.u < 0.2 && farthest.u > 0.8,
            "near reads low and far reads high: {} .. {}",
            nearest.u,
            farthest.u
        );
        for (i, ci) in by_depth.iter().enumerate() {
            for cj in &by_depth[i + 1..] {
                let (di, dj) = (depth_of(&frame, ci), depth_of(&frame, cj));
                assert_eq!(
                    di == dj,
                    ci.u == cj.u,
                    "depths {di} and {dj} took {} and {}",
                    ci.u,
                    cj.u
                );
            }
        }
        // Non-vacuity: the knot spans its depth, and a pair of chords at nearly
        // one depth sits far apart on the walk, where the path axis colours
        // them apart.
        let (lo, hi) = by_depth
            .iter()
            .fold((1.0f32, 0.0f32), |(lo, hi), c| (lo.min(c.u), hi.max(c.u)));
        assert!(
            hi - lo > 0.5,
            "the knot spans the volume's depth: {lo}..{hi}"
        );
        let n = by_depth.len();
        let mut pair = (0, 0, f32::INFINITY);
        for i in 0..n {
            // At least a quarter of the closed walk apart, either way round.
            for j in (i + n / 4)..(i + 3 * n / 4).min(n) {
                let gap = (by_depth[i].u - by_depth[j].u).abs();
                if gap < pair.2 {
                    pair = (i, j, gap);
                }
            }
        }
        let (i, j, gap) = pair;
        assert!(
            gap < 1e-3,
            "two chords a quarter-walk apart share a depth: {gap}"
        );
        assert!(
            (by_path[i].u - by_path[j].u).abs() > 0.2,
            "the path axis colours them apart"
        );

        // A chord the near plane cuts: a two-point walk from the volume's far
        // side straight through the eye along the view axis, so the cut end
        // stays at the centre of the frame instead of being culled off it. The
        // coordinate is the emitted, clipped chord's depth, which the unclipped
        // chord's midpoint would not give.
        let (sy, cy) = 0.4f32.sin_cos();
        let (sp, cp) = 0.7f32.sin_cos();
        let toward_eye = [cp * sy, sp, cp * cy];
        let along_axis = |t: f32| toward_eye.map(|v| v * t);
        let (pa, pb) = (along_axis(-1.0), along_axis(frame.view.distance + 1.0));
        let mut cut = Vec::new();
        space_chords(&frame, &[pa, pb], false, 1.0, 1.0, |c| cut.push(c));
        let [c] = cut.as_slice() else {
            panic!("the axial chord is drawn: {cut:?}");
        };
        assert!(
            c.a == pa && c.b != pb,
            "the near plane cuts the chord's far end"
        );
        assert_eq!(c.u.to_bits(), depth_of(&frame, c).to_bits());
        let unclipped = frame.volume_depth(frame.view.depth([
            0.5 * (pa[0] + pb[0]),
            0.5 * (pa[1] + pb[1]),
            0.5 * (pa[2] + pb[2]),
        ]));
        assert!(
            (c.u - unclipped).abs() > 0.05,
            "the clipped chord reads a different depth from the unclipped one: {} vs {unclipped}",
            c.u
        );
    }

    /// Total over the degenerate sample counts an expression can produce: a
    /// one-point or empty walk has no path to ramp along and must not divide by
    /// zero on the render path.
    #[test]
    fn a_degenerate_sample_count_leaves_the_figure_flat() {
        for samples in [0usize, 1, 2] {
            let out = curve(samples, 1.0, 0.9);
            for seg in &out {
                assert!(
                    seg.color.iter().all(|c| c.is_finite()),
                    "samples = {samples} produced a non-finite colour"
                );
            }
        }
    }
}