@vanillaskyai/video 0.7.0 → 0.8.0

package/dist/react.js

@@ -1,31 +1,29 @@
 import {
-  createSceneTimeline,
   getSceneDuration
-} from "./chunk-SKRGRKHY.js";
+} from "./chunk-ZD2VTUYR.js";
 import {
-  VIDEO_STREAM_CONTENT_TYPE,
-  VIDEO_STREAM_HEADER,
   decodeVideoSse,
-  sanitizeVideoChatMedia
-} from "./chunk-2XT4MZ76.js";
+  sanitizeVideoChatMedia,
+  withDeadline
+} from "./chunk-APQKY6P3.js";
 import {
   applyVideoEvent,
-  createReplayableStream,
+  checksumVideo,
+  createVideoEventFactory,
   createVideoState
-} from "./chunk-GAIOHGNR.js";
+} from "./chunk-2OKB27TG.js";
 import {
   safePublicDiagnostic
 } from "./chunk-MMUXVA47.js";
 import {
   parseVideo
-} from "./chunk-2PYO6VAC.js";
+} from "./chunk-2DOLF4QN.js";
 import {
-  VIDEO_PROTOCOL_VERSION,
-  createVideoRequest
+  VIDEO_SCHEMA_VERSION
 } from "./chunk-AOWSXU2K.js";
 import {
   getBuiltinTemplateMetadata
-} from "./chunk-JNN3EYVP.js";
+} from "./chunk-4UNKZEAT.js";
 import "./chunk-3O7OMMMF.js";
 import {
   assertTemplateTransitionMetadata
@@ -33,7 +31,7 @@ import {
 import {
   VideoFrame,
   getDimensions
-} from "./chunk-K746NUIP.js";
+} from "./chunk-2USVB3CY.js";
 import "./chunk-224QNWRA.js";
 import "./chunk-5CDAM24P.js";
 import {
@@ -43,7 +41,9 @@ import {
   getVideoDuration,
   resolveVideoTimeline
 } from "./chunk-SPVTJH3F.js";
-import "./chunk-XGRA2MUV.js";
+import {
+  resolveVideoBrand
+} from "./chunk-XGRA2MUV.js";
 import "./chunk-WJ6FLKNC.js";
 import "./chunk-73NTSFFI.js";
 
@@ -1018,6 +1018,15 @@ function usePlaybackClock({
 }) {
   useEffect(() => {
     if (!isPlaying) return;
+    let stalled = false;
+    const reportStall = (next) => {
+      if (stalled === next) return;
+      stalled = next;
+      try {
+        void Promise.resolve(callbacksRef.current.onStallChange?.(next)).catch(() => void 0);
+      } catch {
+      }
+    };
     let frame = 0;
     let previous = performance.now();
     const tick = (now) => {
@@ -1067,11 +1076,15 @@ function usePlaybackClock({
         }
       }
       const duration = current.config ? getVideoDuration(current.config) : 0;
+      reportStall(!settled && Boolean(current.config?.scenes.length) && duration > 0 && timeRef.current >= duration);
       if (!settled || looping || timeRef.current < duration) frame = requestAnimationFrame(tick);
       else setIsPlaying(false);
     };
     frame = requestAnimationFrame(tick);
-    return () => cancelAnimationFrame(frame);
+    return () => {
+      cancelAnimationFrame(frame);
+      reportStall(false);
+    };
   }, [isPlaying]);
 }
 
@@ -1106,6 +1119,8 @@ function VideoPlayerRuntime({
   onComplete,
   onError,
   onSceneChange,
+  onFramePresented,
+  onStallChange,
   onStateChange
 }) {
   const nativeMediaVolume = Math.max(0, Math.min(
@@ -1140,14 +1155,25 @@ function VideoPlayerRuntime({
   const timeRef = useRef(currentTime);
   const audioRef = useRef(null);
   const introStartedAtRef = useRef(autoStartGeneration ? performance.now() : null);
-  const callbacksRef = useRef({ onComplete, onPlaybackEnd, onError, onSceneChange, onStateChange });
+  const callbacksRef = useRef({ onComplete, onPlaybackEnd, onError, onSceneChange, onFramePresented, onStallChange, onStateChange });
   const loopRef = useRef(loop);
   const sceneIndexRef = useRef(-1);
   const playbackEndedRef = useRef(false);
   stateRef.current = state;
   timeRef.current = currentTime;
-  callbacksRef.current = { onComplete, onPlaybackEnd, onError, onSceneChange, onStateChange };
+  callbacksRef.current = { onComplete, onPlaybackEnd, onError, onSceneChange, onFramePresented, onStallChange, onStateChange };
   loopRef.current = loop;
+  const reportFramePresented = useMemo(() => {
+    let reported = false;
+    return () => {
+      if (reported) return;
+      reported = true;
+      try {
+        void Promise.resolve(callbacksRef.current.onFramePresented?.()).catch(() => void 0);
+      } catch {
+      }
+    };
+  }, [stream, video]);
   const primeSoundtrack = () => {
     const audio = audioRef.current;
     if (!audio || audio.dataset.audioOutput) return;
@@ -1499,6 +1525,7 @@ function VideoPlayerRuntime({
           VideoFrame,
           {
             kit,
+            onFramePresented: !showStartPoster && onFramePresented ? reportFramePresented : void 0,
             config: displayConfig,
             time: showStartPoster ? posterTime : currentTime,
             width: dimensions.width,
@@ -1611,292 +1638,134 @@ var VideoError = class extends Error {
   }
 };
 
-// src/player/use-video.ts
-import { useCallback, useEffect as useEffect3, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
+// src/video-chat/use-video-chat.ts
+import { useCallback as useCallback2, useEffect as useEffect4, useReducer, useRef as useRef3 } from "react";
 
-// src/player/stream-video.ts
-var HTTP_ERROR_CODES = /* @__PURE__ */ new Set([
-  "body_too_large",
-  "http_error",
-  "invalid_body",
-  "invalid_cursor",
-  "invalid_input",
-  "invalid_json",
-  "invalid_request",
-  "method_not_allowed",
-  "origin_forbidden",
-  "resume_unavailable",
-  "secret_field",
-  "unauthorized"
-]);
-async function responseError(response, requestId) {
-  let code = "http_error";
-  let message = `Video response endpoint failed (${response.status})`;
-  try {
-    const body = await response.json();
-    if (body && typeof body === "object" && "error" in body) {
-      const error = body.error;
-      if (error && typeof error === "object") {
-        if ("code" in error && typeof error.code === "string" && HTTP_ERROR_CODES.has(error.code)) {
-          code = error.code;
-        }
-        if ("message" in error && typeof error.message === "string") {
-          message = safePublicDiagnostic(error.message, message);
-        }
-      }
-    }
-  } catch {
-  }
-  return new VideoError(message, { code, status: response.status, requestId });
-}
-function normalizeStreamError(cause, requestId, state, aborted) {
-  if (cause instanceof VideoError) return cause;
-  const causeError = cause instanceof Error ? cause : void 0;
-  const safeMessage = aborted ? causeError?.name === "TimeoutError" ? "Request timed out" : safePublicDiagnostic(causeError?.message, "Video generation was aborted") : causeError?.message.startsWith("Video response protocol") || causeError?.message.startsWith("Video response endpoint omitted protocol") ? safePublicDiagnostic(causeError.message, "Video response protocol failed") : "Video response stream failed";
-  return new VideoError(safeMessage, {
-    code: aborted ? "aborted" : "stream_failed",
-    requestId: state.requestId ?? requestId,
-    runId: state.runId,
-    recoverable: false
-  });
-}
-function streamVideo(options) {
-  const request = createVideoRequest(options.input, {
-    requestId: options.requestId,
-    capabilities: options.capabilities,
-    ...options.resume?.state.runId != null && options.resume.state.lastSequence >= 0 ? {
-      resume: {
-        runId: options.resume.state.runId,
-        afterSequence: options.resume.state.lastSequence
-      }
-    } : {}
-  });
-  const controller = new AbortController();
-  const forwardAbort = () => controller.abort(options.signal?.reason);
-  if (options.signal?.aborted) forwardAbort();
-  else options.signal?.addEventListener("abort", forwardAbort, { once: true });
-  let resolveResult;
-  let rejectResult;
-  let settled = false;
-  const result = new Promise((resolve, reject) => {
-    resolveResult = resolve;
-    rejectResult = reject;
-  });
-  const source = (async function* consume() {
-    let state = options.resume?.state ?? createVideoState();
-    try {
-      const fetcher = options.fetcher ?? fetch;
-      const headers = new Headers(options.headers);
-      headers.set("Accept", VIDEO_STREAM_CONTENT_TYPE);
-      headers.set("Content-Type", "application/json");
-      if (request.resume) headers.set("Last-Event-ID", `${request.resume.runId}:${request.resume.afterSequence}`);
-      const response = await fetcher(options.endpoint, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(request),
-        signal: controller.signal,
-        credentials: options.credentials
-      });
-      if (!response.ok) throw await responseError(response, request.requestId);
-      if (!response.body || !response.headers.get("content-type")?.includes("text/event-stream")) {
-        throw new Error("Video response endpoint did not return an SSE stream");
-      }
-      const protocolVersion = response.headers.get(VIDEO_STREAM_HEADER);
-      if (protocolVersion == null) {
-        throw new Error(`Video response endpoint omitted protocol version header ${VIDEO_STREAM_HEADER}`);
-      }
-      if (protocolVersion !== VIDEO_PROTOCOL_VERSION) {
-        throw new Error(
-          `Video response protocol mismatch: expected ${VIDEO_PROTOCOL_VERSION}, received ${protocolVersion}`
-        );
-      }
-      for await (const event of decodeVideoSse(response.body)) {
-        state = applyVideoEvent(state, event);
-        options.onEvent?.(event, state);
-        if (state.status === "complete" && !settled) {
-          settled = true;
-          resolveResult(state);
-        } else if (state.status === "error" && !settled) {
-          settled = true;
-          const error = state.errors.at(-1);
-          rejectResult(new VideoError(error?.message ?? "Video response could not finish", {
-            code: error?.code ?? "generation_failed",
-            status: response.status,
-            requestId: state.requestId ?? request.requestId,
-            runId: state.runId,
-            recoverable: error?.recoverable
-          }));
-        } else if (state.status === "aborted" && !settled) {
-          settled = true;
-          rejectResult(new VideoError(state.abortReason ?? "Video generation was aborted", {
-            code: "aborted",
-            status: response.status,
-            requestId: state.requestId ?? request.requestId,
-            runId: state.runId,
-            recoverable: false
-          }));
-        }
-        yield event;
-      }
-      if (!["complete", "error", "aborted"].includes(state.status)) {
-        throw new Error("Video response stream ended without a terminal event");
-      }
-      if (!settled && state.status === "complete") {
-        settled = true;
-        resolveResult(state);
+// src/protocol/scene-timeline.ts
+function createQueue() {
+  const buffered = [];
+  const waiting = [];
+  let closed = false;
+  return {
+    push(value) {
+      const next = waiting.shift();
+      if (next) next({ value, done: false });
+      else buffered.push(value);
+    },
+    close() {
+      closed = true;
+      let next = waiting.shift();
+      while (next) {
+        next({ value: void 0, done: true });
+        next = waiting.shift();
       }
-    } catch (cause) {
-      const error = normalizeStreamError(cause, request.requestId, state, controller.signal.aborted);
-      if (!settled) {
-        settled = true;
-        rejectResult(error);
+    },
+    iterable: {
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            const buffer = buffered.shift();
+            if (buffer !== void 0) return Promise.resolve({ value: buffer, done: false });
+            if (closed) return Promise.resolve({ value: void 0, done: true });
+            return new Promise((resolve) => waiting.push(resolve));
+          }
+        };
       }
-      throw error;
-    } finally {
-      options.signal?.removeEventListener("abort", forwardAbort);
-    }
-  })();
-  const stream = createReplayableStream(source, () => void 0);
-  return {
-    request,
-    stream,
-    result,
-    abort(reason = "user cancelled") {
-      controller.abort(new Error(reason));
     }
   };
 }
-
-// src/player/use-video.ts
-function defaultRequestId() {
-  const id = globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
-  return `request-${id}`;
-}
-function errorFrom(cause) {
-  if (cause instanceof VideoError) return cause;
-  const error = cause instanceof Error ? cause : new Error(String(cause));
-  return new VideoError(error.message, { code: "video_failed" });
-}
-function useVideo(options = {}) {
-  const templates = useMemo2(
-    () => overlayPlayerTemplateRegistry(BUILTIN_PLAYER_KIT, options.templates),
-    [options.templates]
-  );
-  const [state, setState] = useState2(() => createVideoState());
-  const [error, setError] = useState2();
-  const [run, setRun] = useState2();
-  const activeRun = useRef2(void 0);
-  const generation = useRef2(0);
-  const mounted = useRef2(true);
-  const optionsRef = useRef2(options);
-  const templatesRef = useRef2(templates);
-  optionsRef.current = options;
-  templatesRef.current = templates;
-  const abort = useCallback((reason = "user cancelled") => {
-    generation.current += 1;
-    const current = activeRun.current;
-    activeRun.current = void 0;
-    current?.abort(reason);
-    if (current && mounted.current) {
-      setError(new VideoError(reason, {
-        code: "aborted",
-        requestId: current.request.requestId,
-        recoverable: false
-      }));
-      setState((previous) => ({ ...previous, status: "aborted", abortReason: reason }));
+var runCounter = 0;
+function createSceneTimeline(options) {
+  const queue = createQueue();
+  const runId = options.runId ?? `composed-${runCounter += 1}`;
+  const events = createVideoEventFactory({ runId });
+  const orientation = options.orientation ?? "landscape";
+  const snapshot = {
+    schemaVersion: VIDEO_SCHEMA_VERSION,
+    orientation,
+    scenes: [],
+    style: options.style
+  };
+  let position = 0;
+  let finished = false;
+  const held = [];
+  let openForScenes = !options.awaitAudio;
+  const emit = (event) => {
+    if (finished) return;
+    queue.push(event);
+  };
+  emit(events.create("response.start", {
+    requestId: options.requestId ?? runId,
+    format: { orientation },
+    style: options.style
+  }));
+  if (options.audio) {
+    snapshot.audio = options.audio;
+    emit(events.create("audio.set", { audio: options.audio }));
+  }
+  const release = () => {
+    const pending = held.splice(0, held.length);
+    for (const scene of pending) {
+      snapshot.scenes.push(scene);
+      emit(events.create("scene.add", { scene, position: position++ }));
     }
-  }, []);
-  const generate = useCallback((input) => {
-    const currentGeneration = generation.current + 1;
-    generation.current = currentGeneration;
-    activeRun.current?.abort("replaced by a new composition");
-    const currentOptions = optionsRef.current;
-    const initialState2 = createVideoState();
-    setState({ ...initialState2, status: "streaming" });
-    setError(void 0);
-    const nextRun = streamVideo({
-      endpoint: currentOptions.endpoint ?? "/api/video",
-      input,
-      requestId: (currentOptions.createRequestId ?? defaultRequestId)(),
-      capabilities: currentOptions.templateIds ? { ...templatesRef.current.capabilities, templates: [...new Set(currentOptions.templateIds)] } : templatesRef.current.capabilities,
-      headers: currentOptions.headers,
-      credentials: currentOptions.credentials,
-      fetcher: currentOptions.fetcher,
-      onEvent: (_event, nextState) => {
-        if (_event.type === "scene.add") {
-          if (!currentOptions.templates?.getTemplate(_event.data.scene.templateId)) {
-            preloadBuiltinTemplate(_event.data.scene.templateId);
-          }
-          warmSceneMedia(_event.data.scene.variables);
-        }
-        if (mounted.current && generation.current === currentGeneration) setState(nextState);
+  };
+  return {
+    stream: queue.iterable,
+    add(scene) {
+      if (finished) return;
+      if (!openForScenes) {
+        held.push(scene);
+        return;
       }
-    });
-    activeRun.current = nextRun;
-    setRun(nextRun);
-    void nextRun.result.then(() => {
-      if (generation.current === currentGeneration) activeRun.current = void 0;
-    }).catch((cause) => {
-      if (mounted.current && generation.current === currentGeneration) {
-        activeRun.current = void 0;
-        const error2 = errorFrom(cause);
-        setError(error2);
-        setState((previous) => ({
-          ...previous,
-          status: error2.code === "aborted" ? "aborted" : "error",
-          ...error2.code === "aborted" && previous.abortReason == null ? { abortReason: error2.message } : {}
-        }));
+      snapshot.scenes.push(scene);
+      emit(events.create("scene.add", { scene, position: position++ }));
+    },
+    setAudio(audio) {
+      if (finished || openForScenes) return;
+      if (audio) {
+        snapshot.audio = audio;
+        emit(events.create("audio.set", { audio }));
       }
-    });
-    const result = nextRun.result.then((nextState) => {
-      if (!nextState.config) throw new Error("Video generation ended without a video");
-      return nextState.config;
-    });
-    void result.catch(() => void 0);
-    return result;
-  }, []);
-  useEffect3(() => {
-    mounted.current = true;
-    return () => {
-      mounted.current = false;
-      generation.current += 1;
-      activeRun.current?.abort("component unmounted");
-      activeRun.current = void 0;
-    };
-  }, []);
-  return {
-    generate,
-    abort,
-    video: state.config,
-    status: state.status,
-    error,
-    warnings: state.warnings,
-    playerProps: {
-      ...options.templates ? { templates: options.templates } : {},
-      ...run ? { stream: run.stream } : {}
+      openForScenes = true;
+      release();
+    },
+    complete() {
+      if (finished) return;
+      if (!openForScenes) {
+        openForScenes = true;
+        release();
+      }
+      emit(events.create("response.complete", {
+        finishReason: "stop",
+        snapshot,
+        checksum: checksumVideo(snapshot)
+      }));
+      finished = true;
+      queue.close();
     }
   };
 }
 
 // src/player/use-narration.ts
-import { useCallback as useCallback2, useEffect as useEffect4, useRef as useRef3, useState as useState3 } from "react";
+import { useCallback, useEffect as useEffect3, useRef as useRef2, useState as useState2 } from "react";
 function useNarration(options) {
-  const [speaking, setSpeaking] = useState3(false);
-  const optionsRef = useRef3(options);
+  const [speaking, setSpeaking] = useState2(false);
+  const optionsRef = useRef2(options);
   optionsRef.current = options;
-  const currentRef = useRef3(void 0);
-  const spokenIndexRef = useRef3(void 0);
-  const stop = useCallback2(() => {
+  const currentRef = useRef2(void 0);
+  const spokenIndexRef = useRef2(void 0);
+  const stop = useCallback(() => {
     currentRef.current?.abort();
     currentRef.current = void 0;
     setSpeaking(false);
   }, []);
-  const interrupt = useCallback2(() => {
+  const interrupt = useCallback(() => {
     spokenIndexRef.current = void 0;
     stop();
   }, [stop]);
-  useEffect4(() => () => currentRef.current?.abort(), []);
-  const onSceneChange = useCallback2((scene, index) => {
+  useEffect3(() => () => currentRef.current?.abort(), []);
+  const onSceneChange = useCallback((scene, index) => {
     const { voice, enabled = true } = optionsRef.current;
     if (!enabled) return;
     if (spokenIndexRef.current === index) return;
@@ -1909,7 +1778,18 @@ function useNarration(options) {
     setSpeaking(true);
     void (async () => {
       try {
-        await voice.speak(line, { signal: controller.signal });
+        let started = false;
+        await voice.speak(line, {
+          signal: controller.signal,
+          onStart: (source) => {
+            if (started || controller.signal.aborted || currentRef.current !== controller || spokenIndexRef.current !== index || optionsRef.current.enabled === false) return;
+            started = true;
+            try {
+              void Promise.resolve(optionsRef.current.onSpeechStart?.(source)).catch(() => void 0);
+            } catch {
+            }
+          }
+        });
       } catch {
       } finally {
         if (currentRef.current === controller) {
@@ -1922,11 +1802,9 @@ function useNarration(options) {
   return { onSceneChange, interrupt, speaking };
 }
 
-// src/video-chat/use-video-chat.ts
-import { useCallback as useCallback3, useEffect as useEffect5, useReducer, useRef as useRef4 } from "react";
-
 // src/video-chat/voice.ts
 var DEFAULT_MAX_CACHED_LINES = 60;
+var SPEECH_PREPARATION_TIMEOUT_MS = 3e3;
 var FALLBACK_BITS_PER_SECOND = 128e3;
 var sharedContext;
 function actionEndpoint(endpoint, action) {
@@ -1959,6 +1837,13 @@ function createVideoChatVoice(options = {}) {
   let silent = false;
   let disposed = false;
   let generatedSpeechUnavailable = false;
+  let playbackFailure;
+  const notifyFallback = () => {
+    try {
+      void Promise.resolve(options.onFallback?.()).catch(() => void 0);
+    } catch {
+    }
+  };
   const forgetOldest = () => {
     while (lines.size > maximum) {
       const oldest = lines.keys().next();
@@ -1991,38 +1876,34 @@ function createVideoChatVoice(options = {}) {
         if (generatedSpeechUnavailable) {
           prepared = { source: "browser", seconds: estimatedBrowserSeconds(normalized) };
         } else {
-          const response = await fetcher(actionEndpoint(endpoint, "speech"), {
-            method: "POST",
-            headers,
-            credentials: options.credentials,
-            signal: controller.signal,
-            body: JSON.stringify({ text: normalized })
-          });
-          if (controller.signal.aborted) {
-            throw controller.signal.reason ?? new DOMException("Speech preparation cancelled", "AbortError");
-          }
-          if (response.status === 204 || response.status === 404) {
-            generatedSpeechUnavailable = true;
-            prepared = { source: "browser", seconds: estimatedBrowserSeconds(normalized) };
-          } else if (!response.ok) {
-            prepared = { source: "browser", seconds: estimatedBrowserSeconds(normalized) };
-          } else {
-            const bytes = await response.arrayBuffer();
-            if (controller.signal.aborted) {
-              throw controller.signal.reason ?? new DOMException("Speech preparation cancelled", "AbortError");
+          prepared = await withDeadline(async (preparationSignal) => {
+            const response = await fetcher(actionEndpoint(endpoint, "speech"), {
+              method: "POST",
+              headers,
+              credentials: options.credentials,
+              signal: preparationSignal,
+              body: JSON.stringify({ text: normalized })
+            });
+            preparationSignal.throwIfAborted();
+            if (response.status === 204 || response.status === 404) {
+              generatedSpeechUnavailable = true;
+              return { source: "browser", seconds: estimatedBrowserSeconds(normalized) };
             }
+            if (!response.ok) throw new Error("Speech is unavailable");
+            const bytes = await response.arrayBuffer();
+            preparationSignal.throwIfAborted();
+            const seconds = await measureSeconds(bytes);
+            preparationSignal.throwIfAborted();
             createdSrc = URL.createObjectURL(new Blob([bytes], {
               type: response.headers.get("content-type") || "audio/mpeg"
             }));
-            prepared = { source: "generated", src: createdSrc, seconds: await measureSeconds(bytes) };
-            if (controller.signal.aborted) {
-              throw controller.signal.reason ?? new DOMException("Speech preparation cancelled", "AbortError");
-            }
-          }
+            return { source: "generated", src: createdSrc, seconds };
+          }, SPEECH_PREPARATION_TIMEOUT_MS, controller.signal);
         }
       } catch (cause) {
         if (createdSrc) URL.revokeObjectURL(createdSrc);
         if (controller.signal.aborted) throw controller.signal.reason ?? cause;
+        notifyFallback();
         prepared = { source: "browser", seconds: estimatedBrowserSeconds(normalized) };
       }
       if (disposed || controller.signal.aborted) {
@@ -2044,6 +1925,19 @@ function createVideoChatVoice(options = {}) {
       signal?.removeEventListener("abort", forwardAbort);
     }
   };
+  const speechStops = /* @__PURE__ */ new Set();
+  const watchSpeech = (seconds, expire) => {
+    let remaining = Math.max(1, seconds) * 2e3 + 5e3;
+    const timer = setInterval(() => {
+      if (held) return;
+      remaining -= 250;
+      if (remaining <= 0) {
+        clearInterval(timer);
+        expire();
+      }
+    }, 250);
+    return () => clearInterval(timer);
+  };
   const stopBrowser = () => {
     globalThis.speechSynthesis?.cancel();
     browserFinish?.();
@@ -2060,7 +1954,7 @@ function createVideoChatVoice(options = {}) {
     },
     resume() {
       held = false;
-      if (sounding && !silent) void sounding.play().catch(() => void 0);
+      if (sounding && !silent) void sounding.play().catch(() => playbackFailure?.());
       if (!silent) globalThis.speechSynthesis?.resume();
     },
     setMuted(muted) {
@@ -2068,7 +1962,16 @@ function createVideoChatVoice(options = {}) {
       if (sounding) sounding.muted = muted;
       if (muted) stopBrowser();
     },
-    async speak(text, { signal }) {
+    async speak(text, { signal, onStart }) {
+      let started = false;
+      const notifyStart = (source) => {
+        if (started || disposed || signal.aborted || silent || held) return;
+        started = true;
+        try {
+          void Promise.resolve(onStart?.(source)).catch(() => void 0);
+        } catch {
+        }
+      };
       const line = await load(text, signal);
       if (disposed || signal.aborted || silent) return;
       if (line.source === "browser") {
@@ -2081,40 +1984,91 @@ function createVideoChatVoice(options = {}) {
           const finish = () => {
             if (finished) return;
             finished = true;
+            clearWatchdog();
+            signal.removeEventListener("abort", stop);
+            speechStops.delete(stop);
+            utterance.onstart = null;
+            utterance.onend = null;
+            utterance.onerror = null;
             if (browserFinish === finish) browserFinish = void 0;
             resolve();
           };
+          const stop = () => {
+            synthesis.cancel();
+            finish();
+          };
+          const clearWatchdog = watchSpeech(estimatedBrowserSeconds(text), stop);
+          speechStops.add(stop);
           browserFinish = finish;
+          utterance.onstart = () => {
+            if (!finished) notifyStart("browser");
+          };
           utterance.onend = finish;
           utterance.onerror = finish;
-          signal.addEventListener("abort", () => {
-            synthesis.cancel();
+          signal.addEventListener("abort", stop, { once: true });
+          try {
+            synthesis.speak(utterance);
+            if (held) synthesis.pause();
+          } catch {
             finish();
-          }, { once: true });
-          synthesis.speak(utterance);
-          if (held) synthesis.pause();
+          }
         });
         return;
       }
-      const element = new Audio(line.src);
-      element.muted = silent;
-      sounding = element;
-      await new Promise((resolve) => {
-        let finished = false;
-        const finish = () => {
-          if (finished) return;
-          finished = true;
-          if (sounding === element) sounding = void 0;
-          resolve();
-        };
-        element.onended = finish;
-        element.onerror = finish;
-        signal.addEventListener("abort", () => {
-          element.pause();
-          finish();
-        }, { once: true });
-        if (!held) void element.play().catch(finish);
-      });
+      let playbackFailed = false;
+      try {
+        const element = new Audio(line.src);
+        element.muted = silent;
+        sounding = element;
+        await new Promise((resolve) => {
+          let finished = false;
+          const finish = () => {
+            if (finished) return;
+            finished = true;
+            clearWatchdog();
+            signal.removeEventListener("abort", stop);
+            speechStops.delete(stop);
+            element.onplaying = null;
+            element.onended = null;
+            element.onerror = null;
+            if (sounding === element) {
+              sounding = void 0;
+              playbackFailure = void 0;
+            }
+            resolve();
+          };
+          const stop = () => {
+            element.pause();
+            finish();
+          };
+          const fail = () => {
+            playbackFailed = true;
+            stop();
+          };
+          const clearWatchdog = watchSpeech(Math.max(line.seconds, estimatedBrowserSeconds(text)), fail);
+          speechStops.add(stop);
+          playbackFailure = fail;
+          element.onplaying = () => {
+            if (!finished) notifyStart("generated");
+          };
+          element.onended = finish;
+          element.onerror = fail;
+          signal.addEventListener("abort", stop, { once: true });
+          try {
+            if (!held) void element.play().catch(fail);
+          } catch {
+            fail();
+          }
+        });
+      } catch {
+        playbackFailed = true;
+      }
+      if (playbackFailed && !disposed && !signal.aborted && !silent) {
+        notifyFallback();
+        URL.revokeObjectURL(line.src);
+        lines.set(text.trim(), { source: "browser", seconds: estimatedBrowserSeconds(text) });
+        await this.speak(text, { signal, onStart: notifyStart });
+      }
     },
     dispose() {
       disposed = true;
@@ -2122,6 +2076,8 @@ function createVideoChatVoice(options = {}) {
         controller.abort(new DOMException("Video chat voice was disposed", "AbortError"));
       }
       pendingLoads.clear();
+      for (const stop of speechStops) stop();
+      speechStops.clear();
       sounding?.pause();
       sounding = void 0;
       stopBrowser();
@@ -2135,6 +2091,12 @@ function createVideoChatVoice(options = {}) {
 
 // src/video-chat/use-video-chat.ts
 var DEFAULT_TIMEOUT_MS = 18e4;
+function observe(callback) {
+  try {
+    void Promise.resolve(callback?.()).catch(() => void 0);
+  } catch {
+  }
+}
 function initialState(muted) {
   return {
     turns: [],
@@ -2160,6 +2122,7 @@ function reducer(state, action) {
       return {
         ...state,
         turns: [...state.turns, action.turn],
+        playerKey: state.playerKey + 1,
         shownTurnId: action.turn.id,
         status: "composing",
         resumeStatus: "composing",
@@ -2219,6 +2182,8 @@ function reducer(state, action) {
           suggestions: action.suggestions
         }))
       };
+    case "suggestions":
+      return { ...state, turns: replaceTurn(state.turns, action.id, (turn) => ({ ...turn, suggestions: action.suggestions })) };
     case "scene":
       if (state.playerKey !== action.key) return state;
       return {
@@ -2229,6 +2194,11 @@ function reducer(state, action) {
     case "playback-end":
       if (state.playerKey !== action.key) return state;
       return { ...state, status: "ended", resumeStatus: "ended", playbackEnded: true, openingSpeaking: false };
+    case "warning":
+      return { ...state, turns: replaceTurn(state.turns, action.id, (turn) => ({
+        ...turn,
+        warnings: [.../* @__PURE__ */ new Set([...turn.warnings ?? [], action.message])]
+      })) };
     case "error":
       if (state.turns.at(-1)?.id !== action.id) return state;
       return {
@@ -2311,28 +2281,35 @@ function conversationFor(turns) {
     response: [...transcriptFor(turn).join(" ")].slice(0, 8e3).join("")
   }));
 }
-function errorFrom2(cause) {
+async function untilAborted(work, signal) {
+  let abort = () => void 0;
+  const cancelled = new Promise((_resolve, reject) => {
+    abort = () => reject(signal.reason ?? new DOMException("Cancelled", "AbortError"));
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+  });
+  try {
+    return await Promise.race([work, cancelled]);
+  } finally {
+    signal.removeEventListener("abort", abort);
+  }
+}
+function errorFrom(cause) {
   if (cause instanceof VideoError) return cause;
   if (cause instanceof DOMException && cause.name === "AbortError") {
     return new VideoError("Video chat was cancelled", { code: "aborted", recoverable: false });
   }
-  return new VideoError(safePublicDiagnostic(
-    cause instanceof Error ? cause.message : String(cause),
-    "Video chat failed"
-  ), { code: "video_chat_failed", recoverable: false });
-}
-async function responseError2(response) {
-  let code = "http_error";
-  let message = `Video chat endpoint failed (${response.status})`;
-  try {
-    const body = await response.json();
-    if (typeof body.error?.code === "string") code = body.error.code.slice(0, 80);
-    if (typeof body.error?.message === "string") {
-      message = safePublicDiagnostic(body.error.message, message);
-    }
-  } catch {
+  if (cause instanceof DOMException && cause.name === "TimeoutError") {
+    return new VideoError("Video chat timed out", { code: "timeout", recoverable: false });
   }
-  return new VideoError(message, { code, status: response.status, recoverable: false });
+  return new VideoError("Video chat could not produce a playable response", { code: "video_chat_failed", recoverable: false });
+}
+async function responseError(response) {
+  return new VideoError("Video chat could not produce a playable response", {
+    code: "http_error",
+    status: response.status,
+    recoverable: false
+  });
 }
 function pacedScene(scene, spokenSeconds, templates) {
   const held = spokenSeconds && spokenSeconds > 0 ? spokenSeconds + 0.8 : getSceneDuration(scene, templates?.getTemplateMetadata(scene.templateId) ?? getBuiltinTemplateMetadata(scene.templateId));
@@ -2361,35 +2338,76 @@ function prepareVisualScene(scene, mode) {
   return overMedia ? { ...shown, textArchetype: "subtle" } : shown;
 }
 function useVideoChat(options = {}) {
-  const optionsRef = useRef4(options);
+  const optionsRef = useRef3(options);
   optionsRef.current = options;
-  const ownedVoiceRef = useRef4(void 0);
+  const voiceWarningRef = useRef3(() => void 0);
+  const ownedVoiceRef = useRef3(void 0);
   if (!options.voice && !ownedVoiceRef.current) {
     ownedVoiceRef.current = createVideoChatVoice({
       endpoint: options.endpoint,
       headers: options.headers,
       credentials: options.credentials,
-      fetcher: options.fetcher
+      fetcher: options.fetcher,
+      onFallback: () => voiceWarningRef.current()
     });
   }
   const voice = options.voice ?? ownedVoiceRef.current;
-  const voiceRef = useRef4(voice);
+  const voiceRef = useRef3(voice);
   voiceRef.current = voice;
-  const narration = useNarration({ voice });
-  const narrationRef = useRef4(narration);
+  const unavailableVoiceLines = useRef3(/* @__PURE__ */ new Set());
+  const speechStartRef = useRef3(() => void 0);
+  const narration = useNarration({ onSpeechStart: (source) => speechStartRef.current(source), voice: {
+    speak: (text, options2) => unavailableVoiceLines.current.has(text) ? void 0 : voice.speak(text, options2)
+  } });
+  const narrationRef = useRef3(narration);
   narrationRef.current = narration;
   const [state, dispatch] = useReducer(reducer, options.initialMuted ?? false, initialState);
-  const stateRef = useRef4(state);
+  const stateRef = useRef3(state);
   stateRef.current = state;
-  const runRef = useRef4(0);
-  const inFlightRef = useRef4(void 0);
-  const openingRef = useRef4(void 0);
-  const timelineRef = useRef4(void 0);
-  const heldRef = useRef4(false);
-  const flushRef = useRef4(void 0);
-  const mountedRef = useRef4(true);
-  const firstFrameRef = useRef4(void 0);
-  const request = useCallback3(async (action, init = {}, signal) => {
+  const runRef = useRef3(0);
+  const inFlightRef = useRef3(void 0);
+  const suggestionsRef = useRef3(void 0);
+  const openingRef = useRef3(void 0);
+  const timelineRef = useRef3(void 0);
+  const heldRef = useRef3(false);
+  const flushRef = useRef3(void 0);
+  const mountedRef = useRef3(true);
+  const firstFrameRef = useRef3(void 0);
+  const reportMetric = useCallback2((metric) => {
+    observe(() => optionsRef.current.onPlaybackMetric?.(metric));
+  }, []);
+  const finishStall = useCallback2(() => {
+    const timing = firstFrameRef.current;
+    if (!timing?.active || timing.stallStartedAt == null) return;
+    const now = monotonicNow();
+    const started = timing.stallStartedAt;
+    timing.stallStartedAt = void 0;
+    reportMetric({
+      type: "stall",
+      turnId: timing.turnId,
+      mode: timing.mode,
+      elapsedMs: Math.max(0, Math.round(now - timing.startedAt)),
+      durationMs: Math.max(0, Math.round(now - started)),
+      reason: "scene-generation"
+    });
+  }, [reportMetric]);
+  const endTiming = useCallback2(() => {
+    finishStall();
+    if (firstFrameRef.current) firstFrameRef.current.active = false;
+  }, [finishStall]);
+  speechStartRef.current = (source) => {
+    const timing = firstFrameRef.current;
+    if (!mountedRef.current || !timing?.active || timing.speechReported || heldRef.current || stateRef.current.muted) return;
+    timing.speechReported = true;
+    reportMetric({
+      type: "first-speech",
+      turnId: timing.turnId,
+      mode: timing.mode,
+      elapsedMs: Math.max(0, Math.round(monotonicNow() - timing.startedAt)),
+      source: optionsRef.current.voice ? "custom" : source === "generated" ? "generated" : "browser"
+    });
+  };
+  const request = useCallback2(async (action, init = {}, signal) => {
     const current = optionsRef.current;
     const headers = new Headers(current.headers);
     new Headers(init.headers).forEach((header, name) => headers.set(name, header));
@@ -2403,27 +2421,29 @@ function useVideoChat(options = {}) {
       signal
     });
   }, []);
-  useEffect5(() => {
+  useEffect4(() => {
     mountedRef.current = true;
     const controller = new AbortController();
     void request("capabilities", {}, controller.signal).then(async (response) => {
-      if (!response.ok) throw await responseError2(response);
+      if (!response.ok) throw await responseError(response);
       return response.json();
     }).then((value) => {
       if (mountedRef.current) dispatch({ type: "capabilities", value });
     }).catch(() => void 0);
     void request("welcome", {}, controller.signal).then(async (response) => {
-      if (!response.ok) throw await responseError2(response);
+      if (!response.ok) throw await responseError(response);
       return response.json();
     }).then((value) => {
       if (mountedRef.current) dispatch({ type: "welcome", value });
     }).catch(() => void 0);
     return () => {
+      endTiming();
       mountedRef.current = false;
       controller.abort();
       runRef.current += 1;
       inFlightRef.current?.abort(new DOMException("Component unmounted", "AbortError"));
       openingRef.current?.abort(new DOMException("Component unmounted", "AbortError"));
+      suggestionsRef.current?.abort();
       timelineRef.current?.complete();
       timelineRef.current = void 0;
       narrationRef.current.interrupt();
@@ -2431,12 +2451,14 @@ function useVideoChat(options = {}) {
         if (!mountedRef.current) ownedVoiceRef.current?.dispose?.();
       });
     };
-  }, [request]);
-  useEffect5(() => voice.setMuted(state.muted), [state.muted, voice]);
-  const cancel = useCallback3((reason = "Video chat was cancelled") => {
+  }, [request, endTiming]);
+  useEffect4(() => voice.setMuted(state.muted), [state.muted, voice]);
+  const cancel = useCallback2((reason = "Video chat was cancelled") => {
+    endTiming();
     runRef.current += 1;
     inFlightRef.current?.abort(new DOMException(reason, "AbortError"));
     openingRef.current?.abort(new DOMException(reason, "AbortError"));
+    suggestionsRef.current?.abort();
     inFlightRef.current = void 0;
     openingRef.current = void 0;
     timelineRef.current?.complete();
@@ -2444,16 +2466,19 @@ function useVideoChat(options = {}) {
     flushRef.current = void 0;
     narrationRef.current.interrupt();
     dispatch({ type: "cancelled" });
-  }, []);
-  const ask = useCallback3(async (value, askOptions = {}) => {
+  }, [endTiming]);
+  const ask = useCallback2(async (value, askOptions = {}) => {
     const prompt = value.trim();
     if (!prompt) return void 0;
+    endTiming();
     inFlightRef.current?.abort(new DOMException("Replaced by a new prompt", "AbortError"));
     openingRef.current?.abort(new DOMException("Replaced by a new prompt", "AbortError"));
+    suggestionsRef.current?.abort();
     timelineRef.current?.complete();
     timelineRef.current = void 0;
     narrationRef.current.interrupt();
     voiceRef.current.resume();
+    unavailableVoiceLines.current.clear();
     heldRef.current = false;
     const controller = new AbortController();
     const openingController = new AbortController();
@@ -2488,7 +2513,7 @@ function useVideoChat(options = {}) {
       suggestions: [],
       ...openingMedia ? { openingMedia } : {}
     };
-    firstFrameRef.current = { turnId: id, mode, startedAt: monotonicNow(), reported: false };
+    firstFrameRef.current = { turnId: id, mode, startedAt: monotonicNow(), reported: false, speechReported: false, active: true };
     dispatch({ type: "start", turn });
     let timeline;
     let style;
@@ -2500,9 +2525,14 @@ function useVideoChat(options = {}) {
     let terminal = false;
     let attempt = 0;
     let ready = [];
+    let received = [];
     let appended = 0;
-    const isCurrent = () => mountedRef.current && runRef.current === run && !controller.signal.aborted;
+    const isCurrent = () => mountedRef.current && runRef.current === run && !controller.signal.aborted && !terminal;
     const isOpeningCurrent = () => isCurrent() && !terminal && openingRef.current === openingController && !openingController.signal.aborted;
+    const warn = (message) => {
+      if (isCurrent()) dispatch({ type: "warning", id, message });
+    };
+    voiceWarningRef.current = () => warn("Using browser voice for this response.");
     const flush = () => {
       if (!isCurrent()) return;
       let available = appended;
@@ -2536,11 +2566,11 @@ function useVideoChat(options = {}) {
       }
     };
     flushRef.current = flush;
-    const resolveOpeningMedia = async (keyword) => {
+    const resolveOpeningMedia = async (keyword, fallbackKeyword) => {
       try {
         const response = await request("opening-media", {
           method: "POST",
-          body: JSON.stringify({ keyword, orientation })
+          body: JSON.stringify({ keyword, ...fallbackKeyword ? { fallbackKeyword } : {}, orientation })
         }, openingController.signal);
         if (!response.ok || !isOpeningCurrent() || timeline) return;
         const payload = await response.json();
@@ -2549,13 +2579,25 @@ function useVideoChat(options = {}) {
       } catch {
       }
     };
+    const prepareSpeech = async (text, signal) => {
+      try {
+        return currentOptions.voice ? await withDeadline((child) => voiceRef.current.prepare(text, { signal: child }), 3e3, signal) : await voiceRef.current.prepare(text, { signal });
+      } catch (cause) {
+        if (currentOptions.voice && !signal.aborted && isCurrent()) unavailableVoiceLines.current.add(text);
+        throw cause;
+      }
+    };
     const speakOpening = async (text) => {
       try {
-        await voiceRef.current.prepare(text, { signal: openingController.signal });
         if (!isOpeningCurrent()) return;
         dispatch({ type: "opening-start", id, line: text });
-        await voiceRef.current.speak(text, { signal: openingController.signal });
+        await prepareSpeech(text, openingController.signal);
+        if (!isOpeningCurrent()) return;
+        await voiceRef.current.speak(text, { signal: openingController.signal, onStart: (source) => {
+          if (isOpeningCurrent()) speechStartRef.current(source);
+        } });
       } catch {
+        if (isOpeningCurrent()) warn("Some narration is unavailable; the response will continue.");
       } finally {
         openingActive = false;
         if (isOpeningCurrent()) dispatch({ type: "opening-end", id });
@@ -2581,7 +2623,7 @@ function useVideoChat(options = {}) {
           ...currentOptions.style ? { style: currentOptions.style } : {}
         })
       }, controller.signal);
-      if (!response.ok) throw await responseError2(response);
+      if (!response.ok) throw await responseError(response);
       if (!response.body || !response.headers.get("content-type")?.includes("text/event-stream")) {
         throw new VideoError("Video chat endpoint did not return a video stream", { code: "invalid_response" });
       }
@@ -2590,83 +2632,100 @@ function useVideoChat(options = {}) {
       const pending = [];
       let narrating = Promise.resolve();
       let terminalError;
-      for await (const event of decodeVideoSse(response.body)) {
-        if (!isCurrent() || currentAttempt !== attempt) return { video: { schemaVersion: "0.1", orientation, scenes: [], style }, suggestions: [] };
-        if (event.type === "response.start") style = event.data.style;
-        if (event.type === "data.video-chat-opening") {
-          const payload = event.data && typeof event.data === "object" && !Array.isArray(event.data) ? event.data : {};
-          const line = typeof payload.line === "string" ? payload.line.trim().slice(0, 300) : "";
-          const keyword = typeof payload.keyword === "string" ? payload.keyword.trim().slice(0, 80) : "";
-          if (!openingMedia && keyword) void resolveOpeningMedia(keyword);
-          if (!openingRequested && line) {
-            spokenHook = line;
-            lines.push(line);
-            openingRequested = true;
-            openingActive = true;
-            void speakOpening(line);
+      try {
+        for await (const event of decodeVideoSse(response.body)) {
+          if (!isCurrent() || currentAttempt !== attempt) return { video: { schemaVersion: "0.1", orientation, scenes: [], style }, lines: [] };
+          if (event.type === "response.start") style = event.data.style;
+          if (event.type === "response.warning" || event.type === "response.error" && !event.data.terminal) {
+            warn("Some parts were simplified so the response could continue.");
           }
-          continue;
-        }
-        if (event.type === "response.error" && event.data.terminal) {
-          terminalError = new VideoError(event.data.error.message, {
-            code: event.data.error.code,
-            requestId: event.data.snapshot ? void 0 : id,
-            recoverable: event.data.error.recoverable
+          if (event.type === "data.video-chat-opening") {
+            const payload = event.data && typeof event.data === "object" && !Array.isArray(event.data) ? event.data : {};
+            const line = typeof payload.line === "string" ? payload.line.trim().slice(0, 300) : "";
+            const keyword = typeof payload.keyword === "string" ? payload.keyword.trim().slice(0, 80) : "";
+            const fallbackKeyword = typeof payload.fallbackKeyword === "string" ? payload.fallbackKeyword.trim().slice(0, 80) : void 0;
+            if (!openingMedia && keyword) void resolveOpeningMedia(keyword, fallbackKeyword);
+            if (!openingRequested && line) {
+              spokenHook = line;
+              lines.push(line);
+              openingRequested = true;
+              openingActive = true;
+              void speakOpening(line);
+            }
+            continue;
+          }
+          if (event.type === "response.error" && event.data.terminal) {
+            terminalError = new VideoError("Video chat could not finish this response", {
+              code: event.data.error.code,
+              requestId: event.data.snapshot ? void 0 : id,
+              recoverable: event.data.error.recoverable
+            });
+          }
+          if (event.type === "response.abort") {
+            terminalError = new VideoError("Video chat was interrupted", { code: "aborted", recoverable: false });
+          }
+          if (event.type !== "scene.add") continue;
+          const position = event.data.position;
+          const plannedScene = event.data.scene;
+          planned[position] = plannedScene;
+          received[position] = prepareVisualScene(plannedScene, mode);
+          if (!currentOptions.templates?.getTemplate(plannedScene.templateId)) {
+            preloadBuiltinTemplate(plannedScene.templateId);
+          }
+          warmSceneMedia(plannedScene.variables);
+          const narrated = narrating.then(async () => {
+            const supplied = plannedScene.narration?.trim();
+            if (supplied) return supplied;
+            return withDeadline(async (signal) => {
+              const narrationResponse = await request("narration", {
+                method: "POST",
+                body: JSON.stringify({ prompt, scene: plannedScene, earlier: [...lines] })
+              }, signal);
+              if (!narrationResponse.ok) throw new Error("Narration unavailable");
+              const payload = await narrationResponse.json();
+              const line = typeof payload.line === "string" ? payload.line.trim() : "";
+              if (!line) throw new Error("Narration unavailable");
+              return line;
+            }, 3e3, controller.signal);
+          }).catch((cause) => {
+            if (controller.signal.aborted) throw cause;
+            warn("Some narration was simplified so the response could continue.");
+            return Object.values(plannedScene.variables).filter((value2) => typeof value2 === "string" && !/^https?:/i.test(value2)).join(" ").slice(0, 500);
+          }).then((line) => {
+            if (line) lines.push(line);
+            return line;
           });
+          narrating = narrated.catch(() => "");
+          pending.push(narrated.then(async (line) => {
+            if (!isCurrent() || currentAttempt !== attempt) return;
+            const visual = prepareVisualScene(plannedScene, mode);
+            const withNarration = line ? { ...visual, narration: line } : visual;
+            const spoken = line ? await prepareSpeech(line, controller.signal).catch((cause) => {
+              if (controller.signal.aborted) throw cause;
+              warn("Some narration is unavailable; the response will continue.");
+              return void 0;
+            }) : void 0;
+            if (!isCurrent() || currentAttempt !== attempt) return;
+            ready[position] = pacedScene(withNarration, spoken?.seconds, currentOptions.templates);
+            flush();
+          }).catch(() => {
+            if (!isCurrent() || currentAttempt !== attempt) return;
+            ready[position] = { ...received[position], timing: { fixedDuration: 5 } };
+            warn("Some parts were simplified so the response could continue.");
+            flush();
+          }));
         }
-        if (event.type === "response.abort") {
-          terminalError = new VideoError(event.data.reason, { code: "aborted", recoverable: false });
-        }
-        if (event.type !== "scene.add") continue;
-        const position = event.data.position;
-        const plannedScene = event.data.scene;
-        planned[position] = plannedScene;
-        if (!currentOptions.templates?.getTemplate(plannedScene.templateId)) {
-          preloadBuiltinTemplate(plannedScene.templateId);
-        }
-        warmSceneMedia(plannedScene.variables);
-        const narrated = narrating.then(async () => {
-          const supplied = plannedScene.narration?.trim();
-          if (supplied) return supplied;
-          const narrationResponse = await request("narration", {
-            method: "POST",
-            body: JSON.stringify({ prompt, scene: plannedScene, earlier: [...lines] })
-          }, controller.signal);
-          if (!narrationResponse.ok) return "";
-          const payload = await narrationResponse.json();
-          return typeof payload.line === "string" ? payload.line.trim() : "";
-        }).then((line) => {
-          if (line) lines.push(line);
-          return line;
-        });
-        narrating = narrated.catch(() => "");
-        pending.push(narrated.then(async (line) => {
-          if (!isCurrent() || currentAttempt !== attempt) return;
-          const visual = prepareVisualScene(plannedScene, mode);
-          const withNarration = line ? { ...visual, narration: line } : visual;
-          const spoken = line ? await voiceRef.current.prepare(line, { signal: controller.signal }) : void 0;
-          if (!isCurrent() || currentAttempt !== attempt) return;
-          ready[position] = pacedScene(withNarration, spoken?.seconds, currentOptions.templates);
-          flush();
-        }));
+      } catch (cause) {
+        if (controller.signal.aborted) throw cause;
+        terminalError = errorFrom(cause);
       }
       await Promise.all(pending);
-      if (terminalError) throw terminalError;
+      if (terminalError && ready.some(Boolean) && style) {
+        warn("The response was interrupted; completed scenes are still available.");
+      } else if (terminalError) throw terminalError;
       if (planned.length === 0 || ready.filter(Boolean).length === 0 || !style) {
         throw new VideoError("The video response contained no playable scenes", { code: "empty_response" });
       }
-      let suggestions2 = [];
-      try {
-        const suggestionsResponse = await request("suggestions", {
-          method: "POST",
-          body: JSON.stringify({ prompt, lines })
-        }, controller.signal);
-        if (suggestionsResponse.ok) {
-          suggestions2 = (await suggestionsResponse.json()).suggestions ?? [];
-        }
-      } catch (cause) {
-        if (controller.signal.aborted) throw cause;
-      }
       return {
         video: {
           schemaVersion: "0.1",
@@ -2674,25 +2733,43 @@ function useVideoChat(options = {}) {
           scenes: ready.filter((entry) => entry != null),
           style
         },
-        suggestions: suggestions2
+        lines
       };
     };
     try {
       let response;
       try {
-        response = await runAttempt(attempt);
+        response = await untilAborted(runAttempt(attempt), controller.signal);
       } catch (cause) {
-        if (controller.signal.aborted || timeline) throw cause;
+        if (controller.signal.aborted || timeline || spokenHook) throw cause;
         attempt += 1;
         ready = [];
+        received = [];
         appended = 0;
         style = void 0;
-        response = await runAttempt(attempt);
+        response = await untilAborted(runAttempt(attempt), controller.signal);
       }
       if (!isCurrent()) return void 0;
       planDone = true;
       flush();
-      dispatch({ type: "complete", id, video: response.video, suggestions: response.suggestions });
+      dispatch({ type: "complete", id, video: response.video, suggestions: [] });
+      const suggestionsController = new AbortController();
+      suggestionsRef.current = suggestionsController;
+      void withDeadline(async (signal) => {
+        const result = await request("suggestions", {
+          method: "POST",
+          body: JSON.stringify({ prompt, lines: response.lines })
+        }, signal);
+        if (!result.ok) return [];
+        const payload = await result.json();
+        return Array.isArray(payload.suggestions) ? payload.suggestions : [];
+      }, 7e3, suggestionsController.signal).then((suggestions2) => {
+        if (mountedRef.current && runRef.current === run && !suggestionsController.signal.aborted) {
+          dispatch({ type: "suggestions", id, suggestions: suggestions2 });
+        }
+      }).catch(() => void 0).finally(() => {
+        if (suggestionsRef.current === suggestionsController) suggestionsRef.current = void 0;
+      });
       return response.video;
     } catch (cause) {
       if (runRef.current !== run) return void 0;
@@ -2700,31 +2777,52 @@ function useVideoChat(options = {}) {
         return void 0;
       }
       terminal = true;
+      const recovered = received.flatMap((scene, index) => scene ? [ready[index] ?? { ...scene, timing: { fixedDuration: 5 } }] : []);
+      if (recovered.length === 0 && spokenHook) {
+        recovered.push({ id: `${id}-opening`, templateId: "media", variables: { texts: spokenHook, mediaType: "gradient" }, narration: spokenHook, timing: { fixedDuration: Math.max(4, spokenHook.split(/\s+/u).length / 2.5) } });
+      }
+      if (recovered.length > 0) {
+        style ??= { brand: resolveVideoBrand(currentOptions.brand), density: "normal", motion: "normal", defaultBackgroundEffect: "static", defaultTextArchetype: "subtle", defaultTransition: "crossfade" };
+        openingController.abort(new DOMException("Continuing completed response", "AbortError"));
+        if (!timeline) {
+          timeline = createSceneTimeline({ style, orientation });
+          dispatch({ type: "player", id, stream: timeline.stream });
+        }
+        for (const scene of recovered.slice(appended)) timeline.add(scene);
+        timeline.complete();
+        if (timelineRef.current === timeline) timelineRef.current = void 0;
+        const video = { schemaVersion: "0.1", orientation, style, scenes: recovered };
+        dispatch({ type: "warning", id, message: "The response was interrupted; completed scenes are still available." });
+        dispatch({ type: "complete", id, video, suggestions: [] });
+        return video;
+      }
       openingController.abort(new DOMException("Response failed", "AbortError"));
       timeline?.complete();
       if (timelineRef.current === timeline) timelineRef.current = void 0;
-      const error = errorFrom2(cause);
+      const error = errorFrom(cause);
       dispatch({ type: "error", id, error });
       return void 0;
     } finally {
       clearTimeout(timeout);
       if (runRef.current === run) inFlightRef.current = void 0;
     }
-  }, [request]);
-  const pause = useCallback3(() => {
+  }, [request, endTiming]);
+  const pause = useCallback2(() => {
+    finishStall();
     heldRef.current = true;
     voiceRef.current.pause();
     dispatch({ type: "pause" });
-  }, []);
-  const resume = useCallback3(() => {
+  }, [finishStall]);
+  const resume = useCallback2(() => {
     heldRef.current = false;
     voiceRef.current.resume();
     dispatch({ type: "resume" });
     flushRef.current?.();
   }, []);
-  const replay = useCallback3(() => {
+  const replay = useCallback2(() => {
     const turn = stateRef.current.turns.find((entry) => entry.id === stateRef.current.shownTurnId);
     if (!turn?.completed || !turn.video) return;
+    endTiming();
     if (inFlightRef.current) {
       runRef.current += 1;
       inFlightRef.current.abort(new DOMException("Replaying a saved response", "AbortError"));
@@ -2738,10 +2836,11 @@ function useVideoChat(options = {}) {
     heldRef.current = false;
     voiceRef.current.resume();
     dispatch({ type: "replay" });
-  }, []);
-  const selectTurn = useCallback3((id) => {
+  }, [endTiming]);
+  const selectTurn = useCallback2((id) => {
     const turn = stateRef.current.turns.find((entry) => entry.id === id);
     if (!turn?.completed || !turn.video) return;
+    endTiming();
     if (inFlightRef.current) {
       runRef.current += 1;
       inFlightRef.current.abort(new DOMException("Viewing a saved response", "AbortError"));
@@ -2755,14 +2854,14 @@ function useVideoChat(options = {}) {
     heldRef.current = false;
     voiceRef.current.resume();
     dispatch({ type: "select", id });
-  }, []);
-  const reset = useCallback3(() => {
+  }, [endTiming]);
+  const reset = useCallback2(() => {
     cancel("Session reset");
     heldRef.current = false;
     voiceRef.current.resume();
     dispatch({ type: "reset" });
   }, [cancel]);
-  const setMuted = useCallback3((muted) => dispatch({ type: "mute", value: muted }), []);
+  const setMuted = useCallback2((muted) => dispatch({ type: "mute", value: muted }), []);
   const currentTurn = state.turns.at(-1);
   const shownTurn = state.turns.find((turn) => turn.id === state.shownTurnId) ?? currentTurn;
   const availableModes = state.capabilities?.modes ?? ["templates"];
@@ -2777,27 +2876,35 @@ function useVideoChat(options = {}) {
     paused: state.status === "paused",
     controls: false,
     orientation: shownTurn?.fixedOrientation ? shownTurn.orientation : "auto",
+    onFramePresented: () => {
+      const timing = firstFrameRef.current;
+      if (stateRef.current.playerKey !== playbackKey || state.playback?.kind !== "stream" || !timing?.active || timing.reported) return;
+      timing.reported = true;
+      const elapsedMs = Math.max(0, Math.round(monotonicNow() - timing.startedAt));
+      observe(() => optionsRef.current.onFirstFrame?.({ turnId: timing.turnId, mode: timing.mode, timeToFirstFrameMs: elapsedMs }));
+      reportMetric({ type: "first-frame", turnId: timing.turnId, mode: timing.mode, elapsedMs });
+    },
+    onStallChange: (stalled) => {
+      if (stateRef.current.playerKey !== playbackKey || state.playback?.kind !== "stream") return;
+      const timing = firstFrameRef.current;
+      if (!timing?.active || !timing.reported) return;
+      if (!stalled) finishStall();
+      else if (!heldRef.current && timing.stallStartedAt == null) timing.stallStartedAt = monotonicNow();
+    },
     onSceneChange: (scene, index) => {
       if (stateRef.current.playerKey !== playbackKey) return;
-      const firstFrame = firstFrameRef.current;
-      if (index === 0 && firstFrame && !firstFrame.reported && state.playback?.kind === "stream") {
-        firstFrame.reported = true;
-        try {
-          void optionsRef.current.onFirstFrame?.({
-            turnId: firstFrame.turnId,
-            mode: firstFrame.mode,
-            timeToFirstFrameMs: Math.max(0, Math.round(monotonicNow() - firstFrame.startedAt))
-          });
-        } catch {
-        }
-      }
       dispatch({ type: "scene", key: playbackKey, scene, index });
       narrationRef.current.onSceneChange(scene, index);
     },
-    onPlaybackEnd: () => dispatch({ type: "playback-end", key: playbackKey }),
+    onPlaybackEnd: () => {
+      if (stateRef.current.playerKey !== playbackKey) return;
+      endTiming();
+      dispatch({ type: "playback-end", key: playbackKey });
+    },
     onError: (cause) => {
+      if (stateRef.current.playerKey !== playbackKey) return;
       const id = stateRef.current.turns.at(-1)?.id;
-      if (id) dispatch({ type: "error", id, error: errorFrom2(cause) });
+      if (id) dispatch({ type: "error", id, error: errorFrom(cause) });
     }
   } : void 0;
   return {
@@ -2815,6 +2922,7 @@ function useVideoChat(options = {}) {
     welcome: state.welcome,
     availableModes,
     status: state.status,
+    warnings: shownTurn?.warnings ?? [],
     error: state.error,
     suggestions,
     caption: state.caption,
@@ -2829,7 +2937,7 @@ function useVideoChat(options = {}) {
 }
 
 // src/video-chat/video-chat.tsx
-import { useCallback as useCallback6, useEffect as useEffect9, useId, useMemo as useMemo3, useRef as useRef7, useState as useState6 } from "react";
+import { useCallback as useCallback5, useEffect as useEffect8, useId, useMemo as useMemo2, useRef as useRef6, useState as useState5 } from "react";
 
 // src/video-chat/modes.ts
 var visualModes = [
@@ -2939,9 +3047,9 @@ var Warning = () => /* @__PURE__ */ jsxs3(Glyph, { children: [
 ] });
 
 // src/video-chat/use-dismiss.ts
-import { useEffect as useEffect6 } from "react";
+import { useEffect as useEffect5 } from "react";
 function useDismiss(open, close, surfaces) {
-  useEffect6(() => {
+  useEffect5(() => {
     if (!open) return;
     const onKeyDown = (event) => {
       if (event.key !== "Escape") return;
@@ -2963,7 +3071,7 @@ function useDismiss(open, close, surfaces) {
   }, [open, close, surfaces]);
 }
 function useFocusTrap(active, surface) {
-  useEffect6(() => {
+  useEffect5(() => {
     if (!active) return;
     const returnTo = document.activeElement;
     const focusable = () => Array.from(
@@ -2996,11 +3104,11 @@ function useFocusTrap(active, surface) {
 }
 
 // src/video-chat/suggestion-cards.tsx
-import { useCallback as useCallback4, useEffect as useEffect7, useRef as useRef5, useState as useState4 } from "react";
+import { useCallback as useCallback3, useEffect as useEffect6, useRef as useRef4, useState as useState3 } from "react";
 import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
 function Frame({ media, poster, playing }) {
-  const video = useRef5(null);
-  useEffect7(() => {
+  const video = useRef4(null);
+  useEffect6(() => {
     const element = video.current;
     if (!element || playing === void 0) return;
     if (playing) void element.play().catch(() => void 0);
@@ -3025,20 +3133,20 @@ function Frame({ media, poster, playing }) {
   );
 }
 function SuggestionCards({ suggestions, label, onAsk }) {
-  const railRef = useRef5(null);
-  const [at, setAt] = useState4(0);
-  const [taken, setTaken] = useState4(false);
-  const take = useCallback4((index) => {
+  const railRef = useRef4(null);
+  const [at, setAt] = useState3(0);
+  const [taken, setTaken] = useState3(false);
+  const take = useCallback3((index) => {
     setTaken(true);
     setAt(index);
   }, []);
-  useEffect7(() => {
+  useEffect6(() => {
     if (taken || suggestions.length < 2) return;
     if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return;
     const tour = window.setInterval(() => setAt((index) => (index + 1) % suggestions.length), 5e3);
     return () => window.clearInterval(tour);
   }, [taken, suggestions.length]);
-  useEffect7(() => {
+  useEffect6(() => {
     const rail = railRef.current;
     const card = rail?.children[at];
     if (!rail || !card) return;
@@ -3095,7 +3203,7 @@ function Welcome({ data, onAsk, title }) {
 }
 
 // src/video-chat/use-voice-input.ts
-import { useCallback as useCallback5, useEffect as useEffect8, useRef as useRef6, useState as useState5 } from "react";
+import { useCallback as useCallback4, useEffect as useEffect7, useRef as useRef5, useState as useState4 } from "react";
 function recognitionConstructor() {
   if (typeof window === "undefined") return void 0;
   const holder = window;
@@ -3165,19 +3273,19 @@ async function recordAndTranscribe(signal, ready, captured, options) {
   return clip ? transcribeRecording(clip, signal, options) : "";
 }
 function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {}) {
-  const [supported, setSupported] = useState5(false);
-  const [listening, setListening] = useState5(false);
-  const [error, setError] = useState5();
-  const [thinking, setThinking] = useState5(false);
-  const recognitionRef = useRef6(void 0);
-  const useRecorderRef = useRef6(false);
-  const operationRef = useRef6(void 0);
-  const handlerRef = useRef6(onTranscript);
+  const [supported, setSupported] = useState4(false);
+  const [listening, setListening] = useState4(false);
+  const [error, setError] = useState4();
+  const [thinking, setThinking] = useState4(false);
+  const recognitionRef = useRef5(void 0);
+  const useRecorderRef = useRef5(false);
+  const operationRef = useRef5(void 0);
+  const handlerRef = useRef5(onTranscript);
   handlerRef.current = onTranscript;
-  useEffect8(() => {
+  useEffect7(() => {
     setSupported(supportsVoiceInput(transcriptionAvailable));
   }, [transcriptionAvailable]);
-  const stop = useCallback5(() => {
+  const stop = useCallback4(() => {
     recognitionRef.current?.abort();
     recognitionRef.current = void 0;
     const operation = operationRef.current;
@@ -3187,7 +3295,7 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
     setListening(false);
     setThinking(false);
   }, []);
-  useEffect8(() => () => {
+  useEffect7(() => () => {
     recognitionRef.current?.abort();
     recognitionRef.current = void 0;
     const operation = operationRef.current;
@@ -3195,7 +3303,7 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
     operation?.controller.abort();
     operation?.finish?.();
   }, []);
-  const finish = useCallback5(() => {
+  const finish = useCallback4(() => {
     const recognition = recognitionRef.current;
     if (recognition) {
       recognition.stop();
@@ -3209,7 +3317,7 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
     }
     stop();
   }, [stop]);
-  const record = useCallback5(async () => {
+  const record = useCallback4(async () => {
     if (!transcriptionAvailable || !recorderAvailable()) {
       setError("Server transcription is not configured.");
       return;
@@ -3247,7 +3355,7 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
       }
     }
   }, [transcriptionAvailable, options.endpoint, options.headers, options.credentials, options.fetcher]);
-  const toggle = useCallback5(() => {
+  const toggle = useCallback4(() => {
     if (listening) {
       finish();
       return;
@@ -3302,8 +3410,8 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
 import { Fragment as Fragment4, jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
 var DESKTOP_WIDTH = 900;
 function useViewportOrientation() {
-  const [portrait, setPortrait] = useState6(() => typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(`(max-width: ${DESKTOP_WIDTH - 1}px)`).matches : false);
-  useEffect9(() => {
+  const [portrait, setPortrait] = useState5(() => typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(`(max-width: ${DESKTOP_WIDTH - 1}px)`).matches : false);
+  useEffect8(() => {
     if (typeof window.matchMedia !== "function") return;
     const query = window.matchMedia(`(max-width: ${DESKTOP_WIDTH - 1}px)`);
     const update = () => setPortrait(query.matches);
@@ -3320,8 +3428,8 @@ var STEPS = [
   "Still filming\u2026"
 ];
 function useFilmingStep(active, key) {
-  const [step, setStep] = useState6(0);
-  useEffect9(() => {
+  const [step, setStep] = useState5(0);
+  useEffect8(() => {
     if (!active) return;
     setStep(0);
     const stepper = window.setInterval(() => setStep((current) => current + 1), 3e3);
@@ -3333,14 +3441,14 @@ function Waveform({ active, listening }) {
   return /* @__PURE__ */ jsx6("span", { className: `waveform${active ? " on" : ""}${listening ? " hearing" : ""}`, "aria-hidden": "true", children: [0, 1, 2, 3, 4].map((bar) => /* @__PURE__ */ jsx6("span", { style: { animationDelay: `${bar * 140}ms`, animationDuration: `${900 + bar * 130}ms` } }, bar)) });
 }
 function VideoChat({ options = {}, className, welcomeTitle }) {
-  const [draft, setDraft] = useState6("");
-  const [themeId, setThemeId] = useState6(defaultTheme.id);
-  const [modeId, setModeId] = useState6(options.mode ?? defaultMode.id);
-  const [historyOpen, setHistoryOpen] = useState6(false);
-  const [settingsOpen, setSettingsOpen] = useState6(false);
-  const [sheetOpen, setSheetOpen] = useState6(false);
+  const [draft, setDraft] = useState5("");
+  const [themeId, setThemeId] = useState5(defaultTheme.id);
+  const [modeId, setModeId] = useState5(options.mode ?? defaultMode.id);
+  const [historyOpen, setHistoryOpen] = useState5(false);
+  const [settingsOpen, setSettingsOpen] = useState5(false);
+  const [sheetOpen, setSheetOpen] = useState5(false);
   const viewportOrientation = useViewportOrientation();
-  const [themeChoice, setThemeChoice] = useState6("system");
+  const [themeChoice, setThemeChoice] = useState5("system");
   const theme = themeById(themeId);
   const sessionOrientation = options.orientation ?? viewportOrientation;
   const { brand: configuredBrand, style: configuredStyle, ...sessionOptions } = options;
@@ -3360,29 +3468,29 @@ function VideoChat({ options = {}, className, welcomeTitle }) {
   const appearanceName = `${instanceId}-appearance`;
   const visualsName = `${instanceId}-visuals`;
   const styleName = `${instanceId}-style`;
-  const inputRef = useRef7(null);
-  const historyRef = useRef7(null);
-  const historyButtonRef = useRef7(null);
-  const settingsRef = useRef7(null);
-  const settingsButtonRef = useRef7(null);
-  const sheetRef = useRef7(null);
+  const inputRef = useRef6(null);
+  const historyRef = useRef6(null);
+  const historyButtonRef = useRef6(null);
+  const settingsRef = useRef6(null);
+  const settingsButtonRef = useRef6(null);
+  const sheetRef = useRef6(null);
   const listen = useVoiceInput(setDraft, chat.capabilities?.transcription ?? false, {
     endpoint: options.endpoint,
     headers: options.headers,
     credentials: options.credentials,
     fetcher: options.fetcher
   });
-  const historySurfaces = useMemo3(() => [historyRef, historyButtonRef], []);
-  const settingsSurfaces = useMemo3(() => [settingsRef, settingsButtonRef], []);
-  const noSurfaces = useMemo3(() => [], []);
-  const closeHistory = useCallback6(() => setHistoryOpen(false), []);
-  const closeSettings = useCallback6(() => setSettingsOpen(false), []);
-  const closeSheet = useCallback6(() => setSheetOpen(false), []);
+  const historySurfaces = useMemo2(() => [historyRef, historyButtonRef], []);
+  const settingsSurfaces = useMemo2(() => [settingsRef, settingsButtonRef], []);
+  const noSurfaces = useMemo2(() => [], []);
+  const closeHistory = useCallback5(() => setHistoryOpen(false), []);
+  const closeSettings = useCallback5(() => setSettingsOpen(false), []);
+  const closeSheet = useCallback5(() => setSheetOpen(false), []);
   useDismiss(historyOpen, closeHistory, historySurfaces);
   useDismiss(settingsOpen, closeSettings, settingsSurfaces);
   useDismiss(sheetOpen, closeSheet, noSurfaces);
   useFocusTrap(sheetOpen, sheetRef);
-  const ask = useCallback6((value) => {
+  const ask = useCallback5((value) => {
     const prompt = (typeof value === "string" ? value : value.prompt).trim();
     if (!prompt) return;
     setDraft("");
@@ -3395,7 +3503,7 @@ function VideoChat({ options = {}, className, welcomeTitle }) {
       opening: value.opening
     });
   }, [chat, listen]);
-  const newSession = useCallback6(() => {
+  const newSession = useCallback5(() => {
     if (chat.turns.length === 0) {
       inputRef.current?.focus();
       return;
@@ -3643,7 +3751,5 @@ export {
   VideoError,
   VideoPlayer,
   createVideoChatVoice,
-  useNarration,
-  useVideo,
   useVideoChat
 };