rlx_core/render/scenes/lines/

renderer.rs

//! The shared line primitive: a GPU helper that draws thick, glowing lines as
//! instanced camera-facing quads. Each [`SegmentInstance`] (two endpoints, a
//! colour, a half-width) is expanded in the vertex shader into a quad whose
//! width is uniform *on screen* — the swarm scene's instanced-quad pipeline
//! (ADR-0007) with segments in place of points. Additive blend, so overlapping
//! and dense strokes bloom.
//!
//! Native wgpu line primitives are deliberately not used: their width is locked
//! near 1px and varies by backend (ADR-0007). The buffer is fixed-capacity and
//! reused every frame, so a full curve upload never allocates on the hot path.

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

use crate::render::gpu;
use crate::render::metrics::{self, DrawExtent};

/// The sharpest corner a miter is drawn for, as a multiple of the half-width
/// the miter would reach (ADR-0158).
///
/// A corner of interior angle `theta` needs `width / sin(theta / 2)`, which
/// grows without bound as the corner sharpens: a spike that doubles back on
/// itself would reach to infinity and paint a spear across the frame. Past the
/// limit the joint **reverts to the flat half-width** — a bevel, which is what
/// `stroke-miterlimit` selects in SVG and what an unmitred joint always drew.
/// It is a fallback and not a truncation: clamping to `MITER_LIMIT * width`
/// instead leaves the stroke reaching four half-widths past the vertex along its
/// own direction, which reads as a burr rather than as a corner.
///
/// **`4.0` is adopted, not measured.** It is SVG's `stroke-miterlimit` default,
/// and it draws exactly every corner at or above
/// `2 * asin(1 / 4) = 28.96 degrees` — that is the angle at which
/// `1 / sin(theta / 2)` reaches 4, so the limit is a statement about which
/// corners are mitred and which are bevelled, not a tuned number (ADR-0071).
/// `diamond`'s 61.9-degree vertex needs 1.9437 and is well inside it; a Maurer
/// chord web's near-reversals are the population outside it.
pub const MITER_LIMIT: f32 = 4.0;

/// The extension a joined end needs to reach its corner's point: the miter
/// length at `vertex`, where the chain arrives from `prev` and leaves for
/// `next`, clamped to [`MITER_LIMIT`] half-widths (ADR-0158).
///
/// # The expression, and why it carries no trigonometry
///
/// For an interior angle `theta` the miter is `width / sin(theta / 2)`. Writing
/// `d1`, `d2` for the two unit directions, the turn between them is
/// `theta_turn = pi - theta`, so
///
/// ```text
/// sin(theta / 2) = cos(theta_turn / 2) = sqrt((1 + d1 · d2) / 2)
/// ```
///
/// — a dot product and a square root, with no `acos` to lose precision near the
/// straight case and no branch on the turn's sign. A straight joint has
/// `d1 · d2 = 1` and yields exactly `width`, which is the flat half-width, so a
/// collinear chain is byte-identical to one that extends by `width`.
///
/// # Homogeneous of degree 1 in `width`
///
/// Both `width / sin(theta / 2)` and the clamp `MITER_LIMIT * width` scale
/// linearly, so `miter(c * w) == c * miter(w)` and the clamp cannot be engaged
/// at one width and not another. That is what lets the cached producers compute
/// this against `PLACEHOLDER_WIDTH` at `configure` and have
/// `LineInstance::styled` carry it to this frame's width by the ratio. Both are
/// crate-private, so this names them rather than linking them. `theta` survives
/// that too: every transform between a producer and the shader — uniform scale,
/// rotation, reflection, the mirror replication, `normalize_fit` — is a
/// similarity, and a similarity preserves angles.
///
/// # Degenerate input
///
/// A zero-length arm has no direction, and a chain that doubles back exactly
/// (`d1 · d2 = -1`) has no reachable point. Both fall back to `width`, the flat
/// half-width — which is the same value a corner past [`MITER_LIMIT`] takes, so
/// the degenerate case is the limit case rather than a separate rule.
pub fn miter_extension(width: f32, prev: [f32; 2], vertex: [f32; 2], next: [f32; 2]) -> f32 {
    let unit = |from: [f32; 2], to: [f32; 2]| -> Option<[f32; 2]> {
        let (dx, dy) = (to[0] - from[0], to[1] - from[1]);
        let len = dx.hypot(dy);
        (len > 1e-9).then(|| [dx / len, dy / len])
    };
    let (Some(d1), Some(d2)) = (unit(prev, vertex), unit(vertex, next)) else {
        return width;
    };
    miter_extension_between(width, d1, d2)
}

/// [`miter_extension`] for a chain that carries its own tangents rather than a
/// third point — a fitted arc/line chain, where the direction a neighbour
/// arrives or leaves at is a property of the piece and not of any vertex.
///
/// `incoming` and `outgoing` are **unit** directions of travel through the
/// joint. A G1 joint has them equal, so this returns exactly `width` there and a
/// tangent-continuous run is byte-identical to one extended by the flat
/// half-width; only the chain's genuine corners move.
pub fn miter_extension_between(width: f32, incoming: [f32; 2], outgoing: [f32; 2]) -> f32 {
    let half = ((1.0 + incoming[0] * outgoing[0] + incoming[1] * outgoing[1]) * 0.5)
        .max(0.0)
        .sqrt();
    if half <= 1.0 / MITER_LIMIT {
        // Bevel, not a truncated miter — see `MITER_LIMIT`.
        return width;
    }
    width / half
}

/// One line segment: endpoints `a`/`b` in world space (x is divided by aspect
/// in the shader, matching the swarm's convention), an RGB colour, a
/// half-width in world units, and the per-endpoint extension length the join
/// needs.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
pub struct SegmentInstance {
    /// First endpoint (world space).
    pub a: [f32; 2],
    /// Second endpoint (world space).
    pub b: [f32; 2],
    /// RGB colour (pre-brightness; additive blend sums overlaps).
    pub color: [f32; 3],
    /// Half-width in **world units** — the isotropic space, where the stroke is
    /// the same thickness on screen at every orientation (ADR-0160). It is
    /// numerically an NDC-y half-width: world y and NDC y are the same axis, so
    /// the horizontal case is the same number in either space and every other
    /// orientation agrees with it.
    ///
    /// **Unless the draw selected [`StrokeMetric::Clip`]**, where this is an NDC
    /// half-width and the on-screen thickness varies with the segment's
    /// orientation by up to the aspect. That metric is per draw call rather than
    /// per instance, and `warp_mesh` is the one surface on it.
    pub width: f32,
    /// How far the quad extends **backward** past `a`, along the segment's own
    /// direction, in the same world half-width units as [`width`](Self::width).
    /// `0.0` is a free end (ADR-0158).
    ///
    /// The length is the **producer's** to compute: only it knows whether an end
    /// is shared with a neighbour and at what interior angle, which is the same
    /// argument that put connectivity on the producer side. `0.0` renders exactly
    /// the geometry an unflagged end rendered, because `dir * 0.0` is exactly
    /// zero — that is what keeps the isolated producers, `spectrum`'s `Bars` and
    /// `RadialRing`, byte-identical.
    ///
    /// **A length, not a factor.** It is resolved against `width` at
    /// the moment the producer fills the instance. Every producer in this crate
    /// rebuilds its instance buffer per frame, so the two cannot drift; a
    /// producer that ever caches instances across frames while animating
    /// `thickness` would have to recompute this alongside it.
    pub ext_a: f32,
    /// **How much of its own footprint this stroke occupies**, on top of the
    /// across-the-stroke falloff — the fragment's alpha is `falloff * alpha`.
    ///
    /// `1.0` for every producer that draws through the additive seam, and that is
    /// the value to pass unless you know otherwise: ADR-0056's rule is that a
    /// dimmed stroke still covers its own footprint, so brightness belongs in
    /// [`color`](Self::color) and never here. Every line scene in this crate
    /// passes `1.0`, which makes the fragment exactly what it was before this
    /// field existed.
    ///
    /// What it is for is [`LineRenderer::draw_split`]'s second range, where the
    /// stroke is composited **over** rather than added and the blend needs the
    /// producer's real coverage: a MilkDrop waveform at `wave_a = 0.1` must
    /// replace a tenth of what is under it, not all of it (Plan 0100 Phase 4).
    ///
    /// **Its position in this struct is load-bearing.** `vertex_attr_array!`
    /// derives each attribute's byte offset from the order of the *shader
    /// locations*, so a field inserted ahead of this one shifts location 5 onto
    /// the bytes location 4 is reading and every attribute after it by one slot.
    /// The result compiles, renders, and quietly reinterprets one field as
    /// another's mantissa — which is what it did, moving five composite golden
    /// baselines. **A new field goes last**, which is where
    /// [`ext_b`](Self::ext_b) is.
    pub alpha: f32,
    /// How far the quad extends **forward** past `b`. The `b`-end counterpart of
    /// [`ext_a`](Self::ext_a), in the same units and with the same `0.0`-is-free
    /// convention.
    ///
    /// **Declared last**, for the reason [`alpha`](Self::alpha) records: it was
    /// appended when the endpoint stopped carrying a flag and started carrying a
    /// length, and appending is the only placement that re-points nothing.
    pub ext_b: f32,
}

/// One **circular arc**: a centre and radius in world space, a signed angular
/// span in radians, an RGB colour and a half-width in NDC-y units — the same
/// conventions [`SegmentInstance`] uses, so the two kinds place geometry in one
/// coordinate system and stroke it to one profile.
///
/// Expanded in the vertex shader to a single bounding quad and shaded by the
/// **per-pixel distance to the arc** (ADR-0098) rather than by an
/// interpolated across-the-stroke coordinate. So a `circle` is one instance
/// with no vertices at any resolution, where the segment path needs one
/// instance and one additive joint per sample.
///
/// **No extension fields: an arc has no interior joints**, which is the whole
/// point of the primitive. Where two arcs in a chain meet they overlap by a
/// half-width as any two strokes do, and the additive composite
/// sums that overlap exactly as it does for segments — the bead is reduced by
/// there being fewer joints, not by a joint doing anything different.
///
/// **No `alpha` field either.** Every arc producer draws through ADR-0056's
/// additive seam, where the coverage a premultiplied fragment carries is the
/// stroke's own falloff; the OVER range [`LineRenderer::draw_split`] serves is
/// a MilkDrop waveform, which is segments. A future over-blended arc adds the
/// field **last**, for the reason [`SegmentInstance::alpha`] records.
///
/// **Field order is shader-location order**, and that is load-bearing for the
/// same reason it is on [`SegmentInstance`]: `vertex_attr_array!` derives each
/// attribute's byte offset from the order of the locations, so a field inserted
/// anywhere but the end silently re-points every attribute after it.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
pub struct ArcInstance {
    /// Centre of curvature (world space).
    pub centre: [f32; 2],
    /// Radius (world space). The arc's centreline, not either stroke edge.
    pub radius: f32,
    /// Where the span starts, in radians, measured the usual way from `+x`.
    pub angle_start: f32,
    /// How far it sweeps, **signed**. `|sweep|` may exceed `PI`, and a full
    /// circle is one instance at `sweep = TAU`.
    pub angle_sweep: f32,
    /// RGB colour (pre-brightness; additive blend sums overlaps).
    pub color: [f32; 3],
    /// Half-width in world units — the same quantity, in the same space, as
    /// [`SegmentInstance::width`]. Named `width` to match its sibling; it is a
    /// half-width in both.
    ///
    /// There is no [`StrokeMetric`] choice here: no arc producer wants the clip
    /// metric, because `warp_mesh` — the one surface still on it — emits no
    /// [`ArcInstance`] at all (ADR-0160).
    pub width: f32,
}

