@vanillaskyai/video 0.7.1 → 0.8.0

package/dist/server.d.ts

@@ -1,9 +1,9 @@
-import { o as VideoGenerationContext, p as VideoPlanner, q as VideoRequest, a as VideoCapabilities, g as VideoInput, d as VideoAudio, r as VideoSceneValidator, j as VideoTemplatePacing, s as VideoSnapshotRetention, t as VideoResumeCursor, u as VideoSceneValidationContext, e as VideoScene, b as VideoOrientation } from './types-2wHBqtg8.js';
-import { a as VideoFinishReason, V as VideoWarning, b as VideoEvent } from './events-B6qS1Lsb.js';
-export { c as VideoWarningCategory } from './events-B6qS1Lsb.js';
+import { m as VideoGenerationContext, n as VideoPlanner, o as VideoRequest, a as VideoCapabilities, g as VideoInput, d as VideoAudio, p as VideoSceneValidator, j as VideoTemplatePacing, q as VideoSnapshotRetention, r as VideoResumeCursor, s as VideoSceneValidationContext, e as VideoScene, b as VideoOrientation } from './types-CEh9eUFu.js';
+import { a as VideoFinishReason, V as VideoWarning, b as VideoEvent } from './events-BQ6z264n.js';
+export { c as VideoWarningCategory } from './events-BQ6z264n.js';
 import { S as SceneTemplateMetadata } from './catalog-types-BIhSpOWK.js';
-import { V as VideoChatWelcomeOptions } from './types-DrABlRa7.js';
-export { a as VideoChatCapabilities, b as VideoChatConversationTurn, c as VideoChatMode, d as VideoChatWelcomePrompt } from './types-DrABlRa7.js';
+import { f as VideoChatWelcomeOptions } from './types-DWFO6qca.js';
+export { d as VideoChatCapabilities, g as VideoChatConversationTurn, V as VideoChatMode, h as VideoChatWelcomePrompt } from './types-DWFO6qca.js';
 
 interface VideoProviderUsage {
     inputTokens?: number;
@@ -104,7 +104,6 @@ interface VideoStreamHandlerOptions {
         signal: AbortSignal;
     }) => AsyncIterable<VideoEvent>;
 }
-type VideoStreamHandler = (request: Request) => Promise<Response>;
 
 interface ServerTemplateRegistry {
     readonly capabilities: VideoCapabilities;
@@ -185,11 +184,6 @@ interface VideoHandlerOptions extends Omit<VideoStreamHandlerOptions, "generate"
      */
     narrate?: boolean;
 }
