@vanillaskyai/video 0.8.7 → 0.9.0

package/dist/template-catalog.d.ts

@@ -1,24 +1,265 @@
-import { S as SceneTemplateMetadata, T as TemplateFamily, a as TemplateJob, b as TemplateRegister, c as TemplateTimingMetadata } from './catalog-types-BIhSpOWK.js';
+import { S as SceneTemplateMetadata, b as TemplateTimingMetadata } from './catalog-types-WTbLP6Jh.js';
 
-type BuiltinTemplateId = "media" | "reaction" | "confetti" | "emojiBurst" | "bigNumber" | "barChart" | "progressRing" | "phoneMockup" | "webMockup" | "codeEditor" | "terminal" | "tweet" | "notification" | "chatMessenger" | "chatWhatsapp" | "milestone" | "reviewStack" | "testimonial" | "incomingCall" | "brandMessage" | "promptInput" | "beforeAfter" | "tripleStats" | "problemSolution" | "cardList" | "steps" | "ctaLogo" | "ctaMedia";
+declare const BUILTIN_TEMPLATE_SCHEMAS: {
+    readonly cinemaMedia: {
+        readonly type: "object";
+        readonly properties: {
+            readonly mediaKeyword: {
+                readonly type: "string";
+                readonly format: "stock-media-keyword";
+                readonly minLength: 1;
+                readonly maxLength: 80;
+                readonly description: "2–8 word literal subject/action search intent, maximum 80 characters. Host resolves URLs.";
+                readonly examples: readonly ["Ocean waves breaking on a rocky shore"];
+            };
+            readonly mediaUrl: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly description: "Host-only approved photo or video URL.";
+                readonly default: "";
+            };
+            readonly mediaType: {
+                readonly type: "string";
+                readonly enum: readonly ["photo", "video"];
+                readonly default: "video";
+                readonly description: "Host-resolved asset kind.";
+            };
+            readonly mediaPoster: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly description: "Host-only approved poster URL for video decoding.";
+                readonly default: "";
+            };
+            readonly shotDirection: {
+                readonly type: "string";
+                readonly maxLength: 220;
+                readonly description: "Optional action, framing and continuity for generation. Preserve the subject; do not request rendered text.";
+            };
+            readonly mediaSource: {
+                readonly type: "string";
+                readonly enum: readonly ["generate", "stock"];
+                readonly description: "Generate distinctive illustrative shots; use approved stock for familiar observable subjects.";
+            };
+            readonly fallbackText: {
+                readonly type: "string";
+                readonly maxLength: 65;
+                readonly description: "Optional grounded concise chapter text if this shot cannot be resolved; not visible over footage.";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: false;
+        readonly "x-vanillasky": {
+            readonly allowsStockMedia: true;
+            readonly requiredAnyOf: readonly [readonly ["mediaKeyword", "mediaUrl"]];
+        };
+    };
+    readonly chapterTitle: {
+        readonly type: "object";
+        readonly properties: {
+            readonly title: {
+                readonly type: "string";
+                readonly maxLength: 65;
+                readonly description: "Short title. Line breaks optional.";
+                readonly default: "A different perspective";
+            };
+        };
+        readonly required: readonly ["title"];
+        readonly additionalProperties: false;
+    };
+    readonly focusCards: {
+        readonly type: "object";
+        readonly properties: {
+            readonly items: {
+                readonly type: "array";
+                readonly minItems: 2;
+                readonly maxItems: 4;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 55;
+                };
+                readonly default: readonly ["Listen closely", "Notice the pattern", "Make room for change"];
+                readonly description: "2–4 parallel phrases, about 2–6 words each; no heading or numbering.";
+            };
+        };
+        readonly required: readonly ["items"];
+        readonly additionalProperties: false;
+    };
+    readonly editorialTimeline: {
+        readonly type: "object";
+        readonly properties: {
+            readonly events: {
+                readonly type: "array";
+                readonly minItems: 3;
+                readonly maxItems: 5;
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly label: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 45;
+                        };
+                    };
+                    readonly required: readonly ["label"];
+                    readonly additionalProperties: false;
+                };
+                readonly default: readonly [{
+                    readonly label: "Observe";
+                }, {
+                    readonly label: "Understand";
+                }, {
+                    readonly label: "Act";
+                }];
+                readonly description: "3–5 ordered events or actions, each with one short label; no dates.";
+            };
+        };
+        readonly required: readonly ["events"];
+        readonly additionalProperties: false;
+    };
+    readonly mobileMessage: {
+        readonly type: "object";
+        readonly properties: {
+            readonly mediaKeyword: {
+                readonly type: "string";
+                readonly format: "stock-media-keyword";
+                readonly minLength: 1;
+                readonly maxLength: 80;
+                readonly description: "2–8 word literal subject/action search intent, maximum 80 characters. Host resolves URLs.";
+                readonly examples: readonly ["Ocean waves breaking on a rocky shore"];
+            };
+            readonly mediaUrl: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly description: "Host-only approved photo or video URL.";
+                readonly default: "";
+            };
+            readonly mediaType: {
+                readonly type: "string";
+                readonly enum: readonly ["photo", "video"];
+                readonly default: "video";
+                readonly description: "Host-resolved asset kind.";
+            };
+            readonly mediaPoster: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly description: "Host-only approved poster URL for video decoding.";
+                readonly default: "";
+            };
+            readonly message: {
+                readonly type: "string";
+                readonly maxLength: 120;
+                readonly default: "Can we talk?";
+                readonly description: "Exact supplied or explicitly illustrative message, preferably 6–16 words.";
+            };
+            readonly app: {
+                readonly type: "string";
+                readonly maxLength: 24;
+                readonly default: "Messages";
+                readonly description: "Optional app label; Messages is the visual default.";
+            };
+            readonly shotDirection: {
+                readonly type: "string";
+                readonly maxLength: 220;
+                readonly description: "Optional action, framing and continuity for generation. Preserve the subject; do not request rendered text.";
+            };
+            readonly mediaSource: {
+                readonly type: "string";
+                readonly enum: readonly ["generate", "stock"];
+                readonly description: "Generate distinctive illustrative shots; use approved stock for familiar observable subjects.";
+            };
+        };
+        readonly required: readonly ["message"];
+        readonly additionalProperties: false;
+        readonly "x-vanillasky": {
+            readonly allowsStockMedia: true;
+        };
+    };
+    readonly comparison: {
+        readonly type: "object";
+        readonly properties: {
+            readonly leftLabel: {
+                readonly type: "string";
+                readonly maxLength: 20;
+                readonly description: "Optional short identifier for the first alternative.";
+            };
+            readonly rightLabel: {
+                readonly type: "string";
+                readonly maxLength: 20;
+                readonly description: "Optional short identifier for the second alternative.";
+            };
+            readonly leftText: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 60;
+                readonly default: "More distractions";
+                readonly description: "First real alternative in one short phrase.";
+            };
+            readonly rightText: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 60;
+                readonly default: "More room to think";
+                readonly description: "Second real alternative, parallel to the first.";
+            };
+        };
+        readonly required: readonly ["leftText", "rightText"];
+        readonly additionalProperties: false;
+    };
+    readonly quote: {
+        readonly type: "object";
+        readonly properties: {
+            readonly quote: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 140;
+                readonly format: "grounded-quote";
+                readonly examples: readonly ["Look closely. There is always more to see."];
+                readonly description: "Exact supplied quotation; do not paraphrase or invent.";
+            };
+            readonly attribution: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 60;
+                readonly examples: readonly ["Illustrative example"];
+                readonly description: "Grounded attribution belonging to these exact quoted words.";
+            };
+        };
+        readonly required: readonly ["quote", "attribution"];
+        readonly additionalProperties: false;
+    };
+    readonly keyFigure: {
+        readonly type: "object";
+        readonly properties: {
+            readonly value: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 14;
+                readonly format: "grounded-stat";
+                readonly examples: readonly ["42%"];
+                readonly description: "One supplied supported quantity, preserving its unit.";
+            };
+            readonly label: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 50;
+                readonly examples: readonly ["Illustrative example"];
+                readonly description: "Exactly one short label identifying the quantity and its context.";
+            };
+        };
+        readonly required: readonly ["value", "label"];
+        readonly additionalProperties: false;
+        readonly "x-vanillasky": {
+            readonly requiresStat: true;
+        };
+    };
+};
+
+type BuiltinTemplateId = keyof typeof BUILTIN_TEMPLATE_SCHEMAS;
 interface BuiltinTemplateManifestEntry extends SceneTemplateMetadata {
     id: BuiltinTemplateId;
-    label: string;
-    description: string;
-    family: TemplateFamily;
-    jobs: TemplateJob[];
-    register: TemplateRegister;
-    useWhen: string;
-    avoidWhen: string;
-    textCanvas: "tight" | "open";
-    minDuration: number;
-    preferredDuration: number;
     timing: TemplateTimingMetadata;
 }
