@vanillaskyai/video 0.10.20 → 0.10.22

package/CHANGELOG.md

@@ -4,6 +4,15 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.22
+
+- Offer eight diverse homepage prompts with curated footage, a balanced fresh-page shuffle, and stable ordering when returning Home.
+- Browse four cards on desktop and two on mobile, with only the active card loading video.
+
+## 0.10.21
+
+- Choose illustrated, realistic, or cinematic generated-video direction within the existing chat brief, with consistent treatment across shots and caller style overrides.
+
 ## 0.10.20
 
 - Collapse completed-response subtitles to an expandable transcript and remove the Pexels header link.

package/dist/{chunk-HKUI5BTB.js → chunk-44WND2VP.js}

@@ -8,6 +8,47 @@ import {
   VIDEO_PROTOCOL_VERSION
 } from "./chunk-7NZOMTAL.js";
 
+// src/video-chat/welcome-cards.ts
+var WELCOME_CARDS = [
+  { prompt: "Why do cats stare at us?", category: "curiosity", media: { "url": "https://videos.pexels.com/video-files/6131490/6131490-sd_640_360_25fps.mp4", "type": "video", "posterUrl": "https://images.pexels.com/videos/6131490/pictures/preview-0.jpg?auto=compress&fit=crop&w=640" } },
+  { prompt: "Tell me a joke about office life", category: "entertainment", media: { "url": "https://videos.pexels.com/video-files/7438239/7438239-sd_640_338_25fps.mp4", "type": "video", "posterUrl": "https://images.pexels.com/videos/7438239/pictures/preview-0.jpg?auto=compress&fit=crop&w=640" } },
+  { prompt: "Where would you take me in Japan?", category: "explore", media: { "url": "https://videos.pexels.com/video-files/35972506/15252635_360_640_30fps.mp4", "type": "video", "posterUrl": "https://images.pexels.com/videos/35972506/pictures/preview-0.jpg?auto=compress&fit=crop&w=640" } },
+  { prompt: "How do I make better coffee?", category: "practical", media: { "url": "https://videos.pexels.com/video-files/5564283/5564283-sd_640_360_24fps.mp4", "type": "video", "posterUrl": "https://images.pexels.com/videos/5564283/pictures/preview-0.jpg?auto=compress&fit=crop&w=640" } },
+  { prompt: "What would Earth look like without humans?", category: "explore", media: { "url": "https://videos.pexels.com/video-files/28732001/12464538_640_360_30fps.mp4", "type": "video", "posterUrl": "https://images.pexels.com/videos/28732001/pictures/preview-0.jpg?auto=compress&fit=crop&w=640" } },
+  { prompt: "Tell me a short story with a twist", category: "entertainment", media: { "url": "https://videos.pexels.com/video-files/5683159/5683159-sd_640_360_30fps.mp4", "type": "video", "posterUrl": "https://images.pexels.com/videos/5683159/pictures/preview-0.jpg?auto=compress&fit=crop&w=640" } },
+  { prompt: "Why does music give us goosebumps?", category: "curiosity", media: { "url": "https://videos.pexels.com/video-files/6870450/6870450-sd_640_360_30fps.mp4", "type": "video", "posterUrl": "https://images.pexels.com/videos/6870450/pictures/preview-0.jpg?auto=compress&fit=crop&w=640" } },
+  { prompt: "How can I make my room feel bigger?", category: "practical", media: { "url": "https://videos.pexels.com/video-files/37479012/15875787_360_640_30fps.mp4", "type": "video", "posterUrl": "https://images.pexels.com/videos/37479012/pictures/preview-0.jpg?auto=compress&fit=crop&w=640" } }
+];
+function orderWelcomeCards(cards, seed) {
+  if (cards.length !== WELCOME_CARDS.length || new Set(cards.map((card) => card.prompt)).size !== cards.length || cards.some((card) => !WELCOME_CARDS.some((entry) => entry.prompt === card.prompt))) return [...cards];
+  let state = seed >>> 0;
+  const random = () => {
+    state = Math.imul(state, 1664525) + 1013904223 >>> 0;
+    return state / 4294967296;
+  };
+  const shuffle = (values) => {
+    const copy = [...values];
+    for (let i = copy.length - 1; i > 0; i--) {
+      const j = Math.floor(random() * (i + 1));
+      [copy[i], copy[j]] = [copy[j], copy[i]];
+    }
+    return copy;
+  };
+  const groups = /* @__PURE__ */ new Map();
+  for (const card of shuffle(cards)) {
+    const category = WELCOME_CARDS.find((entry) => entry.prompt === card.prompt).category;
+    const group = groups.get(category) ?? [];
+    group.push(card);
+    groups.set(category, group);
+  }
+  const categories = shuffle([...groups.values()]);
+  return [...categories.map((group) => group[0]), ...shuffle(categories.flatMap((group) => group.slice(1)))];
+}
+var pageSeed;
+function welcomeVisitSeed() {
+  return pageSeed ??= Math.floor(Math.random() * 4294967296);
+}
+
 // src/video-chat/recovery.ts
 var MEDIA_RECOVERY_NOTICE = "Some visuals were replaced so your response can continue.";
 
