@vanillaskyai/video 0.5.8 → 0.6.0

package/dist/{infographic-steps-JDDEDI7X.js → infographic-steps-L7W24Z35.js}

@@ -8,14 +8,14 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   TemplateText
 } from "./chunk-TCEHK2BW.js";
 import {
   Emoji
 } from "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import {
   TOP_TEXT_AREA_RATIO,
   autoTextColor,
@@ -25,10 +25,10 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   resolveTokens

package/dist/{prompt-input-6ZWXEL3V.js → prompt-input-F3CYU2XH.js}

@@ -4,8 +4,8 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
-import "./chunk-HT6BGERF.js";
+} from "./chunk-7BGAU6C3.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   SPRING_BOUNCY,
@@ -13,8 +13,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   resolveTokens
 } from "./chunk-XWWLKRNU.js";

package/dist/react.d.ts

@@ -7,12 +7,18 @@ import './catalog-types-BIhSpOWK.js';
 
 type VideoPlaybackMode = "manual" | "muted-autoplay" | "autoplay-with-sound" | "autoplay-after-interaction";
 
+interface NativeMediaAudioOptions {
+    /** Volume of the active scene video's embedded audio, from 0 to 1. */
+    volume?: number;
+}
 interface VideoPlayerSharedProps {
     /** High-level startup policy. When set, this overrides autoPlay and startMuted. */
     playbackMode?: VideoPlaybackMode;
     /** Initial playback state. Reduced-motion preferences take precedence. */
     autoPlay?: boolean;
     startMuted?: boolean;
+    /** Play embedded audio from active scene videos as a layer beneath the master mute control. */
+    nativeMediaAudio?: NativeMediaAudioOptions;
     /** Fixed display width. Omit to observe and fill the parent width. */
     width?: number;
     /** Override the streamed orientation, or switch at the container breakpoint. */

package/dist/react.js

@@ -24,9 +24,9 @@ import {
 import {
   VideoFrame,
   getDimensions
-} from "./chunk-NGY3TNND.js";
-import "./chunk-C6WVCZRW.js";
+} from "./chunk-K746NUIP.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   fontStack
 } from "./chunk-XWWLKRNU.js";
