@vanillaskyai/video 0.10.7 → 0.10.9

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/dist/server.js

@@ -895,6 +895,21 @@ var object = (value) => value && typeof value === "object" && !Array.isArray(val
 function text(value, maximum) {
   return typeof value === "string" && value.trim().length <= maximum ? value.trim() : "";
 }
+function readStockSelection(value) {
+  const item = object(value);
+  const phrase = (candidate) => {
+    if (typeof candidate !== "string") return;
+    const normalized = candidate.trim().replace(/\s+/gu, " ");
+    if (!normalized || normalized.length > 48 || !/^[\p{L}\p{N} '’-]+$/u.test(normalized)) return;
+    const words = normalized.match(/[\p{L}\p{N}]+/gu) ?? [];
+    return words.length >= 1 && words.length <= 4 ? normalized : void 0;
+  };
+  const subject = phrase(item?.subject);
+  if (!subject) return;
+  const activity = phrase(item?.activity), equipment = phrase(item?.equipment);
+  const exclude = Array.isArray(item?.exclude) && item.exclude.length <= 3 ? item.exclude.map(phrase).filter((value2) => value2 !== void 0) : [];
+  return { subject, ...activity ? { activity } : {}, ...equipment ? { equipment } : {}, ...exclude.length ? { exclude } : {} };
+}
 function chapterSubject(subject) {
   const normalized = subject.replace(/\s+/gu, " ");
   if (normalized.length <= 65) return normalized;
@@ -912,6 +927,7 @@ function readShot(value, clipDurationSec, answerSubject = "") {
   return {
     narration,
     title,
+    stockSelection: readStockSelection(item?.stockSelection),
     subject,
     action: text(item?.action, 600),
     durationSec: typeof item?.durationSec === "number" && Number.isFinite(item.durationSec) ? Math.min(clipDurationSec, Math.max(2, item.durationSec)) : clipDurationSec,
@@ -964,7 +980,7 @@ function createChatShotPlanner(options) {
           return { type: "scene.add", ...closer ? { placement: "closer" } : {}, scene: {
             id: `${context.request.requestId}-shot-${++index}`,
             templateId: "cinemaMedia",
-            variables: { fallbackText: shot.title, mediaType: "video", mediaKeyword: shot.subject, shotDirection: [
+            variables: { ...options.mode === "pexels" && shot.stockSelection ? { stockSelection: shot.stockSelection } : {}, fallbackText: shot.title, mediaType: "video", mediaKeyword: shot.subject, shotDirection: [
               brief?.visualDirection,
               shot.action,
               shot.continuity === "continue" ? "Continue the established subject, setting and action consistently." : "A deliberate new shot; choose framing that reveals this beat.",
@@ -1132,8 +1148,10 @@ function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlr
     `First write one brief: {"type":"answer","intent":"explanation|story|comedy|imagination|practical","opening":"a short inviting spoken introduction of 6\u20139 words","subject":"literal visual subject","development":"the essential development of this answer","visualDirection":"consistent subjects, appearance and visual approach","ending":{"title":"short meaningful chapter title, at most 65 characters","narration":"the authored payoff","subject":"literal subject","action":"visible action or change","durationSec":${clipDurationSec},"continuity":"cut|continue"}}.`,
     `Then stream each developing shot on its own line: {"type":"shot","title":"short meaningful chapter title, at most 65 characters","narration":"the exact spoken beat","subject":"2\u20138 literal filmable words, at most 80 characters","action":"concrete subject, action or visible change and useful framing","durationSec":${clipDurationSec},"continuity":"cut|continue"}.`,
     `The selected footage mode is ${mode === "pexels" ? "Pexels stock search: use literal filmable subjects; never imply stock proves a mechanism or depicts fictional events exactly" : `AI video, with at most ${generatedVideoAvailable ? maxGeneratedVideos : 0} generation attempts`}. Missing footage becomes the authored chapter title, with complete narration. Preserve the full answer rather than shortening it to fit credits. The host selects providers; do not make source choices.`,
+    ...mode === "pexels" ? ["Stock queries must retain the essential subject, activity and distinguishing equipment in the shot's subject field, within its word limit. That field alone is the search query; action and visualDirection do not refine it. Prefer common observable actions with usable framing. Do not replace the required actor or activity with scenery, a different sport or a loosely related setting. Preserve fictional or comic narration, but do not depend on stock showing an exact invented expression or sequence; choose an illustrative action that supports the beat."] : [],
+    ...mode === "pexels" ? ['Include stockSelection on every shot and the saved ending when the essential subject is known: "stockSelection":{"subject":"essential actor or object category","activity":"optional literal activity","equipment":"optional distinguishing equipment","exclude":["optional contradictory subject or activity"]}. Each phrase must be 1\u20134 words and at most 48 characters; exclude has at most 3 phrases. The essential subject is separate from the setting: do not use scenery, mood, camera framing or incidental appearance as the actor. Keep the search query broad enough to find footage; the optional hint helps select results without substituting a different actor or task. Use exclusions only for actual contradictions, not every detail absent from the story. Omit unknown fields or the whole hint rather than inventing an anchor. This is selection guidance, not verification that footage depicts the exact narration.'] : [],
     "For a very short answer whose ending alone fulfills the request, development may be empty and no developing shots are needed. Otherwise, develop the essential content before the ending.",
-    "The brief's ending is saved and played after your developing shots. Do not repeat it as a shot. Stop writing after the last developing shot. No technical events, identifiers, template choices, media providers, URLs or extra fields.",
+    "The brief's ending is saved and played after your developing shots. Do not repeat it as a shot. Stop writing after the last developing shot. No technical events, identifiers, template choices, media providers, URLs or unlisted fields.",
     "Every shot uses moving footage with separate narration and subtitles. Generated footage is silent: do not ask its subjects to speak or render words. No headline cards or on-screen explanatory text.",
     `Each clip has at most ${clipDurationSec} seconds. Write spoken beats that fit naturally, usually ${Math.floor(clipDurationSec * 1.6)}\u2013${Math.floor(clipDurationSec * 2)} words per shot. Split longer ideas across purposeful shots, preserving facts and qualifiers. Never truncate a claim to meet a word target. Use only the shots needed within the total duration, including the ending; do not pad to a fixed count.`,
     "Identify the full answer and its ending before developing shots. Each action must support what is said: camera movement alone is not progression. Vary scale, viewpoint and meaningful details while keeping subjects consistent.",
@@ -1141,7 +1159,7 @@ function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlr
     "Stories: portray characters making choices and experiencing consequences; use consistent character descriptions and an earned resolution, not a promised next scene.",
     "Comedy: establish the premise, time the visual or spoken reveal, allow a reaction beat, and stop on the payoff without explaining the joke.",
     "Imagination: make the impossible action concrete, establish the world's internal rules and keep its imagery consistent. Do not replace imagination with an explanation of it.",
-    "Practical answers: show usable actions in their necessary order, with framing that makes the method and result visible. Preserve essential steps and relevant safety conditions.",
+    "Practical answers: show usable actions in their necessary order, with framing that makes the method and result visible. Preserve essential steps and relevant safety conditions. Match the requested experience level. For beginners, explain an unavoidable technical term in ordinary words or replace it with an observable action. Make the essential setup and a useful success cue explicit. Qualify advice that depends on equipment, task or conditions instead of presenting one setup as universal. Never add unsupported precision merely to sound instructional.",
     openingAlreadyProvided ? "The supplied opening has already been spoken. Preserve it and begin the body with new content." : "The brief opening is spoken during preparation. The first body shot must develop it rather than repeat its words or claim.",
     "Use continuity=continue when the same subject/action should remain coherent; choose cut for a purposeful new view. Describe recurring subjects consistently. Never assume a different angle or generated depiction proves a factual claim."
   ].join("\n");
@@ -1630,6 +1648,7 @@ function createVideoChatHandler(options) {
       invalidPartBehavior: videoOptions.invalidPartBehavior,
       requireCloser: options.requireCloser ?? true,
       generate: createChatShotPlanner({
+        mode,
         streamText: (context) => {
           lifecycle = getGenerationLifecycleSink(context);
           return videoOptions.streamText(context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.7",
+  "version": "0.10.9",
   "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.
 
@@ -70,3 +66,26 @@ work and playback, and failed media becomes the authored chapter.
 The provider names its own model. Override the tested defaults with
 `ANTHROPIC_PLANNER_MODEL`, `ANTHROPIC_NARRATION_MODEL`, or `FAL_VIDEO_MODEL`
 when needed.
+
+### Stock selection hints
+
+In Pexels mode, the same planning stream can supply an optional
+`scene.variables.stockSelection` to the application's media resolver:
+
+```ts
+{ subject: "cyclist", activity: "riding", equipment: "bicycle", exclude: ["motorcycle"] }
+```
+
+`subject` names the essential actor or object separately from the search query's
+setting. `activity`, `equipment` and `exclude` are optional. Each phrase has
+one to four words and at most 48 characters; `exclude` has at most three phrases.
+The SDK validates these fields, drops unknown keys and invalid optional values,
+and omits the whole hint when the essential subject is missing or invalid.
+It never guesses that subject from the first query word.
+
+Adapters can use this hint to prefer matching subjects and reject explicitly
+contradictory metadata while keeping the query broad enough for catalog search.
+Missing metadata remains uncertain, not proof of a match. The hint does not
+verify the depicted action or factual correctness. It is omitted from AI-video
+requests and removed before scenes are emitted or persisted; it adds no model
+request or public scene field.