/// One segment in **3D**, drawn through the shared camera (ADR-0257): two world
/// endpoints, an RGB colour, a width in pixels at the camera's reference depth
/// and an alpha.
///
/// Drawn by the `seg3d` pipeline, which [`LineRenderer::new_3d`] builds and
/// `LineRenderer::draw_3d` selects — a separate pipeline and instance buffer
/// rather than a branch in the 2D one, so every 2D line scene keeps its bytes.
///
/// **Field order is shader-location order**, for the reason
/// [`SegmentInstance::alpha`] records: a field inserted anywhere but the end
/// re-points every attribute after it.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
pub struct Segment3dInstance {
    /// First endpoint, world space, in front of the near plane.
    pub a: [f32; 3],
    /// Second endpoint, world space, in front of the near plane.
    pub b: [f32; 3],
    /// RGB light (pre-glow; additive blend sums overlaps).
    pub color: [f32; 3],
    /// Full stroke width in **pixels of the render target** at the camera's
    /// reference depth; each end is scaled by perspective from there.
    pub width: f32,
    /// How much of the stroke is present: its light and its coverage are both
    /// multiplied by this, so a fading edge fades out of the frame rather than
    /// into a dark line.
    pub alpha: f32,
    /// The polyline's point before [`a`](Self::a), or `a` itself where `a` is
    /// a free end. A joined end is mitred in screen space against the
    /// direction it arrives from, so two neighbours meet on one line instead
    /// of overlapping (ADR-0263); a free end draws flat, as an unjoined stroke
    /// always did.
    ///
    /// **Bit-equal to the neighbour's own `a`**, or the two quads compute the
    /// shared corner from different numbers and leave a seam:
    /// `joined_chord` is what makes it so, near-plane clip included.
    pub prev: [f32; 3],
    /// The polyline's point after [`b`](Self::b), or `b` itself where `b` is a
    /// free end. The `b`-end counterpart of [`prev`](Self::prev).
    pub next: [f32; 3],
    /// `1.0` on a **skirt**: not a stroke but a filled band from `a -> b` down
    /// to the ground plane the draw names
    /// (`LineRenderer::draw_3d_terrain`), at full coverage times
    /// [`alpha`](Self::alpha) in [`color`](Self::color). A solid waterfall
    /// row lays one under each of its segments, so a near row hides what lies
    /// behind it (ADR-0263). `0.0` on every stroke.
    pub skirt: f32,
}

/// The chord `pa -> pb` of a polyline, clipped against `view`'s near plane, as
/// `[prev, a, b, next]` for a [`Segment3dInstance`] — or `None` when the whole
/// chord lies behind the plane.
///
/// `before` is the point ahead of `pa` and `after` the point past `pb`, `None`
/// at an open polyline's ends. A neighbour that reaches behind the plane is
/// taken where its own chord meets the plane, which is **exactly the point**
/// that chord's own [`CameraView::clip_near`] cuts to — the same arguments in
/// the same order — so the two quads still share their corner bit for bit. An
/// end that was itself cut has no neighbour on screen and is left free.
///
/// [`CameraView::clip_near`]: crate::render::camera::CameraView::clip_near
pub(crate) fn joined_chord(
    view: &crate::render::camera::CameraView,
    before: Option<[f32; 3]>,
    pa: [f32; 3],
    pb: [f32; 3],
    after: Option<[f32; 3]>,
) -> Option<[[f32; 3]; 4]> {
    let (a, b) = view.clip_near(pa, pb)?;
    let prev = match before {
        Some(p) if a == pa => view.clip_near(p, pa).map_or(a, |(cut, _)| cut),
        _ => a,
    };
    let next = match after {
        Some(n) if b == pb => view.clip_near(pb, n).map_or(b, |(_, cut)| cut),
        _ => b,
    };
    Some([prev, a, b, next])
}

/// **Which space the stroke is measured in** (ADR-0160) — the half-width, the
/// join extensions and the direction all three are taken along.
///
/// A per-draw-call parameter rather than a per-instance field or a second
/// pipeline: it rides the segment uniform's `v.w`, a lane that was unused, so it
/// costs no bytes, no bind-group entry and no new resource (ADR-0058).
///
/// Explicit at every call site rather than inferred from which entry point the
/// caller used, so a producer that picks the wrong one is visible in its own
/// source rather than implicit in a pipeline.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StrokeMetric {
    /// **World space, the isotropic one**: a world displacement `(dx, dy)` lands
    /// on `(dx * H/2, dy * H/2)` pixels whichever axis it is on, because
    /// dividing x by the aspect is exactly what squares the space up. So the
    /// half-width is a thickness on screen and the extension is a length on
    /// screen, at every orientation.
    ///
    /// What the four line families pass, and what makes a producer's
    /// world-space interior angle the angle the shader extends along (ADR-0158).
    World,
    /// **Clip space, the anisotropic one**: one clip x unit is `aspect` times as
    /// many pixels as one clip y unit, so a vertical stroke is `aspect` times
    /// thicker on screen than a horizontal one at the same `width`.
    ///
    /// `warp_mesh` is the one surface on it, and it is a **dated deferral, not
    /// an endorsement** — see the comment at its call site.
    Clip,
}

impl StrokeMetric {
    /// The `v.w` lane's value. `World` is `0.0`, so the uniform a line family
    /// writes is byte-identical to the one written before this existed.
    fn lane(self) -> f32 {
        match self {
            Self::World => 0.0,
            Self::Clip => 1.0,
        }
    }
}

#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct Uniforms {
    // x: aspect, y: glow multiplier, z: softness (ADR-0124), w: the stroke
    // metric (ADR-0160) — 0 world, 1 clip
    v: [f32; 4],
    // x: zoom, yz: pan, w: unused — the shared ViewTransform (ADR-0018)
    view: [f32; 4],
}

/// The across-the-stroke profile, **one definition prepended to both fragment
/// modules** (ADR-0124).
///
/// `u` runs 0 at the stroke edge to 1 at the centreline; `du` is that
/// coordinate's change per pixel of the render target, from `fwidth` — so the
/// ramp derived from it is a width in **pixels of the render target** rather
/// than a fraction of the stroke, and no uniform has to carry a resolution.
/// `softness` is the ramp's width as a fraction of the half-width:
///
/// - **`1.0` reduces the whole expression to `g = u²` term for term** — the
///   profile every line scene drew before this parameter existed. That equality
///   is what the golden corpus rests on, and it holds **only because `edge` is
///   capped at 1.0**: a sub-pixel stroke drives `fwidth` above 1, where an
///   uncapped `max(softness, edge)` would divide `u` down and *dim* the stroke
///   instead of sharpening it. `warp_mesh`'s pin
///   ([`MILKDROP_SOFTNESS`](crate::render::scenes::warp_mesh::MILKDROP_SOFTNESS))
///   is byte-identical for the same reason — its `THIN` stroke is 1.0–1.35 px of
///   half-width, exactly that regime.
/// - `0.5` makes the inner half of the stroke solid and ramps across the outer.
/// - `0` is a solid stroke whose coverage falls to zero across **one pixel**,
///   whatever the stroke width, the resolution or the aspect.
///
/// Shared rather than written twice: two copies of a profile is a divergence
/// that compiles, and here it would mean a mandala whose circles and interlace
/// stop matching.
///
/// **`fwidth` exists only in a fragment shader**, so each caller evaluates it at
/// the fragment's top level and passes the result in — which also keeps the call
/// out of the arc fragment's non-uniform endpoint branch.
const PROFILE_WGSL: &str = r#"
fn stroke_coverage(u: f32, du: f32, softness: f32) -> f32 {
    let edge = clamp(du, 1e-6, 1.0);
    let ramp = max(clamp(softness, 0.0, 1.0), edge);
    let core = clamp(u / ramp, 0.0, 1.0);
    return core * core;
}
"#;

/// The WGSL body, minus the shared profile — [`shader_source`] prepends that.
const SHADER_BODY: &str = r#"
struct Uniforms {
    v: vec4<f32>,
    view: vec4<f32>,
}

@group(0) @binding(0) var<uniform> u: Uniforms;

struct VsOut {
    @builtin(position) pos: vec4<f32>,
    @location(0) side: f32,
    @location(1) color: vec3<f32>,
    @location(2) alpha: f32,
}

