@vanillaskyai/video 0.1.1 → 0.2.0

package/dist/server.js

@@ -1,27 +1,27 @@
 import {
   createTextDeltaVideoPlanner
-} from "./chunk-GRMUV7QY.js";
+} from "./chunk-BKF3A357.js";
 import {
   createVideo
-} from "./chunk-IXCUY3B3.js";
+} from "./chunk-TGFO454Q.js";
 import "./chunk-E7CL7UPB.js";
 import {
   BUILTIN_SERVER_TEMPLATE_KIT,
   createServerTemplateRegistry,
   overlayServerTemplateRegistry
-} from "./chunk-A2X45FET.js";
+} from "./chunk-I5YWVQ5R.js";
 import {
   createTemplateSceneValidator
 } from "./chunk-LMG3GHLL.js";
 import {
   encodeVideoSseEvent,
   videoSseHeaders
-} from "./chunk-OOPIETLW.js";
-import "./chunk-ABPKM4GK.js";
+} from "./chunk-S5ZU5WUU.js";
+import "./chunk-STIFILQG.js";
 import {
   parseVideoEvent,
   safePublicDiagnostic
-} from "./chunk-ERY4S6QV.js";
+} from "./chunk-JW47XCRL.js";
 import {
   MAX_RETAINED_MEDIA_URL_LENGTH
 } from "./chunk-GHJEAP4O.js";
@@ -29,14 +29,15 @@ import {
   VIDEO_PROTOCOL_VERSION
 } from "./chunk-EE6PK6XC.js";
 import {
-  createTemplateSystemPrompt
-} from "./chunk-YC5MFXA5.js";
+  createTemplateSystemPrompt,
+  getStandardMediaResolverContract
+} from "./chunk-Q2DDQKEG.js";
 import {
   DEFAULT_VIDEO_SYSTEM_PROMPT
-} from "./chunk-FQ47WXAJ.js";
-import "./chunk-EVG2ZYIY.js";
+} from "./chunk-K5SRF7D3.js";
+import "./chunk-3O7OMMMF.js";
 import "./chunk-352ZZCET.js";
