@vanillaskyai/video 0.5.8 → 0.7.0

package/dist/{showcase-code-NWQAAJIA.js → showcase-code-2HLAVKBM.js}

@@ -5,21 +5,21 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   TemplateText
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   resolveTokens
 } from "./chunk-XWWLKRNU.js";

package/dist/{showcase-phone-5UW45ATT.js → showcase-phone-Q4HEO4LH.js}

@@ -7,22 +7,22 @@ import "./chunk-S7HFLYNN.js";
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   TemplateText
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   SPRING_SMOOTH,
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   resolveTokens

package/dist/{showcase-terminal-UVOD25UF.js → showcase-terminal-DL45LUFG.js}

@@ -7,21 +7,21 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   TemplateText
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   resolveTokens

package/dist/{showcase-web-3AW6VHIG.js → showcase-web-2QZO73FZ.js}

@@ -9,22 +9,22 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   TemplateText
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   SPRING_SMOOTH,
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import {
   hasSceneMedia
 } from "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   resolveTokens

package/dist/{social-milestone-KPKHFOB5.js → social-milestone-GEFUQSBF.js}

@@ -8,12 +8,12 @@ import "./chunk-QAAO7OAY.js";
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   Emoji,
   renderWithEmoji
 } from "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import {
   accessibleTextColor,
   withOpacity
@@ -24,8 +24,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   MEDIA_TEXT_SHADOW,
   TOKEN_DEFAULTS,

package/dist/{social-notification-EDOU6TZB.js → social-notification-FJ5VHVLK.js}

@@ -4,20 +4,20 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   Emoji,
   renderWithEmoji
 } from "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {
   SPRING_SMOOTH,
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   resolveTokens
 } from "./chunk-XWWLKRNU.js";

package/dist/{social-review-stack-EZOO33SV.js → social-review-stack-KXQCKFRP.js}

@@ -4,8 +4,8 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
-import "./chunk-HT6BGERF.js";
+} from "./chunk-MXZSDGZQ.js";
+import "./chunk-FRN6WKHA.js";
 import {
   accessibleTextColor,
   withOpacity
@@ -15,8 +15,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   lighten,
   resolveTokens

package/dist/{social-testimonial-DLOINMMY.js → social-testimonial-JZ7CHC7S.js}

@@ -4,8 +4,8 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
-import "./chunk-HT6BGERF.js";
+} from "./chunk-MXZSDGZQ.js";
+import "./chunk-FRN6WKHA.js";
 import {
   accessibleTextColor,
   autoTextColor,
@@ -17,8 +17,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   TOKEN_DEFAULTS,
   lighten,

package/dist/{social-tweet-6JUM323G.js → social-tweet-UCDXM25F.js}

@@ -4,11 +4,11 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-6M6DATLW.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   renderWithEmoji
 } from "./chunk-L5BTTCZV.js";
-import "./chunk-HT6BGERF.js";
+import "./chunk-FRN6WKHA.js";
 import {
   autoTextColor
 } from "./chunk-W3VDIBGR.js";
@@ -17,8 +17,8 @@ import {
   interpolate,
   spring
 } from "./chunk-XTOXFMLM.js";
-import "./chunk-C6WVCZRW.js";
 import "./chunk-224QNWRA.js";
+import "./chunk-5CDAM24P.js";
 import {
   resolveTokens
 } from "./chunk-XWWLKRNU.js";

package/dist/{system-prompt-4I6Z5HK3.js → system-prompt-RRXIWDDD.js}

@@ -1,10 +1,12 @@
 import {
   DEFAULT_VIDEO_SYSTEM_PROMPT,
   VIDEO_PLAN_INSTRUCTION,
-  createVideoSystemPrompt
-} from "./chunk-PNS52FL4.js";
+  createVideoSystemPrompt,
+  videoPlanInstruction
+} from "./chunk-5SLENAJW.js";
 export {
   DEFAULT_VIDEO_SYSTEM_PROMPT,
   VIDEO_PLAN_INSTRUCTION,
-  createVideoSystemPrompt
+  createVideoSystemPrompt,
+  videoPlanInstruction
 };

