@vanillaskyai/video 0.8.8 → 0.10.0

package/dist/validate-4OUD2CLX.js

@@ -0,0 +1,10 @@
+import {
+  createTemplateSceneValidator,
+  validateTemplateSceneStructure
+} from "./chunk-IQMYK5DX.js";
+import "./chunk-EGVQODKU.js";
+import "./chunk-73NTSFFI.js";
+export {
+  createTemplateSceneValidator,
+  validateTemplateSceneStructure
+};

package/docs/architecture.md

@@ -67,7 +67,7 @@ prompt/validation registry in `vanillasky/server.ts`.
 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,
-   brand, and approved media.
+   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.

package/docs/concepts.md

@@ -31,7 +31,7 @@ or export pipeline when an encoded file is required.
 
 The viewer sends a prompt with bounded completed conversation turns. The server
 adds trusted application `instructions`, template capabilities, and the selected
-visual mode. `VideoChat` options control brand, style, orientation, and custom
+cinematic mode. `VideoChat` options control style, orientation, and custom
 templates. Exact facts belong in the authorized prompt or conversation; secrets
 and provider configuration stay on the server.
 

package/docs/custom-templates.md

@@ -37,7 +37,7 @@ npx vanillasky templates describe customer-health
 Or copy a built-in when its behavior is already close:
 
 ```bash
-npx vanillasky templates add bigNumber
+npx vanillasky templates add keyFigure
 ```
 
 Then edit the owned `.tsx` file, regenerate the two small registries, and check
@@ -50,7 +50,7 @@ npx vanillasky templates check
 
 For an original template, the source is
 `vanillasky/templates/customer-health.tsx`. For the copied built-in, it is
-`vanillasky/templates/bigNumber.tsx`. These are application source: commit them,
+`vanillasky/templates/keyFigure.tsx`. These are application source: commit them,
 review them, and change them like any other React component.
 
 `create` and `add` run `sync` once, so the generated entry points exist
@@ -62,8 +62,8 @@ registry parity.
 Preview either operation without applying the proposed file writes:
 
 ```bash
-npx vanillasky templates add bigNumber --dry-run
-npx vanillasky templates add bigNumber --diff
+npx vanillasky templates add keyFigure --dry-run
+npx vanillasky templates add keyFigure --diff
 ```
 
 `--dry-run` lists every proposed file and `--diff` shows its content changes,
@@ -119,8 +119,8 @@ the selected catalog contains a template with one of those two jobs.
 
 Customer templates hard-cut by default. Opt into renderer-owned fades only
 for scenes that use the standard media-background variables, and only after
-both timing points are visually tested in portrait and landscape. Shared brand
-gradients and unchanged media do not crossfade:
+both timing points are visually tested in portrait and landscape. Shared render
+black backgrounds and unchanged media do not crossfade:
 
 ```tsx
 export default defineTemplate({
@@ -277,7 +277,7 @@ import { VideoPlayer } from "@vanillaskyai/video/react";
 import { templates } from "../vanillasky";
 
 const savedVideo: Video = {
-  schemaVersion: "0.1",
+  schemaVersion: "0.2",
   orientation: "portrait",
   scenes: [{
     id: "customer-health-preview",
@@ -288,21 +288,7 @@ const savedVideo: Video = {
     },
     timing: { fixedDuration: 5 },
   }],
-  style: {
-    brand: {
-      font: "Inter",
-      scriptFont: "Caveat",
-      background: { type: "gradient", colors: ["#8711C1", "#2167E3"] },
-      colors: {
-        primary: "#00E5A0",
-        secondary: "#006BE5",
-        foreground: "#FFFFFF",
-        surface: "#0A0A14",
-        surfaceElevated: "#14152A",
-        muted: "#A7A6B0",
-      },
-    },
-  },
+  style: {},
 };
 
 export function TemplatePreview() {
@@ -328,8 +314,8 @@ maps.
 
 Useful formats add grounding behavior:
 
-- `grounded-stat` marks numeric statistical evidence for the planner; it does
-  not compare the value against raw input at runtime;
+- `grounded-stat` accepts numeric or string quantities and requires an exact
+  quantity in raw input, preserving its unit;
 - `grounded-quote` requires the quote to exist verbatim in the input;
 - `uri` validates approved media URLs restored by the server;
 - `stock-media-keyword` is only for hosts that resolve stock media before a
@@ -338,14 +324,13 @@ Useful formats add grounding behavior:
 Templates whose core proof needs a real statistic can add
 `"x-vanillasky": { "requiresStat": true }`. See the structured-data reference for a complete example.
 
-For media-backed chat scenes, copy the built-in `media` template and keep its
+For media-backed chat scenes, copy the built-in `cinemaMedia` template and keep its
 `mediaKeyword`, `mediaUrl`, and `mediaType` contract. Configure `searchMedia` on
 the chat handler so the server resolves semantic searches into approved assets.
 The chat request does not accept a separate supplied-media input list.
 
-The automatic `opening` uses the built-in `media` variables (`texts` and
-`mediaType: "gradient"`). If you replace `media` while using automatic
-openings, keep that variable contract.
+The automatic `opening` uses the built-in `chapterTitle` variable `title`.
+If you replace that template while using automatic openings, keep this contract.
 
 ## What belongs where
 

package/docs/customization.md

@@ -14,7 +14,6 @@ heading and a root class when the application needs its own copy or chrome color
 <VideoChat
   className="acme-chat"
   welcomeTitle={<>Ask Acme<br />See the answer</>}
-  options={{ brand: acmeBrand }}
 />
 ```
 
