rustmotion-core 0.6.0

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use std::collections::HashMap;

use super::animation::EasingType;
use super::background::{
    deserialize_animated_backgrounds, deserialize_background_value, AnimatedBackground,
    BackgroundValue, ResolvedBackground,
};
use super::style::{CardAlign, CardDirection, CardJustify};

/// Definition of a variable in a structural component.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct VariableDefinition {
    #[serde(rename = "type")]
    pub var_type: VariableType,
    pub default: serde_json::Value,
    /// Optional description for documentation/schema.
    #[serde(default)]
    pub description: Option<String>,
}

/// Supported variable types.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum VariableType {
    String,
    Number,
    Boolean,
    Object,
    Array,
}

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Scenario {
    #[serde(default = "default_version")]
    pub version: String,
    pub video: VideoConfig,
    #[serde(default)]
    pub audio: Vec<AudioTrack>,
    #[serde(default)]
    pub fonts: Vec<FontEntry>,
    #[serde(default, deserialize_with = "deserialize_scene_entries")]
    pub scenes: Vec<SceneEntry>,
    /// Composition: a sequence of views (slide or world). Mutually exclusive with top-level `scenes`.
    #[serde(default)]
    pub composition: Option<Vec<View>>,
    /// Config definitions for structural components. Each config entry has a type and default value.
    #[serde(default)]
    pub config: Option<HashMap<String, VariableDefinition>>,
    /// Named background templates that scenes can reference via `$ref`.
    #[serde(default)]
    pub backgrounds: HashMap<String, serde_json::Value>,
    /// Studio feedback annotations. Persisted in the scenario but never read by
    /// the renderer or the geometry validator. Skipped on serialization when empty.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub annotations: Vec<Annotation>,
}

/// Lifecycle of a studio annotation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
#[derive(Default)]
pub enum AnnotationStatus {
    #[default]
    Open,
    Resolved,
}

/// What an annotation points at: a JSON Pointer into the source scenario,
/// plus optional context captured at click time.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct AnnotationTarget {
    /// RFC 6901 JSON Pointer into the source scenario (e.g. "/scenes/2/children/5").
    pub pointer: String,
    /// Component kind label captured at click time (e.g. "text", "card").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kind: Option<String>,
    /// Bounding box [x, y, w, h] in video coords at the capture frame.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rect: Option<[f32; 4]>,
}

/// A single studio feedback note attached to an element at a moment in time.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct Annotation {
    /// Stable id (generated by the studio).
    pub id: String,
    /// Free-text change request for the agent/skill.
    pub note: String,
    #[serde(default)]
    pub status: AnnotationStatus,
    /// Frame index at capture time (global playhead).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub frame: Option<u32>,
    /// Resolved view index (convenience for the skill).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub view: Option<usize>,
    /// Resolved scene index (convenience for the skill).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scene: Option<usize>,
    pub target: AnnotationTarget,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ViewType {
    Slide,
    World,
}

fn default_view_type() -> ViewType {
    ViewType::Slide
}

fn default_camera_pan_duration() -> f64 {
    0.8
}

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct View {
    #[serde(rename = "type", default = "default_view_type")]
    pub view_type: ViewType,
    #[serde(default, deserialize_with = "deserialize_scene_entries")]
    pub scenes: Vec<SceneEntry>,
    /// Transition entering this view (between views).
    #[serde(default)]
    pub transition: Option<Transition>,
    /// (world) Shared background: color string, animated entry, or array.
    // Constat #5: `background`'s `deserialize_with` bypasses the normal
    // derive, so schemars had nothing to infer a schema from — hence the
    // `#[schemars(skip)]` this used to carry. But `View` is also
    // `deny_unknown_fields` (-> `additionalProperties: false` in the
    // exported schema), so skipping the property didn't just leave it
    // undocumented: it made the exported schema declare invalid every view
    // that actually sets `background`. `BackgroundValue` now has a real
    // (manual) `JsonSchema` impl — see `background.rs` — so this can be a
    // normal declared property again.
    #[serde(default, deserialize_with = "deserialize_background_value")]
    pub background: Option<BackgroundValue>,
    /// (world) Legacy shared animated backgrounds.
    #[serde(
        default,
        rename = "animated-background",
        deserialize_with = "deserialize_animated_backgrounds"
    )]
    pub animated_background: Vec<AnimatedBackground>,
    /// (world) Easing for camera pan between scenes.
    #[serde(default = "default_transition_easing")]
    pub camera_easing: EasingType,
    /// (world) Duration of camera pan between scenes (default 0.8s).
    #[serde(default = "default_camera_pan_duration")]
    pub camera_pan_duration: f64,
}

