dsh-drawai 0.3.3 → 0.4.0

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/wall-reveal-moves.md

@@ -0,0 +1,47 @@
+---
+name: wall-reveal-moves
+一句话: 整墙批量入场两式——bento 逐格点亮、蓝图描线成形，全部原位显形不位移，与 deck-deal-flyin 的飞入位移型互补成品类矩阵
+适用: 功能墙/卡片墙/整页界面的整体亮相；内容已在原位、要"显形"而非"涌入"的段落
+时长: 单式约 5s（A 150f / B 150f @30fps，含建立 hold 与静止收尾）
+能量: 中
+---
+
+## 意图
+"一墙内容怎么出场"库内此前只有 deck-deal-flyin 一个答案——高能量、位移型、
+"东西涌进来"。但不是每面墙都该涌：品牌段要庄重、
+"从设计到实物"要讲工序。这两式共同点是**非位移批量入场**——元素原地显形，
+版式从第一帧就成立，观众看的是"状态变化的波前扫过一面墙"而不是"物体飞行"。
+选型先问一句：这面墙该"涌进来"还是"亮起来"？前者去 deck-deal-flyin，后者进本卡。
+
+## 两式选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A bento-light-up 逐格点亮 | 暗场 3×2 bento 墙（两行宽窄互补 600/420/420 ↔ 420/420/600，暗色卡面）压暗待命，强调色彗星流光逐格描边一圈、内容随即提亮上浮，全亮后镜头缓推收住；墙上方眉标是 video-shotcraft 标志 + 字标，主标题「Every shot, tuned in one place.」 | 内容庄重/暗场品牌段；节奏沉稳的功能总览 |
+| B wireframe-draw-on 蓝图描线成形 | 界面先以 SVG 细线蓝图分组描画，再一条强调色发光竖线左→右扫过，扫过处线框实体化成真实界面（demo 里是 video-shotcraft 工作台，侧栏 logo 方块内描出镜刻标志） | "从设计到实物/从想法到产品"叙事；产品首次整体亮相 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 节拍 | hold 20f → 每格间隔 12f 依次激活（六格 ~96f 全亮）→ scale 1→1.04 缓推 25f（bezier 0.33,0,0.2,1）→ 静止收尾 | 12f 级联是"逐格可辨"与"整墙拖沓"的平衡点；格数增多可压到 8–10f，但间隔均匀本身就是这一式的庄重感来源，别学发牌加速 |
+| A 单格 | 暗态 opacity 0.18 + translateY 20px；SVG rect pathLength=100 描边 8f：22% 周长的彗星段（#e8b45e 6px 高斯辉光 + #ffe3ae 2.5px 亮芯）领跑，身后留 1.5px 细边；描边过半（+6f）内容 back-out(0.3,1.4,0.5,1) 弹出 8f 提亮归位；描完 +12f 流光退火到 0.4 常亮细边 | 描边与内容弹出要**接力不同步**——同帧起读作整格闪现；点亮中段辉光脉冲用 lit·(1−lit)·4 抛物线，峰值幅度按格 seed 微差（正弦哈希，禁真随机） |
+| B 描线 | hold 20f → 分组错峰各 30f 描完：侧栏 20f 起/顶栏 30f 起/6 卡 40+i*3f 起/折线图 52f 起；SVG pathLength=1 + dashoffset 1→0，蓝图冷灰蓝 #6c7894（外框 1.6px / 内件 1.25px）round，淡蓝 24px 点阵底 + 卡角裁切标记 | 分组错峰是"手在画"的感觉来源，全部同帧起笔读作打印机；卡内占位线再按 +3f 细错峰，长短用 seed 哈希微差 |
+| B 实体化 | 88–118f 实体层 clip-path inset(0 right% 0 0) 从左向右展开 30f，bezier(0.55,0,0.25,1)；前沿跟 4px 强调色竖线（#ffc46b + 双层辉光 boxShadow），86–92f 淡入、112–120f 淡出；竖线身后 260px 一段渐隐暖光（刚显影的余温） | 竖线位置与 clip 前沿必须同一个 scan 值驱动，异步读作穿帮；描线段与扫描段之间留 ~6f 喘息（82→88f），线框画完立刻扫读作赶工 |
+| 静止收尾 | 两式动作全部落定后真静止 ≥15f（A 在缓推结束后、B 在扫描线淡出后起算） | R1 呼吸判例：静止期一切属性锁死，包括辉光/阴影/高光残留 |
+
+## 已知坑
+- **demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验**
+- A/B 的强调色描边/扫描线属"单点高质量光效"范畴（Q4 三约束内合规），但一支片
+  整墙点亮 ≤1 次（P4 手法去重）——A 和 B 同片共用即算两次整墙光效，选一
+- B 式线框几何必须与实体层布局逐像素对位（demo 里按 FakeDashboard A 手排），
+  换素材要重排线框——对不齐则扫描线扫过瞬间元素跳位，一眼穿帮；改了品牌名 / logo
+  也算换素材（字宽变了，面包屑后面的元素会整组右移），线长要按实体层实测字宽重对
+- 两式都是"原位显形"，别混入位移入场（如逐格点亮时再加 translateX 飞入）——
+  位移需求去 deck-deal-flyin，杂交会两头不像
+- A 式暗态 opacity 0.18 依赖暗底（#2a2a28）成立，亮底下压暗读作褪色故障
+
+## 参考实现
+demos/ui-entrance/wall-reveal-moves/
+（BentoLightUp.tsx / WireframeDrawOn.tsx）
+
+实现状态：两式均有参考实现与 Gallery 动态样片。

package/lib/motion/shotcraft/upstream/references/sound-design.md

