@vanillaskyai/video 0.10.5 → 0.10.7

package/CHANGELOG.md

@@ -4,6 +4,23 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.7
+
+- Reuse the first presented video frame at scene handoffs so a second readiness observation cannot briefly interrupt continuous narration.
+
+- Keep an already-speaking paragraph uninterrupted across brief visual handoffs, while genuinely late footage still pauses narration until it can play.
+
+- Keep the final chapter visible through answer completion, including recovery from failed footage.
+- Derive recovery titles from authored titles or subject excerpts instead of a generic placeholder.
+
+- Let cold footage finish its bounded initial load before treating it as stalled. Require the actual new source to present a frame before narration starts, and keep source changes from cancelling their own native load.
+
+## 0.10.6
+
+- Initialize the reusable narration audio element during the existing user gesture so delayed first speech can play on Safari.
+
+- Accept valid Pexels search results without descriptive URL slugs. Rank available matching metadata above unknown relevance, without requiring most query words to appear in the slug.
+
 ## 0.10.5
 
 - Keep footage visible when native playback reports waiting without another playing event. Observe resumed motion directly and recover to the authored chapter after one second without progress, preserving narration.

package/dist/{chapter-title-YRLIQY3V.js → chapter-title-2JVDU62E.js}

@@ -1,6 +1,6 @@
 import {
   TitleSceneTemplate
-} from "./chunk-EWWCQFTI.js";
+} from "./chunk-7AA2JWHZ.js";
 import "./chunk-4YM2M62S.js";
 export {
   TitleSceneTemplate

package/dist/check-runtime.js

@@ -1,6 +1,6 @@
 import {
   VideoFrame
-} from "./chunk-VWJBIYBM.js";
+} from "./chunk-24TCMDAA.js";
 import "./chunk-224QNWRA.js";
 import "./chunk-OOBT4X46.js";
 import "./chunk-SPVTJH3F.js";

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

@@ -33,17 +33,19 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
     let frame = 0;
     let callback;
     let observed;