@@ -32,10 +31,10 @@ that instance:
 ```
 
 The built-in navigation carries the VanillaSky logo. `welcomeTitle` changes
-the welcome heading; it does not replace the navigation logo. `options.brand`
-styles generated video content independently of the surrounding controls.
+the welcome heading; it does not replace the navigation logo. Graphic scenes
+use fixed black backgrounds and white/neutral system typography.
 
-Use `options` for the endpoint, templates, orientation, visual brand, request
+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.
@@ -44,63 +43,16 @@ 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.
 
-## Background and semantic brand
+## Cinematic visual direction
 
-Omit brand configuration to use the standard `cosmic` background. Prefer a
-named curated choice over raw color work:
+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.
 
-```ts
-const brand = {
-  name: "Acme",
-  logoUrl: "https://cdn.acme.com/logo.svg",
-  font: "Inter",
-  scriptFont: "Caveat",
-  background: "twilight",
-  colors: {
-    primary: "#6D5EF5",
-    secondary: "#3D2A78",
-    foreground: "#FFFFFF",
-    surface: "#17122F",
-    surfaceElevated: "#231B42",
-    muted: "#A7A6B0",
-  },
-};
-```
-
-Gradient presets: `cosmic`, `horizon`, `twilight`, `meadow`, `velvet`,
-`flamingo`, `peach`, `saffron`. Solid presets: `black`, `midnight`,
-`aubergine`, `coal`, `navy`. When a named choice genuinely cannot express the
-brand, use `{ colors: ["#112233", "#334455"] }` for a custom gradient or
-`{ color: "#070B20" }` for a custom solid.
-
-`colors` may be partial; the resolver fills every semantic token before the
-video is emitted. With no foreground, named and custom backgrounds
-deterministically select black or white for at least 4.5:1 contrast across the
-full rendered sRGB ramp, including gradient interiors. A ramp that neither can
-cover is rejected. An explicit foreground is preserved and validated by the
-same invariant during input resolution and replay; low-contrast values are
-rejected with the failing path and minimum ratio. Elevated surfaces derive an
-accessible internal text treatment without changing the semantic foreground.
-Use an approved public or signed URL for logos, and never put a private storage
-credential in the config.
-
-## Global visual direction
-
-Leave visual direction unset to use VanillaSky's defaults, or set one coherent
-look for the completed video:
-
-```ts
-style: {
-  density: "airy",           // airy | normal | packed
-  motion: "calm",            // calm | normal | punchy
-  textArchetype: "cinematic",
-  backgroundEffect: "slow-zoom-out",
-}
-```
-
-These are defaults, not generated CSS. A validated scene may still select a
-more appropriate text or background treatment when its trusted template allows
-it.
+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.
 
 ## Opening
 

package/docs/getting-started.md

@@ -96,8 +96,8 @@ spoken hook from the response stream before the full plan is complete, holds its
 scene is ready, reaches its final frame, and leaves the composer ready for
 another turn. With stock media enabled, click a welcome or follow-up card and
 confirm its footage carries directly into that opening. With generated video
-enabled, confirm the only choices are Templates and Full AI video and that the
-first generated shot continues the spoken hook without repeating it.
+enabled, confirm that relevant generated shots and editorial templates form one
+cinematic response, and the first shot continues the hook without repeating it.
 
 The generated local authorization accepts localhost only. Replace it with your
 real session check, rate limits, and usage policy before deploying.

package/docs/immersive-interface.md

@@ -67,8 +67,7 @@ hover movement remain inside the rail's available space.
 ## Layout and access
 
 The foreground video preserves its scene ratio, so diagrams and text remain
-visible without cropping or distortion. Ambient opening media fills the
-surrounding viewport, with a gradient fallback when media is unavailable.
+visible without cropping or distortion. The surrounding viewport remains black during playback.
 Display layout does not rewrite the saved response's orientation. See
 [responsive orientation](responsive-orientation.md) for saved videos and custom
 players.
@@ -79,9 +78,9 @@ radio behavior, and popovers support Escape and outside-click dismissal.
 Reduced motion removes movement and fades; increased contrast strengthens
 surface opacity and borders.
 
-## Branding
+## Customization
 
 Use the existing `welcomeTitle`, `className` and `options` props to customize
-copy, scoped CSS properties and generated video branding. There is no separate
+copy, scoped CSS properties and generated footage direction. There is no separate
 light/dark appearance picker. See [customization](customization.md) for examples.
 Use `useVideoChat` when the application needs to own the whole interface.

package/docs/maintainers/cinematic-migration.md

@@ -0,0 +1,38 @@
+# Cinematic contract migration
+
+The eight-template replacement is an approved breaking pre-1.0 change. Persisted Video schema is now `0.2`; event protocol is `0.6`.
+
+## Breaking changes
+
+- Removed `VideoInput.brand`, `VideoStyle.brand`, `VideoBrand`, `VideoBrandInput`, `VideoBackground`, and `resolveVideoBrand`. Graphics use black, white/neutral text and system typography. Naturally colored media is unaffected.
+- Removed all 28 old built-in IDs. Eight new IDs describe different schemas: `cinemaMedia`, `chapterTitle`, `focusCards`, `editorialTimeline`, `mobileMessage`, `comparison`, `quote`, `keyFigure`.
+- `parseVideo` rejects the old persisted `0.1` fixture with `unsupported_video_version`. The parser also rejects `style.brand` if a caller merely stamps the new version onto an old object.
+- Scene source intent uses `mediaKeyword` (up to 80 characters) and optional `mediaSource`. The host owns `mediaUrl`, `mediaPoster` and resolved `mediaType`. No gradient fallback mode. Full-bleed requires a resolvable intent or asset; Reach out can remain on black when media is unavailable.
+
+## Adoption
+
+Regenerate videos from the retained source and narration using the new catalog. Do not automatically relabel old IDs: before/after emojis, count-ups and factual quote/stat schemas have different meanings. Retain an older published SDK in a separate legacy playback boundary if historical exports must continue to render; do not pass those payloads into the new parser.
+
+Before (old persisted format):
+
+```json
+{"schemaVersion":"0.1","scenes":[{"id":"one","templateId":"media","variables":{"texts":"A new perspective","mediaType":"gradient"},"timing":{"fixedDuration":4}}],"style":{"brand":{"font":"Inter"}}}
+```
+
+After re-authoring that title as a chapter:
+
+```json
+{"schemaVersion":"0.2","scenes":[{"id":"one","templateId":"chapterTitle","variables":{"title":"A new perspective"},"timing":{"fixedDuration":4}}],"style":{}}
+```
+
+Evidence: persistence tests preserve the untouched old release fixture and assert rejection, accept current-style round trips, reject hidden/non-JSON input as before, and pin new checksums. Template tests cover both orientations, deterministic seeking, exact evidence text and single-decoder backdrop ownership. Final packed consumer and mobile playback checks remain release gates.
+
+## Render fonts
+
+The cinematic templates use `-apple-system, BlinkMacSystemFont, "Helvetica Neue", Roboto, Arial, sans-serif` at regular and medium weights. Apple devices keep native system typography. The existing `@vanillaskyai/video/video-chat.css` entry registers packaged Roboto v51 WOFF2 subsets as the fallback for environments without those fonts. Standalone player and source-owned template integrations should also import that stylesheet. No font is fetched from Google at runtime; browsers fetch local packaged subsets only when Roboto is selected for the rendered glyphs. The font assets include the SIL Open Font License and a source/hash manifest.
+
+Live native fonts and a Linux renderer’s Roboto have slightly different metrics. For repeatable exports, keep the browser, installed fonts, viewport and package version fixed, and await `document.fonts.ready` after mounting the final scene before capturing frames. This is a host export responsibility; the SDK does not add a separate export API or force downloaded fonts onto Apple devices.
+
+## Media-led follow-up
+
+The owner requested removing `focusCards`. Regenerate persisted videos using that ID; migrate parallel explanations to narration over footage rather than another bullet layout. The remaining seven templates retain their IDs. Comparison, quote, key figure and timeline accept optional standard media variables and remain readable on black when assets are absent. No provider callback signatures or host limits change.

package/docs/media-and-audio.md

@@ -6,20 +6,19 @@ VanillaSky keeps provider choice in the application. The SDK defines small
 server callbacks, advertises only the capabilities you configure, and keeps
 all credentials out of React and the browser bundle.
 
-## Two visual modes
+## One cinematic mode
 
-The chat exposes only two clear choices:
+The director combines relevant footage and seven editorial templates. Graphics
+use black and white; footage carries atmosphere and concrete action. Each media
+scene declares `mediaSource: "stock"` or `"generate"`. Provider availability and
+host budgets constrain those choices. There is no all-stock or all-AI switch.
 
-| Mode | Visual source | Required callback |
-| --- | --- | --- |
-| `templates` | Trusted rendered templates, optionally with stock footage | none; `searchMedia` is optional |
-| `full` | A generated clip for every visual beat | `generateVideo` |
+The canonical templates are `cinemaMedia`, `chapterTitle`,
+`editorialTimeline`, `mobileMessage`, `comparison`, `quote`, and `keyFigure`.
+All except `chapterTitle` accept optional media backgrounds. Editorial overlays use soft text shadows and a dark contrast scrim over relevant media, and fall back to black. Use at most one explanatory overlay per typical thirty-second answer. Full-bleed
+footage has no headline; narration and subtitles carry the explanation.
 
-Templates are always available and are the fast, inexpensive fallback. The
-`full` mode is advertised only when `generateVideo` exists. VanillaSky does not
-offer a mixed mode that generates only some scenes.
-
-## Stock media for templates
+## Reviewed stock
 
 Add `searchMedia` when template answers, the welcome screen, and follow-up
 cards should use approved photography or footage:
@@ -46,15 +45,16 @@ createVideoChatHandler({
 The planner emits a short semantic keyword, not a URL. The callback returns an
 application-approved image or video URL, and the SDK validates it before it
 reaches a scene. Return `null` when no licensed, safe, relevant asset exists;
-the template falls back to its built-in treatment.
+`cinemaMedia` becomes a chapter using its grounded `fallbackText`; a message can
+keep its content on black. Missing fallback copy produces an explicit error.
 
 For Pexels, keep `PEXELS_API_KEY` on the server, enforce a deadline, filter for
 orientation, and return only validated Pexels asset domains. Licensing,
 attribution, caching, MIME checks, and byte limits remain application-owned.
 
-## Full generated video
+## Planned generated shots
 
-Add `generateVideo` to enable full AI video. It receives the planned visual
+Add `generateVideo` to enable generated shots within cinematic responses. It receives the planned visual
 subject plus the generated look so every clip can follow the same direction:
 
 ```ts

