@vanillaskyai/video 0.9.0 → 0.10.0

package/dist/react.js

@@ -30,7 +30,7 @@ import {
 } from "./chunk-7NZOMTAL.js";
 import {
   getBuiltinTemplateMetadata
-} from "./chunk-LH4BPALA.js";
+} from "./chunk-IIN5M5HW.js";
 import "./chunk-3O7OMMMF.js";
 import {
   assertTemplateTransitionMetadata
@@ -40,8 +40,8 @@ import {
   VideoFrame,
   getDimensions,
   sceneReadinessKey
-} from "./chunk-3ZTEFJIR.js";
-import "./chunk-UDIODEDK.js";
+} from "./chunk-ELVOT2FQ.js";
+import "./chunk-224QNWRA.js";
 import "./chunk-TVIU23OM.js";
 import {
   getVideoDuration,
@@ -93,14 +93,13 @@ import { createElement } from "react";
 
 // src/visual-system/catalog/builtin-loaders.generated.ts
 var GENERATED_BUILTIN_TEMPLATE_LOADERS = {
-  "cinemaMedia": () => import("./cinema-media-YQHSIFDA.js").then((module) => ({ default: module.MediaSceneTemplate })),
+  "cinemaMedia": () => import("./cinema-media-C7OUPNSH.js").then((module) => ({ default: module.MediaSceneTemplate })),
   "chapterTitle": () => import("./chapter-title-YRLIQY3V.js").then((module) => ({ default: module.TitleSceneTemplate })),
-  "focusCards": () => import("./focus-cards-TJ72BT7U.js").then((module) => ({ default: module.CardsSceneTemplate })),
-  "editorialTimeline": () => import("./editorial-timeline-OZX7OS6G.js").then((module) => ({ default: module.TimelineSceneTemplate })),
-  "mobileMessage": () => import("./mobile-message-UZUPIKHD.js").then((module) => ({ default: module.NotificationSceneTemplate })),
-  "comparison": () => import("./comparison-RZMMHZR2.js").then((module) => ({ default: module.ComparisonSceneTemplate })),
-  "quote": () => import("./quote-EW5HQA6H.js").then((module) => ({ default: module.QuoteSceneTemplate })),
-  "keyFigure": () => import("./key-figure-GYENXKH3.js").then((module) => ({ default: module.KeyFigureSceneTemplate }))
+  "editorialTimeline": () => import("./editorial-timeline-EMV5335S.js").then((module) => ({ default: module.TimelineSceneTemplate })),
+  "mobileMessage": () => import("./mobile-message-OF7T62B7.js").then((module) => ({ default: module.NotificationSceneTemplate })),
+  "comparison": () => import("./comparison-GNZOR7MF.js").then((module) => ({ default: module.ComparisonSceneTemplate })),
+  "quote": () => import("./quote-T6WYLN7A.js").then((module) => ({ default: module.QuoteSceneTemplate })),
+  "keyFigure": () => import("./key-figure-P37VK425.js").then((module) => ({ default: module.KeyFigureSceneTemplate }))
 };
 
 // src/visual-system/catalog/builtin-player.generated.ts
@@ -121,17 +120,6 @@ var GENERATED_BUILTIN_PLAYER_TEMPLATES = [
     },
     "usesGlobalTransition": false
   },
-  {
-    "id": "focusCards",
-    "defaults": {
-      "items": [
-        "Listen closely",
-        "Notice the pattern",
-        "Make room for change"
-      ]
-    },
-    "usesGlobalTransition": false
-  },
   {
     "id": "editorialTimeline",
     "defaults": {
@@ -145,7 +133,10 @@ var GENERATED_BUILTIN_PLAYER_TEMPLATES = [
         {
           "label": "Act"
         }
-      ]
+      ],
+      "mediaUrl": "",
+      "mediaType": "video",
+      "mediaPoster": ""
     },
     "usesGlobalTransition": false
   },
