@vanillaskyai/video 0.10.6 → 0.10.8

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/package.json

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

package/registry/items/backgrounds.json

@@ -28,7 +28,7 @@
       "path": "src/visual-system/scene-templates/external-video-backdrop.tsx",
       "type": "registry:lib",
       "target": "vanillasky/scene-templates/external-video-backdrop.tsx",
-      "content": "import React from \"react\";\n\n// Source-owned templates may live in a consumer's tree while VideoFrame comes\n// from the package. Both copies must observe the same internal context or the\n// consumer template would mount a second video over the player-owned plane,\n// and would never inherit the player's native media audio state.\nexport type ExternalVideoBackdropMode = false | \"pending\" | \"ready\" | \"fallback\";\n\ninterface BackdropContextValue {\n  mode: ExternalVideoBackdropMode;\n  audioMuted: boolean;\n  audioVolume: number;\n  preparingNarration?: boolean;\n  onMediaError?: () => void;\n}\n\nconst DEFAULT: BackdropContextValue = { mode: false, audioMuted: true, audioVolume: 1 };\n\nconst sharedContext = globalThis as typeof globalThis & {\n  __vanillaskyVideoBackdropContext?: React.Context<BackdropContextValue>;\n};\nconst BackdropContext = sharedContext.__vanillaskyVideoBackdropContext\n  ??= React.createContext<BackdropContextValue>(DEFAULT);\n\nexport function ExternalVideoBackdropProvider({\n  mode,\n  audioMuted = true,\n  audioVolume = 1,\n  preparingNarration = false,\n  onMediaError,\n  children,\n}: {\n  mode: ExternalVideoBackdropMode;\n  audioMuted?: boolean;\n  audioVolume?: number;\n  preparingNarration?: boolean;\n  onMediaError?: () => void;\n  children: React.ReactNode;\n}) {\n  const value = React.useMemo(\n    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),\n    [mode, audioMuted, audioVolume, preparingNarration, onMediaError],\n  );\n  return (\n    <BackdropContext.Provider value={value}>\n      {children}\n    </BackdropContext.Provider>\n  );\n}\n\nexport function useExternalVideoBackdrop(): ExternalVideoBackdropMode {\n  return React.useContext(BackdropContext).mode;\n}\n\nexport function useMediaAudio(): { muted: boolean; volume: number } {\n  const { audioMuted, audioVolume } = React.useContext(BackdropContext);\n  return { muted: audioMuted, volume: audioVolume };\n}\n\n/** Internal first-frame priming state; an explicit viewer pause never sets it. */\nexport function useNarrationPreroll(): boolean {\n  return React.useContext(BackdropContext).preparingNarration === true;\n}\n\n/** Routes local decoder/playback failures to the scene-owned recovery surface. */\nexport function useMediaFailure(): (() => void) | undefined {\n  return React.useContext(BackdropContext).onMediaError;\n}\n"
+      "content": "import React from \"react\";\n\n// Source-owned templates may live in a consumer's tree while VideoFrame comes\n// from the package. Both copies must observe the same internal context or the\n// consumer template would mount a second video over the player-owned plane,\n// and would never inherit the player's native media audio state.\nexport type ExternalVideoBackdropMode = false | \"pending\" | \"ready\" | \"fallback\";\n\nexport type MediaRecoveryReason = \"decode-error\" | \"frame-readiness-timeout\" | \"stalled-media\" | \"playback-error\";\n\ninterface BackdropContextValue {\n  mode: ExternalVideoBackdropMode;\n  audioMuted: boolean;\n  audioVolume: number;\n  preparingNarration?: boolean;\n  onMediaError?: (reason?: MediaRecoveryReason) => void;\n}\n\nconst DEFAULT: BackdropContextValue = { mode: false, audioMuted: true, audioVolume: 1 };\n\nconst sharedContext = globalThis as typeof globalThis & {\n  __vanillaskyVideoBackdropContext?: React.Context<BackdropContextValue>;\n};\nconst BackdropContext = sharedContext.__vanillaskyVideoBackdropContext\n  ??= React.createContext<BackdropContextValue>(DEFAULT);\n\nexport function ExternalVideoBackdropProvider({\n  mode,\n  audioMuted = true,\n  audioVolume = 1,\n  preparingNarration = false,\n  onMediaError,\n  children,\n}: {\n  mode: ExternalVideoBackdropMode;\n  audioMuted?: boolean;\n  audioVolume?: number;\n  preparingNarration?: boolean;\n  onMediaError?: (reason?: MediaRecoveryReason) => void;\n  children: React.ReactNode;\n}) {\n  const value = React.useMemo(\n    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),\n    [mode, audioMuted, audioVolume, preparingNarration, onMediaError],\n  );\n  return (\n    <BackdropContext.Provider value={value}>\n      {children}\n    </BackdropContext.Provider>\n  );\n}\n\nexport function useExternalVideoBackdrop(): ExternalVideoBackdropMode {\n  return React.useContext(BackdropContext).mode;\n}\n\nexport function useMediaAudio(): { muted: boolean; volume: number } {\n  const { audioMuted, audioVolume } = React.useContext(BackdropContext);\n  return { muted: audioMuted, volume: audioVolume };\n}\n\n/** Internal first-frame priming state; an explicit viewer pause never sets it. */\nexport function useNarrationPreroll(): boolean {\n  return React.useContext(BackdropContext).preparingNarration === true;\n}\n\n/** Routes local decoder/playback failures to the scene-owned recovery surface. */\nexport function useMediaFailure(): ((reason?: MediaRecoveryReason) => void) | undefined {\n  return React.useContext(BackdropContext).onMediaError;\n}\n"
     },
     {
       "path": "src/visual-system/scene-templates/media-position.ts",
@@ -40,7 +40,7 @@
       "path": "src/visual-system/scene-templates/scene-video-backdrop.tsx",
       "type": "registry:lib",
       "target": "vanillasky/scene-templates/scene-video-backdrop.tsx",
-      "content": "import React, { useCallback, useEffect, useRef, useState } from \"react\";\nimport { getBackgroundTransform } from \"../backgrounds\";\nimport { useMediaAudio, useMediaFailure, useNarrationPreroll } from \"./external-video-backdrop\";\nimport { resolveMediaPosition } from \"./media-position\";\n\nexport interface SceneVideoBackdropProps {\n  mediaUrl: string;\n  mediaPoster?: string;\n  mediaPosition?: string;\n  backgroundEffect?: string;\n  progress: number;\n  /** Narration-led visible duration; muted or pitch-preserving footage may be gently retimed. */\n  sceneDuration?: number;\n  /** Internal player-owned decoder priming, distinct from viewer pause. */\n  preparingNarration?: boolean;\n  beatIntensity?: number;\n  isPlaying: boolean;\n  muted?: boolean;\n  volume?: number;\n  playbackId?: string;\n  retainPoster?: boolean;\n  persistent?: boolean;\n  preparedPoster?: {\n    presentationKey: string;\n    mediaPoster: string;\n    mediaPosition: string;\n    backgroundEffect?: string;\n    /** Existing global transition progress. On decoder-constrained Safari,\n     * this fades the decoded incoming still above the outgoing video before\n     * the single video element changes source. */\n    opacity?: number;\n  };\n  onReady?: () => void;\n  onError?: () => void;\n}\n\nexport const SceneVideoBackdrop: React.FC<SceneVideoBackdropProps> = ({\n  mediaUrl,\n  mediaPoster,\n  mediaPosition = \"center\",\n  backgroundEffect,\n  progress,\n  sceneDuration,\n  preparingNarration = false,\n  beatIntensity = 0,\n  isPlaying,\n  muted,\n  volume,\n  playbackId = mediaUrl,\n  retainPoster = false,\n  persistent = false,\n  preparedPoster,\n  onReady,\n  onError,\n}) => {\n  const inheritedAudio = useMediaAudio();\n  const reportMediaFailure = useMediaFailure();\n  const inheritedPreroll = useNarrationPreroll();\n  const rewindPreroll = preparingNarration || inheritedPreroll;\n  const resolvedMuted = muted ?? inheritedAudio.muted;\n  const resolvedVolume = volume ?? inheritedAudio.volume;\n  const resolvedPosition = resolveMediaPosition(mediaPosition);\n  const bgTransform = getBackgroundTransform(backgroundEffect, progress, beatIntensity);\n  const [decodedVideoUrl, setDecodedVideoUrl] = useState<string>();\n  const [waitingKey, setWaitingKey] = useState<string>();\n  const [exhaustedKey, setExhaustedKey] = useState<string>();\n\n  const videoRef = useRef<HTMLVideoElement>(null);\n  const 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 { type MediaRecoveryReason, useMediaAudio, useMediaFailure, useNarrationPreroll } from \"./external-video-backdrop\";\nimport { resolveMediaPosition } from \"./media-position\";\n\nexport interface SceneVideoBackdropProps {\n  mediaUrl: string;\n  mediaPoster?: string;\n  mediaPosition?: string;\n  backgroundEffect?: string;\n  progress: number;\n  /** Narration-led visible duration; muted or pitch-preserving footage may be gently retimed. */\n  sceneDuration?: number;\n  /** Internal player-owned decoder priming, distinct from viewer pause. */\n  preparingNarration?: boolean;\n  beatIntensity?: number;\n  isPlaying: boolean;\n  muted?: boolean;\n  volume?: number;\n  playbackId?: string;\n  onReady?: () => void;\n  onError?: () => void;\n}\n\nexport const SceneVideoBackdrop: React.FC<SceneVideoBackdropProps> = ({\n  mediaUrl,\n  mediaPoster,\n  mediaPosition = \"center\",\n  backgroundEffect,\n  progress,\n  sceneDuration,\n  preparingNarration = false,\n  beatIntensity = 0,\n  isPlaying,\n  muted,\n  volume,\n  playbackId = mediaUrl,\n  onReady,\n  onError,\n}) => {\n  const inheritedAudio = useMediaAudio();\n  const reportMediaFailure = useMediaFailure();\n  const inheritedPreroll = useNarrationPreroll();\n  const rewindPreroll = preparingNarration || inheritedPreroll;\n  const resolvedMuted = muted ?? inheritedAudio.muted;\n  const resolvedVolume = volume ?? inheritedAudio.volume;\n  const resolvedPosition = resolveMediaPosition(mediaPosition);\n  const bgTransform = getBackgroundTransform(backgroundEffect, progress, beatIntensity);\n  const [decodedVideoUrl, setDecodedVideoUrl] = useState<string>();\n  const [waitingKey, setWaitingKey] = useState<string>();\n  const [exhaustedKey, setExhaustedKey] = useState<string>();\n\n  const videoRef = useRef<HTMLVideoElement>(null);\n  const presentedVideoUrl = useRef<string | undefined>(undefined);\n  const startedVideoUrl = useRef<string | undefined>(undefined);\n  const startedPlaybackId = useRef<string | undefined>(undefined);\n  const videoPresentationKey = `${playbackId}\\0${mediaUrl}`;\n\n  const presentationRef = useRef({ key: videoPresentationKey, playing: isPlaying });\n  presentationRef.current = { key: videoPresentationKey, playing: isPlaying };\n  const unavailable = (reason: MediaRecoveryReason = \"playback-error\") => {\n    if (presentationRef.current.key === videoPresentationKey && presentationRef.current.playing) {\n      setExhaustedKey(videoPresentationKey);\n      onError?.();\n      reportMediaFailure?.(reason);\n    }\n  };\n  useEffect(() => {\n    if (!isPlaying || waitingKey !== videoPresentationKey) {\n      if (waitingKey) setWaitingKey(undefined);\n      return;\n    }\n    const video = videoRef.current;\n    if (!video) return;\n    const expectedSource = video.getAttribute(\"src\") === mediaUrl ? video.src : undefined;\n    let awaitingFirstFrame = presentedVideoUrl.current !== mediaUrl || video.currentSrc !== expectedSource;\n    let previousTime = video.currentTime;\n    let forwardFrames = 0;\n    let stopped = false;\n    let frame: number | undefined;\n    let poll: ReturnType<typeof setTimeout> | undefined;\n    const observe = (_now?: number, metadata?: VideoFrameCallbackMetadata) => {\n      if (stopped) return;\n      const currentSource = video.currentSrc === expectedSource;\n      if (currentSource && awaitingFirstFrame && (metadata || presentedVideoUrl.current === mediaUrl)) {\n        awaitingFirstFrame = false;\n        clearTimeout(deadline);\n        deadline = setTimeout(fail, 1000);\n      }\n      const time = metadata?.mediaTime ?? video.currentTime;\n      if (!currentSource || video.seeking || time < previousTime) forwardFrames = 0;\n      else if (time > previousTime + .001) forwardFrames++;\n      previousTime = time;\n      // One seek frame is not resumed motion. Require consecutive forward\n      // observations before releasing the original bounded stall deadline.\n      if (forwardFrames >= 2) {\n        stopped = true;\n        clearTimeout(deadline);\n        setWaitingKey(undefined);\n        return;\n      }\n      if (video.requestVideoFrameCallback) frame = video.requestVideoFrameCallback(observe);\n      else poll = setTimeout(observe, 50);\n    };\n    // A seek can emit waiting without another playing event, even while frames\n    // resume. Keep the decoder visible and observe motion directly. A real\n    // stall gets the player's authored chapter instead of an endless spinner.\n    const fail = () => { if (!stopped) { stopped = true; unavailable(awaitingFirstFrame ? \"frame-readiness-timeout\" : \"stalled-media\"); } };\n    // Initial network/decode work has the same bound as mounted readiness.\n    // Only a source that has presented a frame can be judged as stalled motion.\n    let deadline = setTimeout(fail, awaitingFirstFrame ? 8000 : 1000);\n    observe();\n    return () => {\n      stopped = true;\n      clearTimeout(deadline);\n      clearTimeout(poll);\n      if (frame !== undefined) video.cancelVideoFrameCallback?.(frame);\n    };\n  }, [waitingKey, videoPresentationKey, isPlaying]);\n\n  const onReadyRef = useRef(onReady);\n  onReadyRef.current = onReady;\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    let stopped = false;\n    let frame: number | undefined;\n    const markPresented = () => {\n      if (stopped || !video.isConnected || presentationRef.current.key !== videoPresentationKey\n        || video.getAttribute(\"src\") !== mediaUrl || video.currentSrc !== video.src) return false;\n      presentedVideoUrl.current = mediaUrl;\n      video.dispatchEvent(new Event(\"vanillasky:video-frame-presented\", { bubbles: true }));\n      onReadyRef.current?.();\n      setDecodedVideoUrl(mediaUrl);\n      stopped = true;\n      return true;\n    };\n    const observe = () => {\n      if (stopped || frame !== undefined) return;\n      if (video.requestVideoFrameCallback) {\n        frame = video.requestVideoFrameCallback(() => {\n          frame = undefined;\n          if (!markPresented()) observe();\n        });\n      } else if (video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) markPresented();\n    };\n    // A cached resource can finish loading while its Suspense tree is still\n    // detached. Observe the mounted frame even if loadeddata was missed.\n    video.addEventListener(\"loadeddata\", observe);\n    observe();\n    return () => {\n      stopped = true;\n      video.removeEventListener(\"loadeddata\", observe);\n      if (frame !== undefined) video.cancelVideoFrameCallback?.(frame);\n    };\n  }, [mediaUrl, videoPresentationKey]);\n\n  const fitDuration = useCallback((video: HTMLVideoElement) => {\n    // Allow a small decode-to-speech onset margin without changing narration.\n    video.playbackRate = (resolvedMuted || video.preservesPitch === true) && sceneDuration && Number.isFinite(video.duration) && video.duration > 0\n      ? Math.max(.75, Math.min(1, video.duration / (sceneDuration + .2))) : 1;\n  }, [resolvedMuted, sceneDuration]);\n  useEffect(() => {\n    if (videoRef.current) fitDuration(videoRef.current);\n  }, [fitDuration]);\n  const continueMotion = (video: HTMLVideoElement) => {\n    if (!isPlaying) return;\n    // The finite scene clock bounds silent coverage. Speech may outlast a\n    // short clip; repeat motion until the scene ends, never audible dialogue.\n    if (!resolvedMuted) {\n      unavailable();\n      return;\n    }\n    video.currentTime = 0;\n    void video.play().catch(() => unavailable());\n  };\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    // React Strict Mode rehearses setup → cleanup → setup in development.\n    // The cleanup deliberately releases the decoder, so the repeated setup\n    // must restore the declarative source before the playback effect runs.\n    if (video.getAttribute(\"src\") !== mediaUrl) {\n      video.setAttribute(\"src\", mediaUrl);\n      video.load();\n    }\n  }, [mediaUrl]);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    // A source change already starts a native load via React's src update.\n    // Tear down the decoder only on unmount, never cancel that new request.\n    return () => {\n      video.pause();\n      video.removeAttribute(\"src\");\n      video.load();\n      startedVideoUrl.current = undefined;\n      startedPlaybackId.current = undefined;\n    };\n  }, []);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (video) video.volume = resolvedVolume;\n  }, [resolvedVolume]);\n\n  useEffect(() => {\n    const video = videoRef.current;\n    if (!video) return;\n    if (!isPlaying) {\n      video.pause();\n      if (rewindPreroll && video.currentTime > 0) video.currentTime = 0;\n      return;\n    }\n    if (startedPlaybackId.current === playbackId) {\n      if (video.ended) continueMotion(video);\n      else void video.play().catch(() => unavailable());\n      return;\n    }\n    const changingSource = startedVideoUrl.current !== undefined && startedVideoUrl.current !== mediaUrl;\n    fitDuration(video);\n    if (!changingSource && video.currentTime > 0) video.currentTime = 0;\n    video.play().catch(() => unavailable());\n    startedVideoUrl.current = mediaUrl;\n    startedPlaybackId.current = playbackId;\n  }, [isPlaying, mediaUrl, playbackId, rewindPreroll]);\n\n  const enforceRequestedPause = (event: React.SyntheticEvent<HTMLVideoElement>) => {\n    // WebKit may enter playback without a playing event while seeking or\n    // waiting. Both native start events must honor the latest requested hold.\n    if (presentationRef.current.playing) return;\n    event.currentTarget.pause();\n    if (rewindPreroll && event.currentTarget.currentTime > 0) event.currentTarget.currentTime = 0;\n  };\n\n  const mediaStyle: React.CSSProperties = {\n    position: \"absolute\",\n    inset: 0,\n    width: \"100%\",\n    height: \"100%\",\n    objectFit: \"cover\",\n    objectPosition: resolvedPosition,\n    transform: bgTransform.transform,\n    transformOrigin: bgTransform.transformOrigin,\n  };\n  return (\n    <>\n      {exhaustedKey === videoPresentationKey && <div\n        role=\"status\" data-media-continuity=\"exhausted\"\n        style={{ position: \"absolute\", inset: 0, zIndex: 3, background: \"#000\", color: \"#bbb\", display: \"grid\", placeContent: \"center\", font: \"14px system-ui\" }}\n      >Visual unavailable</div>}\n      <video\n        ref={videoRef}\n        src={mediaUrl}\n        poster={decodedVideoUrl !== mediaUrl ? mediaPoster || undefined : undefined}\n        muted={resolvedMuted}\n        loop={false}\n        playsInline\n        preload=\"auto\"\n        onLoadedMetadata={event => fitDuration(event.currentTarget)}\n        onEnded={event => continueMotion(event.currentTarget)}\n        onPlay={enforceRequestedPause}\n        onPlaying={enforceRequestedPause}\n        onWaiting={() => { if (isPlaying) setWaitingKey(videoPresentationKey); }}\n        onError={onError}\n        data-media-position={mediaPosition}\n        data-video-backdrop=\"scene\"\n        style={{ ...mediaStyle, visibility: exhaustedKey === videoPresentationKey ? \"hidden\" : undefined }}\n      />\n    </>\n  );\n};\n"
     },
     {
       "path": "src/visual-system/scene-templates/color-utils.ts",

package/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/README.md

@@ -49,15 +49,11 @@ call. A template introduction starts while footage prepares; body shots contain
 moving footage, narration and subtitles. Intent changes the visible actions and
 pacing, not the rendering pipeline.
 
-The SDK tries generated footage first, then relevant approved stock when the
-provider is unavailable, denied, or fails. Attempts, including failures, share
-the host's `maxGeneratedVideos` ceiling. A stock miss never broadens the subject
-automatically. If no relevant footage is available, narration and subtitles
-continue as authored chapter scenes.
-
 Choose AI video or Pexels in Settings. Each mode uses only its selected footage
-provider, and both use chapter scenes when footage cannot be prepared. The
-Pexels adapter searches the full catalog with bounded subject matching,
+provider, and both use chapter scenes when footage cannot be prepared. AI video
+attempts, including failures, share the host's `maxGeneratedVideos` ceiling.
+Exhausted allowance recovers directly to authored chapters without stock calls.
+The Pexels adapter searches the full catalog with bounded subject matching,
 orientation selection and caching; it no longer requires a reviewed index.
 Custom interfaces must display a prominent [Pexels](https://www.pexels.com) credit.
 

package/starters/video-chat/package.json

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

package/starters/video-chat/server.ts

@@ -25,11 +25,6 @@ export const handleVideoChat = createVideoChatHandler({
         output_config: { effort: "medium" },
       },
     },
-    onFinish: ({ finishReason, text }) => {
-      if (finishReason !== "stop") console.warn(`[planner] ${finishReason}: ${text.slice(0, 300)}`);
-      const keyed = (text.match(/"mediaKeyword"/g) ?? []).length;
-      console.log(`[planner] ${(text.match(/"scene\.add"/g) ?? []).length} scenes, ${keyed} asked for footage`);
-    },
   }),
   generateText: async ({ systemPrompt, userPrompt, maxOutputTokens, signal }) => {
     const { text } = await generateText({

package/dist/chunk-MGCD3ZJ3.js

@@ -1,207 +0,0 @@
-import {
-  BrandGradientOverlay,
-  SceneVideoBackdrop,
-  getBackgroundTransform,
-  resolveMediaPosition
-} from "./chunk-DD4ZSYKG.js";
-import {
-  resolveMediaType
-} from "./chunk-224QNWRA.js";
-import {
-  useExternalVideoBackdrop
-} from "./chunk-OOBT4X46.js";
-
-// src/visual-system/scene-templates/scene-background.tsx
-import { useEffect, useState } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-function resolveMediaTreatment(value) {
-  return value === "none" || value === "subtle" || value === "text-safe" ? value : "cinematic";
-}
-var SCRIM_STOP_COUNT = 7;
-function smoothstep(t) {
-  return t * t * (3 - 2 * t);
-}
-function easedStops(peakAlpha, start, end, direction) {
-  const alphaAt = (t) => {
-    const eased = direction === "fade-out" ? 1 - smoothstep(t) : smoothstep(t);
-    return `rgba(0,0,0,${Number((peakAlpha * eased).toFixed(3))})`;
-  };
-  const stops = [];
-  if (start > 0) stops.push(`${alphaAt(0)} 0%`);
-  for (let i = 0; i < SCRIM_STOP_COUNT; i += 1) {
-    const t = i / (SCRIM_STOP_COUNT - 1);
-    const position = Number((start + (end - start) * t).toFixed(2));
-    stops.push(`${alphaAt(t)} ${position}%`);
-  }
-  if (end < 100) stops.push(`${alphaAt(1)} 100%`);
-  return stops.join(", ");
-}
-function getMediaTreatmentLayers(value, anchor = "full") {
-  const treatment = resolveMediaTreatment(value);
-  if (treatment === "none") return [];
-  const vignette = {
-    id: "vignette",
-    background: treatment === "subtle" ? `radial-gradient(ellipse at center, ${easedStops(0.28, 45, 100, "fade-in")})` : `radial-gradient(ellipse at center, ${easedStops(0.72, 32, 100, "fade-in")})`
-  };
-  if (treatment === "subtle") return [vignette];
-  const textSafe = treatment === "text-safe";
-  const layers = [vignette];
-  if (anchor !== "bottom") {
-    layers.push({
-      id: "center-scrim",
-      background: textSafe ? `radial-gradient(ellipse 92% 58% at 50% 50%, ${easedStops(0.46, 34, 90, "fade-out")})` : `radial-gradient(ellipse 88% 52% at 50% 50%, ${easedStops(0.26, 30, 88, "fade-out")})`
-    });
-  }
-  if (anchor !== "center") {
-    layers.push({
-      id: "bottom-scrim",
-      background: `linear-gradient(to top, ${easedStops(textSafe ? 0.64 : 0.5, 8, 100, "fade-out")})`,
-      style: { top: "55%" }
-    });
-  }
-  return layers;
-}
-function initialMediaPaint(wantsMedia, resolved, mediaUrl, mediaPoster) {
-  if (typeof window === "undefined") return "ready";
-  if (!wantsMedia) return "ready";
-  if (resolved === "video") return mediaPoster ? "ready" : "pending";
-  if (typeof Image === "undefined") return "ready";
-  const cached = new Image();
-  cached.src = mediaUrl;
-  return cached.complete && cached.naturalWidth > 0 ? "ready" : "pending";
-}
-function getMediaBackgroundProps(variables) {
-  return {
-    mediaUrl: String(variables.mediaUrl || ""),
-    mediaType: String(variables.mediaType || "auto"),
-    mediaPoster: String(variables.mediaPoster || ""),
-    mediaPosition: String(variables.mediaPosition || "center"),
-    mediaTreatment: String(variables.mediaTreatment || "cinematic")
-  };
-}
-var SceneBackground = ({
-  style,
-  progress,
-  sceneDuration,
-  width: _width,
-  // accepted for symmetry; not currently used in render
-  height: _height,
-  mediaUrl = "",
-  mediaType = "auto",
-  mediaPoster,
-  mediaPosition = "center",
-  mediaTreatment = "cinematic",
-  textAnchor = "full",
-  backgroundEffect,
-  seed,
-  isPlaying = true,
-  beatIntensity = 0
-}) => {
-  void _width;
-  void _height;
-  const resolved = resolveMediaType(mediaType, mediaUrl);
-  const wantsMedia = resolved !== "gradient" && !!mediaUrl;
-  const externalVideoBackdrop = useExternalVideoBackdrop();
-  const hasExternalVideoBackdrop = externalVideoBackdrop !== false && resolved === "video";
-  const externalVideoFailed = externalVideoBackdrop === "fallback" && resolved === "video";
-  const externalVideoReady = externalVideoBackdrop === "ready" && resolved === "video";
-  const [mediaPaint, setMediaPaint] = useState(
-    () => initialMediaPaint(wantsMedia, resolved, mediaUrl, mediaPoster)
-  );
-  useEffect(() => {
-    setMediaPaint(initialMediaPaint(wantsMedia, resolved, mediaUrl, mediaPoster));
-    if (!wantsMedia || resolved !== "photo") return;
-    if (typeof Image === "undefined") return;
-    let cancelled = false;
-    const probe = new Image();
-    probe.onload = () => {
-      if (!cancelled) setMediaPaint("ready");
-    };
-    probe.onerror = () => {
-      if (!cancelled) setMediaPaint("failed");
-    };
-    probe.src = mediaUrl;
-    if (probe.complete) setMediaPaint(probe.naturalWidth > 0 ? "ready" : "failed");
-    return () => {
-      cancelled = true;
-      probe.onload = null;
-      probe.onerror = null;
-    };
-  }, [mediaUrl, mediaPoster, resolved, wantsMedia]);
-  const showMedia = wantsMedia && mediaPaint !== "failed";
-  const showTreatment = wantsMedia && mediaPaint === "ready";
-  const resolvedPosition = resolveMediaPosition(mediaPosition);
-  const resolvedTreatment = resolveMediaTreatment(mediaTreatment);
-  const treatmentLayers = getMediaTreatmentLayers(resolvedTreatment, textAnchor);
-  const gradSeed = typeof seed === "number" ? seed : typeof seed === "string" ? seed.split("").reduce((acc, c) => acc + c.charCodeAt(0), 0) : 0;
-  const bgTransform = getBackgroundTransform(
-    backgroundEffect,
-    progress,
-    beatIntensity
-  );
-  return /* @__PURE__ */ jsxs(Fragment, { children: [
-    (!hasExternalVideoBackdrop || externalVideoFailed) && /* @__PURE__ */ jsx(
-      BrandGradientOverlay,
-      {
-        style,
-        progress,
-        sceneDuration,
-        seed: gradSeed
-      }
-    ),
-    showMedia && !hasExternalVideoBackdrop && (resolved === "video" ? /* @__PURE__ */ jsx(
-      SceneVideoBackdrop,
-      {
-        mediaUrl,
-        mediaPoster,
-        mediaPosition,
-        backgroundEffect,
-        progress,
-        sceneDuration,
-        beatIntensity,
-        isPlaying,
-        onReady: () => setMediaPaint("ready"),
-        onError: () => setMediaPaint("failed")
-      }
-    ) : /* @__PURE__ */ jsx(
-      "img",
-      {
-        src: mediaUrl,
-        alt: "",
-        "aria-hidden": "true",
-        draggable: false,
-        "data-media-position": mediaPosition,
-        style: {
-          position: "absolute",
-          inset: 0,
-          transform: bgTransform.transform,
-          transformOrigin: bgTransform.transformOrigin,
-          width: "100%",
-          height: "100%",
-          objectFit: "cover",
-          objectPosition: resolvedPosition
-        }
-      }
-    )),
-    (hasExternalVideoBackdrop ? externalVideoReady : showTreatment) && !externalVideoFailed && treatmentLayers.map((layer) => /* @__PURE__ */ jsx(
-      "div",
-      {
-        "data-media-treatment": resolvedTreatment,
-        "data-media-overlay": layer.id,
-        style: {
-          position: "absolute",
-          inset: 0,
-          background: layer.background,
-          pointerEvents: "none",
-          ...layer.style
-        }
-      },
-      layer.id
-    ))
-  ] });
-};
-
-export {
-  getMediaBackgroundProps,
-  SceneBackground
-};

package/dist/scene-video-backdrop-MUGIXE2Q.js

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

package/dist/{chunk-OOBT4X46.js → chunk-5JBMYQP6.js}

@@ -1,37 +1,3 @@
-// src/visual-system/scene-templates/external-video-backdrop.tsx
-import React from "react";
-import { jsx } from "react/jsx-runtime";
-var DEFAULT = { mode: false, audioMuted: true, audioVolume: 1 };
-var sharedContext = globalThis;
-var BackdropContext = sharedContext.__vanillaskyVideoBackdropContext ??= React.createContext(DEFAULT);
-function ExternalVideoBackdropProvider({
-  mode,
-  audioMuted = true,
-  audioVolume = 1,
-  preparingNarration = false,
-  onMediaError,
-  children
-}) {
-  const value = React.useMemo(
-    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),
-    [mode, audioMuted, audioVolume, preparingNarration, onMediaError]
-  );
-  return /* @__PURE__ */ jsx(BackdropContext.Provider, { value, children });
-}
-function useExternalVideoBackdrop() {
-  return React.useContext(BackdropContext).mode;
-}
-function useMediaAudio() {
-  const { audioMuted, audioVolume } = React.useContext(BackdropContext);
-  return { muted: audioMuted, volume: audioVolume };
-}
-function useNarrationPreroll() {
-  return React.useContext(BackdropContext).preparingNarration === true;
-}
-function useMediaFailure() {
-  return React.useContext(BackdropContext).onMediaError;
-}
-
 // src/visual-system/scene-templates/tokens.ts
 var STYLE_PRESETS = {
   bold: {
@@ -144,6 +110,40 @@ function darken(hex, factor) {
   return `#${ch(1)}${ch(3)}${ch(5)}`;
 }
 
+// src/visual-system/scene-templates/external-video-backdrop.tsx
+import React from "react";
+import { jsx } from "react/jsx-runtime";
+var DEFAULT = { mode: false, audioMuted: true, audioVolume: 1 };
+var sharedContext = globalThis;
+var BackdropContext = sharedContext.__vanillaskyVideoBackdropContext ??= React.createContext(DEFAULT);
+function ExternalVideoBackdropProvider({
+  mode,
+  audioMuted = true,
+  audioVolume = 1,
+  preparingNarration = false,
+  onMediaError,
+  children
+}) {
+  const value = React.useMemo(
+    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),
+    [mode, audioMuted, audioVolume, preparingNarration, onMediaError]
+  );
+  return /* @__PURE__ */ jsx(BackdropContext.Provider, { value, children });
+}
+function useExternalVideoBackdrop() {
+  return React.useContext(BackdropContext).mode;
+}
+function useMediaAudio() {
+  const { audioMuted, audioVolume } = React.useContext(BackdropContext);
+  return { muted: audioMuted, volume: audioVolume };
+}
+function useNarrationPreroll() {
+  return React.useContext(BackdropContext).preparingNarration === true;
+}
+function useMediaFailure() {
+  return React.useContext(BackdropContext).onMediaError;
+}
+
 export {
   resolveDensity,
   resolveTokens,