@vanillaskyai/video 0.7.1 → 0.8.1

package/dist/{chunk-LKBZX7GV.js → chunk-PP3MCPN4.js}

@@ -3,7 +3,7 @@ function createBackgroundMediaSchemaProperties(options = {}) {
   const mediaKeyword = {
     type: "string",
     title: "Background search keyword",
-    description: "2-4 word English term for Pexels stock-footage search (auto-fills mediaUrl).",
+    description: "2-4 word English term for stock-media search (auto-fills mediaUrl).",
     ...options.stockMediaKeyword === false ? {} : { format: "stock-media-keyword" },
     default: ""
   };
@@ -26,7 +26,7 @@ function createBackgroundMediaSchemaProperties(options = {}) {
     mediaPoster: {
       type: "string",
       title: "Background poster image",
-      description: "Still image URL shown while a video backdrop is decoding its first frame. Auto-filled from Pexels' thumbnail when fillPexelsUrls sets a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50\u2013400ms gap between a <video> mounting and decoding its first frame.",
+      description: "Still image URL shown while a video backdrop is decoding its first frame. A media resolver can supply a poster alongside a video mediaUrl. Hides the gradient flash that would otherwise appear in the ~50\u2013400ms gap between a <video> mounting and decoding its first frame.",
       format: "uri",
       default: ""
     },
@@ -84,7 +84,7 @@ var BUILTIN_TEMPLATE_SCHEMAS = {
       "reactionTag": {
         "type": "string",
         "title": "Reaction tag",
-        "description": "Pexels meme search intent. Pick from the punchline/problem copy first, then the overall video topic.",
+        "description": "Stock-media search intent. Pick from the punchline/problem copy first, then the overall video topic.",
         "enum": [
           "launch",
           "productLaunch",
@@ -125,7 +125,7 @@ var BUILTIN_TEMPLATE_SCHEMAS = {
       "mediaUrl": {
         "type": "string",
         "title": "Reaction clip",
-        "description": "Resolved Pexels MP4 URL.",
+        "description": "Resolved stock-video URL.",
         "format": "uri",
         "default": ""
       },

package/dist/chunk-ZD2VTUYR.js

@@ -0,0 +1,28 @@
+import {
+  getReadableSceneDuration
+} from "./chunk-3O7OMMMF.js";
+
+// src/protocol/scene-duration.ts
+var NARRATION_WORDS_PER_SECOND = 2.6;
+var NARRATION_TAIL_SECONDS = 0.6;
+function getSceneDurationBounds(scene, metadata) {
+  return {
+    minimum: Math.max(1e-3, metadata?.minDuration ?? 1),
+    readable: getReadableSceneDuration(scene, metadata)
+  };
+}
+function getSpokenDuration(narration) {
+  const words = narration.trim().split(/\s+/u).filter(Boolean).length;
+  if (words === 0) return 0;
+  return words / NARRATION_WORDS_PER_SECOND + NARRATION_TAIL_SECONDS;
+}
+function getSceneDuration(scene, metadata) {
+  const { readable } = getSceneDurationBounds(scene, metadata);
+  return Math.max(readable, scene.narration ? getSpokenDuration(scene.narration) : 0);
+}
+
+export {
+  getSceneDurationBounds,
+  getSpokenDuration,
+  getSceneDuration
+};

package/dist/cli.js

@@ -8,14 +8,14 @@ import {
 import {
   getBuiltinTemplateMetadata,
   listBuiltinTemplateMetadata
-} from "./chunk-JNN3EYVP.js";
+} from "./chunk-4UNKZEAT.js";
 import "./chunk-3O7OMMMF.js";
 import {
   assertTemplateTransitionMetadata
 } from "./chunk-2E6T633S.js";
 import {
   BUILTIN_TEMPLATE_MANIFEST
-} from "./chunk-LKBZX7GV.js";
+} from "./chunk-PP3MCPN4.js";
 import {
   externalVideoBackdropCapabilitySource
 } from "./chunk-WJ6FLKNC.js";
@@ -1629,6 +1629,10 @@ async function initVideoChatApp(options) {
   for (const path of SCAFFOLD_FILES) {
     planned.set(path, readFileSync2(join8(starterRoot, path), "utf8"));
   }
+  const providersPath = safeProjectPath(cwd, "providers.ts");
+  if (!existsSync3(providersPath)) {
+    planned.set("providers.ts", readFileSync2(join8(starterRoot, "providers.ts"), "utf8"));
+  }
   planned.set("package.json", mergedManifest(cwd, starterRoot, options.sdkSpec));
   planned.set(".gitignore", mergeGitignore(
     existsSync3(join8(cwd, ".gitignore")) ? readFileSync2(join8(cwd, ".gitignore"), "utf8") : void 0
@@ -1651,7 +1655,6 @@ async function initVideoChatApp(options) {
     }
     throw new Error(`${path} already exists with different content. Run init in a new npm project.`);
   }
-  if (!changed) return { initialized: false, installed: false };
   for (const [path, contents] of planned) {
     const destination = safeProjectPath(cwd, path);
     if (!existsSync3(destination) || readFileSync2(destination, "utf8") !== contents) atomicWrite(destination, contents);
@@ -1662,16 +1665,89 @@ async function initVideoChatApp(options) {
     const detail = cause instanceof Error ? cause.message : String(cause);
     throw new Error(`${detail}. The app files are ready; run npm install to finish setup.`);
   }
-  return { initialized: true, installed: true };
+  return { initialized: changed, installed: true };
+}
+
+// src/cli/providers.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync as renameSync3, unlinkSync as unlinkSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname4, join as join9 } from "path";
+var PROVIDERS = {
+  speech: { dependency: "@ai-sdk/xai", version: "^4.0.52", key: "XAI_API_KEY", export: "speechProvider" },
+  video: { dependency: "@fal-ai/client", version: "1.10.1", key: "FAL_KEY", export: "videoProvider" }
+};
+function registry(enabled) {
+  const imports = enabled.map((name) => `import { ${PROVIDERS[name].export} } from "./providers/${name}";`).join("\n");
+  const value = enabled.length ? `{
+${enabled.map((name) => `  ...${PROVIDERS[name].export},`).join("\n")}
+}` : "{}";
+  return `import type { VideoChatHandlerOptions } from "@vanillaskyai/video/server";
+${imports ? `${imports}
+` : ""}
+export const providers: Pick<VideoChatHandlerOptions, "generateSpeech" | "generateVideo" | "transcribe"> = ${value};
+`;
+}
+async function addVideoChatProvider(name, options) {
+  if (name !== "speech" && name !== "video") throw new Error("Choose a provider capability: speech or video.");
+  const manifestPath = safeProjectPath(options.cwd, "package.json");
+  const registryPath = safeProjectPath(options.cwd, "providers.ts");
+  if (!existsSync4(manifestPath) || !existsSync4(registryPath)) throw new Error("Run vanillasky init before adding providers.");
+  const manifest = JSON.parse(readFileSync3(manifestPath, "utf8"));
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new Error("Expected an application package.json object.");
+  const config = manifest.vanillasky ?? {};
+  if (!config || typeof config !== "object" || Array.isArray(config)) throw new Error("Expected vanillasky configuration to be an object.");
+  const previous = config.providers ?? [];
+  if (!Array.isArray(previous) || previous.some((value) => value !== "speech" && value !== "video") || new Set(previous).size !== previous.length) {
+    throw new Error("Invalid vanillasky.providers configuration.");
+  }
+  const enabled = [...previous].sort();
+  if (readFileSync3(registryPath, "utf8") !== registry(enabled)) {
+    throw new Error("providers.ts has custom wiring. Preserve it and add the provider manually, or restore the generated wiring before using this command.");
+  }
+  const adapterPath = safeProjectPath(options.cwd, `providers/${name}.ts`);
+  const adapter = readFileSync3(join9(options.starterRoot ?? locateStarterRoot(), "providers", `${name}.ts`), "utf8");
+  if (!enabled.includes(name) && existsSync4(adapterPath) && readFileSync3(adapterPath, "utf8") !== adapter) {
+    throw new Error(`providers/${name}.ts already contains customer source; no files were changed.`);
+  }
+  const dependencies = manifest.dependencies ?? {};
+  if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies)) throw new Error("Expected dependencies to be an object.");
+  if (!enabled.includes(name)) enabled.push(name);
+  enabled.sort();
+  const provider = PROVIDERS[name];
+  manifest.dependencies = { ...dependencies, [provider.dependency]: dependencies[provider.dependency] ?? provider.version };
+  manifest.vanillasky = { ...config, providers: enabled };
+  const writes = /* @__PURE__ */ new Map([
+    [manifestPath, `${JSON.stringify(manifest, null, 2)}
+`],
+    [registryPath, registry(enabled)]
+  ]);
+  if (!existsSync4(adapterPath)) writes.set(adapterPath, adapter);
+  const staged = [...writes].map(([path, contents]) => ({ path, contents, temporary: safeProjectPath(options.cwd, `${path.slice(options.cwd.length + 1)}.${randomUUID3()}.tmp`) }));
+  for (const { path, contents, temporary } of staged) {
+    mkdirSync3(dirname4(path), { recursive: true });
+    writeFileSync3(temporary, contents, { flag: "wx" });
+    try {
+      renameSync3(temporary, path);
+    } finally {
+      if (existsSync4(temporary)) unlinkSync3(temporary);
+    }
+  }
+  try {
+    await (options.installDependencies ?? defaultInstall)(options.cwd);
+  } catch {
+    throw new Error(`Provider files are ready. Rerun npx vanillasky providers add ${name} to finish installation.`);
+  }
+  return `Enabled ${name}. Add ${provider.key} to .env.local, then restart npm run dev.`;
 }
 
 // src/cli/doctor.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
-import { join as join9, resolve as resolve8 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { join as join10, resolve as resolve8 } from "path";
 var REQUIRED_FILES = [
   ".env.local",
   "index.html",
   "server.ts",
+  "providers.ts",
   "src/main.tsx",
   "stock.ts",
   "tsconfig.json",
@@ -1680,11 +1756,15 @@ var REQUIRED_FILES = [
 var REQUIRED_DEPENDENCIES = [
   "@vanillaskyai/video",
   "@ai-sdk/anthropic",
-  "@ai-sdk/xai",
-  "@fal-ai/client",
   "ai",
   "react",
-  "react-dom"
+  "react-dom",
+  "@types/node",
+  "@types/react",
+  "@types/react-dom",
+  "@vitejs/plugin-react",
+  "typescript",
+  "vite"
 ];
 var PROVIDER_KEYS = /* @__PURE__ */ new Set(["ANTHROPIC_API_KEY", "XAI_API_KEY", "FAL_KEY", "PEXELS_API_KEY"]);
 var CLIENT_ENV_PREFIXES = ["VITE", "NEXT_PUBLIC"].map((prefix) => `${prefix}_`);
@@ -1717,14 +1797,14 @@ function doctorVideoChatApp(cwdInput) {
   const lines = [];
   let ok = true;
   for (const path of REQUIRED_FILES) {
-    if (!existsSync4(join9(cwd, path))) {
+    if (!existsSync5(join10(cwd, path))) {
       ok = false;
       lines.push(`MISSING  ${path}`);
     }
   }
   let manifest = {};
   try {
-    const parsed = JSON.parse(readFileSync3(join9(cwd, "package.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync4(join10(cwd, "package.json"), "utf8"));
     if (!isJsonObject(parsed)) throw new Error("expected an object");
     manifest = parsed;
   } catch {
@@ -1737,17 +1817,22 @@ function doctorVideoChatApp(cwdInput) {
     ok = false;
     lines.push(`MISSING  dependency ${name}`);
   }
+  const installed = (name) => existsSync5(join10(cwd, "node_modules", name, "package.json"));
+  for (const name of REQUIRED_DEPENDENCIES.filter((name2) => dependencies[name2] && !installed(name2))) {
+    ok = false;
+    lines.push(`NOT INSTALLED  ${name} \u2014 run npm install`);
+  }
   const scripts = stringMap2(manifest.scripts);
   if (scripts.dev !== "vite" || scripts.build !== "tsc && vite build") {
     ok = false;
     lines.push("MISSING  video-chat dev/build scripts");
   }
-  const ignore = existsSync4(join9(cwd, ".gitignore")) ? readFileSync3(join9(cwd, ".gitignore"), "utf8") : "";
+  const ignore = existsSync5(join10(cwd, ".gitignore")) ? readFileSync4(join10(cwd, ".gitignore"), "utf8") : "";
   if (!effectivelyIgnoresLocalEnvironment(ignore)) {
     ok = false;
     lines.push("UNSAFE   .env.local is not ignored");
   }
-  const environment = existsSync4(join9(cwd, ".env.local")) ? parseEnvironment(readFileSync3(join9(cwd, ".env.local"), "utf8")) : /* @__PURE__ */ new Map();
+  const environment = existsSync5(join10(cwd, ".env.local")) ? parseEnvironment(readFileSync4(join10(cwd, ".env.local"), "utf8")) : /* @__PURE__ */ new Map();
   for (const name of environment.keys()) {
     if (CLIENT_ENV_PREFIXES.some((prefix) => name.startsWith(prefix) && PROVIDER_KEYS.has(name.slice(prefix.length)))) {
       ok = false;
@@ -1760,10 +1845,23 @@ function doctorVideoChatApp(cwdInput) {
     ok = false;
     lines.push("MISSING  ANTHROPIC_API_KEY in .env.local");
   }
-  lines.push(environment.get("XAI_API_KEY") ? "READY    generated speech" : "OPTIONAL generated speech \u2014 add XAI_API_KEY");
-  lines.push(environment.get("FAL_KEY") ? "READY    generated video + transcription" : "OPTIONAL generated video + transcription \u2014 add FAL_KEY");
+  const configuration = isJsonObject(manifest.vanillasky) ? manifest.vanillasky : {};
+  const enabled = Array.isArray(configuration.providers) ? configuration.providers : [];
+  for (const provider of [
+    { id: "speech", label: "generated speech", dependency: "@ai-sdk/xai", key: "XAI_API_KEY" },
+    { id: "video", label: "generated video + transcription", dependency: "@fal-ai/client", key: "FAL_KEY" }
+  ]) {
+    const configured = enabled.includes(provider.id) && existsSync5(join10(cwd, "providers.ts")) && existsSync5(join10(cwd, "providers", `${provider.id}.ts`)) && dependencies[provider.dependency] && installed(provider.dependency);
+    if (!configured) {
+      lines.push(`OPTIONAL ${provider.label} \u2014 run npx vanillasky providers add ${provider.id}`);
+    } else if (!environment.get(provider.key)) {
+      lines.push(`OPTIONAL ${provider.label} \u2014 add ${provider.key} to .env.local`);
+    } else {
+      lines.push(`READY    ${provider.label}`);
+    }
+  }
   lines.push(environment.get("PEXELS_API_KEY") ? "READY    stock media" : "OPTIONAL stock media \u2014 add PEXELS_API_KEY");
-  if (existsSync4(join9(cwd, "vanillasky", "templates"))) {
+  if (existsSync5(join10(cwd, "vanillasky", "templates"))) {
     lines.push("CHECK    custom templates with npx vanillasky templates check");
   }
   return { ok, lines };
@@ -1777,6 +1875,7 @@ function help() {
     "Usage:",
     "  vanillasky init",
     "  vanillasky doctor",
+    "  vanillasky providers add <speech|video>",
     "  vanillasky templates <command>",
     "",
     "Template commands:",
@@ -1848,14 +1947,22 @@ function runVanillaSkyCli(argv, environment = {}) {
           sdkSpec: environment.sdkSpec ?? process.env.npm_config_package,
           installDependencies: environment.installDependencies
         });
-        if (!result.initialized) {
-          write("Video chat is already initialized.");
-          return 0;
-        }
-        write("Video chat initialized with packaged templates and browser voice.");
-        write("Add ANTHROPIC_API_KEY to .env.local.");
-        write("Then run: npm run dev");
-        write("Check setup: npx vanillasky doctor");
+        write(result.initialized ? "Video chat initialized with packaged templates and browser voice." : "Video chat is already initialized; dependencies checked.");
+        const health = doctorVideoChatApp(cwd);
+        health.lines.forEach(write);
+        write(health.ok ? "Ready. Run: npm run dev" : health.lines.some((line) => line === "MISSING  ANTHROPIC_API_KEY in .env.local") ? "Add ANTHROPIC_API_KEY to .env.local. Then run: npm run dev" : "Next: fix the missing setup items above, then run npm run dev.");
+        return 0;
+      } catch (error) {
+        write(error instanceof Error ? error.message : String(error));
+        return 1;
+      }
+    })();
+  }
+  if (rootCommand === "providers") {
+    return (async () => {
+      try {
+        if (rootArgs.length !== 2 || rootArgs[0] !== "add") throw new Error("Usage: vanillasky providers add <speech|video>");
+        write(await addVideoChatProvider(rootArgs[1], { cwd, starterRoot: environment.starterRoot, installDependencies: environment.installDependencies }));
         return 0;
       } catch (error) {
         write(error instanceof Error ? error.message : String(error));

package/dist/{compose-video-PD6LKKRK.js → compose-video-2NFH4DZY.js}

@@ -1,10 +1,10 @@
 import {
   createVideo
-} from "./chunk-RE4IMWJR.js";
+} from "./chunk-3VRMKFM7.js";
 import "./chunk-E7CL7UPB.js";
-import "./chunk-GAIOHGNR.js";
+import "./chunk-2OKB27TG.js";
 import "./chunk-MMUXVA47.js";
-import "./chunk-2PYO6VAC.js";
+import "./chunk-2DOLF4QN.js";
 import "./chunk-AOWSXU2K.js";
 import "./chunk-3O7OMMMF.js";
 import "./chunk-XGRA2MUV.js";

package/dist/{events-B6qS1Lsb.d.ts → events-BQ6z264n.d.ts}

@@ -1,4 +1,4 @@
-import { b as VideoOrientation, V as VideoStyle, c as Video, a as VideoCapabilities, d as VideoAudio, e as VideoScene, f as VIDEO_PROTOCOL_VERSION } from './types-2wHBqtg8.js';
+import { b as VideoOrientation, V as VideoStyle, c as Video, a as VideoCapabilities, d as VideoAudio, e as VideoScene, f as VIDEO_PROTOCOL_VERSION } from './types-CEh9eUFu.js';
 
 type VideoWarningCategory = "validation" | "readability" | "grounding" | "provider" | "media" | "protocol";
 type VideoWarningCode = "scene_duration_adjusted" | "scene_omitted_unreadable" | "scene_omitted_for_closer" | "scene_variable_clipped" | "chart_scale_imbalance" | "plan_incomplete" | "plan_missing_closer" | "provider_warning" | "provider_diagnostics_unavailable" | "media_budget_reached";

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { c as Video, h as VideoBrandInput, i as VideoBrand, e as VideoScene, d as VideoAudio, V as VideoStyle, b as VideoOrientation, j as VideoTemplatePacing } from './types-2wHBqtg8.js';
-export { k as VideoBackground, g as VideoInput, l as VideoKnowledgeMode, m as VideoStyleOptions, n as VideoSuppliedMedia } from './types-2wHBqtg8.js';
-export { V as VideoStatus } from './state-DZcKuS32.js';
-import { b as VideoEvent } from './events-B6qS1Lsb.js';
+import { c as Video, h as VideoBrandInput, i as VideoBrand, e as VideoScene, j as VideoTemplatePacing } from './types-CEh9eUFu.js';
+export { d as VideoAudio, k as VideoBackground, b as VideoOrientation, V as VideoStyle, l as VideoStyleOptions } from './types-CEh9eUFu.js';
+
+type VideoStatus = "idle" | "streaming" | "complete" | "error" | "aborted";
 
 type VideoValidationErrorCode = "invalid_video" | "unsupported_video_version";
 declare class VideoValidationError extends Error {
@@ -15,68 +15,6 @@ declare function getVideoDuration(config: Video): number;
 
 declare function resolveVideoBrand(input?: VideoBrandInput): VideoBrand;
 
-/**
- * Compose a playable video from scenes the host builds itself.
- *
- * `VideoInput.opening` is a single line of copy, so an application that wants
- * several scenes of its own before the generated ones has nowhere to put them.
- * Handing the player a fresh `video` prop is not an answer either: that resets
- * playback to zero on every change, so a video that grows replays its opening
- * each time something is appended. The player's `stream` prop appends, and this
- * builds a stream.
- *
- * The reason it belongs here rather than in each application is that the
- * envelope rules are exact and their failure is silent. `response.start` must
- * be sequence zero, every event exactly one higher, `eventId` exactly
- * `${runId}:${sequence}`, `scene.add.position` the index the scene lands at,
- * and the completion snapshot must reproduce what the reducer built. Miss any
- * one and the whole stream is rejected: the player renders nothing, and the
- * console stays clean.
- */
-interface SceneTimeline {
-    /**
-     * Hand this to the player's `stream` prop once. Never swap it: a new stream
-     * is a new video, and playback restarts.
-     */
-    stream: AsyncIterable<VideoEvent>;
-    /** Append a scene. Ignored once the timeline has completed. */
-    add(scene: VideoScene): void;
-    /**
-     * Say what the soundtrack is, or that there is none.
-     *
-     * Only meaningful with `awaitAudio`, where it releases the scenes held back
-     * while the track was unknown. Calling it twice, or after the first scene has
-     * been emitted, does nothing.
-     */
-    setAudio(audio: VideoAudio | undefined): void;
-    /** Finish the video. Safe to call more than once. */
-    complete(): void;
-}
-interface SceneTimelineOptions {
-    style: VideoStyle;
-    orientation?: VideoOrientation;
-    /**
-     * The soundtrack, when it is already known.
-     *
-     * Use `awaitAudio` instead when it is resolved by a request that has not
-     * answered yet.
-     */
-    audio?: VideoAudio;
-    /**
-     * Hold scenes until `setAudio` is called.
-     *
-     * `audio.set` is only valid before the first scene, so a timeline that opens
-     * with host-built scenes cannot add a soundtrack afterwards - the event
-     * arrives too late and the video plays silently, with nothing to show for it.
-     * Holding the openings costs the wait for the track to resolve, not the wait
-     * for the video to be planned.
-     */
-    awaitAudio?: boolean;
-    requestId?: string;
-    runId?: string;
-}
-declare function createSceneTimeline(options: SceneTimelineOptions): SceneTimeline;
-
 interface SceneDurationBounds {
     /**
      * The least this scene survives being shown for.
@@ -100,4 +38,4 @@ declare function getSceneDurationBounds(scene: Pick<VideoScene, "variables">, me
 declare function getSpokenDuration(narration: string): number;
 declare function getSceneDuration(scene: Pick<VideoScene, "variables" | "narration">, metadata: VideoTemplatePacing | undefined): number;
 
-export { type SceneDurationBounds, type SceneTimeline, type SceneTimelineOptions, Video, VideoAudio, VideoBrand, VideoBrandInput, VideoOrientation, VideoScene, VideoStyle, VideoValidationError, type VideoValidationErrorCode, createSceneTimeline, getSceneDuration, getSceneDurationBounds, getSpokenDuration, getVideoDuration, parseVideo, resolveVideoBrand };
+export { type SceneDurationBounds, Video, VideoBrand, VideoBrandInput, VideoScene, type VideoStatus, VideoValidationError, type VideoValidationErrorCode, getSceneDuration, getSceneDurationBounds, getSpokenDuration, getVideoDuration, parseVideo, resolveVideoBrand };

package/dist/index.js

@@ -1,13 +1,12 @@
 import {
-  createSceneTimeline,
   getSceneDuration,
   getSceneDurationBounds,
   getSpokenDuration
-} from "./chunk-SKRGRKHY.js";
+} from "./chunk-ZD2VTUYR.js";
 import {
   VideoValidationError,
   parseVideo
-} from "./chunk-2PYO6VAC.js";
+} from "./chunk-2DOLF4QN.js";
 import "./chunk-AOWSXU2K.js";
 import "./chunk-3O7OMMMF.js";
 import {
@@ -18,7 +17,6 @@ import {
 } from "./chunk-XGRA2MUV.js";
 export {
   VideoValidationError,
-  createSceneTimeline,
   getSceneDuration,
   getSceneDurationBounds,
   getSpokenDuration,

package/dist/{kit-8g46H2RZ.d.ts → kit-tQnCPMOM.d.ts}

@@ -1,4 +1,4 @@
-import { V as VideoStyle, a as VideoCapabilities } from './types-2wHBqtg8.js';
+import { V as VideoStyle, a as VideoCapabilities } from './types-CEh9eUFu.js';
 import { ComponentType } from 'react';
 import { S as SceneTemplateMetadata, d as TemplateJsonSchema, f as TemplateJsonSchemaProperty } from './catalog-types-BIhSpOWK.js';
 

package/dist/react.d.ts

@@ -1,10 +1,9 @@
 import * as react from 'react';
 import { CSSProperties, ReactElement, ReactNode } from 'react';
-import { b as VideoEvent, V as VideoWarning } from './events-B6qS1Lsb.js';
-import { b as VideoOrientation, c as Video, e as VideoScene, g as VideoInput, h as VideoBrandInput, m as VideoStyleOptions } from './types-2wHBqtg8.js';
-import { T as TemplateRegistry } from './kit-8g46H2RZ.js';
-import { V as VideoStatus } from './state-DZcKuS32.js';
-import { c as VideoChatMode, e as VideoChatAskOptions, f as VideoChatMedia, g as VideoChatSuggestion, a as VideoChatCapabilities, h as VideoChatWelcome } from './types-DrABlRa7.js';
+import { b as VideoEvent } from './events-BQ6z264n.js';
+import { b as VideoOrientation, c as Video, e as VideoScene, h as VideoBrandInput, l as VideoStyleOptions } from './types-CEh9eUFu.js';
+import { T as TemplateRegistry } from './kit-tQnCPMOM.js';
+import { V as VideoChatMode, a as VideoChatAskOptions, b as VideoChatMedia, c as VideoChatSuggestion, d as VideoChatCapabilities, e as VideoChatWelcome } from './types-DWFO6qca.js';
 import './catalog-types-BIhSpOWK.js';
 
 type VideoPlaybackMode = "manual" | "muted-autoplay" | "autoplay-with-sound" | "autoplay-after-interaction";
@@ -62,6 +61,10 @@ interface VideoPlayerSharedProps {
     /** Fires when a streamed response has finished composing. */
     onComplete?: (video: Video) => void;
     onError?: (error: Error) => void;
+    /** First active scene committed, observed at the next animation frame; excludes idle posters. */
+    onFramePresented?: () => unknown;
+    /** Stream playback has reached its available scenes; excludes initial waiting and deliberate pauses. */
+    onStallChange?: (stalled: boolean) => unknown;
     /** Fires when the scene under the playhead changes, including on a loop wrap. */
     onSceneChange?: (scene: VideoScene, index: number) => void;
 }
@@ -94,33 +97,6 @@ declare class VideoError extends Error {
     constructor(message: string, options: VideoErrorOptions);
 }
 
-interface UseVideoOptions {
-    endpoint?: string | URL;
-    /** Customer-owned templates that replace matching built-ins and add new IDs. */
-    templates?: TemplateRegistry;
-    /** Templates the planner may select for this client experience. Renderers remain available for replay. */
-    templateIds?: readonly string[];
-    headers?: HeadersInit;
-    credentials?: RequestCredentials;
-    fetcher?: typeof fetch;
-    /** Override ID generation for tracing or deterministic tests. */
-    createRequestId?: () => string;
-}
-interface UseVideoResult {
-    /** Resolves with a completed video; rejects terminal errors and aborts. */
-    generate(input: VideoInput): Promise<Video>;
-    abort(reason?: string): void;
-    video?: Video;
-    status: VideoStatus;
-    error?: VideoError;
-    warnings: readonly VideoWarning[];
-    /** Spread into an explicitly rendered VideoPlayer. */
-    playerProps: VideoPlayerProps & {
-        video?: never;
-    };
-}
-declare function useVideo(options?: UseVideoOptions): UseVideoResult;
-
 /**
  * Say a video's narration as it plays.
  *
@@ -143,31 +119,14 @@ interface NarrationVoice {
      *
      * The signal aborts when the scene changes, when the viewer interrupts, or
      * when the player goes away. Stop speaking promptly: talking over the next
-     * scene is worse than being cut off.
+     * scene is worse than being cut off. Report onStart only when speech actually
+     * begins playing; leave it uncalled when onset cannot be observed.
      */
     speak(text: string, options: {
         signal: AbortSignal;
+        onStart?: (source?: "browser" | "generated") => void;
     }): void | Promise<void>;
 }
-interface NarrationOptions {
-    voice: NarrationVoice;
-    /** Say nothing at all while false. Defaults to true. */
-    enabled?: boolean;
-}
-interface Narration {
-    /**
-     * Hand this to the player's `onSceneChange`.
-     *
-     * The player already reports which scene is showing, which is the only cue a
-     * narrator needs, so nothing here has to run its own clock.
-     */
-    onSceneChange: (scene: VideoScene, index: number) => void;
-    /** Stop the current line. Nothing is said again until the next scene. */
-    interrupt: () => void;
-    /** Whether a line is being spoken right now. */
-    speaking: boolean;
-}
-declare function useNarration(options: NarrationOptions): Narration;
 
 interface VideoChatPreparedSpeech {
     /** Measured or conservatively estimated spoken duration, in seconds. */
@@ -188,6 +147,8 @@ interface CreateVideoChatVoiceOptions {
     credentials?: RequestCredentials;
     fetcher?: typeof fetch;
     maxCachedLines?: number;
+    /** Called when optional generated speech falls back to browser speech. */
+    onFallback?: () => unknown;
 }
 /**
  * Create the SDK's generated-speech client with a browser-voice fallback.
@@ -204,6 +165,8 @@ interface VideoChatTurn {
     /** True only after the complete response has been received. */
     completed: boolean;
     opening?: string;
+    /** Concise notices for recovered optional failures. */
+    warnings?: readonly string[];
     /** Optional stock footage held behind the opening hook until playback starts. */
     openingMedia?: VideoChatMedia;
     orientation: VideoOrientation;
@@ -231,7 +194,23 @@ interface UseVideoChatOptions {
     createTurnId?: () => string;
     /** Observe how long a fresh response takes to display its first actual scene. */
     onFirstFrame?: (metric: VideoChatFirstFrameMetric) => unknown;
+    /** Local observations only; no automatic telemetry or prompt/provider data. */
+    onPlaybackMetric?: (metric: VideoChatPlaybackMetric) => unknown;
 }
+type VideoChatPlaybackMetric = {
+    turnId: string;
+    mode: VideoChatMode;
+    elapsedMs: number;
+} & ({
+    type: "first-frame";
+} | {
+    type: "first-speech";
+    source: "browser" | "generated" | "custom";
+} | {
+    type: "stall";
+    durationMs: number;
+    reason: "scene-generation";
+});
 interface VideoChatFirstFrameMetric {
     turnId: string;
     mode: VideoChatMode;
@@ -252,6 +231,7 @@ interface UseVideoChatResult {
     welcome?: VideoChatWelcome;
     availableModes: readonly VideoChatMode[];
     status: VideoChatStatus;
+    warnings: readonly string[];
     error?: VideoError;
     suggestions: readonly VideoChatSuggestion[];
     caption?: string;
@@ -280,4 +260,4 @@ interface VideoChatProps {
 /** A complete voice-and-video chat interface backed by createVideoChatHandler. */
 declare function VideoChat({ options, className, welcomeTitle }: VideoChatProps): react.JSX.Element;
 
-export { type CreateVideoChatVoiceOptions, type Narration, type NarrationOptions, type NarrationVoice, type UseVideoChatOptions, type UseVideoChatResult, type UseVideoOptions, type UseVideoResult, VideoChat, VideoChatAskOptions, VideoChatCapabilities, type VideoChatFirstFrameMetric, VideoChatMedia, VideoChatMode, type VideoChatPreparedSpeech, type VideoChatProps, type VideoChatStatus, VideoChatSuggestion, type VideoChatTurn, type VideoChatVoice, VideoChatWelcome, VideoError, type VideoErrorOptions, type VideoPlaybackMode, VideoPlayer, type VideoPlayerProps, createVideoChatVoice, useNarration, useVideo, useVideoChat };
+export { type CreateVideoChatVoiceOptions, type UseVideoChatOptions, type UseVideoChatResult, VideoChat, VideoChatAskOptions, VideoChatCapabilities, type VideoChatFirstFrameMetric, VideoChatMedia, VideoChatMode, type VideoChatPlaybackMetric, type VideoChatPreparedSpeech, type VideoChatProps, type VideoChatStatus, VideoChatSuggestion, type VideoChatTurn, type VideoChatVoice, VideoChatWelcome, VideoError, type VideoErrorOptions, type VideoPlaybackMode, VideoPlayer, type VideoPlayerProps, createVideoChatVoice, useVideoChat };