@vanillaskyai/video 0.10.18 → 0.10.20

package/dist/server.js

@@ -1235,6 +1235,7 @@ function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlr
     `The selected footage mode is ${mode === "pexels" ? "Pexels stock search: use literal filmable subjects; never imply stock proves a mechanism or depicts fictional events exactly" : `AI video, with at most ${generatedVideoAvailable ? maxGeneratedVideos : 0} generation attempts`}. Missing footage becomes the authored chapter title, with complete narration. Never truncate already-authored narration when footage fails. The host selects providers; do not make source choices.`,
     ...mode === "cinematic" ? [generatedVideoAvailable && maxGeneratedVideos > 0 ? `Plan at most ${maxGeneratedVideos} generated-video beats in total, including the saved ending. Use at most ${maxGeneratedVideos - 1} developing shot records; the ending uses the remaining beat. The opening chapter does not consume a generated clip. Before writing, choose a concise, complete treatment that fits this budget: combine related ideas, preserve essential facts and qualifiers, and finish the requested answer. Do not plan an extra chapter tail simply because generation attempts will run out.${maxGeneratedVideos === 1 ? " Put the complete answer in the saved ending, set development to an empty string, and emit no developing shot records." : ""}` : "No generated-video attempts are available; plan a complete chapter-led answer with a useful ending. Do not omit the answer to satisfy a zero clip budget."] : [],
     ...mode === "pexels" ? ["Stock queries must retain the essential subject, activity and distinguishing equipment in the shot's subject field, within its word limit. That field alone is the search query; action and visualDirection do not refine it. Prefer common observable actions with usable framing. Do not replace the required actor or activity with scenery, a different sport or a loosely related setting. Preserve fictional or comic narration, but do not depend on stock showing an exact invented expression or sequence; choose an illustrative action that supports the beat."] : [],
+    ...mode === "pexels" ? ["Choose a separate stock subject for each beat, describing footage that can realistically exist in a stock library. For historical, abstract or unseen events, use relevant present-day evidence, objects, environments or analogous visible processes as clearly illustrative support. Do not require literal footage of events or subjects that cannot realistically be filmed. Keep the causal explanation in narration; do not claim illustrative footage records the historical event or proves the mechanism. Make stockSelection describe the chosen visible subject, not the overall topic. Do not use illustrative freedom to replace a required practical action, person, sport or distinguishing equipment with unrelated scenery."] : [],
     ...mode === "pexels" ? ['Include stockSelection on every shot and the saved ending when the essential subject is known: "stockSelection":{"subject":"essential actor or object category","activity":"optional literal activity","equipment":"optional distinguishing equipment","exclude":["optional contradictory subject or activity"]}. Each phrase must be 1\u20134 words and at most 48 characters; exclude has at most 3 phrases. The essential subject is separate from the setting: do not use scenery, mood, camera framing or incidental appearance as the actor. Keep the search query broad enough to find footage; the optional hint helps select results without substituting a different actor or task. Use exclusions only for actual contradictions, not every detail absent from the story. Omit unknown fields or the whole hint rather than inventing an anchor. This is selection guidance, not verification that footage depicts the exact narration.'] : [],
     "Keep development to one concise sentence and visualDirection to the few details needed for consistency. Emit the complete brief, then the first developing shot immediately when developing shots are needed and allowed by the budget; otherwise end after the brief. Continue the same stream without an outline, recap or second planning pass. The saved ending must still contain the complete payoff before the brief is emitted.",
     "For a very short answer whose ending alone fulfills the request, development may be empty and no developing shots are needed. Otherwise, develop the essential content before the ending.",

package/docs/reference/protocol.md

