edit/

project.rs

//! [`EditProject`] — the top-level, serializable edit document and the
//! project↔source frame mapping built on top of the segment list.

use serde::{Deserialize, Serialize};

use crate::clip::ClipRef;
use crate::segment::{Frame, TimelineSegment};
use crate::style::{AspectRatio, BackgroundConfig, CropRect, CursorConfig};
use crate::telemetry::{ClickEvent, CursorSample};
use crate::zoom::ZoomSegment;

/// On-disk schema version. Bumped when the project file format changes
/// incompatibly so older files can be migrated (ED.23).
pub const SCHEMA_VERSION: u32 = 1;

/// Default project timeline frame rate. The editor's time authority runs
/// at this rate regardless of the source recording's frame rate.
pub const DEFAULT_PROJECT_FPS: u32 = 30;

fn default_schema_version() -> u32 {
    SCHEMA_VERSION
}

fn default_project_fps() -> u32 {
    DEFAULT_PROJECT_FPS
}

/// The serialized source of truth for one editing session.
///
/// The edited video is the ordered concatenation of [`segments`]; the
/// cinematic framing comes from [`background`] / [`cursor`] / [`crop`] /
/// [`aspect`]; cinematic punch-ins come from [`zooms`]. Nothing here is
/// a GPU or media handle — the renderer and encoder re-derive every
/// frame from this model at preview + export time.
///
/// [`segments`]: Self::segments
/// [`background`]: Self::background
/// [`cursor`]: Self::cursor
/// [`crop`]: Self::crop
/// [`aspect`]: Self::aspect
/// [`zooms`]: Self::zooms
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct EditProject {
    /// On-disk schema version (see [`SCHEMA_VERSION`]).
    #[serde(default = "default_schema_version")]
    pub schema_version: u32,
    /// The source recording this project edits.
    pub source: ClipRef,
    /// Ordered timeline slices (trim / split / speed).
    pub segments: Vec<TimelineSegment>,
    /// Cinematic zoom regions.
    #[serde(default)]
    pub zooms: Vec<ZoomSegment>,
    /// Background framing (wallpaper / padding / radius / shadow).
    #[serde(default)]
    pub background: BackgroundConfig,
    /// Cursor styling + auto-zoom detection settings.
    #[serde(default)]
    pub cursor: CursorConfig,
    /// Optional crop / reframe of the source. `None` = full frame.
    #[serde(default)]
    pub crop: Option<CropRect>,
    /// Output aspect ratio.
    #[serde(default)]
    pub aspect: AspectRatio,
    /// Timeline frame rate (the editor's time authority).
    #[serde(default = "default_project_fps")]
    pub project_fps: u32,
    /// Monotonic counter for allocating fresh [`crate::ZoomId`]s
    /// (managed by edit operations in ED.2).
    #[serde(default)]
    pub next_zoom_id: u32,
    /// Per-frame cursor track captured at record time (ED.17). `None` for
    /// projects recorded before cursor capture, or when the macOS
    /// input-monitoring permission was denied. Drives the cursor overlay
    /// (ED.19).
    #[serde(default)]
    pub cursor_track: Option<Vec<CursorSample>>,
    /// Click log captured at record time. Feeds auto-zoom detection
    /// ([`crate::telemetry::auto_zoom_segments`]) and the cursor click-ripple
    /// overlay (ED.19). `None` = no telemetry captured.
    #[serde(default)]
    pub clicks: Option<Vec<ClickEvent>>,
}

impl EditProject {
    /// Build a fresh project from a source recording: a single,
    /// full-length, real-time segment with default framing and no zooms —
    /// i.e. "the recording, untouched", ready to edit.
    #[must_use]
    pub fn from_recording(source: ClipRef) -> Self {
        let segments = vec![TimelineSegment::new(0, source.frame_count)];
        Self {
            schema_version: SCHEMA_VERSION,
            source,
            segments,
            zooms: Vec::new(),
            background: BackgroundConfig::default(),
            cursor: CursorConfig::default(),
            crop: None,
            aspect: AspectRatio::default(),
            project_fps: DEFAULT_PROJECT_FPS,
            next_zoom_id: 0,
            cursor_track: None,
            clicks: None,
        }
    }

