@vanillaskyai/video 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.0
+
+### Breaking
+
+- Remove `focusCards` from the built-in catalog and generated source templates, as requested. Existing callers must replace it with narration over `cinemaMedia`, or an appropriate comparison/timeline when supported by their content. Persisted videos using that ID must be regenerated before playback with the new catalog.
+
+### Changed
+
+- Opening narration advances into the first shot and body. Exact repeated introductory sentences are removed without additional model calls or startup waits.
+- Prefer relevant footage over repeated graphic scenes; use no more than one explanatory overlay in a typical thirty-second answer. Comparison, key figure, quote and timeline can now use optional host-resolved media with a contrast scrim and soft text shadows. Black remains the fallback; chapter titles stay black.
+
+
 ## 0.9.0
 
 - Continue video playback with subtitles when native browser speech cannot start, without weakening generated-audio readiness or counting paused time toward the fallback.

package/dist/{builtin-server-HW6HGXCZ.js → builtin-server-W4PLJUZ5.js}

@@ -1,7 +1,7 @@
 import {
   BUILTIN_SERVER_TEMPLATE_KIT
-} from "./chunk-MQILEEXC.js";
-import "./chunk-LH4BPALA.js";
+} from "./chunk-IR44XKBI.js";
+import "./chunk-IIN5M5HW.js";
 import "./chunk-2E6T633S.js";
 export {
   BUILTIN_SERVER_TEMPLATE_KIT

package/dist/check-runtime.js

@@ -1,7 +1,7 @@
 import {
   VideoFrame
-} from "./chunk-3ZTEFJIR.js";
-import "./chunk-UDIODEDK.js";
+} from "./chunk-ELVOT2FQ.js";
+import "./chunk-224QNWRA.js";
 import "./chunk-TVIU23OM.js";
 import "./chunk-SPVTJH3F.js";
 import "./chunk-R3XAOMKP.js";

package/dist/{chunk-UDIODEDK.js → chunk-224QNWRA.js}

@@ -19,8 +19,12 @@ function resolveMediaType(mediaType, mediaUrl) {
   if (mediaType === "photo") return "photo";
   return mediaUrl && isVideoUrl(mediaUrl) ? "video" : "photo";
 }
+function hasSceneMedia(variables) {
+  return String(variables.mediaUrl || "").trim() !== "" && String(variables.mediaType || "auto") !== "gradient";
+}
 
 export {
   limitsConcurrentVideoDecoders,
-  resolveMediaType
+  resolveMediaType,
+  hasSceneMedia
 };

package/dist/{chunk-OR52UMSF.js → chunk-2HFO22K2.js}

@@ -118,7 +118,7 @@ ${options.basePrompt.trim()}` : void 0,
     "Variable notation is type[count]{characters}(options)! where count is list cardinality, characters is the inclusive character count for a string or each string-array item, and ! means required. Omitted ! means optional.",
     "Choose a template only when the permitted factual basis contains every fact it needs. Never invent peer values to complete a chart, comparison, stat set, timeline, or list.",
     ...PACING_PLANNER_RULES,
-    "Do not compress a list, sequence, metric set, or comparison into a general-purpose prose field when a specific catalog template can show that structure.",
+    "Let narration carry ordinary lists. Use a structured overlay only when a comparison, sequence, exact quote or key figure adds understanding beyond the voice. Prefer relevant full-bleed footage for the rest of the explanation.",
     "If the catalog includes a suitable ask template and the input supplies a grounded CTA or URL, keep that concise action closer as its own final scene instead of folding it into preceding content.",
     "When a grounded CTA or URL is supplied and the catalog contains jobs:[ask], emit that final closer. A brand name may accompany the action but never qualifies as an ask by itself.",
     terminalPayoffs.length > 0 ? `When there is no grounded action, end with a concise supported payoff using a suitable template from ${terminalPayoffs.join(", ")}. Do not repeat the hook or invent a CTA.` : void 0,
@@ -127,6 +127,7 @@ ${options.basePrompt.trim()}` : void 0,
     mediaTemplates.length > 0 && options.mediaOnFirstScene !== true ? `The host owns immediate startup; reserve external media templates (${mediaTemplates.join(", ")}) for later beats when an asset-free opening is required.` : void 0,
     "For list and event variables emit actual JSON arrays. Follow each field's content budget; never use pipe-delimited strings or invent entries.",
     resolverMediaAvailable ? "Media-capable scenes may carry mediaKeyword: a literal 2\u20138 word shot description, at most 80 characters. Choose mediaSource=generate for distinctive illustrative shots and mediaSource=stock for common subjects a verified asset can depict. For generated footage, optional shotDirection gives action, framing and continuity separately from the stock query. Keep people, actions and essential details precise. Never broaden an exact identity or action into unrelated atmosphere. Supply a grounded fallbackText where declared. Only the host fills mediaUrl and mediaPoster; never invent them. If no media fits an abstract beat, choose an appropriate graphic template instead." : "Use media only when a supplied asset satisfies the scene. Never invent asset URLs. Otherwise choose a grounded graphic template.",