/// A scenario with all includes expanded — safe to pass to the rendering pipeline.
#[derive(Debug)]
pub struct ResolvedScenario {
    pub video: VideoConfig,
    pub audio: Vec<AudioTrack>,
    pub fonts: Vec<FontEntry>,
    pub views: Vec<ResolvedView>,
    /// Local file paths that were included during resolution (for watch mode).
    pub included_paths: Vec<std::path::PathBuf>,
}

impl ResolvedScenario {
    /// Iterate over all scenes across all views (for prefetch, validation, etc.)
    pub fn all_scenes(&self) -> impl Iterator<Item = &Scene> {
        self.views.iter().flat_map(|v| v.scenes.iter())
    }

    /// Collect all scenes into a flat Vec (for indexed access)
    #[allow(dead_code)]
    pub fn all_scenes_vec(&self) -> Vec<&Scene> {
        self.all_scenes().collect()
    }
}

#[derive(Debug)]
pub struct ResolvedView {
    pub view_type: ViewType,
    pub scenes: Vec<Scene>,
    pub transition: Option<Transition>,
    pub background: ResolvedBackground,
    pub camera_easing: EasingType,
    pub camera_pan_duration: f64,
}

/// An entry in the `scenes` array: either a concrete scene or an include directive.
///
/// `#[serde(untagged)]` is kept so [`schemars`] still emits the correct
/// (flat, non-wrapped) JSON Schema for this enum, and so a direct
/// `SceneEntry::deserialize` call elsewhere keeps working. It is **not**
/// how `Scenario.scenes` / `View.scenes` actually deserialize an entry from
/// JSON, though: those two fields use [`deserialize_scene_entries`] instead
/// (see its doc comment for why — M6, issue #110).
#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[serde(untagged)]
#[allow(clippy::large_enum_variant)] // untagged serde enum; boxing Scene would break all match arms
pub enum SceneEntry {
    /// A regular scene defined inline.
    Scene(Scene),
    /// A reference to an external scenario file whose scenes will be injected here.
    Include(IncludeDirective),
}

/// Deserializer for `Scenario.scenes` / `View.scenes`, used in place of
/// `SceneEntry`'s derived `#[serde(untagged)]` deserialization (M6, issue
/// #110 / #102).
///
/// `#[serde(untagged)]` deserializes by trying each variant in declaration
/// order and keeping the first one that succeeds; when *all* variants fail
/// (e.g. a scene missing its required `duration`, or a `transition.type`
/// typo three levels down) serde discards every per-variant error and
/// reports only `data did not match any variant of untagged enum
/// SceneEntry` — no scene index, no field name. The wave-2 audit called
/// this the worst diagnostic in the product.
///
/// The two variants are unambiguous by shape — `IncludeDirective`'s only
/// required field is `include`; a `Scene` never has that key — so this
/// classifies each entry explicitly instead of trying-and-discarding, then
/// deserializes it as its concrete type and reports *that* type's real
/// error, prefixed with the entry's index in the `scenes` array.
///
/// Note on precision: this still deserializes from an already-parsed
/// [`serde_json::Value`] (as the untagged path did too), which has no
/// source line/column to report — the fix here is naming the scene index
/// and field, not a source position that doesn't exist at this layer.
fn deserialize_scene_entries<'de, D>(deserializer: D) -> Result<Vec<SceneEntry>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    use serde::de::Error as _;

    let raw: Vec<serde_json::Value> = Vec::deserialize(deserializer)?;
    let mut out = Vec::with_capacity(raw.len());
    for (i, entry) in raw.into_iter().enumerate() {
        let is_include = entry.get("include").is_some();
        if is_include {
            let directive: IncludeDirective = serde_json::from_value(entry)
                .map_err(|e| D::Error::custom(format!("scenes[{i}] (include directive): {e}")))?;
            out.push(SceneEntry::Include(directive));
        } else {
            let scene: Scene = serde_json::from_value(entry)
                .map_err(|e| D::Error::custom(format!("scenes[{i}]: {e}")))?;
            out.push(SceneEntry::Scene(scene));
        }
    }
    Ok(out)
}