    /// Total length of the edited timeline in **project** frames.
    #[must_use]
    pub fn project_duration(&self) -> Frame {
        self.segments
            .iter()
            .copied()
            .map(TimelineSegment::project_len)
            .sum()
    }

    /// Walk the segments with their cumulative **project-frame** start
    /// offset: yields `(index, project_start, segment)`.
    ///
    /// This is the single accumulation site for the segment→project-time
    /// walk — [`locate`](Self::locate), [`segment_project_range`](Self::segment_project_range),
    /// and the UI's timeline lanes all derive from it instead of
    /// re-implementing the running sum.
    pub fn segment_offsets(&self) -> impl Iterator<Item = (usize, Frame, &TimelineSegment)> + '_ {
        let mut acc: Frame = 0;
        self.segments.iter().enumerate().map(move |(index, seg)| {
            let start = acc;
            acc += seg.project_len();
            (index, start, seg)
        })
    }

    /// The `[start, end)` **project-frame** range occupied by segment
    /// `index`, or `None` if the index is out of range.
    #[must_use]
    pub fn segment_project_range(&self, index: usize) -> Option<(Frame, Frame)> {
        self.segment_offsets()
            .nth(index)
            .map(|(_, start, seg)| (start, start + seg.project_len()))
    }

    /// Locate a project frame: returns `(segment index, source frame)`,
    /// or `None` if the frame is at/past the end of the timeline.
    ///
    /// This is the core of the editor's time model — it walks the segment
    /// list accumulating project-frame lengths until it finds the segment
    /// containing `project_frame`, then maps the within-segment offset to
    /// a source frame via that segment's `timescale`.
    #[must_use]
    pub fn locate(&self, project_frame: Frame) -> Option<(usize, Frame)> {
        self.segment_offsets()
            .find(|(_, start, seg)| project_frame < start + seg.project_len())
            .map(|(index, start, seg)| (index, seg.source_frame_at(project_frame - start)))
    }

    /// Map a project frame to the **source** frame the renderer should
    /// decode, or `None` past the end of the timeline.
    #[must_use]
    pub fn source_time(&self, project_frame: Frame) -> Option<Frame> {
        self.locate(project_frame).map(|(_, frame)| frame)
    }

    /// The composed-output **canvas** dimensions in pixels — the source's
    /// longer edge reframed to the project's [`aspect`](Self::aspect) ratio
    /// (e.g. a 1920×1080 recording → 1080×1920 when `aspect` is `Vertical`).
    /// Both edges are even (H.264 chroma subsampling needs it). The source
    /// frame is letterboxed/pillarboxed into this canvas at render time, so
    /// changing the aspect reframes the export without distorting the content.
    ///
    /// This is the **unclamped** canvas (the live preview composes at it
    /// directly); the export path additionally passes it through
    /// `media::encode::fit_within_encoder_limits` for the HW-encoder edge cap.
    #[must_use]
    pub fn canvas_dims(&self) -> (u32, u32) {
        let long = self.source.width.max(self.source.height).max(2);
        self.aspect.canvas_dims(long)
    }

    /// The normalized `(x, y)` a cursor-targeted zoom should punch into at
    /// project `frame` — the cursor's position there from
    /// [`cursor_track`](Self::cursor_track), or the frame centre `(0.5, 0.5)`
    /// when no track was captured. Pure; the basis for the editor's
    /// "zoom to cursor" authoring action.
    #[must_use]
    pub fn zoom_cursor_target(&self, frame: Frame) -> (f32, f32) {
        self.cursor_track
            .as_deref()
            .and_then(|track| crate::telemetry::cursor_at(track, frame, 0))
            .unwrap_or((0.5, 0.5))
    }

    /// Generate auto-zoom blocks from the captured click log (ED.17 — the
    /// "Auto-Zoom: detect from cursor" feature). Returns the number generated.
    ///
    /// A no-op (returns `0`) unless detection is enabled
    /// ([`CursorConfig::auto_zoom`](crate::style::CursorConfig::auto_zoom)), a
    /// click log is present, **and no zooms exist yet** — so a freshly recorded
    /// clip arrives already punched-in on its click clusters, while a re-opened
    /// edit keeps the zooms the user already tuned (the generator never
    /// clobbers an existing list). The blocks are ordinary editable
    /// [`ZoomSegment`]s ([`crate::telemetry::auto_zoom_segments`]) — the user
    /// nudges, deletes, or retunes them like any other zoom.
    pub fn generate_auto_zooms(&mut self) -> usize {
        if !self.zooms.is_empty() {
            return 0;
        }
        let Some(clicks) = self.clicks.as_deref() else {
            return 0;
        };
        let zooms =
            crate::telemetry::auto_zoom_segments(clicks, self.project_fps, &self.cursor.auto_zoom);
        let n = zooms.len();
        if n > 0 {
            // Keep the id allocator ahead of the generated blocks so a later
            // manual zoom can't collide with an auto one.
            self.next_zoom_id = self.next_zoom_id.max(u32::try_from(n).unwrap_or(u32::MAX));
            self.zooms = zooms;
        }
        n
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::style::CropRect;
    use crate::telemetry::{ClickEvent, CursorSample};
    use crate::zoom::{ZoomId, ZoomSegment};

    fn sample_clip() -> ClipRef {
        ClipRef::new(PathBuf::from("/tmp/rec.mp4"), 1920, 1080, 30, 900)
    }

    use std::path::PathBuf;

    #[test]
    fn from_recording_is_single_full_length_realtime_segment() {
        let proj = EditProject::from_recording(sample_clip());
        assert_eq!(proj.segments.len(), 1);
        assert_eq!(proj.segments[0], TimelineSegment::new(0, 900));
        assert_eq!(proj.project_duration(), 900);
        assert!(proj.zooms.is_empty());
        assert!(proj.crop.is_none());
        assert_eq!(proj.project_fps, DEFAULT_PROJECT_FPS);
        assert_eq!(proj.schema_version, SCHEMA_VERSION);
        assert_eq!(proj.aspect, AspectRatio::Wide);
    }

    #[test]
    fn canvas_dims_reframes_the_source_to_the_aspect() {
        // 1920×1080 source (long edge 1920).
        let mut proj = EditProject::from_recording(sample_clip());
        // Wide (default) keeps the source shape.
        assert_eq!(proj.canvas_dims(), (1920, 1080));
        // Vertical swaps to a 9:16 canvas seeded by the same long edge.
        proj.aspect = AspectRatio::Vertical;
        assert_eq!(proj.canvas_dims(), (1080, 1920));
        // Square → a 1:1 canvas; Classic → 4:3. Both even.
        proj.aspect = AspectRatio::Square;
        assert_eq!(proj.canvas_dims(), (1920, 1920));
        proj.aspect = AspectRatio::Classic;
        let (w, h) = proj.canvas_dims();
        assert_eq!((w, h), (1920, 1440));
        assert_eq!((w & 1, h & 1), (0, 0), "canvas dims are even");
    }

    #[test]
    fn canvas_dims_seeds_from_the_longer_source_edge_for_portrait_sources() {
        // A portrait source (1080×1920, long edge 1920) exported Wide → a
        // 16:9 canvas the portrait content pillarboxes into.
        let mut proj = EditProject::from_recording(ClipRef::new(
            PathBuf::from("/tmp/p.mp4"),
            1080,
            1920,
            30,
            60,
        ));
        assert_eq!(proj.canvas_dims(), (1920, 1080));
        proj.aspect = AspectRatio::Vertical;
        assert_eq!(proj.canvas_dims(), (1080, 1920), "stays full vertical");
    }

    #[test]
    fn generate_auto_zooms_punches_in_on_clicks() {
        let mut proj = EditProject::from_recording(sample_clip());
        // No click log → nothing generated.
        assert_eq!(proj.generate_auto_zooms(), 0);
        assert!(proj.zooms.is_empty());

        // A click → one auto-zoom block (detect_from_cursor defaults on).
        proj.clicks = Some(vec![ClickEvent::new(100, 0.4, 0.6)]);
        let n = proj.generate_auto_zooms();
        assert_eq!(n, 1, "one click cluster → one zoom");
        assert_eq!(proj.zooms.len(), 1);
        assert!(
            proj.next_zoom_id >= 1,
            "id allocator advanced past the auto block"
        );

        // Idempotent: never clobbers an existing (e.g. user-tuned) zoom list.
        proj.clicks = Some(vec![ClickEvent::new(500, 0.2, 0.2)]);
        assert_eq!(proj.generate_auto_zooms(), 0, "guarded by non-empty zooms");
        assert_eq!(proj.zooms.len(), 1);
    }

    #[test]
    fn zoom_cursor_target_uses_the_track_or_falls_back_to_centre() {
        let mut proj = EditProject::from_recording(sample_clip());
        // No track → centre.
        let (cx, cy) = proj.zoom_cursor_target(100);
        assert!(
            (cx - 0.5).abs() < 1e-6 && (cy - 0.5).abs() < 1e-6,
            "no track → centre"
        );
        // With a track → the cursor position at that frame (smoothing 0 = raw).
        proj.cursor_track = Some(vec![
            CursorSample::new(0, 0.1, 0.1),
            CursorSample::new(100, 0.8, 0.3),
        ]);
        let (tx, ty) = proj.zoom_cursor_target(100);
        assert!(
            (tx - 0.8).abs() < 1e-6 && (ty - 0.3).abs() < 1e-6,
            "track → cursor at frame"
        );
    }

    #[test]
    fn generate_auto_zooms_respects_the_detect_toggle() {
        let mut proj = EditProject::from_recording(sample_clip());
        proj.cursor.auto_zoom.detect_from_cursor = false;
        proj.clicks = Some(vec![ClickEvent::new(100, 0.5, 0.5)]);
        assert_eq!(proj.generate_auto_zooms(), 0, "detection off → no zooms");
        assert!(proj.zooms.is_empty());
    }

    #[test]
    fn source_time_walks_segments_including_a_speed_segment() {
        let mut proj = EditProject::from_recording(sample_clip());
        // seg0: src[0,300) real-time   → 300 project frames (project 0..300)
        // seg1: src[300,600) at 2×     → 150 project frames (project 300..450)
        // seg2: src[600,900) real-time → 300 project frames (project 450..750)
        proj.segments = vec![
            TimelineSegment::new(0, 300),
            TimelineSegment::with_speed(300, 600, 2.0),
            TimelineSegment::new(600, 900),
        ];
        assert_eq!(proj.project_duration(), 300 + 150 + 300);

        assert_eq!(proj.source_time(0), Some(0));
        assert_eq!(proj.source_time(299), Some(299));
        // First project frame of the 2× segment maps to its source start.
        assert_eq!(proj.source_time(300), Some(300));
        // Mid 2× segment: project offset 75 → source 300 + 150 = 450.
        assert_eq!(proj.source_time(375), Some(450));
        // First project frame of the final real-time segment.
        assert_eq!(proj.source_time(450), Some(600));
        assert_eq!(proj.source_time(749), Some(899));
        // Past the end of the timeline.
        assert_eq!(proj.source_time(750), None);
    }

    #[test]
    fn segment_offsets_and_ranges_are_the_canonical_walk() {
        let mut proj = EditProject::from_recording(sample_clip());
        // [0,300) real → project [0,300); [300,600) 2× → project [300,450);
        // [600,900) real → project [450,750).
        proj.segments = vec![
            TimelineSegment::new(0, 300),
            TimelineSegment::with_speed(300, 600, 2.0),
            TimelineSegment::new(600, 900),
        ];
        let offsets: Vec<_> = proj
            .segment_offsets()
            .map(|(i, start, seg)| (i, start, seg.project_len()))
            .collect();
        assert_eq!(offsets, vec![(0, 0, 300), (1, 300, 150), (2, 450, 300)]);
        assert_eq!(proj.segment_project_range(0), Some((0, 300)));
        assert_eq!(proj.segment_project_range(1), Some((300, 450)));
        assert_eq!(proj.segment_project_range(2), Some((450, 750)));
        assert_eq!(proj.segment_project_range(3), None);
    }

    #[test]
    fn locate_returns_segment_index() {
        let mut proj = EditProject::from_recording(sample_clip());
        proj.segments = vec![TimelineSegment::new(0, 300), TimelineSegment::new(300, 900)];
        assert_eq!(proj.locate(0), Some((0, 0)));
        assert_eq!(proj.locate(299), Some((0, 299)));
        assert_eq!(proj.locate(300), Some((1, 300)));
        assert_eq!(proj.locate(899), Some((1, 899)));
        assert_eq!(proj.locate(900), None);
    }

    #[test]
    fn serde_round_trip_is_lossless() {
        let mut proj = EditProject::from_recording(sample_clip());
        proj.segments = vec![
            TimelineSegment::new(0, 300),
            TimelineSegment::with_speed(300, 600, 2.0),
            TimelineSegment::new(600, 900),
        ];
        proj.zooms = vec![ZoomSegment::manual(ZoomId(0), 30, 90, 1.6)];
        proj.next_zoom_id = 1;
        proj.crop = Some(CropRect {
            x: 0.1,
            y: 0.0,
            width: 0.8,
            height: 1.0,
        });
        proj.aspect = AspectRatio::Vertical;
        // ED.17/ED.19 telemetry round-trips losslessly too.
        proj.cursor_track = Some(vec![
            CursorSample::new(0, 0.1, 0.2),
            CursorSample::new(15, 0.5, 0.5),
        ]);
        proj.clicks = Some(vec![ClickEvent::new(15, 0.5, 0.5)]);

        let json = serde_json::to_string_pretty(&proj).expect("serialize");
        let back: EditProject = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(proj, back);
    }

    #[test]
    fn missing_optional_fields_deserialize_to_defaults() {
        // A minimal project file (only required fields) should fill the
        // rest from defaults — the forward-compat path for ED.23.
        let json = r#"{
            "source": { "path": "/tmp/x.mp4", "width": 1280, "height": 720, "source_fps": 30, "frame_count": 600 },
            "segments": [ { "source_start": 0, "source_end": 600, "timescale": 1.0 } ]
        }"#;
        let proj: EditProject = serde_json::from_str(json).expect("deserialize minimal");
        assert_eq!(proj.schema_version, SCHEMA_VERSION);
        assert_eq!(proj.project_fps, DEFAULT_PROJECT_FPS);
        assert_eq!(proj.aspect, AspectRatio::Wide);
        assert!(proj.zooms.is_empty());
        assert!(proj.crop.is_none());
        assert_eq!(proj.background, BackgroundConfig::default());
        assert_eq!(proj.project_duration(), 600);
        // A pre-ED.17 project (no telemetry fields) deserializes with the
        // track/clicks absent — forward-compat for cursor capture.
        assert!(proj.cursor_track.is_none());
        assert!(proj.clicks.is_none());
    }

    #[test]
    fn from_recording_has_no_telemetry() {
        // A fresh project carries no cursor track or click log until capture
        // (ED.17) attaches one at Record→Edit import.
        let proj = EditProject::from_recording(sample_clip());
        assert!(proj.cursor_track.is_none());
        assert!(proj.clicks.is_none());
    }
}