@vanillaskyai/video 0.1.0

package/docs/errors.md

@@ -0,0 +1,70 @@
+[← Documentation home](../README.md) · [Previous: Security](security.md) · [Next: Production →](production.md)
+
+# Errors and recovery
+
+Render errors in normal application UI outside the video. Never show stack traces, provider details, raw deltas, or protocol diagnostics inside a scene.
+
+| Boundary | Example codes | Host response |
+| --- | --- | --- |
+| HTTP | `unauthorized`, `origin_forbidden`, `body_too_large` | Fix session/policy; do not retry blindly |
+| Input | `invalid_json`, `invalid_request`, `secret_field` | Correct client request |
+| Protocol | invalid sequence/checksum/scene | Stop the stream and record a safe diagnostic |
+| Generation | `generation_failed` | Hold current scene, end cleanly, offer retry |
+| Generated part | `invalid_generated_part` | Keep accepted scenes; inspect the private server log |
+| Resume | `invalid_cursor`, `resume_unavailable` | Restart only before visible output or from valid storage |
+
+```tsx
+import { VideoError } from "@vanillaskyai/video/react";
+
+try {
+  const completed = await video.generate({ input });
+  await saveVideo(completed);
+} catch (error) {
+  if (error instanceof VideoError) {
+    logSafeFailure({
+      code: error.code,
+      status: error.status,
+      requestId: error.requestId,
+      runId: error.runId,
+    });
+  }
+}
+```
+
+`generate()` resolves only for `response.complete`. A terminal
+`response.error` or `response.abort` rejects it. The hook still retains the
+latest validated `video.video`, and its player stream still receives terminal
+events, so an application may keep already accepted scenes visible while it
+offers a retry.
+
+Both a server `response.abort` and an explicit `video.abort(reason)` keep
+`video.status` at `aborted`; `video.error` contains the same safe typed abort
+reported by the rejected `generate()` promise.
+
+`VideoError` preserves only actionable public context: the server's safe
+`code` and `message`, HTTP `status` when available, `requestId`, `runId`, and
+`recoverable`. Do not replace those fields with raw provider errors.
+
+Abort replaced compositions and client disconnects. Retry provider throttles or transient failures only within an explicit request/time budget and only before visible output unless you have validated resume storage. Never silently restart after the viewer has begun watching.
+
+Log safe codes with request/run IDs and latency. Keep private provider messages in server logs through `onError`; redact source, personalization, keys, tokens, and signed URLs.
+
+Live acceptance artifacts use stable failure categories: `network`,
+`authentication`, `model_not_found`, `rate_limit`, `provider`, `planner_parse`,
+`scene_validation`, or `unknown`. Before diagnosing the SDK, probe the provider
+with one minimal request using the same server-only credential and model. Check
+DNS/proxy access, credential validity, model availability, account/rate limits,
+and timeout settings in that order. Never copy raw provider payloads, streamed
+deltas, prompts, or credentials into browser errors or CI artifacts.
+
+Server handlers drop invalid generated parts by default. Each rejection calls
+`onError` with the full internal reason, while the browser receives only the
+recoverable `invalid_generated_part` diagnostic. Set `invalidPartBehavior: "fail"`
+only when fail-fast generation is an intentional compatibility requirement.
+
+`onComplete` runs exactly once only after `response.complete`. Terminal errors,
+client disconnects, explicit aborts, and host timeouts do not call it;
+`onError` receives internal failures, while cancellation remains a safe
+`response.abort`. Abort and timeout signals always propagate to `streamText`.
+The host owns timeout construction and retry policy. Do not retry invisibly
+after any scene has reached the viewer.

package/docs/getting-started.md

