@vanillaskyai/video 0.7.1 → 0.8.1

package/registry/items/terminal.json

@@ -137,7 +137,7 @@
           "mediaKeyword": {
             "type": "string",
             "title": "Background search keyword",
-            "description": "2-4 word English term for Pexels stock-footage search (auto-fills mediaUrl).",
+            "description": "2-4 word English term for stock-media search (auto-fills mediaUrl).",
             "format": "stock-media-keyword",
             "default": ""
           },
@@ -156,7 +156,7 @@
           "mediaPoster": {
             "type": "string",
             "title": "Background poster image",
-            "description": "Still image URL shown while a video backdrop is decoding its first frame. Auto-filled from Pexels' thumbnail when fillPexelsUrls sets a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
+            "description": "Still image URL shown while a video backdrop is decoding its first frame. A media resolver can supply a poster alongside a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
             "format": "uri",
             "default": ""
           },

package/registry/items/testimonial.json

@@ -93,7 +93,7 @@
           "mediaKeyword": {
             "type": "string",
             "title": "Background search keyword",
-            "description": "2-4 word English term for Pexels stock-footage search (auto-fills mediaUrl).",
+            "description": "2-4 word English term for stock-media search (auto-fills mediaUrl).",
             "format": "stock-media-keyword",
             "default": ""
           },
@@ -112,7 +112,7 @@
           "mediaPoster": {
             "type": "string",
             "title": "Background poster image",
-            "description": "Still image URL shown while a video backdrop is decoding its first frame. Auto-filled from Pexels' thumbnail when fillPexelsUrls sets a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
+            "description": "Still image URL shown while a video backdrop is decoding its first frame. A media resolver can supply a poster alongside a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
             "format": "uri",
             "default": ""
           },

package/registry/items/tripleStats.json

@@ -146,7 +146,7 @@
           "mediaKeyword": {
             "type": "string",
             "title": "Background search keyword",
-            "description": "2-4 word English term for Pexels stock-footage search (auto-fills mediaUrl).",
+            "description": "2-4 word English term for stock-media search (auto-fills mediaUrl).",
             "format": "stock-media-keyword",
             "default": ""
           },
@@ -165,7 +165,7 @@
           "mediaPoster": {
             "type": "string",
             "title": "Background poster image",
-            "description": "Still image URL shown while a video backdrop is decoding its first frame. Auto-filled from Pexels' thumbnail when fillPexelsUrls sets a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
+            "description": "Still image URL shown while a video backdrop is decoding its first frame. A media resolver can supply a poster alongside a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
             "format": "uri",
             "default": ""
           },

package/registry/items/tweet.json

@@ -129,7 +129,7 @@
           "mediaKeyword": {
             "type": "string",
             "title": "Background search keyword",
-            "description": "2-4 word English term for Pexels stock-footage search (auto-fills mediaUrl).",
+            "description": "2-4 word English term for stock-media search (auto-fills mediaUrl).",
             "format": "stock-media-keyword",
             "default": ""
           },
@@ -148,7 +148,7 @@
           "mediaPoster": {
             "type": "string",
             "title": "Background poster image",
-            "description": "Still image URL shown while a video backdrop is decoding its first frame. Auto-filled from Pexels' thumbnail when fillPexelsUrls sets a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
+            "description": "Still image URL shown while a video backdrop is decoding its first frame. A media resolver can supply a poster alongside a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
             "format": "uri",
             "default": ""
           },

package/registry/items/webMockup.json