/// Directive to inject scenes from an external scenario file.
#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct IncludeDirective {
    /// Path (relative to parent file) or URL (http/https) to a scenario JSON file.
    pub include: String,
    /// Only include scenes at these 0-based indices. When absent, all scenes are included.
    #[serde(default)]
    pub scenes: Option<Vec<usize>>,
    /// Config overrides to pass to the included structural component.
    #[serde(default)]
    pub config: Option<HashMap<String, serde_json::Value>>,
}

/// Font file to load at startup.
///
/// Two mutually exclusive modes:
/// - **Local**: `path` (required) + `family`. Loads a `.ttf`/`.otf` file directly.
/// - **Google Fonts**: `source = "google"` + `family` + optional `weights` (default [400]).
///   The font is downloaded from the Google Fonts CSS2 API and cached in
///   `~/.cache/rustmotion/fonts` (or `%LOCALAPPDATA%\rustmotion\fonts` on Windows).
///   Subsequent renders with a warm cache make zero network calls.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct FontEntry {
    /// Local file path (.ttf/.otf). Required when `source` is absent.
    #[serde(default)]
    pub path: Option<String>,
    /// Font family name (e.g. "Inter", "JetBrains Mono").
    pub family: String,
    /// Font source. Currently the only recognised value is `"google"`.
    /// When set, `path` must be absent.
    #[serde(default)]
    pub source: Option<String>,
    /// Font weights to download (Google Fonts only). Defaults to `[400]`.
    #[serde(default)]
    pub weights: Option<Vec<u16>>,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct AudioTrack {
    pub src: String,
    #[serde(default)]
    pub start: f64,
    #[serde(default)]
    pub end: Option<f64>,
    #[serde(default = "default_volume")]
    pub volume: f32,
    #[serde(default)]
    pub fade_in: Option<f64>,
    #[serde(default)]
    pub fade_out: Option<f64>,
    #[serde(default)]
    pub volume_keyframes: Vec<VolumeKeyframe>,
}

/// Dynamic volume control point
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct VolumeKeyframe {
    pub time: f64,
    pub volume: f32,
    #[serde(default)]
    pub easing: EasingType,
}

fn default_volume() -> f32 {
    1.0
}

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct VideoConfig {
    pub width: u32,
    pub height: u32,
    #[serde(default = "default_fps")]
    pub fps: u32,
    #[serde(default = "default_background")]
    pub background: String,
    #[serde(default)]
    pub codec: Option<VideoCodec>,
    #[serde(default)]
    pub crf: Option<u8>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct WorldPosition {
    #[serde(default)]
    pub x: f32,
    #[serde(default)]
    pub y: f32,
}

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Scene {
    pub duration: f64,
    /// Unified background: color string, animated entry (with optional $ref), or array.
    // Constat #5: see the identical note on `View::background` — same
    // `#[schemars(skip)]` + `deny_unknown_fields` combination made the
    // exported schema declare invalid every `examples/*.json` scene that
    // sets `background` (which is most of them).
    #[serde(default, deserialize_with = "deserialize_background_value")]
    pub background: Option<BackgroundValue>,
    #[serde(default)]
    pub children: Vec<serde_json::Value>,
    #[serde(default)]
    pub transition: Option<Transition>,
    #[serde(default)]
    pub freeze_at: Option<f64>,
    /// Flex layout for automatic layer positioning
    #[serde(default)]
    pub layout: Option<SceneLayout>,
    /// Legacy animated background (kept for backward compat)
    #[serde(
        default,
        rename = "animated-background",
        deserialize_with = "deserialize_animated_backgrounds"
    )]
    pub animated_background: Vec<AnimatedBackground>,
    /// Virtual camera with animatable x, y, zoom, rotation.
    #[serde(default)]
    pub camera: Option<Camera>,
    /// Position of this scene in the 2D world (used by world views).
    #[serde(default, rename = "world-position")]
    pub world_position: Option<WorldPosition>,
    /// (world) Keep this scene visible after its time window ends.
    #[serde(default)]
    pub persist: bool,
    /// Post-processing effects applied to the full frame buffer after Skia renders.
    /// Effects are additive and applied in declaration order.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub effects: Vec<PostEffect>,
    /// Post-resolution background (populated by include.rs, ignored by serde).
    #[serde(skip)]
    #[schemars(skip)]
    pub resolved_background: ResolvedBackground,
}

