@vanillaskyai/video 0.10.3 → 0.10.4

package/docs/provider-integration.md

@@ -58,14 +58,12 @@ browser speech. Supplying `generateSpeech`, `transcribe`, `searchMedia`, or
 structural and provider-neutral; their SDKs and credentials remain application
 dependencies and never enter the browser bundle.
 
-The planner emits a 6-9 word hook first, then continues into the scenes in the
-same stream. The stock lookup is a separate cancellable request, so it cannot
-delay speech or planning. A welcome card can carry a prewritten `opening`, which
-starts immediately with its already-loaded media. When generated shots are available, the
-same first streamed object reserves the exact first body scene. Its clip starts
-generating while the planner continues the story. Playback begins after its
-contiguous preparation cushion, without requiring the entire plan, and normal narration is written in that same planner call rather than
-through a second model round trip.
+The planner emits a short spoken opening, then continues the answer in the same
+stream. The default UI shows a chapter immediately. A welcome card can carry a
+prewritten `opening`, whose narration starts without waiting for the model.
+Each authored body beat prepares speech and selected footage together. Playback
+starts after its contiguous preparation cushion, without requiring the entire
+plan or a second model call for narration.
 
 The matching complete React interface is one component and one scoped style
 import:
@@ -84,9 +82,9 @@ export function App() {
 For a custom interface, use `useVideoChat` and render its `turns`, `welcome`,
 `suggestions`, `caption`, and `status`; the hook owns their network and playback
 lifecycle. Pass a selected card through
-`chat.ask(card.prompt, { opening: card.opening, openingMedia: card.media })` to
-start its hook and reuse its footage immediately. For typed prompts, the hook
-and media keyword arrive through the response stream automatically.
+`chat.ask(card.prompt, { opening: card.opening })` to start its hook immediately.
+Custom interfaces can still pass and render `openingMedia`; the default UI uses
+the chapter. Typed prompts receive their authored opening through the stream.
 
 Any AI SDK `LanguageModel` works in both `streamText` and `generateText`. Keep
 selection in one server-only module when an application supports several text

package/docs/reference/provider-adapters.md

@@ -96,8 +96,9 @@ stream-reconnect contract.
 
 Set `maxGeneratedVideos` on `createVideoChatHandler` to a nonnegative safe integer
 (default `5`). This is a per-response generation attempt limit, including
-failures. Default chat attempts generated footage before relevant stock. Use `0` to keep the configured full mode on
-stock footage. Stock lookup is independent of this limit. Retries inside your
+failures. AI mode uses authored chapter recovery after the allowance is reached;
+`0` skips all generated footage. Pexels mode searches stock independently and
+never consumes the generated-video allowance. Retries inside your
 provider callback can incur additional charges; bound those separately. Never
 copy an untrusted request value into this application-owned option.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.3",
+  "version": "0.10.4",
   "description": "Open-source voice-and-video chat SDK for AI applications.",
   "keywords": [
     "video-chat",
@@ -116,7 +116,10 @@
     "verify:api": "npm run build && node scripts/verify-public-api-surface.mjs",
     "verify:package": "npm run build && node scripts/verify-packed-package.mjs",
     "release:build": "node scripts/release-build.mjs",
-    "acceptance:chat": "tsx scripts/acceptance/run.ts"
+    "acceptance:chat": "tsx scripts/acceptance/run.ts",
+    "dev:chat": "vite --config dev/chat/vite.config.ts --open /dev/chat/",
+    "check:chat": "node scripts/chat-check.mjs",
+    "verify:release": "node scripts/chat-verify.mjs"
   },
   "peerDependencies": {
     "react": ">=18 <20",

package/registry/items/backgrounds.json

@@ -28,7 +28,7 @@
       "path": "src/visual-system/scene-templates/external-video-backdrop.tsx",
       "type": "registry:lib",
       "target": "vanillasky/scene-templates/external-video-backdrop.tsx",
-      "content": "import React from \"react\";\n\n// Source-owned templates may live in a consumer's tree while VideoFrame comes\n// from the package. Both copies must observe the same internal context or the\n// consumer template would mount a second video over the player-owned plane,\n// and would never inherit the player's native media audio state.\nexport type ExternalVideoBackdropMode = false | \"pending\" | \"ready\" | \"fallback\";\n\ninterface BackdropContextValue {\n  mode: ExternalVideoBackdropMode;\n  audioMuted: boolean;\n  audioVolume: number;\n  preparingNarration?: boolean;\n}\n\nconst DEFAULT: BackdropContextValue = { mode: false, audioMuted: true, audioVolume: 1 };\n\nconst sharedContext = globalThis as typeof globalThis & {\n  __vanillaskyVideoBackdropContext?: React.Context<BackdropContextValue>;\n};\nconst BackdropContext = sharedContext.__vanillaskyVideoBackdropContext\n  ??= React.createContext<BackdropContextValue>(DEFAULT);\n\nexport function ExternalVideoBackdropProvider({\n  mode,\n  audioMuted = true,\n  audioVolume = 1,\n  preparingNarration = false,\n  children,\n}: {\n  mode: ExternalVideoBackdropMode;\n  audioMuted?: boolean;\n  audioVolume?: number;\n  preparingNarration?: boolean;\n  children: React.ReactNode;\n}) {\n  const value = React.useMemo(\n    () => ({ mode, audioMuted, audioVolume, preparingNarration }),\n    [mode, audioMuted, audioVolume, preparingNarration],\n  );\n  return (\n    <BackdropContext.Provider value={value}>\n      {children}\n    </BackdropContext.Provider>\n  );\n}\n\nexport function useExternalVideoBackdrop(): ExternalVideoBackdropMode {\n  return React.useContext(BackdropContext).mode;\n}\n\nexport function useMediaAudio(): { muted: boolean; volume: number } {\n  const { audioMuted, audioVolume } = React.useContext(BackdropContext);\n  return { muted: audioMuted, volume: audioVolume };\n}\n\n/** Internal first-frame priming state; an explicit viewer pause never sets it. */\nexport function useNarrationPreroll(): boolean {\n  return React.useContext(BackdropContext).preparingNarration === true;\n}\n"
+      "content": "import React from \"react\";\n\n// Source-owned templates may live in a consumer's tree while VideoFrame comes\n// from the package. Both copies must observe the same internal context or the\n// consumer template would mount a second video over the player-owned plane,\n// and would never inherit the player's native media audio state.\nexport type ExternalVideoBackdropMode = false | \"pending\" | \"ready\" | \"fallback\";\n\ninterface BackdropContextValue {\n  mode: ExternalVideoBackdropMode;\n  audioMuted: boolean;\n  audioVolume: number;\n  preparingNarration?: boolean;\n  onMediaError?: () => void;\n}\n\nconst DEFAULT: BackdropContextValue = { mode: false, audioMuted: true, audioVolume: 1 };\n\nconst sharedContext = globalThis as typeof globalThis & {\n  __vanillaskyVideoBackdropContext?: React.Context<BackdropContextValue>;\n};\nconst BackdropContext = sharedContext.__vanillaskyVideoBackdropContext\n  ??= React.createContext<BackdropContextValue>(DEFAULT);\n\nexport function ExternalVideoBackdropProvider({\n  mode,\n  audioMuted = true,\n  audioVolume = 1,\n  preparingNarration = false,\n  onMediaError,\n  children,\n}: {\n  mode: ExternalVideoBackdropMode;\n  audioMuted?: boolean;\n  audioVolume?: number;\n  preparingNarration?: boolean;\n  onMediaError?: () => void;\n  children: React.ReactNode;\n}) {\n  const value = React.useMemo(\n    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),\n    [mode, audioMuted, audioVolume, preparingNarration, onMediaError],\n  );\n  return (\n    <BackdropContext.Provider value={value}>\n      {children}\n    </BackdropContext.Provider>\n  );\n}\n\nexport function useExternalVideoBackdrop(): ExternalVideoBackdropMode {\n  return React.useContext(BackdropContext).mode;\n}\n\nexport function useMediaAudio(): { muted: boolean; volume: number } {\n  const { audioMuted, audioVolume } = React.useContext(BackdropContext);\n  return { muted: audioMuted, volume: audioVolume };\n}\n\n/** Internal first-frame priming state; an explicit viewer pause never sets it. */\nexport function useNarrationPreroll(): boolean {\n  return React.useContext(BackdropContext).preparingNarration === true;\n}\n\n/** Routes local decoder/playback failures to the scene-owned recovery surface. */\nexport function useMediaFailure(): (() => void) | undefined {\n  return React.useContext(BackdropContext).onMediaError;\n}\n"
     },
     {
       "path": "src/visual-system/scene-templates/media-position.ts",
@@ -40,7 +40,7 @@
       "path": "src/visual-system/scene-templates/scene-video-backdrop.tsx",
       "type": "registry:lib",
       "target": "vanillasky/scene-templates/scene-video-backdrop.tsx",
-      "content": "import React, { useCallback, useEffect, useRef, useState } from \"react\";\nimport { getBackgroundTransform } from \"../backgrounds\";\nimport { useMediaAudio, 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 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  const continuityReplay = useRef<string | undefined>(undefined);\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    }\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 planner supplies short shots as the normal coverage. A single replay\n    // bridges exceptional speech overrun/late delivery; never loop indefinitely.\n    if (!resolvedMuted || continuityReplay.current === videoPresentationKey) {\n      setExhaustedKey(videoPresentationKey);\n      return;\n    }\n    continuityReplay.current = videoPresentationKey;\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  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"
     },
     {
       "path": "src/visual-system/scene-templates/color-utils.ts",

package/starters/video-chat/README.md

@@ -53,21 +53,19 @@ The SDK tries generated footage first, then relevant approved stock when the
 provider is unavailable, denied, or fails. Attempts, including failures, share
 the host's `maxGeneratedVideos` ceiling. A stock miss never broadens the subject
 automatically. If no relevant footage is available, narration and subtitles
-continue with an unavailable-visual state.
-
-Plan narration that fits the provider's five-second clips. Playback measures
-speech and prepares upcoming media before cuts. Verify full answers, including
-longer-than-expected speech and late or failed footage; a finished clip must not
-freeze while the answer keeps speaking.
-
-## Reviewed stock
-
-The starter's `approvedStock` index in `stock.ts` is deliberately empty. Add an
-asset only after inspecting its content, poster and allowed orientations. List
-literal matching queries and a reviewed description. Add those available
-queries to your host instructions so the planner can choose them when relevant.
-An unreviewed query returns `null` without a network search or unrelated result.
-The host owns licensing, storage, clip rendition and retention.
+continue as authored chapter scenes.
+
+Choose AI video or Pexels in Settings. Each mode uses only its selected footage
+provider, and both use chapter scenes when footage cannot be prepared. The
+Pexels adapter searches the full catalog with bounded subject matching,
+orientation selection and caching; it no longer requires a reviewed index.
+Custom interfaces must display a prominent [Pexels](https://www.pexels.com) credit.
+
+Speech and video prepare together. Keep `generatedClipDurationSec` aligned with
+the duration actually requested by the video adapter (five seconds by default).
+The planner writes natural short beats; measured speech controls scene timing.
+Silent footage loops through any remaining narration. Cancellation stops pending
+work and playback, and failed media becomes the authored chapter.
 
 The provider names its own model. Override the tested defaults with
 `ANTHROPIC_PLANNER_MODEL`, `ANTHROPIC_NARRATION_MODEL`, or `FAL_VIDEO_MODEL`

package/starters/video-chat/package.json

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

package/starters/video-chat/providers/video.ts

@@ -1,6 +1,8 @@
 import { fal } from "@fal-ai/client";
 import type { VideoChatHandlerOptions } from "@vanillaskyai/video/server";
 
+// Change only to a duration supported by the selected model and your allowance.
+const CLIP_DURATION_SEC = 5;
 const VIDEO_MODEL = process.env.FAL_VIDEO_MODEL ?? "minimax/h3-max-turbo/text-to-video";
 
 async function filmScene(
@@ -23,7 +25,7 @@ async function filmScene(
           "Natural scene sound only when appropriate. No speech, dialogue, singing, music or voiceover; narration is added separately.",
           generatedLook,
         ].filter(Boolean).join("\n\n"),
-        duration: 5,
+        duration: CLIP_DURATION_SEC,
         resolution: "480P",
         aspect_ratio: orientation === "portrait" ? "9:16" : "16:9",
         prompt_expansion_mode: "balanced",
@@ -44,7 +46,8 @@ async function filmScene(
 }
 
 /** Optional generated video and transcription; credentials remain server-only. */
-export const videoProvider: Pick<VideoChatHandlerOptions, "generateVideo" | "transcribe"> = {
+export const videoProvider: Pick<VideoChatHandlerOptions, "generateVideo" | "transcribe" | "generatedClipDurationSec"> = {
+  generatedClipDurationSec: CLIP_DURATION_SEC,
   generateVideo: process.env.FAL_KEY
     ? async (query, { generatedLook, orientation, signal, scene }) => ({
         url: await filmScene(query, generatedLook, orientation, signal, typeof scene?.variables.shotDirection === "string" ? scene.variables.shotDirection : undefined),

package/starters/video-chat/server.ts

@@ -42,7 +42,7 @@ export const handleVideoChat = createVideoChatHandler({
     return text;
   },
   searchMedia: process.env.PEXELS_API_KEY
-    ? (query, { orientation, signal, fallbackQuery }) => findStockFootage(query, orientation, signal, fallbackQuery)
+    ? (query, { orientation, signal }) => findStockFootage(query, orientation, signal)
     : undefined,
   ...providers,
   welcome: {

package/starters/video-chat/stock.ts

@@ -1,38 +1,66 @@
 import type { VideoOrientation } from "@vanillaskyai/video";
 
-export interface ApprovedStock {
-  /** Literal phrases the inspected clip actually depicts; no broad topic aliases. */
-  queries: readonly string[];
-  orientations: readonly VideoOrientation[];
-  description: string;
-  reviewedAt: string;
-  media: { url: string; type: "video" | "image"; posterUrl?: string };
+interface StockVideo {
+  url: string;
+  type: "video";
+  posterUrl?: string;
 }
-
-/** Add assets only after watching the clip and checking its crop and poster.
- * An empty collection deliberately declines stock instead of guessing from
- * search rank. The host can maintain this reviewed index independently of the SDK.
- */
-export const approvedStock: readonly ApprovedStock[] = [];
-
-const normalize = (value: string) => value.trim().toLowerCase().replace(/\s+/g, ' ');
-function approvedUrl(value: string): boolean {
-  try { const url=new URL(value);return url.protocol==='https:' && !url.username && !url.password && !url.port; }
-  catch { return false; }
+interface PexelsVideo {
+  url?: string;
+  image?: string;
+  video_files?: { link?: string; width?: number; height?: number; file_type?: string }[];
+}
+const cache = new Map<string, { expires: number; media: StockVideo | null }>();
+const words = (value: string): string[] => value.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+function pexelsUrl(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password && !url.port
+      && (url.hostname === "pexels.com" || url.hostname.endsWith(".pexels.com"));
+  } catch { return false; }
 }
 
-export async function findStockFootage(
-  query: string,
-  orientation: VideoOrientation,
-  signal: AbortSignal,
-  _fallbackQuery?: string,
-  index: readonly ApprovedStock[] = approvedStock,
-) {
+/** Full catalog search. Metadata establishes subject relevance, not factual proof.
+ * Applications using this adapter must display a prominent link to Pexels.
+ * https://www.pexels.com/api/documentation/#guidelines
+ */
+export async function findStockFootage(query: string, orientation: VideoOrientation, signal: AbortSignal) {
+  signal.throwIfAborted();
+  const normalized = query.trim().toLowerCase().replace(/\s+/g, " ");
+  const tokens = words(normalized);
+  const key = `${orientation}:${normalized}`;
+  const apiKey = process.env.PEXELS_API_KEY;
+  if (!apiKey || !tokens.length || normalized.length > 80 || tokens.length > 8) return null;
+  const existing = cache.get(key);
+  if (existing && existing.expires > Date.now()) return existing.media;
+  const url = new URL("https://api.pexels.com/v1/videos/search");
+  url.search = new URLSearchParams({ query: normalized, orientation, per_page: "12", size: "medium" }).toString();
+  const response = await fetch(url, { headers: { Authorization: apiKey }, signal });
+  signal.throwIfAborted();
+  if (!response.ok) return null;
+  const result = await response.json() as { videos?: PexelsVideo[] };
   signal.throwIfAborted();
-  const intent=normalize(query);
-  if(!intent || intent.length>80 || intent.split(' ').length>8)return null;
-  const entry=index.find(asset=>asset.reviewedAt && asset.description && asset.orientations.includes(orientation)
-    && asset.queries.some(candidate=>normalize(candidate)===intent)
-    && approvedUrl(asset.media.url) && (!asset.media.posterUrl || approvedUrl(asset.media.posterUrl)));
-  return entry ? {...entry.media} : null;
+  let selected: StockVideo | null = null, bestScore = 0;
+  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 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;
+    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)
+      && Math.min(file.width!, file.height!) >= 360
+      && (orientation === "portrait" ? file.height! > file.width! : file.width! >= file.height!),
+    ).sort((a, b) => Math.abs(Math.max(a.width!, a.height!) - 1280) - Math.abs(Math.max(b.width!, b.height!) - 1280));
+    const file = files[0];
+    if (!file || matches <= bestScore) continue;
+    bestScore = matches;
+    selected = { url: file.link!, type: "video", ...(pexelsUrl(video.image) ? { posterUrl: video.image } : {}) };
+  }
+  // Bounded process-local cache; no request signal or credentials are retained.
+  if (cache.size >= 128) cache.delete(cache.keys().next().value!);
+  cache.set(key, { expires: Date.now() + (selected ? 24 * 60 * 60_000 : 60_000), media: selected });
+  return selected;
 }

package/styles/video-chat.css

@@ -193,59 +193,6 @@
 
 .vanillasky-video-chat .stage :where(video, canvas, img) { max-width: 100%; max-height: 100%; object-fit: contain; }
 
-.vanillasky-video-chat .ground {
-  position: absolute;
-  inset: -30%;
-  background: radial-gradient(closest-side, oklch(1 0 0 / 28%), transparent 70%);
-  animation: vanillasky-video-chat-drift 9s ease-in-out infinite alternate;
-}
-
-@keyframes vanillasky-video-chat-drift {
-  from { transform: translate3d(-12%, -8%, 0) scale(1); }
-  to { transform: translate3d(14%, 10%, 0) scale(1.25); }
-}
-
-.vanillasky-video-chat .asked {
-  margin: 0 auto;
-  padding: 0 1.5rem;
-  display: grid;
-  gap: 1.1rem;
-  justify-items: center;
-  align-content: center;
-  text-align: center;
-  color: var(--vs-on-media);
-}
-
-.vanillasky-video-chat .asked-prompt {
-  margin: 0;
-  max-width: 26ch;
-  font-size: var(--vs-text-display);
-  line-height: var(--vs-lead-display);
-  letter-spacing: var(--vs-track-display);
-  font-weight: 700;
-  text-wrap: balance;
-  animation: vanillasky-video-chat-step-in 620ms ease both;
-}
-
-.vanillasky-video-chat .asked-step {
-  margin: 0;
-  font-size: var(--vs-text-subhead);
-  line-height: var(--vs-lead-subhead);
-  letter-spacing: var(--vs-track-subhead);
-  font-weight: 500;
-  background: linear-gradient(100deg, oklch(1 0 0 / 45%) 20%, oklch(1 0 0) 42%, oklch(1 0 0 / 45%) 64%);
-  background-size: 220% 100%;
-  -webkit-background-clip: text;
-  background-clip: text;
-  color: transparent;
-  animation: vanillasky-video-chat-sweep 2.4s linear infinite, vanillasky-video-chat-step-in 520ms ease both;
-}
-
-@keyframes vanillasky-video-chat-step-in {
-  from { opacity: 0; transform: translateY(6px); }
-  to { opacity: 1; transform: none; }
-}
-
 .vanillasky-video-chat .welcome { position: absolute; inset: 0; overflow: hidden; }
 
 .vanillasky-video-chat .frame-media { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
@@ -463,7 +410,6 @@
   animation: vanillasky-video-chat-fade-in 320ms ease both;
 }
 
-@keyframes vanillasky-video-chat-sweep { from { background-position: 140% 0; } to { background-position: -40% 0; } }
 
 @keyframes vanillasky-video-chat-fade-in { from { opacity: 0; } to { opacity: 1; } }
 
@@ -573,7 +519,6 @@
     animation-iteration-count: 1 !important;
     transition-duration: 0.01ms !important;
   }
-  .vanillasky-video-chat .asked-step { color: var(--vs-on-media); -webkit-text-fill-color: currentColor; }
 }
 
 .vanillasky-video-chat {
@@ -1053,12 +998,7 @@
 @media (max-width: 700px) {
   .vanillasky-video-chat .sheet-popover { max-height: calc(100% - 102px); }
 }
-.vanillasky-video-chat .opening-wash {
-  position: absolute;
-  inset: 0;
-  background: linear-gradient(180deg, rgb(8 11 22 / 12%), rgb(8 11 22 / 42%));
-  pointer-events: none;
-}
+
 .vanillasky-video-chat .ending { pointer-events: none; }
 .vanillasky-video-chat .ending .cards { pointer-events: auto; }
 
@@ -1138,3 +1078,8 @@
   backdrop-filter: none;
   -webkit-backdrop-filter: none;
 }
+
+.vanillasky-video-chat .opening-chapter { animation: vanillasky-chapter-enter 450ms ease-out both; }
+.vanillasky-video-chat .media-credit { color: var(--vs-fg); font-size: 11px; margin-left: 12px; text-underline-offset: 3px; }
+@keyframes vanillasky-chapter-enter { from { opacity: 0; } to { opacity: 1; } }
+@media (prefers-reduced-motion: reduce) { .vanillasky-video-chat .opening-chapter { animation: none; } }