-/**
- * Build the secure route for a template kit while leaving provider, model,
- * credentials, authentication, and deployment ownership with the app.
- */
-declare function createVideoHandler(options: VideoHandlerOptions): VideoStreamHandler;
 
 type VideoChatTextTask = "narration" | "suggestions";
 interface VideoChatTextContext {
@@ -224,9 +218,11 @@ interface VideoChatMediaContext {
     scene?: Readonly<VideoScene>;
     templateId?: string;
     preferredType?: "image" | "video" | "any";
+    /** Optional broader subject for atmospheric opening stock, not instructional footage. */
+    fallbackQuery?: string;
 }
 type VideoChatMediaResolver = (query: string, context: VideoChatMediaContext) => ResolvedMedia | null | Promise<ResolvedMedia | null>;
-interface VideoChatHandlerOptions extends Omit<VideoHandlerOptions, "allowMediaUrl" | "basePrompt" | "maxResolvedMedia" | "narrate" | "resolveMedia"> {
+interface VideoChatHandlerOptions extends Pick<VideoHandlerOptions, "templates" | "streamText" | "includeRawProviderData" | "mediaConcurrency" | "allowedOrigins" | "authorize" | "maxBodyBytes" | "heartbeatMs" | "onError" | "onWarning" | "onComplete" | "invalidPartBehavior" | "requireCloser" | "allowCredentials"> {
     /** Generate the small non-streaming text tasks around the visual plan. */
     generateText: VideoChatTextGenerator;
     /** Optional generated speech. Browsers can speak locally when absent. */
@@ -237,6 +233,8 @@ interface VideoChatHandlerOptions extends Omit<VideoHandlerOptions, "allowMediaU
     searchMedia?: VideoChatMediaResolver;
     /** Optional generated-video provider. Its presence enables paid visual modes. */
     generateVideo?: VideoChatMediaResolver;
+    /** Maximum generated-video attempts per response, including failures. Defaults to 5. */
+    maxGeneratedVideos?: number;
     /** Trusted application guidance appended to the general-purpose response brief. */
     instructions?: string;
     /** Application-owned prompts and visual searches shown before the first turn. */
@@ -255,4 +253,4 @@ type VideoChatHandler = (request: Request) => Promise<Response>;
  */
 declare function createVideoChatHandler(options: VideoChatHandlerOptions): VideoChatHandler;
 
-export { type MediaResolver, type MediaResolverContext, type ResolvedMedia, SceneTemplateMetadata as ServerTemplateMetadata, type ServerTemplateRegistry, type VideoChatHandlerOptions, VideoChatWelcomeOptions, VideoFinishReason, type VideoGenerationSummary, type VideoHandlerOptions, type VideoProviderUsage, VideoWarning, createServerTemplateRegistry, createVideoChatHandler, createVideoHandler };
+export { SceneTemplateMetadata as ServerTemplateMetadata, type ServerTemplateRegistry, type VideoChatHandlerOptions, VideoChatWelcomeOptions, VideoFinishReason, type VideoGenerationSummary, type VideoProviderUsage, VideoWarning, createServerTemplateRegistry, createVideoChatHandler };

package/dist/server.js

@@ -1,15 +1,18 @@
 import {
   createTextDeltaVideoPlanner
-} from "./chunk-LLPMVDJZ.js";
+} from "./chunk-L7QGGKJ2.js";
 import {
-  createVideo
-} from "./chunk-RE4IMWJR.js";
-import "./chunk-E7CL7UPB.js";
+  createVideo,
+  invokeIsolated
+} from "./chunk-3VRMKFM7.js";
+import {
+  getGenerationLifecycleSink
+} from "./chunk-E7CL7UPB.js";
 import {
   BUILTIN_SERVER_TEMPLATE_KIT,
   createServerTemplateRegistry,
   overlayServerTemplateRegistry
-} from "./chunk-RGF452LL.js";
+} from "./chunk-OWBT45EN.js";
 import {
   createTemplateSceneValidator
 } from "./chunk-LMG3GHLL.js";
@@ -17,9 +20,10 @@ import {
   decodeVideoSse,
   encodeVideoSseEvent,
   sanitizeVideoChatMedia,
-  videoSseHeaders
-} from "./chunk-2XT4MZ76.js";
-import "./chunk-GAIOHGNR.js";
+  videoSseHeaders,
+  withDeadline
+} from "./chunk-APQKY6P3.js";
+import "./chunk-2OKB27TG.js";
 import {
   allowedKeys,
   createClippedVariableWarning,
@@ -33,7 +37,7 @@ import {
 } from "./chunk-MMUXVA47.js";
 import {
   MAX_RETAINED_MEDIA_URL_LENGTH
-} from "./chunk-2PYO6VAC.js";
+} from "./chunk-2DOLF4QN.js";
 import {
   VIDEO_PROTOCOL_VERSION
 } from "./chunk-AOWSXU2K.js";
@@ -43,7 +47,7 @@ import {
 } from "./chunk-AITKH6QT.js";
 import "./chunk-5SLENAJW.js";
 import "./chunk-352ZZCET.js";
