@vanillaskyai/video 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.11.2
+
+- Show the spoken introduction in the normal subtitle line when subtitles are enabled. Keep the opening once in the full transcript, including replay and restored sessions.
+- Keep “Ask next” directly above its follow-up thumbnails on desktop and phone layouts.
+- Allow one native-speed repeat for a small measured speech overrun on healthy footage, ending when speech finishes. Never repeat solely for the quiet tail; retain chapter recovery for larger or unmeasured overruns and failed media. Planning still targets a 0.8-second tail and never buys an extra clip to fit narration.
+
 ## 0.11.1
 
 - Plan single-idea narration with voice headroom against the configured video duration; keep the full repair budget for necessary meaning. Give the single rewrite explicit speech/word budgets and report content-free outcomes instead of silently collapsing timeout, empty, failed and oversized results.

package/PUBLIC-API.md

@@ -35,7 +35,7 @@ Two visual modes remain: `cinematic` (AI video) and `pexels` (application-owned
 
 The video callback receives `requestedDurationSec`, `shotDirection` and an absolute `deadlineAt`, alongside its abort signal. Returned media may report `durationSec`. Configure the model, clip duration and timeout together in the application adapter; the server accepts timeouts up to ten minutes, while the client defaults to an eleven-minute response deadline. These are safety ceilings, not latency promises.
 
-Planning and playback share one conservative narration budget, reserving at least 0.8 seconds of quiet footage. Before buying a clip, the handler allows one bounded `generateText` call with task `narration-rewrite`. Oversized or failed rewrites retain the original narration on a chapter and do not buy a clip. Measured audio and decoded footage are checked again before playback; normal video runs at its native speed without repeats. Rewriting is model-assisted, not automatic fact verification.
+Planning targets at least 0.8 seconds of quiet footage after narration. Before buying a clip, the handler allows one bounded `generateText` call with task `narration-rewrite`. Oversized or failed rewrites retain the original narration on a chapter and do not buy a clip. Measured audio and decoded footage are checked again before playback; normal video runs at its native speed without repeats. A measured speech overrun of at most the smaller of one second or 25% of the actual clip may repeat healthy footage once, ending at speech completion. Footage never repeats just to fill a quiet tail; larger/unmeasured overruns and failed media recover to a chapter. Rewriting is model-assisted, not automatic fact verification.
 
 `authorize` is required; use `authorize: "none"` only for intentionally local/test handlers. `invalidPartBehavior: "drop"` preserves valid scenes after malformed planner output; `"fail"` opts into strict failure. Interrupted plans preserve playable partial answers and emit a safe warning. The narration action is a fallback for missing narration, not a second model call in the normal path.
 

package/README.md

@@ -67,8 +67,9 @@ substitutes stock; stock mode never spends on generated video. A failed or late
 clip becomes a narrated chapter. Narration targets a 0.8-second visual tail;
 one short rewrite may fit an oversized beat before generation. If it still
 does not fit, the complete original narration plays over a chapter. Footage
-plays once at native speed; unexpected overruns recover to a chapter without
-cutting off the sentence.
+normally plays once at native speed. A small measured speech overrun can repeat
+healthy footage once, only until speech finishes; larger or unmeasured overruns
+recover to a chapter without cutting off the sentence.
 
 This is progressive **scene** delivery, not real-time frames from every vendor.
 Some generation APIs take minutes; preloading cannot remove that latency.

package/dist/chunk-NEKYSCT6.js

@@ -0,0 +1,39 @@
+// src/protocol/clip-budget.ts
+var CLIP_NARRATION_TAIL_SEC = 0.8;
+function clipNarrationBudget(clipDurationSec) {
+  const maxSpeechSec = Math.max(0, clipDurationSec - CLIP_NARRATION_TAIL_SEC);
+  const maxWords = Math.floor(maxSpeechSec * 2);
+  const maxUnspacedCharacters = Math.floor(maxSpeechSec * 3);
+  return {
+    clipDurationSec,
+    maxSpeechSec,
+    targetWords: Math.floor(maxWords * 0.8),
+    targetUnspacedCharacters: Math.floor(maxUnspacedCharacters * 0.8),
+    maxWords,
+    maxUnspacedCharacters
+  };
+}
+var UNSPACED_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Script=Thai}\p{Script=Lao}\p{Script=Khmer}\p{Script=Myanmar}]/gu;
+function estimateNarrationSeconds(text) {
+  const normalized = text.trim();
+  if (!normalized) return 0;
+  const characters = normalized.match(UNSPACED_SCRIPT)?.length ?? 0;
+  const words = normalized.replace(UNSPACED_SCRIPT, " ").match(/[\p{L}\p{N}]+(?:['’][\p{L}\p{N}]+)*/gu)?.length ?? 0;
+  const numericExpansion = (normalized.match(/\p{Nd}+/gu) ?? []).reduce((sum, digits) => sum + Math.max(0, digits.length - 1) + (digits.length >= 3 ? 1 : 0), 0);
+  const symbols = normalized.match(/[%°\p{Sc}]/gu)?.length ?? 0;
+  const pauses = normalized.match(/[.!?。！？;；:：]/gu)?.length ?? 0;
+  return (words + numericExpansion + symbols) / 2.2 + characters / 3.5 + pauses * 0.15;
+}
+function speechFitsClip(seconds, durationSec) {
+  return Number.isFinite(seconds) && seconds >= 0 && Number.isFinite(durationSec) && durationSec > 0 && seconds + CLIP_NARRATION_TAIL_SEC <= durationSec + 1e-6;
+}
+function narrationFitsClip(text, durationSec) {
+  return speechFitsClip(estimateNarrationSeconds(text), durationSec);
+}
+
+export {
+  CLIP_NARRATION_TAIL_SEC,
+  clipNarrationBudget,
+  estimateNarrationSeconds,
+  narrationFitsClip
+};

package/dist/{chunk-666HGTVZ.js → chunk-R2RJIB6B.js}

@@ -1,3 +1,7 @@
+import {
+  CLIP_NARRATION_TAIL_SEC
+} from "./chunk-NEKYSCT6.js";
+
 // src/visual-system/scene-templates/external-video-backdrop.tsx
 import React from "react";
 import { jsx } from "react/jsx-runtime";
@@ -32,10 +36,20 @@ function useMediaFailure() {
   return React.useContext(BackdropContext).onMediaError;
 }
 
+// src/player/clip-repeat.ts
+function measuredClipPlayback(spokenSeconds, clipDurationSec) {
+  if (typeof spokenSeconds !== "number" || !Number.isFinite(spokenSeconds) || spokenSeconds <= 0 || !Number.isFinite(clipDurationSec) || clipDurationSec <= 0) return void 0;
+  const overrun = spokenSeconds - clipDurationSec;
+  if (overrun <= 0) return { durationSec: Math.min(spokenSeconds + CLIP_NARRATION_TAIL_SEC, clipDurationSec), repeat: false };
+  if (overrun <= Math.min(1, clipDurationSec * 0.25) + 1e-6) return { durationSec: spokenSeconds, repeat: true };
+  return void 0;
+}
+
 export {
   ExternalVideoBackdropProvider,
   useExternalVideoBackdrop,
   useMediaAudio,
   useNarrationPreroll,
-  useMediaFailure
+  useMediaFailure,
+  measuredClipPlayback
 };

package/dist/{chunk-RFXHLLYU.js → chunk-XJ36A5JD.js}

@@ -136,39 +136,6 @@ function videoSseHeaders(headers) {
   return result;
 }
 
-// src/protocol/clip-budget.ts
-var CLIP_NARRATION_TAIL_SEC = 0.8;
-function clipNarrationBudget(clipDurationSec) {
-  const maxSpeechSec = Math.max(0, clipDurationSec - CLIP_NARRATION_TAIL_SEC);
-  const maxWords = Math.floor(maxSpeechSec * 2);
-  const maxUnspacedCharacters = Math.floor(maxSpeechSec * 3);
-  return {
-    clipDurationSec,
-    maxSpeechSec,
-    targetWords: Math.floor(maxWords * 0.8),
-    targetUnspacedCharacters: Math.floor(maxUnspacedCharacters * 0.8),
-    maxWords,
-    maxUnspacedCharacters
-  };
-}
-var UNSPACED_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Script=Thai}\p{Script=Lao}\p{Script=Khmer}\p{Script=Myanmar}]/gu;
-function estimateNarrationSeconds(text) {
-  const normalized = text.trim();
-  if (!normalized) return 0;
-  const characters = normalized.match(UNSPACED_SCRIPT)?.length ?? 0;
-  const words = normalized.replace(UNSPACED_SCRIPT, " ").match(/[\p{L}\p{N}]+(?:['’][\p{L}\p{N}]+)*/gu)?.length ?? 0;
-  const numericExpansion = (normalized.match(/\p{Nd}+/gu) ?? []).reduce((sum, digits) => sum + Math.max(0, digits.length - 1) + (digits.length >= 3 ? 1 : 0), 0);
-  const symbols = normalized.match(/[%°\p{Sc}]/gu)?.length ?? 0;
-  const pauses = normalized.match(/[.!?。！？;；:：]/gu)?.length ?? 0;
-  return (words + numericExpansion + symbols) / 2.2 + characters / 3.5 + pauses * 0.15;
-}
-function speechFitsClip(seconds, durationSec) {
-  return Number.isFinite(seconds) && seconds >= 0 && Number.isFinite(durationSec) && durationSec > 0 && seconds + CLIP_NARRATION_TAIL_SEC <= durationSec + 1e-6;
-}
-function narrationFitsClip(text, durationSec) {
-  return speechFitsClip(estimateNarrationSeconds(text), durationSec);
-}
-
 export {
   WELCOME_CARDS,
   orderWelcomeCards,
@@ -176,10 +143,5 @@ export {
   MEDIA_RECOVERY_NOTICE,
   encodeVideoSseEvent,
   decodeVideoSse,
-  videoSseHeaders,
-  CLIP_NARRATION_TAIL_SEC,
-  clipNarrationBudget,
-  estimateNarrationSeconds,
-  speechFitsClip,
-  narrationFitsClip
+  videoSseHeaders
 };

package/dist/{cinema-media-YZ2UANJG.js → cinema-media-DLIYPESB.js}

@@ -1,12 +1,14 @@
 import {
+  measuredClipPlayback,
   useExternalVideoBackdrop,
   useMediaAudio,
   useMediaFailure,
   useNarrationPreroll
-} from "./chunk-666HGTVZ.js";
+} from "./chunk-R2RJIB6B.js";
 import {
   resolveMediaType
 } from "./chunk-K5J7ESRO.js";
+import "./chunk-NEKYSCT6.js";
 
 // src/visual-system/scene-templates/scene-background.tsx
 import { useEffect as useEffect2, useState as useState2 } from "react";
@@ -32,6 +34,7 @@ var SceneVideoBackdrop = ({
   mediaPosition = "center",
   progress,
   sceneDuration,
+  measuredSpeechDurationSec,
   preparingNarration = false,
   isPlaying,
   muted,
@@ -50,15 +53,18 @@ var SceneVideoBackdrop = ({
   const [decodedVideoUrl, setDecodedVideoUrl] = useState();
   const [waitingKey, setWaitingKey] = useState();
   const [exhaustedKey, setExhaustedKey] = useState();
+  const [repeatingKey, setRepeatingKey] = useState();
+  const [endedKey, setEndedKey] = useState();
   const videoRef = useRef(null);
   const playableVideoUrl = useRef(void 0);
   const startedVideoUrl = useRef(void 0);
   const startedPlaybackId = useRef(void 0);
   const videoPresentationKey = `${playbackId}\0${mediaUrl}`;
-  const presentationRef = useRef({ key: videoPresentationKey, playing: isPlaying });
+  const presentationRef = useRef({ key: videoPresentationKey, playing: isPlaying, progress });
   const failedPresentationRef = useRef(void 0);
+  const repeatedPresentationRef = useRef(void 0);
   const previousProgressRef = useRef({ key: videoPresentationKey, progress });
-  presentationRef.current = { key: videoPresentationKey, playing: isPlaying };
+  presentationRef.current = { key: videoPresentationKey, playing: isPlaying, progress };
   const unavailable = (reason = "playback-error") => {
     if (presentationRef.current.key === videoPresentationKey && failedPresentationRef.current !== videoPresentationKey && (presentationRef.current.playing || reason === "duration-mismatch")) {
       failedPresentationRef.current = videoPresentationKey;
@@ -152,20 +158,60 @@ var SceneVideoBackdrop = ({
       if (frame !== void 0) video.cancelVideoFrameCallback?.(frame);
     };
   }, [mediaUrl, videoPresentationKey]);
+  const allowsRepeat = (video) => {
+    const fit = measuredClipPlayback(measuredSpeechDurationSec, video.duration);
+    return fit?.repeat === true && sceneDuration !== void 0 && sceneDuration <= fit.durationSec + 1e-6;
+  };
   const fitDuration = useCallback((video) => {
     video.playbackRate = 1;
-    if (sceneDuration && Number.isFinite(video.duration) && video.duration > 0 && sceneDuration > video.duration + 0.05) {
+    if (sceneDuration && Number.isFinite(video.duration) && video.duration > 0 && sceneDuration > video.duration + 0.05 && !allowsRepeat(video)) {
       video.pause();
       unavailable("duration-mismatch");
       return false;
     }
     return true;
-  }, [sceneDuration, videoPresentationKey]);
+  }, [sceneDuration, measuredSpeechDurationSec, videoPresentationKey]);
   useEffect(() => {
     if (videoRef.current) fitDuration(videoRef.current);
   }, [fitDuration]);
+  useEffect(() => {
+    if (!isPlaying || endedKey !== videoPresentationKey) return;
+    const timer = setTimeout(() => {
+      if (videoRef.current?.ended) unavailable();
+    }, 50);
+    return () => clearTimeout(timer);
+  }, [endedKey, videoPresentationKey, isPlaying]);
+  useEffect(() => {
+    if (!isPlaying || repeatingKey !== videoPresentationKey) return;
+    let frame;
+    const observe = () => {
+      const video = videoRef.current;
+      const fit = video && measuredClipPlayback(measuredSpeechDurationSec, video.duration);
+      if (!video || presentationRef.current.progress >= 1) return;
+      if (!fit?.repeat || video.currentTime > fit.durationSec - video.duration + 0.05) {
+        unavailable("duration-mismatch");
+        return;
+      }
+      frame = requestAnimationFrame(observe);
+    };
+    frame = requestAnimationFrame(observe);
+    return () => cancelAnimationFrame(frame);
+  }, [repeatingKey, videoPresentationKey, isPlaying, measuredSpeechDurationSec]);
   const finishMotion = () => {
     if (!isPlaying) return;
+    const video = videoRef.current;
+    const fit = video && measuredClipPlayback(measuredSpeechDurationSec, video.duration);
+    if (video?.ended && fit && !fit.repeat && sceneDuration !== void 0 && sceneDuration <= video.duration + 0.05 && (1 - progress) * sceneDuration <= 0.05) {
+      setEndedKey(videoPresentationKey);
+      return;
+    }
+    if (video && video.ended && !video.error && video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA && video.currentSrc === video.src && playableVideoUrl.current === mediaUrl && failedPresentationRef.current !== videoPresentationKey && waitingKey !== videoPresentationKey && repeatedPresentationRef.current !== videoPresentationKey && progress < 1 && allowsRepeat(video)) {
+      repeatedPresentationRef.current = videoPresentationKey;
+      setRepeatingKey(videoPresentationKey);
+      video.currentTime = 0;
+      void video.play().catch(() => unavailable());
+      return;
+    }
     unavailable();
   };
   useEffect(() => {
@@ -173,11 +219,17 @@ var SceneVideoBackdrop = ({
     previousProgressRef.current = { key: videoPresentationKey, progress };
     const video = videoRef.current;
     if (!video || rewindPreroll || previous.key !== videoPresentationKey || progress >= previous.progress - 0.05 || !sceneDuration || !Number.isFinite(sceneDuration)) return;
-    video.currentTime = Math.max(0, progress * sceneDuration);
+    const target = Math.max(0, progress * sceneDuration);
+    setEndedKey(void 0);
+    const seekingRepeated = allowsRepeat(video) && target >= video.duration;
+    setRepeatingKey(seekingRepeated ? videoPresentationKey : void 0);
+    if (seekingRepeated) repeatedPresentationRef.current = videoPresentationKey;
+    else if (progress <= 1e-3) repeatedPresentationRef.current = void 0;
+    video.currentTime = seekingRepeated ? target % video.duration : target;
     failedPresentationRef.current = void 0;
     setExhaustedKey(void 0);
     if (isPlaying && video.paused) void video.play().catch(() => unavailable());
-  }, [progress, videoPresentationKey, sceneDuration, rewindPreroll, isPlaying]);
+  }, [progress, videoPresentationKey, sceneDuration, measuredSpeechDurationSec, rewindPreroll, isPlaying]);
   useEffect(() => {
     const video = videoRef.current;
     if (!video) return;
@@ -280,12 +332,14 @@ function getMediaBackgroundProps(variables) {
     mediaUrl: String(variables.mediaUrl || ""),
     mediaType: String(variables.mediaType || "auto"),
     mediaPoster: String(variables.mediaPoster || ""),
-    mediaPosition: String(variables.mediaPosition || "center")
+    mediaPosition: String(variables.mediaPosition || "center"),
+    measuredSpeechDurationSec: typeof variables.measuredSpeechDurationSec === "number" && Number.isFinite(variables.measuredSpeechDurationSec) && variables.measuredSpeechDurationSec > 0 ? variables.measuredSpeechDurationSec : void 0
   };
 }
 function SceneBackground({
   progress,
   sceneDuration,
+  measuredSpeechDurationSec,
   mediaUrl = "",
   mediaType = "auto",
   mediaPoster,
@@ -328,6 +382,7 @@ function SceneBackground({
         mediaPosition,
         progress,
         sceneDuration,
+        measuredSpeechDurationSec,
         isPlaying,
         onError: () => setFailedUrl(mediaUrl)
       }

package/dist/react.js

@@ -3,8 +3,9 @@ import {
   getBuiltinSceneDefinition
 } from "./chunk-NM4CXXZY.js";
 import {
-  ExternalVideoBackdropProvider
-} from "./chunk-666HGTVZ.js";
+  ExternalVideoBackdropProvider,
+  measuredClipPlayback
+} from "./chunk-R2RJIB6B.js";
 import {
   TitleSceneTemplate
 } from "./chunk-5DOQTIMD.js";
@@ -18,14 +19,15 @@ import {
   resolveVideoTimeline
 } from "./chunk-AUN4S3YW.js";
 import {
-  CLIP_NARRATION_TAIL_SEC,
   MEDIA_RECOVERY_NOTICE,
   decodeVideoSse,
-  estimateNarrationSeconds,
   orderWelcomeCards,
-  speechFitsClip,
   welcomeVisitSeed
-} from "./chunk-RFXHLLYU.js";
+} from "./chunk-XJ36A5JD.js";
+import {
+  CLIP_NARRATION_TAIL_SEC,
+  estimateNarrationSeconds
+} from "./chunk-NEKYSCT6.js";
 import {
   withDeadline
 } from "./chunk-4G4JBMCM.js";
@@ -101,7 +103,7 @@ function MountedSceneReadiness({
           consumed = true;
           return valid;
         } } : void 0);
-      } else report?.(key, error, actualVideoFrame);
+      } else report?.(key, error, actualVideoFrame, actualVideoFrame ? presented ?? observed : void 0);
     };
     const check = () => {
       if (stopped) return;
@@ -122,6 +124,7 @@ function MountedSceneReadiness({
           const video = layer.querySelector("video");
           if (video && video.getAttribute("src") === mediaUrl && video.currentSrc === video.src && video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) {
             if (preparedProof?.consume(video)) {
+              presented = video;
               finish(void 0, true);
               return;
             }
@@ -248,7 +251,7 @@ function createRenderer(defaults, loader) {
   return Object.freeze({ component, defaults, preload });
 }
 var loaders = {
-  cinemaMedia: () => import("./cinema-media-YZ2UANJG.js").then((module) => ({ default: module.MediaSceneTemplate })),
+  cinemaMedia: () => import("./cinema-media-DLIYPESB.js").then((module) => ({ default: module.MediaSceneTemplate })),
   chapterTitle: () => import("./chapter-title-2RCXX7SN.js").then((module) => ({ default: module.TitleSceneTemplate }))
 };
 var renderers = new Map(SCENE_DEFINITIONS.map((scene) => [
@@ -1044,6 +1047,7 @@ function usePlaybackClock({
   loopRef,
   sceneIndexRef,
   visualReadyRef,
+  activeMediaRef,
   callbacksRef,
   setCurrentTime,
   setIsPlaying
@@ -1055,6 +1059,7 @@ function usePlaybackClock({
     let onsetWaitSeconds = 0;
     let clockWaitSeconds = 0;
     let lastNarrationTime;
+    let narratedKey;
     let completionHold;
     let committedTime = timeRef.current;
     let groupHandoff;
@@ -1094,6 +1099,7 @@ function usePlaybackClock({
       if (externallySeeked || replaced) {
         groupHandoff = void 0;
         completionHold = void 0;
+        narratedKey = void 0;
       }
       let deferGroupStall = false;
       let completionBlocked = false;
@@ -1132,6 +1138,8 @@ function usePlaybackClock({
         }
         clockWaitSeconds = narrationTime !== void 0 && narrationTime === lastNarrationTime && narrationReady && !stalled ? clockWaitSeconds + elapsed : 0;
         const audioMovedBackwards = narrationTime !== void 0 && lastNarrationTime !== void 0 && narrationTime < lastNarrationTime;
+        if (audioMovedBackwards) narratedKey = void 0;
+        if (cued && narrationReady && narrationTime !== void 0 && narrationTime > 0) narratedKey = sceneReadinessKey(cued.scene);
         lastNarrationTime = narrationTime;
         if (clockWaitSeconds >= 8) {
           failNarration(new Error("Narration audio clock did not advance within eight seconds"), current);
@@ -1142,6 +1150,8 @@ function usePlaybackClock({
           raw = Math.max(timeRef.current, raw);
         }
         if (cued && !cued.scene.narrationGroup && narrationTime === void 0) {
+          const measuredSpeech = cued.scene.variables.measuredSpeechDurationSec;
+          const tailSeconds = cued.scene.templateId === "cinemaMedia" && typeof measuredSpeech === "number" && Number.isFinite(measuredSpeech) && measuredSpeech > 0 ? Math.min(CLIP_NARRATION_TAIL_SEC, Math.max(0, cued.end - cued.start - measuredSpeech)) : CLIP_NARRATION_TAIL_SEC;
           let speaking = false;
           try {
             speaking = callbacksRef.current.narrationActive?.(cued.scene) === true;
@@ -1149,8 +1159,15 @@ function usePlaybackClock({
             failNarration(cause instanceof Error ? cause : new Error("Narration completion failed"), current);
             return;
           }
+          const key = sceneReadinessKey(cued.scene);
+          if (speaking && narrationReady) narratedKey = key;
+          const native = activeMediaRef?.current;
+          const media = native?.video;
+          if (!speaking && narrationReady && callbacksRef.current.narrationActive && narratedKey === key && typeof measuredSpeech === "number" && Number.isFinite(measuredSpeech) && measuredSpeech > 0 && native?.key === key && media?.isConnected && !media.error && !media.seeking && media.getAttribute("src") === String(cued.scene.variables.mediaUrl || "") && media.currentSrc === media.src && media.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA && Number.isFinite(media.currentTime) && media.currentTime >= 0 && Number.isFinite(media.duration) && media.duration > 0 && measuredSpeech <= media.duration && cued.end - cued.start <= media.duration + 0.05) {
+            raw = Math.max(raw, Math.min(cued.end, cued.start + media.currentTime));
+          }
           if (completionHold?.sceneId !== cued.scene.id) completionHold = void 0;
-          if (raw >= cued.end - CLIP_NARRATION_TAIL_SEC && speaking) {
+          if (raw >= cued.end - tailSeconds && speaking) {
             completionHold ??= { sceneId: cued.scene.id, wait: 0, tail: 0 };
             if (raw >= cued.end) completionHold.wait += elapsed;
             if (completionHold.wait >= 8) {
@@ -1163,10 +1180,10 @@ function usePlaybackClock({
             }
           } else if (completionHold && !speaking) {
             completionHold.tail += elapsed;
-            if (completionHold.tail < CLIP_NARRATION_TAIL_SEC && raw >= cued.end) {
+            if (completionHold.tail < tailSeconds && raw >= cued.end) {
               raw = Math.max(cued.start, cued.end - 0.01);
               completionBlocked = true;
-            } else if (completionHold.tail >= CLIP_NARRATION_TAIL_SEC) completionHold = void 0;
+            } else if (completionHold.tail >= tailSeconds) completionHold = void 0;
           }
         }
         let nextTime;
@@ -1322,7 +1339,9 @@ function VideoPlayerRuntime({
   const sceneIndexRef = useRef4(-1);
   const mediaFrameReportedRef = useRef4(false);
   const visualReadyRef = useRef4(void 0);
-  const reportVisualReady = useMemo(() => (key, error, actualVideoFrame = false) => {
+  const activeMediaRef = useRef4(void 0);
+  const reportVisualReady = useMemo(() => (key, error, actualVideoFrame = false, media) => {
+    activeMediaRef.current = !error && actualVideoFrame && media ? { key, video: media } : void 0;
     if (error) {
       setIsPlaying(false);
       callbacksRef.current.onError?.(error, stateRef.current);
@@ -1382,6 +1401,7 @@ function VideoPlayerRuntime({
     setActiveStream(stream);
     setActiveSavedVideo(video);
     mediaFrameReportedRef.current = false;
+    activeMediaRef.current = void 0;
     sceneIndexRef.current = -1;
     setReplacementPending(stream != null);
     setState(video ? savedVideoState(video) : createVideoState());
@@ -1494,6 +1514,7 @@ function VideoPlayerRuntime({
     loopRef,
     sceneIndexRef,
     visualReadyRef,
+    activeMediaRef,
     callbacksRef,
     setCurrentTime,
     setIsPlaying
@@ -1638,6 +1659,7 @@ function VideoPlayerRuntime({
       return;
     }
     if (!isPlaying && ended) {
+      activeMediaRef.current = void 0;
       timeRef.current = 0;
       setCurrentTime(0);
       if (audioRef.current) audioRef.current.currentTime = 0;
@@ -1942,13 +1964,21 @@ function preparedSceneDuration(scene, spokenSeconds, metadata, clipDurationSec)
   const speech = Number.isFinite(spokenSeconds) && spokenSeconds > 0 ? spokenSeconds + CLIP_NARRATION_TAIL_SEC : scene.narration ? getSpokenDuration(scene.narration) : 0;
   return Math.max(floor, speech);
 }
-function prepareNarratedScene(scene, spokenSeconds) {
+function prepareNarratedScene(scene, spokenSeconds, measured = false) {
   const requested = scene.timing.fixedDuration;
   const actual = scene.variables.mediaDurationSec;
   const clipDurationSec = scene.templateId === "cinemaMedia" ? [actual, requested].find((value) => typeof value === "number" && Number.isFinite(value) && value > 0) : void 0;
-  const recovered = clipDurationSec !== void 0 && spokenSeconds !== void 0 && !speechFitsClip(spokenSeconds, clipDurationSec);
-  const visual = recovered ? recoverSceneMedia(scene) : scene;
-  const duration = preparedSceneDuration(visual, spokenSeconds, getBuiltinSceneDefinition(visual.templateId), clipDurationSec);
+  const { measuredSpeechDurationSec: _incomingMeasurement, ...variables } = scene.variables;
+  const measuredSeconds = measured && typeof spokenSeconds === "number" && Number.isFinite(spokenSeconds) && spokenSeconds > 0 ? spokenSeconds : void 0;
+  const candidate = { ...scene, variables: {
+    ...variables,
+    ...scene.templateId === "cinemaMedia" && measuredSeconds !== void 0 ? { measuredSpeechDurationSec: measuredSeconds } : {}
+  } };
+  const fit = clipDurationSec === void 0 ? void 0 : measuredClipPlayback(measuredSeconds, clipDurationSec);
+  const recovered = clipDurationSec !== void 0 && (measuredSeconds === void 0 ? preparedSceneDuration(candidate, spokenSeconds, getBuiltinSceneDefinition(scene.templateId), clipDurationSec) > clipDurationSec : fit === void 0);
+  const visual = recovered ? recoverSceneMedia(candidate) : candidate;
+  const prepared = preparedSceneDuration(visual, spokenSeconds, getBuiltinSceneDefinition(visual.templateId), clipDurationSec);
+  const duration = fit && !recovered ? fit.repeat ? fit.durationSec : Math.min(prepared, clipDurationSec) : prepared;
   const { startTime: _start, endTime: _end, beatStart: _beatStart, beatEnd: _beatEnd, ...timing } = visual.timing;
   return { scene: { ...visual, timing: { ...timing, fixedDuration: duration } }, recovered, clipDurationSec };
 }
@@ -2011,8 +2041,8 @@ function createScenePreparation(options) {
     void prepared.catch(() => void 0);
     return prepared;
   };
-  const pace = (scene, seconds) => {
-    const prepared = prepareNarratedScene(scene, seconds);
+  const pace = (scene, seconds, measured) => {
+    const prepared = prepareNarratedScene(scene, seconds, measured);
     if (prepared.recovered) options.warn(MEDIA_RECOVERY_NOTICE);
     if (seconds !== void 0 && prepared.clipDurationSec !== void 0) {
       try {
@@ -3219,7 +3249,7 @@ function useVideoChatSession(options = {}) {
             const withNarration = line ? { ...visual, narration: line } : visual;
             const group = plannedScene.narrationGroup;
             if (group && (spoken?.supportsOffsets !== true || voiceRef.current.supportsOffsets !== true || Math.abs(spoken.seconds - group.totalSeconds) > 0.1)) throw new VideoError("Narration group requires matching measured audio with offset support", { code: "narration_group_invalid" });
-            ready[position] = group ? withNarration : preparation.pace(withNarration, spoken?.seconds);
+            ready[position] = group ? withNarration : preparation.pace(withNarration, spoken?.seconds, spoken?.supportsOffsets === true);
             flush();
           }).catch((cause) => {
             if (!isCurrent() || currentAttempt !== attempt) return;
@@ -4612,7 +4642,6 @@ function VideoChat({ options = {}, className, welcomeTitle, branding, showRecove
             "div",
             {
               className: "line-row",
-              "data-opening-copy": openingChapter && line === shown?.opening && !captionsExpanded,
               "data-expanded": captionsExpanded,
               "data-actions-visible": captionControls.visible,
               onPointerMove: captionControls.onPointerEnter,
@@ -4631,7 +4660,7 @@ function VideoChat({ options = {}, className, welcomeTitle, branding, showRecove
                     setCaptionsExpanded(false);
                   }, children: /* @__PURE__ */ jsx11(Close, {}) })
                 ] }),
-                captionsExpanded ? /* @__PURE__ */ jsx11("div", { className: "expanded-captions", role: "region", tabIndex: 0, "aria-label": "Expanded subtitles", children: fullTranscript.map((entry, index) => /* @__PURE__ */ jsx11("p", { children: entry }, index)) }) : /* @__PURE__ */ jsx11(CaptionPages, { text: openingChapter && line === shown?.opening ? "" : line, getProgress: getCaptionProgress }, `${shown?.id}:${chat.playerKey}`)
+                captionsExpanded ? /* @__PURE__ */ jsx11("div", { className: "expanded-captions", role: "region", tabIndex: 0, "aria-label": "Expanded subtitles", children: fullTranscript.map((entry, index) => /* @__PURE__ */ jsx11("p", { children: entry }, index)) }) : /* @__PURE__ */ jsx11(CaptionPages, { text: line, getProgress: getCaptionProgress }, `${shown?.id}:${chat.playerKey}`)
               ]
             }
           ) }) }),

package/dist/server.js

@@ -1,14 +1,16 @@
 import {
-  CLIP_NARRATION_TAIL_SEC,
   MEDIA_RECOVERY_NOTICE,
   WELCOME_CARDS,
-  clipNarrationBudget,
   decodeVideoSse,
   encodeVideoSseEvent,
-  estimateNarrationSeconds,
-  narrationFitsClip,
   videoSseHeaders
-} from "./chunk-RFXHLLYU.js";
+} from "./chunk-XJ36A5JD.js";
+import {
+  CLIP_NARRATION_TAIL_SEC,
+  clipNarrationBudget,
+  estimateNarrationSeconds,
+  narrationFitsClip
+} from "./chunk-NEKYSCT6.js";
 import {
   withDeadline
 } from "./chunk-4G4JBMCM.js";

package/docs/architecture.md

@@ -30,8 +30,11 @@ Narration is estimated against each clip with a 0.8-second tail. An oversized
 beat gets at most one short rewrite before footage is requested. A failed or
 still-oversized rewrite preserves the original speech in a chapter instead of
 spending on unusable footage. Measured speech remains authoritative during
-playback; video plays once and unexpected overruns recover to a chapter. Estimation is
-not a guarantee that every voice/language finishes inside its clip.
+playback. Normal footage plays once; a small measured speech overrun can repeat
+healthy footage once until speech completes. Larger or unmeasured overruns
+recover to a chapter. See the [playback bounds](media-and-audio.md#timing-and-recovery)
+for the exceptional-repeat policy. Estimation is not a guarantee that every
+voice/language finishes inside its clip.
 
 ## Where to work
 

package/docs/customization.md

@@ -72,6 +72,10 @@ await chat.ask(card.prompt, { opening: card.opening, openingMedia: card.media })
 
 Typed prompts receive their opening from the same model stream as the answer.
 The opening holds until its narration completes and the first scene is ready.
+When subtitles are enabled, the spoken opening also appears in the standard
+subtitle line. The full transcript includes that opening once, followed by the
+scene narration, including on replay and when restoring an in-memory session.
+At the end, the "Ask next" label stays directly above its follow-up cards.
 
 `portrait` reserves a 9:16 response frame; `landscape` reserves 16:9.
 The saved orientation stays stable. For responsive display without changing the

package/docs/media-and-audio.md

@@ -137,8 +137,20 @@ settings and host spending limits. The planner fits natural spoken beats to that
 budget with a 0.8-second tail. One bounded rewrite may shorten an oversized
 beat before generation; otherwise its complete narration stays on a chapter.
 Measured audio and actual decoded footage are checked before playback. Normal
-footage plays once at native speed; overruns recover to a chapter without
-cutting off narration or buying another clip.
+footage plays once at native speed. If measured speech itself exceeds a healthy
+clip by at most the smaller of one second or 25% of its length, playback may
+repeat that same clip once, stopping when speech finishes. It never repeats just
+to fill the quiet tail: when speech already fits, a shorter available tail is
+allowed. Larger or unmeasured speech overruns, missing media and failed/stalled
+decoders still recover to a chapter without cutting off narration or buying
+another clip. The mounted decoder rechecks the bound against actual footage;
+pause/resume does not grant another repeat, and explicit replay starts a fresh
+playback lifecycle.
+
+Repeat eligibility uses the prepared audio's decoded duration, not a browser
+speech estimate. A custom voice must return `supportsOffsets: true` from
+`prepare` only when its audio is measured and seekable. In-memory replay keeps
+that prepared timing; the mounted decoder still enforces the repeat bound.
 
 `generateVideoTimeoutMs` sets the first-shot preparation budget (default 15 seconds).
 Later deadlines account for their position in the answer rather than restarting

package/docs/provider-integration.md

@@ -104,8 +104,10 @@ footage generation. If the rewrite fails or still cannot fit, no video job is
 submitted for that beat: its complete original narration plays over a chapter.
 Rewrites are instructed to preserve facts and qualifications; applications
 should still evaluate meaning and timing with their actual models and voices.
-Measured speech can overrun the estimate; playback recovers to a chapter
-rather than looping or cutting off the sentence. Requested duration constrains
+Measured speech can overrun the estimate. A small measured overrun may repeat
+healthy footage once until speech finishes; other overruns recover to a chapter
+without cutting off the sentence. See the [playback bounds](media-and-audio.md#timing-and-recovery).
+Requested duration constrains
 the paid submission; a valid returned duration describes the footage actually
 available for playback. The mounted decoder also checks its physical duration.
 Without reported duration, generated footage keeps its requested budget.

package/package.json

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

package/starters/video-chat/package.json

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

package/styles/video-chat.css

@@ -887,7 +887,7 @@
 }
 
 .vanillasky-video-chat .ending { pointer-events: none; }
-.vanillasky-video-chat .ending .cards { pointer-events: auto; }
+.vanillasky-video-chat .ending .cards { pointer-events: auto; margin-block-start: 0; }
 
 /* Respect viewers who prefer solid controls over translucent media surfaces. */
 @media (prefers-reduced-transparency: reduce) {
@@ -961,12 +961,6 @@
 .vanillasky-video-chat .opening-chapter [data-title-composition="centered"] {
   animation: vanillasky-video-chat-fade-in 800ms ease both;
 }
-.vanillasky-video-chat .line-row[data-opening-copy="true"] {
-  background: transparent;
-  backdrop-filter: none;
-  -webkit-backdrop-filter: none;
-}
-
 .vanillasky-video-chat .opening-chapter { animation: vanillasky-chapter-enter 450ms ease-out both; }
 @keyframes vanillasky-chapter-enter { from { opacity: 0; } to { opacity: 1; } }
 @media (prefers-reduced-motion: reduce) { .vanillasky-video-chat .opening-chapter { animation: none; } }