@@ -0,0 +1,170 @@
+# sound-design — 声音设计
+
+声音是时间线级资产：集中管理 SFX 钉帧表，场景组件不内嵌音频。
+新制作与换音统一从 **Freesound** 搜索、下载，操作见 [sfx-sourcing.md](sfx-sourcing.md)。
+仓库不再维护共享 SFX 库；模板的历史音频只用于原样预览与回归验证。
+
+## 1. 方法
+
+1. 分镜阶段记下动作、材质、时长和音色；画面时间线锁定后再精确钉 SFX。
+   用户已指定 BGM 的卡点片仍先按 [music-beat-sync.md](music-beat-sync.md) 分析再分镜。
+2. 先铺 BGM 定能量骨架，再钉画面独有动作。强鼓点本身已有节拍，不给每拍重复加 impact。
+3. SFX 按片种与真实声源选：whoosh（运镜）、impact（落地）、riser（铺垫）、
+   sparkle（光效）、transition（转场），有辨识度的动作另配真实拟音。
+4. 候选在成片语境中试听。下载量、评分、描述、波形是筛选证据，不能被写成“已经听过”。
+5. 下载到当前工程 `public/audio/sfx/`，随文件保留 `audio-manifest.json` 与
+   `FREESOUND-CREDITS.md`；Remotion 只读这些固定本地文件，渲染时不联网找音。
+6. 声音时间表从 `SHOTS` 派生并供工作台复用；时间线变更后逐条复核，最终按
+   [final-review.md](final-review.md) 的 A 项验收。
+
+## 2. BGM 选型与混音
+
+Freesound 路线负责 SFX。BGM 保留用户指定音乐或 `assets/audio/bgm/` 的备选，
+授权见 `assets/audio/ATTRIBUTION.md`，不能把 SFX 许可套到音乐上。
+
+- 音乐能量应匹配片子结构。产品宣传片可优先试鼓点清楚的电子底；用户的调性要求优先。
+  候选曲垫进成片试听，避免只因“欢快/好听”选择与产品气质不符的音乐。
+- 音量按素材实测给。模板中 0.34 的 BGM、0.2–0.6 的 SFX 只是历史参考，
+  `volume` 是乘法系数，不是目标响度。多轨叠加后检查削波和人声/SFX 是否被掩盖。
+- 用 `interpolate` 做首尾淡入淡出；有配音时在说话段压低音乐。
+- BGM `<Audio>` 单独受 `bgm` inputProp（默认 true）控制；配 BGM 的片子从同一
+  时间线交付带 BGM / 无 BGM（保留 SFX）两版。跨平台无 BGM 渲染使用
+  `--props=props-nobgm.json`，文件内容 `{"bgm":false}`。
+
+## 3. 音色与选材
+
+### 3.1 从画面组织搜索词
+
+完整选材规则和 CLI 在 [sfx-sourcing.md](sfx-sourcing.md)。先明确声源、质感、
+攻击长度和尾音，再查 Freesound；不要只用 `click` 或 `impact` 这类宽泛词。
+
+| 画面 | 查询示例 | 筛选重点 |
+|---|---|---|
+| 卡片飞入 / 运镜 | `short soft whoosh` | 攻击峰位置、无过长拖尾 |
+| 纸卡滑入 / 翻页 | `dry paper slide` / `single page turn` | 真实纸声、单次动作 |
+| 开关 / 轻点 | `mechanical switch click` | 短促物理质感，避免提示音 |
+| 字标落地 | `short cinematic impact` | 重量感、低频不盖住 BGM |
+| 打字 | `computer keyboard typing` | 节奏密度、段落长度、底噪 |
+| 组装与余韵 | `cinematic riser` / `subtle shimmer` | 渐强能否抵达落点、尾音是否自然 |
+
+### 3.2 连发候选先检查重复
+
+两个名称或两个 Freesound ID 可能对应相同声音。用清单的 SHA-256 发现相同文件，
+再试听确认音色差异；不同编码的同一录音可能哈希不同。不能把同一声音的改名副本
+当成双样本交替。不要下载整库，只取当前动作需要的候选。
+
+### 3.3 UI 动作仍要逐个判断音色
+
+S1 禁的是游戏式合成提示音质感，不是点击动作。真实开关、快门、玻璃、纸张拟音可用；
+`confirmation tone`、`bleep`、`notification` 往往是合成反馈，不能因为搜索词匹配
+就入选。片子刻意表现“系统提示”时可以使用，在设计记录中说明叙事理由。
+
+录音描述有明确声源与设备是有用线索；`made with my mouth`、`built-in mic`
+可能不适合干净的产品片。设备名字不能保证质量，仍需结合片中试听。
+
+## 4. 对齐技巧
+
+### 4.1 钉帧、时长和音量
+
+- 中央注册表保持 `{ from, src, volume }[]`，可扩展 `durationInFrames`；
+  每条注释对应动作，渲染层用 `<Sequence>` 挂载。工作台从同一张表派生轨道。
+- 以下载文件的 `analysis` 为准，不能把网页列出的原文件时长/采样率当成预览文件实测。
+  `get` 自动分析；处理或换文件后再运行 `analyze`，更新清单和哈希。
+- 动作声显式设置播放窗口，特别是 >5s 的键盘、环境与机械长样本。
+  Sequence 裁剪贴动作时长；底噪铺满对应段落；impact 的自然混响可越过落点，避免硬截。
+- 峰值低于 -12dB 的轻音素材先考虑换更干净的候选，或预处理后重新分析。
+  必要时可用 >1 增益，但预览与渲染的行为可能不同，以成片实测防削波。
+- 工具给出 10ms 窗口的 RMS 能量峰、sample peak 和整体 RMS，**不是 LUFS 或 true peak**。
+  多次敲击或渐强素材需人工选择语义落点，不能机械地把全文件最大峰当作每个动作的落点。
+
+### 4.2 连发防机枪感
+
+双样本交替、音量阶梯递减（如 0.40→0.25）、间隔跟随动画加速。
+密到无法逐个听清时收成 swoosh 或淡出，不让多个长尾叠成噪声。
+
+### 4.3 riser→impact→sparkle：镜头收束句式
+
+组装铺垫起 riser，主体落地钉 impact，余韵配 sparkle。按镜头实际落点确定
+三者间隔，从 Freesound 选匹配的三个声源；不沿用模板文件名或绝对帧号。
+是否使用该句式服从分镜，不强行给所有结尾套同一种声音。
+
+### 4.4 画面返工后的复核
+
+镜头时长、顺序或动作峰值变了，复核对应声音窗口和其后所有钉点；
+只调整画面而不检查声音会导致错位。选材可以提前，精确钉帧在时间线锁定后做。
+
+### 4.5 相对 shot 起点钉帧
+
+写 `SHOTS.<shot>.from + offset`，卡点片写 `beatF(n)`；新项目不写裸绝对帧号。
+镜头起点变化时 SFX 自动跟随，但镜头内部动作变化后仍需复核。
+
+### 4.6 音画对齐补两项偏移（硬规则）
+
+设计意图是"音源峰值落在目标拍帧上"，从意图到成片隔着两项偏移，都
+不补时会叠加——本仓库实测最重一击晚了 0.27s，明显读作音画不同步；
+卡点片里差 2–3 帧就足以让观众听不出"这一下是跟着鼓的"，合理的卡点
+动效被读作无端抖动（S5 判例）。统一公式（浮点计算，最后一步取整）：
+
+```
+Sequence.from = 目标峰值帧 − 音源峰值滞后帧 − 输出音轨偏移帧
+```
+
+**偏移一：最终输出音轨偏移（逐渲染管线实测）。**
+渲出成片的整条音轨相对视频有一个固定滞后。根因在**输出编码/封装
+链路**，不是 `<Audio>` 或 `Sequence.from` 的行为：AAC 编码器有
+encoder priming（头部垫入的预热样本），48kHz 下典型值 2048 samples
+= 1.28f@30fps。本仓库 AiflPromo 实测 click 滞后 2032 samples、
+impact 2066 samples（≈1.27–1.29f），与 priming 指纹吻合；且渲染品
+（aifl-ref.mp4）音轨的 edit list（elst media time=0）未声明裁剪这段
+垫头，解码后就体现为真实偏移。Remotion 官方跟踪同族问题：
+remotion-dev/remotion#7099。
+
+- **按管线记录，不按"片"**：偏移由 Remotion 版本 + 音频 codec +
+  sample rate + 容器四要素决定，实测值随四要素一起记档；四要素不变
+  可复用，换任何一样必须重测。priming 量级依编码器而异（ffmpeg 内置
+  aac ≈1024、fdk-aac 2048、Apple ≈2112 samples），不能预设常数。
+- promo-ink 时代实测过 **4f**（≈133ms/6400 samples），量级远超
+  priming 所能解释、根因未验证——仅作为"旧常数不可跨管线搬运"的
+  警示数据保留，不作机制陈述。
+
+实测方法（渲后做，同管线量准一次通用）：
+
+```bash
+ffmpeg -i out/promo.mp4 -vn -acodec pcm_s16le /tmp/render-audio.wav
+```
+
+拿 2–3 个尖锐 SFX 的**原文件**对渲出音轨做归一化交叉相关（numpy
+`np.correlate` 即可），峰值位置减去设计帧号就是偏移量；多个探针
+残差一致才算量准，只测一个点可能撞上音源自身的峰值滞后。
+
+**偏移二：音源自身的峰值滞后（逐文件量）。**
+很多素材的能量峰不在文件头（渐强攻击、前置气口），按文件头对齐等于
+晚到。实测例：brush-write 2f、paper-slide 10f、ink-char 深达 24f。
+峰值位置用音频能量包络定位，新音效入库时随 max_volume 一并记录
+（见 4.1；与 music-beat-sync §4 "素材按内部峰值对齐，不按文件头
+对齐"同一条原则）。
+
+渲染层实现——SFX 表保持 §4.1 的 `{ from, src, volume }` schema 不变，
+三项拆分发生在 `from` 的计算表达式里（审计链完整，绝不逐条手改帧号）：
+
+```tsx
+// 本管线实测：Remotion 4.x + AAC 48kHz mp4，2026-08-23，click/impact 双探针交叉相关
+const OUTPUT_AUDIO_OFFSET_F = 1.28;
+const PEAK_F: Record<string, number> = { 'impact-deep-whoosh.mp3': 2 /* 逐文件实测 */ };
+const sfxFrom = (targetPeakF: number, src: string) =>
+  Math.max(0, Math.round(targetPeakF - (PEAK_F[src] ?? 0) - OUTPUT_AUDIO_OFFSET_F));
+// 表内写法：{ from: sfxFrom(SHOTS.outro.from + 35, 'impact-deep-whoosh.mp3'), src: …, volume: 0.55 }
+```
+
+两个边界注意：
+- **durationInFrames 不加偏移**：窗口整体前移后起止点在听感上一起
+  归位；给截断型音效（显式 durationInFrames 裁长样本的）加长窗口，
+  会多播出本该裁掉的内容。
+- `Math.max(0, …)` 兜底意味着片头约 2f 内的钉点无法完成全部补偿，
+  残差记进验收表；片头重音尽量不要设计在前 2 帧。
+
+BGM 侧同理但记账位置不同：源音乐网格常量 `SOURCE_BEAT0` 保持分析
+真值不动，输出偏移单独设常量参与 `beatT` 换算，见 music-beat-sync
+§5b——两处共用同一套交叉相关实测法。
+
+验收：补偿后重渲，对 2–3 个探针重跑交叉相关，残差 ≤0.5f 为合格。

