@vanillaskyai/video 0.10.7 → 0.10.8

package/dist/{chunk-24TCMDAA.js → chunk-KUCEOG2L.js}

@@ -1,11 +1,11 @@
+import {
+  ExternalVideoBackdropProvider,
+  resolveDensity
+} from "./chunk-5JBMYQP6.js";
 import {
   limitsConcurrentVideoDecoders,
   resolveMediaType
 } from "./chunk-224QNWRA.js";
-import {
-  ExternalVideoBackdropProvider,
-  resolveDensity
-} from "./chunk-OOBT4X46.js";
 import {
   resolveVideoTimeline
 } from "./chunk-SPVTJH3F.js";
@@ -60,8 +60,7 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
           return;
         }
         if (isVideo) {
-          const persistent = root.querySelector("[data-persistent-video-scene-id]");
-          const video = (persistent?.getAttribute("data-persistent-video-scene-id") === scene.id ? persistent : layer)?.querySelector("video");
+          const video = layer.querySelector("video");
           if (video && video.getAttribute("src") === mediaUrl && video.currentSrc === video.src && video.readyState >= 2) {
             if (presented === video) {
               finish(void 0, true);
@@ -116,9 +115,9 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
 import {
   createElement,
   Component,
-  lazy,
   Suspense,
   useState,
+  useRef as useRef2,
   useCallback,
   useEffect as useEffect2,
   useSyncExternalStore
@@ -193,7 +192,6 @@ var SceneBoundary = class extends Component {
   }
 };
 var SCENE_TRANSITION_SECONDS = 0.3;
-var SceneVideoBackdrop = lazy(() => import("./scene-video-backdrop-NK2XK3XE.js").then((module) => ({ default: module.SceneVideoBackdrop })));
 var MEDIA_PREROLL_SECONDS = 1.2;
 var CONTIGUITY_ULP_FACTOR = 4;
 var subscribeToDecoderPolicy = () => () => {
@@ -353,19 +351,25 @@ function VideoFrame({
   className,
   style
 }) {
+  const recoveryRoot = useRef2(null);
+  const reportedFailures = useRef2(/* @__PURE__ */ new Set());
   const [failedMedia, setFailedMedia] = useState(() => /* @__PURE__ */ new Set());
-  const markMediaFailed = useCallback((key) => {
+  const markMediaFailed = useCallback((key, reason = "playback-error") => {
     if (!key || !config.scenes.some((scene) => sceneReadinessKey(scene) === key)) return;
+    if (!reportedFailures.current.has(key)) {
+      reportedFailures.current.add(key);
+      recoveryRoot.current?.dispatchEvent(new CustomEvent("vanillasky:media-recovery", { bubbles: true, detail: { reason: ["decode-error", "frame-readiness-timeout", "stalled-media", "playback-error"].includes(reason) ? reason : "playback-error" } }));
+    }
     setFailedMedia((previous) => previous.has(key) ? previous : /* @__PURE__ */ new Set([...previous, key]));
   }, [config.scenes]);
   useEffect2(() => {
     const currentKeys = new Set(config.scenes.map(sceneReadinessKey));
+    for (const key of reportedFailures.current) if (!currentKeys.has(key)) reportedFailures.current.delete(key);
     setFailedMedia((previous) => {
       const retained = new Set([...previous].filter((key) => currentKeys.has(key)));
       return retained.size === previous.size ? previous : retained;
     });
   }, [config.scenes]);
-  const [readyPersistentVideo, setReadyPersistentVideo] = useState();
   const decoderConstrainedDevice = useDecoderConstraint();
   const timeline = resolveVideoTimeline(config);
   const lastRange = timeline.at(-1);
@@ -419,34 +423,13 @@ function VideoFrame({
   );
   const prerollDuration = prerollsNext ? Math.min(Math.max(MEDIA_PREROLL_SECONDS, blendDuration), Math.max(0, duration)) : blendDuration;
   const prerollStart = active.end - prerollDuration;
+  const boundedPreparation = decoderConstrainedDevice && registrySupportsExternalVideoBackdrop(kit);
   const decoderConstrainedTransition = Boolean(
-    contiguousNext && decoderConstrainedDevice && sceneHasVideoBackdrop(active) && sceneHasVideoBackdrop(contiguousNext)
+    contiguousNext && decoderConstrainedDevice && !boundedPreparation && sceneHasVideoBackdrop(active) && sceneHasVideoBackdrop(contiguousNext)
   );
-  const persistentVideoEnabled = decoderConstrainedDevice && registrySupportsExternalVideoBackdrop(kit);
-  const activeUsesPersistentVideo = persistentVideoEnabled && sceneHasVideoBackdrop(active);
-  const incomingUsesPersistentVideo = Boolean(
-    persistentVideoEnabled && contiguousNext && !sceneHasVideoBackdrop(active) && sceneHasVideoBackdrop(contiguousNext) && time >= prerollStart && time < blendEnd
-  );
-  const persistentVideoRange = activeUsesPersistentVideo ? active : incomingUsesPersistentVideo && contiguousNext ? contiguousNext : void 0;
-  const persistentVideoKey = persistentVideoRange ? `${persistentVideoRange.scene.id}\0${String(persistentVideoRange.scene.variables.mediaUrl || "")}` : void 0;
-  const firstVideoRange = timeline.find(sceneHasVideoBackdrop);
-  const posterPreparationRange = activeUsesPersistentVideo ? contiguousNext && sceneHasVideoBackdrop(contiguousNext) ? contiguousNext : activeIndex === timeline.length - 1 && firstVideoRange?.scene.id !== active.scene.id ? firstVideoRange : void 0 : void 0;
-  const preparedPoster = posterPreparationRange && String(
-    posterPreparationRange.scene.variables.mediaPoster || ""
-  ) ? {
-    presentationKey: `${posterPreparationRange.scene.id}\0${String(
-      posterPreparationRange.scene.variables.mediaUrl || ""
-    )}`,
-    mediaPoster: String(posterPreparationRange.scene.variables.mediaPoster),
-    mediaPosition: String(posterPreparationRange.scene.variables.mediaPosition || "center"),
-    backgroundEffect: posterPreparationRange.scene.backgroundEffect ?? config.style.defaultBackgroundEffect
-  } : void 0;
   const activeMediaFailed = failedMedia.has(sceneReadinessKey(active.scene));
-  const persistentVideoFailed = persistentVideoKey !== void 0 && failedMedia.has(persistentVideoKey);
-  const persistentVideoReady = persistentVideoRange !== void 0 && (String(persistentVideoRange.scene.variables.mediaPoster || "") !== "" || readyPersistentVideo === persistentVideoKey);
-  const persistentVideoMode = persistentVideoFailed ? "fallback" : persistentVideoReady ? "ready" : "pending";
   const mountingNext = Boolean(
-    contiguousNext && !decoderConstrainedTransition && time >= prerollStart && time < blendEnd && (eligibleNextTransition || prerollsNext)
+    contiguousNext && !decoderConstrainedTransition && (boundedPreparation || time >= prerollStart) && time < blendEnd && (eligibleNextTransition || prerollsNext || boundedPreparation && sceneHasVideoBackdrop(contiguousNext))
   );
   const previewingNext = Boolean(
     eligibleNextTransition && time >= blendStart && time < blendEnd
@@ -464,10 +447,15 @@ function VideoFrame({
   return /* @__PURE__ */ jsxs(
     "div",
     {
+      ref: recoveryRoot,
       onErrorCapture: (event) => {
         const target = event.target;
-        if ((target instanceof HTMLVideoElement || target instanceof HTMLImageElement) && target.getAttribute("src") === active.scene.variables.mediaUrl && supportsExternalVideoBackdrop(activeTemplate) && (target.closest("[data-layer-scene-id]")?.getAttribute("data-layer-scene-id") === active.scene.id || target.closest("[data-persistent-video-scene-id]")?.getAttribute("data-persistent-video-scene-id") === active.scene.id)) {
-          markMediaFailed(sceneReadinessKey(active.scene));
+        if (!(target instanceof HTMLVideoElement || target instanceof HTMLImageElement)) return;
+        const ownerId = target.closest("[data-layer-scene-id]")?.getAttribute("data-layer-scene-id");
+        const owner = [active, contiguousNext].find((range) => range?.scene.id === ownerId);
+        const template = owner && kit.getTemplate(owner.scene.templateId);
+        if (owner && template && supportsExternalVideoBackdrop(template) && target.getAttribute("src") === owner.scene.variables.mediaUrl) {
+          markMediaFailed(sceneReadinessKey(owner.scene), "decode-error");
         }
       },
       "data-video-frame": "ready",
@@ -489,7 +477,7 @@ function VideoFrame({
             scene: active.scene,
             playing,
             fallback: activeMediaFailed,
-            onFailure: sceneHasBackdrop(active) && supportsExternalVideoBackdrop(activeTemplate) && !activeMediaFailed ? () => markMediaFailed(sceneReadinessKey(active.scene)) : void 0
+            onFailure: sceneHasBackdrop(active) && supportsExternalVideoBackdrop(activeTemplate) && !activeMediaFailed ? () => markMediaFailed(sceneReadinessKey(active.scene), "frame-readiness-timeout") : void 0
           }
         ),
         /* @__PURE__ */ jsxs(
@@ -520,58 +508,6 @@ function VideoFrame({
                   }
                 }
               ),
-              persistentVideoRange && !persistentVideoFailed && /* @__PURE__ */ jsx2(
-                "div",
-                {
-                  "data-persistent-video-scene-id": persistentVideoRange.scene.id,
-                  "aria-hidden": "true",
-                  style: { position: "absolute", inset: 0, zIndex: 0 },
-                  children: /* @__PURE__ */ jsx2(Suspense, { fallback: String(persistentVideoRange.scene.variables.mediaPoster || "") ? /* @__PURE__ */ jsx2(
-                    "img",
-                    {
-                      src: String(persistentVideoRange.scene.variables.mediaPoster),
-                      alt: "",
-                      "data-video-poster-plane": "loading",
-                      "data-video-poster-visible": "true",
-                      style: {
-                        position: "absolute",
-                        inset: 0,
-                        width: "100%",
-                        height: "100%",
-                        objectFit: "cover",
-                        objectPosition: String(persistentVideoRange.scene.variables.mediaPosition || "center")
-                      }
-                    }
-                  ) : null, children: /* @__PURE__ */ jsx2(
-                    SceneVideoBackdrop,
-                    {
-                      mediaUrl: String(persistentVideoRange.scene.variables.mediaUrl || ""),
-                      mediaPoster: String(persistentVideoRange.scene.variables.mediaPoster || "") || void 0,
-                      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,
-                      retainPoster: true,
-                      persistent: true,
-                      preparedPoster: preparedPoster ? {
-                        ...preparedPoster,
-                        // The image is already decoded and costs no second video
-                        // decoder. Fade it above the outgoing video using the same
-                        // authored transition clock, then reuse that exact DOM image
-                        // as the new source's underlay at the cut.
-                        opacity: decoderConstrainedTransition ? blendProgress : 0
-                      } : void 0,
-                      onReady: () => setReadyPersistentVideo(persistentVideoKey),
-                      onError: () => markMediaFailed(persistentVideoKey)
-                    }
-                  ) })
-                }
-              ),
               mountingNext && contiguousNext ? [
                 /* @__PURE__ */ jsx2(
                   SceneLayer,
@@ -580,7 +516,7 @@ function VideoFrame({
                     kit,
                     config,
                     range: active,
-                    onMediaError: () => markMediaFailed(sceneReadinessKey(active.scene)),
+                    onMediaError: (reason) => markMediaFailed(sceneReadinessKey(active.scene), reason),
                     progress,
                     motionProgress,
                     width: canvas.width,
@@ -593,7 +529,7 @@ function VideoFrame({
                     opacity: 1 - blendProgress,
                     interactive: true,
                     zIndex: 1,
-                    externalVideoBackdrop: activeMediaFailed ? "fallback" : persistentVideoRange?.scene.id === active.scene.id ? persistentVideoMode : false
+                    externalVideoBackdrop: activeMediaFailed ? "fallback" : false
                   },
                   active.scene.id
                 ),
@@ -615,7 +551,8 @@ function VideoFrame({
                     opacity: blendProgress,
                     interactive: false,
                     zIndex: 2,
-                    externalVideoBackdrop: persistentVideoRange?.scene.id === contiguousNext.scene.id ? persistentVideoMode : false
+                    onMediaError: (reason) => markMediaFailed(sceneReadinessKey(contiguousNext.scene), reason),
+                    externalVideoBackdrop: failedMedia.has(sceneReadinessKey(contiguousNext.scene)) ? "fallback" : false
                   },
                   contiguousNext.scene.id
                 )
@@ -627,7 +564,7 @@ function VideoFrame({
                     kit,
                     config,
                     range: active,
-                    onMediaError: () => markMediaFailed(sceneReadinessKey(active.scene)),
+                    onMediaError: (reason) => markMediaFailed(sceneReadinessKey(active.scene), reason),
                     progress,
                     motionProgress,
                     width: canvas.width,
@@ -640,7 +577,7 @@ function VideoFrame({
                     opacity: 1,
                     interactive: true,
                     zIndex: 1,
-                    externalVideoBackdrop: activeMediaFailed ? "fallback" : persistentVideoRange?.scene.id === active.scene.id ? persistentVideoMode : false
+                    externalVideoBackdrop: activeMediaFailed ? "fallback" : false
                   },
                   active.scene.id
                 )

package/dist/{chunk-PMJNBR4F.js → chunk-Q3LPOPHL.js}

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

package/dist/{chunk-MKMCX3AF.js → chunk-R5ZX2LJV.js}

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

package/dist/{cinema-media-BVQFZL3A.js → cinema-media-WUS7CKPC.js}

@@ -1,11 +1,10 @@
 import {
   MediaScene,
   MediaSceneTemplate
-} from "./chunk-PMJNBR4F.js";
-import "./chunk-X4RGAEL5.js";
-import "./chunk-OBRKB7PL.js";
+} from "./chunk-Q3LPOPHL.js";
+import "./chunk-J7EGPURK.js";
+import "./chunk-5JBMYQP6.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-OOBT4X46.js";
 export {
   MediaScene,
   MediaSceneTemplate

package/dist/{comparison-T27C7FSV.js → comparison-T4OYCOH3.js}

@@ -1,16 +1,15 @@
 import {
   EditorialSurface
-} from "./chunk-MKMCX3AF.js";
-import "./chunk-X4RGAEL5.js";
-import "./chunk-OBRKB7PL.js";
+} from "./chunk-R5ZX2LJV.js";
+import "./chunk-J7EGPURK.js";
 import {
   editorialLabel,
   fade
 } from "./chunk-4YM2M62S.js";
+import "./chunk-5JBMYQP6.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/comparison.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{editorial-timeline-JADHHNEV.js → editorial-timeline-JHQZIPNE.js}

@@ -1,13 +1,12 @@
 import {
   EditorialSurface
-} from "./chunk-MKMCX3AF.js";
-import "./chunk-X4RGAEL5.js";
-import "./chunk-OBRKB7PL.js";
+} from "./chunk-R5ZX2LJV.js";
+import "./chunk-J7EGPURK.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";
+import "./chunk-5JBMYQP6.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/editorial-timeline.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{key-figure-TZQWPFMI.js → key-figure-YWN2OBQU.js}

@@ -1,16 +1,15 @@
 import {
   EditorialSurface
-} from "./chunk-MKMCX3AF.js";
-import "./chunk-X4RGAEL5.js";
-import "./chunk-OBRKB7PL.js";
+} from "./chunk-R5ZX2LJV.js";
+import "./chunk-J7EGPURK.js";
 import {
   editorialLabel,
   fade
 } from "./chunk-4YM2M62S.js";
+import "./chunk-5JBMYQP6.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/key-figure.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{mobile-message-GADX632R.js → mobile-message-CDKOERRZ.js}

@@ -1,15 +1,14 @@
 import {
   MediaScene
-} from "./chunk-PMJNBR4F.js";
-import "./chunk-X4RGAEL5.js";
+} from "./chunk-Q3LPOPHL.js";
 import {
   spring
-} from "./chunk-OBRKB7PL.js";
+} from "./chunk-J7EGPURK.js";
 import {
   editorialFont
 } from "./chunk-4YM2M62S.js";
+import "./chunk-5JBMYQP6.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/mobile-message.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{quote-FRCEC34C.js → quote-JKABOMIG.js}

@@ -1,15 +1,14 @@
 import {
   EditorialSurface
-} from "./chunk-MKMCX3AF.js";
-import "./chunk-X4RGAEL5.js";
-import "./chunk-OBRKB7PL.js";
+} from "./chunk-R5ZX2LJV.js";
+import "./chunk-J7EGPURK.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";
+import "./chunk-5JBMYQP6.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/quote.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/react.js

@@ -40,9 +40,9 @@ import {
   VideoFrame,
   getDimensions,
   sceneReadinessKey
-} from "./chunk-24TCMDAA.js";
+} from "./chunk-KUCEOG2L.js";
+import "./chunk-5JBMYQP6.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-OOBT4X46.js";
 import {
   getVideoDuration,
   resolveVideoTimeline
@@ -94,13 +94,13 @@ import { createElement } from "react";
 
 // src/visual-system/catalog/builtin-loaders.generated.ts
 var GENERATED_BUILTIN_TEMPLATE_LOADERS = {
-  "cinemaMedia": () => import("./cinema-media-BVQFZL3A.js").then((module) => ({ default: module.MediaSceneTemplate })),
+  "cinemaMedia": () => import("./cinema-media-WUS7CKPC.js").then((module) => ({ default: module.MediaSceneTemplate })),
   "chapterTitle": () => import("./chapter-title-2JVDU62E.js").then((module) => ({ default: module.TitleSceneTemplate })),
-  "editorialTimeline": () => import("./editorial-timeline-JADHHNEV.js").then((module) => ({ default: module.TimelineSceneTemplate })),
-  "mobileMessage": () => import("./mobile-message-GADX632R.js").then((module) => ({ default: module.NotificationSceneTemplate })),
-  "comparison": () => import("./comparison-T27C7FSV.js").then((module) => ({ default: module.ComparisonSceneTemplate })),
-  "quote": () => import("./quote-FRCEC34C.js").then((module) => ({ default: module.QuoteSceneTemplate })),
-  "keyFigure": () => import("./key-figure-TZQWPFMI.js").then((module) => ({ default: module.KeyFigureSceneTemplate }))
+  "editorialTimeline": () => import("./editorial-timeline-JHQZIPNE.js").then((module) => ({ default: module.TimelineSceneTemplate })),
+  "mobileMessage": () => import("./mobile-message-CDKOERRZ.js").then((module) => ({ default: module.NotificationSceneTemplate })),
+  "comparison": () => import("./comparison-T4OYCOH3.js").then((module) => ({ default: module.ComparisonSceneTemplate })),
+  "quote": () => import("./quote-JKABOMIG.js").then((module) => ({ default: module.QuoteSceneTemplate })),
+  "keyFigure": () => import("./key-figure-YWN2OBQU.js").then((module) => ({ default: module.KeyFigureSceneTemplate }))
 };
 
 // src/visual-system/catalog/builtin-player.generated.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.7",
+  "version": "0.10.8",
   "description": "Open-source voice-and-video chat SDK for AI applications.",
   "keywords": [
     "video-chat",

package/registry/items/backgrounds.json

@@ -28,7 +28,7 @@
       "path": "src/visual-system/scene-templates/external-video-backdrop.tsx",
       "type": "registry:lib",
       "target": "vanillasky/scene-templates/external-video-backdrop.tsx",
-      "content": "import React from \"react\";\n\n// Source-owned templates may live in a consumer's tree while VideoFrame comes\n// from the package. Both copies must observe the same internal context or the\n// consumer template would mount a second video over the player-owned plane,\n// and would never inherit the player's native media audio state.\nexport type ExternalVideoBackdropMode = false | \"pending\" | \"ready\" | \"fallback\";\n\ninterface BackdropContextValue {\n  mode: ExternalVideoBackdropMode;\n  audioMuted: boolean;\n  audioVolume: number;\n  preparingNarration?: boolean;\n  onMediaError?: () => void;\n}\n\nconst DEFAULT: BackdropContextValue = { mode: false, audioMuted: true, audioVolume: 1 };\n\nconst sharedContext = globalThis as typeof globalThis & {\n  __vanillaskyVideoBackdropContext?: React.Context<BackdropContextValue>;\n};\nconst BackdropContext = sharedContext.__vanillaskyVideoBackdropContext\n  ??= React.createContext<BackdropContextValue>(DEFAULT);\n\nexport function ExternalVideoBackdropProvider({\n  mode,\n  audioMuted = true,\n  audioVolume = 1,\n  preparingNarration = false,\n  onMediaError,\n  children,\n}: {\n  mode: ExternalVideoBackdropMode;\n  audioMuted?: boolean;\n  audioVolume?: number;\n  preparingNarration?: boolean;\n  onMediaError?: () => void;\n  children: React.ReactNode;\n}) {\n  const value = React.useMemo(\n    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),\n    [mode, audioMuted, audioVolume, preparingNarration, onMediaError],\n  );\n  return (\n    <BackdropContext.Provider value={value}>\n      {children}\n    </BackdropContext.Provider>\n  );\n}\n\nexport function useExternalVideoBackdrop(): ExternalVideoBackdropMode {\n  return React.useContext(BackdropContext).mode;\n}\n\nexport function useMediaAudio(): { muted: boolean; volume: number } {\n  const { audioMuted, audioVolume } = React.useContext(BackdropContext);\n  return { muted: audioMuted, volume: audioVolume };\n}\n\n/** Internal first-frame priming state; an explicit viewer pause never sets it. */\nexport function useNarrationPreroll(): boolean {\n  return React.useContext(BackdropContext).preparingNarration === true;\n}\n\n/** Routes local decoder/playback failures to the scene-owned recovery surface. */\nexport function useMediaFailure(): (() => void) | undefined {\n  return React.useContext(BackdropContext).onMediaError;\n}\n"
+      "content": "import React from \"react\";\n\n// Source-owned templates may live in a consumer's tree while VideoFrame comes\n// from the package. Both copies must observe the same internal context or the\n// consumer template would mount a second video over the player-owned plane,\n// and would never inherit the player's native media audio state.\nexport type ExternalVideoBackdropMode = false | \"pending\" | \"ready\" | \"fallback\";\n\nexport type MediaRecoveryReason = \"decode-error\" | \"frame-readiness-timeout\" | \"stalled-media\" | \"playback-error\";\n\ninterface BackdropContextValue {\n  mode: ExternalVideoBackdropMode;\n  audioMuted: boolean;\n  audioVolume: number;\n  preparingNarration?: boolean;\n  onMediaError?: (reason?: MediaRecoveryReason) => void;\n}\n\nconst DEFAULT: BackdropContextValue = { mode: false, audioMuted: true, audioVolume: 1 };\n\nconst sharedContext = globalThis as typeof globalThis & {\n  __vanillaskyVideoBackdropContext?: React.Context<BackdropContextValue>;\n};\nconst BackdropContext = sharedContext.__vanillaskyVideoBackdropContext\n  ??= React.createContext<BackdropContextValue>(DEFAULT);\n\nexport function ExternalVideoBackdropProvider({\n  mode,\n  audioMuted = true,\n  audioVolume = 1,\n  preparingNarration = false,\n  onMediaError,\n  children,\n}: {\n  mode: ExternalVideoBackdropMode;\n  audioMuted?: boolean;\n  audioVolume?: number;\n  preparingNarration?: boolean;\n  onMediaError?: (reason?: MediaRecoveryReason) => void;\n  children: React.ReactNode;\n}) {\n  const value = React.useMemo(\n    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),\n    [mode, audioMuted, audioVolume, preparingNarration, onMediaError],\n  );\n  return (\n    <BackdropContext.Provider value={value}>\n      {children}\n    </BackdropContext.Provider>\n  );\n}\n\nexport function useExternalVideoBackdrop(): ExternalVideoBackdropMode {\n  return React.useContext(BackdropContext).mode;\n}\n\nexport function useMediaAudio(): { muted: boolean; volume: number } {\n  const { audioMuted, audioVolume } = React.useContext(BackdropContext);\n  return { muted: audioMuted, volume: audioVolume };\n}\n\n/** Internal first-frame priming state; an explicit viewer pause never sets it. */\nexport function useNarrationPreroll(): boolean {\n  return React.useContext(BackdropContext).preparingNarration === true;\n}\n\n/** Routes local decoder/playback failures to the scene-owned recovery surface. */\nexport function useMediaFailure(): ((reason?: MediaRecoveryReason) => void) | undefined {\n  return React.useContext(BackdropContext).onMediaError;\n}\n"
     },
     {
       "path": "src/visual-system/scene-templates/media-position.ts",
@@ -40,7 +40,7 @@
       "path": "src/visual-system/scene-templates/scene-video-backdrop.tsx",
       "type": "registry:lib",
       "target": "vanillasky/scene-templates/scene-video-backdrop.tsx",
-      "content": "import React, { useCallback, useEffect, useRef, useState } from \"react\";\nimport { getBackgroundTransform } from \"../backgrounds\";\nimport { useMediaAudio, useMediaFailure, useNarrationPreroll } from \"./external-video-backdrop\";\nimport { resolveMediaPosition } from \"./media-position\";\n\nexport interface SceneVideoBackdropProps {\n  mediaUrl: string;\n  mediaPoster?: string;\n  mediaPosition?: string;\n  backgroundEffect?: string;\n  progress: number;\n  /** Narration-led visible duration; muted or pitch-preserving footage may be gently retimed. */\n  sceneDuration?: number;\n  /** Internal player-owned decoder priming, distinct from viewer pause. */\n  preparingNarration?: boolean;\n  beatIntensity?: number;\n  isPlaying: boolean;\n  muted?: boolean;\n  volume?: number;\n  playbackId?: string;\n  retainPoster?: boolean;\n  persistent?: boolean;\n  preparedPoster?: {\n    presentationKey: string;\n    mediaPoster: string;\n    mediaPosition: string;\n    backgroundEffect?: string;\n    /** Existing global transition progress. On decoder-constrained Safari,\n     * this fades the decoded incoming still above the outgoing video before\n     * the single video element changes source. */\n    opacity?: number;\n  };\n  onReady?: () => void;\n  onError?: () => void;\n}\n\nexport const SceneVideoBackdrop: React.FC<SceneVideoBackdropProps> = ({\n  mediaUrl,\n  mediaPoster,\n  mediaPosition = \"center\",\n  backgroundEffect,\n  progress,\n  sceneDuration,\n  preparingNarration = false,\n  beatIntensity = 0,\n  isPlaying,\n  muted,\n  volume,\n  playbackId = mediaUrl,\n  retainPoster = false,\n  persistent = false,\n  preparedPoster,\n  onReady,\n  onError,\n}) => {\n  const inheritedAudio = useMediaAudio();\n  const reportMediaFailure = useMediaFailure();\n  const inheritedPreroll = useNarrationPreroll();\n  const rewindPreroll = preparingNarration || inheritedPreroll;\n  const resolvedMuted = muted ?? inheritedAudio.muted;\n  const resolvedVolume = volume ?? inheritedAudio.volume;\n  const resolvedPosition = resolveMediaPosition(mediaPosition);\n  const bgTransform = getBackgroundTransform(backgroundEffect, progress, beatIntensity);\n  const [decodedVideoUrl, setDecodedVideoUrl] = useState<string>();\n  const [waitingKey, setWaitingKey] = useState<string>();\n  const [exhaustedKey, setExhaustedKey] = useState<string>();\n\n  const videoRef = useRef<HTMLVideoElement>(null);\n  const presentedVideoUrl = useRef<string | undefined>(undefined);\n  const startedVideoUrl = useRef<string | undefined>(undefined);\n  const startedPlaybackId = useRef<string | undefined>(undefined);\n  const videoPresentationKey = `${playbackId}\\0${mediaUrl}`;\n\n  const presentationRef = useRef({ key: videoPresentationKey, playing: isPlaying });\n  presentationRef.current = { key: videoPresentationKey, playing: isPlaying };\n  const unavailable = () => {\n    if (presentationRef.current.key === videoPresentationKey && presentationRef.current.playing) {\n      setExhaustedKey(videoPresentationKey);\n      onError?.();\n      reportMediaFailure?.();\n    }\n  };\n  useEffect(() => {\n    if (!isPlaying || waitingKey !== videoPresentationKey) {\n      if (waitingKey) setWaitingKey(undefined);\n      return;\n    }\n    const video = videoRef.current;\n    if (!video) return;\n    const expectedSource = video.getAttribute(\"src\") === mediaUrl ? video.src : undefined;\n    let awaitingFirstFrame = presentedVideoUrl.current !== mediaUrl || video.currentSrc !== expectedSource;\n    let previousTime = video.currentTime;\n    let forwardFrames = 0;\n    let stopped = false;\n    let frame: number | undefined;\n    let poll: ReturnType<typeof setTimeout> | undefined;\n    const observe = (_now?: number, metadata?: VideoFrameCallbackMetadata) => {\n      if (stopped) return;\n      const currentSource = video.currentSrc === expectedSource;\n      if (currentSource && awaitingFirstFrame && (metadata || presentedVideoUrl.current === mediaUrl)) {\n        awaitingFirstFrame = false;\n        clearTimeout(deadline);\n        deadline = setTimeout(fail, 1000);\n      }\n      const time = metadata?.mediaTime ?? video.currentTime;\n      if (!currentSource || video.seeking || time < previousTime) forwardFrames = 0;\n      else if (time > previousTime + .001) forwardFrames++;\n      previousTime = time;\n      // One seek frame is not resumed motion. Require consecutive forward\n      // observations before releasing the original bounded stall deadline.\n      if (forwardFrames >= 2) {\n        stopped = true;\n        clearTimeout(deadline);\n        setWaitingKey(undefined);\n        return;\n      }\n      if (video.requestVideoFrameCallback) frame = video.requestVideoFrameCallback(observe);\n      else poll = setTimeout(observe, 50);\n    };\n    // A seek can emit waiting without another playing event, even while frames\n    // resume. Keep the decoder visible and observe motion directly. A real\n    // stall gets the player's authored chapter instead of an endless spinner.\n    const fail = () => { if (!stopped) { stopped = true; unavailable(); } };\n    // Initial network/decode work has the same bound as mounted readiness.\n    // Only a source that has presented a frame can be judged as stalled motion.\n    let deadline = setTimeout(fail, awaitingFirstFrame ? 8000 : 1000);\n    observe();\n    return () => {\n      stopped = true;\n      clearTimeout(deadline);\n      clearTimeout(poll);\n      if (frame !== undefined) video.cancelVideoFrameCallback?.(frame);\n    };\n  }, [waitingKey, videoPresentationKey, isPlaying]);\n\n  const fitDuration = useCallback((video: HTMLVideoElement) => {\n    // Allow a small decode-to-speech onset margin without changing narration.\n    video.playbackRate = (resolvedMuted || video.preservesPitch === true) && sceneDuration && Number.isFinite(video.duration) && video.duration > 0\n      ? Math.max(.75, Math.min(1, video.duration / (sceneDuration + .2))) : 1;\n  }, [resolvedMuted, sceneDuration]);\n  useEffect(() => {\n    if (videoRef.current) fitDuration(videoRef.current);\n  }, [fitDuration]);\n  const continueMotion = (video: HTMLVideoElement) => {\n    if (!isPlaying) return;\n    // The finite scene clock bounds silent coverage. Speech may outlast a\n    // short clip; repeat motion until the scene ends, never audible dialogue.\n    if (!resolvedMuted) {\n      unavailable();\n      return;\n    }\n    video.currentTime = 0;\n    void video.play().catch(unavailable);\n  };\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    // React Strict Mode rehearses setup → cleanup → setup in development.\n    // The cleanup deliberately releases the decoder, so the repeated setup\n    // must restore the declarative source before the playback effect runs.\n    if (video.getAttribute(\"src\") !== mediaUrl) {\n      video.setAttribute(\"src\", mediaUrl);\n      video.load();\n    }\n  }, [mediaUrl]);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    // A source change already starts a native load via React's src update.\n    // Tear down the decoder only on unmount, never cancel that new request.\n    return () => {\n      video.pause();\n      video.removeAttribute(\"src\");\n      video.load();\n      startedVideoUrl.current = undefined;\n      startedPlaybackId.current = undefined;\n    };\n  }, []);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (video) video.volume = resolvedVolume;\n  }, [resolvedVolume]);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    if (!isPlaying) {\n      video.pause();\n      if (rewindPreroll && video.currentTime > 0) video.currentTime = 0;\n      return;\n    }\n    if (startedPlaybackId.current === playbackId) {\n      if (video.ended) continueMotion(video);\n      else void video.play().catch(unavailable);\n      return;\n    }\n    const changingSource = startedVideoUrl.current !== undefined && startedVideoUrl.current !== mediaUrl;\n    fitDuration(video);\n    if (!changingSource && video.currentTime > 0) video.currentTime = 0;\n    video.play().catch(unavailable);\n    startedVideoUrl.current = mediaUrl;\n    startedPlaybackId.current = playbackId;\n  }, [isPlaying, mediaUrl, playbackId, rewindPreroll]);\n\n  const mediaStyle: React.CSSProperties = {\n    position: \"absolute\",\n    inset: 0,\n    width: \"100%\",\n    height: \"100%\",\n    objectFit: \"cover\",\n    objectPosition: resolvedPosition,\n    transform: bgTransform.transform,\n    transformOrigin: bgTransform.transformOrigin,\n    zIndex: persistent ? 1 : undefined,\n  };\n  const preparedPosition = preparedPoster\n    ? resolveMediaPosition(preparedPoster.mediaPosition)\n    : resolvedPosition;\n  const preparedTransform = getBackgroundTransform(preparedPoster?.backgroundEffect, 0, 0);\n  const posterPlanes = [\n    ...(persistent && mediaPoster ? [{\n      presentationKey: videoPresentationKey,\n      mediaPoster,\n      mediaPosition: resolvedPosition,\n      transform: bgTransform.transform,\n      transformOrigin: bgTransform.transformOrigin,\n      opacity: 1,\n      zIndex: 0,\n      role: \"current\",\n    }] : []),\n    ...(preparedPoster && preparedPoster.presentationKey !== videoPresentationKey ? [{\n      presentationKey: preparedPoster.presentationKey,\n      mediaPoster: preparedPoster.mediaPoster,\n      mediaPosition: preparedPosition,\n      transform: preparedTransform.transform,\n      transformOrigin: preparedTransform.transformOrigin,\n      opacity: preparedPoster.opacity ?? 0,\n      zIndex: 2,\n      role: \"prepared\",\n    }] : []),\n  ];\n\n  return (\n    <>\n      {posterPlanes.map((posterPlane) => (\n        <img\n          key={posterPlane.presentationKey}\n          src={posterPlane.mediaPoster}\n          alt=\"\"\n          aria-hidden=\"true\"\n          draggable={false}\n          data-video-poster-plane={posterPlane.role}\n          data-video-poster-visible={posterPlane.opacity > 0 ? \"true\" : \"false\"}\n          style={{\n            position: \"absolute\",\n            inset: 0,\n            width: \"100%\",\n            height: \"100%\",\n            objectFit: \"cover\",\n            objectPosition: posterPlane.mediaPosition,\n            transform: posterPlane.transform,\n            transformOrigin: posterPlane.transformOrigin,\n            zIndex: posterPlane.zIndex,\n            opacity: posterPlane.opacity,\n            pointerEvents: \"none\",\n          }}\n        />\n      ))}\n      {exhaustedKey === videoPresentationKey && <div\n        role=\"status\" data-media-continuity=\"exhausted\"\n        style={{ position: \"absolute\", inset: 0, zIndex: 3, background: \"#000\", color: \"#bbb\", display: \"grid\", placeContent: \"center\", font: \"14px system-ui\" }}\n      >Visual unavailable</div>}\n      <video\n        ref={videoRef}\n        src={mediaUrl}\n        poster={retainPoster || decodedVideoUrl !== mediaUrl ? mediaPoster || undefined : undefined}\n        muted={resolvedMuted}\n        loop={false}\n        playsInline\n        preload=\"auto\"\n        onLoadedMetadata={event => fitDuration(event.currentTarget)}\n        onEnded={event => continueMotion(event.currentTarget)}\n        onWaiting={() => { if (isPlaying) setWaitingKey(videoPresentationKey); }}\n        onLoadedData={(event) => {\n          const video = event.currentTarget;\n          const markPresented = () => {\n            if (!video.isConnected || presentationRef.current.key !== videoPresentationKey\n              || video.getAttribute(\"src\") !== mediaUrl || video.currentSrc !== video.src) return;\n            presentedVideoUrl.current = mediaUrl;\n            video.dispatchEvent(new Event(\"vanillasky:video-frame-presented\", { bubbles: true }));\n            onReady?.();\n            if (!retainPoster) setDecodedVideoUrl(mediaUrl);\n          };\n          if (video.requestVideoFrameCallback) {\n            video.requestVideoFrameCallback(markPresented);\n            return;\n          }\n          markPresented();\n        }}\n        onError={onError}\n        data-media-position={mediaPosition}\n        data-video-backdrop={persistent ? \"persistent\" : \"scene\"}\n        style={{ ...mediaStyle, visibility: exhaustedKey === videoPresentationKey ? \"hidden\" : undefined }}\n      />\n    </>\n  );\n};\n"
+      "content": "import React, { useCallback, useEffect, useRef, useState } from \"react\";\nimport { getBackgroundTransform } from \"../backgrounds\";\nimport { type MediaRecoveryReason, useMediaAudio, useMediaFailure, useNarrationPreroll } from \"./external-video-backdrop\";\nimport { resolveMediaPosition } from \"./media-position\";\n\nexport interface SceneVideoBackdropProps {\n  mediaUrl: string;\n  mediaPoster?: string;\n  mediaPosition?: string;\n  backgroundEffect?: string;\n  progress: number;\n  /** Narration-led visible duration; muted or pitch-preserving footage may be gently retimed. */\n  sceneDuration?: number;\n  /** Internal player-owned decoder priming, distinct from viewer pause. */\n  preparingNarration?: boolean;\n  beatIntensity?: number;\n  isPlaying: boolean;\n  muted?: boolean;\n  volume?: number;\n  playbackId?: string;\n  onReady?: () => void;\n  onError?: () => void;\n}\n\nexport const SceneVideoBackdrop: React.FC<SceneVideoBackdropProps> = ({\n  mediaUrl,\n  mediaPoster,\n  mediaPosition = \"center\",\n  backgroundEffect,\n  progress,\n  sceneDuration,\n  preparingNarration = false,\n  beatIntensity = 0,\n  isPlaying,\n  muted,\n  volume,\n  playbackId = mediaUrl,\n  onReady,\n  onError,\n}) => {\n  const inheritedAudio = useMediaAudio();\n  const reportMediaFailure = useMediaFailure();\n  const inheritedPreroll = useNarrationPreroll();\n  const rewindPreroll = preparingNarration || inheritedPreroll;\n  const resolvedMuted = muted ?? inheritedAudio.muted;\n  const resolvedVolume = volume ?? inheritedAudio.volume;\n  const resolvedPosition = resolveMediaPosition(mediaPosition);\n  const bgTransform = getBackgroundTransform(backgroundEffect, progress, beatIntensity);\n  const [decodedVideoUrl, setDecodedVideoUrl] = useState<string>();\n  const [waitingKey, setWaitingKey] = useState<string>();\n  const [exhaustedKey, setExhaustedKey] = useState<string>();\n\n  const videoRef = useRef<HTMLVideoElement>(null);\n  const presentedVideoUrl = useRef<string | undefined>(undefined);\n  const startedVideoUrl = useRef<string | undefined>(undefined);\n  const startedPlaybackId = useRef<string | undefined>(undefined);\n  const videoPresentationKey = `${playbackId}\\0${mediaUrl}`;\n\n  const presentationRef = useRef({ key: videoPresentationKey, playing: isPlaying });\n  presentationRef.current = { key: videoPresentationKey, playing: isPlaying };\n  const unavailable = (reason: MediaRecoveryReason = \"playback-error\") => {\n    if (presentationRef.current.key === videoPresentationKey && presentationRef.current.playing) {\n      setExhaustedKey(videoPresentationKey);\n      onError?.();\n      reportMediaFailure?.(reason);\n    }\n  };\n  useEffect(() => {\n    if (!isPlaying || waitingKey !== videoPresentationKey) {\n      if (waitingKey) setWaitingKey(undefined);\n      return;\n    }\n    const video = videoRef.current;\n    if (!video) return;\n    const expectedSource = video.getAttribute(\"src\") === mediaUrl ? video.src : undefined;\n    let awaitingFirstFrame = presentedVideoUrl.current !== mediaUrl || video.currentSrc !== expectedSource;\n    let previousTime = video.currentTime;\n    let forwardFrames = 0;\n    let stopped = false;\n    let frame: number | undefined;\n    let poll: ReturnType<typeof setTimeout> | undefined;\n    const observe = (_now?: number, metadata?: VideoFrameCallbackMetadata) => {\n      if (stopped) return;\n      const currentSource = video.currentSrc === expectedSource;\n      if (currentSource && awaitingFirstFrame && (metadata || presentedVideoUrl.current === mediaUrl)) {\n        awaitingFirstFrame = false;\n        clearTimeout(deadline);\n        deadline = setTimeout(fail, 1000);\n      }\n      const time = metadata?.mediaTime ?? video.currentTime;\n      if (!currentSource || video.seeking || time < previousTime) forwardFrames = 0;\n      else if (time > previousTime + .001) forwardFrames++;\n      previousTime = time;\n      // One seek frame is not resumed motion. Require consecutive forward\n      // observations before releasing the original bounded stall deadline.\n      if (forwardFrames >= 2) {\n        stopped = true;\n        clearTimeout(deadline);\n        setWaitingKey(undefined);\n        return;\n      }\n      if (video.requestVideoFrameCallback) frame = video.requestVideoFrameCallback(observe);\n      else poll = setTimeout(observe, 50);\n    };\n    // A seek can emit waiting without another playing event, even while frames\n    // resume. Keep the decoder visible and observe motion directly. A real\n    // stall gets the player's authored chapter instead of an endless spinner.\n    const fail = () => { if (!stopped) { stopped = true; unavailable(awaitingFirstFrame ? \"frame-readiness-timeout\" : \"stalled-media\"); } };\n    // Initial network/decode work has the same bound as mounted readiness.\n    // Only a source that has presented a frame can be judged as stalled motion.\n    let deadline = setTimeout(fail, awaitingFirstFrame ? 8000 : 1000);\n    observe();\n    return () => {\n      stopped = true;\n      clearTimeout(deadline);\n      clearTimeout(poll);\n      if (frame !== undefined) video.cancelVideoFrameCallback?.(frame);\n    };\n  }, [waitingKey, videoPresentationKey, isPlaying]);\n\n  const onReadyRef = useRef(onReady);\n  onReadyRef.current = onReady;\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    let stopped = false;\n    let frame: number | undefined;\n    const markPresented = () => {\n      if (stopped || !video.isConnected || presentationRef.current.key !== videoPresentationKey\n        || video.getAttribute(\"src\") !== mediaUrl || video.currentSrc !== video.src) return false;\n      presentedVideoUrl.current = mediaUrl;\n      video.dispatchEvent(new Event(\"vanillasky:video-frame-presented\", { bubbles: true }));\n      onReadyRef.current?.();\n      setDecodedVideoUrl(mediaUrl);\n      stopped = true;\n      return true;\n    };\n    const observe = () => {\n      if (stopped || frame !== undefined) return;\n      if (video.requestVideoFrameCallback) {\n        frame = video.requestVideoFrameCallback(() => {\n          frame = undefined;\n          if (!markPresented()) observe();\n        });\n      } else if (video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) markPresented();\n    };\n    // A cached resource can finish loading while its Suspense tree is still\n    // detached. Observe the mounted frame even if loadeddata was missed.\n    video.addEventListener(\"loadeddata\", observe);\n    observe();\n    return () => {\n      stopped = true;\n      video.removeEventListener(\"loadeddata\", observe);\n      if (frame !== undefined) video.cancelVideoFrameCallback?.(frame);\n    };\n  }, [mediaUrl, videoPresentationKey]);\n\n  const fitDuration = useCallback((video: HTMLVideoElement) => {\n    // Allow a small decode-to-speech onset margin without changing narration.\n    video.playbackRate = (resolvedMuted || video.preservesPitch === true) && sceneDuration && Number.isFinite(video.duration) && video.duration > 0\n      ? Math.max(.75, Math.min(1, video.duration / (sceneDuration + .2))) : 1;\n  }, [resolvedMuted, sceneDuration]);\n  useEffect(() => {\n    if (videoRef.current) fitDuration(videoRef.current);\n  }, [fitDuration]);\n  const continueMotion = (video: HTMLVideoElement) => {\n    if (!isPlaying) return;\n    // The finite scene clock bounds silent coverage. Speech may outlast a\n    // short clip; repeat motion until the scene ends, never audible dialogue.\n    if (!resolvedMuted) {\n      unavailable();\n      return;\n    }\n    video.currentTime = 0;\n    void video.play().catch(() => unavailable());\n  };\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    // React Strict Mode rehearses setup → cleanup → setup in development.\n    // The cleanup deliberately releases the decoder, so the repeated setup\n    // must restore the declarative source before the playback effect runs.\n    if (video.getAttribute(\"src\") !== mediaUrl) {\n      video.setAttribute(\"src\", mediaUrl);\n      video.load();\n    }\n  }, [mediaUrl]);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    // A source change already starts a native load via React's src update.\n    // Tear down the decoder only on unmount, never cancel that new request.\n    return () => {\n      video.pause();\n      video.removeAttribute(\"src\");\n      video.load();\n      startedVideoUrl.current = undefined;\n      startedPlaybackId.current = undefined;\n    };\n  }, []);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (video) video.volume = resolvedVolume;\n  }, [resolvedVolume]);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    if (!isPlaying) {\n      video.pause();\n      if (rewindPreroll && video.currentTime > 0) video.currentTime = 0;\n      return;\n    }\n    if (startedPlaybackId.current === playbackId) {\n      if (video.ended) continueMotion(video);\n      else void video.play().catch(() => unavailable());\n      return;\n    }\n    const changingSource = startedVideoUrl.current !== undefined && startedVideoUrl.current !== mediaUrl;\n    fitDuration(video);\n    if (!changingSource && video.currentTime > 0) video.currentTime = 0;\n    video.play().catch(() => unavailable());\n    startedVideoUrl.current = mediaUrl;\n    startedPlaybackId.current = playbackId;\n  }, [isPlaying, mediaUrl, playbackId, rewindPreroll]);\n\n  const enforceRequestedPause = (event: React.SyntheticEvent<HTMLVideoElement>) => {\n    // WebKit may enter playback without a playing event while seeking or\n    // waiting. Both native start events must honor the latest requested hold.\n    if (presentationRef.current.playing) return;\n    event.currentTarget.pause();\n    if (rewindPreroll && event.currentTarget.currentTime > 0) event.currentTarget.currentTime = 0;\n  };\n\n  const mediaStyle: React.CSSProperties = {\n    position: \"absolute\",\n    inset: 0,\n    width: \"100%\",\n    height: \"100%\",\n    objectFit: \"cover\",\n    objectPosition: resolvedPosition,\n    transform: bgTransform.transform,\n    transformOrigin: bgTransform.transformOrigin,\n  };\n  return (\n    <>\n      {exhaustedKey === videoPresentationKey && <div\n        role=\"status\" data-media-continuity=\"exhausted\"\n        style={{ position: \"absolute\", inset: 0, zIndex: 3, background: \"#000\", color: \"#bbb\", display: \"grid\", placeContent: \"center\", font: \"14px system-ui\" }}\n      >Visual unavailable</div>}\n      <video\n        ref={videoRef}\n        src={mediaUrl}\n        poster={decodedVideoUrl !== mediaUrl ? mediaPoster || undefined : undefined}\n        muted={resolvedMuted}\n        loop={false}\n        playsInline\n        preload=\"auto\"\n        onLoadedMetadata={event => fitDuration(event.currentTarget)}\n        onEnded={event => continueMotion(event.currentTarget)}\n        onPlay={enforceRequestedPause}\n        onPlaying={enforceRequestedPause}\n        onWaiting={() => { if (isPlaying) setWaitingKey(videoPresentationKey); }}\n        onError={onError}\n        data-media-position={mediaPosition}\n        data-video-backdrop=\"scene\"\n        style={{ ...mediaStyle, visibility: exhaustedKey === videoPresentationKey ? \"hidden\" : undefined }}\n      />\n    </>\n  );\n};\n"
     },
     {
       "path": "src/visual-system/scene-templates/color-utils.ts",

package/starters/video-chat/README.md

@@ -49,15 +49,11 @@ call. A template introduction starts while footage prepares; body shots contain
 moving footage, narration and subtitles. Intent changes the visible actions and
 pacing, not the rendering pipeline.
 
-The SDK tries generated footage first, then relevant approved stock when the
-provider is unavailable, denied, or fails. Attempts, including failures, share
-the host's `maxGeneratedVideos` ceiling. A stock miss never broadens the subject
-automatically. If no relevant footage is available, narration and subtitles
-continue as authored chapter scenes.
-
 Choose AI video or Pexels in Settings. Each mode uses only its selected footage
-provider, and both use chapter scenes when footage cannot be prepared. The
-Pexels adapter searches the full catalog with bounded subject matching,
+provider, and both use chapter scenes when footage cannot be prepared. AI video
+attempts, including failures, share the host's `maxGeneratedVideos` ceiling.
+Exhausted allowance recovers directly to authored chapters without stock calls.
+The Pexels adapter searches the full catalog with bounded subject matching,
 orientation selection and caching; it no longer requires a reviewed index.
 Custom interfaces must display a prominent [Pexels](https://www.pexels.com) credit.
 

package/starters/video-chat/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@vanillaskyai/video": "0.10.7",
+    "@vanillaskyai/video": "0.10.8",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "@ai-sdk/anthropic": "^3.0.0",

package/starters/video-chat/server.ts

@@ -25,11 +25,6 @@ export const handleVideoChat = createVideoChatHandler({
         output_config: { effort: "medium" },
       },
     },
-    onFinish: ({ finishReason, text }) => {
-      if (finishReason !== "stop") console.warn(`[planner] ${finishReason}: ${text.slice(0, 300)}`);
-      const keyed = (text.match(/"mediaKeyword"/g) ?? []).length;
-      console.log(`[planner] ${(text.match(/"scene\.add"/g) ?? []).length} scenes, ${keyed} asked for footage`);
-    },
   }),
   generateText: async ({ systemPrompt, userPrompt, maxOutputTokens, signal }) => {
     const { text } = await generateText({