package/docs/motion-and-effects.md

@@ -47,22 +47,14 @@ only when two ranges are contiguous (allowing floating-point arithmetic noise)
 and both templates declare `usesGlobalTransition: true` with valid
 `transitionTiming` metadata. It is also conditional on the effective backdrop:
 the 300 ms outer crossfade runs only when the resolved background media changes.
-Scenes that share the brand gradient, or the same resolved media backdrop, do
+Scenes that share the black base, or the same resolved media backdrop, do
 not crossfade. This keeps one stable background visible while each template
 plays its own entrance, hold, and exit choreography.
 
-Animated brand gradients use a closed, eased loop per scene. Every gradient
-family reaches the exact same zero-velocity frame at progress `0` and `1`, and
-content-seeded variation converges before the boundary. A same-gradient cut
-therefore changes only the foreground template; the backdrop cannot jump or
-flash between scene-specific phases.
-
-The player owns a persistent brand-color backdrop beneath every scene. Built-in
-renderers preload through the same component state used for playback, so their
-first frame does not suspend when a new template type appears. If a genuinely
-cold custom renderer does suspend, its transparent loading frame reveals the
-brand backdrop rather than a black canvas. Scene media still belongs to the
-scene and covers that base only while the media scene is active.
+The player owns a fixed black backdrop beneath the scenes. Built-in renderers
+preload through the same component state used for playback. A cold custom
+renderer reveals this black base while loading. Resolved scene media covers it
+only while the media scene is active.
 
 During a changed-media overlap, the current scene continues to its exact end.
 The incoming component may be pre-mounted for media readiness, but remains
