@vanillaskyai/video 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -4,6 +4,20 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.3
+
+- Remove the implicit documentary visual style from the chat interface; preserve explicitly supplied application styles and let the answer direct its own look.
+- Default chat now plans an answer brief and narrated shots, with an immediate introduction followed by AI-first footage and relevant stock fallback. Creative direction adapts to the request; the model no longer chooses body templates, media sources, scene IDs, or completion commands. Explicit custom template registries retain their existing composition contract.
+- Reserve the answer's ending before streaming body shots, retain valid narration when visuals are unavailable, and skip exact repeated opening or ending lines before requesting media.
+- Fit short clips to measured narration within a bounded playback rate. If moving coverage runs out, use bounded recovery and an explicit waiting state instead of holding a finished frame while speech continues. Preserve deliberate pauses and audio activation across scenes.
+- The optional starter video adapter uses Fal Turbo with five-second clips and intent-specific shot direction; providers, credentials, admission and spending limits remain application-owned.
+
+## 0.10.2
+
+- Keep generated narration playing in Safari after a delayed opening-to-body handoff by reusing the permitted audio element; isolate late playback failures from subsequent lines.
+- In drop mode, a media miss without usable authored fallback skips only that scene and preserves later valid scenes and the ending. Strict mode still fails. The skipped beat is reported; its content cannot be reconstructed without a usable asset or fallback.
+- Guide first-shot narration to fit its five-second footage budget and develop the answer in later scenes, without imposing a fixed sentence length on the rest of the video.
+
 ## 0.10.1
 
 - Continue narration through failed built-in media using the authored fallback or the existing graphic on black. Keep the recovery anchor after URL resolution, and observe actual mounted images for photo readiness.

package/README.md

