@vanillaskyai/video 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -4,6 +4,16 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 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.
+
 ## 0.10.4
 
 - Show the canonical chapter immediately after submitting a prompt; remove the separate gradient loading placeholder and opening stock requests.

package/dist/check-runtime.js

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

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

@@ -267,6 +267,47 @@ var SceneVideoBackdrop = ({
       reportMediaFailure?.();
     }
   };
+  useEffect(() => {
+    if (!isPlaying || waitingKey !== videoPresentationKey) {
+      if (waitingKey) setWaitingKey(void 0);
+      return;
+    }
+    const video = videoRef.current;
+    if (!video) return;
+    let previousTime = video.currentTime;
+    let forwardFrames = 0;
+    let stopped = false;
+    let frame;
+    let poll;
+    const observe = (_now, metadata) => {
+      if (stopped) return;
+      const time = metadata?.mediaTime ?? video.currentTime;
+      if (video.seeking || time < previousTime) forwardFrames = 0;
+      else if (time > previousTime + 1e-3) forwardFrames++;
+      previousTime = time;
+      if (forwardFrames >= 2) {
+        stopped = true;
+        clearTimeout(deadline);
+        setWaitingKey(void 0);
+        return;
+      }
+      if (video.requestVideoFrameCallback) frame = video.requestVideoFrameCallback(observe);
+      else poll = setTimeout(observe, 50);
+    };
+    const deadline = setTimeout(() => {
+      if (!stopped) {
+        stopped = true;
+        unavailable();
+      }
+    }, 1e3);
+    observe();
+    return () => {
+      stopped = true;
+      clearTimeout(deadline);
+      clearTimeout(poll);
+      if (frame !== void 0) video.cancelVideoFrameCallback?.(frame);
+    };
+  }, [waitingKey, videoPresentationKey, isPlaying]);
   const fitDuration = useCallback((video) => {
     video.playbackRate = (resolvedMuted || video.preservesPitch === true) && sceneDuration && Number.isFinite(video.duration) && video.duration > 0 ? Math.max(0.75, Math.min(1, video.duration / (sceneDuration + 0.2))) : 1;
   }, [resolvedMuted, sceneDuration]);
@@ -382,13 +423,13 @@ var SceneVideoBackdrop = ({
       },
       posterPlane.presentationKey
     )),