@vertex
fn vs_main(
    @builtin(vertex_index) vi: u32,
    @location(0) a: vec2<f32>,
    @location(1) b: vec2<f32>,
    @location(2) color: vec3<f32>,
    @location(3) width: f32,
    @location(4) ext_a: f32,
    @location(5) alpha: f32,
    @location(6) ext_b: f32,
) -> VsOut {
    // (along, side): along runs a->b, side spans -1..1 across the width.
    var corners = array<vec2<f32>, 6>(
        vec2<f32>(0.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(0.0, 1.0),
        vec2<f32>(0.0, 1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
    );
    let c = corners[vi];
    let aspect = max(u.v.x, 0.1);
    let inv_aspect = 1.0 / aspect;

    // Shared ViewTransform (ADR-0018): zoom about the frame centre, then pan, in
    // world space before the aspect divide. Endpoints move; stroke width does not.
    let zoom = u.view.x;
    let pan = u.view.yz;
    let a_v = a * zoom + pan;
    let b_v = b * zoom + pan;

    // The stroke is measured in WORLD space, which is the isotropic one: a
    // world displacement lands on the same number of pixels whichever axis it
    // is on, because dividing x by the aspect is exactly what squares the space
    // up. So the perpendicular offset below is a uniform on-screen thickness
    // whatever the segment's orientation, and the extension is a length on
    // screen (ADR-0160). The divide happens once, on the way out.
    //
    // `v.w` selects the space, per draw call: `warp_mesh` passes the CLIP
    // metric, which scales x in on the way IN and leaves `out.pos` alone, so
    // the offset lands in the anisotropic space. Multiplying by exactly 1.0 is
    // exact in f32, so each arm carries only its own scale - and at aspect 1.0
    // `inv_aspect` is exactly 1.0 and the two arms are the same arithmetic.
    let clip_metric = u.v.w > 0.5;
    let into_stroke = select(1.0, inv_aspect, clip_metric);
    let out_of_stroke = select(inv_aspect, 1.0, clip_metric);
    let a_s = vec2<f32>(a_v.x * into_stroke, a_v.y);
    let b_s = vec2<f32>(b_v.x * into_stroke, b_v.y);
    var dir = b_s - a_s;
    let len = length(dir);
    if (len > 1e-6) {
        dir = dir / len;
    } else {
        dir = vec2<f32>(1.0, 0.0);
    }
    let nrm = vec2<f32>(-dir.y, dir.x);

    // Join (ADR-0158): an end that continues into a neighbouring segment is
    // pushed past that endpoint along its **own** direction by the length the
    // producer computed for it. Adjacent quads then overlap across the shared
    // vertex and the additive falloff fills the wedge the two divergent
    // perpendiculars would otherwise leave. The producer is the only party that
    // can compute it, because a segment cannot see its neighbour's direction.
    // Each end is independent, and a free end is exactly `0.0` — `dir * 0.0` is
    // exactly zero, so a producer that extends nothing is byte-identical.
    let a_j = a_s - dir * ext_a;
    let b_j = b_s + dir * ext_b;

    let base = mix(a_j, b_j, c.x);
    let pos = base + nrm * c.y * width;

    var out: VsOut;
    out.pos = vec4<f32>(pos.x * out_of_stroke, pos.y, 0.0, 1.0);
    out.side = c.y;
    out.color = color;
    out.alpha = alpha;
    return out;
}

@fragment
fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
    // The shared profile (ADR-0124): a solid core of width `softness`, then a
    // quadratic ramp to the quad edge, floored at one pixel of the render
    // target. `side` spans -1..1 across the half-width, so `1 - |side|` is the
    // coordinate the profile takes.
    //
    // The derivative is read off `side` and NOT off `|side|`, whose kink at the
    // centreline would make `fwidth` meaningless on the 2x2 quad that straddles
    // it. Away from that quad the two are equal in magnitude.
    let inward = max(0.0, 1.0 - abs(in.side));
    let g = stroke_coverage(inward, fwidth(in.side), u.v.z);
    // Premultiplied: colour AND alpha carry the same coverage `g * alpha`, so
    // the two long edges of the quad - where the across-the-stroke falloff
    // reaches zero - write nothing at all rather than opaque black (ADR-0056).
    // Note the glow multiplier scales the LIGHT, not the coverage: a dimmed
    // stroke still covers its own footprint. See
    // `gpu::ADDITIVE_LIGHT_SATURATING_COVERAGE`.
    //
    // `alpha` is 1.0 for every additive producer, so this is byte-identical to
    // the pre-Plan-0100 fragment for all of them; it is the OVER pipeline's
    // second range that passes anything else. The colour is NOT divided by it -
    // an over-blended producer arrives premultiplied already.
    return vec4<f32>(in.color * g * u.v.y, g * in.alpha);
}
"#;

/// The full WGSL: the shared profile prepended to the body.
///
/// **The prelude carries no constants.** An endpoint's extension is an `f32`
/// length the shader multiplies by a direction (ADR-0158), and a float has no
/// bit assignment that could disagree with a Rust-side numbering — so there is
/// nothing here to generate and keep in step.
///
/// Prepending rather than `format!`-ing the whole body is deliberate: the body
/// is full of braces and every one would need escaping.
///
/// Runs once per [`LineRenderer::new`] (pipeline build, not the hot path).
fn shader_source() -> String {
    format!("{PROFILE_WGSL}\n{SHADER_BODY}")
}

/// The arc pipeline's full WGSL: [`PROFILE_WGSL`] prepended to [`ARC_SHADER`].
///
/// The two fragments are separate modules, so **the profile is shared by
/// construction rather than by convention** - the same reason [`shader_source`]
/// prepends it instead of the body restating it. Two hand-kept copies of the
/// expression would compile, render, and give a mandala whose circles and
/// interlace stop matching.
///
/// Runs once per [`LineRenderer::new_with_arcs`] (pipeline build, not the hot
/// path).
fn arc_shader_source() -> String {
    format!(
        "{PROFILE_WGSL}
{ARC_SHADER}"
    )
}

/// The arc pipeline's WGSL, **a separate shader module** from [`SHADER_BODY`]
/// and built only when a scene asked for arcs.
///
/// Separate rather than two more entry points in the one module, so a
/// `LineRenderer` without arcs creates exactly the resources it created before
/// this existed. Appending to the shared module would have changed what every
/// line scene compiles, and on the software adapter the golden suite captures
/// on, a changed resource is a changed picture (ADR-0058; measured on WARP,
/// unverified on lavapipe as of 2026-10-06).
///
/// # What the fragment computes, and in which space
///
/// The arc is authored in **world space**, which is isotropic on screen: the
/// vertex shader divides x by the aspect on the way out, so a world circle is a
/// circle in pixels. The **stroke** is measured there too (ADR-0160), which is
/// where the segment path measures it — so the two primitives place geometry
/// and stroke it in one space, and this arc draws the same picture as a densely
/// sampled polyline of it.
///
/// So the signed distance is `length(p - c) - r`, the exact world radial
/// distance, used as it stands. Outside the angular span it is the distance to
/// the nearer endpoint, which is a point, so that arm is exact too.
///
/// **The aspect is the render target's** (ADR-0037): it arrives in the uniform
/// `draw` was handed, and there is no internal grid, texture or second size
/// anywhere in this shader for another one to come from. This family has
/// shipped that bug three times, which is why the control renders at a
/// non-16:9 target where a grid-derived aspect and the target's disagree.
const ARC_SHADER: &str = r#"
struct Uniforms {
    v: vec4<f32>,
    view: vec4<f32>,
}

@group(0) @binding(0) var<uniform> u: Uniforms;

const TAU: f32 = 6.2831853071795864;
const QUARTER_TURN: f32 = 1.5707963267948966;

struct VsOut {
    @builtin(position) pos: vec4<f32>,
    @location(0) ndc: vec2<f32>,
    @location(1) @interpolate(flat) centre: vec2<f32>,
    @location(2) @interpolate(flat) radius: f32,
    // (lo, hi): the span's two ends in increasing order, so the sweep's sign
    // stops mattering past this point and the two endpoints are the same two
    // points either way.
    @location(3) @interpolate(flat) span: vec2<f32>,
    @location(4) @interpolate(flat) color: vec3<f32>,
    @location(5) @interpolate(flat) width: f32,
}

@vertex
fn vs_main(
    @builtin(vertex_index) vi: u32,
    @location(0) centre: vec2<f32>,
    @location(1) radius: f32,
    @location(2) angle_start: f32,
    @location(3) angle_sweep: f32,
    @location(4) color: vec3<f32>,
    @location(5) width: f32,
) -> VsOut {
    // The unit square, expanded to the arc's own bounding box below.
    var corners = array<vec2<f32>, 6>(
        vec2<f32>(0.0, 0.0), vec2<f32>(1.0, 0.0), vec2<f32>(0.0, 1.0),
        vec2<f32>(0.0, 1.0), vec2<f32>(1.0, 0.0), vec2<f32>(1.0, 1.0),
    );
    let c = corners[vi];
    let aspect = max(u.v.x, 0.1);

    // Shared ViewTransform (ADR-0018), applied exactly as the segment shader
    // applies it: in world space, before the aspect divide. A uniform zoom
    // scales the radius with the centre; stroke width does not move.
    let centre_v = centre * u.view.x + u.view.yz;
    let radius_v = radius * u.view.x;

    let a0 = angle_start;
    let a1 = angle_start + angle_sweep;
    let lo = min(a0, a1);
    let hi = max(a0, a1);

    // The centreline's bounding box: the two ends always, plus each axis
    // extreme the span actually reaches. A full turn reaches all four and the
    // box is the whole circle; a short span gets a box barely bigger than its
    // own chord, which is what keeps the shaded area near the stroke's.
    let end0 = vec2<f32>(cos(a0), sin(a0));
    let end1 = vec2<f32>(cos(a1), sin(a1));
    var lo_dir = min(end0, end1);
    var hi_dir = max(end0, end1);
    for (var k = 0u; k < 4u; k = k + 1u) {
        let ang = f32(k) * QUARTER_TURN;
        // The smallest representative of `ang` modulo TAU at or above `lo`.
        let t = ang + TAU * ceil((lo - ang) / TAU);
        if (t <= hi) {
            let d = vec2<f32>(cos(ang), sin(ang));
            lo_dir = min(lo_dir, d);
            hi_dir = max(hi_dir, d);
        }
    }

    // The stroke reaches `width` in WORLD units on every side (ADR-0160), so
    // the pad is isotropic in the space this box is built in. The 2 % is slack
    // for the distance being a first-order expression of a curved level set -
    // see the fragment.
    //
    // The pad has to be at least what the stroke reaches on each axis or the
    // box clips its own edge, and in world units that is `width` on both -
    // scaling either axis by the aspect under-pads it on one side of 1.0.
    let pad = vec2<f32>(width, width) * 1.02;
    let lo_w = centre_v + radius_v * lo_dir - pad;
    let hi_w = centre_v + radius_v * hi_dir + pad;
    let p = mix(lo_w, hi_w, c);
    let ndc = vec2<f32>(p.x / aspect, p.y);

    var out: VsOut;
    out.pos = vec4<f32>(ndc, 0.0, 1.0);
    out.ndc = ndc;
    out.centre = centre_v;
    out.radius = radius_v;
    out.span = vec2<f32>(lo, hi);
    out.color = color;
    out.width = width;
    return out;
}

@fragment
fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
    let aspect = max(u.v.x, 0.1);
    // Back into the isotropic world space the arc is authored in.
    let p = vec2<f32>(in.ndc.x * aspect, in.ndc.y);
    let q = p - in.centre;
    let len = length(q);

    // Inside the span, or past one of its ends? The same modulo reduction the
    // vertex shader uses, so an arc that wraps the branch cut of atan2 is not
    // a special case.
    let theta = atan2(q.y, q.x);
    let t = theta + TAU * ceil((in.span.x - theta) / TAU);

    // SIGNED across the stroke, and that is load-bearing: the profile below
    // takes `fwidth` of this, and `fwidth` of an ABSOLUTE distance is garbage
    // on the 2x2 quad that straddles the centreline - the kink makes the finite
    // difference near zero exactly where the stroke is brightest. The segment
    // fragment reads `side` and not `|side|` for the same reason.
    var sd: f32;
    if (t <= in.span.y) {
        // The exact world radial distance, and the stroke is measured in world
        // units too (ADR-0160) - so it is used as it stands, with nothing
        // converted and nothing to keep in step with the segment path.
        sd = len - in.radius;
    } else {
        // Past an end: the world distance to the nearer endpoint. A point has
        // an exact distance, so this arm approximates nothing.
        let e0 = in.centre + in.radius * vec2<f32>(cos(in.span.x), sin(in.span.x));
        let e1 = in.centre + in.radius * vec2<f32>(cos(in.span.y), sin(in.span.y));
        sd = min(length(p - e0), length(p - e1));
    }

    // The segment path's profile on the arc's own distance - literally the
    // same `stroke_coverage`, prepended to both modules (ADR-0124), so the two
    // fragments cannot draw different strokes on the same figure.
    //
    // `sd` is a world distance and `width` is flat-interpolated, so the
    // normalized coordinate is `sd / width` and its screen derivative is
    // `fwidth(sd) / width`. One pixel of the render target is `2 / H` world
    // units on BOTH axes - `2 * aspect / W` is that same number - so the ramp
    // is one pixel of the target at every orientation and on any frame. Taken
    // on the signed distance, per its declaration.
    //
    // Premultiplied, so colour and alpha carry the same coverage and the quad
    // outside the stroke writes nothing at all rather than opaque black
    // (ADR-0056). The glow multiplier scales the LIGHT, not the coverage,
    // exactly as it does for a segment.
    //
    // DIVIDED, not multiplied by a reciprocal: `x / w` and `x * (1 / w)` differ
    // in the last ulp, and byte-identity at the default is what the golden
    // corpus rests on.
    let width = max(in.width, 1e-8);
    let g = stroke_coverage(max(0.0, 1.0 - abs(sd) / width), fwidth(sd) / width, u.v.z);
    return vec4<f32>(in.color * g * u.v.y, g);
}
"#;

