GitCorner

Code

ossartcraftfilmcraft🌐
f67d38b35cc5
//! Effect presets (Premiere's Presets bin): one or more configured effects — parameters,
//! keyframes and masks — saved under a name and applied to clips.
//!
//! - **Keyframes.** Times are stored relative to the in point of the clip the preset was saved
//!   from, with that clip's length (`source_duration`, media ticks). Applying re-times them per
//!   [`KeyframeMode`]: *Scale* stretches them over the target clip, *Anchor to In Point* keeps their
//!   distance from the target's in point, *Anchor to Out Point* their distance from its out point.
//!   Saving with `keyframes: "none"` stores every parameter as its value at the playhead.
//! - **Geometry.** Point parameters and mask paths are in clip pixels; they are scaled by the
//!   target / source frame-size ratio so a preset made on 4K media lands in the same place on HD.
//! - **Intrinsic effects** (Motion, Opacity, Time Remapping) replace the target clip's own instance;
//!   standard effects are added at the end of the clip's effects, like `effects.apply`.
//! - **Library.** Built-in presets are authored in code ([`builtin_presets`]); user presets persist
//!   in `<data dir>/effect-presets.json`. Preset files (export/import) are JSON:
//!   `{"format": "filmcraft.effect-presets", "version": 1, "presets": [EffectPreset…]}`.
//!
//! Commands: `presets.list`, `presets.save`, `presets.apply` (undoable), `presets.delete`,
//! `presets.rename`, `presets.export`, `presets.import`.

use std::collections::BTreeMap;
use std::path::{Path, PathBuf};

use filmcraft_geom::{Affine, Vec2};
use filmcraft_project::{ClipId, EffectInstance, Keyframe, Mask, MaskPath, Param, ParamValue, TrackItem, TrackKind};
use filmcraft_time::{TICKS_PER_SECOND, Tick};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};

use crate::commands::{CommandSpec, always, bad, clip_p, has_seq, str_p};
use crate::{EngineError, Result, Session};

pub const FILE_FORMAT: &str = "filmcraft.effect-presets";
const LIBRARY_FILE: &str = "effect-presets.json";
/// Premiere `.prfpset` (and FilmCraft `.json`) files dropped in this folder are detected and
/// loaded automatically on start-up (and by `presets.scan`).
pub const LIBRARY_DIR: &str = "Effect Presets";
const LIBRARY_INDEX: &str = "effect-preset-library.json";

/// How a preset's keyframes are placed on the target clip.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum KeyframeMode {
    #[default]
    Scale,
    AnchorToIn,
    AnchorToOut,
}

impl KeyframeMode {
    pub fn from_name(s: &str) -> Option<Self> {
        match s.to_ascii_lowercase().replace([' ', '_', '-'], "").as_str() {
            "scale" => Some(KeyframeMode::Scale),
            "anchorin" | "anchortoin" | "anchortoinpoint" | "in" => Some(KeyframeMode::AnchorToIn),
            "anchorout" | "anchortoout" | "anchortooutpoint" | "out" => Some(KeyframeMode::AnchorToOut),
            _ => None,
        }
    }
    pub fn label(self) -> &'static str {
        match self {
            KeyframeMode::Scale => "Scale",
            KeyframeMode::AnchorToIn => "Anchor to In Point",
            KeyframeMode::AnchorToOut => "Anchor to Out Point",
        }
    }
}

/// A saved effect preset.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct EffectPreset {
    pub name: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub description: String,
    #[serde(default)]
    pub keyframes: KeyframeMode,
    /// Length (media ticks) of the clip the preset was saved from; keyframe times are relative to its in point.
    pub source_duration: Tick,
    /// Frame size (clip pixels) of the clip the preset was saved from.
    #[serde(default = "hd")]
    pub source_size: (u32, u32),
    pub effects: Vec<EffectInstance>,
    /// Built-in (not saved, cannot be deleted).
    #[serde(skip)]
    pub builtin: bool,
}

/// Default 1080p HD dimensions.
fn hd() -> (u32, u32) {
    (1920, 1080)
}

#[derive(Serialize, Deserialize)]
struct PresetFile {
    format: String,
    version: u32,
    presets: Vec<EffectPreset>,
}

/// One preset file loaded by the native library scan.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
struct LibraryFile {
    /// Modification time (nanoseconds since the epoch) and length: cheap change detection.
    stamp: String,
    /// The (unique) preset names this file contributed, so a changed or removed file can be
    /// replaced without touching presets the user saved or imported by hand.
    names: Vec<String>,
}

#[derive(Serialize, Deserialize)]
struct LibraryIndexFile {
    format: String,
    version: u32,
    files: BTreeMap<String, LibraryFile>,
}

const LIBRARY_INDEX_FORMAT: &str = "filmcraft.effect-preset-library";

/// What one library scan did.
#[derive(Clone, Debug, Default)]
pub struct ScanReport {
    pub files: usize,
    /// Presets added or refreshed (including re-imports of changed files).
    pub imported: usize,
    /// Library presets removed because their file disappeared or changed.
    pub removed: usize,
    /// Presets inside those files that FilmCraft cannot apply (third-party plugins).
    pub skipped: usize,
    /// Presets that apply but dropped parameters the built-in effect does not expose.
    pub warnings: usize,
    /// The loaded preset list or the file index changed.
    pub changed: bool,
    pub errors: Vec<String>,
}

impl ScanReport {
    pub fn json(&self) -> Value {
        json!({
            "files": self.files,
            "imported": self.imported,
            "removed": self.removed,
            "skipped": self.skipped,
            "warnings": self.warnings,
            "changed": self.changed,
            "errors": self.errors,
        })
    }
}

/// User presets (+ where they persist) and the file-backed preset library.
#[derive(Default)]
pub struct PresetLibrary {
    pub user: Vec<EffectPreset>,
    dir: Option<PathBuf>,
    /// Files under `<data dir>/Effect Presets` and the presets each contributed.
    library: BTreeMap<String, LibraryFile>,
    user_load_failed: bool,
}

