@vanillaskyai/video 0.10.2 → 0.10.4

package/CHANGELOG.md

@@ -4,6 +4,23 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.4
+
+- Show the canonical chapter immediately after submitting a prompt; remove the separate gradient loading placeholder and opening stock requests.
+- Separate AI video and Pexels in Settings. AI mode uses generated footage only; Pexels performs full bounded video search without AI-video calls. Missing or late footage becomes an authored chapter with complete narration.
+- Prepare speech while footage generates, reuse prepared lines, and limit concurrent speech requests so an answer does not flood host admission. Describe HTTP throttling as a retryable request limit.
+- Keep silent footage looping for the finite narrated scene, and recover missing URLs or rejected playback to a chapter rather than an unavailable screen. Preserve user pause, cancellation and replay.
+- Allow hosts to configure the actual generated clip duration (default five seconds) and apply scene-position deadlines to media preparation.
+- Add optional host-only phase diagnostics with bounded timing and fixed recovery reasons, without retaining prompt or provider content.
+
+## 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.

package/PUBLIC-API.md

@@ -116,6 +116,19 @@ provider-neutral text-delta escape hatch.
 
 ### Handler contract
 
+The chat contract includes two footage modes: `"cinematic"` (labelled AI video)
+and `"pexels"`. AI mode does not fall back to stock; either mode recovers missing
+footage to an authored chapter. Existing `"cinematic"` requests remain valid.
+`generatedClipDurationSec?: number` on the handler defaults to 5 and accepts 2–20;
+it must match the host adapter's requested duration. `VideoChatTurn.mode` is
+optional so older in-memory saved turns remain readable.
+
+A declared `data.video-chat-preparation` extension carries
+`{ sceneId: string, narration: string }` before media resolves. It permits bounded
+speech preparation, not playback of an unvalidated scene. The client limits
+speech preparation to two concurrent jobs and reuses it when `scene.add` arrives.
+The six public exports, persisted video schema and protocol version are unchanged.
+
 `createVideoChatHandler` is the opinionated general-purpose video-chat route.
 Mount it once and use its bounded `action` query parameter for capabilities,
 responses, opening media, narration, suggestions, speech,
@@ -124,33 +137,28 @@ application-configured visual-mode attempt limits, capability fallbacks, and aux
 shapes. The application supplies provider-neutral `streamText`, `generateText`,
 `generateSpeech`, `transcribe`, `searchMedia`, and `generateVideo` callbacks.
 Only the two text callbacks are required. Missing optional callbacks remove
-their capability; templates and browser speech remain available. During response
-creation, failed generated footage falls back to stock when available, then to
-matching completed footage and finally a safe template. The default handler skips invalid planner parts and preserves
-playable scenes on an interrupted plan, emitting non-fatal warnings. Explicit
-`invalidPartBehavior: "fail"` retains strict generation semantics.
+their capability; templates and browser speech remain available. Failed or late
+footage becomes an authored chapter with complete narration. The default handler
+skips invalid planner parts and preserves playable scenes on an interrupted plan,
+emitting non-fatal warnings. Explicit `invalidPartBehavior: "fail"` retains strict
+generation semantics.
 
 - A response accepts `prompt`, `mode`, `orientation`, optional bounded
   `conversation`, `opening`, and `style`. `opening` is an optional
   prewritten hook from a selected suggestion. The response returns protocol
