@vanillaskyai/video 0.10.23 → 0.11.1

package/CHANGELOG.md

@@ -4,6 +4,75 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.11.1
+
+- Plan single-idea narration with voice headroom against the configured video duration; keep the full repair budget for necessary meaning. Give the single rewrite explicit speech/word budgets and report content-free outcomes instead of silently collapsing timeout, empty, failed and oversized results.
+- Account conservatively for spoken expansion of numeric measurements before paid generation, and request spoken-form narration rather than compact symbols.
+- Keep stock search and playback independent of generated-video duration/deadline settings. Use reported footage duration when available and the mounted decoder when stock duration is unknown; retain every authored beat within the existing bounded plan.
+- Preserve two-second video budgets through composition and preparation. Delivered footage duration governs playback, with the requested duration as a fallback for generated clips; keep the 0.8-second speech tail, native-speed playback and full-narration chapter recovery.
+- Adopt a late narration clock without rewinding already-prepared footage. Hold visual time until forward-moving audio catches up; preserve deliberate playhead/audio resets and replay, avoiding unnecessary WebKit seeks and recovery chapters.
+
+## 0.11.0
+
+### Integration and developer experience
+
+- Add optional `resolveAnswer({ prompt, conversation, signal })` for completed existing-assistant answers. Validate input before invoking it; preserve cancellation and fail explicitly on unusable output.
+- Separate bounded HTTP admission from response policy; stop oversized streamed bodies without waiting for unresponsive cleanup. Keep inbound limits separate from the SDK-owned answer envelope.
+- Add small optional application branding controls with unchanged default UI.
+- Update the architecture, quickstart and provider/UI recipes around footage and chapters. Remove retired internal prompt guidance and duplicate prose/source-structure assertions.
+- Verify native existing-assistant integration through the installed npm artifact, with no React or provider frameworks required by the server entry.
+
+### Provider setup
+
+- Keep providers application-owned: editable fal, Google, Runway and arbitrary-provider examples share the same client contract, not a fixed vendor list.
+- Add `init --native` with plain HTTP text callbacks and no Vercel/Anthropic dependency. Keep the optional Vercel AI SDK starter.
+- Separate video, speech and transcription setup; make `doctor` inspect the selected configuration. Bundle the native starter and all adapter helpers in npm.
+- Submit video jobs once, retain identity, bound polling/ledger/cleanup callbacks and cancel unfinished work best-effort. Preserve terminal job records and native text finish reasons.
+- Require application-owned video storage/delivery in direct-provider examples. No paid generation runs in CI.
+
+### Timing and preparation
+
+- Reset an unexpected native video start during narration preparation so paused WebKit decoders cannot drift ahead and freeze when speech begins.
+- Share a clip budget between planning and playback, with a 0.8-second narration tail and one bounded rewrite before any paid clip. If it cannot fit, keep the complete original narration on a chapter.
+- Check measured speech and actual decoded footage; play normal footage at native speed without looping. Respect browser speech completion with bounded failure handling.
+- Announce completed media ahead of ordered scene delivery. Limit actual decoding to active and next scenes on every browser; isolate speech/media preparation from session state.
+- Add content-free duration, buffering, repeat and wait-reason diagnostics. Stop automatically retrying ambiguous cinematic responses.
+- Pass requested duration, shot direction and an absolute deadline to application video callbacks; accept actual media duration in results. Allow long-running provider deadlines without client edits.
+
+### Breaking changes
+
+The beta now focuses on footage and chapter opening/recovery. The default chat
+experience and saved `cinemaMedia` / `chapterTitle` playback remain supported.
+Custom renderers, the five other built-ins, all registry bundles, template CLI
+commands, and `/templates` and `/templates/catalog` exports are removed.
+Server template registries and custom-registry options are removed as well.
+There is no compatibility loader for retired custom-template videos.
+
+Before, applications could install and pass a custom registry:
+
+```tsx
+import { createTemplateRegistry } from "@vanillaskyai/video/templates";
+const templates = createTemplateRegistry({ templates: customScenes });
+<VideoChat options={{ endpoint: "/api/video", templates }} />;
+```
+
+### Adoption
+
+Use the built-in video-and-chapter experience. Remove registry imports, custom
+template files, authoring scripts and their configuration from your application.
+Use visual direction for the footage and the headless hook for custom chat UI:
+
+```tsx
+import { VideoChat } from "@vanillaskyai/video/react";
+import "@vanillaskyai/video/video-chat.css";
+<VideoChat options={{ endpoint: "/api/video" }} />;
+```
+
+Keep provider integrations application-owned. npm distribution and optional
+Vercel AI SDK integration remain; the SDK does not require `ai`, Anthropic or
+any video-provider package. Support is best-effort beta support for the focused
+chat flow, not an expanding model compatibility matrix.
+
 ## 0.10.23
 
 - Stop shipping the maintainer-only cinematic migration note in the published

