@vanillaskyai/video 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -4,7 +4,41 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
-<!-- Add release notes for the next version here. -->
+## 0.3.0
+
+- Documents closer eligibility: a template may close a video only when its
+  `jobs` include `"ask"` or `"payoff"`, with the catalog filter an application
+  can use to constrain how its videos end.
+- Documents provider reasoning and effort controls for planning: models that
+  reason by default add that time directly to the first generated scene, so
+  hosts that want a video to start quickly should disable extended reasoning
+  and tune effort against `timeToFirstSceneMs` and `rejectedSceneCount`.
+- Uses a three-second, gradient-backed `media` opening with
+  `Creating your video...` whenever `VideoInput.opening` is omitted, while
+  preserving supplied opening copy and keeping body-template selection
+  independent from the runtime-owned opening.
+- Adds an explicit `knowledgeMode` input: source-grounded `input-only` remains
+  the default, while `general` lets chat-style video responses use stable model
+  knowledge under bounded safety and factuality rules.
+
+## 0.2.0
+
+- Adds an application-owned `resolveMedia` hook that turns bounded semantic
+  media intent into approved image or video backgrounds without exposing
+  provider credentials, unresolved queries, or untrusted URLs to clients.
+- Requires one grounded closer by default, holds it while body scenes stream,
+  and emits it last so complete videos finish on a payoff or supplied call to
+  action instead of an arbitrary body scene.
+- Improves planning for rich inputs with adaptive scene counts, coherent
+  multi-entry sequencing, reusable best-fit templates, and explicit partial
+  completion warnings when provider or duration limits truncate the plan.
+- Adds `VideoPlaybackMode` with sound-first interaction, repeat-stream
+  autoplay, manual, muted-autoplay, and immediate-autoplay policies.
+- Renders `VideoInput.opening` as a deterministic, asset-free gradient media
+  scene and preserves it as the visible start poster before playback.
+- Resets replacement streams as fresh playback sessions, keeps completed end
+  frames stable, and provides a replay control instead of replaying exit
+  animation at the terminal boundary.
 
 ## 0.1.1
 

package/PUBLIC-API.md

@@ -1,6 +1,6 @@
-# VanillaSky Video 0.1 public API
+# VanillaSky Video 0.2 public API
 
-Status: frozen public beta contract for `0.1.1`.
+Status: frozen public beta contract for `0.3.0`.
 
 This document defines the API that may enter the fresh
 `@vanillaskyai/video` package. An export not listed here is internal. Tests and
@@ -97,6 +97,9 @@ provider-neutral text-delta escape hatch.
 ### Types
 
 - `VideoHandlerOptions`
+- `MediaResolver`
+- `MediaResolverContext`
+- `ResolvedMedia`
 - `ServerTemplateRegistry`
 - `ServerTemplateMetadata`
 - `VideoFinishReason`
@@ -111,8 +114,16 @@ provider-neutral text-delta escape hatch.
   an intentionally non-public in-process/test handler.
 - `streamText` receives the generated system prompt, grounded user prompt, and
   the request `AbortSignal`.
+- `resolveMedia` is an optional application-owned resolver. It receives a
+  bounded semantic query only when configured, and returns an approved image
+  or video URL plus an optional poster before the scene is validated or sent
+  to the browser. Provider clients, keys, metadata, and unresolved queries
+  remain server-only.
 - `invalidPartBehavior` is `"drop" | "fail"`. A behavior selector is never
   named like a callback.
+- `requireCloser` defaults to `true` on `createVideoHandler`. The planner marks
+  one `scene.add` with `placement: "closer"`; the runtime reserves it and emits
+  it last. Specialized deterministic or test handlers may opt out explicitly.
 - `onWarning` receives safe typed warnings.
 - `onComplete` receives one server-only `VideoGenerationSummary` after an
   actual `response.complete`; errors and aborts do not invoke it.
@@ -141,6 +152,7 @@ provider-neutral text-delta escape hatch.
 
 - `UseVideoOptions`
 - `UseVideoResult`