@@ -0,0 +1,111 @@
+[← Documentation home](../README.md) · [Previous: Prompt and input](prompt-and-input.md) · [Next: Next.js →](integrate-nextjs.md)
+
+# Getting started
+
+Install VanillaSky:
+
+```bash
+npm install @vanillaskyai/video@0.1.0 ai @ai-sdk/openai
+```
+
+Set your provider key in `.env.local` (never commit it):
+
+```bash
+OPENAI_API_KEY=your-key
+OPENAI_MODEL=gpt-4.1
+```
+
+Create one authenticated server route with `createVideoHandler`. Connect your
+provider through `streamText`; keep the model, credentials, authentication, rate
+limits, and media policy on the server:
+
+```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");
+
+const handle = createVideoHandler({
+  // Local development only. Replace with your session check before deploying.
+  authorize: (request) => {
+    if (process.env.NODE_ENV !== "development") return false;
+    const hostname = new URL(request.url).hostname;
+    return hostname === "localhost" || hostname === "127.0.0.1";
+  },
+  streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
+    model,
+    system: systemPrompt,
+    prompt: userPrompt,
+    abortSignal: signal,
+  }),
+});
+
+export const POST = handle;
+export const OPTIONS = handle;
+```
+
+The local bypass is intentionally fail-closed: it accepts only localhost while
+Next.js is in development and denies every production request. Replace it with
+your real session validation before deploying. For literal files and commands,
+use the tested
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.1.0/examples/nextjs-quickstart).
+
+`model` can come from any AI SDK provider, registry, gateway, compatible API,
+or custom implementation. The application can choose a cheaper or faster model
+per request without changing VanillaSky.
+
+Call that route from React and render the player:
+
+```tsx
+"use client";
+
+import { VideoPlayer, useVideo } from "@vanillaskyai/video/react";
+
+export function GeneratedVideo({ input }: { input: string }) {
+  const video = useVideo();
+
+  return <>
+    <button onClick={() => { void video.generate({ input }); }}>Generate video</button>
+    {video.error && <p role="alert">Video generation failed.</p>}
+    <VideoPlayer {...video.playerProps} />
+  </>;
+}
+```
+
+No template setup is required. VanillaSky advertises the trusted built-in
+catalog to your LLM, validates its selected scenes, and lazy-loads only the
+renderers the video uses.
+
+`useVideo()` uses `/api/video` by default. Pass `endpoint` to use another route.
+`generate()` returns a `Promise<Video>` if you need the completed config directly:
+
+```ts
+const completedVideo = await video.generate({ input });
+```
+
+The promise resolves only after successful completion. It rejects on terminal
+generation errors and aborts; `video.error` contains the same typed error for
+reactive UI.
+
+`video.status` is `idle`, `streaming`, `complete`, `error`, or `aborted`.
+`video.video` is the latest deterministic video, and `video.warnings` contains
+bounded typed diagnostics safe to show or branch on. Provider limits and
+content filters are available to the server through the `onComplete` summary;
+surface that server-owned state separately if completeness matters to your
+product.
+
+Persist a completed `Video` as JSON and play it later without another model
+request:
+
+```tsx
+<VideoPlayer video={savedVideo} />
+```
+
+Built-in templates work without additional props. Pass `templates` when the
+saved video uses customer-owned templates.
+
+All other input controls are optional. Continue with [input and opening
+scenes](input-and-first-scene.md), [branding and personalization](branding-and-personalization.md),
+or [media and soundtrack audio](media-and-audio.md). To edit or create visual
+building blocks, see [custom templates](custom-templates.md).

package/docs/input-and-first-scene.md

@@ -0,0 +1,41 @@
+[← Documentation home](../README.md) · [Previous: Provider integration](provider-integration.md) · [Next: Branding and personalization →](branding-and-personalization.md)
+
+# Raw input and the opening
+
+`VideoInput` is the small boundary between application truth and creative planning.
+
+```ts
+import type { VideoInput } from "@vanillaskyai/video";
+
+const input: VideoInput = {
+  input: "Joris completed 142 customer conversations in Q2.",
+  instructions: "Celebrate the result. Never alter a metric.",
+  opening: "Joris, your Q2 recap is ready.",
+  personalization: { firstName: "Joris", period: "Q2" },
+  brand,
+  suppliedMedia,
+  audio: { src: "/audio/calm.mp3" },
+  orientation: "portrait",
+  maxDurationSec: 24,
+};
+```
+
+## Raw source
+
+Put every fact the response may claim in `input`. Use plain text, compact JSON, or a server-produced digest. Include units, periods, comparison bases, and provenance identifiers where ambiguity is possible. Keep creative direction in `instructions`; it may change emphasis and tone but cannot expand the factual boundary.
+
+Bound request bytes and reject secret-shaped fields on the server. Do not pass provider keys, authorization headers, internal prompt fragments, or storage credentials as source material.
+
+## Opening
+
+When supplied, `opening` becomes a deterministic five-second `notification`
+scene emitted before provider work. The SDK owns its scene ID, template, variables,
+and timing so callers only provide the copy. It should:
+
+- be personal or situational enough to feel intentional;
+- require no network media lookup;
+- remain true if generation later fails;
+- fit comfortably in both supported orientations;
+- be part of the final story, not a spinner disguised as a scene.
+
+Omit `opening` when the generated story should begin with its first planned scene.

