@vanillaskyai/video 0.10.18 → 0.10.19

package/CHANGELOG.md

@@ -4,6 +4,12 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.19
+
+- Show a subtle preparation status while the first response scene is loading.
+- Use the same compact suggestion-card layout before and after answers, and link the logo to the homepage.
+- Plan relevant illustrative stock subjects per beat and prefer, rather than require, matching footage orientation in the starter.
+
 ## 0.10.18
 
 - Preserve later valid shots after a malformed body record containing an unescaped newline, while keeping malformed initial containers rejected. Bound unfinished JSON records independently of provider chunk sizes.

package/dist/react.js

@@ -3047,35 +3047,46 @@ function Welcome({ data, onAsk, title }) {
 
 // src/video-chat/opening-chapter.tsx
 import { useLayoutEffect, useRef as useRef5, useState as useState4 } from "react";
-import { jsx as jsx6 } from "react/jsx-runtime";
-function OpeningChapter({ title }) {
+import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
+function OpeningChapter({ title, preparing = false }) {
   const root = useRef5(null);
   const [size, setSize] = useState4({ width: 1080, height: 1080 });
+  const [titleBottom, setTitleBottom] = useState4(0);
   useLayoutEffect(() => {
     const element = root.current;
     if (!element) return;
     const measure = () => {
       const { width, height } = element.getBoundingClientRect();
       if (width > 0 && height > 0) setSize({ width, height });
+      const title3 = element.querySelector('[data-title-composition="centered"]');
+      if (title3) setTitleBottom(title3.getBoundingClientRect().bottom - element.getBoundingClientRect().top);
     };
     measure();
     if (typeof ResizeObserver === "undefined") return;
     const observer = new ResizeObserver(measure);
     observer.observe(element);
+    const title2 = element.querySelector('[data-title-composition="centered"]');
+    if (title2) observer.observe(title2);
     return () => observer.disconnect();
-  }, []);
-  return /* @__PURE__ */ jsx6("div", { ref: root, "data-opening-chapter": true, className: "opening-chapter", children: /* @__PURE__ */ jsx6(
-    TitleSceneTemplate,
-    {
-      variables: { title },
-      style: {},
-      width: size.width,
-      height: size.height,
-      progress: 0.3,
-      beatIntensity: 0,
-      safeZone: { top: 0, right: 0, bottom: 0, left: 0 }
-    }
-  ) });
+  }, [title]);
+  return /* @__PURE__ */ jsxs6("div", { ref: root, "data-opening-chapter": true, className: "opening-chapter", children: [
+    /* @__PURE__ */ jsx6(
+      TitleSceneTemplate,
+      {
+        variables: { title },
+        style: {},
+        width: size.width,
+        height: size.height,
+        progress: 0.3,
+        beatIntensity: 0,
+        safeZone: { top: 0, right: 0, bottom: 0, left: 0 }
+      }
+    ),
+    preparing && /* @__PURE__ */ jsxs6("div", { className: "video-preparation", style: { top: titleBottom + 24 }, role: "status", "aria-label": "Video preparation", children: [
+      /* @__PURE__ */ jsx6("span", { className: "video-preparation-spinner", "aria-hidden": "true" }),
+      /* @__PURE__ */ jsx6("span", { className: "video-preparation-text", children: "Preparing your video\u2026" })
+    ] })
+  ] });
 }
 
 // src/video-chat/use-voice-input.ts
