@vanillaskyai/video 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,95 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.5.0
+
+### Breaking changes
+
+- Simplifies streaming protocol `0.5` to complete immutable `scene.add` parts
+  followed by `plan.complete`. It removes `scene.patch`, `asset.patch`,
+  `plan.error`, and scene revision counters. Provider failures now use thrown
+  errors, while media resolution finishes before its scene is emitted.
+- Raises the supported Node.js floor from 20 to 22. Node 20 reached end of life
+  and is no longer exercised by the SDK's tests, builds, or clean-room package
+  verification.
+- Stops returning the merged built-in template catalog through
+  `useVideo().playerProps.templates`. `playerProps` now carries only the
+  customer registry passed to `useVideo`, while `VideoPlayer` supplies its
+  built-in renderers internally. Existing `<VideoPlayer {...playerProps} />`
+  usage is unchanged. This removes planner-only metadata from the initial
+  React graph, reducing it from 48,197 to 35,649 gzip bytes.
+
+### Adoption
+
+Custom planners that previously emitted a scene and patched it later:
+
+```ts
+yield { type: "scene.add", scene: draftScene };
+yield { type: "asset.patch", sceneId: draftScene.id, variables: resolvedMedia };
+```
+
+should emit one complete scene instead:
+
+```ts
+yield {
+  type: "scene.add",
+  scene: { ...draftScene, variables: { ...draftScene.variables, ...resolvedMedia } },
+};
+```
+
+Throw planner failures instead of emitting `plan.error`. Protocol `0.4` replay
+logs cannot be mixed into a `0.5` run; completed stored `Video` values remain on
+the unchanged `0.1` storage schema.
+
+Update applications that pin Node 20 before installing the next SDK release:
+
+```json
+{
+  "engines": { "node": "20.x" }
+}
+```
+
+becomes:
+
+```json
+{
+  "engines": { "node": "22.x" }
+}
+```
+
+Code that used the player binding to inspect built-in metadata:
+
+```ts
+const templates = video.playerProps.templates.listTemplateMetadata();
+```
+
+should import the explicit React-free catalog instead:
+
+```ts
+import { builtinTemplates } from "@vanillaskyai/video/templates/catalog";
+```
+
+Inspect a customer registry directly when the application created it; it is
+still passed through `playerProps` unchanged.
+
+### Maintenance
+
+- Makes React 19 the primary development and example runtime. CI continues to
+  verify React 18 with its own runtime and type packages, including typecheck,
+  focused component tests, and a production build.
+- Shares the replay buffer and identical JSON-validation primitives across
+  their call sites, removing duplicate implementations without changing the
+  public API.
+- Keeps the first install provider-neutral, removes stale version and model
+  defaults from public guides, and moves the quality-oriented Anthropic/Sonnet
+  choice into the later provider setup step.
+
+## 0.4.1
+
+- Keeps soundtrack audio continuous when a saved `VideoPlayer` uses `loop`.
+  A track shorter than the visual timeline now repeats as soon as it ends,
+  instead of leaving silence until the video itself wraps.
+
 ## 0.4.0
 
 - Adds `loop` to `VideoPlayer` for saved videos. A completed video previously

package/PUBLIC-API.md

@@ -1,6 +1,6 @@
-# VanillaSky Video 0.2 public API
+# VanillaSky Video public API
 
-Status: frozen public beta contract for `0.3.0`.
+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
@@ -16,7 +16,7 @@ public API review.
 
 ## Compatibility promise
 
-- `0.1.x` patch releases do not make breaking changes to documented APIs or the
+- 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
@@ -26,7 +26,7 @@ public API review.
   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 20 or newer.