package/docs/integrate-nextjs.md

@@ -0,0 +1,79 @@
+[← Documentation home](../README.md) · [Previous: Getting started](getting-started.md) · [Next: Provider integration →](provider-integration.md)
+
+# Next.js integration
+
+Install VanillaSky and one AI SDK provider:
+
+```bash
+npm install @vanillaskyai/video@0.1.0 ai @ai-sdk/openai
+```
+
+Create an ignored `.env.local`:
+
+```bash
+OPENAI_API_KEY=your-key
+OPENAI_MODEL=gpt-4.1
+```
+
+Create `app/api/video/route.ts`:
+
+```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");
+
+const handle = createVideoHandler({
+  // Local development only. Replace with your session check before deploying.
+  authorize: (request) => {
+    if (process.env.NODE_ENV !== "development") return false;
+    const hostname = new URL(request.url).hostname;
+    return hostname === "localhost" || hostname === "127.0.0.1";
+  },
+  streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
+    model,
+    system: systemPrompt,
+    prompt: userPrompt,
+    abortSignal: signal,
+  }),
+});
+
+export const POST = handle;
+export const OPTIONS = handle;
+```
+
+Create a Client Component:
+
+```tsx
+"use client";
+
+import { VideoPlayer, useVideo } from "@vanillaskyai/video/react";
+
+export function Video() {
+  const video = useVideo();
+  return <>
+    <button onClick={() => { void video.generate({
+      input: "Activation increased from 41% to 58%.",
+      personalization: { firstName: "Maya" },
+    }); }}>
+      Generate
+    </button>
+    {video.error && <p role="alert">Could not generate the video.</p>}
+    <VideoPlayer {...video.playerProps} />
+  </>;
+}
+```
+
+That is the complete first path. Built-in templates need no registry setup.
+The development authorization accepts only local requests and denies production
+requests; replace it with your application's session validation before
+deploying.
+
+The copy-and-run app is in the
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.1.0/examples/nextjs-quickstart).
+
+For another LLM, replace `openai(...)` with the matching AI SDK model. The route
+shape and React code stay the same. See [Provider integration](provider-integration.md)
+for adapters, authentication, diagnostics, and production controls. Add media,
+audio, persistence, or custom templates only after the default path works.

package/docs/media-and-audio.md