/// Virtual camera for pan/zoom/rotation effects at the scene level.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Camera {
    /// Camera center X offset from scene center (pixels). Default: 0.
    #[serde(default)]
    pub x: f32,
    /// Camera center Y offset from scene center (pixels). Default: 0.
    #[serde(default)]
    pub y: f32,
    /// Zoom factor. 1.0 = no zoom, 2.0 = 2x zoom in, 0.5 = zoom out.
    #[serde(default = "default_camera_zoom")]
    pub zoom: f32,
    /// Rotation in degrees around the camera origin. Default: 0.
    #[serde(default)]
    pub rotation: f32,
    /// Focal point for zoom/rotation, in frame pixels. Absent = frame centre
    /// (the historical behaviour). When the object is present, `x`/`y`
    /// default to 0 (top-left corner) — set both explicitly.
    #[serde(default)]
    pub origin: Option<CameraOrigin>,
    /// Keyframe animations for camera properties.
    #[serde(default)]
    pub keyframes: Vec<CameraKeyframe>,
}

/// Focal point of the camera in frame pixels.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CameraOrigin {
    #[serde(default)]
    pub x: f32,
    #[serde(default)]
    pub y: f32,
}

/// Every camera property `interpolate_camera_property`
/// (`crates/rustmotion/src/engine/render/scene.rs`, owned by the sibling
/// GEO workstream this wave — read-only here) actually looks up via
/// `camera.keyframes.iter().find(|k| k.property == property)`. Constat #4:
/// a `CameraKeyframe.property` outside this fixed set (or the dotted
/// `origin.x`/`origin.y` convention misspelled as `origin_x`/`originX`)
/// never matches that lookup — the keyframe track is silently ignored and
/// the camera just uses its static value for that property, with no error.
const KNOWN_CAMERA_PROPERTIES: &[&str] = &["x", "y", "zoom", "rotation", "origin.x", "origin.y"];

fn validate_camera_property<E: serde::de::Error>(value: &str) -> Result<(), E> {
    if KNOWN_CAMERA_PROPERTIES.contains(&value) {
        return Ok(());
    }
    let normalize = |s: &str| s.replace(['-', '_', ' '], ".").to_lowercase();
    let normalized = normalize(value);
    if let Some(suggestion) = KNOWN_CAMERA_PROPERTIES
        .iter()
        .find(|known| normalize(known) == normalized)
    {
        Err(E::custom(format!(
            "unknown camera keyframe property '{value}' — did you mean '{suggestion}'?"
        )))
    } else {
        Err(E::custom(format!(
            "unknown camera keyframe property '{value}': expected one of {}",
            KNOWN_CAMERA_PROPERTIES.join(", ")
        )))
    }
}

fn deserialize_camera_property<'de, D>(deserializer: D) -> Result<String, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let s = String::deserialize(deserializer)?;
    validate_camera_property::<D::Error>(&s)?;
    Ok(s)
}

/// A keyframe for a camera property.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CameraKeyframe {
    /// The camera property to animate: "x", "y", "zoom", "rotation",
    /// "origin.x", "origin.y" (dotted form, matching the component keyframe
    /// convention for compound properties).
    #[serde(deserialize_with = "deserialize_camera_property")]
    pub property: String,
    /// Time-value pairs for the animation.
    pub values: Vec<CameraKeyframePoint>,
    /// Easing function for interpolation.
    #[serde(default)]
    pub easing: EasingType,
}

/// A single time-value point in a camera keyframe.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CameraKeyframePoint {
    /// Time in seconds (relative to scene start).
    pub time: f64,
    /// Value at this time.
    pub value: f32,
}

fn default_camera_zoom() -> f32 {
    1.0
}

/// Direction for progressive blur.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
#[derive(Default)]
pub enum BlurDirection {
    Top,
    #[default]
    Bottom,
}

