# 模板系统

模板会在运行时展开成普通 clips，不应被理解为一个会自动把样式或动画传递给子元素的父容器。

真实流程：
1. `template` clip 进入渲染器
2. 根据 `template` 找到模板定义和渲染器
3. 按 `defaults -> variant.defaults -> data -> overrides.data` 合并参数
4. 生成普通 clip 数组
5. 应用 `overrides.style` / `overrides.transition` / `overrides.zIndexOffset`
6. 这些普通 clip 再逐个渲染

## 1. 模板列表

当前支持：
- `product-intro`
- `slideshow`
- `subtitle-video`
- `talking-head`
- `comparison`
- `countdown`
- `text-reveal`
- `news`
- `quote`
- `list`

## 2. 通用限制

模板 clip 自己的以下字段，不作为已文档化的子 clip 继承行为：
- `transform`
- `animations`
- `keyframes`

模板内部控制应通过 `data` 传入。要统一覆盖展开后的子 clip 样式或转场，可以使用 `overrides`。

## 3. 模板高级字段

```ts
interface TemplateClip extends BaseClip {
  type: "template";
  template: TemplateType;
  variant?: string;
  version?: string;
  data: Record<string, any>;
  overrides?: {
    data?: Record<string, any>;
    style?: Style;
    transition?: Transition;
    zIndexOffset?: number;
  };
}
```

### `variant`
- 从模板注册表中选择一组预设参数
- 未找到对应 variant 时会继续使用默认模板，只输出 warning

### `version`
- 当前作为模板调用方声明字段保留
- 方便未来做模板版本兼容和迁移

### `overrides.data`
- 最后合并到模板参数中，优先级高于 `data`

### `overrides.style`
- 合并到展开后的非音频 clip `style`

### `overrides.transition`
- 给展开后的非音频 clip 补默认转场
- 如果子 clip 自己已有 `transition`，不会覆盖

### `overrides.zIndexOffset`
- 给展开后的所有子 clip 统一增加 zIndex

## 4. `product-intro`

当前有效字段：
- `name`
- `tagline`
- `features`
- `price`
- `image`
- `cta`

渲染行为：
- 可选左侧产品图
- 右侧产品标题与说明
- 可选特性列表
- 可选价格
- 可选 CTA 文本

示例：

```json
{
  "type": "template",
  "template": "product-intro",
  "start": 0,
  "duration": 8,
  "data": {
    "name": "Smart Watch Pro",
    "tagline": "Built for modern teams",
    "features": ["AMOLED display", "7-day battery", "Health tracking"],
    "price": "$299",
    "image": "https://example.com/watch.png",
    "cta": "Order Now"
  }
}
```

## 5. `slideshow`

当前有效字段：
- `images`
- `durationPerSlide`
- `showCaptions`
- `transition`

渲染行为：
- 每张图片展开成一个 `image` clip
- slide 使用当前内置切换行为
- `blur` / `push` / `iris` 会映射为真实 clip `transition`
- 当图片项包含 `caption` 且 `showCaptions !== false` 时，会生成说明文字

示例：

```json
{
  "type": "template",
  "template": "slideshow",
  "start": 0,
  "duration": 9,
  "data": {
    "images": [
      { "image": "https://example.com/slide-1.jpg", "caption": "Welcome" },
      { "image": "https://example.com/slide-2.jpg", "caption": "New Features" },
      { "image": "https://example.com/slide-3.jpg", "caption": "Get Started" }
    ],
    "durationPerSlide": 3,
    "showCaptions": true
  }
}
```

## 6. `subtitle-video`

当前有效字段：
- `src`
- `words`
- `config`
- `source`
- `volume`
- `muted`
- `playbackRate`

渲染行为：
- 生成一个全屏 `video`
- 生成一个 `subtitle`

示例：

```json
{
  "type": "template",
  "template": "subtitle-video",
  "start": 0,
  "duration": 8,
  "data": {
    "src": { "$ref": "host-video" },
    "words": { "$ref": "subtitle-main" },
    "muted": false,
    "volume": 1,
    "config": {
      "position": "bottom",
      "fontSize": 58,
      "highlightColor": "#22d3ee"
    }
  }
}
```

## 7. `talking-head`