package/PUBLIC-API.md

@@ -1,474 +1,83 @@
 # VanillaSky Video public API
 
-Status: current public beta contract.
-
-This document defines the API that may enter the fresh
-`@vanillaskyai/video` package. An export not listed here is internal. Tests and
-the packed-package verifier must fail if the final package adds or removes an
-export without changing this contract intentionally.
-
-`tests/fixtures/public-api-signatures.json` is the reviewed normalized
-declaration report for this surface. `npm run verify:api` checks the local build's
-public names, complete reachable signatures, and runtime and declaration
-dependency boundaries. `npm run verify:package` applies the same contract to the
-exact packed artifact. Regenerate the report only as part of an intentional
-public API review.
-
-## Compatibility promise
-
-- Patch releases do not make breaking changes to documented APIs or the
-  serialized `Video` schema.
-- A compatible later `0.x` minor needs no migration ceremony. A breaking
-  pre-1.0 minor must document both `### Breaking changes` and `### Adoption` in
-  its changelog section, with concrete fenced before and after code examples
-  respectively.
-- An API prefixed with `experimental_` may change in a patch. Canonical examples
-  must pin an exact package version when they use one.
-- Deprecated APIs remain usable until the next minor release. The `0.1`
-  package starts without undocumented compatibility aliases.
-- The package is ESM-only, targets ES2022, and supports Node.js 22 or newer.
-- React is an optional peer dependency. Only `/react` and renderer definitions
-  under `/templates` may depend on React.
-- Framework adapters are examples, not separate public APIs. The release suite
-  verifies current Next.js and Vite production builds.
-
-The frozen public API surface report is compared on every pull request. It is
-intentionally conservative: every existing normalized declaration and reachable
-support declaration must remain exactly equal because the report cannot safely
-distinguish input and output positions.
-As a result, even optional field additions to an existing public
-type fail a patch gate; use a documented pre-1.0 minor unless a separately
-reviewed, direction-aware compatibility check can prove the change safe. New
-exports, wider supported peer ranges, and new optional peers remain additive.
-
-## Environment boundaries
-
-| Entry point | Environment | May import React | May import Node built-ins |
-|---|---|---:|---:|
-| `@vanillaskyai/video` | Universal | No | No |
-| `@vanillaskyai/video/server` | Server | No | No required runtime built-ins |
-| `@vanillaskyai/video/react` | Browser/React | Yes | No |
-| `@vanillaskyai/video/templates` | Browser/React authoring | Yes | No |
-| `@vanillaskyai/video/templates/catalog` | Universal JSON metadata | No | No |
-| `@vanillaskyai/video/test` | Node test runners | No | Node test helpers allowed |
-
-The CLI is exposed separately as the `vanillasky` binary.
-
-## Root
-
-The root contains serializable protocol types and pure helpers. It never starts
-a request, renders React, imports a provider, or accesses browser globals.
-
-### Values
-
-- `getVideoDuration(video: Video): number`
-- `getSceneDuration(scene, metadata)`
-- `getSceneDurationBounds(scene, metadata)`
-- `getSpokenDuration(text)`
-- `parseVideo(value: unknown): Video`
-- `resolveVideoBrand(input?: VideoBrandInput): VideoBrand`
-- `VideoValidationError`
-
-### Types
-
-- `Video`
-- `VideoAudio`
-- `VideoBackground`
-- `VideoBrand`
-- `VideoBrandInput`
-- `VideoOrientation`
-- `VideoScene`
-- `VideoStyle`
-- `VideoStyleOptions`
-- `VideoStatus`
-- `VideoValidationErrorCode`
-- `SceneDurationBounds`
-
-`VideoState` remains internal protocol reducer state. Browser consumers use the
-normalized fields returned by `useVideoChat` instead.
-
-## Server
-
-The server entry point creates a customer-owned authenticated route. It accepts
-the result of Vercel AI SDK `streamText()` directly while retaining a small
-provider-neutral text-delta escape hatch.
-
-### Values
-
-- `createVideoChatHandler(options)`
-- `createServerTemplateRegistry(options)`
-
-### Types
-
-- `VideoChatCapabilities`
-- `VideoChatConversationTurn`
-- `VideoChatHandlerOptions`
-- `VideoChatMode`
-- `VideoChatWelcomeOptions`
-- `VideoChatWelcomePrompt`
-- `ServerTemplateRegistry`
-- `ServerTemplateMetadata`
-- `VideoFinishReason`
-- `VideoGenerationSummary`
-- `VideoProviderUsage`
-- `VideoWarning`
-- `VideoWarningCategory`
-
-### Handler contract
-
-The chat contract includes two footage modes: `"cinematic"` (labelled AI video)
-and `"pexels"`. AI mode does not fall back to stock; either mode recovers missing
-footage to an authored chapter. Existing `"cinematic"` requests remain valid.
-`generatedClipDurationSec?: number` on the handler defaults to 5 and accepts 2–20;
-it must match the host adapter's requested duration. `VideoChatTurn.mode` is
-optional so older in-memory saved turns remain readable.
-
-A declared `data.video-chat-preparation` extension carries
-`{ sceneId: string, narration: string }` before media resolves. It permits bounded
-speech preparation, not playback of an unvalidated scene. The client limits
-speech preparation to two concurrent jobs and reuses it when `scene.add` arrives.
-The six public exports, persisted video schema and protocol version are unchanged.
-
-`createVideoChatHandler` is the opinionated general-purpose video-chat route.
-Mount it once and use its bounded `action` query parameter for capabilities,
-responses, opening media, narration, suggestions, speech,
-transcription, and the welcome screen. It owns the general response prompts,
-application-configured visual-mode attempt limits, capability fallbacks, and auxiliary response
-shapes. The application supplies provider-neutral `streamText`, `generateText`,
-`generateSpeech`, `transcribe`, `searchMedia`, and `generateVideo` callbacks.
-Only the two text callbacks are required. Missing optional callbacks remove
-their capability; templates and browser speech remain available. Failed or late
-footage becomes an authored chapter with complete narration. The default handler
-skips invalid planner parts and preserves playable scenes on an interrupted plan,
-emitting non-fatal warnings. Explicit `invalidPartBehavior: "fail"` retains strict
-generation semantics.
-
-- A response accepts `prompt`, `mode`, `orientation`, optional bounded
-  `conversation`, `opening`, and `style`. `opening` is an optional
-  prewritten hook from a selected suggestion. The response returns protocol
-  `0.6` SSE and negotiates `data.video-chat-opening` and
-  `data.video-chat-preparation` before the associated scene is ready.
-- The planner produces the opening and shots in one model stream, reserving the
-  intended ending. Each shot supplies an authored recovery title, complete
-  narration and visual direction. The default UI uses a chapter opening; the
-  separate opening-media action remains available to custom consumers.
-- `cinematic` uses the application-owned `maxGeneratedVideos` limit (default
-  five, nonnegative safe integer). It counts generation attempts, including
-  failures. Zero skips generation and keeps authored chapters. Expired scene
-  deadlines also skip generation without consuming an attempt. This limit is
-  neither a currency nor duration cap. Pexels mode uses only `searchMedia` and
-  never consumes this allowance. Capabilities expose Pexels when stock search
-  is configured; AI mode remains usable with chapter recovery without video.
-- The response planner writes narration on each scene. The narration action is
-  retained as a compatibility fallback for missing lines, not used in the
-  normal path.
-- Every action applies the same authorization, origin, request-size,
-  cancellation, safe-error, and server-only-provider boundaries.
-
-The chat handler requires `authorize`; `authorize: "none"` is only for an
-intentionally non-public in-process/test handler. All provider callbacks receive
-cancellation signals. The application owns authentication, origins, request
-limits, provider credentials, deadlines, and retry budgets.
-
-`onWarning` receives safe typed diagnostics; `onComplete` receives a server-only
-`VideoGenerationSummary` after an actual `response.complete`, including recovered
-playable responses. `onError` receives private internal errors. Observer failures
-do not change playback. Provider metadata remains server-side, with raw usage
-and metadata requiring the bounded `includeRawProviderData` opt-in.
-
-The handler exposes chat-relevant policy, template, and provider options only.
-Standalone soundtrack selection, snapshot-retention overrides, and durable
-stream replay are not public chat options.
-
-## React
-
-### Values
-
-- `VideoChat(props)`
-- `useVideoChat(options?)`
-- `createVideoChatVoice(options?)`
-- `VideoPlayer`
-- `VideoError`
-
-### Types
-
-- `VideoChatProps`
-- `UseVideoChatOptions`
-- `UseVideoChatResult`
-- `VideoChatAskOptions`
-- `VideoChatFirstFrameMetric`
-- `VideoChatTurn`
-- `VideoChatStatus`
-- `VideoChatMode`
-- `VideoChatCapabilities`
-- `VideoChatWelcome`
-- `VideoChatSuggestion`
-- `VideoChatMedia`
-- `VideoChatVoice`
-- `VideoChatPreparedSpeech`
-- `CreateVideoChatVoiceOptions`
-- `VideoPlaybackMode`
-- `VideoPlayerProps`
-- `VideoErrorOptions`
-
-`VideoChat` is the complete default interface. Import its scoped stylesheet
-explicitly so the host application keeps control over CSS loading:
+The 0.11 beta is a focused video-chat SDK. It supports footage (`cinemaMedia`) and chapter opening/recovery (`chapterTitle`). Custom renderers, registries, source installation and template authoring are no longer part of the product.
 
