@vanillaskyai/video 0.10.3 → 0.10.4

package/dist/server.js

@@ -895,15 +895,16 @@ var object = (value) => value && typeof value === "object" && !Array.isArray(val
 function text(value, maximum) {
   return typeof value === "string" && value.trim().length <= maximum ? value.trim() : "";
 }
-function readShot(value) {
+function readShot(value, clipDurationSec) {
   const item = object(value);
   const narration = text(item?.narration, 2e3);
   if (!narration) throw new Error("Chat shot requires bounded authored narration");
   return {
     narration,
+    title: text(item?.title, 65) || text(item?.subject, 65) || "The next step",
     subject: text(item?.subject, 80),
     action: text(item?.action, 600),
-    durationSec: typeof item?.durationSec === "number" && Number.isFinite(item.durationSec) ? Math.min(5, Math.max(2, item.durationSec)) : 5,
+    durationSec: typeof item?.durationSec === "number" && Number.isFinite(item.durationSec) ? Math.min(clipDurationSec, Math.max(2, item.durationSec)) : clipDurationSec,
     continuity: item?.continuity === "continue" ? "continue" : "cut"
   };
 }
@@ -916,12 +917,13 @@ function replaceStream(source, textStream) {
   });
 }
 function createChatShotPlanner(options) {
+  const clipDurationSec = options.generatedClipDurationSec ?? 5;
   const incomplete = /* @__PURE__ */ new WeakSet();
   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 five seconds; give each spoken beat room to finish.`,
+        `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"}.`,
         "USER REQUEST AND CONVERSATION",
         context.request.input.input
@@ -952,7 +954,7 @@ function createChatShotPlanner(options) {
           return { type: "scene.add", ...closer ? { placement: "closer" } : {}, scene: {
             id: `${context.request.requestId}-shot-${++index}`,
             templateId: "cinemaMedia",
-            variables: { mediaType: "video", mediaKeyword: shot.subject, shotDirection: [
+            variables: { fallbackText: shot.title, mediaType: "video", mediaKeyword: shot.subject, shotDirection: [
               brief?.visualDirection,
               shot.action,
               shot.continuity === "continue" ? "Continue the established subject, setting and action consistently." : "A deliberate new shot; choose framing that reveals this beat.",
@@ -971,7 +973,7 @@ function createChatShotPlanner(options) {
             brief = { opening: text(part.opening, 300), subject: text(part.subject, 80), visualDirection: text(part.visualDirection, 600), development: text(part.development, 2e3) };
             if (part.ending) {
               try {
-                brief.ending = readShot(part.ending);
+                brief.ending = readShot(part.ending, clipDurationSec);
               } catch (cause) {
                 reject(cause);
               }
@@ -981,10 +983,10 @@ function createChatShotPlanner(options) {
           }
           if (part?.type !== "shot") throw new Error("Chat plan requires an answer brief followed by shots");
           if (!brief) throw new Error("Chat shot arrived before its answer brief");
-          const shot = readShot(part);
+          const shot = readShot(part, clipDurationSec);
           if (shot.narration === brief.ending?.narration) return;
           if (firstBody && !continueAfterOpening(shot.narration, [options.openingLine ?? brief.opening])) return;
-          const budget = (context.request.input.maxDurationSec ?? 40) - (brief.ending?.durationSec ?? 5);
+          const budget = (context.request.input.maxDurationSec ?? 40) - (brief.ending?.durationSec ?? clipDurationSec);
           if (bodyDuration + shot.durationSec > budget) throw new Error("Chat shot exceeds the answer duration budget");
           bodyDuration += shot.durationSec;
           return scenePart(shot);
@@ -1051,6 +1053,7 @@ async function* resolveShots(parts, context, options) {
   let notify, space;
   const resolve = async (part) => {
     if (part.type !== "scene.add") return part;
+    options.prepareScene?.({ sceneId: part.scene.id, narration: part.scene.narration ?? "" });
     const { mediaKeyword } = part.scene.variables;
     let media;
     if (typeof mediaKeyword === "string" && mediaKeyword && options.resolveMedia) media = await options.resolveMedia(mediaKeyword, {
@@ -1063,8 +1066,9 @@ async function* resolveShots(parts, context, options) {
       signal: context.signal
     });
     context.signal.throwIfAborted();
-    if (!media) getGenerationLifecycleSink(context)?.reportWarning?.({ code: "provider_warning", category: "provider", message: "Some visuals are unavailable; narration continues.", recoverable: true });
-    const scene = { ...part.scene, variables: { mediaType: media?.type === "image" ? "photo" : "video", mediaUrl: media?.url ?? "", ...media?.posterUrl ? { mediaPoster: media.posterUrl } : {} } };
+    if (!media) getGenerationLifecycleSink(context)?.reportWarning?.({ code: "provider_warning", category: "provider", message: MEDIA_RECOVERY_NOTICE, recoverable: true });
+    const title = part.scene.variables.fallbackText;
+    const scene = media ? { ...part.scene, variables: { fallbackText: title, mediaType: media.type === "image" ? "photo" : "video", mediaUrl: media.url, ...media.posterUrl ? { mediaPoster: media.posterUrl } : {} } } : { ...part.scene, templateId: "chapterTitle", variables: { title } };
     return { ...part, scene };
   };
   const producer = (async () => {
@@ -1112,16 +1116,16 @@ async function* resolveShots(parts, context, options) {
 }
 
 // src/server/video-chat-prompts.ts
-function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlreadyProvided = false, maxGeneratedVideos = 5) {
+function createVideoChatResponseInstructions(generatedVideoAvailable, openingAlreadyProvided = false, maxGeneratedVideos = 5, clipDurationSec = 5, mode = "cinematic") {
   return [
     "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":"a short inviting spoken introduction of 6\u20139 words","subject":"literal visual subject","development":"the essential development of this answer","visualDirection":"consistent subjects, appearance and visual approach","ending":{"narration":"the authored payoff","subject":"literal subject","action":"visible action or change","durationSec":5,"continuity":"cut|continue"}}.',
-    'Then stream each developing shot on its own line: {"type":"shot","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":5,"continuity":"cut|continue"}.',
-    `The host permits at most ${generatedVideoAvailable ? maxGeneratedVideos : 0} generated-video attempts for this response. ${generatedVideoAvailable ? "Generated footage is preferred." : "Generated footage is unavailable."} Relevant stock is the fallback and may only depict a literal filmable subject; some requested visuals may be unavailable. Preserve the complete answer rather than shortening it to fit credits. The host selects providers; do not make source choices.`,
+    `First write one brief: {"type":"answer","intent":"explanation|story|comedy|imagination|practical","opening":"a short inviting spoken introduction of 6\u20139 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"}}.`,
+    `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. Preserve the full answer rather than shortening it to fit credits. The host selects providers; do not make source choices.`,
     "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 extra fields.",
     "Every shot uses moving footage with separate narration and subtitles. Generated footage is silent: do not ask its subjects to speak or render words. No headline cards or on-screen explanatory text.",
-    "Each clip has at most five seconds. Write spoken beats that fit naturally, usually 8\u201310 words per five-second shot. Split longer ideas across purposeful shots, preserving facts and qualifiers. Never truncate a claim to meet a word target. Use only the shots needed within the total duration, including the ending; do not pad to a fixed count.",
+    `Each clip has at most ${clipDurationSec} seconds. Write spoken beats that fit naturally, usually ${Math.floor(clipDurationSec * 1.6)}\u2013${Math.floor(clipDurationSec * 2)} words per shot. Split longer ideas across purposeful shots, preserving facts and qualifiers. Never truncate a claim to meet a word target. Use only the shots needed within the total duration, including the ending; do not pad to a fixed count.`,
     "Identify the full answer and its ending before developing shots. Each action must support what is said: camera movement alone is not progression. Vary scale, viewpoint and meaningful details while keeping subjects consistent.",
     "Explanations: clarify the actual causal mechanism, separating physical cause from a metaphor. Generated cutaways and animation illustrate ideas; they are not factual evidence. Preserve uncertainty, quantities and conditions; never invent evidence or quotations.",
     "Stories: portray characters making choices and experiencing consequences; use consistent character descriptions and an earned resolution, not a promised next scene.",
@@ -1221,8 +1225,8 @@ function parseResponseRequest(value) {
   const body = record2(value, "request");
   allowedKeys2(body, ["prompt", "opening", "mode", "orientation", "conversation", "style"], "request");
   const mode = body.mode ?? "cinematic";
-  if (mode !== "cinematic") {
-    throw new Error("request.mode must be cinematic");
+  if (mode !== "cinematic" && mode !== "pexels") {
+    throw new Error("request.mode must be cinematic or pexels");
   }
   const orientation = body.orientation ?? "landscape";
   if (orientation !== "portrait" && orientation !== "landscape") {
@@ -1308,7 +1312,25 @@ function resequenceEvent(event, sequence) {
     eventId: `${event.runId}:${sequence}`
   };
 }
-function streamVideoChatOpening(response, openingReady) {
+var VIDEO_CHAT_PREPARATION_EVENT_TYPE = "data.video-chat-preparation";
+function createPreparationChannel() {
+  let wake;
+  const channel = {
+    queue: [],
+    changed: new Promise((resolve) => {
+      wake = resolve;
+    }),
+    publish(value) {
+      channel.queue.push(value);
+      wake();
+      channel.changed = new Promise((resolve) => {
+        wake = resolve;
+      });
+    }
+  };
+  return channel;
+}
+function streamVideoChatOpening(response, openingReady, preparations, cancel) {
   if (!response.body || !response.headers.get("content-type")?.includes("text/event-stream")) return response;
   const events = decodeVideoSse(response.body)[Symbol.asyncIterator]();
   const encoded = (async function* () {
@@ -1324,7 +1346,8 @@ function streamVideoChatOpening(response, openingReady) {
             ...first.value.data.capabilities,
             extensions: Array.from(/* @__PURE__ */ new Set([
               ...first.value.data.capabilities?.extensions ?? [],
-              VIDEO_CHAT_OPENING_EVENT_TYPE
+              VIDEO_CHAT_OPENING_EVENT_TYPE,
+              VIDEO_CHAT_PREPARATION_EVENT_TYPE
             ]))
           }
         }
@@ -1347,10 +1370,28 @@ function streamVideoChatOpening(response, openingReady) {
         });
         sequence += 1;
       }
-      let next = await nextEvent;
-      while (!next.done) {
-        yield encodeVideoSseEvent(resequenceEvent(next.value, sequence++));
-        next = await events.next();
+      let pending = nextEvent;
+      while (true) {
+        while (preparations.queue.length) {
+          const data = preparations.queue.shift();
+          yield encodeVideoSseEvent({
+            protocolVersion: first.value.protocolVersion,
+            runId: first.value.runId,
+            sequence,
+            eventId: `${first.value.runId}:${sequence}`,
+            type: VIDEO_CHAT_PREPARATION_EVENT_TYPE,
+            data
+          });
+          sequence += 1;
+        }
+        const next = await Promise.race([
+          pending.then((value) => ({ value })),
+          preparations.changed.then(() => void 0)
+        ]);
+        if (!next || preparations.queue.length) continue;
+        if (next.value.done) break;
+        yield encodeVideoSseEvent(resequenceEvent(next.value.value, sequence++));
+        pending = events.next();
       }
     } finally {
       await events.return?.(void 0);
@@ -1376,6 +1417,7 @@ function streamVideoChatOpening(response, openingReady) {
       }
     },
     async cancel() {
+      cancel();
       completed = true;
       await iterator.return?.();
     }
@@ -1440,7 +1482,8 @@ function createVideoChatHandler(options) {
     allowCredentials,
     mediaConcurrency = 5,
     maxGeneratedVideos = 5,
-    generateVideoTimeoutMs = 15e3
+    generateVideoTimeoutMs = 15e3,
+    generatedClipDurationSec = 5
   } = options;
   const videoOptions = {
     templates: options.templates,
@@ -1456,6 +1499,7 @@ function createVideoChatHandler(options) {
   if (!Number.isFinite(maxAudioBytes) || maxAudioBytes <= 0) throw new Error("maxAudioBytes must be positive");
   if (!Number.isFinite(maxBodyBytes) || maxBodyBytes <= 0) throw new Error("maxBodyBytes must be positive");
   if (!Number.isSafeInteger(generateVideoTimeoutMs) || generateVideoTimeoutMs < 1 || generateVideoTimeoutMs > 12e4) throw new Error("generateVideoTimeoutMs must be an integer from 1 to 120000");
+  if (!Number.isFinite(generatedClipDurationSec) || generatedClipDurationSec < 2 || generatedClipDurationSec > 20) throw new Error("generatedClipDurationSec must be from 2 to 20");
   if (!Number.isSafeInteger(maxGeneratedVideos) || maxGeneratedVideos < 0) throw new Error("maxGeneratedVideos must be a nonnegative safe integer");
   const capabilities2 = {
     templates: true,
@@ -1463,17 +1507,41 @@ function createVideoChatHandler(options) {
     generatedVideo: generateVideo != null,
     stockMedia: searchMedia != null,
     transcription: transcribe != null,
-    modes: ["cinematic"]
+    modes: searchMedia ? ["cinematic", "pexels"] : ["cinematic"]
   };
   const welcomePrompts = (welcomeOptions?.prompts ?? DEFAULT_WELCOME_PROMPTS).slice(0, 4);
   const heroQuery = welcomeOptions?.heroQuery;
   let welcomeResponse;
   let requestSequence = 0;
-  const responseHandler = (requestId, openingProvided, openingChannel, openingLine) => {
-    const generatedVideoAvailable = generateVideo != null && maxGeneratedVideos > 0;
+  const responseHandler = (requestId, openingProvided, openingChannel, openingLine, mode, preparations) => {
+    const startedAt = Date.now();
+    const diagnose = (event) => {
+      try {
+        void Promise.resolve(options.onDiagnostic?.({ requestId, mode, elapsedMs: Math.max(0, Date.now() - startedAt), ...event })).catch(() => void 0);
+      } catch {
+      }
+    };
+    diagnose({ phase: "request-accepted" });
+    const generatedVideoAvailable = mode === "cinematic" && generateVideo != null && maxGeneratedVideos > 0;
     let lifecycle;
     let generatedAttempts = 0;
+    let mediaStartedAt;
+    let mediaIndex = 0;
     const resolveSelected = generateVideo || searchMedia ? async (query, context) => {
+      mediaStartedAt ??= Date.now();
+      const remainingMs = mediaStartedAt + generateVideoTimeoutMs + mediaIndex++ * generatedClipDurationSec * 1e3 - Date.now();
+      if (remainingMs <= 0) {
+        diagnose({ phase: "media-skipped", sceneId: context.scene.id, reason: "deadline" });
+        return null;
+      }
+      if (mode === "cinematic" && (!generateVideo || generatedAttempts >= maxGeneratedVideos)) {
+        diagnose({ phase: "media-skipped", sceneId: context.scene.id, reason: !generateVideo ? "not-configured" : "allowance" });
+        return null;
+      }
+      if (mode === "pexels" && !searchMedia) {
+        diagnose({ phase: "media-skipped", sceneId: context.scene.id, reason: "not-configured" });
+        return null;
+      }
       const mediaContext = {
         purpose: "response",
         orientation: context.input.orientation ?? "landscape",
@@ -1487,6 +1555,8 @@ function createVideoChatHandler(options) {
       const attempt = async (resolver, timeoutMs) => {
         context.signal.throwIfAborted();
         if (!resolver) return null;
+        const mediaStart = Date.now();
+        diagnose({ phase: "media-start", sceneId: context.scene.id });
         try {
           const result = sanitizeVideoChatMedia(await withDeadline(
             (signal) => resolver(query, { ...mediaContext, signal }),
@@ -1494,15 +1564,27 @@ function createVideoChatHandler(options) {
             context.signal
           ));
           context.signal.throwIfAborted();
+          diagnose({
+            phase: "media-end",
+            sceneId: context.scene.id,
+            durationMs: Math.max(0, Date.now() - mediaStart),
+            reason: result && (result.type === "video" || options.templates && resolver === searchMedia) ? "ready" : "empty"
+          });
           return result;
         } catch (cause) {
+          diagnose({
+            phase: "media-end",
+            sceneId: context.scene.id,
+            durationMs: Math.max(0, Date.now() - mediaStart),
+            reason: context.signal.aborted ? "cancelled" : cause instanceof DOMException && cause.name === "TimeoutError" ? "timeout" : "provider-error"
+          });
           context.signal.throwIfAborted();
           reportError(cause);
           return null;
         }
       };
       if (generatedVideoAvailable && (!options.templates || context.scene.variables.mediaSource === "generate")) {
-        const generated = generatedAttempts < maxGeneratedVideos ? (generatedAttempts++, await attempt(generateVideo, generateVideoTimeoutMs)) : null;
+        const generated = generatedAttempts < maxGeneratedVideos ? (generatedAttempts++, await attempt(generateVideo, remainingMs)) : null;
         if (generated?.type === "video") return generated;
         lifecycle?.reportWarning?.({
           code: "provider_warning",
@@ -1511,7 +1593,8 @@ function createVideoChatHandler(options) {
           recoverable: true
         });
       }
-      const stock = await attempt(searchMedia, 3e3);
+      if (mode !== "pexels") return null;
+      const stock = await attempt(searchMedia, Math.min(3e3, remainingMs));
       if (stock && (options.templates || stock.type === "video")) return stock;
       return null;
     } : void 0;
@@ -1543,7 +1626,16 @@ function createVideoChatHandler(options) {
         },
         includeRawProviderData: videoOptions.includeRawProviderData,
         openingLine,
-        publishOpening: openingChannel.publish,
+        publishOpening: (opening) => {
+          if (opening) diagnose({ phase: "opening-authored" });
+          openingChannel.publish(opening);
+        },
+        prepareScene: (scene) => {
+          diagnose({ phase: "shot-authored", sceneId: scene.sceneId });
+          if (!resolveSelected) diagnose({ phase: "media-skipped", sceneId: scene.sceneId, reason: "not-configured" });
+          preparations.publish(scene);
+        },
+        generatedClipDurationSec,
         resolveMedia: resolveSelected,
         mediaConcurrency
       }),
@@ -1551,7 +1643,7 @@ function createVideoChatHandler(options) {
       allowedOrigins,
       allowCredentials,
       maxBodyBytes,
-      systemPrompt: [createVideoChatResponseInstructions(generatedVideoAvailable, openingProvided, maxGeneratedVideos), instructions?.trim()].filter(Boolean).join("\n\nAPPLICATION GUIDANCE\n")
+      systemPrompt: [createVideoChatResponseInstructions(generatedVideoAvailable, openingProvided, maxGeneratedVideos, generatedClipDurationSec, mode), instructions?.trim()].filter(Boolean).join("\n\nAPPLICATION GUIDANCE\n")
     });
     return handler;
   };
@@ -1677,12 +1769,14 @@ function createVideoChatHandler(options) {
       }
       const requestId = `video-chat-${Date.now()}-${requestSequence += 1}`;
       const openingChannel = createOpeningChannel(input.opening ? { line: input.opening, keyword: "" } : void 0);
+      const preparations = createPreparationChannel();
+      const cancellation = new AbortController();
       const forwardedHeaders = new Headers(request.headers);
       forwardedHeaders.delete("content-length");
       const videoRequest = new Request(request.url, {
         method: "POST",
         headers: forwardedHeaders,
-        signal: request.signal,
+        signal: AbortSignal.any([request.signal, cancellation.signal]),
         body: JSON.stringify({
           protocolVersion: VIDEO_PROTOCOL_VERSION,
           requestId,
@@ -1705,9 +1799,11 @@ function createVideoChatHandler(options) {
         requestId,
         input.opening != null,
         openingChannel,
-        input.opening
+        input.opening,
+        input.mode,
+        preparations
       )(videoRequest);
-      return streamVideoChatOpening(response, openingChannel.ready);
+      return streamVideoChatOpening(response, openingChannel.ready, preparations, () => cancellation.abort());
     }
     try {
       if (action === "opening-media") {

package/dist/{types-CdBmNTGD.d.ts → types-BqB8zC9u.d.ts}

@@ -1,4 +1,4 @@
-type VideoChatMode = "cinematic";
+type VideoChatMode = "cinematic" | "pexels";
 interface VideoChatConversationTurn {
     prompt: string;
     response?: string;

package/docs/concepts.md

@@ -23,7 +23,7 @@ trusted templates. It begins before the full plan is available and ends as an
 editable deterministic configuration.
 
 It is not an encoded video stream. The browser renders normal React components
-from validated scene instructions. The 0.1 SDK does not include MP4 or WebM
+from validated scene instructions. The SDK does not include MP4 or WebM
 encoding; pass the completed deterministic JSON to an application-owned render
 or export pipeline when an encoded file is required.
 
@@ -31,7 +31,7 @@ or export pipeline when an encoded file is required.
 
 The viewer sends a prompt with bounded completed conversation turns. The server
 adds trusted application `instructions`, template capabilities, and the selected
-cinematic mode. `VideoChat` options control style, orientation, and custom
+AI video or Pexels mode. `VideoChat` options control style, orientation, and custom
 templates. Exact facts belong in the authorized prompt or conversation; secrets
 and provider configuration stay on the server.
 

package/docs/development.md

@@ -0,0 +1,23 @@
+# Develop the chat experience
+
+Run `npm ci --no-audit`, then `npm run dev:chat`. The localhost HMR surface renders the actual SDK `VideoChat`, templates and server handler from source. It never loads provider credentials. Select an intent and fault condition in the development toolbar; use the chat's normal media-mode controls. The prompt box remains the real product UI.
+
+Offline answers are deterministic for explanation, story, comedy, imagination, practical steps and golf. They use local waterfall footage and a recorded timing cue, **not narration that matches the displayed script**. This harness is for loading, playback, controls and recovery. It cannot prove generated answer quality. Conditions cover ready, delayed footage, missing media, decode failure, speech failure, exhausted video allowance and request throttling. Browser speech may be used in the speech-failure condition.
+
+The toolbar labels source and fixture identity. It separates the first body surface from the first decoded moving-footage frame; the former is a renderer paint opportunity and can precede decode. Its bounded safe phase log records browser request/stream arrival phases, speech response completion, first speech, footage and buffer pauses. No prompts, narration, scene IDs or provider bodies are retained. Media start/end/skip reasons come from the handler’s separate host-only `onDiagnostic` callback, shown in the local terminal for offline fixtures; live hosts own that callback themselves. Stream arrival is not the server’s exact authorship timestamp. Local fixtures never fetch external footage or invoke a paid model. Mode boundaries, provider deadlines and host admission remain covered by their dedicated server and host suites.
+
+## Optional live host
+
+Set `VANILLASKY_CHAT_LIVE_ENDPOINT` to an application-owned video-chat endpoint before starting the harness. The toolbar then offers **Connect live endpoint (uses allowance)**. It stays offline until that explicit click. Live fetches include host cookies, subject to browser cookie policy. The host must allow credentialed requests from the localhost origin and provide its normal authorization; credentials and allowances stay with that application. This tool does not proxy secrets, reset limits, or retry generated answers. Capabilities and welcome requests may run as soon as you connect. Request only the bounded live examples needed to evaluate actual quality.
+
+## Fast checks
+
+`npm run check:chat` runs the harness/unit recovery cases, checks harness TypeScript and runs one Chromium recording with short footage looping under actual audio. Install Chromium once with `npx playwright install chromium`. The harness smoke additionally records submit-to-visible-chapter paint opportunity with a 200 ms warm-UI target. This is a browser animation-frame opportunity, not a physical display measurement. The target for the complete command is under a minute on a warm machine; the command reports its measured duration. It does not replace release checks or claim browser-wide/live-provider coverage.
+
+## One candidate for release verification
+
+`npm run verify:release` runs registry, lint, type, unit, acceptance, size, production dependency audit, API, packed-consumer, onboarding, provider and all existing browser checks. It builds and packs once into ignored `artifacts/chat-candidate/`, then sends the exact tarball and integrity to every consumer verifier. Each verifier still uses its independent clean install. Browser and provider compatibility remain independent gates; no paid API calls are enabled by this command.
+
+`candidate.json` records version, source commit, dirty-tree status, SHA-256 and npm integrity. A local candidate may include uncommitted work; it is never called a published artifact. `VANILLASKY_CANDIDATE_DIR` selects a different output directory. The command verifies but never publishes, merges or deploys. CI additionally retains the existing Node and React version checks.
+
+For one targeted consumer check, run `node scripts/chat-candidate.mjs`, then provide `VANILLASKY_PACKED_TARBALL`, `VANILLASKY_EXPECTED_INTEGRITY` and `VANILLASKY_EXPECTED_SHA256` from that manifest to an existing verifier. Do not repack between checks of the same candidate.

package/docs/getting-started.md

@@ -4,9 +4,9 @@
 
 The fastest VanillaSky integration is the complete, general-purpose video chat.
 It starts with a template introduction and browser voice. Add the video adapter
-and its server key for generated footage, plus reviewed stock for fallback.
+and its server key for generated footage, or choose Pexels for stock footage.
 Without a media provider, the answer retains narration and subtitles with an
-unavailable-visual state. Generated speech is optional.
+chapter template. Generated speech is optional.
 
 ## Create the app
 

package/docs/media-and-audio.md

@@ -8,21 +8,21 @@ all credentials out of React and the browser bundle.
 
 ## AI-first video answers
 
-The default chat shows an immediate template introduction while footage prepares,
-then moving video with narration and subtitles. The planner describes visible
-subjects and actions, adapting its direction to the request's intent. The runtime
-attempts generated footage first and uses relevant stock when generation is
-unavailable, denied by the host budget, or fails. It does not select body cards.
+The default chat displays the real chapter template immediately, then prepares
+speech and footage concurrently. Choose `mode: "cinematic"` for AI video or
+`mode: "pexels"` for stock. The UI labels these choices **AI video** and **Pexels**.
+Each mode uses only its selected media provider. A failure, exhausted video
+allowance, or missed deadline becomes an authored chapter with complete narration.
+The chapter retains narration and subtitles for the whole beat.
 
-The seven packaged templates remain available to custom compositions. Default
-chat body shots use `cinemaMedia` as the footage renderer, without extra headlines.
-If both media providers miss, the answer retains its narration and subtitles
-with an explicit unavailable-visual state rather than a text-slide replacement.
+## Pexels search
 
-## Reviewed stock
+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.
 
-Add `searchMedia` for relevant fallback footage, welcome covers, and follow-up
-cards:
+Applications can replace `searchMedia` with their own licensed catalog:
 
 ```ts
 createVideoChatHandler({
@@ -46,7 +46,7 @@ createVideoChatHandler({
 The planner emits a short semantic keyword, not a URL. The callback returns an
 application-approved image or video URL, and the SDK validates it before it
 reaches a scene. Return `null` when no licensed, safe, relevant asset exists;
-default chat retains the spoken answer when footage is unavailable. An explicit custom `templates` registry retains its structured planner,
+default chat displays an authored chapter while retaining the spoken answer. An explicit custom `templates` registry retains its structured planner,
 validation, and fallback contracts.
 
 For Pexels, keep `PEXELS_API_KEY` on the server, enforce a deadline, filter for
@@ -96,6 +96,19 @@ decision with a known budget.
 VanillaSky does not depend on a video model or storage service. The application
 owns the provider key, model, spend, generated bytes, retention, and delivery.
 
+### Timing and recovery
+
+Set `generatedClipDurationSec` to the duration your video adapter actually
+requests (default 5, supported range 2–20 seconds). Keep it aligned with provider
+settings and host spending limits. The planner fits natural spoken beats to that
+budget; measured audio determines the final scene timing. Silent footage may
+loop until the finite scene ends. Audible footage is not looped.
+
+`generateVideoTimeoutMs` sets the first-shot preparation budget (default 15 seconds).
+Later deadlines account for their position in the answer rather than restarting
+an unlimited wait. Hosts must honor cancellation. A missed deadline selects the
+authored chapter instead of a second paid generation or cross-mode stock search.
+
 ## Voice and transcription
 
 Without `generateSpeech`, `VideoChat` uses the browser voice. Add a speech

package/docs/performance.md

@@ -20,6 +20,13 @@ The SDK sends nothing to a telemetry service. Events contain only an opaque
 turn ID, mode, relative timing, and fixed event categories. Keep custom turn IDs
 opaque; do not put prompts or customer information into them.
 
+The handler's optional `onDiagnostic(event)` observes accepted requests,
+authored openings and shots, and media start/end/skip timings on the host.
+Fixed reasons distinguish allowance, deadline, timeout, provider error, empty
+results, cancellation and absent configuration. These records contain no
+prompt, narration, query, media URL or provider response. They are never sent
+to the browser automatically, and callback failures cannot stop an answer.
+
 ## What the measurements mean
 
 `first-frame` is the first committed active scene reaching an animation-frame
@@ -55,15 +62,19 @@ these against an explicitly authorized, bounded live run before treating them
 as tuned provider budgets. Compare first-frame/speech times, stalled duration,
 and visual/voice quality together; faster fallback alone does not prove quality.
 
-## Opening stock footage
+## Opening and media preparation
+
+The submitted prompt immediately appears in the chapter template; the streamed
+opening replaces that topic with an authored spoken beat. The default UI makes
+no opening stock request. Each body beat starts speech preparation while its
+selected footage source prepares. At most two speech preparations run together.
 
-The opening's stock lookup runs alongside narration and body generation. Ready
-footage stays behind the hook until the body starts; late results are ignored.
-Playback never waits solely for intro footage.
+`first-media-frame` reports the first decoded footage frame presented by the
+mounted media surface. It is separate from `first-frame`, which also includes
+chapter scenes. Neither callback measures the immediate opening template;
+measure that surface separately when checking submit-to-template latency.
 
-The packaged stock adapter tries the specific and optional broader video query
-before photo recovery, within one three-second budget. The planner supplies the
-broader query only for opening atmosphere; body demonstrations retain their
-specific subject. Pexels resource-page slugs and photo descriptions can screen
-obvious mismatches, but missing metadata remains unknown and is accepted. This
-is not visual relevance verification. See the [Pexels API contract](https://www.pexels.com/api/documentation/).
+AI and Pexels modes remain separate. Missing, late, or unplayable footage uses
+the authored chapter and complete narration. Silent clips loop for the finite
+narrated scene. See [the local chat harness](development.md) for fixture timing
+and explicit live-provider checks.

package/docs/production.md

@@ -22,13 +22,11 @@ player. Read the [security guide](security.md) for the complete controls.
 
 ## Cinematic direction and providers
 
-Default chat uses a template introduction during preparation, then generated
-footage with narration and subtitles. Add `generateVideo` for these shots and
-`searchMedia` for relevant stock fallback. The runtime selects media within the
-host generation budget; the model supplies narration and visible actions.
-If both sources miss, valid narration remains available with an explicit visual
-unavailability state. Explicit custom template registries keep their existing
-composition and fallback contracts.
+Default chat shows an immediate chapter while speech and selected footage prepare.
+Configure `generateVideo` for AI mode and `searchMedia` for Pexels mode. Neither
+mode calls the other footage source. Missing or late footage uses the authored
+chapter with complete narration. Explicit custom template registries keep their
+existing composition and fallback contracts.
 A stock candidate must match the subject, action and permitted crop. Return
 `null` for uncertainty rather than broadening an essential detail.
 
@@ -39,11 +37,11 @@ licensing before use.
 
 ## Fast first response
 
-The planner's first streamed object supplies the spoken hook and media keyword.
-Start speech immediately, resolve stock in parallel, and keep the opening
-playing until the contiguous preparation cushion and first frame are ready. Welcome cards
-should carry a prepared hook and preloaded footage so they can start without a
-model round trip.
+The prompt appears immediately in the chapter template. The planner's first
+streamed object supplies an authored spoken opening and reserves the ending.
+Prepare each shot's speech alongside its footage, and keep the opening readable
+until its narration and the contiguous preparation cushion are ready. Welcome
+cards may carry a prepared opening so its speech starts without a model round trip.
 
 Do not wait for the complete plan before showing the first validated scene.
 Preload upcoming assets and keep the current visual if the next one is late.
@@ -106,7 +104,7 @@ npm test
 - [ ] Keys exist only in the server secret store.
 - [ ] Authentication, tenant policy, rate limits, and origin allowlist are live.
 - [ ] Cancellation, timeouts, fallbacks, and safe errors are tested.
-- [ ] Grounded graphic recovery works when every optional provider is unavailable.
+- [ ] Authored chapter recovery works when every optional provider is unavailable.
 - [ ] Per-scene media choices obey provider availability and spending limits.
 - [ ] Both orientations render and narration stays synchronized.
 - [ ] A packed-artifact consumer and deterministic browser chat pass.

package/docs/prompt-and-input.md

@@ -96,9 +96,9 @@ Every `scene.add` is validated before the browser receives it. The model never
 returns React, HTML, CSS, or executable JavaScript. Invalid planning content
 produces safe diagnostics. A media failure does not delete valid narration.
 
-Generated footage is preferred within the host's allowance. Relevant stock is
-fallback. If neither is available, retain narration and subtitles and report
-unavailable visuals. Handlers configured with an explicit custom `templates` registry continue to
+AI mode generates footage within the host allowance. Pexels mode searches
+stock without calling the video generator. Each authored beat includes a short
+chapter title; missing footage becomes that chapter with its complete narration. Handlers configured with an explicit custom `templates` registry continue to
 support the trusted catalog and its existing structured planner contract.
 
 ## Grounding