# ADR-0003: 预览与导出分层——交互近似预览 + 单一滤镜图计划

状态：已接受。日期：2026-09-01。来源：借鉴 Concat 预览近似与导出降级设计。

> 更新记录（2026-09-01）：采纳 ADR-0005 后，预览渲染器与导出渲染器成为插件贡献点（`registerPreviewRenderer` / `registerExportRenderer`）；单一滤镜图计划约束不变，对插件同样强制。

## 背景

Concat 的预览近似层：交互期间用 CSS 滤镜 / canvas 运算渲染近似效果，监视器播放引擎真帧；其原则是"导出只是你已看到内容的更高画质版本"。转场在导出器降级（交叉淡化 → 重叠片段 + 透明度斜坡）。Concat 自述的最大债务是 chains mirror（§6.1）：TS 手写镜像 Rust 滤镜链，两侧靠钉死测试维持一致，新增效果成本翻倍。

影策已有 `timeline-to-ffmpeg.ts` 纯函数规划层（trim → gap → concat → subtitle → burn），`timeline-export.ts` 用浏览器 ffmpeg.wasm 执行；后端 Go 暂无 ffmpeg。

## 决策

- **交互预览只做浏览器原生近似**：`<video>` 裁剪/缩放/透明度/音量、CSS 滤镜、canvas 合成近似。近似预览是交互真相，但不是导出像素；UI 上不把两者混为一谈。
- **预览渲染器与导出渲染器为插件贡献点**：预设插件（如转场/滤镜效果插件）通过 `registerPreviewRenderer` / `registerExportRenderer` 贡献渲染实现；宿主按插槽渲染，插件不得绕过插槽直接挂载 DOM。
- **单一滤镜图计划对插件强制生效**：插件贡献的导出渲染必须消费 `buildTimelineRenderPlan` 的输出参数，禁止插件内部自行拼第二套滤镜串（无论多简单）。
- **导出滤镜图只由 `buildTimelineRenderPlan` 单一模块生成**：这是滤镜串的唯一来源。主路径为 Go 后端 ffmpeg 任务（复用任务队列），浏览器 ffmpeg.wasm 为降级路径，二者吃同一份计划。
- **新增效果必须同时产出两份描述，且出自同一参数模型**：`预览近似描述`（CSS/canvas 等价实现）与 `导出滤镜参数`（ffmpeg filtergraph 片段）。禁止在 UI 组件里手写第二套滤镜串——即不复制 Concat 的 chains mirror 债务。
- 转场、滤镜等视觉允许预览与导出存在级差（如预览用近似淡化、导出用 xfade/淡入淡出），但参数必须同源，不允许出现"预览一套、导出另一套"的漂移。

## 后果

- 滤镜参数模型成为编辑器和导出共用的契约：新增效果 = 参数模型 + 两份降级实现，测试围绕参数模型做黄金文件。
- 预览与导出管线各自可演进：服务端派生"预览近似描述"（Concat 式 engine emits preview looks）时，无需改 UI 消费方式。
- 浏览器 wasm 与后端 ffmpeg 的切换不改变编辑模型；wasm 仅承担无后端场景下的降级导出。
- 渲染器插件化后，新增效果仍是「参数模型 + 预览近似 + 导出滤镜」三件套，只是后两者的实现方变为插件；参数模型仍是黄金文件测试的唯一锚点，防止插件间出现参数漂移。