package/dist/template-catalog.js

@@ -1,6 +1,6 @@
 import {
   BUILTIN_TEMPLATE_MANIFEST
-} from "./chunk-HVCPEAQF.js";
+} from "./chunk-LKBZX7GV.js";
 export {
   BUILTIN_TEMPLATE_MANIFEST as builtinTemplates
 };

package/dist/templates.d.ts

@@ -1,9 +1,9 @@
-import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-DEG3fcaL.js';
-export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-DEG3fcaL.js';
+import { I as InferTemplateJsonSchema, S as SceneTemplateProps, a as SceneTemplate } from './kit-8g46H2RZ.js';
+export { T as TemplateRegistry, c as createTemplateRegistry } from './kit-8g46H2RZ.js';
 import { ComponentType } from 'react';
 import { d as TemplateJsonSchema, S as SceneTemplateMetadata } from './catalog-types-BIhSpOWK.js';
 export { T as TemplateFamily, c as TemplateTimingMetadata, e as TemplateTransitionTiming } from './catalog-types-BIhSpOWK.js';
-import './types-BV9IqExh.js';
+import './types-2wHBqtg8.js';
 
 interface TemplateExample<Variables extends Record<string, unknown> = Record<string, unknown>> {
     name: string;

package/dist/test.d.ts

@@ -1,5 +1,5 @@
-import { e as VideoScene, b as VideoOrientation, V as VideoStyle, c as Video, d as VideoAudio, j as VideoInput } from './types-BV9IqExh.js';
-import { V as VideoWarning, a as VideoFinishReason } from './events-BBP30j3c.js';
+import { e as VideoScene, b as VideoOrientation, V as VideoStyle, c as Video, d as VideoAudio, g as VideoInput } from './types-2wHBqtg8.js';
+import { V as VideoWarning, a as VideoFinishReason } from './events-B6qS1Lsb.js';
 
 type MockVideoStreamPart = {
     type: "scene.add";

package/dist/test.js

@@ -233,9 +233,9 @@ async function* simulateVideoStream(parts, options = {}) {
   if (timeoutMs != null && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
     throw new Error("Simulation timeoutMs must be a non-negative finite number");
   }
-  const { createVideo } = await import("./compose-video-JWIEDTEJ.js");
-  const { createTextDeltaVideoPlanner } = await import("./text-stream-J6EDDJP4.js");
-  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-YHEZ2JRF.js");
+  const { createVideo } = await import("./compose-video-PD6LKKRK.js");
+  const { createTextDeltaVideoPlanner } = await import("./text-stream-FW4BLBAL.js");
+  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-KB7FKF6A.js");
   const { createTemplateSceneValidator } = await import("./validate-T7GBU2YF.js");
   const controller = new AbortController();
   const forwardAbort = () => controller.abort(options.signal?.reason);

package/dist/{text-stream-J6EDDJP4.js → text-stream-FW4BLBAL.js}

@@ -1,8 +1,8 @@
 import {
   createTextDeltaVideoPlanner
-} from "./chunk-34O5BY6X.js";
+} from "./chunk-RXHW4EP4.js";
 import "./chunk-E7CL7UPB.js";
-import "./chunk-G66Z5CWR.js";
+import "./chunk-MMUXVA47.js";
 import "./chunk-AOWSXU2K.js";
 import "./chunk-XGRA2MUV.js";
 export {

package/dist/{types-BV9IqExh.d.ts → types-2wHBqtg8.d.ts}

@@ -47,8 +47,23 @@ interface VideoStyle {
     defaultTransition?: string;
     density?: string;
     motion?: string;
+    /**
+     * The visual language generated media is produced in.
+     *
+     * A style has two halves once media can be generated: the brand decides how
+     * captions are drawn, and this decides what the footage behind them looks
+     * like. They have to travel together - pale illustrated ground under dark
+     * documentary footage is unreadable - so this belongs on the style rather
+     * than being threaded into each provider call by hand.
+     *
+     * Nothing is rendered from it. It reaches `resolveMedia`, which is where a
+     * provider prompt is written.
+     */
+    generatedLook?: string;
 }
 interface VideoStyleOptions {
+    /** The visual language generated media is produced in. See `VideoStyle`. */
+    generatedLook?: string;
     density?: "airy" | "normal" | "packed";
     motion?: "calm" | "normal" | "punchy";
     textArchetype?: "subtle" | "typewriter" | "wordStagger" | "slam" | "cinematic" | "heroWord";
@@ -69,6 +84,19 @@ interface VideoScene {
     textArchetype?: string;
     backgroundEffect?: string;
     timing: VideoTiming;
+    /**
+     * What is said aloud while this scene is showing.
+     *
+     * A narrated video otherwise has to be carried as two things kept in step by
+     * index - the scenes, and a separate script - and they drift. Holding the
+     * line on the scene keeps them together through planning, playback, storage
+     * and replay, so a stored video can be spoken again without the model that
+     * wrote it.
+     *
+     * The renderer never draws this. It is the spoken half of the scene, not
+     * on-screen copy.
+     */
+    narration?: string;
 }
 interface VideoAudio {
     trackId: string;
@@ -194,4 +222,4 @@ interface VideoSnapshotRetention {
     suppliedMediaUrls?: boolean;
 }
 
-export { type VideoStyle as V, type VideoCapabilities as a, type VideoOrientation as b, type Video as c, type VideoAudio as d, type VideoScene as e, VIDEO_PROTOCOL_VERSION as f, type VideoBrandInput as g, type VideoBrand as h, type VideoBackground as i, type VideoInput as j, type VideoKnowledgeMode as k, type VideoStyleOptions as l, type VideoSuppliedMedia as m, type VideoGenerationContext as n, type VideoPlanner as o, type VideoRequest as p, type VideoSceneValidator as q, type VideoTemplatePacing as r, type VideoSnapshotRetention as s, type VideoResumeCursor as t, type VideoSceneValidationContext as u };
+export { type VideoStyle as V, type VideoCapabilities as a, type VideoOrientation as b, type Video as c, type VideoAudio as d, type VideoScene as e, VIDEO_PROTOCOL_VERSION as f, type VideoInput as g, type VideoBrandInput as h, type VideoBrand as i, type VideoTemplatePacing as j, type VideoBackground as k, type VideoKnowledgeMode as l, type VideoStyleOptions as m, type VideoSuppliedMedia as n, type VideoGenerationContext as o, type VideoPlanner as p, type VideoRequest as q, type VideoSceneValidator as r, type VideoSnapshotRetention as s, type VideoResumeCursor as t, type VideoSceneValidationContext as u };

package/dist/types-DrABlRa7.d.ts

@@ -0,0 +1,46 @@
+type VideoChatMode = "templates" | "full";
+interface VideoChatConversationTurn {
+    prompt: string;
+    response?: string;
+}
+interface VideoChatCapabilities {
+    templates: true;
+    generatedSpeech: boolean;
+    generatedVideo: boolean;
+    stockMedia: boolean;
+    transcription: boolean;
+    modes: VideoChatMode[];
+}
+interface VideoChatMedia {
+    url: string;
+    type: "image" | "video";
+    posterUrl?: string;
+}
+interface VideoChatSuggestion {
+    prompt: string;
+    /** Optional short hook that can start speaking the moment this suggestion is selected. */
+    opening?: string;
+    media: VideoChatMedia | null;
+}
+interface VideoChatAskOptions {
+    /** Reuse already-loaded suggestion footage while the answer is prepared. */
+    openingMedia?: VideoChatMedia | null;
+    /** A prewritten 6-9 word hook that can start immediately while the response streams. */
+    opening?: string;
+}
+interface VideoChatWelcome {
+    hero: VideoChatMedia | null;
+    cards: VideoChatSuggestion[];
+}
+interface VideoChatWelcomePrompt {
+    prompt: string;
+    /** A prewritten 6-9 word hook for an instant suggested-prompt response. */
+    opening?: string;
+    mediaQuery?: string;
+}
+interface VideoChatWelcomeOptions {
+    heroQuery?: string;
+    prompts?: readonly VideoChatWelcomePrompt[];
+}
+
+export type { VideoChatWelcomeOptions as V, VideoChatCapabilities as a, VideoChatConversationTurn as b, VideoChatMode as c, VideoChatWelcomePrompt as d, VideoChatAskOptions as e, VideoChatMedia as f, VideoChatSuggestion as g, VideoChatWelcome as h };

package/docs/agent-integration.md

@@ -2,39 +2,63 @@
 
 # Agent integration
 
-Use the same public path a human developer uses. The optional repository skill
-packages these instructions for coding agents:
+Coding agents should build the same canonical video chat as a human developer.
+Install the repository skill when the agent supports skills:
 
 ```bash
 npx skills add VanillaSkyAi/video@vanillasky
 ```
 
-## Build the first response
+Then prompt: `Use $vanillasky to set up and verify a general-purpose video chat in this project.`
 
-1. Install `@vanillaskyai/video`.
-2. Choose and configure a current model separately; put its provider key in an
-   ignored `.env.local` file.
-3. Connect that app-owned model with `createVideoHandler` in an authenticated
-   server route.
-4. Pass grounded text or structured data as `input`.
-5. Call `useVideo()` and render `VideoPlayer` in React.
-6. Verify one complete response in a browser before adding optional features.
+## Set up the canonical chat
 
-The root README and `examples/nextjs-quickstart` are the canonical working
-reference. Built-in templates require no registry setup.
+The skill follows this public path in an empty npm project:
 
-## Keep responsibilities clear
+```bash
+npx @vanillaskyai/video init
+npx vanillasky doctor
+npm run dev
+```
+
+Init generates the thin application-owned shell around the SDK's complete
+`VideoChat` experience. The default uses packaged templates + browser voice.
+One text-provider key makes it answer; optional keys enable generated speech,
+stock media, transcription, and generated video without client changes.
+
+If doctor reports a missing key, add the named key to the ignored `.env.local`
+yourself. Never read or print a secret value, and never paste one into the chat.
+Doctor is the safe capability interface: it reports names and readiness only.
+
+## Verify, do not merely scaffold
+
+The agent should leave the dev server running and open its reported localhost
+URL in a real browser. Browser automation should use normal motion
+(`reducedMotion: "no-preference"`) so playback advances.
+
+1. Confirm the welcome screen, suggestions, composer, and voice control load
+   without console or page errors.
+2. Ask one explanatory question and confirm the answer streams, speaks, reaches
+   its final frame, and returns to a usable composer.
+3. Ask one unrelated creative question in the same conversation and confirm it
+   produces a distinct response.
+4. If doctor reports generated video ready, choose that mode and verify one
+   suitable prompt without editing client code.
+5. Check failed network responses before reporting success.
+
+The handoff should name the localhost URL and ready capabilities. It should
+never include credential values.
+
+## Keep ownership clear
 
-VanillaSky owns the planning prompt, trusted templates, validation, streaming
-protocol, and player. The application owns its LLM, credentials,
-authentication, source retrieval, media licensing, persistence, and product
-UI.
+VanillaSky owns the chat flow, planning prompts, templates, validation,
+streaming, voice timing, and player. The application owns provider choices,
+keys, authentication, persistence, branding, copy, and policy.
 
-Use `input` for facts the video may claim, `instructions` for presentation
-direction, and `personalization` for viewer or account context. Treat all three
-as untrusted application data. Add brand, media, audio, persistence, or custom
-templates only when the requested experience needs them.
+Customize generated application files only after the default chat passes in the
+browser. Do not inspect SDK internals, copy its template tree, or invent a
+parallel integration path. Source-own a template with
+`npx vanillasky templates ...` only when the product actually needs to edit it.
 
-If a required credential is missing, ask the developer to add it to the ignored
-environment file. Never invent another provider or request secret values in
-chat.
+The root README and [Getting started](getting-started.md) are the canonical
+human references. Evaluation-only package checks remain in the maintainer docs.

package/docs/architecture.md

@@ -7,35 +7,38 @@ embedded video that starts playing while it is still being composed.
 ## The shortest mental model
 
 ```text
-application context
+user message + conversation context
   → app-owned model
   → trusted scene plan
   → validation and streaming protocol
-  → embedded React player
+  → synchronized voice-and-video response
 ```
 
-VanillaSky does not choose your model, retrieve your application context, or
-generate executable UI code. It supplies the video-planning prompt, trusted
-visual vocabulary, validation, streaming lifecycle, and player.
+VanillaSky does not choose your model, retrieve private application context, or
+own your product policy. It supplies the complete default chat, video-planning
+prompts, trusted visual vocabulary, conversation and narration lifecycle,
+validation, streaming, and player.
 
 ## Repository map
 
 | Location | Purpose |
 | --- | --- |
-| `src/server/create-video-handler.ts` | Public server integration and provider adapter boundary |
+| `src/server/create-video-chat-handler.ts` | Complete chat endpoint and capability boundary |
+| `src/server/create-video-handler.ts` | Lower-level video composition and provider adapter boundary |
 | `src/server/prompts/` | System and user prompts sent to the app-owned model |
 | `src/server/model/` | Converts provider text deltas into typed video plan parts |
 | `src/protocol/` | Shared request, event, validation, checksum, and SSE contract |
 | `src/player/` | Browser stream client, `useVideo`, timeline, and React player |
+| `src/video-chat/` | Default `VideoChat` interface and headless conversation/session engine |
 | `src/visual-system/catalog/` | Template metadata, schemas, loading, and planner catalog |
 | `src/visual-system/scene-templates/` | Complete scenes the model may select |
 | `src/visual-system/primitives/` | Reusable visual components used inside scenes |
 | `src/visual-system/backgrounds/` | Standalone background renderers |
 | `src/visual-system/motion/` | Animation functions and timing behavior |
 | `src/visual-system/theme/` | Color and design tokens |
-| `src/cli/` | `vanillasky create`, `add`, `sync`, `check`, `list`, and `describe` for customer-owned templates |
+| `src/cli/` | `vanillasky init` and `doctor`, plus `vanillasky templates create`, `add`, `sync`, `check`, `list`, and `describe` |
 | `registry/items/` | Generated distributable copies installed into customer projects |
-| `src/index.ts`, `src/server.ts`, `src/react.ts`, `src/templates.ts`, `src/template-catalog.ts`, `src/test.ts` | The six small public package entry points |
+| `src/index.ts`, `src/server.ts`, `src/react.ts`, `src/templates.ts`, `src/template-catalog.ts`, `src/test.ts`, `styles/video-chat.css` | The six small code entry points and one scoped stylesheet |
 
 The source of truth for built-in visuals is `src/visual-system`. The JSON files
 in `registry/items` are distribution artifacts, kept flat so the CLI can address
@@ -44,25 +47,36 @@ every installable item by a stable name. Their `meta.vanillasky.layer` and
 support code. Run `npm run registry:sync` after changing canonical visual source.
 
 Customer applications do not edit those internal locations. Their source of
-truth is one file per visual under `vanillasky/templates/`; `vanillasky sync`
+truth is one file per visual under `vanillasky/templates/`; `vanillasky templates sync`
 derives a browser registry in `vanillasky/index.ts` and a React-free
 prompt/validation registry in `vanillasky/server.ts`.
 
 ## Request flow
 
-1. `useVideo().generate(...)` sends grounded input and live application context
-   to the authenticated application route.
-2. `createVideoHandler(...)` builds the prompts and calls the application's
-   `streamText` adapter. This is where OpenAI, Anthropic, or another model is
-   connected.
-3. The system prompt combines the composition rules with the trusted template
+1. `VideoChat` uses `useVideoChat` to send the user's message. A clicked
+   suggestion can start its prewritten hook and existing media immediately.
+2. For a typed prompt, the model emits a short hook first and then continues
+   planning scenes in the same response stream. Its stock-search keyword is
+   resolved separately while the hook is spoken.
+3. `createVideoChatHandler(...)` owns chat actions, suggestions, narration,
+   capability discovery, and generated-video budgets. The application supplies
+   provider callbacks and policy.
+4. Video answers flow into `createVideoHandler(...)`, which calls the
+   application's `streamText` adapter. This is where Anthropic, OpenAI, or
+   another text model is connected.
+5. The system prompt combines the opening and composition rules with the trusted template
    catalog, including generated metadata for customer-owned templates. The user
    prompt serializes the factual input, instructions,
    personalization, brand, and approved media.
-4. The model streams NDJSON plan parts. The server parses and validates complete
-   scenes before emitting versioned video events.
-5. The browser reduces those events into a deterministic `Video`; `VideoPlayer`
-   starts as soon as its first playable scene arrives.
+6. The model streams one host-consumed opening object followed by NDJSON plan
+   parts. The server emits the opening event, then parses and validates complete
+   scenes before emitting them.
+7. The browser reduces those events into a deterministic `Video`. The opening
+   loops or holds until its voice ends and the first playable scene is ready;
+   the planned playback and narration then take over in one cut.
+
+The lower-level `useVideo` and `VideoPlayer` path skips chat actions and remains
+available for explicit one-shot video response integrations.
 
 ## Where to change common behavior
 
@@ -79,6 +93,7 @@ prompt/validation registry in `vanillasky/server.ts`.
 
 ## Public vocabulary
 
-Use `Video`, `VideoInput`, `useVideo`, and `VideoPlayer` for the product API.
-Use “video response” when describing the lifecycle or output category. Use
-“motion” only for animation behavior inside the visual system.
+Use `VideoChat`, `useVideoChat`, `createVideoChatHandler`, `Video`, `VideoInput`,
+`useVideo`, and `VideoPlayer` for the product API. Use “video response” when
+describing the lifecycle or output category. Use “motion” only for animation
+behavior inside the visual system.

package/docs/branding-and-personalization.md

@@ -1,4 +1,4 @@
-[← Documentation home](../README.md) · [Previous: Input and first scene](input-and-first-scene.md) · [Next: Media and audio →](media-and-audio.md)
+[← Documentation home](../README.md) · [Previous: Prompt and conversation input](prompt-and-input.md) · [Next: Media and audio →](media-and-audio.md)
 
 # Branding and personalization
 

package/docs/concepts.md

@@ -2,6 +2,20 @@
 
 # Core concepts
 
+## Video chat
+
+The default product surface is a conversation whose answers are synchronized
+voice-and-video responses. `VideoChat` supplies the complete interface;
+`useVideoChat` supplies the same session, turn, suggestion, voice, and playback
+lifecycle for custom interfaces; `createVideoChatHandler` connects app-owned
+providers and reports their capabilities through one endpoint.
+
+Packaged templates and browser voice are the base mode. A text model makes that
+mode answer, while optional provider callbacks progressively add generated
+speech, stock media, transcription, and generated video without changing the
+client. Visual responses deliberately choose between templates and fully
+generated video; there is no mixed mode.
+
 ## Video response
 
 A video response is a short, responsive animated experience assembled from