package/lib/motion/shotcraft/upstream/references/workbench.md

@@ -0,0 +1,157 @@
+# 动效工作台：成片交付后的可视化微调
+
+`workbench/` 是一个剪映式的浏览器工作台（多轨时间线 + 素材库 + 属性面板 + Remotion
+实时预览 + 一键导出），从系列姊妹项目 video-talkcraft 的 `workbench/` 移植而来。
+skill 渲出成片后**主动打开它**，用户不用回到代码里改 tsx 就能：挪一个镜头、拉长一段
+停留、改一句字卡文案、换一个音效、给某段变速，改完直接导出 MP4。
+
+**触发时机**：任何模式下成片交付后，先跑下面的命令把工作台打开并告知用户地址，再说
+「交付收尾」的 1-2-3（见 `SKILL.md`）。不要等用户问。
+
+```bash
+# 在 skill 根目录执行；<成片工程目录> = 含 package.json / remotion.config.ts 的那一层
+node workbench/scripts/open.mjs <成片工程目录>
+# → 链接工程 src/ 与 public/ → 生成索引 → 起 dev server（5198）→ 浏览器打开并自动导入成片
+```
+
+首次会自动 `npm install`（一次性，约 1 分钟）。dev server 后台常驻，`kill $(cat workbench/.dev.pid)` 停。
+两个 skill 的工作台端口错开（talkcraft 5199 / shotcraft 5198），可同时开。
+
+## 1. 三层可编辑度：什么能改、代码要满足什么
+
+工作台把片子拆成 clip（Project → Track → Clip），每个 clip 有三层可编辑面：
+
+| 层 | 用户能改什么 | 对动效代码的要求 |
+|---|---|---|
+| **时间与图层**（所有 clip 都有） | 起点 / 时长（超出原长尾帧定格）/ 变速 0.25×–4× / 裁入点 / 不透明度 / 缩放 / 位移 / 换轨 / 隐藏整层 | 组件是 `useCurrentFrame()` 的纯函数、tween 全部 clamp、无 `Date.now`/`Math.random`——本 skill 第 9 条铁律已保证。**现有 demo（152 个里 150 个自动接入，见 §4）与全部成片镜头无需改动**即可上轨 |
+| **内容与样式**（属性面板） | 文案 / 颜色 / 字号 / 位置 / 开关 / 枚举，逐项可视化调 | 组件把语境级参数暴露为**带默认值的 props**，并给出 `schema`（字段列表，见 §3）。demo 里的顶部 `CONFIG` 常量不改就不可调——只能动时间/图层 |
+| **拆解导入**（把成片一键拆成多轨） | 每个镜头 / 转场 / 字幕 / 音效各成一段，单独挪、删、复制 | 成片工程提供 `src/workbench.ts` 清单（§2），时间表与 Main.tsx **同源**，导入后不改任何东西渲出来就是原片 |
+
+这和 talkcraft 的做法一一对应：talkcraft 把 79 张模板卡逐张复制成 `gen/*.tsx`
+（CONFIG → props + schema，「节奏命门」保持 FIXED），成片则靠 `@kbsrc` 符号链接进工程、
+按 `SHOTS`/`SFX_CUES`/`WIPE_TIMES` 表拆解，逐镜参数化靠为每个镜头手写 `kscene-sNN` 卡。
+shotcraft 这边的差别：demo 组件 150 个全部**原样接入**（不做逐张参数化复制，避免维护两份），
+成片的逐镜可编辑性由**清单里的 `schema`** 声明——所以「未来的片子能不能逐属性改」
+取决于制作时是否按 §3 写镜头组件，而不是事后改工作台。
+
+## 2. 成片工程接入清单 `src/workbench.ts`
+
+导出一个 `WORKBENCH` 常量，结构（TypeScript 类型在 `workbench/src/cards/manifest.ts`，工程
+文件不需要 import，结构兼容即可）：
+
+```ts
+export const WORKBENCH = {
+  name: 'Ink Press · AIFL promo',
+  fps: 30, width: 1920, height: 1080,
+  total: AIFL_TOTAL,                 // 成片总帧数
+  background: '#f2eee6',             // Main 最外层 AbsoluteFill 的底色
+  revision: undefined,               // 可选版本号；不给则按清单内容哈希判「是不是同一版成片」
+  shots: [                           // 镜头：from/duration 与 <Sequence> 一一对应（绝对帧）
+    { id: 'morning', label: 'S1 墨线开场', from: 0, duration: 220, component: SceneOpen },
+    { id: 'card1', label: '字卡①', from: 220, duration: 55,
+      component: TitleCardUnit,                     // 吃 props 的组件
+      props: { text: 'All your team’s research, *one* place to go.' },  // 成片里的实际值
+      schema: [{ type: 'textarea', key: 'text', label: '文案', default: '' }],
+      durationProp: 'duration',                     // 把 clip 时长注入这个 prop（尾部淡出跟着走）
+      cardId: 'title-card', cardName: '字卡' },     // 四张字卡共用一张卡
+    …
+  ],
+  transitions: [...],                // 转场层（闪白 / 光条），结构同上
+  captions: [...],                   // 字幕 / 解说条
+  overlays: [...],                   // 全片常驻叠加层（网格 / 暗角）
+  sfx: SFX.map(s => ({ from: s.from, duration: 90, src: `audio/${s.src}`, volume: s.volume })),
+  bgm: [{ from: 0, duration: TOTAL, src: 'audio/bgm.mp3', volume: 0.34 }],
+  order: ['transitions', 'captions', 'overlays'],   // 叠加层 z 序（上→下），缺省即此
+  original: AiflMain,                // 原合成，供 parity 对照
+};
+```
+
+**范例的参数化程度**：模板六个场景 + 字卡 + 解说条全部导出 `*_DEFAULTS`（文案 / 字号 / 色板）并以带默认值
+的 props 读取，清单 schema 直接引用同一对象——属性面板里改的就是屏幕上的值，缓动 / 时值 / 相机键不暴露。
+demo 里的场景常量（`CONFIG` / 顶部 `const`）照这个模式提成 `DEFAULTS + Partial<typeof DEFAULTS>` 即可接入。
+
+**同源原则**：清单里的每张表都从 Main.tsx `import`（`SHOTS` / `CAPTIONS` / `SFX` / 字卡文案表），
+不要手抄第二份。范例：`template/src/workbench.ts` + `template/src/aifl/Main.tsx`
+（`AIFL_SHOTS` / `TITLE_CARDS` / `CAPTIONS` / `SFX` / `FLASH_CUTS` / `sfxDuration` 全部 `export`，
+渲染与清单同一份数据）。
+
+**版本判据**：`?import=project` 打开时，存档的 `source` 与 `manifestKey(清单)` 不同才重新导入。key = 名字 + 总帧数 + `revision`，
+未写 `revision` 时用清单内容哈希（时间表 / label / props / 单元→卡的分组拓扑 / 组件 displayName / 音效表）——改了镜头位置、文案、
+音效或换了组件即视为新版本；旧存档压进撤销栈，⌘Z 可找回。
+
+**分组规则**：同一 `cardId`（或同一 `component` 引用）的单元共用一张「成片单元卡」，
+素材库里只出现一次，可以再拖一份上轨；`label` 是时间轨上的显示名（中英文都行：工作台默认英文界面，展示时按 `workbench/src/i18n.ts` 的词典把中文标签翻成当前界面语言（英文 / 俄文），查不到就原样显示）。卡 id 为
+`proj:<kind>:<cardId|首个单元 id>`；显式 `cardId` 与另一组的首个单元 id 撞名（或单元 id 重复）时，
+后出现的组加 `~2` 后缀并在控制台警告——请给单元换 id 或写显式 `cardId`，别依赖后缀。
+
+**素材路径**：`sfx[].src` 等一律相对工程 `public/`（工作台把工程 `public/*` 链接进自己的
+`public/`）。字幕/字卡文案里的 `*词*` 记法是 Ink Press 字卡的强调词 DSL（`parseWords`），
+其他工程可以自定 DSL，只要 props 是字符串/数字/布尔就能进属性面板。
+
+## 3. 制作新片时怎么写镜头（让它"未来可编辑"）
+
+在 pipeline 阶段 5 实现每个镜头时：
+
+1. **语境级参数 → props（带默认值）**：文案、颜色、字号、位置、开关、数据（多条用逐行
+   文本 DSL）。**节奏命门保持常量**（弹入时长、错峰间隔、缓动曲线、相机路径）——它们决定
+   动效品相，暴露出去反而容易调坏。这与 talkcraft 的「FIXED / 开放」分界一致。
+2. **`duration`/`dur` 类 prop 要真的用**（出场淡出按它算），清单里声明 `durationProp`，
+   clip 拉长后淡出会跟着挪而不是定格在原时长处。
+3. **时间表只写一份**：`timeline.ts`/`Main.tsx` 里的 `SHOTS` 是唯一事实源，SFX 钉帧、字幕
+   表、转场点都从它派生并 `export`；`workbench.ts` 只 import + 补 component/schema。
+4. **纯函数、确定性**：不读 `useVideoConfig().durationInFrames` 做绝对时间假设（motion-lab
+   系 `useT()` 归一化是例外且被工作台正确处理：clip 拉长=动画放慢）。
+5. 交付前跑一次 `npm run parity`（§5）确认拆解无损。
+6. **实时预览得跑得动**：Player 是实时合成，不像渲染那样每帧等栅格化完成再截图。铺满巨型平面
+   （几千 px 见方）的程序渐变 / `backdrop-filter` 放在 PageCam 这类每帧改 `zoom` 的 3D 层里，
+   Chrome 栅格化跟不上就整块时有时无——Ink Press 模板 S3 的金属桌面曾因此在预览里疯狂闪，
+   其余镜头全片 0 次异常（用 CDP screencast 逐帧测亮度脉冲得出）。这类纯装饰的重绘内容用
+   `getRemotionEnvironment().isRendering` 分流：渲染走原效果，预览用纯色 / 更轻的替身，几何
+   与时序不变（`SceneFlyIn.tsx` 的 `METAL_PREVIEW` 是范例）。parity 只比渲染结果，所以仍成立。
+
+schema 字段类型：`text` / `textarea` / `number`（min/max/step/unit）/ `slider` / `color` /
+`select`（options）/ `boolean`，定义在 `workbench/src/cards/types.ts`。
+
+## 4. 动效库（demos/）在工作台里的形态
+
+`scripts/gen-index.mjs` 扫 `demos/<类别>/<卡>/<组件>.tsx`，凡导出 `<组件>: React.FC`（无必填
+props）即接入为一张卡（152 个 tsx 里接入 150 个：`ClipCardLooping` 需要真实 mp4 素材、
+`page-waterfall-wall/VerticalTicker` 是辅助组件，两者跳过），中文名/分类/一句话取自画廊 `library.json` + `translations.js`，
+预览用 `gallery/media/<style>.mp4`（先 `gallery/fetch-media.sh` 拉取，否则用 Player 实时循环）。
+时长取值链：demo 导出的 `*_DURATION|*_DUR` → 镜头卡 md「时长:」的 `NNNf` → 文件内
+`const *DUR*` → 缺省 150f；来源写在 `DEMO_MODULES[].durationSource`，clip 上轨后随时可裁。
+demo 全部 schema 为空（时间/图层可编辑，属性不可编辑）——要逐属性调参就按 §3 把 CONFIG
+提成 props，加 `export const schema`… 目前不自动读取，属于后续扩展点。
+
+工作台自带 4 张参数化原生卡：通用文字、Ink Press 字卡、解说字幕条、暖白闪转场
+（`workbench/src/cards/inkpress/`，源出 template 组件，动效逐字同式，文案/颜色/字号开放）。
+
+## 5. 导出、Studio 与无损校验
+
+- **导出成片**：顶栏「导出成片」→ dev server 内起 Remotion CLI 渲当前工程（`workbench/exports/`）。
+  渲染前会把 `public/` 解引用同步到 `.render-public/`（Remotion 静态服务器拒绝服务符号链接）。
+  `remotion.config.ts` 与 template 同口径：jpeg 帧、ANGLE GL、并发 4。
+- **Remotion Studio**：`cd workbench && npm run studio`——`Main`（贴工程 JSON）、`ProjImported`
+  （刚导入的成片）、`ProjOriginal`（原合成）+ 每张卡一个合成（schema 自动转 Zod，官方 Inspector 调参）。
+- **无损校验**：`npm run parity -- --frames 150,240,470,1000` 渲 `ProjImported` 与 `ProjOriginal`
+  同帧 PNG 逐像素比对（需 python3 + Pillow），差异像素 < 0.1% 视为一致。退出码 0 一致 / 1 有差异 /
+  2 无法得出结论（缺 Pillow、比对未执行）——不会假绿。改过清单或 Main.tsx 的时间表后跑一次。
+
+## 6. 已知边界
+
+- 同轨允许 clip 重叠（层级用多轨表达）；变速为匀速重映射（无曲线变速）。
+- 卡片库（demo / 原生卡）按 30fps 编排（`CARD_FPS`），成片单元卡按成片清单的 fps（`CardDef.sourceFps`）；
+  工程 fps 不同时，拖卡上轨按 `clipDefaultsFor` 换算时长并反向变速，播放速度不变；媒体卡
+  （视频 / 音频 / 图片，`timing: "realtime"`）只换算时长、不变速。Freeze 不改 `useVideoConfig().fps`，
+  卡内若用 `spring({fps})` 等按秒计时，非 30fps 工程里节奏会偏移——属性面板会提示，成片单元不受影响
+  （帧率与工程一致）。时间码 / 片段秒数 / 预览余量都按工程 fps 计。
+- `open.mjs` 只重启自己启动的 dev server（`.dev.pid` + 进程命令行核实）；端口被手动起的 server
+  占着时报错退出，因为 `@proj` 别名在 vite 启动时定死、刷新不会换工程。
+- 音频 clip 导入时截到成片总长（原片里超出合成尾部的 `<Sequence>` 本就被截）。
+- demo 卡需要的灰阶纹理（`textures/live/*.png`）：工程自己带 `public/textures` 时以工程为准，
+  否则工作台兜底链接 `demos/_textures`；工程纹理与 demo 纹理同名不同图时 demo 预览会"换皮"。
+- 工程 `src/` 被以符号链接方式打包进工作台，`react`/`remotion` 落到工作台的 node_modules
+  （remotion 4.0.484 / React 19）；工程若用了 `@remotion/three`、`three`、`@remotion/motion-blur`、
+  `@remotion/google-fonts` 以外的包，先在 `workbench/` 里装同版本。
+- 与剪映导出（`jianying-export.md`）的分工：剪映给"外部剪辑软件里继续剪"的用户；工作台给
+  "在本机浏览器里改几处就出片"的用户，且能改镜头内部的参数化属性（剪映只能整段变速）。

