@vanillaskyai/video 0.10.3 → 0.10.4

package/CHANGELOG.md

@@ -4,6 +4,15 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.4
+
+- Show the canonical chapter immediately after submitting a prompt; remove the separate gradient loading placeholder and opening stock requests.
+- Separate AI video and Pexels in Settings. AI mode uses generated footage only; Pexels performs full bounded video search without AI-video calls. Missing or late footage becomes an authored chapter with complete narration.
+- Prepare speech while footage generates, reuse prepared lines, and limit concurrent speech requests so an answer does not flood host admission. Describe HTTP throttling as a retryable request limit.
+- Keep silent footage looping for the finite narrated scene, and recover missing URLs or rejected playback to a chapter rather than an unavailable screen. Preserve user pause, cancellation and replay.
+- Allow hosts to configure the actual generated clip duration (default five seconds) and apply scene-position deadlines to media preparation.
+- Add optional host-only phase diagnostics with bounded timing and fixed recovery reasons, without retaining prompt or provider content.
+
 ## 0.10.3
 
 - Remove the implicit documentary visual style from the chat interface; preserve explicitly supplied application styles and let the answer direct its own look.

package/PUBLIC-API.md

@@ -116,6 +116,19 @@ provider-neutral text-delta escape hatch.
 
 ### Handler contract
 
+The chat contract includes two footage modes: `"cinematic"` (labelled AI video)
+and `"pexels"`. AI mode does not fall back to stock; either mode recovers missing
+footage to an authored chapter. Existing `"cinematic"` requests remain valid.
+`generatedClipDurationSec?: number` on the handler defaults to 5 and accepts 2–20;
+it must match the host adapter's requested duration. `VideoChatTurn.mode` is
+optional so older in-memory saved turns remain readable.
+
+A declared `data.video-chat-preparation` extension carries
+`{ sceneId: string, narration: string }` before media resolves. It permits bounded
+speech preparation, not playback of an unvalidated scene. The client limits
+speech preparation to two concurrent jobs and reuses it when `scene.add` arrives.
+The six public exports, persisted video schema and protocol version are unchanged.
+
 `createVideoChatHandler` is the opinionated general-purpose video-chat route.
 Mount it once and use its bounded `action` query parameter for capabilities,
 responses, opening media, narration, suggestions, speech,
@@ -124,33 +137,28 @@ application-configured visual-mode attempt limits, capability fallbacks, and aux
 shapes. The application supplies provider-neutral `streamText`, `generateText`,
 `generateSpeech`, `transcribe`, `searchMedia`, and `generateVideo` callbacks.
 Only the two text callbacks are required. Missing optional callbacks remove
-their capability; templates and browser speech remain available. During response
-creation, failed generated footage falls back to stock when available, then to
-matching completed footage and finally a safe template. The default handler skips invalid planner parts and preserves
-playable scenes on an interrupted plan, emitting non-fatal warnings. Explicit
-`invalidPartBehavior: "fail"` retains strict generation semantics.
+their capability; templates and browser speech remain available. Failed or late
+footage becomes an authored chapter with complete narration. The default handler
+skips invalid planner parts and preserves playable scenes on an interrupted plan,
+emitting non-fatal warnings. Explicit `invalidPartBehavior: "fail"` retains strict
+generation semantics.
 
 - A response accepts `prompt`, `mode`, `orientation`, optional bounded
   `conversation`, `opening`, and `style`. `opening` is an optional
   prewritten hook from a selected suggestion. The response returns protocol