@@ -25,9 +25,10 @@ npx vanillasky doctor
 npm run dev
 ```
 
-Open the reported localhost URL. One text key gives you the complete chat with
-packaged templates and browser voice. No template setup or optional provider
-packages are required. If installation is interrupted, rerun the init command.
+Open the reported localhost URL. One text key gives you the chat, an immediate introduction, and browser voice.
+Add the video adapter for generated footage and optional stock for fallback.
+Without a media provider, answers retain narration and subtitles with an
+unavailable-visual state. If installation is interrupted, rerun the init command.
 
 Optional upgrades keep the same client:
 
@@ -80,11 +81,15 @@ conversation and playback lifecycle. Edit the generated server when you want a
 different provider. The [provider guide](docs/provider-integration.md) explains
 both boundaries.
 
-## Templates are the built-in fallback
+## An immediate intro, then moving footage
 
-The packaged visual templates are the fast, inexpensive default and require no
-copied source tree. Add a video provider when you want generated footage; the
-same conversation can mix both modes.
+The default chat uses a template introduction while its first shot prepares,
+then generated footage with narration and subtitles. Relevant stock is the
+fallback when generation is unavailable or fails. The planner adapts its
+visible actions and spoken beats to explanations, stories, comedy, imagination,
+and practical requests. It does not choose body templates.
+
+Packaged templates remain available for custom compositions and source ownership.
 
 Copy template source only when you want to own and edit it:
 

package/dist/check-runtime.js

@@ -1,8 +1,8 @@
 import {
   VideoFrame
-} from "./chunk-6KZGF63O.js";
+} from "./chunk-3U2F7C7C.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-TVIU23OM.js";
+import "./chunk-YZZSWGC3.js";
 import "./chunk-SPVTJH3F.js";
 import "./chunk-R3XAOMKP.js";
 import "./chunk-73NTSFFI.js";

package/dist/{chunk-6KZGF63O.js → chunk-3U2F7C7C.js}

@@ -5,7 +5,7 @@ import {
 import {
   ExternalVideoBackdropProvider,
   resolveDensity
-} from "./chunk-TVIU23OM.js";
+} from "./chunk-YZZSWGC3.js";
 import {
   resolveVideoTimeline
 } from "./chunk-SPVTJH3F.js";
@@ -209,7 +209,7 @@ var SceneBoundary = class extends Component {
   }
 };
 var SCENE_TRANSITION_SECONDS = 0.3;
-var SceneVideoBackdrop = lazy(() => import("./scene-video-backdrop-PCTARAAJ.js").then((module) => ({ default: module.SceneVideoBackdrop })));
+var SceneVideoBackdrop = lazy(() => import("./scene-video-backdrop-OWUXPXHZ.js").then((module) => ({ default: module.SceneVideoBackdrop })));
 var MEDIA_PREROLL_SECONDS = 1.2;
 var CONTIGUITY_ULP_FACTOR = 4;
 var subscribeToDecoderPolicy = () => () => {
@@ -265,6 +265,7 @@ function SceneLayer({
   width,
   height,
   playing,
+  preparingNarration,
   mediaAudioMuted,
   mediaAudioVolume,
   layer,
@@ -283,7 +284,8 @@ function SceneLayer({
       mode: externalVideoBackdrop,
       audioMuted: mediaAudioMuted || !playing,
       audioVolume: mediaAudioVolume,
-      children: /* @__PURE__ */ jsx2(
+      preparingNarration,
+      children: /* @__PURE__ */ jsxs(
         "div",
         {
           "data-scene-layer": layer,
@@ -304,37 +306,48 @@ function SceneLayer({
             "--vanillasky-transition-semantic-visibility": layer === "incoming" ? "hidden" : "visible",
             "--vanillasky-template-surface": externalVideoBackdrop !== false ? "transparent" : void 0
           },
-          children: template ? /* @__PURE__ */ jsx2(SceneBoundary, { scene: range.scene, onFramePresented, children: /* @__PURE__ */ jsxs(Suspense, { fallback: /* @__PURE__ */ jsx2(
-            "div",
-            {
-              "data-template-loading": range.scene.templateId,
-              style: { position: "absolute", inset: 0 }
-            }
-          ), children: [
-            /* @__PURE__ */ jsx2(PresentedScene, { notify: onFramePresented }),
-            createElement(template.component, {
-              variables: {
-                ...template.defaults ?? getTemplateDefaults(template.schema),
-                ...range.scene.variables,
-                ...mediaFailed ? { mediaUrl: "", mediaPoster: "", mediaType: "gradient" } : {},
-                ...recoveryTitle ? { title: recoveryTitle } : {}
-              },
-              style: config.style,
-              progress,
-              motionProgress,
-              beatIntensity: 0,
-              width,
-              height,
-              textArchetype: range.scene.textArchetype ?? config.style.defaultTextArchetype,
-              backgroundEffect: range.scene.backgroundEffect ?? config.style.defaultBackgroundEffect,
-              safeZone: scaleSafeZone(
-                getSafeZone(config.orientation),
-                resolveDensity(config.style.density).safeZoneScale
-              ),
-              sceneDuration: duration,
-              isPlaying: playing
-            })
-          ] }) }, range.scene.id) : /* @__PURE__ */ jsx2(SafeScene, { scene: range.scene, onFramePresented })
+          children: [
+            range.scene.templateId === "cinemaMedia" && !recoveryTitle && (mediaFailed || !String(range.scene.variables.mediaUrl || "").trim()) && /* @__PURE__ */ jsx2(
+              "div",
+              {
+                role: "status",
+                "data-media-unavailable": "true",
+                style: { position: "absolute", inset: 0, zIndex: 2, display: "grid", placeContent: "center", color: "#bbb", font: "14px system-ui", background: "#000" },
+                children: "Visual unavailable"
+              }
+            ),
+            template ? /* @__PURE__ */ jsx2(SceneBoundary, { scene: range.scene, onFramePresented, children: /* @__PURE__ */ jsxs(Suspense, { fallback: /* @__PURE__ */ jsx2(
+              "div",
+              {
+                "data-template-loading": range.scene.templateId,
+                style: { position: "absolute", inset: 0 }
+              }
+            ), children: [
+              /* @__PURE__ */ jsx2(PresentedScene, { notify: onFramePresented }),
+              createElement(template.component, {
+                variables: {
+                  ...template.defaults ?? getTemplateDefaults(template.schema),
+                  ...range.scene.variables,
+                  ...mediaFailed ? { mediaUrl: "", mediaPoster: "", mediaType: "gradient" } : {},
+                  ...recoveryTitle ? { title: recoveryTitle } : {}
+                },
+                style: config.style,
+                progress,
+                motionProgress,
+                beatIntensity: 0,
+                width,
+                height,
+                textArchetype: range.scene.textArchetype ?? config.style.defaultTextArchetype,
+                backgroundEffect: range.scene.backgroundEffect ?? config.style.defaultBackgroundEffect,
+                safeZone: scaleSafeZone(
+                  getSafeZone(config.orientation),
+                  resolveDensity(config.style.density).safeZoneScale
+                ),
+                sceneDuration: duration,
+                isPlaying: playing
+              })
+            ] }) }, range.scene.id) : /* @__PURE__ */ jsx2(SafeScene, { scene: range.scene, onFramePresented })
+          ]
         }
       )
     }
@@ -348,6 +361,7 @@ function VideoFrame({
   width,
   height,
   playing = false,
+  preparingNarration = false,
   mediaAudioMuted = true,
   mediaAudioVolume = 1,
   className,
@@ -550,7 +564,9 @@ function VideoFrame({
                       mediaPosition: String(persistentVideoRange.scene.variables.mediaPosition || "center"),
                       backgroundEffect: persistentVideoRange.scene.backgroundEffect ?? config.style.defaultBackgroundEffect,
                       progress: persistentVideoRange.scene.id === active.scene.id ? rawProgress : 0,
+                      sceneDuration: persistentVideoRange.end - persistentVideoRange.start,
                       isPlaying: persistentVideoRange.scene.id === active.scene.id && playing,
+                      preparingNarration,
                       muted: mediaAudioMuted || persistentVideoRange.scene.id !== active.scene.id || !playing,
                       volume: mediaAudioVolume,
                       playbackId: persistentVideoRange.scene.id,
@@ -583,6 +599,7 @@ function VideoFrame({
                     width: canvas.width,
                     height: canvas.height,
                     playing,
+                    preparingNarration,
                     mediaAudioMuted,
                     mediaAudioVolume,
                     layer: previewingNext ? "outgoing" : "active",
@@ -604,6 +621,7 @@ function VideoFrame({
                     width: canvas.width,
                     height: canvas.height,
                     playing: false,
+                    preparingNarration: false,
                     mediaAudioMuted,
                     mediaAudioVolume,
                     layer: "incoming",
@@ -627,6 +645,7 @@ function VideoFrame({
                     width: canvas.width,
                     height: canvas.height,
                     playing,
+                    preparingNarration,
                     mediaAudioMuted,
                     mediaAudioVolume,
                     layer: "active",

package/dist/{chunk-5C6HZNHY.js → chunk-LJR5VLEI.js}

@@ -3,13 +3,13 @@ import {
   SceneVideoBackdrop,
   getBackgroundTransform,
   resolveMediaPosition
-} from "./chunk-77VY4O7A.js";
+} from "./chunk-SI6CFFAA.js";
 import {
   resolveMediaType
 } from "./chunk-224QNWRA.js";
 import {
   useExternalVideoBackdrop
-} from "./chunk-TVIU23OM.js";
+} from "./chunk-YZZSWGC3.js";
 
 // src/visual-system/scene-templates/scene-background.tsx
 import { useEffect, useState } from "react";
@@ -157,6 +157,7 @@ var SceneBackground = ({
         mediaPosition,
         backgroundEffect,
         progress,
+        sceneDuration,
         beatIntensity,
         isPlaying,
         onReady: () => setMediaPaint("ready"),

package/dist/{chunk-77VY4O7A.js → chunk-SI6CFFAA.js}

@@ -1,11 +1,12 @@
 import {
   darken,
   resolveTokens,
-  useMediaAudio
-} from "./chunk-TVIU23OM.js";
+  useMediaAudio,
+  useNarrationPreroll
+} from "./chunk-YZZSWGC3.js";
 
 // src/visual-system/scene-templates/scene-video-backdrop.tsx
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 
 // src/visual-system/scene-templates/color-utils.ts
 import React from "react";
@@ -228,6 +229,8 @@ var SceneVideoBackdrop = ({
   mediaPosition = "center",
   backgroundEffect,
   progress,
+  sceneDuration,
+  preparingNarration = false,
   beatIntensity = 0,
   isPlaying,
   muted,
@@ -240,15 +243,44 @@ var SceneVideoBackdrop = ({
   onError
 }) => {
   const inheritedAudio = useMediaAudio();
+  const inheritedPreroll = useNarrationPreroll();
+  const rewindPreroll = preparingNarration || inheritedPreroll;
   const resolvedMuted = muted ?? inheritedAudio.muted;
   const resolvedVolume = volume ?? inheritedAudio.volume;
   const resolvedPosition = resolveMediaPosition(mediaPosition);
   const bgTransform = getBackgroundTransform(backgroundEffect, progress, beatIntensity);
   const [decodedVideoUrl, setDecodedVideoUrl] = useState();
+  const [waitingKey, setWaitingKey] = useState();
+  const [exhaustedKey, setExhaustedKey] = useState();
+  const continuityReplay = useRef(void 0);
   const videoRef = useRef(null);
   const startedVideoUrl = useRef(void 0);
   const startedPlaybackId = useRef(void 0);
   const videoPresentationKey = `${playbackId}\0${mediaUrl}`;
+  const presentationRef = useRef({ key: videoPresentationKey, playing: isPlaying });
+  presentationRef.current = { key: videoPresentationKey, playing: isPlaying };
+  const unavailable = () => {
+    if (presentationRef.current.key === videoPresentationKey && presentationRef.current.playing) {
+      setExhaustedKey(videoPresentationKey);
+      onError?.();
+    }
+  };
+  const fitDuration = useCallback((video) => {
+    video.playbackRate = (resolvedMuted || video.preservesPitch === true) && sceneDuration && Number.isFinite(video.duration) && video.duration > 0 ? Math.max(0.75, Math.min(1, video.duration / (sceneDuration + 0.2))) : 1;
+  }, [resolvedMuted, sceneDuration]);
+  useEffect(() => {
+    if (videoRef.current) fitDuration(videoRef.current);
+  }, [fitDuration]);
+  const continueMotion = (video) => {
+    if (!isPlaying) return;
+    if (!resolvedMuted || continuityReplay.current === videoPresentationKey) {
+      setExhaustedKey(videoPresentationKey);
+      return;
+    }
+    continuityReplay.current = videoPresentationKey;
+    video.currentTime = 0;
+    void video.play().catch(unavailable);
+  };
   useEffect(() => {
     const video = videoRef.current;
     if (!video) return;
@@ -273,21 +305,21 @@ var SceneVideoBackdrop = ({
     if (!video) return;
     if (!isPlaying) {
       video.pause();
+      if (rewindPreroll && video.currentTime > 0) video.currentTime = 0;
       return;
     }
     if (startedPlaybackId.current === playbackId) {
-      if (!video.ended) void video.play().catch(() => {
-      });
+      if (video.ended) continueMotion(video);
+      else void video.play().catch(unavailable);
       return;
     }
     const changingSource = startedVideoUrl.current !== void 0 && startedVideoUrl.current !== mediaUrl;
-    video.playbackRate = 1;
+    fitDuration(video);
     if (!changingSource && video.currentTime > 0) video.currentTime = 0;
-    video.play().catch(() => {
-    });
+    video.play().catch(unavailable);
     startedVideoUrl.current = mediaUrl;
     startedPlaybackId.current = playbackId;
-  }, [isPlaying, mediaUrl, playbackId]);
+  }, [isPlaying, mediaUrl, playbackId, rewindPreroll]);
   const mediaStyle = {
     position: "absolute",
     inset: 0,
@@ -349,6 +381,15 @@ var SceneVideoBackdrop = ({
       },
       posterPlane.presentationKey
     )),
+    (exhaustedKey === videoPresentationKey || waitingKey === videoPresentationKey) && /* @__PURE__ */ jsx(
+      "div",
+      {
+        role: "status",
+        "data-media-continuity": exhaustedKey === videoPresentationKey ? "exhausted" : "waiting",
+        style: { position: "absolute", inset: 0, zIndex: 3, background: "#000", color: "#bbb", display: "grid", placeContent: "center", font: "14px system-ui" },
+        children: exhaustedKey === videoPresentationKey ? "Visual unavailable" : "Loading visual"
+      }
+    ),
     /* @__PURE__ */ jsx(
       "video",
       {
@@ -359,6 +400,12 @@ var SceneVideoBackdrop = ({
         loop: false,
         playsInline: true,
         preload: "auto",
+        onLoadedMetadata: (event) => fitDuration(event.currentTarget),
+        onEnded: (event) => continueMotion(event.currentTarget),
+        onWaiting: () => {
+          if (isPlaying) setWaitingKey(videoPresentationKey);
+        },
+        onPlaying: () => setWaitingKey(void 0),
         onLoadedData: (event) => {
           const video = event.currentTarget;
           const markPresented = () => {
@@ -375,7 +422,7 @@ var SceneVideoBackdrop = ({
         onError,
         "data-media-position": mediaPosition,
         "data-video-backdrop": persistent ? "persistent" : "scene",
-        style: mediaStyle
+        style: { ...mediaStyle, visibility: exhaustedKey === videoPresentationKey || waitingKey === videoPresentationKey ? "hidden" : void 0 }
       }
     )
   ] });

package/dist/{chunk-KHLO5OHT.js → chunk-UCXQORDZ.js}

@@ -1,7 +1,7 @@
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-5C6HZNHY.js";
+} from "./chunk-LJR5VLEI.js";
 import {
   editorialFont
 } from "./chunk-4YM2M62S.js";

package/dist/{chunk-VQH3JTQC.js → chunk-VVNZCY2U.js}

@@ -1,7 +1,7 @@
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-5C6HZNHY.js";
+} from "./chunk-LJR5VLEI.js";
 
 // src/visual-system/scene-templates/cinema-media.tsx
 import { jsx } from "react/jsx-runtime";

package/dist/{chunk-TVIU23OM.js → chunk-YZZSWGC3.js}

@@ -8,11 +8,12 @@ function ExternalVideoBackdropProvider({
   mode,
   audioMuted = true,
   audioVolume = 1,
+  preparingNarration = false,
   children
 }) {
   const value = React.useMemo(
-    () => ({ mode, audioMuted, audioVolume }),
-    [mode, audioMuted, audioVolume]
+    () => ({ mode, audioMuted, audioVolume, preparingNarration }),
+    [mode, audioMuted, audioVolume, preparingNarration]
   );
   return /* @__PURE__ */ jsx(BackdropContext.Provider, { value, children });
 }
@@ -23,6 +24,9 @@ function useMediaAudio() {
   const { audioMuted, audioVolume } = React.useContext(BackdropContext);
   return { muted: audioMuted, volume: audioVolume };
 }
+function useNarrationPreroll() {
+  return React.useContext(BackdropContext).preparingNarration === true;
+}
 
 // src/visual-system/scene-templates/tokens.ts
 var STYLE_PRESETS = {
@@ -142,5 +146,6 @@ export {
   darken,
   ExternalVideoBackdropProvider,
   useExternalVideoBackdrop,
-  useMediaAudio
+  useMediaAudio,
+  useNarrationPreroll
 };

package/dist/{cinema-media-APDJS7SC.js → cinema-media-4JUYKPQI.js}

@@ -1,11 +1,11 @@
 import {
   MediaScene,
   MediaSceneTemplate
-} from "./chunk-VQH3JTQC.js";
-import "./chunk-5C6HZNHY.js";
-import "./chunk-77VY4O7A.js";
+} from "./chunk-VVNZCY2U.js";
+import "./chunk-LJR5VLEI.js";
+import "./chunk-SI6CFFAA.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-TVIU23OM.js";
+import "./chunk-YZZSWGC3.js";
 export {
   MediaScene,
   MediaSceneTemplate

package/dist/{comparison-ZVE2DE7U.js → comparison-3QLMUC5V.js}

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-KHLO5OHT.js";
-import "./chunk-5C6HZNHY.js";
-import "./chunk-77VY4O7A.js";
+} from "./chunk-UCXQORDZ.js";
+import "./chunk-LJR5VLEI.js";
+import "./chunk-SI6CFFAA.js";
 import {
   editorialLabel,
   fade
@@ -10,7 +10,7 @@ import {
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-TVIU23OM.js";
+import "./chunk-YZZSWGC3.js";
 
 // src/visual-system/scene-templates/comparison.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{editorial-timeline-YIXXVJUV.js → editorial-timeline-IVE2P25N.js}

@@ -1,13 +1,13 @@
 import {
   EditorialSurface
-} from "./chunk-KHLO5OHT.js";
-import "./chunk-5C6HZNHY.js";
-import "./chunk-77VY4O7A.js";
+} from "./chunk-UCXQORDZ.js";
+import "./chunk-LJR5VLEI.js";
+import "./chunk-SI6CFFAA.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-TVIU23OM.js";
+import "./chunk-YZZSWGC3.js";
 
 // src/visual-system/scene-templates/editorial-timeline.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{key-figure-I2C37FWV.js → key-figure-APD56LCO.js}

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-KHLO5OHT.js";
-import "./chunk-5C6HZNHY.js";
-import "./chunk-77VY4O7A.js";
+} from "./chunk-UCXQORDZ.js";
+import "./chunk-LJR5VLEI.js";
+import "./chunk-SI6CFFAA.js";
 import {
   editorialLabel,
   fade
@@ -10,7 +10,7 @@ import {
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-TVIU23OM.js";
+import "./chunk-YZZSWGC3.js";
 
 // src/visual-system/scene-templates/key-figure.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{mobile-message-JSGBU6EX.js → mobile-message-WLK3WY5B.js}

@@ -1,15 +1,15 @@
 import {
   MediaScene
-} from "./chunk-VQH3JTQC.js";
-import "./chunk-5C6HZNHY.js";
+} from "./chunk-VVNZCY2U.js";
+import "./chunk-LJR5VLEI.js";
 import {
   spring
-} from "./chunk-77VY4O7A.js";
+} from "./chunk-SI6CFFAA.js";
 import {
   editorialFont
 } from "./chunk-4YM2M62S.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-TVIU23OM.js";
+import "./chunk-YZZSWGC3.js";
 
 // src/visual-system/scene-templates/mobile-message.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{quote-XH54G3FS.js → quote-Z6YET5BO.js}

@@ -1,15 +1,15 @@
 import {
   EditorialSurface
-} from "./chunk-KHLO5OHT.js";
-import "./chunk-5C6HZNHY.js";
-import "./chunk-77VY4O7A.js";
+} from "./chunk-UCXQORDZ.js";
+import "./chunk-LJR5VLEI.js";
+import "./chunk-SI6CFFAA.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-TVIU23OM.js";
+import "./chunk-YZZSWGC3.js";
 
 // src/visual-system/scene-templates/quote.tsx
 import { jsx, jsxs } from "react/jsx-runtime";