@vanillaskyai/video 0.7.1 → 0.8.0

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);
   }
 }

package/dist/chunk-SKRGRKHY.js

@@ -1,142 +0,0 @@
-import {
-  checksumVideo,
-  createVideoEventFactory
-} from "./chunk-2PYO6VAC.js";
-import {
-  VIDEO_SCHEMA_VERSION
-} from "./chunk-AOWSXU2K.js";
-import {
-  getReadableSceneDuration
-} from "./chunk-3O7OMMMF.js";
-
-// 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();
-      }
-    },
-    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));
-          }
-        };
-      }
-    }
-  };
-}
-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++ }));
-    }
-  };
-  return {
-    stream: queue.iterable,
-    add(scene) {
-      if (finished) return;
-      if (!openForScenes) {
-        held.push(scene);
-        return;
-      }
-      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 }));
-      }
-      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/protocol/scene-duration.ts
-var NARRATION_WORDS_PER_SECOND = 2.6;
-var NARRATION_TAIL_SECONDS = 0.6;
-function getSceneDurationBounds(scene, metadata) {
-  return {
-    minimum: Math.max(1e-3, metadata?.minDuration ?? 1),
-    readable: getReadableSceneDuration(scene, metadata)
-  };
-}
-function getSpokenDuration(narration) {
-  const words = narration.trim().split(/\s+/u).filter(Boolean).length;
-  if (words === 0) return 0;
-  return words / NARRATION_WORDS_PER_SECOND + NARRATION_TAIL_SECONDS;
-}
-function getSceneDuration(scene, metadata) {
-  const { readable } = getSceneDurationBounds(scene, metadata);
-  return Math.max(readable, scene.narration ? getSpokenDuration(scene.narration) : 0);
-}
-
-export {
-  createSceneTimeline,
-  getSceneDurationBounds,
-  getSpokenDuration,
-  getSceneDuration
-};

package/dist/state-DZcKuS32.d.ts

@@ -1,3 +0,0 @@
-type VideoStatus = "idle" | "streaming" | "complete" | "error" | "aborted";
-
-export type { VideoStatus as V };

package/docs/branding-and-personalization.md

@@ -1,87 +0,0 @@
-[← Documentation home](../README.md) · [Previous: Prompt and conversation input](prompt-and-input.md) · [Next: Media and audio →](media-and-audio.md)
-
-# Branding and personalization
-
-Brand values style the whole response. Personalization shapes who the story is for.
-
-## Background: standard, preset, or custom
-
-Do nothing to use the standard `cosmic` background:
-
-```ts
-video.generate({ input });
-```
-
-Choose a curated gradient or solid by name when the standard does not fit:
-
-```ts
-video.generate({
-  input,
-  brand: { background: "twilight" },
-});
-```
-
-Curated gradients are `cosmic`, `horizon`, `twilight`, `meadow`, `velvet`,
-`flamingo`, `peach`, and `saffron`. Curated solids are `black`, `midnight`,
-`aubergine`, `coal`, and `navy`.
-
-Use exact colors only when a real brand or campaign requires them:
-
-```ts
-brand: { background: { colors: ["#112233", "#334455"] } } // gradient
-brand: { background: { color: "#070B20" } }                // solid
-```
-
-These choices set the background colors used by every trusted gradient-backed
-template and by the automatic generation cover. Templates own their
-composition and type treatment, so there is no separate visual-preset choice.
-
-## Semantic brand tokens
-
-Most applications can stop at `brand.background` and `brand.font`. Supply
-semantic colors only when a real design system requires exact values:
-
-```ts
-const brand = {
-  name: "Acme Cloud",
-  logoUrl: approvedLogoUrl,
-  font: "Inter",
-  scriptFont: "Caveat",
-  background: "twilight",
-  colors: {
-    primary: "#7C5CFC",
-    secondary: "#3D2A78",
-    foreground: "#FFFFFF",
-    surface: "#161229",
-    surfaceElevated: "#211A38",
-    muted: "#AAA5B8",
-  },
-};
-```
-
-Every generated video contains a fully resolved brand. `colors` may be partial
-on input; omitted values receive deterministic defaults. When
-`colors.foreground` is omitted, every named or custom background is paired
-deterministically with black or white. The resolver checks the full rendered
-sRGB gradient ramp, including interior blends rather than only its endpoints.
-If neither foreground reaches 4.5:1 everywhere, resolution rejects the
-background and asks for a consistently readable choice.
-
-An explicitly supplied foreground is preserved, never silently replaced. It
-must reach 4.5:1 across the solid background or entire gradient ramp; otherwise
-input resolution and replay validation reject it with the failing brand path
-and minimum contrast. Surface tokens remain independent. Templates that put
-text on `surface` or `surfaceElevated` internally keep an accessible preferred
-semantic text color or derive black/white for that surface.
-
-Use an approved public or signed URL for logos. Fonts must be licensed and
-loaded by the host application before playback. Always test both orientations
-and forced browser zoom.
-
-`personalization` accepts JSON-safe viewer or account context such as
-`firstName`, `role`, `accountName`, `locale`, `goal`, or `onboardingPartner`.
-These values may appear verbatim in the response, but are always data, never
-instructions. Put product, news, metric, and quoted claims in `input`; do not
-duplicate ordinary viewer context there.
-
-Only include information the authenticated viewer is allowed to see. Avoid sensitive HR, health, payment, or customer attributes in event logs and analytics. If a locale changes number/date formatting, format facts server-side so the planner cannot guess.