-import "./chunk-CHLGW22F.js";
+import "./chunk-XAMUOSX7.js";
 import "./chunk-2E6T633S.js";
 import {
   validateBrandInput
@@ -397,6 +398,7 @@ function createVideoStreamHandler(options) {
           validateScene: options.validateScene,
           getTemplatePacing: options.getTemplatePacing,
           invalidPartBehavior: options.invalidPartBehavior ?? "drop",
+          requireCloser: options.requireCloser,
           onError: options.onError,
           onWarning: options.onWarning,
           onComplete: options.onComplete,
@@ -459,6 +461,155 @@ function createVideoStreamHandler(options) {
   };
 }
 
+// src/server/media-resolver.ts
+var MAX_MEDIA_QUERY_CHARACTERS = 80;
+var MAX_MEDIA_QUERY_WORDS = 8;
+function queryIsBounded(query) {
+  const length = [...query].length;
+  const words = query.match(/\S+/gu)?.length ?? 0;
+  return length >= 2 && length <= MAX_MEDIA_QUERY_CHARACTERS && words <= MAX_MEDIA_QUERY_WORDS;
+}
+function preferredType(value) {
+  if (value === "photo") return "image";
+  if (value === "video") return "video";
+  return "any";
+}
+function cleanUrl(value, field) {
+  if (value == null || value === "") return void 0;
+  if (typeof value !== "string" || !value.trim() || value.length > MAX_RETAINED_MEDIA_URL_LENGTH) {
+    throw new Error(`Resolved media ${field} is invalid`);
+  }
+  return value.trim();
+}
+function fallbackVariables(variables) {
+  const fallback = { ...variables };
+  delete fallback.mediaKeyword;
+  delete fallback.mediaUrl;
+  delete fallback.mediaPoster;
+  fallback.mediaType = "gradient";
+  return fallback;
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+async function resolveVariables(options) {
+  if (!Object.hasOwn(options.variables, "mediaKeyword")) return options.variables;
+  const variables = { ...options.variables };
+  const rawQuery = typeof variables.mediaKeyword === "string" ? variables.mediaKeyword.trim() : "";
+  delete variables.mediaKeyword;
+  if (!options.contract) return variables;
+  if (!options.openingReady || !options.resolveMedia || !queryIsBounded(rawQuery)) {
+    return fallbackVariables(variables);
+  }
+  let resolved;
+  try {
+    resolved = await options.resolveMedia(rawQuery, {
+      input: options.input,
+      templateId: options.templateId,
+      preferredType: preferredType(variables.mediaType),
+      signal: options.signal
+    });
+  } catch (error) {
+    if (options.signal.aborted) throw options.signal.reason ?? error;
+    if (isAbortError(error)) throw error;
+    return fallbackVariables(variables);
+  }
+  if (options.signal.aborted) {
+    throw options.signal.reason ?? new DOMException("The media request was aborted", "AbortError");
+  }
+  if (!resolved) return fallbackVariables(variables);
+  if (resolved.type !== "image" && resolved.type !== "video") {
+    throw new Error("Resolved media type is invalid");
+  }
+  const url = cleanUrl(resolved.url, "URL");
+  if (!url) throw new Error("Resolved media URL is required");
+  const posterUrl = options.contract.acceptsPoster ? cleanUrl(resolved.posterUrl, "poster URL") : void 0;
+  options.approveUrl(options.input, url);
+  if (posterUrl) options.approveUrl(options.input, posterUrl);
+  variables.mediaUrl = url;
+  variables.mediaType = resolved.type === "image" ? "photo" : "video";
+  if (posterUrl) variables.mediaPoster = posterUrl;
+  else delete variables.mediaPoster;
+  return variables;
+}
+function templateContract(templates, templateId) {
+  const metadata = templates.getTemplateMetadata(templateId);
+  return metadata == null ? void 0 : getStandardMediaResolverContract(metadata.schema);
+}
+function withoutKeyword(variables) {
+  if (!Object.hasOwn(variables, "mediaKeyword")) return variables;
+  const clean = { ...variables };
+  delete clean.mediaKeyword;
+  return clean;
+}
+function sanitizeUnknownTemplatePart(part) {
+  if (part.type === "scene.add") {
+    return { ...part, scene: { ...part.scene, variables: withoutKeyword(part.scene.variables) } };
+  }
+  if (part.type === "scene.patch" && part.patch.variables) {
+    return { ...part, patch: { ...part.patch, variables: withoutKeyword(part.patch.variables) } };
+  }
+  if (part.type === "asset.patch") {
+    return { ...part, variables: withoutKeyword(part.variables) };
+  }
+  return part;
+}
+async function resolvePartVariables(options) {
+  if (!options.templateId) return sanitizeUnknownTemplatePart(options.part);
+  const shared = {
+    contract: templateContract(options.templates, options.templateId),
+    input: options.input,
+    templateId: options.templateId,
+    signal: options.signal,
+    resolveMedia: options.resolveMedia,
+    approveUrl: options.approveUrl,
+    openingReady: options.openingReady
+  };
+  if (options.part.type === "scene.add") {
+    const variables = await resolveVariables({
+      ...shared,
+      variables: options.part.scene.variables
+    });
+    return { ...options.part, scene: { ...options.part.scene, variables } };
+  }
+  if (options.part.type === "scene.patch" && options.part.patch.variables) {
+    const variables = await resolveVariables({
+      ...shared,
+      variables: options.part.patch.variables
+    });
+    return { ...options.part, patch: { ...options.part.patch, variables } };
+  }
+  if (options.part.type === "asset.patch") {
+    const variables = await resolveVariables({
+      ...shared,
+      variables: options.part.variables
+    });
+    return { ...options.part, variables };
+  }
+  return options.part;
+}
+function createMediaResolvingPlanner(options) {
+  return async function* resolveMediaPlan(context) {
+    const sceneTemplates = /* @__PURE__ */ new Map();
+    for await (const part of options.planner(context)) {
+      const templateId = part.type === "scene.add" ? part.scene.templateId : part.type === "scene.patch" || part.type === "asset.patch" ? sceneTemplates.get(part.sceneId) : void 0;
+      if (part.type === "scene.add") {
+        sceneTemplates.set(part.scene.id, part.scene.templateId);
+      }
+      yield await resolvePartVariables({
+        part,
+        templateId,
+        input: context.request.input,
+        signal: context.signal,
+        templates: options.templates,
+        resolveMedia: options.resolveMedia,
+        approveUrl: options.approveUrl,
+        openingReady: options.isOpeningReady(context.request.input)
+      });
+    }
+  };
+}
+
 // src/server/create-video-handler.ts
 function createVideoHandler(options) {
   if (options?.authorize !== "none" && typeof options?.authorize !== "function") {
@@ -473,22 +624,50 @@ function createVideoHandler(options) {
     includeRawProviderData,
     basePrompt,
     allowMediaUrl,
+    resolveMedia,
+    requireCloser = true,
     ...handlerOptions
   } = options;
   const templates = configuredTemplates ? overlayServerTemplateRegistry(BUILTIN_SERVER_TEMPLATE_KIT, configuredTemplates) : BUILTIN_SERVER_TEMPLATE_KIT;
+  const approvedMediaUrls = /* @__PURE__ */ new WeakMap();
+  const openingReadyInputs = /* @__PURE__ */ new WeakSet();
+  const approveUrl = (input, url) => {
+    const approved = approvedMediaUrls.get(input) ?? /* @__PURE__ */ new Set();
+    approved.add(url);
+    approvedMediaUrls.set(input, approved);
+  };
+  const planner = createTextDeltaVideoPlanner({ streamText, includeRawProviderData });
+  const validateTemplateScene = createTemplateSceneValidator({
+    kit: templates,
+    allowMediaUrl: (url, context) => approvedMediaUrls.get(context.input)?.has(url) === true || allowMediaUrl?.(url, context) === true
+  });
   return createVideoStreamHandler({
     ...handlerOptions,
-    generate: createTextDeltaVideoPlanner({ streamText, includeRawProviderData }),
+    requireCloser,
+    generate: createMediaResolvingPlanner({
+      planner,
+      templates,
+      resolveMedia,
+      approveUrl,
+      isOpeningReady: (input) => openingReadyInputs.has(input)
+    }),
     systemPrompt: ({ capabilities: capabilities2 }) => {
       const selectedIds = capabilities2?.templates == null ? void 0 : new Set(capabilities2.templates);
       const selectedTemplates = selectedIds == null ? templates.listTemplateMetadata() : templates.listTemplateMetadata().filter(({ id }) => selectedIds.has(id));
       return createTemplateSystemPrompt({
         kit: { listTemplateMetadata: () => selectedTemplates },
-        basePrompt
+        basePrompt,
+        mediaResolverAvailable: resolveMedia != null
       });
     },
     supportedCapabilities: templates.capabilities,
-    validateScene: createTemplateSceneValidator({ kit: templates, allowMediaUrl }),
+    validateScene: (scene, context) => {
+      validateTemplateScene(scene, context);
+      const isAsk = templates.getTemplateMetadata(scene.templateId)?.jobs?.includes("ask") === true;
+      if (!isAsk) {
+        openingReadyInputs.add(context.input);
+      }
+    },
     getTemplatePacing: (templateId) => templates.getTemplateMetadata(templateId)
   });
 }

package/dist/{system-prompt-A6UXNTPK.js → system-prompt-GYTYGWGO.js}

@@ -1,7 +1,7 @@
 import {
   DEFAULT_VIDEO_SYSTEM_PROMPT,
   VIDEO_PLAN_INSTRUCTION
-} from "./chunk-FQ47WXAJ.js";
+} from "./chunk-K5SRF7D3.js";
 export {
   DEFAULT_VIDEO_SYSTEM_PROMPT,
   VIDEO_PLAN_INSTRUCTION

package/dist/template-catalog.js

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

package/dist/templates.d.ts

@@ -1,9 +1,9 @@
-import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-BMNcHqa9.js';
-export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-BMNcHqa9.js';
+import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-CBedbj1n.js';
+export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-CBedbj1n.js';
 import { ComponentType } from 'react';
 import { d as TemplateJsonSchema, S as SceneTemplateMetadata } from './catalog-types-BIhSpOWK.js';
 export { T as TemplateFamily, c as TemplateTimingMetadata, e as TemplateTransitionTiming } from './catalog-types-BIhSpOWK.js';
-import './types-B-PZR6G_.js';
+import './types-_t4bduwX.js';
 
 interface TemplateExample<Variables extends Record<string, unknown> = Record<string, unknown>> {
     name: string;

package/dist/test.d.ts

@@ -1,8 +1,9 @@
-import { f as VideoScene, e as VideoOrientation, g as VideoStyle, V as Video, a as VideoAudio, d as VideoInput } from './types-B-PZR6G_.js';
-import { a as VideoWarning, b as VideoFinishReason } from './events-_wfjbmEp.js';
+import { f as VideoScene, e as VideoOrientation, g as VideoStyle, V as Video, a as VideoAudio, d as VideoInput } from './types-_t4bduwX.js';
+import { a as VideoWarning, b as VideoFinishReason } from './events-B-28kERX.js';
 
 type MockVideoStreamPart = {
     type: "scene.add";
+    placement?: "closer";
     scene: VideoScene;
 } | {
     type: "scene.patch";

package/dist/test.js

@@ -233,9 +233,9 @@ async function* simulateVideoStream(parts, options = {}) {
   if (timeoutMs != null && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
     throw new Error("Simulation timeoutMs must be a non-negative finite number");
   }
-  const { createVideo } = await import("./compose-video-CN3VSWST.js");
-  const { createTextDeltaVideoPlanner } = await import("./text-stream-6XHC7J47.js");
-  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-F7YXRVCH.js");
+  const { createVideo } = await import("./compose-video-34GRZIF2.js");
+  const { createTextDeltaVideoPlanner } = await import("./text-stream-UPGUD2TD.js");
+  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-BRTZN4Q7.js");
   const { createTemplateSceneValidator } = await import("./validate-T7GBU2YF.js");
   const controller = new AbortController();
   const forwardAbort = () => controller.abort(options.signal?.reason);

package/dist/{text-stream-6XHC7J47.js → text-stream-UPGUD2TD.js}

@@ -1,8 +1,8 @@
 import {
   createTextDeltaVideoPlanner
-} from "./chunk-GRMUV7QY.js";
+} from "./chunk-BKF3A357.js";
 import "./chunk-E7CL7UPB.js";
-import "./chunk-ERY4S6QV.js";
+import "./chunk-JW47XCRL.js";
 import "./chunk-EE6PK6XC.js";
 import "./chunk-XGRA2MUV.js";
 export {

package/dist/{types-B-PZR6G_.d.ts → types-_t4bduwX.d.ts}

@@ -159,6 +159,7 @@ interface VideoGenerationContext {
 }
 type VideoPlanPart = {
     type: "scene.add";
+    placement?: "closer";
     scene: VideoScene;
 } | {
     type: "scene.patch";

package/docs/concepts.md

@@ -54,6 +54,12 @@ another streaming text model.
 The planner does not create public event IDs, checksums, revisions, or final
 snapshots. The runtime owns those guarantees.
 
+`createVideoHandler` asks the planner to emit one early
+`scene.add` with `placement: "closer"` after the first playable body scene.
+That placement is planner-only: the runtime holds the validated closer,
+reserves its readable duration while later body scenes stream, and appends it
+last without persisting `placement` into the completed `Video`.
+
 | Boundary | Type | Owner |
 | --- | --- | --- |
 | Planner parts | Internal validated plan data | Server/provider adapter |
@@ -73,6 +79,7 @@ audio.set             optional, before any scene
 scene.add             supplied opening
 scene.add             generated body
 scene.add             generated body
+scene.add             reserved closer
 response.complete     exact terminal snapshot
 ```
 

package/docs/custom-templates.md

@@ -311,9 +311,9 @@ Templates whose core proof needs a real statistic can add
 `"x-vanillasky": { "requiresStat": true }`. See the structured-data and
 supplied-media references for complete examples.
 
-The automatic `opening` uses the built-in `notification` variables (`appName`
-and `message`). If you replace `notification` while using automatic openings,
-keep that variable contract.
+The automatic `opening` uses the built-in `media` variables (`texts` and
+`mediaType: "gradient"`). If you replace `media` while using automatic
+openings, keep that variable contract.
 
 ## What belongs where
 

package/docs/errors.md

@@ -35,7 +35,9 @@ try {
 `response.error` or `response.abort` rejects it. The hook still retains the
 latest validated `video.video`, and its player stream still receives terminal
 events, so an application may keep already accepted scenes visible while it
-offers a retry.
+offers a retry. If the planner already supplied a validated reserved closer,
+the runtime appends it to that playable terminal snapshot before reporting a
+late provider failure; it never invents or rewrites closer copy during recovery.
 
 Both a server `response.abort` and an explicit `video.abort(reason)` keep
 `video.status` at `aborted`; `video.error` contains the same safe typed abort

package/docs/getting-started.md

@@ -5,7 +5,7 @@
 Install VanillaSky:
 
 ```bash
-npm install @vanillaskyai/video@0.1.1 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.2.0 ai @ai-sdk/openai
 ```
 
 Set your provider key in `.env.local` (never commit it):
@@ -49,7 +49,7 @@ The local bypass is intentionally fail-closed: it accepts only localhost while
 Next.js is in development and denies every production request. Replace it with
 your real session validation before deploying. For literal files and commands,
 use the tested
-[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.1.1/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.2.0/examples/nextjs-quickstart).
 
 `model` can come from any AI SDK provider, registry, gateway, compatible API,
 or custom implementation. The application can choose a cheaper or faster model
@@ -90,10 +90,12 @@ reactive UI.
 
 `video.status` is `idle`, `streaming`, `complete`, `error`, or `aborted`.
 `video.video` is the latest deterministic video, and `video.warnings` contains
-bounded typed diagnostics safe to show or branch on. Provider limits and
-content filters are available to the server through the `onComplete` summary;
-surface that server-owned state separately if completeness matters to your
-product.
+bounded typed diagnostics safe to show or branch on. A playable response that
+stops at a planner length limit includes a `plan_incomplete` warning because
+requested scenes or the ending may be missing. Provider finish reasons and
+content-filter details remain available to the server through the `onComplete`
+summary; surface that server-owned state separately when completeness matters
+to your product.
 
 Persist a completed `Video` as JSON and play it later without another model
 request:

package/docs/input-and-first-scene.md

@@ -28,14 +28,17 @@ Bound request bytes and reject secret-shaped fields on the server. Do not pass p
 
 ## Opening
 
-When supplied, `opening` becomes a deterministic five-second `notification`
-scene emitted before provider work. The SDK owns its scene ID, template, variables,
-and timing so callers only provide the copy. It should:
+When supplied, `opening` becomes a deterministic `media` scene emitted before
+provider work. It contains only the supplied sentence and explicitly uses the
+brand gradient without stock media. The SDK requests a three-second opening,
+then applies its normal readability and overall-duration budget. It owns the
+scene ID, template, variables, and timing so callers only provide the copy. It
+should:
 
 - be personal or situational enough to feel intentional;
 - require no network media lookup;
 - remain true if generation later fails;
-- fit comfortably in both supported orientations;
+- be one concise sentence that fits comfortably in both supported orientations;
 - be part of the final story, not a spinner disguised as a scene.
 
 Omit `opening` when the generated story should begin with its first planned scene.

package/docs/integrate-nextjs.md

@@ -5,7 +5,7 @@
 Install VanillaSky and one AI SDK provider:
 
 ```bash
-npm install @vanillaskyai/video@0.1.1 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.2.0 ai @ai-sdk/openai
 ```
 
 Create an ignored `.env.local`:
@@ -71,7 +71,7 @@ requests; replace it with your application's session validation before
 deploying.
 
 The copy-and-run app is in the
-[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.1.1/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.2.0/examples/nextjs-quickstart).
 
 For another LLM, replace `openai(...)` with the matching AI SDK model. The route
 shape and React code stay the same. See [Provider integration](provider-integration.md)

package/docs/media-and-audio.md

@@ -10,9 +10,10 @@ The 0.1 SDK does not provide narration, TTS, or speech synchronization.
 If a product needs spoken audio, the application must create and synchronize
 that experience outside this contract.
 
-Only send source URLs you trust. Resolve provider results before generation,
-pass approved assets through `suppliedMedia`, and preload the next scene's asset
-before it becomes active. Keep provider credentials on the server.
+Only send source URLs you trust. Pass known approved assets through
+`suppliedMedia`, or configure the server-only `resolveMedia` callback for
+planner-selected backgrounds. Preload the next scene's asset before it becomes
+active. Keep provider credentials on the server.
 
 Supplied URLs and data URIs are not copied into the LLM prompt. The model sees
 an optional pool of opaque HTTPS-shaped references plus safe descriptive
@@ -47,23 +48,81 @@ Keep the catalog and files in your application so you control caching,
 licensing, and deployment. The SDK continues to handle playback, timing,
 serialization, replay, and export from the supplied URL.
 
+## Start with sound
+
+Browsers block audible autoplay unless the viewer has already interacted with
+the page. For a sound-first experience, keep the branded generation intro
+visible and let the player's start control provide that interaction:
+
+```tsx
+<VideoPlayer
+  {...video.playerProps}
+  playbackMode="autoplay-after-interaction"
+/>
+```
+
+The generation cover immediately includes a centered **Play with sound**
+button. A click starts the soundtrack and holds that branded cover as a
+three-second generation intro while planning continues. Once both the intro
+and the first validated scene are ready, the generated timeline begins from
+time zero. The generation intro remains visible indefinitely if the viewer has
+not clicked yet, even when the complete generated video is already ready. The
+server keeps the generated first scene on screen for at least three more
+seconds when the duration budget permits. After that first successful sound start,
+replacement streams on the same mounted player autoplay the same generation
+intro with sound and fall back to a start control if the browser blocks them.
+
+When `VideoInput.opening` is supplied, its asset-free gradient `media` scene
+replaces the generic generation cover as soon as it is available. It remains
+as the static start poster until the viewer clicks, then begins the actual
+timeline with sound; there is no additional generic pre-roll before it.
+
+Use `playbackMode="manual"` to require the button on every run,
+`playbackMode="muted-autoplay"` for browser-safe muted autoplay, or
+`playbackMode="autoplay-with-sound"` to try audible autoplay immediately. The
+lower-level `autoPlay` and `startMuted` props remain available when no playback
+mode is set.
+
 ## Media providers
 
-VanillaSky is provider-independent. Resolve image or video searches in your
-server application before generation and pass the approved results through
-`suppliedMedia`. The built-in planner sees opaque references and safe metadata;
-it does not call a stock-media provider or turn `mediaKeyword` into a URL.
+VanillaSky is provider-independent. When `resolveMedia` is configured, the
+built-in planner may emit a bounded semantic query for later media-capable
+scenes. The SDK calls the application-owned resolver on the server, replaces
+the query with the approved URL, type, and optional poster, then validates the
+scene before emitting it. Without the callback, media intent stays hidden from
+the planner. The first accepted generated scene remains asset-free.
+
+```ts
+import { createVideoHandler } from "@vanillaskyai/video/server";
+
+createVideoHandler({
+  authorize: checkSession,
+  streamText: planWithYourModel,
+  resolveMedia: async (query, { preferredType, signal }) => {
+    const asset = await searchYourApprovedCatalog({ query, preferredType, signal });
+    return asset
+      ? { url: asset.url, type: asset.type, posterUrl: asset.posterUrl }
+      : null;
+  },
+});
+```
+
+The resolver query is 2–80 characters and at most eight words. Return `null`
+when no licensed, safe, relevant asset exists; media-capable templates fall
+back to the brand gradient when their schema permits it. The browser never
+receives `mediaKeyword`, provider keys, or raw provider metadata.
 
 `allowMediaUrl` is an authorization hook for applications with their own custom
 stream adapter. It validates a final URL; it does not search for, fetch, or
 resolve media. The default 0.1 path needs no callback because every planner URL
 must already be present in `suppliedMedia`.
 
-Do not expose provider keys to React, allow arbitrary planner URLs, or add a
-provider abstraction to the template API. Templates describe visual building
-blocks; the application owns media retrieval, caching, licensing, and delivery.
+Do not expose provider keys to React or allow arbitrary planner URLs. Templates
+describe visual building blocks; the application owns media retrieval,
+caching, licensing, and delivery.
 
-For Pexels, keep `PEXELS_API_KEY` on the server, search before generation, and
-pass only validated `images.pexels.com` or `videos.pexels.com` results through
-`suppliedMedia`. The application remains responsible for attribution, search,
-orientation filtering, MIME checks, timeouts, caching, and fallback behavior.
+For Pexels, keep `PEXELS_API_KEY` on the server and implement `resolveMedia`
+with the Pexels API. Return only validated `images.pexels.com` or
+`videos.pexels.com` results. The application remains responsible for
+attribution, search, orientation filtering, MIME checks, timeouts, caching,
+and fallback behavior.

package/docs/prompt-and-input.md

@@ -83,6 +83,13 @@ The model never returns React, HTML, CSS, or executable JavaScript.
 Generated `scene.add`, `scene.patch`, and `asset.patch` operations all pass
 through the same merged-scene validation before the player sees them.
 
+The standard planner contract requires one `scene.add` with
+`placement: "closer"` immediately after the first playable body scene. The
+model writes short grounded conclusion copy: a supplied action when one
+exists, otherwise a declarative payoff that answers the story's “so what.” The
+runtime holds the closer and emits it last, so a long body plan cannot displace
+an ending that was already generated.
+
 ## What reaches the LLM
 
 The provider adapter receives:

package/docs/provider-integration.md

@@ -84,6 +84,13 @@ duration actually committed; compare it with the `maxDurationSec` supplied by
 your application when applying a retry policy. These fields provide a
 server-side quality signal without exposing model metadata in the browser.
 Warnings include the same bounded typed warnings emitted to the client.
+`plan_incomplete` identifies a playable partial response whose planner reported
+a length limit; applications should show that result as incomplete and may
+offer a bounded retry with a larger output or duration budget.
+`plan_missing_closer` identifies a playable plan that ended without the
+explicit final scene required by the standard handler. `createVideoHandler`
+sets `requireCloser: true` by default. Specialized deterministic integrations
+may set `requireCloser: false`; ordinary AI planners should keep the default.
 For non-interactive backfills, define an application threshold (for example,
 no rejected scenes and a useful committed-duration ratio) and retry a bounded
 number of times. Keep the best accepted result rather than treating

package/docs/reference/protocol.md

@@ -78,6 +78,15 @@ validated `scene.add`, `scene.patch`, `asset.patch`, `plan.complete`, or
 snapshots, and checksums. Generated HTML, React, JavaScript, CSS, component
 source, audio events, protocol envelopes, and unknown part types are rejected.
 
+A planner may add `placement: "closer"` to exactly one `scene.add`. The
+standard handler requires that closer by default, holds it outside the public
+event stream while body scenes continue, and commits it as the final scene.
+Only templates advertised for `jobs:[ask]` or `jobs:[payoff]` qualify. The
+placement marker is not part of `VideoScene` and never enters a replay
+snapshot. If the planner completes without a valid closer, the handler emits
+`plan_missing_closer` and uses `finishReason: "other"`; provider `length` and
+`content-filter` reasons remain unchanged.
+
 ## Resume
 
 A resume request repeats the public input and includes:

package/examples/nextjs-quickstart/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.42",
-    "@vanillaskyai/video": "0.1.1",
+    "@vanillaskyai/video": "0.2.0",
     "ai": "^7.0.66",
     "next": "16.3.1",
     "react": "19.2.8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Open-source video response SDK for personalized AI applications.",
   "keywords": [
     "generative-video",