impl PresetLibrary {
    /// Persist user presets in `data_dir`, load them, and detect the preset library
    /// (`<data dir>/Effect Presets`, scanned recursively for `.prfpset` and FilmCraft `.json`).
    pub fn set_dir(&mut self, data_dir: &Path) {
        self.dir = Some(data_dir.to_path_buf());
        let path = data_dir.join(LIBRARY_FILE);
        if let Ok(bytes) = std::fs::read(&path) {
            match parse_file(&bytes) {
                Ok(p) => self.user = p,
                Err(e) => {
                    log::warn!("{}: {e}", path.display());
                    let mut backup = path.with_extension("json.unreadable");
                    let mut n = 1u32;
                    while backup.exists() {
                        backup = path.with_extension(format!("json.unreadable.{n}"));
                        n += 1;
                    }
                    if let Err(e) = std::fs::rename(&path, &backup) {
                        log::warn!("{}: {e}", backup.display());
                        self.user_load_failed = true;
                    }
                }
            }
        }
        let index_path = data_dir.join(LIBRARY_INDEX);
        if let Ok(bytes) = std::fs::read(&index_path) {
            match serde_json::from_slice::<LibraryIndexFile>(&bytes) {
                Ok(f) if f.format == LIBRARY_INDEX_FORMAT && f.version <= 1 => self.library = f.files,
                Ok(_) => log::warn!("{}: unsupported preset library index", index_path.display()),
                Err(e) => log::warn!("{}: {e}", index_path.display()),
            }
        }
        let report = self.scan_library();
        // Only rewrite the (possibly multi-megabyte) user file when the library actually
        // contributed or removed presets; a plain start-up must not touch it.
        if (report.imported > 0 || report.removed > 0)
            && let Err(e) = self.persist()
        {
            log::warn!("{e}");
        }
        if report.changed
            && let Err(e) = self.persist_index()
        {
            log::warn!("{e}");
        }
        for e in report.errors {
            log::warn!("{e}");
        }
    }

    /// Re-scan the preset library now (`presets.scan`; the Effects panel also does this when its
    /// Presets folder is opened).
    pub fn rescan(&mut self) -> ScanReport {
        let report = self.scan_library();
        let mut errors = report.errors.clone();
        if (report.imported > 0 || report.removed > 0)
            && let Err(e) = self.persist()
        {
            errors.push(e);
        }
        if report.changed
            && let Err(e) = self.persist_index()
        {
            errors.push(e);
        }
        ScanReport { errors, ..report }
    }

    fn persist(&self) -> std::result::Result<(), String> {
        if self.user_load_failed {
            return Err("refusing to persist presets while user file failed to load (preserved on disk)".into());
        }
        let Some(d) = &self.dir else { return Ok(()) };
        let _ = std::fs::create_dir_all(d);
        let bytes = file_bytes(&self.user);
        filmcraft_format::atomic_write(&d.join(LIBRARY_FILE), &bytes).map_err(|e| e.to_string())
    }

    fn persist_index(&self) -> std::result::Result<(), String> {
        let Some(d) = &self.dir else { return Ok(()) };
        let _ = std::fs::create_dir_all(d);
        let f = LibraryIndexFile { format: LIBRARY_INDEX_FORMAT.into(), version: 1, files: self.library.clone() };
        let bytes = serde_json::to_vec_pretty(&f).map_err(|e| e.to_string())?;
        filmcraft_format::atomic_write(&d.join(LIBRARY_INDEX), &bytes).map_err(|e| e.to_string())
    }

    /// The preset library folder, creating it so users can drop files into it.
    pub fn library_dir(&self) -> Option<PathBuf> {
        let d = self.dir.as_ref()?.join(LIBRARY_DIR);
        let _ = std::fs::create_dir_all(&d);
        Some(d)
    }

    /// The file a library preset came from (None for built-in and hand-imported presets).
    pub fn source_of(&self, name: &str) -> Option<&str> {
        self.library.iter().find(|(_, f)| f.names.iter().any(|n| n == name)).map(|(path, _)| path.as_str())
    }

    pub fn is_library_preset(&self, name: &str) -> bool {
        self.source_of(name).is_some()
    }

    /// Scan `<data dir>/Effect Presets` recursively. Unchanged files with all their presets still
    /// loaded are skipped; changed files replace exactly the presets they contributed; files that
    /// disappeared take their presets with them.
    fn scan_library(&mut self) -> ScanReport {
        let mut report = ScanReport::default();
        let Some(dir) = self.library_dir() else { return report };
        let mut files = Vec::new();
        let mut unreadable = Vec::new();
        collect_preset_files(&dir, 0, &mut files, &mut unreadable);
        for u in &unreadable {
            report.errors.push(format!("{}: cannot read directory", u.display()));
        }
        files.sort();
        report.files = files.len();

        let mut seen: BTreeMap<String, LibraryFile> = BTreeMap::new();
        for path in files {
            let Some(key) = path.to_str().map(str::to_string) else { continue };
            let Some(stamp) = file_stamp(&path) else {
                report.errors.push(format!("{}: cannot read file information", path.display()));
                if let Some(old) = self.library.get(&key) {
                    seen.insert(key, old.clone());
                }
                continue;
            };
            if let Some(old) = self.library.get(&key)
                && old.stamp == stamp
                && old.names.iter().all(|n| self.user.iter().any(|p| p.name == *n))
            {
                seen.insert(key, old.clone());
                continue;
            }
            if std::fs::metadata(&path).map(|m| m.len() > crate::prfpset::MAX_BYTES).unwrap_or(false) {
                report.errors.push(format!("{}: file is too large for a preset", path.display()));
                if let Some(old) = self.library.get(&key) {
                    seen.insert(key, old.clone());
                }
                continue;
            }
            let bytes = match std::fs::read(&path) {
                Ok(b) => b,
                Err(e) => {
                    // Keep the old entry: a temporarily unreadable file should not delete presets.
                    report.errors.push(format!("{}: {e}", path.display()));
                    if let Some(old) = self.library.get(&key) {
                        seen.insert(key, old.clone());
                    }
                    continue;
                }
            };
            if bytes.len() as u64 > crate::prfpset::MAX_BYTES {
                report.errors.push(format!("{}: file is too large for a preset", path.display()));
                if let Some(old) = self.library.get(&key) {
                    seen.insert(key, old.clone());
                }
                continue;
            }
            let parsed = match parse_file_detailed(&bytes) {
                Ok(p) => p,
                Err(e) => {
                    report.errors.push(format!("{}: {e}", path.display()));
                    if let Some(old) = self.library.get(&key) {
                        seen.insert(key, old.clone());
                    }
                    continue;
                }
            };
            if let Some(old) = self.library.get(&key) {
                for name in &old.names {
                    let before = self.user.len();
                    self.user.retain(|p| p.name != *name);
                    if self.user.len() < before {
                        report.removed += 1;
                    }
                }
            }
            let mut names = Vec::new();
            report.warnings += parsed.warnings.len();
            for preset in parsed.presets {
                let name = unique_preset_name(&self.user, &preset.name);
                let mut preset = preset;
                preset.name = name.clone();
                names.push(name);
                self.user.push(preset);
            }
            report.imported += names.len();
            report.skipped += parsed.skipped.len();
            if names.is_empty() && !parsed.skipped.is_empty() {
                report.errors.push(format!(
                    "{}: no supported effects ({} preset{} skipped)",
                    path.display(),
                    parsed.skipped.len(),
                    if parsed.skipped.len() == 1 { "" } else { "s" }
                ));
            }
            seen.insert(key, LibraryFile { stamp, names });
        }

        for (key, file) in &self.library {
            if !seen.contains_key(key) && unreadable.iter().any(|u| Path::new(key).starts_with(u)) {
                seen.insert(key.clone(), file.clone());
            }
        }
        let missing: Vec<String> = self.library.keys().filter(|k| !seen.contains_key(*k)).cloned().collect();
        for key in missing {
            if let Some(old) = self.library.remove(&key) {
                report.changed = true;
                for name in old.names {
                    let before = self.user.len();
                    self.user.retain(|p| p.name != name);
                    if self.user.len() < before {
                        report.removed += 1;
                    }
                }
            }
        }
        if self.library != seen {
            report.changed = true;
        }
        self.library = seen;
        report
    }

