@vanillaskyai/video 0.1.1 → 0.3.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-XYZOJ5NZ.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,13 @@ import {
   VIDEO_PROTOCOL_VERSION
 } from "./chunk-EE6PK6XC.js";
 import {
-  createTemplateSystemPrompt
-} from "./chunk-YC5MFXA5.js";
-import {
-  DEFAULT_VIDEO_SYSTEM_PROMPT
-} from "./chunk-FQ47WXAJ.js";
-import "./chunk-EVG2ZYIY.js";
+  createTemplateSystemPrompt,
+  getStandardMediaResolverContract
+} from "./chunk-GR4I3MN2.js";
+import "./chunk-WHPZED7X.js";
+import "./chunk-3O7OMMMF.js";
 import "./chunk-352ZZCET.js";
-import "./chunk-CHLGW22F.js";
+import "./chunk-XAMUOSX7.js";
 import "./chunk-2E6T633S.js";
 import {
   validateBrandInput
@@ -130,6 +129,7 @@ function parseVideoRequest(value) {
   const input = record(request.input, "request.input");
   allowedKeys(input, [
     "input",
+    "knowledgeMode",
     "instructions",
     "maxDurationSec",
     "orientation",
@@ -141,6 +141,14 @@ function parseVideoRequest(value) {
     "audio"
   ], "request.input");
   string(input.input, "request.input.input");
+  if (input.knowledgeMode != null) {
+    enumValue(
+      input.knowledgeMode,
+      ["input-only", "general"],
+      "input-only or general",
+      "request.input.knowledgeMode"
+    );
+  }
   if (input.instructions != null) string(input.instructions, "request.input.instructions");
   if (input.maxDurationSec != null) {
     numberBetween(input.maxDurationSec, 5, 120, "request.input.maxDurationSec");
@@ -397,10 +405,11 @@ 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,
-          systemPrompt: systemPrompt ?? DEFAULT_VIDEO_SYSTEM_PROMPT,
+          systemPrompt,
           selectAudio: options.selectAudio,
           snapshotRetention: options.snapshotRetention,
           signal: request.signal,
@@ -459,6 +468,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 +631,51 @@ 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 }),
-    systemPrompt: ({ capabilities: capabilities2 }) => {
+    requireCloser,
+    generate: createMediaResolvingPlanner({
+      planner,
+      templates,
+      resolveMedia,
+      approveUrl,
+      isOpeningReady: (input) => openingReadyInputs.has(input)
+    }),
+    systemPrompt: ({ request, 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,
+        knowledgeMode: request.input.knowledgeMode,
+        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-NMYHLAMJ.js

@@ -0,0 +1,10 @@
+import {
+  DEFAULT_VIDEO_SYSTEM_PROMPT,
+  VIDEO_PLAN_INSTRUCTION,
+  createVideoSystemPrompt
+} from "./chunk-WHPZED7X.js";
+export {
+  DEFAULT_VIDEO_SYSTEM_PROMPT,
+  VIDEO_PLAN_INSTRUCTION,
+  createVideoSystemPrompt
+};

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-DA2cfJ96.js';
+export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-DA2cfJ96.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-CkO2EYr4.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 { g as VideoScene, f as VideoOrientation, h as VideoStyle, V as Video, a as VideoAudio, d as VideoInput } from './types-CkO2EYr4.js';
+import { a as VideoWarning, b as VideoFinishReason } from './events-CTIsANzz.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-TQOHDXNW.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-CkO2EYr4.d.ts}

@@ -1,6 +1,7 @@
 declare const VIDEO_PROTOCOL_VERSION: "0.4";
 declare const VIDEO_SCHEMA_VERSION: "0.1";
 type VideoOrientation = "portrait" | "landscape";
+type VideoKnowledgeMode = "input-only" | "general";
 interface VideoBrandColors {
     primary: string;
     secondary: string;
@@ -114,15 +115,17 @@ interface VideoSuppliedMedia {
     role?: "product" | "proof" | "background" | "logo";
 }
 interface VideoInput {
-    /** Raw factual boundary: news, product updates, metrics, or an assistant answer. */
+    /** Raw source, request, or question for the video. */
     input: string;
-    /** Optional creative direction. It never expands the factual boundary. */
+    /** Keep claims source-grounded by default, or allow stable model knowledge. */
+    knowledgeMode?: VideoKnowledgeMode;
+    /** Optional creative direction. It never changes the knowledge mode. */
     instructions?: string;
     maxDurationSec?: number;
     orientation?: VideoOrientation;
     /** Optional global visual direction. Omit for VanillaSky defaults. */
     style?: VideoStyleOptions;
-    /** Optional deterministic opening copy. Scene details are inferred. */
+    /** Optional custom opening copy. Omit for the deterministic "Creating your video..." fallback. */
     opening?: string;
     brand?: VideoBrandInput;
     /** Viewer or account context that may appear verbatim. It is data, never instructions. */
@@ -159,6 +162,7 @@ interface VideoGenerationContext {
 }
 type VideoPlanPart = {
     type: "scene.add";
+    placement?: "closer";
     scene: VideoScene;
 } | {
     type: "scene.patch";
@@ -205,4 +209,4 @@ interface VideoSnapshotRetention {
     suppliedMediaUrls?: boolean;
 }
 
-export { type Video as V, type VideoAudio as a, type VideoBackground as b, type VideoBrand as c, type VideoInput as d, type VideoOrientation as e, type VideoScene as f, type VideoStyle as g, type VideoStyleOptions as h, type VideoSuppliedMedia as i, type VideoCapabilities as j, VIDEO_PROTOCOL_VERSION as k, type VideoGenerationContext as l, type VideoPlanner as m, type VideoRequest as n, type VideoSceneValidator as o, type VideoTemplatePacing as p, type VideoSnapshotRetention as q, type VideoResumeCursor as r, type VideoSceneValidationContext as s };
+export { type Video as V, type VideoAudio as a, type VideoBackground as b, type VideoBrand as c, type VideoInput as d, type VideoKnowledgeMode as e, type VideoOrientation as f, type VideoScene as g, type VideoStyle as h, type VideoStyleOptions as i, type VideoSuppliedMedia as j, type VideoCapabilities as k, VIDEO_PROTOCOL_VERSION as l, type VideoGenerationContext as m, type VideoPlanner as n, type VideoRequest as o, type VideoSceneValidator as p, type VideoTemplatePacing as q, type VideoSnapshotRetention as r, type VideoResumeCursor as s, type VideoSceneValidationContext as t };

package/docs/concepts.md

@@ -21,8 +21,11 @@ or export pipeline when an encoded file is required.
   curated set of articles, metrics, events, notes, or an AI answer. It may be
   short, but the planner is designed to distill larger sources into a concise
   video rather than represent every fact;
+- `knowledgeMode`: `input-only` by default, or `general` when stable model
+  knowledge may supplement the request;
 - `instructions`: optional creative direction that cannot override facts;
-- `opening`: optional copy for a deterministic opening that can play immediately;
+- `opening`: optional custom copy for the deterministic opening; omission uses
+  `Creating your video...`;
 - `personalization`: application-defined fields such as name, role, account,
   period, goal, or onboarding partner;
 - `brand`: an optional background preset plus name, logo, font, surfaces, and
@@ -54,6 +57,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 +82,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

@@ -83,6 +83,8 @@ The file created by `vanillasky create` is a complete working template. Keep
 these concerns together:
 
 - `useWhen` and `avoidWhen` tell the AI when the visual is appropriate;
+- `jobs` declares the narrative roles the template can fill, and decides
+  whether it may close a video;
 - `schema` defines allowed variables, validation, defaults, labels, and
   grounding formats;
 - named `examples` provide complete deterministic preview values;
@@ -90,6 +92,31 @@ these concerns together:
 - raw `progress`, dimensions, and `safeZone` make semantic state deterministic
   and layout safe in portrait and landscape.
 
+### Which templates may close a video
+
+Every complete plan ends on exactly one closer, and the runtime only accepts a
+closer whose `jobs` include `"ask"` or `"payoff"`. Marking any other template as
+the closer rejects that scene with `Scene template <id> cannot be used as a
+closer`, and the reserved closing time is given to a template that qualifies.
+
+Declare `jobs: ["ask"]` on a call to action and `jobs: ["payoff"]` on a
+celebration or resolution beat. A template that only presents evidence keeps
+`jobs: ["proof"]` and is never asked to close.
+
+The same rule reads the built-in catalog, so an application that wants to
+constrain how its videos end can compute the eligible IDs instead of guessing:
+
+```ts
+import { builtinTemplates } from "@vanillaskyai/video/templates/catalog";
+
+const closerTemplateIds = builtinTemplates
+  .filter((template) => template.jobs.some((job) => job === "ask" || job === "payoff"))
+  .map((template) => template.id);
+```
+
+Pacing uses the same signal: the planner reserves time for the closer whenever
+the selected catalog contains a template with one of those two jobs.
+
 Customer templates hard-cut by default. Opt into renderer-owned fades only
 for scenes that use the standard media-background variables, and only after
 both timing points are visually tested in portrait and landscape. Shared brand
@@ -194,7 +221,7 @@ import { templates } from "../vanillasky/server";
 export const handleVideo = createVideoHandler({
   templates,
   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";
   },
@@ -207,8 +234,9 @@ export const handleVideo = createVideoHandler({
 });
 ```
 
-The local-only authorization above is intentionally narrow. Replace it with
-your application's session check before deployment, as shown in
+The local-only authorization above is intentionally narrow. Supply its marker
+only from the development command; replace it with your application's session
+check before deployment, as shown in
 [Getting started](getting-started.md).
 
 Use the browser registry for generation and playback:
@@ -311,9 +339,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/customization.md

@@ -76,7 +76,8 @@ appear in the story.
 first validated scene arrives. The cover is player state, not video content: it
 is never written to the event log, replay, or export.
 
-An optional opening is deterministic and should not wait for an LLM or remote media:
+The opening is deterministic and should not wait for an LLM or remote media.
+Omit it to use `Creating your video...`, or supply one concise custom sentence:
 
 ```ts
 opening: "Joris, your Q2 recap is ready."

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.3.0 ai @ai-sdk/openai
 ```
 
 Set your provider key in `.env.local` (never commit it):
@@ -29,7 +29,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";
   },
@@ -45,11 +45,12 @@ export const POST = handle;
 export const OPTIONS = handle;
 ```
 
-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,
+The local bypass is intentionally fail-closed: the packaged development command
+sets its marker only for `next dev`, and it accepts only localhost. Every
+production request is denied. 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.3.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 +91,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

@@ -9,6 +9,7 @@ import type { VideoInput } from "@vanillaskyai/video";
 
 const input: VideoInput = {
   input: "Joris completed 142 customer conversations in Q2.",
+  knowledgeMode: "input-only",
   instructions: "Celebrate the result. Never alter a metric.",
   opening: "Joris, your Q2 recap is ready.",
   personalization: { firstName: "Joris", period: "Q2" },
@@ -22,20 +23,30 @@ const input: VideoInput = {
 
 ## Raw source
 
-Put every fact the response may claim in `input`. Use plain text, compact JSON, or a server-produced digest. Include units, periods, comparison bases, and provenance identifiers where ambiguity is possible. Keep creative direction in `instructions`; it may change emphasis and tone but cannot expand the factual boundary.
+In the default `input-only` mode, put every fact the response may claim in
+`input`. Use plain text, compact JSON, or a server-produced digest. Include
+units, periods, comparison bases, and provenance identifiers where ambiguity
+is possible. Choose `knowledgeMode: "general"` only when the model should use
+stable general knowledge to answer a question or develop content. Creative
+direction in `instructions` never changes that setting.
 
 Bound request bytes and reject secret-shaped fields on the server. Do not pass provider keys, authorization headers, internal prompt fragments, or storage credentials as source material.
 
 ## 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:
+`opening` becomes a deterministic `media` scene emitted before provider work.
+When callers omit it, the SDK uses `Creating your video...`; a supplied value
+replaces that fallback. The scene contains only that 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
+optional custom copy. That copy 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.
+The opening is runtime-owned, so it remains available even when `templateIds`
+does not let the planner select `media` for generated body scenes.