-  `0.6` SSE and negotiates `data.video-chat-opening`, which carries the bounded
-  6-9 word hook and optional stock-search `keyword` and `fallbackKeyword` before the first scene.
-- The planner produces that opening as the first line of the same model stream
-  that produces the scenes. The separate opening-media action resolves its
-  keyword through the application-owned `searchMedia` callback, with an optional
-  bounded `fallbackQuery` for broader opening atmosphere. Stock lookup
-  never delays speech or planning. In `full` mode the first line also directs
-  the exact first generated scene; the handler consumes that private direction
-  and starts the clip while the model continues with scenes two through five.
-- `templates` never generates video. `full` uses an application-owned
-  `maxGeneratedVideos` limit (default five, nonnegative safe integer). The limit
-  counts attempts including failed attempts and the reserved first shot; it is
-  neither a currency nor duration cap. Stock lookup remains available after
-  the limit. With zero, full mode uses stock only. The planner receives this
-  budget, and the server enforces it independently. If providers fail, an
-  already completed video with the identical search query and visual look may
-  be reused once in the same response before a readable template fallback. Without `generateVideo`, only `templates` is exposed
-  and forged generated-mode requests degrade to it.
+  `0.6` SSE and negotiates `data.video-chat-opening` and
+  `data.video-chat-preparation` before the associated scene is ready.
+- The planner produces the opening and shots in one model stream, reserving the
+  intended ending. Each shot supplies an authored recovery title, complete
+  narration and visual direction. The default UI uses a chapter opening; the
+  separate opening-media action remains available to custom consumers.
+- `cinematic` uses the application-owned `maxGeneratedVideos` limit (default
+  five, nonnegative safe integer). It counts generation attempts, including
+  failures. Zero skips generation and keeps authored chapters. Expired scene
+  deadlines also skip generation without consuming an attempt. This limit is
+  neither a currency nor duration cap. Pexels mode uses only `searchMedia` and
+  never consumes this allowance. Capabilities expose Pexels when stock search
+  is configured; AI mode remains usable with chapter recovery without video.
 - The response planner writes narration on each scene. The narration action is
   retained as a compatibility fallback for missing lines, not used in the
   normal path.
@@ -251,9 +259,9 @@ playable output; an error is shown only when no playable response remains.
 `ask(prompt, { opening, openingMedia })` lets a custom interface start a
 prewritten suggestion hook immediately and reuse its image or video without
 another model or media lookup. The hook otherwise reads the opening from the
-response stream, resolves its media keyword, holds that media while it is
-spoken, and starts the planned timeline only when both speech and the first
-scene are ready. `UseVideoChatOptions.onFirstFrame` receives a
+response stream and starts the planned timeline only when opening speech and
+the contiguous prepared scenes are ready. It no longer requests opening stock
+automatically. `UseVideoChatOptions.onFirstFrame` receives a
 `VideoChatFirstFrameMetric` once after its first active scene commits and reaches
 an animation-frame opportunity. This measures presentation readiness, not physical
 screen paint or media decoding. Each `VideoChatTurn` exposes `openingMedia` and `completed`, so
@@ -428,6 +436,7 @@ from `/server` without crossing a React type boundary.
 and nonnegative `elapsedMs` since the prompt was submitted:
 
 - `first-frame`: first committed active scene at an animation-frame opportunity;
+- `first-media-frame`: first decoded frame reported by the mounted footage surface;
 - `first-speech`: actual speech playback onset, with `source` equal to `browser`,
   `generated`, or `custom`;
 - `stall`: a finished wait for the next prepared scene, with `durationMs` and
@@ -455,8 +464,11 @@ resolver deadline (integer 1–120000 milliseconds, default 15000). The host sti
 provider cancellation, authorization and spend limits; a timeout does not prove the
 provider avoided a charge. `maxGeneratedVideos` continues to count attempted clips.
 
-`VideoChatProps.generatedVideoLabel` and `generatedVideoDescription` customize the
-existing generated-video Settings choice without changing server capabilities.
-`showRecoveryNotice` opts into a dismissible, fixed SDK media-fallback notice. It
-never displays arbitrary provider messages. All three default to existing behavior.
-These are additive members; no new entry points or exports are introduced.
+`VideoChatProps.showRecoveryNotice` opts into a dismissible, fixed SDK
+media-recovery notice; it never displays arbitrary provider messages.
+
+`VideoChatHandlerOptions.onDiagnostic` is an optional host-only observer for
+request, authoring and media phase timings with fixed recovery reason codes.
+It does not retain prompt, narration, query, asset URL or provider error text,
+and cannot affect response delivery. No new entry points or named exports are
+introduced; its additive signature is checked in the packed consumer contract.

