# VanillaSky scene templates — agent index

> Generated by `npm run gen:registry` from `src/lib/scene-templates/registry.ts` — do not edit.
> Every template is a `registry:block` in the shadcn-compatible registry
> (repo: `registry/registry.json`). Per-item JSON with source, full variable
> schema, and defaults: `https://vanillasky.ai/r/<name>.json` (repo:
> `registry/r/<name>.json`).
>
> `npx shadcn add @vanillasky/<name>` works once the `@vanillasky` namespace is
> mapped in the consuming project's `components.json`:
> `{ "registries": { "@vanillasky": "https://vanillasky.ai/r/{name}.json" } }`.
> Without that entry the namespace does not resolve. Reading the item JSON
> directly needs no setup at all.
>
> All templates are orientation-responsive: the same config renders portrait
> 9:16 (1080x1920) or landscape 16:9 (1920x1080) via the config's `orientation`
> field — the user's choice, portrait when omitted.
>
> Durations are seconds (min–preferred). Variables = field count in the item's
> `meta.vanillasky.variableSchema`. `{needs stat/quote/screenshot}` are hard gates:
> the input must actually contain that material — never fabricate it.

## Core

The 10 templates to reach for first — one per motion archetype, register-diverse.

| Template | Use when | Register | Jobs | Duration | Variables | Tier |
|---|---|---|---|---|---|---|
| `media` | **Archetype: hook.** The default opener — full-frame footage with a text effect riding the motion; also the atmospheric body bridge. Full-bleed photo, video, or gradient with open text. Use for hooks, atmospheric body beats, uploaded scenic media, or a concrete product-context sentence over footage. | motion-led | atmosphere, setup | 1–2s | 6 | free |
| `bigNumber` | **Archetype: stat-pop.** Hero number counts up and pops; everything else stays quiet. One important real number explicitly present in the input: customer count, reduction, uplift, speed claim, percentage, rank, or headline metric. Use only when you can copy the exact number into value/prefix/unit; never invent a number or leave the default. {needs stat} | typography-led | claim, proof | 1.5–4s | 11 | free |
| `tweet` | **Archetype: social card.** Brand-voiced post that reads like a real public post. X-style post card with optional 1-4 image grid (tweetImage1..4). Brand-voiced announcement that reads like a real public post, launch quote, founder update, or compact social claim. Avoid for generic product explainers. | card-led | claim, proof | 2.5–3.5s | 10 | free |
| `testimonial` | **Archetype: reveal-slide.** Quote card fades/scales in, inner content word-by-word. One real attributed customer quote, testimonial, review, or named endorsement. Do not fabricate names, roles, or quotes. {needs quote} | card-led | proof | 2.5–4s | 8 | free |
| `phoneMockup` | **Archetype: mockup-zoom.** Phone chrome slides up and settles; real portrait UI only. Uploaded portrait/mobile UI screenshots or a mobile app workflow. Use one scene for up to three same-orientation phone screens. {needs screenshot} | device-led | proof, atmosphere | 2–3s | 5 | free |
| `terminal` | **Archetype: dev device.** A command or log output IS the content; synthesize from the input. Developer or technical product where a CLI command, install command, log output, deploy/test flow, or status result communicates the workflow better than prose. Prefer when the input includes a command or install snippet. | device-led | proof, atmosphere | 2–3s | 5 | free |
| `steps` | **Archetype: card-grid-stagger.** Ordered cards spring in one at a time. Sequential workflow or how-it-works explanation where order matters: connect, generate, review, publish. Avoid for unordered feature lists. | card-led | proof, setup | 2–3.5s | 4 | free |
| `beforeAfter` | **Archetype: transformation.** Two states, one contrast. Clear transformation or contrast between two states, especially symbolic or visual before/after: manual to automated, chaos to order, old way to new way. | motion-led | proof, setup | 3–4.5s | 7 | free |
| `milestone` | **Archetype: celebrate-burst.** Number + particles radiating from center. Real numeric achievement explicitly in the input: users, revenue, years, installs, customers, stars, or adoption count. Use exact targetNumber; never for generic releases, versions, 'free', or proof without an achievement count. {needs stat} | typography-led | claim, proof | 2.5–4s | 10 | free |
| `ctaLogo` | **Archetype: text-slam closer.** Prefer over ctaMedia when a real logo exists or 2+ scenes already ran full-frame footage. Minimal brand stamp closer when the video already has enough motion or proof and only needs brand, URL, or a simple next action. | typography-led | ask | 2–3.5s | 8 | free |

