@vanillaskyai/video 0.10.23 → 0.11.0

package/docs/testing.md

@@ -1,150 +1,83 @@
 # Test video chat without a model
 
-`@vanillaskyai/video/test` provides deterministic planner streams and
-in-process protocol events. It has no React or provider-SDK dependency, makes
-no network request, and needs no model key.
+Use deterministic callbacks for your route and the React-free
+`@vanillaskyai/video/test` helpers for protocol cases. These tests need no keys,
+provider SDKs, or real model requests.
 
-## Test the chat route with Vitest
+## Test the default route
 
-Pass `createMockVideoPlanner()` to the same `createVideoChatHandler` used by the
-application, using an explicit template registry for the structured composition
-fixtures. Default AI-first chat tests should instead return an authored answer
-brief and shot descriptions matching the supplied planning prompt. A standard
-`Request` exercises parsing, validation, pacing, the
-opening extension, and SSE without starting an HTTP server.
+Return the answer-brief shape requested by the handler's planning prompt, not
+a generic template plan:
 
 ```ts
-import { describe, expect, it } from "vitest";
-import { createVideoChatHandler, createServerTemplateRegistry } from "@vanillaskyai/video/server";
-import { createMockVideoPlanner } from "@vanillaskyai/video/test";
-
-describe("POST /api/video-chat", () => {
-  it("returns a completed video answer", async () => {
-    const handle = createVideoChatHandler({
-      authorize: "none", // Only acceptable because this handler stays in process.
-      heartbeatMs: false,
-      templates: createServerTemplateRegistry({ templates: [] }),
-      streamText: createMockVideoPlanner(),
-      generateText: async ({ task }) => task === "suggestions"
-        ? JSON.stringify({ suggestions: [] })
-        : "A deterministic narration line.",
-    });
-
-    const response = await handle(new Request(
-      "https://app.test/api/video-chat?action=response",
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({
-          prompt: "Explain why the Moon shows one face",
-          opening: "The Moon turns, perfectly matching its orbit.",
-          mode: "cinematic",
-          orientation: "landscape",
-        }),
-      },
-    ));
-    const body = await response.text();
-
-    expect(response.status).toBe(200);
-    expect(body).toContain('"type":"data.video-chat-opening"');
-    expect(body).toContain('"type":"scene.add"');
-    expect(body).toContain('"type":"response.complete"');
+import { expect, it } from "vitest";
+import { createVideoChatHandler } from "@vanillaskyai/video/server";
+
+it("completes a narrated chapter when footage is unavailable", async () => {
+  const handle = createVideoChatHandler({
+    authorize: "none", // In-process test only.
+    heartbeatMs: false,
+    streamText: async function* () {
+      yield JSON.stringify({
+        type: "answer", intent: "informational",
+        opening: "Waves move toward the shore.",
+        subject: "ocean waves", development: "",
+        visualDirection: "Natural ocean footage.",
+        ending: {
+          title: "Waves carry energy",
+          narration: "Ocean waves carry energy toward the shore.",
+          subject: "ocean waves", action: "Follow waves toward the shore.",
+          durationSec: 4, continuity: "cut",
+        },
+      }) + "\n";
+    },
+    generateText: async () => "[]",
   });
+  const response = await handle(new Request(
+    "https://app.test/api/video-chat?action=response",
+    { method: "POST", body: JSON.stringify({ prompt: "Explain waves" }) },
+  ));
+  const body = await response.text();
+  expect(response.status).toBe(200);
+  expect(body).toContain('"type":"scene.add"');
+  expect(body).toContain('"type":"response.complete"');
 });
 ```
 
-Also request `?action=capabilities` and `?action=welcome` in route tests. Assert
-that optional modes and controls appear only when their callbacks are present.
-For browser coverage, render `<VideoChat />`, submit through the visible prompt,
-and wait for a known template rather than reaching into hook internals.
-
-## Test protocol events in process
+Also test authorization and capability discovery. In the browser, submit through
+the visible composer and verify a completed answer and recovery. Do not couple
+application tests to private hook state or exact prompt wording.
 
