feat(v0.14.0): wire voice subtitle preview loop

session: codex-2026-04-24-v014-build

What: Add v2 subtitle tracks to the showreel, render synced subtitle overlays in desktop preview, expose audio/subtitle tracks in the inspector, support array field patch paths, add a voice/subtitle smoke composition, and record build evidence plus the full-showreel export blocker.

Why: The next product slice needs the visible voice+subtitle loop in the editor before the larger showreel export performance issue is solved. The smoke export proves the saved JSON -> source -> MP4 audio/subtitle path while keeping the 24s showreel performance failure explicit instead of hiding it.

Co-Authored-By: Claude Opus 4.7

Author: claude

CLAUDE.md

@@ -15,7 +15,8 @@ Example projects live under `examples/`; runtime projects are copied to `~/.next
 ## AI 验证接口
 
 `target/debug/nf open --project=<slug> --composition=<slug>` — open a v2 composition in the desktop editor.
-`target/debug/nf screenshot --project=<slug> --episode=<slug> --region=editor --out=<png>` — capture a desktop editor region.
+`target/debug/nf screenshot --project=<slug> --episode=<slug> --region=editor --out=<png>` — probe a desktop editor region and write a size stub PNG; use `capture` for visual evidence.
+`target/debug/nf capture --project=<slug> --episode=<slug> --out=<png>` — capture the native macOS window PNG for real visual verification.
 `target/debug/nf devtools --project=<slug> --episode=<slug> --query=<css> --get=<prop>` — inspect live DOM, including shadow DOM selectors.
 `target/debug/nf composition show --project=<slug> --composition=<slug> [--track=<id>] [--field=<path>]` — read raw v2 composition JSON or one track field.
 `target/debug/nf composition patch --project=<slug> --composition=<slug> --track=<id> --field=<path> --value=<json-or-string>` — patch one v2 track field such as `params.title`, `style.x`, or `time.start`.
@@ -38,9 +39,9 @@ Do not write generated videos, screenshots, node_modules, Cargo targets, or one-
 
 ## Current Focus
 
-v0.13.0 is the project skeleton governance version: clean root layout, spec in the main repo, archived generated artifacts, refreshed entry docs, and a structure gate.
+v0.14.0 is the voice/subtitle loop version: JSON carries paired voice and subtitle tracks, the desktop editor previews and edits subtitles, and smoke export proves AAC audio plus burned-in captions. Full 24s showreel export is still blocked by recorder performance near the finale.
 
 Specs and acceptance scenarios:
 
-- `spec/versions/v0.13.0/spec.json`
-- `spec/bdd/repo-skeleton-governance/feature.json`
+- `spec/versions/v0.14.0/spec.json`
+- `spec/bdd/voice-subtitle-loop/feature.json`

crates/nf-project/src/lib.rs

@@ -2,6 +2,7 @@ use std::collections::BTreeMap;
 use std::fs;
 use std::io::Write;
 use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
 
 use directories::BaseDirs;
 use once_cell::sync::Lazy;
@@ -231,7 +232,7 @@ pub fn atomic_write<T: Serialize>(path: &Path, value: &T) -> Result<(), ProjectE
         fs::create_dir_all(parent).map_err(|err| ProjectError::StorageFailed(err.to_string()))?;
     }
 
-    let tmp_path = path.with_extension("tmp");
+    let tmp_path = unique_tmp_path(path);
     let result = (|| -> Result<(), ProjectError> {
         let json = serde_json::to_string_pretty(value)?;
         let mut tmp = fs::File::create(&tmp_path)?;
@@ -249,6 +250,18 @@ pub fn atomic_write<T: Serialize>(path: &Path, value: &T) -> Result<(), ProjectE
     result
 }
 
+fn unique_tmp_path(path: &Path) -> PathBuf {
+    let nonce = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_nanos())
+        .unwrap_or(0);
+    let file_name = path
+        .file_name()
+        .and_then(|value| value.to_str())
+        .unwrap_or("nextframe.json");
+    path.with_file_name(format!("{file_name}.tmp-{}-{nonce}", std::process::id()))
+}
+
 fn read_json<T: for<'de> Deserialize<'de>>(path: &Path) -> Result<T, ProjectError> {
     let raw =
         fs::read_to_string(path).map_err(|err| ProjectError::StorageFailed(err.to_string()))?;

crates/nf-shell/src/handlers/compositions.rs

@@ -123,7 +123,11 @@ fn select_composition_value(composition: &Value, params: &Value) -> Result<Value
 fn get_field_path<'a>(value: &'a Value, field: &str) -> Option<&'a Value> {
     let mut current = value;
     for part in field.split('.').map(str::trim).filter(|part| !part.is_empty()) {
-        current = current.get(part)?;
+        if let Some(index) = path_index(part) {
+            current = current.as_array()?.get(index)?;
+        } else {
+            current = current.get(part)?;
+        }
     }
     Some(current)
 }
@@ -137,17 +141,73 @@ fn set_field_path(target: &mut Value, field: &str, value: Value) -> Result<(), N
     if parts.is_empty() {
         return Err(NfError::ValidationFailed("field path is required".to_string()));
     }
-    let mut current = target;
-    for part in &parts[..parts.len() - 1] {
-        if !current.get(part).is_some_and(Value::is_object) {
-            current[part] = json!({});
+    set_path_part(target, &parts, value, field)
+}
+
+fn set_path_part(target: &mut Value, parts: &[&str], value: Value, field: &str) -> Result<(), NfError> {
+    let Some((part, rest)) = parts.split_first() else {
+        *target = value;
+        return Ok(());
+    };
+    if rest.is_empty() {
+        if let Some(index) = path_index(part) {
+            ensure_array(target);
+            let array = target
+                .as_array_mut()
+                .ok_or_else(|| NfError::ValidationFailed(format!("invalid array path: {field}")))?;
+            if array.len() <= index {
+                array.resize(index + 1, Value::Null);
+            }
+            array[index] = value;
+            return Ok(());
+        }
+        ensure_object(target);
+        target[*part] = value;
+        return Ok(());
+    }
+
+    let next_is_array = path_index(rest[0]).is_some();
+    if let Some(index) = path_index(part) {
+        ensure_array(target);
+        let array = target
+            .as_array_mut()
+            .ok_or_else(|| NfError::ValidationFailed(format!("invalid array path: {field}")))?;
+        if array.len() <= index {
+            array.resize(index + 1, Value::Null);
         }
-        current = current
-            .get_mut(part)
-            .ok_or_else(|| NfError::ValidationFailed(format!("invalid field path: {field}")))?;
+        if !array[index].is_object() && !array[index].is_array() {
+            array[index] = if next_is_array { json!([]) } else { json!({}) };
+        }
+        return set_path_part(&mut array[index], rest, value, field);
+    }
+
+    ensure_object(target);
+    if !target.get(part).is_some_and(|item| item.is_object() || item.is_array()) {
+        target[*part] = if next_is_array { json!([]) } else { json!({}) };
+    }
+    let child = target
+        .get_mut(part)
+        .ok_or_else(|| NfError::ValidationFailed(format!("invalid field path: {field}")))?;
+    set_path_part(child, rest, value, field)
+}
+
+fn ensure_object(value: &mut Value) {
+    if !value.is_object() {
+        *value = json!({});
+    }
+}
+
+fn ensure_array(value: &mut Value) {
+    if !value.is_array() {
+        *value = json!([]);
+    }
+}
+
+fn path_index(part: &str) -> Option<usize> {
+    if part.is_empty() || (part.len() > 1 && part.starts_with('0')) {
+        return None;
     }
-    current[parts[parts.len() - 1]] = value;
-    Ok(())
+    part.parse::<usize>().ok()
 }
 
 impl OpHandler for CompositionsOpHandler {

crates/nf-tracks/official/subtitle.js

@@ -333,7 +333,7 @@ export function render(t, params, viewport) {
     containerStyle +
     '">' +
     _vpTag +
-    spanParts.join("") +
+    spanParts.join(" ") +
     "</div>"
   );
 }

examples/v2-showcase/compositions/showreel-24s.json

@@ -141,6 +141,66 @@
         "steps": ["JSON", "DOM", "SVG", "Canvas", "Edit", "Export"]
       }
     },
+    {
+      "id": "subtitle-main",
+      "kind": "subtitle",
+      "z": 80,
+      "time": { "start": "intro", "end": "out" },
+      "style": {
+        "active_color": "#ffca66",
+        "color": "#ffffff",
+        "size_px": 34,
+        "position": "bottom",
+        "padding": 62
+      },
+      "params": {
+        "words": [
+          { "text": "One", "start_ms": 0, "end_ms": 420 },
+          { "text": "JSON", "start_ms": 420, "end_ms": 920 },
+          { "text": "drives", "start_ms": 920, "end_ms": 1320 },
+          { "text": "the", "start_ms": 1320, "end_ms": 1540 },
+          { "text": "whole", "start_ms": 1540, "end_ms": 1980 },
+          { "text": "video.", "start_ms": 1980, "end_ms": 2520 },
+          { "text": "HTML,", "start_ms": 3180, "end_ms": 3700 },
+          { "text": "SVG,", "start_ms": 3700, "end_ms": 4140 },
+          { "text": "Canvas,", "start_ms": 4140, "end_ms": 4680 },
+          { "text": "CSS", "start_ms": 4680, "end_ms": 5060 },
+          { "text": "motion", "start_ms": 5060, "end_ms": 5560 },
+          { "text": "share", "start_ms": 5560, "end_ms": 6020 },
+          { "text": "one", "start_ms": 6020, "end_ms": 6300 },
+          { "text": "timeline.", "start_ms": 6300, "end_ms": 7040 },
+          { "text": "The", "start_ms": 7600, "end_ms": 7900 },
+          { "text": "editor", "start_ms": 7900, "end_ms": 8420 },
+          { "text": "changes", "start_ms": 8420, "end_ms": 9020 },
+          { "text": "the", "start_ms": 9020, "end_ms": 9300 },
+          { "text": "saved", "start_ms": 9300, "end_ms": 9780 },
+          { "text": "JSON.", "start_ms": 9780, "end_ms": 10420 },
+          { "text": "Preview", "start_ms": 11600, "end_ms": 12140 },
+          { "text": "and", "start_ms": 12140, "end_ms": 12440 },
+          { "text": "export", "start_ms": 12440, "end_ms": 13020 },
+          { "text": "read", "start_ms": 13020, "end_ms": 13420 },
+          { "text": "that", "start_ms": 13420, "end_ms": 13780 },
+          { "text": "same", "start_ms": 13780, "end_ms": 14220 },
+          { "text": "file.", "start_ms": 14220, "end_ms": 14820 },
+          { "text": "Voice", "start_ms": 15600, "end_ms": 16080 },
+          { "text": "and", "start_ms": 16080, "end_ms": 16380 },
+          { "text": "subtitles", "start_ms": 16380, "end_ms": 17140 },
+          { "text": "stay", "start_ms": 17140, "end_ms": 17540 },
+          { "text": "locked", "start_ms": 17540, "end_ms": 18120 },
+          { "text": "to", "start_ms": 18120, "end_ms": 18360 },
+          { "text": "the", "start_ms": 18360, "end_ms": 18620 },
+          { "text": "playhead.", "start_ms": 18620, "end_ms": 19440 },
+          { "text": "The", "start_ms": 20000, "end_ms": 20320 },
+          { "text": "final", "start_ms": 20320, "end_ms": 20780 },
+          { "text": "MP4", "start_ms": 20780, "end_ms": 21320 },
+          { "text": "keeps", "start_ms": 21320, "end_ms": 21740 },
+          { "text": "both", "start_ms": 21740, "end_ms": 22160 },
+          { "text": "sound", "start_ms": 22160, "end_ms": 22680 },
+          { "text": "and", "start_ms": 22680, "end_ms": 22980 },
+          { "text": "captions.", "start_ms": 22980, "end_ms": 23840 }
+        ]
+      }
+    },
     {
       "id": "voice-intro",
       "kind": "audio",

examples/v2-showcase/compositions/voice-subtitle-smoke.json

@@ -0,0 +1,54 @@
+{
+  "schema": "nextframe.composition.v2",
+  "id": "voice-subtitle-smoke",
+  "name": "Voice Subtitle Smoke",
+  "duration": "4s",
+  "viewport": { "w": 1920, "h": 1080, "ratio": "16:9" },
+  "theme": "launch.dark",
+  "export": { "resolution": "720p" },
+  "anchors": {
+    "intro": "0s",
+    "out": "4s"
+  },
+  "tracks": [
+    {
+      "id": "stage-bg",
+      "kind": "component",
+      "component": "html.stage-background",
+      "z": 0,
+      "time": { "start": "intro", "end": "out" },
+      "params": {
+        "pulse": 0.95
+      }
+    },
+    {
+      "id": "subtitle-main",
+      "kind": "subtitle",
+      "z": 80,
+      "time": { "start": "intro", "end": "out" },
+      "style": {
+        "active_color": "#ffca66",
+        "color": "#ffffff",
+        "size_px": 42,
+        "position": "bottom",
+        "padding": 68
+      },
+      "params": {
+        "words": [
+          { "text": "JSON", "start_ms": 0, "end_ms": 600 },
+          { "text": "edits", "start_ms": 600, "end_ms": 1180 },
+          { "text": "become", "start_ms": 1180, "end_ms": 1780 },
+          { "text": "live", "start_ms": 1780, "end_ms": 2280 },
+          { "text": "captions.", "start_ms": 2280, "end_ms": 3400 }
+        ]
+      }
+    },
+    {
+      "id": "voice-main",
+      "kind": "audio",
+      "time": { "start": "intro", "end": "out" },
+      "src": "audio/showreel-narration.mp3",
+      "volume": 1
+    }
+  ]
+}

frontend/nf-components/src/components/inspector.ts

@@ -324,7 +324,7 @@ export class NfInspector extends NfBase {
     const voiceError = this.getAttribute("voice-error") ?? "";
     const voiceAudio = this.getAttribute("voice-audio") ?? "";
     const compositionTrackId = clip?.track_id ?? clip?.id ?? clipId ?? "";
-    const compositionTrack = clip?.kind === "component" ? getCompositionTrack(compositionTrackId) : undefined;
+    const compositionTrack = compositionTrackId ? getCompositionTrack(compositionTrackId) : undefined;
     if (compositionTrack) {
       this.renderCompositionTrack({
         trackId: compositionTrackId,
@@ -484,10 +484,15 @@ export class NfInspector extends NfBase {
     exportProfile: string;
     exportProgress: ExportProgressState;
   }): void {
-    const component = stringValue(state.track.component) ?? "component";
+    const kind = stringValue(state.track.kind) ?? "component";
+    const component = stringValue(state.track.component) ?? kind;
     const time = recordValue(state.track.time);
     const params = recordValue(state.track.params);
     const style = recordValue(state.track.style);
+    const topLevelFields = [
+      state.track.src !== undefined ? this.compositionField("src", state.track.src, "src") : "",
+      state.track.volume !== undefined ? this.compositionField("volume", state.track.volume, "volume") : "",
+    ].join("");
     this.root.innerHTML = `
       <div class="insp" data-inspector-track-id="${escapeAttr(state.trackId)}">
         ${renderExportPanel(state)}
@@ -503,6 +508,12 @@ export class NfInspector extends NfBase {
           <span class="n">${escapeHtml(state.trackId)}</span>
           <span class="m">${escapeHtml(component)} · ${state.duration.toFixed(1)}s</span>
         </div>
+        ${topLevelFields ? `
+          <div class="insp-card">
+            <h4>轨道</h4>
+            ${topLevelFields}
+          </div>
+        ` : ""}
         <div class="insp-card">
           <h4>时间</h4>
           ${this.compositionField("time.start", time.start ?? "", "start")}