@vanillaskyai/video 0.2.0 → 0.3.1

package/docs/integrate-nextjs.md

@@ -5,7 +5,7 @@
 Install VanillaSky and one AI SDK provider:
 
 ```bash
-npm install @vanillaskyai/video@0.2.0 ai @ai-sdk/openai
+npm install @vanillaskyai/video@0.3.1 ai @ai-sdk/openai
 ```
 
 Create an ignored `.env.local`:
@@ -27,7 +27,7 @@ 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;
+    if (process.env.VANILLASKY_LOCAL_DEMO !== "1") return false;
     const hostname = new URL(request.url).hostname;
     return hostname === "localhost" || hostname === "127.0.0.1";
   },
@@ -43,6 +43,9 @@ 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
@@ -71,7 +74,7 @@ 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.2.0/examples/nextjs-quickstart).
+[`examples/nextjs-quickstart` directory](https://github.com/VanillaSkyAi/video/tree/v0.3.1/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)

package/docs/media-and-audio.md

@@ -81,7 +81,11 @@ Use `playbackMode="manual"` to require the button on every run,
 `playbackMode="muted-autoplay"` for browser-safe muted autoplay, or
 `playbackMode="autoplay-with-sound"` to try audible autoplay immediately. The
 lower-level `autoPlay` and `startMuted` props remain available when no playback
-mode is set.
+mode is set. For a chat response that should try audible autoplay without the
+SDK generation intro, pass `opening: false`, wait to mount the player until a
+generated scene exists, and render it with `autoPlay` and `startMuted={false}`.
+If the browser blocks the audible start, the player returns to the first frame
+and exposes its sound-start control.
 
 ## Media providers
 

package/docs/prompt-and-input.md

@@ -40,16 +40,17 @@ video.generate({
 ```
 
 Instructions can influence selection, emphasis, ordering, tone, and pacing.
-They never expand the factual boundary, authorize a new media URL, or weaken
-the event and validation contract.
+They never change `knowledgeMode`, authorize a new media URL, or weaken the
+event and validation contract.
 
 For durable product-wide direction, use the server handler's `basePrompt`.
 Keep per-request creative direction in `instructions`.
 
-### 3. Grounded input
+### 3. Input and knowledge mode
 
-`input` is required and is the complete factual source for the video. It may be
-plain text or a serialized structured object:
+`input` is required. With the default `knowledgeMode: "input-only"`, it is the
+complete factual source for the video. It may be plain text or a serialized
+structured object:
 
 ```ts
 video.generate({
@@ -71,6 +72,20 @@ Include exact numbers, quote wording, attribution, names, dates, and product
 facts that may appear on screen. Do not place secrets, provider keys, or hidden
 policy in input.
 
+For a chat question or a request to develop content, opt in explicitly:
+
+```ts
+video.generate({
+  input: "How can a small team improve customer onboarding?",
+  knowledgeMode: "general",
+});
+```
+
+General mode permits stable model knowledge. The generated system prompt still
+forbids invented citations, quotations, URLs, personal details, live facts,
+guarantees, and precise claims that require a source. Claims already present in
+`input` remain authoritative.
+
 `personalization`, `brand`, and `suppliedMedia` are separate structured context.
 They do not replace the source material.
 
@@ -106,7 +121,8 @@ streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
 `userPrompt` is assembled by VanillaSky from:
 
 - orientation and maximum duration;
-- whether an opening scene already exists;
+- whether a deterministic opening scene already exists or the host is waiting
+  for the first generated scene;
 - raw `input`;
 - creative `instructions`;
 - personalization;
@@ -144,7 +160,7 @@ video.generate({
     escalationsResolved: "96%",
     improvementsLaunched: 4,
   }),
-  personalization: { firstName: "Joris" },
+  personalization: { role: "Product leader", focus: "activation" },
 });
 ```
 

package/docs/provider-integration.md

@@ -45,6 +45,41 @@ same handler without adding a VanillaSky abstraction. See
 [provider adapter reference](reference/provider-adapters.md) for model alternatives and advanced native
 provider loops.
 
+## Planning effort and reasoning modes
+
+Planning is a structured emit against a trusted catalog, not a reasoning task.
+Where a provider exposes a reasoning or effort control, a host that wants a
+video to start quickly should turn extended reasoning off and keep effort low
+to moderate. The default matters: several current models reason by default, and
+that reasoning happens before the first plan part is emitted, so it is added
+directly to time to first generated scene.
+
+With the Vercel AI SDK and a current Anthropic model, that is one option object:
+
+```ts
+streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
+  model,
+  system: systemPrompt,
+  prompt: userPrompt,
+  abortSignal: signal,
+  providerOptions: {
+    anthropic: { thinking: { type: "disabled" }, effort: "medium" },
+  },
+}),
+```
+
+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.
+
+VanillaSky never sets these controls. Provider selection, sampling parameters,
+and credentials stay with the application.
+
 ## Completion and usage
 
 Use `onComplete` for server-side cost and completion measurement:
@@ -118,5 +153,6 @@ same explicit request budget.
 `createVideoHandler` constructs the planner prompt from the generated server
 template registry. Normal integrations do not build prompts or capabilities.
 Use the handler's `basePrompt` option only for durable product-level direction.
-Grounded facts still come from `VideoInput.input`; presentation guidance must
-never override that factual boundary.
+`VideoInput.knowledgeMode` owns the knowledge boundary: `input-only` is strict
+and remains the default, while `general` permits stable model knowledge.
+Presentation guidance in `basePrompt` or `instructions` never changes it.

package/examples/nextjs-quickstart/README.md

@@ -16,7 +16,9 @@ Add your OpenAI API key to `.env.local` before selecting **Generate video**.
 
 Open <http://localhost:3000> and select **Generate video**.
 
-The example authorizes local development only and denies production requests.
+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/package.json

@@ -3,13 +3,13 @@
   "private": true,
   "version": "0.0.0",
   "scripts": {
-    "dev": "next dev",
+    "dev": "cross-env VANILLASKY_LOCAL_DEMO=1 next dev",
     "build": "next build",
     "start": "next start"
   },
   "dependencies": {
     "@ai-sdk/openai": "^4.0.42",
-    "@vanillaskyai/video": "0.2.0",
+    "@vanillaskyai/video": "0.3.1",
     "ai": "^7.0.66",
     "next": "16.3.1",
     "react": "19.2.8",
@@ -19,6 +19,7 @@
     "@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

@@ -6,7 +6,7 @@ const model = openai(process.env.OPENAI_MODEL ?? "gpt-4.1");
 
 const handle = createVideoHandler({
   authorize: (request) => {
-    if (process.env.NODE_ENV !== "development") return false;
+    if (process.env.VANILLASKY_LOCAL_DEMO !== "1") return false;
     const hostname = new URL(request.url).hostname;
     return hostname === "localhost" || hostname === "127.0.0.1";
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillaskyai/video",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Open-source video response SDK for personalized AI applications.",
   "keywords": [
     "generative-video",

package/dist/system-prompt-GYTYGWGO.js

@@ -1,8 +0,0 @@
-import {
-  DEFAULT_VIDEO_SYSTEM_PROMPT,
-  VIDEO_PLAN_INSTRUCTION
-} from "./chunk-K5SRF7D3.js";
-export {
-  DEFAULT_VIDEO_SYSTEM_PROMPT,
-  VIDEO_PLAN_INSTRUCTION
-};