@vanillaskyai/video 0.1.0

package/dist/test.js

@@ -0,0 +1,272 @@
+// src/test/clone.ts
+function cloneValue(value) {
+  if (Array.isArray(value)) return value.map((item) => cloneValue(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [key, cloneValue(child)])
+    );
+  }
+  return value;
+}
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+// src/test/fixtures.ts
+var portrait = {
+  input: {
+    input: "VanillaSky summarizes a grounded product update.",
+    orientation: "portrait"
+  },
+  parts: [
+    {
+      type: "scene.add",
+      scene: {
+        id: "portrait-summary",
+        templateId: "notification",
+        variables: { appName: "VanillaSky", message: "Grounded product update" },
+        timing: { fixedDuration: 4 }
+      }
+    },
+    { type: "plan.complete" }
+  ]
+};
+var landscape = {
+  input: {
+    input: "Revenue reached 42 million.",
+    orientation: "landscape"
+  },
+  parts: [
+    {
+      type: "scene.add",
+      scene: {
+        id: "landscape-metric",
+        templateId: "bigNumber",
+        variables: { texts: "Revenue", value: 42, label: "million" },
+        timing: { fixedDuration: 4 }
+      }
+    },
+    { type: "plan.complete" }
+  ]
+};
+var delayed = [
+  { type: "mock.delay", durationMs: 25 },
+  ...portrait.parts
+];
+var truncated = [
+  {
+    type: "scene.add",
+    scene: {
+      id: "truncated-partial",
+      templateId: "notification",
+      variables: { appName: "VanillaSky", message: "Playable partial result" },
+      timing: { fixedDuration: 4 }
+    }
+  },
+  { type: "mock.raw", text: '{"type":"scene.add","scene":{"id":"unfinished' }
+];
+var invalidScene = [
+  {
+    type: "scene.add",
+    scene: {
+      id: "invalid-scene",
+      templateId: "not-installed",
+      variables: {},
+      timing: { fixedDuration: 3 }
+    }
+  },
+  {
+    type: "scene.add",
+    scene: {
+      id: "valid-after-invalid",
+      templateId: "notification",
+      variables: { appName: "VanillaSky", message: "Recovered after invalid content" },
+      timing: { fixedDuration: 4 }
+    }
+  },
+  { type: "plan.complete" }
+];
+var providerFailure = [
+  {
+    type: "mock.error",
+    message: "Provider failed with authorization=fixture-private-value"
+  }
+];
+var contentFilter = [
+  {
+    type: "scene.add",
+    scene: {
+      id: "content-filter-partial",
+      templateId: "notification",
+      variables: { appName: "VanillaSky", message: "Safe partial result" },
+      timing: { fixedDuration: 4 }
+    }
+  },
+  { type: "plan.complete", finishReason: "content-filter" }
+];
+var abort = [
+  {
+    type: "scene.add",
+    scene: {
+      id: "abort-partial",
+      templateId: "notification",
+      variables: { appName: "VanillaSky", message: "Partial result before cancellation" },
+      timing: { fixedDuration: 4 }
+    }
+  },
+  { type: "mock.wait-for-abort" }
+];
+var timeout = [
+  {
+    type: "scene.add",
+    scene: {
+      id: "timeout-partial",
+      templateId: "notification",
+      variables: { appName: "VanillaSky", message: "Partial result before timeout" },
+      timing: { fixedDuration: 4 }
+    }
+  },
+  { type: "mock.wait-for-abort" }
+];
+var videoFixtures = deepFreeze({
+  portrait,
+  landscape,
+  scenarios: {
+    success: portrait.parts,
+    delayed,
+    truncated,
+    invalidScene,
+    providerFailure,
+    contentFilter,
+    abort,
+    timeout
+  }
+});
+
+// src/test/mock-video-planner.ts
+function abortError(signal) {
+  return signal.reason ?? new Error("Request aborted");
+}
+function wait(durationMs, signal) {
+  if (signal.aborted) return Promise.reject(abortError(signal));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, durationMs);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      reject(abortError(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function waitForAbort(signal) {
+  if (signal.aborted) return Promise.reject(abortError(signal));
+  return new Promise((_, reject) => {
+    signal.addEventListener("abort", () => reject(abortError(signal)), { once: true });
+  });
+}
+function fixtureParts(options) {
+  if (options.parts) return options.parts;
+  return videoFixtures.scenarios[options.scenario ?? "success"];
+}
+function providerFinishReason(parts) {
+  if (parts.some((part) => part.type === "mock.raw")) return "length";
+  let completed;
+  for (let index = parts.length - 1; index >= 0; index -= 1) {
+    if (parts[index].type === "plan.complete") {
+      completed = parts[index];
+      break;
+    }
+  }
+  if (completed?.type === "plan.complete" && completed.finishReason === "content-filter") {
+    return "content-filter";
+  }
+  if (completed?.type === "plan.complete" && completed.finishReason === "length") return "length";
+  return "stop";
+}
+function createMockVideoPlanner(options = {}) {
+  const delayMs = options.delayMs ?? 0;
+  if (!Number.isFinite(delayMs) || delayMs < 0) {
+    throw new Error("Mock planner delayMs must be a non-negative finite number");
+  }
+  const configured = cloneValue(fixtureParts(options));
+  const finishReason = providerFinishReason(configured);
+  return ({ signal }) => {
+    const parts = cloneValue(configured);
+    return {
+      textStream: (async function* () {
+        for (const part of parts) {
+          if (part.type === "mock.delay") {
+            await wait(part.durationMs, signal);
+            continue;
+          }
+          if (part.type === "mock.wait-for-abort") {
+            await waitForAbort(signal);
+          }
+          if (part.type === "mock.error") throw new Error(part.message);
+          if (delayMs > 0) await wait(delayMs, signal);
+          if (part.type === "mock.raw") yield part.text;
+          else yield `${JSON.stringify(part)}
+`;
+        }
+      })(),
+      finishReason: Promise.resolve(finishReason)
+    };
+  };
+}
+
+// src/test/simulate-video-stream.ts
+var DEFAULT_REQUEST_ID = "test-request";
+var DEFAULT_RUN_ID = "test-run";
+function timeoutError() {
+  const error = new Error("Simulation timeout detail");
+  error.name = "TimeoutError";
+  return error;
+}
+async function* simulateVideoStream(parts, options = {}) {
+  const timeoutMs = options.timeoutMs;
+  if (timeoutMs != null && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
+    throw new Error("Simulation timeoutMs must be a non-negative finite number");
+  }
+  const { createVideo } = await import("./compose-video-CN3VSWST.js");
+  const { createTextDeltaVideoPlanner } = await import("./text-stream-6XHC7J47.js");
+  const { BUILTIN_SERVER_TEMPLATE_KIT } = await import("./builtin-server-F7YXRVCH.js");
+  const { createTemplateSceneValidator } = await import("./validate-T7GBU2YF.js");
+  const controller = new AbortController();
+  const forwardAbort = () => controller.abort(options.signal?.reason);
+  if (options.signal?.aborted) forwardAbort();
+  else options.signal?.addEventListener("abort", forwardAbort, { once: true });
+  const timeout2 = timeoutMs == null ? void 0 : setTimeout(() => controller.abort(timeoutError()), timeoutMs);
+  const streamText = createMockVideoPlanner({ parts: cloneValue(parts) });
+  const generate = createTextDeltaVideoPlanner({ streamText });
+  const input = cloneValue(options.input ?? videoFixtures.portrait.input);
+  const run = createVideo(input, {
+    requestId: options.requestId ?? DEFAULT_REQUEST_ID,
+    runId: options.runId ?? DEFAULT_RUN_ID,
+    capabilities: cloneValue(BUILTIN_SERVER_TEMPLATE_KIT.capabilities),
+    validateScene: createTemplateSceneValidator({ kit: BUILTIN_SERVER_TEMPLATE_KIT }),
+    getTemplatePacing: (templateId) => BUILTIN_SERVER_TEMPLATE_KIT.getTemplateMetadata(templateId),
+    invalidPartBehavior: options.invalidPartBehavior ?? "drop",
+    signal: controller.signal,
+    generate
+  });
+  try {
+    for await (const event of run.stream) {
+      yield cloneValue(event);
+    }
+  } finally {
+    if (timeout2) clearTimeout(timeout2);
+    options.signal?.removeEventListener("abort", forwardAbort);
+    if (!controller.signal.aborted) run.abort("Simulation stopped");
+  }
+}
+export {
+  createMockVideoPlanner,
+  simulateVideoStream,
+  videoFixtures
+};

package/dist/text-stream-6XHC7J47.js

@@ -0,0 +1,10 @@
+import {
+  createTextDeltaVideoPlanner
+} from "./chunk-GRMUV7QY.js";
+import "./chunk-E7CL7UPB.js";
+import "./chunk-ERY4S6QV.js";
+import "./chunk-EE6PK6XC.js";
+import "./chunk-XGRA2MUV.js";
+export {
+  createTextDeltaVideoPlanner
+};

package/dist/types-B-PZR6G_.d.ts

@@ -0,0 +1,208 @@
+declare const VIDEO_PROTOCOL_VERSION: "0.4";
+declare const VIDEO_SCHEMA_VERSION: "0.1";
+type VideoOrientation = "portrait" | "landscape";
+interface VideoBrandColors {
+    primary: string;
+    secondary: string;
+    foreground: string;
+    surface: string;
+    surfaceElevated: string;
+    muted: string;
+}
+type VideoBackgroundPreset = "cosmic" | "horizon" | "twilight" | "meadow" | "velvet" | "flamingo" | "peach" | "saffron" | "black" | "midnight" | "aubergine" | "coal" | "navy";
+type VideoBackgroundInput = VideoBackgroundPreset | {
+    color: string;
+} | {
+    colors: [string, string];
+};
+type VideoBackground = {
+    type: "solid";
+    color: string;
+} | {
+    type: "gradient";
+    colors: [string, string];
+};
+interface VideoBrandInput {
+    name?: string;
+    logoUrl?: string;
+    font?: string;
+    scriptFont?: string;
+    background?: VideoBackgroundInput;
+    colors?: Partial<VideoBrandColors>;
+}
+interface VideoBrand {
+    name?: string;
+    logoUrl?: string;
+    font: string;
+    scriptFont: string;
+    background: VideoBackground;
+    colors: VideoBrandColors;
+}
+interface VideoStyle {
+    brand: VideoBrand;
+    preset?: string;
+    defaultBackgroundEffect?: string;
+    defaultTextArchetype?: string;
+    defaultTransition?: string;
+    density?: string;
+    motion?: string;
+}
+interface VideoStyleOptions {
+    density?: "airy" | "normal" | "packed";
+    motion?: "calm" | "normal" | "punchy";
+    textArchetype?: "subtle" | "typewriter" | "wordStagger" | "slam" | "cinematic" | "heroWord";
+    backgroundEffect?: "static" | "slow-zoom-in" | "slow-zoom-out" | "ken-burns" | "drift" | "pulse" | "breathe" | "slow-tilt" | "camera-shake";
+}
+interface VideoTiming {
+    beatStart?: number;
+    beatEnd?: number;
+    startTime?: number;
+    endTime?: number;
+    fixedDuration?: number;
+    durationWeight?: number;
+}
+interface VideoScene {
+    id: string;
+    templateId: string;
+    variables: Record<string, unknown>;
+    textArchetype?: string;
+    backgroundEffect?: string;
+    timing: VideoTiming;
+}
+interface VideoAudio {
+    trackId: string;
+    audioUrl: string;
+    sourceDuration?: number;
+    duration: number;
+    beatDetection: {
+        sensitivity: number;
+        targetBeats?: number;
+        minInterval?: number;
+    };
+    beatMarkers: Array<{
+        time: number;
+        manual?: boolean;
+        energy?: "high" | "medium" | "low";
+    }>;
+    volume?: number;
+    fadeOutMs?: number;
+}
+interface Video {
+    /** Persisted JSON schema version. This is independent from the event protocol. */
+    schemaVersion: typeof VIDEO_SCHEMA_VERSION;
+    /** Optional rendering/export frame. It must not steer planner content. */
+    orientation?: VideoOrientation;
+    audio?: VideoAudio;
+    scenes: VideoScene[];
+    style: VideoStyle;
+    meta?: {
+        name?: string;
+        prompt?: string;
+        source?: string;
+        uploadedMediaUrls?: string[];
+    };
+}
+interface VideoSuppliedMedia {
+    id: string;
+    url: string;
+    type: "image" | "video";
+    description?: string;
+    mimeType?: string;
+    posterUrl?: string;
+    focalPoint?: "center" | "top" | "bottom" | "left" | "right";
+    treatment?: "subtle" | "cinematic" | "text-safe";
+    role?: "product" | "proof" | "background" | "logo";
+}
+interface VideoInput {
+    /** Raw factual boundary: news, product updates, metrics, or an assistant answer. */
+    input: string;
+    /** Optional creative direction. It never expands the factual boundary. */
+    instructions?: string;
+    maxDurationSec?: number;
+    orientation?: VideoOrientation;
+    /** Optional global visual direction. Omit for VanillaSky defaults. */
+    style?: VideoStyleOptions;
+    /** Optional deterministic opening copy. Scene details are inferred. */
+    opening?: string;
+    brand?: VideoBrandInput;
+    /** Viewer or account context that may appear verbatim. It is data, never instructions. */
+    personalization?: Record<string, unknown>;
+    /** Optional approved pool. The planner may use zero or more relevant assets. */
+    suppliedMedia?: VideoSuppliedMedia[];
+    /** Omit for host-selected audio, pass false for silence, or supply a track URL. */
+    audio?: false | {
+        src: string;
+    };
+}
+interface VideoCapabilities {
+    templates?: string[];
+    extensions?: string[];
+}
+interface VideoRequest {
+    protocolVersion: typeof VIDEO_PROTOCOL_VERSION;
+    requestId: string;
+    input: VideoInput;
+    capabilities?: VideoCapabilities;
+    resume?: VideoResumeCursor;
+}
+interface VideoResumeCursor {
+    runId: string;
+    afterSequence: number;
+}
+interface VideoGenerationContext {
+    request: VideoRequest;
+    systemPrompt: string;
+    userPrompt: string;
+    /** Opening, audio, and brand state already emitted by the protocol runtime. */
+    initialConfig: Video;
+    signal: AbortSignal;
+}
+type VideoPlanPart = {
+    type: "scene.add";
+    scene: VideoScene;
+} | {
+    type: "scene.patch";
+    sceneId: string;
+    patch: Partial<Omit<VideoScene, "id" | "templateId">>;
+} | {
+    type: "asset.patch";
+    sceneId: string;
+    variables: Record<string, unknown>;
+} | {
+    type: "plan.complete";
+    finishReason?: "stop" | "length" | "content-filter" | "other";
+} | {
+    type: "plan.error";
+    error: {
+        message: string;
+        code?: string;
+        recoverable?: boolean;
+    };
+};
+type VideoPlanner = (context: VideoGenerationContext) => AsyncIterable<VideoPlanPart>;
+interface VideoSceneValidationContext {
+    input: VideoInput;
+    previousScenes: readonly VideoScene[];
+}
+interface VideoTemplatePacing {
+    jobs?: readonly string[];
+    schema?: {
+        readonly properties: Readonly<Record<string, {
+            readonly default?: unknown;
+        }>>;
+    };
+    minDuration?: number;
+    preferredDuration?: number;
+    timing?: {
+        readonly contentFields: readonly string[];
+        readonly contentUnit: "words" | "characters" | "items";
+    };
+}
+type VideoSceneValidator = (scene: VideoScene, context: VideoSceneValidationContext) => void;
+interface VideoSnapshotRetention {
+    source?: boolean;
+    instructions?: boolean;
+    suppliedMediaUrls?: boolean;
+}
+
+export { type Video as V, type VideoAudio as a, type VideoBackground as b, type VideoBrand as c, type VideoInput as d, type VideoOrientation as e, type VideoScene as f, type VideoStyle as g, type VideoStyleOptions as h, type VideoSuppliedMedia as i, type VideoCapabilities as j, VIDEO_PROTOCOL_VERSION as k, type VideoGenerationContext as l, type VideoPlanner as m, type VideoRequest as n, type VideoSceneValidator as o, type VideoTemplatePacing as p, type VideoSnapshotRetention as q, type VideoResumeCursor as r, type VideoSceneValidationContext as s };

package/dist/validate-T7GBU2YF.js

@@ -0,0 +1,8 @@
+import {
+  createTemplateSceneValidator
+} from "./chunk-LMG3GHLL.js";
+import "./chunk-352ZZCET.js";
+import "./chunk-73NTSFFI.js";
+export {
+  createTemplateSceneValidator
+};

package/docs/agent-integration.md

@@ -0,0 +1,39 @@
+[← Documentation home](../README.md) · [Next: Getting started →](getting-started.md)
+
+# Agent integration
+
+Use the same public path a human developer uses. The optional repository skill
+packages these instructions for coding agents:
+
+```bash
+npx skills add VanillaSkyAi/video@vanillasky
+```
+
+## Build the first response
+
+1. Install `@vanillaskyai/video`, `ai`, and one model provider.
+2. Put the provider key in an ignored `.env.local` file.
+3. Connect the application's LLM with `createVideoHandler` in an authenticated
+   server route.
+4. Pass grounded text or structured data as `input`.
+5. Call `useVideo()` and render `VideoPlayer` in React.
+6. Verify one complete response in a browser before adding optional features.
+
+The root README and `examples/nextjs-quickstart` are the canonical working
+reference. Built-in templates require no registry setup.
+
+## Keep responsibilities clear
+
+VanillaSky owns the planning prompt, trusted templates, validation, streaming
+protocol, and player. The application owns its LLM, credentials,
+authentication, source retrieval, media licensing, persistence, and product
+UI.
+
+Use `input` for facts the video may claim, `instructions` for presentation
+direction, and `personalization` for viewer or account context. Treat all three
+as untrusted application data. Add brand, media, audio, persistence, or custom
+templates only when the requested experience needs them.
+
+If a required credential is missing, ask the developer to add it to the ignored
+environment file. Never invent another provider or request secret values in
+chat.

package/docs/architecture.md

@@ -0,0 +1,84 @@
+# Architecture
+
+VanillaSky turns context into a visual response. Your application and its AI
+decide what matters; VanillaSky turns that decision into a grounded, validated,
+embedded video that starts playing while it is still being composed.
+
+## The shortest mental model
+
+```text
+application context
+  → app-owned model
+  → trusted scene plan
+  → validation and streaming protocol
+  → embedded React player
+```
+
+VanillaSky does not choose your model, retrieve your application context, or
+generate executable UI code. It supplies the video-planning prompt, trusted
+visual vocabulary, validation, streaming lifecycle, and player.
+
+## Repository map
+
+| Location | Purpose |
+| --- | --- |
+| `src/server/create-video-handler.ts` | Public server integration and provider adapter boundary |
+| `src/server/prompts/` | System and user prompts sent to the app-owned model |
+| `src/server/model/` | Converts provider text deltas into typed video plan parts |
+| `src/protocol/` | Shared request, event, validation, checksum, and SSE contract |
+| `src/player/` | Browser stream client, `useVideo`, timeline, and React player |
+| `src/visual-system/catalog/` | Template metadata, schemas, loading, and planner catalog |
+| `src/visual-system/scene-templates/` | Complete scenes the model may select |
+| `src/visual-system/primitives/` | Reusable visual components used inside scenes |
+| `src/visual-system/backgrounds/` | Standalone background renderers |
+| `src/visual-system/motion/` | Animation functions and timing behavior |
+| `src/visual-system/theme/` | Color and design tokens |
+| `src/cli/` | `vanillasky create`, `add`, `sync`, `check`, `list`, and `describe` for customer-owned templates |
+| `registry/items/` | Generated distributable copies installed into customer projects |
+| `src/index.ts`, `src/server.ts`, `src/react.ts`, `src/templates.ts`, `src/template-catalog.ts`, `src/test.ts` | The six small public package entry points |
+
+The source of truth for built-in visuals is `src/visual-system`. The JSON files
+in `registry/items` are distribution artifacts, kept flat so the CLI can address
+every installable item by a stable name. Their `meta.vanillasky.layer` and
+`category` fields distinguish full templates, primitives, effects, and shared
+support code. Run `npm run registry:sync` after changing canonical visual source.
+
+Customer applications do not edit those internal locations. Their source of
+truth is one file per visual under `vanillasky/templates/`; `vanillasky sync`
+derives a browser registry in `vanillasky/index.ts` and a React-free
+prompt/validation registry in `vanillasky/server.ts`.
+
+## Request flow
+
+1. `useVideo().generate(...)` sends grounded input and live application context
+   to the authenticated application route.
+2. `createVideoHandler(...)` builds the prompts and calls the application's
+   `streamText` adapter. This is where OpenAI, Anthropic, or another model is
+   connected.
+3. The system prompt combines the composition rules with the trusted template
+   catalog, including generated metadata for customer-owned templates. The user
+   prompt serializes the factual input, instructions,
+   personalization, brand, and approved media.
+4. The model streams NDJSON plan parts. The server parses and validates complete
+   scenes before emitting versioned video events.
+5. The browser reduces those events into a deterministic `Video`; `VideoPlayer`
+   starts as soon as its first playable scene arrives.
+
+## Where to change common behavior
+
+- Model connection: `src/server/create-video-handler.ts`
+- Base planning rules: `src/server/prompts/system-prompt.ts`
+- Per-request context formatting: `src/server/prompts/user-prompt.ts`
+- Template-specific prompt catalog: `src/visual-system/catalog/prompt.ts`
+- Wire contract: `src/protocol/types.ts` and `src/protocol/events.ts`
+- Scene rendering: `src/visual-system/scene-templates/`
+- Background effects: `src/visual-system/backgrounds/` and
+  `src/visual-system/scene-templates/background-effect.ts`
+- Text effects: `src/visual-system/scene-templates/text-archetypes.ts`
+- Gradients and design tokens: `src/visual-system/theme/`
+
+## Public vocabulary
+
+Use `Video`, `VideoInput`, `useVideo`, and `VideoPlayer` for the product API.
+Use “video response” when describing the lifecycle or output category. Use
+“motion” only for animation behavior inside the visual system.