@vanillaskyai/video 0.6.0 → 0.7.1

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

@@ -1,64 +0,0 @@
-[← 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: "Maya completed 142 customer conversations in Q2.",
-  knowledgeMode: "input-only",
-  instructions: "Celebrate the result. Never alter a metric.",
-  opening: "Maya, your Q2 customer impact recap is ready.",
-  personalization: { firstName: "Maya", period: "Q2", role: "Product leader" },
-  brand,
-  suppliedMedia,
-  audio: { src: "/audio/calm.mp3" },
-  orientation: "portrait",
-  maxDurationSec: 24,
-};
-```
-
-## Raw source
-
-In the default `input-only` mode, 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. Choose `knowledgeMode: "general"` only when the model should use
-stable general knowledge to answer a question or develop content. Creative
-direction in `instructions` never changes that setting.
-
-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
-
-`opening` becomes a deterministic `media` scene emitted before provider work.
-When callers omit it, the SDK uses `Creating your video...`; a supplied value
-replaces that fallback. The scene contains only that sentence and explicitly
-uses the brand gradient without stock media. The SDK requests a three-second
-opening, then applies its normal readability and overall-duration budget. It
-owns the scene ID, template, variables, and timing so callers only provide
-optional custom copy. That copy should:
-
-- be personal or situational enough to feel intentional;
-- require no network media lookup;
-- remain true if generation later fails;
-- be one concise sentence that fits comfortably in both supported orientations;
-- be part of the final story, not a spinner disguised as a scene.
-
-Pass `opening: false` when the application should own the waiting experience:
-
-```ts
-opening: false
-```
-
-The SDK then starts with an empty timeline and emits the first validated,
-generated scene as soon as it is ready. Render a transient loading state in the
-host application until `video.video?.scenes.length` is non-zero. That loading
-state is not persisted in the event stream or completed video. A generated
-scene is still required; a planner that completes without one fails the run.
-
-The deterministic opening is runtime-owned, so it remains available even when `templateIds`
-does not let the planner select `media` for generated body scenes.

package/docs/integrate-nextjs.md

@@ -1,86 +0,0 @@
-[← Documentation home](../README.md) · [Previous: Getting started](getting-started.md) · [Next: Provider integration →](provider-integration.md)
-
-# Next.js integration
-
-After installing VanillaSky, choose the provider and model for your server. This
-complete example uses Anthropic and asks you to select a current Claude Sonnet
-model explicitly instead of baking a model ID into the SDK docs:
-
-```bash
-npm install @vanillaskyai/video ai @ai-sdk/anthropic
-```
-
-Create an ignored `.env.local`:
-
-```bash
-ANTHROPIC_API_KEY=your-key
-ANTHROPIC_MODEL=your-current-sonnet-model
-```
-
-Create `app/api/video/route.ts`:
-
-```ts
-import { anthropic } from "@ai-sdk/anthropic";
-import { streamText } from "ai";
-import { createVideoHandler } from "@vanillaskyai/video/server";
-
-const modelId = process.env.ANTHROPIC_MODEL;
-if (!modelId) throw new Error("Set ANTHROPIC_MODEL in the server environment");
-const model = anthropic(modelId);
-
-const handle = createVideoHandler({
-  // Local development only. Replace with your session check before deploying.
-  authorize: (request) => {
-    if (process.env.VANILLASKY_LOCAL_DEMO !== "1") 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 packaged `npm run dev` command supplies this non-secret marker only to
-`next dev`. Production builds and `next start` never receive it.
-
-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](../examples/nextjs-quickstart).
-
-For another LLM, replace `anthropic(...)` 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/live-channels.md

@@ -1,149 +0,0 @@
-[← Documentation home](../README.md) · [Previous: Persistence and replay](persistence.md) · [Next: Streaming protocol →](streaming-protocol.md)
-
-# Live channels
-
-A live channel is a video that plays continuously and rebuilds itself on a
-schedule: a market ticker, a news wall, a status board in an office, a loop
-behind a conference stand. Nobody presses play, nobody watches from the start,
-and the content changes on its own.
-
-This is a different shape from a generated response. A response is produced for
-one person, once, in reply to something they asked. A channel is produced ahead
-of time for nobody in particular, and then played to whoever is looking.
-
-That difference is what makes it cheap. Playback of a saved `Video` performs no
-generation request and no model call — the player is DOM and CSS advanced by a
-`requestAnimationFrame` clock — so a channel that loops all day costs exactly as
-much as a channel that loops once. All of the cost lives in building the
-configuration, which happens on your schedule rather than per viewer.
-
-## The shape
-
-```
-scheduled job                       browser
-─────────────                       ───────
-fetch your data          ┌────────► fetch the stored Video
-map it to scenes         │          parseVideo(...)
-parseVideo(...)  ────────┘          <VideoPlayer video={...} loop />
-store the JSON                      plays forever
-```
-
-The job owns the data and the mapping. The player owns nothing but playback.
-
-## Play without stopping
-
-Pass `loop` alongside a saved video. The player restarts from the beginning
-instead of showing its replay affordance and loops its soundtrack continuously.
-A track shorter than the channel repeats as soon as it ends; when the visual
-timeline wraps, the soundtrack restarts from the beginning with it.
-
-<!-- verify:live-channel-example:start -->
-```tsx
-import { useEffect, useState } from "react";
-import { parseVideo, type Video, type VideoScene } from "@vanillaskyai/video";
-import { VideoPlayer } from "@vanillaskyai/video/react";
-
-export function Channel({ endpoint }: { endpoint: string }) {
-  const [video, setVideo] = useState<Video | undefined>(undefined);
-  const [onScreen, setOnScreen] = useState<VideoScene | undefined>(undefined);
-
-  const load = async () => {
-    const stored: unknown = await fetch(endpoint).then((response) => response.json());
-    setVideo(parseVideo(stored));
-  };
-
-  useEffect(() => { void load(); }, []);
-  if (!video) return null;
-
-  return <>
-    <VideoPlayer
-      video={video}
-      loop
-      autoPlay
-      playbackMode="muted-autoplay"
-      onSceneChange={(scene, index) => {
-        setOnScreen(scene);
-        // Wrapping back to the start is a natural moment to pick up a rebuild,
-        // so a screen left running all day never serves a stale channel.
-        if (index === 0) void load();
-      }}
-    />
-    <p>{onScreen ? onScreen.templateId : "starting"}</p>
-  </>;
-}
-```
-<!-- verify:live-channel-example:end -->
-
-`loop` applies to saved videos. A streaming response still ends when the stream
-ends, because there is nothing to loop back to until it completes.
-
-## Follow what is on screen
-
-`onSceneChange` fires whenever the scene under the playhead changes, and again
-on index `0` each time a loop wraps. Use it to drive anything that has to stay
-in step with the video: a caption rail, a source panel, chapter markers, an
-analytics event per scene.
-
-Do not run your own timer for this. A parallel clock drifts from the player's
-as soon as playback is paused, throttled in a background tab, or delayed by a
-slow asset, and the drift is silent.
-
-`onComplete` is not an alternative here: it reports the end of a *stream*, so it
-never fires for a saved video.
-
-## Build the configuration yourself
-
-A channel's scenes usually come from your own data rather than from a model.
-`resolveVideoBrand` fills a partial brand with the documented defaults, so a
-hand-authored `Video` satisfies `parseVideo` without copying a defaults blob
-into your application:
-
-```ts
-import { parseVideo, resolveVideoBrand } from "@vanillaskyai/video";
-
-const channel = parseVideo({
-  schemaVersion: "0.1",
-  orientation: "landscape",
-  scenes: rows.map((row, index) => ({
-    id: `row-${index}`,
-    templateId: "bigNumber",
-    variables: { texts: row.label, value: row.value, unit: row.unit },
-    timing: { fixedDuration: 5 },
-  })),
-  style: { brand: resolveVideoBrand({ name: "Acme", background: "midnight" }) },
-});
-```
-
-Validate with `parseVideo` inside the job, before storing. A channel that fails
-validation in the browser is a channel nobody can watch; one that fails in the
-job can simply leave the previous version in place.
-
-## Keep motion independent of scene length
-
-Templates receive `sceneDuration`. Express motion in seconds against it rather
-than as a fraction of `progress`, or lengthening a scene to give viewers more
-reading time will stretch its animation instead and give them none.
-
-## Practical notes
-
-- **Rebuild on a schedule, not per request.** Viewers should read a stored
-  configuration. If every viewer triggers generation, a channel becomes the most
-  expensive surface you own rather than the cheapest.
-- **Never replace a good channel with a broken one.** Validate first, and on
-  failure leave the previous configuration in place.
-- **Autoplay needs `playbackMode="muted-autoplay"`.** Browsers refuse unmuted
-  autoplay. A channel can still carry a looping soundtrack: it starts muted and
-  becomes audible when a viewer uses the player's sound control.
-- **Host your media.** Loops re-request assets over long sessions; serving them
-  from your own origin keeps a content policy simple and avoids depending on
-  someone else's CDN.
-- **Long channels are ordinary videos.** Ten minutes of scenes is one `Video`
-  with more entries in `scenes`; there is no separate playlist concept.
-
-## Related
-
-- [Persistence and replay](persistence.md) — the storage boundary these
-  configurations pass through
-- [Custom templates](custom-templates.md) — templates for your own data shapes
-- [Responsive orientation](responsive-orientation.md) — the same channel on a
-  portrait screen

package/docs/use-cases.md

@@ -1,59 +0,0 @@
-[← Documentation home](../README.md)
-
-# Video response use cases
-
-These four inputs show the primary product shape: AI answers and live
-application context become embedded video responses. The application decides
-which context matters and keeps it current. VanillaSky grounds, validates,
-composes, and plays the visual response.
-
-## News summary
-
-```ts
-video.generate({
-  input: `Headline: North Sea wind output reached a record on August 17.
-Source summary: Grid operators reported 18.2 GW at 14:00 CET, 12% above the
-previous record. Operators said lower demand helped reduce wholesale prices.`,
-  instructions: "Lead with the record, explain the comparison, then the impact.",
-  maxDurationSec: 24,
-});
-```
-
-## Contextual help
-
-```ts
-video.generate({
-  input: `The user is configuring an alert. The current threshold is 80%.
-Alerts evaluate every 15 minutes. Email and Slack are enabled. The Save button
-applies the rule to 42 selected accounts.`,
-  instructions: "Explain what will happen if the user saves this configuration.",
-  opening: "Here is what this alert will do.",
-  maxDurationSec: 24,
-});
-```
-
-## Personalized briefing
-
-```ts
-video.generate({
-  input: `The Acme account has 1,240 weekly active users, up 18% month over
-month. Three renewals are due in September. Support response time improved from
-4.2 hours to 2.8 hours.`,
-  personalization: { firstName: "Maya", accountName: "Acme" },
-  instructions: "Create a concise morning account briefing.",
-  maxDurationSec: 30,
-});
-```
-
-## Dynamic personalized page content
-
-```ts
-video.generate({
-  input: `The page shows the Q2 onboarding funnel. 8,420 users started setup,
-6,315 connected a data source, and 4,884 invited a teammate. The largest drop
-is between connecting a data source and inviting a teammate.`,
-  instructions: "Respond to the visible funnel and focus on the largest drop.",
-  orientation: "landscape",
-  maxDurationSec: 24,
-});
-```

package/examples/nextjs-quickstart/.env.example

@@ -1,2 +0,0 @@
-ANTHROPIC_API_KEY=replace-me
-ANTHROPIC_MODEL=replace-with-current-sonnet-model

package/examples/nextjs-quickstart/README.md

@@ -1,27 +0,0 @@
-# Next.js quickstart
-
-This is the smallest complete VanillaSky app: one server route, one React page,
-and the built-in templates.
-
-<!-- verify:start -->
-```bash
-npm install
-cp .env.example .env.local
-npm run build
-npm run dev
-```
-<!-- verify:end -->
-
-Before selecting **Generate video**, add your Anthropic API key and replace the
-model placeholder with a current Claude Sonnet model ID available to your
-account. Provider and model selection happen here, after SDK installation, so
-VanillaSky never silently chooses either one.
-
-Open <http://localhost:3000> and select **Generate video**.
-
-The packaged development command supplies a non-secret marker only to
-`next dev`, so the example authorizes local development and denies production
-requests.
-Replace the local-only authorization before deploying. See the
-[Next.js guide](../../docs/integrate-nextjs.md) for production and optional
-configuration.

package/examples/nextjs-quickstart/next-env.d.ts

@@ -1,4 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-
-// This file is generated and maintained by Next.js.

package/examples/nextjs-quickstart/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "vanillasky-nextjs-quickstart",
-  "private": true,
-  "version": "0.0.0",
-  "scripts": {
-    "dev": "cross-env VANILLASKY_LOCAL_DEMO=1 next dev",
-    "build": "next build",
-    "start": "next start"
-  },
-  "dependencies": {
-    "@ai-sdk/anthropic": "^4.0.41",
-    "@vanillaskyai/video": "0.6.0",
-    "ai": "^7.0.77",
-    "next": "16.3.2",
-    "react": "19.2.8",
-    "react-dom": "19.2.8"
-  },
-  "devDependencies": {
-    "@types/node": "^24.10.1",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "cross-env": "10.1.0",
-    "typescript": "^5.9.3"
-  }
-}

package/examples/nextjs-quickstart/src/app/api/video/route.ts

@@ -1,33 +0,0 @@
-import { anthropic } from "@ai-sdk/anthropic";
-import { streamText } from "ai";
-import { createVideoHandler } from "@vanillaskyai/video/server";
-
-// Resolved per request so the app still builds with the shipped placeholder.
-function resolveModel() {
-  const modelId = process.env.ANTHROPIC_MODEL;
-  if (!modelId || modelId === "replace-with-current-sonnet-model") {
-    throw new Error(
-      "Set ANTHROPIC_MODEL in .env.local to a current Claude Sonnet model ID available to your " +
-        "account. The shipped value is a placeholder: VanillaSky never selects a provider or " +
-        "model for you.",
-    );
-  }
-  return anthropic(modelId);
-}
-
-const handle = createVideoHandler({
-  authorize: (request) => {
-    if (process.env.VANILLASKY_LOCAL_DEMO !== "1") return false;
-    const hostname = new URL(request.url).hostname;
-    return hostname === "localhost" || hostname === "127.0.0.1";
-  },
-  streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
-    model: resolveModel(),
-    system: systemPrompt,
-    prompt: userPrompt,
-    abortSignal: signal,
-  }),
-});
-
-export const POST = handle;
-export const OPTIONS = handle;

