spec(v0.22.0): add clip-first export expectation pack

session: codex130

What: Add a feature-scoped expectation pack with BDD scenarios, visual animation, TTS voice asset, expected keyframes, fixtures, and render_source contract draft for clip-first export.

Why: The next development mode should let PM review the final feature outcome before module implementation. Feature acceptance becomes the organizing unit, while recorder/compiler/verifier contracts serve that acceptance flow.

Co-Authored-By: Claude Opus 4.7

Author: claude

spec/bdd/clip-first-export/contracts/render-source-v1.md

@@ -0,0 +1,27 @@
+# nf.render_source.v1 Contract Draft
+
+`render_source.json` is the recorder/runtime input. It is generated by the compiler from AI-authored `composition.json`.
+
+Recorder accepts this contract only. Recorder must not read project storage, desktop state, selected clip state, or authoring-only anchor expressions.
+
+Required fields:
+
+- `schema_version`: `"nf.render_source.v1"`
+- `duration_ms`: whole video duration in milliseconds
+- `viewport`: `{ "w": number, "h": number }`
+- `theme.background`: stage background used behind transparent components
+- `tracks[]`: resolved render tracks with numeric `begin_ms` / `end_ms`
+- `components`: component source registry needed by component tracks
+- `assets[]`: explicit local or data assets needed for render/export
+
+Primary commands:
+
+```bash
+nf composition compile --project=<slug> --composition=<slug> --out=<source.json>
+nf-recorder validate-source --source=<source.json>
+nf-recorder export --source=<source.json> --profile=draft --out=<video.mp4> --diagnostics=<diagnostics.json>
+nf-recorder snapshot --source=<source.json> --t-ms=<ms> --out=<frame.png>
+nf verify-export --source=<source.json> --video=<video.mp4> --out=<report.json>
+```
+
+Failure format should include `module`, `stage`, `code`, `message`, and when applicable `track_id`, `clip_id`, and `t_ms`.

spec/bdd/clip-first-export/demos/expectation-pack/animation.js

@@ -0,0 +1,79 @@
+import { checks, contracts, slides, tracks } from "./mock.js";
+
+const stage = document.querySelector("#stage");
+const caption = document.querySelector("#caption");
+const checkRoot = document.querySelector("#checks");
+const contractRoot = document.querySelector("#contracts");
+const trackRoot = document.querySelector("#tracks");
+const voice = document.querySelector("#voice");
+const voiceBtn = document.querySelector("#voiceBtn");
+
+checkRoot.innerHTML = checks.map((item, index) => `
+  <article class="check" data-index="${index}">
+    <b>${item[0]}</b>
+    <span>${item[1]}</span>
+  </article>
+`).join("");
+
+contractRoot.innerHTML = contracts.map((item, index) => `
+  <article class="contract" data-index="${index}">
+    <span>${item[0]}</span>
+    <code>${item[1]}</code>
+  </article>
+`).join("");
+
+trackRoot.innerHTML = tracks.map((track) => `
+  <div class="clip ${track.kind}" style="left:${track.left}%;width:${track.width}%">${track.label}</div>
+`).join("");
+
+function renderSlide(index) {
+  const slide = slides[index % slides.length];
+  stage.innerHTML = `
+    <div class="grid"></div>
+    <section class="hero">
+      <em>${slide.tag}</em>
+      <h1>${slide.title}</h1>
+      <p>${slide.caption}</p>
+    </section>
+    <div class="source-card">
+      <strong>${index < 2 ? "composition.json" : "render_source.json"}</strong>
+      <span>${index < 2 ? "AI 写创作协议" : "recorder 吃渲染协议"}</span>
+    </div>
+    <div class="frame-card">
+      <strong>${index < 3 ? "preview" : "verify-export"}</strong>
+      <span>${index < 3 ? "same runtime" : "sample clip frames"}</span>
+    </div>
+  `;
+  caption.textContent = slide.caption;
+  document.querySelectorAll(".check").forEach((el) => el.toggleAttribute("active", Number(el.dataset.index) === slide.activeCheck));
+  document.querySelectorAll(".contract").forEach((el) => el.toggleAttribute("active", Number(el.dataset.index) === slide.activeContract));
+}
+
+let current = 0;
+renderSlide(current);
+setInterval(() => {
+  current += 1;
+  renderSlide(current);
+}, 6500);
+
+voiceBtn.addEventListener("click", async () => {
+  if (voice.paused) {
+    await voice.play();
+    voiceBtn.textContent = "暂停语音";
+  } else {
+    voice.pause();
+    voiceBtn.textContent = "播放语音";
+  }
+});
+
+voice.addEventListener("ended", () => {
+  voiceBtn.textContent = "重播语音";
+});
+
+setTimeout(() => {
+  voice.play().then(() => {
+    voiceBtn.textContent = "暂停语音";
+  }).catch(() => {
+    voiceBtn.textContent = "播放语音";
+  });
+}, 600);