    /// Built-in and user presets (user presets shadow built-ins of the same name).
    pub fn all(&self) -> Vec<EffectPreset> {
        let mut v: Vec<EffectPreset> = builtin_presets().into_iter().filter(|b| !self.user.iter().any(|u| u.name == b.name)).collect();
        v.extend(self.user.iter().cloned());
        v
    }
    pub fn find(&self, name: &str) -> Option<EffectPreset> {
        let needle = name.trim();
        // 1. Exact match in user presets or built-in presets
        if let Some(p) = self.user.iter().find(|p| p.name == needle) {
            return Some(p.clone());
        }
        if let Some(b) = builtin_presets().into_iter().find(|p| p.name == needle) {
            return Some(b);
        }

        // 2. Case-insensitive exact match
        if let Some(p) = self.user.iter().find(|p| p.name.eq_ignore_ascii_case(needle)) {
            return Some(p.clone());
        }
        if let Some(b) = builtin_presets().into_iter().find(|p| p.name.eq_ignore_ascii_case(needle)) {
            return Some(b);
        }

        // Helper to normalize path separators: replace "/", "\", "->" with " ▸ " and trim
        let normalize = |s: &str| -> String {
            s.replace(['/', '\\'], " ▸ ").replace("->", " ▸ ").split('▸').map(str::trim).filter(|seg| !seg.is_empty()).collect::<Vec<_>>().join(" ▸ ")
        };
        let norm_needle = normalize(needle);
        if norm_needle.is_empty() {
            return None;
        }

        // 3. Match normalized path
        if let Some(p) = self.user.iter().find(|p| normalize(&p.name).eq_ignore_ascii_case(&norm_needle)) {
            return Some(p.clone());
        }

        // 4. Match leaf name (e.g. "DROP SHADOW" or "Glow" or "LENS DISTORTION -25")
        if !norm_needle.contains('▸') {
            let leaf_hits: Vec<_> = self
                .user
                .iter()
                .filter(|p| {
                    let p_norm = normalize(&p.name);
                    p_norm.rsplit('▸').next().unwrap_or(&p_norm).trim().eq_ignore_ascii_case(&norm_needle)
                })
                .collect();
            if let [p] = leaf_hits.as_slice() {
                return Some((*p).clone());
            }
        }

        // 5. Unambiguous path-suffix match only (e.g. "EFFECTS ▸ DROP SHADOW")
        let n_norm = format!(" ▸ {}", norm_needle.to_ascii_lowercase());
        let hits: Vec<_> = self.user.iter().filter(|p| normalize(&p.name).to_ascii_lowercase().ends_with(&n_norm)).collect();
        if let [p] = hits.as_slice() {
            return Some((*p).clone());
        }

        None
    }
}

/// Ensure a preset name does not collide with existing presets by appending a counter.
fn unique_preset_name(existing: &[EffectPreset], base: &str) -> String {
    let base = base.trim();
    let base = if base.is_empty() { "Preset" } else { base };
    if !existing.iter().any(|p| p.name == base) {
        return base.to_string();
    }
    for n in 2..10_000u32 {
        let candidate = format!("{base} ({n})");
        if !existing.iter().any(|p| p.name == candidate) {
            return candidate;
        }
    }
    format!("{base} ({})", existing.len() + 2)
}

/// Compute a fingerprint based on file modification timestamp and size.
fn file_stamp(path: &Path) -> Option<String> {
    let md = std::fs::metadata(path).ok()?;
    let len = md.len();
    let mtime = md.modified().ok().and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0);
    Some(format!("{mtime}-{len}"))
}

/// Recursively discover preset files within a directory, collecting unreadable folders.
fn collect_preset_files(dir: &Path, depth: usize, out: &mut Vec<PathBuf>, unreadable: &mut Vec<PathBuf>) {
    if depth > 8 {
        return;
    }
    let Ok(entries) = std::fs::read_dir(dir) else {
        unreadable.push(dir.to_path_buf());
        return;
    };
    for entry in entries {
        let Ok(entry) = entry else {
            unreadable.push(dir.to_path_buf());
            continue;
        };
        let Ok(kind) = entry.file_type() else { continue };
        // Never follow links: a linked folder could point back up the tree.
        if kind.is_symlink() {
            continue;
        }
        let path = entry.path();
        if kind.is_dir() {
            collect_preset_files(&path, depth + 1, out, unreadable);
            continue;
        }
        if !kind.is_file() {
            continue;
        }
        let supported = path.extension().and_then(|e| e.to_str()).is_some_and(|e| e.eq_ignore_ascii_case("prfpset") || e.eq_ignore_ascii_case("json"));
        if supported {
            out.push(path);
        }
    }
}

/// Serialize a slice of effect presets into formatted JSON bytes.
fn file_bytes(presets: &[EffectPreset]) -> Vec<u8> {
    let f = PresetFile { format: FILE_FORMAT.into(), version: 1, presets: presets.to_vec() };
    serde_json::to_vec_pretty(&f).unwrap_or_default()
}