package/lib/motion/shotcraft/upstream/template/TEMPLATE.md

@@ -0,0 +1,103 @@
+# template/ — 成片模板 Ink Press：纸墨晨读风产品宣传片（36.2s）
+
+一支已验收的完整宣传片工程，作为"极度相似复现"的模板：换一个 web/桌面
+产品的截图素材，按本文档逐镜头替换适配，即可得到同等质感的成片。
+
+- 规格：1920×1080 @ 30fps，1085 帧（36.2s），SFX-only（无 BGM 版）
+- 风格：纸墨琥珀（纸底 `#f2eee6`，墨字，衬线大标题，琥珀强调色）
+- 跑起来：`npm install && npx remotion studio src/index.ts`（预览）
+  / `npx remotion render src/index.ts AiflPromo out/promo.mp4`（渲染）
+- 验收静帧：`npx remotion still src/index.ts AiflPromo out/qa/f150.png --frame=150`
+
+## 一、片子结构（src/aifl/Main.tsx 的 AIFL_SHOTS）
+
+能量骨架：品牌开场（低）→ 功能段×3 与字卡呼吸位交替（中高/低）→
+结尾组装推到全片峰值。两处 wordmark 时刻（开场、收尾）落定后 hold 满 1s。
+
+| # | 帧区间 | 时长 | 场景文件 | 内容 | 对应镜头卡 |
+|---|--------|------|----------|------|-----------|
+| 1 | 0–220 | 7.3s | live/SceneOpen.tsx | 墨线描画+字标压印开场 → dashboard 全景 → 聚光主角卡（悬浮+光束扫+归位） | brand-ink-open / spotlight-hero-card（高清栅格化技法见审美准则 Q2） |
+| 2 | 220–275 | 1.8s | PaperTitleCard.tsx | 字卡①"All your team's research, one place to go." | paper-title-card |
+| 3 | 275–465 | 6.3s | live/SceneFlyIn.tsx | 牌堆特写环绕 → 发牌飞入网格 → 滚动 → 搜索打字 → 筛选 → 点击推近 | deck-deal-flyin / type-and-filter |
+| 4 | 465–565 | 3.3s | live/SceneDetail.tsx | 详情页宏观特写，行元素逐条嵌入 | row-embed |
+| 5 | 565–620 | 1.8s | PaperTitleCard.tsx | 字卡②"Paper Radar…"（含 DigitRoll 数字子标） | paper-title-card |
+| 6 | 620–725 | 3.5s | live/ScenePapers.tsx | 论文雷达列表堆叠压入 + 计数器落定 | list-stack-press |
+| 7 | 725–775 | 1.7s | PaperTitleCard.tsx | 字卡③"Every project, linked to your weekly report." | paper-title-card |
+| 8 | 775–885 | 3.7s | live/SceneWbr.tsx | 周报页"自己写自己"打字机揭示 + 历史周报逐条 pop 入侧栏 | document-typewriter-reveal |
+| 9 | 885–940 | 1.8s | PaperTitleCard.tsx | 字卡④"The whole team, on the same page." | paper-title-card |
+| 10 | 940–1085 | 4.8s | live/SceneOutroLive.tsx | 虚焦 → 元素合影组装 → 铅印字标砸落（riser→impact→sparkle）→ 1s hold | outro-group-photo-launch |
+
+叠加层（全部在 Main.tsx 里声明式管理，且全部 `export`——`src/workbench.ts` 清单从这里
+import，动效工作台据此把成片拆成多轨，见 ../references/workbench.md）：
+- **TITLE_CARDS**：四张字卡的文案表（`*词*` = 琥珀斜体强调词，`parseWords` 解析），
+  card2 带副标 + 滚动数字
+- **CAPTIONS**：底部通栏解说字幕 6 条（绝对帧号表），压在功能段上，字卡/outro 段不加
+- **FLASH_CUTS / FlashCut**：暖白闪转场 4 处，`from = 切点 − 5`，两侧各 5f 跨骑接缝
+- **SFX 钉帧表**：30+ 条 `{from, src, volume}`，逐条注释对应画面动作；
+  keyboard 长样本按语境用 Sequence duration 截断（`sfxDuration`：24f/44f）
+
+## 二、共用地基组件
+
+| 文件 | 作用 | 关键点 |
+|------|------|--------|
+| live/Scene*.tsx · PaperTitleCard · Caption | 每个场景导出 `*_DEFAULTS`（文案 / 字号 / 色板），并以带默认值的 props 读取；`src/workbench.ts` 的 schema 直接引用同一对象，工作台属性面板里改的就是这些。缓动 / 时值 / 相机键不暴露 | 换产品时优先改 DEFAULTS 而不是散落的字面量；色值是原 oklch 令牌的 sRGB 渲染值（墨 #13110f · 琥珀 #955905 · 灰墨 #65635f · 深琥珀 #ae6700） |
+| live/PageCam.tsx | 2.5D 页面相机——一切"真实页面"镜头的地基 | 整页截图 + 关键帧 `{frame,cx,cy,zoom,rotX/Y/Z,persp}` 插值运镜；children 按页面 CSS px 定位（与 layout.json 同坐标系）；**3D 模式用 CSS `zoom` 做布局级放大**（transform scale 会先降采样再放大导致文字糊——根治法详见审美准则 Q2）；可选 dof 顶部渐变糊带 |
+| PaperTitleCard.tsx | 字卡呼吸位 | 衬线大字逐词入场，accent 词琥珀色；可挂 DigitRoll 数字子标 |
+| FlashCut.tsx | 暖白闪转场 | 只盖硬切两侧 10f，不当装饰光效 |
+| Caption.tsx | 底部通栏解说 | 等宽小字+字距，入出场各带轻推 |
+| DigitRoll.tsx | 里程表数字滚动 | 逐位滚动落定 |
+| live-layout.json | 页面元素坐标表 | 每元素 `{x,y,w,h}`（整页 CSS px 坐标系）+ 每页 pageH；场景代码 import 它决定飞行目标位/遮罩位置 |
+
+## 三、素材清单（public/）
+
+- `textures/live/*.png` — 整页 2x 截图（projects-full / detail-full / papers-full /
+  wbr-full）、元素切片（card1–10、paper1–5、float-*、nav）、空板
+  （projects-empty）、高清特写卡（card4-hires，4x 单独截）
+- `audio/*.mp3` — 本片用到的 11 个 SFX（历史固定依赖，来源与未核实项见 `public/audio/ATTRIBUTION.md`）
+
+> 注意：本模板的截图素材来自一个内部研究管理工具（数据为虚构演示数据）。
+> 对外分发成片前，务必整套替换为目标产品自己的截图。
+
+## 四、换产品复现指南（保质量的最短路径）
+
+1. **采集素材**（具体采集方法见 ../references/pipeline.md 阶段 4；模板路线只借用
+   采集方法，不执行自由创作的阶段 0–3）：
+   复制 `../assets/scripts/capture-template.mjs` 进目标产品项目，改 BASE_URL
+   与选择器，产出三件套——整页 2x 截图、元素透明底切片、layout.json。
+   素材命名对齐本模板（projects-full/detail-full/…），可直接覆盖 public/。
+2. **换 layout 坐标**：用新 layout.json 替换 `src/aifl/live-layout.json`。
+   场景代码里所有飞行目标位/遮罩位/悬浮件位置都从它读，坐标换了动画跟着走。
+3. **逐镜头适配**（顺序照第 1 节表）：
+   - 每镜头**先读对应镜头卡全文 + 场景源码**，理解参数含义再改；
+   - 必改项：PageCam 的 keys（cx/cy/zoom 按新页面构图重定）、
+     元素切片文件名、卡片数量/槽位循环、文案；
+   - 不要动的：缓动曲线、时长配比、hold 帧预算、SFX 钉帧结构——
+     这些是质感所在，改了等于重做调校。
+4. **文案**：`TITLE_CARDS` 表（字卡，`*词*` 标强调）、CAPTIONS 表、outro 品牌名/tagline。
+   镜头结构变了同步改 `src/workbench.ts`（新镜头加一行 `scene(...)`；字卡照 `title(...)`），
+   然后 `cd ../workbench && npm run parity` 确认拆解无损。
+5. **音效换源**：新产品按 `../references/sfx-sourcing.md` 从 Freesound 选材，下载到
+   本工程 `public/audio/sfx/` 并保留来源/署名清单。沿用 SFX 的动作语义与钉帧结构，
+   更新 `src`、时长和增益，按新文件峰值重对。历史音频保留供模板原样预览/回归，
+   用户点名复现原声音时遵守其要求并核实原许可。
+6. **验收**：每改完一个镜头 `npx remotion still` 出静帧自检（每镜头至少
+   入场中/动作峰值/落定后三帧）；全改完整片渲染 + ffmpeg 抽帧回看；
+   最后对照 ../references/aesthetic-rules.md 过 checklist。
+7. **时长伸缩**：加/删镜头时整体平移 AIFL_SHOTS 的 from（它是单一事实源），
+   CAPTIONS/SFX/FlashCut 的绝对帧号表跟着平移——建议先把新时间线定稿再动
+   SFX 表（画面每动一次钉帧表全体重排）。
+
+## 五、质感清单（复现时的硬指标）
+
+- 文字在 3D/放大下必须锐利：2x 整页纹理 + PageCam 布局级 zoom +
+  被特写元素 4x 单独截图，三件缺一不可
+- 落定后必呼吸：字标 hold ≥30f，批量动效收尾 ≥15f 静止
+- 一种动画手法全片只当一次主角
+- 飞入元素必须落进页面真实槽位（layout.json 坐标），不悬空
+- SFX 用电影系词汇（whoosh/impact/riser/sparkle/transition），
+  禁游戏 UI 音色；结尾固定句式 riser→impact→sparkle
+- 复现片若加了 BGM，终渲固定交付两版：带 BGM 版 + 无 BGM 版（保留 SFX），
+  BGM `<Audio>` 用 `bgm` inputProp 包住，从同一时间线渲出无 BGM 版：
+  `--props=props-nobgm.json`（内容 `{"bgm":false}`；Windows 内联 JSON
+  会被 shell 剥引号，走文件）
+- 确定性渲染：无 Math.random/Date.now，一切伪随机用固定种子