@@ -204,7 +204,7 @@
           "mediaKeyword": {
             "type": "string",
             "title": "Background search keyword",
-            "description": "2-4 word English term for Pexels stock-footage search (auto-fills mediaUrl).",
+            "description": "2-4 word English term for stock-media search (auto-fills mediaUrl).",
             "default": ""
           },
           "mediaType": {
@@ -222,7 +222,7 @@
           "mediaPoster": {
             "type": "string",
             "title": "Background poster image",
-            "description": "Still image URL shown while a video backdrop is decoding its first frame. Auto-filled from Pexels' thumbnail when fillPexelsUrls sets a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
+            "description": "Still image URL shown while a video backdrop is decoding its first frame. A media resolver can supply a poster alongside a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50–400ms gap between a <video> mounting and decoding its first frame.",
             "format": "uri",
             "default": ""
           },

package/starters/video-chat/.env.example

@@ -1,10 +1,12 @@
 # Required: plans the response, including its opening and narration, and suggestions.
 ANTHROPIC_API_KEY=
 
-# Optional: generated speech. The browser voice is used when this is empty.
+# Optional: run `npx vanillasky providers add speech` first.
+# Generated speech; browser voice remains the fallback.
 XAI_API_KEY=
 
-# Optional: generated video and server-side speech transcription.
+# Optional: run `npx vanillasky providers add video` first.
+# Generated video and server-side speech transcription.
 FAL_KEY=
 
 # Optional: stock video and photography for templates and suggestion cards.

package/starters/video-chat/README.md

@@ -20,11 +20,23 @@ ANTHROPIC_API_KEY=...
 ```
 
 That is enough for rendered templates and the browser's built-in voice. The
-optional keys progressively improve the same experience:
+starter installs only the text provider. Enable optional adapters when needed:
 
-- `XAI_API_KEY` replaces the browser voice with generated speech.
-- `FAL_KEY` enables generated-video modes and server transcription.
-- `PEXELS_API_KEY` adds stock footage to rendered responses and suggestion cards.
+```bash
+npx vanillasky providers add speech
+npx vanillasky providers add video
+```
+
+Each command installs its provider package and connects the adapter through
+`providers.ts`. Run both commands to enable both upgrades.
+
+- Speech: add `XAI_API_KEY` to replace browser voice with generated speech.
+- Video: add `FAL_KEY` for generated video and server transcription.
+- Stock: add `PEXELS_API_KEY` for footage and suggestion images; no installation
+  is needed.
+
+The adapters live in `providers/` and remain application-owned. Running an
+upgrade again can finish an interrupted dependency installation.
 
 Restart the development server after changing keys. Open
 <http://localhost:5173> and prompt anything.
@@ -42,7 +54,7 @@ Restart the development server after changing keys. Open
 4. The opening footage loops or holds until the first planned scene and its
    voice are ready, then the response timeline takes over without a blank gap.
 5. The SDK holds every planned scene for its measured or estimated speech time
-   and prepares four possible next prompts while playback continues.
+   and loads possible next prompts independently after the response completes.
 
 The text model is the only required provider. Generated speech, transcription,
 stock media, and generated video are independent upgrades and never prevent a

package/starters/video-chat/index.html

@@ -2,8 +2,9 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <title>VanillaSky video chat</title>
+    <style>html, body { margin: 0; min-height: 100%; background: #080b16; }</style>
   </head>
   <body>
     <div id="root"></div>

package/starters/video-chat/package.json

@@ -9,13 +9,11 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@vanillaskyai/video": "0.7.1",
+    "@vanillaskyai/video": "0.8.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "@ai-sdk/anthropic": "^3.0.0",
-    "ai": "^7.0.77",
-    "@ai-sdk/xai": "^4.0.52",
-    "@fal-ai/client": "1.10.1"
+    "ai": "^7.0.77"
   },
   "devDependencies": {
     "@types/react": "^19.2.18",

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

@@ -0,0 +1,20 @@
+import { createXai } from "@ai-sdk/xai";
+import { experimental_generateSpeech as synthesizeSpeech } from "ai";
+import type { VideoChatHandlerOptions } from "@vanillaskyai/video/server";
+
+/** Optional generated speech; the SDK supplies the browser-voice fallback. */
+export const speechProvider: Pick<VideoChatHandlerOptions, "generateSpeech"> = {
+  generateSpeech: process.env.XAI_API_KEY
+    ? async ({ text, signal }) => {
+        const speech = await synthesizeSpeech({
+          model: createXai({ apiKey: process.env.XAI_API_KEY }).speech(),
+          text,
+          abortSignal: signal,
+        });
+        return {
+          audio: speech.audio.uint8Array,
+          mediaType: speech.audio.mediaType || "audio/mpeg",
+        };
+      }
+    : undefined,
+};

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

@@ -0,0 +1,66 @@
+import { fal } from "@fal-ai/client";
+import type { VideoChatHandlerOptions } from "@vanillaskyai/video/server";
+
+const VIDEO_MODEL = process.env.FAL_VIDEO_MODEL ?? "minimax/h3-max/text-to-video";
+
+async function filmScene(
+  subject: string,
+  generatedLook: string | undefined,
+  orientation: "portrait" | "landscape",
+  signal: AbortSignal,
+) {
+  fal.config({ credentials: process.env.FAL_KEY });
+  const started = Date.now();
+  console.log(`[video-chat] filming: ${subject.slice(0, 70)}`);
+  try {
+    const result = await fal.subscribe(VIDEO_MODEL, {
+      input: {
+        prompt: [
+          `Locked-off shot, ${orientation === "portrait" ? "9:16 vertical" : "16:9"}. ${subject}.`,
+          "One slow continuous camera move. Physically plausible motion.",
+          "No on-screen text, captions, subtitles, watermarks or logos.",
+          "Diegetic sound only. No music, no voiceover.",
+          generatedLook,
+        ].filter(Boolean).join("\n\n"),
+        duration: 5,
+        resolution: "480P",
+        aspect_ratio: orientation === "portrait" ? "9:16" : "16:9",
+      },
+      abortSignal: signal,
+    });
+    const url = result?.data?.video?.url;
+    if (typeof url !== "string") throw new Error("the video provider returned no url");
+    console.log(`[video-chat] filmed in ${Date.now() - started}ms`);
+    return url;
+  } catch (cause) {
+    const status = (cause as { status?: unknown })?.status;
+    console.error(
+      `[video-chat] filming failed after ${Date.now() - started}ms${typeof status === "number" ? ` (status ${status})` : ""}`,
+    );
+    throw cause;
+  }
+}
+
+/** Optional generated video and transcription; credentials remain server-only. */
+export const videoProvider: Pick<VideoChatHandlerOptions, "generateVideo" | "transcribe"> = {
+  generateVideo: process.env.FAL_KEY
+    ? async (query, { generatedLook, orientation, signal }) => ({
+        url: await filmScene(query, generatedLook, orientation, signal),
+        type: "video" as const,
+      })
+    : undefined,
+  transcribe: process.env.FAL_KEY
+    ? async ({ audio, mediaType, signal }) => {
+        signal.throwIfAborted();
+        fal.config({ credentials: process.env.FAL_KEY });
+        const bytes = Uint8Array.from(audio);
+        const url = await fal.storage.upload(new Blob([bytes.buffer], { type: mediaType }));
+        signal.throwIfAborted();
+        const result = await fal.subscribe(process.env.FAL_TRANSCRIBE_MODEL ?? "fal-ai/whisper", {
+          input: { audio_url: url, task: "transcribe" },
+          abortSignal: AbortSignal.any([signal, AbortSignal.timeout(60_000)]),
+        });
+        return String((result?.data as { text?: unknown })?.text ?? "");
+      }
+    : undefined,
+};

package/starters/video-chat/providers.ts

@@ -0,0 +1,3 @@
+import type { VideoChatHandlerOptions } from "@vanillaskyai/video/server";
+
+export const providers: Pick<VideoChatHandlerOptions, "generateSpeech" | "generateVideo" | "transcribe"> = {};

package/starters/video-chat/server.ts

@@ -1,57 +1,11 @@
 import { anthropic } from "@ai-sdk/anthropic";
-import { fal } from "@fal-ai/client";
-import { createXai } from "@ai-sdk/xai";
-import {
-  experimental_generateSpeech as synthesizeSpeech,
-  generateText,
-  streamText,
-} from "ai";
+import { generateText, streamText } from "ai";
 import { createVideoChatHandler } from "@vanillaskyai/video/server";
 import { findStockFootage } from "./stock";
+import { providers } from "./providers";
 
 const PLANNER_MODEL = process.env.ANTHROPIC_PLANNER_MODEL ?? "claude-sonnet-5";
 const NARRATION_MODEL = process.env.ANTHROPIC_NARRATION_MODEL ?? "claude-haiku-4-5";
-const VIDEO_MODEL = process.env.FAL_VIDEO_MODEL ?? "minimax/h3-max/text-to-video";
-const SHOT_DEADLINE_MS = 180_000;
-
-async function filmScene(
-  subject: string,
-  generatedLook: string | undefined,
-  orientation: "portrait" | "landscape",
-  signal: AbortSignal,
-) {
-  fal.config({ credentials: process.env.FAL_KEY });
-  const started = Date.now();
-  console.log(`[video-chat] filming: ${subject.slice(0, 70)}`);
-  try {
-    const result = await fal.subscribe(VIDEO_MODEL, {
-      input: {
-        prompt: [
-          `Locked-off shot, ${orientation === "portrait" ? "9:16 vertical" : "16:9"}. ${subject}.`,
-          "One slow continuous camera move. Physically plausible motion.",
-          "No on-screen text, captions, subtitles, watermarks or logos.",
-          "Diegetic sound only. No music, no voiceover.",
-          generatedLook,
-        ].filter(Boolean).join("\n\n"),
-        duration: 5,
-        resolution: "480P",
-        aspect_ratio: orientation === "portrait" ? "9:16" : "16:9",
-      },
-      abortSignal: AbortSignal.any([signal, AbortSignal.timeout(SHOT_DEADLINE_MS)]),
-    });
-    const url = result?.data?.video?.url;
-    if (typeof url !== "string") throw new Error("the video provider returned no url");
-    console.log(`[video-chat] filmed in ${Date.now() - started}ms`);
-    return url;
-  } catch (cause) {
-    const status = (cause as { status?: unknown })?.status;
-    console.error(
-      `[video-chat] filming failed after ${Date.now() - started}ms${typeof status === "number" ? ` (status ${status})` : ""}`,
-    );
-    throw cause;
-  }
-}
-
 /**
  * The application chooses providers and keeps their credentials here. The SDK
  * owns the video-chat protocol, prompts, capability negotiation, spend limits,
@@ -87,40 +41,10 @@ export const handleVideoChat = createVideoChatHandler({
     });
     return text;
   },
-  generateSpeech: process.env.XAI_API_KEY
-    ? async ({ text, signal }) => {
-        const speech = await synthesizeSpeech({
-          model: createXai({ apiKey: process.env.XAI_API_KEY }).speech(),
-          text,
-          abortSignal: signal,
-        });
-        return {
-          audio: speech.audio.uint8Array,
-          mediaType: speech.audio.mediaType || "audio/mpeg",
-        };
-      }
-    : undefined,
-  transcribe: process.env.FAL_KEY
-    ? async ({ audio, mediaType, signal }) => {
-        fal.config({ credentials: process.env.FAL_KEY });
-        const bytes = Uint8Array.from(audio);
-        const url = await fal.storage.upload(new Blob([bytes.buffer], { type: mediaType }));
-        const result = await fal.subscribe(process.env.FAL_TRANSCRIBE_MODEL ?? "fal-ai/whisper", {
-          input: { audio_url: url, task: "transcribe" },
-          abortSignal: AbortSignal.any([signal, AbortSignal.timeout(60_000)]),
-        });
-        return String((result?.data as { text?: unknown })?.text ?? "");
-      }
-    : undefined,
   searchMedia: process.env.PEXELS_API_KEY
-    ? (query, { orientation, signal }) => findStockFootage(query, orientation, signal)
-    : undefined,
-  generateVideo: process.env.FAL_KEY
-    ? async (query, { generatedLook, orientation, signal }) => ({
-        url: await filmScene(query, generatedLook, orientation, signal),
-        type: "video" as const,
-      })
+    ? (query, { orientation, signal, fallbackQuery }) => findStockFootage(query, orientation, signal, fallbackQuery)
     : undefined,
+  ...providers,
   welcome: {
     heroQuery: process.env.VIDEO_CHAT_WELCOME_KEYWORD ?? "underwater ocean sunlight",
     prompts: [

package/starters/video-chat/stock.ts

@@ -1,26 +1,10 @@
-/**
- * Stock footage for the modes that do not generate any.
- *
- * A rendered card on a brand gradient is the least a template can look like,
- * and templates-only mode was every scene that way. A stock search costs a few
- * hundred milliseconds and nothing per request, so unlike a generated clip it
- * never lands on the critical path - the difference between cards on gradients
- * and cards over real footage is close to free.
- *
- * Ported from the site's playground, trimmed to what a video chat needs. Every URL
- * that comes back is checked against the host it must come from: the planner
- * asks for a subject, and what a search returns is not something to trust into
- * a page unexamined.
- */
 import type { VideoOrientation } from "@vanillaskyai/video";
 
-const VIDEO_SEARCH = "https://api.pexels.com/videos/search";
+const VIDEO_SEARCH = "https://api.pexels.com/v1/videos/search";
 const PHOTO_SEARCH = "https://api.pexels.com/v1/search";
 const MAX_KEYWORD_LENGTH = 80;
-// Shorter than the shot deadline by two orders of magnitude, deliberately: a
-// scene with no footage is a scene on a gradient, and that is a better outcome
-// than a response that waits.
-const LOOKUP_TIMEOUT_MS = 4_000;
+// One budget covers specific/broader video searches and photo recovery.
+const LOOKUP_TIMEOUT_MS = 3_000;
 
 interface StockMedia {
   url: string;
@@ -28,12 +12,6 @@ interface StockMedia {
   posterUrl?: string;
 }
 
-interface VideoFile {
-  link?: unknown;
-  width?: number;
-  height?: number;
-}
-
 /** One hour, keyed by query. The same response asked twice searches once. */
 const cache = new Map<string, { payload: unknown; expiresAt: number }>();
 
@@ -45,95 +23,132 @@ function normalizeKeyword(value: string): string {
     .slice(0, MAX_KEYWORD_LENGTH);
 }
 
-function trustedUrl(value: unknown, host: string): string {
-  const url = new URL(String(value));
-  if (url.protocol !== "https:" || url.hostname !== host) {
-    throw new Error(`Stock search returned a URL outside ${host}`);
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function entries(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function trustedUrl(value: unknown, host: string): string | undefined {
+  if (typeof value !== "string") return undefined;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:" || url.hostname !== host || url.username || url.password || url.port) return undefined;
+    return url.toString();
+  } catch {
+    return undefined;
   }
-  return url.toString();
 }
 
-function pickVideoFile(files: VideoFile[], orientation: VideoOrientation): VideoFile & { link: string } | null {
-  const usable = files
-    .filter((file): file is VideoFile & { link: string } => typeof file.link === "string")
-    // One file on an unexpected host is one file to skip, not a reason to give
-    // up the search: throwing here lost every other rendition of the same clip.
-    .flatMap((file) => {
-      try {
-        return [{ ...file, link: trustedUrl(file.link, "videos.pexels.com") }];
-      } catch {
-        return [];
-      }
-    })
-    .filter((file) => file.width && file.height);
-  // Matched to the stage, because a clip cropped to the other shape loses
-  // whatever the search was actually for - a landscape river in a portrait
-  // frame is a column of water with both banks cut off.
-  const wanted = orientation === "portrait"
-    ? (file: VideoFile) => (file.height ?? 0) >= (file.width ?? 0)
-    : (file: VideoFile) => (file.width ?? 0) >= (file.height ?? 0);
-  return usable.find(wanted) ?? usable[0] ?? null;
+function pickVideoFile(files: unknown, orientation: VideoOrientation): string | undefined {
+  const usable = entries(files).flatMap((value) => {
+    const file = record(value);
+    const direct = trustedUrl(file.link, "videos.pexels.com");
+    const external = trustedUrl(file.link, "player.vimeo.com");
+    const link = direct ?? (external && /^\/external\/[a-zA-Z0-9._-]+\.mp4$/.test(new URL(external).pathname) ? external : undefined);
+    const { width, height } = file;
+    if (!link || typeof width !== "number" || typeof height !== "number"
+      || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return [];
+    return [{ link, width, height }];
+  });
+  // Prefer the stage's shape without discarding other safe renditions.
+  return (usable.find((file) => orientation === "portrait"
+    ? file.height >= file.width
+    : file.width >= file.height) ?? usable[0])?.link;
 }
 
 async function search(url: string, apiKey: string, signal: AbortSignal): Promise<unknown> {
   const cached = cache.get(url);
   if (cached && cached.expiresAt > Date.now()) return cached.payload;
 
-  const response = await fetch(url, {
-    headers: { Authorization: apiKey },
-    signal: AbortSignal.any([signal, AbortSignal.timeout(LOOKUP_TIMEOUT_MS)]),
-  });
-  // Only a real response is worth keeping. Caching the failure would let one
-  // rate-limited minute leave every response about the Moon on a gradient for
-  // the hour that followed.
-  if (!response.ok) return null;
-  const payload = await response.json();
-  cache.set(url, { payload, expiresAt: Date.now() + 60 * 60 * 1_000 });
-  if (cache.size > 100) cache.delete(cache.keys().next().value!);
-  return payload;
+  if (signal.aborted) return null;
+  try {
+    const response = await fetch(url, {
+      headers: { Authorization: apiKey },
+      signal,
+    });
+    if (!response.ok || signal.aborted) return null;
+    const payload: unknown = await response.json();
+    if (signal.aborted) return null;
+    cache.set(url, { payload, expiresAt: Date.now() + 60 * 60 * 1_000 });
+    if (cache.size > 100) cache.delete(cache.keys().next().value!);
+    return payload;
+  } catch {
+    // A failed video search must still allow the independent photo fallback.
+    if (!signal.aborted) console.warn("[video-chat] Stock lookup unavailable; trying a fallback.");
+    return null;
+  }
+}
+
+/** Metadata is a weak mismatch filter, never visual verification. Numeric URLs
+ * and missing descriptions are unknown and retain the provider's search ranking. */
+function matchesMetadata(item: Record<string, unknown>, keyword: string): boolean {
+  let description = typeof item.alt === "string" ? item.alt : "";
+  if (!description) {
+    const page = trustedUrl(item.url, "www.pexels.com");
+    if (page) description = new URL(page).pathname.replace(/^\/(?:video|photo)\//, "");
+  }
+  const words = (value: string) => normalizeKeyword(value).toLowerCase().split(/[\s-]+/)
+    .filter(word => /\p{L}/u.test(word) && !["a", "an", "the", "of", "in", "on", "with", "and", "video", "photo", "free", "footage"].includes(word));
+  const labels = words(description);
+  const requested = words(keyword);
+  return labels.length === 0 || requested.length === 0 || requested.some(word => labels.includes(word));
 }
 
-/**
- * Find footage for one beat. Video first, a photograph if there is none.
- *
- * Returns null rather than throwing when there is nothing to show: the scene
- * falls back to the brand gradient, which is what it looked like before.
- */
-export async function findStockFootage(subject: string, orientation: VideoOrientation, signal: AbortSignal): Promise<StockMedia | null> {
+/** Video queries precede photos. All work shares one deadline, including body
+ * parsing, even if a custom fetch implementation ignores its abort signal. */
+export async function findStockFootage(subject: string, orientation: VideoOrientation, signal: AbortSignal, fallbackSubject?: string): Promise<StockMedia | null> {
   const apiKey = process.env.PEXELS_API_KEY;
   const keyword = normalizeKeyword(subject);
-  if (!apiKey || !keyword) return null;
-
-  const params = new URLSearchParams({ query: keyword, orientation, per_page: "3", page: "1" });
-  const started = Date.now();
-  try {
-    const videos = await search(`${VIDEO_SEARCH}?${params}`, apiKey, signal) as
-      { videos?: Array<{ image?: unknown; video_files?: VideoFile[] }> } | null;
-    for (const video of videos?.videos ?? []) {
-      const file = pickVideoFile(video.video_files ?? [], orientation);
-      if (!file) continue;
-      console.log(`[video-chat] stock video in ${Date.now() - started}ms: ${keyword}`);
-      return {
-        url: file.link,
-        type: "video",
-        // The still shown while the video decodes its first frame, which is
-        // otherwise a flash of gradient where the footage should be.
-        ...(video.image ? { posterUrl: trustedUrl(video.image, "images.pexels.com") } : {}),
-      };
+  if (!apiKey || !keyword || signal.aborted) return null;
+  const keywords = [keyword];
+  const fallback = normalizeKeyword(fallbackSubject ?? "");
+  if (fallback && fallback.toLowerCase() !== keyword.toLowerCase()) keywords.push(fallback);
+  const controller = new AbortController();
+  let finish!: (value: null) => void;
+  const stopped = new Promise<null>(resolve => { finish = resolve; });
+  const abort = () => { controller.abort(); finish(null); };
+  signal.addEventListener("abort", abort, { once: true });
+  const timer = setTimeout(abort, LOOKUP_TIMEOUT_MS);
+  const active = controller.signal;
+  const lookup = async (): Promise<StockMedia | null> => {
+    for (const query of keywords) {
+      const params = new URLSearchParams({ query, orientation, per_page: "3", page: "1" });
+      const videos = record(await search(`${VIDEO_SEARCH}?${params}`, apiKey, active));
+      if (active.aborted) return null;
+      for (const value of entries(videos.videos)) {
+        const video = record(value);
+        if (!matchesMetadata(video, query)) continue;
+        const url = pickVideoFile(video.video_files, orientation);
+        if (!url) continue;
+        const posterUrl = trustedUrl(video.image, "images.pexels.com");
+        return { url, type: "video", ...(posterUrl ? { posterUrl } : {}) };
+      }
     }
-
-    const photos = await search(`${PHOTO_SEARCH}?${params}`, apiKey, signal) as
-      { photos?: Array<{ src?: { large2x?: unknown; large?: unknown } }> } | null;
-    const photo = photos?.photos?.[0]?.src?.large2x ?? photos?.photos?.[0]?.src?.large;
-    if (!photo) return null;
-    console.log(`[video-chat] stock photo in ${Date.now() - started}ms: ${keyword}`);
-    return { url: trustedUrl(photo, "images.pexels.com"), type: "image" };
-  } catch (cause) {
-    // A timeout, an abort, or a search that returned something unexpected. The
-    // beat keeps its copy on the brand gradient.
-    if (!signal.aborted) {
-      console.warn(`[video-chat] stock search failed after ${Date.now() - started}ms:`, cause instanceof Error ? cause.message : cause);
+    for (const query of keywords) {
+      const params = new URLSearchParams({ query, orientation, per_page: "3", page: "1" });
+      const photos = record(await search(`${PHOTO_SEARCH}?${params}`, apiKey, active));
+      if (active.aborted) return null;
+      for (const value of entries(photos.photos)) {
+        const photo = record(value);
+        if (!matchesMetadata(photo, query)) continue;
+        const source = record(photo.src);
+        for (const candidate of [source.large2x, source.large]) {
+          const url = trustedUrl(candidate, "images.pexels.com");
+          if (url) return { url, type: "image" };
+        }
+      }
     }
     return null;
+  };
+  try {
+    return await Promise.race([lookup(), stopped]);
+  } finally {
+    clearTimeout(timer);
+    signal.removeEventListener("abort", abort);
   }
 }