@vanillaskyai/video 0.8.8 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.
+
+- Show the spoken opening as a quiet chapter on black when opening media is absent or cannot load. Keep it readable until media or the film is ready, without another generation call.
+
+- Package licensed, self-hosted Roboto fallback fonts for the fixed cinematic typography; remove unused promotional template primitives.
+
+
+### Breaking changes
+
+- Replace the 28 promotional templates with eight cinematic templates: Full-bleed, Chapter, Focus cards, Timeline, Reach out, Comparison, Quote, and Key figure. Graphics use fixed black backgrounds and white/neutral system typography; only Full-bleed and Reach out accept media.
+- Remove configurable `brand` input and persisted `style.brand`, and remove the public `VideoBrand`, `VideoBrandInput`, `VideoBackground`, and `resolveVideoBrand` exports. Persisted schema is now `0.2` and streaming protocol is `0.6`; older payloads are explicitly rejected.
+- Source-owned templates declare authored reveal, hold and exit minimums. Quote and figure examples remain authoring fixtures and never become factual runtime defaults.
+
+Before:
+
+```tsx
+<VideoChat options={{ endpoint: "/api/video-chat", brand: { background: "twilight" } }} />
+```
+
+### Adoption
+
+Remove brand options and regenerate source-owned templates from the new catalog. Re-author or regenerate saved videos from retained source material; do not rename old IDs or change their version field blindly. See [cinematic migration](docs/maintainers/cinematic-migration.md).
+
+```tsx
+<VideoChat options={{ endpoint: "/api/video-chat" }} />
+```
+
+
 ## 0.8.8
 
 - Use equal spacing between Sessions, Settings, and Voice controls on mobile and desktop.

package/PUBLIC-API.md

@@ -131,9 +131,9 @@ playable scenes on an interrupted plan, emitting non-fatal warnings. Explicit
 `invalidPartBehavior: "fail"` retains strict generation semantics.
 
 - A response accepts `prompt`, `mode`, `orientation`, optional bounded
-  `conversation`, `opening`, `brand`, and `style`. `opening` is an optional
+  `conversation`, `opening`, and `style`. `opening` is an optional
   prewritten hook from a selected suggestion. The response returns protocol
-  `0.5` SSE and negotiates `data.video-chat-opening`, which carries the bounded
+  `0.6` SSE and negotiates `data.video-chat-opening`, which carries the bounded
   6-9 word hook and optional stock-search `keyword` and `fallbackKeyword` before the first scene.
 - The planner produces that opening as the first line of the same model stream
   that produces the scenes. The separate opening-media action resolves its