@@ -98,7 +90,7 @@ also protects intentional hard cuts; it does not pause or otherwise alter the
 visual or soundtrack clocks.
 
 Undefined or unknown transition names preserve a hard cut and unmodified local
-motion. Overlapping ranges also hard-cut. A timeline gap renders the owned brand
+motion. Overlapping ranges also hard-cut. A timeline gap renders the fixed black
 background instead of replaying an earlier scene.
 
 ## Reduced motion

package/docs/persistence.md

@@ -10,7 +10,7 @@ SDK serializer. An interrupted turn can remain visible without qualifying as
 completed conversation history. The default `VideoChat` keeps history in memory;
 use the headless hook when the application needs durable storage.
 
-Every stored video has `schemaVersion: "0.1"`. This storage version is separate
+Every stored video has `schemaVersion: "0.2"`. This storage version is separate
 from streaming protocol `0.5`. The 0.1 policy supports the current storage
 schema only: there are no compatibility aliases or implicit coercions.
 
@@ -39,12 +39,12 @@ The release verifier compiles this exact documented snippet against the packed
 SDK artifact, including its root and React subpath imports.
 
 `parseVideo(value: unknown)` validates the complete shape, known fields,
-resolved brand and style, audio, metadata, unique scenes, timing, and JSON-safe
+style, audio, metadata, unique scenes, timing, and JSON-safe
 template variables. It returns a detached, deeply frozen `Video`, so later
 changes to the loaded object cannot mutate player state.
 
 Invalid data throws `VideoValidationError` with `code: "invalid_video"`.