package/examples/nextjs-quickstart/src/app/layout.tsx

@@ -1,5 +0,0 @@
-import type { ReactNode } from "react";
-
-export default function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
-  return <html lang="en"><body>{children}</body></html>;
-}

package/examples/nextjs-quickstart/src/app/page.tsx

@@ -1,31 +0,0 @@
-"use client";
-
-import { useState } from "react";
-import { VideoPlayer, useVideo } from "@vanillaskyai/video/react";
-
-export default function Page() {
-  const [input, setInput] = useState(
-    "Activation increased from 41% to 58% after guided onboarding.",
-  );
-  const video = useVideo();
-
-  return <main>
-    <h1>VanillaSky quickstart</h1>
-    <label>
-      Grounded input
-      <textarea value={input} onChange={(event) => setInput(event.target.value)} />
-    </label>
-    <button
-      disabled={!input.trim() || video.status === "streaming"}
-      onClick={() => { void video.generate({
-        input,
-        personalization: { firstName: "Maya" },
-      }); }}
-    >
-      Generate video
-    </button>
-    <output data-testid="status">{video.status}</output>
-    {video.error && <p role="alert">{video.error.message}</p>}
-    <VideoPlayer {...video.playerProps} />
-  </main>;
-}

package/examples/nextjs-quickstart/tsconfig.json