package/README.md

@@ -26,9 +26,8 @@ npm run dev
 ```
 
 Open the reported localhost URL. One text key gives you the chat, an immediate introduction, and browser voice.
-Add the video adapter for generated footage and optional stock for fallback.
-Without a media provider, answers retain narration and subtitles with an
-unavailable-visual state. If installation is interrupted, rerun the init command.
+Add the video adapter for AI footage, or a Pexels key for the lower-cost stock mode.
+Without footage, authored chapter scenes carry the narration and subtitles. If installation is interrupted, rerun the init command.
 
 Optional upgrades keep the same client:
 
@@ -36,7 +35,7 @@ Optional upgrades keep the same client:
 | --- | --- | --- |
 | Generated speech | `npx vanillasky providers add speech` | `XAI_API_KEY` |
 | Generated video and voice transcription | `npx vanillasky providers add video` | `FAL_KEY` |
-| Stock media, including opening backgrounds | No install needed | `PEXELS_API_KEY` |
+| Pexels video search | No install needed | `PEXELS_API_KEY` |
 
 Run the selected command, add its key to `.env.local`, and restart the server.
 Only selected provider packages are installed. `npx vanillasky doctor` reports
@@ -84,18 +83,22 @@ both boundaries.
 ## An immediate intro, then moving footage
 
 The default chat uses a template introduction while its first shot prepares,
-then generated footage with narration and subtitles. Relevant stock is the
-fallback when generation is unavailable or fails. The planner adapts its
+then footage with narration and subtitles. Choose AI video or Pexels in Settings.
+AI mode never substitutes stock, and Pexels mode never calls the AI-video provider.
+Missing or late footage becomes a useful chapter scene. The planner adapts its
 visible actions and spoken beats to explanations, stories, comedy, imagination,
 and practical requests. It does not choose body templates.
 
+Speech and footage prepare together. Silent clips loop through the remaining
+narration when necessary, and every answer preserves its intended ending.
+
 Packaged templates remain available for custom compositions and source ownership.
 
 Copy template source only when you want to own and edit it:
 
 ```bash
 npm install --save-dev tsx