+    let presented;
+    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);
       }
     };
     const check = () => {
       if (stopped) return;
-      const root = marker.current?.closest("[data-video-frame]");
       if (fallback && root?.querySelector("[data-scene-fallback]") && !root.querySelector("[data-template-loading]") && document.fonts?.status !== "loading") {
         finish();
         return;
@@ -60,7 +62,11 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
         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");
-          if (video && video.getAttribute("src") === mediaUrl && video.readyState >= 2) {
+          if (video && video.getAttribute("src") === mediaUrl && video.currentSrc === video.src && video.readyState >= 2) {
+            if (presented === video) {
+              finish(void 0, true);
+              return;
+            }
             observed = video;
             if (video.requestVideoFrameCallback) {
               callback = video.requestVideoFrameCallback(() => finish(void 0, true));
@@ -83,9 +89,20 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
       }
       frame = requestAnimationFrame(check);
     };
+    const onPresented = (event) => {
+      const video = event.target;
+      if (!(video instanceof HTMLVideoElement) || stopped || video.getAttribute("src") !== String(scene.variables.mediaUrl || "") || video.currentSrc !== video.src) return;
+      presented = video;
+      cancelAnimationFrame(frame);
+      if (callback !== void 0) observed?.cancelVideoFrameCallback?.(callback);
+      callback = void 0;
+      check();
+    };
+    root?.addEventListener("vanillasky:video-frame-presented", onPresented);
     check();
     const timeout = setTimeout(() => finish(new Error("Scene media did not become ready")), 8e3);
     return () => {
+      root?.removeEventListener("vanillasky:video-frame-presented", onPresented);
       stopped = true;
       clearTimeout(timeout);
       cancelAnimationFrame(frame);
@@ -94,39 +111,6 @@ function MountedSceneReadiness({ scene, playing, fallback = false, onFailure })
   }, [key, report, scene, playing, fallback]);
   return /* @__PURE__ */ jsx("span", { ref: marker, hidden: true });
 }
-function PreparedSceneReadiness({ scene }) {
-  const marker = useRef(null);
-  const report = useContext(MountedReadinessContext);
-  useEffect(() => {
-    if (!report) return;
-    let frame = 0;
-    let stopped = false;
-    const check = () => {
-      if (stopped) return;
-      const root = marker.current?.closest("[data-video-frame]");
-      const incoming = root?.querySelector("[data-scene-layer='incoming']");
-      const video = incoming?.getAttribute("data-layer-scene-id") === scene.id ? incoming.querySelector("video") : void 0;
-      if (video && video.getAttribute("src") === scene.variables.mediaUrl && video.readyState >= 2) {
-        report(sceneReadinessKey(scene), void 0, false, true);
-        return;
-      }
-      const image = [...root?.querySelectorAll("img[data-video-poster-plane='prepared']") ?? []].find((image2) => image2.getAttribute("src") === scene.variables.mediaPoster);
-      if (image?.complete && image.naturalWidth > 0) {
-        void image.decode().then(() => {
-          if (!stopped && image.isConnected) report(sceneReadinessKey(scene), void 0, false, true);
-        }).catch(() => void 0);
-        return;
-      }
-      frame = requestAnimationFrame(check);
-    };
-    check();
-    return () => {
-      stopped = true;
-      cancelAnimationFrame(frame);
-    };
-  }, [scene, report]);
-  return /* @__PURE__ */ jsx("span", { ref: marker, hidden: true });
-}
 
 // src/player/video-frame.tsx
 import {
@@ -209,7 +193,7 @@ var SceneBoundary = class extends Component {
   }
 };
 var SCENE_TRANSITION_SECONDS = 0.3;
-var SceneVideoBackdrop = lazy(() => import("./scene-video-backdrop-MUGIXE2Q.js").then((module) => ({ default: module.SceneVideoBackdrop })));
+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 = () => () => {
@@ -447,7 +431,6 @@ function VideoFrame({
   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 preparedReadinessRange = posterPreparationRange ?? (contiguousNext && sceneHasVideoBackdrop(contiguousNext) ? contiguousNext : void 0);
   const preparedPoster = posterPreparationRange && String(
     posterPreparationRange.scene.variables.mediaPoster || ""
   ) ? {
@@ -471,7 +454,9 @@ function VideoFrame({
   const blendProgress = previewingNext && blendDuration > 0 ? Math.round(clamp01((time - blendStart) / blendDuration) * 1e6) / 1e6 : 0;
   const progress = rawProgress;
   const isFinalScene = activeIndex === timeline.length - 1;
-  const motionProgress = isFinalScene && activeTiming ? Math.min(rawProgress, activeTiming.holdProgress) : rawProgress;
+  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 canvas = getDimensions(config.orientation);
   const scale = Math.min(width / canvas.width, height / canvas.height);
   const canvasLeft = (width - canvas.width * scale) / 2;
@@ -507,7 +492,6 @@ function VideoFrame({
             onFailure: sceneHasBackdrop(active) && supportsExternalVideoBackdrop(activeTemplate) && !activeMediaFailed ? () => markMediaFailed(sceneReadinessKey(active.scene)) : void 0
           }
         ),
-        preparedReadinessRange && /* @__PURE__ */ jsx2(PreparedSceneReadiness, { scene: preparedReadinessRange.scene }),
         /* @__PURE__ */ jsxs(
           "div",
           {

package/dist/{chunk-EWWCQFTI.js → chunk-7AA2JWHZ.js}

@@ -5,10 +5,11 @@ import {
 
 // src/visual-system/scene-templates/chapter-title.tsx
 import { jsx } from "react/jsx-runtime";
-function TitleScene({ variables, width, height, progress }) {
+function TitleScene({ variables, width, height, progress, motionProgress }) {
   const title = String(variables.title ?? "A different perspective");
   const unit = Math.min(width, height);
-  const opacity = fade(progress / 0.22) * (1 - fade((progress - 0.76) / 0.24));
+  const presentation = motionProgress ?? progress;
+  const opacity = fade(presentation / 0.22) * (1 - fade((presentation - 0.76) / 0.24));
   return /* @__PURE__ */ jsx("div", { "data-template": "title", "data-title-treatment": "quiet-fade", style: { position: "absolute", inset: 0, background: "#000", color: "#fff", display: "flex", alignItems: "center", justifyContent: "center" }, children: /* @__PURE__ */ jsx("div", { "data-title-composition": "centered", style: { width: "76%", textAlign: "center", opacity, fontFamily: editorialFont, fontWeight: 500, fontSize: unit * 0.068, lineHeight: 1.18, letterSpacing: "-.025em", textWrap: "balance", overflowWrap: "anywhere" }, children: title }) });
 }
 var TitleSceneTemplate = TitleScene;

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

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

package/dist/{chunk-DD4ZSYKG.js → chunk-OBRKB7PL.js}

@@ -255,6 +255,7 @@ var SceneVideoBackdrop = ({
   const [waitingKey, setWaitingKey] = useState();
   const [exhaustedKey, setExhaustedKey] = useState();
   const videoRef = useRef(null);
+  const presentedVideoUrl = useRef(void 0);
   const startedVideoUrl = useRef(void 0);
   const startedPlaybackId = useRef(void 0);
   const videoPresentationKey = `${playbackId}\0${mediaUrl}`;
@@ -274,6 +275,8 @@ var SceneVideoBackdrop = ({
     }
     const video = videoRef.current;
     if (!video) return;
+    const expectedSource = video.getAttribute("src") === mediaUrl ? video.src : void 0;
+    let awaitingFirstFrame = presentedVideoUrl.current !== mediaUrl || video.currentSrc !== expectedSource;
     let previousTime = video.currentTime;
     let forwardFrames = 0;
     let stopped = false;
@@ -281,8 +284,14 @@ var SceneVideoBackdrop = ({
     let poll;
     const observe = (_now, metadata) => {
       if (stopped) return;
+      const currentSource = video.currentSrc === expectedSource;
+      if (currentSource && awaitingFirstFrame && (metadata || presentedVideoUrl.current === mediaUrl)) {
+        awaitingFirstFrame = false;
+        clearTimeout(deadline);
+        deadline = setTimeout(fail, 1e3);
+      }
       const time = metadata?.mediaTime ?? video.currentTime;
-      if (video.seeking || time < previousTime) forwardFrames = 0;
+      if (!currentSource || video.seeking || time < previousTime) forwardFrames = 0;
       else if (time > previousTime + 1e-3) forwardFrames++;
       previousTime = time;
       if (forwardFrames >= 2) {
@@ -294,12 +303,13 @@ var SceneVideoBackdrop = ({
       if (video.requestVideoFrameCallback) frame = video.requestVideoFrameCallback(observe);
       else poll = setTimeout(observe, 50);
     };
-    const deadline = setTimeout(() => {
+    const fail = () => {
       if (!stopped) {
         stopped = true;
         unavailable();
       }
-    }, 1e3);
+    };
+    let deadline = setTimeout(fail, awaitingFirstFrame ? 8e3 : 1e3);
     observe();
     return () => {
       stopped = true;
@@ -330,6 +340,10 @@ var SceneVideoBackdrop = ({
       video.setAttribute("src", mediaUrl);
       video.load();
     }
+  }, [mediaUrl]);
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video) return;
     return () => {
       video.pause();
       video.removeAttribute("src");
@@ -337,7 +351,7 @@ var SceneVideoBackdrop = ({
       startedVideoUrl.current = void 0;
       startedPlaybackId.current = void 0;
     };
-  }, [mediaUrl]);
+  }, []);
   useEffect(() => {
     const video = videoRef.current;
     if (video) video.volume = resolvedVolume;
@@ -450,7 +464,9 @@ var SceneVideoBackdrop = ({
         onLoadedData: (event) => {
           const video = event.currentTarget;
           const markPresented = () => {
-            if (!video.isConnected) return;
+            if (!video.isConnected || presentationRef.current.key !== videoPresentationKey || video.getAttribute("src") !== mediaUrl || video.currentSrc !== video.src) return;
+            presentedVideoUrl.current = mediaUrl;
+            video.dispatchEvent(new Event("vanillasky:video-frame-presented", { bubbles: true }));
             onReady?.();
             if (!retainPoster) setDecodedVideoUrl(mediaUrl);
           };

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

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

package/dist/{chunk-MGCD3ZJ3.js → chunk-X4RGAEL5.js}

@@ -3,7 +3,7 @@ import {
   SceneVideoBackdrop,
   getBackgroundTransform,
   resolveMediaPosition
-} from "./chunk-DD4ZSYKG.js";
+} from "./chunk-OBRKB7PL.js";
 import {
   resolveMediaType
 } from "./chunk-224QNWRA.js";

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

@@ -1,9 +1,9 @@
 import {
   MediaScene,
   MediaSceneTemplate
-} from "./chunk-XBIKTSFY.js";
-import "./chunk-MGCD3ZJ3.js";
-import "./chunk-DD4ZSYKG.js";
+} from "./chunk-PMJNBR4F.js";
+import "./chunk-X4RGAEL5.js";
+import "./chunk-OBRKB7PL.js";
 import "./chunk-224QNWRA.js";
 import "./chunk-OOBT4X46.js";
 export {

package/dist/{comparison-74B2XEH4.js → comparison-T27C7FSV.js}

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-JNZRVC45.js";
-import "./chunk-MGCD3ZJ3.js";
-import "./chunk-DD4ZSYKG.js";
+} from "./chunk-MKMCX3AF.js";
+import "./chunk-X4RGAEL5.js";
+import "./chunk-OBRKB7PL.js";
 import {
   editorialLabel,
   fade

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

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-JNZRVC45.js";
-import "./chunk-MGCD3ZJ3.js";
-import "./chunk-DD4ZSYKG.js";
+} from "./chunk-MKMCX3AF.js";
+import "./chunk-X4RGAEL5.js";
+import "./chunk-OBRKB7PL.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";

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

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-JNZRVC45.js";
-import "./chunk-MGCD3ZJ3.js";
-import "./chunk-DD4ZSYKG.js";
+} from "./chunk-MKMCX3AF.js";
+import "./chunk-X4RGAEL5.js";
+import "./chunk-OBRKB7PL.js";
 import {
   editorialLabel,
   fade

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

@@ -1,10 +1,10 @@
 import {
   MediaScene
-} from "./chunk-XBIKTSFY.js";
-import "./chunk-MGCD3ZJ3.js";
+} from "./chunk-PMJNBR4F.js";
+import "./chunk-X4RGAEL5.js";
 import {
   spring
-} from "./chunk-DD4ZSYKG.js";
+} from "./chunk-OBRKB7PL.js";
 import {
   editorialFont
 } from "./chunk-4YM2M62S.js";

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

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-JNZRVC45.js";
-import "./chunk-MGCD3ZJ3.js";
-import "./chunk-DD4ZSYKG.js";
+} from "./chunk-MKMCX3AF.js";
+import "./chunk-X4RGAEL5.js";
+import "./chunk-OBRKB7PL.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";

package/dist/react.js

@@ -1,6 +1,6 @@
 import {
   TitleSceneTemplate
-} from "./chunk-EWWCQFTI.js";
+} from "./chunk-7AA2JWHZ.js";
 import "./chunk-4YM2M62S.js";
 import {
   getSceneDuration,
@@ -40,7 +40,7 @@ import {
   VideoFrame,
   getDimensions,
   sceneReadinessKey
-} from "./chunk-VWJBIYBM.js";
+} from "./chunk-24TCMDAA.js";
 import "./chunk-224QNWRA.js";
 import "./chunk-OOBT4X46.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-AYKCBXRI.js").then((module) => ({ default: module.MediaSceneTemplate })),
-  "chapterTitle": () => import("./chapter-title-YRLIQY3V.js").then((module) => ({ default: module.TitleSceneTemplate })),
-  "editorialTimeline": () => import("./editorial-timeline-DUW7C75H.js").then((module) => ({ default: module.TimelineSceneTemplate })),
-  "mobileMessage": () => import("./mobile-message-KBLF3WUR.js").then((module) => ({ default: module.NotificationSceneTemplate })),
-  "comparison": () => import("./comparison-74B2XEH4.js").then((module) => ({ default: module.ComparisonSceneTemplate })),
-  "quote": () => import("./quote-QCGR2HOU.js").then((module) => ({ default: module.QuoteSceneTemplate })),
-  "keyFigure": () => import("./key-figure-OEWIMPGS.js").then((module) => ({ default: module.KeyFigureSceneTemplate }))
+  "cinemaMedia": () => import("./cinema-media-BVQFZL3A.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 }))
 };
 
 // src/visual-system/catalog/builtin-player.generated.ts
@@ -534,7 +534,6 @@ function usePlaybackClock({
   loopRef,
   sceneIndexRef,
   visualReadyRef,
-  posterBridgeKeysRef,
   callbacksRef,
   setCurrentTime,
   setIsPlaying
@@ -545,6 +544,10 @@ function usePlaybackClock({
     let onsetWaitSeconds = 0;
     let clockWaitSeconds = 0;
     let lastNarrationTime;
+    let committedTime = timeRef.current;
+    let groupHandoff;
+    let requestId = stateRef.current.requestId;
+    let runId = stateRef.current.runId;
     const failNarration = (error, state) => {
       setIsPlaying(false);
       try {
@@ -565,6 +568,12 @@ function usePlaybackClock({
     const tick = (now) => {
       const current = stateRef.current;
       const config = current.config;
+      const externallySeeked = timeRef.current !== committedTime;
+      const replaced = current.requestId !== requestId || current.runId !== runId;
+      requestId = current.requestId;
+      runId = current.runId;
+      if (externallySeeked || replaced) groupHandoff = void 0;
+      let deferGroupStall = false;
       const elapsed = Math.max(0, (now - previous) / 1e3);
       let narrationReady = true;
       try {
@@ -599,6 +608,7 @@ function usePlaybackClock({
           return;
         }
         clockWaitSeconds = narrationTime !== void 0 && narrationTime === lastNarrationTime && narrationReady && !stalled ? clockWaitSeconds + elapsed : 0;
+        const audioMovedBackwards = narrationTime !== void 0 && lastNarrationTime !== void 0 && narrationTime < lastNarrationTime;
         lastNarrationTime = narrationTime;
         if (clockWaitSeconds >= 8) {
           failNarration(new Error("Narration audio clock did not advance within eight seconds"), current);
@@ -613,8 +623,18 @@ function usePlaybackClock({
           nextTime = Math.min(raw, duration2);
         }
         const target = ranges.find((range) => nextTime >= range.start && nextTime < range.end) ?? ranges.at(-1);
-        const waitingForVisual = Boolean(target && visualReadyRef && visualReadyRef.current !== sceneReadinessKey(target.scene) && !posterBridgeKeysRef?.current.has(sceneReadinessKey(target.scene)));
-        if (waitingForVisual && target) nextTime = target.start;
+        const waitingForVisual = Boolean(target && visualReadyRef && visualReadyRef.current !== sceneReadinessKey(target.scene));
+        if (waitingForVisual && target) {
+          nextTime = target.start;
+          const fromGroup = cued?.scene.narrationGroup;
+          const toGroup = target.scene.narrationGroup;
+          const continuesParagraph = !externallySeeked && !replaced && !audioMovedBackwards && narrationReady && narrationTime !== void 0 && fromGroup && toGroup && fromGroup.id === toGroup.id && fromGroup.text === toGroup.text && target === ranges[sceneIndexRef.current + 1] && narrationTime > fromGroup.offsetSeconds + 0.04;
+          if (continuesParagraph) {
+            const key = `${sceneReadinessKey(cued.scene)}\0${sceneReadinessKey(target.scene)}\0${fromGroup.id}\0${fromGroup.text}`;
+            if (groupHandoff?.key !== key) groupHandoff = { key, startedAt: now };
+            deferGroupStall = !stalled && now - groupHandoff.startedAt < 200;
+          } else groupHandoff = void 0;
+        } else groupHandoff = void 0;
         if (nextTime !== timeRef.current) {
           timeRef.current = nextTime;
           setCurrentTime(nextTime);
@@ -645,7 +665,8 @@ function usePlaybackClock({
       }
       const duration = current.config ? getVideoDuration(current.config) : 0;
       const active = current.config ? resolveVideoTimeline(current.config).find((range) => timeRef.current >= range.start && timeRef.current < range.end) : void 0;
-      reportStall(Boolean(active && visualReadyRef && visualReadyRef.current !== sceneReadinessKey(active.scene) && !posterBridgeKeysRef?.current.has(sceneReadinessKey(active.scene))) || !settled && Boolean(current.config?.scenes.length) && duration > 0 && timeRef.current >= duration);
+      reportStall(Boolean(active && visualReadyRef && visualReadyRef.current !== sceneReadinessKey(active.scene) && !deferGroupStall) || !settled && Boolean(current.config?.scenes.length) && duration > 0 && timeRef.current >= duration);
+      committedTime = timeRef.current;
       if (!settled || looping || timeRef.current < duration) frame = requestAnimationFrame(tick);
       else setIsPlaying(false);
     };
@@ -732,13 +753,8 @@ function VideoPlayerRuntime({
   const loopRef = useRef(loop);
   const sceneIndexRef = useRef(-1);
   const mediaFrameReportedRef = useRef(false);
-  const posterBridgeKeysRef = useRef(/* @__PURE__ */ new Set());
   const visualReadyRef = useRef(void 0);
-  const reportVisualReady = useMemo(() => (key, error, actualVideoFrame = false, posterBridge = false) => {
-    if (posterBridge) {
-      posterBridgeKeysRef.current.add(key);
-      return;
-    }
+  const reportVisualReady = useMemo(() => (key, error, actualVideoFrame = false) => {
     if (error) {
       setIsPlaying(false);
       callbacksRef.current.onError?.(error, stateRef.current);
@@ -798,7 +814,6 @@ function VideoPlayerRuntime({
     setActiveStream(stream);
     setActiveSavedVideo(video);
     mediaFrameReportedRef.current = false;
-    posterBridgeKeysRef.current.clear();
     sceneIndexRef.current = -1;
     setReplacementPending(stream != null);
     setState(video ? savedVideoState(video) : createVideoState());
@@ -917,7 +932,6 @@ function VideoPlayerRuntime({
     loopRef,
     sceneIndexRef,
     visualReadyRef,
-    posterBridgeKeysRef,
     callbacksRef,
     setCurrentTime,
     setIsPlaying
@@ -1537,6 +1551,7 @@ async function prepareSceneMedia(variables, signal) {
 var DEFAULT_MAX_CACHED_LINES = 60;
 var SPEECH_PREPARATION_TIMEOUT_MS = 3e3;
 var FALLBACK_BITS_PER_SECOND = 128e3;
+var ACTIVATION_AUDIO = "data:audio/wav;base64,UklGRrQBAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YZABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
 var sharedContext;
 function actionEndpoint(endpoint, action) {
   const value = String(endpoint);
@@ -1689,6 +1704,14 @@ function createVideoChatVoice(options = {}) {
     },
     resume() {
       held = false;
+      if (!disposed && !silent && !generatedElement && globalThis.navigator?.userActivation?.isActive) {
+        const element = generatedElement = new Audio();
+        element.src = ACTIVATION_AUDIO;
+        try {
+          void element.play().catch(() => void 0);
+        } catch {
+        }
+      }
       if (sounding) {
         const fail = playbackFailure;
         void sounding.play().catch(() => {

package/dist/{scene-video-backdrop-MUGIXE2Q.js → scene-video-backdrop-NK2XK3XE.js}

@@ -1,6 +1,6 @@
 import {
   SceneVideoBackdrop
-} from "./chunk-DD4ZSYKG.js";
+} from "./chunk-OBRKB7PL.js";
 import "./chunk-OOBT4X46.js";
 export {
   SceneVideoBackdrop

package/dist/server.js

@@ -895,14 +895,24 @@ 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 readShot(value, clipDurationSec) {
+function chapterSubject(subject) {
+  const normalized = subject.replace(/\s+/gu, " ");
+  if (normalized.length <= 65) return normalized;
+  const prefix = normalized.slice(0, 65);
+  const boundary = prefix.lastIndexOf(" ");
+  return boundary > 0 ? prefix.slice(0, boundary) : "";
+}
+function readShot(value, clipDurationSec, answerSubject = "") {
   const item = object(value);
   const narration = text(item?.narration, 2e3);
   if (!narration) throw new Error("Chat shot requires bounded authored narration");
+  const subject = text(item?.subject, 80);
+  const title = text(item?.title, 65) || chapterSubject(subject) || chapterSubject(answerSubject);
+  if (!title) throw new Error("Chat shot requires an authored chapter title or subject");
   return {
     narration,
-    title: text(item?.title, 65) || text(item?.subject, 65) || "The next step",
-    subject: text(item?.subject, 80),
+    title,
+    subject,
     action: text(item?.action, 600),
     durationSec: typeof item?.durationSec === "number" && Number.isFinite(item.durationSec) ? Math.min(clipDurationSec, Math.max(2, item.durationSec)) : clipDurationSec,
     continuity: item?.continuity === "continue" ? "continue" : "cut"
@@ -973,7 +983,7 @@ function createChatShotPlanner(options) {
             brief = { opening: text(part.opening, 300), subject: text(part.subject, 80), visualDirection: text(part.visualDirection, 600), development: text(part.development, 2e3) };
             if (part.ending) {
               try {
-                brief.ending = readShot(part.ending, clipDurationSec);
+                brief.ending = readShot(part.ending, clipDurationSec, brief.subject);
               } catch (cause) {
                 reject(cause);
               }
@@ -983,7 +993,7 @@ function createChatShotPlanner(options) {
           }
           if (part?.type !== "shot") throw new Error("Chat plan requires an answer brief followed by shots");
           if (!brief) throw new Error("Chat shot arrived before its answer brief");
-          const shot = readShot(part, clipDurationSec);
+          const shot = readShot(part, clipDurationSec, brief.subject);
           if (shot.narration === brief.ending?.narration) return;
           if (firstBody && !continueAfterOpening(shot.narration, [options.openingLine ?? brief.opening])) return;
           const budget = (context.request.input.maxDurationSec ?? 40) - (brief.ending?.durationSec ?? clipDurationSec);

package/docs/development.md

@@ -2,7 +2,7 @@
 
 Run `npm ci --no-audit`, then `npm run dev:chat`. The localhost HMR surface renders the actual SDK `VideoChat`, templates and server handler from source. It never loads provider credentials. Select an intent and fault condition in the development toolbar; use the chat's normal media-mode controls. The prompt box remains the real product UI.
 
-Offline answers are deterministic for explanation, story, comedy, imagination, practical steps and golf. They use local waterfall footage and a recorded timing cue, **not narration that matches the displayed script**. This harness is for loading, playback, controls and recovery. It cannot prove generated answer quality. Conditions cover ready, delayed footage, missing media, decode failure, speech failure, exhausted video allowance and request throttling. Browser speech may be used in the speech-failure condition.
+Offline answers are deterministic for explanation, story, comedy, imagination, practical steps and golf. They use local waterfall footage and locally synthesized speech matching each displayed opening, body and ending. This harness lets you hear complete narration while checking loading, timing, controls and recovery without AI credits. The waterfall remains generic fixture footage; it cannot prove generated answer quality or visual relevance. See [spoken fixture provenance](https://github.com/VanillaSkyAi/video/blob/main/dev/chat/speech/README.md) for transcripts and regeneration commands. Conditions cover ready, delayed footage, missing media, decode failure, speech failure, exhausted video allowance and request throttling. Browser speech may be used in the speech-failure condition.
 
 The toolbar labels source and fixture identity. It separates the first body surface from the first decoded moving-footage frame; the former is a renderer paint opportunity and can precede decode. Its bounded safe phase log records browser request/stream arrival phases, speech response completion, first speech, footage and buffer pauses. No prompts, narration, scene IDs or provider bodies are retained. Media start/end/skip reasons come from the handler’s separate host-only `onDiagnostic` callback, shown in the local terminal for offline fixtures; live hosts own that callback themselves. Stream arrival is not the server’s exact authorship timestamp. Local fixtures never fetch external footage or invoke a paid model. Mode boundaries, provider deadlines and host admission remain covered by their dedicated server and host suites.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.5",
+  "version": "0.10.7",
   "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 { 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 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    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 time = metadata?.mediaTime ?? video.currentTime;\n      if (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 deadline = setTimeout(() => {\n      if (!stopped) { stopped = true; unavailable(); }\n    }, 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    return () => {\n      video.pause();\n      video.removeAttribute(\"src\");\n      video.load();\n      startedVideoUrl.current = undefined;\n      startedPlaybackId.current = undefined;\n    };\n  }, [mediaUrl]);\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) return;\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 { 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"
     },
     {
       "path": "src/visual-system/scene-templates/color-utils.ts",

package/registry/items/chapterTitle.json

@@ -16,7 +16,7 @@
       "path": "src/visual-system/scene-templates/chapter-title.tsx",
       "type": "registry:component",
       "target": "vanillasky/scene-templates/chapter-title.tsx",
-      "content": "import type { SceneTemplateProps } from './types';\n\nimport {editorialFont,fade as ease} from './editorial-typography';\n\n/** A quiet chapter beat: fade in, read, fade to black. */\nfunction TitleScene({ variables, width, height, progress }: SceneTemplateProps) {\n  const title = String(variables.title ?? 'A different perspective');\n  const unit = Math.min(width, height);\n  const opacity = ease(progress / .22) * (1 - ease((progress - .76) / .24));\n  return <div data-template=\"title\" data-title-treatment=\"quiet-fade\" style={{position:'absolute',inset:0,background:'#000',color:'#fff',display:'flex',alignItems:'center',justifyContent:'center'}}>\n    <div data-title-composition=\"centered\" style={{width:'76%',textAlign:'center',opacity,fontFamily:editorialFont,fontWeight:500,fontSize:unit * .068,lineHeight:1.18,letterSpacing:'-.025em',textWrap:'balance',overflowWrap:'anywhere'}}>{title}</div>\n  </div>;\n}\n\nexport const TitleSceneTemplate = TitleScene;\n"
+      "content": "import type { SceneTemplateProps } from './types';\n\nimport {editorialFont,fade as ease} from './editorial-typography';\n\n/** A quiet chapter beat: fade in, read, fade to black. */\nfunction TitleScene({ variables, width, height, progress, motionProgress }: SceneTemplateProps) {\n  const title = String(variables.title ?? 'A different perspective');\n  const unit = Math.min(width, height);\n  const presentation = motionProgress ?? progress;\n  const opacity = ease(presentation / .22) * (1 - ease((presentation - .76) / .24));\n  return <div data-template=\"title\" data-title-treatment=\"quiet-fade\" style={{position:'absolute',inset:0,background:'#000',color:'#fff',display:'flex',alignItems:'center',justifyContent:'center'}}>\n    <div data-title-composition=\"centered\" style={{width:'76%',textAlign:'center',opacity,fontFamily:editorialFont,fontWeight:500,fontSize:unit * .068,lineHeight:1.18,letterSpacing:'-.025em',textWrap:'balance',overflowWrap:'anywhere'}}>{title}</div>\n  </div>;\n}\n\nexport const TitleSceneTemplate = TitleScene;\n"
     },
     {
       "path": "src/visual-system/scene-templates/types.ts",

package/starters/video-chat/package.json

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

package/starters/video-chat/stock.ts

@@ -8,6 +8,8 @@ interface StockVideo {
 interface PexelsVideo {
   url?: string;
   image?: string;
+  title?: unknown;
+  tags?: unknown;
   video_files?: { link?: string; width?: number; height?: number; file_type?: string }[];
 }
 const cache = new Map<string, { expires: number; media: StockVideo | null }>();
@@ -21,7 +23,7 @@ function pexelsUrl(value: unknown): value is string {
   } catch { return false; }
 }
 
-/** Full catalog search. Metadata establishes subject relevance, not factual proof.
+/** Full catalog search. Available metadata ranks subject relevance, not factual proof.
  * Applications using this adapter must display a prominent link to Pexels.
  * https://www.pexels.com/api/documentation/#guidelines
  */
@@ -41,13 +43,18 @@ export async function findStockFootage(query: string, orientation: VideoOrientat
   if (!response.ok) return null;
   const result = await response.json() as { videos?: PexelsVideo[] };
   signal.throwIfAborted();
-  let selected: StockVideo | null = null, bestScore = 0;
+  let selected: StockVideo | null = null, bestScore = -1;
   for (const video of (Array.isArray(result.videos) ? result.videos : []).slice(0, 12)) {
     if (!pexelsUrl(video.url)) continue;
-    const subject = words(new URL(video.url).pathname);
+    const slug = new URL(video.url).pathname.replace(/^\/video\//, "");
+    const title = typeof video.title === "string" ? video.title : "";
+    const tags = Array.isArray(video.tags) ? video.tags.filter((tag): tag is string => typeof tag === "string").join(" ") : "";
+    const subject = words(`${slug} ${title} ${tags}`).filter(token => !/^\d+$/.test(token));
     const matches = tokens.filter(token => subject.includes(token)).length;
-    // Require a majority of the literal query, never accept search rank alone.
-    if (matches < Math.ceil(tokens.length * 0.6)) continue;
+    // The documented Video resource can have only a numeric page URL and no
+    // editorial metadata. Preserve provider search order for unknown relevance;
+    // positive overlap ranks above it, while explicitly unrelated copy is skipped.
+    if (subject.length > 0 && matches === 0) continue;
     const files = (Array.isArray(video.video_files) ? video.video_files : []).filter(file =>
       file.file_type === "video/mp4" && pexelsUrl(file.link)
       && Number.isFinite(file.width) && Number.isFinite(file.height)