Struct Preset 

pub struct Preset {

    pub name: String,
    pub system: SystemKind,
    pub source: Option<PathBuf>,
    pub params: Vec<Binding>,
    pub per_vertex: Vec<Binding>,
    pub latches: Vec<Latch>,
    pub config: Option<GeneratorConfig>,
    pub palette: Option<PaletteConfig>,
    pub feedback: FeedbackConfig,
    pub palette_b: Option<PaletteConfig>,
    pub salt: u32,
    pub pinned_salt: u32,
    pub occupancy_exempt: Vec<String>,
    pub representative: bool,
    pub layer: Option<Layer>,
    pub warnings: Vec<String>,
}

A loaded, ready-to-evaluate preset.

Fields

name: String

Human-readable name (defaults to the system name if omitted).

system: SystemKind

Which built-in system this preset drives.

source: Option<PathBuf>

The absolute path this preset was read from, when it came from a directory. None for the embedded set, which has no file on disk, and for anything compiled straight from a string.

Set by crate::preset::load_dir rather than here: from_toml_str is handed source text and has no way to know where it came from, and a caller that does know is the one that can say. A consumer that offers to edit a preset needs this to be able to distinguish “not editable” from “the write failed” (ADR-0184).

params: Vec<Binding>

Parameter bindings, sorted by name for deterministic iteration.

per_vertex: Vec<Binding>

The [per_vertex] table’s bindings (Plan 0100 Phase 1): the warp mesh’s per-vertex program, evaluated once per mesh vertex per frame with x/y/rad/ang bound to that vertex’s position.

A separate table rather than a naming convention inside [params], because the cost is categorically different: one of these is N evaluations where an ordinary binding is one, and an author has to be able to see which of their bindings they are paying N for. Empty for every system but the warp mesh, and for a warp-mesh preset that accepts the identity transform.

Never eased: like a per-element binding, a per-vertex one has no single value for the smoother to hold. A [smoothing] entry naming one is a load warning.

latches: Vec<Latch>

The [latch] table’s entries (ADR-0137), in slot order — the one part of the preset surface whose value depends on frame history.

Empty for a preset declaring no table, which is the overwhelmingly common case and costs exactly what it cost before latches existed: the render layer’s bank advances nothing and every reserved slot stays at its rest value of 0.0.

config: Option<GeneratorConfig>

Declarative structural config for a line scene (ADR-0007), applied once at preset load via Scene::configure. None for the fragment/swarm systems and for curve presets that accept the family default.

palette: Option<PaletteConfig>

Optional color palette selection (ADR-0021 / Plan 0020), from a [palette] table — a built-in name or custom stops, validated and baked-ready at this boundary. None means the default spectrum (the exact current cosine), so a preset without [palette] is visually unchanged. The renderer bakes it into a LUT and hands it to the active scene via Scene::set_palette on each preset switch.

feedback: FeedbackConfig

The [feedback] structural table (ADR-0048): which curated warp the accumulation buffers resample their past through, and how this frame’s light is deposited onto it.

Not an Option: the absent table and the all-defaults table mean the same thing, and a plain value is what lets the renderer hand it over on every preset switch — so the outgoing preset’s warp can never survive into the incoming one. Load-time by [curve] family’s reasoning; the strength that rides on it is the bindable fb_warp.

palette_b: Option<PaletteConfig>

Optional second palette (ADR-0021 / Plan 0020 Phase 4), from a [palette_b] table. When present, the renderer bakes an A/B pair and a bindable palette_mix param crossfades between them per frame. None means no crossfade (palette A only).

salt: u32

The salt this preset’s hash()/noise() calls mix into their argument in the live app (ADR-0051): folded at load from the [generator] seed key (Plan 0010 reserved it, Plan 0047 gave it meaning), or drawn once from OS entropy where the preset declares seed = "random". 0 when it declares nothing — a perfectly good salt, and the one the whole shipped library used before any preset asked for another.

A load-time constant. Nothing per-frame recomputes it, and no expression can read it except through the two functions it salts.

pinned_salt: u32

The salt every capture path uses in place of salt: the declared number, or 0 for seed = "random".

Equal to salt unless the preset opted into per-run variety — the whole point of the pair (ADR-0051, following ADR-0045’s tier pinning). The live app varies and the harness pins, so shot, the goldens, --report and the behavioral gates stay pure functions of their inputs while a preset can still be different every time the user starts the app.

It is the renderer that chooses between the two, not the loader, and deliberately: default_presets() feeds both the live C-ABI path and the capture gates, so a decision taken at load would be wrong for one of them.

occupancy_exempt: Vec<String>

Parameters whose clamp() bounds are meant to pin, from an [occupancy] exempt = [...] table (ADR-0062). Sorted and deduplicated at load.

A safety rail exists to bind at peak, and the saturation gate would otherwise convict it of the defect it was written to prevent. The exemption silences core/tests/saturation.rs, and only that: the binding still appears in --report’s occ count and SAT lines, because an exemption is a place to hide and the one mitigation available is that it stays visible.

A preset-level table naming params rather than a per-expression annotation, deliberately: the grammar stays a pure expression language (ADR-0020), and this is metadata about a binding rather than part of it. Harness-only — nothing per-frame reads it.

representative: bool

Whether this preset is one of its family’s representatives — the sample the dev lane’s per-phase test tier renders (ADR-0157).

Absent means false. Harness-only, like occupancy_exempt: nothing per-frame reads it, and it changes nothing about how the preset looks or what the close and CI render, which is the whole library either way. It is declared, not derived — a first-N or hash-rotation rule would either never sample a newly landed preset or make the same tree gate differently on different commits.

A floor is enforced in core/tests/preset.rs: every family carries at least two. That catches a sample decayed to nothing; it cannot catch two representatives that have stopped representing a family that grew around them, which is a curation duty with no gate behind it.

layer: Option<Layer>

The optional second scene layer (ADR-0090 / Plan 0076), from a [layer] table. None — the overwhelmingly common case — takes exactly the code path a preset took before layers existed: no new pass, no new target.

warnings: Vec<String>

Non-fatal problems found while loading — today, bindings naming a parameter this system does not consume (ADR-0020). The preset loaded and its good bindings apply; these are surfaced so a typo stops failing silently. Empty for a clean preset. Load-time only — never read per frame.

Implementations

impl Preset

pub fn from_toml_str(src: &str) -> Result<Self, PresetError>

Parse and compile a preset from a TOML source string.

Trait Implementations

impl Debug for Preset

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.