/// A post-processing effect applied to the full frame buffer after Skia renders.
/// Effects are pure Rust, deterministic, and applied in declaration order.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum PostEffect {
    /// Film grain noise overlaid on every pixel.
    Grain {
        /// Noise strength clamped to 0..1. Default: 0.15.
        #[serde(default = "default_grain_intensity")]
        intensity: f32,
        /// Base seed for the noise hash. Default: 42.
        #[serde(default = "default_grain_seed")]
        seed: u64,
        /// When true, the pattern changes per frame (`seed ^ frame_index`). Default: true.
        #[serde(default = "default_true")]
        animated: bool,
    },
    /// Darken the frame edges towards the corners.
    Vignette {
        /// Darkness strength clamped to 0..1. Default: 0.5.
        #[serde(default = "default_vignette_intensity")]
        intensity: f32,
        /// Fraction of the half-diagonal where darkening starts. Default: 0.75.
        #[serde(default = "default_vignette_radius")]
        radius: f32,
    },
    /// Reduce spatial resolution by averaging square pixel blocks.
    Pixelate {
        /// Block size in pixels, clamped to 1..=256. Default: 8.
        #[serde(default = "default_pixelate_size")]
        size: u32,
    },
    /// Blur that grows from zero at `start` to `max_radius` at the frame edge.
    ProgressiveBlur {
        /// Which edge gets the maximum blur. Default: bottom.
        #[serde(default)]
        direction: BlurDirection,
        /// Fraction of the frame height where blur begins (0.0..1.0). Default: 0.5.
        #[serde(default = "default_blur_start")]
        start: f32,
        /// Maximum box-blur radius in pixels at the far edge. Default: 12.0.
        #[serde(default = "default_blur_max_radius")]
        max_radius: f32,
    },
}

fn default_grain_intensity() -> f32 {
    0.15
}
fn default_grain_seed() -> u64 {
    42
}
fn default_true() -> bool {
    true
}
fn default_vignette_intensity() -> f32 {
    0.5
}
fn default_vignette_radius() -> f32 {
    0.75
}
fn default_pixelate_size() -> u32 {
    8
}
fn default_blur_start() -> f32 {
    0.5
}
fn default_blur_max_radius() -> f32 {
    12.0
}

/// Scene-level flex layout configuration
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct SceneLayout {
    #[serde(default)]
    pub direction: Option<CardDirection>,
    #[serde(default)]
    pub gap: Option<f32>,
    #[serde(default)]
    pub align_items: Option<CardAlign>,
    #[serde(default)]
    pub justify_content: Option<CardJustify>,
    #[serde(default)]
    pub padding: Option<f32>,
}

/// The order `pixel_dissolve` turns its cells in.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum PixelDissolveOrder {
    /// From the frame's border inward, so the centre — where the subject
    /// usually is — is the last thing to go. This is what the reference piece
    /// does, and it is the default for that reason.
    #[default]
    EdgesIn,
    /// The mirror: the centre opens first and the border closes last.
    CenterOut,
    /// No spatial order at all — every cell on its own draw.
    Random,
}

/// The corner a `corner_reveal` is anchored to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum TransitionCorner {
    /// Measured default: the reference piece grows its reveal from here, with
    /// the right and top edges pinned and the left and bottom edges travelling.
    #[default]
    TopRight,
    TopLeft,
    BottomRight,
    BottomLeft,
}

/// Which way a directional transition travels.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum TransitionDirection {
    /// Both frames travel leftwards; the incoming one enters from the right.
    #[default]
    Left,
    Right,
    Up,
    Down,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Transition {
    #[serde(rename = "type")]
    pub transition_type: TransitionType,
    /// Which corner a `corner_reveal` grows from. Ignored by every other type.
    #[serde(default)]
    pub corner: TransitionCorner,
    /// Cell edge in px for `pixel_dissolve`. Ignored by every other type.
    #[serde(default = "default_transition_cell")]
    pub cell: f32,
    /// `pixel_dissolve` only: stable scatter selector. Two transitions with the
    /// same seed dissolve in the same order.
    #[serde(default = "default_transition_seed")]
    pub seed: u32,
    /// `pixel_dissolve` only: which cells turn first.
    #[serde(default)]
    pub order: PixelDissolveOrder,
    /// Which way a `chromatic_wipe` travels. Ignored by every other type —
    /// the `wipe_*`/`slide` family encodes its direction in the type name.
    #[serde(default)]
    pub direction: TransitionDirection,
    /// `chromatic_wipe` only: how far the red and cyan channels split at the
    /// peak of the wipe, as a multiple of the tuned default. `0` removes the
    /// colour flash and leaves a plain fast slide; `2` doubles it.
    #[serde(default = "default_transition_aberration")]
    pub aberration: f32,
    #[serde(default = "default_transition_duration")]
    pub duration: f64,
    #[serde(default = "default_transition_easing")]
    pub easing: EasingType,
    /// How the background behaves during a `camera_pan`. Ignored by every
    /// other transition type, which composite two finished frames and have no
    /// separate background layer to move.
    #[serde(default)]
    pub background: PanBackground,
}