/// Whether `path` or `bytes` represents an effect preset file (Premiere `.prfpset` XML or FilmCraft JSON).
pub fn is_preset_file(path: &Path, bytes: &[u8]) -> bool {
    if path.extension().and_then(|e| e.to_str()).is_some_and(|e| e.eq_ignore_ascii_case("prfpset")) {
        return true;
    }
    let trimmed = bytes.strip_prefix(b"\xef\xbb\xbf").unwrap_or(bytes);
    let head = &trimmed[..trimmed.len().min(1024)];
    let s = match std::str::from_utf8(head) {
        Ok(s) => s,
        // A character cut by the 1024-byte window is not an encoding error.
        Err(e) if e.error_len().is_none() => std::str::from_utf8(&head[..e.valid_up_to()]).unwrap_or(""),
        Err(_) => return false,
    }
    .trim_start();
    if s.starts_with('<') && s.contains("<PremiereData") {
        return true;
    }
    if s.starts_with('{') && s.contains(FILE_FORMAT) {
        return true;
    }
    false
}

/// Read a preset file, detecting Premiere `.prfpset` XML and FilmCraft JSON by content (the
/// extension is not trusted). The XML path reports presets it had to skip and parameters the
/// target effects do not have.
pub fn parse_file_detailed(bytes: &[u8]) -> std::result::Result<crate::prfpset::PrfpsetImport, String> {
    if bytes.len() as u64 > crate::prfpset::MAX_BYTES {
        return Err(format!("preset file is too large ({} MB; the limit is {} MB)", bytes.len() / (1024 * 1024), crate::prfpset::MAX_BYTES / (1024 * 1024)));
    }
    let text = std::str::from_utf8(bytes).map_err(|_| "effect presets must be UTF-8 text".to_string())?;
    let text = text.strip_prefix('\u{feff}').unwrap_or(text);
    let trimmed = text.trim_start();
    if trimmed.starts_with('<') {
        if !trimmed.contains("<PremiereData") {
            return Err("not an effect preset file (unrecognised XML document)".into());
        }
        return crate::prfpset::parse_prfpset(text);
    }
    if !trimmed.starts_with('{') {
        return Err("not an effect preset file (expected Premiere XML or FilmCraft JSON)".into());
    }
    let f: PresetFile = serde_json::from_str(text).map_err(|e| format!("not an effect preset file: {e}"))?;
    if f.format != FILE_FORMAT {
        return Err(format!("not an effect preset file (format `{}`)", f.format));
    }
    if f.version > 1 {
        return Err(format!("preset file version {} is newer than this build reads (1)", f.version));
    }
    for p in &f.presets {
        if p.effects.iter().any(|e| e.def().is_none()) {
            return Err(format!("preset `{}` uses an effect this build doesn't have", p.name));
        }
    }
    Ok(crate::prfpset::PrfpsetImport { presets: f.presets, skipped: Vec::new(), warnings: Vec::new() })
}

/// Backwards-compatible form of [`parse_file_detailed`] for callers that only need the presets.
pub fn parse_file(bytes: &[u8]) -> std::result::Result<Vec<EffectPreset>, String> {
    Ok(parse_file_detailed(bytes)?.presets)
}

// ---------------------------------------------------------------- built-ins

/// Helper to construct a keyframe at seconds offset.
fn kf(t_secs: f64, v: ParamValue) -> Keyframe {
    Keyframe::new(Tick((t_secs * TICKS_PER_SECOND as f64).round() as i64), v)
}

/// A fresh instance of a built-in effect (a bare instance named `id` if the registry lacks it,
/// which the preset tests rule out).
pub(crate) fn effect_instance(id: &str) -> EffectInstance {
    filmcraft_project::find_effect(id).map(|d| d.instance()).unwrap_or_else(|| EffectInstance {
        effect: id.to_string(),
        enabled: true,
        params: Default::default(),
        masks: Vec::new(),
        post_fader: false,
        essential: false,
        layer: None,
    })
}

/// Construct an effect instance with initial parameter overrides.
fn effect(id: &str, params: &[(&str, ParamValue)]) -> EffectInstance {
    let mut e = effect_instance(id);
    for (k, v) in params {
        if let Some(p) = e.params.get_mut(*k) {
            p.value = v.clone();
        }
    }
    e
}

/// Apply animated keyframes to an effect parameter.
fn animate(e: &mut EffectInstance, param: &str, keys: Vec<Keyframe>) {
    if let Some(p) = e.params.get_mut(param) {
        p.value = keys[0].value.clone();
        p.keyframes = keys;
    }
}

/// Helper to build a built-in effect preset definition.
fn preset(name: &str, description: &str, keyframes: KeyframeMode, secs: f64, effects: Vec<EffectInstance>) -> EffectPreset {
    EffectPreset {
        name: name.into(),
        description: description.into(),
        keyframes,
        source_duration: Tick((secs * TICKS_PER_SECOND as f64) as i64),
        source_size: hd(),
        effects,
        builtin: true,
    }
}