-  `0.6` SSE and negotiates `data.video-chat-opening`, which carries the bounded
-  6-9 word hook and optional stock-search `keyword` and `fallbackKeyword` before the first scene.
-- The planner produces that opening as the first line of the same model stream
-  that produces the scenes. The separate opening-media action resolves its
-  keyword through the application-owned `searchMedia` callback, with an optional
-  bounded `fallbackQuery` for broader opening atmosphere. Stock lookup
-  never delays speech or planning. In `full` mode the first line also directs
-  the exact first generated scene; the handler consumes that private direction
-  and starts the clip while the model continues with scenes two through five.
-- `templates` never generates video. `full` uses an application-owned
-  `maxGeneratedVideos` limit (default five, nonnegative safe integer). The limit
-  counts attempts including failed attempts and the reserved first shot; it is
-  neither a currency nor duration cap. Stock lookup remains available after
-  the limit. With zero, full mode uses stock only. The planner receives this
-  budget, and the server enforces it independently. If providers fail, an
-  already completed video with the identical search query and visual look may
-  be reused once in the same response before a readable template fallback. Without `generateVideo`, only `templates` is exposed
-  and forged generated-mode requests degrade to it.
+  `0.6` SSE and negotiates `data.video-chat-opening` and
+  `data.video-chat-preparation` before the associated scene is ready.
+- The planner produces the opening and shots in one model stream, reserving the
+  intended ending. Each shot supplies an authored recovery title, complete
+  narration and visual direction. The default UI uses a chapter opening; the
+  separate opening-media action remains available to custom consumers.
+- `cinematic` uses the application-owned `maxGeneratedVideos` limit (default
+  five, nonnegative safe integer). It counts generation attempts, including
+  failures. Zero skips generation and keeps authored chapters. Expired scene
+  deadlines also skip generation without consuming an attempt. This limit is
+  neither a currency nor duration cap. Pexels mode uses only `searchMedia` and
+  never consumes this allowance. Capabilities expose Pexels when stock search
+  is configured; AI mode remains usable with chapter recovery without video.
 - The response planner writes narration on each scene. The narration action is
   retained as a compatibility fallback for missing lines, not used in the
   normal path.
@@ -251,9 +259,9 @@ playable output; an error is shown only when no playable response remains.
 `ask(prompt, { opening, openingMedia })` lets a custom interface start a
 prewritten suggestion hook immediately and reuse its image or video without
 another model or media lookup. The hook otherwise reads the opening from the
-response stream, resolves its media keyword, holds that media while it is
-spoken, and starts the planned timeline only when both speech and the first
-scene are ready. `UseVideoChatOptions.onFirstFrame` receives a
+response stream and starts the planned timeline only when opening speech and
+the contiguous prepared scenes are ready. It no longer requests opening stock
+automatically. `UseVideoChatOptions.onFirstFrame` receives a
 `VideoChatFirstFrameMetric` once after its first active scene commits and reaches
 an animation-frame opportunity. This measures presentation readiness, not physical
 screen paint or media decoding. Each `VideoChatTurn` exposes `openingMedia` and `completed`, so
@@ -428,6 +436,7 @@ from `/server` without crossing a React type boundary.
 and nonnegative `elapsedMs` since the prompt was submitted:
 
 - `first-frame`: first committed active scene at an animation-frame opportunity;
+- `first-media-frame`: first decoded frame reported by the mounted footage surface;
 - `first-speech`: actual speech playback onset, with `source` equal to `browser`,
   `generated`, or `custom`;
 - `stall`: a finished wait for the next prepared scene, with `durationMs` and
@@ -455,8 +464,11 @@ resolver deadline (integer 1–120000 milliseconds, default 15000). The host sti
 provider cancellation, authorization and spend limits; a timeout does not prove the
 provider avoided a charge. `maxGeneratedVideos` continues to count attempted clips.
 
-`VideoChatProps.generatedVideoLabel` and `generatedVideoDescription` customize the
-existing generated-video Settings choice without changing server capabilities.
-`showRecoveryNotice` opts into a dismissible, fixed SDK media-fallback notice. It
-never displays arbitrary provider messages. All three default to existing behavior.
-These are additive members; no new entry points or exports are introduced.
+`VideoChatProps.showRecoveryNotice` opts into a dismissible, fixed SDK
+media-recovery notice; it never displays arbitrary provider messages.
+
+`VideoChatHandlerOptions.onDiagnostic` is an optional host-only observer for
+request, authoring and media phase timings with fixed recovery reason codes.
+It does not retain prompt, narration, query, asset URL or provider error text,
+and cannot affect response delivery. No new entry points or named exports are
+introduced; its additive signature is checked in the packed consumer contract.

package/README.md