-Unknown or future storage versions throw the same error class with
+Previous, unknown, or future storage versions throw the same error class with
 `code: "unsupported_video_version"`. `<VideoPlayer video={value} />` repeats
 this boundary validation and rejects the entire value before any renderer
 runs; it never renders a partial future document.

package/docs/production.md

@@ -20,12 +20,14 @@ The handler rejects unknown templates and fields, invalid variables, unsafe
 media, and fabricated quote-template content before a scene reaches the
 player. Read the [security guide](security.md) for the complete controls.
 
-## Visual modes and providers
+## Cinematic direction and providers
 
-Keep templates available on every deployment. They are the reliable fallback
-when stock, speech, or generated-video providers are missing or late. Add
-`searchMedia` for approved stock footage and `generateVideo` for the separate
-full AI video mode. Do not expose a partial generated-video mode.
+One cinematic mode combines footage and editorial graphics according to the
+story. Keep templates available as grounded fallbacks. Add `searchMedia` for
+reviewed stock and `generateVideo` for selected illustrative shots. The planner
+sets `mediaSource` per media scene; the host enforces the generation budget.
+A stock candidate must match the subject, action and permitted crop. Return
+`null` for uncertainty rather than broadening an essential detail.
 
 Use explicit provider deadlines. Generated video should use idempotency keys
 and `maxRetries: 0` so one visible action cannot silently create several
@@ -36,13 +38,13 @@ licensing before use.
 
 The planner's first streamed object supplies the spoken hook and media keyword.
 Start speech immediately, resolve stock in parallel, and keep the opening
-playing until the first narrated scene and its media are ready. Welcome cards
+playing until the contiguous preparation cushion and first frame are ready. Welcome cards
 should carry a prepared hook and preloaded footage so they can start without a
 model round trip.
 
 Do not wait for the complete plan before showing the first validated scene.
 Preload upcoming assets and keep the current visual if the next one is late.
-For full AI video, reserve the first shot in the opening object so generation
+When generated footage is useful, reserve the first shot in the opening object so generation
 can begin while the planner streams later scenes.
 
 ## Data and privacy
@@ -101,8 +103,8 @@ npm test
 - [ ] Keys exist only in the server secret store.
 - [ ] Authentication, tenant policy, rate limits, and origin allowlist are live.
 - [ ] Cancellation, timeouts, fallbacks, and safe errors are tested.
-- [ ] Template mode completes when every optional provider is unavailable.
-- [ ] Full mode appears only when generated video is configured.
+- [ ] Grounded graphic recovery works when every optional provider is unavailable.
+- [ ] Per-scene media choices obey provider availability and spending limits.
 - [ ] Both orientations render and narration stays synchronized.
 - [ ] A packed-artifact consumer and deterministic browser chat pass.
 - [ ] One bounded real-provider run meets the product's latency and quality target.

package/docs/provider-integration.md

@@ -61,11 +61,10 @@ dependencies and never enter the browser bundle.
 The planner emits a 6-9 word hook first, then continues into the scenes in the
 same stream. The stock lookup is a separate cancellable request, so it cannot
 delay speech or planning. A welcome card can carry a prewritten `opening`, which
-starts immediately with its already-loaded media. For a full AI response, the
+starts immediately with its already-loaded media. When generated shots are available, the
 same first streamed object reserves the exact first body scene. Its clip starts
-generating while the planner continues with scenes two through five. Template
-responses stream their first resolved scene without waiting for the rest of the
-plan, and normal narration is written in that same planner call rather than
+generating while the planner continues the story. Playback begins after its
+contiguous preparation cushion, without requiring the entire plan, and normal narration is written in that same planner call rather than
 through a second model round trip.
 
 The matching complete React interface is one component and one scoped style