当前有效字段：
- `src`
- `words`
- `config`
- `source`
- `volume`
- `muted`
- `playbackRate`
- `speaker`
- `role`
- `title`
- `showLowerThird`

渲染行为：
- 生成一个全屏人物视频
- 可选顶部标题
- 可选底部 lower-third 信息条
- 可选字幕轨

示例：

```json
{
  "type": "template",
  "template": "talking-head",
  "start": 0,
  "duration": 8,
  "data": {
    "src": { "$ref": "host-video" },
    "words": { "$ref": "subtitle-main" },
    "title": "Weekly Update",
    "speaker": "Alex Chen",
    "role": "Founder",
    "showLowerThird": true,
    "config": {
      "position": "bottom",
      "fontSize": 60,
      "highlightColor": "#22d3ee"
    }
  }
}
```

## 8. `comparison`

当前有效字段：
- `left.title`
- `left.items`
- `left.image`
- `right.title`
- `right.items`
- `right.image`
- `vsText`

渲染行为：
- 生成左右对比区块
- 支持两侧可选图片与列表
- 生成中间分隔线和 VS 文本

示例：

```json
{
  "type": "template",
  "template": "comparison",
  "start": 0,
  "duration": 7,
  "data": {
    "left": {
      "title": "Before",
      "items": ["Manual workflow", "Slow review", "Higher cost"],
      "image": "https://example.com/before.png"
    },
    "right": {
      "title": "After",
      "items": ["Automated workflow", "Fast review", "Lower cost"],
      "image": "https://example.com/after.png"
    },
    "vsText": "VS"
  }
}
```

## 9. `countdown`

当前有效字段：
- `from`
- `to`
- `showText`
- `onComplete`

渲染行为：
- 生成倒计时序列
- 临近结束时可显示提示文字
- 结束时可显示完成文案

示例：

```json
{
  "type": "template",
  "template": "countdown",
  "start": 0,
  "duration": 6,
  "data": {
    "from": 5,
    "to": 0,
    "showText": true,
    "onComplete": "Launch"
  }
}
```

## 10. `text-reveal`

当前有效字段：
- `text`
- `style`
- `speed`
- `fontSize`
- `fontFamily`
- `color`
- `textAlign`
- `position`

当前文档化的 `style` 值：
- `fade`
- `slide`
- `zoom`
- `typewriter`
- `glitch`

渲染行为：
- 生成分阶段出现的文字 clips
- 在当前已实现范围内应用指定 reveal 样式

示例：

```json
{
  "type": "template",
  "template": "text-reveal",
  "start": 0,
  "duration": 5,
  "data": {
    "text": "Ship faster with AI video",
    "style": "slide",
    "fontSize": 72,
    "color": "#ffffff",
    "textAlign": "center",
    "position": "center"
  }
}
```

## 11. `news`

当前有效字段：
- `headline`
- `content`
- `reporter`
- `location`
- `showLowerThird`

渲染行为：
- 主标题
- 可选内容区
- 可选底部信息条

示例：

```json
{
  "type": "template",
  "template": "news",
  "start": 0,
  "duration": 8,
  "data": {
    "headline": "Quarterly results exceed expectations",
    "content": "Revenue grew 38% year over year, driven by strong subscription growth.",
    "reporter": "Maya Lin",
    "location": "San Francisco",
    "showLowerThird": true
  }
}
```

## 12. `quote`

当前有效字段：
- `quote`
- `author`
- `source`

渲染行为：
- 渲染引用文本
- 可选作者与来源行

示例：

```json
{
  "type": "template",
  "template": "quote",
  "start": 0,
  "duration": 6,
  "data": {
    "quote": "Simplicity scales better than complexity.",
    "author": "Alex Chen",
    "source": "Team Memo"
  }
}
```

## 13. `list`

当前有效字段：
- `title`
- `items`
- `style`
- `itemDuration`
- `animation`

渲染行为：
- 可选标题
- 顺序生成列表项
- 支持前缀样式与条目动画
- `itemDuration: "auto"` 会自动分配总时长

示例：

```json
{
  "type": "template",
  "template": "list",
  "start": 0,
  "duration": 8,
  "data": {
    "title": "Release Checklist",
    "items": ["Finalize copy", "Export assets", "Publish update"],
    "style": "checkmark",
    "itemDuration": "auto",
    "animation": "fadeIn"
  }
}
```