@vanillaskyai/video 0.10.21 → 0.10.23

package/CHANGELOG.md

@@ -4,6 +4,23 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.23
+
+- Stop shipping the maintainer-only cinematic migration note in the published
+  package. The changelog now links it on GitHub.
+- Remove the unreferenced text-rendering and emoji modules from the source tree.
+  The bundle is unchanged; this code was already excluded from it.
+- Correct the repository map in the architecture guide, and drop the stale
+  comments that described a text component the templates no longer use. Those
+  comments also shipped inside the installable `theme` registry item.
+- Remove the CLI redirect for template command names that were renamed before
+  the package had users. Use `vanillasky templates <command>`.
+
+## 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.
@@ -170,7 +187,7 @@ Before:
 
 ### Adoption
 
-Remove brand options and regenerate source-owned templates from the new catalog. Re-author or regenerate saved videos from retained source material; do not rename old IDs or change their version field blindly. See [cinematic migration](docs/maintainers/cinematic-migration.md).
+Remove brand options and regenerate source-owned templates from the new catalog. Re-author or regenerate saved videos from retained source material; do not rename old IDs or change their version field blindly. See [cinematic migration](https://github.com/VanillaSkyAi/video/blob/main/docs/maintainers/cinematic-migration.md).
 
 ```tsx
 <VideoChat options={{ endpoint: "/api/video-chat" }} />

package/README.md

@@ -1,5 +1,10 @@
 # Give your AI a voice and a face
 
+[![CI](https://github.com/VanillaSkyAi/video/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/VanillaSkyAi/video/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@vanillaskyai/video.svg)](https://www.npmjs.com/package/@vanillaskyai/video)
+[![runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](package.json)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
 **VanillaSky is the open-source voice-and-video chat layer.** Add a polished,
 general-purpose AI conversation that speaks and starts playing visual answers
 while they are still being composed.

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/cli.js

@@ -1994,11 +1994,6 @@ function runVanillaSkyCli(argv, environment = {}) {
     return result.ok ? 0 : 1;
   }
   if (rootCommand !== "templates") {
-    const removed = /* @__PURE__ */ new Set(["list", "describe", "add", "sync", "check", "create"]);
-    if (rootCommand && removed.has(rootCommand)) {
-      write(`Template commands moved. Use: vanillasky templates ${argv.join(" ")}`);
-      return 1;
-    }
     write(help());
     return rootCommand == null || rootCommand === "help" || rootCommand === "--help" || rootCommand === "-h" ? 0 : 1;
   }

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,
@@ -1328,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 });
 }
@@ -1658,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;
@@ -1860,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/architecture.md

@@ -19,6 +19,26 @@ own your product policy. It supplies the complete default chat, video-planning
 prompts, trusted visual vocabulary, conversation and narration lifecycle,
 validation, streaming, and player.
 
+## Start here
+
+Six files, in this order, are enough to hold the whole system in your head.
+About 2,600 lines total, and two of them are most of it.
+
+1. `src/protocol/types.ts` — the `Video` shape. Everything else exists to
+   produce, validate, transport, or play this one object.
+2. `src/server/prompts/system-prompt.ts` — what the model is actually asked
+   for. The product's behavior is mostly here, not in the code around it.
+3. `src/server/create-video-chat-handler.ts` — the one endpoint. Where an
+   application's providers and policy attach.
+4. `src/protocol/events.ts` — the wire contract between server and browser.
+5. `src/video-chat/use-video-chat.ts` — the client lifecycle, as a reducer.
+   Read `reducer` first and the hook second.
+6. `src/visual-system/scene-templates/quote.tsx` — one complete scene, small
+   enough to read in a sitting. Every other template has this shape.
+
+To watch it run instead, `npm run dev:chat` renders the real `VideoChat` from
+source against fixtures, with no provider credentials and no spend.
+
 ## Repository map
 
 | Location | Purpose |
@@ -32,19 +52,20 @@ validation, streaming, and player.
 | `src/video-chat/` | Default `VideoChat` interface and headless conversation/session engine |
 | `src/visual-system/catalog/` | Template metadata, schemas, loading, and planner catalog |
 | `src/visual-system/scene-templates/` | Complete scenes the model may select |
-| `src/visual-system/primitives/` | Reusable visual components used inside scenes |
 | `src/visual-system/backgrounds/` | Standalone background renderers |
 | `src/visual-system/motion/` | Animation functions and timing behavior |
 | `src/visual-system/theme/` | Color and design tokens |
+| `src/visual-system/typography/` | Text fitting, formatting, and kinetic type lifecycles |
 | `src/cli/` | `vanillasky init`, `doctor`, and `providers add`, plus `vanillasky templates create`, `add`, `sync`, `check`, `list`, and `describe` |
 | `registry/items/` | Generated distributable copies installed into customer projects |
 | `src/index.ts`, `src/server.ts`, `src/react.ts`, `src/templates.ts`, `src/template-catalog.ts`, `src/test.ts`, `styles/video-chat.css` | The six small code entry points and one scoped stylesheet |
 
 The source of truth for built-in visuals is `src/visual-system`. The JSON files
 in `registry/items` are distribution artifacts, kept flat so the CLI can address
-every installable item by a stable name. Their `meta.vanillasky.layer` and
-`category` fields distinguish full templates, primitives, effects, and shared
-support code. Run `npm run registry:sync` after changing canonical visual source.
+every installable item by a stable name. Their `meta.vanillasky.layer` field is
+`template` for a complete scene the model may select, or `lib` for shared
+support code a template imports. Run `npm run registry:sync` after changing
+canonical visual source.
 
 Customer applications do not edit those internal locations. Their source of
 truth is one file per visual under `vanillasky/templates/`; `vanillasky templates sync`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.21",
+  "version": "0.10.23",
   "description": "Open-source voice-and-video chat SDK for AI applications.",
   "keywords": [
     "video-chat",
@@ -56,8 +56,7 @@
     "docs/reference/protocol.md",
     "CHANGELOG.md",
     "docs/*.md",
-    "docs/reference",
-    "docs/maintainers/cinematic-migration.md"
+    "docs/reference"
   ],
   "bin": {
     "vanillasky": "bin/vanillasky.js"

package/registry/items/theme.json

@@ -24,7 +24,7 @@
       "path": "src/visual-system/scene-templates/tokens.ts",
       "type": "registry:lib",
       "target": "vanillasky/scene-templates/tokens.ts",
-      "content": "/** Internal monochrome render tokens for cinematic scenes and shared primitives. */\nimport type { TemplateStyle } from \"../template-context\";\n\n// ─── Canonical defaults (the only place these values are defined) ──\n\nexport const TOKEN_DEFAULTS = {\n  /** Primary brand colour — CTA, highlights. */\n  primary: \"#00E5A0\",\n  /** Deepest background surface. */\n  surface: \"#0A0A14\",\n  /** Elevated card / panel surface. */\n  surfaceElevated: \"#14152A\",\n  /** Primary text color. */\n  foreground: \"#FFFFFF\",\n  /** Muted text — labels, footers, supporting copy. */\n  muted: \"#A7A6B0\",\n  /** Primary sans font family (first name of the stack). */\n  font: \"Inter\",\n  /** Script accent font family for handwritten callouts. */\n  scriptFont: \"Caveat\",\n} as const;\n\n/**\n * The canonical template font stack: first family of the resolved brand font, backed by\n * OS-native sans fallbacks that render identically in preview and the\n * SVG-as-image export path.\n */\nexport function fontStack(styleFont: string | undefined): string {\n  return `${(styleFont || \"\").split(\",\")[0].trim() || TOKEN_DEFAULTS.font}, -apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Helvetica, Arial, sans-serif`;\n}\n\n// ─── Resolved tokens ───────────────────────────────────────────────\n\n// ─── Style presets ─────────────────────────────────────────────────\n\n/**\n * Background families a preset can pick. Each resolves to a pure CSS\n * background string in `gradientBackground` — no CSS `filter`, which the\n * SVG export path cannot rasterize.\n */\nexport type BackgroundFamily = \"mesh\" | \"wash\" | \"spotlight\";\n\n/** Title placement a preset defaults to (SceneFrameVariant, minus no-title). */\nexport type PresetTitlePlacement = \"title-top\" | \"title-center\";\n\nexport interface TypeTreatment {\n  /** Added to the computed fontWeight (clamped 100–900). */\n  weightDelta: number;\n  /** Added to the size role's letterSpacing, in em. */\n  trackingDeltaEm: number;\n  /** Multiplies the computed fontSize. */\n  sizeScale: number;\n  /** Applied as CSS text-transform when set. */\n  transform?: \"uppercase\";\n  /**\n   * Multiplies every text-archetype entrance/exit phase duration. Set by\n   * `resolveTokens` from `style.motion`; absent on the raw preset literals,\n   * where it reads as 1.\n   *\n   * It rides on the type treatment because that object is the one channel\n   * that already flows from `style` into every `<TemplateText>` — 17 call\n   * sites pass `resolveTokens(style).preset.type` and nothing else\n   * style-derived. Pacing of typographic motion is part of how the type is\n   * treated, so this isn't a smuggled payload.\n   */\n  phaseScale?: number;\n}\n\nexport interface StylePreset {\n  id: string;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  background: BackgroundFamily;\n  titlePlacement: PresetTitlePlacement;\n  type: TypeTreatment;\n}\n\n/**\n * The named looks. `bold` is the default and is a deliberate no-op: a config\n * with no `preset` resolves to it and renders byte-identically to the\n * pre-preset output, so adding presets can't restyle anyone's existing video.\n *\n * Deliberately small. Every preset multiplies the QA surface by every\n * template at both orientations — grow this only when a brief can't be\n * expressed by the ones here.\n */\nexport const STYLE_PRESETS: Record<string, StylePreset> = {\n  bold: {\n    id: \"bold\",\n    useWhen:\n      \"The default. Drifting two-color brand mesh, heavy tight headlines at the top. Launches, hype, product moments — the loudest of the three.\",\n    background: \"mesh\",\n    titlePlacement: \"title-top\",\n    type: { weightDelta: 0, trackingDeltaEm: 0, sizeScale: 1 },\n  },\n  editorial: {\n    id: \"editorial\",\n    useWhen:\n      \"Calm vertical wash, lighter and wider-tracked headlines, centered. Reviews, thoughtful updates, premium or B2B brands — when the copy should feel considered rather than shouted.\",\n    background: \"wash\",\n    titlePlacement: \"title-center\",\n    type: { weightDelta: -200, trackingDeltaEm: 0.01, sizeScale: 1.08 },\n  },\n  stark: {\n    id: \"stark\",\n    useWhen:\n      \"Single hard spotlight on near-black, uppercase and tightly tracked. Dev tools, technical claims, high-contrast statements — maximum weight on very few words.\",\n    background: \"spotlight\",\n    titlePlacement: \"title-top\",\n    type: { weightDelta: 100, trackingDeltaEm: -0.01, sizeScale: 1, transform: \"uppercase\" },\n  },\n};\n\nexport const DEFAULT_PRESET_ID = \"bold\";\nexport const PRESET_IDS = Object.keys(STYLE_PRESETS);\n\n/** Unknown/unset ids fall back to the default rather than throwing — a bad\n *  preset should never be the reason a render fails. */\nexport function resolvePreset(id: string | undefined): StylePreset {\n  return (id && STYLE_PRESETS[id]) || STYLE_PRESETS[DEFAULT_PRESET_ID];\n}\n\n// ─── Density & motion ──────────────────────────────────────────────\n//\n// Two dimensions orthogonal to the named preset. `preset` answers \"which\n// look\"; these answer \"how loud\". Splitting them is what lets \"make the\n// whole video more understated\" be one instruction instead of hand-tuning\n// every scene: they resolve into multipliers on levers that already reach\n// all 28 templates, so no template file knows they exist.\n//\n// Both default to `normal`, whose multipliers are all 1 — a config that sets\n// neither renders byte-identically to the pre-density output. Same invariant\n// the presets hold.\n\nexport type StyleDensity = \"airy\" | \"normal\" | \"packed\";\nexport type StyleMotion = \"calm\" | \"normal\" | \"punchy\";\n\nexport interface DensityScale {\n  id: StyleDensity;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  /** Multiplies the headline font size (via the preset's `type.sizeScale`). */\n  typeScale: number;\n  /** Multiplies the frame's safe-zone insets — bigger insets, more air. */\n  safeZoneScale: number;\n}\n\nexport interface MotionScale {\n  id: StyleMotion;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  /** Multiplies every text-archetype entrance/exit phase duration. */\n  phaseScale: number;\n}\n\nexport const DENSITY_SCALES: Record<StyleDensity, DensityScale> = {\n  airy: {\n    id: \"airy\",\n    useWhen:\n      \"Smaller headlines held further off the frame edges. Premium, considered, editorial — when the copy should have room to breathe.\",\n    typeScale: 0.92,\n    safeZoneScale: 1.3,\n  },\n  normal: {\n    id: \"normal\",\n    useWhen: \"The default. No change to type size or frame padding.\",\n    typeScale: 1,\n    safeZoneScale: 1,\n  },\n  packed: {\n    id: \"packed\",\n    useWhen:\n      \"Bigger headlines pushed closer to the edges. Dense, urgent, information-heavy — when the frame should feel full.\",\n    typeScale: 1.08,\n    safeZoneScale: 0.8,\n  },\n};\n\nexport const MOTION_SCALES: Record<StyleMotion, MotionScale> = {\n  calm: {\n    id: \"calm\",\n    useWhen:\n      \"Slower entrances and exits — text eases in rather than arriving. Founder stories, sober data, anything reflective.\",\n    phaseScale: 1.4,\n  },\n  normal: {\n    id: \"normal\",\n    useWhen: \"The default. Archetype timings as authored.\",\n    phaseScale: 1,\n  },\n  punchy: {\n    id: \"punchy\",\n    useWhen:\n      \"Snappier entrances and exits — text lands fast and clears fast. Hype, launches, hot takes.\",\n    phaseScale: 0.7,\n  },\n};\n\nexport const DEFAULT_DENSITY_ID: StyleDensity = \"normal\";\nexport const DEFAULT_MOTION_ID: StyleMotion = \"normal\";\nexport const DENSITY_IDS = Object.keys(DENSITY_SCALES) as StyleDensity[];\nexport const MOTION_IDS = Object.keys(MOTION_SCALES) as StyleMotion[];\n\n/** Unknown/unset ids fall back to `normal`, same as `resolvePreset`. */\nexport function resolveDensity(id: string | undefined): DensityScale {\n  return (id && DENSITY_SCALES[id as StyleDensity]) || DENSITY_SCALES[DEFAULT_DENSITY_ID];\n}\n\n/** Unknown/unset ids fall back to `normal`, same as `resolvePreset`. */\nexport function resolveMotion(id: string | undefined): MotionScale {\n  return (id && MOTION_SCALES[id as StyleMotion]) || MOTION_SCALES[DEFAULT_MOTION_ID];\n}\n\nexport interface ResolvedTokens {\n  /** Primary brand colour. */\n  primary: string;\n  /** Secondary brand colour. */\n  secondary: string;\n  /** Visual background, deliberately separate from semantic foreground colours. */\n  background: { type: \"solid\"; color: string } | { type: \"gradient\"; colors: [string, string] };\n  /** Deepest background surface. */\n  surface: string;\n  /** Elevated card / panel surface. */\n  surfaceElevated: string;\n  /** Primary foreground colour. */\n  foreground: string;\n  /** Muted text color. */\n  muted: string;\n  /** Full font fallback stack (see fontStack). */\n  font: string;\n  /** Script accent font family. */\n  scriptFont: string;\n  logoUrl?: string;\n  name?: string;\n  /**\n   * Resolved style preset — frame-level look. Always set.\n   *\n   * `preset.type` is the composed treatment, not the raw preset literal:\n   * `sizeScale` already carries the density multiplier and `phaseScale`\n   * carries the motion one. Templates pass this straight to `<TemplateText>`,\n   * which is how both dials reach every template without a template edit.\n   */\n  preset: StylePreset;\n  /** Resolved density dial. Always set; `normal` when unset. */\n  density: DensityScale;\n  /** Resolved motion dial. Always set; `normal` when unset. */\n  motion: MotionScale;\n}\n\nexport function resolveTokens(\n  style: TemplateStyle,\n): ResolvedTokens {\n\n  // Compose the two dials into the preset's type treatment here, once. Every\n  // template already passes `preset.type` to <TemplateText>, so folding them\n  // in at the resolver is what makes them bite everywhere with no template\n  // edits. At `normal`/`normal` both multipliers are 1 and the object is\n  // value-identical to the preset literal.\n  const preset = resolvePreset(style.preset);\n  const density = resolveDensity(style.density);\n  const motion = resolveMotion(style.motion);\n  const composedPreset: StylePreset = {\n    ...preset,\n    type: {\n      ...preset.type,\n      sizeScale: preset.type.sizeScale * density.typeScale,\n      phaseScale: motion.phaseScale,\n    },\n  };\n\n  return {\n    primary: \"#FFFFFF\",\n    secondary: \"#FFFFFF\",\n    background: { type: \"solid\", color: \"#000000\" },\n    surface: \"#000000\",\n    surfaceElevated: \"#171717\",\n    foreground: \"#FFFFFF\",\n    muted: \"#B7B7BC\",\n    font: '-apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Roboto, Arial, sans-serif',\n    scriptFont: \"Georgia\",\n    preset: composedPreset,\n    density,\n    motion,\n  };\n}\n\n// ─── Color math the resolver depends on ────────────────────────────\n// (Lives beside the resolver because theme owns both token resolution and\n// color derivation.)\n\n/**\n * Shift a hex color's hue by a number of degrees.\n * Used by internal template treatments that need a related hue.\n */\nexport function shiftHue(hex: string, degrees: number): string {\n  const r = parseInt(hex.slice(1, 3), 16) / 255;\n  const g = parseInt(hex.slice(3, 5), 16) / 255;\n  const b = parseInt(hex.slice(5, 7), 16) / 255;\n\n  const max = Math.max(r, g, b);\n  const min = Math.min(r, g, b);\n  const d = max - min;\n  const l = (max + min) / 2;\n  let h = 0;\n  let s = 0;\n\n  if (d > 0) {\n    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);\n    if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;\n    else if (max === g) h = ((b - r) / d + 2) / 6;\n    else h = ((r - g) / d + 4) / 6;\n  }\n\n  h = (h + degrees / 360 + 1) % 1;\n\n  const hue2rgb = (p: number, q: number, t: number) => {\n    if (t < 0) t += 1;\n    if (t > 1) t -= 1;\n    if (t < 1 / 6) return p + (q - p) * 6 * t;\n    if (t < 1 / 2) return q;\n    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;\n    return p;\n  };\n\n  let r2: number, g2: number, b2: number;\n  if (s === 0) {\n    r2 = g2 = b2 = l;\n  } else {\n    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;\n    const p = 2 * l - q;\n    r2 = hue2rgb(p, q, h + 1 / 3);\n    g2 = hue2rgb(p, q, h);\n    b2 = hue2rgb(p, q, h - 1 / 3);\n  }\n\n  const toHex = (v: number) =>\n    Math.round(v * 255)\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${toHex(r2)}${toHex(g2)}${toHex(b2)}`;\n}\n\n/** Lighten a hex color by a 0-1 factor. */\n/** Scale a hex color toward black by `factor` (0 = unchanged, 1 = black). */\nexport function darken(hex: string, factor: number): string {\n  if (!hex.startsWith(\"#\") || (hex.length !== 4 && hex.length !== 7)) {\n    return hex;\n  }\n  const full = hex.length === 4\n    ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`\n    : hex;\n  const ch = (i: number) =>\n    Math.max(0, Math.round(parseInt(full.slice(i, i + 2), 16) * (1 - factor)))\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${ch(1)}${ch(3)}${ch(5)}`;\n}\n\nexport function lighten(hex: string, factor: number): string {\n  if (!hex.startsWith(\"#\") || (hex.length !== 4 && hex.length !== 7)) {\n    return hex;\n  }\n  const full = hex.length === 4\n    ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`\n    : hex;\n  const r = parseInt(full.slice(1, 3), 16);\n  const g = parseInt(full.slice(3, 5), 16);\n  const b = parseInt(full.slice(5, 7), 16);\n  const lr = Math.min(255, Math.round(r + (255 - r) * factor));\n  const lg = Math.min(255, Math.round(g + (255 - g) * factor));\n  const lb = Math.min(255, Math.round(b + (255 - b) * factor));\n  return `#${lr.toString(16).padStart(2, \"0\")}${lg.toString(16).padStart(2, \"0\")}${lb.toString(16).padStart(2, \"0\")}`;\n}\n\n/**\n * Per-glyph halo for type sitting directly on photo or video.\n *\n * A frame-wide scrim can only trade picture for contrast, and it loses that\n * trade against blown-out highlights: holding white type at 4.5:1 over a\n * near-white region needs ~0.8 alpha of black across the whole plate. A\n * two-layer shadow buys the same local separation for free — a tight 8px pass\n * for edge definition against fine texture, a wide 16px pass for the soft\n * falloff that separates the word from whatever sits behind it. Export-safe:\n * `text-shadow` survives SVG capture, `filter`/`backdrop-filter` do not.\n */\nexport const MEDIA_TEXT_SHADOW =\n  \"0 2px 8px rgba(0,0,0,0.55), 0 6px 16px rgba(0,0,0,0.35)\";\n"
+      "content": "/** Internal monochrome render tokens for cinematic scenes and shared primitives. */\nimport type { TemplateStyle } from \"../template-context\";\n\n// ─── Canonical defaults (the only place these values are defined) ──\n\nexport const TOKEN_DEFAULTS = {\n  /** Primary brand colour — CTA, highlights. */\n  primary: \"#00E5A0\",\n  /** Deepest background surface. */\n  surface: \"#0A0A14\",\n  /** Elevated card / panel surface. */\n  surfaceElevated: \"#14152A\",\n  /** Primary text color. */\n  foreground: \"#FFFFFF\",\n  /** Muted text — labels, footers, supporting copy. */\n  muted: \"#A7A6B0\",\n  /** Primary sans font family (first name of the stack). */\n  font: \"Inter\",\n  /** Script accent font family for handwritten callouts. */\n  scriptFont: \"Caveat\",\n} as const;\n\n/**\n * The canonical template font stack: first family of the resolved brand font, backed by\n * OS-native sans fallbacks that render identically in preview and the\n * SVG-as-image export path.\n */\nexport function fontStack(styleFont: string | undefined): string {\n  return `${(styleFont || \"\").split(\",\")[0].trim() || TOKEN_DEFAULTS.font}, -apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Helvetica, Arial, sans-serif`;\n}\n\n// ─── Resolved tokens ───────────────────────────────────────────────\n\n// ─── Style presets ─────────────────────────────────────────────────\n\n/**\n * Background families a preset can pick. Each resolves to a pure CSS\n * background string in `gradientBackground` — no CSS `filter`, which the\n * SVG export path cannot rasterize.\n */\nexport type BackgroundFamily = \"mesh\" | \"wash\" | \"spotlight\";\n\n/** Title placement a preset defaults to (SceneFrameVariant, minus no-title). */\nexport type PresetTitlePlacement = \"title-top\" | \"title-center\";\n\nexport interface TypeTreatment {\n  /** Added to the computed fontWeight (clamped 100–900). */\n  weightDelta: number;\n  /** Added to the size role's letterSpacing, in em. */\n  trackingDeltaEm: number;\n  /** Multiplies the computed fontSize. */\n  sizeScale: number;\n  /** Applied as CSS text-transform when set. */\n  transform?: \"uppercase\";\n  /**\n   * Multiplies every text-archetype entrance/exit phase duration. Set by\n   * `resolveTokens` from `style.motion`; absent on the raw preset literals,\n   * where it reads as 1.\n   *\n   * It rides on the type treatment because that object is the one channel\n   * that already flows from `style` into text rendering. Pacing of\n   * typographic motion is part of how the type is treated, so this isn't a\n   * smuggled payload.\n   */\n  phaseScale?: number;\n}\n\nexport interface StylePreset {\n  id: string;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  background: BackgroundFamily;\n  titlePlacement: PresetTitlePlacement;\n  type: TypeTreatment;\n}\n\n/**\n * The named looks. `bold` is the default and is a deliberate no-op: a config\n * with no `preset` resolves to it and renders byte-identically to the\n * pre-preset output, so adding presets can't restyle anyone's existing video.\n *\n * Deliberately small. Every preset multiplies the QA surface by every\n * template at both orientations — grow this only when a brief can't be\n * expressed by the ones here.\n */\nexport const STYLE_PRESETS: Record<string, StylePreset> = {\n  bold: {\n    id: \"bold\",\n    useWhen:\n      \"The default. Drifting two-color brand mesh, heavy tight headlines at the top. Launches, hype, product moments — the loudest of the three.\",\n    background: \"mesh\",\n    titlePlacement: \"title-top\",\n    type: { weightDelta: 0, trackingDeltaEm: 0, sizeScale: 1 },\n  },\n  editorial: {\n    id: \"editorial\",\n    useWhen:\n      \"Calm vertical wash, lighter and wider-tracked headlines, centered. Reviews, thoughtful updates, premium or B2B brands — when the copy should feel considered rather than shouted.\",\n    background: \"wash\",\n    titlePlacement: \"title-center\",\n    type: { weightDelta: -200, trackingDeltaEm: 0.01, sizeScale: 1.08 },\n  },\n  stark: {\n    id: \"stark\",\n    useWhen:\n      \"Single hard spotlight on near-black, uppercase and tightly tracked. Dev tools, technical claims, high-contrast statements — maximum weight on very few words.\",\n    background: \"spotlight\",\n    titlePlacement: \"title-top\",\n    type: { weightDelta: 100, trackingDeltaEm: -0.01, sizeScale: 1, transform: \"uppercase\" },\n  },\n};\n\nexport const DEFAULT_PRESET_ID = \"bold\";\nexport const PRESET_IDS = Object.keys(STYLE_PRESETS);\n\n/** Unknown/unset ids fall back to the default rather than throwing — a bad\n *  preset should never be the reason a render fails. */\nexport function resolvePreset(id: string | undefined): StylePreset {\n  return (id && STYLE_PRESETS[id]) || STYLE_PRESETS[DEFAULT_PRESET_ID];\n}\n\n// ─── Density & motion ──────────────────────────────────────────────\n//\n// Two dimensions orthogonal to the named preset. `preset` answers \"which\n// look\"; these answer \"how loud\". Splitting them is what lets \"make the\n// whole video more understated\" be one instruction instead of hand-tuning\n// every scene: they resolve into multipliers on levers that already reach\n// all 28 templates, so no template file knows they exist.\n//\n// Both default to `normal`, whose multipliers are all 1 — a config that sets\n// neither renders byte-identically to the pre-density output. Same invariant\n// the presets hold.\n\nexport type StyleDensity = \"airy\" | \"normal\" | \"packed\";\nexport type StyleMotion = \"calm\" | \"normal\" | \"punchy\";\n\nexport interface DensityScale {\n  id: StyleDensity;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  /** Multiplies the headline font size (via the preset's `type.sizeScale`). */\n  typeScale: number;\n  /** Multiplies the frame's safe-zone insets — bigger insets, more air. */\n  safeZoneScale: number;\n}\n\nexport interface MotionScale {\n  id: StyleMotion;\n  /** Agent-facing use-when — surfaced in the registry index. */\n  useWhen: string;\n  /** Multiplies every text-archetype entrance/exit phase duration. */\n  phaseScale: number;\n}\n\nexport const DENSITY_SCALES: Record<StyleDensity, DensityScale> = {\n  airy: {\n    id: \"airy\",\n    useWhen:\n      \"Smaller headlines held further off the frame edges. Premium, considered, editorial — when the copy should have room to breathe.\",\n    typeScale: 0.92,\n    safeZoneScale: 1.3,\n  },\n  normal: {\n    id: \"normal\",\n    useWhen: \"The default. No change to type size or frame padding.\",\n    typeScale: 1,\n    safeZoneScale: 1,\n  },\n  packed: {\n    id: \"packed\",\n    useWhen:\n      \"Bigger headlines pushed closer to the edges. Dense, urgent, information-heavy — when the frame should feel full.\",\n    typeScale: 1.08,\n    safeZoneScale: 0.8,\n  },\n};\n\nexport const MOTION_SCALES: Record<StyleMotion, MotionScale> = {\n  calm: {\n    id: \"calm\",\n    useWhen:\n      \"Slower entrances and exits — text eases in rather than arriving. Founder stories, sober data, anything reflective.\",\n    phaseScale: 1.4,\n  },\n  normal: {\n    id: \"normal\",\n    useWhen: \"The default. Archetype timings as authored.\",\n    phaseScale: 1,\n  },\n  punchy: {\n    id: \"punchy\",\n    useWhen:\n      \"Snappier entrances and exits — text lands fast and clears fast. Hype, launches, hot takes.\",\n    phaseScale: 0.7,\n  },\n};\n\nexport const DEFAULT_DENSITY_ID: StyleDensity = \"normal\";\nexport const DEFAULT_MOTION_ID: StyleMotion = \"normal\";\nexport const DENSITY_IDS = Object.keys(DENSITY_SCALES) as StyleDensity[];\nexport const MOTION_IDS = Object.keys(MOTION_SCALES) as StyleMotion[];\n\n/** Unknown/unset ids fall back to `normal`, same as `resolvePreset`. */\nexport function resolveDensity(id: string | undefined): DensityScale {\n  return (id && DENSITY_SCALES[id as StyleDensity]) || DENSITY_SCALES[DEFAULT_DENSITY_ID];\n}\n\n/** Unknown/unset ids fall back to `normal`, same as `resolvePreset`. */\nexport function resolveMotion(id: string | undefined): MotionScale {\n  return (id && MOTION_SCALES[id as StyleMotion]) || MOTION_SCALES[DEFAULT_MOTION_ID];\n}\n\nexport interface ResolvedTokens {\n  /** Primary brand colour. */\n  primary: string;\n  /** Secondary brand colour. */\n  secondary: string;\n  /** Visual background, deliberately separate from semantic foreground colours. */\n  background: { type: \"solid\"; color: string } | { type: \"gradient\"; colors: [string, string] };\n  /** Deepest background surface. */\n  surface: string;\n  /** Elevated card / panel surface. */\n  surfaceElevated: string;\n  /** Primary foreground colour. */\n  foreground: string;\n  /** Muted text color. */\n  muted: string;\n  /** Full font fallback stack (see fontStack). */\n  font: string;\n  /** Script accent font family. */\n  scriptFont: string;\n  logoUrl?: string;\n  name?: string;\n  /**\n   * Resolved style preset — frame-level look. Always set.\n   *\n   * `preset.type` is the composed treatment, not the raw preset literal:\n   * `sizeScale` already carries the density multiplier and `phaseScale`\n   * carries the motion one, which is how both dials reach text rendering\n   * without a template edit.\n   */\n  preset: StylePreset;\n  /** Resolved density dial. Always set; `normal` when unset. */\n  density: DensityScale;\n  /** Resolved motion dial. Always set; `normal` when unset. */\n  motion: MotionScale;\n}\n\nexport function resolveTokens(\n  style: TemplateStyle,\n): ResolvedTokens {\n\n  // Compose the two dials into the preset's type treatment here, once, so\n  // folding them in at the resolver is what makes them bite everywhere with\n  // no template edits. At `normal`/`normal` both multipliers are 1 and the\n  // object is value-identical to the preset literal.\n  const preset = resolvePreset(style.preset);\n  const density = resolveDensity(style.density);\n  const motion = resolveMotion(style.motion);\n  const composedPreset: StylePreset = {\n    ...preset,\n    type: {\n      ...preset.type,\n      sizeScale: preset.type.sizeScale * density.typeScale,\n      phaseScale: motion.phaseScale,\n    },\n  };\n\n  return {\n    primary: \"#FFFFFF\",\n    secondary: \"#FFFFFF\",\n    background: { type: \"solid\", color: \"#000000\" },\n    surface: \"#000000\",\n    surfaceElevated: \"#171717\",\n    foreground: \"#FFFFFF\",\n    muted: \"#B7B7BC\",\n    font: '-apple-system, BlinkMacSystemFont, \"Helvetica Neue\", Roboto, Arial, sans-serif',\n    scriptFont: \"Georgia\",\n    preset: composedPreset,\n    density,\n    motion,\n  };\n}\n\n// ─── Color math the resolver depends on ────────────────────────────\n// (Lives beside the resolver because theme owns both token resolution and\n// color derivation.)\n\n/**\n * Shift a hex color's hue by a number of degrees.\n * Used by internal template treatments that need a related hue.\n */\nexport function shiftHue(hex: string, degrees: number): string {\n  const r = parseInt(hex.slice(1, 3), 16) / 255;\n  const g = parseInt(hex.slice(3, 5), 16) / 255;\n  const b = parseInt(hex.slice(5, 7), 16) / 255;\n\n  const max = Math.max(r, g, b);\n  const min = Math.min(r, g, b);\n  const d = max - min;\n  const l = (max + min) / 2;\n  let h = 0;\n  let s = 0;\n\n  if (d > 0) {\n    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);\n    if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;\n    else if (max === g) h = ((b - r) / d + 2) / 6;\n    else h = ((r - g) / d + 4) / 6;\n  }\n\n  h = (h + degrees / 360 + 1) % 1;\n\n  const hue2rgb = (p: number, q: number, t: number) => {\n    if (t < 0) t += 1;\n    if (t > 1) t -= 1;\n    if (t < 1 / 6) return p + (q - p) * 6 * t;\n    if (t < 1 / 2) return q;\n    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;\n    return p;\n  };\n\n  let r2: number, g2: number, b2: number;\n  if (s === 0) {\n    r2 = g2 = b2 = l;\n  } else {\n    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;\n    const p = 2 * l - q;\n    r2 = hue2rgb(p, q, h + 1 / 3);\n    g2 = hue2rgb(p, q, h);\n    b2 = hue2rgb(p, q, h - 1 / 3);\n  }\n\n  const toHex = (v: number) =>\n    Math.round(v * 255)\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${toHex(r2)}${toHex(g2)}${toHex(b2)}`;\n}\n\n/** Lighten a hex color by a 0-1 factor. */\n/** Scale a hex color toward black by `factor` (0 = unchanged, 1 = black). */\nexport function darken(hex: string, factor: number): string {\n  if (!hex.startsWith(\"#\") || (hex.length !== 4 && hex.length !== 7)) {\n    return hex;\n  }\n  const full = hex.length === 4\n    ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`\n    : hex;\n  const ch = (i: number) =>\n    Math.max(0, Math.round(parseInt(full.slice(i, i + 2), 16) * (1 - factor)))\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${ch(1)}${ch(3)}${ch(5)}`;\n}\n\nexport function lighten(hex: string, factor: number): string {\n  if (!hex.startsWith(\"#\") || (hex.length !== 4 && hex.length !== 7)) {\n    return hex;\n  }\n  const full = hex.length === 4\n    ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`\n    : hex;\n  const r = parseInt(full.slice(1, 3), 16);\n  const g = parseInt(full.slice(3, 5), 16);\n  const b = parseInt(full.slice(5, 7), 16);\n  const lr = Math.min(255, Math.round(r + (255 - r) * factor));\n  const lg = Math.min(255, Math.round(g + (255 - g) * factor));\n  const lb = Math.min(255, Math.round(b + (255 - b) * factor));\n  return `#${lr.toString(16).padStart(2, \"0\")}${lg.toString(16).padStart(2, \"0\")}${lb.toString(16).padStart(2, \"0\")}`;\n}\n\n/**\n * Per-glyph halo for type sitting directly on photo or video.\n *\n * A frame-wide scrim can only trade picture for contrast, and it loses that\n * trade against blown-out highlights: holding white type at 4.5:1 over a\n * near-white region needs ~0.8 alpha of black across the whole plate. A\n * two-layer shadow buys the same local separation for free — a tight 8px pass\n * for edge definition against fine texture, a wide 16px pass for the soft\n * falloff that separates the word from whatever sits behind it. Export-safe:\n * `text-shadow` survives SVG capture, `filter`/`backdrop-filter` do not.\n */\nexport const MEDIA_TEXT_SHADOW =\n  \"0 2px 8px rgba(0,0,0,0.55), 0 6px 16px rgba(0,0,0,0.35)\";\n"
     }
   ],
   "meta": {

package/starters/video-chat/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@vanillaskyai/video": "0.10.21",
+    "@vanillaskyai/video": "0.10.23",
     "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; } }

package/docs/maintainers/cinematic-migration.md

@@ -1,38 +0,0 @@
-# Cinematic contract migration
-
-The eight-template replacement is an approved breaking pre-1.0 change. Persisted Video schema is now `0.2`; event protocol is `0.6`.
-
-## Breaking changes
-
-- Removed `VideoInput.brand`, `VideoStyle.brand`, `VideoBrand`, `VideoBrandInput`, `VideoBackground`, and `resolveVideoBrand`. Graphics use black, white/neutral text and system typography. Naturally colored media is unaffected.
-- Removed all 28 old built-in IDs. Eight new IDs describe different schemas: `cinemaMedia`, `chapterTitle`, `focusCards`, `editorialTimeline`, `mobileMessage`, `comparison`, `quote`, `keyFigure`.
-- `parseVideo` rejects the old persisted `0.1` fixture with `unsupported_video_version`. The parser also rejects `style.brand` if a caller merely stamps the new version onto an old object.
-- Scene source intent uses `mediaKeyword` (up to 80 characters) and optional `mediaSource`. The host owns `mediaUrl`, `mediaPoster` and resolved `mediaType`. No gradient fallback mode. Full-bleed requires a resolvable intent or asset; Reach out can remain on black when media is unavailable.
-
-## Adoption
-
-Regenerate videos from the retained source and narration using the new catalog. Do not automatically relabel old IDs: before/after emojis, count-ups and factual quote/stat schemas have different meanings. Retain an older published SDK in a separate legacy playback boundary if historical exports must continue to render; do not pass those payloads into the new parser.
-
-Before (old persisted format):
-
-```json
-{"schemaVersion":"0.1","scenes":[{"id":"one","templateId":"media","variables":{"texts":"A new perspective","mediaType":"gradient"},"timing":{"fixedDuration":4}}],"style":{"brand":{"font":"Inter"}}}
-```
-
-After re-authoring that title as a chapter:
-
-```json
-{"schemaVersion":"0.2","scenes":[{"id":"one","templateId":"chapterTitle","variables":{"title":"A new perspective"},"timing":{"fixedDuration":4}}],"style":{}}
-```
-
-Evidence: persistence tests preserve the untouched old release fixture and assert rejection, accept current-style round trips, reject hidden/non-JSON input as before, and pin new checksums. Template tests cover both orientations, deterministic seeking, exact evidence text and single-decoder backdrop ownership. Final packed consumer and mobile playback checks remain release gates.
-
-## Render fonts
-
-The cinematic templates use `-apple-system, BlinkMacSystemFont, "Helvetica Neue", Roboto, Arial, sans-serif` at regular and medium weights. Apple devices keep native system typography. The existing `@vanillaskyai/video/video-chat.css` entry registers packaged Roboto v51 WOFF2 subsets as the fallback for environments without those fonts. Standalone player and source-owned template integrations should also import that stylesheet. No font is fetched from Google at runtime; browsers fetch local packaged subsets only when Roboto is selected for the rendered glyphs. The font assets include the SIL Open Font License and a source/hash manifest.
-
-Live native fonts and a Linux renderer’s Roboto have slightly different metrics. For repeatable exports, keep the browser, installed fonts, viewport and package version fixed, and await `document.fonts.ready` after mounting the final scene before capturing frames. This is a host export responsibility; the SDK does not add a separate export API or force downloaded fonts onto Apple devices.
-
-## Media-led follow-up
-
-The owner requested removing `focusCards`. Regenerate persisted videos using that ID; migrate parallel explanations to narration over footage rather than another bullet layout. The remaining seven templates retain their IDs. Comparison, quote, key figure and timeline accept optional standard media variables and remain readable on black when assets are absent. No provider callback signatures or host limits change.