-```tsx
-import { VideoChat } from "@vanillaskyai/video/react";
-import "@vanillaskyai/video/video-chat.css";
+## Supported entry points
 
-export function App() {
-  return <VideoChat />;
-}
-```
+- `@vanillaskyai/video`: serializable video types, validation and duration helpers; no React, browser globals or providers.
+- `@vanillaskyai/video/server`: `createVideoChatHandler` and its configuration/diagnostic types; no required provider or Node runtime dependencies.
+- `@vanillaskyai/video/react`: `VideoChat`, `useVideoChat`, `VideoPlayer`, `createVideoChatVoice`, `VideoError` and their types.
+- `@vanillaskyai/video/test`: deterministic `createMockVideoPlanner`, `simulateVideoStream`, `videoFixtures`.
+- `@vanillaskyai/video/video-chat.css`: explicitly imported, scoped default UI styles.
+- `vanillasky` executable: starter initialization, configuration diagnosis and application-owned provider setup.
 
-Pass the same session configuration through `options`, for example
-`<VideoChat options={{ endpoint, headers, templates }} />`. `className`
-and `welcomeTitle` are the only shell-level customizations. The stylesheet is
-scoped under `.vanillasky-video-chat` and does not style the host document.
+The exact named exports are recorded in `tests/fixtures/public-api-surface.json`; normalized declarations and all reachable types are recorded in `public-api-signatures.json` beside it. Regenerate these only for an intentional contract change. `verify:api` checks a local build; `verify:package` checks the actual packed artifact and environment boundaries.
 
