# Template System

Templates expand into normal clips at runtime. They should not be treated as parent containers that automatically pass styling or animation to their generated children.

Runtime flow:
1. The `template` clip enters the renderer
2. The renderer resolves template definitions and defaults
3. Parameters merge as `defaults -> variant.defaults -> data -> overrides.data`
4. The template returns normal clips
5. `overrides.style`, `overrides.transition`, and `overrides.zIndexOffset` are applied

## 1. Registered templates

Currently supported:
- `product-intro`
- `slideshow`
- `subtitle-video`
- `talking-head`
- `comparison`
- `countdown`
- `text-reveal`
- `news`
- `quote`
- `list`

## 2. Shared limits

These fields on the template clip itself are not documented as inherited by generated child clips:
- `transform`
- `animations`
- `keyframes`

Template-specific control should be passed through `data`. Use `overrides` when you need to apply a common style or transition to generated clips.

## 3. Shared advanced fields

```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`
- Selects a registered preset for the template
- Unknown variants continue with the default template and emit a warning

### `version`
- Reserved for future template compatibility and migration

### `overrides.data`
- Merged last into template parameters

### `overrides.style`
- Merged into generated non-audio clip styles

### `overrides.transition`
- Added to generated non-audio clips that do not already define a transition

### `overrides.zIndexOffset`
- Adds a common offset to generated clip `zIndex` values

## 4. `product-intro`

Effective fields:
- `name`
- `tagline`
- `features`
- `price`
- `image`
- `cta`

Behavior:
- Optional product image on the left
- Product title and supporting text on the right
- Optional feature list
- Optional price
- Optional CTA text

Example:

```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`

Effective fields:
- `images`
- `durationPerSlide`
- `showCaptions`
- `transition`

Behavior:
- Each image expands into an `image` clip
- Slides use the current built-in transition behavior
- `blur`, `push`, and `iris` map to real clip transitions
- Caption text is generated when a slide includes `caption` and `showCaptions !== false`

Example:

```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`

Effective fields:
- `src`
- `words`
- `config`
- `source`
- `volume`
- `muted`
- `playbackRate`

Behavior:
- Generates a full-screen `video`
- Generates a `subtitle`

Example:

```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`

Effective fields:
- `src`
- `words`
- `config`
- `source`
- `volume`
- `muted`
- `playbackRate`
- `speaker`
- `role`
- `title`
- `showLowerThird`

Behavior:
- Generates a full-screen host video
- Optional top title
- Optional lower-third block
- Optional subtitle track

Example:

```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`

Effective fields:
- `left.title`
- `left.items`
- `left.image`
- `right.title`
- `right.items`
- `right.image`
- `vsText`

Behavior:
- Generates left and right comparison blocks
- Optional images and lists for both sides
- Generates center divider and VS text

Example:

```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`

Effective fields:
- `from`
- `to`
- `showText`
- `onComplete`

Behavior:
- Renders a countdown sequence
- Can show helper text near completion
- Can show a completion message

Example:

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

## 10. `text-reveal`

Effective fields:
- `text`
- `style`
- `speed`
- `fontSize`
- `fontFamily`
- `color`
- `textAlign`
- `position`

Documented style values:
- `fade`
- `slide`
- `zoom`
- `typewriter`
- `glitch`

Behavior:
- Generates one or more text clips for staged reveal
- Uses the selected reveal style where currently implemented

Example:

```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`

Effective fields:
- `headline`
- `content`
- `reporter`
- `location`
- `showLowerThird`

Behavior:
- Main headline
- Optional content block
- Optional lower-third information block

Example:

```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`

Effective fields:
- `quote`
- `author`
- `source`

Behavior:
- Renders quote text
- Optional author and source line

Example:

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

## 13. `list`

Effective fields:
- `title`
- `items`
- `style`
- `itemDuration`
- `animation`

Behavior:
- Generates a title when provided
- Generates list items in sequence
- Supports marker style and item animation
- `itemDuration: "auto"` distributes the total time automatically

Example:

```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"
  }
}
```

## 14. Variant and overrides example

```json
{
  "type": "template",
  "template": "slideshow",
  "variant": "cinematic",
  "start": 0,
  "duration": 9,
  "data": {
    "images": [
      { "image": "https://example.com/slide-1.jpg", "caption": "Launch" },
      { "image": "https://example.com/slide-2.jpg", "caption": "Scale" }
    ]
  },
  "overrides": {
    "data": {
      "transition": "blur"
    },
    "transition": {
      "type": "blur",
      "duration": 0.35,
      "blur": 18
    },
    "zIndexOffset": 20
  }
}
```