+- 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
@@ -178,6 +178,13 @@ interface UseVideoResult {
 <VideoPlayer video={savedVideo} />
 ```
 
+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 `useVideo` 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.
+
 Set `playbackMode="autoplay-after-interaction"` for chat feeds: the first
 soundtrack waits on a visible scene-one poster, and later streams on the same
 mounted player autoplay with sound after the first successful viewer start.
@@ -290,7 +297,7 @@ from `/server` without crossing a React type boundary.
 
 - A completed `Video` is JSON-serializable and may be stored by the host.
 - Every completed value carries the required storage field
-  `schemaVersion: "0.1"`; it is independent from streaming protocol `0.4`.
+  `schemaVersion: "0.1"`; it is independent from streaming protocol `0.5`.
 - `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

package/README.md

@@ -1,6 +1,6 @@
 # Give your AI a video output
 
-![Version 0.4.0 beta](https://img.shields.io/badge/version-0.4.0_beta-7c3aed)
+![npm version](https://img.shields.io/npm/v/@vanillaskyai/video?label=version)
 
 **VanillaSky is the open-source video response layer.** Turn text, structured
 data, and live application context into personalized video responses that start
@@ -17,7 +17,7 @@ the planning prompt, trusted templates, validation, streaming, and player.
 For humans:
 
 ```bash
-npm install @vanillaskyai/video@0.4.0 ai @ai-sdk/openai
+npm install @vanillaskyai/video
 ```
 
 For coding agents:
@@ -28,24 +28,20 @@ npx skills add VanillaSkyAi/video@vanillasky
 
 Then prompt: `Use $vanillasky to turn this application's data into a personalized video response.`
 
-Add your model key to an ignored `.env.local`:
-
-```bash
-OPENAI_API_KEY=your-key
-OPENAI_MODEL=gpt-4.1
-```
-
 ## Connect your LLM
 
+VanillaSky never chooses a provider or model. Configure that separately on the
+server, then connect the model your application already owns. The route below
+assumes an AI SDK `LanguageModel` exported as `videoModel`; if you do not have
+one yet, choose a provider and current model in [Provider integration](docs/provider-integration.md).
+
 Create one authenticated server route:
 
 ```ts
 // app/api/video/route.ts
-import { openai } from "@ai-sdk/openai";
 import { streamText } from "ai";
 import { createVideoHandler } from "@vanillaskyai/video/server";
-
-const model = openai(process.env.OPENAI_MODEL ?? "gpt-4.1");
+import { videoModel } from "@/lib/video-model";
 
 const handle = createVideoHandler({
   // Local development only. Replace with your session check before deploying.
@@ -55,7 +51,7 @@ const handle = createVideoHandler({
     return hostname === "localhost" || hostname === "127.0.0.1";
   },
   streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
-    model,
+    model: videoModel,
     system: systemPrompt,
     prompt: userPrompt,
     abortSignal: signal,
@@ -68,8 +64,10 @@ export const OPTIONS = handle;
 
 The packaged development command supplies the local marker only to `next dev`,
 so production builds and `next start` deny every request. Replace it before
-deploying. The model can come from OpenAI, Anthropic, an AI SDK registry or
-gateway, or any compatible streaming adapter.
+deploying. The model can come from Anthropic, OpenAI, an AI SDK registry or
+gateway, or any compatible streaming adapter. The
+[Next.js quickstart](examples/nextjs-quickstart) shows the later, explicit
+provider-selection step with a quality-oriented Claude Sonnet model.
 
 For planner-selected image and video backgrounds, configure the optional
 server-only `resolveMedia` callback described in
@@ -105,8 +103,7 @@ That is the complete path. Built-in templates require no setup. VanillaSky
 shows each complete, validated scene as soon as it is ready and returns a
 deterministic `Video` object when generation finishes.
 
-A copy-and-run app is in
-[`examples/nextjs-quickstart`](https://github.com/VanillaSkyAi/video/tree/v0.4.0/examples/nextjs-quickstart).
+A copy-and-run app is in [`examples/nextjs-quickstart`](examples/nextjs-quickstart).
 
 ## Shape the response
 

package/dist/{builtin-server-BRTZN4Q7.js → builtin-server-YHEZ2JRF.js}

@@ -1,7 +1,7 @@
 import {
   BUILTIN_SERVER_TEMPLATE_KIT
-} from "./chunk-I5YWVQ5R.js";
-import "./chunk-XAMUOSX7.js";
+} from "./chunk-FVTMYS6U.js";
+import "./chunk-3RV4YKB3.js";
 import "./chunk-2E6T633S.js";
 export {
   BUILTIN_SERVER_TEMPLATE_KIT

package/dist/check-runtime.js

@@ -1,6 +1,6 @@
 import {
   VideoFrame
-} from "./chunk-N3KUA7VP.js";
+} from "./chunk-K6YVQODK.js";
 import "./chunk-XWWLKRNU.js";
 import "./chunk-SPVTJH3F.js";
 import {

package/dist/{chunk-BKF3A357.js → chunk-34O5BY6X.js}

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