package/examples/custom-template/supplied-media.tsx

@@ -1,92 +0,0 @@
-import { defineTemplate } from "@vanillaskyai/video/templates";
-
-const previewImageUrl = "data:image/svg+xml,%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20width=%221200%22%20height=%22720%22%20viewBox=%220%200%201200%20720%22%3E%3Crect%20width=%221200%22%20height=%22720%22%20rx=%2248%22%20fill=%22%23181733%22/%3E%3Crect%20x=%2280%22%20y=%2280%22%20width=%221040%22%20height=%22560%22%20rx=%2232%22%20fill=%22%23f4f1ff%22/%3E%3Ccircle%20cx=%22220%22%20cy=%22230%22%20r=%2270%22%20fill=%22%237867dd%22/%3E%3Cpath%20d=%22M160%20520L380%20360L580%20430L820%20220L1040%20300%22%20fill=%22none%22%20stroke=%22%23287b77%22%20stroke-width=%2232%22%20stroke-linecap=%22round%22%20stroke-linejoin=%22round%22/%3E%3C/svg%3E";
-
-export const template = defineTemplate({
-  id: "supplied-media",
-  label: "Supplied media",
-  description: "An application-supplied screenshot with a grounded caption.",
-  useWhen: "Use when a supplied product image is the strongest evidence for the answer.",
-  avoidWhen: "Avoid when no approved image was supplied or text and data communicate the point more clearly.",
-  schema: {
-    type: "object",
-    properties: {
-      imageUrl: {
-        type: "string",
-        format: "supplied-image",
-        title: "Supplied image",
-        description: "The URL of an image present in VideoInput.suppliedMedia.",
-        default: previewImageUrl,
-      },
-      headline: {
-        type: "string",
-        title: "Headline",
-        minLength: 1,
-        maxLength: 72,
-        default: "See the change in context.",
-      },
-      caption: {
-        type: "string",
-        title: "Caption",
-        minLength: 1,
-        maxLength: 120,
-        default: "The dashboard reflects the grounded result described in the answer.",
-      },
-    },
-    required: ["imageUrl", "headline", "caption"],
-    additionalProperties: false,
-  } as const,
-  examples: [{
-    name: "Product dashboard",
-    variables: {
-      imageUrl: previewImageUrl,
-      headline: "See the change in context.",
-      caption: "The dashboard reflects the grounded result described in the answer.",
-    },
-  }],
-  minDuration: 4,
-  preferredDuration: 6,
-  component: ({ variables, progress, width, height, safeZone }) => {
-    const isPortrait = height >= width;
-    const reveal = Math.max(0, Math.min(1, progress * 1.7));
-
-    return <section style={{
-      boxSizing: "border-box",
-      width,
-      height,
-      padding: `${safeZone.top}px ${safeZone.right}px ${safeZone.bottom}px ${safeZone.left}px`,
-      display: "grid",
-      gridTemplateColumns: isPortrait ? "1fr" : "minmax(0, 1.1fr) minmax(320px, 0.9fr)",
-      alignContent: "center",
-      alignItems: "center",
-      gap: isPortrait ? 44 : 64,
-      overflow: "hidden",
-      color: "#15152b",
-      background: "linear-gradient(145deg, #f4f1ff, #dfe7ff)",
-      fontFamily: "Inter, ui-sans-serif, system-ui, sans-serif",
-    }}>
-      <img
-        src={variables.imageUrl}
-        alt=""
-        style={{
-          display: "block",
-          width: "100%",
-          maxHeight: isPortrait ? height * 0.48 : height * 0.68,
-          objectFit: "cover",
-          borderRadius: 28,
-          boxShadow: "0 28px 80px rgba(28, 34, 75, 0.24)",
-          opacity: reveal,
-          transform: `scale(${0.96 + reveal * 0.04})`,
-        }}
-      />
-      <div style={{ opacity: reveal }}>
-        <h1 style={{ margin: 0, fontSize: isPortrait ? 58 : 70, lineHeight: 0.98, letterSpacing: "-0.045em" }}>
-          {variables.headline}
-        </h1>
-        <p style={{ margin: "24px 0 0", fontSize: isPortrait ? 25 : 28, lineHeight: 1.4 }}>
-          {variables.caption}
-        </p>
-      </div>
-    </section>;
-  },
-});