/// The `seg3d` pipeline's full WGSL: [`PROFILE_WGSL`], the shared camera and
/// [`SEG3D_SHADER`], in that order.
///
/// The profile is prepended here for the reason [`arc_shader_source`] gives: a
/// 3D stroke and a 2D one fall off across their width by one definition.
///
/// [`MITER_LIMIT`] is written into it from the one Rust constant, so a 3D
/// joint and a 2D one fall back to the bevel at the same corner, and
/// [`NEAR`](crate::render::camera::NEAR) likewise, so a skirt's foot is held to
/// the plane the CPU clips at.
///
/// Runs once per [`LineRenderer::new_3d`] (pipeline build, not the hot path).
pub(crate) fn seg3d_shader_source() -> String {
    format!(
        "{PROFILE_WGSL}
const MITER_LIMIT: f32 = {MITER_LIMIT:?};
const NEAR_DEPTH: f32 = {:?};
{}
{SEG3D_SHADER}",
        crate::render::camera::NEAR,
        crate::render::camera::CAMERA_WGSL
    )
}

/// The `seg3d` pipeline's WGSL: each [`Segment3dInstance`] projected through the
/// shared camera and expanded into a quad **in pixels of the render target**.
///
/// The quad is built in pixel space after the divide, where the space is
/// isotropic, so the stroke has the same thickness on screen at every
/// orientation; the aspect comes from the camera's viewport, which is the
/// render target's (ADR-0037). Each end's half-width is the stroke width carried
/// to that end's depth by perspective, and the quad is a trapezoid between the
/// two, so a line receding from the camera thins along its length.
///
/// **A half-width is floored at half a pixel, and the light is scaled down by
/// the same ratio**, so a stroke too thin to rasterize fades rather than
/// breaking into a dotted line, and keeps the light it would have had.
///
/// # Depth of field, per endpoint (ADR-0257)
///
/// Each end takes the camera's circle of confusion at its own depth, `coc`, and
/// its half-width grows from `w` to `w + coc`. Its edge softness widens with
/// it, from the stroke's own `s0` toward `1` by `coc / (w + coc)`, so a blurred
/// end has no hard edge. Both are interpolated along the quad, so one line is
/// sharp where it crosses the focal plane and soft at either end.
///
/// **The light is divided down so the stroke's integrated cross-section keeps
/// its energy.** The profile integrates across a half-width `h` to
/// `h * (1 - 2s/3)` — a solid core of `1 - s` plus a quadratic ramp worth
/// `s / 3` — so each fragment's light is scaled by
///
/// ```text
/// w * (1 - 2 s0 / 3)  /  ((w + coc) * (1 - 2 s / 3))
/// ```
///
/// from the interpolated sharp half-width `w`, blurred half-width `w + coc` and
/// softness `s`. It is evaluated per fragment rather than at the two ends and
/// interpolated: the energy is a product of interpolated quantities, and a
/// linear blend of the end factors overshoots it everywhere between them.
///
/// **A blurred stroke reads its across-the-stroke coordinate exactly.** A
/// trapezoid is drawn as two triangles, and the corner coordinate `side`
/// interpolated affinely over each of them bends wherever the two ends'
/// widths differ — which a blurred end makes them do by a factor of several.
/// The perpendicular pixel offset is affine over the whole quad, and so is the
/// half-width along it, so their ratio is the true coordinate at every
/// fragment.
///
/// A sharp stroke skips both the factor and the exact coordinate on a flat
/// flag, so an aperture of `0` draws the bytes a pinhole camera drew.
///
/// # Joins (ADR-0263)
///
/// An end whose [`Segment3dInstance::prev`] or [`next`](Segment3dInstance::next)
/// names a neighbour is mitred in pixel space: its two corners move onto the
/// line bisecting the turn, where the neighbour's corners also lie, so two
/// blurred neighbours abut instead of summing their overlap into a ridge. A
/// corner sharper than [`MITER_LIMIT`] stays flat, as in 2D.
///
/// # Fog (ADR-0263)
///
/// Each end's light is scaled by `fog_light()` at its own depth, `1 - fog * d`
/// with `d` its place across the volume, and the factor is interpolated along
/// the quad. Coverage is untouched, so a fogged stroke darkens rather than
/// thins.
///
/// The position leaves the vertex shader already divided (`w = 1`). The quad is
/// a screen-space shape, and interpolating its varyings perspective-correctly
/// against the endpoints' depths would bend the across-the-stroke coordinate.
const SEG3D_SHADER: &str = r#"
struct Stroke {
    // x: glow multiplier, y: softness (ADR-0124), z: fog (ADR-0263), w: the
    // world y of the ground plane a skirt reaches down to. The vertex stage
    // reads the softness too, to widen it toward a blurred end.
    v: vec4<f32>,
}

@group(0) @binding(0) var<uniform> cam: Camera;
@group(0) @binding(1) var<uniform> stroke: Stroke;

struct Seg3dOut {
    @builtin(position) pos: vec4<f32>,
    @location(0) side: f32,
    @location(1) color: vec3<f32>,
    @location(2) alpha: f32,
    // The edge softness, widened by the circle of confusion toward each end.
    @location(3) soft: f32,
    // The half-width the stroke would have with no blur, and the blurred one,
    // in pixels - the two sides of the energy ratio.
    @location(5) sharp_hw: f32,
    @location(6) wide_hw: f32,
    // The fragment's perpendicular offset from the centreline, in pixels.
    @location(7) offset: f32,
    // 1 when either end is blurred, 0 otherwise. Flat, so a sharp stroke reads
    // the uniform softness itself rather than an interpolation of copies of it.
    @location(4) @interpolate(flat) blurred: f32,
    // 1 on a skirt, which fills at full coverage rather than stroking.
    @location(8) @interpolate(flat) skirt: f32,
}

// The profile's integral across a unit half-width at softness `s`.
fn profile_mass(s: f32) -> f32 {
    return 1.0 - 2.0 * clamp(s, 0.0, 1.0) / 3.0;
}

// Half a pixel: the narrowest half-width a stroke is rasterized at.
const MIN_HALF_PX: f32 = 0.5;

// The mitred corner offset at `v`, where the polyline arrives from `p0` and
// leaves for `p1`, for a half-width `hw` - all in pixels. `xy` is the offset of
// the corner on the left side (`side = +1`), and `z` is 1 when the end is
// joined, 0 when it is free: a neighbour that coincides with `v` on screen,
// or a corner sharper than MITER_LIMIT, which draws flat as the bevel
// fallback does in 2D (ADR-0158).
//
// Both quads that share `v` call this with the same three points, in the same
// roles, so they compute the same corner bit for bit and abut on the mitre
// line with no pixel covered twice and none missed.
//
// The left normal of each arm, summed, is the mitre direction; its corner
// lies `hw / cos(turn / 2)` along it, and `cos(turn / 2)` is
// `sqrt((1 + d_in . d_out) / 2)` - the expression `miter_extension_between`
// takes, with no trigonometry.
fn mitre_offset(p0: vec2<f32>, v: vec2<f32>, p1: vec2<f32>, hw: f32) -> vec3<f32> {
    let arm_in = v - p0;
    let arm_out = p1 - v;
    let len_in = length(arm_in);
    let len_out = length(arm_out);
    if (len_in <= 1e-6 || len_out <= 1e-6) {
        return vec3<f32>(0.0, 0.0, 0.0);
    }
    let d_in = arm_in / len_in;
    let d_out = arm_out / len_out;
    let cos_half = sqrt(max((1.0 + dot(d_in, d_out)) * 0.5, 0.0));
    if (cos_half <= 1.0 / MITER_LIMIT) {
        return vec3<f32>(0.0, 0.0, 0.0);
    }
    let bisector = vec2<f32>(-d_in.y, d_in.x) + vec2<f32>(-d_out.y, d_out.x);
    let m = bisector / length(bisector);
    return vec3<f32>(m * (hw / cos_half), 1.0);
}