## Text archetypes (scene-level `textArchetype`)

Six complete text lifecycles (entrance + hold + exit) — the biggest single
quality lever on text-led scenes. Set on the SCENE (never inside `variables`);
unset or unknown values fall back to `subtle`. Canvas must match the template's
`meta.vanillasky.textCanvas` — `open`-only archetypes look broken on `tight`
canvases (cards, mockups).

| Value | Use when | Roles | Canvas |
|---|---|---|---|
| `subtle` | Quiet fade for supporting captions — the visual is the star; the safe default over busy footage. | body, closer | tight, open |
| `typewriter` | Char-by-char reveal with blinking cursor — terminal/dev-flavored copy or "typing the prompt" moments. | body, hook | tight, open |
| `wordStagger` | Words land one at a time with active-word focus — rhythmic multi-word statements meant to be read in order. | body | tight, open |
| `slam` | Squash-and-stretch impact with frame shake — punchy short hooks (≤4 words) that must hit hard. | hook, body | tight, open |
| `cinematic` | Trailer fly-in from depth that recedes on exit — dramatic brand statements. | hook, body, closer | open |
| `heroWord` | One oversized word per beat fills the frame — ultra-short declarations where each word is a beat. | hook, body, closer | open |

## Style presets (video-level `style.preset`)

The frame-level look: background family, headline type treatment, and default
title placement, moved together by one token. Set it ONCE on `style`, not per
scene. This is the main lever against every video looking alike — two videos
with the same brand colors and different presets read as different pieces.
Unset resolves to the default, which is the original look.

| Preset | Use when | Background | Title |
|---|---|---|---|
| `bold` *(default)* | The default. Drifting two-color brand mesh, heavy tight headlines at the top. Launches, hype, product moments — the loudest of the three. | mesh | top |
| `editorial` | Calm vertical wash, lighter and wider-tracked headlines, centered. Reviews, thoughtful updates, premium or B2B brands — when the copy should feel considered rather than shouted. | wash | centered, lighter, wider tracking, larger (1.08×) |
| `stark` | Single hard spotlight on near-black, uppercase and tightly tracked. Dev tools, technical claims, high-contrast statements — maximum weight on very few words. | spotlight | top, uppercase, heavier, tighter tracking |

## Full catalog