-    (exhaustedKey === videoPresentationKey || waitingKey === videoPresentationKey) && /* @__PURE__ */ jsx(
+    exhaustedKey === videoPresentationKey && /* @__PURE__ */ jsx(
       "div",
       {
         role: "status",
-        "data-media-continuity": exhaustedKey === videoPresentationKey ? "exhausted" : "waiting",
+        "data-media-continuity": "exhausted",
         style: { position: "absolute", inset: 0, zIndex: 3, background: "#000", color: "#bbb", display: "grid", placeContent: "center", font: "14px system-ui" },
-        children: exhaustedKey === videoPresentationKey ? "Visual unavailable" : "Loading visual"
+        children: "Visual unavailable"
       }
     ),
     /* @__PURE__ */ jsx(
@@ -406,7 +447,6 @@ var SceneVideoBackdrop = ({
         onWaiting: () => {
           if (isPlaying) setWaitingKey(videoPresentationKey);
         },
-        onPlaying: () => setWaitingKey(void 0),
         onLoadedData: (event) => {
           const video = event.currentTarget;
           const markPresented = () => {
@@ -423,7 +463,7 @@ var SceneVideoBackdrop = ({
         onError,
         "data-media-position": mediaPosition,
         "data-video-backdrop": persistent ? "persistent" : "scene",
-        style: { ...mediaStyle, visibility: exhaustedKey === videoPresentationKey || waitingKey === videoPresentationKey ? "hidden" : void 0 }
+        style: { ...mediaStyle, visibility: exhaustedKey === videoPresentationKey ? "hidden" : void 0 }
       }
     )
   ] });

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

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

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

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

package/dist/{chunk-WZFLEPLM.js → chunk-VWJBIYBM.js}

@@ -209,7 +209,7 @@ var SceneBoundary = class extends Component {
   }
 };
 var SCENE_TRANSITION_SECONDS = 0.3;
-var SceneVideoBackdrop = lazy(() => import("./scene-video-backdrop-4EZVVQY7.js").then((module) => ({ default: module.SceneVideoBackdrop })));
+var SceneVideoBackdrop = lazy(() => import("./scene-video-backdrop-MUGIXE2Q.js").then((module) => ({ default: module.SceneVideoBackdrop })));
 var MEDIA_PREROLL_SECONDS = 1.2;
 var CONTIGUITY_ULP_FACTOR = 4;
 var subscribeToDecoderPolicy = () => () => {

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

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

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

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

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

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-G5TYLTL5.js";
-import "./chunk-QZAZT44G.js";
-import "./chunk-O6FBIB4L.js";
+} from "./chunk-JNZRVC45.js";
+import "./chunk-MGCD3ZJ3.js";
+import "./chunk-DD4ZSYKG.js";
 import {
   editorialLabel,
   fade

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

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-G5TYLTL5.js";
-import "./chunk-QZAZT44G.js";
-import "./chunk-O6FBIB4L.js";
+} from "./chunk-JNZRVC45.js";
+import "./chunk-MGCD3ZJ3.js";
+import "./chunk-DD4ZSYKG.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";

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

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-G5TYLTL5.js";
-import "./chunk-QZAZT44G.js";
-import "./chunk-O6FBIB4L.js";
+} from "./chunk-JNZRVC45.js";
+import "./chunk-MGCD3ZJ3.js";
+import "./chunk-DD4ZSYKG.js";
 import {
   editorialLabel,
   fade

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

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

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

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-G5TYLTL5.js";
-import "./chunk-QZAZT44G.js";
-import "./chunk-O6FBIB4L.js";
+} from "./chunk-JNZRVC45.js";
+import "./chunk-MGCD3ZJ3.js";
+import "./chunk-DD4ZSYKG.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";

package/dist/react.js

@@ -40,7 +40,7 @@ import {
   VideoFrame,
   getDimensions,
   sceneReadinessKey
-} from "./chunk-WZFLEPLM.js";
+} from "./chunk-VWJBIYBM.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-3SIGVVCY.js").then((module) => ({ default: module.MediaSceneTemplate })),
+  "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-QJU4JJWB.js").then((module) => ({ default: module.TimelineSceneTemplate })),
-  "mobileMessage": () => import("./mobile-message-ZMMTUDUQ.js").then((module) => ({ default: module.NotificationSceneTemplate })),
-  "comparison": () => import("./comparison-VDGRWPB5.js").then((module) => ({ default: module.ComparisonSceneTemplate })),
-  "quote": () => import("./quote-BB6UJT6L.js").then((module) => ({ default: module.QuoteSceneTemplate })),
-  "keyFigure": () => import("./key-figure-YUAQW6OE.js").then((module) => ({ default: module.KeyFigureSceneTemplate }))
+  "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 }))
 };
 
 // src/visual-system/catalog/builtin-player.generated.ts
@@ -1537,6 +1537,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 +1690,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-4EZVVQY7.js → scene-video-backdrop-MUGIXE2Q.js}

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

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.4",
+  "version": "0.10.6",
   "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  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 || waitingKey === videoPresentationKey) && <div\n        role=\"status\" data-media-continuity={exhaustedKey === videoPresentationKey ? \"exhausted\" : \"waiting\"}\n        style={{ position: \"absolute\", inset: 0, zIndex: 3, background: \"#000\", color: \"#bbb\", display: \"grid\", placeContent: \"center\", font: \"14px system-ui\" }}\n      >{exhaustedKey === videoPresentationKey ? \"Visual unavailable\" : \"Loading visual\"}</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        onPlaying={() => setWaitingKey(undefined)}\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 || waitingKey === 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 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"
     },
     {
       "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.4",
+    "@vanillaskyai/video": "0.10.6",
     "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)