fix(v0.21.0): keep export stage background behind transparent clips

claude · claude · commit f0d0f1798353 · 2026-04-26T18:47:06.000+08:00
session: codex130

What: Resolve the exported stage background from the source theme and apply it to the export stage, add regression BDD coverage, and record the bug-fix evidence.

Why: Draft export was leaking the recorder magenta body canary whenever later clip-first segments used transparent component tracks. The stage should carry the composition background while the canary remains behind it for real viewport holes.

Co-Authored-By: Claude Opus 4.7
diff --git a/crates/nf-recorder/src/export_api.rs b/crates/nf-recorder/src/export_api.rs
@@ -211,6 +211,7 @@ pub async fn run_export_from_source(
     let preset = resolve_export_preset(&source_json, &opts)?;
     override_source_viewport(&mut source_json, preset.viewport);
     let tracks_map_json = build_tracks_map_json(&source_json);
+    let stage_background = resolve_stage_background(&source_json);
     let source_text = serde_json::to_string(&source_json).map_err(|e| {
         RecordError::BundleLoadFailed(format!("serialize source.json for export HTML: {e}"))
     })?;
@@ -223,6 +224,7 @@ pub async fn run_export_from_source(
         vp_w,
         vp_h,
         requested_duration_ms,
+        &stage_background,
     );
 
     // 写 tmp file · macOS /tmp 没 gitignore 问题 · 独占进程 pid + nanos 防撞。
@@ -363,6 +365,56 @@ fn override_source_viewport(source_json: &mut serde_json::Value, viewport: (u32,
     );
 }
 
+fn resolve_stage_background(source_json: &serde_json::Value) -> String {
+    let theme = source_json.get("theme").unwrap_or(&serde_json::Value::Null);
+    for pointer in ["/background", "/bg", "/colors/background", "/colors/bg"] {
+        if let Some(raw) = theme.pointer(pointer).and_then(serde_json::Value::as_str) {
+            if let Some(value) = sanitize_stage_background(raw) {
+                return value;
+            }
+        }
+    }
+
+    if let Some(css) = theme.get("css").and_then(serde_json::Value::as_str) {
+        if let Some(raw) = extract_css_custom_property(css, "--nfv2-bg") {
+            if let Some(value) = sanitize_stage_background(raw) {
+                return value;
+            }
+        }
+    }
+
+    "#000".to_string()
+}
+
+fn extract_css_custom_property<'a>(css: &'a str, name: &str) -> Option<&'a str> {
+    let start = css.find(name)?;
+    let rest = &css[start + name.len()..];
+    let colon = rest.find(':')?;
+    let rest = &rest[colon + 1..];
+    let end = rest.find(';')?;
+    Some(rest[..end].trim())
+}
+
+fn sanitize_stage_background(raw: &str) -> Option<String> {
+    let value = raw.trim();
+    if value.is_empty() || value.len() > 96 || value.contains([';', '{', '}']) {
+        return None;
+    }
+    let lower = value.to_ascii_lowercase();
+    let named = matches!(
+        lower.as_str(),
+        "black" | "white" | "transparent" | "canvas" | "currentcolor"
+    );
+    let functional = lower.starts_with("rgb(")
+        || lower.starts_with("rgba(")
+        || lower.starts_with("hsl(")
+        || lower.starts_with("hsla(");
+    let hex = lower.starts_with('#')
+        && matches!(lower.len(), 4 | 5 | 7 | 9)
+        && lower[1..].chars().all(|ch| ch.is_ascii_hexdigit());
+    (named || functional || hex).then(|| value.to_string())
+}
+
 /// 构造自包含 export HTML · 含 runtime + __NF_SOURCE__ + mount。
 ///
 /// 关键点(ADR-064):
