@vanillaskyai/video 0.10.23 → 0.11.0

package/README.md

@@ -1,20 +1,20 @@
-# Give your AI a voice and a face
+# Video answers for your AI chat
 
 [![CI](https://github.com/VanillaSkyAi/video/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/VanillaSkyAi/video/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@vanillaskyai/video.svg)](https://www.npmjs.com/package/@vanillaskyai/video)
-[![runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](package.json)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
-**VanillaSky is the open-source voice-and-video chat layer.** Add a polished,
-general-purpose AI conversation that speaks and starts playing visual answers
-while they are still being composed.
+VanillaSky is an open-source React SDK for spoken video conversations. A short
+chapter introduction starts the answer while footage prepares; narrated clips
+then play in order as the response is generated.
 
-> **Status: Beta.** VanillaSky is pre-1.0 and its public API may change as we
-> test it in real applications. Pin an exact version before production use.
+Your application owns models, keys, authentication, storage, and spending.
+VanillaSky owns the chat interface, shot-planning prompts, streaming, validation,
+voice timing, and playback. The core has no runtime dependencies.
 
-Your application owns the providers, keys, authentication, persistence,
-branding, and product copy. VanillaSky owns the chat flow, planning prompts,
-trusted templates, validation, streaming, voice timing, and player.
+Pre-1.0 beta, distributed through npm with [best-effort support](SUPPORT.md).
+Pin an exact version and use its matching docs; an unreleased checkout is not
+the published package. Review [breaking changes](CHANGELOG.md) before upgrading.
 
 ## Start on localhost
 
@@ -22,7 +22,7 @@ trusted templates, validation, streaming, voice timing, and player.
 npx @vanillaskyai/video init
 ```
 
-Init installs the baseline dependencies and runs doctor automatically. Add
+The default starter uses the optional Vercel AI SDK text adapter. Add
 `ANTHROPIC_API_KEY` to the generated, ignored `.env.local`, then run:
 
 ```bash
@@ -30,42 +30,16 @@ npx vanillasky doctor
 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 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.
+Prefer native callbacks? Use `init --native` in a new directory and configure
+`GEMINI_API_KEY`; that starter needs neither `ai` nor `@ai-sdk/anthropic`.
+Both are application examples, not SDK requirements.
 
-Optional upgrades keep the same client:
-
-| Add | Setup command | Server-only key |
-| --- | --- | --- |
-| Generated speech | `npx vanillasky providers add speech` | `XAI_API_KEY` |
-| Generated video and voice transcription | `npx vanillasky providers add video` | `FAL_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
-readiness by key name and never prints values. Provider SDKs remain application
-dependencies, outside the core package.
-
-For coding agents:
-
-```bash
-npx skills add VanillaSkyAi/video@vanillasky
-```
-
-Then prompt: `Use $vanillasky to set up and verify a general-purpose video chat in this project.`
-
-## What init creates
-
-The generated application is a thin, editable shell:
-
-- `src/main.tsx` mounts the complete SDK-owned `<VideoChat />` interface;
-- `server.ts` connects app-owned text, speech, transcription, stock, and video
-  providers through one `createVideoChatHandler`;
-- `vite.config.ts` serves the UI and the single `/api/video-chat` endpoint;
-- `.env.local` holds server-only keys and is ignored by Git.
-
-The UI stays this small:
+One text key gives you chat, chapter introductions, subtitles, and browser voice.
+Add stock or generated footage through app-owned adapters. fal, Google, and
+Runway references are included; any vendor can implement the same callback.
+Direct video generation also requires your storage/delivery callback.
+See [Getting started](docs/getting-started.md) for the complete setup and
+[Provider integration](docs/provider-integration.md) for the adapter boundary.
 
 ```tsx
 import { VideoChat } from "@vanillaskyai/video/react";
@@ -76,62 +50,44 @@ export function App() {
 }
 ```
 
-The default interface puts video behind a floating conversation field, with
-on-video subtitles and contextual controls. See the [immersive interface guide](docs/immersive-interface.md)
-for behavior and [customization](docs/customization.md) for application branding.
-
-Use `useVideoChat` when you want a custom interface while keeping the SDK-owned
-conversation and playback lifecycle. Edit the generated server when you want a
-different provider. The [provider guide](docs/provider-integration.md) explains
-both boundaries.
-
-## An immediate intro, then moving footage
-
-The default chat uses a template introduction while its first shot prepares,
-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.
+Use `useVideoChat` to build your own interface, and `parseVideo` with
+`VideoPlayer` to replay completed responses. Changing a provider does not
+require changing the React client.
 
-Speech and footage prepare together. Silent clips loop through the remaining
-narration when necessary, and every answer preserves its intended ending.
+Already have an assistant? The optional server `resolveAnswer` callback turns
+its completed answer into the source for the video, while your application
+keeps retrieval, tools and answer policy. See [existing-assistant integration](docs/provider-integration.md#use-an-existing-assistant).
 
-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 chapterTitle
-```
+## How it works
 
-That compiler is needed only for source-owned templates. See
-[Custom templates](docs/custom-templates.md).
+The model streams an answer brief and shot directions, not component code.
+Footage generation overlaps browser-owned speech preparation. The server
+announces prepared media early and streams validated scenes in order. AI-video mode never silently
+substitutes stock; stock mode never spends on generated video. A failed or late
+clip becomes a narrated chapter. Narration targets a 0.8-second visual tail;
+one short rewrite may fit an oversized beat before generation. If it still
+does not fit, the complete original narration plays over a chapter. Footage
+plays once at native speed; unexpected overruns recover to a chapter without
+cutting off the sentence.
 
-## Go deeper
+This is progressive **scene** delivery, not real-time frames from every vendor.
+Some generation APIs take minutes; preloading cannot remove that latency.
+Evaluate the model, voice and delivery path you actually deploy.
 
-Completed chat responses are deterministic JSON and can be stored and replayed.
-MP4/WebM export remains application-owned.
+The supported visual vocabulary is deliberately small: footage and chapter
+introductions/fallbacks. There is no template-authoring CLI, renderer plugin
+system, or hosted service dependency.
 
 ## Documentation
 
-| Goal | Guide |
-| --- | --- |
-| Run the complete chat | [Getting started](docs/getting-started.md) |
-| Set it up with a coding agent | [Agent integration guide](docs/agent-integration.md) |
-| Change or add providers | [Provider integration](docs/provider-integration.md) |
-| Customize the interface | [Customization](docs/customization.md) |
-| Understand prompts and grounding | [Prompt and input](docs/prompt-and-input.md) |
-| 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) |
-
-Try a keyless template response in the
-[playground](https://vanillasky.ai/playground/), or visit
-[vanillasky.ai](https://vanillasky.ai/).
-
-Apache-2.0
+- [Agent integration](docs/agent-integration.md) and the optional
+  [integration skill](https://github.com/VanillaSkyAi/video/blob/main/skills/vanillasky/SKILL.md)
+- [Provider integration](docs/provider-integration.md), [adapter reference](docs/reference/provider-adapters.md), and [media and voice](docs/media-and-audio.md)
+- [Customization](docs/customization.md) and [prompt guidance](docs/prompt-and-input.md)
+- [Persistence and replay](docs/persistence.md), [protocol](docs/reference/protocol.md), and [testing](docs/testing.md)
+- [Performance](docs/performance.md), [production](docs/production.md), [security](docs/security.md), and [errors](docs/errors.md)
+- [Architecture](docs/architecture.md), [development](docs/development.md), and [contributing](https://github.com/VanillaSkyAi/video/blob/main/CONTRIBUTING.md)
+
+Node 22+; React 18 or 19. The four code entry points are the root package,
+`/server`, `/react`, and `/test`, plus the scoped `/video-chat.css` stylesheet.
+See the [public API contract](PUBLIC-API.md).

package/dist/builtin-metadata-OT6V7TB4.js

@@ -0,0 +1,8 @@
+import {
+  SCENE_DEFINITIONS,
+  getBuiltinSceneDefinition
+} from "./chunk-NM4CXXZY.js";
+export {
+  SCENE_DEFINITIONS,
+  getBuiltinSceneDefinition
+};

package/dist/{chapter-title-2JVDU62E.js → chapter-title-2RCXX7SN.js}

@@ -1,7 +1,6 @@
 import {
   TitleSceneTemplate
-} from "./chunk-7AA2JWHZ.js";
-import "./chunk-4YM2M62S.js";
+} from "./chunk-5DOQTIMD.js";
 export {
   TitleSceneTemplate
 };

package/dist/{chunk-PDQFQIQW.js → chunk-3EQ6PVWL.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-E7CL7UPB.js";
 import {
   parseVideoPlanPart
-} from "./chunk-7M56IUUX.js";
+} from "./chunk-6Z3ID54H.js";
 
 // src/server/model/truncated-json.ts
 function isConfidentlyTruncatedJson(source) {

package/dist/chunk-4G4JBMCM.js

@@ -0,0 +1,37 @@
+// src/video-chat/deadline.ts
+function withDeadline(operation, timeoutMs, parent) {
+  return new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    let settled = false;
+    const timer = setTimeout(() => finish({ error: new DOMException("Optional work exceeded its deadline", "TimeoutError") }), timeoutMs);
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      parent?.removeEventListener("abort", cancel);
+      if ("error" in result) {
+        reject(result.error);
+        controller.abort(result.error);
+      } else {
+        resolve(result.value);
+        controller.abort();
+      }
+    };
+    const cancel = () => finish({ error: parent?.reason ?? new DOMException("Cancelled", "AbortError") });
+    if (parent?.aborted) {
+      cancel();
+      return;
+    }
+    parent?.addEventListener("abort", cancel, { once: true });
+    try {
+      const result = operation(controller.signal);
+      Promise.resolve(result).then((value) => finish({ value }), (error) => finish({ error }));
+    } catch (error) {
+      finish({ error });
+    }
+  });
+}
+
+export {
+  withDeadline
+};

package/dist/{chunk-7AA2JWHZ.js → chunk-5DOQTIMD.js}

@@ -1,15 +1,15 @@
-import {
-  editorialFont,
-  fade
-} from "./chunk-4YM2M62S.js";
-
 // src/visual-system/scene-templates/chapter-title.tsx
 import { jsx } from "react/jsx-runtime";
+var editorialFont = '-apple-system, BlinkMacSystemFont, "Helvetica Neue", Roboto, Arial, sans-serif';
+function ease(value) {
+  const t = Math.max(0, Math.min(1, value));
+  return t * t * (3 - 2 * t);
+}
 function TitleScene({ variables, width, height, progress, motionProgress }) {
   const title = String(variables.title ?? "A different perspective");
   const unit = Math.min(width, height);
   const presentation = motionProgress ?? progress;
-  const opacity = fade(presentation / 0.22) * (1 - fade((presentation - 0.76) / 0.24));
+  const opacity = ease(presentation / 0.22) * (1 - ease((presentation - 0.76) / 0.24));
   return /* @__PURE__ */ jsx("div", { "data-template": "title", "data-title-treatment": "quiet-fade", style: { position: "absolute", inset: 0, background: "#000", color: "#fff", display: "flex", alignItems: "center", justifyContent: "center" }, children: /* @__PURE__ */ jsx("div", { "data-title-composition": "centered", style: { width: "76%", textAlign: "center", opacity, fontFamily: editorialFont, fontWeight: 500, fontSize: unit * 0.068, lineHeight: 1.18, letterSpacing: "-.025em", textWrap: "balance", overflowWrap: "anywhere" }, children: title }) });
 }
 var TitleSceneTemplate = TitleScene;

package/dist/chunk-666HGTVZ.js

@@ -0,0 +1,41 @@
+// src/visual-system/scene-templates/external-video-backdrop.tsx
+import React from "react";
+import { jsx } from "react/jsx-runtime";
+var DEFAULT = { mode: false, audioMuted: true, audioVolume: 1 };
+var sharedContext = globalThis;
+var BackdropContext = sharedContext.__vanillaskyVideoBackdropContext ??= React.createContext(DEFAULT);
+function ExternalVideoBackdropProvider({
+  mode,
+  audioMuted = true,
+  audioVolume = 1,
+  preparingNarration = false,
+  onMediaError,
+  children
+}) {
+  const value = React.useMemo(
+    () => ({ mode, audioMuted, audioVolume, preparingNarration, onMediaError }),
+    [mode, audioMuted, audioVolume, preparingNarration, onMediaError]
+  );
+  return /* @__PURE__ */ jsx(BackdropContext.Provider, { value, children });
+}
+function useExternalVideoBackdrop() {
+  return React.useContext(BackdropContext).mode;
+}
+function useMediaAudio() {
+  const { audioMuted, audioVolume } = React.useContext(BackdropContext);
+  return { muted: audioMuted, volume: audioVolume };
+}
+function useNarrationPreroll() {
+  return React.useContext(BackdropContext).preparingNarration === true;
+}
+function useMediaFailure() {
+  return React.useContext(BackdropContext).onMediaError;
+}
+
+export {
+  ExternalVideoBackdropProvider,
+  useExternalVideoBackdrop,
+  useMediaAudio,
+  useNarrationPreroll,
+  useMediaFailure
+};

package/dist/{chunk-7M56IUUX.js → chunk-6Z3ID54H.js}

@@ -33,22 +33,6 @@ function safePublicDiagnostic(value, fallback) {
   if (redacted.length <= MAX_PUBLIC_DIAGNOSTIC_LENGTH) return redacted;
   return `${redacted.slice(0, MAX_PUBLIC_DIAGNOSTIC_LENGTH - 1).trimEnd()}\u2026`;
 }
-function createClippedVariableWarning(templateId, fields) {
-  return {
-    code: "scene_variable_clipped",
-    category: VIDEO_WARNING_CATEGORIES.scene_variable_clipped,
-    message: `Trimmed ${fields.join(", ")} on ${templateId} to the length the template declares.`,
-    recoverable: true
-  };
-}
-function createMediaBudgetWarning(limit) {
-  return {
-    code: "media_budget_reached",
-    category: VIDEO_WARNING_CATEGORIES.media_budget_reached,
-    message: `Resolved media for ${limit} scene${limit === 1 ? "" : "s"}; later scenes keep their copy on the brand gradient.`,
-    recoverable: true
-  };
-}
 
 // src/protocol/json-validation.ts
 var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
@@ -361,8 +345,6 @@ function parseVideoPlanPart(value) {
 
 export {
   safePublicDiagnostic,
-  createClippedVariableWarning,
-  createMediaBudgetWarning,
   record,
   allowedKeys,
   string,

package/dist/{chunk-5BSJLT6H.js → chunk-E7FHBLAC.js}

@@ -1,16 +1,21 @@
-import {
-  attachGenerationLifecycleSink
-} from "./chunk-E7CL7UPB.js";
 import {
   applyVideoEvent,
   checksumVideo,
   createVideoEventFactory,
   createVideoState
-} from "./chunk-RXTN2CW6.js";
+} from "./chunk-Z3DLSLAJ.js";
+import {
+  getCloserReserve,
+  getReadableSceneDuration,
+  paceScene
+} from "./chunk-WZESNEPT.js";
+import {
+  attachGenerationLifecycleSink
+} from "./chunk-E7CL7UPB.js";
 import {
   parseVideoPlanPart,
   safePublicDiagnostic
-} from "./chunk-7M56IUUX.js";
+} from "./chunk-6Z3ID54H.js";
 import {
   MAX_RETAINED_INSTRUCTIONS_LENGTH,
   MAX_RETAINED_MEDIA_URLS,
@@ -22,11 +27,6 @@ import {
   VIDEO_SCHEMA_VERSION,
   createVideoRequest
 } from "./chunk-7NZOMTAL.js";
-import {
-  getCloserReserve,
-  getReadableSceneDuration,
-  paceScene
-} from "./chunk-3O7OMMMF.js";
 
 // src/replayable-stream.ts
 function createReplayableStream(source, onError) {
@@ -108,23 +108,11 @@ function buildVideoUserPrompt(input, openingDurationSec = 0) {
     "Compose a video response from the structured customer input below.",
     `Knowledge mode: ${input.knowledgeMode ?? "input-only"}.`,
     `Maximum duration: ${input.maxDurationSec ?? 30} seconds, including the supplied opening.`,
-    input.opening === false ? "The host owns the opening wait. Add the first grounded scene as soon as it is complete; it may use host-resolved media." : typeof input.opening === "string" && input.opening.trim() ? `The host has already added the opening scene, which consumes ${openingDurationSec} seconds. Continue after it and do not repeat or rewrite it.` : "Add the first grounded scene as soon as it is complete.",
-    ...input.opening === false ? [] : [
-      "The first generated body scene must be fully playable without external media. Use a content-fit text, data, comparison, list, or device-free template with no media URL or keyword.",
-      "Add that scene before resolving any stock or supplied asset. Resolve media as part of each complete later body scene."
-    ],
-    "Use only claims supported by the factual basis permitted by the trusted system prompt.",
-    "Develop the requested answer within the duration: preserve its mechanism, essential actions, story resolution or punchline. A short prompt can need several distinct visual beats; input length is not the answer length.",
-    "For a long source, summarize instead of attempting to represent every fact, unless the creative instructions explicitly request complete fact coverage that fits the duration.",
-    "When selecting claims from the raw input, preserve their exact wording and numbers. Preserve qualifiers, units, denominators, ranges, and comparison direction; for example, do not shorten 4.8 out of 5 to 4.8.",
-    "Choose the scene count from the requested intent, visual progression and duration budget. A joke can be brief; a practical sequence or imaginative story may need more development. Do not stop while an essential step or payoff is missing.",
-    "If the creative instructions explicitly require one separate scene per named item, release, section, or list entry, do not merge, group, or omit those required items. Keep related required scenes adjacent in a coherent progression while preserving each item as its own scene.",
-    "Before emitting, verify that the explicitly requested structure can fit readably within the maximum duration. If it cannot, preserve readability and the requested separation for the scenes that fit, then finish with plan.complete using finishReason length rather than silently changing the structure.",
-    "Before plan.complete, check that the answer fulfills the actual request. Do not mistake a hook and a single supporting statement for a complete explanation, or explain a joke after its punchline.",
-    "Emit exactly one final scene.add with placement closer. Land the requested ending without repeating the opening or implying another scene follows.",
-    "Reuse the same suitable template when it serves successive beats. Vary the subject action, shot scale, perspective or purposeful detail, not the template merely for variety.",
-    "Never add filler to satisfy a count or diversity target.",
-    input.suppliedMedia?.length ? input.opening === false ? "Select zero or more relevant opaque supplied-media references for visible scenes. Never invent or transform a reference. Only emit mediaKeyword when the trusted system catalog explicitly exposes it. Never invent mediaUrl or mediaPoster." : "Select zero or more relevant opaque supplied-media references for visible later scenes. Never invent or transform a reference. Only emit mediaKeyword when the trusted system catalog explicitly exposes it, and only on later scenes. Never invent mediaUrl or mediaPoster." : input.opening === false ? "No supplied media URL is available. Use asset-free templates unless the trusted system catalog explicitly permits host-resolved media intent, which may begin on the first scene. Only emit mediaKeyword when the trusted system catalog explicitly exposes it. Never invent mediaUrl or mediaPoster." : "No supplied media URL is available. Use asset-free templates unless the trusted system catalog explicitly permits host-resolved media intent. Only emit mediaKeyword when the trusted system catalog explicitly exposes it, and only on later scenes. Never invent mediaUrl or mediaPoster.",
+    input.opening === false ? "The host owns the opening wait. Add the first grounded scene as soon as it is complete." : `The host has already added the opening scene, which consumes ${openingDurationSec} seconds. Do not repeat it.`,
+    "Use cinemaMedia for resolved footage and chapterTitle for a chapter opening or recovery.",
+    "Use only claims supported by the factual basis permitted by the trusted system prompt. Preserve quantities, qualifications and the answer's conclusion.",
+    "Use only the supplied opaque media references or media resolved by the host. Never invent media URLs.",
+    "End with one closer scene and plan.complete; do not add filler.",
     "",
     "RAW INPUT",
     input.input.trim(),
@@ -691,7 +679,7 @@ function createVideo(rawInput, options) {
           position
         }));
       }
-      const systemPrompt = options.systemPrompt ?? (await import("./system-prompt-AG26KJAA.js")).createVideoSystemPrompt(input.knowledgeMode);
+      const systemPrompt = options.systemPrompt ?? "";
       const context = { request, systemPrompt, userPrompt, initialConfig, signal: controller.signal };
       attachGenerationLifecycleSink(context, lifecycle);
       for await (const untrustedPart of options.generate(context)) {
@@ -864,6 +852,5 @@ function createVideo(rawInput, options) {
 }
 
 export {
-  invokeIsolated,
   createVideo
 };

package/dist/chunk-HIQM4J3U.js

@@ -0,0 +1,30 @@
+import {
+  sanitizeVideoChatMedia
+} from "./chunk-ISWQ6T5X.js";
+
+// src/server/scene-validation.ts
+function validateBuiltinScene(scene) {
+  const variables = scene.variables;
+  const boundedText = (value, maximum) => typeof value === "string" && Boolean(value.trim()) && [...value].length <= maximum;
+  if (scene.templateId === "chapterTitle") {
+    if (!boundedText(variables.title, 65)) throw new Error("Chapter requires a title of 1\u201365 characters");
+    if (Object.keys(variables).some((key) => key !== "title")) throw new Error("Unsupported chapter variable");
+    return;
+  }
+  if (scene.templateId !== "cinemaMedia") throw new Error("Unsupported scene kind");
+  if (!sanitizeVideoChatMedia({
+    url: variables.mediaUrl,
+    type: variables.mediaType === "photo" ? "image" : variables.mediaType,
+    ...variables.mediaPoster ? { posterUrl: variables.mediaPoster } : {}
+  })) throw new Error("Media scene requires a safe media URL and type");
+  if (variables.fallbackText !== void 0 && !boundedText(variables.fallbackText, 65)) {
+    throw new Error("Media recovery title must contain 1\u201365 characters");
+  }
+  if (variables.mediaDurationSec !== void 0 && (typeof variables.mediaDurationSec !== "number" || !Number.isFinite(variables.mediaDurationSec) || variables.mediaDurationSec <= 0 || variables.mediaDurationSec > 3600)) throw new Error("Invalid media duration");
+  const allowed = /* @__PURE__ */ new Set(["mediaUrl", "mediaType", "mediaPoster", "fallbackText", "mediaDurationSec"]);
+  if (Object.keys(variables).some((key) => !allowed.has(key))) throw new Error("Unsupported media variable");
+}
+
+export {
+  validateBuiltinScene
+};

package/dist/chunk-ISWQ6T5X.js

@@ -0,0 +1,36 @@
+import {
+  MAX_RETAINED_MEDIA_URL_LENGTH
+} from "./chunk-AUPC6MDK.js";
+
+// src/video-chat/media.ts
+function sanitizeVideoChatMedia(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const media = value;
+  if (media.type !== "image" && media.type !== "video") return null;
+  if (typeof media.url !== "string") return null;
+  const url = media.url.trim();
+  if (!safeMediaUrl(url)) return null;
+  if (media.posterUrl != null && typeof media.posterUrl !== "string") return null;
+  const posterUrl = typeof media.posterUrl === "string" ? media.posterUrl.trim() : "";
+  if (posterUrl && !safeMediaUrl(posterUrl)) return null;
+  if (media.durationSec !== void 0 && (typeof media.durationSec !== "number" || !Number.isFinite(media.durationSec) || media.durationSec <= 0 || media.durationSec > 3600)) return null;
+  return {
+    url,
+    type: media.type,
+    ...posterUrl ? { posterUrl } : {},
+    ...typeof media.durationSec === "number" ? { durationSec: media.durationSec } : {}
+  };
+}
+function safeMediaUrl(value) {
+  if (!value || value.length > MAX_RETAINED_MEDIA_URL_LENGTH) return false;
+  try {
+    const protocol = new URL(value).protocol;
+    return protocol === "https:" || protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+export {
+  sanitizeVideoChatMedia
+};

package/dist/{chunk-224QNWRA.js → chunk-K5J7ESRO.js}

@@ -9,22 +9,13 @@ function isVideoUrl(url) {
     return VIDEO_EXTENSIONS.some((ext) => lower.endsWith(ext));
   }
 }
-function limitsConcurrentVideoDecoders() {
-  if (typeof navigator === "undefined") return false;
-  return /iPad|iPhone|iPod/.test(navigator.userAgent) || navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1;
-}
 function resolveMediaType(mediaType, mediaUrl) {
   if (mediaType === "gradient") return "gradient";
   if (mediaType === "video") return "video";
   if (mediaType === "photo") return "photo";
   return mediaUrl && isVideoUrl(mediaUrl) ? "video" : "photo";
 }
-function hasSceneMedia(variables) {
-  return String(variables.mediaUrl || "").trim() !== "" && String(variables.mediaType || "auto") !== "gradient";
-}
 
 export {
-  limitsConcurrentVideoDecoders,
-  resolveMediaType,
-  hasSceneMedia
+  resolveMediaType
 };

package/dist/chunk-KMVRBUL5.js

@@ -0,0 +1,50 @@
+import {
+  getReadableSceneDuration
+} from "./chunk-WZESNEPT.js";
+
+// src/protocol/timeline.ts
+function resolveVideoTimeline(config) {
+  const ranges = [];
+  let cursor = 0;
+  for (const scene of config.scenes) {
+    const timing = scene.timing ?? {};
+    const beatStart = timing.beatStart == null ? void 0 : config.audio?.beatMarkers[timing.beatStart]?.time;
+    const beatEnd = timing.beatEnd == null ? void 0 : config.audio?.beatMarkers[timing.beatEnd]?.time;
+    const start = timing.startTime ?? beatStart ?? cursor;
+    const duration = Math.max(1e-3, timing.fixedDuration ?? 5);
+    const end = Math.max(start + 1e-3, timing.endTime ?? beatEnd ?? start + duration);
+    ranges.push({ scene, start, end });
+    cursor = end;
+  }
+  return ranges;
+}
+function getVideoDuration(config) {
+  return resolveVideoTimeline(config).at(-1)?.end ?? 0;
+}
+
+// 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 {
+  resolveVideoTimeline,
+  getVideoDuration,
+  getSceneDurationBounds,
+  getSpokenDuration,
+  getSceneDuration
+};

package/dist/chunk-NM4CXXZY.js

@@ -0,0 +1,25 @@
+// src/visual-system/catalog/builtin-metadata.ts
+var SCENE_DEFINITIONS = Object.freeze([
+  Object.freeze({
+    id: "cinemaMedia",
+    defaults: Object.freeze({ mediaUrl: "", mediaType: "video", mediaPoster: "" }),
+    minDuration: 3,
+    preferredDuration: 6,
+    timing: Object.freeze({ contentFields: Object.freeze([]), contentUnit: "words", revealSeconds: 0, holdSeconds: 3, exitSeconds: 0 })
+  }),
+  Object.freeze({
+    id: "chapterTitle",
+    defaults: Object.freeze({ title: "A different perspective" }),
+    minDuration: 3,
+    preferredDuration: 4,
+    timing: Object.freeze({ contentFields: Object.freeze(["title"]), contentUnit: "words", revealSeconds: 0.8, holdSeconds: 1.5, exitSeconds: 0.8 })
+  })
+]);
+function getBuiltinSceneDefinition(id) {
+  return SCENE_DEFINITIONS.find((scene) => scene.id === id);
+}
+
+export {
+  SCENE_DEFINITIONS,
+  getBuiltinSceneDefinition
+};