@vanillaskyai/video 0.1.1-beta.1 → 0.2.0

package/CHANGELOG.md

@@ -4,19 +4,37 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
-<!-- Add release notes here before running release:prepare. -->
-
-## 0.1.1-beta.1
-
-### Patch Changes
-
-- 9c42eb7: Publish the customer-compatible beta through the read-only npm API comparison.
-
-## 0.1.1-beta.0
-
-### Patch Changes
-
-- 66e8e95: Enforce pre-1.0 compatibility intent with structurally parsed release evidence.
+<!-- Add release notes for the next version here. -->
+
+## 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
+
+No runtime changes: the public API, behavior, and dependencies are identical to
+0.1.0. This release replaces the 0.1.1-beta line and moves `latest` onto a
+single, current version so the repository, npm, and vanillasky.ai agree.
+
+- Simplified the release process to a version bump, an annotated tag on `main`,
+  and an OIDC publish. Changesets, the generated Version Packages branch, and
+  the npm-latest compatibility gate are removed; the tag job now packs a commit
+  CI has already verified instead of re-running the suite.
 
 ## 0.1.0
 

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-beta.1`.
+Status: frozen public beta contract for `0.2.0`.
 
 This document defines the API that may enter the fresh
 `@vanillaskyai/video` package. An export not listed here is internal. Tests and
@@ -19,17 +19,9 @@ public API review.
 - `0.1.x` patch releases do not make breaking changes to documented APIs or the
   serialized `Video` schema.
 - A compatible later `0.x` minor needs no migration ceremony. A breaking
-  pre-1.0 minor requires either its package-targeting `minor` Changeset (on a
-  feature PR) or its generated candidate changelog section (on the Version
-  Packages PR) to contain both `### Breaking changes` and `### Adoption`.
-  Those sections must include concrete fenced before and after code examples,
-  respectively. Start a breaking Changeset with its one-line summary, followed
-  by those headings, so Changesets preserves both as real headings in the
-  generated changelog. The verifier accepts the configured Changesets
-  changelog's canonical two-space continuation indentation, but not headings
-  hidden inside code fences. On a feature PR, only a Changeset added since the
-  pull request's exact base commit can provide this evidence. A `patch`
-  Changeset never authorizes a breaking change.
+  pre-1.0 minor must document both `### Breaking changes` and `### Adoption` in
+  its changelog section, with concrete fenced before and after code examples
+  respectively.
 - An API prefixed with `experimental_` may change in a patch. Canonical examples
   must pin an exact package version when they use one.
 - Deprecated APIs remain usable until the next minor release. The `0.1`
@@ -40,11 +32,10 @@ public API review.
 - Framework adapters are examples, not separate public APIs. The release suite
   verifies current Next.js and Vite production builds.
 
-The automated npm comparison runs for every candidate, including a feature PR
-whose package version still equals npm `latest` and a Version Packages PR whose
-Changesets have already been consumed. It is intentionally conservative: every
-existing normalized declaration and reachable support declaration must remain
-exactly equal because the report cannot safely distinguish input and output positions.
+The frozen public API surface report is compared on every pull request. It is
+intentionally conservative: every existing normalized declaration and reachable
+support declaration must remain exactly equal because the report cannot safely
+distinguish input and output positions.
 As a result, even optional field additions to an existing public
 type fail a patch gate; use a documented pre-1.0 minor unless a separately
 reviewed, direction-aware compatibility check can prove the change safe. New
@@ -106,6 +97,9 @@ provider-neutral text-delta escape hatch.
 ### Types
 
 - `VideoHandlerOptions`
+- `MediaResolver`
+- `MediaResolverContext`
+- `ResolvedMedia`
 - `ServerTemplateRegistry`
 - `ServerTemplateMetadata`
 - `VideoFinishReason`
@@ -120,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.
@@ -150,6 +152,7 @@ provider-neutral text-delta escape hatch.
 
 - `UseVideoOptions`
 - `UseVideoResult`
+- `VideoPlaybackMode`
 - `VideoPlayerProps`
 - `VideoErrorOptions`
 
@@ -174,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.1 beta](https://img.shields.io/badge/version-0.1.1-beta.1_beta-7c3aed)
+![Version 0.2.0 beta](https://img.shields.io/badge/version-0.2.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-beta.1 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.2.0 ai @ai-sdk/openai
 ```
 
 For coding agents:
@@ -70,6 +70,10 @@ The local authorization denies every production 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,7 +105,7 @@ 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-beta.1/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart`](https://github.com/VanillaSkyAi/video/tree/v0.2.0/examples/nextjs-quickstart).
 
 ## Shape the response
 

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-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-FQ47WXAJ.js → chunk-K5SRF7D3.js}

@@ -2,6 +2,7 @@
 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"}
@@ -12,6 +13,8 @@ Turn the supplied factual input into a concise, coherent sequence using trusted
 
 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 grounded in the supplied input.
 - 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.
@@ -25,6 +28,7 @@ Composition rules:
 
 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.

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

@@ -1,14 +1,28 @@
 import {
   DEFAULT_VIDEO_SYSTEM_PROMPT
-} from "./chunk-FQ47WXAJ.js";
+} from "./chunk-K5SRF7D3.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 = DEFAULT_VIDEO_SYSTEM_PROMPT.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(),
@@ -116,17 +136,19 @@ ${options.basePrompt.trim()}` : 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.",
+    resolverMediaAvailable ? "Prefer a relevant resolved image or video background on later media-capable scenes whenever the input 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 customer input.",
-    JSON.stringify(plannerCatalog(templates))
+    JSON.stringify(plannerCatalog(templates, resolverMediaAvailable))
   ].filter((line) => line != null).join("\n");
 }
 
 export {
+  getStandardMediaResolverContract,
   createTemplateSystemPrompt
 };

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";