@@ -377,6 +429,7 @@ fn build_export_html(
     vp_w: u32,
     vp_h: u32,
     requested_duration_ms: u64,
+    stage_background: &str,
 ) -> String {
     format!(
         r#"<!DOCTYPE html>
@@ -387,7 +440,7 @@ fn build_export_html(
 <title>nf-export</title>
 <style>
 html,body{{margin:0;padding:0;background:#000;width:{vp_w}px;height:{vp_h}px;overflow:hidden}}
-#nf-stage{{position:absolute;top:0;left:0;width:{vp_w}px;height:{vp_h}px;transform-origin:top left}}
+#nf-stage{{position:absolute;top:0;left:0;width:{vp_w}px;height:{vp_h}px;transform-origin:top left;background:{stage_background}}}
 </style>
 </head>
 <body>
@@ -532,3 +585,31 @@ window.__NF_TRACKS__ = {tracks_map_json};
         runtime = RUNTIME_IIFE,
     )
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn stage_background_uses_theme_css_var() {
+        let source = json!({
+            "theme": {
+                "css": ":root { --nfv2-bg: #05070a; --nfv2-text: #fff; }"
+            }
+        });
+
+        assert_eq!(resolve_stage_background(&source), "#05070a");
+    }
+
+    #[test]
+    fn stage_background_rejects_css_injection() {
+        let source = json!({
+            "theme": {
+                "background": "#000; } body { background: red"
+            }
+        });
+
+        assert_eq!(resolve_stage_background(&source), "#000");
+    }
+}
diff --git a/spec/bdd/clip-first-composition/demos/export-stage-background.html b/spec/bdd/clip-first-composition/demos/export-stage-background.html
@@ -0,0 +1,48 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>export-stage-background</title>
+  <style>
+    html, body { margin: 0; width: 100%; height: 100%; background: #05070a; color: #f6f7f2; font: 16px/1.4 Inter, system-ui, sans-serif; overflow: hidden; }
+    .stage { position: fixed; inset: 0; display: grid; place-items: center; background: #05070a; }
+    .frame { width: min(980px, 86vw); aspect-ratio: 16 / 9; position: relative; overflow: hidden; border: 1px solid rgba(255,255,255,.18); background: #05070a; }
+    .bad, .good { position: absolute; inset: 0; display: grid; place-items: end center; padding-bottom: 42px; box-sizing: border-box; animation: swap 10s infinite; }
+    .bad { background: #ff00ff; }
+    .good { background: #05070a; opacity: 0; }
+    .good i { position: absolute; width: 7px; height: 7px; background: #62f5d2; left: 58%; top: 34%; box-shadow: -210px 30px #c8ff5d, 170px 70px #78a7ff, 60px 180px #62f5d2, -40px 230px #78a7ff; }
+    .subtitle { font-size: 30px; text-shadow: 0 2px 14px rgba(0,0,0,.7); }
+    .toast { position: fixed; right: 24px; bottom: 24px; padding: 10px 14px; border: 1px solid rgba(255,255,255,.18); background: rgba(5,7,10,.82); animation: toast 10s infinite; }
+    .bar { position: fixed; left: 0; right: 0; bottom: 0; height: 4px; background: rgba(255,255,255,.14); }
+    .bar::after { content: ""; display: block; height: 100%; width: 100%; background: #62f5d2; transform-origin: left; animation: progress 10s linear infinite; }
+    @keyframes swap {
+      0%, 38% { opacity: 1; }
+      48%, 100% { opacity: 0; }
+    }
+    .good { animation-name: swapGood; }
+    @keyframes swapGood {
+      0%, 42% { opacity: 0; }
+      52%, 100% { opacity: 1; }
+    }
+    @keyframes progress {
+      from { transform: scaleX(0); }
+      to { transform: scaleX(1); }
+    }
+    @keyframes toast {
+      0%, 82% { opacity: 0; transform: translateY(8px); }
+      88%, 100% { opacity: 1; transform: translateY(0); }
+    }
+  </style>
+</head>
+<body>
+  <main class="stage">
+    <section class="frame" aria-label="Export stage background regression">
+      <div class="bad"><div class="subtitle">Transparent clip exposes magenta canary.</div></div>
+      <div class="good"><i></i><div class="subtitle">Transparent clip renders on the stage background.</div></div>
+    </section>
+  </main>
+  <div class="toast">本轮完成</div>
+  <div class="bar"></div>
+</body>
+</html>
diff --git a/spec/bdd/clip-first-composition/feature.json b/spec/bdd/clip-first-composition/feature.json
@@ -16,7 +16,8 @@
       "export-clip-first",
       "voice-preview-audible",
       "clip-all-and-local-preview",
-      "track-click-stable"
+      "track-click-stable",
+      "export-stage-background"
     ],
     "status": "implemented"
   }
diff --git a/spec/bdd/clip-first-composition/scenarios/export-stage-background.bdd.json b/spec/bdd/clip-first-composition/scenarios/export-stage-background.bdd.json
@@ -0,0 +1,21 @@
+{
+  "id": "export-stage-background",
+  "given": "A clip-first composition stitches transparent component clips after the first clip.",
+  "when": "The user exports a draft MP4 and inspects frames after clip boundaries.",
+  "then": "Later clips render on the composition stage background instead of exposing the recorder magenta canary.",
+  "human_actions": ["export draft", "inspect second clip frame", "inspect third clip frame"],
+  "ai_tools": [
+    {
+      "tool": "export",
+      "command": "NEXTFRAME_HOME=examples target/debug/nf export --project=v2-showcase --composition=showreel-clip-first --profile=draft --diagnostics --out=/tmp/nextframe-clip-first-stage-bg.mp4"
+    },
+    {
+      "tool": "frame",
+      "command": "ffmpeg -y -ss 6 -i /tmp/nextframe-clip-first-stage-bg.mp4 -frames:v 1 /tmp/nextframe-clip-first-stage-bg-06s.png"
+    },
+    {
+      "tool": "pixel",
+      "command": "magick /tmp/nextframe-clip-first-stage-bg-06s.png -format '%[pixel:p{640,360}]' info: # expected srgb(3,5,9), not srgb(255,0,255)"
+    }
+  ]
+}
diff --git a/spec/devlog/02.md b/spec/devlog/02.md
@@ -1,5 +1,62 @@
 ---
 
+## 2026-04-25 14:36 · v0.21.0 · bug-fix · [export, clip-first, recorder]
+
+**Session**: codex130
+
+### 症状
+
+`showreel-clip-first` 草稿导出后，第一个 clip 正常，后续 clip 变成粉色背景屏幕。
+
+### 复现计划
+
+- 用 `nf export --profile draft --diagnostics` 导出当前 clip-first composition。
+- 抽取 1s / 6s / 12s 帧，确认粉屏从哪个 clip 开始。
+- 查 recorder/runtime 是否在组件切换后触发错误 fallback。
+
+### 状态
+
+open。
+
+---
+
+## 2026-04-25 14:44 · v0.21.0 · bug-fix · [export, clip-first, recorder]
+
+**Session**: codex130
+
+### Root cause
+
+Draft export uses a magenta body canary (`#ff00ff`) in record mode to expose uncovered viewport holes.
+The first clip had a full-cover `html.stage-background`, but later transparent component clips (`canvas.particle-field`, title-only outro) did not cover the stage, so the canary leaked into the MP4.
+
+### Fix
+
+- `nf-recorder` export HTML now gives `#nf-stage` a stable background resolved from the source theme (`theme.background`, `theme.bg`, or `theme.css --nfv2-bg`, fallback `#000`).
+- The body canary remains behind the stage, so real stage sizing holes are still detectable.
+- Added unit coverage for theme CSS background extraction and CSS-injection rejection.
+- Added BDD regression `export-stage-background`.
+
+### Verification
+
+- Repro before fix:
+  - `NEXTFRAME_HOME=.../examples target/debug/nf export --project=v2-showcase --composition=showreel-clip-first --profile=draft --diagnostics --out=.../showreel-clip-first-pink-repro.mp4`
+  - 6s and 12s extracted frames were magenta.
+- After fix:
+  - `NEXTFRAME_HOME=.../examples target/debug/nf export --project=v2-showcase --composition=showreel-clip-first --profile=draft --diagnostics --out=.../showreel-clip-first-fixed.mp4`
+  - `magick fixed-frame-06s.png -format '%[pixel:p{640,360}]' info:` -> `srgb(3,5,9)`
+  - `magick fixed-frame-12s.png -format '%[pixel:p{640,360}]' info:` -> `srgb(3,5,9)`
+- `cargo test -p nf-recorder export_api::tests -- --nocapture` passed.
+- `cargo fmt --check && cargo check -p nf-cli -p nf-recorder` passed.
+- `find spec/bdd/clip-first-composition -name '*.json' -print0 | xargs -0 -n1 jq . >/dev/null` passed.
+- `./scripts/check-structure.sh` passed.
+- `./scripts/audit.sh --gate-only` passed, report `spec/quality-reports/2026-04-25-1443.md`.
+
+### 状态
+
+fixed。
+
+---
+
 ## 2026-04-25 14:27 · v0.21.0 · bug-fix · [editor, timeline, perf]
 
 **Session**: codex130
diff --git a/spec/quality-reports/2026-04-25-1443.md b/spec/quality-reports/2026-04-25-1443.md
@@ -0,0 +1,27 @@
+# NextFrame 质量审计 · 2026-04-25 14:43
+
+**版本**: `v0.13.0`
+**模式**: gate
+**总分**: 10.0 / 10
+**门禁**: 2 绿 / 0 红 / 2 N/A (4 硬门禁中)
+
+## 维度打分
+
+| # | 维度 | 硬度 | 分 | 说明 |
+|---|---|---|---|---|
+| G1 | 编译 + lint | 门禁 | **A** | make check 三绿(rust=1 clippy=1 fmt=1 ts=1) |
+| G2 | 架构边界 | 门禁 | **A** | 0 违约 · 依赖方向单向 |
+| P1 | frame pure | 门禁 | **NA** | nf-engine 未实现(4 行) · v0.3+ 上 property test |
+| P2 | 3 模式像素 | 门禁 | **NA** | nf-runtime 未实现(5 行) · v0.3+ 上 diff harness |
+| G3 | AI 可操作 | 报告 | **—** | (未跑) |
+| P3 | 视觉 token | 报告 | **—** | (未跑) |
+| P4 | 零框架 | 报告 | **—** | (未跑) |
+
+## 关注项
+
+- ⚪ **P1** N/A: nf-engine 未实现(4 行) · v0.3+ 上 property test
+- ⚪ **P2** N/A: nf-runtime 未实现(5 行) · v0.3+ 上 diff harness
+
+---
+
+_自动产出 · `./scripts/audit.sh` · 标准见 `spec/standards/`_
