@vanillaskyai/video 0.10.10 → 0.10.12

package/CHANGELOG.md

@@ -4,6 +4,16 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.12
+
+- Use query context to choose between equally relevant Pexels subject matches in the starter, while preserving subject, activity and equipment priority.
+
+## 0.10.11
+
+- Keep the opening chapter visible until the first body visual and narration are ready, without mounting a second player or replaying the opening.
+- Keep outgoing silent footage moving, or a chapter readable, while the next clip becomes playable; retain bounded chapter recovery, pause/cancel behavior and two-video preparation.
+- Recognize sustained native video motion, reuse fresh readiness across scene promotion, and preserve prepared footage during narration holds instead of rewinding it. Let silent clips loop natively within their finite scene.
+
 ## 0.10.10
 
 - Accept multiline streamed chat JSON objects without waiting for the entire answer, while retaining bounded parsing and strict scene validation.

package/dist/check-runtime.js

@@ -1,6 +1,6 @@
 import {
   VideoFrame
-} from "./chunk-FFKAHNYD.js";
+} from "./chunk-MXLVTOGR.js";
 import "./chunk-5JBMYQP6.js";
 import "./chunk-224QNWRA.js";
 import "./chunk-SPVTJH3F.js";

package/dist/{chunk-XL3H42K5.js → chunk-HFVNAPHZ.js}

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

package/dist/{chunk-FFKAHNYD.js → chunk-MXLVTOGR.js}