@@ -164,22 +155,33 @@ var GENERATED_BUILTIN_PLAYER_TEMPLATES = [
     "id": "comparison",
     "defaults": {
       "leftText": "More distractions",
-      "rightText": "More room to think"
+      "rightText": "More room to think",
+      "mediaUrl": "",
+      "mediaType": "video",
+      "mediaPoster": ""
     },
     "usesGlobalTransition": false
   },
   {
     "id": "quote",
-    "defaults": {},
+    "defaults": {
+      "mediaUrl": "",
+      "mediaType": "video",
+      "mediaPoster": ""
+    },
     "usesGlobalTransition": false
   },
   {
     "id": "keyFigure",
-    "defaults": {},
+    "defaults": {
+      "mediaUrl": "",
+      "mediaType": "video",
+      "mediaPoster": ""
+    },
     "usesGlobalTransition": false
   }
 ];
-var GENERATED_BUILTIN_VIDEO_BACKDROP_IDS = ["cinemaMedia", "mobileMessage"];
+var GENERATED_BUILTIN_VIDEO_BACKDROP_IDS = ["cinemaMedia", "editorialTimeline", "mobileMessage", "comparison", "quote", "keyFigure"];
 
 // src/visual-system/catalog/builtin-player.ts
 function createPreloadableBuiltinTemplate(loader, mediaBackdrop) {
@@ -235,7 +237,7 @@ function preloadBuiltinTemplate(id) {
 
 // src/player/warm-scene-media.ts
 function warmSceneMedia(variables) {
-  void import("./preload-media-CFTZIMZL.js").then((module) => module.preloadSceneMedia(variables)).catch(() => {
+  void import("./preload-media-LJXWKTWG.js").then((module) => module.preloadSceneMedia(variables)).catch(() => {
   });
 }
 

package/dist/server.js

@@ -12,7 +12,7 @@ import {
   BUILTIN_SERVER_TEMPLATE_KIT,
   createServerTemplateRegistry,
   overlayServerTemplateRegistry
-} from "./chunk-MQILEEXC.js";
+} from "./chunk-IR44XKBI.js";
 import {
   createTemplateSceneValidator,
   validateTemplateSceneStructure
@@ -47,14 +47,77 @@ import {
 import {
   createTemplateSystemPrompt,
   getStandardMediaResolverContract
-} from "./chunk-OR52UMSF.js";
+} from "./chunk-2HFO22K2.js";
 import "./chunk-PAJ44TFW.js";
 import "./chunk-EGVQODKU.js";
-import "./chunk-LH4BPALA.js";
+import "./chunk-IIN5M5HW.js";
 import "./chunk-3O7OMMMF.js";
 import "./chunk-2E6T633S.js";
 import "./chunk-73NTSFFI.js";
 
+// src/server/opening-continuity.ts
+function continueAfterOpening(narration, earlier) {
+  const words = (value) => Array.from(value.matchAll(/[\p{L}\p{N}]+(?:['’][\p{L}\p{N}]+)*/gu));
+  let remaining = narration;
+  for (const previous of [...earlier].reverse()) {
+    const known = words(previous), current = words(remaining);
+    if (known.length < 5 || known.length > current.length) continue;
+    if (!known.every((word, index) => word[0].toLowerCase() === current[index][0].toLowerCase())) continue;
+    if (known.length === current.length) return "";
+    const last = current[known.length - 1];
+    const suffix = remaining.slice(last.index + last[0].length);
+    const boundary = suffix.match(/^[”"'’\])]*[.!?…]+[\s”"'’\])]*/u);
+    if (boundary) remaining = suffix.slice(boundary[0].length).trim();
+  }
+  return remaining;
+}
+function createOpeningContinuation(initialOpening) {
+  const earlier = initialOpening ? [initialOpening] : [];
+  let bodyStarted = false;
+  const copy = (authored, narration) => {
+    if (continueAfterOpening(authored, earlier) !== "") return authored;
+    const next = continueAfterOpening(narration, earlier).trim();
+    return next && [...next].length <= 65 && /[.!?…][”"’')\]]*$/u.test(next) ? next : authored;
+  };
+  return {
+    copy,
+    remember(line) {
+      if (line.trim()) earlier.push(line);
+    },
+    narration(line) {
+      return continueAfterOpening(line, earlier);
+    },
+    line(rawLine) {
+      if (bodyStarted || earlier.length === 0) return rawLine;
+      let part;
+      try {
+        part = JSON.parse(rawLine);
+      } catch {
+        return rawLine;
+      }
+      if (!part || part.type !== "scene.add" || part.placement === "closer") return rawLine;
+      const scene = part.scene;
+      if (!scene) return rawLine;
+      if (typeof scene.narration !== "string") {
+        bodyStarted = true;
+        return rawLine;
+      }
+      const narration = continueAfterOpening(scene.narration, earlier);
+      if (!narration && scene.templateId === "cinemaMedia") return null;
+      const variables = scene.variables;
+      if (!narration && scene.templateId === "chapterTitle" && typeof variables?.title === "string" && !continueAfterOpening(variables.title, earlier)) return null;
+      bodyStarted = true;
+      if (!narration) return rawLine;
+      const field = scene.templateId === "cinemaMedia" ? "fallbackText" : scene.templateId === "chapterTitle" ? "title" : void 0;
+      const authored = field && variables?.[field];
+      const updated = typeof authored === "string" ? copy(authored, narration) : void 0;
+      const copyChanged = typeof authored === "string" && updated !== authored;
+      if (narration === scene.narration && !copyChanged) return rawLine;
+      return JSON.stringify({ ...part, scene: { ...scene, narration, ...copyChanged ? { variables: { ...variables, [field]: updated } } : {} } });
+    }
+  };
+}
+
 // src/server/request-validation.ts
 var MAX_GENERATED_LOOK_LENGTH = 1e3;
 function boundedString(value, path) {
@@ -865,11 +928,12 @@ function createVideoHandler(options) {
 function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlreadyProvided = false, maxGeneratedVideos = 5) {
   return [
     "Respond as a coherent short film: establish, develop, then land a useful or emotional payoff. Match the user's requested form.",
-    generatedVideoAvailable ? 'First emit one host-consumed opening JSON object: {"type":"video-chat.opening","spokenHook":"6-9 words","mediaKeyword":"literal subject","firstShot":{"text":"short grounded fallback","narration":"one natural spoken sentence","mediaKeyword":"2-8 concrete words","shotDirection":"optional framing and action"}}. Include firstShot only when a distinctive illustrative shot serves the story; omit it for an abstract explanation best opened with graphics. When present, the host inserts it once and begins generation immediately; do not emit it again.' : openingAlreadyProvided ? "Start directly with scene.add; the opening has already been supplied." : 'First emit {"type":"video-chat.opening","spokenHook":"6-9 words","mediaKeyword":"literal subject"}. This is host-consumed, not a scene.',
+    generatedVideoAvailable ? 'First emit one host-consumed opening JSON object: {"type":"video-chat.opening","spokenHook":"6-9 words","mediaKeyword":"literal subject","firstShot":{"text":"short grounded fallback","narration":"one natural sentence advancing the hook","mediaKeyword":"2-8 concrete words","shotDirection":"optional framing and action"}}. Include firstShot only when a distinctive illustrative shot serves the story; omit it for an abstract explanation best opened with graphics. When present, the host inserts it once and begins generation immediately; do not emit it again.' : openingAlreadyProvided ? "Start directly with scene.add; the opening has already been supplied." : 'First emit {"type":"video-chat.opening","spokenHook":"6-9 words","mediaKeyword":"literal subject"}. This is host-consumed, not a scene.',
     openingAlreadyProvided ? "Preserve the supplied opening exactly; continue it without repeating its words or claim." : void 0,
+    "The spokenHook is already heard before the first scene. Start firstShot.narration with the next fact, cause, action or consequence; never restate the hook. The first ordinary scene must then advance beyond firstShot rather than repeat its narration or opening claim. If firstShot is omitted, that first scene must advance the hook directly. firstShot.text, fallbackText and chapter titles must also express that new beat, not reuse the hook or prior shot copy; write a short complete grounded thought within the schema budget, never a clipped statistic or qualifying clause.",
     "Continue with only as many scenes as the story and duration need. Never pad to a fixed count. Every emitted scene carries narration beside variables and timing; no additional narration request should be needed.",
-    "For concrete topics, coherent footage carries the story and graphics clarify particular points. Maintain consistent setting, lighting and subject while varying shot scale. Avoid unrelated cinematic montages.",
-    "Use the installed catalog: parallel points, ordered events, comparison, exact quote, one key figure, chapter or a message only when its narrative job fits. Do not force every template into a video. Avoid repeating the same graphic or more than two consecutive graphic scenes unless necessary.",
+    "Make most of the film relevant footage: use full-bleed media for action, subjects and atmosphere, with graphics only to clarify a specific relationship or piece of evidence. Maintain consistent setting, lighting and subject while varying shot scale. Avoid unrelated cinematic montages.",
+    "Use the installed catalog: ordered events, comparison, exact quote, one key figure, chapter or a message only when its narrative job fits. At most one graphic-led explanatory beat per 30 seconds, plus a brief chapter opening when needed. Do not place graphic beats consecutively unless no honest relevant media is available. Give media-capable graphics a relevant background when it supports the meaning; keep black when no matching media exists. Do not force every template into a video or use lists of bullets.",
     `At most ${generatedVideoAvailable ? maxGeneratedVideos : 0} generated-video attempts are available. Media scenes choose mediaSource=generate for distinctive illustrative shots or mediaSource=stock for generic verified imagery. A stock miss is not permission to broaden essential details. Do not spend generation on every scene.`,
     "Each mediaKeyword is a literal filmable subject/action, 2\u20138 words, maximum 80 characters. Use optional shotDirection for action, camera framing and continuity; it does not change the literal stock subject. Supply a short grounded fallbackText when the schema declares it. Do not put visible headline text over full-bleed footage.",
     "No invented quotations, attribution, statistics, personal evidence or URLs. Creative stories may be invented when requested; do not present generated illustration as historical evidence.",
@@ -1111,6 +1175,19 @@ function interceptOpeningPlan(source, options) {
   const textStream = (async function* () {
     let buffer = "";
     let decided = !options.expectOpening;
+    const continuation = createOpeningContinuation(options.openingLine);
+    const acceptOpening = (opening) => {
+      if (!options.openingProvided) {
+        options.publish(opening.line ? opening : void 0);
+        continuation.remember(opening.line);
+      }
+      if (!options.generatedVideoAvailable || !opening.firstShot) return void 0;
+      const narration = continuation.narration(opening.firstShot.narration);
+      if (!narration) return void 0;
+      const text = continuation.copy(opening.firstShot.text, narration);
+      continuation.remember(narration);
+      return JSON.stringify(reservedFirstScene(options.requestId, { ...opening.firstShot, text, narration }));
+    };
     try {
       for await (const delta of upstream) {
         if (typeof delta !== "string") throw new Error("The LLM adapter returned a non-text delta");
@@ -1124,17 +1201,16 @@ function interceptOpeningPlan(source, options) {
             const opening = readOpeningPlanLine(line);
             decided = true;
             if (opening) {
-              if (!options.openingProvided) options.publish(opening.line ? opening : void 0);
-              if (options.generatedVideoAvailable && opening.firstShot) {
-                yield `${JSON.stringify(reservedFirstScene(options.requestId, opening.firstShot))}
+              const firstScene = acceptOpening(opening);
+              if (firstScene) yield `${firstScene}
 `;
-              }
               newline = buffer.indexOf("\n");
               continue;
             }
             options.publish(void 0);
           }
-          yield `${rawLine}
+          const continued = continuation.line(rawLine);
+          if (continued != null) yield `${continued}
 `;
           newline = buffer.indexOf("\n");
         }
@@ -1145,17 +1221,17 @@ function interceptOpeningPlan(source, options) {
           const opening = readOpeningPlanLine(line);
           decided = true;
           if (opening) {
-            if (!options.openingProvided) options.publish(opening.line ? opening : void 0);
-            if (options.generatedVideoAvailable && opening.firstShot) {
-              yield `${JSON.stringify(reservedFirstScene(options.requestId, opening.firstShot))}
+            const firstScene = acceptOpening(opening);
+            if (firstScene) yield `${firstScene}
 `;
-            }
           } else {
             options.publish(void 0);
-            yield buffer;
+            const continued = continuation.line(buffer);
+            if (continued != null) yield continued;
           }
         } else {
-          yield buffer;
+          const continued = continuation.line(buffer);
+          if (continued != null) yield continued;
         }
       }
     } finally {
@@ -1332,7 +1408,7 @@ function createVideoChatHandler(options) {
   const heroQuery = welcomeOptions?.heroQuery;
   let welcomeResponse;
   let requestSequence = 0;
-  const responseHandler = (requestId, openingProvided, openingChannel) => {
+  const responseHandler = (requestId, openingProvided, openingChannel, openingLine) => {
     const generatedVideoAvailable = generateVideo != null && maxGeneratedVideos > 0;
     let lifecycle;
     let generatedAttempts = 0;
@@ -1400,6 +1476,7 @@ function createVideoChatHandler(options) {
           return interceptOpeningPlan(videoOptions.streamText(context), {
             expectOpening: generatedVideoAvailable || !openingProvided,
             openingProvided,
+            openingLine,
             requestId,
             generatedVideoAvailable,
             publish: openingChannel.publish
@@ -1569,7 +1646,8 @@ function createVideoChatHandler(options) {
       const response = await responseHandler(
         requestId,
         input.opening != null,
-        openingChannel
+        openingChannel,
+        input.opening
       )(videoRequest);
       return streamVideoChatOpening(response, openingChannel.ready);
     }

package/dist/template-catalog.d.ts

@@ -66,25 +66,6 @@ declare const BUILTIN_TEMPLATE_SCHEMAS: {
         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: {
@@ -113,9 +94,48 @@ declare const BUILTIN_TEMPLATE_SCHEMAS: {
                 }];
                 readonly description: "3–5 ordered events or actions, each with one short label; no dates.";
             };
+            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 required: readonly ["events"];
         readonly additionalProperties: false;
+        readonly "x-vanillasky": {
+            readonly allowsStockMedia: true;
+        };
     };
     readonly mobileMessage: {
         readonly type: "object";
@@ -202,9 +222,48 @@ declare const BUILTIN_TEMPLATE_SCHEMAS: {
                 readonly default: "More room to think";
                 readonly description: "Second real alternative, parallel to the first.";
             };
+            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 required: readonly ["leftText", "rightText"];
         readonly additionalProperties: false;
+        readonly "x-vanillasky": {
+            readonly allowsStockMedia: true;
+        };
     };
     readonly quote: {
         readonly type: "object";
@@ -224,9 +283,48 @@ declare const BUILTIN_TEMPLATE_SCHEMAS: {
                 readonly examples: readonly ["Illustrative example"];
                 readonly description: "Grounded attribution belonging to these exact quoted words.";
             };
+            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 required: readonly ["quote", "attribution"];
         readonly additionalProperties: false;
+        readonly "x-vanillasky": {
+            readonly allowsStockMedia: true;
+        };
     };
     readonly keyFigure: {
         readonly type: "object";
@@ -246,11 +344,48 @@ declare const BUILTIN_TEMPLATE_SCHEMAS: {
                 readonly examples: readonly ["Illustrative example"];
                 readonly description: "Exactly one short label identifying the quantity and its context.";
             };
+            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 required: readonly ["value", "label"];
         readonly additionalProperties: false;
         readonly "x-vanillasky": {
             readonly requiresStat: true;
+            readonly allowsStockMedia: true;
         };
     };
 };

package/dist/template-catalog.js

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

package/dist/test.js

@@ -235,7 +235,7 @@ async function* simulateVideoStream(parts, options = {}) {
   }
   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 { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-W4PLJUZ5.js");
   const { createTemplateSceneValidator } = await import("./validate-4OUD2CLX.js");
   const controller = new AbortController();
   const forwardAbort = () => controller.abort(options.signal?.reason);

package/docs/customization.md

@@ -52,7 +52,7 @@ explain with their own composition and motion. There is no brand-kit option.
 The host can provide a shared `generatedLook` description for media preparation.
 Custom source-owned templates can define their own visual language in code.
 Do not rely on old global brand, text-effect, or gradient controls to restyle
-the eight cinematic templates.
+the seven cinematic templates.
 
 ## Opening
 

package/docs/maintainers/cinematic-migration.md

@@ -32,3 +32,7 @@ Evidence: persistence tests preserve the untouched old release fixture and asser
 The cinematic templates use `-apple-system, BlinkMacSystemFont, "Helvetica Neue", Roboto, Arial, sans-serif` at regular and medium weights. Apple devices keep native system typography. The existing `@vanillaskyai/video/video-chat.css` entry registers packaged Roboto v51 WOFF2 subsets as the fallback for environments without those fonts. Standalone player and source-owned template integrations should also import that stylesheet. No font is fetched from Google at runtime; browsers fetch local packaged subsets only when Roboto is selected for the rendered glyphs. The font assets include the SIL Open Font License and a source/hash manifest.
 
 Live native fonts and a Linux renderer’s Roboto have slightly different metrics. For repeatable exports, keep the browser, installed fonts, viewport and package version fixed, and await `document.fonts.ready` after mounting the final scene before capturing frames. This is a host export responsibility; the SDK does not add a separate export API or force downloaded fonts onto Apple devices.
+
+## Media-led follow-up
+
+The owner requested removing `focusCards`. Regenerate persisted videos using that ID; migrate parallel explanations to narration over footage rather than another bullet layout. The remaining seven templates retain their IDs. Comparison, quote, key figure and timeline accept optional standard media variables and remain readable on black when assets are absent. No provider callback signatures or host limits change.

package/docs/media-and-audio.md

@@ -8,14 +8,14 @@ all credentials out of React and the browser bundle.
 
 ## One cinematic mode
 
-The director combines relevant footage and eight editorial templates. Graphics
+The director combines relevant footage and seven editorial templates. Graphics
 use black and white; footage carries atmosphere and concrete action. Each media
 scene declares `mediaSource: "stock"` or `"generate"`. Provider availability and
 host budgets constrain those choices. There is no all-stock or all-AI switch.
 
-The canonical templates are `cinemaMedia`, `chapterTitle`, `focusCards`,
+The canonical templates are `cinemaMedia`, `chapterTitle`,
 `editorialTimeline`, `mobileMessage`, `comparison`, `quote`, and `keyFigure`.
-Only `cinemaMedia` and `mobileMessage` accept media backgrounds. Full-bleed
+All except `chapterTitle` accept optional media backgrounds. Editorial overlays use soft text shadows and a dark contrast scrim over relevant media, and fall back to black. Use at most one explanatory overlay per typical thirty-second answer. Full-bleed
 footage has no headline; narration and subtitles carry the explanation.
 
 ## Reviewed stock

package/docs/provider-integration.md

@@ -180,7 +180,7 @@ is intentionally substantial. It is stable for the same SDK version, template
 kit, media policy, and base prompt. Record input-token usage, keep the selected
 kit no broader than the product needs, and enable provider-side prompt caching
 where the chosen provider/model supports it. VanillaSky does not assume one
-provider's cache controls in its provider-neutral adapter. The cinematic catalog contains eight templates; use provider-reported token
+provider's cache controls in its provider-neutral adapter. The cinematic catalog contains seven templates; use provider-reported token
 usage as the authoritative measurement rather than a character estimate.
 
 Provider finish reasons `error` and `tool-calls` are terminal failures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Open-source voice-and-video chat SDK for AI applications.",
   "keywords": [
     "video-chat",