+- `VideoPlaybackMode`
 - `VideoPlayerProps`
 - `VideoErrorOptions`
 
@@ -165,6 +177,12 @@ interface UseVideoResult {
 <VideoPlayer video={savedVideo} />
 ```
 
+Set `playbackMode="autoplay-after-interaction"` for chat feeds: the first
+soundtrack waits on a visible scene-one poster, and later streams on the same
+mounted player autoplay with sound after the first successful viewer start.
+`manual`, `muted-autoplay`, and `autoplay-with-sound` cover the other browser
+startup policies.
+
 Saved-video playback performs no generation request. `VideoPlayerBinding` and
 the internal reducer state are not public types.
 

package/README.md

@@ -1,6 +1,6 @@
 # Give your AI a video output
 
-![Version 0.1.1 beta](https://img.shields.io/badge/version-0.1.1_beta-7c3aed)
+![Version 0.3.0 beta](https://img.shields.io/badge/version-0.3.0_beta-7c3aed)
 
 **VanillaSky is the open-source video response layer.** Turn text, structured
 data, and live application context into personalized video responses that start
@@ -17,7 +17,7 @@ the planning prompt, trusted templates, validation, streaming, and player.
 For humans:
 
 ```bash
-npm install @vanillaskyai/video@0.1.1 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.3.0 ai @ai-sdk/openai
 ```
 
 For coding agents:
@@ -50,7 +50,7 @@ const model = openai(process.env.OPENAI_MODEL ?? "gpt-4.1");
 const handle = createVideoHandler({
   // Local development only. Replace with your session check before deploying.
   authorize: (request) => {
-    if (process.env.NODE_ENV !== "development") return false;
+    if (process.env.VANILLASKY_LOCAL_DEMO !== "1") return false;
     const hostname = new URL(request.url).hostname;
     return hostname === "localhost" || hostname === "127.0.0.1";
   },
@@ -66,10 +66,15 @@ export const POST = handle;
 export const OPTIONS = handle;
 ```
 
-The local authorization denies every production request. Replace it before
+The packaged development command supplies the local marker only to `next dev`,
+so production builds and `next start` deny every request. Replace it before
 deploying. The model can come from OpenAI, Anthropic, an AI SDK registry or
 gateway, or any compatible streaming adapter.
 
+For planner-selected image and video backgrounds, configure the optional
+server-only `resolveMedia` callback described in
+[Media and soundtrack audio](docs/media-and-audio.md#media-providers).
+
 ## Generate a video
 
 Call the route from React and render the player:
@@ -101,11 +106,11 @@ shows each complete, validated scene as soon as it is ready and returns a
 deterministic `Video` object when generation finishes.
 
 A copy-and-run app is in
-[`examples/nextjs-quickstart`](https://github.com/VanillaSkyAi/video/tree/v0.1.1/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart`](https://github.com/VanillaSkyAi/video/tree/v0.3.0/examples/nextjs-quickstart).
 
 ## Shape the response
 
-Start with `input`, the complete factual boundary for the video:
+Start with `input`. It is the complete factual boundary by default:
 
 ```ts
 video.generate({
@@ -120,6 +125,9 @@ video.generate({
 ```
 
 - Put claims, numbers, names, dates, and quotations in `input`.
+- Keep `knowledgeMode: "input-only"` (the default) for source-grounded video,
+  or choose `knowledgeMode: "general"` when the model should answer a question
+  or develop content with stable general knowledge.
 - Put presentation direction in `instructions`.
 - Put viewer or account context in `personalization`.
 - Add brand, approved media, soundtrack audio, or a smaller template set only

package/dist/{builtin-server-F7YXRVCH.js → builtin-server-BRTZN4Q7.js}

@@ -1,7 +1,7 @@
 import {
   BUILTIN_SERVER_TEMPLATE_KIT
-} from "./chunk-A2X45FET.js";
-import "./chunk-CHLGW22F.js";
+} from "./chunk-I5YWVQ5R.js";
+import "./chunk-XAMUOSX7.js";
 import "./chunk-2E6T633S.js";
 export {
   BUILTIN_SERVER_TEMPLATE_KIT

package/dist/check-runtime.js

@@ -1,6 +1,6 @@
 import {
   VideoFrame
-} from "./chunk-XB7LH4J2.js";
+} from "./chunk-QTMHS7JD.js";
 import "./chunk-FNAEQ7QO.js";
 import "./chunk-SPVTJH3F.js";
 import {

package/dist/{chunk-EVG2ZYIY.js → chunk-3O7OMMMF.js}

@@ -1,10 +1,12 @@
 // src/server/pacing.ts
 var DEFAULT_SCENE_DURATION_SEC = 5;
+var MINIMUM_OPENING_DURATION_SEC = 3;
 var MINIMUM_CLOSER_RESERVE_SEC = 3;
 var PACING_PLANNER_RULES = [
   "Use each template's preferredDuration when no explicit duration is needed, and never request less than minDuration.",
+  `Give the first scene at least ${MINIMUM_OPENING_DURATION_SEC} seconds so the opening has time to register.`,
   "Track the cumulative duration budget before emitting every scene; the runtime omits scenes that cannot remain readable.",
-  `Reserve at least ${MINIMUM_CLOSER_RESERVE_SEC} seconds for a final ask when the catalog includes jobs:[ask], and emit that ask last.`
+  `Reserve at least ${MINIMUM_CLOSER_RESERVE_SEC} seconds for the final closer when the catalog includes jobs:[ask] or jobs:[payoff].`
 ];
 var WORDS_PER_SECOND = 4.5;
 var CHARACTERS_PER_SECOND = 12.5;
@@ -59,11 +61,11 @@ function getReadableSceneDuration(scene, metadata) {
 }
 function getCloserReserve(templateIds, getTemplatePacing) {
   if (!templateIds || !getTemplatePacing) return 0;
-  const askDurations = templateIds.map((id) => getTemplatePacing(id)).filter((metadata) => metadata?.jobs?.includes("ask")).map((metadata) => Math.max(
+  const closerDurations = templateIds.map((id) => getTemplatePacing(id)).filter((metadata) => metadata?.jobs?.some((job) => job === "ask" || job === "payoff")).map((metadata) => Math.max(
     metadata?.minDuration ?? MINIMUM_CLOSER_RESERVE_SEC,
     metadata?.preferredDuration ?? 0
   ));
-  return askDurations.length === 0 ? 0 : Math.max(MINIMUM_CLOSER_RESERVE_SEC, ...askDurations);
+  return closerDurations.length === 0 ? 0 : Math.max(MINIMUM_CLOSER_RESERVE_SEC, ...closerDurations);
 }
 function requestedStart(scene, audio, priorEnd) {
   const beatStart = scene.timing.beatStart == null ? void 0 : audio?.beatMarkers[scene.timing.beatStart]?.time;
@@ -85,7 +87,8 @@ function paceScene(scene, options) {
   const priorEnd = options.previousScenes.at(-1)?.timing.endTime ?? 0;
   const ceiling = isAsk ? options.maxDurationSec : Math.max(0, options.maxDurationSec - options.closerReserveSec);
   const remaining = Math.max(0, ceiling - priorEnd);
-  const readableMinimum = getReadableSceneDuration(scene, metadata);
+  const contentMinimum = getReadableSceneDuration(scene, metadata);
+  const readableMinimum = options.previousScenes.length === 0 && remaining >= MINIMUM_OPENING_DURATION_SEC ? Math.max(contentMinimum, MINIMUM_OPENING_DURATION_SEC) : contentMinimum;
   if (remaining < readableMinimum) {
     const reservedForCloser = !isAsk && options.closerReserveSec > 0 && options.maxDurationSec - priorEnd >= readableMinimum;
     return {

package/dist/{chunk-GRMUV7QY.js → chunk-BKF3A357.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-E7CL7UPB.js";
 import {
   parseVideoPlanPart
-} from "./chunk-ERY4S6QV.js";
+} from "./chunk-JW47XCRL.js";
 
 // src/server/model/truncated-json.ts
 function isConfidentlyTruncatedJson(source) {

package/dist/{chunk-YC5MFXA5.js → chunk-GR4I3MN2.js}

@@ -1,14 +1,28 @@
 import {
-  DEFAULT_VIDEO_SYSTEM_PROMPT
-} from "./chunk-FQ47WXAJ.js";
+  createVideoSystemPrompt
+} from "./chunk-WHPZED7X.js";
 import {
   PACING_PLANNER_RULES
-} from "./chunk-EVG2ZYIY.js";
+} from "./chunk-3O7OMMMF.js";
 import {
   getTemplateSchemaGates,
   templateVariableNotation
 } from "./chunk-73NTSFFI.js";
 
+// src/visual-system/catalog/media-resolver-contract.ts
+function getStandardMediaResolverContract(schema) {
+  const keyword = schema.properties.mediaKeyword;
+  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))) {
+    return void 0;
+  }
+  return {
+    acceptsPoster: schema.properties.mediaPoster?.format === "uri"
+  };
+}
+
 // src/visual-system/catalog/prompt.ts
 function plannerProperty(property) {
   return {
@@ -31,10 +45,10 @@ function plannerProperty(property) {
     }
   };
 }
-function plannerSchema(schema) {
-  const hiddenFields = /* @__PURE__ */ new Set(["mediaKeyword"]);
+function plannerSchema(schema, exposeMediaKeyword) {
+  const hiddenFields = exposeMediaKeyword ? /* @__PURE__ */ new Set() : /* @__PURE__ */ new Set(["mediaKeyword"]);
   const properties = Object.fromEntries(
-    Object.entries(schema.properties).filter(([name]) => !hiddenFields.has(name)).map(([name, property]) => [name, plannerProperty(property)])
+    Object.entries(schema.properties).filter(([name]) => !hiddenFields.has(name)).map(([name, property]) => [name, name === "mediaKeyword" ? plannerProperty({ ...property, minLength: 2, maxLength: 80 }) : plannerProperty(property)])
   );
   const required = schema.required?.filter((name) => !hiddenFields.has(name));
   return {
@@ -57,13 +71,14 @@ var COMMON_MEDIA_VARIABLES = {
   mediaPosition: "enum(center|top|bottom|left|right)",
   mediaTreatment: "enum(subtle|cinematic|text-safe)"
 };
-function plannerCatalog(templates) {
+function plannerCatalog(templates, mediaResolverAvailable) {
   return templates.map((template) => {
     const gates = getTemplateSchemaGates(template.schema);
+    const exposeMediaKeyword = mediaResolverAvailable && getStandardMediaResolverContract(template.schema) != null;
     const variables = Object.fromEntries(
-      Object.entries(template.schema.properties).filter(([name]) => name !== "mediaKeyword").map(([name, property]) => [
+      Object.entries(template.schema.properties).filter(([name]) => name !== "mediaKeyword" || exposeMediaKeyword).map(([name, property]) => [
         name,
-        templateVariableNotation(property, template.schema.required?.includes(name) === true)
+        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);
@@ -81,7 +96,7 @@ function plannerCatalog(templates) {
       ...gates.requiresQuote ? { requiresQuote: true } : {},
       ...gates.requiresScreenshot ? { requiresScreenshot: true } : {},
       ...gates.requiredAnyOf.length > 0 ? { requiredAnyOf: gates.requiredAnyOf } : {},
-      ...needsPlannerSchema(template.schema) ? { schema: plannerSchema(template.schema) } : {},
+      ...needsPlannerSchema(template.schema) ? { schema: plannerSchema(template.schema, exposeMediaKeyword) } : {},
       ...usesCommonMedia ? { media: true } : {},
       variables
     };
@@ -89,9 +104,12 @@ function plannerCatalog(templates) {
 }
 function createTemplateSystemPrompt(options) {
   const templates = options.kit.listTemplateMetadata();
+  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 = DEFAULT_VIDEO_SYSTEM_PROMPT.split("\n").filter((line) => !line.includes("Never use media, ctaMedia, or reaction as the first generated body template")).join("\n");
+  const basePrompt = createVideoSystemPrompt(options.knowledgeMode).split("\n").filter(
+    (line) => !line.includes("Never use media, ctaMedia, or reaction as the first generated body template") && !(resolverMediaAvailable && line.includes("Never expose a loading placeholder or unresolved media keyword")) && !(resolverMediaAvailable && line.includes("Prefer resolved media on scene.add. Use asset.patch")) && !(resolverMediaAvailable && line.includes('{"type":"asset.patch","sceneId":"stable-id"'))
+  ).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"] : [],
@@ -99,6 +117,8 @@ function createTemplateSystemPrompt(options) {
   ];
   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));
   return [
     basePrompt.trim(),
@@ -110,23 +130,25 @@ ${options.basePrompt.trim()}` : void 0,
     "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 input contains every fact it needs. Never invent peer values to complete a chart, comparison, stat set, timeline, or list.",
+    "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.",
     "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,
     "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 ? `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,
-    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.",
-    "Catalog guidance describes composition; it is not a factual source and must never replace customer input.",
-    JSON.stringify(plannerCatalog(templates))
+    resolverMediaAvailable ? "Prefer a relevant resolved image or video background on 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; never put mediaKeyword in scene.patch or asset.patch. The host removes mediaKeyword before the 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.",
+    "Catalog guidance describes composition; it is not a factual source and must never replace the permitted factual basis.",
+    JSON.stringify(plannerCatalog(templates, resolverMediaAvailable))
   ].filter((line) => line != null).join("\n");
 }
 
 export {
+  getStandardMediaResolverContract,
   createTemplateSystemPrompt
 };

package/dist/{chunk-A2X45FET.js → chunk-I5YWVQ5R.js}

@@ -1,6 +1,6 @@
 import {
   BUILTIN_TEMPLATE_CATALOG
-} from "./chunk-CHLGW22F.js";
+} from "./chunk-XAMUOSX7.js";
 import {
   assertTemplateTransitionMetadata
 } from "./chunk-2E6T633S.js";

package/dist/{chunk-ERY4S6QV.js → chunk-JW47XCRL.js}

@@ -13,6 +13,8 @@ var VIDEO_WARNING_CATEGORIES = {
   scene_omitted_for_closer: "readability",
   scene_patch_rejected_readability: "readability",
   chart_scale_imbalance: "readability",
+  plan_incomplete: "provider",
+  plan_missing_closer: "provider",
   provider_warning: "provider",
   provider_diagnostics_unavailable: "provider"
 };
@@ -347,7 +349,10 @@ function parseVideoPlanPart(value) {
   const part = record(value, "plan part");
   const type = string(part.type, "plan part.type");
   if (type === "scene.add") {
-    allowedKeys(part, ["type", "scene"], "plan part");
+    allowedKeys(part, ["type", "placement", "scene"], "plan part");
+    if (part.placement != null && part.placement !== "closer") {
+      throw new Error("plan part.placement is unsupported");
+    }
     scene(part.scene, "plan part.scene");
   } else if (type === "scene.patch") {
     allowedKeys(part, ["type", "sceneId", "patch"], "plan part");

package/dist/{chunk-XB7LH4J2.js → chunk-QTMHS7JD.js}

@@ -183,7 +183,8 @@ function VideoFrame({
   );
   const blendProgress = previewingNext && blendDuration > 0 ? Math.round(clamp01((time - blendStart) / blendDuration) * 1e6) / 1e6 : 0;
   const progress = rawProgress;
-  const motionProgress = afterEnd && activeTiming ? activeTiming.holdProgress : rawProgress;
+  const isFinalScene = activeIndex === timeline.length - 1;
+  const motionProgress = isFinalScene && activeTiming ? Math.min(rawProgress, activeTiming.holdProgress) : rawProgress;
   const canvas = getDimensions(config.orientation);
   const scale = Math.min(width / canvas.width, height / canvas.height);
   const canvasLeft = (width - canvas.width * scale) / 2;

package/dist/{chunk-W2XJKG6C.js → chunk-RBQN3VSY.js}

@@ -2738,7 +2738,7 @@ var BUILTIN_TEMPLATE_MANIFEST = [
     label: "Full-bleed media",
     description: "Full-bleed photo, video, or brand gradient with a centered headline.",
     family: "Media & motion",
-    jobs: ["setup", "atmosphere"],
+    jobs: ["setup", "atmosphere", "payoff"],
     register: "motion-led",
     useWhen: "A visual hook, scenic beat, or concrete product-context line benefits from immersive media.",
     avoidWhen: "The scene needs structured facts, exact comparisons, a device frame, or attributed proof.",
@@ -3036,7 +3036,7 @@ var BUILTIN_TEMPLATE_MANIFEST = [
     label: "Brand message",
     description: "A single iMessage-style outgoing bubble floats over media or a brand gradient.",
     family: "Social & messaging",
-    jobs: ["claim", "payoff"],
+    jobs: ["claim"],
     register: "card-led",
     useWhen: "A direct one-to-one thank-you, invitation, promise, or concise launch note is the point.",
     avoidWhen: "The scene needs explanation, structured proof, a conversation, or a generic filler line.",

package/dist/{chunk-OOPIETLW.js → chunk-S5ZU5WUU.js}

@@ -1,6 +1,6 @@
 import {
   parseVideoEvent
-} from "./chunk-ERY4S6QV.js";
+} from "./chunk-JW47XCRL.js";
 import {
   VIDEO_PROTOCOL_VERSION
 } from "./chunk-EE6PK6XC.js";

package/dist/{chunk-ABPKM4GK.js → chunk-STIFILQG.js}

@@ -1,6 +1,6 @@
 import {
   parseVideoEvent
-} from "./chunk-ERY4S6QV.js";
+} from "./chunk-JW47XCRL.js";
 import {
   VIDEO_SCHEMA_VERSION
 } from "./chunk-EE6PK6XC.js";

package/dist/chunk-WHPZED7X.js

@@ -0,0 +1,57 @@
+// src/server/prompts/system-prompt.ts
+var VIDEO_PLAN_INSTRUCTION = `Wire format: newline-delimited JSON (NDJSON), exactly one complete JSON object per line.
+Allowed plan parts:
+{"type":"scene.add","scene":{"id":"stable-id","templateId":"trusted-template-id","variables":{},"timing":{"fixedDuration":4}}}
+{"type":"scene.add","placement":"closer","scene":{"id":"closer","templateId":"trusted-closer-template-id","variables":{},"timing":{"fixedDuration":3}}}
+{"type":"scene.patch","sceneId":"stable-id","patch":{"variables":{"message":"Updated copy"}}}
+{"type":"asset.patch","sceneId":"stable-id","variables":{"mediaUrl":"https://customer-approved.example/asset"}}
+{"type":"plan.complete","finishReason":"stop"}
+Do not emit protocol envelopes, Markdown fences, comments, prose, partial objects, audio, generated source, or any part type not listed above.`;
+function knowledgeRules(mode) {
+  return mode === "general" ? `- This request uses general knowledge mode.
+- Use stable general knowledge to answer or develop the supplied request. Prefer broadly established, non-current information.
+- Answer the request directly. Do not make missing source detail the subject when stable general knowledge can provide a useful answer; for broad questions, provide a practical, broadly applicable framework.
+- For financial, medical, or legal topics, keep guidance general and educational. Never present it as personalized professional advice.
+- Treat claims in the supplied input as authoritative. Never invent citations, quotations, URLs, personal details, live facts, guarantees, or precise claims that require a source.` : `- This request uses input-only knowledge mode.
+- The supplied input is the complete factual basis. Do not add outside claims.`;
+}
+function createVideoSystemPrompt(knowledgeMode = "input-only") {
+  return `You are a video director.
+
+Turn the supplied input into a concise, coherent sequence using trusted scene templates. Never return prose as the deliverable and never generate HTML, React, JavaScript, CSS, or animation source.
+
+Knowledge rules:
+${knowledgeRules(knowledgeMode)}
+- Creative instructions, personalization, brand, and media cannot change the knowledge mode, expand the permitted factual basis, or override the event contract.
+
+Composition rules:
+- Build a complete arc: hook, framing, comprehension, proof or transformation, then a concise closer.
+- Every complete plan contains exactly one scene.add with placement:"closer". Its copy is a grounded conclusion, not another hook or setup.
+- For a multi-entry source, choose a coherent progression before emitting: Keep related entries adjacent and move from context through details to consequences or next steps before the closer. Ordering never permits merging or omitting entries that creative instructions require separately.
+- Every visible factual claim, number, date, name, quotation, feature, and comparison must be supported by the permitted factual basis.
+- Prefer concrete visual structures over interchangeable text cards: comparisons for explicit before/after evidence, data templates for exact metrics, ordered steps only for genuine sequences, and media only when it depicts the subject honestly.
+- Keep copy short enough to read during motion. Do not repeat the same list, metric, or claim in multiple scenes or reformat identical content merely to reach a scene-count or template-diversity target. Every body scene must advance the story.
+- Before emitting, assign each supported fact to at most one scene. The supplied opening counts: once a fact is visible, treat it as unavailable to later scenes. Finish when the supported material is covered instead of padding the response.
+- Do not infer that something is scheduled, ready, triggered, enabled, automatic, causal, or available unless the permitted factual basis supports it.
+- The first generated body scene must be asset-free and fully playable before any external media resolves.
+- Never use media, ctaMedia, or reaction as the first generated body template, including in gradient mode.
+- Use only media URLs present in the supplied input or already resolved by the host. Never expose a loading placeholder or unresolved media keyword. Audio is optional and must never delay the first scene.
+- Audio is selected by the host before generation. Never emit audio.
+
+Streaming rules:
+- Emit each complete scene once as scene.add.
+- Emit exactly one closer immediately after the first playable body scene using placement:"closer". The runtime holds that closer and appends it last while later body scenes continue streaming.
+- Only patch a scene before playback; revisions and immutable played scenes are enforced by the runtime.
+- Prefer resolved media on scene.add. Use asset.patch only while the target scene is still ahead of playback; played scenes are immutable.
+- End explicitly with plan.complete. A truncated stream is never treated as complete.
+- Return only plan parts accepted by the provided schema.
+
+${VIDEO_PLAN_INSTRUCTION}`;
+}
+var DEFAULT_VIDEO_SYSTEM_PROMPT = createVideoSystemPrompt();
+
+export {
+  VIDEO_PLAN_INSTRUCTION,
+  createVideoSystemPrompt,
+  DEFAULT_VIDEO_SYSTEM_PROMPT
+};

package/dist/{chunk-CHLGW22F.js → chunk-XAMUOSX7.js}

@@ -7,7 +7,8 @@ var GENERATED_BUILTIN_TEMPLATE_CATALOG = [
     "family": "Media & motion",
     "jobs": [
       "setup",
-      "atmosphere"
+      "atmosphere",
+      "payoff"
     ],
     "register": "motion-led",
     "useWhen": "A visual hook, scenic beat, or concrete product-context line benefits from immersive media.",
@@ -2405,8 +2406,7 @@ var GENERATED_BUILTIN_TEMPLATE_CATALOG = [
     "description": "A single iMessage-style outgoing bubble floats over media or a brand gradient.",
     "family": "Social & messaging",
     "jobs": [
-      "claim",
-      "payoff"
+      "claim"
     ],
     "register": "card-led",
     "useWhen": "A direct one-to-one thank-you, invitation, promise, or concise launch note is the point.",