-`simulateVideoStream(parts, options?)` runs the composition and validation
-pipeline without an HTTP boundary. It yields typed event objects and remains
-useful for focused planner and protocol cases beneath the chat handler.
+## Protocol fixtures
 
 ```ts
 import { expect, it } from "vitest";
-import {
-  simulateVideoStream,
-  videoFixtures,
-} from "@vanillaskyai/video/test";
+import { simulateVideoStream, videoFixtures } from "@vanillaskyai/video/test";
 
 it("keeps a truncated result playable", async () => {
   const events = [];
-  for await (const event of simulateVideoStream(
-    videoFixtures.scenarios.truncated,
-  )) {
+  for await (const event of simulateVideoStream(videoFixtures.scenarios.truncated)) {
     events.push(event);
   }
-
   expect(events.at(-1)).toMatchObject({
-    type: "response.complete",
-    data: { finishReason: "length" },
+    type: "response.complete", data: { finishReason: "length" },
   });
 });
 ```
 
-The portrait and landscape fixtures each contain `{ input, parts }`. Public
-fixture values are deeply frozen and every helper clones parts before a run.
-
-## Delays, aborts, and timeouts
-
-Delays and `timeoutMs` use ordinary timers and work with Vitest fake timers.
-
-```ts
-import { expect, it, vi } from "vitest";
-import {
-  simulateVideoStream,
-  videoFixtures,
-} from "@vanillaskyai/video/test";
-
-it("times out deterministically", async () => {
-  vi.useFakeTimers();
-  try {
-    const result = (async () => {
-      const events = [];
-      for await (const event of simulateVideoStream(
-        videoFixtures.scenarios.timeout,
-        { timeoutMs: 50 },
-      )) events.push(event);
-      return events;
-    })();
-
-    await vi.advanceTimersByTimeAsync(50);
-    await expect(result).resolves.toMatchObject([
-      { type: "response.start" },
-      { type: "scene.add" },
-      { type: "response.abort", data: { reason: "Request timed out" } },
-    ]);
-  } finally {
-    vi.useRealTimers();
-  }
-});
-```
-
-For host cancellation, pass an `AbortController` signal and abort after the
-desired partial event. At the route boundary, the host remains responsible for
-aborting the request signal and each provider callback must honour it.
-
-## Fixed planner scenarios
-
-`createMockVideoPlanner({ scenario })` accepts:
+The portrait and landscape fixtures contain frozen `{ input, parts }`.
+Helpers clone inputs for each run. `createMockVideoPlanner({ scenario })`
+provides success, delayed, truncated, invalidScene, providerFailure,
+contentFilter, abort, and timeout scenarios for structural protocol tests.
+Those structural parts are not the default chat model's answer-brief format.
 
-| Scenario | Expected terminal behavior |
-| --- | --- |
-| `success` | Completed portrait fixture |
-| `delayed` | Success after a 25 ms fake-timer-safe delay |
-| `truncated` | Partial playable result completed with `length` |
-| `invalidScene` | Invalid scene dropped with a recoverable warning, then completion |
-| `providerFailure` | Redacted terminal generation failure |
-| `contentFilter` | Partial playable result completed with `content-filter` |
-| `abort` | Waits for the supplied request signal to abort |
-| `timeout` | Waits for the host signal or simulator `timeoutMs` |
+`simulateVideoStream(parts, { signal, timeoutMs })` handles abort and timeout
+without a server. Delays use ordinary timers and work with Vitest fake timers.
+Test cancellation at your route boundary too: every provider must honor the
+request signal.
 
-Use `parts` for custom structural plan parts and `delayMs` to delay each
-provider chunk. Keep provider selection, credentials, retries, and real-model
-acceptance outside deterministic CI.
+Keep fast tests focused on behavior. Run the real packed consumer when public
+types or installation change and browser media tests when playback changes.
+A deterministic fixture proves integration, not live-video quality or latency.
 