/// Whether a `camera_pan` treats the background as a fixed backdrop the scenes
/// slide across, or as part of each scene, travelling with it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum PanBackground {
    /// The outgoing scene's background stays put while both foregrounds slide
    /// over it. Keeps a shared ambience continuous, so the cut is invisible —
    /// this is the default because it is what makes a multi-beat video read as
    /// one shot.
    #[default]
    Static,
    /// Each scene carries its own background, and both travel with their
    /// foreground. Use this when the beats are meant to look like different
    /// places rather than one continuous space.
    Travel,
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum TransitionType {
    Fade,
    WipeLeft,
    WipeRight,
    WipeUp,
    WipeDown,
    ZoomIn,
    ZoomOut,
    Flip,
    ClockWipe,
    Iris,
    Slide,
    Dissolve,
    CornerReveal,
    PixelDissolve,
    CameraPan,
    /// A fast slide in which the reveal edge splits into its red and cyan
    /// channels at the peak and recombines as it lands — the glitch-flash
    /// cut. `direction` steers it, `aberration` scales the split.
    ChromaticWipe,
    None,
}

fn default_transition_cell() -> f32 {
    48.0
}

fn default_transition_seed() -> u32 {
    11
}

fn default_transition_aberration() -> f32 {
    1.0
}

fn default_transition_duration() -> f64 {
    0.5
}

pub(crate) fn default_transition_easing() -> EasingType {
    EasingType::EaseInOut
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
#[derive(Default)]
pub enum VideoCodec {
    #[default]
    H264,
    H265,
    Vp9,
    Prores,
}

// --- Default functions ---

fn default_version() -> String {
    "1.0".to_string()
}

fn default_fps() -> u32 {
    30
}

fn default_background() -> String {
    "#000000".to_string()
}

#[cfg(test)]
mod annotation_tests {
    use super::*;

    const MINIMAL: &str = r#"{ "video": { "width": 1920, "height": 1080 }, "scenes": [] }"#;

    const WITH_ANNOTATIONS: &str = r#"{
        "video": { "width": 1920, "height": 1080 },
        "scenes": [],
        "annotations": [
            {
                "id": "an_4f2a",
                "note": "reduce font-size",
                "status": "open",
                "frame": 142,
                "view": 0,
                "scene": 2,
                "target": {
                    "pointer": "/scenes/2/children/5",
                    "kind": "text",
                    "rect": [10.0, 20.0, 30.0, 40.0]
                }
            }
        ]
    }"#;

    #[test]
    fn scenario_without_annotations_defaults_empty() {
        let s: Scenario = serde_json::from_str(MINIMAL).unwrap();
        assert!(s.annotations.is_empty());
    }

    #[test]
    fn scenario_with_annotations_deserializes() {
        let s: Scenario = serde_json::from_str(WITH_ANNOTATIONS).unwrap();
        assert_eq!(s.annotations.len(), 1);
        let a = &s.annotations[0];
        assert_eq!(a.id, "an_4f2a");
        assert_eq!(a.status, AnnotationStatus::Open);
        assert_eq!(a.frame, Some(142));
        assert_eq!(a.view, Some(0));
        assert_eq!(a.scene, Some(2));
        assert_eq!(a.target.pointer, "/scenes/2/children/5");
        assert_eq!(a.target.kind.as_deref(), Some("text"));
        assert_eq!(a.target.rect, Some([10.0, 20.0, 30.0, 40.0]));
    }

    #[test]
    fn empty_annotations_are_not_serialized() {
        let s: Scenario = serde_json::from_str(MINIMAL).unwrap();
        let json = serde_json::to_string(&s).unwrap();
        assert!(
            !json.contains("annotations"),
            "empty annotations must be skipped, got: {json}"
        );
    }

    #[test]
    fn status_defaults_to_open_and_target_fields_optional() {
        let json = r#"{
            "video": { "width": 1, "height": 1 },
            "scenes": [],
            "annotations": [ { "id": "x", "note": "n", "target": { "pointer": "/scenes/0" } } ]
        }"#;
        let s: Scenario = serde_json::from_str(json).unwrap();
        assert_eq!(s.annotations[0].status, AnnotationStatus::Open);
        assert_eq!(s.annotations[0].target.kind, None);
        assert_eq!(s.annotations[0].target.rect, None);
        assert_eq!(s.annotations[0].frame, None);
    }
}