-import "./chunk-JNN3EYVP.js";
+import "./chunk-4UNKZEAT.js";
 import "./chunk-3O7OMMMF.js";
 import "./chunk-2E6T633S.js";
 import {
@@ -471,9 +475,6 @@ function fallbackVariables(variables) {
   fallback.mediaType = "gradient";
   return fallback;
 }
-function isAbortError(error) {
-  return error instanceof Error && error.name === "AbortError";
-}
 async function resolveVariables(options) {
   if (!Object.hasOwn(options.variables, "mediaKeyword")) return options.variables;
   const variables = { ...options.variables };
@@ -484,6 +485,10 @@ async function resolveVariables(options) {
     return fallbackVariables(variables);
   }
   if (options.claimBudget && !options.claimBudget()) return fallbackVariables(variables);
+  const fallback = () => {
+    options.onFallback?.();
+    return fallbackVariables(variables);
+  };
   let resolved;
   try {
     resolved = await options.resolveMedia(rawQuery, {
@@ -495,28 +500,27 @@ async function resolveVariables(options) {
       generatedLook: options.input.style?.generatedLook,
       signal: options.signal
     });
+    if (options.signal.aborted) {
+      throw options.signal.reason ?? new DOMException("The media request was aborted", "AbortError");
+    }
+    if (!resolved) return fallback();
+    if (resolved.type !== "image" && resolved.type !== "video") {
+      throw new Error("Resolved media type is invalid");
+    }
+    const url = cleanUrl(resolved.url, "URL");
+    if (!url) throw new Error("Resolved media URL is required");
+    const posterUrl = options.contract.acceptsPoster ? cleanUrl(resolved.posterUrl, "poster URL") : void 0;
+    options.approveUrl(options.input, url);
+    if (posterUrl) options.approveUrl(options.input, posterUrl);
+    variables.mediaUrl = url;
+    variables.mediaType = resolved.type === "image" ? "photo" : "video";
+    if (posterUrl) variables.mediaPoster = posterUrl;
+    else delete variables.mediaPoster;
+    return variables;
   } catch (error) {
     if (options.signal.aborted) throw options.signal.reason ?? error;
-    if (isAbortError(error)) throw error;
-    return fallbackVariables(variables);
-  }
-  if (options.signal.aborted) {
-    throw options.signal.reason ?? new DOMException("The media request was aborted", "AbortError");
-  }
-  if (!resolved) return fallbackVariables(variables);
-  if (resolved.type !== "image" && resolved.type !== "video") {
-    throw new Error("Resolved media type is invalid");
+    return fallback();
   }
-  const url = cleanUrl(resolved.url, "URL");
-  if (!url) throw new Error("Resolved media URL is required");
-  const posterUrl = options.contract.acceptsPoster ? cleanUrl(resolved.posterUrl, "poster URL") : void 0;
-  options.approveUrl(options.input, url);
-  if (posterUrl) options.approveUrl(options.input, posterUrl);
-  variables.mediaUrl = url;
-  variables.mediaType = resolved.type === "image" ? "photo" : "video";
-  if (posterUrl) variables.mediaPoster = posterUrl;
-  else delete variables.mediaPoster;
-  return variables;
 }
 function templateContract(templates, templateId) {
   const metadata = templates.getTemplateMetadata(templateId);
@@ -544,7 +548,8 @@ async function resolvePartVariables(options) {
     resolveMedia: options.resolveMedia,
     approveUrl: options.approveUrl,
     openingReady: options.openingReady,
-    claimBudget: options.claimBudget
+    claimBudget: options.claimBudget,
+    onFallback: options.onFallback
   };
   if (options.part.type === "scene.add") {
     const variables = await resolveVariables({
@@ -583,7 +588,13 @@ function createMediaResolvingPlanner(options) {
       resolveMedia: options.resolveMedia,
       approveUrl: options.approveUrl,
       openingReady: openingReady2 ?? options.isOpeningReady(context.request.input),
-      claimBudget
+      claimBudget,
+      onFallback: () => getGenerationLifecycleSink(context)?.reportWarning?.({
+        code: "provider_warning",
+        category: "provider",
+        message: "Some visuals use a simple background.",
+        recoverable: true
+      })
     });
     if (limit === 1) {
       for await (const part of options.planner(context)) yield await resolveOne(part);
@@ -688,22 +699,36 @@ function boundSceneVariables(templates, templateId, variables) {
 }
 function createBoundedVariablePlanner(options) {
   return async function* boundPlan(context) {
-    for await (const part of options.planner(context)) {
+    for await (let part of options.planner(context)) {
       if (part.type !== "scene.add") {
         yield part;
         continue;
       }
-      const { variables, clipped } = boundSceneVariables(
-        options.templates,
-        part.scene.templateId,
-        part.scene.variables
-      );
-      if (clipped.length === 0) {
-        yield part;
-        continue;
+      try {
+        const lifecycle = getGenerationLifecycleSink(context);
+        if (!options.templates.getTemplateMetadata(part.scene.templateId) && lifecycle?.recoverGeneratedParts && (context.request.capabilities?.templates == null || context.request.capabilities.templates.includes("media"))) {
+          const copy = [part.scene.variables.texts, part.scene.variables.title, part.scene.variables.message, part.scene.narration].find((value) => typeof value === "string" && Boolean(value.trim()) && !/https?:\/\/|\b(?:api[_-]?key|authorization|secret|token|password)\s*[:=]/i.test(value));
+          if (copy) {
+            part = { ...part, scene: { ...part.scene, templateId: "media", variables: { texts: copy, mediaType: "gradient" } } };
+            lifecycle.reportWarning?.({ code: "provider_warning", category: "provider", message: "Some scenes use a simpler layout.", recoverable: true });
+          }
+        }
+        const { variables, clipped } = boundSceneVariables(
+          options.templates,
+          part.scene.templateId,
+          part.scene.variables
+        );
+        if (clipped.length === 0) {
+          yield part;
+          continue;
+        }
+        const templateId = part.scene.templateId;
+        invokeIsolated(options.onClipped && (() => options.onClipped(templateId, clipped)), void 0);
+        yield { ...part, scene: { ...part.scene, variables } };
+      } catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        if (!getGenerationLifecycleSink(context)?.rejectPart?.(error)) throw error;
       }
-      options.onClipped?.(part.scene.templateId, clipped);
-      yield { ...part, scene: { ...part.scene, variables } };
     }
   };
 }
@@ -740,7 +765,8 @@ function createVideoHandler(options) {
   const planner = createBoundedVariablePlanner({
     planner: createTextDeltaVideoPlanner({ streamText, includeRawProviderData }),
     templates,
-    onClipped: (templateId, fields) => void handlerOptions.onWarning?.(
+    onClipped: (templateId, fields) => invokeIsolated(
+      handlerOptions.onWarning,
       createClippedVariableWarning(templateId, fields)
     )
   });
@@ -768,7 +794,7 @@ function createVideoHandler(options) {
       // The ceiling is a spend policy, so it is reported to the application
       // that set it rather than to the browser, which cannot act on it.
       onBudgetReached: maxResolvedMedia === void 0 ? void 0 : () => {
-        void handlerOptions.onWarning?.(createMediaBudgetWarning(maxResolvedMedia));
+        invokeIsolated(handlerOptions.onWarning, createMediaBudgetWarning(maxResolvedMedia));
       },
       // The same rule the scene validator applies, answered from the part
       // rather than from what the validator has already seen.
@@ -804,13 +830,15 @@ function createVideoHandler(options) {
 
 // src/server/video-chat-prompts.ts
 var RESPONSE_SCENES = 5;
-function createVideoChatResponseInstructions(fullAiVideo, openingAlreadyProvided = false) {
+function createVideoChatResponseInstructions(fullAiVideo, openingAlreadyProvided = false, maxGeneratedVideos = 5) {
   return [
     "The input is a prompt from a user. Respond as a short, coherent video.",
     "Honor the requested purpose and tone. A story should feel like a story, a recommendation should be useful, an explanation should be clear, and a creative request should not be turned into a lecture.",
-    fullAiVideo ? 'Your first output line must be exactly one host-consumed JSON object: {"type":"video-chat.opening","spokenHook":"6-9 words","mediaKeyword":"2-4 concrete words","firstShot":{"text":"2-7 words","narration":"10-16 spoken words","mediaKeyword":"2-8 concrete words"}}. This leading object is the one explicit exception to the standard plan-part list and is consumed before plan validation.' : openingAlreadyProvided ? "The host has already started the supplied OPENING ALREADY SPOKEN. Start directly with scene.add plan parts; do not emit a video-chat.opening object." : 'Your first output line must be exactly one host-consumed JSON object: {"type":"video-chat.opening","spokenHook":"6-9 words","mediaKeyword":"2-4 concrete words"}. This leading object is the one explicit exception to the standard plan-part list and is consumed before plan validation.',
+    fullAiVideo ? 'Your first output line must be exactly one host-consumed JSON object: {"type":"video-chat.opening","spokenHook":"6-9 words","mediaKeyword":"2-4 concrete words","fallbackKeyword":"2-4 broader concrete words","firstShot":{"text":"2-7 words","narration":"10-16 spoken words","mediaKeyword":"2-8 concrete words"}}. This leading object is the one explicit exception to the standard plan-part list and is consumed before plan validation.' : openingAlreadyProvided ? "The host has already started the supplied OPENING ALREADY SPOKEN. Start directly with scene.add plan parts; do not emit a video-chat.opening object." : 'Your first output line must be exactly one host-consumed JSON object: {"type":"video-chat.opening","spokenHook":"6-9 words","mediaKeyword":"2-4 concrete words","fallbackKeyword":"2-4 broader concrete words"}. This leading object is the one explicit exception to the standard plan-part list and is consumed before plan validation.',
+    "For the opening only, fallbackKeyword names a broader real-world subject that can provide atmosphere if the specific stock search misses. It must not pretend to demonstrate specialized instructions. For example, Minecraft castle can broaden to medieval castle for atmosphere. Do not broaden body-scene subjects into misleading demonstrations.",
     fullAiVideo && openingAlreadyProvided ? "Copy the supplied OPENING ALREADY SPOKEN exactly into spokenHook; do not replace or paraphrase it." : void 0,
     fullAiVideo ? "The host inserts firstShot as the first body scene and begins generating it immediately. After the opening object, emit exactly four additional scenes that continue it. Never emit, repeat, paraphrase, or replace firstShot as a scene." : `After the opening instruction above, use exactly ${RESPONSE_SCENES} scenes and build a progression that fits the request:`,
+    fullAiVideo ? `The response has a budget of ${maxGeneratedVideos} generated-video attempts, including the host-inserted firstShot. The first ${maxGeneratedVideos} media requests may generate footage; all later requests use stock footage. Plan later subjects that stock footage can honestly illustrate. Keep five total scenes even when the budget is smaller; do not request extra generated scenes.` : void 0,
     fullAiVideo ? void 0 : "1. Open directly on the strongest image, action, claim, or idea.",
     "2. Develop it with new information or movement.",
     "3. Deepen, complicate, or advance the response.",
@@ -996,6 +1024,7 @@ function readOpeningPlanLine(line) {
     return {
       line: boundedWords(parsed.spokenHook, 9, 300),
       keyword: boundedWords(parsed.mediaKeyword, 4, 80),
+      ...boundedWords(parsed.fallbackKeyword, 4, 80) ? { fallbackKeyword: boundedWords(parsed.fallbackKeyword, 4, 80) } : {},
       ...firstShot ? { firstShot } : {}
     };
   } catch {
@@ -1144,7 +1173,8 @@ function streamVideoChatOpening(response, openingReady) {
           type: VIDEO_CHAT_OPENING_EVENT_TYPE,
           data: {
             line: opening.line,
-            ...opening.keyword ? { keyword: opening.keyword } : {}
+            ...opening.keyword ? { keyword: opening.keyword } : {},
+            ...opening.fallbackKeyword ? { fallbackKeyword: opening.fallbackKeyword } : {}
           }
         });
         sequence += 1;
@@ -1239,10 +1269,22 @@ function createVideoChatHandler(options) {
     allowedOrigins,
     allowCredentials,
     mediaConcurrency = 5,
-    ...videoOptions
+    maxGeneratedVideos = 5
   } = options;
+  const videoOptions = {
+    templates: options.templates,
+    streamText: options.streamText,
+    includeRawProviderData: options.includeRawProviderData,
+    heartbeatMs: options.heartbeatMs,
+    onError: options.onError,
+    onWarning: options.onWarning,
+    onComplete: options.onComplete,
+    invalidPartBehavior: options.invalidPartBehavior,
+    requireCloser: options.requireCloser
+  };
   if (!Number.isFinite(maxAudioBytes) || maxAudioBytes <= 0) throw new Error("maxAudioBytes must be positive");
   if (!Number.isFinite(maxBodyBytes) || maxBodyBytes <= 0) throw new Error("maxBodyBytes must be positive");
+  if (!Number.isSafeInteger(maxGeneratedVideos) || maxGeneratedVideos < 0) throw new Error("maxGeneratedVideos must be a nonnegative safe integer");
   const capabilities2 = {
     templates: true,
     generatedSpeech: generateSpeech != null,
@@ -1258,20 +1300,68 @@ function createVideoChatHandler(options) {
   const responseHandler = (requestedMode, requestId, openingProvided, openingChannel) => {
     const mode = requestedMode !== "templates" && !generateVideo ? "templates" : requestedMode;
     const fullAiVideo = mode === "full";
-    const selectedResolver = fullAiVideo ? generateVideo : searchMedia;
-    const resolveSelected = selectedResolver ? (query, context) => selectedResolver(query, {
-      purpose: "response",
-      orientation: context.input.orientation ?? "landscape",
-      generatedLook: context.generatedLook,
-      signal: context.signal,
-      requestId: context.requestId,
-      scene: context.scene,
-      templateId: context.templateId,
-      preferredType: context.preferredType
-    }) : void 0;
+    let lifecycle;
+    let generatedAttempts = 0;
+    const completedVideos = /* @__PURE__ */ new Map();
+    const reusedUrls = /* @__PURE__ */ new Set();
+    const resolveSelected = generateVideo || searchMedia ? async (query, context) => {
+      const reuseKey = JSON.stringify([query, context.generatedLook ?? ""]);
+      const remember = (media) => {
+        if (media?.type === "video") completedVideos.set(reuseKey, media);
+        return media;
+      };
+      const mediaContext = {
+        purpose: "response",
+        orientation: context.input.orientation ?? "landscape",
+        generatedLook: context.generatedLook,
+        signal: context.signal,
+        requestId: context.requestId,
+        scene: context.scene,
+        templateId: context.templateId,
+        preferredType: context.preferredType
+      };
+      const attempt = async (resolver, timeoutMs) => {
+        context.signal.throwIfAborted();
+        if (!resolver) return null;
+        try {
+          const result = sanitizeVideoChatMedia(await withDeadline(
+            (signal) => resolver(query, { ...mediaContext, signal }),
+            timeoutMs,
+            context.signal
+          ));
+          context.signal.throwIfAborted();
+          return result;
+        } catch (cause) {
+          context.signal.throwIfAborted();
+          reportError(cause);
+          return null;
+        }
+      };
+      if (fullAiVideo) {
+        const generated = generatedAttempts < maxGeneratedVideos ? (generatedAttempts++, await attempt(generateVideo, 15e3)) : null;
+        if (generated) return remember(generated);
+        lifecycle?.reportWarning?.({
+          code: "provider_warning",
+          category: "provider",
+          message: "Some visuals were replaced so your response can continue.",
+          recoverable: true
+        });
+      }
+      const stock = await attempt(searchMedia, 3e3);
+      if (stock) return remember(stock);
+      if (fullAiVideo) {
+        const previous = completedVideos.get(reuseKey);
+        if (previous && !reusedUrls.has(previous.url)) {
+          reusedUrls.add(previous.url);
+          return previous;
+        }
+      }
+      return null;
+    } : void 0;
     const handler = createVideoHandler({
       ...videoOptions,
       streamText: (context) => {
+        lifecycle = getGenerationLifecycleSink(context);
         try {
           return interceptOpeningPlan(videoOptions.streamText(context), {
             expectOpening: fullAiVideo || !openingProvided,
@@ -1290,9 +1380,8 @@ function createVideoChatHandler(options) {
       allowCredentials,
       maxBodyBytes,
       mediaConcurrency,
-      basePrompt: [createVideoChatResponseInstructions(fullAiVideo, openingProvided), instructions?.trim()].filter(Boolean).join("\n\nAPPLICATION GUIDANCE\n"),
+      basePrompt: [createVideoChatResponseInstructions(fullAiVideo, openingProvided, maxGeneratedVideos), instructions?.trim()].filter(Boolean).join("\n\nAPPLICATION GUIDANCE\n"),
       narrate: true,
-      ...fullAiVideo ? { maxResolvedMedia: 5 } : {},
       resolveMedia: resolveSelected
     });
     return handler;
@@ -1343,15 +1432,14 @@ function createVideoChatHandler(options) {
         const mediaResolver = searchMedia;
         const resolve = async (query) => {
           if (!mediaResolver || !query) return null;
-          const signal = AbortSignal.any([request.signal, AbortSignal.timeout(1e4)]);
           try {
-            const raw = await Promise.resolve().then(() => mediaResolver(query, {
+            const raw = await withDeadline((signal) => mediaResolver(query, {
               purpose: "welcome",
               orientation: "landscape",
               signal
-            }));
+            }), 3e3, request.signal);
             const media = sanitizeVideoChatMedia(raw);
-            if (signal.aborted || raw != null && !media) failed = true;
+            if (request.signal.aborted || raw != null && !media) failed = true;
             return media;
           } catch (cause) {
             failed = true;
@@ -1459,19 +1547,21 @@ function createVideoChatHandler(options) {
     try {
       if (action === "opening-media") {
         const value = record2(body, "request");
-        allowedKeys2(value, ["keyword", "orientation"], "request");
+        allowedKeys2(value, ["keyword", "fallbackKeyword", "orientation"], "request");
         const keyword = boundedString2(value.keyword, "request.keyword", 80);
+        const fallbackQuery = value.fallbackKeyword == null ? void 0 : boundedString2(value.fallbackKeyword, "request.fallbackKeyword", 80);
         const orientation = value.orientation ?? "landscape";
         if (orientation !== "portrait" && orientation !== "landscape") {
           throw new Error("request.orientation must be portrait or landscape");
         }
         if (!searchMedia) return Response.json({ media: null }, { headers });
         try {
-          const raw = await Promise.resolve().then(() => searchMedia(keyword, {
+          const raw = await withDeadline((signal) => searchMedia(keyword, {
             purpose: "response",
+            ...fallbackQuery ? { fallbackQuery } : {},
             orientation,
-            signal: request.signal
-          }));
+            signal
+          }), 3e3, request.signal);
           return Response.json({ media: sanitizeVideoChatMedia(raw) }, { headers });
         } catch (cause) {
           if (!request.signal.aborted) reportError(cause);
@@ -1502,7 +1592,7 @@ function createVideoChatHandler(options) {
         const prompt = boundedString2(value.prompt, "request.prompt");
         const lines = Array.isArray(value.lines) ? value.lines.slice(-8).map((line, index) => boundedString2(line, `request.lines[${index}]`, 2e3)) : [];
         try {
-          const text = await callText(
+          const text = await withDeadline((signal) => callText(
             "suggestions",
             VIDEO_CHAT_SUGGESTIONS_PROMPT,
             `USER PROMPT: ${prompt}
@@ -1510,18 +1600,18 @@ function createVideoChatHandler(options) {
 VIDEO RESPONSE:
 ${lines.join("\n")}`,
             512,
-            request.signal
-          );
+            signal
+          ), 3e3, request.signal);
           const subjects = readSuggestionSubjects(text);
           const mediaResolver = searchMedia;
           const media = await Promise.all(subjects.map(async (subject) => {
             if (!mediaResolver || !subject.keyword) return null;
             try {
-              const raw = await Promise.resolve().then(() => mediaResolver(subject.keyword, {
+              const raw = await withDeadline((signal) => mediaResolver(subject.keyword, {
                 purpose: "suggestion",
                 orientation: "landscape",
-                signal: request.signal
-              }));
+                signal
+              }), 3e3, request.signal);
               return sanitizeVideoChatMedia(raw);
             } catch (cause) {
               if (!request.signal.aborted) reportError(cause);
@@ -1545,7 +1635,7 @@ ${lines.join("\n")}`,
         allowedKeys2(value, ["text"], "request");
         const text = boundedString2(value.text, "request.text", 4e3);
         try {
-          const result = await generateSpeech({ text, signal: request.signal });
+          const result = await withDeadline((signal) => generateSpeech({ text, signal }), 3e3, request.signal);
           return new Response(audioBody(result.audio), {
             headers: {
               ...Object.fromEntries(headers),
@@ -1569,6 +1659,5 @@ ${lines.join("\n")}`,
 }
 export {
   createServerTemplateRegistry,
-  createVideoChatHandler,
-  createVideoHandler
+  createVideoChatHandler
 };

package/dist/template-catalog.js

@@ -1,6 +1,6 @@
 import {
   BUILTIN_TEMPLATE_MANIFEST
-} from "./chunk-LKBZX7GV.js";
+} from "./chunk-PP3MCPN4.js";
 export {
   BUILTIN_TEMPLATE_MANIFEST as builtinTemplates
 };

package/dist/templates.d.ts

@@ -1,9 +1,9 @@
-import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-8g46H2RZ.js';
-export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-8g46H2RZ.js';
+import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-tQnCPMOM.js';
+export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-tQnCPMOM.js';
 import { ComponentType } from 'react';
 import { d as TemplateJsonSchema, S as SceneTemplateMetadata } from './catalog-types-BIhSpOWK.js';
 export { T as TemplateFamily, c as TemplateTimingMetadata, e as TemplateTransitionTiming } from './catalog-types-BIhSpOWK.js';
-import './types-2wHBqtg8.js';
+import './types-CEh9eUFu.js';
 
 interface TemplateExample<Variables extends Record<string, unknown> = Record<string, unknown>> {
     name: string;

package/dist/test.d.ts

@@ -1,5 +1,5 @@
-import { e as VideoScene, b as VideoOrientation, V as VideoStyle, c as Video, d as VideoAudio, g as VideoInput } from './types-2wHBqtg8.js';
-import { V as VideoWarning, a as VideoFinishReason } from './events-B6qS1Lsb.js';
+import { e as VideoScene, b as VideoOrientation, V as VideoStyle, c as Video, d as VideoAudio, g as VideoInput } from './types-CEh9eUFu.js';
+import { V as VideoWarning, a as VideoFinishReason } from './events-BQ6z264n.js';
 
 type MockVideoStreamPart = {
     type: "scene.add";

package/dist/test.js

@@ -233,9 +233,9 @@ async function* simulateVideoStream(parts, options = {}) {
   if (timeoutMs != null && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
     throw new Error("Simulation timeoutMs must be a non-negative finite number");
   }
-  const { createVideo } = await import("./compose-video-PD6LKKRK.js");
-  const { createTextDeltaVideoPlanner } = await import("./text-stream-ROTNGSD4.js");
-  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-KB7FKF6A.js");
+  const { createVideo } = await import("./compose-video-2NFH4DZY.js");
+  const { createTextDeltaVideoPlanner } = await import("./text-stream-54LXABJW.js");
+  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-CUYPIDE7.js");
   const { createTemplateSceneValidator } = await import("./validate-T7GBU2YF.js");
   const controller = new AbortController();
   const forwardAbort = () => controller.abort(options.signal?.reason);

package/dist/{text-stream-ROTNGSD4.js → text-stream-54LXABJW.js}

@@ -1,6 +1,6 @@
 import {
   createTextDeltaVideoPlanner
-} from "./chunk-LLPMVDJZ.js";
+} from "./chunk-L7QGGKJ2.js";
 import "./chunk-E7CL7UPB.js";
 import "./chunk-MMUXVA47.js";
 import "./chunk-AOWSXU2K.js";

package/dist/{types-2wHBqtg8.d.ts → types-CEh9eUFu.d.ts}

@@ -222,4 +222,4 @@ interface VideoSnapshotRetention {
     suppliedMediaUrls?: boolean;
 }
 
-export { type VideoStyle as V, type VideoCapabilities as a, type VideoOrientation as b, type Video as c, type VideoAudio as d, type VideoScene as e, VIDEO_PROTOCOL_VERSION as f, type VideoInput as g, type VideoBrandInput as h, type VideoBrand as i, type VideoTemplatePacing as j, type VideoBackground as k, type VideoKnowledgeMode as l, type VideoStyleOptions as m, type VideoSuppliedMedia as n, type VideoGenerationContext as o, type VideoPlanner as p, type VideoRequest as q, type VideoSceneValidator as r, type VideoSnapshotRetention as s, type VideoResumeCursor as t, type VideoSceneValidationContext as u };
+export { type VideoStyle as V, type VideoCapabilities as a, type VideoOrientation as b, type Video as c, type VideoAudio as d, type VideoScene as e, VIDEO_PROTOCOL_VERSION as f, type VideoInput as g, type VideoBrandInput as h, type VideoBrand as i, type VideoTemplatePacing as j, type VideoBackground as k, type VideoStyleOptions as l, type VideoGenerationContext as m, type VideoPlanner as n, type VideoRequest as o, type VideoSceneValidator as p, type VideoSnapshotRetention as q, type VideoResumeCursor as r, type VideoSceneValidationContext as s };

package/dist/{types-DrABlRa7.d.ts → types-DWFO6qca.d.ts}

@@ -43,4 +43,4 @@ interface VideoChatWelcomeOptions {
     prompts?: readonly VideoChatWelcomePrompt[];
 }
 
-export type { VideoChatWelcomeOptions as V, VideoChatCapabilities as a, VideoChatConversationTurn as b, VideoChatMode as c, VideoChatWelcomePrompt as d, VideoChatAskOptions as e, VideoChatMedia as f, VideoChatSuggestion as g, VideoChatWelcome as h };
+export type { VideoChatMode as V, VideoChatAskOptions as a, VideoChatMedia as b, VideoChatSuggestion as c, VideoChatCapabilities as d, VideoChatWelcome as e, VideoChatWelcomeOptions as f, VideoChatConversationTurn as g, VideoChatWelcomePrompt as h };

package/docs/agent-integration.md

@@ -22,14 +22,20 @@ npm run dev
 ```
 
 Init generates the thin application-owned shell around the SDK's complete
-`VideoChat` experience. The default uses packaged templates + browser voice.
-One text-provider key makes it answer; optional keys enable generated speech,
-stock media, transcription, and generated video without client changes.
+`VideoChat` experience and runs doctor automatically. The default uses packaged
+templates + browser voice and installs no optional provider packages.
+`ANTHROPIC_API_KEY` is the only required key. Rerun init after an interrupted
+installation.
 
 If doctor reports a missing key, add the named key to the ignored `.env.local`
 yourself. Never read or print a secret value, and never paste one into the chat.
 Doctor is the safe capability interface: it reports names and readiness only.
 
+For requested upgrades, run `npx vanillasky providers add speech` for xAI speech
+or `npx vanillasky providers add video` for FAL video and transcription. Have the
+developer add `XAI_API_KEY` or `FAL_KEY` locally, then restart the server. Stock
+media needs only `PEXELS_API_KEY`. The client does not change.
+
 ## Verify, do not merely scaffold
 
 The agent should leave the dev server running and open its reported localhost