-`useVideoChat` is the headless client for `createVideoChatHandler`. It owns
-the conversation lifecycle and returns UI-neutral state plus a spread-ready
-player binding:
+## Beta compatibility and support
 
-```tsx
-const chat = useVideoChat();
+The package is ESM-only, targets ES2022 and supports Node.js 22+. React 18/19 are optional peers needed only by the React entry. No provider SDK is a runtime or peer dependency. npm distribution remains supported with best-effort beta maintenance, not an unlimited vendor/model compatibility promise.
 
-await chat.ask("Tell me a tiny mystery set on a night train");
+Patch releases preserve documented APIs and saved video data. Breaking pre-1.0 minor releases explain removal and adoption in the changelog; 0.11 intentionally removes `/templates`, `/templates/catalog`, server template-registry exports and custom-registry options. No retired-feature aliases or execution machinery remain. Saved footage/chapter identifiers and replay remain supported; saved custom-template scenes are outside this release's supported contract.
 
-return chat.playerProps
-  ? <VideoPlayer key={chat.playerKey} {...chat.playerProps} />
-  : null;
-```
+## Default server flow
 
-The hook loads capabilities and welcome suggestions, sends completed turns as
-bounded context, cancels replaced prompts, retries once only before playback,
-paces each scene to its prepared speech, and keeps pause, mute, replay, history,
-captions, and actual playback completion synchronized. The default voice tries
-the handler's generated-speech action and falls back to browser speech. Pass a
-`VideoChatVoice` to replace it without rebuilding session orchestration.
-`createVideoChatVoice({ onFallback })` optionally observes a generated-speech
-failure that selects browser speech. Observer exceptions and rejected promises
-are isolated from playback; no provider diagnostics are passed to this callback.
-
-`chat.warnings` exposes concise notices for the displayed turn, also retained
-as optional `VideoChatTurn.warnings`. The default interface recovers silently; these diagnostics are
-for application developers and are not rendered to viewers. Optional scene, narration, speech, or stream failures preserve
-playable output; an error is shown only when no playable response remains.
-`ask(prompt, { opening, openingMedia })` lets a custom interface start a
-prewritten suggestion hook immediately and reuse its image or video without
-another model or media lookup. The hook otherwise reads the opening from the
-response stream and starts the planned timeline only when opening speech and
-the contiguous prepared scenes are ready. It no longer requests opening stock
-automatically. `UseVideoChatOptions.onFirstFrame` receives a
-`VideoChatFirstFrameMetric` once after its first active scene commits and reaches
-an animation-frame opportunity. This measures presentation readiness, not physical
-screen paint or media decoding. Each `VideoChatTurn` exposes `openingMedia` and `completed`, so
-custom interfaces can render the same handoff while partial or cancelled
-responses remain visible without being mistaken for conversation context.
-
-`VideoPlayer` accepts either streaming player props or a completed saved video:
+`createVideoChatHandler` mounts one endpoint. The `action` query selects capabilities, response, opening media, narration, suggestions, speech, transcription or welcome. Every action applies authorization, origin restrictions, bounded request bodies, cancellation and safe public errors.
 