/// M6 (issue #110 / #102): `SceneEntry` used to be a bare `#[serde(untagged)]`
/// enum, so a bad `scenes[]` entry collapsed to "data did not match any
/// variant of untagged enum SceneEntry" — no scene index, no field name.
/// `deserialize_scene_entries` replaces the auto-try-each-variant behaviour
/// with an explicit classify-then-deserialize pass that keeps the real
/// per-scene error and prefixes it with the entry's index.
#[cfg(test)]
mod scene_entry_error_tests {
    use super::*;

    #[test]
    fn missing_duration_names_the_scene_index_and_field_not_the_untagged_message() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "scenes": [
                { "duration": 1.0, "children": [] },
                { "children": [] }
            ]
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("missing duration must fail");
        let msg = err.to_string();
        assert!(
            !msg.contains("did not match any variant of untagged enum"),
            "must not regress to the opaque untagged message: {msg}"
        );
        assert!(
            msg.contains("scenes[1]"),
            "must name the offending scene index: {msg}"
        );
        assert!(
            msg.contains("duration"),
            "must name the missing field: {msg}"
        );
    }

    #[test]
    fn misspelled_transition_type_names_itself() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "scenes": [
                {
                    "duration": 1.0,
                    "children": [],
                    "transition": { "type": "wip_left" }
                }
            ]
        }"#;
        let err =
            serde_json::from_str::<Scenario>(json).expect_err("bad transition type must fail");
        let msg = err.to_string();
        assert!(
            !msg.contains("did not match any variant of untagged enum"),
            "must not regress to the opaque untagged message: {msg}"
        );
        assert!(
            msg.contains("scenes[0]"),
            "must name the offending scene index: {msg}"
        );
        assert!(
            msg.contains("wip_left"),
            "must echo the bad value so the author can spot the typo: {msg}"
        );
    }

    #[test]
    fn include_directive_still_works() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "scenes": [
                { "include": "does/not/matter.json" }
            ]
        }"#;
        let s: Scenario = serde_json::from_str(json).expect("include entry must parse");
        assert!(matches!(s.scenes[0], SceneEntry::Include(_)));
    }

    #[test]
    fn broken_include_directive_names_itself() {
        // `scenes` on IncludeDirective must be an array of indices — a typo'd
        // shape should not silently be mistaken for a Scene.
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "scenes": [
                { "include": "x.json", "scenes": "not-an-array" }
            ]
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("must fail");
        let msg = err.to_string();
        assert!(msg.contains("scenes[0]"), "got: {msg}");
        assert!(msg.contains("include directive"), "got: {msg}");
    }

    #[test]
    fn view_scenes_field_uses_the_same_precise_errors() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "composition": [
                { "type": "slide", "scenes": [ { "children": [] } ] }
            ]
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("must fail");
        let msg = err.to_string();
        assert!(
            !msg.contains("did not match any variant of untagged enum"),
            "got: {msg}"
        );
        assert!(msg.contains("scenes[0]"), "got: {msg}");
        assert!(msg.contains("duration"), "got: {msg}");
    }
}

/// M5 (issue #110 / #102): the unknown-attribute checker only ever inspected
/// the top level of each *component*; a typo in `Scenario`/`Scene`/`View`/
/// `VideoConfig`/`SceneLayout`/`Transition`/`Camera` (e.g. `durration` on a
/// scene, `framerate` on `video`) passed silently because nothing checked
/// those structs at all. `deny_unknown_fields` closes that gap directly at
/// parse time, for every one of them.
#[cfg(test)]
mod strict_schema_tests {
    use super::*;