@@ -0,0 +1,69 @@
+[← Documentation home](../README.md) · [Previous: Branding and personalization](branding-and-personalization.md) · [Next: Custom templates →](custom-templates.md)
+
+# Media and soundtrack audio
+
+Applications own media and soundtrack audio. VanillaSky accepts ordinary
+authorized URLs in the deterministic video model; it does not bundle tracks or
+couple your app to a stock-media provider.
+
+The 0.1 SDK does not provide narration, TTS, or speech synchronization.
+If a product needs spoken audio, the application must create and synchronize
+that experience outside this contract.
+
+Only send source URLs you trust. Resolve provider results before generation,
+pass approved assets through `suppliedMedia`, and preload the next scene's asset
+before it becomes active. Keep provider credentials on the server.
+
+Supplied URLs and data URIs are not copied into the LLM prompt. The model sees
+an optional pool of opaque HTTPS-shaped references plus safe descriptive
+metadata, selects only relevant assets, and the SDK restores their original
+addresses on the server before scene validation. Supplying an asset does not
+require the completed video to use it.
+
+Audio timing, volume, beat markers, and fade-out remain part of the serialized
+output video, so replay and export stay deterministic. The input stays at the
+intent level: provide only the source URL and the SDK infers those playback
+defaults. Hosting and licensing are the application's responsibility.
+
+Host tracks in your application's public assets, object storage, or CDN, then
+pass their URL through the normal video input. For example, a file at
+`public/audio/calm.mp3` can be used without an SDK audio package:
+
+```ts
+const input = {
+  input: "Grounded source material",
+  audio: { src: "/audio/calm.mp3" },
+  maxDurationSec: 24,
+};
+```
+
+The normalized output uses `trackId: "soundtrack"`, the video duration,
+default beat detection, an empty beat-marker list, full volume, and a
+three-second fade-out. Omit `audio` to let the server's synchronous
+`selectAudio` callback choose from an app-owned catalog. Pass `audio: false`
+to guarantee a silent video.
+
+Keep the catalog and files in your application so you control caching,
+licensing, and deployment. The SDK continues to handle playback, timing,
+serialization, replay, and export from the supplied URL.
+
+## Media providers
+
+VanillaSky is provider-independent. Resolve image or video searches in your
+server application before generation and pass the approved results through
+`suppliedMedia`. The built-in planner sees opaque references and safe metadata;
+it does not call a stock-media provider or turn `mediaKeyword` into a URL.
+
+`allowMediaUrl` is an authorization hook for applications with their own custom
+stream adapter. It validates a final URL; it does not search for, fetch, or
+resolve media. The default 0.1 path needs no callback because every planner URL
+must already be present in `suppliedMedia`.
+
+Do not expose provider keys to React, allow arbitrary planner URLs, or add a
+provider abstraction to the template API. Templates describe visual building
+blocks; the application owns media retrieval, caching, licensing, and delivery.
+
+For Pexels, keep `PEXELS_API_KEY` on the server, search before generation, and
+pass only validated `images.pexels.com` or `videos.pexels.com` results through
+`suppliedMedia`. The application remains responsible for attribution, search,
+orientation filtering, MIME checks, timeouts, caching, and fallback behavior.

package/docs/motion-and-effects.md