+    "When the catalog offers media, make relevant footage the default. For a typical 30-second answer use at most one structured explanatory overlay plus an optional brief chapter opening. Do not chain graphic-only beats when honest media is available. Reuse suitable supplied media behind overlays with optional media fields; retain black when no relevant asset exists. Never invent a stock match or spend beyond host generation limits.",
     "Catalog guidance describes composition; it is not a factual source and must never replace the permitted factual basis.",
     JSON.stringify(plannerCatalog(templates, resolverMediaAvailable)),
     // Last, because the catalogue is thousands of tokens of per-scene field

package/dist/{chunk-MXEYPK7M.js → chunk-4ZJLPHBV.js}

@@ -80,31 +80,6 @@ var BUILTIN_TEMPLATE_SCHEMAS = {
     ],
     "additionalProperties": false
   },
-  "focusCards": {
-    "type": "object",
-    "properties": {
-      "items": {
-        "type": "array",
-        "minItems": 2,
-        "maxItems": 4,
-        "items": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 55
-        },
-        "default": [
-          "Listen closely",
-          "Notice the pattern",
-          "Make room for change"
-        ],
-        "description": "2\u20134 parallel phrases, about 2\u20136 words each; no heading or numbering."
-      }
-    },
-    "required": [
-      "items"
-    ],
-    "additionalProperties": false
-  },
   "editorialTimeline": {
     "type": "object",
     "properties": {
@@ -138,12 +113,59 @@ var BUILTIN_TEMPLATE_SCHEMAS = {
           }
         ],
         "description": "3\u20135 ordered events or actions, each with one short label; no dates."
+      },
+      "mediaKeyword": {
+        "type": "string",
+        "format": "stock-media-keyword",
+        "minLength": 1,
+        "maxLength": 80,
+        "description": "2\u20138 word literal subject/action search intent, maximum 80 characters. Host resolves URLs.",
+        "examples": [
+          "Ocean waves breaking on a rocky shore"
+        ]
+      },
+      "mediaUrl": {
+        "type": "string",
+        "format": "uri",
+        "description": "Host-only approved photo or video URL.",
+        "default": ""
+      },
+      "mediaType": {
+        "type": "string",
+        "enum": [
+          "photo",
+          "video"
+        ],
+        "default": "video",
+        "description": "Host-resolved asset kind."
+      },
+      "mediaPoster": {
+        "type": "string",
+        "format": "uri",
+        "description": "Host-only approved poster URL for video decoding.",
+        "default": ""
+      },
+      "shotDirection": {
+        "type": "string",
+        "maxLength": 220,
+        "description": "Optional action, framing and continuity for generation. Preserve the subject; do not request rendered text."
+      },
+      "mediaSource": {
+        "type": "string",
+        "enum": [
+          "generate",
+          "stock"
+        ],
+        "description": "Generate distinctive illustrative shots; use approved stock for familiar observable subjects."
       }
     },
     "required": [
       "events"
     ],