@@ -116,3 +116,13 @@ Grouped playback requires prepared speech with `supportsOffsets: true`. The gene
 For standalone playback, provide a synchronous `narrationReady` callback alongside your `onSceneChange` narration handler. Return false while a new grouped paragraph awaits actual audio onset, then true from the voice's `onStart` callback; also release readiness on completion, failure, or interruption. Abort pending narration from the player's `onError` handler. `VideoChat` wires this automatically through its internal narration hook. For grouped paragraphs, the voice must invoke `onStart` when audio actually begins, not when audio is prepared or `play()` is requested. The first visual cue starts narration, then the playhead waits for that onset without pausing the voice. A missing onset stops the player with an error after eight seconds of active waiting. For prepared audio, also provide `narrationTime(scene)` using the active voice's optional `getCurrentTime()`: return paragraph-relative seconds (including the seek offset) for a group, or scene-relative seconds otherwise. This makes the actual audio clock authoritative through cold-start delays and mid-speech stalls. Return `undefined` for silent scenes or unavailable clocks; after ordinary narration completes, release to wall time so the authored reading hold can finish. `VideoChat` coordinates these callbacks automatically. A clock that stops advancing for eight active seconds produces an error; visual-readiness holds and deliberate pauses do not consume that timeout. Voices without an observable playback clock retain wall-time playback.
 
 Readiness holds pause narration together with the picture. The same audio continues across adjacent group scenes; replay starts a new playback session. This preserves words through delayed media rather than promising uninterrupted playback on every network.
+
+### Host-resolved chat footage mode
+
+A chat host that changes the requested footage mode before planning may return
+`x-vanillasky-resolved-video-mode: pexels` or `cinematic` on a successful SSE
+response. The default chat client records that mode for the active turn and its
+playback metrics. Unknown values are ignored. Authorization, allowance checks
+and provider selection remain host-owned; the header never grants access or
+changes a spending limit. A mixed response that changes footage source partway
+through retains its initially resolved mode.

package/package.json

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

package/starters/video-chat/package.json

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

package/starters/video-chat/stock.ts