@@ -3353,7 +3364,7 @@ var visualModes = [
 var defaultMode = visualModes[0];
 
 // src/video-chat/video-chat.tsx
-import { Fragment as Fragment4, jsx as jsx8, jsxs as jsxs6 } from "react/jsx-runtime";
+import { Fragment as Fragment4, jsx as jsx8, jsxs as jsxs7 } from "react/jsx-runtime";
 var DESKTOP_WIDTH = 900;
 function useViewportOrientation() {
   const [portrait, setPortrait] = useState7(() => typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(`(max-width: ${DESKTOP_WIDTH - 1}px) and (orientation: portrait)`).matches : false);
@@ -3457,6 +3468,13 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
   const handoffStopped = chat.status === "error" || chat.status === "cancelled";
   const waitingForBody = showing && presentedBody !== handoffKey;
   const openingChapter = Boolean(shown?.prompt) && (!showing || waitingForBody) && chat.status !== "error" && chat.status !== "cancelled" && chat.status !== "ended";
+  const [preparingKey, setPreparingKey] = useState7();
+  useEffect9(() => {
+    setPreparingKey(void 0);
+    if (!openingChapter || !shown?.opening || chat.speaking) return;
+    const timer = setTimeout(() => setPreparingKey(shown.id), 1e3);
+    return () => clearTimeout(timer);
+  }, [openingChapter, shown?.opening, shown?.id, chat.speaking]);
   useLayoutEffect2(() => {
     const current = { key: handoffKey, live: showing && !handoffStopped, active: openingChapter && showing, frame: 0 };
     handoff.current = current;
@@ -3533,7 +3551,7 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
     observer.observe(composer);
     return () => observer.disconnect();
   }, []);
-  return /* @__PURE__ */ jsxs6(
+  return /* @__PURE__ */ jsxs7(
     "div",
     {
       className: `vanillasky-video-chat${className ? ` ${className}` : ""}`,
@@ -3545,13 +3563,13 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
       onPointerDown: controls.reveal,
       onKeyDownCapture: controls.reveal,
       children: [
-        /* @__PURE__ */ jsxs6("header", { className: "chrome", ...controlEvents, children: [
-          /* @__PURE__ */ jsxs6("div", { className: "session-brand", children: [
-            /* @__PURE__ */ jsx8(Logo, {}),
-            (shown?.mode ?? selectedMode ?? options.mode) === "pexels" && /* @__PURE__ */ jsx8("a", { className: "media-credit", href: "https://www.pexels.com", target: "_blank", rel: "noopener noreferrer", children: "Videos by Pexels" })
+        /* @__PURE__ */ jsxs7("header", { className: "chrome", ...controlEvents, children: [
+          /* @__PURE__ */ jsxs7("div", { className: "session-brand", children: [
+            /* @__PURE__ */ jsx8("a", { className: "home-link", href: "/", "aria-label": "Home", children: /* @__PURE__ */ jsx8(Logo, {}) }),
+            (shown?.mode ?? selectedMode ?? options.mode) === "pexels" && /* @__PURE__ */ jsx8("a", { className: "media-credit", href: "https://www.pexels.com", target: "_blank", rel: "noopener noreferrer", children: "Pexels" })
           ] }),
-          /* @__PURE__ */ jsxs6("div", { className: "group", children: [
-            /* @__PURE__ */ jsxs6(
+          /* @__PURE__ */ jsxs7("div", { className: "group", children: [
+            /* @__PURE__ */ jsxs7(
               "button",
               {
                 ref: historyButtonRef,
@@ -3601,9 +3619,9 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
             )
           ] })
         ] }),
-        /* @__PURE__ */ jsxs6("div", { className: "stage-area", children: [
-          /* @__PURE__ */ jsxs6("div", { className: "stage", style: { background: "#000" }, children: [
-            openingChapter && /* @__PURE__ */ jsx8(OpeningChapter, { title: openingTitle.length > 120 ? `${openingTitle.slice(0, 117).trimEnd()}\u2026` : openingTitle }, shown.id),
+        /* @__PURE__ */ jsxs7("div", { className: "stage-area", children: [
+          /* @__PURE__ */ jsxs7("div", { className: "stage", style: { background: "#000" }, children: [
+            openingChapter && /* @__PURE__ */ jsx8(OpeningChapter, { preparing: preparingKey === shown.id && !chat.speaking, title: openingTitle.length > 120 ? `${openingTitle.slice(0, 117).trimEnd()}\u2026` : openingTitle }, shown.id),
             !showing && chat.turns.length === 0 && /* @__PURE__ */ jsx8(Welcome, { data: chat.welcome, onAsk: ask, title: welcomeTitle }),
             chat.playerProps && /* @__PURE__ */ jsx8("div", { className: "player-fit", style: { width: stageOrientation === "portrait" ? "min(100cqw, 56.25cqh)" : "min(100cqw, 177.7778cqh)" }, children: /* @__PURE__ */ jsx8(
               VideoPlayer,
@@ -3617,29 +3635,29 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
               },
               chat.playerKey
             ) }),
-            showing && chat.playbackEnded && chat.suggestions.length > 0 && /* @__PURE__ */ jsxs6("div", { className: "ending", children: [
+            showing && chat.playbackEnded && chat.suggestions.length > 0 && /* @__PURE__ */ jsxs7("div", { className: "ending", children: [
               /* @__PURE__ */ jsx8("div", { className: "ending-wash", "aria-hidden": "true" }),
-              /* @__PURE__ */ jsxs6("div", { className: "ending-body", children: [
+              /* @__PURE__ */ jsxs7("div", { className: "ending-body", children: [
                 /* @__PURE__ */ jsx8("p", { className: "ending-label", children: "Ask next" }),
                 /* @__PURE__ */ jsx8(SuggestionCards, { suggestions: [...chat.suggestions], label: "Follow-up prompts", onAsk: ask })
               ] })
             ] })
           ] }),
-          historyOpen && /* @__PURE__ */ jsxs6("nav", { ref: historyRef, id: historyId, className: "sheet-popover history", role: "dialog", "aria-modal": "true", "aria-label": "Sessions", children: [
-            /* @__PURE__ */ jsxs6("div", { className: "popover-heading", children: [
+          historyOpen && /* @__PURE__ */ jsxs7("nav", { ref: historyRef, id: historyId, className: "sheet-popover history", role: "dialog", "aria-modal": "true", "aria-label": "Sessions", children: [
+            /* @__PURE__ */ jsxs7("div", { className: "popover-heading", children: [
               /* @__PURE__ */ jsx8("h2", { children: "Sessions" }),
               /* @__PURE__ */ jsx8("button", { type: "button", className: "round", "aria-label": "Close sessions", onClick: closeHistory, children: /* @__PURE__ */ jsx8(Close, {}) })
             ] }),
-            /* @__PURE__ */ jsxs6("button", { type: "button", className: "history-row session-new", "aria-label": "New session", onClick: newSession, children: [
+            /* @__PURE__ */ jsxs7("button", { type: "button", className: "history-row session-new", "aria-label": "New session", onClick: newSession, children: [
               /* @__PURE__ */ jsx8(Plus, {}),
-              /* @__PURE__ */ jsxs6("span", { className: "prompt", children: [
+              /* @__PURE__ */ jsxs7("span", { className: "prompt", children: [
                 "New session",
                 /* @__PURE__ */ jsx8("small", { children: "Start a fresh conversation" })
               ] })
             ] }),
             /* @__PURE__ */ jsx8("h3", { className: "section-label", children: "Current session" }),
             chat.turns.length === 0 && /* @__PURE__ */ jsx8("p", { className: "history-empty", children: "Your questions will appear here." }),
-            chat.turns.map((turn, index) => /* @__PURE__ */ jsxs6(
+            chat.turns.map((turn, index) => /* @__PURE__ */ jsxs7(
               "button",
               {
                 type: "button",
@@ -3656,7 +3674,7 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
                 },
                 children: [
                   /* @__PURE__ */ jsx8("span", { className: "index", children: String(index + 1).padStart(2, "0") }),
-                  /* @__PURE__ */ jsxs6("span", { className: "prompt", children: [
+                  /* @__PURE__ */ jsxs7("span", { className: "prompt", children: [
                     turn.prompt,
                     /* @__PURE__ */ jsx8("small", { children: turn.id === shown?.id ? "Now showing" : turn.completed ? "Play answer" : "Unfinished answer" })
                   ] })
@@ -3664,9 +3682,9 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
               },
               turn.id
             )),
-            savedSessions.length > 0 && /* @__PURE__ */ jsxs6(Fragment4, { children: [
+            savedSessions.length > 0 && /* @__PURE__ */ jsxs7(Fragment4, { children: [
               /* @__PURE__ */ jsx8("h3", { className: "section-label", children: "Earlier sessions" }),
-              savedSessions.map((session) => /* @__PURE__ */ jsxs6("button", { type: "button", className: "history-row", onClick: () => {
+              savedSessions.map((session) => /* @__PURE__ */ jsxs7("button", { type: "button", className: "history-row", onClick: () => {
                 listen.stop();
                 setDraft("");
                 setEditing(false);
@@ -3678,9 +3696,9 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
                 setCaptionsExpanded(false);
               }, children: [
                 /* @__PURE__ */ jsx8(Replay, {}),
-                /* @__PURE__ */ jsxs6("span", { className: "prompt", children: [
+                /* @__PURE__ */ jsxs7("span", { className: "prompt", children: [
                   session.turns[0]?.prompt,
-                  /* @__PURE__ */ jsxs6("small", { children: [
+                  /* @__PURE__ */ jsxs7("small", { children: [
                     session.turns.length,
                     " ",
                     session.turns.length === 1 ? "answer" : "answers"
@@ -3689,7 +3707,7 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
               ] }, session.id))
             ] })
           ] }),
-          settingsOpen && /* @__PURE__ */ jsxs6(
+          settingsOpen && /* @__PURE__ */ jsxs7(
             "div",
             {
               ref: settingsRef,
@@ -3699,14 +3717,14 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
               "aria-label": "Settings",
               "aria-modal": "true",
               children: [
-                /* @__PURE__ */ jsxs6("div", { className: "popover-heading", children: [
+                /* @__PURE__ */ jsxs7("div", { className: "popover-heading", children: [
                   /* @__PURE__ */ jsx8("h2", { children: "Settings" }),
                   /* @__PURE__ */ jsx8("button", { type: "button", className: "round", "aria-label": "Close settings", onClick: closeSettings, children: /* @__PURE__ */ jsx8(Close, {}) })
                 ] }),
-                /* @__PURE__ */ jsxs6("fieldset", { className: "playback-options", children: [
+                /* @__PURE__ */ jsxs7("fieldset", { className: "playback-options", children: [
                   /* @__PURE__ */ jsx8("legend", { children: "Video source" }),
-                  visualModes.filter((mode) => chat.availableModes.includes(mode.id)).map((mode) => /* @__PURE__ */ jsxs6("label", { className: "switch-row", children: [
-                    /* @__PURE__ */ jsxs6("span", { children: [
+                  visualModes.filter((mode) => chat.availableModes.includes(mode.id)).map((mode) => /* @__PURE__ */ jsxs7("label", { className: "switch-row", children: [
+                    /* @__PURE__ */ jsxs7("span", { children: [
                       /* @__PURE__ */ jsx8("strong", { children: mode.label }),
                       /* @__PURE__ */ jsx8("small", { children: mode.note })
                     ] }),
@@ -3722,10 +3740,10 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
                     )
                   ] }, mode.id))
                 ] }),
-                /* @__PURE__ */ jsxs6("fieldset", { className: "playback-options", children: [
+                /* @__PURE__ */ jsxs7("fieldset", { className: "playback-options", children: [
                   /* @__PURE__ */ jsx8("legend", { children: "Watching" }),
-                  /* @__PURE__ */ jsxs6("label", { className: "switch-row", children: [
-                    /* @__PURE__ */ jsxs6("span", { children: [
+                  /* @__PURE__ */ jsxs7("label", { className: "switch-row", children: [
+                    /* @__PURE__ */ jsxs7("span", { children: [
                       /* @__PURE__ */ jsx8("strong", { children: "Subtitles" }),
                       /* @__PURE__ */ jsx8("small", { children: "Read along with the answer" })
                     ] }),
@@ -3734,26 +3752,26 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
                       setCaptionsExpanded(false);
                     } })
                   ] }),
-                  /* @__PURE__ */ jsxs6("label", { className: "switch-row", children: [
-                    /* @__PURE__ */ jsxs6("span", { children: [
+                  /* @__PURE__ */ jsxs7("label", { className: "switch-row", children: [
+                    /* @__PURE__ */ jsxs7("span", { children: [
                       /* @__PURE__ */ jsx8("strong", { children: "Keep controls visible" }),
                       /* @__PURE__ */ jsx8("small", { children: "Keep the input bar on screen" })
                     ] }),
                     /* @__PURE__ */ jsx8("input", { type: "checkbox", role: "switch", checked: alwaysShowControls, onChange: (event) => setAlwaysShowControls(event.target.checked) })
                   ] })
                 ] }),
-                /* @__PURE__ */ jsxs6("nav", { className: "developer-links", "aria-label": "Build with VanillaSky", children: [
+                /* @__PURE__ */ jsxs7("nav", { className: "developer-links", "aria-label": "Build with VanillaSky", children: [
                   /* @__PURE__ */ jsx8("p", { className: "section-label", children: "Build with VanillaSky" }),
-                  /* @__PURE__ */ jsxs6("a", { href: "https://github.com/VanillaSkyAi/video/blob/main/docs/getting-started.md", target: "_blank", rel: "noopener noreferrer", children: [
+                  /* @__PURE__ */ jsxs7("a", { href: "https://github.com/VanillaSkyAi/video/blob/main/docs/getting-started.md", target: "_blank", rel: "noopener noreferrer", children: [
                     "Docs",
                     /* @__PURE__ */ jsx8("span", { "aria-hidden": "true", children: "\u2197" })
                   ] }),
-                  /* @__PURE__ */ jsxs6("button", { type: "button", "aria-expanded": aboutOpen, "aria-controls": `${instanceId}-about`, onClick: () => setAboutOpen((open) => !open), children: [
+                  /* @__PURE__ */ jsxs7("button", { type: "button", "aria-expanded": aboutOpen, "aria-controls": `${instanceId}-about`, onClick: () => setAboutOpen((open) => !open), children: [
                     "About",
                     /* @__PURE__ */ jsx8("span", { "aria-hidden": "true", children: aboutOpen ? "\u2212" : "+" })
                   ] }),
                   /* @__PURE__ */ jsx8("div", { id: `${instanceId}-about`, className: "developer-about", role: "region", "aria-label": "About VanillaSky", hidden: !aboutOpen, children: /* @__PURE__ */ jsx8("p", { children: "VanillaSky is an open-source SDK for conversations that answer in video. Developers connect their own AI providers through their application server." }) }),
-                  /* @__PURE__ */ jsxs6("a", { href: "https://github.com/VanillaSkyAi/video", target: "_blank", rel: "noopener noreferrer", children: [
+                  /* @__PURE__ */ jsxs7("a", { href: "https://github.com/VanillaSkyAi/video", target: "_blank", rel: "noopener noreferrer", children: [
                     "GitHub",
                     /* @__PURE__ */ jsx8("span", { "aria-hidden": "true", children: "\u2197" })
                   ] })
@@ -3762,8 +3780,8 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
             }
           )
         ] }),
-        /* @__PURE__ */ jsx8("div", { ref: panelRef, className: "panel", "data-input-visible": controls.visible || !captionsOn || !line, children: /* @__PURE__ */ jsxs6("div", { className: "panel-inner", children: [
-          /* @__PURE__ */ jsx8("div", { className: "caption-slot", "data-captions": captionsOn && Boolean(line), "aria-hidden": !captionsOn || !line, children: /* @__PURE__ */ jsx8("div", { className: "caption-clip", children: /* @__PURE__ */ jsxs6(
+        /* @__PURE__ */ jsx8("div", { ref: panelRef, className: "panel", "data-input-visible": controls.visible || !captionsOn || !line, children: /* @__PURE__ */ jsxs7("div", { className: "panel-inner", children: [
+          /* @__PURE__ */ jsx8("div", { className: "caption-slot", "data-captions": captionsOn && Boolean(line), "aria-hidden": !captionsOn || !line, children: /* @__PURE__ */ jsx8("div", { className: "caption-clip", children: /* @__PURE__ */ jsxs7(
             "div",
             {
               className: "line-row",
@@ -3776,8 +3794,8 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
               onFocusCapture: captionControls.onFocusCapture,
               onBlurCapture: captionControls.onBlurCapture,
               children: [
-                captionsOn && line && /* @__PURE__ */ jsxs6("div", { className: "caption-actions", children: [
-                  /* @__PURE__ */ jsxs6("button", { type: "button", className: "caption-action", "aria-label": captionsExpanded ? "Collapse subtitles" : "Expand subtitles", "aria-expanded": captionsExpanded, onClick: () => setCaptionsExpanded((open) => !open), children: [
+                captionsOn && line && /* @__PURE__ */ jsxs7("div", { className: "caption-actions", children: [
+                  /* @__PURE__ */ jsxs7("button", { type: "button", className: "caption-action", "aria-label": captionsExpanded ? "Collapse subtitles" : "Expand subtitles", "aria-expanded": captionsExpanded, onClick: () => setCaptionsExpanded((open) => !open), children: [
                     captionsExpanded ? "Collapse" : "Expand",
                     /* @__PURE__ */ jsx8(ChevronUp, {})
                   ] }),
@@ -3790,17 +3808,17 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
               ]
             }
           ) }) }),
-          showRecoveryNotice && chat.shownTurn && dismissedNoticeTurn !== chat.shownTurn.id && chat.warnings.includes(MEDIA_RECOVERY_NOTICE) && !chat.error && /* @__PURE__ */ jsxs6("div", { className: "recovery-notice", children: [
+          showRecoveryNotice && chat.shownTurn && dismissedNoticeTurn !== chat.shownTurn.id && chat.warnings.includes(MEDIA_RECOVERY_NOTICE) && !chat.error && /* @__PURE__ */ jsxs7("div", { className: "recovery-notice", children: [
             /* @__PURE__ */ jsx8("p", { role: "status", children: MEDIA_RECOVERY_NOTICE }),
             /* @__PURE__ */ jsx8("button", { type: "button", className: "round", "aria-label": "Dismiss notice", onClick: () => setDismissedNoticeTurn(chat.shownTurn?.id), children: /* @__PURE__ */ jsx8(Close, {}) })
           ] }),
-          (chat.error || listen.error) && /* @__PURE__ */ jsxs6("p", { className: "error", role: "status", children: [
+          (chat.error || listen.error) && /* @__PURE__ */ jsxs7("p", { className: "error", role: "status", children: [
             /* @__PURE__ */ jsx8(Warning, {}),
             /* @__PURE__ */ jsx8("span", { children: chat.error?.message ?? listen.error })
           ] }),
-          /* @__PURE__ */ jsxs6("div", { ref: composerRef, className: "conversation-composer", "data-editing": editing, ...controlEvents, children: [
+          /* @__PURE__ */ jsxs7("div", { ref: composerRef, className: "conversation-composer", "data-editing": editing, ...controlEvents, children: [
             (listen.listening || listen.thinking) && /* @__PURE__ */ jsx8("div", { className: "composer-meta", children: /* @__PURE__ */ jsx8("span", { role: "status", children: listen.listening ? "Listening\u2026 Tap the mic to finish, then review and send." : "Turning your words into a draft\u2026" }) }),
-            /* @__PURE__ */ jsxs6("form", { className: "composer", "aria-label": "Ask a question", onSubmit: (event) => {
+            /* @__PURE__ */ jsxs7("form", { className: "composer", "aria-label": "Ask a question", onSubmit: (event) => {
               event.preventDefault();
               ask(draft);
             }, children: [

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.18",
+  "version": "0.10.19",
   "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.19",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "@ai-sdk/anthropic": "^3.0.0",

package/starters/video-chat/stock.ts

@@ -53,19 +53,21 @@ 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: 4, 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();
+  url.search = new URLSearchParams({ query: normalized, 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;
+  let selected: StockVideo | null = null, 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\//, "");
@@ -88,12 +90,15 @@ export async function findStockFootage(query: string, orientation: VideoOrientat
     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));
+      && 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 || matches <= bestScore) continue;
+    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 } : {}) };
   }
   // Bounded process-local cache; no request signal or credentials are retained.

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) {
@@ -1079,31 +1069,58 @@
 @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; }