@@ -160,6 +201,9 @@ function safeMediaUrl(value) {
 }
 
 export {
+  WELCOME_CARDS,
+  orderWelcomeCards,
+  welcomeVisitSeed,
   MEDIA_RECOVERY_NOTICE,
   encodeVideoSseEvent,
   decodeVideoSse,

package/dist/react.js

@@ -9,9 +9,11 @@ import {
 import {
   MEDIA_RECOVERY_NOTICE,
   decodeVideoSse,
+  orderWelcomeCards,
   sanitizeVideoChatMedia,
+  welcomeVisitSeed,
   withDeadline
-} from "./chunk-HKUI5BTB.js";
+} from "./chunk-44WND2VP.js";
 import {
   applyVideoEvent,
   checksumVideo,
@@ -2311,7 +2313,7 @@ function useVideoChatSession(options = {}) {
       if (!response.ok) throw await responseError(response);
       return response.json();
     }).then((value) => {
-      if (mountedRef.current) dispatch({ type: "welcome", value });
+      if (mountedRef.current) dispatch({ type: "welcome", value: { ...value, cards: orderWelcomeCards(value.cards, welcomeVisitSeed()) } });
     }).catch(() => void 0);
     return () => {
       endTiming();
@@ -3008,7 +3010,7 @@ function CaptionPages({ text, getProgress }) {
 }
 
 // src/video-chat/video-chat.tsx
-import { useCallback as useCallback6, useEffect as useEffect10, useId, useLayoutEffect as useLayoutEffect3, useMemo as useMemo3, useRef as useRef9, useState as useState8 } from "react";
+import { useCallback as useCallback5, useEffect as useEffect10, useId as useId2, useLayoutEffect as useLayoutEffect3, useMemo as useMemo3, useRef as useRef9, useState as useState8 } from "react";
 
 // src/video-chat/icons.tsx
 import { jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
@@ -3118,7 +3120,7 @@ function useFocusTrap(active, surface) {
 }
 
 // src/video-chat/suggestion-cards.tsx
-import { useCallback as useCallback3, useEffect as useEffect7, useRef as useRef5, useState as useState4 } from "react";
+import { useEffect as useEffect7, useId, useRef as useRef5, useState as useState4 } from "react";
 import { Fragment as Fragment2, jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
 function Frame({ media, poster, playing, onReady, onError, revealWhenReady = false }) {
   const video = useRef5(null);
@@ -3130,6 +3132,9 @@ function Frame({ media, poster, playing, onReady, onError, revealWhenReady = fal
     else element.pause();
   }, [playing]);
   if (!media) return null;
+  if (playing === false && media.type === "video" && media.posterUrl) {
+    return /* @__PURE__ */ jsx5("img", { className: "frame-media frame-poster", src: media.posterUrl, alt: "", onLoad: onReady, onError });
+  }
   const ready = () => {
     setPlayingUrl(media.url);
     onReady?.();
@@ -3161,37 +3166,38 @@ function Frame({ media, poster, playing, onReady, onError, revealWhenReady = fal
     poster && media.posterUrl && playingUrl !== media.url && /* @__PURE__ */ jsx5("img", { className: "frame-media frame-poster", src: media.posterUrl, alt: "", onLoad: onReady })
   ] });
 }
-function SuggestionCards({ suggestions, label, onAsk }) {
+function SuggestionCards({ suggestions, label, onAsk, browse = false }) {
   const railRef = useRef5(null);
+  const railId = useId();
   const [at, setAt] = useState4(0);
-  const [taken, setTaken] = useState4(false);
-  const take = useCallback3((index) => {
-    setTaken(true);
-    setAt(index);
-  }, []);
-  useEffect7(() => {
-    if (taken || suggestions.length < 2) return;
-    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return;
-    const tour = window.setInterval(() => setAt((index) => (index + 1) % suggestions.length), 5e3);
-    return () => window.clearInterval(tour);
-  }, [taken, suggestions.length]);
+  const [overflow, setOverflow] = useState4({ before: false, after: false });
   useEffect7(() => {
     const rail = railRef.current;
-    const card = rail?.children[at];
-    if (!rail || !card) return;
-    if (rail.scrollWidth <= rail.clientWidth + 4) return;
-    const centred = card.offsetLeft - (rail.clientWidth - card.offsetWidth) / 2;
-    rail.scrollTo({ left: Math.max(0, centred), behavior: "smooth" });
-  }, [at]);
+    if (!browse || !rail) return;
+    const update = () => setOverflow({ before: rail.scrollLeft > 2, after: rail.scrollLeft + rail.clientWidth < rail.scrollWidth - 2 });
+    update();
+    rail.addEventListener("scroll", update, { passive: true });
+    const observer = typeof ResizeObserver === "undefined" ? void 0 : new ResizeObserver(update);
+    observer?.observe(rail);
+    return () => {
+      rail.removeEventListener("scroll", update);
+      observer?.disconnect();
+    };
+  }, [browse, suggestions.length]);
+  const move = (direction) => {
+    const rail = railRef.current;
+    if (!rail) return;
+    rail.scrollBy({ left: direction * rail.clientWidth, behavior: window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth" });
+  };
   if (suggestions.length === 0) return null;
-  return /* @__PURE__ */ jsxs4(Fragment2, { children: [
-    /* @__PURE__ */ jsx5("ul", { className: "cards", ref: railRef, "aria-label": label, children: suggestions.map((card, index) => /* @__PURE__ */ jsx5("li", { children: /* @__PURE__ */ jsxs4(
+  const cards = /* @__PURE__ */ jsxs4(Fragment2, { children: [
+    /* @__PURE__ */ jsx5("ul", { className: "cards", id: railId, ref: railRef, "aria-label": label, children: suggestions.map((card, index) => /* @__PURE__ */ jsx5("li", { children: /* @__PURE__ */ jsxs4(
       "button",
       {
         type: "button",
         "data-active": index === at ? "" : void 0,
-        onFocus: () => take(index),
-        onPointerEnter: () => take(index),
+        onFocus: () => setAt(index),
+        onPointerEnter: () => setAt(index),
         onClick: () => onAsk(card),
         children: [
           /* @__PURE__ */ jsx5(Frame, { media: card.media, poster: true, playing: index === at }),
@@ -3207,11 +3213,23 @@ function SuggestionCards({ suggestions, label, onAsk }) {
         "aria-pressed": index === at,
         "aria-label": `Show suggestion ${index + 1}: ${card.prompt}`,
         className: index === at ? "on" : void 0,
-        onClick: () => take(index)
+        onClick: () => {
+          setAt(index);
+          const rail = railRef.current;
+          const card2 = rail?.children[index];
+          if (rail && card2) rail.scrollTo({ left: card2.offsetLeft, behavior: "smooth" });
+        }
       },
       card.prompt
     )) })
   ] });
+  return browse ? /* @__PURE__ */ jsxs4("div", { className: "suggestion-rail", children: [
+    cards,
+    (overflow.before || overflow.after) && /* @__PURE__ */ jsxs4("div", { className: "rail-arrows", children: [
+      /* @__PURE__ */ jsx5("button", { type: "button", "aria-label": "Previous suggestions", "aria-controls": railId, disabled: !overflow.before, onClick: () => move(-1), children: "\u2039" }),
+      /* @__PURE__ */ jsx5("button", { type: "button", "aria-label": "Next suggestions", "aria-controls": railId, disabled: !overflow.after, onClick: () => move(1), children: "\u203A" })
+    ] })
+  ] }) : cards;
 }
 
 // src/video-chat/welcome.tsx
@@ -3226,7 +3244,7 @@ function Welcome({ data, onAsk, title }) {
         /* @__PURE__ */ jsx6("br", {}),
         /* @__PURE__ */ jsx6("em", { children: "in video, not text." })
       ] }) }),
-      /* @__PURE__ */ jsx6(SuggestionCards, { suggestions: data?.cards ?? [], label: "Suggested prompts", onAsk })
+      /* @__PURE__ */ jsx6(SuggestionCards, { browse: true, suggestions: data?.cards ?? [], label: "Suggested prompts", onAsk })
     ] })
   ] });
 }
@@ -3276,7 +3294,7 @@ function OpeningChapter({ title, preparing = false }) {
 }
 
 // src/video-chat/use-voice-input.ts
-import { useCallback as useCallback4, useEffect as useEffect8, useRef as useRef7, useState as useState6 } from "react";
+import { useCallback as useCallback3, useEffect as useEffect8, useRef as useRef7, useState as useState6 } from "react";
 function recognitionConstructor() {
   if (typeof window === "undefined") return void 0;
   const holder = window;
@@ -3358,7 +3376,7 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
   useEffect8(() => {
     setSupported(supportsVoiceInput(transcriptionAvailable));
   }, [transcriptionAvailable]);
-  const stop = useCallback4(() => {
+  const stop = useCallback3(() => {
     recognitionRef.current?.abort();
     recognitionRef.current = void 0;
     const operation = operationRef.current;
@@ -3376,7 +3394,7 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
     operation?.controller.abort();
     operation?.finish?.();
   }, []);
-  const finish = useCallback4(() => {
+  const finish = useCallback3(() => {
     const recognition = recognitionRef.current;
     if (recognition) {
       recognition.stop();
@@ -3390,7 +3408,7 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
     }
     stop();
   }, [stop]);
-  const record = useCallback4(async () => {
+  const record = useCallback3(async () => {
     if (!transcriptionAvailable || !recorderAvailable()) {
       setError("Server transcription is not configured.");
       return;
@@ -3428,7 +3446,7 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
       }
     }
   }, [transcriptionAvailable, options.endpoint, options.headers, options.credentials, options.fetcher]);
-  const toggle = useCallback4(() => {
+  const toggle = useCallback3(() => {
     if (listening) {
       finish();
       return;
@@ -3480,18 +3498,18 @@ function useVoiceInput(onTranscript, transcriptionAvailable = false, options = {
 }
 
 // src/video-chat/use-immersive-controls.ts
-import { useCallback as useCallback5, useEffect as useEffect9, useRef as useRef8, useState as useState7 } from "react";
+import { useCallback as useCallback4, useEffect as useEffect9, useRef as useRef8, useState as useState7 } from "react";
 function useImmersiveControls(playing, pinned, hasCaptions = false) {
   const [visible, setVisible] = useState7(true);
   const hovered = useRef8(false);
   const focused = useRef8(false);
   const previousCaptions = useRef8(false);
   const timer = useRef8(null);
-  const clearTimer = useCallback5(() => {
+  const clearTimer = useCallback4(() => {
     if (timer.current !== null) clearTimeout(timer.current);
     timer.current = null;
   }, []);
-  const reveal = useCallback5(() => {
+  const reveal = useCallback4(() => {
     clearTimer();
     setVisible(true);
     if (playing && !pinned && !hovered.current && !focused.current) {
@@ -3513,21 +3531,21 @@ function useImmersiveControls(playing, pinned, hasCaptions = false) {
     }
     return clearTimer;
   }, [hasCaptions, playing, pinned, reveal, clearTimer]);
-  const onPointerEnter = useCallback5((event) => {
+  const onPointerEnter = useCallback4((event) => {
     if (event?.pointerType === "touch") return;
     hovered.current = true;
     reveal();
   }, [reveal]);
-  const onPointerLeave = useCallback5(() => {
+  const onPointerLeave = useCallback4(() => {
     if (!hovered.current) return;
     hovered.current = false;
     reveal();
   }, [reveal]);
-  const onFocusCapture = useCallback5((event) => {
+  const onFocusCapture = useCallback4((event) => {
     focused.current = event.target.matches(":focus-visible");
     reveal();
   }, [reveal]);
-  const onBlurCapture = useCallback5((event) => {
+  const onBlurCapture = useCallback4((event) => {
     if (focused.current && !event.currentTarget.contains(event.relatedTarget)) {
       focused.current = false;
       reveal();
@@ -3601,7 +3619,7 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
     if (turn.id !== chat.shownTurn?.id) return;
     if (previous?.id !== turn.id || previous.mode !== turn.mode) setSelectedMode(turn.mode);
   }, [chat.currentTurn, chat.shownTurn?.id]);
-  const instanceId = useId();
+  const instanceId = useId2();
   const historyId = `${instanceId}-history`;
   const settingsId = `${instanceId}-settings`;
   const promptId = `${instanceId}-prompt`;
@@ -3618,13 +3636,13 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
   });
   const historySurfaces = useMemo3(() => [historyRef, historyButtonRef], []);
   const settingsSurfaces = useMemo3(() => [settingsRef, settingsButtonRef], []);
-  const closeHistory = useCallback6(() => setHistoryOpen(false), []);
-  const closeSettings = useCallback6(() => setSettingsOpen(false), []);
+  const closeHistory = useCallback5(() => setHistoryOpen(false), []);
+  const closeSettings = useCallback5(() => setSettingsOpen(false), []);
   useDismiss(historyOpen, closeHistory, historySurfaces);
   useDismiss(settingsOpen, closeSettings, settingsSurfaces);
   useFocusTrap(settingsOpen, settingsRef);
   useFocusTrap(historyOpen, historyRef);
-  const ask = useCallback6((value) => {
+  const ask = useCallback5((value) => {
     const prompt = (typeof value === "string" ? value : value.prompt).trim();
     if (!prompt) return;
     setDraft("");
@@ -3639,7 +3657,7 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
       opening: value.opening
     });
   }, [chat, listen]);
-  const newSession = useCallback6(() => {
+  const newSession = useCallback5(() => {
     if (chat.turns.length === 0) {
       setHistoryOpen(false);
       setSettingsOpen(false);
@@ -3712,7 +3730,7 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
   const line = chat.caption ?? "";
   const fullTranscript = shown?.video ? [shown.opening, ...shown.video.scenes.map((scene) => scene.narration)].filter((entry) => Boolean(entry)) : chat.transcript;
   const transport = status === "narrating" ? { label: "Pause", action: chat.pause, icon: /* @__PURE__ */ jsx9(Stop, {}) } : status === "paused" ? { label: "Continue", action: chat.resume, icon: /* @__PURE__ */ jsx9(Play, {}) } : status === "ended" && shown?.completed && shown.video ? { label: "Play again", action: chat.replay, icon: /* @__PURE__ */ jsx9(Replay, {}) } : void 0;
-  const cancelInput = useCallback6(() => {
+  const cancelInput = useCallback5(() => {
     listen.stop();
     setDraft("");
     setEditing(false);
@@ -3765,7 +3783,11 @@ function VideoChat({ options = {}, className, welcomeTitle, showRecoveryNotice =
       onKeyDownCapture: controls.reveal,
       children: [
         /* @__PURE__ */ jsxs7("header", { className: "chrome", ...controlEvents, children: [
-          /* @__PURE__ */ jsx9("div", { className: "session-brand", children: /* @__PURE__ */ jsx9("a", { className: "home-link", href: "/", "aria-label": "Home", children: /* @__PURE__ */ jsx9(Logo, {}) }) }),
+          /* @__PURE__ */ jsx9("div", { className: "session-brand", children: /* @__PURE__ */ jsx9("a", { className: "home-link", href: "/", "aria-label": "Home", onClick: (event) => {
+            if (window.location.pathname !== "/" || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+            event.preventDefault();
+            newSession();
+          }, children: /* @__PURE__ */ jsx9(Logo, {}) }) }),
           /* @__PURE__ */ jsxs7("div", { className: "group", children: [
             /* @__PURE__ */ jsxs7(
               "button",

package/dist/server.js

@@ -20,12 +20,13 @@ import {
 } from "./chunk-IQMYK5DX.js";
 import {
   MEDIA_RECOVERY_NOTICE,
+  WELCOME_CARDS,
   decodeVideoSse,
   encodeVideoSseEvent,
   sanitizeVideoChatMedia,
   videoSseHeaders,
   withDeadline
-} from "./chunk-HKUI5BTB.js";
+} from "./chunk-44WND2VP.js";
 import "./chunk-RXTN2CW6.js";
 import {
   allowedKeys,
@@ -873,6 +874,27 @@ function createVideoHandler(options) {
   });
 }
 
+// src/server/chat-visual-direction.ts
+var defaults = {
+  explanation: "illustrated",
+  practical: "realistic",
+  story: "cinematic",
+  comedy: "cinematic",
+  imagination: "cinematic"
+};
+var bibles = {
+  illustrated: "Illustrated visual language: clear shaped forms, restrained texture and a coherent limited palette. Use readable spatial relationships, cutaways and purposeful motion to reveal the idea. Keep the same design of subjects and materials across shots.",
+  realistic: "Realistic visual language: natural light, credible materials, consistent colour and true physical proportions. Use unobstructed framing and meaningful close views so actions and results are easy to observe. Keep subjects, equipment and setting consistent.",
+  cinematic: "Cinematic visual language: intentional lighting, coherent colour and tactile detail. Use purposeful changes of shot scale and viewpoint, with clear action, consequence and a readable final frame. Preserve character appearance and the established world across cuts."
+};
+function compileVisualDirection(brief, callerLook) {
+  const intent = typeof brief.intent === "string" && Object.hasOwn(defaults, brief.intent) ? brief.intent : "explanation";
+  const visualStyle = typeof brief.visualStyle === "string" && Object.hasOwn(bibles, brief.visualStyle) ? brief.visualStyle : defaults[intent];
+  const visualDirection = typeof brief.visualDirection === "string" && brief.visualDirection.trim().length <= 600 ? brief.visualDirection.trim() : "";
+  const explicit = typeof callerLook === "string" && callerLook.trim().length <= 1e3 ? callerLook.trim() : "";
+  return { intent, visualStyle, visualDirection, generatedLook: explicit || bibles[visualStyle] };
+}
+
 // src/server/opening-continuity.ts
 function continueAfterOpening(narration, earlier) {
   const words = (value) => Array.from(value.matchAll(/[\p{L}\p{N}]+(?:['’][\p{L}\p{N}]+)*/gu));
@@ -960,6 +982,7 @@ function recoverFirstBrief(part, clipDurationSec) {
   if (!ending || !bounded(ending.narration, 2e3) || !bounded(ending.subject, 80, true) || !bounded(ending.action, 600, true) || Object.hasOwn(ending, "title") && !bounded(ending.title, 65) || typeof ending.durationSec !== "number" || !Number.isFinite(ending.durationSec) || ending.continuity !== "cut" && ending.continuity !== "continue") return;
   const subject = text(part.subject, 80);
   return {
+    ...compileVisualDirection(part),
     opening: text(part.opening, 300),
     subject,
     development: text(part.development, 2e3),
@@ -978,12 +1001,14 @@ function replaceStream(source, textStream) {
 function createChatShotPlanner(options) {
   const clipDurationSec = options.generatedClipDurationSec ?? 5;
   const incomplete = /* @__PURE__ */ new WeakSet();
+  const generatedLooks = /* @__PURE__ */ new WeakMap();
   const planner = createTextDeltaVideoPlanner({
     includeRawProviderData: options.includeRawProviderData,
     streamText(context) {
       const providerContext = { ...context, userPrompt: [
         `Create a complete answer within ${context.request.input.maxDurationSec ?? 40} seconds. Each generated clip has at most ${clipDurationSec} seconds; give each spoken beat room to finish.`,
         `Orientation: ${context.request.input.orientation ?? "landscape"}.`,
+        ...context.request.input.style?.generatedLook ? [`CALLER VISUAL DIRECTION (takes precedence over automatic style): ${context.request.input.style.generatedLook}`, "Preserve this requested visual language. The brief visualDirection must contain compatible subjects, setting and palette, never a contradictory rendering style."] : [],
         "USER REQUEST AND CONVERSATION",
         context.request.input.input
       ].join("\n") };
@@ -1005,6 +1030,10 @@ function createChatShotPlanner(options) {
           const error = cause instanceof Error ? cause : new Error(String(cause));
           if (!getGenerationLifecycleSink(context)?.rejectPart?.(error)) throw error;
         };
+        const acceptDirection = (value) => {
+          const direction = compileVisualDirection(value, context.request.input.style?.generatedLook);
+          generatedLooks.set(context, direction.generatedLook);
+        };
         const scenePart = (shot, closer = false) => {
           let narration = shot.narration;
           if (firstBody && !closer) narration = continueAfterOpening(narration, [options.openingLine ?? brief?.opening ?? ""]);
@@ -1032,12 +1061,14 @@ function createChatShotPlanner(options) {
           const recovered = firstRecord && !brief && index === 0 ? recoverFirstBrief(part, clipDurationSec) : void 0;
           if (recovered) {
             brief = recovered;
+            acceptDirection(brief);
             options.publishOpening({ line: brief.opening, keyword: brief.subject });
             return;
           }
           if (part?.type === "answer") {
             if (brief) throw new Error("Chat answer brief was emitted more than once");
-            brief = { opening: text(part.opening, 300), subject: text(part.subject, 80), visualDirection: text(part.visualDirection, 600), development: text(part.development, 2e3) };
+            brief = { ...compileVisualDirection(part), opening: text(part.opening, 300), subject: text(part.subject, 80), visualDirection: text(part.visualDirection, 600), development: text(part.development, 2e3) };
+            acceptDirection(brief);
             if (part.ending) {
               try {
                 brief.ending = readShot(part.ending, clipDurationSec, brief.subject);
@@ -1144,7 +1175,7 @@ function createChatShotPlanner(options) {
   });
   return async function* (context) {
     let completed = false;
-    for await (const part of resolveShots(planner(context), context, options)) {
+    for await (const part of resolveShots(planner(context), context, options, () => options.mode === "pexels" ? context.request.input.style?.generatedLook : generatedLooks.get(context))) {
       if (part.type === "plan.complete") completed = true;
       yield part;
     }
@@ -1154,7 +1185,7 @@ function createChatShotPlanner(options) {
     }
   };
 }
-async function* resolveShots(parts, context, options) {
+async function* resolveShots(parts, context, options, generatedLook) {
   const queue = [];
   const iterator = parts[Symbol.asyncIterator]();
   const limit = Number.isFinite(options.mediaConcurrency) ? Math.min(5, Math.max(1, Math.floor(options.mediaConcurrency))) : 1;
@@ -1171,7 +1202,7 @@ async function* resolveShots(parts, context, options) {
       scene: part.scene,
       templateId: "cinemaMedia",
       preferredType: "video",
-      generatedLook: context.request.input.style?.generatedLook,
+      generatedLook: generatedLook() ?? context.request.input.style?.generatedLook,
       signal: context.signal
     });
     context.signal.throwIfAborted();
@@ -1229,7 +1260,7 @@ function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlr
   return [
     'Use the exact record type "answer" for the first brief and "shot" for developing beats. Output JSON records only, with no prose outside them, including when explaining a limitation.',
     "Write a complete, intentful video answer as newline-delimited JSON. Match the user's form and tone; mixed intents can combine directions.",
-    `First write one brief: {"type":"answer","intent":"explanation|story|comedy|imagination|practical","opening":"one useful spoken line of 4\u20137 ordinary words","subject":"literal visual subject","development":"the essential development of this answer","visualDirection":"consistent subjects, appearance and visual approach","ending":{"title":"short meaningful chapter title, at most 65 characters","narration":"the authored payoff","subject":"literal subject","action":"visible action or change","durationSec":${clipDurationSec},"continuity":"cut|continue"}}.`,
+    `First write one brief: {"type":"answer","intent":"explanation|story|comedy|imagination|practical","visualStyle":"illustrated|realistic|cinematic","opening":"one useful spoken line of 4\u20137 ordinary words","subject":"literal visual subject","development":"the essential development of this answer","visualDirection":"consistent subjects, appearance and visual approach","ending":{"title":"short meaningful chapter title, at most 65 characters","narration":"the authored payoff","subject":"literal subject","action":"visible action or change","durationSec":${clipDurationSec},"continuity":"cut|continue"}}.`,
     "The opening should take roughly 2\u20133 seconds at a natural pace: give the core answer, a useful starting cue, or the story's immediate situation. No greeting, topic announcement, promise to explain, or description of loading. Never compress away an essential qualifier just to hit the word target.",
     `Then stream each developing shot on its own line: {"type":"shot","title":"short meaningful chapter title, at most 65 characters","narration":"the exact spoken beat","subject":"2\u20138 literal filmable words, at most 80 characters","action":"concrete subject, action or visible change and useful framing","durationSec":${clipDurationSec},"continuity":"cut|continue"}.`,
     `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.`,
@@ -1237,6 +1268,8 @@ function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlr
     ...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.'] : [],
+    "Choose one of the five intents and one visualStyle in the first brief. Default explanation to illustrated, practical to realistic, and story, comedy or imagination to cinematic. An explicit visual-style request can choose any of the three. Put its specific medium, palette, character appearance and setting in visualDirection; keep those details consistent through the ending. A supplied caller visual direction takes precedence over these defaults and must not be contradicted.",
+    "The visualStyle names describe generated footage only. Stock mode selects existing literal footage; it cannot redraw or restyle that footage.",
     "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.",
     "The brief's ending is saved and played after your developing shots. Do not repeat it as a shot. Stop writing after the last developing shot. No technical events, identifiers, template choices, media providers, URLs or unlisted fields.",
@@ -1296,28 +1329,6 @@ var MAX_PROMPT_CHARACTERS = 8e3;
 var MAX_CONVERSATION_TURNS = 12;
 var MAX_CONVERSATION_RESPONSE_CHARACTERS = 8e3;
 var VIDEO_CHAT_OPENING_EVENT_TYPE = "data.video-chat-opening";
-var DEFAULT_WELCOME_PROMPTS = [
-  {
-    prompt: "Why does the Moon always show one face?",
-    opening: "The Moon turns, perfectly matching its orbit.",
-    mediaQuery: "full moon night sky"
-  },
-  {
-    prompt: "Tell me a tiny story about a robot growing a garden on Mars",
-    opening: "One patient robot is about to make Mars bloom.",
-    mediaQuery: "robot garden mars"
-  },
-  {
-    prompt: "Recommend a perfect rainy afternoon in Amsterdam",
-    opening: "Rain makes Amsterdam's best afternoons feel even warmer.",
-    mediaQuery: "Amsterdam rain cafe"
-  },
-  {
-    prompt: "Pitch a playful ad for a coffee mug that never spills",
-    opening: "This mug makes gravity look completely optional.",
-    mediaQuery: "coffee mug desk"
-  }
-];
 function jsonError2(status, code, message, headers) {
   return Response.json({ error: { code, message } }, { status, headers });
 }
@@ -1626,7 +1637,7 @@ function createVideoChatHandler(options) {
     transcription: transcribe != null,
     modes: searchMedia ? ["cinematic", "pexels"] : ["cinematic"]
   };
-  const welcomePrompts = (welcomeOptions?.prompts ?? DEFAULT_WELCOME_PROMPTS).slice(0, 4);
+  const welcomePrompts = (welcomeOptions?.prompts ?? WELCOME_CARDS).slice(0, 8);
   const heroQuery = welcomeOptions?.heroQuery;
   let welcomeResponse;
   let requestSequence = 0;
@@ -1828,7 +1839,7 @@ function createVideoChatHandler(options) {
         };
         const [hero, ...cards] = await Promise.all([
           heroQuery === void 0 ? DEFAULT_WELCOME_HERO : resolve(heroQuery),
-          ...welcomePrompts.map((entry) => resolve(entry.mediaQuery))
+          ...welcomePrompts.map((entry, index) => welcomeOptions?.prompts === void 0 ? WELCOME_CARDS[index]?.media ?? null : resolve("mediaQuery" in entry ? entry.mediaQuery : void 0))
         ]);
         return {
           cacheable: !failed,

package/docs/media-and-audio.md

@@ -19,8 +19,8 @@ The chapter retains narration and subtitles for the whole beat.
 
 The starter performs bounded full-catalog Pexels video search with subject
 matching, orientation-aware renditions and a bounded cache. Add `PEXELS_API_KEY`
-on the server and choose Pexels in Settings. The SDK UI links to Pexels; custom
-interfaces must also display the attribution required by their media provider.
+on the server and choose Pexels in Settings. The default header has no Pexels
+link; the application owns any attribution required by its media provider.
 
 Applications can replace `searchMedia` with their own licensed catalog:
 
@@ -50,9 +50,43 @@ default chat displays an authored chapter while retaining the spoken answer. An
 validation, and fallback contracts.
 
 For Pexels, keep `PEXELS_API_KEY` on the server, enforce a deadline, filter for
-orientation, and return only validated Pexels asset domains. Licensing,
+suitable renditions, and return only validated Pexels asset domains. Licensing,
 attribution, caching, MIME checks, and byte limits remain application-owned.
 
+## Automatic visual direction
+
+Default chat uses the existing answer brief to choose the requested form:
+explanation (including comparisons), practical instruction, story, comedy, or
+imagination. These shape the content and pacing; they do not change knowledge
+rules or provider allowances.
+
+The same brief selects one of three generated-video treatments:
+
+- **Illustrated:** clear drawn forms, consistent materials and a restrained palette;
+  the default for explanations.
+- **Realistic:** believable lighting, proportions and movement with useful framing;
+  the default for practical instruction.
+- **Cinematic:** deliberate composition, lighting and motivated camera movement;
+  the default for stories, comedy and imagined worlds.
+
+An explicit style request in the prompt takes priority over the default. The
+planner carries its response-specific subjects, palette and setting in the
+brief's visual direction. Every body shot and ending receives the same selected
+base treatment through `generatedLook`, alongside its individual `shotDirection`.
+Adapters must pass both to their video provider. An explicit
+`style.generatedLook` replaces the automatic base treatment.
+
+There is no separate classification call or image-generation stage. Selecting a
+look does not guarantee that independently generated clips preserve character
+identity. Evaluate actual footage for subject consistency, useful action,
+narration fit and completion; mocked responses only verify the integration.
+
+Pexels retains literal footage queries; these instructions cannot restyle stock
+assets. The opening chapter keeps its existing appearance. Automatic direction
+is generation-time guidance, not a new persisted style field; saved media keeps
+its rendered appearance and existing caller-supplied style persistence is
+unchanged. Custom template planning keeps its existing behavior.
+
 ## Generated shots
 
 Add `generateVideo` to enable generated shots within cinematic responses. It receives the planned visual

package/package.json

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

package/styles/video-chat.css

@@ -1127,3 +1127,17 @@
 .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; }
+
+/* Welcome shows a deliberate four-card window; the rest stays in the rail. */
+.vanillasky-video-chat .suggestion-rail { position: relative; flex-shrink: 0; width: calc(4 * clamp(160px, 18vw, 260px) + 66px); max-width: calc(100% + 24px); margin: auto -12px 0; }
+.vanillasky-video-chat .suggestion-rail .cards { width: 100%; max-width: 100%; margin: 0; }
+.vanillasky-video-chat .rail-arrows { position: absolute; inset: 50% -6px auto; display: flex; justify-content: space-between; transform: translateY(-50%); pointer-events: none; }
+.vanillasky-video-chat .rail-arrows button { width: 36px; height: 36px; border: 1px solid rgb(255 255 255 / 30%); border-radius: 50%; background: #202438; color: white; font: inherit; font-size: 25px; line-height: 1; cursor: pointer; pointer-events: auto; }
+.vanillasky-video-chat .rail-arrows button:disabled { visibility: hidden; pointer-events: none; }
+.vanillasky-video-chat .rail-arrows button:focus-visible { outline: 2px solid white; outline-offset: 3px; }
+@media (max-width: 700px) {
+  .vanillasky-video-chat .suggestion-rail { width: calc(100% + 40px); max-width: calc(100% + 40px); margin-inline: -20px; }
+  .vanillasky-video-chat .rail-arrows { display: none; }
+}
+
+@media (hover: none) { .vanillasky-video-chat .rail-arrows { display: none; } }