-[← Documentation home](../README.md)
+[Documentation home](../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.10.23",
+  "version": "0.11.0",
   "description": "Open-source voice-and-video chat SDK for AI applications.",
   "keywords": [
     "video-chat",
@@ -34,19 +34,17 @@
     "styles/video-chat.css",
     "styles/fonts",
     "starters/video-chat/.env.example",
+    "starters/video-chat/.env.native.example",
     "starters/video-chat/README.md",
     "starters/video-chat/index.html",
     "starters/video-chat/package.json",
     "starters/video-chat/server.ts",
     "starters/video-chat/providers.ts",
-    "starters/video-chat/providers/speech.ts",
-    "starters/video-chat/providers/video.ts",
+    "starters/video-chat/providers",
     "starters/video-chat/src/main.tsx",
     "starters/video-chat/stock.ts",
     "starters/video-chat/tsconfig.json",
     "starters/video-chat/vite.config.ts",
-    "registry/items",
-    "examples/custom-template",
     "README.md",
     "LICENSE",
     "SECURITY.md",
@@ -77,16 +75,6 @@
       "import": "./dist/react.js",
       "default": "./dist/react.js"
     },
-    "./templates": {
-      "types": "./dist/templates.d.ts",
-      "import": "./dist/templates.js",
-      "default": "./dist/templates.js"
-    },
-    "./templates/catalog": {
-      "types": "./dist/template-catalog.d.ts",
-      "import": "./dist/template-catalog.js",
-      "default": "./dist/template-catalog.js"
-    },
     "./test": {
       "types": "./dist/test.d.ts",
       "import": "./dist/test.js",
@@ -99,11 +87,6 @@
     "browser:test": "playwright test",
     "build": "tsup",
     "lint": "eslint .",
-    "catalog:sync": "tsx scripts/generate-builtin-catalog.ts",
-    "catalog:check": "tsx scripts/generate-builtin-catalog.ts --check",
-    "registry:sync": "npm run catalog:sync && node scripts/sync-template-registry.mjs",
-    "registry:check": "node scripts/sync-template-registry.mjs --check && npm run catalog:check",
-    "template:check": "tsx scripts/template-check.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
@@ -122,8 +105,7 @@
   },
   "peerDependencies": {
     "react": ">=18 <20",
-    "react-dom": ">=18 <20",
-    "tsx": ">=4.19 <5"
+    "react-dom": ">=18 <20"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -131,9 +113,6 @@
     },
     "react-dom": {
       "optional": true
-    },
-    "tsx": {
-      "optional": true
     }
   },
   "devDependencies": {

package/starters/video-chat/.env.example

@@ -5,14 +5,22 @@ ANTHROPIC_API_KEY=
 # Generated speech; browser voice remains the fallback.
 XAI_API_KEY=
 
-# Optional: run `npx vanillasky providers add video` first.
-# Generated video and server-side speech transcription.
+# Optional: `providers add video fal` and/or `providers add transcription`.
+# These are independent capabilities.
 FAL_KEY=
+GEMINI_API_KEY=
+RUNWAY_API_KEY=
 
-# Optional: stock video and photography for templates and suggestion cards.
+# Required by the example video-delivery callback, or replace it with your storage.
+VIDEO_UPLOAD_URL=
+VIDEO_STORAGE_TOKEN=
+
+# Optional: stock video and photography for scenes and suggestion cards.
 PEXELS_API_KEY=
 
-# Optional model overrides. The starter ships with tested defaults.
+# Optional model overrides. Check model duration/resolution policy when changing.
 # ANTHROPIC_PLANNER_MODEL=
 # ANTHROPIC_NARRATION_MODEL=
 # FAL_VIDEO_MODEL=
+# GOOGLE_VIDEO_MODEL=
+# RUNWAY_VIDEO_MODEL=

package/starters/video-chat/.env.native.example

@@ -0,0 +1,13 @@
+# Required for the native Gemini REST text adapter (no Vercel AI SDK packages).
+GEMINI_API_KEY=
+# GEMINI_TEXT_MODEL=gemini-2.5-flash
+
+# Optional independent capabilities; install each with providers add.
+XAI_API_KEY=
+FAL_KEY=
+RUNWAY_API_KEY=
+PEXELS_API_KEY=
+
+# Required by the example video-delivery callback, or replace it with your storage.
+VIDEO_UPLOAD_URL=
+VIDEO_STORAGE_TOKEN=

package/starters/video-chat/README.md

@@ -13,31 +13,44 @@ npm run dev
 ```
 <!-- verify:end -->
 
-Add one required key to `.env.local`:
+The default text adapter uses the optional Vercel AI SDK. Add its key to `.env.local`:
 
 ```bash
 ANTHROPIC_API_KEY=...
 ```
 
+Prefer native callbacks? In a new folder run `npx vanillasky init --native` and
+set `GEMINI_API_KEY`. This installs editable Gemini REST text callbacks without
+`ai` or `@ai-sdk/anthropic`. The SDK itself requires neither Vercel nor Google.
+Change `providers/text.ts` to use any text model or your own service.
+
 That enables the introduction and browser voice. Add the video adapter for
 generated footage; without media, narration and subtitles remain available.
 The starter installs only the text provider. Enable adapters as needed:
 
 ```bash
 npx vanillasky providers add speech
-npx vanillasky providers add video
+npx vanillasky providers add video fal
+npx vanillasky providers add transcription
 ```
 
-Each command installs its provider package and connects the adapter through
-`providers.ts`. Run both commands to enable both upgrades.
+Video choices are `fal`, `google`, `runway`, or `custom`; omitting a name selects
+fal. Pick one. These are editable reference integrations, not an SDK vendor
+registry. Video and transcription use native `fetch` with no provider packages.
+Only the optional speech upgrade installs `ai` and `@ai-sdk/xai`.
 
 - Speech: add `XAI_API_KEY` to replace browser voice with generated speech.
-- Video: add `FAL_KEY` for generated video and server transcription.
+- Video: `FAL_KEY`, `GEMINI_API_KEY`, or `RUNWAY_API_KEY` for the selected vendor,
+  plus your app-owned video delivery callback described below.
+- Transcription: add `FAL_KEY` for Whisper independently of your video vendor.
 - Stock: add `PEXELS_API_KEY` for footage and suggestion images; no installation
   is needed.
 
 The adapters live in `providers/` and remain application-owned. Running an
 upgrade again can finish an interrupted dependency installation.
+To switch an already-installed video vendor, replace `providers/video.ts` with
+the corresponding packaged reference (or your implementation) and update
+`vanillasky.videoVendor` in package.json. The CLI will not overwrite edited code.
 
 Restart the development server after changing keys. Open
 <http://localhost:5173> and prompt anything.
@@ -57,16 +70,64 @@ The Pexels adapter searches the full catalog with bounded subject matching,
 orientation selection and caching; it no longer requires a reviewed index.
 Custom interfaces must display a prominent [Pexels](https://www.pexels.com) credit.
 
-Speech and video prepare together. Keep `generatedClipDurationSec` aligned with
-the duration actually requested by the video adapter (five seconds by default).
-The planner writes natural short beats; measured speech controls scene timing.
-Silent footage loops through any remaining narration. Cancellation stops pending
-work and playback, and failed media becomes the authored chapter.
+Speech and video prepare together. Each adapter owns its model, duration,
+resolution, concurrency and deadline; its exported preset forwards those values
+to the handler. Do not override the preset's `generatedClipDurationSec` without
+changing the model request, too. It returns `durationSec` with the delivered
+video. The SDK budgets narration to the clip and holds its last frame if speech
+still overruns; failed media becomes a simple authored chapter.
+
+The fal reference requests five seconds at 480P, concurrency 3, deadline 120s.
+Google Veo requests six seconds at 720p, concurrency 2, deadline 360s.
+Runway Gen-4.5 requests five seconds at 720p, concurrency 2, deadline 180s.
+These are explicit starting policies, not measured performance promises.
+Google and Runway may take minutes. Preparing scenes early and playing them in
+order does not make a provider's job API a real-time video stream.
+
+Each request submits paid generation once and retains its job ID while polling.
+An ambiguous network failure is never automatically resubmitted. Inspect the
+provider dashboard before retrying. To survive process restarts, add an
+`onSubmitted` callback to `runVideoJob` that persists the ID in your job ledger.
+Abort/deadline stops polling and requests best-effort cancellation on fal/Runway.
+Google Veo has no documented cancellation operation; accepted work can still
+complete and be billed. Cancellation never promises a refund.
+
+### App-owned storage and delivery
+
+Every direct video adapter requires a delivery callback. `video-delivery.ts`
+includes an example for **your own** upload endpoint: configure `VIDEO_UPLOAD_URL`
+and `VIDEO_STORAGE_TOKEN`; the endpoint accepts `PUT` MP4 bytes with a `jobId`
+query parameter and returns `{ "url": "https://your-cdn.example/clip.mp4" }`.
+This endpoint is not supplied by VanillaSky. Replace the callback with your
+existing S3/R2/storage code and update `videoDeliveryConfigured` if preferred.
+Until delivery is configured, the starter does not submit video jobs.
+
+The callback receives server-side bytes, the job ID and clip duration. Google
+downloads require a private API key; that key and its private video URI must
+never be sent to the player. Store all vendors' temporary results long enough
+for playback/replay. Deliver H.264 MP4 with the moov atom at the front, correct
+Content-Type/Content-Length, byte-range support and appropriate CORS. The app
+owns storage, access rules, retention and deletion; the core SDK owns none of it.
+
+`providers add video custom` supplies a callback skeleton for any native API or
+vendor SDK. Fill in submit, poll, optional cancel and deliver, then wire the
+factory into `videoProvider.generateVideo`. There is no vendor allowlist in the
+core API. Update `vanillasky.requiredEnv` for custom text key requirements;
+`doctor` checks configuration locally and never submits a paid test job.
 
 The provider names its own model. Override the tested defaults with
-`ANTHROPIC_PLANNER_MODEL`, `ANTHROPIC_NARRATION_MODEL`, or `FAL_VIDEO_MODEL`
+`ANTHROPIC_PLANNER_MODEL`, `ANTHROPIC_NARRATION_MODEL`, `GEMINI_TEXT_MODEL`,
+`FAL_VIDEO_MODEL`, `GOOGLE_VIDEO_MODEL`, or `RUNWAY_VIDEO_MODEL`
 when needed.
 
+API references checked for these examples: [fal queue](https://fal.ai/docs/documentation/model-apis/inference/queue),
+[fal H3](https://fal.ai/models/minimax/h3-max-turbo/text-to-video/api),
+[Google Veo](https://ai.google.dev/gemini-api/docs/video),
+[Runway](https://docs.dev.runwayml.com/api/),
+[native Gemini text](https://ai.google.dev/gemini-api/docs/generate-content/text-generation).
+The offline tests check request/response contracts; they do not establish live
+model quality, account access, provider availability or paid generation speed.
+
 ### Stock selection hints
 
 In Pexels mode, the same planning stream can supply an optional

package/starters/video-chat/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@vanillaskyai/video": "0.10.23",
+    "@vanillaskyai/video": "0.11.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "@ai-sdk/anthropic": "^3.0.0",

package/starters/video-chat/providers/text-native.ts

@@ -0,0 +1,94 @@
+import type { VideoChatHandlerOptions } from "@vanillaskyai/video/server";
+
+// Native Gemini REST example; the SDK only needs strings/AsyncIterable<string>.
+// https://ai.google.dev/gemini-api/docs/generate-content/text-generation
+const MODEL = process.env.GEMINI_TEXT_MODEL ?? "gemini-2.5-flash";
+const BASE = "https://generativelanguage.googleapis.com/v1beta";
+type TextInput = { systemPrompt: string; userPrompt: string; signal: AbortSignal; maxOutputTokens?: number };
+type GeminiOutput = {
+  candidates?: { content?: { parts?: { text?: string; thought?: boolean }[] }; finishReason?: string }[];
+  promptFeedback?: { blockReason?: string };
+  error?: unknown;
+};
+type Completion = { finishReason: "stop" | "length" | "content-filter" | "error"; rawFinishReason?: string };
+
+function completion(output: GeminiOutput): Completion | undefined {
+  const raw = output.promptFeedback?.blockReason ?? output.candidates?.[0]?.finishReason;
+  if (!raw) return undefined;
+  const filtered = output.promptFeedback?.blockReason || ["SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII", "IMAGE_SAFETY"].includes(raw);
+  return { rawFinishReason: raw, finishReason: filtered ? "content-filter" : raw === "STOP" ? "stop" : raw === "MAX_TOKENS" ? "length" : "error" };
+}
+
+function outputText(output: GeminiOutput): string {
+  if (output.error) throw new Error("Text provider failed");
+  return (output.candidates?.[0]?.content?.parts ?? []).filter((part) => !part.thought).map((part) => part.text ?? "").join("");
+}
+
+async function request(input: TextInput, streaming: boolean): Promise<Response> {
+  if (!process.env.GEMINI_API_KEY) throw new Error("Configure GEMINI_API_KEY for the native text adapter");
+  const response = await fetch(`${BASE}/models/${MODEL}:${streaming ? "streamGenerateContent?alt=sse" : "generateContent"}`, {
+    method: "POST", signal: input.signal,
+    headers: { "x-goog-api-key": process.env.GEMINI_API_KEY, "content-type": "application/json" },
+    body: JSON.stringify({ systemInstruction: { parts: [{ text: input.systemPrompt }] },
+      contents: [{ role: "user", parts: [{ text: input.userPrompt }] }],
+      generationConfig: { maxOutputTokens: input.maxOutputTokens ?? 8192, thinkingConfig: { thinkingBudget: 0 } } }),
+  });
+  if (!response.ok) throw new Error(`Text provider HTTP ${response.status}`);
+  return response;
+}
+
+async function* stream(input: TextInput, settle: (value: Completion) => void): AsyncGenerator<string> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  const decoder = new TextDecoder();
+  let pending = "";
+  try {
+    const response = await request(input, true);
+    if (!response.body) throw new Error("Text provider returned no stream");
+    reader = response.body.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      pending += decoder.decode(value, { stream: !done });
+      const lines = pending.split(/\r?\n/);
+      pending = done ? "" : lines.pop()!;
+      for (const line of lines) {
+        if (!line.startsWith("data:")) continue;
+        const data = line.slice(5).trim();
+        if (!data || data === "[DONE]") continue;
+        const output = JSON.parse(data) as GeminiOutput;
+        const text = outputText(output);
+        const finished = completion(output);
+        if (finished) settle(finished);
+        if (text) yield text;
+        if (finished) return;
+      }
+      if (done) break;
+    }
+  } finally {
+    // Also settle transport errors, missing terminal events and iterator close.
+    // Promises resolve (never reject together) so diagnostics cannot hang or
+    // create unhandled rejections when the text iterator itself fails.
+    settle({ finishReason: "error" });
+    void reader?.cancel().catch(() => undefined);
+    reader?.releaseLock();
+  }
+}
+
+export const textProvider: Pick<VideoChatHandlerOptions, "streamText" | "generateText"> = {
+  streamText: (input) => {
+    let settle!: (value: Completion) => void;
+    const finished = new Promise<Completion>(resolve => { settle = resolve; });
+    const iterator = stream(input, settle);
+    // An async generator's finally does not run when closed before first next().
+    const textStream: AsyncIterable<string> = { [Symbol.asyncIterator]: () => ({
+      next: () => iterator.next(),
+      return: () => { settle({ finishReason: "error" }); return iterator.return(undefined); },
+    }) };
+    return { textStream, finishReason: finished.then(value => value.finishReason),
+      rawFinishReason: finished.then(value => value.rawFinishReason) };
+  },
+  generateText: async (input) => {
+    const output = await (await request(input, false)).json() as GeminiOutput;
+    if (completion(output)?.finishReason !== "stop") throw new Error("Text provider did not return a complete unblocked answer");
+    return outputText(output);
+  },
+};

package/starters/video-chat/providers/text.ts

@@ -0,0 +1,19 @@
+import { anthropic } from "@ai-sdk/anthropic";
+import { generateText, streamText } from "ai";
+import type { VideoChatHandlerOptions } from "@vanillaskyai/video/server";
+
+// Optional Vercel AI SDK integration. Replace just this file to change text vendors.
+const PLANNER_MODEL = process.env.ANTHROPIC_PLANNER_MODEL ?? "claude-sonnet-5";
+const NARRATION_MODEL = process.env.ANTHROPIC_NARRATION_MODEL ?? "claude-haiku-4-5";
+export const textProvider: Pick<VideoChatHandlerOptions, "streamText" | "generateText"> = {
+  streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
+    model: anthropic(PLANNER_MODEL), system: systemPrompt, prompt: userPrompt,
+    abortSignal: signal, maxOutputTokens: 8192,
+    providerOptions: { anthropic: { thinking: { type: "disabled" }, output_config: { effort: "medium" } } },
+  }),
+  generateText: async ({ systemPrompt, userPrompt, maxOutputTokens, signal }) => {
+    const { text } = await generateText({ model: anthropic(NARRATION_MODEL), system: systemPrompt,
+      prompt: userPrompt, maxOutputTokens, abortSignal: signal });
+    return text;
+  },
+};

package/starters/video-chat/providers/transcription.ts

@@ -0,0 +1,32 @@
+import type { VideoChatHandlerOptions } from "@vanillaskyai/video/server";
+import { jsonResponse, providerUrl, runVideoJob } from "./video-job";
+
+// Separate capability: using fal Whisper does not select fal for video.
+// https://fal.ai/models/fal-ai/whisper/api — accepts a base64 data URI.
+export const transcriptionProvider: Pick<VideoChatHandlerOptions, "transcribe"> = {
+  transcribe: process.env.FAL_KEY ? async ({ audio, mediaType, signal }) => {
+    signal.throwIfAborted();
+    const headers = { Authorization: `Key ${process.env.FAL_KEY}`, "content-type": "application/json" };
+    const { value } = await runVideoJob({
+      signal, deadlineAt: Date.now() + 60_000, pollIntervalMs: 1000,
+      submit: async (signal) => {
+        const result = await jsonResponse<{ request_id: string; status_url: string; response_url: string; cancel_url: string }>(await fetch("https://queue.fal.run/fal-ai/whisper", {
+          method: "POST", headers, signal,
+          body: JSON.stringify({ audio_url: `data:${mediaType};base64,${Buffer.from(audio).toString("base64")}`, task: "transcribe" }),
+        }));
+        return { id: result.request_id, statusUrl: providerUrl(result.status_url, "https://queue.fal.run"),
+          resultUrl: providerUrl(result.response_url, "https://queue.fal.run"), cancelUrl: providerUrl(result.cancel_url, "https://queue.fal.run") };
+      },
+      poll: async (job, signal) => {
+        const status = await jsonResponse<{ status: string; error?: unknown }>(await fetch(job.statusUrl, { headers, signal }));
+        if (status.error) throw new Error("Transcription failed");
+        if (["IN_QUEUE", "IN_PROGRESS"].includes(status.status)) return null;
+        if (status.status !== "COMPLETED") throw new Error("Unexpected transcription status");
+        const result = await jsonResponse<{ text: string }>(await fetch(job.resultUrl, { headers, signal }));
+        return result.text;
+      },
+      cancel: async (job, signal) => { await fetch(job.cancelUrl, { method: "PUT", headers, signal }); },
+    });
+    return value;
+  } : undefined,
+};