-/**
- * Canonical, serializable metadata for every bundled template.
- * Schemas own defaults; this manifest owns discovery, selection, and timing hints.
- */
 declare const BUILTIN_TEMPLATE_MANIFEST: readonly BuiltinTemplateManifestEntry[];
 
 export { type BuiltinTemplateId, type BuiltinTemplateManifestEntry as BuiltinTemplateMetadata, BUILTIN_TEMPLATE_MANIFEST as builtinTemplates };

package/dist/template-catalog.js

@@ -1,6 +1,6 @@
 import {
   BUILTIN_TEMPLATE_MANIFEST
-} from "./chunk-PP3MCPN4.js";
+} from "./chunk-MXEYPK7M.js";
 export {
   BUILTIN_TEMPLATE_MANIFEST as builtinTemplates
 };

package/dist/templates.d.ts

@@ -1,9 +1,9 @@
-import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-tQnCPMOM.js';
-export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-tQnCPMOM.js';
+import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-DrRpdn0p.js';
+export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-DrRpdn0p.js';
 import { ComponentType } from 'react';
-import { d as TemplateJsonSchema, S as SceneTemplateMetadata } from './catalog-types-BIhSpOWK.js';
-export { T as TemplateFamily, c as TemplateTimingMetadata, e as TemplateTransitionTiming } from './catalog-types-BIhSpOWK.js';
-import './types-CEh9eUFu.js';
+import { T as TemplateJsonSchema, S as SceneTemplateMetadata } from './catalog-types-WTbLP6Jh.js';
+export { a as TemplateFamily, b as TemplateTimingMetadata, c as TemplateTransitionTiming } from './catalog-types-WTbLP6Jh.js';
+import './types-DdZw4GRQ.js';
 
 interface TemplateExample<Variables extends Record<string, unknown> = Record<string, unknown>> {
     name: string;

package/dist/test.d.ts

@@ -1,5 +1,5 @@
-import { e as VideoScene, b as VideoOrientation, V as VideoStyle, c as Video, d as VideoAudio, g as VideoInput } from './types-CEh9eUFu.js';
-import { V as VideoWarning, a as VideoFinishReason } from './events-BQ6z264n.js';
+import { e as VideoScene, f as VIDEO_PROTOCOL_VERSION, b as VideoOrientation, V as VideoStyle, c as Video, d as VideoAudio, j as VideoInput } from './types-DdZw4GRQ.js';
+import { V as VideoWarning, a as VideoFinishReason } from './events-B4YCc4vc.js';
 
 type MockVideoStreamPart = {
     type: "scene.add";
@@ -35,7 +35,7 @@ interface MockProviderTextStream {
     finishReason: Promise<"stop" | "length" | "content-filter">;
 }
 type SimulatedEventEnvelope<TType extends string, TData> = {
-    protocolVersion: "0.5";
+    protocolVersion: typeof VIDEO_PROTOCOL_VERSION;
     runId: string;
     sequence: number;
     eventId: string;

package/dist/test.js

@@ -25,8 +25,8 @@ var portrait = {
       type: "scene.add",
       scene: {
         id: "portrait-summary",
-        templateId: "notification",
-        variables: { appName: "VanillaSky", message: "Grounded product update" },
+        templateId: "mobileMessage",
+        variables: { app: "VanillaSky", message: "Grounded product update" },
         timing: { fixedDuration: 4 }
       }
     },
@@ -43,8 +43,8 @@ var landscape = {
       type: "scene.add",
       scene: {
         id: "landscape-metric",
-        templateId: "bigNumber",
-        variables: { texts: "Revenue", value: 42, label: "million" },
+        templateId: "keyFigure",
+        variables: { value: "42 million", label: "Revenue" },
         timing: { fixedDuration: 4 }
       }
     },
@@ -60,8 +60,8 @@ var truncated = [
     type: "scene.add",
     scene: {
       id: "truncated-partial",
-      templateId: "notification",
-      variables: { appName: "VanillaSky", message: "Playable partial result" },
+      templateId: "mobileMessage",
+      variables: { app: "VanillaSky", message: "Playable partial result" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -81,8 +81,8 @@ var invalidScene = [
     type: "scene.add",
     scene: {
       id: "valid-after-invalid",
-      templateId: "notification",
-      variables: { appName: "VanillaSky", message: "Recovered after invalid content" },
+      templateId: "mobileMessage",
+      variables: { app: "VanillaSky", message: "Recovered after invalid content" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -99,8 +99,8 @@ var contentFilter = [
     type: "scene.add",
     scene: {
       id: "content-filter-partial",
-      templateId: "notification",
-      variables: { appName: "VanillaSky", message: "Safe partial result" },
+      templateId: "mobileMessage",
+      variables: { app: "VanillaSky", message: "Safe partial result" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -111,8 +111,8 @@ var abort = [
     type: "scene.add",
     scene: {
       id: "abort-partial",
-      templateId: "notification",
-      variables: { appName: "VanillaSky", message: "Partial result before cancellation" },
+      templateId: "mobileMessage",
+      variables: { app: "VanillaSky", message: "Partial result before cancellation" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -123,8 +123,8 @@ var timeout = [
     type: "scene.add",
     scene: {
       id: "timeout-partial",
-      templateId: "notification",
-      variables: { appName: "VanillaSky", message: "Partial result before timeout" },
+      templateId: "mobileMessage",
+      variables: { app: "VanillaSky", message: "Partial result before timeout" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -233,10 +233,10 @@ async function* simulateVideoStream(parts, options = {}) {
   if (timeoutMs != null && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
     throw new Error("Simulation timeoutMs must be a non-negative finite number");
   }
-  const { createVideo } = await import("./compose-video-2NFH4DZY.js");
-  const { createTextDeltaVideoPlanner } = await import("./text-stream-54LXABJW.js");
-  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-CUYPIDE7.js");
-  const { createTemplateSceneValidator } = await import("./validate-T7GBU2YF.js");
+  const { createVideo } = await import("./compose-video-TBFTONUC.js");
+  const { createTextDeltaVideoPlanner } = await import("./text-stream-LD364KBI.js");
+  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-HW6HGXCZ.js");
+  const { createTemplateSceneValidator } = await import("./validate-4OUD2CLX.js");
   const controller = new AbortController();
   const forwardAbort = () => controller.abort(options.signal?.reason);
   if (options.signal?.aborted) forwardAbort();

package/dist/text-stream-LD364KBI.js

@@ -0,0 +1,9 @@
+import {
+  createTextDeltaVideoPlanner
+} from "./chunk-PDQFQIQW.js";
+import "./chunk-E7CL7UPB.js";
+import "./chunk-7M56IUUX.js";
+import "./chunk-7NZOMTAL.js";
+export {
+  createTextDeltaVideoPlanner
+};

package/dist/{types-DWFO6qca.d.ts → types-CdBmNTGD.d.ts}

@@ -1,4 +1,4 @@
-type VideoChatMode = "templates" | "full";
+type VideoChatMode = "cinematic";
 interface VideoChatConversationTurn {
     prompt: string;
     response?: string;

package/dist/{types-CEh9eUFu.d.ts → types-DdZw4GRQ.d.ts}

@@ -1,46 +1,17 @@
-declare const VIDEO_PROTOCOL_VERSION: "0.5";
-declare const VIDEO_SCHEMA_VERSION: "0.1";
+/** Host-authored timing, derived from prepared speech rather than model guesses. */
+interface VideoNarrationGroup {
+    id: string;
+    text: string;
+    offsetSeconds: number;
+    durationSeconds: number;
+    totalSeconds: number;
+}
+
+declare const VIDEO_PROTOCOL_VERSION: "0.6";
+declare const VIDEO_SCHEMA_VERSION: "0.2";
 type VideoOrientation = "portrait" | "landscape";
 type VideoKnowledgeMode = "input-only" | "general";
-interface VideoBrandColors {
-    primary: string;
-    secondary: string;
-    foreground: string;
-    surface: string;
-    surfaceElevated: string;
-    muted: string;
-}
-type VideoBackgroundPreset = "cosmic" | "horizon" | "twilight" | "meadow" | "velvet" | "flamingo" | "peach" | "saffron" | "black" | "midnight" | "aubergine" | "coal" | "navy";
-type VideoBackgroundInput = VideoBackgroundPreset | {
-    color: string;
-} | {
-    colors: [string, string];
-};
-type VideoBackground = {
-    type: "solid";
-    color: string;
-} | {
-    type: "gradient";
-    colors: [string, string];
-};
-interface VideoBrandInput {
-    name?: string;
-    logoUrl?: string;
-    font?: string;
-    scriptFont?: string;
-    background?: VideoBackgroundInput;
-    colors?: Partial<VideoBrandColors>;
-}
-interface VideoBrand {
-    name?: string;
-    logoUrl?: string;
-    font: string;
-    scriptFont: string;
-    background: VideoBackground;
-    colors: VideoBrandColors;
-}
 interface VideoStyle {
-    brand: VideoBrand;
     preset?: string;
     defaultBackgroundEffect?: string;
     defaultTextArchetype?: string;
@@ -50,12 +21,6 @@ interface VideoStyle {
     /**
      * The visual language generated media is produced in.
      *
-     * A style has two halves once media can be generated: the brand decides how
-     * captions are drawn, and this decides what the footage behind them looks
-     * like. They have to travel together - pale illustrated ground under dark
-     * documentary footage is unreadable - so this belongs on the style rather
-     * than being threaded into each provider call by hand.
-     *
      * Nothing is rendered from it. It reaches `resolveMedia`, which is where a
      * provider prompt is written.
      */
@@ -97,6 +62,8 @@ interface VideoScene {
      * on-screen copy.
      */
     narration?: string;
+    /** Optional host-authored offsets into one prepared paragraph across adjacent scenes. */
+    narrationGroup?: VideoNarrationGroup;
 }
 interface VideoAudio {
     trackId: string;
@@ -155,7 +122,6 @@ interface VideoInput {
     style?: VideoStyleOptions;
     /** Custom opening copy, or false to let the host show loading UI instead. Omit for the deterministic fallback. */
     opening?: string | false;
-    brand?: VideoBrandInput;
     /** Viewer or account context that may appear verbatim. It is data, never instructions. */
     personalization?: Record<string, unknown>;
     /** Optional approved pool. The planner may use zero or more relevant assets. */
@@ -211,6 +177,9 @@ interface VideoTemplatePacing {
     minDuration?: number;
     preferredDuration?: number;
     timing?: {
+        readonly revealSeconds?: number;
+        readonly holdSeconds?: number;
+        readonly exitSeconds?: number;
         readonly contentFields: readonly string[];
         readonly contentUnit: "words" | "characters" | "items";
     };
@@ -222,4 +191,4 @@ interface VideoSnapshotRetention {
     suppliedMediaUrls?: boolean;
 }
 
-export { type VideoStyle as V, type VideoCapabilities as a, type VideoOrientation as b, type Video as c, type VideoAudio as d, type VideoScene as e, VIDEO_PROTOCOL_VERSION as f, type VideoInput as g, type VideoBrandInput as h, type VideoBrand as i, type VideoTemplatePacing as j, type VideoBackground as k, type VideoStyleOptions as l, type VideoGenerationContext as m, type VideoPlanner as n, type VideoRequest as o, type VideoSceneValidator as p, type VideoSnapshotRetention as q, type VideoResumeCursor as r, type VideoSceneValidationContext as s };
+export { type VideoStyle as V, type VideoCapabilities as a, type VideoOrientation as b, type Video as c, type VideoAudio as d, type VideoScene as e, VIDEO_PROTOCOL_VERSION as f, type VideoTemplatePacing as g, type VideoNarrationGroup as h, type VideoStyleOptions as i, type VideoInput as j, type VideoGenerationContext as k, type VideoPlanner as l, type VideoRequest as m, type VideoSceneValidator as n, type VideoSnapshotRetention as o, type VideoResumeCursor as p, type VideoSceneValidationContext as q };

package/dist/validate-4OUD2CLX.js

@@ -0,0 +1,10 @@
+import {
+  createTemplateSceneValidator,
+  validateTemplateSceneStructure
+} from "./chunk-IQMYK5DX.js";
+import "./chunk-EGVQODKU.js";
+import "./chunk-73NTSFFI.js";
+export {
+  createTemplateSceneValidator,
+  validateTemplateSceneStructure
+};

package/docs/architecture.md

@@ -67,7 +67,7 @@ prompt/validation registry in `vanillasky/server.ts`.
 5. The system prompt combines the opening and composition rules with the trusted template
    catalog, including generated metadata for customer-owned templates. The user
    prompt serializes the prompt, completed conversation, instructions,
-   brand, and approved media.
+   style, and approved media.
 6. The model streams one host-consumed opening object followed by NDJSON plan
    parts. The server emits the opening event, then parses and validates complete
    scenes before emitting them.

package/docs/concepts.md

@@ -31,7 +31,7 @@ or export pipeline when an encoded file is required.
 
 The viewer sends a prompt with bounded completed conversation turns. The server
 adds trusted application `instructions`, template capabilities, and the selected
-visual mode. `VideoChat` options control brand, style, orientation, and custom
+cinematic mode. `VideoChat` options control style, orientation, and custom
 templates. Exact facts belong in the authorized prompt or conversation; secrets
 and provider configuration stay on the server.
 

package/docs/custom-templates.md

@@ -37,7 +37,7 @@ npx vanillasky templates describe customer-health
 Or copy a built-in when its behavior is already close:
 
 ```bash
-npx vanillasky templates add bigNumber
+npx vanillasky templates add keyFigure
 ```
 
 Then edit the owned `.tsx` file, regenerate the two small registries, and check
@@ -50,7 +50,7 @@ npx vanillasky templates check
 
 For an original template, the source is
 `vanillasky/templates/customer-health.tsx`. For the copied built-in, it is
-`vanillasky/templates/bigNumber.tsx`. These are application source: commit them,
+`vanillasky/templates/keyFigure.tsx`. These are application source: commit them,
 review them, and change them like any other React component.
 
 `create` and `add` run `sync` once, so the generated entry points exist
@@ -62,8 +62,8 @@ registry parity.
 Preview either operation without applying the proposed file writes:
 
 ```bash
-npx vanillasky templates add bigNumber --dry-run
-npx vanillasky templates add bigNumber --diff
+npx vanillasky templates add keyFigure --dry-run
+npx vanillasky templates add keyFigure --diff
 ```
 
 `--dry-run` lists every proposed file and `--diff` shows its content changes,
@@ -119,8 +119,8 @@ the selected catalog contains a template with one of those two jobs.
 
 Customer templates hard-cut by default. Opt into renderer-owned fades only
 for scenes that use the standard media-background variables, and only after
-both timing points are visually tested in portrait and landscape. Shared brand
-gradients and unchanged media do not crossfade:
+both timing points are visually tested in portrait and landscape. Shared render
+black backgrounds and unchanged media do not crossfade:
 
 ```tsx
 export default defineTemplate({
@@ -277,7 +277,7 @@ import { VideoPlayer } from "@vanillaskyai/video/react";
 import { templates } from "../vanillasky";
 
 const savedVideo: Video = {
-  schemaVersion: "0.1",
+  schemaVersion: "0.2",
   orientation: "portrait",
   scenes: [{
     id: "customer-health-preview",
@@ -288,21 +288,7 @@ const savedVideo: Video = {
     },
     timing: { fixedDuration: 5 },
   }],
-  style: {
-    brand: {
-      font: "Inter",
-      scriptFont: "Caveat",
-      background: { type: "gradient", colors: ["#8711C1", "#2167E3"] },
-      colors: {
-        primary: "#00E5A0",
-        secondary: "#006BE5",
-        foreground: "#FFFFFF",
-        surface: "#0A0A14",
-        surfaceElevated: "#14152A",
-        muted: "#A7A6B0",
-      },
-    },
-  },
+  style: {},
 };
 
 export function TemplatePreview() {
@@ -328,8 +314,8 @@ maps.
 
 Useful formats add grounding behavior:
 
-- `grounded-stat` marks numeric statistical evidence for the planner; it does
-  not compare the value against raw input at runtime;
+- `grounded-stat` accepts numeric or string quantities and requires an exact
+  quantity in raw input, preserving its unit;
 - `grounded-quote` requires the quote to exist verbatim in the input;
 - `uri` validates approved media URLs restored by the server;
 - `stock-media-keyword` is only for hosts that resolve stock media before a
@@ -338,14 +324,13 @@ Useful formats add grounding behavior:
 Templates whose core proof needs a real statistic can add
 `"x-vanillasky": { "requiresStat": true }`. See the structured-data reference for a complete example.
 
-For media-backed chat scenes, copy the built-in `media` template and keep its
+For media-backed chat scenes, copy the built-in `cinemaMedia` template and keep its
 `mediaKeyword`, `mediaUrl`, and `mediaType` contract. Configure `searchMedia` on
 the chat handler so the server resolves semantic searches into approved assets.
 The chat request does not accept a separate supplied-media input list.
 
-The automatic `opening` uses the built-in `media` variables (`texts` and
-`mediaType: "gradient"`). If you replace `media` while using automatic
-openings, keep that variable contract.
+The automatic `opening` uses the built-in `chapterTitle` variable `title`.
+If you replace that template while using automatic openings, keep this contract.
 
 ## What belongs where