-```tsx
-<VideoPlayer {...chat.playerProps} />
-<VideoPlayer video={savedVideo} />
-```
+Applications supply required `streamText` and `generateText` callbacks, plus optional `generateSpeech`, `transcribe`, `searchMedia` and `generateVideo`. Text streams can be plain async iterables or structurally compatible AI SDK results. Vercel AI SDK is an optional application integration, not the core abstraction or a requirement.
+
+Optional `resolveAnswer({ prompt, conversation, signal })` returns an existing assistant's completed answer as a nonempty string, bounded to 32,000 characters after trimming and 30 seconds. It runs only after authorization and full input validation. Its output is the video planner's sole factual source, not a second assistant answer. Empty, oversized, failed or timed-out output returns `502 answer_unavailable`; cancellation returns `499 aborted`. This source constraint is model guidance, not automatic fact verification.
 
-Built-in renderers are always available, so a streaming `VideoPlayer` does not
-require a template registry. `playerProps` is a spread-ready player binding; it
-contains the customer registry supplied to `useVideoChat` when one exists, but it
-does not expose the built-in planning catalog. Import `builtinTemplates` from
-`@vanillaskyai/video/templates/catalog` for labels, schemas, selection guidance,
-and other React-free metadata.
+The response action accepts `prompt`, `mode`, `orientation`, optional bounded `conversation`, `opening` and `style`. The model produces a single creative brief followed by shots, reserving an authored ending. The server converts these into validated footage scenes or chapters; models do not choose renderer IDs or author lifecycle events.
 
-The chat owns playback startup, speech, and synchronization. Custom saved-video
-players may choose a `VideoPlaybackMode` to match browser autoplay rules.
+Two visual modes remain: `cinematic` (AI video) and `pexels` (application-owned stock search). AI mode never silently substitutes stock. Missing/failed footage becomes an authored chapter without losing narration. The default UI opens on a chapter; the opening-media action is available to custom interfaces.
 