@@ -1,26 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2017",
-    "lib": ["dom", "dom.iterable", "esnext"],
-    "allowJs": true,
-    "skipLibCheck": true,
-    "strict": true,
-    "noEmit": true,
-    "incremental": true,
-    "esModuleInterop": true,
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "jsx": "react-jsx",
-    "plugins": [{ "name": "next" }]
-  },
-  "include": [
-    "next-env.d.ts",
-    "**/*.ts",
-    "**/*.tsx",
-    ".next/types/**/*.ts",
-    ".next/dev/types/**/*.ts"
-  ],
-  "exclude": ["node_modules"]
-}

package/examples/server-integrations/README.md

@@ -1,20 +0,0 @@
-# Server examples
-
-The normal example uses the AI SDK's `streamText`, so any AI SDK `LanguageModel`
-works without VanillaSky owning the provider, model, or credentials. Replace
-`openai(modelId)` in `src/ai-sdk.ts` with an official provider, community
-provider, AI Gateway model, OpenAI-compatible provider, or custom model.
-
-`src/provider-neutral.ts` and `src/openai.ts` show the lower-level text-delta
-escape hatch for applications that need to own the native provider loop.
-
-<!-- verify:start -->
-```bash
-npm install
-npm run typecheck
-npm run ai-sdk:compat
-```
-<!-- verify:end -->
-
-Use the returned Web `Request` → `Response` handler directly in Next.js, Hono,
-Remix, Cloudflare Workers, or another standards-based server runtime.