@vertex
fn vs_main(
    @builtin(vertex_index) vi: u32,
    @location(0) a: vec3<f32>,
    @location(1) b: vec3<f32>,
    @location(2) color: vec3<f32>,
    @location(3) width: f32,
    @location(4) alpha: f32,
    @location(5) prev: vec3<f32>,
    @location(6) next: vec3<f32>,
    @location(7) skirt: f32,
) -> Seg3dOut {
    // (along, side): along runs a->b, side spans -1..1 across the width.
    var corners = array<vec2<f32>, 6>(
        vec2<f32>(0.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(0.0, 1.0),
        vec2<f32>(0.0, 1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
    );
    let c = corners[vi];

    let ca = project(cam, a);
    let cb = project(cam, b);
    let sa = clip_to_px(cam, ca);
    let sb = clip_to_px(cam, cb);

    let hw_a = at_depth(cam, 0.5 * width, ca.w);
    let hw_b = at_depth(cam, 0.5 * width, cb.w);
    let coc_a = coc(cam, ca.w);
    let coc_b = coc(cam, cb.w);
    let s0 = stroke.v.y;

    // The blurred half-width at each end, and `c.x` is exactly 0 or 1 at every
    // corner, so `mix` picks one end exactly.
    let hw_true = mix(hw_a + coc_a, hw_b + coc_b, c.x);
    let hw = max(hw_true, MIN_HALF_PX);

    // Each end's softness, widened toward 1 by its share of blur. Guarded
    // against a zero width, where there is no stroke to soften.
    let wide_a = hw_a + coc_a;
    let wide_b = hw_b + coc_b;
    let soft_a = mix(s0, 1.0, select(0.0, coc_a / wide_a, wide_a > 0.0));
    let soft_b = mix(s0, 1.0, select(0.0, coc_b / wide_b, wide_b > 0.0));

    var dir = sb - sa;
    let len = length(dir);
    if (len > 1e-6) {
        dir = dir / len;
    } else {
        dir = vec2<f32>(1.0, 0.0);
    }
    let nrm = vec2<f32>(-dir.y, dir.x);
    var p = mix(sa, sb, c.x) + nrm * c.y * hw;

    // The join (ADR-0263). This corner's end, its neighbour on the far side
    // and the half-width there are picked with `select` rather than `mix`:
    // `mix(x, y, 1.0)` need not be `y` to the bit, and the neighbouring quad
    // reads the same end as its `a`, where it is. A free end keeps the flat
    // corner above untouched, so a stroke with no neighbours draws the bytes
    // it drew before joins existed.
    let at_b = c.x > 0.5;
    let joint = select(sa, sb, at_b);
    let before = select(clip_to_px(cam, project(cam, prev)), sa, at_b);
    let after = select(sb, clip_to_px(cam, project(cam, next)), at_b);
    let hw_joint = max(select(wide_a, wide_b, at_b), MIN_HALF_PX);
    let mitre = mitre_offset(before, joint, after, hw_joint);
    let joined = mitre.z > 0.5;
    if (joined) {
        p = joint + mitre.xy * c.y;
    }

    // Fog (ADR-0263), per end and interpolated along the quad. It scales the
    // light and never the coverage, and at fog 0 it is exactly 1.
    let fogged = fog_light(cam, stroke.v.z, select(ca.w, cb.w, at_b));

    // A skirt (ADR-0263) is the band under this end: its `side = +1` corners
    // on the segment, its `side = -1` corners straight below on the ground
    // plane, each projected on its own. No width, no join and no blur reach
    // it; the fragment fills it.
    let is_skirt = skirt > 0.5;
    if (is_skirt) {
        let top = select(a, b, at_b);
        let foot = vec3<f32>(top.x, stroke.v.w, top.z);
        let corner = project(cam, select(foot, top, c.y > 0.0));
        p = clip_to_px(cam, vec4<f32>(corner.xyz, max(corner.w, NEAR_DEPTH)));
    }

    var out: Seg3dOut;
    out.pos = vec4<f32>(px_to_ndc(cam, p), 0.0, 1.0);
    out.skirt = select(0.0, 1.0, is_skirt);
    out.side = c.y;
    out.color = color * (hw_true / hw) * fogged;
    out.alpha = alpha;
    out.soft = mix(soft_a, soft_b, c.x);
    out.sharp_hw = mix(hw_a, hw_b, c.x);
    out.wide_hw = hw_true;
    // A mitred corner lies `hw_joint` from the centreline across the stroke,
    // wherever the mitre has slid it along, so the offset stays the true
    // across-the-stroke distance.
    out.offset = c.y * select(hw, hw_joint, joined);
    out.blurred = select(0.0, 1.0, max(coc_a, coc_b) > 0.0);
    return out;
}

@fragment
fn fs_main(in: Seg3dOut) -> @location(0) vec4<f32> {
    // The shared profile, read off `side` rather than `|side|` for the reason
    // the 2D fragment gives.
    let blurred = in.blurred > 0.5;
    let side = select(in.side, in.offset / max(in.wide_hw, 1e-6), blurred);
    let inward = max(0.0, 1.0 - abs(side));
    let soft = select(stroke.v.y, in.soft, blurred);
    let g = stroke_coverage(inward, fwidth(side), soft) * in.alpha;
    // The energy ratio, exactly 1 for a sharp stroke.
    let spread = in.wide_hw * profile_mass(soft);
    let keep = select(
        1.0,
        (in.sharp_hw * profile_mass(stroke.v.y)) / spread,
        blurred && spread > 0.0,
    );
    // Premultiplied (ADR-0056): the glow scales the light, not the coverage.
    // A skirt covers its whole band at its alpha; it is chosen after the
    // stroke is computed rather than branched to, because `fwidth` above must
    // stay in uniform control flow.
    let lit = vec4<f32>(in.color * g * stroke.v.x * keep, g);
    let fill = vec4<f32>(in.color * stroke.v.x * in.alpha, in.alpha);
    return select(lit, fill, in.skirt > 0.5);
}
"#;

/// The `seg3d` stroke uniform: `[glow, softness, fog, ground y]`.
#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
struct Stroke3dUniform {
    v: [f32; 4],
}

/// The `seg3d` pipeline and everything it binds — built only by
/// [`LineRenderer::new_3d`].
struct Seg3d {
    pipeline: wgpu::RenderPipeline,
    /// The same pipeline composited **over** rather than added, for a solid
    /// frame (ADR-0263). Built with the additive one rather than on the first
    /// solid frame: a resource created mid-run moves what later passes
    /// resolve to on the software adapter the goldens capture on (measured on
    /// WARP, unverified on lavapipe as of 2026-10-06).
    over_pipeline: wgpu::RenderPipeline,
    instances: wgpu::Buffer,
    camera: wgpu::Buffer,
    stroke: wgpu::Buffer,
    bind_group: wgpu::BindGroup,
    capacity: usize,
    /// A solid frame's sort keys, `(depth, index)`, preallocated to
    /// `capacity` so the sort allocates nothing.
    keys: Vec<(f32, u32)>,
    /// A solid frame's segments in draw order, far to near, preallocated to
    /// `capacity`.
    sorted: Vec<Segment3dInstance>,
}

/// `segments` in **far-to-near** order into `out`, by the camera depth of each
/// segment's midpoint under `view` — the painter's order a solid frame draws
/// in (ADR-0263), so a nearer stroke composites over a farther one.
///
/// **The order is a function of the set, not of the order it arrived in.**
/// Two segments at one depth are ordered by their own bytes, which is a total
/// order on the instance, so a system that emits the same segments in another
/// order draws the same frame.
///
/// **Allocation-free** while `segments` fits the capacity `keys` and `out`
/// were reserved to: both are cleared and refilled, and `sort_unstable_by`
/// sorts in place.
pub(crate) fn sort_far_to_near(
    view: &crate::render::camera::CameraView,
    segments: &[Segment3dInstance],
    keys: &mut Vec<(f32, u32)>,
    out: &mut Vec<Segment3dInstance>,
) {
    sort_painter(view, segments, None, keys, out);
}

/// [`sort_far_to_near`], with the depth each segment sorts by taken at its
/// midpoint's **foot** on the plane `y = ground` when one is named.
///
/// A heightfield's rows are what occlude one another, not its peaks: keyed at
/// the midpoint itself, a tall peak several rows back sorts nearer than a low
/// row in front of it, because raising a point toward a camera that looks down
/// shortens its depth. Keyed at the foot, every segment of one row sorts by
/// where the row stands.
///
/// At one key, a skirt sorts **before** the stroke it lies under, so the
/// stroke is drawn over its own band; past that the instance bytes break the
/// tie.
pub(crate) fn sort_painter(
    view: &crate::render::camera::CameraView,
    segments: &[Segment3dInstance],
    ground: Option<f32>,
    keys: &mut Vec<(f32, u32)>,
    out: &mut Vec<Segment3dInstance>,
) {
    keys.clear();
    out.clear();
    for (i, s) in segments.iter().enumerate() {
        let mid = [
            0.5 * (s.a[0] + s.b[0]),
            ground.unwrap_or(0.5 * (s.a[1] + s.b[1])),
            0.5 * (s.a[2] + s.b[2]),
        ];
        keys.push((view.depth(mid), i as u32));
    }
    let skirt = |i: u32| segments.get(i as usize).map_or(0.0, |s| s.skirt);
    let content = |i: u32| segments.get(i as usize).map(bytemuck::bytes_of);
    keys.sort_unstable_by(|x, y| {
        y.0.total_cmp(&x.0)
            .then_with(|| skirt(y.1).total_cmp(&skirt(x.1)))
            .then_with(|| content(x.1).cmp(&content(y.1)))
    });
    out.extend(
        keys.iter()
            .filter_map(|&(_, i)| segments.get(i as usize).copied()),
    );
}

impl Seg3d {
    fn new(
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        capacity: usize,
        label: &str,
    ) -> Self {
        use crate::render::camera::CameraUniform;

        let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some(&format!("{label}-seg3d-shader")),
            source: wgpu::ShaderSource::Wgsl(seg3d_shader_source().into()),
        });
        let instances = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some(&format!("{label}-seg3d-instances")),
            size: (capacity * std::mem::size_of::<Segment3dInstance>()) as u64,
            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        let camera = gpu::uniform_buffer(
            device,
            &format!("{label}-seg3d-camera"),
            std::mem::size_of::<CameraUniform>(),
        );
        let stroke = gpu::uniform_buffer(
            device,
            &format!("{label}-seg3d-stroke"),
            std::mem::size_of::<Stroke3dUniform>(),
        );
        // A shape of its own — two sized uniforms, the camera for the vertex
        // stage and the stroke for both — so no other live layout matches it
        // (ADR-0058).
        let bind_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some(&format!("{label}-seg3d-bind-layout")),
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::VERTEX,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: wgpu::BufferSize::new(
                            std::mem::size_of::<CameraUniform>() as u64,
                        ),
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: wgpu::BufferSize::new(
                            std::mem::size_of::<Stroke3dUniform>() as u64,
                        ),
                    },
                    count: None,
                },
            ],
        });
        let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some(&format!("{label}-seg3d-bind-group")),
            layout: &bind_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: camera.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: stroke.as_entire_binding(),
                },
            ],
        });
        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some(&format!("{label}-seg3d-pipeline-layout")),
            bind_group_layouts: &[Some(&bind_layout)],
            immediate_size: 0,
        });
        // The two pipelines differ in the blend state and nothing else, so they
        // are built from one closure, as the 2D pair is.
        let make = |blend: wgpu::BlendState, suffix: &str| {
            device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                label: Some(&format!("{label}-seg3d-pipeline{suffix}")),
                layout: Some(&pipeline_layout),
                vertex: wgpu::VertexState {
                    module: &shader,
                    entry_point: Some("vs_main"),
                    compilation_options: Default::default(),
                    buffers: &[Some(wgpu::VertexBufferLayout {
                        array_stride: std::mem::size_of::<Segment3dInstance>() as u64,
                        step_mode: wgpu::VertexStepMode::Instance,
                        attributes: &wgpu::vertex_attr_array![
                            0 => Float32x3,
                            1 => Float32x3,
                            2 => Float32x3,
                            3 => Float32,
                            4 => Float32,
                            5 => Float32x3,
                            6 => Float32x3,
                            7 => Float32,
                        ],
                    })],
                },
                fragment: Some(wgpu::FragmentState {
                    module: &shader,
                    entry_point: Some("fs_main"),
                    compilation_options: Default::default(),
                    targets: &[Some(wgpu::ColorTargetState {
                        format: surface_format,
                        blend: Some(blend),
                        write_mask: wgpu::ColorWrites::ALL,
                    })],
                }),
                primitive: wgpu::PrimitiveState::default(),
                depth_stencil: None,
                multisample: wgpu::MultisampleState::default(),
                multiview_mask: None,
                cache: None,
            })
        };
        // The seam every additive line draws through (ADR-0056), then the
        // premultiplied OVER a solid frame takes. The fragment is premultiplied
        // either way, which is why one shader serves both.
        let pipeline = make(gpu::ADDITIVE_LIGHT_SATURATING_COVERAGE, "");
        let over_pipeline = make(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING, "-over");
        Self {
            pipeline,
            over_pipeline,
            instances,
            camera,
            stroke,
            bind_group,
            capacity,
            keys: Vec::with_capacity(capacity),
            sorted: Vec::with_capacity(capacity),
        }
    }
}