-Set `nativeMediaAudio={{ volume: 0.85 }}` when scene video files contain an
-embedded audio track. The active clip's audio becomes a second layer alongside
-the video's continuous `audio` soundtrack. Both follow the player's master
-mute control; `nativeMediaAudio.volume` and serialized `audio.volume` set their
-independent mix levels. Incoming preroll videos remain muted until active.
+`maxGeneratedVideos` bounds attempted generated clips, including failures (default five). Zero keeps chapter recovery. `mediaConcurrency` overlaps bounded jobs while preserving narrative order. `generatedClipDurationSec` must match the application adapter. `generateVideoTimeoutMs` bounds waiting, not provider charges. The application owns credentials, authentication, storage, delivery, billing and provider cancellation.
 
-Saved-video playback performs no generation request. `VideoPlayerBinding` and
-the internal reducer state are not public types.
+The video callback receives `requestedDurationSec`, `shotDirection` and an absolute `deadlineAt`, alongside its abort signal. Returned media may report `durationSec`. Configure the model, clip duration and timeout together in the application adapter; the server accepts timeouts up to ten minutes, while the client defaults to an eleven-minute response deadline. These are safety ceilings, not latency promises.
 
-`loop` and `onSceneChange` apply to saved-video playback. `loop` restarts a
-completed video from the beginning instead of showing the replay affordance;
-`onSceneChange(scene, index)` fires whenever the scene under the playhead
-changes, including when a loop wraps back to the first scene. Streaming
-playback is unaffected by either. `onComplete(video)` reports that a streamed
-response finished composing; `onPlaybackEnd(video)` reports that the visible
-playhead actually reached the end for either a stream or saved replay.
+Planning and playback share one conservative narration budget, reserving at least 0.8 seconds of quiet footage. Before buying a clip, the handler allows one bounded `generateText` call with task `narration-rewrite`. Oversized or failed rewrites retain the original narration on a chapter and do not buy a clip. Measured audio and decoded footage are checked again before playback; normal video runs at its native speed without repeats. Rewriting is model-assisted, not automatic fact verification.
 
-Graphic scenes use fixed black backgrounds, white/neutral typography, and the system font stack. `VideoInput.brand`, `VideoStyle.brand`, `VideoBrand`, `VideoBrandInput`, `VideoBackground`, and `resolveVideoBrand` are removed. Media retains natural color. Persisted schema `0.2` and event protocol `0.6` reject earlier versions; changing a version field alone is not a migration.
+`authorize` is required; use `authorize: "none"` only for intentionally local/test handlers. `invalidPartBehavior: "drop"` preserves valid scenes after malformed planner output; `"fail"` opts into strict failure. Interrupted plans preserve playable partial answers and emit a safe warning. The narration action is a fallback for missing narration, not a second model call in the normal path.
 
-## Template authoring
+## Streaming, replay and diagnostics
 
-The template entry point owns React render definitions only. React-free server
-metadata registries are created through `/server`.
+Responses use protocol 0.6 SSE. A declared `data.video-chat-opening` event announces the opening and `data.video-chat-preparation` allows bounded preparation ahead of ordered `scene.add`. Preparation alone never authorizes scene playback. Saved videos retain schema 0.2; parsing/checksums do not authenticate ownership or tenancy.
 
-### Values
+Completed media is announced immediately, even when an earlier shot is still generating. Byte warming uses a bounded queue; only the active and next scenes may allocate playback decoders. An ambiguous interrupted cinematic request is not automatically resubmitted.
 
-- `defineTemplate(definition)`
-- `createTemplateRegistry(options)`
+`onError` receives private errors server-side. `onWarning` receives bounded safe warnings. `onComplete` receives a server-only generation summary after an actual completion, including recovered partial output. Raw provider usage/metadata requires explicit `includeRawProviderData`. Observer failures never affect generation.
 
-### Types
+`onDiagnostic` and client `onPlaybackMetric` provide opt-in, local callbacks with opaque IDs, fixed reason codes and timing measurements. They contain no prompts, narration, asset URLs or credentials and perform no automatic reporting. First-frame measures a presentation opportunity; first-media-frame requires actual decoder proof. Speech onset uses playback events, not preparation estimates.
 
