vargai 0.4.0-alpha2 → 0.4.0-alpha21

package/src/react/examples/madi.tsx

@@ -1,6 +1,6 @@
 import { elevenlabs } from "../../ai-sdk/providers/elevenlabs";
 import { fal } from "../../ai-sdk/providers/fal";
-import { Animate, Clip, Image, Music, Render } from "..";
+import { Clip, Image, Music, Render, Video } from "..";
 
 const MADI_REF =
   "https://s3.varg.ai/fellowers/madi/character_shots/madi_shot_03_closeup.png";
@@ -43,16 +43,19 @@ export default (
 
     {SCENES.map((scene) => (
       <Clip key={scene.prompt} duration={2}>
-        <Animate
-          image={Image({
-            prompt: { text: scene.prompt, images: [MADI_REF] },
-            model: fal.imageModel("nano-banana-pro/edit"),
-            aspectRatio: "9:16",
-            resize: "cover",
-          })}
-          motion={scene.motion}
+        <Video
+          prompt={{
+            text: scene.motion,
+            images: [
+              Image({
+                prompt: { text: scene.prompt, images: [MADI_REF] },
+                model: fal.imageModel("nano-banana-pro/edit"),
+                aspectRatio: "9:16",
+                resize: "cover",
+              }),
+            ],
+          }}
           model={fal.videoModel("wan-2.5")}
-          duration={5}
         />
       </Clip>
     ))}

package/src/react/examples/mcmeows.tsx

@@ -0,0 +1,40 @@
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs";
+import { fal } from "../../ai-sdk/providers/fal";
+import { Clip, Music, Render, render, Title, Video } from "..";
+
+export default (
+  <Render>
+    <Clip duration={4}>
+      <Video prompt="A sophisticated tabby cat wearing a tailored tiny business suit and small round glasses, standing upright at a McDonald's counter. One paw raised pointing assertively at the illuminated menu board above. The cat has an extremely serious, concentrated expression with furrowed brows. Cinematic lighting with warm McDonald's interior ambiance, shallow depth of field focusing on the cat's determined face, photorealistic fur texture with fine detail. Professional business atmosphere meets fast food chaos." />
+    </Clip>
+
+    <Clip duration={4}>
+      <Video prompt="Absolute mayhem - four to five cats in a chaotic pile fight. Orange tabby, black and white tuxedo cat, calico with patches, and fluffy gray cat all scrambling, paws flailing, tumbling over each other in exaggerated cartoon-style motion. They're all desperately reaching for a single perfect golden McDonald's french fry sitting on a red plastic tray in the center. Wide-eyed expressions, mouths open mid-meow, dynamic motion blur, comedic timing. Fast food restaurant background slightly blurred. Playful, over-the-top energy." />
+    </Clip>
+
+    <Clip duration={3}>
+      <Video prompt="Proud orange tabby cat wearing an official McDonald's crew member visor and name tag, standing upright behind a restaurant register counter. Front paws crossed confidently across chest, chin lifted with a smug, self-satisfied expression. Perfect posture, professional demeanor. Bright McDonald's interior lighting, red and yellow color scheme in background. The cat radiates 'employee of the month' energy. Crisp, clean, professional fast food aesthetic." />
+      <Title position="bottom">McMeow's: NOW HIRING</Title>
+    </Clip>
+
+    <Music
+      model={elevenlabs.musicModel()}
+      prompt="playful upbeat comedy music with quirky pizzicato strings and light percussion, funny corporate training video vibes"
+      duration={11}
+    />
+  </Render>
+);
+
+async function main() {
+  const component = await import("./mcmeows.tsx").then((m) => m.default);
+  await render(component, {
+    output: "output/mcmeows.mp4",
+    cache: ".cache/ai",
+    verbose: true,
+    defaults: {
+      video: fal.videoModel("wan-2.5"),
+    },
+  });
+}
+
+main().catch(console.error);

package/src/react/examples/music-defaults.tsx

@@ -0,0 +1,24 @@
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs";
+import { Clip, Image, Music, Render, render } from "..";
+
+export default (
+  <Render width={1920} height={1080}>
+    <Clip duration={5}>
+      <Image src="media/cyberpunk-street.png" />
+    </Clip>
+    <Music prompt="calm ambient electronic music" duration={5} />
+  </Render>
+);
+
+async function main() {
+  const component = await import("./music-defaults.tsx").then((m) => m.default);
+  await render(component, {
+    output: "output/music-defaults.mp4",
+    defaults: {
+      music: elevenlabs.musicModel(),
+    },
+  });
+  console.log("done! check output/music-defaults.mp4");
+}
+
+main().catch(console.error);

package/src/react/examples/quickstart-test.tsx

@@ -0,0 +1,97 @@
+/**
+ * Quickstart Test - Verification script for video generation setup
+ *
+ * This minimal test confirms your FAL_API_KEY is working correctly.
+ * It generates a simple 3-second animated image.
+ *
+ * Run: bun run src/react/examples/quickstart-test.tsx
+ * Output: output/quickstart-test.mp4
+ */
+
+import { fal } from "../../ai-sdk/providers/fal";
+import { Clip, Image, Render, render, Video } from "..";
+
+async function main() {
+  console.log("=== Varg Video Generation - Setup Verification ===\n");
+
+  // Check for FAL_API_KEY
+  if (!process.env.FAL_API_KEY) {
+    console.error("ERROR: FAL_API_KEY not found in environment");
+    console.error("\nTo fix this:");
+    console.error("1. Get an API key at: https://fal.ai/dashboard/keys");
+    console.error("2. Add to .env file: FAL_API_KEY=fal_xxxxx");
+    console.error("3. Run this test again");
+    process.exit(1);
+  }
+
+  console.log("FAL_API_KEY found");
+
+  // Check for optional keys
+  const hasElevenLabs = !!process.env.ELEVENLABS_API_KEY;
+  const hasReplicate = !!process.env.REPLICATE_API_TOKEN;
+  const hasGroq = !!process.env.GROQ_API_KEY;
+
+  console.log("\nOptional keys:");
+  console.log(
+    `  ELEVENLABS_API_KEY: ${hasElevenLabs ? "found" : "not found (music/voice unavailable)"}`,
+  );
+  console.log(
+    `  REPLICATE_API_TOKEN: ${hasReplicate ? "found" : "not found (lipsync unavailable)"}`,
+  );
+  console.log(
+    `  GROQ_API_KEY: ${hasGroq ? "found" : "not found (transcription unavailable)"}`,
+  );
+
+  console.log("\n--- Running verification test ---\n");
+  console.log("Generating a simple 3-second animation...");
+  console.log("This may take 30-60 seconds on first run.\n");
+
+  const video = (
+    <Render width={720} height={720}>
+      <Clip duration={3}>
+        <Video
+          prompt={{
+            text: "robot waves hello, friendly gesture, slight head tilt",
+            images: [
+              Image({
+                prompt:
+                  "a friendly robot waving hello, simple cartoon style, blue and white colors, clean background",
+                model: fal.imageModel("flux-schnell"),
+                aspectRatio: "1:1",
+              }),
+            ],
+          }}
+          model={fal.videoModel("wan-2.5")}
+        />
+      </Clip>
+    </Render>
+  );
+
+  try {
+    const buffer = await render(video, {
+      output: "output/quickstart-test.mp4",
+      cache: ".cache/ai",
+    });
+
+    console.log("\n=== SUCCESS ===");
+    console.log(
+      `Output: output/quickstart-test.mp4 (${(buffer.byteLength / 1024 / 1024).toFixed(2)} MB)`,
+    );
+    console.log("\nYour setup is working! You can now:");
+    console.log("1. Try the templates in .claude/skills/video-generation.md");
+    console.log(
+      "2. Run existing examples: bun run src/react/examples/madi.tsx",
+    );
+    console.log("3. Create your own videos using the React engine");
+  } catch (error) {
+    console.error("\n=== VERIFICATION FAILED ===");
+    console.error("Error:", error instanceof Error ? error.message : error);
+    console.error("\nCommon fixes:");
+    console.error("- Check FAL_API_KEY is correct (no extra spaces)");
+    console.error("- Ensure you have credits at fal.ai");
+    console.error("- Try running: bun install");
+    process.exit(1);
+  }
+}
+
+main();

package/src/react/index.ts

@@ -1,6 +1,6 @@
 export type { SizeValue } from "../ai-sdk/providers/editly/types";
+export { assets } from "./assets";
 export {
-  Animate,
   Captions,
   Clip,
   Image,
@@ -20,7 +20,6 @@ export {
 export { Grid, SplitLayout } from "./layouts";
 export { render, renderStream } from "./render";
 export type {
-  AnimateProps,
   CaptionsProps,
   ClipProps,
   ImageProps,

package/src/react/react.test.ts

@@ -2,7 +2,6 @@ import { describe, expect, test } from "bun:test";
 import { existsSync, unlinkSync } from "node:fs";
 import { fal } from "../ai-sdk/providers/fal";
 import {
-  Animate,
   Captions,
   Clip,
   Image,
@@ -80,19 +79,20 @@ describe("varg-react elements", () => {
     expect(element.children).toContain("I'M IN DANGER");
   });
 
-  test("Animate creates correct element with nested image", () => {
+  test("Video creates correct element with nested image", () => {
     const image = Image({ prompt: "luigi in wheelchair" });
-    const element = Animate({
-      image,
+    const element = Video({
+      prompt: { text: "wheels spinning fast", images: [image] },
       model: fal.videoModel("wan-2.5"),
-      motion: "wheels spinning fast",
-      duration: 5,
     });
 
-    expect(element.type).toBe("animate");
-    expect(element.props.image).toBe(image);
-    expect(element.props.motion).toBe("wheels spinning fast");
-    expect(element.props.duration).toBe(5);
+    expect(element.type).toBe("video");
+    expect((element.props.prompt as { images: unknown[] }).images[0]).toBe(
+      image,
+    );
+    expect((element.props.prompt as { text: string }).text).toBe(
+      "wheels spinning fast",
+    );
   });
 
   test("nested composition builds correct tree", () => {

package/src/react/renderers/clip.ts

@@ -8,7 +8,6 @@ import type {
   VideoLayer,
 } from "../../ai-sdk/providers/editly/types";
 import type {
-  AnimateProps,
   ClipProps,
   ImageProps,
   SpeechProps,
@@ -16,7 +15,6 @@ import type {
   VargNode,
   VideoProps,
 } from "../types";
-import { renderAnimate } from "./animate";
 import type { RenderContext } from "./context";
 import { renderImage } from "./image";
 import { renderPackshot } from "./packshot";
@@ -32,9 +30,15 @@ type PendingLayer =
   | { type: "sync"; layer: Layer }
   | { type: "async"; promise: Promise<Layer> };
 
+interface ClipLayerOptions {
+  cutFrom?: number;
+  cutTo?: number;
+}
+
 async function renderClipLayers(
   children: VargNode[],
   ctx: RenderContext,
+  clipOptions?: ClipLayerOptions,
 ): Promise<Layer[]> {
   const pending: PendingLayer[] = [];
 
@@ -86,8 +90,9 @@ async function renderClipLayers(
                 type: "video",
                 path,
                 resizeMode: props.resize,
-                cutFrom: props.cutFrom,
-                cutTo: props.cutTo,
+                // Video-level cutFrom/cutTo take precedence over clip-level
+                cutFrom: props.cutFrom ?? clipOptions?.cutFrom,
+                cutTo: props.cutTo ?? clipOptions?.cutTo,
                 mixVolume: props.keepAudio ? (props.volume ?? 1) : 0,
                 left: props.left,
                 top: props.top,
@@ -99,25 +104,6 @@ async function renderClipLayers(
         break;
       }
 
-      case "animate": {
-        const props = element.props as AnimateProps;
-        pending.push({
-          type: "async",
-          promise: renderAnimate(element as VargElement<"animate">, ctx).then(
-            (path) =>
-              ({
-                type: "video",
-                path,
-                left: props.left,
-                top: props.top,
-                width: props.width,
-                height: props.height,
-              }) as VideoLayer,
-          ),
-        });
-        break;
-      }
-
       case "title": {
         pending.push({
           type: "sync",
@@ -220,7 +206,10 @@ export async function renderClip(
   ctx: RenderContext,
 ): Promise<Clip> {
   const props = element.props as ClipProps;
-  const layers = await renderClipLayers(element.children, ctx);
+  const layers = await renderClipLayers(element.children, ctx, {
+    cutFrom: props.cutFrom,
+    cutTo: props.cutTo,
+  });
 
   const isOverlayVideo = (l: Layer) =>
     l.type === "video" &&

package/src/react/renderers/context.ts

@@ -1,6 +1,7 @@
 import type { generateImage } from "ai";
 import type { fileCache } from "../../ai-sdk/file-cache";
 import type { generateVideo } from "../../ai-sdk/generate-video";
+import type { DefaultModels } from "../types";
 import type { ProgressTracker } from "./progress";
 
 export interface RenderContext {
@@ -14,4 +15,6 @@ export interface RenderContext {
   progress?: ProgressTracker;
   /** In-memory deduplication for concurrent renders of the same element */
   pending: Map<string, Promise<string>>;
+  /** Default models for elements that don't specify one */
+  defaults?: DefaultModels;
 }

package/src/react/renderers/image.ts

@@ -54,9 +54,11 @@ export async function renderImage(
     throw new Error("Image element requires either 'prompt' or 'src'");
   }
 
-  const model = props.model;
+  const model = props.model ?? ctx.defaults?.image;
   if (!model) {
-    throw new Error("Image element requires 'model' prop when using prompt");
+    throw new Error(
+      "Image element requires 'model' prop (or set defaults.image in render options)",
+    );
   }
 
   // Compute cache key for deduplication

package/src/react/renderers/index.ts

@@ -1,4 +1,3 @@
-export { renderAnimate } from "./animate";
 export { renderCaptions } from "./captions";
 export { renderClip } from "./clip";
 export type { RenderContext } from "./context";

package/src/react/renderers/music.ts

@@ -10,9 +10,9 @@ export async function renderMusic(
   const props = element.props as MusicProps;
 
   const prompt = props.prompt;
-  const model = props.model;
+  const model = props.model ?? ctx.defaults?.music;
   if (!prompt || !model) {
-    throw new Error("Music generation requires both prompt and model");
+    throw new Error("Music requires prompt and model (or set defaults.music)");
   }
 
   const cacheKey = JSON.stringify({
@@ -22,7 +22,7 @@ export async function renderMusic(
     duration: props.duration,
   });
 
-  const modelId = model.modelId;
+  const modelId = model.modelId ?? "music";
   const taskId = ctx.progress ? addTask(ctx.progress, "music", modelId) : null;
 
   const generateFn = async () => {

package/src/react/renderers/progress.ts

@@ -1,7 +1,6 @@
 export type GenerationType =
   | "image"
   | "video"
-  | "animate"
   | "speech"
   | "music"
   | "editly"
@@ -11,7 +10,6 @@ export type GenerationType =
 export const TIME_ESTIMATES: Record<GenerationType, number> = {
   image: 30,
   video: 120,
-  animate: 90,
   speech: 5,
   music: 45,
   editly: 15,
@@ -103,7 +101,7 @@ export function completeTask(tracker: ProgressTracker, id: string): void {
 }
 
 function getEstimate(task: ProgressTask): number {
-  const modelLower = task.model.toLowerCase();
+  const modelLower = task.model?.toLowerCase() ?? "";
   for (const [key, estimate] of Object.entries(MODEL_TIME_ESTIMATES)) {
     if (modelLower.includes(key.toLowerCase())) {
       return estimate;

package/src/react/renderers/render.ts

@@ -25,7 +25,6 @@ import type {
   SpeechProps,
   VargElement,
 } from "../types";
-import { renderAnimate } from "./animate";
 import { renderCaptions } from "./captions";
 import { renderClip } from "./clip";
 import type { RenderContext } from "./context";
@@ -54,58 +53,59 @@ export async function renderRoot(
   const props = element.props as RenderProps;
   const progress = createProgressTracker(options.quiet ?? false);
 
-  const mode: RenderMode = options.mode ?? "default";
+  const mode: RenderMode = options.mode ?? "strict";
   const placeholderCount = { images: 0, videos: 0, total: 0 };
 
-  const onFallback = (error: Error, prompt: string) => {
-    if (!options.quiet) {
-      console.warn(
-        `\x1b[33m⚠ provider failed: ${error.message} → placeholder\x1b[0m`,
-      );
-    }
-  };
-
   const trackPlaceholder = (type: "image" | "video") => {
     placeholderCount[type === "image" ? "images" : "videos"]++;
     placeholderCount.total++;
   };
 
+  const cachedGenerateImage = options.cache
+    ? withCache(generateImage, { storage: fileCache({ dir: options.cache }) })
+    : generateImage;
+
+  const cachedGenerateVideo = options.cache
+    ? withCache(generateVideo, { storage: fileCache({ dir: options.cache }) })
+    : generateVideo;
+
   const wrapGenerateImage: typeof generateImage = async (opts) => {
     if (
       typeof opts.model === "string" ||
       opts.model.specificationVersion !== "v3"
     ) {
-      return generateImage(opts);
+      return cachedGenerateImage(opts);
     }
-    const wrappedModel = wrapImageModel({
-      model: opts.model,
-      middleware: imagePlaceholderFallbackMiddleware({
-        mode,
-        onFallback: (error, prompt) => {
-          trackPlaceholder("image");
-          onFallback(error, prompt);
-        },
-      }),
-    });
-    const result = await generateImage({ ...opts, model: wrappedModel });
-    if (mode === "preview") trackPlaceholder("image");
-    return result;
+
+    if (mode === "preview") {
+      trackPlaceholder("image");
+      const wrappedModel = wrapImageModel({
+        model: opts.model,
+        middleware: imagePlaceholderFallbackMiddleware({
+          mode: "preview",
+          onFallback: () => {},
+        }),
+      });
+      return generateImage({ ...opts, model: wrappedModel });
+    }
+
+    return cachedGenerateImage(opts);
   };
 
   const wrapGenerateVideo: typeof generateVideo = async (opts) => {
-    const wrappedModel = wrapVideoModel({
-      model: opts.model,
-      middleware: placeholderFallbackMiddleware({
-        mode,
-        onFallback: (error, prompt) => {
-          trackPlaceholder("video");
-          onFallback(error, prompt);
-        },
-      }),
-    });
-    const result = await generateVideo({ ...opts, model: wrappedModel });
-    if (mode === "preview") trackPlaceholder("video");
-    return result;
+    if (mode === "preview") {
+      trackPlaceholder("video");
+      const wrappedModel = wrapVideoModel({
+        model: opts.model,
+        middleware: placeholderFallbackMiddleware({
+          mode: "preview",
+          onFallback: () => {},
+        }),
+      });
+      return generateVideo({ ...opts, model: wrappedModel });
+    }
+
+    return cachedGenerateVideo(opts);
   };
 
   const ctx: RenderContext = {
@@ -113,19 +113,12 @@ export async function renderRoot(
     height: props.height ?? 1080,
     fps: props.fps ?? 30,
     cache: options.cache ? fileCache({ dir: options.cache }) : undefined,
-    generateImage: options.cache
-      ? withCache(wrapGenerateImage, {
-          storage: fileCache({ dir: options.cache }),
-        })
-      : wrapGenerateImage,
-    generateVideo: options.cache
-      ? withCache(wrapGenerateVideo, {
-          storage: fileCache({ dir: options.cache }),
-        })
-      : wrapGenerateVideo,
+    generateImage: wrapGenerateImage,
+    generateVideo: wrapGenerateVideo,
     tempFiles: [],
     progress,
     pending: new Map(),
+    defaults: options.defaults,
   };
 
   const clipElements: VargElement<"clip">[] = [];
@@ -177,13 +170,10 @@ export async function renderRoot(
       const childElement = child as VargElement;
 
       let path: string | undefined;
-      const isVideo =
-        childElement.type === "video" || childElement.type === "animate";
+      const isVideo = childElement.type === "video";
 
       if (childElement.type === "video") {
         path = await renderVideo(childElement as VargElement<"video">, ctx);
-      } else if (childElement.type === "animate") {
-        path = await renderAnimate(childElement as VargElement<"animate">, ctx);
       } else if (childElement.type === "image") {
         path = await renderImage(childElement as VargElement<"image">, ctx);
       }
@@ -255,11 +245,11 @@ export async function renderRoot(
     let path: string;
     if (musicProps.src) {
       path = resolvePath(musicProps.src);
-    } else if (musicProps.prompt && musicProps.model) {
+    } else if (musicProps.prompt) {
       const result = await renderMusic(musicElement, ctx);
       path = result.path;
     } else {
-      throw new Error("Music requires either src or prompt+model");
+      throw new Error("Music requires either src or prompt");
     }
 
     audioTracks.push({
@@ -287,6 +277,8 @@ export async function renderRoot(
     fps: ctx.fps,
     clips,
     audioTracks: audioTracks.length > 0 ? audioTracks : undefined,
+    shortest: props.shortest,
+    verbose: options.verbose,
   });
 
   completeTask(progress, editlyTaskId);
@@ -302,16 +294,10 @@ export async function renderRoot(
     completeTask(progress, captionsTaskId);
   }
 
-  if (!options.quiet && placeholderCount.total > 0) {
-    if (mode === "preview") {
-      console.log(
-        `\x1b[36mℹ preview mode: ${placeholderCount.total} placeholders used (${placeholderCount.images} images, ${placeholderCount.videos} videos)\x1b[0m`,
-      );
-    } else {
-      console.warn(
-        `\x1b[33m⚠ ${placeholderCount.total} elements used placeholders - run with --strict for production\x1b[0m`,
-      );
-    }
+  if (!options.quiet && mode === "preview" && placeholderCount.total > 0) {
+    console.log(
+      `\x1b[36mℹ preview mode: ${placeholderCount.total} placeholders used (${placeholderCount.images} images, ${placeholderCount.videos} videos)\x1b[0m`,
+    );
   }
 
   const result = await Bun.file(finalOutPath).arrayBuffer();

package/src/react/renderers/speech.ts

@@ -21,9 +21,9 @@ export async function renderSpeech(
     throw new Error("Speech element requires text content");
   }
 
-  const model = props.model;
+  const model = props.model ?? ctx.defaults?.speech;
   if (!model) {
-    throw new Error("Speech element requires 'model' prop");
+    throw new Error("Speech requires 'model' prop (or set defaults.speech)");
   }
 
   const cacheKey = computeCacheKey(element);