@@ -79,34 +79,34 @@ import { createElement } from "react";
 
 // src/visual-system/catalog/builtin-loaders.generated.ts
 var GENERATED_BUILTIN_TEMPLATE_LOADERS = {
-  "media": () => import("./bg-media-FEBATBT2.js").then((module) => ({ default: module.BgMediaTemplate })),
-  "reaction": () => import("./reaction-Z3JIM3MQ.js").then((module) => ({ default: module.ReactionTemplate })),
+  "media": () => import("./bg-media-G4XOQEAS.js").then((module) => ({ default: module.BgMediaTemplate })),
+  "reaction": () => import("./reaction-2XCLOJOK.js").then((module) => ({ default: module.ReactionTemplate })),
   "confetti": () => import("./bg-confetti-SHQI7ATB.js").then((module) => ({ default: module.BgConfettiTemplate })),
   "emojiBurst": () => import("./bg-emoji-XYFRA63Q.js").then((module) => ({ default: module.BgEmojiTemplate })),
-  "bigNumber": () => import("./chart-counter-HFYNE4HT.js").then((module) => ({ default: module.ChartCounterTemplate })),
-  "barChart": () => import("./chart-bar-ZB45ZRKH.js").then((module) => ({ default: module.ChartBarTemplate })),
-  "progressRing": () => import("./chart-progress-ring-ZKMLRGSB.js").then((module) => ({ default: module.ChartProgressRingTemplate })),
-  "phoneMockup": () => import("./showcase-phone-5UW45ATT.js").then((module) => ({ default: module.ShowcasePhoneTemplate })),
-  "webMockup": () => import("./showcase-web-3AW6VHIG.js").then((module) => ({ default: module.ShowcaseWebTemplate })),
-  "codeEditor": () => import("./showcase-code-NWQAAJIA.js").then((module) => ({ default: module.ShowcaseCodeTemplate })),
-  "terminal": () => import("./showcase-terminal-UVOD25UF.js").then((module) => ({ default: module.ShowcaseTerminalTemplate })),
-  "tweet": () => import("./social-tweet-6JUM323G.js").then((module) => ({ default: module.SocialTweetTemplate })),
-  "notification": () => import("./social-notification-EDOU6TZB.js").then((module) => ({ default: module.SocialNotificationTemplate })),
+  "bigNumber": () => import("./chart-counter-KFPV44RB.js").then((module) => ({ default: module.ChartCounterTemplate })),
+  "barChart": () => import("./chart-bar-HRHD57ML.js").then((module) => ({ default: module.ChartBarTemplate })),
+  "progressRing": () => import("./chart-progress-ring-OR2VOIHV.js").then((module) => ({ default: module.ChartProgressRingTemplate })),
+  "phoneMockup": () => import("./showcase-phone-M4CEANIW.js").then((module) => ({ default: module.ShowcasePhoneTemplate })),
+  "webMockup": () => import("./showcase-web-TY6CZV2Z.js").then((module) => ({ default: module.ShowcaseWebTemplate })),
+  "codeEditor": () => import("./showcase-code-KHSMIPG6.js").then((module) => ({ default: module.ShowcaseCodeTemplate })),
+  "terminal": () => import("./showcase-terminal-26I3DYF7.js").then((module) => ({ default: module.ShowcaseTerminalTemplate })),
+  "tweet": () => import("./social-tweet-TK7SH2F6.js").then((module) => ({ default: module.SocialTweetTemplate })),
+  "notification": () => import("./social-notification-2RJDAZSF.js").then((module) => ({ default: module.SocialNotificationTemplate })),
   "chatMessenger": () => import("./social-conversation-75SD2637.js").then((module) => ({ default: module.SocialConversationTemplate })),
   "chatWhatsapp": () => import("./social-conversation-75SD2637.js").then((module) => ({ default: module.SocialConversationTemplate })),
-  "milestone": () => import("./social-milestone-KPKHFOB5.js").then((module) => ({ default: module.SocialMilestoneTemplate })),
-  "reviewStack": () => import("./social-review-stack-EZOO33SV.js").then((module) => ({ default: module.SocialReviewStackTemplate })),
-  "testimonial": () => import("./social-testimonial-DLOINMMY.js").then((module) => ({ default: module.SocialTestimonialTemplate })),
-  "incomingCall": () => import("./incoming-call-5IWJ2TAS.js").then((module) => ({ default: module.IncomingCallTemplate })),
-  "brandMessage": () => import("./brand-message-P56WEJPG.js").then((module) => ({ default: module.BrandMessageTemplate })),
-  "promptInput": () => import("./prompt-input-6ZWXEL3V.js").then((module) => ({ default: module.PromptInputTemplate })),
+  "milestone": () => import("./social-milestone-TF6MX7ET.js").then((module) => ({ default: module.SocialMilestoneTemplate })),
+  "reviewStack": () => import("./social-review-stack-2ICKJQG7.js").then((module) => ({ default: module.SocialReviewStackTemplate })),
+  "testimonial": () => import("./social-testimonial-X7OGADA3.js").then((module) => ({ default: module.SocialTestimonialTemplate })),
+  "incomingCall": () => import("./incoming-call-KXF67OT2.js").then((module) => ({ default: module.IncomingCallTemplate })),
+  "brandMessage": () => import("./brand-message-XHONEDNW.js").then((module) => ({ default: module.BrandMessageTemplate })),
+  "promptInput": () => import("./prompt-input-F3CYU2XH.js").then((module) => ({ default: module.PromptInputTemplate })),
   "beforeAfter": () => import("./infographic-before-after-2I7YZVDD.js").then((module) => ({ default: module.InfographicBeforeAfterTemplate })),
-  "tripleStats": () => import("./infographic-stat-row-XHUZZPDM.js").then((module) => ({ default: module.InfographicStatRowTemplate })),
-  "problemSolution": () => import("./infographic-problem-solution-IW35S6BR.js").then((module) => ({ default: module.InfographicProblemSolutionTemplate })),
-  "cardList": () => import("./infographic-feature-list-7SK65U3K.js").then((module) => ({ default: module.InfographicFeatureListTemplate })),
-  "steps": () => import("./infographic-steps-JDDEDI7X.js").then((module) => ({ default: module.InfographicStepsTemplate })),
-  "ctaLogo": () => import("./cta-logo-S4OMTNXD.js").then((module) => ({ default: module.CtaLogoTemplate })),
-  "ctaMedia": () => import("./cta-media-EROTHDRR.js").then((module) => ({ default: module.CtaMediaTemplate }))
+  "tripleStats": () => import("./infographic-stat-row-VFTIXS5F.js").then((module) => ({ default: module.InfographicStatRowTemplate })),
+  "problemSolution": () => import("./infographic-problem-solution-FMLJCPG6.js").then((module) => ({ default: module.InfographicProblemSolutionTemplate })),
+  "cardList": () => import("./infographic-feature-list-QDM4I7XE.js").then((module) => ({ default: module.InfographicFeatureListTemplate })),
+  "steps": () => import("./infographic-steps-L7W24Z35.js").then((module) => ({ default: module.InfographicStepsTemplate })),
+  "ctaLogo": () => import("./cta-logo-JJOGK4UC.js").then((module) => ({ default: module.CtaLogoTemplate })),
+  "ctaMedia": () => import("./cta-media-IQ3MAWEH.js").then((module) => ({ default: module.CtaMediaTemplate }))
 };
 
 // src/visual-system/catalog/builtin-player.generated.ts