@@ -216,7 +216,7 @@ export function App() {
 ```
 
 Pass the same session configuration through `options`, for example
-`<VideoChat options={{ endpoint, headers, templates, brand }} />`. `className`
+`<VideoChat options={{ endpoint, headers, templates }} />`. `className`
 and `welcomeTitle` are the only shell-level customizations. The stylesheet is
 scoped under `.vanillasky-video-chat` and does not style the host document.
 
@@ -294,10 +294,7 @@ playback is unaffected by either. `onComplete(video)` reports that a streamed
 response finished composing; `onPlaybackEnd(video)` reports that the visible
 playhead actually reached the end for either a stream or saved replay.
 
-`resolveVideoBrand` fills a partial brand with the documented defaults and
-preset backgrounds, producing the fully resolved `VideoBrand` that `parseVideo`
-requires. Use it when authoring a `Video` by hand rather than copying default
-values into application code.
+Graphic scenes use fixed black backgrounds, white/neutral typography, and the system font stack. `VideoInput.brand`, `VideoStyle.brand`, `VideoBrand`, `VideoBrandInput`, `VideoBackground`, and `resolveVideoBrand` are removed. Media retains natural color. Persisted schema `0.2` and event protocol `0.6` reject earlier versions; changing a version field alone is not a migration.
 
 ## Template authoring
 
@@ -394,7 +391,7 @@ from `/server` without crossing a React type boundary.
 
 - A completed `Video` is JSON-serializable and may be stored by the host.
 - Every completed value carries the required storage field
-  `schemaVersion: "0.1"`; it is independent from streaming protocol `0.5`.
+  `schemaVersion: "0.2"`; it is independent from streaming protocol `0.6`.
 - `parseVideo(value: unknown)` is the strict universal storage boundary. It
   validates the full document and returns a detached, deeply frozen `Video`.
 - JSON serialization remains platform-native; the SDK has no redundant public

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

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

package/dist/{catalog-types-BIhSpOWK.d.ts → catalog-types-WTbLP6Jh.d.ts}

@@ -36,6 +36,10 @@ type TemplateFamily = "Media & motion" | "Data & metrics" | "Product showcase" |
 interface TemplateTimingMetadata {
     /** Schema fields whose rendered content may inform a future adaptive duration. */
     readonly contentFields: readonly string[];
+    /** Authored motion and uninterrupted reading minimums in seconds. */
+    readonly revealSeconds?: number;
+    readonly holdSeconds?: number;
+    readonly exitSeconds?: number;
     /** How content in contentFields should be measured; no runtime behavior is implied. */
     readonly contentUnit: "words" | "characters" | "items";
 }
@@ -71,4 +75,4 @@ interface SceneTemplateMetadata {
     timing?: TemplateTimingMetadata;
 }
 
-export type { SceneTemplateMetadata as S, TemplateFamily as T, TemplateJob as a, TemplateRegister as b, TemplateTimingMetadata as c, TemplateJsonSchema as d, TemplateTransitionTiming as e, TemplateJsonSchemaProperty as f };
+export type { SceneTemplateMetadata as S, TemplateJsonSchema as T, TemplateFamily as a, TemplateTimingMetadata as b, TemplateTransitionTiming as c, TemplateJsonSchemaProperty as d };

package/dist/chapter-title-YRLIQY3V.js

@@ -0,0 +1,7 @@
+import {
+  TitleSceneTemplate
+} from "./chunk-EWWCQFTI.js";
+import "./chunk-4YM2M62S.js";
+export {
+  TitleSceneTemplate
+};

package/dist/check-runtime.js

@@ -1,14 +1,10 @@
 import {
   VideoFrame
-} from "./chunk-2USVB3CY.js";
+} from "./chunk-ELVOT2FQ.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-5CDAM24P.js";
-import "./chunk-XWWLKRNU.js";
+import "./chunk-TVIU23OM.js";
 import "./chunk-SPVTJH3F.js";
-import {
-  resolveVideoBrand
-} from "./chunk-XGRA2MUV.js";
-import "./chunk-WJ6FLKNC.js";
+import "./chunk-R3XAOMKP.js";
 import "./chunk-73NTSFFI.js";
 
 // src/cli/check-runtime.ts
@@ -48,7 +44,7 @@ async function renderTemplateChecks(input) {
   for (const orientation of ["portrait", "landscape"]) {
     const [width, height] = orientation === "portrait" ? [1080, 1920] : [1920, 1080];
     const config = {
-      schemaVersion: "0.1",
+      schemaVersion: "0.2",
       orientation,
       scenes: [{
         id: "authoring-check",
@@ -56,12 +52,7 @@ async function renderTemplateChecks(input) {
         variables: input.variables,
         timing: { startTime: 0, endTime: input.duration, fixedDuration: input.duration }
       }],
-      style: {
-        brand: resolveVideoBrand({
-          font: "Inter, sans-serif",
-          colors: { primary: "#6D5EF5", secondary: "#17122F", foreground: "#FFFFFF" }
-        })
-      }
+      style: {}
     };
     for (const progress of progressPoints) {
       let first;

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

@@ -1,6 +1,6 @@
 import {
   createVideoSystemPrompt
-} from "./chunk-5SLENAJW.js";
+} from "./chunk-PAJ44TFW.js";
 import {
   PACING_PLANNER_RULES
 } from "./chunk-3O7OMMMF.js";
@@ -15,7 +15,7 @@ function getStandardMediaResolverContract(schema) {
   const url = schema.properties.mediaUrl;
   const type = schema.properties.mediaType;
   const allowedTypes = new Set(type?.enum ?? []);
-  if (keyword?.format !== "stock-media-keyword" || url?.format !== "uri" || !["photo", "video", "gradient"].every((value) => allowedTypes.has(value))) {
+  if (keyword?.format !== "stock-media-keyword" || url?.format !== "uri" || !["photo", "video"].every((value) => allowedTypes.has(value))) {
     return void 0;
   }
   return {
@@ -26,6 +26,8 @@ function getStandardMediaResolverContract(schema) {
 // src/visual-system/catalog/prompt.ts
 function plannerProperty(property) {
   return {
+    ...property.description == null ? {} : { description: property.description },
+    ...property.examples == null ? {} : { examples: property.examples.slice(0, 1) },
     ...property.type == null ? {} : { type: property.type },
     ...property.format == null ? {} : { format: property.format },
     ...property.enum == null ? {} : { enum: property.enum },
@@ -60,10 +62,6 @@ function plannerSchema(schema, exposeMediaKeyword) {
     }
   };
 }
-function needsPlannerSchema(schema) {
-  const visit = (property) => property.minimum != null || property.maximum != null || property.type === "object" || property.items != null && visit(property.items);
-  return Object.values(schema.properties).some(visit);
-}
 function isMediaProperty(property) {
   return property?.format === "uri" || property?.format === "supplied-image" || property?.format === "stock-media-keyword";
 }
@@ -71,13 +69,6 @@ function requiresAvailableMedia(template) {
   const gates = getTemplateSchemaGates(template.schema);
   return (template.schema.required ?? []).some((name) => isMediaProperty(template.schema.properties[name])) || gates.requiredAnyOf.some((group) => group.every((name) => isMediaProperty(template.schema.properties[name])));
 }
-var COMMON_MEDIA_VARIABLES = {
-  mediaUrl: "media",
-  mediaType: "enum(auto|photo|video|gradient)",
-  mediaPoster: "media",
-  mediaPosition: "enum(center|top|bottom|left|right)",
-  mediaTreatment: "enum(none|subtle|cinematic|text-safe)"
-};
 function plannerCatalog(templates, mediaResolverAvailable) {
   return templates.map((template) => {
     const gates = getTemplateSchemaGates(template.schema);
@@ -88,23 +79,19 @@ function plannerCatalog(templates, mediaResolverAvailable) {
         name === "mediaKeyword" ? "string{2..80}" : templateVariableNotation(property, template.schema.required?.includes(name) === true)
       ])
     );
-    const usesCommonMedia = Object.entries(COMMON_MEDIA_VARIABLES).every(([name, notation]) => variables[name] === notation);
-    if (usesCommonMedia) {
-      for (const name of Object.keys(COMMON_MEDIA_VARIABLES)) delete variables[name];
-    }
     return {
       id: template.id,
       jobs: template.jobs,
       use: template.useWhen ?? template.description,
+      ...template.avoidWhen ? { avoid: template.avoidWhen } : {},
       ...template.minDuration == null && template.preferredDuration == null ? {} : {
         seconds: [template.minDuration ?? null, template.preferredDuration ?? null]
       },
       ...gates.requiresStat ? { requiresStat: true } : {},
       ...gates.requiresQuote ? { requiresQuote: true } : {},
       ...gates.requiresScreenshot ? { requiresScreenshot: true } : {},
-      ...gates.requiredAnyOf.length > 0 ? { requiredAnyOf: gates.requiredAnyOf } : {},
-      ...needsPlannerSchema(template.schema) ? { schema: plannerSchema(template.schema, exposeMediaKeyword) } : {},
-      ...usesCommonMedia ? { media: true } : {},
+      ...gates.requiredAnyOf.length > 0 ? { requiredAnyOf: gates.requiredAnyOf.map((group) => group.filter((name) => name !== "mediaKeyword" || exposeMediaKeyword)) } : {},
+      schema: plannerSchema(template.schema, exposeMediaKeyword),
       variables
     };
   });
@@ -112,24 +99,14 @@ function plannerCatalog(templates, mediaResolverAvailable) {
 function createTemplateSystemPrompt(options) {
   const templates = options.kit.listTemplateMetadata().filter((template) => !requiresAvailableMedia(template) || options.suppliedMediaAvailable === true || options.mediaResolverAvailable === true && getStandardMediaResolverContract(template.schema) != null);
   const resolverMediaAvailable = options.mediaResolverAvailable === true && templates.some(({ schema }) => getStandardMediaResolverContract(schema) != null);
-  const ids = new Set(templates.map(({ id }) => id));
-  const fields = new Set(templates.flatMap(({ schema }) => Object.keys(schema.properties)));
   const basePrompt = createVideoSystemPrompt(options.knowledgeMode, options.narrate === true).split("\n").filter(
     (line) => !line.includes("Never use media, ctaMedia, or reaction as the first generated body template") && // The rule that keeps the opening beat asset-free belongs to the same
     // pair as the one below it: both exist so playback can start without
     // waiting on a provider, and both go when the host owns that wait.
     !(options.mediaOnFirstScene === true && line.includes("The first generated body scene must be asset-free")) && !(resolverMediaAvailable && line.includes("Never expose a loading placeholder or unresolved media keyword"))
   ).join("\n");
-  const factRules = [
-    ...ids.has("cardList") ? ["cardList needs two or three unused parallel facts"] : [],
-    ...ids.has("steps") ? ["steps needs two or three unused sequential facts"] : [],
-    ...ids.has("tripleStats") ? ["tripleStats needs exactly three unused peer values"] : []
-  ];
-  const mediaTemplates = ["media", "ctaMedia", "reaction"].filter((id) => ids.has(id));
-  const mediaTemplateNames = mediaTemplates.length === 3 ? "media, ctaMedia, and reaction" : mediaTemplates.join(", ");
-  const terminalPayoffs = ["media", "emojiBurst", "confetti"].filter((id) => ids.has(id));
-  const terminalPayoffNames = terminalPayoffs.length < 2 ? terminalPayoffs.join("") : `${terminalPayoffs.slice(0, -1).join(", ")}, or ${terminalPayoffs.at(-1)}`;
-  const listFields = ["items", "itemEmojis", "steps", "stepEmojis", "problemEmojis", "solutionEmojis"].filter((name) => fields.has(name));
+  const mediaTemplates = templates.filter(({ schema }) => getStandardMediaResolverContract(schema) != null).map(({ id }) => id);
+  const terminalPayoffs = templates.filter(({ jobs }) => jobs?.includes("payoff")).map(({ id }) => id);
   return [
     basePrompt.trim(),
     options.basePrompt?.trim() ? `
@@ -139,20 +116,18 @@ ${options.basePrompt.trim()}` : void 0,
     "TRUSTED TEMPLATE CATALOG",
     "Only use template IDs from this catalog. Only emit variables declared for the selected template.",
     "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.",
-    `seconds is [minimum, preferred]. media=true adds these optional variables: ${Object.entries(COMMON_MEDIA_VARIABLES).map(([name, notation]) => `${name}:${notation}`).join(", ")}.`,
     "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,
-    ids.has("cardList") && ids.has("steps") && ids.has("tripleStats") ? "Fact availability carries across templates: cardList and steps each need two or three unused facts (parallel for cardList, sequential for steps) and must carry only the count the evidence supports, and tripleStats needs exactly three unused peer values. Never invent a fact to fill a collection, and do not fill one with facts already shown in another scene." : factRules.length > 0 ? `Fact availability carries across templates: ${factRules.join(", and ")}. Use only the count the evidence supports. Never invent a fact to fill a collection, and do not fill one with facts already shown in another scene.` : void 0,
-    "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 the input has no clear grounded action, never invent one and do not use jobs:[ask]. End with a grounded payoff using ${terminalPayoffNames}. Its concise 6\u201312 words of declarative copy must answer the story's so-what without repeating hook or setup language. Use media for an honest visual payoff, emojiBurst for playful delight, and confetti only for a real celebration, win, or milestone.` : void 0,
+    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,
     "requiresQuote is a hard gate: use those templates only for exact quoted words and attribution present in raw input. Never turn a role, relationship, or summary into speech. requiresScreenshot likewise needs an actual supplied screenshot URL.",
     templates.some(({ schema }) => (schema["x-vanillasky"]?.requiredAnyOf?.length ?? 0) > 0) ? "requiredAnyOf is a hard presence gate: satisfy every listed group with at least one non-empty value." : void 0,
-    mediaTemplates.length > 0 && options.mediaOnFirstScene !== true ? `For streaming startup, ${mediaTemplateNames} ${mediaTemplates.length === 1 ? "is" : "are"} forbidden as the first generated body template, even when mediaType is gradient. Start with a content-fit non-media template.` : void 0,
-    listFields.length > 0 ? `For list variables (${listFields.join(", ")}), emit actual JSON arrays. Keep list labels to 1\u20133 words. Keep step labels to 1\u20132 words and at most 18 characters. Do not use pipes or newlines as list delimiters.` : void 0,
-    fields.has("bars") ? 'For bars, emit an actual JSON array of 2\u20136 grounded objects with "label" and "value" fields. Use comparable units and avoid a largest-to-smallest positive ratio above 20. Do not encode bars as a string.' : void 0,
-    resolverMediaAvailable ? `Prefer a relevant resolved image or video background on ${options.mediaOnFirstScene === true ? "every media-capable scene, the first included," : "later media-capable scenes"} whenever the permitted factual basis names a concrete person, place, product context, activity, or outcome that can be depicted honestly. Emit mediaKeyword on scene.add as a specific 2\u20138 word semantic query of at most 80 characters. The host removes mediaKeyword before the complete scene reaches the browser and replaces it with an approved asset. Use mediaType=gradient for abstract, sensitive, unsafe, or visually ambiguous material. Never emit or invent mediaUrl or mediaPoster.` : mediaTemplates.length > 0 ? `Use exact grounded values for required fields. mediaUrl must come verbatim from supplied input. Stock queries are not available. Do not select ${mediaTemplateNames} without a supplied mediaUrl; if another template has no mediaUrl, explicitly use mediaType=gradient. mediaType auto detects a URL, while gradient deliberately uses no external asset.` : "Use exact grounded values for required fields.",
+    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-4YM2M62S.js

@@ -0,0 +1,13 @@
+// src/visual-system/scene-templates/editorial-typography.ts
+var editorialFont = '-apple-system, BlinkMacSystemFont, "Helvetica Neue", Roboto, Arial, sans-serif';
+var fade = (value) => {
+  const t = Math.max(0, Math.min(1, value));
+  return t * t * (3 - 2 * t);
+};
+var editorialLabel = (unit) => ({ fontSize: unit * 0.042, fontWeight: 400, color: "#b7b7bc", lineHeight: 1.25 });
+
+export {
+  editorialFont,
+  fade,
+  editorialLabel
+};