@vanillaskyai/video 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.3.1
+
+- Redesigns player controls for each playback state with responsive circular
+  icon controls, a sound-first start action, and a dimmed replay treatment that
+  leaves the completed poster frame visible.
+- Lets applications pass `opening: false` to omit the deterministic opening
+  scene and render their own transient loading UI while the first generated
+  scene is planned. This keeps loading state out of completed video JSON and
+  does not force `media` into the planner's template capabilities.
+
 ## 0.3.0
 
 - Documents closer eligibility: a template may close a video only when its

package/PUBLIC-API.md

@@ -183,6 +183,10 @@ mounted player autoplay with sound after the first successful viewer start.
 `manual`, `muted-autoplay`, and `autoplay-with-sound` cover the other browser
 startup policies.
 
+`VideoInput.opening` accepts custom copy, uses the deterministic fallback when
+omitted, and accepts `false` when the application owns transient loading UI and
+wants the completed video to begin with the first generated scene.
+
 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.3.0 beta](https://img.shields.io/badge/version-0.3.0_beta-7c3aed)
+![Version 0.3.1 beta](https://img.shields.io/badge/version-0.3.1_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.3.0 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.3.1 ai @ai-sdk/openai
 ```
 
 For coding agents:
@@ -106,7 +106,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.3.0/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart`](https://github.com/VanillaSkyAi/video/tree/v0.3.1/examples/nextjs-quickstart).
 
 ## Shape the response
 

package/dist/{chunk-XYZOJ5NZ.js → chunk-LHFADNWJ.js}

@@ -97,7 +97,7 @@ function buildVideoUserPrompt(input, openingDurationSec = 0) {
     "Compose a video response from the structured customer input below.",
     `Knowledge mode: ${input.knowledgeMode ?? "input-only"}.`,
     `Maximum duration: ${input.maxDurationSec ?? 30} seconds, including the supplied opening.`,
-    input.opening?.trim() ? `The host has already added the opening scene, which consumes ${openingDurationSec} seconds. Continue after it and do not repeat or rewrite it.` : "Add the first grounded scene as soon as it is complete.",
+    typeof input.opening === "string" && input.opening.trim() ? `The host has already added the opening scene, which consumes ${openingDurationSec} seconds. Continue after it and do not repeat or rewrite it.` : "Add the first grounded scene as soon as it is complete.",
     "The first generated body scene must be fully playable without external media. Use a content-fit text, data, comparison, list, or device-free template with no media URL or keyword.",
     "Never use media, ctaMedia, or reaction as the first generated body template, even with mediaType=gradient. Choose a non-media template first.",
     "Add that scene before resolving any stock or supplied asset. Media belongs on later body scenes and must arrive without blocking scene additions.",
@@ -139,10 +139,11 @@ var DEFAULT_OPENING_TEXT = "Creating your video...";
 function resolveVideoInput(input) {
   return {
     ...input,
-    opening: input.opening?.trim() || DEFAULT_OPENING_TEXT
+    opening: input.opening === false ? false : input.opening?.trim() || DEFAULT_OPENING_TEXT
   };
 }
-function resolveStreamCapabilities(capabilities) {
+function resolveStreamCapabilities(capabilities, hasRuntimeOpening) {
+  if (!hasRuntimeOpening) return capabilities;
   if (capabilities?.templates == null) return capabilities;
   return {
     ...capabilities,
@@ -174,7 +175,7 @@ function safeAbortReason(value) {
   return safePublicDiagnostic(value instanceof Error ? value.message : value, "Request aborted");
 }
 function buildInitialConfig(input, audio, snapshotRetention, closerReserveSec, getTemplatePacing) {
-  const openingText = input.opening?.trim();
+  const openingText = typeof input.opening === "string" ? input.opening.trim() : void 0;
   const rawScenes = openingText ? [{
     id: "supplied-opening",
     templateId: "media",
@@ -238,7 +239,7 @@ function validateInput(input) {
   if (input.maxDurationSec != null && (!Number.isFinite(input.maxDurationSec) || input.maxDurationSec < 5 || input.maxDurationSec > 120)) {
     throw new Error("Video response maximum duration must be between 5 and 120 seconds");
   }
-  if (input.opening != null && !input.opening.trim()) {
+  if (input.opening !== false && input.opening != null && !input.opening.trim()) {
     throw new Error("Video response opening must be a non-empty string");
   }
   if (input.audio && !input.audio.src.trim()) {
@@ -331,7 +332,7 @@ function createSceneQualityWarnings(scene) {
 }
 function createVideo(rawInput, options) {
   validateInput(rawInput);
-  const usesDefaultOpening = rawInput.opening == null;
+  const requiresGeneratedScene = rawInput.opening == null || rawInput.opening === false;
   const input = resolveVideoInput(rawInput);
   const requestId = options.requestId ?? createId("request");
   const runId = options.runId ?? createId("run");
@@ -446,7 +447,7 @@ function createVideo(rawInput, options) {
         format: { orientation: initialConfig.orientation ?? "portrait" },
         style: initialConfig.style,
         meta: initialConfig.meta,
-        capabilities: resolveStreamCapabilities(options.capabilities)
+        capabilities: resolveStreamCapabilities(options.capabilities, initialConfig.scenes.length > 0)
       }));
       if (initialConfig.audio) yield emit(events.create("audio.set", { audio: initialConfig.audio }));
       for (const warning of initial.warnings) {
@@ -784,7 +785,7 @@ function createVideo(rawInput, options) {
           warning: createIncompletePlanWarning()
         }));
       }
-      if (generatedSceneCount === 0 && usesDefaultOpening) {
+      if (generatedSceneCount === 0 && requiresGeneratedScene) {
         throw new Error("The planner completed without adding a scene");
       }
       const snapshot = parseVideo(state.config);

package/dist/{compose-video-TQOHDXNW.js → compose-video-6UQ33DOO.js}

@@ -1,6 +1,6 @@
 import {
   createVideo
-} from "./chunk-XYZOJ5NZ.js";
+} from "./chunk-LHFADNWJ.js";
 import "./chunk-E7CL7UPB.js";
 import "./chunk-STIFILQG.js";
 import "./chunk-JW47XCRL.js";

package/dist/{events-CTIsANzz.d.ts → events-tQ0x-VaL.d.ts}

@@ -1,4 +1,4 @@
-import { f as VideoOrientation, h as VideoStyle, V as Video, k as VideoCapabilities, a as VideoAudio, g as VideoScene, l as VIDEO_PROTOCOL_VERSION } from './types-CkO2EYr4.js';
+import { f as VideoOrientation, h as VideoStyle, V as Video, k as VideoCapabilities, a as VideoAudio, g as VideoScene, l as VIDEO_PROTOCOL_VERSION } from './types-CVMb6QEq.js';
 
 type VideoWarningCategory = "validation" | "readability" | "grounding" | "provider" | "media" | "protocol";
 type VideoWarningCode = "scene_duration_adjusted" | "scene_omitted_unreadable" | "scene_omitted_for_closer" | "scene_patch_rejected_readability" | "chart_scale_imbalance" | "plan_incomplete" | "plan_missing_closer" | "provider_warning" | "provider_diagnostics_unavailable";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { V as Video } from './types-CkO2EYr4.js';
-export { a as VideoAudio, b as VideoBackground, c as VideoBrand, d as VideoInput, e as VideoKnowledgeMode, f as VideoOrientation, g as VideoScene, h as VideoStyle, i as VideoStyleOptions, j as VideoSuppliedMedia } from './types-CkO2EYr4.js';
+import { V as Video } from './types-CVMb6QEq.js';
+export { a as VideoAudio, b as VideoBackground, c as VideoBrand, d as VideoInput, e as VideoKnowledgeMode, f as VideoOrientation, g as VideoScene, h as VideoStyle, i as VideoStyleOptions, j as VideoSuppliedMedia } from './types-CVMb6QEq.js';
 export { V as VideoStatus } from './state-DZcKuS32.js';
 
 type VideoValidationErrorCode = "invalid_video" | "unsupported_video_version";

package/dist/{kit-DA2cfJ96.d.ts → kit-DlUSg8lA.d.ts}

@@ -1,4 +1,4 @@
-import { h as VideoStyle, k as VideoCapabilities } from './types-CkO2EYr4.js';
+import { h as VideoStyle, k as VideoCapabilities } from './types-CVMb6QEq.js';
 import { ComponentType } from 'react';
 import { S as SceneTemplateMetadata, d as TemplateJsonSchema, f as TemplateJsonSchemaProperty } from './catalog-types-BIhSpOWK.js';
 

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import { CSSProperties, ReactElement } from 'react';
-import { V as VideoEvent, a as VideoWarning } from './events-CTIsANzz.js';
-import { f as VideoOrientation, V as Video, d as VideoInput } from './types-CkO2EYr4.js';
-import { T as TemplateRegistry } from './kit-DA2cfJ96.js';
+import { V as VideoEvent, a as VideoWarning } from './events-tQ0x-VaL.js';
+import { f as VideoOrientation, V as Video, d as VideoInput } from './types-CVMb6QEq.js';
+import { T as TemplateRegistry } from './kit-DlUSg8lA.js';
 import { V as VideoStatus } from './state-DZcKuS32.js';
 import './catalog-types-BIhSpOWK.js';
 

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 { 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-CkO2EYr4.js';
-import { b as VideoFinishReason, a as VideoWarning, V as VideoEvent } from './events-CTIsANzz.js';
-export { c as VideoWarningCategory } from './events-CTIsANzz.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-XYZOJ5NZ.js";
+} from "./chunk-LHFADNWJ.js";
 import "./chunk-E7CL7UPB.js";
 import {
   BUILTIN_SERVER_TEMPLATE_KIT,
@@ -161,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");

package/dist/templates.d.ts

@@ -1,9 +1,9 @@
-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 { 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-CkO2EYr4.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 { 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';
+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-TQOHDXNW.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-CkO2EYr4.d.ts → types-CVMb6QEq.d.ts}

@@ -125,8 +125,8 @@ interface VideoInput {
     orientation?: VideoOrientation;
     /** Optional global visual direction. Omit for VanillaSky defaults. */
     style?: VideoStyleOptions;
-    /** Optional custom opening copy. Omit for the deterministic "Creating your video..." fallback. */
-    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>;

package/docs/concepts.md

@@ -25,7 +25,8 @@ or export pipeline when an encoded file is required.
   knowledge may supplement the request;
 - `instructions`: optional creative direction that cannot override facts;
 - `opening`: optional custom copy for the deterministic opening; omission uses
-  `Creating your video...`;
+  `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/customization.md

@@ -80,12 +80,15 @@ 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.3.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):
@@ -50,7 +50,7 @@ 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.3.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,11 +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" },
@@ -48,5 +48,17 @@ optional custom copy. That copy 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.
 
-The opening is runtime-owned, so it remains available even when `templateIds`
+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.

package/docs/integrate-nextjs.md

@@ -5,7 +5,7 @@
 Install VanillaSky and one AI SDK provider:
 
 ```bash
-npm install @vanillaskyai/video@0.3.0 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.3.1 ai @ai-sdk/openai
 ```
 
 Create an ignored `.env.local`:
@@ -74,7 +74,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.3.0/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.3.1/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

@@ -81,7 +81,11 @@ 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.
+mode is set. For a chat response that should try audible autoplay without the
+SDK generation intro, pass `opening: false`, wait to mount the player until a
+generated scene exists, and render it with `autoPlay` and `startMuted={false}`.
+If the browser blocks the audible start, the player returns to the first frame
+and exposes its sound-start control.
 
 ## Media providers
 

package/docs/prompt-and-input.md

@@ -121,7 +121,8 @@ streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
 `userPrompt` is assembled by VanillaSky from:
 
 - orientation and maximum duration;
-- whether an opening scene already exists;
+- whether a deterministic opening scene already exists or the host is waiting
+  for the first generated scene;
 - raw `input`;
 - creative `instructions`;
 - personalization;
@@ -159,7 +160,7 @@ video.generate({
     escalationsResolved: "96%",
     improvementsLaunched: 4,
   }),
-  personalization: { firstName: "Joris" },
+  personalization: { role: "Product leader", focus: "activation" },
 });
 ```
 

package/examples/nextjs-quickstart/package.json

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

package/package.json

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