@@ -1083,6 +1083,7 @@ function VideoPlayerRuntime({
   playbackMode,
   autoPlay = true,
   startMuted = true,
+  nativeMediaAudio,
   width,
   orientation: orientationOverride,
   responsiveBreakpoint = 520,
@@ -1095,6 +1096,10 @@ function VideoPlayerRuntime({
   onSceneChange,
   onStateChange
 }) {
+  const nativeMediaVolume = Math.max(0, Math.min(
+    1,
+    typeof nativeMediaAudio?.volume === "number" && Number.isFinite(nativeMediaAudio.volume) ? nativeMediaAudio.volume : 1
+  ));
   const [reducedMotion, setReducedMotion] = useState(
     () => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches
   );
@@ -1459,6 +1464,8 @@ function VideoPlayerRuntime({
             width: dimensions.width,
             height: dimensions.height,
             playing: isPlaying,
+            mediaAudioMuted: !nativeMediaAudio || isMuted,
+            mediaAudioVolume: nativeMediaVolume,
             style: {
               position: "absolute",
               left: 0,
@@ -1500,7 +1507,7 @@ function VideoPlayerRuntime({
             isPlaying,
             isMuted,
             isFullscreen,
-            hasAudio: Boolean(config?.audio),
+            hasAudio: Boolean(config?.audio) || Boolean(nativeMediaAudio),
             onTogglePlayback: togglePlayback,
             onToggleMuted: () => setIsMuted((muted) => {
               if (muted) setAudioUnlocked(true);

package/dist/{reaction-Z3JIM3MQ.js → reaction-2XCLOJOK.js}

@@ -1,15 +1,15 @@
 import {
   SceneBackground
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   TemplateText
 } from "./chunk-TCEHK2BW.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   resolveTokens
 } from "./chunk-XWWLKRNU.js";

package/dist/{scene-video-backdrop-IL4F2SVD.js → scene-video-backdrop-XFPX4O3I.js}

@@ -1,8 +1,9 @@
 import {
   SceneVideoBackdrop
-} from "./chunk-HT6BGERF.js";
+} from "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import "./chunk-XTOXFMLM.js";
+import "./chunk-5CDAM24P.js";
 import "./chunk-XWWLKRNU.js";
 export {
   SceneVideoBackdrop

package/dist/server.d.ts

@@ -129,6 +129,8 @@ interface ResolvedMedia {
 }
 interface MediaResolverContext {
     input: VideoInput;
+    requestId: string;
+    scene: Readonly<VideoScene>;
     templateId: string;
     preferredType: "image" | "video" | "any";
     signal: AbortSignal;

package/dist/server.js

@@ -476,6 +476,8 @@ async function resolveVariables(options) {
   try {
     resolved = await options.resolveMedia(rawQuery, {
       input: options.input,
+      requestId: options.requestId,
+      scene: { ...options.scene, variables },
       templateId: options.templateId,
       preferredType: preferredType(variables.mediaType),
       signal: options.signal
@@ -533,6 +535,8 @@ async function resolvePartVariables(options) {
   if (options.part.type === "scene.add") {
     const variables = await resolveVariables({
       ...shared,
+      requestId: options.requestId,
+      scene: options.part.scene,
       variables: options.part.scene.variables
     });
     return { ...options.part, scene: { ...options.part.scene, variables } };
@@ -544,6 +548,7 @@ function createMediaResolvingPlanner(options) {
     for await (const part of options.planner(context)) {
       yield await resolvePartVariables({
         part,
+        requestId: context.request.requestId,
         templateId: part.type === "scene.add" ? part.scene.templateId : void 0,
         input: context.request.input,
         signal: context.signal,

package/dist/{showcase-code-NWQAAJIA.js → showcase-code-KHSMIPG6.js}

@@ -5,21 +5,21 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   TemplateText
 } from "./chunk-TCEHK2BW.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   resolveTokens
 } from "./chunk-XWWLKRNU.js";

package/dist/{showcase-phone-5UW45ATT.js → showcase-phone-M4CEANIW.js}

@@ -7,22 +7,22 @@ import "./chunk-S7HFLYNN.js";
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   TemplateText
 } from "./chunk-TCEHK2BW.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   SPRING_SMOOTH,
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   resolveTokens

package/dist/{showcase-terminal-UVOD25UF.js → showcase-terminal-26I3DYF7.js}

@@ -7,21 +7,21 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   TemplateText
 } from "./chunk-TCEHK2BW.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   resolveTokens

package/dist/{showcase-web-3AW6VHIG.js → showcase-web-TY6CZV2Z.js}

@@ -9,22 +9,22 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   TemplateText
 } from "./chunk-TCEHK2BW.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   SPRING_SMOOTH,
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   resolveTokens

package/dist/{social-milestone-KPKHFOB5.js → social-milestone-TF6MX7ET.js}

@@ -8,12 +8,12 @@ import "./chunk-QAAO7OAY.js";
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   Emoji,
   renderWithEmoji
 } from "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import {
   accessibleTextColor,
   withOpacity
@@ -24,8 +24,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   MEDIA_TEXT_SHADOW,
   TOKEN_DEFAULTS,

package/dist/{social-notification-EDOU6TZB.js → social-notification-2RJDAZSF.js}

@@ -4,20 +4,20 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   Emoji,
   renderWithEmoji
 } from "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   SPRING_SMOOTH,
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   resolveTokens
 } from "./chunk-XWWLKRNU.js";

package/dist/{social-review-stack-EZOO33SV.js → social-review-stack-2ICKJQG7.js}

@@ -4,8 +4,8 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
-import "./chunk-HT6BGERF.js";
+} from "./chunk-7BGAU6C3.js";
+import "./chunk-FRN6WKHA.js";
 import {
   accessibleTextColor,
   withOpacity
@@ -15,8 +15,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   lighten,
   resolveTokens

package/dist/{social-testimonial-DLOINMMY.js → social-testimonial-X7OGADA3.js}

@@ -4,8 +4,8 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
-import "./chunk-HT6BGERF.js";
+} from "./chunk-7BGAU6C3.js";
+import "./chunk-FRN6WKHA.js";
 import {
   accessibleTextColor,
   autoTextColor,
@@ -17,8 +17,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   lighten,

package/dist/{social-tweet-6JUM323G.js → social-tweet-TK7SH2F6.js}

@@ -4,11 +4,11 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-7BGAU6C3.js";
 import {
   renderWithEmoji
 } from "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import {
   autoTextColor
 } from "./chunk-W3VDIBGR.js";
@@ -17,8 +17,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   resolveTokens
 } from "./chunk-XWWLKRNU.js";

package/docs/media-and-audio.md

@@ -94,6 +94,65 @@ timeline wraps. This does not bypass browser autoplay policy: use muted autoplay
 for unattended playback and let a viewer unmute, or start audible playback from
 a user interaction.
 
+## Mix native clip audio with a soundtrack
+
+Some generated or supplied scene videos contain their own synchronized
+dialogue, effects, or ambience. Opt into that embedded track at the player:
+
+```tsx
+<VideoPlayer
+  video={video}
+  nativeMediaAudio={{ volume: 0.85 }}
+  playbackMode="muted-autoplay"
+/>
+```
+
+This produces two independent layers: the active scene video's native audio
+at `nativeMediaAudio.volume`, and the continuous soundtrack at the serialized
+`video.audio.volume`. The existing sound button is their shared master mute.
+Incoming videos may preroll visually, but remain muted until their scene is
+active. Native media audio is off by default so existing players keep their
+current soundtrack-only behavior.
+
+## Generate media instead of searching for it
+
+`resolveMedia` does not have to search a catalog. The same callback can
+generate the asset, because it receives the `requestId` and the `scene` being
+resolved alongside the query:
+
+```ts
+resolveMedia: async (query, { requestId, scene, preferredType, signal }) => {
+  const asset = await generateAndStore({ prompt: query, requestId, scene, preferredType, signal });
+  return asset ? { url: asset.url, type: asset.type } : null;
+}
+```
+
+Generation stays outside the SDK install. VanillaSky depends on no image or
+video model, and never selects a provider: the application supplies the model
+and owns the key, the spend, and where bytes are stored.
+
+[`examples/server-integrations/src/ai-sdk-media.ts`](../examples/server-integrations/src/ai-sdk-media.ts)
+is a provider-neutral adapter built on the AI SDK. It takes `ImageModel` and
+`VideoModel` instances rather than naming a vendor, so it runs against any
+model the AI SDK supports. Install the AI SDK and whichever provider you
+chose — for example:
+
+```bash
+npm install ai @ai-sdk/fal
+```
+
+Two rules that example encodes, both about money:
+
+- **`maxRetries: 0`.** A generated asset is billable, so a silent retry can
+  charge twice for one scene. Retrying stays an explicit, budget-aware
+  decision in the application.
+- **A per-scene idempotency key** built from `requestId` and `scene.id`, so a
+  retried request reuses the stored object instead of generating a second one.
+
+Generation is slower than a catalog lookup. Honour `signal`, keep a deadline,
+and return `null` when it passes: a scene that falls back to the brand
+gradient is better than one that never arrives.
+
 ## Media providers
 
 VanillaSky is provider-independent. When `resolveMedia` is configured, the

package/examples/nextjs-quickstart/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^4.0.41",
-    "@vanillaskyai/video": "0.5.8",
+    "@vanillaskyai/video": "0.6.0",
     "ai": "^7.0.77",
     "next": "16.3.2",
     "react": "19.2.8",

package/examples/nextjs-quickstart/src/app/api/video/route.ts

@@ -2,9 +2,18 @@ import { anthropic } from "@ai-sdk/anthropic";
 import { streamText } from "ai";
 import { createVideoHandler } from "@vanillaskyai/video/server";
 
-const modelId = process.env.ANTHROPIC_MODEL;
-if (!modelId) throw new Error("Set ANTHROPIC_MODEL in the server environment");
-const model = anthropic(modelId);
+// Resolved per request so the app still builds with the shipped placeholder.
+function resolveModel() {
+  const modelId = process.env.ANTHROPIC_MODEL;
+  if (!modelId || modelId === "replace-with-current-sonnet-model") {
+    throw new Error(
+      "Set ANTHROPIC_MODEL in .env.local to a current Claude Sonnet model ID available to your " +
+        "account. The shipped value is a placeholder: VanillaSky never selects a provider or " +
+        "model for you.",
+    );
+  }
+  return anthropic(modelId);
+}
 
 const handle = createVideoHandler({
   authorize: (request) => {
@@ -13,7 +22,7 @@ const handle = createVideoHandler({
     return hostname === "localhost" || hostname === "127.0.0.1";
   },
   streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
-    model,
+    model: resolveModel(),
     system: systemPrompt,
     prompt: userPrompt,
     abortSignal: signal,

package/examples/server-integrations/README.md

@@ -0,0 +1,20 @@
+# Server examples
+
+The normal example uses the AI SDK's `streamText`, so any AI SDK `LanguageModel`
+works without VanillaSky owning the provider, model, or credentials. Replace
+`openai(modelId)` in `src/ai-sdk.ts` with an official provider, community
+provider, AI Gateway model, OpenAI-compatible provider, or custom model.
+
+`src/provider-neutral.ts` and `src/openai.ts` show the lower-level text-delta
+escape hatch for applications that need to own the native provider loop.
+
+<!-- verify:start -->
+```bash
+npm install
+npm run typecheck
+npm run ai-sdk:compat
+```
+<!-- verify:end -->
+
+Use the returned Web `Request` → `Response` handler directly in Next.js, Hono,
+Remix, Cloudflare Workers, or another standards-based server runtime.