/// The share of the segment `a -> b` lying inside `[-aspect, aspect] x [-1, 1]`,
/// as a fraction of its own length: Liang-Barsky against the four edges.
///
/// **Exactly `1.0`** when the segment is untouched by any edge — the two
/// parameters start at `0.0` and `1.0` and no edge moves them — which is what
/// lets an unclipped figure sum to exactly its own total. **Exactly `0.0`** when
/// the segment is wholly outside.
///
/// A parametric clip rather than an endpoint test on purpose: the case a naive
/// "are both ends outside" check gets wrong is a segment whose ends are both out
/// but which crosses the frame between them, and that is precisely what a badly
/// over-scaled figure is made of.
fn in_frame_fraction(a: [f32; 2], b: [f32; 2], aspect: f32) -> f32 {
    let [ax, ay] = a;
    let [bx, by] = b;
    let (dx, dy) = (bx - ax, by - ay);
    let (mut t0, mut t1) = (0.0f32, 1.0f32);
    // (direction, distance) per edge: left, right, bottom, top.
    for (p, q) in [
        (-dx, ax + aspect),
        (dx, aspect - ax),
        (-dy, ay + 1.0),
        (dy, 1.0 - ay),
    ] {
        if p == 0.0 {
            // Parallel to this edge: wholly out if it starts outside it.
            if q < 0.0 {
                return 0.0;
            }
            continue;
        }
        let r = q / p;
        if p < 0.0 {
            if r > t1 {
                return 0.0;
            }
            if r > t0 {
                t0 = r;
            }
        } else {
            if r < t0 {
                return 0.0;
            }
            if r < t1 {
                t1 = r;
            }
        }
    }
    t1 - t0
}

/// Sub-arcs one [`ArcInstance`] is measured in — a **power of two**, which is
/// load-bearing.
///
/// Each sub-arc is clipped by its own chord and weighted `1 / ARC_STEPS`, so an
/// arc wholly inside the frame accumulates that weight exactly `ARC_STEPS`
/// times. At a power of two the weight is exact in binary and the sum is
/// **exactly 1.0**, which is what keeps an unclipped figure measuring exactly
/// its own length — the property `in_frame_fraction` is written to preserve for
/// segments.
///
/// Sixty-four puts 5.6 degrees in a sub-arc of a full circle, whose chord
/// departs from it by `r * (1 - cos(2.8 deg))`, about `0.0012 * r`. The error is
/// a function of the angle per step alone, so it does not grow with radius.
const ARC_STEPS: usize = 64;

/// The world-space length of `arc` and the share of it inside
/// `[-aspect, aspect] x [-1, 1]`, under the same view transform the vertex
/// shader applies.
///
/// Measured as [`ARC_STEPS`] sub-arcs clipped by their own chords rather than by
/// solving the circle against the four edges: the closed form needs the
/// intersection of four half-planes with a circle, which is up to four disjoint
/// angular components and considerably more code than the property is worth.
/// Both sums are taken from the arc's **own** length (`|sweep| * radius`), never
/// from the chords', so the sub-chord sampling changes only *where* the arc is
/// judged to be, never how long it is.
fn measure_arc(arc: &ArcInstance, aspect: f32, xform: super::ViewTransform) -> (f32, f32) {
    let [pan_x, pan_y] = xform.pan;
    let centre = [
        arc.centre[0] * xform.zoom + pan_x,
        arc.centre[1] * xform.zoom + pan_y,
    ];
    let radius = arc.radius * xform.zoom;
    let len = (radius * arc.angle_sweep).abs();
    if len <= 0.0 || !len.is_finite() {
        return (0.0, 0.0); // a degenerate (or non-finite) arc measures nothing
    }
    let step = 1.0 / ARC_STEPS as f32;
    let at = |k: usize| {
        let t = arc.angle_start + arc.angle_sweep * k as f32 * step;
        [centre[0] + radius * t.cos(), centre[1] + radius * t.sin()]
    };
    let mut inside = 0.0;
    for k in 0..ARC_STEPS {
        inside += in_frame_fraction(at(k), at(k + 1), aspect) * step;
    }
    (len, len * inside)
}

/// Measure `segments` against the frame — the diagnostic's whole computation.
///
/// **The aspect is a parameter, and it is the only source of one in here**
/// (ADR-0037): this is a free function over the endpoints, so there is no
/// internal grid, no texture and no `self` for a second aspect to come from.
/// Its caller hands it the value `draw` was handed, which is the **render
/// target's**.
///
/// The view transform is applied first, exactly as the vertex shader applies it
/// (`a * zoom + pan`, before the aspect divide), because a figure pushed off the
/// frame by `zoom` or `pan_y` has overshot just as surely as one scaled off it.
fn measure_extent(
    segments: &[SegmentInstance],
    arcs: &[ArcInstance],
    aspect: f32,
    xform: super::ViewTransform,
) -> DrawExtent {
    let mut extent = DrawExtent::default();
    let [pan_x, pan_y] = xform.pan;
    for segment in segments {
        let [ax, ay] = segment.a;
        let [bx, by] = segment.b;
        let a = [ax * xform.zoom + pan_x, ay * xform.zoom + pan_y];
        let b = [bx * xform.zoom + pan_x, by * xform.zoom + pan_y];
        let ([ax, ay], [bx, by]) = (a, b);
        let (dx, dy) = (bx - ax, by - ay);
        let len = (dx * dx + dy * dy).sqrt();
        if len <= 0.0 || !len.is_finite() {
            continue; // a degenerate (or non-finite) segment measures nothing
        }
        extent.total_len += len;
        // `len * 1.0` is `len` exactly, so an unclipped figure adds the same
        // value to both sums and the fraction is exactly 1.0.
        extent.in_frame_len += len * in_frame_fraction(a, b, aspect);
    }
    // Arcs, into the same two sums: the fraction is over everything drawn, and
    // a batch of both kinds has one denominator.
    for arc in arcs {
        let (len, in_frame) = measure_arc(arc, aspect, xform);
        extent.total_len += len;
        extent.in_frame_len += in_frame;
    }
    extent
}

/// Draws segment buffers as thick glowing quads. Owns its pipeline, a
/// fixed-capacity instance buffer, and the aspect/glow uniform.
pub struct LineRenderer {
    pipeline: wgpu::RenderPipeline,
    /// The same pipeline with the light composited **over** rather than added —
    /// see [`LineRenderer::draw_split`]. It shares the shader, the layout and the
    /// bind group with [`pipeline`](Self::pipeline), so ADR-0058 has nothing to
    /// separate: there is one layout, not two that happen to match.
    ///
    /// **`None` unless the scene asked for it** ([`LineRenderer::new_split`]),
    /// and that is not a micro-optimization. Building a pipeline the scene never
    /// binds still allocates on the device, and on the WARP software adapter a
    /// changed allocation order changes what a later pass resolves to — the
    /// hazard `core/tests/suite/composite.rs`'s header records, on a software
    /// adapter like the one the golden suite captures on. Building this for the
    /// nine line scenes that do not use it moved five composite baselines while
    /// changing nothing a driver would render differently. (WARP readings,
    /// unverified on lavapipe as of 2026-10-06.)
    over_pipeline: Option<wgpu::RenderPipeline>,
    /// The [`ArcInstance`] pipeline, drawn in the same additive pass from its
    /// own buffer — [`ARC_SHADER`] and ADR-0098.
    ///
    /// **`None` unless the scene asked for it**
    /// ([`LineRenderer::new_with_arcs`]), for the reason
    /// [`over_pipeline`](Self::over_pipeline) records and with the same
    /// evidence behind it: building a pipeline nobody binds still allocates on
    /// the device, and on WARP a changed allocation order changes what a later
    /// pass resolves to (unverified on lavapipe as of 2026-10-06). It **shares
    /// the bind-group layout, the bind group and the pipeline layout** with the
    /// segment pipelines — one uniform, one layout, so ADR-0058 has nothing new
    /// to separate. Only the vertex layout and the shader module differ.
    arc_pipeline: Option<wgpu::RenderPipeline>,
    /// [`arc_pipeline`](Self::arc_pipeline) with the light composited **over**
    /// rather than added — the arc half of the opacity-preserving seam
    /// (ADR-0138), built exactly when [`over_pipeline`](Self::over_pipeline) and
    /// the arc pipeline both are.
    ///
    /// Without it, [`draw_opaque`](Self::draw_opaque) on a scene whose motifs are
    /// arcs would lay opaque strokes and additive circles into one picture, and
    /// the limited-ink guarantee would hold for half of what the scene drew.
    arc_over_pipeline: Option<wgpu::RenderPipeline>,
    instances: wgpu::Buffer,
    /// The arc instance buffer, `Some` exactly when
    /// [`arc_pipeline`](Self::arc_pipeline) is.
    arcs: Option<wgpu::Buffer>,
    uniforms: wgpu::Buffer,
    bind_group: wgpu::BindGroup,
    /// Maximum segments the instance buffer holds; extra are dropped by `draw`.
    capacity: usize,
    /// Maximum arcs the arc buffer holds; `0` when there is no arc pipeline.
    arc_capacity: usize,
    /// The 3D segment pipeline (ADR-0257), **`None` unless the scene asked for
    /// it** ([`LineRenderer::new_3d`]) — for the reason
    /// [`over_pipeline`](Self::over_pipeline) records: a pipeline nobody binds
    /// still allocates on the device, and on WARP a changed allocation order
    /// changes what a later pass resolves to (unverified on lavapipe as of
    /// 2026-10-06).
    seg3d: Option<Seg3d>,
}

impl LineRenderer {
    /// Build the pipeline and a `capacity`-segment instance buffer on `device`.
    /// `label` names this instance's GPU resources; it must be **unique per
    /// LineRenderer** — two line scenes coexist (parametric + generator), and
    /// distinct labels keep their pipelines/buffers unambiguous in tooling and
    /// captures.
    pub fn new(
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        capacity: usize,
        label: &str,
    ) -> Self {
        Self::build(device, surface_format, capacity, label, false, 0)
    }

    /// [`new`](Self::new), plus the second pipeline
    /// [`draw_split`](Self::draw_split) needs. Only a scene that actually splits
    /// its batch by blend mode should call this — see
    /// `over_pipeline` for why building it unconditionally
    /// is not free.
    pub fn new_split(
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        capacity: usize,
        label: &str,
    ) -> Self {
        Self::build(device, surface_format, capacity, label, true, 0)
    }

    /// [`new_with_arcs`](Self::new_with_arcs), plus the OVER pipelines
    /// [`draw_opaque`](Self::draw_opaque) needs — the constructor the shared line
    /// renderer takes, because any of the four line systems may ask for the
    /// opacity-preserving seam (ADR-0138).
    ///
    /// The pipelines are built here rather than on the first preset that asks,
    /// deliberately: building a GPU resource mid-run changes what a later pass
    /// resolves to on the DX12 software adapter, which would make the seam's
    /// arrival visible in scenes that never selected it. (A WARP reading,
    /// unverified on lavapipe as of 2026-10-06.)
    pub fn new_split_with_arcs(
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        capacity: usize,
        arc_capacity: usize,
        label: &str,
    ) -> Self {
        Self::build(device, surface_format, capacity, label, true, arc_capacity)
    }

    /// [`new`](Self::new), plus the arc pipeline and an `arc_capacity`-instance
    /// arc buffer ([`ArcInstance`], ADR-0098).
    ///
    /// Only a scene that actually draws arcs should call this — see
    /// `arc_pipeline` for why building it unconditionally
    /// is not free. `arc_capacity` is its own budget rather than a share of
    /// `capacity`: an arc replaces many segments, so the two counts are not the
    /// same order and sizing one from the other would waste most of it.
    pub fn new_with_arcs(
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        capacity: usize,
        arc_capacity: usize,
        label: &str,
    ) -> Self {
        Self::build(device, surface_format, capacity, label, false, arc_capacity)
    }