@@ -53,48 +53,59 @@ export async function findStockFootage(query: string, orientation: VideoOrientat
   const normalized = query.trim().toLowerCase().replace(/\s+/g, " ");
   const tokens = words(normalized);
   const selection = selectionHint(rawSelection);
-  const key = JSON.stringify({version: 3, orientation, query: normalized, selection});
+  const key = JSON.stringify({version: 5, orientation, query: normalized, selection});
   const apiKey = process.env.PEXELS_API_KEY;
   if (!apiKey || !tokens.length || normalized.length > 80 || tokens.length > 8) return null;
   const existing = cache.get(key);
   if (existing && existing.expires > Date.now()) return existing.media;
-  const url = new URL("https://api.pexels.com/v1/videos/search");
-  url.search = new URLSearchParams({ query: normalized, orientation, per_page: "12", size: "medium" }).toString();
-  const response = await fetch(url, { headers: { Authorization: apiKey }, signal });
-  signal.throwIfAborted();
-  if (!response.ok) return null;
-  const result = await response.json() as { videos?: PexelsVideo[] };
-  signal.throwIfAborted();
-  let selected: StockVideo | null = null, bestScore = -1;
-  for (const video of (Array.isArray(result.videos) ? result.videos : []).slice(0, 12)) {
-    if (!pexelsUrl(video.url)) continue;
-    const slug = new URL(video.url).pathname.replace(/^\/video\//, "");
-    const title = typeof video.title === "string" ? video.title : "";
-    const tags = Array.isArray(video.tags) ? video.tags.filter((tag): tag is string => typeof tag === "string").join(" ") : "";
-    const subject = words(`${slug} ${title} ${typeof video.description === "string" ? video.description : ""} ${tags}`).filter(token => !/^\d+$/.test(token)).map(wordForm);
-    let matches = tokens.filter(token => subject.includes(wordForm(token))).length;
-    if (selection && subject.length) {
-      const covers = (phrase: string) => terms(phrase).every(word => subject.includes(wordForm(word)));
-      if (!covers(selection.subject) || selection.exclude?.some(covers)) continue;
-      // Query context breaks equal hint matches without outweighing a hint.
-      const contextScore = matches / (tokens.length + 1);
-      matches = 2 + contextScore + Number(Boolean(selection.activity && covers(selection.activity)))
-        + Number(Boolean(selection.equipment && covers(selection.equipment)));
+  let selected: StockVideo | null = null;
+  // Reuse the caller's deadline signal; broadening never starts a new timeout.
+  const queries = [...new Set([normalized, ...(selection ? [selection.subject] : [])])];
+  for (const searchQuery of queries) {
+    signal.throwIfAborted();
+    const url = new URL("https://api.pexels.com/v1/videos/search");
+    url.search = new URLSearchParams({ query: searchQuery, per_page: "12", size: "medium" }).toString();
+    const response = await fetch(url, { headers: { Authorization: apiKey }, signal });
+    signal.throwIfAborted();
+    if (!response.ok) return null;
+    const result = await response.json() as { videos?: PexelsVideo[] };
+    signal.throwIfAborted();
+    let bestScore = -1, bestOrientation = -1;
+    const matchesOrientation = (file: {width?: number; height?: number}) => orientation === "portrait"
+      ? file.height! > file.width! : file.width! >= file.height!;
+    for (const video of (Array.isArray(result.videos) ? result.videos : []).slice(0, 12)) {
+      if (!pexelsUrl(video.url)) continue;
+      const slug = new URL(video.url).pathname.replace(/^\/video\//, "");
+      const title = typeof video.title === "string" ? video.title : "";
+      const tags = Array.isArray(video.tags) ? video.tags.filter((tag): tag is string => typeof tag === "string").join(" ") : "";
+      const subject = words(`${slug} ${title} ${typeof video.description === "string" ? video.description : ""} ${tags}`).filter(token => !/^\d+$/.test(token)).map(wordForm);
+      let matches = tokens.filter(token => subject.includes(wordForm(token))).length;
+      if (selection && subject.length) {
+        const covers = (phrase: string) => terms(phrase).every(word => subject.includes(wordForm(word)));
+        if (selection.exclude?.some(covers)) continue;
+        // Query context breaks equal hint matches without outweighing a hint.
+        const contextScore = matches / (tokens.length + 1);
+        matches = covers(selection.subject) ? 2 + contextScore + Number(Boolean(selection.activity && covers(selection.activity)))
+          + Number(Boolean(selection.equipment && covers(selection.equipment))) : 0;
+      }
+      // The documented Video resource can have only a numeric page URL and no
+      // editorial metadata. Preserve provider search order for unknown relevance;
+      // positive overlap ranks above provider-ranked illustrative alternatives.
+      const files = (Array.isArray(video.video_files) ? video.video_files : []).filter(file =>
+        file.file_type === "video/mp4" && pexelsUrl(file.link)
+        && Number.isFinite(file.width) && Number.isFinite(file.height)
+        && Math.min(file.width!, file.height!) >= 360,
+      ).sort((a, b) => Number(matchesOrientation(b)) - Number(matchesOrientation(a)) || Math.abs(Math.max(a.width!, a.height!) - 1280) - Math.abs(Math.max(b.width!, b.height!) - 1280));
+      const file = files[0];
+      if (!file) continue;
+      const orientationScore = Number(matchesOrientation(file));
+      // Prefer composition fit only when subject relevance is equal.
+      if (matches < bestScore || (matches === bestScore && orientationScore <= bestOrientation)) continue;
+      bestScore = matches;
+      bestOrientation = orientationScore;
+      selected = { url: file.link!, type: "video", ...(pexelsUrl(video.image) ? { posterUrl: video.image } : {}) };
     }
-    // The documented Video resource can have only a numeric page URL and no
-    // editorial metadata. Preserve provider search order for unknown relevance;
-    // positive overlap ranks above it, while explicitly unrelated copy is skipped.
-    if (subject.length > 0 && matches === 0) continue;
-    const files = (Array.isArray(video.video_files) ? video.video_files : []).filter(file =>
-      file.file_type === "video/mp4" && pexelsUrl(file.link)
-      && Number.isFinite(file.width) && Number.isFinite(file.height)
-      && Math.min(file.width!, file.height!) >= 360
-      && (orientation === "portrait" ? file.height! > file.width! : file.width! >= file.height!),
-    ).sort((a, b) => Math.abs(Math.max(a.width!, a.height!) - 1280) - Math.abs(Math.max(b.width!, b.height!) - 1280));
-    const file = files[0];
-    if (!file || matches <= bestScore) continue;
-    bestScore = matches;
-    selected = { url: file.link!, type: "video", ...(pexelsUrl(video.image) ? { posterUrl: video.image } : {}) };
+    if (selected) break;
   }
   // Bounded process-local cache; no request signal or credentials are retained.
   if (cache.size >= 128) cache.delete(cache.keys().next().value!);

package/styles/video-chat.css

@@ -370,16 +370,6 @@
   text-shadow: 0 1px 3px oklch(0.14 0.05 265 / 70%);
 }
 
-.vanillasky-video-chat .ending .cards {
-  margin-top: 0;
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  flex-shrink: 0;
-  overflow: visible;
-}
-
-.vanillasky-video-chat .ending .card-dots { align-self: flex-start; margin-left: -0.35rem; }
-
 .vanillasky-video-chat .panel { display: grid; align-items: center; min-height: 0; background: var(--vs-bg); }
 
 .vanillasky-video-chat .panel-inner {
@@ -620,7 +610,7 @@
 
 .vanillasky-video-chat .cards { gap: 14px; margin: auto -12px 0; width: calc(100% + 24px); max-width: calc(100% + 24px); padding: 12px; }
 
-.vanillasky-video-chat .cards button { width: clamp(160px, 18vw, 260px); aspect-ratio: 1.65; border-radius: 14px; box-shadow: 0 8px 30px rgb(0 0 0 / 24%); background: #202438; }
+.vanillasky-video-chat .cards button { --vs-card-width: clamp(160px, 18vw, 260px); --vs-card-ratio: 1.65; width: var(--vs-card-width); aspect-ratio: 1.65; border-radius: 14px; box-shadow: 0 8px 30px rgb(0 0 0 / 24%); background: #202438; }
 
 .vanillasky-video-chat .card-prompt { font-size: clamp(13px, 1.1vw, 16px); padding: 14px 16px; letter-spacing: -.015em; font-weight: 550; }
 
@@ -642,7 +632,7 @@
   .vanillasky-video-chat .welcome-body { padding: max(135px, 17dvh) 20px 118px; gap: 24px; }
   .vanillasky-video-chat .welcome-title { font-size: clamp(36px, 9.6vw, 58px); line-height: 1.12; letter-spacing: -.055em; }
   .vanillasky-video-chat .cards { gap: 12px; width: calc(100% + 20px); max-width: calc(100% + 20px); padding: 12px 20px 12px 12px; }
-  .vanillasky-video-chat .cards button { width: 172px; aspect-ratio: .95; }
+  .vanillasky-video-chat .cards button { --vs-card-width: 172px; --vs-card-ratio: .95; width: var(--vs-card-width); aspect-ratio: .95; }
   .vanillasky-video-chat .card-prompt { font-size: 14px; padding: 14px; }
 
 }
@@ -650,13 +640,13 @@
 @media (max-height: 650px) and (min-width: 701px) {
   .vanillasky-video-chat .welcome-body { padding-top: 110px; padding-bottom: 118px; }
   .vanillasky-video-chat .welcome-title { font-size: clamp(32px, 4vw, 54px); }
-  .vanillasky-video-chat .cards button { width: 160px; }
+  .vanillasky-video-chat .cards button { --vs-card-width: 160px; width: var(--vs-card-width); }
 }
 
 @media (max-height: 650px) and (max-width: 700px) {
   .vanillasky-video-chat .welcome-body { padding-top: 98px; }
   .vanillasky-video-chat .welcome-title { font-size: 34px; }
-  .vanillasky-video-chat .cards button { width: 145px; aspect-ratio: 1.5; }
+  .vanillasky-video-chat .cards button { --vs-card-width: 145px; --vs-card-ratio: 1.5; width: var(--vs-card-width); aspect-ratio: 1.5; }
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -1075,35 +1065,65 @@
 }
 
 .vanillasky-video-chat .opening-chapter { animation: vanillasky-chapter-enter 450ms ease-out both; }
-.vanillasky-video-chat .media-credit { color: var(--vs-fg); font-size: 11px; margin-left: 12px; text-underline-offset: 3px; }
 @keyframes vanillasky-chapter-enter { from { opacity: 0; } to { opacity: 1; } }
 @media (prefers-reduced-motion: reduce) { .vanillasky-video-chat .opening-chapter { animation: none; } }
 
-.vanillasky-video-chat .ending .cards li { min-width: 0; }
-
-.vanillasky-video-chat .ending .cards button {
-  display: flex;
-  flex-direction: column;
-  justify-content: flex-end;
-  width: 100%;
-  height: 100%;
-  min-height: 180px;
-  aspect-ratio: auto;
+@media (max-height: 650px) {
+  .vanillasky-video-chat .ending-body { inset-block: 80px 180px; }
 }
 
-.vanillasky-video-chat .ending .card-prompt {
-  position: relative;
-  inset: auto;
-  overflow-wrap: anywhere;
-  font-size: clamp(14px, 1.2vw, 18px);
+.vanillasky-video-chat .video-preparation {
+  position: absolute;
+  inset-inline: 0;
+  z-index: 3;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  pointer-events: none;
+  color: rgb(255 255 255 / 62%);
+  font-size: 17px;
   line-height: 1.4;
 }
-
-@container (min-width: 1200px) {
-  .vanillasky-video-chat .ending .cards { grid-template-columns: repeat(4, minmax(0, 1fr)); }
-  .vanillasky-video-chat .ending .cards button { min-height: 210px; }
+.vanillasky-video-chat .video-preparation-spinner {
+  width: 16px;
+  height: 16px;
+  border: 1.5px solid rgb(255 255 255 / 18%);
+  border-top-color: rgb(255 255 255 / 75%);
+  border-radius: 50%;
+  animation: vanillasky-video-preparation 1s linear infinite;
+}
+@keyframes vanillasky-video-preparation { to { transform: rotate(360deg); } }
+@media (prefers-reduced-motion: reduce) {
+  .vanillasky-video-chat .video-preparation-spinner { animation: none; }
 }
 
-@media (max-height: 650px) {
-  .vanillasky-video-chat .ending-body { inset-block: 80px 180px; }
+.vanillasky-video-chat .video-preparation-text {
+  color: transparent;
+  background: linear-gradient(105deg, rgb(255 255 255 / 55%) 35%, #fff 50%, rgb(255 255 255 / 55%) 65%);
+  background-size: 250% 100%;
+  background-clip: text;
+  -webkit-background-clip: text;
+  animation: vanillasky-preparation-shimmer 2.4s ease-in-out infinite;
 }
+@keyframes vanillasky-preparation-shimmer {
+  from { background-position: 100% 0; }
+  to { background-position: 0% 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .vanillasky-video-chat .video-preparation-text { animation: none; background: none; color: inherit; }
+}
+@media (forced-colors: active) {
+  .vanillasky-video-chat .video-preparation-text { animation: none; background: none; color: CanvasText; }
+}
+
+.vanillasky-video-chat .home-link { display: inline-flex; border-radius: 4px; }
+.vanillasky-video-chat .home-link:focus-visible { outline: 2px solid currentColor; outline-offset: 6px; }
+.vanillasky-video-chat .cards button { display: flex; flex-direction: column; justify-content: flex-end; aspect-ratio: auto; min-height: calc(var(--vs-card-width) / var(--vs-card-ratio)); }
+.vanillasky-video-chat .card-prompt { position: relative; inset: auto; overflow-wrap: anywhere; flex-shrink: 0; }
+
+.vanillasky-video-chat .cards { flex-shrink: 0; }
+
+.vanillasky-video-chat .transcript-toggle { display: inline-flex; align-items: center; gap: 8px; min-height: 40px; padding: 8px 12px; border: 0; border-radius: 10px; background: var(--vs-media-glass); color: var(--vs-media-muted); font: inherit; font-size: 13px; cursor: pointer; pointer-events: auto; }
+.vanillasky-video-chat .transcript-toggle svg { width: 16px; height: 16px; }
+.vanillasky-video-chat .transcript-toggle:focus-visible { outline: 2px solid currentColor; outline-offset: 3px; }