    #[test]
    fn misspelled_scene_field_is_rejected() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "scenes": [ { "durration": 3.0, "children": [] } ]
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("must fail");
        assert!(err.to_string().contains("durration"), "got: {err}");
    }

    #[test]
    fn misspelled_video_field_is_rejected() {
        let json = r#"{
            "video": { "width": 100, "height": 100, "framerate": 30 },
            "scenes": [ { "duration": 1.0, "children": [] } ]
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("must fail");
        assert!(err.to_string().contains("framerate"), "got: {err}");
    }

    #[test]
    fn misspelled_top_level_scenario_field_is_rejected() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "scenes": [ { "duration": 1.0, "children": [] } ],
            "titel": "typo"
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("must fail");
        assert!(err.to_string().contains("titel"), "got: {err}");
    }

    #[test]
    fn misspelled_camera_field_is_rejected() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "scenes": [ {
                "duration": 1.0,
                "children": [],
                "camera": { "zooom": 1.5 }
            } ]
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("must fail");
        assert!(err.to_string().contains("zooom"), "got: {err}");
    }

    #[test]
    fn misspelled_scene_layout_field_is_rejected() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "scenes": [ {
                "duration": 1.0,
                "children": [],
                "layout": { "gapp": 10 }
            } ]
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("must fail");
        assert!(err.to_string().contains("gapp"), "got: {err}");
    }

    #[test]
    fn misspelled_view_field_is_rejected() {
        let json = r#"{
            "video": { "width": 100, "height": 100 },
            "composition": [ { "typ": "slide", "scenes": [] } ]
        }"#;
        let err = serde_json::from_str::<Scenario>(json).expect_err("must fail");
        assert!(err.to_string().contains("typ"), "got: {err}");
    }

    #[test]
    fn valid_scenario_with_every_covered_struct_still_parses() {
        // Regression guard: deny_unknown_fields must not reject any
        // currently-valid field across Scenario/Scene/View/VideoConfig/
        // SceneLayout/Transition/Camera.
        let json = r##"{
            "version": "1.0",
            "video": { "width": 100, "height": 100, "fps": 30, "background": "#000000" },
            "scenes": [ {
                "duration": 1.0,
                "children": [],
                "layout": { "direction": "column", "gap": 10, "align_items": "center", "justify_content": "center", "padding": 5 },
                "transition": { "type": "fade", "duration": 0.5, "easing": "ease_in_out" },
                "camera": { "x": 0, "y": 0, "zoom": 1.0, "rotation": 0, "origin": { "x": 1, "y": 2 }, "keyframes": [ { "property": "zoom", "values": [ { "time": 0.0, "value": 1.0 } ], "easing": "linear" } ] }
            } ]
        }"##;
        let s: Scenario = serde_json::from_str(json).expect("valid scenario must still parse");
        assert_eq!(s.scenes.len(), 1);
    }
}

/// Constat #4 (camera half): `CameraKeyframe.property` is consumed by
/// `interpolate_camera_property` in `crates/rustmotion/src/engine/render/
/// scene.rs` (read-only for this workstream — owned by the sibling GEO
/// workstream this wave), which looks up
/// `camera.keyframes.iter().find(|k| k.property == property)` for each of a
/// *fixed* set of six properties (`"x"`, `"y"`, `"zoom"`, `"rotation"`,
/// `"origin.x"`, `"origin.y"`). A misspelled or wrongly-cased
/// `CameraKeyframe.property` simply never matches that lookup — the track
/// silently falls back to the camera's static value and never animates,
/// with no error anywhere.
#[cfg(test)]
mod camera_keyframe_property_tests {
    use super::*;

    #[test]
    fn known_camera_properties_still_work() {
        for prop in ["x", "y", "zoom", "rotation", "origin.x", "origin.y"] {
            let json = format!(
                r#"{{ "property": "{prop}", "values": [ {{ "time": 0.0, "value": 1.0 }} ] }}"#
            );
            let kf: CameraKeyframe = serde_json::from_str(&json)
                .unwrap_or_else(|e| panic!("property '{prop}' must be accepted, got: {e}"));
            assert_eq!(kf.property, prop);
        }
    }

    #[test]
    fn unknown_camera_property_is_a_named_error_not_a_silent_no_op() {
        let json = r#"{ "property": "tilt", "values": [ { "time": 0.0, "value": 1.0 } ] }"#;
        let err = serde_json::from_str::<CameraKeyframe>(json).expect_err(
            "an unrecognised camera keyframe property must be rejected, not silently inert",
        );
        assert!(err.to_string().contains("tilt"), "got: {err}");
    }

    #[test]
    fn misspelled_origin_property_is_a_named_error() {
        // The documented dotted-compound-property convention
        // (`origin.x`/`origin.y`) is easy to get wrong (`originX`,
        // `origin_x`) — before this fix, any of those silently never
        // animated the camera origin, with the keyframes block accepted
        // and simply ignored.
        let json = r#"{ "property": "origin_x", "values": [ { "time": 0.0, "value": 1.0 } ] }"#;
        let err = serde_json::from_str::<CameraKeyframe>(json)
            .expect_err("origin_x must be rejected — the real property is origin.x");
        let msg = err.to_string();
        assert!(msg.contains("origin_x"), "got: {msg}");
        assert!(
            msg.contains("origin.x"),
            "expected a did-you-mean nudge toward origin.x, got: {msg}"
        );
    }
}