/// Presets that ship with FilmCraft (original work: parameter values chosen by us).
pub fn builtin_presets() -> Vec<EffectPreset> {
    let f = ParamValue::Float;
    let mut blur_in = effect("gaussian_blur", &[]);
    animate(&mut blur_in, "blurriness", vec![kf(0.0, f(60.0)), kf(1.0, f(0.0))]);
    let mut blur_out = effect("gaussian_blur", &[]);
    animate(&mut blur_out, "blurriness", vec![kf(9.0, f(0.0)), kf(10.0, f(60.0))]);
    let mut fade_in = effect("opacity", &[]);
    animate(&mut fade_in, "opacity", vec![kf(0.0, f(0.0)), kf(1.0, f(100.0))]);
    let mut fade_out = effect("opacity", &[]);
    animate(&mut fade_out, "opacity", vec![kf(9.0, f(100.0)), kf(10.0, f(0.0))]);
    let mut mosaic_in = effect("mosaic", &[]);
    animate(&mut mosaic_in, "horizontal", vec![kf(0.0, f(8.0)), kf(1.0, f(400.0))]);
    animate(&mut mosaic_in, "vertical", vec![kf(0.0, f(5.0)), kf(1.0, f(225.0))]);
    // soft oval vignette: darken outside an inverted, heavily feathered ellipse
    let mut vignette = effect("brightness_contrast", &[("brightness", f(-60.0))]);
    let mut m = Mask::new("Mask (1)", MaskPath::ellipse(Vec2::new(960.0, 540.0), Vec2::new(900.0, 520.0)));
    m.inverted = true;
    m.feather.value = f(320.0);
    vignette.masks.push(m);
    let mut spotlight = effect("brightness_contrast", &[("brightness", f(18.0)), ("contrast", f(10.0))]);
    let mut m = Mask::new("Mask (1)", MaskPath::ellipse(Vec2::new(960.0, 540.0), Vec2::new(420.0, 420.0)));
    m.feather.value = f(160.0);
    spotlight.masks.push(m);
    let warm =
        effect("tint", &[("black", ParamValue::Color([0.08, 0.04, 0.02, 1.0])), ("white", ParamValue::Color([1.0, 0.93, 0.8, 1.0])), ("amount", f(35.0))]);
    let mut pip = effect("motion", &[("scale", f(35.0)), ("position", ParamValue::Vec2(Vec2::new(1530.0, 270.0)))]);
    pip.enabled = true;
    vec![
        preset("Blur In", "Gaussian Blur from 60 to 0 over the first second", KeyframeMode::AnchorToIn, 10.0, vec![blur_in]),
        preset("Blur Out", "Gaussian Blur from 0 to 60 over the last second", KeyframeMode::AnchorToOut, 10.0, vec![blur_out]),
        preset("Fade In", "Opacity 0 → 100 % over the first second", KeyframeMode::AnchorToIn, 10.0, vec![fade_in]),
        preset("Fade Out", "Opacity 100 → 0 % over the last second", KeyframeMode::AnchorToOut, 10.0, vec![fade_out]),
        preset("Mosaic In", "Large blocks resolving to the picture over the first second", KeyframeMode::AnchorToIn, 10.0, vec![mosaic_in]),
        preset("Soft Vignette", "Darkens outside a feathered oval mask", KeyframeMode::Scale, 10.0, vec![vignette]),
        preset("Spotlight", "Brightens inside a feathered circular mask", KeyframeMode::Scale, 10.0, vec![spotlight]),
        preset("Warm Tint", "Warm highlights, brown shadows", KeyframeMode::Scale, 10.0, vec![warm]),
        preset("PiP 35% Upper Right", "Picture-in-picture: 35 % scale in the upper right", KeyframeMode::Scale, 10.0, vec![pip]),
    ]
}

// ---------------------------------------------------------------- save / apply

/// Every parameter of an effect instance (its own and its masks').
fn params_mut(e: &mut EffectInstance) -> Vec<&mut Param> {
    let mut v: Vec<&mut Param> = e.params.values_mut().collect();
    for m in &mut e.masks {
        v.extend(m.params_mut());
    }
    v
}

/// Media length of a track item.
fn media_len(it: &TrackItem) -> Tick {
    Tick((it.duration.0 as f64 * it.speed.abs()).round() as i64)
}

/// Build a preset from effects of a clip. `mt` = the clip's media time at the playhead.
pub fn capture(it: &TrackItem, idx: &[usize], name: &str, description: &str, mode: Option<KeyframeMode>, mt: Tick, size: (u32, u32)) -> EffectPreset {
    let mut effects: Vec<EffectInstance> = idx.iter().filter_map(|i| it.effects.get(*i).cloned()).collect();
    for e in &mut effects {
        e.essential = false;
        for p in params_mut(e) {
            match mode {
                None => {
                    // without keyframes: the value at the playhead
                    p.value = p.value_at(mt);
                    p.keyframes.clear();
                }
                Some(_) => {
                    for k in &mut p.keyframes {
                        k.time -= it.source_in;
                    }
                }
            }
        }
    }
    EffectPreset {
        name: name.to_string(),
        description: description.to_string(),
        keyframes: mode.unwrap_or_default(),
        source_duration: media_len(it),
        source_size: size,
        effects,
        builtin: false,
    }
}

/// Map a preset keyframe time (relative to the source in point) onto `target`.
pub fn retime(rel: Tick, mode: KeyframeMode, source_len: Tick, target: &TrackItem) -> Tick {
    let tin = target.source_in;
    let tlen = media_len(target);
    match mode {
        KeyframeMode::AnchorToIn => tin + rel,
        KeyframeMode::AnchorToOut => tin + tlen - (source_len - rel),
        KeyframeMode::Scale => {
            if source_len.0 <= 0 {
                tin + rel
            } else {
                tin + Tick((rel.0 as i128 * tlen.0 as i128 / source_len.0 as i128) as i64)
            }
        }
    }
}

/// Scale geometric parameter values to fit target sequence dimensions.
fn scale_value(v: &mut ParamValue, sx: f64, sy: f64) {
    match v {
        ParamValue::Vec2(p) if !p.x.is_nan() => *p = Vec2::new(p.x * sx, p.y * sy),
        ParamValue::Path(path) => *path = path.transformed(&Affine::scale(sx, sy)),
        _ => {}
    }
}

/// The preset's effects prepared for `target` (keyframes re-timed, geometry scaled).
pub fn instantiate(p: &EffectPreset, target: &TrackItem, size: (u32, u32)) -> Vec<EffectInstance> {
    let sx = size.0 as f64 / p.source_size.0.max(1) as f64;
    let sy = size.1 as f64 / p.source_size.1.max(1) as f64;
    let geometric = (sx - 1.0).abs() > 1e-9 || (sy - 1.0).abs() > 1e-9;
    let mut out = p.effects.clone();
    for e in &mut out {
        // Point params scale only when they are positions (the def kind says so)
        let point_ids: Vec<String> = e
            .def()
            .map(|d| d.params.iter().filter(|q| matches!(q.kind, filmcraft_project::ParamKind::Point)).map(|q| q.id.to_string()).collect())
            .unwrap_or_default();
        for (id, prm) in e.params.iter_mut() {
            for k in &mut prm.keyframes {
                k.time = retime(k.time, p.keyframes, p.source_duration, target);
            }
            prm.keyframes.sort_by_key(|k| k.time);
            prm.keyframes.dedup_by_key(|k| k.time);
            if geometric && point_ids.contains(id) {
                scale_value(&mut prm.value, sx, sy);
                for k in &mut prm.keyframes {
                    scale_value(&mut k.value, sx, sy);
                }
            }
        }
        for m in &mut e.masks {
            for prm in m.params_mut() {
                for k in &mut prm.keyframes {
                    k.time = retime(k.time, p.keyframes, p.source_duration, target);
                }
                prm.keyframes.sort_by_key(|k| k.time);
                prm.keyframes.dedup_by_key(|k| k.time);
                if geometric {
                    scale_value(&mut prm.value, sx, sy);
                    for k in &mut prm.keyframes {
                        scale_value(&mut k.value, sx, sy);
                    }
                }
            }
            if geometric {
                // feather / expansion are lengths: scale by the mean factor
                let s = (sx * sy).sqrt();
                for prm in [&mut m.feather, &mut m.expansion] {
                    if let ParamValue::Float(v) = &mut prm.value {
                        *v *= s;
                    }
                    for k in &mut prm.keyframes {
                        if let ParamValue::Float(v) = &mut k.value {
                            *v *= s;
                        }
                    }
                }
            }
        }
    }
    out
}