@@ -121,14 +120,10 @@ streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
 }),
 ```
 
-Measured on one grounded chat answer with the 28 built-in templates, leaving
-the Anthropic default in place cost roughly twenty seconds before the first
-scene; disabling reasoning brought the same plan to a few seconds. Other
-providers expose equivalent controls under their own names. Treat the exact
-values as host-owned tuning: the lowest effort setting is the fastest, but a
-weaker plan misses schema limits more often, which shows up as rejected scenes
-in `onComplete`. Compare `timeToFirstSceneMs` and `rejectedSceneCount` across
-settings before fixing one.
+Reasoning settings can substantially affect startup latency. Measure them with
+your installed catalog and representative requests. Compare first-scene timing,
+rejected scenes and factual accuracy; the fastest token stream is not useful if
+its scenes cannot be rendered. Keep these settings in the provider adapter.
 
 VanillaSky never sets these controls. Provider selection, sampling parameters,
 and credentials stay with the application.
@@ -185,10 +180,8 @@ is intentionally substantial. It is stable for the same SDK version, template
 kit, media policy, and base prompt. Record input-token usage, keep the selected
 kit no broader than the product needs, and enable provider-side prompt caching
 where the chosen provider/model supports it. VanillaSky does not assume one
-provider's cache controls in its provider-neutral adapter. With the 28 built-in
-templates, the current catalog prompt is roughly 28,000 characters (about
-7,000 tokens before user input; tokenizer-dependent); provider-reported usage
-is the authoritative measurement.
+provider's cache controls in its provider-neutral adapter. The cinematic catalog contains seven templates; use provider-reported token
+usage as the authoritative measurement rather than a character estimate.
 
 Provider finish reasons `error` and `tool-calls` are terminal failures.
 `length` and `content-filter` may complete with already accepted scenes; a

package/docs/reference/design-system.html

@@ -104,7 +104,7 @@ body { background: #080b16; }
 <section class="doc-section" id="conversation"><div class="section-heading"><span class="number">03</span><h2>One field. Every follow-up.</h2></div><p class="section-copy">Speak or type directly over the picture. Beginning a question pauses playback. Sending starts the next answer; canceling returns to the previous playback state.</p><div class="doc-preview"><div class="demo-toolbar" aria-label="Composer preview states"><button type="button" data-state="ready" aria-pressed="true">Ready</button><button type="button" data-state="listening" aria-pressed="false">Listening</button><button type="button" data-state="thinking" aria-pressed="false">Transcribing</button></div><div class="conversation-composer"><div class="composer-meta"><span id="composer-status" role="status">Interactive preview · no microphone or model call</span></div><form class="composer" id="composer-demo"><button class="ghost transport" type="button" aria-label="Play preview" id="play-demo"><svg data-icon="play"></svg></button><label class="sr-only" for="demo-question">Question</label><textarea id="demo-question" rows="1" placeholder="Ask a follow-up…"></textarea><button class="ghost" type="button" id="mic-demo" aria-label="Preview listening state" aria-pressed="false"><svg data-icon="mic"></svg></button><button class="send" type="submit" aria-label="Preview send" disabled><svg data-icon="send"></svg></button></form></div></div><p class="doc-note">44px targets. 10px between microphone and send. The field grows to 120px and keeps the controls within reach.</p></section>
 <section class="doc-section" id="captions"><div class="section-heading"><span class="number">04</span><h2>Words stay with the picture</h2></div><p class="section-copy">The first subtitle takes the input’s bottom baseline. The complete cue remains readable without truncation. Reveal the input to move subtitles upward; expand for the transcript or restore hidden subtitles in Settings.</p><div class="doc-preview"><div class="demo-toolbar"><button type="button" id="restore-caption">Show subtitles</button><button type="button" id="toggle-transcript">Expand transcript</button></div><div class="line-row" id="caption-demo" data-expanded="false"><div class="caption-actions"><button class="caption-action" type="button" id="expand-action" aria-label="Expand subtitles" aria-expanded="false">Expand <svg data-icon="up"></svg></button><button class="caption-action" type="button" id="hide-action" aria-label="Hide subtitles"><svg data-icon="close"></svg></button></div><p class="line" id="compact-caption">Water absorbs the warm colors of sunlight,<br>leaving more blue light to reach your eyes.</p><div class="expanded-captions" id="transcript-demo" tabindex="0" aria-label="Expanded subtitles" hidden><span class="eyebrow">Full answer</span><p>The ocean’s color begins with sunlight.</p><p>Water absorbs the warm colors of sunlight, leaving more blue light to reach your eyes.</p><p>Depth, particles and the sky change what we see. That is why a shallow lagoon and the open ocean can look so different.</p></div></div></div></section>
 <section class="doc-section" id="suggestions"><div class="section-heading"><span class="number">05</span><h2>A little more curiosity</h2></div><p class="section-copy">A horizontal rail offers the next question. Video cards show their poster image before playback, including when autoplay is blocked. Hover or keyboard focus selects a card. Its outline and lift have room to breathe.</p><div class="doc-preview"><ul class="cards" aria-label="Example suggested questions"><li><button type="button" data-active><span class="card-art"></span><span class="card-wash"></span><span class="card-prompt">What is hiding in the deep ocean?</span></button></li><li><button type="button"><span class="card-art space"></span><span class="card-wash"></span><span class="card-prompt">Why do planets stay in orbit?</span></button></li><li><button type="button"><span class="card-art mind"></span><span class="card-wash"></span><span class="card-prompt">How does a memory begin?</span></button></li></ul></div><p class="doc-note">Reference artwork uses abstract color fields. The live rail uses the answer’s resolved media. Select a card here to place its question in the preview composer.</p></section>
-<section class="doc-section" id="foundations"><div class="section-heading"><span class="number">06</span><h2>Small decisions, shared everywhere</h2></div><p class="section-copy">System typography, generous touch targets and a compact spacing scale. The video carries the color; the interface carries meaning.</p><div class="doc-preview"><div class="type-row"><span style="font-size:40px;letter-spacing:-.055em;line-height:1.08">An answer worth watching.</span><code>Display · responsive / 1.08</code></div><div class="type-row"><span style="font-size:22px;letter-spacing:-.02em;line-height:1.45">A clear line over a moving picture.</span><code>Subtitles · 17–22px / 1.45</code></div><div class="type-row"><span style="font-size:16px;letter-spacing:-.015em;line-height:1.625">Ask a follow-up…</span><code>Input · 16px / 26px</code></div><div class="type-row"><span style="font-size:13px;color:var(--vs-media-muted)">One answer leads to another.</span><code>Context · 13px</code></div><div class="metrics"><div class="metric"><strong>44<span style="display:inline;font-size:15px"> px</span></strong><span>Minimum primary control target</span></div><div class="metric"><strong>180<span style="display:inline;font-size:15px"> ms</span></strong><span>Navigation and opacity fade</span></div><div class="metric"><strong>280<span style="display:inline;font-size:15px"> ms</span></strong><span>Input and subtitle movement</span></div><div class="metric"><strong>2<span style="display:inline;font-size:15px"> s</span></strong><span>Idle delay after revealing controls</span></div></div></div><p class="doc-note">First subtitles hide the input immediately unless the viewer is editing, listening or using keyboard focus. Reduced motion removes movement and fades. Increased contrast strengthens the surfaces and borders. The input respects bottom safe areas. Subtitle actions fade while inactive and return on hover, touch or keyboard focus. The foreground preserves the scene ratio and readable text. Ambient opening media or a gradient fills the surrounding viewport.</p></section>
+<section class="doc-section" id="foundations"><div class="section-heading"><span class="number">06</span><h2>Small decisions, shared everywhere</h2></div><p class="section-copy">System typography, generous touch targets and a compact spacing scale. The video carries the color; the interface carries meaning.</p><div class="doc-preview"><div class="type-row"><span style="font-size:40px;letter-spacing:-.055em;line-height:1.08">An answer worth watching.</span><code>Display · responsive / 1.08</code></div><div class="type-row"><span style="font-size:22px;letter-spacing:-.02em;line-height:1.45">A clear line over a moving picture.</span><code>Subtitles · 17–22px / 1.45</code></div><div class="type-row"><span style="font-size:16px;letter-spacing:-.015em;line-height:1.625">Ask a follow-up…</span><code>Input · 16px / 26px</code></div><div class="type-row"><span style="font-size:13px;color:var(--vs-media-muted)">One answer leads to another.</span><code>Context · 13px</code></div><div class="metrics"><div class="metric"><strong>44<span style="display:inline;font-size:15px"> px</span></strong><span>Minimum primary control target</span></div><div class="metric"><strong>180<span style="display:inline;font-size:15px"> ms</span></strong><span>Navigation and opacity fade</span></div><div class="metric"><strong>280<span style="display:inline;font-size:15px"> ms</span></strong><span>Input and subtitle movement</span></div><div class="metric"><strong>2<span style="display:inline;font-size:15px"> s</span></strong><span>Idle delay after revealing controls</span></div></div></div><p class="doc-note">First subtitles hide the input immediately unless the viewer is editing, listening or using keyboard focus. Reduced motion removes movement and fades. Increased contrast strengthens the surfaces and borders. The input respects bottom safe areas. Subtitle actions fade while inactive and return on hover, touch or keyboard focus. The foreground preserves the scene ratio and readable text. The surrounding viewport remains black during playback.</p></section>
 <footer class="doc-footer"><span>VanillaSky · VideoChat immersive interface</span><span>Rendered with the same tokens and component CSS as the experience.</span></footer>
 </div></main>
 <script>

package/docs/reference/protocol.md

@@ -1,10 +1,10 @@
-# Video Response Protocol 0.5
+# Video Response Protocol 0.6
 
 ## Transport
 
 The public transport is UTF-8 Server-Sent Events returned from a `POST` request.
 Responses use `Content-Type: text/event-stream`,
-`x-vanillasky-video-stream: 0.5`, `Cache-Control: no-cache, no-transform`, and
+`x-vanillasky-video-stream: 0.6`, `Cache-Control: no-cache, no-transform`, and
 `X-Accel-Buffering: no`. Each block has an SSE `id`, the event name
 `video`, and one JSON envelope in `data`. A final `data: [DONE]`
 closes the transport after a terminal protocol event. Comment heartbeats do not
@@ -14,7 +14,7 @@ change protocol state.
 
 ```ts
 type VideoEvent<T extends string, D> = {
-  protocolVersion: "0.5";
+  protocolVersion: "0.6";
   runId: string;
   sequence: number;
   eventId: string;        // exactly `${runId}:${sequence}`
@@ -42,7 +42,7 @@ finish reason, and a deterministic checksum. The reducer verifies that the
 snapshot equals the state produced by all prior events. The checksum detects
 accidental drift; it is not a cryptographic signature.
 
-The terminal snapshot carries persisted `schemaVersion: "0.1"`. That storage
+The terminal snapshot carries persisted `schemaVersion: "0.2"`. That storage
 version is independent from this streaming protocol version. Load stored
 snapshots through the universal `parseVideo` boundary described in the
 [persistence guide](../persistence.md).
@@ -100,3 +100,13 @@ SDK does not prescribe or operate a persistence service.
 Validate adapter output and persisted replay logs against this protocol before
 accepting them. A replay log must preserve ordering, checksums, and a terminal
 event.
+
+## Host-authored narration across cuts
+
+`VideoScene.narrationGroup` optionally joins adjacent shots to one prepared spoken paragraph. A host supplies the shared `id`, `text`, measured `totalSeconds`, and each segment's `offsetSeconds` and `durationSeconds`. Each scene retains its narration fragment and a matching `timing.fixedDuration`; fragments must exactly cover the paragraph in order. The planner cannot emit this field or guess speech timings.
+
+Grouped playback requires prepared speech with `supportsOffsets: true`. The generated-audio voice supports offsets; browser speech synthesis does not. The chat hook prepares and validates a complete group before showing its first scene, including saved replay. Hosts using a standalone player must prepare the paragraph and coordinate narration themselves before starting playback. Unsupported voices and mismatched measured durations fail explicitly. Default planner responses still prepare narration per scene.
+
+For standalone playback, provide a synchronous `narrationReady` callback alongside your `onSceneChange` narration handler. Return false while a new grouped paragraph awaits actual audio onset, then true from the voice's `onStart` callback; also release readiness on completion, failure, or interruption. Abort pending narration from the player's `onError` handler. `VideoChat` wires this automatically through its internal narration hook. For grouped paragraphs, the voice must invoke `onStart` when audio actually begins, not when audio is prepared or `play()` is requested. The first visual cue starts narration, then the playhead waits for that onset without pausing the voice. A missing onset stops the player with an error after eight seconds of active waiting. For prepared audio, also provide `narrationTime(scene)` using the active voice's optional `getCurrentTime()`: return paragraph-relative seconds (including the seek offset) for a group, or scene-relative seconds otherwise. This makes the actual audio clock authoritative through cold-start delays and mid-speech stalls. Return `undefined` for silent scenes or unavailable clocks; after ordinary narration completes, release to wall time so the authored reading hold can finish. `VideoChat` coordinates these callbacks automatically. A clock that stops advancing for eight active seconds produces an error; visual-readiness holds and deliberate pauses do not consume that timeout. Voices without an observable playback clock retain wall-time playback.
+
+Readiness holds pause narration together with the picture. The same audio continues across adjacent group scenes; replay starts a new playback session. This preserves words through delayed media rather than promising uninterrupted playback on every network.

package/docs/testing.md

@@ -34,7 +34,7 @@ describe("POST /api/video-chat", () => {
         body: JSON.stringify({
           prompt: "Explain why the Moon shows one face",
           opening: "The Moon turns, perfectly matching its orbit.",
-          mode: "templates",
+          mode: "cinematic",
           orientation: "landscape",
         }),
       },