-    "additionalProperties": false
+    "additionalProperties": false,
+    "x-vanillasky": {
+      "allowsStockMedia": true
+    }
   },
   "mobileMessage": {
     "type": "object",
@@ -239,13 +261,60 @@ var BUILTIN_TEMPLATE_SCHEMAS = {
         "maxLength": 60,
         "default": "More room to think",
         "description": "Second real alternative, parallel to the first."
+      },
+      "mediaKeyword": {
+        "type": "string",
+        "format": "stock-media-keyword",
+        "minLength": 1,
+        "maxLength": 80,
+        "description": "2\u20138 word literal subject/action search intent, maximum 80 characters. Host resolves URLs.",
+        "examples": [
+          "Ocean waves breaking on a rocky shore"
+        ]
+      },
+      "mediaUrl": {
+        "type": "string",
+        "format": "uri",
+        "description": "Host-only approved photo or video URL.",
+        "default": ""
+      },
+      "mediaType": {
+        "type": "string",
+        "enum": [
+          "photo",
+          "video"
+        ],
+        "default": "video",
+        "description": "Host-resolved asset kind."
+      },
+      "mediaPoster": {
+        "type": "string",
+        "format": "uri",
+        "description": "Host-only approved poster URL for video decoding.",
+        "default": ""
+      },
+      "shotDirection": {
+        "type": "string",
+        "maxLength": 220,
+        "description": "Optional action, framing and continuity for generation. Preserve the subject; do not request rendered text."
+      },
+      "mediaSource": {
+        "type": "string",
+        "enum": [
+          "generate",
+          "stock"
+        ],
+        "description": "Generate distinctive illustrative shots; use approved stock for familiar observable subjects."
       }
     },
     "required": [
       "leftText",
       "rightText"
     ],
-    "additionalProperties": false
+    "additionalProperties": false,
+    "x-vanillasky": {
+      "allowsStockMedia": true
+    }
   },
   "quote": {
     "type": "object",
@@ -268,13 +337,60 @@ var BUILTIN_TEMPLATE_SCHEMAS = {
           "Illustrative example"
         ],
         "description": "Grounded attribution belonging to these exact quoted words."
+      },
+      "mediaKeyword": {
+        "type": "string",
+        "format": "stock-media-keyword",
+        "minLength": 1,
+        "maxLength": 80,
+        "description": "2\u20138 word literal subject/action search intent, maximum 80 characters. Host resolves URLs.",
+        "examples": [
+          "Ocean waves breaking on a rocky shore"
+        ]
+      },
+      "mediaUrl": {
+        "type": "string",
+        "format": "uri",
+        "description": "Host-only approved photo or video URL.",
+        "default": ""
+      },
+      "mediaType": {
+        "type": "string",
+        "enum": [
+          "photo",
+          "video"
+        ],
+        "default": "video",
+        "description": "Host-resolved asset kind."
+      },
+      "mediaPoster": {
+        "type": "string",
+        "format": "uri",
+        "description": "Host-only approved poster URL for video decoding.",
+        "default": ""
+      },
+      "shotDirection": {
+        "type": "string",
+        "maxLength": 220,
+        "description": "Optional action, framing and continuity for generation. Preserve the subject; do not request rendered text."
+      },
+      "mediaSource": {
+        "type": "string",
+        "enum": [
+          "generate",
+          "stock"
+        ],
+        "description": "Generate distinctive illustrative shots; use approved stock for familiar observable subjects."
       }
     },
     "required": [
       "quote",
       "attribution"
     ],
-    "additionalProperties": false
+    "additionalProperties": false,
+    "x-vanillasky": {
+      "allowsStockMedia": true
+    }
   },
   "keyFigure": {
     "type": "object",
@@ -297,6 +413,50 @@ var BUILTIN_TEMPLATE_SCHEMAS = {
           "Illustrative example"
         ],
         "description": "Exactly one short label identifying the quantity and its context."
+      },
+      "mediaKeyword": {
+        "type": "string",
+        "format": "stock-media-keyword",
+        "minLength": 1,
+        "maxLength": 80,
+        "description": "2\u20138 word literal subject/action search intent, maximum 80 characters. Host resolves URLs.",
+        "examples": [
+          "Ocean waves breaking on a rocky shore"
+        ]
+      },
+      "mediaUrl": {
+        "type": "string",
+        "format": "uri",
+        "description": "Host-only approved photo or video URL.",
+        "default": ""
+      },
+      "mediaType": {
+        "type": "string",
+        "enum": [
+          "photo",
+          "video"
+        ],
+        "default": "video",
+        "description": "Host-resolved asset kind."
+      },
+      "mediaPoster": {
+        "type": "string",
+        "format": "uri",
+        "description": "Host-only approved poster URL for video decoding.",
+        "default": ""
+      },
+      "shotDirection": {
+        "type": "string",
+        "maxLength": 220,
+        "description": "Optional action, framing and continuity for generation. Preserve the subject; do not request rendered text."
+      },
+      "mediaSource": {
+        "type": "string",
+        "enum": [
+          "generate",
+          "stock"
+        ],
+        "description": "Generate distinctive illustrative shots; use approved stock for familiar observable subjects."
       }
     },
     "required": [
@@ -305,7 +465,8 @@ var BUILTIN_TEMPLATE_SCHEMAS = {
     ],
     "additionalProperties": false,
     "x-vanillasky": {
-      "requiresStat": true
+      "requiresStat": true,
+      "allowsStockMedia": true
     }
   }
 };