package/lib/motion/shotcraft/upstream/template/THEMES.md

@@ -0,0 +1,44 @@
+# Visual themes and palette editing
+
+Open the **主题 (Themes)** tab in the existing left sidebar. Its upper section selects a preset; its lower section edits background, card surface, text, secondary text, accent, subtle fill, and border colors using a color picker or a six-digit HEX value. Press Enter or leave the HEX field to apply it. Invalid input is discarded.
+
+Presets: Ink Press, Modern Light, Midnight, Sage, Coral, Iris, Deep Ocean, Obsidian Violet, and Vintage Kraft. Sage, Coral, and Iris replace the earlier bright experiments with pale surfaces and restrained accents. Their existing IDs (`solar-pop`, `coral-burst`, `color-play`) remain compatible with saved projects. Coral's neutral surface / dark violet text / coral accent direction draws on [Happy Hues](https://www.happyhues.co/); values are adapted for this fixture, not an exact copy of a complete site.
+
+- `themeId` and optional `themeColors` are stored in project JSON and browser saves. Changes support undo/redo. A continuous color-picker gesture creates one undo step and keeps the current clip selected.
+- Selecting another preset clears palette overrides; **恢复预设** clears them for the current preset. Explicit per-clip edits remain intact and take precedence.
+- Ink Press preserves its original raster screenshots and has no palette editor. Select another preset to recolor both the film and its demo UI assets.
+- Editable presets preserve the weekly heading in the report-header band and use compact 36px captions near the bottom. Explicit per-clip text, size, and position edits still take precedence.
+- Themes apply to the adapted template scenes. Ordinary Gallery cards and the editor's own chrome are not globally recolored.
+- Old projects without a theme marker are normalized once; explicit edits are never inferred or discarded after migration.
+
+## Single palette source
+
+`src/themes/palettes.json` defines the seven semantic colors per editable preset. Both the scene adapter and `themes/ui.cjs` read it. Add the palette, its type ID, and a manifest label to add a preset using the same fixture. No copied scene tree is needed.
+
+`src/themes/palette-assets.json` contains five trusted, serialized demo pages and 27 crop definitions. Runtime SVG assets embed this markup using `foreignObject` and validated HEX variables. The same renderer is used in preview and video export, with a bounded cache. Editing colors does not invoke a capture service or recolor pixels with a filter. Third-party screenshots still require a separately adapted source.
+
+After changing fixture markup or geometry, run `node scripts/build-palette-assets.cjs` from `template/`. It requires Playwright in the development environment. `SHOTCRAFT_PLAYWRIGHT` and `SHOTCRAFT_BROWSER` can select an existing module and Chromium executable. The compiled JSON is committed, so end users do not need these tools.
+
+The optional manifest additions are `themes[].palette` and `paletteProp`, alongside `themes`, `defaultTheme`, `themeProp`, and each unit's `themeKey`. Props resolve schema defaults → preset defaults → project palette → explicit clip edits. Manifests without palette support keep their existing behavior.
+
+## Direct render
+
+The existing `AiflPromo` composition accepts `theme` and optional `colors`:
+
+```json
+{"theme":"coral-burst","colors":{"accent":"#2459ad","surface":"#e1ecff"}}
+```
+
+Save this as a props JSON and pass it to `npm run render -- --props=<file>`. Workbench exports instead carry `project.themeId` and `project.themeColors`. Missing or unknown preset IDs fall back to Ink Press.
+
+## Verification and provenance
+
+After installing dependencies in both `workbench/` and `template/`, run `npm run test:themes` and `npx tsc --noEmit` from `workbench/`, and `npx tsc --noEmit` from `template/`. Tests cover custom palette validation and precedence, reset, edit preservation, legacy saves, unthemed projects, palette history, preserved weekly copy, caption defaults, and separate light/accent/shadow roles. Browser/export validation results are recorded in PR #80.
+
+The fixture describes a fictional research workspace, not a connected service or real research results. Original assets retain their existing attribution/license terms; new fixture code and derived assets use this repository's Apache-2.0 license.
+
+## Save, import and export palettes
+
+Name a palette and click **保存配色** to add it to **我的主题**. These entries live in this browser's local storage, scoped to the current manifest name (up to 50 entries); they are separate from the project timeline. Click an entry to apply it, or its × button to remove it. Export a JSON file to back it up or move it to another browser.
+
+**导入配色** accepts version-1 `shotcraft-palette` JSON exported by this panel, validates the compatible base theme and complete HEX fields, and applies it without changing timeline edits. Click Save afterward to add the imported palette to My Themes. Arbitrary color-site JSON schemas are not yet supported. **导出配色** downloads the current palette, name and base theme ID. Vintage Kraft (`vintage-kraft`) preserves its procedural paper texture when its palette is saved or imported.