-npx vanillasky templates add bigNumber
+npx vanillasky templates add chapterTitle
 ```
 
 That compiler is needed only for source-owned templates. See
@@ -118,6 +121,7 @@ MP4/WebM export remains application-owned.
 | Add media or voice | [Media and voice](docs/media-and-audio.md) |
 | Persist and replay results | [Performance measurements](docs/performance.md) · [Persistence and replay](docs/persistence.md) |
 | Test routes and streams | [Test integrations](docs/testing.md) |
+| Iterate on SDK chat | [Development](docs/development.md): `dev:chat`, `check:chat`, `verify:release` |
 | Deploy securely | [Production](docs/production.md) · [Security](docs/security.md) |
 | Inspect the API contract | [Public API](PUBLIC-API.md) · [Protocol](docs/reference/protocol.md) |
 

package/dist/check-runtime.js

@@ -1,8 +1,8 @@
 import {
   VideoFrame
-} from "./chunk-3U2F7C7C.js";
+} from "./chunk-WZFLEPLM.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-YZZSWGC3.js";
+import "./chunk-OOBT4X46.js";
 import "./chunk-SPVTJH3F.js";
 import "./chunk-R3XAOMKP.js";
 import "./chunk-73NTSFFI.js";

package/dist/{chunk-UCXQORDZ.js → chunk-G5TYLTL5.js}

@@ -1,7 +1,7 @@
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-LJR5VLEI.js";
+} from "./chunk-QZAZT44G.js";
 import {
   editorialFont
 } from "./chunk-4YM2M62S.js";

package/dist/{chunk-SI6CFFAA.js → chunk-O6FBIB4L.js}

@@ -2,8 +2,9 @@ import {
   darken,
   resolveTokens,
   useMediaAudio,
+  useMediaFailure,
   useNarrationPreroll
-} from "./chunk-YZZSWGC3.js";
+} from "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/scene-video-backdrop.tsx
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -243,6 +244,7 @@ var SceneVideoBackdrop = ({
   onError
 }) => {
   const inheritedAudio = useMediaAudio();
+  const reportMediaFailure = useMediaFailure();
   const inheritedPreroll = useNarrationPreroll();
   const rewindPreroll = preparingNarration || inheritedPreroll;
   const resolvedMuted = muted ?? inheritedAudio.muted;
@@ -252,7 +254,6 @@ var SceneVideoBackdrop = ({
   const [decodedVideoUrl, setDecodedVideoUrl] = useState();
   const [waitingKey, setWaitingKey] = useState();
   const [exhaustedKey, setExhaustedKey] = useState();
-  const continuityReplay = useRef(void 0);
   const videoRef = useRef(null);
   const startedVideoUrl = useRef(void 0);
   const startedPlaybackId = useRef(void 0);
@@ -263,6 +264,7 @@ var SceneVideoBackdrop = ({
     if (presentationRef.current.key === videoPresentationKey && presentationRef.current.playing) {
       setExhaustedKey(videoPresentationKey);
       onError?.();
+      reportMediaFailure?.();
     }
   };
   const fitDuration = useCallback((video) => {
@@ -273,11 +275,10 @@ var SceneVideoBackdrop = ({
   }, [fitDuration]);
   const continueMotion = (video) => {
     if (!isPlaying) return;
-    if (!resolvedMuted || continuityReplay.current === videoPresentationKey) {
-      setExhaustedKey(videoPresentationKey);
+    if (!resolvedMuted) {
+      unavailable();
       return;
     }
-    continuityReplay.current = videoPresentationKey;
     video.currentTime = 0;
     void video.play().catch(unavailable);
   };

package/dist/{chunk-YZZSWGC3.js → chunk-OOBT4X46.js}

@@ -9,11 +9,12 @@ function ExternalVideoBackdropProvider({
   audioMuted = true,
   audioVolume = 1,
   preparingNarration = false,
+  onMediaError,
   children
 }) {
   const value = React.useMemo(
-    () => ({ mode, audioMuted, audioVolume, preparingNarration }),
-    [mode, audioMuted, audioVolume, preparingNarration]
+    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),
+    [mode, audioMuted, audioVolume, preparingNarration, onMediaError]
   );
   return /* @__PURE__ */ jsx(BackdropContext.Provider, { value, children });
 }
@@ -27,6 +28,9 @@ function useMediaAudio() {
 function useNarrationPreroll() {
   return React.useContext(BackdropContext).preparingNarration === true;
 }
+function useMediaFailure() {
+  return React.useContext(BackdropContext).onMediaError;
+}
 
 // src/visual-system/scene-templates/tokens.ts
 var STYLE_PRESETS = {
@@ -147,5 +151,6 @@ export {
   ExternalVideoBackdropProvider,
   useExternalVideoBackdrop,
   useMediaAudio,
-  useNarrationPreroll
+  useNarrationPreroll,
+  useMediaFailure
 };

package/dist/{chunk-LJR5VLEI.js → chunk-QZAZT44G.js}

@@ -3,13 +3,13 @@ import {
   SceneVideoBackdrop,
   getBackgroundTransform,
   resolveMediaPosition
-} from "./chunk-SI6CFFAA.js";
+} from "./chunk-O6FBIB4L.js";
 import {
   resolveMediaType
 } from "./chunk-224QNWRA.js";
 import {
   useExternalVideoBackdrop
-} from "./chunk-YZZSWGC3.js";
+} from "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/scene-background.tsx
 import { useEffect, useState } from "react";

package/dist/{chunk-3U2F7C7C.js → chunk-WZFLEPLM.js}

@@ -5,7 +5,7 @@ import {
 import {
   ExternalVideoBackdropProvider,
   resolveDensity
-} from "./chunk-YZZSWGC3.js";
+} from "./chunk-OOBT4X46.js";
 import {
   resolveVideoTimeline
 } from "./chunk-SPVTJH3F.js";
@@ -209,7 +209,7 @@ var SceneBoundary = class extends Component {
   }
 };
 var SCENE_TRANSITION_SECONDS = 0.3;
-var SceneVideoBackdrop = lazy(() => import("./scene-video-backdrop-OWUXPXHZ.js").then((module) => ({ default: module.SceneVideoBackdrop })));
+var SceneVideoBackdrop = lazy(() => import("./scene-video-backdrop-4EZVVQY7.js").then((module) => ({ default: module.SceneVideoBackdrop })));
 var MEDIA_PREROLL_SECONDS = 1.2;
 var CONTIGUITY_ULP_FACTOR = 4;
 var subscribeToDecoderPolicy = () => () => {
@@ -257,6 +257,7 @@ function sceneBackgroundChanges(left, right) {
 }
 function SceneLayer({
   onFramePresented,
+  onMediaError,
   kit,
   config,
   range,
@@ -274,7 +275,7 @@ function SceneLayer({
   zIndex,
   externalVideoBackdrop
 }) {
-  const mediaFailed = externalVideoBackdrop === "fallback";
+  const mediaFailed = externalVideoBackdrop === "fallback" || range.scene.templateId === "cinemaMedia" && !String(range.scene.variables.mediaUrl || "").trim();
   const recoveryTitle = mediaFailed && range.scene.templateId === "cinemaMedia" && typeof range.scene.variables.fallbackText === "string" ? range.scene.variables.fallbackText : void 0;
   const template = kit.getTemplate(recoveryTitle ? "chapterTitle" : range.scene.templateId);
   const duration = range.end - range.start;
@@ -285,6 +286,7 @@ function SceneLayer({
       audioMuted: mediaAudioMuted || !playing,
       audioVolume: mediaAudioVolume,
       preparingNarration,
+      onMediaError,
       children: /* @__PURE__ */ jsxs(
         "div",
         {
@@ -594,6 +596,7 @@ function VideoFrame({
                     kit,
                     config,
                     range: active,
+                    onMediaError: () => markMediaFailed(sceneReadinessKey(active.scene)),
                     progress,
                     motionProgress,
                     width: canvas.width,
@@ -640,6 +643,7 @@ function VideoFrame({
                     kit,
                     config,
                     range: active,
+                    onMediaError: () => markMediaFailed(sceneReadinessKey(active.scene)),
                     progress,
                     motionProgress,
                     width: canvas.width,

package/dist/{chunk-VVNZCY2U.js → chunk-Z2ZI5G7O.js}

@@ -1,7 +1,7 @@
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-LJR5VLEI.js";
+} from "./chunk-QZAZT44G.js";
 
 // src/visual-system/scene-templates/cinema-media.tsx
 import { jsx } from "react/jsx-runtime";

package/dist/{cinema-media-4JUYKPQI.js → cinema-media-3SIGVVCY.js}

@@ -1,11 +1,11 @@
 import {
   MediaScene,
   MediaSceneTemplate
-} from "./chunk-VVNZCY2U.js";
-import "./chunk-LJR5VLEI.js";
-import "./chunk-SI6CFFAA.js";
+} from "./chunk-Z2ZI5G7O.js";
+import "./chunk-QZAZT44G.js";
+import "./chunk-O6FBIB4L.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-YZZSWGC3.js";
+import "./chunk-OOBT4X46.js";
 export {
   MediaScene,
   MediaSceneTemplate

package/dist/{comparison-3QLMUC5V.js → comparison-VDGRWPB5.js}

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-UCXQORDZ.js";
-import "./chunk-LJR5VLEI.js";
-import "./chunk-SI6CFFAA.js";
+} from "./chunk-G5TYLTL5.js";
+import "./chunk-QZAZT44G.js";
+import "./chunk-O6FBIB4L.js";
 import {
   editorialLabel,
   fade
@@ -10,7 +10,7 @@ import {
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-YZZSWGC3.js";
+import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/comparison.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{editorial-timeline-IVE2P25N.js → editorial-timeline-QJU4JJWB.js}

@@ -1,13 +1,13 @@
 import {
   EditorialSurface
-} from "./chunk-UCXQORDZ.js";
-import "./chunk-LJR5VLEI.js";
-import "./chunk-SI6CFFAA.js";
+} from "./chunk-G5TYLTL5.js";
+import "./chunk-QZAZT44G.js";
+import "./chunk-O6FBIB4L.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-YZZSWGC3.js";
+import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/editorial-timeline.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{key-figure-APD56LCO.js → key-figure-YUAQW6OE.js}

@@ -1,8 +1,8 @@
 import {
   EditorialSurface
-} from "./chunk-UCXQORDZ.js";
-import "./chunk-LJR5VLEI.js";
-import "./chunk-SI6CFFAA.js";
+} from "./chunk-G5TYLTL5.js";
+import "./chunk-QZAZT44G.js";
+import "./chunk-O6FBIB4L.js";
 import {
   editorialLabel,
   fade
@@ -10,7 +10,7 @@ import {
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-YZZSWGC3.js";
+import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/key-figure.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{mobile-message-WLK3WY5B.js → mobile-message-ZMMTUDUQ.js}

@@ -1,15 +1,15 @@
 import {
   MediaScene
-} from "./chunk-VVNZCY2U.js";
-import "./chunk-LJR5VLEI.js";
+} from "./chunk-Z2ZI5G7O.js";
+import "./chunk-QZAZT44G.js";
 import {
   spring
-} from "./chunk-SI6CFFAA.js";
+} from "./chunk-O6FBIB4L.js";
 import {
   editorialFont
 } from "./chunk-4YM2M62S.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-YZZSWGC3.js";
+import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/mobile-message.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{quote-Z6YET5BO.js → quote-BB6UJT6L.js}

@@ -1,15 +1,15 @@
 import {
   EditorialSurface
-} from "./chunk-UCXQORDZ.js";
-import "./chunk-LJR5VLEI.js";
-import "./chunk-SI6CFFAA.js";
+} from "./chunk-G5TYLTL5.js";
+import "./chunk-QZAZT44G.js";
+import "./chunk-O6FBIB4L.js";
 import {
   fade
 } from "./chunk-4YM2M62S.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
-import "./chunk-YZZSWGC3.js";
+import "./chunk-OOBT4X46.js";
 
 // src/visual-system/scene-templates/quote.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/react.d.ts

@@ -3,7 +3,7 @@ import { CSSProperties, ReactElement, ReactNode } from 'react';
 import { b as VideoEvent } from './events-B4YCc4vc.js';
 import { b as VideoOrientation, e as VideoScene, c as Video, i as VideoStyleOptions } from './types-DdZw4GRQ.js';
 import { T as TemplateRegistry } from './kit-DrRpdn0p.js';
-import { V as VideoChatMode, a as VideoChatAskOptions, b as VideoChatMedia, c as VideoChatSuggestion, d as VideoChatCapabilities, e as VideoChatWelcome } from './types-CdBmNTGD.js';
+import { V as VideoChatMode, a as VideoChatAskOptions, b as VideoChatMedia, c as VideoChatSuggestion, d as VideoChatCapabilities, e as VideoChatWelcome } from './types-BqB8zC9u.js';
 import './catalog-types-WTbLP6Jh.js';
 
 type VideoPlaybackMode = "manual" | "muted-autoplay" | "autoplay-with-sound" | "autoplay-after-interaction";
@@ -185,6 +185,8 @@ interface VideoChatTurn {
     orientation: VideoOrientation;
     /** Generated footage keeps the orientation it was created in. */
     fixedOrientation: boolean;
+    /** Footage source selected for this answer; omitted in older saved turns. */
+    mode?: VideoChatMode;
     video?: Video;
     suggestions: readonly VideoChatSuggestion[];
 }