@@ -25,9 +25,9 @@ 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 AI footage, or a Pexels key for the lower-cost stock mode.
+Without footage, authored chapter scenes carry the narration and subtitles. If installation is interrupted, rerun the init command.
 
 Optional upgrades keep the same client:
 
@@ -35,7 +35,7 @@ Optional upgrades keep the same client:
 | --- | --- | --- |
 | Generated speech | `npx vanillasky providers add speech` | `XAI_API_KEY` |
 | Generated video and voice transcription | `npx vanillasky providers add video` | `FAL_KEY` |
-| Stock media, including opening backgrounds | No install needed | `PEXELS_API_KEY` |
+| Pexels video search | No install needed | `PEXELS_API_KEY` |
 
 Run the selected command, add its key to `.env.local`, and restart the server.
 Only selected provider packages are installed. `npx vanillasky doctor` reports
@@ -80,17 +80,25 @@ 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 footage with narration and subtitles. Choose AI video or Pexels in Settings.
+AI mode never substitutes stock, and Pexels mode never calls the AI-video provider.
+Missing or late footage becomes a useful chapter scene. The planner adapts its
+visible actions and spoken beats to explanations, stories, comedy, imagination,
+and practical requests. It does not choose body templates.
+
+Speech and footage prepare together. Silent clips loop through the remaining
+narration when necessary, and every answer preserves its intended ending.
+
+Packaged templates remain available for custom compositions and source ownership.
 
 Copy template source only when you want to own and edit it:
 
 ```bash
 npm install --save-dev tsx
-npx vanillasky templates add bigNumber
+npx vanillasky templates add chapterTitle
 ```
 
 That compiler is needed only for source-owned templates. See
@@ -113,6 +121,7 @@ MP4/WebM export remains application-owned.
 | Add media or voice | [Media and voice](docs/media-and-audio.md) |
 | Persist and replay results | [Performance measurements](docs/performance.md) · [Persistence and replay](docs/persistence.md) |
 | Test routes and streams | [Test integrations](docs/testing.md) |
+| Iterate on SDK chat | [Development](docs/development.md): `dev:chat`, `check:chat`, `verify:release` |
 | Deploy securely | [Production](docs/production.md) · [Security](docs/security.md) |
 | Inspect the API contract | [Public API](PUBLIC-API.md) · [Protocol](docs/reference/protocol.md) |
 

package/dist/check-runtime.js

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

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

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

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

@@ -1,11 +1,13 @@
 import {
   darken,
   resolveTokens,
-  useMediaAudio
-} from "./chunk-TVIU23OM.js";
+  useMediaAudio,
+  useMediaFailure,
+  useNarrationPreroll
+} from "./chunk-OOBT4X46.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 +230,8 @@ var SceneVideoBackdrop = ({
   mediaPosition = "center",
   backgroundEffect,
   progress,
+  sceneDuration,
+  preparingNarration = false,
   beatIntensity = 0,
   isPlaying,
   muted,
@@ -240,15 +244,44 @@ var SceneVideoBackdrop = ({
   onError
 }) => {
   const inheritedAudio = useMediaAudio();
+  const reportMediaFailure = useMediaFailure();
+  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 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?.();
+      reportMediaFailure?.();
+    }
+  };
+  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) {
+      unavailable();
+      return;
+    }
+    video.currentTime = 0;
+    void video.play().catch(unavailable);
+  };
   useEffect(() => {
     const video = videoRef.current;
     if (!video) return;
@@ -273,21 +306,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 +382,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 +401,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 +423,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-TVIU23OM.js → chunk-OOBT4X46.js}

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

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

@@ -3,13 +3,13 @@ import {
   SceneVideoBackdrop,
   getBackgroundTransform,
   resolveMediaPosition
-} from "./chunk-77VY4O7A.js";
+} from "./chunk-O6FBIB4L.js";
 import {
   resolveMediaType
 } from "./chunk-224QNWRA.js";
 import {
   useExternalVideoBackdrop
-} from "./chunk-TVIU23OM.js";
+} from "./chunk-OOBT4X46.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-6KZGF63O.js → chunk-WZFLEPLM.js}