@@ -0,0 +1,107 @@
+[← Documentation home](../README.md) · [Previous: Custom templates](custom-templates.md) · [Next: Production →](production.md)
+
+# Motion and effects
+
+VanillaSky motion is deterministic. The model selects from controlled names;
+the SDK calculates the same frame from the same video JSON and playback time.
+No generated CSS, animation code, or arbitrary transition is executed.
+
+## Text archetypes
+
+Text archetypes own a complete entrance, hold, and exit lifecycle:
+
+- `subtle` — quiet supporting copy;
+- `typewriter` — character-by-character reveal;
+- `wordStagger` — sequential word build;
+- `slam` — short, high-energy impact;
+- `cinematic` — depth-led trailer movement;
+- `heroWord` — one dominant word at a time.
+
+Templates declare whether they have a tight or open text canvas. VanillaSky
+normalizes incompatible or unknown values to a safe default.
+
+## Background effects
+
+Templates that support background motion can use:
+
+- `static`;
+- `slow-zoom-in`;
+- `slow-zoom-out`;
+- `ken-burns`;
+- `drift`;
+- `pulse`;
+- `breathe`;
+- `slow-tilt`;
+- `camera-shake`.
+
+`slow-zoom-in` is the default. Use `static` as the explicit opt-out.
+
+## Scene continuity
+
+`style.defaultTransition` accepts `crossfade` or `fade`. The player applies it
+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
+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.
+
+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
+frozen at its true initial frame (`progress === motionProgress === 0`) until its
+declared range begins. The current scene remains interactive and exposed to
+assistive technology until the exact timeline boundary; the preview layer
+remains inert throughout the overlap.
+
+Templates always receive raw semantic scene time as `progress`. Grounded
+numbers, media time, screen sequences, and other content state must use that
+clock. An opted-in template also receives `motionProgress`; throughout active
+playback it is the same complete `0→1` clock. The player never pre-advances,
+caps, rewinds, or skips a template's entrance, internal motion, exit, or
+terminal frame. `transitionTiming` records audited entry-ready and readable
+checkpoints for verification, but does not remap runtime time. Use
+`motionProgress` only for presentation and fall back to `progress` when it is
+absent. Templates opt out by default.
+
+An incoming changed-media fade can expose the template's initial frame while
+its raw semantic clock is still zero.
+Do not show a synthetic `0%`, `0x`, empty total, or another value that could be
+mistaken for sourced content. Keep the grounded frame and CTA visible, but mark
+only a transient value wrapper with
+`visibility: var(--vanillasky-transition-semantic-visibility, visible)`. The
+player hides that wrapper for the incoming preview and reveals it as soon as
+the same mounted scene becomes active. This guard does not change `progress`,
+media time, the component lifecycle, or final values.
+
+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
+background instead of replaying an earlier scene.
+
+## Reduced motion
+
+The player respects `prefers-reduced-motion`. Applications should keep a
+visible playback control and must not rely on motion alone to communicate a
+fact or state.
+
+## Preview the catalog
+
+The public [motion and effects gallery](https://vanillasky.ai/motion/) renders
+the real SDK effects with their exact configuration. Use it to choose a
+controlled effect, then keep the initial integration on the defaults unless a
+specific editorial need calls for an override.
+
+[← Documentation home](../README.md) · [Previous: Custom templates](custom-templates.md) · [Next: Production →](production.md)

package/docs/persistence.md

@@ -0,0 +1,95 @@
+[← Documentation home](../README.md) · [Previous: Core concepts](concepts.md) · [Next: Streaming protocol →](streaming-protocol.md)
+
+# Persistence and replay
+
+A completed `Video` is ordinary JSON owned by your application. VanillaSky
+does not provide a database or hosted media store. Save the value returned by
+`await video.generate(...)` with the platform-native `JSON.stringify`; there is
+no SDK serializer.
+
+Every stored video has `schemaVersion: "0.1"`. This storage version is separate
+from streaming protocol `0.4`. The 0.1 policy supports the current storage
+schema only: there are no compatibility aliases or implicit coercions.
+
+## Load at the storage boundary
+
+Treat values loaded from a database, object store, API, or file as `unknown`.
+Parse them before using them in application code:
+
+<!-- verify:persistence-example:start -->
+```tsx
+import { getVideoDuration, parseVideo } from "@vanillaskyai/video";
+import { VideoPlayer } from "@vanillaskyai/video/react";
+
+export function SavedVideo({ storedJson }: { storedJson: string }) {
+  const savedVideo = parseVideo(JSON.parse(storedJson));
+
+  return <>
+    <p>{getVideoDuration(savedVideo)} seconds</p>
+    <VideoPlayer video={savedVideo} autoPlay={false} />
+  </>;
+}
+```
+<!-- verify:persistence-example:end -->
+
+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
+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
+`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.
+
+## Retention
+
+By default, completed snapshots omit raw source, creative instructions, and
+the supplied-media URL index. A customer-owned route may retain individual
+fields only when its privacy and deletion policy allows it:
+
+```ts
+createVideoHandler({
+  authorize: verifySession,
+  streamText,
+  snapshotRetention: {
+    source: true,
+    instructions: true,
+    suppliedMediaUrls: true,
+  },
+});
+```
+
+Opt-in values are bounded in the snapshot:
+
+- source: 16,384 characters;
+- instructions: 4,096 characters;
+- supplied-media index: 16 URLs, each at most 2,048 characters.
+
+These metadata limits do not replace a host retention policy. Renderable scene
+variables may still contain a media URL when that asset is necessary for
+replay. Store only approved assets and avoid signed URLs whose lifetime is
+shorter than the replay window.
+
+## Storage ownership
+
+The host owns the database, object storage, tenant authorization, encryption,
+deletion schedule, backups, quotas, and media URL expiry. Persist the final
+`Video` document atomically with your own tenant and record identifiers. Do not
+use the protocol checksum as an authorization or tenancy control.
+
+The checksum on `response.complete` is a deterministic, non-cryptographic
+drift detector. It is not proof of authenticity and is not a signature. Use
+normal authenticated storage and a cryptographic integrity mechanism when
+those properties are required.
+
+Saved replay makes zero generation endpoint or model-provider requests. It is
+not necessarily zero network traffic: audio, images, videos, fonts, and
+customer-owned renderers may make separate media network requests.
+
+When a saved video uses project-owned templates, provide the matching browser
+registry: `<VideoPlayer video={savedVideo} templates={templates} />`.