package/examples/server-integrations/src/ai-sdk-media.ts

@@ -1,90 +0,0 @@
-// App-owned media generation for VanillaSky scenes.
-//
-// VanillaSky never generates media and never selects a provider. It calls
-// `resolveMedia` with a bounded query and the scene being resolved; the
-// application decides what to generate, where to store it, and what it costs.
-//
-// This adapter is provider-neutral: it takes AI SDK model instances rather
-// than naming a vendor, so the same code runs against any image or video
-// model the AI SDK supports. Choose the provider where you build the models,
-// not here.
-import { experimental_generateVideo, generateImage, type ImageModel } from "ai";
-import type { MediaResolver, MediaResolverContext, ResolvedMedia } from "@vanillaskyai/video/server";
-
-// `ai` declares its video model and provider-option types internally without
-// exporting them, so derive them from the call signatures instead of naming
-// them. This keeps the adapter correct across AI SDK releases.
-type VideoModel = Parameters<typeof experimental_generateVideo>[0]["model"];
-type ProviderOptions = Parameters<typeof generateImage>[0]["providerOptions"];
-
-/** Persist generated bytes and return a URL the player can load. */
-export type StoreGeneratedMedia = (media: {
-  data: Uint8Array;
-  mediaType: string;
-  kind: "image" | "video";
-  /** Stable per scene, so a retried request reuses the stored object. */
-  idempotencyKey: string;
-}) => Promise<{ url: string }>;
-
-export interface GeneratedMediaOptions {
-  imageModel: ImageModel;
-  /** Omit to resolve every scene as an image. */
-  videoModel?: VideoModel;
-  store: StoreGeneratedMedia;
-  /** Provider-specific settings, passed straight through to the AI SDK. */
-  providerOptions?: ProviderOptions;
-}
-
-function aspectRatio(context: MediaResolverContext): "16:9" | "9:16" {
-  return context.input.orientation === "portrait" ? "9:16" : "16:9";
-}
-
-// One generated asset per scene, keyed so a retry of the same request cannot
-// be billed twice.
-function idempotencyKey(context: MediaResolverContext): string {
-  return `${context.requestId}:${context.scene.id}`;
-}
-
-export function createGeneratedMediaResolver(options: GeneratedMediaOptions): MediaResolver {
-  return async (query, context): Promise<ResolvedMedia | null> => {
-    const wantsVideo = context.preferredType === "video" && options.videoModel !== undefined;
-
-    if (wantsVideo && options.videoModel) {
-      const result = await experimental_generateVideo({
-        model: options.videoModel,
-        prompt: query,
-        aspectRatio: aspectRatio(context),
-        // Generated media is billable. A silent retry can produce a second
-        // charge for one scene, so retries stay an explicit, budget-aware
-        // decision in the application rather than an SDK default.
-        maxRetries: 0,
-        abortSignal: context.signal,
-        providerOptions: options.providerOptions,
-      });
-      const stored = await options.store({
-        data: result.video.uint8Array,
-        mediaType: result.video.mediaType,
-        kind: "video",
-        idempotencyKey: idempotencyKey(context),
-      });
-      return { url: stored.url, type: "video" };
-    }
-
-    const result = await generateImage({
-      model: options.imageModel,
-      prompt: query,
-      aspectRatio: aspectRatio(context),
-      n: 1,
-      maxRetries: 0,
-      abortSignal: context.signal,
-      providerOptions: options.providerOptions,
-    });
-    const stored = await options.store({
-      data: result.image.uint8Array,
-      mediaType: result.image.mediaType,
-      kind: "image",
-      idempotencyKey: idempotencyKey(context),
-    });
-    return { url: stored.url, type: "image" };
-  };
-}