Struct PresetStore 

pub struct PresetStore { /* private fields */ }

One plugin’s preset library across all three scopes, with the management operations layered on top of the discovery walk.

enumerate applies the identity rule: two presets with the same uuid in different scopes are the same logical preset, and the more user-proximate copy wins (User over Pack over Factory) so a user “override” of a factory preset shows once, not twice. Mutations only ever touch the user scope.

Implementations

impl PresetStore

pub fn new( vendor: &str, plugin_name: &str, plugin_id_hash: u64, user_dir: Option<&str>, ) -> PresetStore

A store for the given plugin identity. The user root resolves from the per-OS environment, honouring the optional [plugin.presets] user_dir override (see user_preset_root for where the path lands per OS); the factory root (inside the installed bundle) is format-specific, so callers that have one add it via Self::with_factory_root.

pub fn with_factory_root(self, root: impl Into<PathBuf>) -> PresetStore

pub fn with_user_root(self, root: impl Into<PathBuf>) -> PresetStore

Override the user root (tests, tools operating on a staged library).

pub fn user_root(&self) -> Option<&Path>

pub fn enumerate(&self) -> Vec<PresetRef>

Every preset across factory, user, and pack scopes, deduped by uuid (User wins over Pack wins over Factory), ordered factory-first then by category / name within each scope.

User / pack files that arrived without a uuid (hand-assembled packs, pre-tool files) get one minted and written back on first read, so their identity is stable from then on; write-back failures degrade to an empty uuid rather than hiding the preset.

pub fn find(&self, sel: &str) -> Option<PresetRef>

Resolve a preset by truce-preset:// URI, bare uuid, or display name. A URI for a different vendor / plugin returns None. Name matching is a fallback after uuid (names are unique per category by library validation; on a cross-category name clash the first in enumeration order wins).

pub fn load(&self, uri_or_uuid: &str) -> Result<DeserializedState, PresetError>

Load a preset’s state, validating it against this plugin’s identity hash.

Errors

PresetError::NotFound for an unknown URI; PresetError::InvalidState when the file’s envelope doesn’t parse or belongs to a different plugin.

pub fn save( &self, meta: PresetMeta, params: &[(u32, f64)], extra: &[u8], ) -> Result<PresetRef, PresetError>

Save a preset into the user scope.

A user preset with the same (category, name) is overwritten in place, keeping its uuid - the natural “Save” gesture. Otherwise a new file is created with a minted uuid (or meta.uuid when the caller pre-assigned one). meta.name is the display name; the file lands at <user root>/<category>/<name>.trucepreset.

Errors

PresetError::NoUserDirectory when the per-OS root can’t be resolved, PresetError::InvalidName for a name that sanitizes to nothing, PresetError::Io on write failure.

pub fn rename( &self, uri_or_uuid: &str, new_name: &str, ) -> Result<(), PresetError>

Rename a user preset’s display name. The uuid (and therefore the URI and any host-side reference) is unchanged; the file keeps its on-disk name.

Errors

PresetError::NotFound, PresetError::ReadOnlyScope for factory / pack presets, PresetError::InvalidState for a file that no longer parses, PresetError::Io.

pub fn recategorise( &self, uri_or_uuid: &str, new_category: &str, ) -> Result<(), PresetError>

Move a user preset to a different category. Rewrites the explicit category metadata and moves the file into the matching directory so the on-disk layout stays readable. The uuid is unchanged.

Errors

Same surface as Self::rename, plus PresetError::NoUserDirectory.

pub fn delete(&self, uri_or_uuid: &str) -> Result<(), PresetError>

Delete a user preset.

Errors

PresetError::NotFound, PresetError::ReadOnlyScope for factory / pack presets, PresetError::Io.