spec/bdd/clip-first-export/demos/expectation-pack/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>clip-first-export expectation pack</title>
+  <link rel="stylesheet" href="./style.css">
+</head>
+<body class="nf-bg">
+  <main class="app" aria-label="Clip first export expectation pack">
+    <header class="topbar">
+      <div class="dots"><span></span><span></span><span></span></div>
+      <strong>NextFrame / clip-first-export</strong>
+      <nav><span>预期动画</span><span class="active">验收</span><span>Contract</span></nav>
+    </header>
+    <section class="workspace">
+      <aside class="panel left"><h2>功能验收点</h2><div id="checks"></div></aside>
+      <section class="preview"><div id="stage"></div><div id="caption"></div></section>
+      <aside class="panel right"><h2>模块契约</h2><div id="contracts"></div></aside>
+    </section>
+    <footer class="timeline"><button id="voiceBtn">播放语音</button><div id="tracks"></div><div class="playhead"></div></footer>
+    <div id="toast">本轮完成</div>
+    <audio id="voice" src="./voice.aac" preload="auto"></audio>
+  </main>
+  <script type="module" src="./animation.js"></script>
+</body>
+</html>

spec/bdd/clip-first-export/demos/expectation-pack/mock.js

@@ -0,0 +1,52 @@
+export const checks = [
+  ["Feature", "clip-first-export 是验收单位，不是 recorder 模块名。"],
+  ["Expectation", "先看动画、语音、关键帧，再确认要不要开工。"],
+  ["BDD", "每个验收点都有 given / when / then 和 ai_tools。"],
+  ["Contract", "recorder 只吃 render_source.json，不能读桌面端状态。"],
+  ["Visual E2E", "导出后抽每个 clip 中段和边界帧，检查不能粉屏。"]
+];
+
+export const contracts = [
+  ["AI / Editor", "composition.json"],
+  ["Compiler", "composition -> render_source"],
+  ["Recorder", "render_source -> mp4 + diagnostics"],
+  ["Verifier", "source + mp4 -> report"]
+];
+
+export const tracks = [
+  { id: "intro", label: "intro", left: 0, width: 32, kind: "scene" },
+  { id: "proof", label: "proof", left: 32, width: 38, kind: "component" },
+  { id: "outro", label: "outro", left: 70, width: 30, kind: "text" },
+  { id: "voice", label: "voice walkthrough", left: 4, width: 88, kind: "audio" }
+];
+
+export const slides = [
+  {
+    tag: "FEATURE FIRST",
+    title: "先看到终点，再开始写代码。",
+    caption: "功能是组织单位。模块只是实现手段。",
+    activeCheck: 0,
+    activeContract: 0
+  },
+  {
+    tag: "EXPECTATION PACK",
+    title: "动画、语音、关键帧先给你看。",
+    caption: "你确认最终效果后，BDD 才变成开发入口。",
+    activeCheck: 1,
+    activeContract: 1
+  },
+  {
+    tag: "RECORDER CONTRACT",
+    title: "recorder 只接受 render_source.json。",
+    caption: "不读桌面端状态，不理解创作层 anchors。",
+    activeCheck: 3,
+    activeContract: 2
+  },
+  {
+    tag: "VISUAL E2E",
+    title: "导出后抽帧，机器先挡明显错误。",
+    caption: "intro / proof / outro 都要不粉屏、不空画面。",
+    activeCheck: 4,
+    activeContract: 3
+  }
+];