@vanillaskyai/video 0.2.0 → 0.3.1

package/dist/react.js

@@ -152,6 +152,51 @@ function savedVideoState(video) {
     config: video
   };
 }
+function PlayerIcon({ name, size = 22 }) {
+  const shared = {
+    width: size,
+    height: size,
+    viewBox: "0 0 24 24",
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: 2,
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+    "aria-hidden": true,
+    focusable: false
+  };
+  if (name === "play") {
+    return /* @__PURE__ */ jsx("svg", { ...shared, children: /* @__PURE__ */ jsx("path", { d: "M8 5v14l11-7z", fill: "currentColor", stroke: "none" }) });
+  }
+  if (name === "pause") {
+    return /* @__PURE__ */ jsxs("svg", { ...shared, children: [
+      /* @__PURE__ */ jsx("rect", { x: "7", y: "5", width: "3.5", height: "14", rx: "1", fill: "currentColor", stroke: "none" }),
+      /* @__PURE__ */ jsx("rect", { x: "13.5", y: "5", width: "3.5", height: "14", rx: "1", fill: "currentColor", stroke: "none" })
+    ] });
+  }
+  if (name === "replay") {
+    return /* @__PURE__ */ jsxs("svg", { ...shared, children: [
+      /* @__PURE__ */ jsx("path", { d: "M4.5 9A8 8 0 1 1 5 16" }),
+      /* @__PURE__ */ jsx("path", { d: "M4.5 4.5V9H9" })
+    ] });
+  }
+  if (name === "volume-off") {
+    return /* @__PURE__ */ jsxs("svg", { ...shared, children: [
+      /* @__PURE__ */ jsx("path", { d: "M11 5 6.5 9H3v6h3.5L11 19z" }),
+      /* @__PURE__ */ jsx("path", { d: "m16 9 5 5M21 9l-5 5" })
+    ] });
+  }
+  if (name === "volume") {
+    return /* @__PURE__ */ jsxs("svg", { ...shared, children: [
+      /* @__PURE__ */ jsx("path", { d: "M11 5 6.5 9H3v6h3.5L11 19z" }),
+      /* @__PURE__ */ jsx("path", { d: "M15 9.5a4 4 0 0 1 0 5M17.8 7a7.5 7.5 0 0 1 0 10" })
+    ] });
+  }
+  if (name === "exit-fullscreen") {
+    return /* @__PURE__ */ jsx("svg", { ...shared, children: /* @__PURE__ */ jsx("path", { d: "M9 4v5H4M15 4v5h5M9 20v-5H4M15 20v-5h5" }) });
+  }
+  return /* @__PURE__ */ jsx("svg", { ...shared, children: /* @__PURE__ */ jsx("path", { d: "M8 3H3v5M16 3h5v5M8 21H3v-5M16 21h5v-5" }) });
+}
 function VideoPlayerRuntime({
   kit,
   stream,
@@ -469,33 +514,38 @@ function VideoPlayerRuntime({
     if (document.fullscreenElement === container) await document.exitFullscreen?.();
     else await container.requestFullscreen?.();
   };
+  const controlSize = Math.max(40, Math.min(52, Math.round(displayWidth * 0.15)));
+  const controlInset = Math.max(10, Math.min(20, Math.round(displayWidth * 0.056)));
   const controlButtonStyle = {
     display: "inline-grid",
     placeItems: "center",
     flex: "0 0 auto",
-    minWidth: 44,
-    minHeight: 44,
-    padding: "6px 9px",
-    border: 0,
-    borderRadius: 8,
-    backgroundColor: "rgba(9, 7, 18, 0.88)",
+    width: controlSize,
+    height: controlSize,
+    minWidth: controlSize,
+    minHeight: controlSize,
+    padding: 0,
+    border: "1px solid rgba(255, 255, 255, 0.08)",
+    borderRadius: 999,
+    backgroundColor: "rgba(255, 255, 255, 0.16)",
     color: "#ffffff",
-    font: "600 13px/1 system-ui, sans-serif",
+    boxShadow: "0 5px 18px rgba(0, 0, 0, 0.16)",
+    backdropFilter: "blur(12px)",
     cursor: "pointer"
   };
   const startButtonStyle = {
     display: "inline-flex",
     alignItems: "center",
     gap: 10,
-    minHeight: 54,
-    padding: "12px 18px",
-    border: "1px solid rgba(255, 255, 255, 0.3)",
+    minHeight: 60,
+    padding: "14px 22px",
+    border: "1px solid rgba(9, 7, 18, 0.08)",
     borderRadius: 999,
-    backgroundColor: "rgba(9, 7, 18, 0.88)",
-    color: "#ffffff",
-    boxShadow: "0 8px 28px rgba(0, 0, 0, 0.4)",
-    backdropFilter: "blur(12px)",
-    font: "700 15px/1 system-ui, sans-serif",
+    backgroundColor: "#ffffff",
+    color: "#090712",
+    boxShadow: "0 8px 28px rgba(0, 0, 0, 0.24)",
+    font: "700 16px/1 system-ui, sans-serif",
+    whiteSpace: "nowrap",
     cursor: "pointer"
   };
   const startButtonPositionStyle = {
@@ -579,7 +629,7 @@ function VideoPlayerRuntime({
                   onClick: armPlayback,
                   style: { ...startButtonStyle, ...startButtonPositionStyle },
                   children: [
-                    /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\u25B6" }),
+                    /* @__PURE__ */ jsx(PlayerIcon, { name: "play", size: 20 }),
                     config?.audio && !isMuted ? "Play with sound" : "Play video"
                   ]
                 }
@@ -615,7 +665,7 @@ function VideoPlayerRuntime({
               ...startButtonPositionStyle
             },
             children: [
-              /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\u25B6" }),
+              /* @__PURE__ */ jsx(PlayerIcon, { name: "play", size: 20 }),
               config?.audio && !isMuted ? "Play with sound" : "Play video"
             ]
           }
@@ -631,60 +681,99 @@ function VideoPlayerRuntime({
             loop: state.status === "streaming" || introPlaying
           }
         ) : null,
-        !generationCoverVisible ? /* @__PURE__ */ jsxs(
+        ended ? /* @__PURE__ */ jsx(
+          "div",
+          {
+            "data-testid": "video-ended-scrim",
+            "aria-hidden": "true",
+            style: {
+              position: "absolute",
+              inset: 0,
+              zIndex: 1,
+              pointerEvents: "none",
+              background: "rgba(4, 3, 18, 0.52)",
+              backdropFilter: "blur(4px)"
+            }
+          }
+        ) : null,
+        ended ? /* @__PURE__ */ jsxs(
+          "button",
+          {
+            type: "button",
+            "data-testid": "video-replay-button",
+            "aria-label": "Replay video response",
+            onClick: togglePlayback,
+            style: {
+              ...startButtonStyle,
+              ...startButtonPositionStyle,
+              zIndex: 3
+            },
+            children: [
+              /* @__PURE__ */ jsx(PlayerIcon, { name: "replay", size: 21 }),
+              "Replay"
+            ]
+          }
+        ) : null,
+        !generationCoverVisible && !showStartPoster && config?.scenes.length ? /* @__PURE__ */ jsxs(
           "div",
           {
             "data-testid": "video-controls",
+            "data-layout": "split",
             style: {
               position: "absolute",
-              right: 10,
-              bottom: 10,
-              zIndex: 2,
-              display: "flex",
-              alignItems: "center",
-              gap: 6,
-              minHeight: 48,
-              padding: "6px 8px",
-              border: "1px solid rgba(255, 255, 255, 0.2)",
-              borderRadius: 12,
-              backgroundColor: "rgba(9, 7, 18, 0.82)",
-              backdropFilter: "blur(12px)",
-              color: "#ffffff",
-              boxShadow: "0 4px 20px rgba(0, 0, 0, 0.35)"
+              inset: 0,
+              zIndex: 4,
+              pointerEvents: "none"
             },
             children: [
-              !showStartPoster ? /* @__PURE__ */ jsx(
-                "button",
-                {
-                  type: "button",
-                  "aria-label": ended ? "Replay video response" : isPlaying ? "Pause video response" : "Play video response",
-                  onClick: togglePlayback,
-                  style: controlButtonStyle,
-                  children: ended ? "\u21BB Replay" : isPlaying ? "\u2161" : "\u25B6"
-                }
-              ) : null,
-              config?.audio ? /* @__PURE__ */ jsx(
-                "button",
+              /* @__PURE__ */ jsx(
+                "div",
                 {
-                  type: "button",
-                  "aria-label": isMuted ? "Unmute video response" : "Mute video response",
-                  "aria-pressed": !isMuted,
-                  onClick: () => setIsMuted((muted) => {
-                    if (muted) setAudioUnlocked(true);
-                    return !muted;
-                  }),
-                  style: controlButtonStyle,
-                  children: isMuted ? "\u{1F507}" : "\u{1F50A}"
+                  "data-testid": "video-primary-controls",
+                  style: { position: "absolute", left: controlInset, bottom: controlInset, display: "flex", pointerEvents: "auto" },
+                  children: /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      type: "button",
+                      "aria-label": ended ? "Play video response from beginning" : isPlaying ? "Pause video response" : "Play video response",
+                      onClick: togglePlayback,
+                      style: controlButtonStyle,
+                      children: /* @__PURE__ */ jsx(PlayerIcon, { name: isPlaying ? "pause" : "play" })
+                    }
+                  )
                 }
-              ) : null,
-              /* @__PURE__ */ jsx(
-                "button",
+              ),
+              /* @__PURE__ */ jsxs(
+                "div",
                 {
-                  type: "button",
-                  "aria-label": isFullscreen ? "Exit fullscreen" : "Enter fullscreen",
-                  onClick: () => void toggleFullscreen(),
-                  style: controlButtonStyle,
-                  children: isFullscreen ? "\u2199" : "\u26F6"
+                  "data-testid": "video-secondary-controls",
+                  style: { position: "absolute", right: controlInset, bottom: controlInset, display: "flex", gap: 10, pointerEvents: "auto" },
+                  children: [
+                    config?.audio ? /* @__PURE__ */ jsx(
+                      "button",
+                      {
+                        type: "button",
+                        "aria-label": isMuted ? "Unmute video response" : "Mute video response",
+                        "aria-pressed": !isMuted,
+                        onClick: () => setIsMuted((muted) => {
+                          if (muted) setAudioUnlocked(true);
+                          return !muted;
+                        }),
+                        style: controlButtonStyle,
+                        children: /* @__PURE__ */ jsx(PlayerIcon, { name: isMuted ? "volume-off" : "volume" })
+                      }
+                    ) : null,
+                    /* @__PURE__ */ jsx(
+                      "button",
+                      {
+                        type: "button",
+                        "aria-label": isFullscreen ? "Exit fullscreen" : "Enter fullscreen",
+                        onClick: () => void toggleFullscreen(),
+                        style: controlButtonStyle,
+                        children: /* @__PURE__ */ jsx(PlayerIcon, { name: isFullscreen ? "exit-fullscreen" : "enter-fullscreen" })
+                      }
+                    )
+                  ]
                 }
               )
             ]

package/dist/server.d.ts

@@ -1,6 +1,6 @@
-import { l as VideoGenerationContext, m as VideoPlanner, n as VideoRequest, j as VideoCapabilities, d as VideoInput, a as VideoAudio, o as VideoSceneValidator, p as VideoTemplatePacing, q as VideoSnapshotRetention, r as VideoResumeCursor, s as VideoSceneValidationContext, f as VideoScene } from './types-_t4bduwX.js';
-import { b as VideoFinishReason, a as VideoWarning, V as VideoEvent } from './events-B-28kERX.js';
-export { c as VideoWarningCategory } from './events-B-28kERX.js';
+import { m as VideoGenerationContext, n as VideoPlanner, o as VideoRequest, k as VideoCapabilities, d as VideoInput, a as VideoAudio, p as VideoSceneValidator, q as VideoTemplatePacing, r as VideoSnapshotRetention, s as VideoResumeCursor, t as VideoSceneValidationContext, g as VideoScene } from './types-CVMb6QEq.js';
+import { b as VideoFinishReason, a as VideoWarning, V as VideoEvent } from './events-tQ0x-VaL.js';
+export { c as VideoWarningCategory } from './events-tQ0x-VaL.js';
 import { S as SceneTemplateMetadata } from './catalog-types-BIhSpOWK.js';
 
 interface VideoProviderUsage {

package/dist/server.js

@@ -3,7 +3,7 @@ import {
 } from "./chunk-BKF3A357.js";
 import {
   createVideo
-} from "./chunk-TGFO454Q.js";
+} from "./chunk-LHFADNWJ.js";
 import "./chunk-E7CL7UPB.js";
 import {
   BUILTIN_SERVER_TEMPLATE_KIT,
@@ -31,10 +31,8 @@ import {
 import {
   createTemplateSystemPrompt,
   getStandardMediaResolverContract
-} from "./chunk-Q2DDQKEG.js";
-import {
-  DEFAULT_VIDEO_SYSTEM_PROMPT
-} from "./chunk-K5SRF7D3.js";
+} from "./chunk-GR4I3MN2.js";
+import "./chunk-WHPZED7X.js";
 import "./chunk-3O7OMMMF.js";
 import "./chunk-352ZZCET.js";
 import "./chunk-XAMUOSX7.js";
@@ -131,6 +129,7 @@ function parseVideoRequest(value) {
   const input = record(request.input, "request.input");
   allowedKeys(input, [
     "input",
+    "knowledgeMode",
     "instructions",
     "maxDurationSec",
     "orientation",
@@ -142,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");
@@ -154,7 +161,7 @@ function parseVideoRequest(value) {
       "request.input.orientation"
     );
   }
-  if (input.opening != null) string(input.opening, "request.input.opening");
+  if (input.opening != null && input.opening !== false) string(input.opening, "request.input.opening");
   if (input.audio != null && input.audio !== false) {
     const soundtrack = record(input.audio, "request.input.audio");
     allowedKeys(soundtrack, ["src"], "request.input.audio");
@@ -402,7 +409,7 @@ function createVideoStreamHandler(options) {
           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,
@@ -651,12 +658,13 @@ function createVideoHandler(options) {
       approveUrl,
       isOpeningReady: (input) => openingReadyInputs.has(input)
     }),
-    systemPrompt: ({ capabilities: capabilities2 }) => {
+    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,
+        knowledgeMode: request.input.knowledgeMode,
         mediaResolverAvailable: resolveMedia != null
       });
     },

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/templates.d.ts

@@ -1,9 +1,9 @@
-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 { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-DlUSg8lA.js';
+export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-DlUSg8lA.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-_t4bduwX.js';
+import './types-CVMb6QEq.js';
 
 interface TemplateExample<Variables extends Record<string, unknown> = Record<string, unknown>> {
     name: string;

package/dist/test.d.ts

@@ -1,5 +1,5 @@
-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';
+import { g as VideoScene, f as VideoOrientation, h as VideoStyle, V as Video, a as VideoAudio, d as VideoInput } from './types-CVMb6QEq.js';
+import { a as VideoWarning, b as VideoFinishReason } from './events-tQ0x-VaL.js';
 
 type MockVideoStreamPart = {
     type: "scene.add";

package/dist/test.js

@@ -233,7 +233,7 @@ 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-34GRZIF2.js");
+  const { createVideo } = await import("./compose-video-6UQ33DOO.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");

package/dist/{types-_t4bduwX.d.ts → types-CVMb6QEq.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,16 +115,18 @@ 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. */
-    opening?: string;
+    /** Custom opening copy, or false to let the host show loading UI instead. Omit for the deterministic fallback. */
+    opening?: string | false;
     brand?: VideoBrandInput;
     /** Viewer or account context that may appear verbatim. It is data, never instructions. */
     personalization?: Record<string, unknown>;
@@ -206,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,12 @@ 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...`, while `false` lets the host render loading UI
+  without adding an opening scene to the 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

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:

package/docs/customization.md

@@ -76,15 +76,19 @@ 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."
+opening: "Your Q2 customer impact recap is ready."
 ```
 
+Pass `opening: false` to omit the persisted opening and show application-owned
+loading UI until the first generated scene arrives.
+
 Use `opening` only for a genuine opening that should remain in the completed
-response. VanillaSky infers the scene ID, `notification` template, variables,
-and five-second timing. You do not need to create a generic loading scene.
+response. VanillaSky infers the scene ID, `media` template, gradient variables,
+and three-second timing. Keep generic loading state in the host UI instead.
 
 ## Aspect ratio and responsive layout
 

package/docs/getting-started.md

@@ -5,7 +5,7 @@
 Install VanillaSky:
 
 ```bash
-npm install @vanillaskyai/video@0.2.0 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.3.1 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.2.0/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.3.1/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

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

@@ -8,10 +8,11 @@
 import type { VideoInput } from "@vanillaskyai/video";
 
 const input: VideoInput = {
-  input: "Joris completed 142 customer conversations in Q2.",
+  input: "Maya 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" },
+  opening: "Maya, your Q2 customer impact recap is ready.",
+  personalization: { firstName: "Maya", period: "Q2", role: "Product leader" },
   brand,
   suppliedMedia,
   audio: { src: "/audio/calm.mp3" },
@@ -22,18 +23,24 @@ 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 `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:
+`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;
@@ -41,4 +48,17 @@ should:
 - 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.
+Pass `opening: false` when the application should own the waiting experience:
+
+```ts
+opening: false
+```
+
+The SDK then starts with an empty timeline and emits the first validated,
+generated scene as soon as it is ready. Render a transient loading state in the
+host application until `video.video?.scenes.length` is non-zero. That loading
+state is not persisted in the event stream or completed video. A generated
+scene is still required; a planner that completes without one fails the run.
+
+The deterministic opening is runtime-owned, so it remains available even when `templateIds`
+does not let the planner select `media` for generated body scenes.