feat(v0.22.0): add stable export source contract

session: 7b54e560

What: add render_source.v1 fields, composition compile, recorder source validate/export/snapshot, and MP4 verify-export frame checks.

Why: split AI authoring from recorder input so export uses a fixed contract, preventing clip-order/state bugs such as later clips rendering with the wrong background while keeping nf export as the compatibility wrapper.

Co-Authored-By: Claude Opus 4.7

Author: claude

CLAUDE.md

@@ -23,10 +23,15 @@ Example projects live under `examples/`; runtime projects are copied to `~/.next
 `target/debug/nf composition show --project=<slug> --composition=<slug> [--clip=<id>] [--track=<id>] [--item=<id>] [--field=<path>]` — read raw composition JSON or one clip/track/item field.
 `target/debug/nf composition patch --project=<slug> --composition=<slug> [--clip=<id>] --track=<id> [--item=<id>] --field=<path> --value=<json-or-string>` — patch one track or clip item field such as `params.title`, `style.x`, or `time.start`.
 `target/debug/nf composition validate --project=<slug> --composition=<slug>` — validate component registry, files, mount/update exports, import-free ABI, used tracks, and observed params.
+`target/debug/nf composition compile --project=<slug> --composition=<slug> --out=<render_source.json>` — compile AI-authored composition JSON into stable `nf.render_source.v1` recorder input.
 `target/debug/nf verify --project=<slug> --composition=<slug> [--out=<json>] [--screenshot-dir=<dir>]` — verify AI-authored composition JSON: component ABI, compiled source, overlap intent, anchor guide, ASCII timeline, layout/text checks, and typical screenshot commands.
+`target/debug/nf-recorder validate-source --source=<render_source.json>` — validate recorder input contract without reading project storage or desktop state.
+`target/debug/nf-recorder export --source=<render_source.json> --profile=draft|standard|final|final-fast --output=<mp4> [--diagnostics=<json>]` — export directly from render source through the recorder module.
+`target/debug/nf-recorder snapshot-source --source=<render_source.json> --t-ms=<ms> --output=<png>` — sample one render-source frame through the same recorder HTML/runtime path.
 `target/debug/nf export --project=<slug> --composition=<slug> --profile=draft|standard|final|final-fast --out=<mp4>` — export a composition to MP4 with a named quality/speed profile.
 `target/debug/nf export --project=<slug> --composition=<slug> --profile=draft --diagnostics --out=<mp4>` — export and write a sibling diagnostics JSON with frame timings, slow spans, and top slow frames.
 `target/debug/nf export --project=<slug> --composition=<slug> --fps=30|60 --resolution=720p|1080p|4k --parallel=<1-8> --events --out=<mp4>` — override export settings and stream recorder progress JSONL before the final summary JSON.
+`target/debug/nf verify-export --source=<render_source.json> --video=<mp4> --out=<report.json>` — sample exported MP4 clip frames and fail on magenta-background or blank-frame regressions.
 `target/debug/nf export-status --job-id=<id>` — read desktop export job status, including progress and diagnostics summary/path when available.
 `target/debug/nf export-cancel --job-id=<id>` — cancel a running desktop export job and stop its recorder process group.
 `./scripts/check-structure.sh` — verify repository skeleton: root allowlist, no nested spec git, no tracked generated artifacts.
@@ -44,9 +49,9 @@ Do not write generated videos, screenshots, node_modules, Cargo targets, or one-
 
 ## Current Focus
 
-v0.21.0 makes composition authoring clip-first: a composition is the whole video, each top-level clip is one video segment, and each clip owns local anchors, tracks, TTS, subtitle_timeline, and subtitles.
+v0.22.0 hardens export contracts: AI writes `composition.json`, `nf composition compile` emits `render_source.v1`, `nf-recorder` accepts only that source contract, and `nf verify-export` checks final MP4 frames against clip windows.
 
 Specs and acceptance scenarios:
 
-- `spec/versions/v0.21.0/spec.json`
-- `spec/bdd/clip-first-composition/feature.json`
+- `spec/bdd/clip-first-export/feature.json`
+- `spec/bdd/clip-first-export/contracts/render-source-v1.md`

Cargo.lock

@@ -19,6 +19,7 @@ directories.workspace = true
 interprocess.workspace = true
 nf-project = { path = "../nf-project" }
 nf-recorder = { path = "../nf-recorder" }
+png = "0.17"
 serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true

crates/nf-cli/Cargo.toml

@@ -1,4 +1,8 @@
-use nf_project::{JsonStorage, Storage, validate_composition_components};
+use std::fs;
+
+use nf_project::{
+    JsonStorage, Storage, compile_composition_source, validate_composition_components,
+};
 use serde_json::{Value, json};
 
 use crate::commands::{CompositionCommand, CompositionSubcommand, print_json, send_ipc};
@@ -30,7 +34,34 @@ pub fn dispatch(args: CompositionCommand) -> Result<(), NfError> {
             }),
         ),
         CompositionSubcommand::Validate(args) => validate(args.project, args.composition),
+        CompositionSubcommand::Compile(args) => compile(args.project, args.composition, args.out),
+    }
+}
+
+fn compile(project: String, composition: String, out: std::path::PathBuf) -> Result<(), NfError> {
+    let storage = JsonStorage::new(JsonStorage::default_root()?);
+    storage.load_project(&project)?;
+    if !storage.composition_exists(&project, &composition)? {
+        return Err(NfError::ValidationFailed(format!(
+            "composition not found: {project}/{composition}"
+        )));
+    }
+    let composition_json = storage.load_composition(&project, &composition)?;
+    let compiled = compile_composition_source(&storage, &project, &composition_json)?;
+    if let Some(parent) = out.parent().filter(|parent| !parent.as_os_str().is_empty()) {
+        fs::create_dir_all(parent).map_err(|err| NfError::StorageFailed(err.to_string()))?;
     }
+    let bytes = serde_json::to_vec_pretty(&compiled.source)?;
+    fs::write(&out, bytes).map_err(|err| NfError::StorageFailed(err.to_string()))?;
+    print_json(&json!({
+        "project": project,
+        "composition": composition,
+        "out": out.display().to_string(),
+        "schema_version": compiled.source.get("schema_version").and_then(Value::as_str),
+        "duration_ms": compiled.source.get("duration_ms").and_then(Value::as_u64),
+        "tracks": compiled.source.get("tracks").and_then(Value::as_array).map(Vec::len).unwrap_or(0),
+        "warnings": compiled.warnings
+    }))
 }
 
 fn validate(project: String, composition: String) -> Result<(), NfError> {

crates/nf-cli/src/commands/compositions.rs

@@ -19,6 +19,7 @@ pub mod poster_import;
 pub mod projects;
 pub mod utility;
 pub mod verify;
+pub mod verify_export;
 
 #[derive(Debug, Parser)]
 #[command(
@@ -213,6 +214,26 @@ COMMON ERRORS:
     - invalid timeline words -> exit 2 · hint: timeline words must use word/start_ms/end_ms"#
     )]
     PosterImport(PosterImportArgs),
+    #[command(
+        name = "verify-export",
+        about = "Verify exported MP4 against render_source.v1 clip windows",
+        long_about = r#"Verify a final exported MP4 by sampling clip windows from the render_source.v1 contract.
+
+USAGE:
+    nf verify-export --source=<render_source.json> --video=<out.mp4> --out=<report.json>
+
+EXAMPLES:
+    nf verify-export --source=tmp/showreel.render_source.json --video=tmp/showreel.mp4 --out=tmp/showreel.verify-export.json
+
+EXPECTED JSON:
+    {"ok":true,"checks":[{"clip":"intro","t_ms":2600,"status":"pass"}],"frames_dir":"tmp/verify-export-frames"}
+
+COMMON ERRORS:
+    - source invalid -> exit 2 · hint: run `nf-recorder validate-source --source=<json>`
+    - video missing -> exit 2 · hint: run `nf-recorder export --source=<json> --profile=draft -o <mp4>`
+    - ffmpeg missing -> exit 2 · hint: install ffmpeg to enable frame sampling"#
+    )]
+    VerifyExport(VerifyExportArgs),
     #[command(
         name = "export-status",
         about = "Read a running desktop export job status",
@@ -441,14 +462,17 @@ USAGE:
     nf composition show --project=<slug> --composition=<slug> [--track=<id>] [--field=<path>]
     nf composition patch --project=<slug> --composition=<slug> --track=<id> --field=<path> --value=<json-or-string>
     nf composition validate --project=<slug> --composition=<slug>
+    nf composition compile --project=<slug> --composition=<slug> --out=<render_source.json>
 
 EXAMPLES:
     nf composition show --project=v2-showcase --composition=showreel-24s --track=final-title --field=params.title
     nf composition patch --project=v2-showcase --composition=showreel-24s --track=final-title --field=params.title --value='NEXTFRAME LIVE EDIT'
     nf composition validate --project=v2-showcase --composition=showreel-24s
+    nf composition compile --project=v2-showcase --composition=showreel-clip-first --out=tmp/showreel.render_source.json
 
 EXPECTED JSON:
     {"composition":{...},"source":{...},"warnings":[]}
+    {"project":"v2-showcase","composition":"showreel-clip-first","out":"tmp/showreel.render_source.json","schema_version":"nf.render_source.v1","duration_ms":16400,"warnings":[]}
     {"ok":true,"components":[...],"errors":[]}
 
 COMMON ERRORS:
@@ -966,6 +990,8 @@ pub enum CompositionSubcommand {
     Patch(CompositionPatchArgs),
     #[command(about = "Validate composition component registry and component ABI")]
     Validate(CompositionValidateArgs),
+    #[command(about = "Compile composition.json into stable render_source.v1 JSON")]
+    Compile(CompositionCompileArgs),
 }
 
 #[derive(Debug, Args)]
@@ -1054,6 +1080,34 @@ pub struct CompositionValidateArgs {
     pub composition: String,
 }
 
+#[derive(Debug, Args)]
+pub struct CompositionCompileArgs {
+    #[arg(
+        long,
+        value_name = "SLUG",
+        help = "Project slug, for example v2-showcase"
+    )]
+    pub project: String,
+    #[arg(
+        long,
+        value_name = "SLUG",
+        help = "Composition slug, for example showreel-clip-first"
+    )]
+    pub composition: String,
+    #[arg(long, value_name = "JSON", help = "Output render_source.v1 JSON path")]
+    pub out: PathBuf,
+}
+
+#[derive(Debug, Args)]
+pub struct VerifyExportArgs {
+    #[arg(long, value_name = "JSON", help = "Input render_source.v1 JSON path")]
+    pub source: PathBuf,
+    #[arg(long, value_name = "MP4", help = "Exported MP4 path to inspect")]
+    pub video: PathBuf,
+    #[arg(long, value_name = "JSON", help = "Output verification report JSON")]
+    pub out: PathBuf,
+}
+
 #[derive(Debug, Subcommand)]
 pub enum ProjectSubcommand {
     #[command(