-- `TemplateDefinition`
-- `TemplateExample`
-- `TemplateJsonSchema`
-- `TemplateFamily`
-- `TemplateTimingMetadata`
-- `TemplateTransitionTiming`
-- `TemplateRegistry`
-- `SceneTemplate`
-- `SceneTemplateMetadata`
-- `SceneTemplateProps`
-
-`SceneTemplateProps.progress` is always the raw `0 → 1` scene clock.
-Transition-enabled templates may use the optional `motionProgress` clock for
-presentation motion; the renderer-owned overlap never prevents that clock from
-reaching `1` across the complete template lifecycle. Their metadata must provide
-`transitionTiming.entryReadyProgress` and `transitionTiming.holdProgress`.
+Duration diagnostics distinguish estimated/rewritten narration from prepared speech and actual clip duration. Playback reports buffered seconds, native media/scene durations and repeat count. Stall reasons distinguish generation, speech and media decoding.
 
-Template timing uses `preferredDuration`; `duration` is not part of the
-package. `AuthoringTemplate` is inferred and internal.
+The host-only `narration-rewrite` diagnostic phase distinguishes rewritten, empty, oversized, timed-out, failed and cancelled helper calls without including text. Generated clips retain their requested budget when actual duration is absent; stock has no generated-video duration/deadline cap. A valid returned duration governs available footage, and the mounted decoder still verifies its physical duration.
 
-## Built-in catalog
+## React integration
 
-The catalog entry point is JSON-safe metadata. It does not contain renderers.
+```tsx
+import { VideoChat } from "@vanillaskyai/video/react";
+import "@vanillaskyai/video/video-chat.css";
 
-### Values
+export function App() {
+  return <VideoChat options={{ endpoint: "/api/video" }} />;
+}
+```
 
-- `builtinTemplates`
+The default experience includes loading states, captions, pause/mute, interruption, complete-turn history and replay. The real `npm run dev:chat` interface is the UI reference.
 
-### Types
-
-- `BuiltinTemplateId`
-- `BuiltinTemplateMetadata`
+`VideoChat` accepts optional `branding: { name, logo?, homeUrl?, showDeveloperLinks? }`. It changes application identity only; omitting it preserves the default UI. Home URLs must be HTTP(S) or root-relative; no external theme or template system is introduced.
 
-Template family and timing types have one canonical home under `/templates`.
-
-## Test utilities
+For an application-owned interface, call `useVideoChat(options)` and spread `chat.playerProps` onto `VideoPlayer`, keyed by `chat.playerKey`. A custom `VideoChatVoice` replaces voice output without replacing session orchestration. Its optional `onStart` callback must signal actual speech onset.
 
-The test entry point allows deterministic consumer tests without provider
-credentials or model spend.
-
-### Values
-
-- `createMockVideoPlanner(options?)`
-- `simulateVideoStream(parts, options?)`
-- `videoFixtures`
-
-### Types
+Unclocked browser/custom speech owns its completion, with a bounded watchdog and quiet tail before advancing. Direct player integrations can supply `narrationActive(scene)` to preserve that behavior; the standard hook wires it automatically.
 
-- `MockVideoPlannerOptions`
-- `SimulatedVideoStreamOptions`
+When wiring `onStallChange(stalled, reason)` manually, do not pause the voice for a `speech` wait: the player is waiting for speech to start or finish. Pause voice only for generation or decoding waits. The standard hook already applies this policy.
 
-The fixtures cover successful generation, delayed streaming, truncation,
-invalid scenes, provider failure, content filtering, abort, and timeout.
-
-## CLI
-
-The `vanillasky` binary supports:
-
-- `init`
-- `doctor`
-- `templates list`
-- `templates describe`
-- `templates create`
-- `templates add`
-- `templates sync`
-- `templates check`
-- `templates add --dry-run`
-- `templates add --diff`
-
-`init` writes the canonical app-owned provider and configuration shell while
-using the SDK's packaged interface, session, handler, and built-in templates.
-`doctor` is read-only and offline. The old top-level template commands are not
-aliases; this is an intentional pre-1.0 namespace change.
+`createVideoChatVoice` uses generated speech when configured and browser speech otherwise. Preparation duration may be estimated; measured generated audio supports offsets for narration groups. Cancellation releases stale voice/media work. Missing optional footage must not discard the spoken answer.
 