package/lib/motion/shotcraft/upstream/template/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "promo-template",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "remotion studio src/index.ts",
+    "render": "remotion render src/index.ts AiflPromo out/promo.mp4",
+    "still": "remotion still src/index.ts AiflPromo"
+  },
+  "dependencies": {
+    "@remotion/cli": "4.0.484",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "remotion": "4.0.484"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "typescript": "6.0.3"
+  }
+}

package/lib/motion/shotcraft/upstream/template/remotion.config.ts

@@ -0,0 +1,6 @@
+import { Config } from '@remotion/cli/config';
+
+Config.setVideoImageFormat('jpeg');
+Config.setOverwriteOutput(true);
+Config.setChromiumOpenGlRenderer('angle');
+Config.setConcurrency(4);

package/lib/motion/shotcraft/upstream/template/src/Root.tsx

@@ -0,0 +1,17 @@
+import { Composition } from 'remotion';
+import { AIFL_TOTAL } from './aifl/Main';
+import { ThemedFilm } from './themes/ThemedFilm';
+
+export const Root: React.FC = () => {
+  return (
+    <Composition
+      id="AiflPromo"
+      component={ThemedFilm}
+      defaultProps={{theme: 'ink-press'}}
+      durationInFrames={AIFL_TOTAL}
+      fps={30}
+      width={1920}
+      height={1080}
+    />
+  );
+};