@vanillaskyai/video 0.10.23 → 0.11.0

package/dist/test.d.ts

@@ -1,5 +1,5 @@
-import { e as VideoScene, f as VIDEO_PROTOCOL_VERSION, b as VideoOrientation, V as VideoStyle, c as Video, d as VideoAudio, j as VideoInput } from './types-DdZw4GRQ.js';
-import { V as VideoWarning, a as VideoFinishReason } from './events-B4YCc4vc.js';
+import { e as VideoScene, f as VIDEO_PROTOCOL_VERSION, V as VideoOrientation, a as VideoStyle, b as Video, d as VideoAudio, j as VideoInput } from './types-ht-Zw3Wv.js';
+import { V as VideoWarning, a as VideoFinishReason } from './events-BZAfl0Dm.js';
 
 type MockVideoStreamPart = {
     type: "scene.add";

package/dist/test.js

@@ -25,8 +25,8 @@ var portrait = {
       type: "scene.add",
       scene: {
         id: "portrait-summary",
-        templateId: "mobileMessage",
-        variables: { app: "VanillaSky", message: "Grounded product update" },
+        templateId: "chapterTitle",
+        variables: { title: "Grounded product update" },
         timing: { fixedDuration: 4 }
       }
     },
@@ -43,8 +43,8 @@ var landscape = {
       type: "scene.add",
       scene: {
         id: "landscape-metric",
-        templateId: "keyFigure",
-        variables: { value: "42 million", label: "Revenue" },
+        templateId: "chapterTitle",
+        variables: { title: "Revenue reached 42 million" },
         timing: { fixedDuration: 4 }
       }
     },
@@ -60,8 +60,8 @@ var truncated = [
     type: "scene.add",
     scene: {
       id: "truncated-partial",
-      templateId: "mobileMessage",
-      variables: { app: "VanillaSky", message: "Playable partial result" },
+      templateId: "chapterTitle",
+      variables: { title: "Playable partial result" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -81,8 +81,8 @@ var invalidScene = [
     type: "scene.add",
     scene: {
       id: "valid-after-invalid",
-      templateId: "mobileMessage",
-      variables: { app: "VanillaSky", message: "Recovered after invalid content" },
+      templateId: "chapterTitle",
+      variables: { title: "Recovered after invalid content" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -99,8 +99,8 @@ var contentFilter = [
     type: "scene.add",
     scene: {
       id: "content-filter-partial",
-      templateId: "mobileMessage",
-      variables: { app: "VanillaSky", message: "Safe partial result" },
+      templateId: "chapterTitle",
+      variables: { title: "Safe partial result" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -111,8 +111,8 @@ var abort = [
     type: "scene.add",
     scene: {
       id: "abort-partial",
-      templateId: "mobileMessage",
-      variables: { app: "VanillaSky", message: "Partial result before cancellation" },
+      templateId: "chapterTitle",
+      variables: { title: "Partial result before cancellation" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -123,8 +123,8 @@ var timeout = [
     type: "scene.add",
     scene: {
       id: "timeout-partial",
-      templateId: "mobileMessage",
-      variables: { app: "VanillaSky", message: "Partial result before timeout" },
+      templateId: "chapterTitle",
+      variables: { title: "Partial result before timeout" },
       timing: { fixedDuration: 4 }
     }
   },
@@ -233,10 +233,10 @@ 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-BH5K6XWT.js");
-  const { createTextDeltaVideoPlanner } = await import("./text-stream-LD364KBI.js");
-  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-W4PLJUZ5.js");
-  const { createTemplateSceneValidator } = await import("./validate-4OUD2CLX.js");
+  const { createVideo } = await import("./compose-video-H2YUQDUY.js");
+  const { createTextDeltaVideoPlanner } = await import("./text-stream-SOVLYR2L.js");
+  const { SCENE_DEFINITIONS, getBuiltinSceneDefinition } = await import("./builtin-metadata-OT6V7TB4.js");
+  const { validateBuiltinScene } = await import("./scene-validation-SGLLLFY5.js");
   const controller = new AbortController();
   const forwardAbort = () => controller.abort(options.signal?.reason);
   if (options.signal?.aborted) forwardAbort();
@@ -248,9 +248,9 @@ async function* simulateVideoStream(parts, options = {}) {
   const run = createVideo(input, {
     requestId: options.requestId ?? DEFAULT_REQUEST_ID,
     runId: options.runId ?? DEFAULT_RUN_ID,
-    capabilities: cloneValue(BUILTIN_SERVER_TEMPLATE_KIT.capabilities),
-    validateScene: createTemplateSceneValidator({ kit: BUILTIN_SERVER_TEMPLATE_KIT }),
-    getTemplatePacing: (templateId) => BUILTIN_SERVER_TEMPLATE_KIT.getTemplateMetadata(templateId),
+    capabilities: { templates: SCENE_DEFINITIONS.map((scene) => scene.id) },
+    validateScene: validateBuiltinScene,
+    getTemplatePacing: getBuiltinSceneDefinition,
     invalidPartBehavior: options.invalidPartBehavior ?? "drop",
     signal: controller.signal,
     generate

package/dist/{text-stream-LD364KBI.js → text-stream-SOVLYR2L.js}

@@ -1,8 +1,8 @@
 import {
   createTextDeltaVideoPlanner
-} from "./chunk-PDQFQIQW.js";
+} from "./chunk-3EQ6PVWL.js";
 import "./chunk-E7CL7UPB.js";
-import "./chunk-7M56IUUX.js";
+import "./chunk-6Z3ID54H.js";
 import "./chunk-7NZOMTAL.js";
 export {
   createTextDeltaVideoPlanner

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

@@ -15,6 +15,8 @@ interface VideoChatMedia {
     url: string;
     type: "image" | "video";
     posterUrl?: string;
+    /** Actual media duration, not a narration estimate. */
+    durationSec?: number;
 }
 interface VideoChatSuggestion {
     prompt: string;
@@ -43,4 +45,4 @@ interface VideoChatWelcomeOptions {
     prompts?: readonly VideoChatWelcomePrompt[];
 }
 
-export type { VideoChatMode as V, VideoChatAskOptions as a, VideoChatMedia as b, VideoChatSuggestion as c, VideoChatCapabilities as d, VideoChatWelcome as e, VideoChatWelcomeOptions as f, VideoChatConversationTurn as g, VideoChatWelcomePrompt as h };
+export type { VideoChatConversationTurn as V, VideoChatMode as a, VideoChatWelcomeOptions as b, VideoChatCapabilities as c, VideoChatWelcomePrompt as d, VideoChatAskOptions as e, VideoChatMedia as f, VideoChatSuggestion as g, VideoChatWelcome as h };

package/dist/{types-DdZw4GRQ.d.ts → types-ht-Zw3Wv.d.ts}

@@ -191,4 +191,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 VideoTemplatePacing as g, type VideoNarrationGroup as h, type VideoStyleOptions as i, type VideoInput as j, type VideoGenerationContext as k, type VideoPlanner as l, type VideoRequest as m, type VideoSceneValidator as n, type VideoSnapshotRetention as o, type VideoResumeCursor as p, type VideoSceneValidationContext as q };
+export { type VideoOrientation as V, type VideoStyle as a, type Video as b, type VideoCapabilities as c, type VideoAudio as d, type VideoScene as e, VIDEO_PROTOCOL_VERSION as f, type VideoTemplatePacing as g, type VideoNarrationGroup as h, type VideoStyleOptions as i, type VideoInput as j, type VideoPlanner as k, type VideoRequest as l, type VideoSceneValidator as m, type VideoSnapshotRetention as n, type VideoResumeCursor as o, type VideoGenerationContext as p };

package/docs/agent-integration.md

@@ -1,71 +1,26 @@
-[← Documentation home](../README.md) · [Next: Getting started →](getting-started.md)
-
 # Agent integration
 
-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
-```
-
-Then prompt: `Use $vanillasky to set up and verify a general-purpose video chat in this project.`
-
-## Set up the canonical chat
-
-The skill follows this public path in an empty npm project:
-
-```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 and runs doctor automatically. The baseline uses an immediate introduction and browser voice, and installs
-no optional provider packages. Add the video adapter for moving video answers;
-without a media provider, narration and subtitles remain available.
-`ANTHROPIC_API_KEY` is the only required key. Rerun init after an interrupted
-installation.
-
-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.
-
-For requested upgrades, run `npx vanillasky providers add speech` for xAI speech
-or `npx vanillasky providers add video` for FAL video and transcription. Have the
-developer add `XAI_API_KEY` or `FAL_KEY` locally, then restart the server. Stock
-media needs only `PEXELS_API_KEY`. The client does not change.
-
-## 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, verify moving footage throughout
-   one complete answer, including its ending, without editing client code.
-5. Check failed network responses before reporting success.
+Build the supported chat path first. The optional integration skill is installed
+with `npx skills add VanillaSkyAi/video@vanillasky`.
 
-The handoff should name the localhost URL and ready capabilities. It should
-never include credential values.
+In an empty app, run `npx @vanillaskyai/video init`, use
+`npx vanillasky doctor` to identify missing setup, and start `npm run dev`.
+For an existing app, keep its framework and connect `VideoChat` to one
+`createVideoChatHandler` using the [provider guide](provider-integration.md).
+Do not copy SDK internals or invent a second generation client.
 
-## Keep ownership clear
+The host adds credentials to ignored server-only environment files. Never read,
+print, screenshot, or send secret values. Doctor exposes key names only.
 
-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.
+Verify in a real browser: a complete answer, its ending, a follow-up, pause/mute,
+and console/network failures. Test moving footage when a video adapter is
+configured. Report the localhost URL and ready capabilities, not just scaffold
+completion.
 
-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.
+The SDK owns chat, shot planning, streaming, voice timing, and the two renderers.
+The application owns providers, keys, auth, persistence, copy, and spending.
+Use `useVideoChat` only when the host needs a custom UI; use `parseVideo` and
+`VideoPlayer` for saved responses. Renderer plugins and template authoring are
+not supported.
 
-The root README and [Getting started](getting-started.md) are the canonical
-human references. Evaluation-only package checks remain in the maintainer docs.
+[Getting started](getting-started.md) · [Documentation home](../README.md)

package/docs/architecture.md

@@ -1,118 +1,92 @@
 # Architecture
 
-VanillaSky turns context into a visual response. Your application and its AI
-decide what matters; VanillaSky turns that decision into a grounded, validated,
-embedded video that starts playing while it is still being composed.
+The product is one video-chat pipeline: a chapter introduction, then narrated
+footage, with chapter fallback when footage is unavailable. The application owns
+providers and policy. There is no public template builder or template registry.
 
-## The shortest mental model
+## Follow one response
 
 ```text
-user message + conversation context
-  → app-owned model
-  → trusted scene plan
-  → validation and streaming protocol
-  → synchronized voice-and-video response
+VideoChat / useVideoChat
+  → createVideoChatHandler (host policy, capabilities)
+      → optional resolveAnswer (application's completed answer)
+  → createChatShotPlanner (answer brief → ordered shots)
+  → concurrent footage jobs + early preparation announcements
+  → createVideo (validated protocol events)
+  → browser speech/media preparation → ordered player + narration
 ```
 
-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.
+Without `resolveAnswer`, shot planning begins directly from the request and
+conversation. With it, the handler waits for the application's completed answer
+before planning; that answer becomes the sole factual source. The hook is not
+a stream of partially written assistant tokens.
 
-## Start here
+Scenes can start before the full video plan is ready. Preparation overlaps;
+early media announcements let the browser warm upcoming assets even while an
+earlier shot is pending. Public scene order stays deterministic. The final Video is replayable data;
+saved replay does not request another generation.
 
-Six files, in this order, are enough to hold the whole system in your head.
-About 2,600 lines total, and two of them are most of it.
+Narration is estimated against each clip with a 0.8-second tail. An oversized
+beat gets at most one short rewrite before footage is requested. A failed or
+still-oversized rewrite preserves the original speech in a chapter instead of
+spending on unusable footage. Measured speech remains authoritative during
+playback; video plays once and unexpected overruns recover to a chapter. Estimation is
+not a guarantee that every voice/language finishes inside its clip.
 
-1. `src/protocol/types.ts` — the `Video` shape. Everything else exists to
-   produce, validate, transport, or play this one object.
-2. `src/server/prompts/system-prompt.ts` — what the model is actually asked
-   for. The product's behavior is mostly here, not in the code around it.
-3. `src/server/create-video-chat-handler.ts` — the one endpoint. Where an
-   application's providers and policy attach.
-4. `src/protocol/events.ts` — the wire contract between server and browser.
-5. `src/video-chat/use-video-chat.ts` — the client lifecycle, as a reducer.
-   Read `reducer` first and the hook second.
-6. `src/visual-system/scene-templates/quote.tsx` — one complete scene, small
-   enough to read in a sitting. Every other template has this shape.
+## Where to work
 
-To watch it run instead, `npm run dev:chat` renders the real `VideoChat` from
-source against fixtures, with no provider credentials and no spend.
-
-## Repository map
-
-| Location | Purpose |
+| Change | Source |
 | --- | --- |
-| `src/server/create-video-chat-handler.ts` | Complete chat endpoint and capability boundary |
-| `src/server/create-video-handler.ts` | Internal 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/` | Internal stream client, 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/backgrounds/` | Standalone background renderers |
-| `src/visual-system/motion/` | Animation functions and timing behavior |
-| `src/visual-system/theme/` | Color and design tokens |
-| `src/visual-system/typography/` | Text fitting, formatting, and kinetic type lifecycles |
-| `src/cli/` | `vanillasky init`, `doctor`, and `providers add`, 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`, `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
-every installable item by a stable name. Their `meta.vanillasky.layer` field is
-`template` for a complete scene the model may select, or `lib` for shared
-support code a template imports. 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 templates sync`
-derives a browser registry in `vanillasky/index.ts` and a React-free
-prompt/validation registry in `vanillasky/server.ts`.
-
-## Request flow
-
-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 the internal composition pipeline, 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 prompt, completed conversation, instructions,
-   style, and approved media.
-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.
-
-`VideoPlayer` also replays completed chat videos parsed at the storage boundary.
-
-## Where to change common behavior
-
-- Model connection: `src/server/create-video-handler.ts`
-- Base planning rules: `src/server/prompts/system-prompt.ts`
-- Per-request context formatting: `src/server/prompts/user-prompt.ts`
-- Template-specific prompt catalog: `src/visual-system/catalog/prompt.ts`
-- Wire contract: `src/protocol/types.ts` and `src/protocol/events.ts`
-- Scene rendering: `src/visual-system/scene-templates/`
-- Background effects: `src/visual-system/backgrounds/` and
-  `src/visual-system/scene-templates/background-effect.ts`
-- Text effects: `src/visual-system/scene-templates/text-archetypes.ts`
-- Gradients and design tokens: `src/visual-system/theme/`
-
-## Public vocabulary
-
-Use `VideoChat`, `useVideoChat`, `createVideoChatHandler`, `Video`, 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.
+| Chat interface and lifecycle | `src/video-chat/` |
+| HTTP admission, methods, CORS and bounded body reading | `src/server/video-chat-http.ts` |
+| Response orchestration, host answer and provider callbacks | `src/server/create-video-chat-handler.ts` |
+| Default planning instructions | `src/server/video-chat-prompts.ts` |
+| Answer brief and shot planning | `src/server/chat-shot-planner.ts` |
+| Validated composition and completion | `src/server/compose-video.ts` |
+| Wire contract and reduction | `src/protocol/` |
+| Turn-owned speech queue and media preparation | `src/video-chat/scene-preparation.ts` |
+| Media readiness, timeline and narration | `src/player/` |
+| Shared speech/clip budget | `src/protocol/clip-budget.ts` |
+| Footage and chapter rendering | `src/visual-system/scene-templates/` |
+| CLI setup and doctor | `src/cli/` |
+| Application-owned provider examples | `starters/video-chat/` |
+| Local real-chat harness | `dev/chat/` |
+| Public entry points | `src/index.ts`, `src/server.ts`, `src/react.ts`, `src/test.ts` |
+| Scoped UI styles and packaged fonts | `styles/` |
+
+The root and test entry points are React-free. Server imports must not pull in
+React; browser entries must not pull in Node or provider libraries.
+[PUBLIC-API.md](../PUBLIC-API.md) and the packed API checks enforce that boundary.
+
+## Prompts and ownership
+
+The handler creates the real chat prompt from the opening, shot, pacing, and
+visual-direction rules. Application `instructions` add product guidance;
+the separate user prompt carries the request and bounded conversation.
+The model emits structured directions, never React, HTML, or executable code.
+Approved media URLs enter only through server callbacks.
+
+Providers can return an async text iterable directly or an AI SDK-shaped result.
+No particular host, model SDK, database, or storage vendor is required.
+Authentication, spending limits, licensing, and persistent media delivery belong
+to the application.
+
+The optional `resolveAnswer({ prompt, conversation, signal })` accepts one
+completed, nonempty string of at most 32,000 characters. It has a fixed,
+abortable 30-second bound; invalid output or failure returns an explicit error,
+not a newly invented answer. The video planner still needs a text callback to
+turn that source into shots. See [integration](provider-integration.md).
+
+The generated-video callback receives `requestedDurationSec`, `shotDirection`
+and an absolute `deadlineAt`, alongside orientation, look and cancellation.
+Its result can report `durationSec`. Model selection, supported duration and
+resolution, concurrency, submission/polling and durable delivery stay in the
+adapter. The SDK does not own provider jobs or a storage service.
+
+Progressive scene delivery cannot remove a vendor's generation delay. A
+minutes-long job API remains minutes-long even when the next scene is prepared
+early. Scope is the beta npm SDK, its documented React/browser boundaries and
+best-effort integration support—not a hosted video service or vendor uptime SLA.
+
+See [development](development.md) for the fast edit loop and
+[testing](testing.md) for deterministic public helpers.

package/docs/customization.md

@@ -1,25 +1,24 @@
-[← Documentation home](../README.md)
-
 # Customization
 
-## Video chat interface
-
-The default `VideoChat` uses an immersive video canvas with a floating
-conversation field, on-video subtitles, and a single dark settings/history
-treatment. See [interface behavior](immersive-interface.md) and the
-[component reference](reference/design-system.html). Pass a custom welcome
-heading and a root class when the application needs its own copy or chrome colors:
+The default interface places footage behind a floating conversation field,
+with on-video subtitles, pause/mute controls, suggestions, settings, and history.
+Keep that interface unless your application needs to own it.
 
 ```tsx
 <VideoChat
   className="acme-chat"
   welcomeTitle={<>Ask Acme<br />See the answer</>}
+  branding={{
+    name: "Acme",
+    logo: <img src="/acme-logo.svg" alt="" width={120} height={30} />,
+    homeUrl: "/app",
+    showDeveloperLinks: false,
+  }}
 />
 ```
 
-Override the scoped custom properties after importing
-`@vanillaskyai/video/video-chat.css`; the selectors and values stay local to
-that instance:
+Import `@vanillaskyai/video/video-chat.css` once. Override its scoped variables
+on the instance class, not global element selectors:
 
 ```css
 .acme-chat {
@@ -30,72 +29,56 @@ that instance:
 }
 ```
 
-The built-in navigation carries the VanillaSky logo. `welcomeTitle` changes
-the welcome heading; it does not replace the navigation logo. Graphic scenes
-use fixed black backgrounds and white/neutral system typography.
+`welcomeTitle` changes the heading. `branding` changes only the navigation
+identity: `name` supplies the accessible home-link label and becomes the visible
+wordmark when `logo` is omitted. Size an app-owned image or React logo explicitly
+to fit the header (about 120–144px wide and 30–36px high). Keep it non-interactive:
+the surrounding home link already handles navigation.
+
+Omit `branding` for the unchanged VanillaSky logo and interface. Omit `homeUrl`
+even with custom branding to keep the existing Home behavior: at `/`, an ordinary
+click starts a new session; elsewhere it navigates to `/`. An explicit `homeUrl`
+navigates normally and never resets the current session first. Only root-relative
+paths and HTTP(S) links without embedded credentials are accepted; other values
+fall back to the existing Home behavior.
 
-Use `options` for the endpoint, templates, orientation, request
-headers, and an optional custom voice. Provider capabilities are discovered
-from the server. Use `useVideoChat()` only when the application needs to own the
-entire interface.
+`showDeveloperLinks` defaults to true. It controls the SDK's Docs/About/GitHub
+section in Settings, not an About page for your application. This is a small UI
+option, not a theme system; it does not affect narration, providers or history.
 
-Pass the following visual settings through `VideoChat` or `useVideoChat` options.
-Keep viewer context in the prompt and completed conversation turns; use the
-server handler’s `instructions` for trusted product guidance.
+The chapter
+introduction uses black with neutral system typography. The supported scenes
+are chapters and footage; there is no renderer-extension or brand-kit API.
 
-## Cinematic visual direction
+Use `options` for endpoint, request headers, orientation, and voice.
+Capabilities are discovered from the server. `useVideoChat` provides the same
+conversation/playback lifecycle for application-owned controls.
 
-Graphics use black backgrounds and white/neutral typography. Full-bleed media
-and Reach out can show naturally colored footage; the other six templates
-explain with their own composition and motion. There is no brand-kit option.
+## Visual direction
 
-The host can provide a shared `generatedLook` description for media preparation.
-Custom source-owned templates can define their own visual language in code.
-Do not rely on old global brand, text-effect, or gradient controls to restyle
-the seven cinematic templates.
+Use server `instructions` for trusted audience, tone, or domain guidance.
+A shared `style.generatedLook` can guide generated footage; the planner carries
+consistent response-specific subjects and setting into each shot.
+[Media and voice](media-and-audio.md) explains the look and adapter contract.
+Style prompts cannot restyle stock assets.
 
-## Opening
+## Opening and layout
 
-The planner streams a short spoken hook before the scenes. The chat holds that
-opening until its speech finishes and the first scene is ready. A selected
-suggestion can start with its prewritten opening and already-loaded media:
+A selected suggestion can start its prepared opening immediately:
 
 ```ts
 await chat.ask(card.prompt, { opening: card.opening, openingMedia: card.media });
 ```
 
-Openings and scene narration share the chat voice and pause/mute controls.
-
-## Aspect ratio and responsive layout
-
-The player is responsive by default: it fills its container width. Templates
-and copy must work at either aspect ratio; orientation is not an AI-planning
-input and must not influence the selected templates or wording.
-
-`portrait` reserves a 9:16 response/export frame and `landscape` reserves 16:9.
-This input setting remains stable in the completed config. For an embed that
-should display landscape on desktop and portrait on mobile without changing the
-saved response, pass `orientation="auto"` to `VideoPlayer`; it responds
-to its container width. See [responsive orientation](responsive-orientation.md).
-
-## Media and voice
-
-Configure `searchMedia`, `generateVideo`, and `generateSpeech` on the server
-handler. They progressively enhance the same chat; failed optional providers
-fall back to templates or browser voice. See [Media and voice](media-and-audio.md).
-
-## Custom templates
+Typed prompts receive their opening from the same model stream as the answer.
+The opening holds until its narration completes and the first scene is ready.
 
-The built-in catalog needs no setup. Only source-owned templates need the
-optional local TSX compiler; install it once with `npm install --save-dev tsx`.
-Then use `npx vanillasky templates create <id>` for an original one-file template or
-`npx vanillasky templates add <builtin>` to copy a close built-in. Edit the owned file,
-run `npx vanillasky templates sync`, then run `npx vanillasky templates check` before committing.
-Pass the generated registry to the server and browser; project-owned IDs
-replace matching built-ins and new IDs extend the catalog.
+`portrait` reserves a 9:16 response frame; `landscape` reserves 16:9.
+The saved orientation stays stable. For responsive display without changing the
+saved response, `<VideoPlayer orientation="auto" />` follows container width.
+Keep the player in a container with a usable width and height.
 
-The model sees selection guidance and a schema, not component source. It chooses
-a trusted template and fills validated variables. Never evaluate model-authored
-React, HTML, CSS, or JavaScript on the live path.
+History in `VideoChat` is in memory. Durable storage belongs to the host;
+see [persistence](persistence.md).
 
-See [custom templates](custom-templates.md).
+[Documentation home](../README.md)