    /// A renderer for **3D segments only** (ADR-0257): the `seg3d` pipeline and
    /// a `capacity`-instance buffer for it, drawn with `draw_3d`.
    ///
    /// Its 2D half is built empty — no segment capacity, no arcs, no OVER
    /// pipelines — so a 3D scene owns its renderer outright and the roster's
    /// shared 2D renderer creates exactly the resources it did before 3D existed.
    pub fn new_3d(
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        capacity: usize,
        label: &str,
    ) -> Self {
        let mut renderer = Self::build(device, surface_format, 0, label, false, 0);
        renderer.seg3d = Some(Seg3d::new(device, surface_format, capacity, label));
        renderer
    }

    fn build(
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        capacity: usize,
        label: &str,
        split: bool,
        arc_capacity: usize,
    ) -> Self {
        let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some(&format!("{label}-shader")),
            source: wgpu::ShaderSource::Wgsl(shader_source().into()),
        });
        let instances = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some(&format!("{label}-instances")),
            size: (capacity * std::mem::size_of::<SegmentInstance>()) as u64,
            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        let uniforms = gpu::uniform_buffer(
            device,
            &format!("{label}-uniforms"),
            std::mem::size_of::<Uniforms>(),
        );
        let bind_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some(&format!("{label}-bind-layout")),
            entries: &[wgpu::BindGroupLayoutEntry {
                binding: 0,
                visibility: wgpu::ShaderStages::VERTEX_FRAGMENT,
                ty: wgpu::BindingType::Buffer {
                    ty: wgpu::BufferBindingType::Uniform,
                    has_dynamic_offset: false,
                    min_binding_size: None,
                },
                count: None,
            }],
        });
        let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some(&format!("{label}-bind-group")),
            layout: &bind_layout,
            entries: &[wgpu::BindGroupEntry {
                binding: 0,
                resource: uniforms.as_entire_binding(),
            }],
        });
        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some(&format!("{label}-pipeline-layout")),
            bind_group_layouts: &[Some(&bind_layout)],
            immediate_size: 0,
        });
        // The two pipelines differ in exactly one field — the blend state — so
        // they are built from one closure. Anything else that diverges between
        // them would be a bug that renders as a difference between two ranges of
        // the same batch, which is close to unreadable in a capture.
        let make = |blend: wgpu::BlendState, suffix: &str| {
            device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                label: Some(&format!("{label}-pipeline{suffix}")),
                layout: Some(&pipeline_layout),
                vertex: wgpu::VertexState {
                    module: &shader,
                    entry_point: Some("vs_main"),
                    compilation_options: Default::default(),
                    buffers: &[Some(wgpu::VertexBufferLayout {
                        array_stride: std::mem::size_of::<SegmentInstance>() as u64,
                        step_mode: wgpu::VertexStepMode::Instance,
                        attributes: &wgpu::vertex_attr_array![
                            0 => Float32x2,
                            1 => Float32x2,
                            2 => Float32x3,
                            3 => Float32,
                            4 => Float32,
                            5 => Float32,
                            6 => Float32,
                        ],
                    })],
                },
                fragment: Some(wgpu::FragmentState {
                    module: &shader,
                    entry_point: Some("fs_main"),
                    compilation_options: Default::default(),
                    targets: &[Some(wgpu::ColorTargetState {
                        format: surface_format,
                        blend: Some(blend),
                        write_mask: wgpu::ColorWrites::ALL,
                    })],
                }),
                primitive: wgpu::PrimitiveState::default(),
                depth_stencil: None,
                multisample: wgpu::MultisampleState::default(),
                multiview_mask: None,
                cache: None,
            })
        };
        // Additive light, saturating coverage (ADR-0056) — the same constant the
        // swarm's sprite pipeline takes, so the two draw seams cannot drift
        // apart. This is what every line scene draws through.
        let pipeline = make(crate::render::gpu::ADDITIVE_LIGHT_SATURATING_COVERAGE, "");
        // Premultiplied OVER, for a producer whose source blend *replaces* rather
        // than accumulates — see `draw_split`. The fragment is premultiplied
        // either way, which is why one shader serves both.
        let over_pipeline =
            split.then(|| make(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING, "-over"));

        // The arc pipeline (ADR-0098). Its own shader module and vertex layout,
        // the *same* bind layout, bind group and pipeline layout as above, and
        // the same additive blend — so an arc and a segment emit into one pass
        // through one uniform and cannot drift apart on aspect, glow or the
        // view transform.
        let arcs = (arc_capacity > 0).then(|| {
            device.create_buffer(&wgpu::BufferDescriptor {
                label: Some(&format!("{label}-arc-instances")),
                size: (arc_capacity * std::mem::size_of::<ArcInstance>()) as u64,
                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            })
        });
        let arc_shader = arcs.is_some().then(|| {
            device.create_shader_module(wgpu::ShaderModuleDescriptor {
                label: Some(&format!("{label}-arc-shader")),
                source: wgpu::ShaderSource::Wgsl(arc_shader_source().into()),
            })
        });
        // The arc pair is built from one closure for the reason the segment pair
        // is: they differ in the blend state and in nothing else, and any other
        // divergence would render as a difference between two batches of the same
        // figure.
        let make_arc = |blend: wgpu::BlendState, suffix: &str| {
            let arc_shader = arc_shader.as_ref()?;
            Some(
                device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
                    label: Some(&format!("{label}-arc-pipeline{suffix}")),
                    layout: Some(&pipeline_layout),
                    vertex: wgpu::VertexState {
                        module: arc_shader,
                        entry_point: Some("vs_main"),
                        compilation_options: Default::default(),
                        buffers: &[Some(wgpu::VertexBufferLayout {
                            array_stride: std::mem::size_of::<ArcInstance>() as u64,
                            step_mode: wgpu::VertexStepMode::Instance,
                            attributes: &wgpu::vertex_attr_array![
                                0 => Float32x2,
                                1 => Float32,
                                2 => Float32,
                                3 => Float32,
                                4 => Float32x3,
                                5 => Float32,
                            ],
                        })],
                    },
                    fragment: Some(wgpu::FragmentState {
                        module: arc_shader,
                        entry_point: Some("fs_main"),
                        compilation_options: Default::default(),
                        targets: &[Some(wgpu::ColorTargetState {
                            format: surface_format,
                            blend: Some(blend),
                            write_mask: wgpu::ColorWrites::ALL,
                        })],
                    }),
                    primitive: wgpu::PrimitiveState::default(),
                    depth_stencil: None,
                    multisample: wgpu::MultisampleState::default(),
                    multiview_mask: None,
                    cache: None,
                }),
            )
        };
        let arc_pipeline = make_arc(crate::render::gpu::ADDITIVE_LIGHT_SATURATING_COVERAGE, "");
        let arc_over_pipeline = split
            .then(|| make_arc(wgpu::BlendState::PREMULTIPLIED_ALPHA_BLENDING, "-over"))
            .flatten();

        // Zero unless the pipeline exists, so `draw_all` needs no second test:
        // a renderer without arcs clamps every arc batch to nothing.
        let arc_capacity = if arc_pipeline.is_some() {
            arc_capacity
        } else {
            0
        };

        Self {
            pipeline,
            over_pipeline,
            arc_pipeline,
            arc_over_pipeline,
            instances,
            arcs,
            uniforms,
            bind_group,
            capacity,
            arc_capacity,
            seg3d: None,
        }
    }

    /// Segments the instance buffer can hold — the scene clamps its geometry to
    /// this and surfaces any drop at load (ADR-0007 cap must never be silent).
    pub fn capacity(&self) -> usize {
        self.capacity
    }

    /// Arcs the arc buffer can hold — `0` when this renderer was not built with
    /// [`new_with_arcs`](Self::new_with_arcs), in which case
    /// [`draw_arcs`](Self::draw_arcs) draws none.
    pub fn arc_capacity(&self) -> usize {
        self.arc_capacity
    }

    /// Draw `segments` as thick glowing quads at the given `aspect` and `glow`
    /// multiplier, under the shared `xform` camera transform (zoom/pan, ADR-0018),
    /// **loading** over the engine backdrop rather than clearing (Plan 0018 Phase
    /// 3 — the background pass owns the clear). Segments beyond `capacity` are
    /// dropped defensively (the scene is responsible for capping at load).
    ///
    /// `softness` is the across-the-stroke profile (`PROFILE_WGSL`, ADR-0124):
    /// `1.0` is the pre-Plan-0114 quadratic falloff, `0` a solid stroke with a
    /// one-pixel edge. **There is no default here** — one uniform serves every
    /// entry point, so each caller names the constant it answers to:
    /// [`lines::DEFAULT_SOFTNESS`](super::DEFAULT_SOFTNESS) for the four line
    /// families, [`warp_mesh::MILKDROP_SOFTNESS`](crate::render::scenes::warp_mesh::MILKDROP_SOFTNESS)
    /// for the MilkDrop surface.
    ///
    /// `metric` is the space the stroke is measured in (ADR-0160) and has no
    /// default either, for the same reason: [`StrokeMetric::World`] for the four
    /// line families, [`StrokeMetric::Clip`] for `warp_mesh`.
    #[allow(
        clippy::too_many_arguments,
        reason = "distinct GPU handles plus the per-frame draw parameters (aspect, glow, \
                  softness, stroke metric, view transform); bundling them would only shuffle \
                  the same values behind a one-use struct"
    )]
    pub fn draw(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
        glow: f32,
        softness: f32,
        metric: StrokeMetric,
        xform: super::ViewTransform,
        segments: &[SegmentInstance],
    ) {
        self.draw_split(
            queue,
            encoder,
            view,
            aspect,
            glow,
            softness,
            metric,
            xform,
            segments,
            segments.len(),
        );
    }

    /// [`draw`](Self::draw), with the batch split by blend mode: the first
    /// `n_additive` segments are added (ADR-0056's seam, what every line scene
    /// uses), and the rest are composited **over** using each segment's own
    /// [`alpha`](SegmentInstance::alpha).
    ///
    /// # Why a split range rather than two calls
    ///
    /// One instance buffer, one upload, one render pass, two `draw` calls that
    /// differ only in the pipeline bound. Two calls would mean two passes over
    /// the same attachment and a second buffer, and the *order* would stop being
    /// expressible: an over-blended stroke has to land on top of the additive
    /// light it covers, which a single ordered batch gives for free.
    ///
    /// The caller partitions — it is the only thing that knows which producer
    /// each segment came from. Passing `n_additive >= segments.len()` is exactly
    /// [`draw`](Self::draw).
    #[allow(
        clippy::too_many_arguments,
        reason = "see `draw` — this is that signature plus the partition index"
    )]
    pub fn draw_split(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
        glow: f32,
        softness: f32,
        metric: StrokeMetric,
        xform: super::ViewTransform,
        segments: &[SegmentInstance],
        n_additive: usize,
    ) {
        self.draw_all(
            queue,
            encoder,
            view,
            aspect,
            glow,
            softness,
            metric,
            xform,
            segments,
            n_additive,
            &[],
            false,
        );
    }

    /// [`draw`](Self::draw), plus `arcs` — [`ArcInstance`]s stroked by the
    /// per-pixel distance field (ADR-0098) **in the same additive pass**, from
    /// the same uniform, after the segments.
    ///
    /// One pass rather than two for the reason [`draw_split`](Self::draw_split)
    /// gives: a second pass would mean a second load of the attachment and a
    /// second set of uniforms to keep in step. Additive blending is
    /// order-independent, so "after the segments" is a statement about the
    /// command stream and not about the picture.
    ///
    /// Arcs beyond [`arc_capacity`](Self::arc_capacity) are dropped defensively,
    /// exactly as segments beyond `capacity` are; a renderer built without the
    /// arc pipeline has a capacity of zero and draws none.
    #[allow(
        clippy::too_many_arguments,
        reason = "see `draw` — this is that signature plus the arc batch"
    )]
    pub fn draw_arcs(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
        glow: f32,
        softness: f32,
        metric: StrokeMetric,
        xform: super::ViewTransform,
        segments: &[SegmentInstance],
        arcs: &[ArcInstance],
    ) {
        self.draw_all(
            queue,
            encoder,
            view,
            aspect,
            glow,
            softness,
            metric,
            xform,
            segments,
            segments.len(),
            arcs,
            false,
        );
    }

    /// [`draw_arcs`](Self::draw_arcs), with the **whole batch composited over**
    /// rather than added — the opacity-preserving seam of ADR-0138's limited-ink
    /// class, reached by the four line systems through `stroke_blend`.
    ///
    /// Segments and arcs both take the OVER pipeline, so a scene whose figure is
    /// part strokes and part circles draws one substance rather than two. Order
    /// inside the batch becomes the order on screen: a later stroke replaces the
    /// interior of what it covers instead of summing with it, which is the whole
    /// property. Pass an empty `arcs` from a scene that draws none.
    ///
    /// A renderer built without the OVER pipelines falls back to the additive
    /// ones, exactly as [`draw_split`](Self::draw_split) does — the wrong blend
    /// rather than a panic, and unreachable in the shipped path, where the shared
    /// line renderer is built with them.
    #[allow(
        clippy::too_many_arguments,
        reason = "see `draw` — this is that signature plus the arc batch"
    )]
    pub fn draw_opaque(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
        glow: f32,
        softness: f32,
        metric: StrokeMetric,
        xform: super::ViewTransform,
        segments: &[SegmentInstance],
        arcs: &[ArcInstance],
    ) {
        self.draw_all(
            queue, encoder, view, aspect, glow, softness, metric, xform, segments, 0, arcs, true,
        );
    }

    /// 3D segments the `seg3d` buffer can hold — `0` when this renderer was not
    /// built with [`new_3d`](Self::new_3d).
    pub fn capacity_3d(&self) -> usize {
        self.seg3d.as_ref().map_or(0, |seg3d| seg3d.capacity)
    }

    /// Draw `segments` through the shared camera (ADR-0257), **loading** over
    /// the backdrop, in one pass of their own. Segments beyond
    /// [`capacity_3d`](Self::capacity_3d) are dropped defensively; a renderer
    /// without the pipeline draws none.
    ///
    /// Every endpoint must already be in front of the near plane: the scene
    /// clips on the CPU against the same view the uniform carries
    /// ([`CameraView::clip_near`](crate::render::camera::CameraView::clip_near)).
    ///
    /// `frame` is the camera block's whole frame, not only its uniform: the
    /// depth cues it carries (`fog`, `solid`) are the block's, so every system
    /// that splices the block draws them without naming them.
    ///
    /// **A solid frame** (ADR-0263) is drawn far to near and composited over:
    /// the segments are sorted by [`sort_far_to_near`] into scratch reserved
    /// at the buffer's capacity, so the sort allocates nothing, and the over
    /// pipeline paints each nearer stroke over what it covers. A glow frame
    /// uploads `segments` as they came, through the additive pipeline.
    #[allow(
        clippy::too_many_arguments,
        reason = "distinct GPU handles plus the per-frame camera and stroke values; bundling \
                  them would only shuffle the same values behind a one-use struct"
    )]
    pub(crate) fn draw_3d(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        frame: &crate::render::camera::CameraFrame,
        glow: f32,
        softness: f32,
        segments: &[Segment3dInstance],
    ) {
        self.draw_3d_on(queue, encoder, view, frame, glow, softness, None, segments);
    }

    /// [`draw_3d`](Self::draw_3d) for a **heightfield** standing on the plane
    /// `y = ground`: a [`skirt`](Segment3dInstance::skirt) instance fills down
    /// to that plane, and a solid frame orders its segments by their feet on
    /// it ([`sort_painter`]), so a near row hides a far one whatever either's
    /// height (ADR-0263).
    #[allow(
        clippy::too_many_arguments,
        reason = "see `draw_3d` — this is that signature plus the ground plane"
    )]
    pub(crate) fn draw_3d_terrain(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        frame: &crate::render::camera::CameraFrame,
        glow: f32,
        softness: f32,
        ground: f32,
        segments: &[Segment3dInstance],
    ) {
        self.draw_3d_on(
            queue,
            encoder,
            view,
            frame,
            glow,
            softness,
            Some(ground),
            segments,
        );
    }

    /// The one body behind [`draw_3d`](Self::draw_3d) and
    /// [`draw_3d_terrain`](Self::draw_3d_terrain). `ground: None` keys the
    /// solid sort at each midpoint and puts a stray skirt's foot at `y = 0`.
    #[allow(clippy::too_many_arguments, reason = "see `draw_3d_terrain`")]
    fn draw_3d_on(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        frame: &crate::render::camera::CameraFrame,
        glow: f32,
        softness: f32,
        ground: Option<f32>,
        segments: &[Segment3dInstance],
    ) {
        let mut pass = gpu::color_pass(encoder, "seg3d-pass", view, wgpu::LoadOp::Load);
        let Some(seg3d) = self.seg3d.as_mut() else {
            return;
        };
        let count = segments.len().min(seg3d.capacity);
        let drawn = segments.get(..count).unwrap_or(&[]);
        if drawn.is_empty() {
            return; // nothing to stroke; the backdrop shows through
        }
        if frame.solid {
            let (keys, sorted) = (&mut seg3d.keys, &mut seg3d.sorted);
            match ground {
                None => sort_far_to_near(&frame.view, drawn, keys, sorted),
                Some(_) => sort_painter(&frame.view, drawn, ground, keys, sorted),
            }
            queue.write_buffer(&seg3d.instances, 0, bytemuck::cast_slice(&seg3d.sorted));
        } else {
            queue.write_buffer(&seg3d.instances, 0, bytemuck::cast_slice(drawn));
        }
        queue.write_buffer(&seg3d.camera, 0, bytemuck::bytes_of(&frame.uniform));
        queue.write_buffer(
            &seg3d.stroke,
            0,
            bytemuck::bytes_of(&Stroke3dUniform {
                v: [glow, softness, frame.fog, ground.unwrap_or(0.0)],
            }),
        );
        pass.set_pipeline(if frame.solid {
            &seg3d.over_pipeline
        } else {
            &seg3d.pipeline
        });
        pass.set_bind_group(0, &seg3d.bind_group, &[]);
        pass.set_vertex_buffer(0, seg3d.instances.slice(..));
        pass.draw(0..6, 0..count as u32);
    }

    /// The one body behind [`draw`](Self::draw),
    /// [`draw_split`](Self::draw_split), [`draw_arcs`](Self::draw_arcs) and
    /// [`draw_opaque`](Self::draw_opaque): one buffer upload per kind, one
    /// uniform write, one render pass.
    #[allow(
        clippy::too_many_arguments,
        reason = "see `draw` — this is that signature plus the partition index, \
                  the arc batch and the arc batch's own seam"
    )]
    fn draw_all(
        &mut self,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        view: &wgpu::TextureView,
        aspect: f32,
        glow: f32,
        softness: f32,
        metric: StrokeMetric,
        xform: super::ViewTransform,
        segments: &[SegmentInstance],
        n_additive: usize,
        arcs: &[ArcInstance],
        arcs_over: bool,
    ) {
        let count = segments.len().min(self.capacity);
        let drawn = segments.get(..count).unwrap_or(&[]);
        let arc_count = arcs.len().min(self.arc_capacity);
        let arcs_drawn = arcs.get(..arc_count).unwrap_or(&[]);

        // The in-frame geometry diagnostic (Plan 0069, ADR-0083). Off in the
        // shipped path, and it reads `drawn` — the segments that actually reach
        // the instance buffer — without touching a GPU resource, so "off" is a
        // `Cell::get` and "on" changes nothing about the picture. The aspect it
        // measures against is the one this call was handed: the render target's
        // (ADR-0037), under the same `max(0.1)` clamp the uniform and the shader
        // apply, so the rectangle is the one the frame actually shows.
        if metrics::extent_diagnostic_on() {
            let extent = measure_extent(drawn, arcs_drawn, aspect.max(0.1), xform);
            metrics::record_draw_extent(extent);
        }

        if !drawn.is_empty() {
            queue.write_buffer(&self.instances, 0, bytemuck::cast_slice(drawn));
        }
        if let (Some(buffer), false) = (&self.arcs, arcs_drawn.is_empty()) {
            queue.write_buffer(buffer, 0, bytemuck::cast_slice(arcs_drawn));
        }
        queue.write_buffer(
            &self.uniforms,
            0,
            bytemuck::bytes_of(&Uniforms {
                v: [aspect.max(0.1), glow, softness, metric.lane()],
                view: [xform.zoom, xform.pan[0], xform.pan[1], 0.0],
            }),
        );

        // Load over the engine backdrop (ADR-0018); additive strokes bloom over
        // it and the empty space reveals it.
        let mut pass = gpu::color_pass(encoder, "line-pass", view, wgpu::LoadOp::Load);
        if drawn.is_empty() && arcs_drawn.is_empty() {
            return; // nothing to stroke; the backdrop shows through
        }
        // Clamped to what actually reached the buffer: `n_additive` counts into
        // `segments`, which may be longer than `drawn`.
        let split = n_additive.min(drawn.len()) as u32;
        pass.set_bind_group(0, &self.bind_group, &[]);
        if split > 0 {
            pass.set_pipeline(&self.pipeline);
            pass.set_vertex_buffer(0, self.instances.slice(..));
            pass.draw(0..6, 0..split);
        }
        // Between the two segment ranges rather than after both: an arc is
        // additive light, and the OVER range has to land on top of the light it
        // covers. No scene draws both today; the ordering is here so that the
        // day one does, it is already right.
        let arc_pipeline = if arcs_over {
            self.arc_over_pipeline
                .as_ref()
                .or(self.arc_pipeline.as_ref())
        } else {
            self.arc_pipeline.as_ref()
        };
        if let (Some(pipeline), Some(buffer), false) =
            (arc_pipeline, &self.arcs, arcs_drawn.is_empty())
        {
            pass.set_pipeline(pipeline);
            pass.set_vertex_buffer(0, buffer.slice(..));
            pass.draw(0..6, 0..arcs_drawn.len() as u32);
        }
        if (drawn.len() as u32) > split {
            // Falls back to the additive pipeline when the scene did not ask for
            // the second one. That is the wrong blend rather than a panic, and it
            // is unreachable in practice: the only caller that passes a partition
            // is the one that built with `new_split`.
            pass.set_pipeline(self.over_pipeline.as_ref().unwrap_or(&self.pipeline));
            pass.set_vertex_buffer(0, self.instances.slice(..));
            pass.draw(0..6, split..drawn.len() as u32);
        }
    }
}

#[cfg(test)]
mod tests;