/// Keep `old`'s keyframes that lie outside the span `new` animates, so presets keyframing the same
/// parameter at different times (Fade In, then Fade Out) add up instead of replacing each other.
fn merge_keyframes(new: &mut EffectInstance, old: &EffectInstance) {
    for (id, p) in new.params.iter_mut() {
        let (Some(first), Some(last)) = (p.keyframes.first().map(|k| k.time), p.keyframes.last().map(|k| k.time)) else { continue };
        let Some(o) = old.params.get(id) else { continue };
        p.keyframes.extend(o.keyframes.iter().filter(|k| k.time < first || k.time > last).cloned());
        p.keyframes.sort_by_key(|k| k.time);
    }
}

/// Put preset effects on a clip: intrinsic ones replace the clip's instance (keeping its keyframes
/// outside the span the preset animates), others are added at the end, like `effects.apply`.
pub fn put_effects(it: &mut TrackItem, effects: Vec<EffectInstance>) {
    for mut e in effects {
        let intrinsic = e.def().is_some_and(|d| d.intrinsic);
        if intrinsic && let Some(slot) = it.effects.iter_mut().find(|x| x.effect == e.effect) {
            merge_keyframes(&mut e, slot);
            *slot = e;
            continue;
        }
        it.effects.push(e);
    }
}

// ---------------------------------------------------------------- commands

type Run = fn(&mut Session, &Value) -> Result<Value>;

/// Helper to construct an engine CommandSpec.
fn spec(
    id: &'static str,
    label: &'static str,
    params: &'static str,
    enabled: fn(&Session) -> std::result::Result<(), String>,
    run: Run,
    journal: bool,
) -> CommandSpec {
    CommandSpec { id, label, menu: &[], shortcut: None, params, enabled, run, journal, named: crate::commands::NamedKeys::NONE }
}