@@ -369,38 +530,9 @@ var BUILTIN_TEMPLATE_MANIFEST = [
     },
     schema: BUILTIN_TEMPLATE_SCHEMAS.chapterTitle
   },
-  {
-    "label": "Focus cards",
-    "description": "Two to four short phrases fade in sequentially on black; no boxes or heading.",
-    "usesGlobalTextEffect": false,
-    "usesGlobalTransition": false,
-    "usesGlobalBackgroundEffect": false,
-    "textCanvas": "tight",
-    "id": "focusCards",
-    "family": "Explainers",
-    "jobs": [
-      "setup",
-      "proof"
-    ],
-    "register": "card-led",
-    "useWhen": "Two to four short parallel points support an explanation. ",
-    "avoidWhen": "The points require an order, long paragraphs, numerical data or additional images to make sense.",
-    "minDuration": 4,
-    "preferredDuration": 5,
-    "timing": {
-      "contentFields": [
-        "items"
-      ],
-      "contentUnit": "items",
-      "revealSeconds": 2.4,
-      "holdSeconds": 1.8,
-      "exitSeconds": 0
-    },
-    schema: BUILTIN_TEMPLATE_SCHEMAS.focusCards
-  },
   {
     "label": "Timeline",
-    "description": "Three to five events on a fine continuous line on black; without dates.",
+    "description": "Three to five events on a fine continuous line over relevant media or black; without dates.",
     "usesGlobalTextEffect": false,
     "usesGlobalTransition": false,
     "usesGlobalBackgroundEffect": false,
@@ -458,7 +590,7 @@ var BUILTIN_TEMPLATE_MANIFEST = [
   },
   {
     "label": "Comparison",
-    "description": "Two short statements with equal weight on black, side by side or stacked in portrait.",
+    "description": "Two short statements with equal weight over relevant media or black, side by side or stacked in portrait.",
     "usesGlobalTextEffect": false,
     "usesGlobalTransition": false,
     "usesGlobalBackgroundEffect": false,
@@ -489,7 +621,7 @@ var BUILTIN_TEMPLATE_MANIFEST = [
   },
   {
     "label": "Quote",
-    "description": "A short exact quotation with a legible attribution on black.",
+    "description": "A short exact quotation with a legible attribution over relevant media or black.",
     "usesGlobalTextEffect": false,
     "usesGlobalTransition": false,
     "usesGlobalBackgroundEffect": false,
@@ -518,7 +650,7 @@ var BUILTIN_TEMPLATE_MANIFEST = [
   },
   {
     "label": "Key figure",
-    "description": "One supplied figure with one short label on black.",
+    "description": "One supplied figure with one short label over relevant media or black.",
     "usesGlobalTextEffect": false,
     "usesGlobalTransition": false,
     "usesGlobalBackgroundEffect": false,

package/dist/{chunk-3ZTEFJIR.js → chunk-ELVOT2FQ.js}

@@ -1,7 +1,7 @@
 import {
   limitsConcurrentVideoDecoders,
   resolveMediaType
-} from "./chunk-UDIODEDK.js";
+} from "./chunk-224QNWRA.js";
 import {
   ExternalVideoBackdropProvider,
   resolveDensity