@vanillaskyai/video 0.3.0 → 0.3.2

package/dist/{showcase-web-Y4W2HVRJ.js → showcase-web-LAKHYXSD.js}

@@ -2,19 +2,22 @@ import {
   ProductSurface,
   WebScreenFill,
   resolveProductSurfaceMotion
-} from "./chunk-FSG2PYWG.js";
+} from "./chunk-G5JPHBX7.js";
 import {
   stripPipe
 } from "./chunk-S7HFLYNN.js";
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-IFOW65Z6.js";
+} from "./chunk-4AODC6MS.js";
+import {
+  hasSceneMedia
+} from "./chunk-35LIYILY.js";
 import {
   TemplateText
-} from "./chunk-BCRUUJ6A.js";
+} from "./chunk-TCEHK2BW.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-ABZACD4G.js";
+import "./chunk-IJM4B2ZN.js";
 import {
   SPRING_SMOOTH,
   interpolate,
@@ -23,7 +26,7 @@ import {
 import {
   TOKEN_DEFAULTS,
   resolveTokens
-} from "./chunk-FNAEQ7QO.js";
+} from "./chunk-XWWLKRNU.js";
 
 // src/visual-system/primitives/devices/WebMockup.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -341,6 +344,7 @@ var ShowcaseWebTemplate = ({
         /* @__PURE__ */ jsx2(
           TemplateText,
           {
+            overMedia: hasSceneMedia(variables),
             motionProgress,
             typeTreatment: tokens.preset.type,
             archetype: textArchetype ?? "subtle",

package/dist/{social-milestone-XI2QE5BO.js → social-milestone-EOBEN7CX.js}

@@ -4,7 +4,8 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-IFOW65Z6.js";
+} from "./chunk-4AODC6MS.js";
+import "./chunk-35LIYILY.js";
 import {
   ConfettiLayer
 } from "./chunk-CJ7F2CE6.js";
@@ -16,7 +17,7 @@ import {
 import {
   accessibleTextColor,
   withOpacity
-} from "./chunk-ABZACD4G.js";
+} from "./chunk-IJM4B2ZN.js";
 import {
   SPRING_BOUNCY,
   SPRING_SMOOTH,
@@ -24,9 +25,10 @@ import {
   spring
 } from "./chunk-XTOXFMLM.js";
 import {
+  MEDIA_TEXT_SHADOW,
   TOKEN_DEFAULTS,
   resolveTokens
-} from "./chunk-FNAEQ7QO.js";
+} from "./chunk-XWWLKRNU.js";
 
 // src/visual-system/primitives/social/MilestoneBadge.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -60,7 +62,7 @@ var MilestoneBadge = ({
   const safeStart = startNumber != null && Number.isFinite(startNumber) ? startNumber : Math.max(0, Math.round(safeTarget * 0.98));
   const mainTextColor = hasMedia ? "#FFFFFF" : foreground;
   const pillTextColor = accessibleTextColor(surfaceElevated, foreground);
-  const mediaTextShadow = hasMedia ? "0 2px 8px rgba(0,0,0,0.55), 0 6px 16px rgba(0,0,0,0.35)" : void 0;
+  const mediaTextShadow = hasMedia ? MEDIA_TEXT_SHADOW : void 0;
   const followerCount = Math.round(
     interpolate(progress, [0.056, 0.556], [safeStart, safeTarget], CLAMP)
   );

package/dist/{social-notification-2UOHQCUY.js → social-notification-MELRWIB6.js}

@@ -4,12 +4,13 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-IFOW65Z6.js";
+} from "./chunk-4AODC6MS.js";
+import "./chunk-35LIYILY.js";
 import {
   Emoji,
   renderWithEmoji
 } from "./chunk-L5BTTCZV.js";
-import "./chunk-ABZACD4G.js";
+import "./chunk-IJM4B2ZN.js";
 import {
   SPRING_SMOOTH,
   interpolate,
@@ -17,7 +18,7 @@ import {
 } from "./chunk-XTOXFMLM.js";
 import {
   resolveTokens
-} from "./chunk-FNAEQ7QO.js";
+} from "./chunk-XWWLKRNU.js";
 
 // src/visual-system/primitives/social/NotificationCard.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{social-review-stack-FDYZGZTJ.js → social-review-stack-H3U437VT.js}

@@ -4,11 +4,12 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-IFOW65Z6.js";
+} from "./chunk-4AODC6MS.js";
+import "./chunk-35LIYILY.js";
 import {
   accessibleTextColor,
   withOpacity
-} from "./chunk-ABZACD4G.js";
+} from "./chunk-IJM4B2ZN.js";
 import {
   SPRING_SNAPPY,
   interpolate,
@@ -17,7 +18,7 @@ import {
 import {
   lighten,
   resolveTokens
-} from "./chunk-FNAEQ7QO.js";
+} from "./chunk-XWWLKRNU.js";
 
 // src/visual-system/primitives/social/ReviewStack.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{social-testimonial-OQ7N52GJ.js → social-testimonial-GNNMKMDD.js}

@@ -4,12 +4,13 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-IFOW65Z6.js";
+} from "./chunk-4AODC6MS.js";
+import "./chunk-35LIYILY.js";
 import {
   accessibleTextColor,
   autoTextColor,
   withOpacity
-} from "./chunk-ABZACD4G.js";
+} from "./chunk-IJM4B2ZN.js";
 import {
   SPRING_SMOOTH,
   SPRING_SNAPPY,
@@ -20,7 +21,7 @@ import {
   TOKEN_DEFAULTS,
   lighten,
   resolveTokens
-} from "./chunk-FNAEQ7QO.js";
+} from "./chunk-XWWLKRNU.js";
 
 // src/visual-system/primitives/social/TestimonialCard.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{social-tweet-5OLCNPPC.js → social-tweet-PBUKKPT3.js}

@@ -4,13 +4,14 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-IFOW65Z6.js";
+} from "./chunk-4AODC6MS.js";
+import "./chunk-35LIYILY.js";
 import {
   renderWithEmoji
 } from "./chunk-L5BTTCZV.js";
 import {
   autoTextColor
-} from "./chunk-ABZACD4G.js";
+} from "./chunk-IJM4B2ZN.js";
 import {
   SPRING_SMOOTH,
   interpolate,
@@ -18,7 +19,7 @@ import {
 } from "./chunk-XTOXFMLM.js";
 import {
   resolveTokens
-} from "./chunk-FNAEQ7QO.js";
+} from "./chunk-XWWLKRNU.js";
 
 // src/visual-system/primitives/social/TweetCard.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

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.2 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.2/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.2 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.2/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.2",
     "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.2",
   "description": "Open-source video response SDK for personalized AI applications.",
   "keywords": [
     "generative-video",