/// Return the command specifications for preset management.
pub(crate) fn commands() -> Vec<CommandSpec> {
    vec![
        spec("presets.list", "List Effect Presets", "{}", always, list, false),
        spec(
            "presets.save",
            "Save Preset",
            r#"{"clip":id?,"effects":[index]?,"name":str,"description":str?,"keyframes":"scale"|"anchorIn"|"anchorOut"|"none"?}"#,
            has_seq,
            save,
            true,
        ),
        spec("presets.apply", "Apply Preset", r#"{"preset":str,"clips":[id]?}"#, has_seq, apply, true),
        spec("presets.delete", "Delete Preset", r#"{"name":str}"#, always, delete, true),
        spec("presets.rename", "Rename Preset", r#"{"name":str,"to":str}"#, always, rename, true),
        spec("presets.export", "Export Presets", r#"{"path":str,"names":[str]?}"#, always, export, false),
        spec("presets.import", "Import Presets", r#"{"path":str}"#, always, import, true),
        spec("presets.scan", "Scan Preset Library", "{}", always, scan, false),
    ]
}

/// Format an effect preset as a JSON value.
fn preset_json(p: &EffectPreset) -> Value {
    json!({
        "name": p.name,
        "description": p.description,
        "builtin": p.builtin,
        "keyframes": p.keyframes.label(),
        "effects": p.effects.iter().map(|e| e.def().map(|d| d.name).unwrap_or(e.effect.as_str()).to_string()).collect::<Vec<_>>(),
        "animated": p.effects.iter().any(|e| e.is_animated()),
        "masks": p.effects.iter().map(|e| e.masks.len()).sum::<usize>(),
    })
}

/// Engine command handler to list all presets.
fn list(s: &mut Session, _: &Value) -> Result<Value> {
    let presets: Vec<Value> = s
        .presets
        .all()
        .iter()
        .map(|p| {
            let mut v = preset_json(p);
            if let Some(source) = s.presets.source_of(&p.name) {
                v["source"] = json!(source);
            }
            v
        })
        .collect();
    Ok(json!({"presets": presets}))
}

/// Retrieve the source or sequence dimensions for a clip item.
fn clip_size(s: &Session, it: &TrackItem) -> (u32, u32) {
    filmcraft_render::source_size(&s.project, it.item).or_else(|| s.active_sequence().map(|q| (q.settings.width, q.settings.height))).unwrap_or(hd())
}

/// Engine command handler to save an effect preset from selected clip.
fn save(s: &mut Session, p: &Value) -> Result<Value> {
    let name = str_p(p, "name").map(str::trim).filter(|n| !n.is_empty()).ok_or_else(|| bad("presets.save", "need a `name`"))?.to_string();
    let seq = s.active_sequence().ok_or(EngineError::NoSequence)?;
    let clip = clip_p(p, "clip")
        .or_else(|| s.state.selection.iter().copied().find(|c| seq.find_item(*c).and_then(|(t, _)| seq.track(t)).is_some_and(|t| t.kind == TrackKind::Video)))
        .or_else(|| s.state.selection.first().copied())
        .ok_or_else(|| bad("presets.save", "select a clip"))?;
    let (_, it) = seq.find_item(clip).ok_or_else(|| bad("presets.save", "no such clip"))?;
    let idx: Vec<usize> = match p.get("effects").and_then(Value::as_array) {
        Some(a) => a.iter().filter_map(|v| v.as_u64().map(|n| n as usize)).filter(|i| *i < it.effects.len()).collect(),
        // default: the standard (non-intrinsic, non-layer) effects
        None => (0..it.effects.len())
            .filter(|i| {
                let e = &it.effects[*i];
                e.def().is_some_and(|d| !d.intrinsic) && !filmcraft_project::graphic::is_layer(e) && !e.essential
            })
            .collect(),
    };
    if idx.is_empty() {
        return Err(bad("presets.save", "no effects to save (pass `effects`)"));
    }
    let mode = match str_p(p, "keyframes") {
        None => Some(KeyframeMode::Scale),
        Some(k) if k.eq_ignore_ascii_case("none") => None,
        Some(k) => Some(KeyframeMode::from_name(k).ok_or_else(|| bad("presets.save", format!("unknown keyframe mode `{k}`")))?),
    };
    let mt = it.source_time_at(s.playhead().clamp(it.start, it.end() - Tick(1)));
    let size = clip_size(s, it);
    let preset = capture(it, &idx, &name, str_p(p, "description").unwrap_or(""), mode, mt, size);
    let out = preset_json(&preset);
    if s.presets.is_library_preset(&name) {
        return Err(bad("presets.save", format!("`{name}` is part of the preset library and cannot be overwritten")));
    }
    s.presets.user.retain(|x| x.name != name);
    s.presets.user.push(preset);
    s.presets.persist().map_err(EngineError::Other)?;
    Ok(out)
}

/// Engine command handler to apply an effect preset to clips.
fn apply(s: &mut Session, p: &Value) -> Result<Value> {
    let name = str_p(p, "preset").or_else(|| str_p(p, "name")).ok_or_else(|| bad("presets.apply", "need `preset`"))?;
    let preset = s.presets.find(name).ok_or_else(|| bad("presets.apply", format!("no preset `{name}`")))?;
    let clips: Vec<ClipId> = match p.get("clips").and_then(Value::as_array) {
        Some(a) => a.iter().filter_map(|v| v.as_u64().map(ClipId)).collect(),
        None => s.state.selection.clone(),
    };
    if clips.is_empty() {
        return Err(bad("presets.apply", "select clips first"));
    }
    let has_video = preset.effects.iter().any(|e| e.def().is_some_and(|d| d.kind != filmcraft_project::EffectKind::Audio));
    let has_audio = preset.effects.iter().any(|e| e.def().is_some_and(|d| d.kind == filmcraft_project::EffectKind::Audio));
    let sizes: Vec<(ClipId, (u32, u32))> = {
        let seq = s.active_sequence().ok_or(EngineError::NoSequence)?;
        clips.iter().filter_map(|c| seq.find_item(*c).map(|(_, it)| (*c, clip_size(s, it)))).collect()
    };
    let label = format!("Apply Preset {}", preset.name);
    let n = s.edit_sequence(&label, |q, _, _| {
        let mut n = 0;
        for t in q.all_tracks_mut() {
            let is_audio_track = t.kind == TrackKind::Audio;
            if (is_audio_track && !has_audio) || (!is_audio_track && !has_video) {
                continue;
            }
            for it in t.items.iter_mut().filter(|i| clips.contains(&i.id)) {
                let size = sizes.iter().find(|(c, _)| *c == it.id).map(|x| x.1).unwrap_or(hd());
                let fx: Vec<_> = instantiate(&preset, it, size)
                    .into_iter()
                    .filter(|e| e.def().is_some_and(|d| (d.kind == filmcraft_project::EffectKind::Audio) == is_audio_track))
                    .collect();
                if !fx.is_empty() {
                    put_effects(it, fx);
                    n += 1;
                }
            }
        }
        if n == 0 {
            return Err(bad("presets.apply", "the preset doesn't fit the selected clips (video/audio)"));
        }
        Ok(n)
    })?;
    Ok(json!({"applied": n}))
}

/// Engine command handler to delete a user preset.
fn delete(s: &mut Session, p: &Value) -> Result<Value> {
    let name = str_p(p, "name").ok_or_else(|| bad("presets.delete", "need `name`"))?;
    if let Some(source) = s.presets.source_of(name) {
        return Err(bad("presets.delete", format!("`{name}` comes from {source}; delete or move that file to remove it from the preset library")));
    }
    let before = s.presets.user.len();
    s.presets.user.retain(|x| x.name != name);
    if s.presets.user.len() == before {
        return Err(bad(
            "presets.delete",
            if builtin_presets().iter().any(|b| b.name == name) { "built-in presets cannot be deleted" } else { "no such preset" },
        ));
    }
    s.presets.persist().map_err(EngineError::Other)?;
    Ok(Value::Null)
}

/// Engine command handler to rename a user preset.
fn rename(s: &mut Session, p: &Value) -> Result<Value> {
    let name = str_p(p, "name").ok_or_else(|| bad("presets.rename", "need `name`"))?;
    if let Some(source) = s.presets.source_of(name) {
        return Err(bad("presets.rename", format!("`{name}` comes from {source}; rename the preset in Premiere and re-import it")));
    }
    let to = str_p(p, "to").map(str::trim).filter(|t| !t.is_empty()).ok_or_else(|| bad("presets.rename", "need `to`"))?.to_string();
    if s.presets.user.iter().any(|x| x.name == to) {
        return Err(bad("presets.rename", format!("a preset named `{to}` exists")));
    }
    let pr = s.presets.user.iter_mut().find(|x| x.name == name).ok_or_else(|| bad("presets.rename", "no such user preset"))?;
    pr.name = to;
    s.presets.persist().map_err(EngineError::Other)?;
    Ok(Value::Null)
}

/// Engine command handler to export presets to a file.
fn export(s: &mut Session, p: &Value) -> Result<Value> {
    let path = str_p(p, "path").ok_or_else(|| bad("presets.export", "need `path`"))?;
    let all = s.presets.all();
    let chosen: Vec<EffectPreset> = match p.get("names").and_then(Value::as_array) {
        Some(n) => {
            let names: Vec<&str> = n.iter().filter_map(Value::as_str).collect();
            let v: Vec<EffectPreset> = all.into_iter().filter(|x| names.contains(&x.name.as_str())).collect();
            if v.len() != names.len() {
                return Err(bad("presets.export", "unknown preset name"));
            }
            v
        }
        None => s.presets.user.clone(),
    };
    if chosen.is_empty() {
        return Err(bad("presets.export", "no presets to export"));
    }
    // through the host: atomic on the desktop, a download on the web (no filesystem there)
    s.services.write_file(path, &file_bytes(&chosen)).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
    Ok(json!({"path": path, "count": chosen.len()}))
}

/// Add `incoming` to `library`, each replacing the entry with the same key in place (a file with
/// many presets used to rescan the growing library once per preset).
pub(crate) fn merge_by_key<T>(library: &mut Vec<T>, incoming: Vec<T>, key: impl Fn(&T) -> String) {
    // Drop the library's duplicates of imported keys, keeping the first, so the replacement lands where `find` looks.
    let imported: std::collections::HashSet<String> = incoming.iter().map(&key).collect();
    let mut kept = std::collections::HashSet::new();
    library.retain(|x| {
        let k = key(x);
        !imported.contains(&k) || kept.insert(k)
    });
    let mut index: std::collections::HashMap<String, usize> = library.iter().enumerate().map(|(i, x)| (key(x), i)).collect();
    for item in incoming {
        match index.get(&key(&item)) {
            Some(&i) => {
                if let Some(slot) = library.get_mut(i) {
                    *slot = item;
                }
            }
            None => {
                index.insert(key(&item), library.len());
                library.push(item);
            }
        }
    }
}

/// Import presets from raw bytes directly into the user preset store.
pub fn import_bytes(s: &mut Session, path: &str, bytes: &[u8]) -> std::result::Result<Value, String> {
    let parsed = parse_file_detailed(bytes)?;
    if parsed.presets.is_empty() {
        let detail = parsed
            .skipped
            .iter()
            .take(8)
            .map(|sk| if sk.effects.is_empty() { sk.name.clone() } else { format!("{} ({})", sk.name, sk.effects.join(", ")) })
            .collect::<Vec<_>>()
            .join("; ");
        let more = if parsed.skipped.len() > 8 { format!(" and {} more", parsed.skipped.len() - 8) } else { String::new() };
        let suffix = if detail.is_empty() { String::new() } else { format!(": {detail}{more}") };
        return Err(format!("{path}: no supported effects in this preset file{suffix}"));
    }
    let mut names = Vec::new();
    let mut incoming = Vec::with_capacity(parsed.presets.len());
    for mut pr in parsed.presets {
        if s.presets.is_library_preset(&pr.name) {
            let mut combined = s.presets.user.clone();
            combined.extend(incoming.iter().cloned());
            pr.name = unique_preset_name(&combined, &pr.name);
        }
        names.push(pr.name.clone());
        incoming.push(pr);
    }
    merge_by_key(&mut s.presets.user, incoming, |x| x.name.clone());
    s.presets.persist()?;
    let skipped: Vec<Value> = parsed.skipped.iter().map(|sk| json!({"name": sk.name, "effects": sk.effects, "reason": sk.reason})).collect();
    Ok(json!({
        "imported": names,
        "skipped": skipped,
        "warning_count": parsed.warnings.len(),
        "warnings": parsed.warnings.iter().take(100).cloned().collect::<Vec<_>>(),
    }))
}

/// Engine command handler to import preset files into the library.
fn import(s: &mut Session, p: &Value) -> Result<Value> {
    let path = str_p(p, "path").ok_or_else(|| bad("presets.import", "need `path`"))?;
    if let Ok(size) = s.services.file_size(path)
        && size > crate::prfpset::MAX_BYTES
    {
        return Err(bad(
            "presets.import",
            format!("{path}: file is too large ({} MB; the limit is {} MB)", size / (1024 * 1024), crate::prfpset::MAX_BYTES / (1024 * 1024)),
        ));
    }
    let bytes = s.services.read_file(path).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;

    let parsed = parse_file_detailed(&bytes).map_err(|e| EngineError::Other(format!("{path}: {e}")))?;
    let indexable =
        std::path::Path::new(path).extension().and_then(|e| e.to_str()).is_some_and(|e| e.eq_ignore_ascii_case("prfpset") || e.eq_ignore_ascii_case("json"));
    if indexable
        && !parsed.presets.is_empty()
        && let Some(lib_dir) = s.presets.library_dir()
        && let Some(fname) = std::path::Path::new(path).file_name()
    {
        let src = std::path::Path::new(path);
        let src_canon = src.canonicalize().unwrap_or_else(|_| src.to_path_buf());
        let lib_canon = lib_dir.canonicalize().unwrap_or_else(|_| lib_dir.clone());
        let in_library = src_canon.starts_with(&lib_canon);
        let mut dest = if in_library { src_canon.clone() } else { lib_dir.join(fname) };
        if !in_library {
            let stem = dest.file_stem().and_then(|s| s.to_str()).unwrap_or("presets").to_string();
            let ext = dest.extension().and_then(|e| e.to_str()).unwrap_or("prfpset").to_string();
            let mut n = 2u32;
            while dest.exists() && std::fs::read(&dest).map(|b| b != bytes).unwrap_or(true) {
                dest = lib_dir.join(format!("{stem} ({n}).{ext}"));
                n += 1;
            }
        }
        if in_library || std::fs::write(&dest, &bytes).is_ok() {
            let _ = s.presets.rescan();
            let dest_canon = dest.canonicalize().unwrap_or_else(|_| dest.clone());
            let names = s
                .presets
                .library
                .iter()
                .find(|(k, _)| {
                    let p = std::path::Path::new(k);
                    p == dest || p == dest_canon || p.canonicalize().map(|c| c == dest_canon).unwrap_or(false)
                })
                .map(|(_, f)| f.names.clone())
                .unwrap_or_default();
            return Ok(json!({
                "imported": names,
                "skipped": parsed.skipped.iter().map(|sk| json!({
                    "name": sk.name,
                    "effects": sk.effects,
                    "reason": sk.reason
                })).collect::<Vec<_>>(),
                "warning_count": parsed.warnings.len(),
                "warnings": parsed.warnings.iter().take(100).cloned().collect::<Vec<_>>(),
            }));
        }
    }
    import_bytes(s, path, &bytes).map_err(EngineError::Other)
}

/// Engine command handler to trigger a preset library rescan.
fn scan(s: &mut Session, _: &Value) -> Result<Value> {
    let report = s.presets.rescan();
    Ok(report.json())
}

#[cfg(test)]
mod merge_tests {
    use super::merge_by_key;

    #[test]
    fn merge_replaces_by_key_and_keeps_new_entries_in_order() {
        let mut lib = vec![("a", 1), ("b", 1)];
        merge_by_key(&mut lib, vec![("b", 2), ("c", 1), ("c", 2), ("d", 1)], |x| x.0.to_string());
        assert_eq!(lib, vec![("a", 1), ("b", 2), ("c", 2), ("d", 1)]);
        // A duplicate already in the library is dropped for an imported key; the first entry is replaced.
        let mut lib = vec![("a", 1), ("b", 1), ("b", 9)];
        merge_by_key(&mut lib, vec![("b", 2)], |x| x.0.to_string());
        assert_eq!(lib, vec![("a", 1), ("b", 2)]);
        // many distinct names: 200k imports all land
        let mut lib: Vec<(String, u32)> = Vec::new();
        merge_by_key(&mut lib, (0..200_000).map(|i| (format!("preset {i}"), i)).collect(), |x| x.0.clone());
        assert_eq!(lib.len(), 200_000);
    }
}