The remaining templates, by category. Core templates above also belong to these
categories (category shown per template in its registry item's `meta.vanillasky.category`).

### media

| Template | Use when | Register | Jobs | Duration | Variables | Tier |
|---|---|---|---|---|---|---|
| `reaction` | Use once for funny/meme/self-aware/roast/silly/unhinged/lol videos. Short full-bleed reaction clip with a punchline. Hook or body payoff. Pick reactionTag from the enum; search appends `meme` to nudge Pexels toward expressive footage. Max one per video. | motion-led | setup, claim | 2.5–3s | 4 | free |

### celebration

| Template | Use when | Register | Jobs | Duration | Variables | Tier |
|---|---|---|---|---|---|---|
| `confetti` | *Runner-up — prefer `milestone` for numeric achievements, `emojiBurst` for themed celebration.* Generic celebration or broad win when no specific emoji theme or numeric milestone is the main point. Prefer emojiBurst for themed emoji celebrations and milestone for numeric achievements. | motion-led | atmosphere | 1–2s | 2 | free |
| `emojiBurst` | Themed celebration where a small emoji set communicates the moment, such as launch, love, achievement, or delight. Prefer confetti for generic celebration. | motion-led | atmosphere | 1–2s | 2 | free |

### data

| Template | Use when | Register | Jobs | Duration | Variables | Tier |
|---|---|---|---|---|---|---|
| `barChart` | Comparison, ranking, trend, or multiple values where relative size matters. Use for category comparisons, before/after quantities, or grouped metrics. {needs stat} | motion-led | proof | 2–3.5s | 4 | free |
| `progressRing` | Completion, readiness, health score, goal progress, adoption progress, or percent complete. Do not use for generic uplift, reduction, speed, or loose percentage claims. {needs stat} | motion-led | proof | 2–3.5s | 6 | free |
| `tripleStats` | Exactly three peer stats or compact specs from the input with comparable weight. Prefer over bigNumber for three parallel facts. Avoid when one number is the hero or values are just brand/tool names. {needs stat} | typography-led | claim, proof | 2–3s | 8 | free |

### device

| Template | Use when | Register | Jobs | Duration | Variables | Tier |
|---|---|---|---|---|---|---|
| `webMockup` | Uploaded landscape or square desktop/web screenshots, dashboard views, or browser/tablet product surfaces. Use one scene for up to three same-orientation screens. {needs screenshot} | device-led | proof, atmosphere | 2–3s | 7 | free |
| `codeEditor` | *Paired with `terminal` — prefer `terminal` when the input has a command/install/log; `codeEditor` for code/config samples.* Developer product, API, SDK, config, codebase, tests, or code-focused workflow where a short synthetic code sample explains the product mechanism. Prefer over generic brand/card scenes when code is a core input signal. | device-led | proof, atmosphere | 2–3s | 4 | free |

### social

| Template | Use when | Register | Jobs | Duration | Variables | Tier |
|---|---|---|---|---|---|---|
| `notification` | A real notification-shaped product moment: alert, reminder, task done, system update, approval, message, or 'your X is ready' event. Avoid for generic URL launches, broad brand announcements, or product explanations. | card-led | proof, setup | 2–3s | 8 | free |
| `chatMessenger` | Short synthetic Messenger-style conversation when a back-and-forth helps explain a use case, objection, or punchline. Use sparingly because it is long. | mockup-led | proof, setup | 5–8s | 7 — `msg1`..`msg5` + `dateChip1`/`dateChip2`, NOT a `bubbles` array | free |
| `chatWhatsapp` | *Runner-up — prefer `chatMessenger` unless the story is explicitly customer-service/WhatsApp shaped.* Short synthetic WhatsApp-style conversation when the product story is naturally conversational or customer-service oriented. Use sparingly because it is long. | mockup-led | proof, setup | 5–8s | 7 — `msg1`..`msg5` + `dateChip1`/`dateChip2`, NOT a `bubbles` array | free |
| `reviewStack` | Two or more real attributed reviews, ratings, or quotes that should appear as social proof together. Requires real quote/source content. {needs quote} | card-led | proof | 2.5–4s | 14 — `review1Title`/`review1Body`/`review1Author` × 3, NOT a `reviews` array | free |
| `incomingCall` | Urgent, interruptive, comeback, or dramatic moment where the brand/product conceptually calls the viewer. Avoid as the default for generic URL launches or calm explanations. | card-led | setup, atmosphere | 2.5–4s | 9 — `callerName`, NOT `brandName` | free |
| `brandMessage` | Single iMessage-style outgoing bubble over media. Use only when a direct 1:1 brand-to-viewer note is the point: thanks, invitation, personal promise, concise launch note. Avoid as generic filler, explanation, or proof. | card-led | claim, setup | 2.5–4s | 6 | free |
| `promptInput` | Centered AI prompt-input demo: pill grows from a circle with sparkles icon, then types the prompt. Use for product PROMPT UX: 'describe what you want', 'ask the AI', or 'show how to prompt'. | card-led | setup, atmosphere | 2.5–4s | 7 — `promptText`, NOT `prompt` | free |

### explainer

| Template | Use when | Register | Jobs | Duration | Variables | Tier |
|---|---|---|---|---|---|---|
| `problemSolution` | Literal pain-to-fix story where the central message is one problem statement and one solution statement. Avoid for generic SaaS launches without a crisp pain/fix pair. | card-led | setup, proof | 3–5.5s | 5 | free |
| `cardList` | Three to five concrete product facts, benefits, use cases, integrations, or feature bullets. Good for product comprehension when the facts are parallel. | card-led | proof, setup | 2–3.5s | 4 | free |

### closer

| Template | Use when | Register | Jobs | Duration | Variables | Tier |
|---|---|---|---|---|---|---|
| `ctaMedia` | *Closer fallback — prefer `ctaLogo` when a real logo exists or 2+ scenes already ran full-frame footage.* Cinematic media-backed closer with headline and URL. Default closer for launch videos when a final visual beat helps the call to action. | typography-led | ask | 2–4s | 8 | free |

## Primitives (`registry:ui`)

The building blocks the templates above are made of — the top rung of the
escalation ladder. Reach for these only when no template expresses the brief.

Inside a `custom_*` scene's `componentSource` every primitive below is
**already in scope by its component name** — custom source takes no imports.
`vanillasky scope` prints the exact global list, and SKILL.md carries the full
custom-scene contract. Each item's `meta.vanillasky.propSchema` documents its
props (name, type, required, description); the source is `files[0].content`.
`npx shadcn add @vanillasky/<name>` is for installing into your own React
project — it does not change what the `vanillasky` CLI renders.

Every primitive is progress-driven, deterministic, and renders at both
1080x1920 and 1920x1080.

| Primitive | Use when | Used by |
|---|---|---|
| `barChartPrimitive` | Animated bar chart — bars grow from zero on EDITORIAL. Compose when several values must be compared in one frame. | `barChart` |
| `beforeAfterSplit` | Split frame contrasting a problem side against a solution side, each with its own headline and emoji set. Compose for transformation beats. | `beforeAfter` |
| `brandMessageBubble` | Single iMessage-style outgoing bubble over media. Compose for a direct 1:1 brand-to-viewer note. | `brandMessage` |
| `codeEditorPrimitive` | Editor chrome with syntax-highlighted code and a filename tab. Compose when a code or config sample is the content. | `codeEditor` |
| `conversationThread` | Multi-bubble chat thread with staggered reveal, typing indicators, and date chips. Compose for Messenger/WhatsApp-shaped stories; theme switches the platform look. | — |
| `countUpNumber` | Hero number that counts up to a target with prefix, unit, and label. Compose whenever one real number is the point. | `bigNumber` |
| `ctaMediaClose` | Media-backed closer with brand name, URL, and call to action. Compose for a final visual beat. | — |
| `designedScreenFill` | Brand-tinted synthetic product UI that fills a device screen when no real screenshot exists. Compose inside phoneFrame/webMockupPrimitive as a fallback — prefer a real screenshot whenever one is provided. *(install-only — not in scope inside `componentSource`)* | `webMockup` |
| `featureGrid` | Grid of feature cards that spring in staggered. Compose for 4+ parallel facts where a list would read too tall. | — |
| `featureList` | Vertical list of feature rows revealed in sequence. Compose for 3–5 parallel product facts. | — |
| `incomingCallCard` | Full-screen incoming-call UI with caller name and accept/decline actions. Compose for interruptive or dramatic beats. | — |
| `milestoneBadge` | Numeric achievement badge with rolling counter, glow, and celebration burst. Compose for a real milestone number. | `milestone` |
| `notificationCard` | OS-style notification card with app icon and message. Compose for a real notification-shaped product moment. | `notification` |
| `phoneFrame` | Portrait phone chrome that slides up and settles, wrapping up to three screens. Compose for mobile UI; pair with designedScreenFill when no screenshot exists. | `phoneMockup` |
| `problemSolutionPrimitive` | Two stacked statements — one pain, one fix — with labels. Compose for a literal problem→solution story. | — |
| `progressRingPrimitive` | Circular progress ring that draws from 0 with a centered value. Compose for completion, readiness, or percent-complete. | `progressRing` |
| `promptInputPill` | AI prompt pill that grows from a circle then types the prompt. Compose for prompt-UX explanations. | `promptInput` |
| `reactionClip` | Full-bleed reaction/meme video clip with an optional punchline overlay. Compose at most once, for funny or self-aware beats. | — |
| `reviewStackPrimitive` | Stacked review cards with staggered spring entrance and star ratings. Compose for 2+ real attributed reviews. | `reviewStack` |
| `statBadgeRow` | Row of peer stat badges with comparable weight. Compose for exactly three parallel facts. | `tripleStats` |
| `stepsList` | Ordered step cards that spring in one at a time. Compose when sequence matters (connect → generate → publish). | `steps` |
| `terminalOutput` | Terminal chrome that types a command then streams output lines. Compose when a CLI command or log IS the content. | `terminal` |
| `testimonialCard` | Single quote card with author name, role, and avatar. Compose for one real attributed quote. | `testimonial` |
| `tweetCard` | X-style post card with verification badge and like/reply counters. Compose for a brand-voiced public post. | `tweet` |
| `webMockupPrimitive` | Browser/desktop chrome with an address bar, wrapping up to three landscape screens. Compose for dashboard or web UI. | — |
| `wordmarkReveal` | Minimal brand stamp — wordmark or logo with URL and action. Compose for a quiet closer when the video already has motion. | `ctaLogo` |

## Libs (`registry:lib`)

Shared vocabulary for custom scenes. Import from these instead of hardcoding
curves, colors, or font stacks.

| Lib | What it gives you | Used by |
|---|---|---|
| `animation-utils` | Core motion vocabulary — `interpolate`, `spring`, `Easing` (incl. `Easing.bezier`), the `SPRING_*` presets, `stagger`, `cubicBezier`. Every custom scene's curves resolve to these; do not reinvent values. | `barChart`, `bigNumber`, `brandMessage`, `cardList`, `chatMessenger`, `chatWhatsapp`, `codeEditor`, `confetti`, `ctaLogo`, `ctaMedia`, `emojiBurst`, `incomingCall`, `media`, `milestone`, `notification`, `phoneMockup`, `problemSolution`, `progressRing`, `promptInput`, `reaction`, `reviewStack`, `steps`, `terminal`, `testimonial`, `tripleStats`, `tweet`, `webMockup` |
| `text-utils` | Text measurement and fitting helpers — notably `fitTextSize(text, baseSize, maxWidth)` for shrink-to-fit copy in fixed-width containers. | `bigNumber`, `brandMessage`, `ctaMedia`, `incomingCall`, `milestone`, `progressRing`, `promptInput`, `testimonial` |
| `tokens` | The canonical brand-token resolver: one derivation path from a config's `style` + `brandKit` to the resolved `accent` / `surface` / `surface_elevated` / `content` / `muted` / `font` / `script_font` tokens, plus `fontStack()`. Read tokens from here instead of hardcoding colors or font stacks. | `barChart`, `beforeAfter`, `bigNumber`, `brandMessage`, `cardList`, `codeEditor`, `confetti`, `ctaLogo`, `ctaMedia`, `emojiBurst`, `incomingCall`, `media`, `milestone`, `notification`, `phoneMockup`, `problemSolution`, `progressRing`, `promptInput`, `reaction`, `reviewStack`, `steps`, `terminal`, `testimonial`, `tripleStats`, `tweet`, `webMockup` |