@@ -21,28 +21,53 @@ import { createContext, useContext, useEffect, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 var MountedReadinessContext = createContext(void 0);
 var sceneReadinessKey = (scene) => `${scene.id}\0${String(scene.variables.mediaUrl || "")}`;
-function MountedSceneReadiness({ scene, playing, fallback = false, onFailure }) {
+function MountedSceneReadiness({
+  scene,
+  playing,
+  fallback = false,
+  onFailure,
+  onReady,
+  observeIncoming = false,
+  timeoutMs = 8e3,
+  preparedProof
+}) {
   const marker = useRef(null);
   const report = useContext(MountedReadinessContext);
   const key = sceneReadinessKey(scene);
   const onFailureRef = useRef(onFailure);
   onFailureRef.current = onFailure;
+  const onReadyRef = useRef(onReady);
+  onReadyRef.current = onReady;
   useEffect(() => {
-    if (!report || !playing) return;
+    if (!report && !onReadyRef.current || !playing) return;
     let stopped = false;
     let frame = 0;
     let callback;
     let observed;
     let presented;
+    let previousMediaTime;
+    let forwardFrames = 0;
+    let motionRevision = 0;
     const root = marker.current?.closest("[data-video-frame]");
     const start = performance.now();
     const finish = (error, actualVideoFrame = false) => {
-      if (!stopped) {
-        stopped = true;
-        if (callback !== void 0) observed?.cancelVideoFrameCallback?.(callback);
-        if (error && onFailureRef.current) onFailureRef.current();
-        else report(key, error, actualVideoFrame);
-      }
+      if (stopped) return;
+      stopped = true;
+      if (callback !== void 0) observed?.cancelVideoFrameCallback?.(callback);
+      if (error && onFailureRef.current) onFailureRef.current();
+      else if (onReadyRef.current && !error) {
+        const video = presented;
+        const mediaTime = video?.currentTime ?? 0;
+        const confirmedAt = performance.now();
+        const source = video?.currentSrc;
+        const revision = motionRevision;
+        let consumed = false;
+        onReadyRef.current(actualVideoFrame && video ? { consume: (candidate) => {
+          const valid = !consumed && candidate === video && video.isConnected && motionRevision === revision && !video.paused && !video.seeking && video.currentSrc === source && video.currentSrc === video.src && performance.now() - confirmedAt <= 200 && video.currentTime >= mediaTime && video.currentTime - mediaTime <= 0.2;
+          consumed = true;
+          return valid;
+        } } : void 0);
+      } else report?.(key, error, actualVideoFrame);
     };
     const check = () => {
       if (stopped) return;
@@ -50,7 +75,7 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
         finish();
         return;
       }
-      const layer = root?.querySelector('[data-scene-layer="active"]');
+      const layer = observeIncoming ? [...root?.querySelectorAll("[data-layer-scene-id]") ?? []].find((node) => node.getAttribute("data-layer-scene-id") === scene.id) : root?.querySelector('[data-scene-layer="active"]');
       const loading = layer?.querySelector("[data-template-loading]");
       const mediaUrl = String(scene.variables.mediaUrl || "");
       const isVideo = scene.variables.mediaType === "video" || /\.(mp4|webm|mov)(?:[?#]|$)/i.test(mediaUrl);
@@ -61,22 +86,38 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
         }
         if (isVideo) {
           const video = layer.querySelector("video");
-          if (video && video.getAttribute("src") === mediaUrl && video.currentSrc === video.src && video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) {
-            if (presented === video) {
+          if (video && video.getAttribute("src") === mediaUrl && video.currentSrc === video.src && video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) {
+            if (preparedProof?.consume(video)) {
+              finish(void 0, true);
+              return;
+            }
+            if (observed !== video) {
+              previousMediaTime = void 0;
+              forwardFrames = 0;
+            }
+            if (presented === video && (video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA || forwardFrames >= 2)) {
               finish(void 0, true);
               return;
             }
             observed = video;
             if (video.requestVideoFrameCallback) {
-              callback = video.requestVideoFrameCallback(() => {
+              callback = video.requestVideoFrameCallback((_now, metadata) => {
                 callback = void 0;
-                presented = video;
+                if (stopped) return;
+                const sameSource = video.isConnected && video.getAttribute("src") === mediaUrl && video.currentSrc === video.src;
+                const mediaTime = metadata.mediaTime;
+                if (!sameSource || video.paused || video.seeking || !Number.isFinite(mediaTime) || previousMediaTime !== void 0 && mediaTime <= previousMediaTime + 1e-3) forwardFrames = 0;
+                else if (previousMediaTime !== void 0 && mediaTime > previousMediaTime + 1e-3) forwardFrames++;
+                previousMediaTime = sameSource && !video.paused && !video.seeking ? mediaTime : void 0;
+                if (sameSource) presented = video;
                 check();
               });
               return;
             }
-            finish(void 0, true);
-            return;
+            if (video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) {
+              finish(void 0, true);
+              return;
+            }
           }
         } else {
           const image = [...layer.querySelectorAll("img") ?? []].find((element) => element.getAttribute("src") === mediaUrl);
@@ -86,7 +127,7 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
           }
         }
       }
-      if (performance.now() - start >= 8e3) {
+      if (timeoutMs !== null && performance.now() - start >= timeoutMs) {
         finish(new Error("Scene media did not become ready"));
         return;
       }
@@ -101,17 +142,26 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
       callback = void 0;
       check();
     };
+    const resetMotion = (event) => {
+      if (event.target === observed || event.target === presented) {
+        motionRevision++;
+        previousMediaTime = void 0;
+        forwardFrames = 0;
+      }
+    };
+    for (const type of ["pause", "waiting", "seeking"]) root?.addEventListener(type, resetMotion, true);
     root?.addEventListener("vanillasky:video-frame-presented", onPresented);
     check();
-    const timeout = setTimeout(() => finish(new Error("Scene media did not become ready")), 8e3);
+    const timeout = timeoutMs === null ? void 0 : setTimeout(() => finish(new Error("Scene media did not become ready")), timeoutMs);
     return () => {
       root?.removeEventListener("vanillasky:video-frame-presented", onPresented);
+      for (const type of ["pause", "waiting", "seeking"]) root?.removeEventListener(type, resetMotion, true);
       stopped = true;
       clearTimeout(timeout);
       cancelAnimationFrame(frame);
       if (callback !== void 0) observed?.cancelVideoFrameCallback?.(callback);
     };
-  }, [key, report, scene, playing, fallback]);
+  }, [key, report, scene, playing, fallback, observeIncoming, timeoutMs, preparedProof]);
   return /* @__PURE__ */ jsx("span", { ref: marker, hidden: true });
 }
 
@@ -356,6 +406,12 @@ function VideoFrame({
   style
 }) {
   const recoveryRoot = useRef2(null);
+  const displayedKey = useRef2(void 0);
+  const displayedWasPlaying = useRef2(false);
+  const handoffProof = useRef2(void 0);
+  const confirmedHandoff = useRef2(void 0);
+  const [preparedMedia, setPreparedMedia] = useState(() => /* @__PURE__ */ new Set());
+  const markPrepared = useCallback((key) => setPreparedMedia((previous2) => /* @__PURE__ */ new Set([...previous2, key])), []);
   const reportedFailures = useRef2(/* @__PURE__ */ new Set());
   const [failedMedia, setFailedMedia] = useState(() => /* @__PURE__ */ new Set());
   const markMediaFailed = useCallback((key, reason = "playback-error") => {
@@ -364,14 +420,18 @@ function VideoFrame({
       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]));
+    setFailedMedia((previous2) => previous2.has(key) ? previous2 : /* @__PURE__ */ new Set([...previous2, key]));
   }, [config.scenes]);
   useEffect2(() => {
     const currentKeys = new Set(config.scenes.map(sceneReadinessKey));
+    setPreparedMedia((previous2) => {
+      const retained = new Set([...previous2].filter((key) => currentKeys.has(key)));
+      return retained.size === previous2.size ? previous2 : retained;
+    });
     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;
+    setFailedMedia((previous2) => {
+      const retained = new Set([...previous2].filter((key) => currentKeys.has(key)));
+      return retained.size === previous2.size ? previous2 : retained;
     });
   }, [config.scenes]);
   const decoderConstrainedDevice = useDecoderConstraint();
@@ -379,8 +439,29 @@ function VideoFrame({
   const lastRange = timeline.at(-1);
   const foundIndex = timeline.findIndex((range) => time >= range.start && time < range.end);
   const afterEnd = lastRange && time >= lastRange.end;
-  const activeIndex = foundIndex >= 0 ? foundIndex : afterEnd ? timeline.length - 1 : -1;
-  const active = activeIndex >= 0 ? timeline[activeIndex] : void 0;
+  const targetIndex = foundIndex >= 0 ? foundIndex : afterEnd ? timeline.length - 1 : -1;
+  const target = timeline[targetIndex];
+  const targetKey = target ? sceneReadinessKey(target.scene) : void 0;
+  if (confirmedHandoff.current !== targetKey || !(playing || preparingNarration)) {
+    confirmedHandoff.current = void 0;
+    handoffProof.current = void 0;
+  }
+  const previousIndex = timeline.findIndex((range) => sceneReadinessKey(range.scene) === displayedKey.current);
+  const previous = timeline[previousIndex];
+  const canPrepare = (range) => Boolean(range && mediaAudioMuted && sceneHasVideoBackdrop(range) && supportsExternalVideoBackdrop(kit.getTemplate(range.scene.templateId)));
+  const canRetain = (range) => canPrepare(range) || range?.scene.templateId === "chapterTitle";
+  const hasPlayableMedia = (range) => {
+    if (!range || !preparedMedia.has(sceneReadinessKey(range.scene))) return false;
+    const layer = [...recoveryRoot.current?.querySelectorAll("[data-layer-scene-id]") ?? []].find((node) => node.getAttribute("data-layer-scene-id") === range.scene.id);
+    const video = layer?.querySelector("video");
+    return Boolean(video && video.getAttribute("src") === range.scene.variables.mediaUrl && video.currentSrc === video.src && video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA);
+  };
+  const handoffPending = Boolean(displayedWasPlaying.current && target && previous && targetIndex === previousIndex + 1 && time <= target.start + 1e-3 && rangesAreContiguous(previous, target) && canRetain(previous) && canPrepare(target) && !failedMedia.has(sceneReadinessKey(target.scene)) && !hasPlayableMedia(target) && confirmedHandoff.current !== targetKey);
+  const activeIndex = handoffPending ? previousIndex : targetIndex;
+  const active = timeline[activeIndex];
+  const displayKey = active ? sceneReadinessKey(active.scene) : void 0;
+  displayedWasPlaying.current = displayedKey.current === displayKey && displayedWasPlaying.current || playing || preparingNarration;
+  displayedKey.current = displayKey;
   if (!active) {
     return /* @__PURE__ */ jsx2(
       "div",
@@ -432,18 +513,21 @@ function VideoFrame({
     contiguousNext && decoderConstrainedDevice && !boundedPreparation && sceneHasVideoBackdrop(active) && sceneHasVideoBackdrop(contiguousNext)
   );
   const activeMediaFailed = failedMedia.has(sceneReadinessKey(active.scene));
-  const mountingNext = Boolean(
+  const preparingNext = canRetain(active) && canPrepare(contiguousNext);
+  const nextPlayable = hasPlayableMedia(contiguousNext);
+  const mountingNext = handoffPending || Boolean(
     contiguousNext && !decoderConstrainedTransition && (boundedPreparation || time >= prerollStart) && time < blendEnd && (eligibleNextTransition || prerollsNext || boundedPreparation && sceneHasVideoBackdrop(contiguousNext))
   );
   const previewingNext = Boolean(
-    eligibleNextTransition && time >= blendStart && time < blendEnd
+    eligibleNextTransition && time >= blendStart && time < blendEnd && (!preparingNext || nextPlayable)
   );
   const blendProgress = previewingNext && blendDuration > 0 ? Math.round(clamp01((time - blendStart) / blendDuration) * 1e6) / 1e6 : 0;
   const progress = rawProgress;
   const isFinalScene = activeIndex === timeline.length - 1;
   const presentsChapter = active.scene.templateId === "chapterTitle" || active.scene.templateId === "cinemaMedia" && (activeMediaFailed || !String(active.scene.variables.mediaUrl || "").trim());
   const finalHold = presentsChapter ? 0.76 : activeTiming?.holdProgress;
-  const motionProgress = isFinalScene && finalHold !== void 0 ? Math.min(rawProgress, finalHold) : rawProgress;
+  const holdChapter = presentsChapter && preparingNext && !nextPlayable;
+  const motionProgress = (isFinalScene || holdChapter) && finalHold !== void 0 ? Math.min(rawProgress, finalHold) : rawProgress;
   const canvas = getDimensions(config.orientation);
   const scale = Math.min(width / canvas.width, height / canvas.height);
   const canvasLeft = (width - canvas.width * scale) / 2;
@@ -453,12 +537,12 @@ function VideoFrame({
     {
       ref: recoveryRoot,
       onErrorCapture: (event) => {
-        const target = event.target;
-        if (!(target instanceof HTMLVideoElement || target instanceof HTMLImageElement)) return;
-        const ownerId = target.closest("[data-layer-scene-id]")?.getAttribute("data-layer-scene-id");
+        const target2 = event.target;
+        if (!(target2 instanceof HTMLVideoElement || target2 instanceof HTMLImageElement)) return;
+        const ownerId = target2.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) {
+        if (owner && template && supportsExternalVideoBackdrop(template) && target2.getAttribute("src") === owner.scene.variables.mediaUrl) {
           markMediaFailed(sceneReadinessKey(owner.scene), "decode-error");
         }
       },
@@ -479,11 +563,30 @@ function VideoFrame({
           MountedSceneReadiness,
           {
             scene: active.scene,
-            playing,
+            playing: playing && !handoffPending,
             fallback: activeMediaFailed,
+            preparedProof: confirmedHandoff.current === sceneReadinessKey(active.scene) ? handoffProof.current : void 0,
             onFailure: sceneHasBackdrop(active) && supportsExternalVideoBackdrop(activeTemplate) && !activeMediaFailed ? () => markMediaFailed(sceneReadinessKey(active.scene), "frame-readiness-timeout") : void 0
           }
         ),
+        mountingNext && contiguousNext && preparingNext && /* @__PURE__ */ jsx2(
+          MountedSceneReadiness,
+          {
+            scene: contiguousNext.scene,
+            playing: playing || preparingNarration,
+            observeIncoming: true,
+            timeoutMs: handoffPending ? 8e3 : null,
+            onReady: (proof) => {
+              const key = sceneReadinessKey(contiguousNext.scene);
+              if (handoffPending) {
+                confirmedHandoff.current = key;
+                handoffProof.current = proof;
+              }
+              markPrepared(key);
+            },
+            onFailure: () => markMediaFailed(sceneReadinessKey(contiguousNext.scene), "frame-readiness-timeout")
+          }
+        ),
         /* @__PURE__ */ jsxs(
           "div",
           {
@@ -525,8 +628,8 @@ function VideoFrame({
                     motionProgress,
                     width: canvas.width,
                     height: canvas.height,
-                    playing,
-                    preparingNarration,
+                    playing: handoffPending ? playing || preparingNarration : playing,
+                    preparingNarration: handoffPending ? false : preparingNarration,
                     mediaAudioMuted,
                     mediaAudioVolume,
                     layer: previewingNext ? "outgoing" : "active",
@@ -547,9 +650,9 @@ function VideoFrame({
                     motionProgress: 0,
                     width: canvas.width,
                     height: canvas.height,
-                    playing: false,
-                    preparingNarration: false,
-                    mediaAudioMuted,
+                    playing: Boolean(preparingNext && (!preparedMedia.has(sceneReadinessKey(contiguousNext.scene)) || handoffPending) && (playing || preparingNarration)),
+                    preparingNarration: preparingNext,
+                    mediaAudioMuted: true,
                     mediaAudioVolume,
                     layer: "incoming",
                     opacity: blendProgress,

package/dist/{chunk-3S5FXE6G.js → chunk-QSBDB4J2.js}

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

package/dist/{chunk-YERSNTFL.js → chunk-YAHT3LST.js}

@@ -271,7 +271,7 @@ var SceneVideoBackdrop = ({
     }
   };
   useEffect(() => {
-    if (!isPlaying || waitingKey !== videoPresentationKey) {
+    if (!isPlaying || rewindPreroll || waitingKey !== videoPresentationKey) {
       if (waitingKey) setWaitingKey(void 0);
       return;
     }
@@ -298,6 +298,7 @@ var SceneVideoBackdrop = ({
       else if (time > previousTime + 1e-3) forwardFrames++;
       previousTime = time;
       if (forwardFrames >= 2) {
+        playableVideoUrl.current = mediaUrl;
         stopped = true;
         clearTimeout(deadline);
         setWaitingKey(void 0);
@@ -320,7 +321,7 @@ var SceneVideoBackdrop = ({
       clearTimeout(poll);
       if (frame !== void 0) video.cancelVideoFrameCallback?.(frame);
     };
-  }, [waitingKey, videoPresentationKey, isPlaying]);
+  }, [waitingKey, videoPresentationKey, isPlaying, rewindPreroll]);
   const onReadyRef = useRef(onReady);
   onReadyRef.current = onReady;
   useEffect(() => {
@@ -397,7 +398,7 @@ var SceneVideoBackdrop = ({
     if (!video) return;
     if (!isPlaying) {
       video.pause();
-      if (rewindPreroll && video.currentTime > 0) video.currentTime = 0;
+      if (rewindPreroll && !resolvedMuted && video.currentTime > 0) video.currentTime = 0;
       return;
     }
     if (startedPlaybackId.current === playbackId) {
@@ -415,7 +416,7 @@ var SceneVideoBackdrop = ({
   const enforceRequestedPause = (event) => {
     if (presentationRef.current.playing) return;
     event.currentTarget.pause();
-    if (rewindPreroll && event.currentTarget.currentTime > 0) event.currentTarget.currentTime = 0;
+    if (rewindPreroll && !resolvedMuted && event.currentTarget.currentTime > 0) event.currentTarget.currentTime = 0;
   };
   const mediaStyle = {
     position: "absolute",
@@ -444,7 +445,7 @@ var SceneVideoBackdrop = ({
         src: mediaUrl,
         poster: decodedVideoUrl !== mediaUrl ? mediaPoster || void 0 : void 0,
         muted: resolvedMuted,
-        loop: false,
+        loop: resolvedMuted && isPlaying && Number.isFinite(sceneDuration) && Number(sceneDuration) > 0,
         playsInline: true,
         preload: "auto",
         onLoadedMetadata: (event) => fitDuration(event.currentTarget),

package/dist/{cinema-media-IAK3LC2J.js → cinema-media-HYCDG65Z.js}

@@ -1,8 +1,8 @@
 import {
   MediaScene,
   MediaSceneTemplate
-} from "./chunk-3S5FXE6G.js";
-import "./chunk-YERSNTFL.js";
+} from "./chunk-QSBDB4J2.js";
+import "./chunk-YAHT3LST.js";
 import "./chunk-5JBMYQP6.js";
 import "./chunk-224QNWRA.js";
 export {

package/dist/{comparison-MCTN376M.js → comparison-XXAP4S4J.js}

@@ -1,7 +1,7 @@
 import {
   EditorialSurface
-} from "./chunk-XL3H42K5.js";
-import "./chunk-YERSNTFL.js";
+} from "./chunk-HFVNAPHZ.js";
+import "./chunk-YAHT3LST.js";
 import {
   editorialLabel,
   fade

package/dist/{editorial-timeline-435UCJ45.js → editorial-timeline-VUQC6KPA.js}

@@ -1,7 +1,7 @@
 import {
   EditorialSurface
-} from "./chunk-XL3H42K5.js";
-import "./chunk-YERSNTFL.js";
+} from "./chunk-HFVNAPHZ.js";
+import "./chunk-YAHT3LST.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";

package/dist/{key-figure-BSOQ3TYN.js → key-figure-4TJK7HLT.js}

@@ -1,7 +1,7 @@
 import {
   EditorialSurface
-} from "./chunk-XL3H42K5.js";
-import "./chunk-YERSNTFL.js";
+} from "./chunk-HFVNAPHZ.js";
+import "./chunk-YAHT3LST.js";
 import {
   editorialLabel,
   fade

package/dist/{mobile-message-GVFA56QP.js → mobile-message-FIHAO6XC.js}

@@ -1,9 +1,9 @@
 import {
   MediaScene
-} from "./chunk-3S5FXE6G.js";
+} from "./chunk-QSBDB4J2.js";
 import {
   spring
-} from "./chunk-YERSNTFL.js";
+} from "./chunk-YAHT3LST.js";
 import {
   editorialFont
 } from "./chunk-4YM2M62S.js";

package/dist/{quote-H2X4XGPB.js → quote-GRPIYKQJ.js}

@@ -1,7 +1,7 @@
 import {
   EditorialSurface
-} from "./chunk-XL3H42K5.js";
-import "./chunk-YERSNTFL.js";
+} from "./chunk-HFVNAPHZ.js";
+import "./chunk-YAHT3LST.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";

package/dist/react.js

@@ -40,7 +40,7 @@ import {
   VideoFrame,
   getDimensions,
   sceneReadinessKey
-} from "./chunk-FFKAHNYD.js";
+} from "./chunk-MXLVTOGR.js";
 import "./chunk-5JBMYQP6.js";
 import "./chunk-224QNWRA.js";
 import {
@@ -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-IAK3LC2J.js").then((module) => ({ default: module.MediaSceneTemplate })),
+  "cinemaMedia": () => import("./cinema-media-HYCDG65Z.js").then((module) => ({ default: module.MediaSceneTemplate })),
   "chapterTitle": () => import("./chapter-title-2JVDU62E.js").then((module) => ({ default: module.TitleSceneTemplate })),
-  "editorialTimeline": () => import("./editorial-timeline-435UCJ45.js").then((module) => ({ default: module.TimelineSceneTemplate })),
-  "mobileMessage": () => import("./mobile-message-GVFA56QP.js").then((module) => ({ default: module.NotificationSceneTemplate })),
-  "comparison": () => import("./comparison-MCTN376M.js").then((module) => ({ default: module.ComparisonSceneTemplate })),
-  "quote": () => import("./quote-H2X4XGPB.js").then((module) => ({ default: module.QuoteSceneTemplate })),
-  "keyFigure": () => import("./key-figure-BSOQ3TYN.js").then((module) => ({ default: module.KeyFigureSceneTemplate }))
+  "editorialTimeline": () => import("./editorial-timeline-VUQC6KPA.js").then((module) => ({ default: module.TimelineSceneTemplate })),
+  "mobileMessage": () => import("./mobile-message-FIHAO6XC.js").then((module) => ({ default: module.NotificationSceneTemplate })),
+  "comparison": () => import("./comparison-XXAP4S4J.js").then((module) => ({ default: module.ComparisonSceneTemplate })),
+  "quote": () => import("./quote-GRPIYKQJ.js").then((module) => ({ default: module.QuoteSceneTemplate })),
+  "keyFigure": () => import("./key-figure-4TJK7HLT.js").then((module) => ({ default: module.KeyFigureSceneTemplate }))
 };
 
 // src/visual-system/catalog/builtin-player.generated.ts
@@ -3466,7 +3466,41 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
   }, [chat, listen]);
   const shown = chat.shownTurn;
   const showing = chat.playerProps != null;
-  const openingChapter = !showing && Boolean(shown?.prompt);
+  const handoffKey = `${shown?.id ?? ""}:${chat.playerKey}`;
+  const [presentedBody, setPresentedBody] = useState7();
+  const handoff = useRef8({ key: handoffKey, live: showing, active: false, frame: 0 });
+  const handoffStopped = chat.status === "error" || chat.status === "cancelled";
+  const waitingForBody = showing && presentedBody !== handoffKey;
+  const openingChapter = Boolean(shown?.prompt) && (!showing || waitingForBody) && chat.status !== "error" && chat.status !== "cancelled" && chat.status !== "ended";
+  useLayoutEffect2(() => {
+    const current = { key: handoffKey, live: showing && !handoffStopped, active: openingChapter && showing, frame: 0 };
+    handoff.current = current;
+    return () => {
+      current.live = false;
+      current.active = false;
+      cancelAnimationFrame(current.frame);
+    };
+  }, [handoffKey, openingChapter, showing, handoffStopped]);
+  const cueBody = (scene, index) => {
+    const current = handoff.current;
+    if (!current.live || current.key !== handoffKey) return;
+    chat.playerProps?.onSceneChange?.(scene, index);
+    if (!current.active) return;
+    cancelAnimationFrame(current.frame);
+    const reveal = () => {
+      if (!current.active || handoff.current !== current) return;
+      let ready = false;
+      try {
+        ready = chat.playerProps?.narrationReady?.() !== false;
+      } catch {
+      }
+      if (ready) {
+        current.active = false;
+        setPresentedBody(handoffKey);
+      } else current.frame = requestAnimationFrame(reveal);
+    };
+    reveal();
+  };
   const openingTitle = shown?.opening ?? shown?.prompt ?? "";
   const status = chat.turns.length === 0 ? "idle" : chat.status === "composing" ? "drawing" : chat.status === "playing" ? "narrating" : chat.status === "error" || chat.status === "cancelled" ? "ended" : chat.status;
   const shownOrientation = shown?.orientation ?? sessionOrientation;
@@ -3584,14 +3618,13 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
         ] }),
         /* @__PURE__ */ jsxs6("div", { className: "stage-area", children: [
           /* @__PURE__ */ jsxs6("div", { className: "stage", style: { background: "#000" }, children: [
-            !showing && /* @__PURE__ */ jsxs6(Fragment4, { children: [
-              openingChapter && /* @__PURE__ */ jsx8(OpeningChapter, { title: openingTitle.length > 120 ? `${openingTitle.slice(0, 117).trimEnd()}\u2026` : openingTitle }, shown.id),
-              chat.turns.length === 0 && /* @__PURE__ */ jsx8(Welcome, { data: chat.welcome, onAsk: ask, title: welcomeTitle })
-            ] }),
+            openingChapter && /* @__PURE__ */ jsx8(OpeningChapter, { title: openingTitle.length > 120 ? `${openingTitle.slice(0, 117).trimEnd()}\u2026` : openingTitle }, shown.id),
+            !showing && chat.turns.length === 0 && /* @__PURE__ */ jsx8(Welcome, { data: chat.welcome, onAsk: ask, title: welcomeTitle }),
             chat.playerProps && /* @__PURE__ */ jsx8("div", { className: "player-fit", style: { width: stageOrientation === "portrait" ? "min(100cqw, 56.25cqh)" : "min(100cqw, 177.7778cqh)" }, children: /* @__PURE__ */ jsx8(
               VideoPlayer,
               {
                 ...chat.playerProps,
+                onSceneChange: cueBody,
                 templates: options.templates,
                 orientation: stageOrientation,
                 responsiveBreakpoint: DESKTOP_WIDTH,

package/package.json

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

package/registry/items/backgrounds.json

@@ -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 { 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 playableVideoUrl = 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 awaitingPlayback = playableVideoUrl.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 && awaitingPlayback && video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) {\n        playableVideoUrl.current = mediaUrl;\n        awaitingPlayback = 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(awaitingPlayback ? \"frame-readiness-timeout\" : \"stalled-media\"); } };\n    // Initial network/decode work has the same bound as mounted readiness.\n    // A decoded still with no future data is still cold, even after its first\n    // frame callback. Keep the short bound only after playback was available.\n    let deadline = setTimeout(fail, awaitingPlayback ? 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      if (video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) playableVideoUrl.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={event => {\n          if (event.currentTarget.currentSrc === event.currentTarget.src\n            && event.currentTarget.getAttribute(\"src\") === mediaUrl\n            && event.currentTarget.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) playableVideoUrl.current = mediaUrl;\n          enforceRequestedPause(event);\n        }}\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"
+      "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 playableVideoUrl = 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    // Hidden preparation is bounded by mounted readiness once its cut is due.\n    // It must not spend the next scene's stall deadline while still incoming.\n    if (!isPlaying || rewindPreroll || 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 awaitingPlayback = playableVideoUrl.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 && awaitingPlayback && video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) {\n        playableVideoUrl.current = mediaUrl;\n        awaitingPlayback = 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        playableVideoUrl.current = mediaUrl;\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(awaitingPlayback ? \"frame-readiness-timeout\" : \"stalled-media\"); } };\n    // Initial network/decode work has the same bound as mounted readiness.\n    // A decoded still with no future data is still cold, even after its first\n    // frame callback. Keep the short bound only after playback was available.\n    let deadline = setTimeout(fail, awaitingPlayback ? 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, rewindPreroll]);\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      if (video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) playableVideoUrl.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      // Keep silent prepared data intact through narration startup. Seeking\n      // back a few milliseconds can trigger another cold Range request.\n      if (rewindPreroll && !resolvedMuted && 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 && !resolvedMuted && 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        // Let the decoder repeat without an ended → script seek/play round trip.\n        // The finite scene clock still owns pause and disposal; never loop speech.\n        loop={resolvedMuted && isPlaying && Number.isFinite(sceneDuration) && Number(sceneDuration) > 0}\n        playsInline\n        preload=\"auto\"\n        onLoadedMetadata={event => fitDuration(event.currentTarget)}\n        onEnded={event => continueMotion(event.currentTarget)}\n        onPlay={enforceRequestedPause}\n        onPlaying={event => {\n          if (event.currentTarget.currentSrc === event.currentTarget.src\n            && event.currentTarget.getAttribute(\"src\") === mediaUrl\n            && event.currentTarget.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) playableVideoUrl.current = mediaUrl;\n          enforceRequestedPause(event);\n        }}\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/package.json

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

package/starters/video-chat/stock.ts

@@ -71,7 +71,9 @@ export async function findStockFootage(query: string, orientation: VideoOrientat
     if (selection && subject.length) {
       const covers = (phrase: string) => terms(phrase).every(word => subject.includes(word));
       if (!covers(selection.subject) || selection.exclude?.some(covers)) continue;
-      matches = 2 + Number(Boolean(selection.activity && covers(selection.activity)))
+      // Query context breaks equal hint matches without outweighing a hint.
+      const contextScore = matches / (tokens.length + 1);
+      matches = 2 + contextScore + Number(Boolean(selection.activity && covers(selection.activity)))
         + Number(Boolean(selection.equipment && covers(selection.equipment)));
     }
     // The documented Video resource can have only a numeric page URL and no

package/styles/video-chat.css

@@ -1066,6 +1066,8 @@
 }
 
 .vanillasky-video-chat .opening-chapter {
+  z-index: 2;
+  pointer-events: none;
   position: absolute;
   inset: 0;
   background: #000;