-Generated customer files import only the public entry points in this document.
-Browser registries import `createTemplateRegistry` from `/templates`. Server
-registries import `createServerTemplateRegistry` and `ServerTemplateMetadata`
-from `/server` without crossing a React type boundary.
-
-## Serialized video
-
-- A completed `Video` is JSON-serializable and may be stored by the host.
-- Every completed value carries the required storage field
-  `schemaVersion: "0.2"`; it is independent from streaming protocol `0.6`.
-- `parseVideo(value: unknown)` is the strict universal storage boundary. It
-  validates the full document and returns a detached, deeply frozen `Video`.
-- JSON serialization remains platform-native; the SDK has no redundant public
-  serializer.
-- Patch releases preserve round-trip compatibility.
-- The 0.1 contract supports the current schema only. It has no compatibility
-  aliases or implicit coercions.
-- Invalid documents throw `VideoValidationError` with `invalid_video`.
-  Unsupported future or unknown versions use `unsupported_video_version` and
-  fail before any renderer runs; they are never rendered partially.
-- Raw prompts, provider payloads, and credentials are never retained by
-  default.
-- Chat snapshots omit raw source, instructions, and the supplied-media URL
-  index. Hosts own storage, tenant policy, deletion, and media URL expiry.
-- Replay through `<VideoPlayer video={savedVideo} />` never calls an LLM.
-- Completion checksums detect accidental drift only; they do not provide
-  authenticity, authorization, or tenancy security.
-
-## Intentionally excluded from 0.1
-
-- Provider-specific OpenAI or Anthropic wrapper clients.
-- Rendering/export infrastructure.
-- Hosted persistence.
-- OpenTelemetry integration.
-- Automatic factual verification or scene repair.
-- Standalone video generation hooks, handlers, narration, and timeline factories.
-- Undocumented API aliases.
-
-
-## Playback measurements
+`chat.warnings` are developer notices; the unchanged default shell stays quiet. `showRecoveryNotice` opts into a fixed dismissible recovery notice without exposing arbitrary provider messages.
 
-`UseVideoChatOptions.onPlaybackMetric` receives the exported
-`VideoChatPlaybackMetric` union. Every event contains an opaque `turnId`, `mode`,
-and nonnegative `elapsedMs` since the prompt was submitted:
+## Deliberately outside the maintenance scope
 
-- `first-frame`: first committed active scene at an animation-frame opportunity;
-- `first-media-frame`: first decoded frame reported by the mounted footage surface;
-- `first-speech`: actual speech playback onset, with `source` equal to `browser`,
-  `generated`, or `custom`;
-- `stall`: a finished wait for the next prepared scene, with `durationMs` and
-  `reason: "scene-generation"`.
-
-Metrics contain no prompt, narration, scene, URL, or provider diagnostics. There
-is no automatic network reporting. Use opaque identifiers when supplying
-`createTurnId`. Observer throws and rejected promises cannot affect playback.
-Replay and stale/cancelled callbacks do not create fresh response measurements.
-Pauses end a stall interval; paused time is excluded from stall duration.
-
-Custom `VideoChatVoice.speak` implementations can call their optional
-`onStart()` argument when audio actually begins. Without that signal, speech
-onset is unavailable, not zero. Built-in voices use browser utterance `start`
-and audio `playing` events, not request completion or preparation estimates.
-
-`VideoPlayerProps.onFramePresented` and `onStallChange` expose the underlying
-presentation and stream-starvation signals for custom players. They do not
-measure media-decoder buffering. See [Performance](docs/performance.md).
-
-### Bounded generated-video previews
-
-`VideoChatHandlerOptions.generateVideoTimeoutMs` optionally sets the generated media
-resolver deadline (integer 1–120000 milliseconds, default 15000). The host still owns
-provider cancellation, authorization and spend limits; a timeout does not prove the
-provider avoided a charge. `maxGeneratedVideos` continues to count attempted clips.
-
-`VideoChatProps.showRecoveryNotice` opts into a dismissible, fixed SDK
-media-recovery notice; it never displays arbitrary provider messages.
-
-`VideoChatHandlerOptions.onDiagnostic` is an optional host-only observer for
-request, authoring and media phase timings with fixed recovery reason codes.
-It does not retain prompt, narration, query, asset URL or provider error text,
-and cannot affect response delivery. No new entry points or named exports are
-introduced; its additive signature is checked in the packed consumer contract.
+No provider SDK wrappers in core, custom-template product, rendering/export service, hosted persistence, automatic fact verification, provider billing management or model compatibility matrix. Applications own delivery and provider-specific configuration. See the quickstart and provider recipes for supported reference integrations.