@@ -5,7 +5,7 @@ import {
 import {
   ExternalVideoBackdropProvider,
   resolveDensity
-} from "./chunk-TVIU23OM.js";
+} from "./chunk-OOBT4X46.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-4EZVVQY7.js").then((module) => ({ default: module.SceneVideoBackdrop })));
 var MEDIA_PREROLL_SECONDS = 1.2;
 var CONTIGUITY_ULP_FACTOR = 4;
 var subscribeToDecoderPolicy = () => () => {
@@ -257,6 +257,7 @@ function sceneBackgroundChanges(left, right) {
 }
 function SceneLayer({
   onFramePresented,
+  onMediaError,
   kit,
   config,
   range,
@@ -265,6 +266,7 @@ function SceneLayer({
   width,
   height,
   playing,
+  preparingNarration,
   mediaAudioMuted,
   mediaAudioVolume,
   layer,
@@ -273,7 +275,7 @@ function SceneLayer({
   zIndex,
   externalVideoBackdrop
 }) {
-  const mediaFailed = externalVideoBackdrop === "fallback";
+  const mediaFailed = externalVideoBackdrop === "fallback" || range.scene.templateId === "cinemaMedia" && !String(range.scene.variables.mediaUrl || "").trim();
   const recoveryTitle = mediaFailed && range.scene.templateId === "cinemaMedia" && typeof range.scene.variables.fallbackText === "string" ? range.scene.variables.fallbackText : void 0;
   const template = kit.getTemplate(recoveryTitle ? "chapterTitle" : range.scene.templateId);
   const duration = range.end - range.start;
@@ -283,7 +285,9 @@ function SceneLayer({
       mode: externalVideoBackdrop,
       audioMuted: mediaAudioMuted || !playing,
       audioVolume: mediaAudioVolume,
-      children: /* @__PURE__ */ jsx2(
+      preparingNarration,
+      onMediaError,
+      children: /* @__PURE__ */ jsxs(
         "div",
         {
           "data-scene-layer": layer,
@@ -304,37 +308,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 +363,7 @@ function VideoFrame({
   width,
   height,
   playing = false,
+  preparingNarration = false,
   mediaAudioMuted = true,
   mediaAudioVolume = 1,
   className,
@@ -550,7 +566,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,
@@ -578,11 +596,13 @@ function VideoFrame({
                     kit,
                     config,
                     range: active,
+                    onMediaError: () => markMediaFailed(sceneReadinessKey(active.scene)),
                     progress,
                     motionProgress,
                     width: canvas.width,
                     height: canvas.height,
                     playing,
+                    preparingNarration,
                     mediaAudioMuted,
                     mediaAudioVolume,
                     layer: previewingNext ? "outgoing" : "active",
@@ -604,6 +624,7 @@ function VideoFrame({
                     width: canvas.width,
                     height: canvas.height,
                     playing: false,
+                    preparingNarration: false,
                     mediaAudioMuted,
                     mediaAudioVolume,
                     layer: "incoming",
@@ -622,11 +643,13 @@ function VideoFrame({
                     kit,
                     config,
                     range: active,
+                    onMediaError: () => markMediaFailed(sceneReadinessKey(active.scene)),
                     progress,
                     motionProgress,
                     width: canvas.width,
                     height: canvas.height,
                     playing,
+                    preparingNarration,
                     mediaAudioMuted,
                     mediaAudioVolume,
                     layer: "active",

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

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

package/dist/{cinema-media-APDJS7SC.js → cinema-media-3SIGVVCY.js}

@@ -1,11 +1,11 @@
 import {
   MediaScene,
   MediaSceneTemplate
-} from "./chunk-VQH3JTQC.js";
-import "./chunk-5C6HZNHY.js";
-import "./chunk-77VY4O7A.js";
+} from "./chunk-Z2ZI5G7O.js";
+import "./chunk-QZAZT44G.js";
+import "./chunk-O6FBIB4L.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-TVIU23OM.js";
+import "./chunk-OOBT4X46.js";
 export {
   MediaScene,
   MediaSceneTemplate