vargai 0.4.0-alpha.1 → 0.4.0-alpha11

package/README.md

@@ -5,9 +5,46 @@ AI video generation from your terminal.
 ## Quick Start
 
 ```bash
-bun install @vargai/sdk
+bun install vargai ai
 ```
 
+### SDK Usage
+
+```typescript
+import { generateImage } from "ai";
+import { File, fal, generateElement, generateVideo, scene } from "vargai";
+
+// generate a character from reference image
+const { element: character } = await generateElement({
+  model: fal.imageModel("nano-banana-pro/edit"),
+  type: "character",
+  prompt: {
+    text: "cartoon character, simple style",
+    images: [await File.fromPath("media/reference.jpg").arrayBuffer()],
+  },
+});
+
+// generate scene with character
+const { image: frame } = await generateImage({
+  model: fal.imageModel("nano-banana-pro"),
+  prompt: scene`${character} walks through a forest`,
+});
+
+// animate the frame
+const { video } = await generateVideo({
+  model: fal.videoModel("wan-2.5"),
+  prompt: {
+    text: `${character.text} walks through a forest`,
+    images: [frame.base64],
+  },
+  duration: 5,
+});
+
+await Bun.write("output/scene.mp4", video.uint8Array);
+```
+
+### CLI Usage
+
 ```bash
 varg run image --prompt "cyberpunk cityscape at night"
 varg run video --prompt "camera flies through clouds" --duration 5

package/package.json

@@ -33,7 +33,9 @@
     "lint-staged": "^16.2.7"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5",
+    "ai": "^6.0.0",
+    "zod": "^3.25.76 || ^4.1.8"
   },
   "dependencies": {
     "@ai-sdk/fal": "^1.0.23",
@@ -62,7 +64,7 @@
     "replicate": "^1.4.0",
     "zod": "^4.2.1"
   },
-  "version": "0.4.0-alpha.1",
+  "version": "0.4.0-alpha11",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",
@@ -70,6 +72,8 @@
     "./providers": "./src/providers/index.ts",
     "./definitions": "./src/definitions/index.ts",
     "./react": "./src/react/index.ts",
-    "./studio": "./src/studio/index.ts"
+    "./studio": "./src/studio/index.ts",
+    "./jsx-runtime": "./src/react/runtime/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/react/runtime/jsx-dev-runtime.ts"
   }
 }

package/src/ai-sdk/index.ts

@@ -25,6 +25,25 @@ export {
   type GenerateVideoResult,
   generateVideo,
 } from "./generate-video";
+export {
+  generatePlaceholder,
+  type ImagePlaceholderFallbackOptions,
+  imagePlaceholderFallbackMiddleware,
+  type MusicModelMiddleware,
+  type MusicPlaceholderFallbackOptions,
+  musicPlaceholderFallbackMiddleware,
+  type PlaceholderFallbackOptions,
+  type PlaceholderOptions,
+  type PlaceholderResult,
+  placeholderFallbackMiddleware,
+  type RenderMode,
+  type VideoModelMiddleware,
+  withImagePlaceholderFallback,
+  withMusicPlaceholderFallback,
+  withPlaceholderFallback,
+  wrapMusicModel,
+  wrapVideoModel,
+} from "./middleware";
 export type {
   MusicModelV3,
   MusicModelV3CallOptions,
@@ -42,8 +61,8 @@ export {
   type ElevenLabsProvider,
   elevenlabs,
   VOICES,
-} from "./providers/elevenlabs-provider";
-export { createFal, type FalProvider, fal } from "./providers/fal-provider";
+} from "./providers/elevenlabs";
+export { createFal, type FalProvider, fal } from "./providers/fal";
 export {
   createHiggsfield,
   type HiggsfieldImageModelSettings,

package/src/ai-sdk/middleware/index.ts

@@ -0,0 +1,25 @@
+export {
+  generatePlaceholder,
+  type PlaceholderOptions,
+  type PlaceholderResult,
+} from "./placeholder";
+export {
+  type ImagePlaceholderFallbackOptions,
+  imagePlaceholderFallbackMiddleware,
+  withImagePlaceholderFallback,
+} from "./wrap-image-model";
+export {
+  type MusicModelMiddleware,
+  type MusicPlaceholderFallbackOptions,
+  musicPlaceholderFallbackMiddleware,
+  withMusicPlaceholderFallback,
+  wrapMusicModel,
+} from "./wrap-music-model";
+export {
+  type PlaceholderFallbackOptions,
+  placeholderFallbackMiddleware,
+  type RenderMode,
+  type VideoModelMiddleware,
+  withPlaceholderFallback,
+  wrapVideoModel,
+} from "./wrap-video-model";

package/src/ai-sdk/middleware/placeholder.ts

@@ -0,0 +1,111 @@
+import { unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { $ } from "bun";
+
+export interface PlaceholderOptions {
+  type: "image" | "video" | "audio";
+  prompt: string;
+  duration?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface PlaceholderResult {
+  data: Uint8Array;
+  placeholder: true;
+}
+
+function promptToColor(prompt: string): string {
+  let hash = 0;
+  for (let i = 0; i < prompt.length; i++) {
+    const char = prompt.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+
+  const h = Math.abs(hash) % 360;
+  const s = 40 + (Math.abs(hash >> 8) % 30);
+  const l = 35 + (Math.abs(hash >> 16) % 20);
+
+  return `hsl(${h},${s}%,${l}%)`;
+}
+
+function hslToHex(hsl: string): string {
+  const match = hsl.match(/hsl\((\d+),(\d+)%,(\d+)%\)/);
+  if (!match) return "333333";
+
+  const h = Number.parseInt(match[1]!) / 360;
+  const s = Number.parseInt(match[2]!) / 100;
+  const l = Number.parseInt(match[3]!) / 100;
+
+  const hue2rgb = (p: number, q: number, t: number) => {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const r = Math.round(hue2rgb(p, q, h + 1 / 3) * 255);
+  const g = Math.round(hue2rgb(p, q, h) * 255);
+  const b = Math.round(hue2rgb(p, q, h - 1 / 3) * 255);
+
+  return `${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+
+function truncatePrompt(text: string, maxLen: number): string {
+  const clean = text.replace(/[^a-zA-Z0-9 .,!?-]/g, "");
+  if (clean.length <= maxLen) return clean;
+  return `${clean.slice(0, maxLen - 3)}...`;
+}
+
+export async function generatePlaceholder(
+  options: PlaceholderOptions,
+): Promise<PlaceholderResult> {
+  const { type, prompt, duration = 3, width = 1080, height = 1920 } = options;
+
+  const color = promptToColor(prompt);
+  const hexColor = hslToHex(color);
+  const labelFontSize = Math.floor(Math.min(width, height) / 20);
+  const promptFontSize = Math.floor(Math.min(width, height) / 35);
+  const maxChars = Math.floor((width * 0.7) / (promptFontSize * 0.5));
+  const typeLabel = type.toUpperCase();
+  const promptText = truncatePrompt(prompt, maxChars);
+
+  const ext = type === "audio" ? "mp3" : type === "image" ? "png" : "mp4";
+  const outputPath = join(
+    tmpdir(),
+    `placeholder_${Date.now()}_${Math.random().toString(36).slice(2)}.${ext}`,
+  );
+
+  try {
+    if (type === "audio") {
+      await $`ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t ${duration} -c:a libmp3lame ${outputPath}`.quiet();
+    } else if (type === "image") {
+      const colorInput = `color=c=0x${hexColor}:s=${width}x${height}:d=1`;
+      const labelY = `(h/2)-${labelFontSize}`;
+      const promptY = `(h/2)+${Math.floor(labelFontSize * 0.5)}`;
+      const drawLabel = `drawtext=text='${typeLabel}':fontcolor=white:fontsize=${labelFontSize}:x=(w-text_w)/2:y=${labelY}`;
+      const drawPrompt = `drawtext=text='${promptText}':fontcolor=white@0.7:fontsize=${promptFontSize}:x=(w-text_w)/2:y=${promptY}`;
+      await $`ffmpeg -y -f lavfi -i ${colorInput} -vf ${drawLabel},${drawPrompt} -frames:v 1 -update 1 ${outputPath}`.quiet();
+    } else {
+      const colorInput = `color=c=0x${hexColor}:s=${width}x${height}:d=${duration}:r=30`;
+      const labelY = `(h/2)-${labelFontSize}`;
+      const promptY = `(h/2)+${Math.floor(labelFontSize * 0.5)}`;
+      const drawLabel = `drawtext=text='${typeLabel}':fontcolor=white:fontsize=${labelFontSize}:x=(w-text_w)/2:y=${labelY}`;
+      const drawPrompt = `drawtext=text='${promptText}':fontcolor=white@0.7:fontsize=${promptFontSize}:x=(w-text_w)/2:y=${promptY}`;
+      await $`ffmpeg -y -f lavfi -i ${colorInput} -vf ${drawLabel},${drawPrompt} -c:v libx264 -preset ultrafast -pix_fmt yuv420p ${outputPath}`.quiet();
+    }
+
+    const data = await Bun.file(outputPath).bytes();
+    await unlink(outputPath).catch(() => {});
+    return { data: new Uint8Array(data), placeholder: true };
+  } catch (e) {
+    await unlink(outputPath).catch(() => {});
+    throw e;
+  }
+}

package/src/ai-sdk/middleware/wrap-image-model.ts

@@ -0,0 +1,86 @@
+import type {
+  ImageModelV3,
+  ImageModelV3CallOptions,
+  ImageModelV3Middleware,
+} from "@ai-sdk/provider";
+import { wrapImageModel } from "ai";
+import { generatePlaceholder } from "./placeholder";
+import type { RenderMode } from "./wrap-video-model";
+
+export interface ImagePlaceholderFallbackOptions {
+  mode: RenderMode;
+  onFallback?: (error: Error, prompt: string) => void;
+}
+
+export function imagePlaceholderFallbackMiddleware(
+  options: ImagePlaceholderFallbackOptions,
+): ImageModelV3Middleware {
+  const { mode, onFallback } = options;
+
+  return {
+    specificationVersion: "v3",
+    wrapGenerate: async ({ doGenerate, params, model }) => {
+      const createPlaceholderResult = async () => {
+        const [width, height] = (params.size?.split("x").map(Number) ?? [
+          1024, 1024,
+        ]) as [number, number];
+        const prompt =
+          typeof params.prompt === "string"
+            ? params.prompt
+            : ((params.prompt as { text?: string } | undefined)?.text ??
+              "placeholder");
+
+        const placeholder = await generatePlaceholder({
+          type: "image",
+          prompt,
+          width,
+          height,
+        });
+
+        return {
+          images: [placeholder.data],
+          warnings: [
+            {
+              type: "other" as const,
+              message: "placeholder: provider skipped or failed",
+            },
+          ],
+          response: {
+            timestamp: new Date(),
+            modelId: model.modelId,
+            headers: undefined,
+          },
+        };
+      };
+
+      if (mode === "preview") {
+        return createPlaceholderResult();
+      }
+
+      try {
+        return await doGenerate();
+      } catch (e) {
+        if (mode === "strict") throw e;
+
+        const error = e instanceof Error ? e : new Error(String(e));
+        const promptText =
+          typeof params.prompt === "string"
+            ? params.prompt
+            : ((params.prompt as { text?: string } | undefined)?.text ??
+              "placeholder");
+        onFallback?.(error, promptText);
+        return createPlaceholderResult();
+      }
+    },
+  };
+}
+
+export function withImagePlaceholderFallback(
+  model: ImageModelV3,
+  options: ImagePlaceholderFallbackOptions,
+): ImageModelV3 {
+  return wrapImageModel({
+    model,
+    middleware: imagePlaceholderFallbackMiddleware(options),
+  });
+}

package/src/ai-sdk/middleware/wrap-music-model.ts

@@ -0,0 +1,108 @@
+import type { MusicModelV3, MusicModelV3CallOptions } from "../music-model";
+import { generatePlaceholder } from "./placeholder";
+import type { RenderMode } from "./wrap-video-model";
+
+export interface MusicModelMiddleware {
+  transformParams?: (options: {
+    params: MusicModelV3CallOptions;
+    model: MusicModelV3;
+  }) => PromiseLike<MusicModelV3CallOptions> | MusicModelV3CallOptions;
+
+  wrapGenerate?: (options: {
+    doGenerate: () => PromiseLike<
+      Awaited<ReturnType<MusicModelV3["doGenerate"]>>
+    >;
+    params: MusicModelV3CallOptions;
+    model: MusicModelV3;
+  }) => PromiseLike<Awaited<ReturnType<MusicModelV3["doGenerate"]>>>;
+}
+
+export function wrapMusicModel({
+  model,
+  middleware,
+}: {
+  model: MusicModelV3;
+  middleware: MusicModelMiddleware;
+}): MusicModelV3 {
+  const { transformParams, wrapGenerate } = middleware;
+
+  return {
+    specificationVersion: "v3",
+    provider: model.provider,
+    modelId: model.modelId,
+
+    async doGenerate(params: MusicModelV3CallOptions) {
+      const transformedParams = transformParams
+        ? await transformParams({ params, model })
+        : params;
+
+      const doGenerate = () => model.doGenerate(transformedParams);
+
+      return wrapGenerate
+        ? wrapGenerate({ doGenerate, params: transformedParams, model })
+        : doGenerate();
+    },
+  };
+}
+
+export interface MusicPlaceholderFallbackOptions {
+  mode: RenderMode;
+  onFallback?: (error: Error, prompt: string) => void;
+}
+
+export function musicPlaceholderFallbackMiddleware(
+  options: MusicPlaceholderFallbackOptions,
+): MusicModelMiddleware {
+  const { mode, onFallback } = options;
+
+  return {
+    wrapGenerate: async ({ doGenerate, params, model }) => {
+      const createPlaceholderResult = async () => {
+        const placeholder = await generatePlaceholder({
+          type: "audio",
+          prompt: params.prompt,
+          duration: params.duration ?? 10,
+        });
+
+        return {
+          audio: placeholder.data,
+          warnings: [
+            {
+              type: "other" as const,
+              message: "placeholder: provider skipped or failed",
+            },
+          ],
+          response: {
+            timestamp: new Date(),
+            modelId: model.modelId,
+            headers: undefined,
+          },
+        };
+      };
+
+      if (mode === "preview") {
+        return createPlaceholderResult();
+      }
+
+      try {
+        return await doGenerate();
+      } catch (e) {
+        if (mode === "strict") throw e;
+
+        const error = e instanceof Error ? e : new Error(String(e));
+        onFallback?.(error, params.prompt);
+        return createPlaceholderResult();
+      }
+    },
+  };
+}
+
+export function withMusicPlaceholderFallback(
+  model: MusicModelV3,
+  options: MusicPlaceholderFallbackOptions,
+): MusicModelV3 {
+  return wrapMusicModel({
+    model,
+    middleware: musicPlaceholderFallbackMiddleware(options),
+  });
+}

package/src/ai-sdk/middleware/wrap-video-model.ts

@@ -0,0 +1,115 @@
+import type { VideoModelV3, VideoModelV3CallOptions } from "../video-model";
+import { generatePlaceholder } from "./placeholder";
+
+export type RenderMode = "strict" | "default" | "preview";
+
+export interface VideoModelMiddleware {
+  transformParams?: (options: {
+    params: VideoModelV3CallOptions;
+    model: VideoModelV3;
+  }) => PromiseLike<VideoModelV3CallOptions> | VideoModelV3CallOptions;
+
+  wrapGenerate?: (options: {
+    doGenerate: () => PromiseLike<
+      Awaited<ReturnType<VideoModelV3["doGenerate"]>>
+    >;
+    params: VideoModelV3CallOptions;
+    model: VideoModelV3;
+  }) => PromiseLike<Awaited<ReturnType<VideoModelV3["doGenerate"]>>>;
+}
+
+export function wrapVideoModel({
+  model,
+  middleware,
+}: {
+  model: VideoModelV3;
+  middleware: VideoModelMiddleware;
+}): VideoModelV3 {
+  const { transformParams, wrapGenerate } = middleware;
+
+  return {
+    specificationVersion: "v3",
+    provider: model.provider,
+    modelId: model.modelId,
+    maxVideosPerCall: model.maxVideosPerCall,
+
+    async doGenerate(params: VideoModelV3CallOptions) {
+      const transformedParams = transformParams
+        ? await transformParams({ params, model })
+        : params;
+
+      const doGenerate = () => model.doGenerate(transformedParams);
+
+      return wrapGenerate
+        ? wrapGenerate({ doGenerate, params: transformedParams, model })
+        : doGenerate();
+    },
+  };
+}
+
+export interface PlaceholderFallbackOptions {
+  mode: RenderMode;
+  onFallback?: (error: Error, prompt: string) => void;
+}
+
+export function placeholderFallbackMiddleware(
+  options: PlaceholderFallbackOptions,
+): VideoModelMiddleware {
+  const { mode, onFallback } = options;
+
+  return {
+    wrapGenerate: async ({ doGenerate, params, model }) => {
+      const createPlaceholderResult = async () => {
+        const [width, height] = (params.resolution?.split("x").map(Number) ?? [
+          1080, 1920,
+        ]) as [number, number];
+        const placeholder = await generatePlaceholder({
+          type: "video",
+          prompt: params.prompt,
+          duration: params.duration ?? 3,
+          width,
+          height,
+        });
+
+        return {
+          videos: [placeholder.data],
+          warnings: [
+            {
+              type: "other" as const,
+              message: "placeholder: provider skipped or failed",
+            },
+          ],
+          response: {
+            timestamp: new Date(),
+            modelId: model.modelId,
+            headers: undefined,
+          },
+        };
+      };
+
+      if (mode === "preview") {
+        return createPlaceholderResult();
+      }
+
+      try {
+        return await doGenerate();
+      } catch (e) {
+        if (mode === "strict") throw e;
+
+        const error = e instanceof Error ? e : new Error(String(e));
+        onFallback?.(error, params.prompt);
+        return createPlaceholderResult();
+      }
+    },
+  };
+}
+
+export function withPlaceholderFallback(
+  model: VideoModelV3,
+  options: PlaceholderFallbackOptions,
+): VideoModelV3 {
+  return wrapVideoModel({
+    model,
+    middleware: placeholderFallbackMiddleware(options),
+  });
+}

package/src/ai-sdk/providers/{elevenlabs-provider.ts → elevenlabs.ts}

@@ -196,8 +196,16 @@ export function createElevenLabs(
   };
 }
 
-export const elevenlabs_provider = createElevenLabs();
-export { elevenlabs_provider as elevenlabs, VOICES };
+let _elevenlabs: ElevenLabsProvider | undefined;
+export const elevenlabs = new Proxy({} as ElevenLabsProvider, {
+  get(_, prop) {
+    if (!_elevenlabs) {
+      _elevenlabs = createElevenLabs();
+    }
+    return _elevenlabs[prop as keyof ElevenLabsProvider];
+  },
+});
+export { VOICES };
 
 export interface GenerateMusicOptions {
   prompt: string;

package/src/cli/commands/index.ts

@@ -1,6 +1,7 @@
 export { findCmd, showFindHelp } from "./find.tsx";
 export { helpCmd, showHelp } from "./help.tsx";
 export { listCmd, showListHelp } from "./list.tsx";
-export { renderCmd } from "./render.tsx";
+export { renderCmd } from "./render.ts";
 export { runCmd, showRunHelp, showTargetHelp } from "./run.tsx";
+export { studioCmd } from "./studio.ts";
 export { showWhichHelp, whichCmd } from "./which.tsx";

package/src/cli/commands/render.ts

@@ -0,0 +1,136 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { defineCommand } from "citty";
+import { render } from "../../react/render";
+import type { RenderMode, VargElement } from "../../react/types";
+
+const AUTO_IMPORTS = `/** @jsxImportSource vargai */
+import { Animate, Captions, Clip, Image, Music, Overlay, Packshot, Render, Slider, Speech, Split, Subtitle, Swipe, TalkingHead, Title, Video, Grid, SplitLayout } from "vargai/react";
+import { fal, elevenlabs, replicate } from "vargai/ai";
+`;
+
+async function loadComponent(filePath: string): Promise<VargElement> {
+  const resolvedPath = resolve(filePath);
+  const source = await Bun.file(resolvedPath).text();
+
+  const hasImports =
+    source.includes("from 'vargai") ||
+    source.includes('from "vargai') ||
+    source.includes("from '@vargai") ||
+    source.includes('from "@vargai');
+
+  const hasJsxPragma =
+    source.includes("@jsxImportSource") || source.includes("@jsx ");
+
+  if (hasImports && hasJsxPragma) {
+    const mod = await import(resolvedPath);
+    return mod.default;
+  }
+
+  const pkgDir = new URL("../../..", import.meta.url).pathname;
+  const tmpDir = `${pkgDir}/.cache/varg-render`;
+  if (!existsSync(tmpDir)) {
+    mkdirSync(tmpDir, { recursive: true });
+  }
+
+  const prepended = hasImports
+    ? `/** @jsxImportSource vargai */\n`
+    : AUTO_IMPORTS;
+  const tmpFile = `${tmpDir}/${Date.now()}.tsx`;
+  await Bun.write(tmpFile, prepended + source);
+
+  try {
+    const mod = await import(tmpFile);
+    return mod.default;
+  } finally {
+    (await Bun.file(tmpFile).exists()) && (await Bun.write(tmpFile, ""));
+  }
+}
+
+export const renderCmd = defineCommand({
+  meta: {
+    name: "render",
+    description: "render a react component to video",
+  },
+  args: {
+    file: {
+      type: "positional",
+      description: "component file (.tsx)",
+      required: true,
+    },
+    output: {
+      type: "string",
+      alias: "o",
+      description: "output path",
+    },
+    cache: {
+      type: "string",
+      alias: "c",
+      description: "cache directory",
+      default: ".cache/ai",
+    },
+    quiet: {
+      type: "boolean",
+      alias: "q",
+      description: "minimal output",
+      default: false,
+    },
+    strict: {
+      type: "boolean",
+      description: "fail on provider errors (no fallback)",
+      default: false,
+    },
+    preview: {
+      type: "boolean",
+      description: "skip all generation, use placeholders only",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const file = args.file as string;
+
+    if (!file) {
+      console.error("usage: varg render <component.tsx> [-o output.mp4]");
+      process.exit(1);
+    }
+
+    const component = await loadComponent(file);
+
+    if (!component || component.type !== "render") {
+      console.error("error: default export must be a <Render> element");
+      process.exit(1);
+    }
+
+    const basename = file
+      .replace(/\.tsx?$/, "")
+      .split("/")
+      .pop();
+    const outputPath = args.output ?? `output/${basename}.mp4`;
+
+    const mode: RenderMode = args.strict
+      ? "strict"
+      : args.preview
+        ? "preview"
+        : "default";
+
+    if (!args.quiet) {
+      const modeLabel =
+        mode === "preview"
+          ? " (preview)"
+          : mode === "strict"
+            ? " (strict)"
+            : "";
+      console.log(`rendering ${file} → ${outputPath}${modeLabel}`);
+    }
+
+    const buffer = await render(component, {
+      output: outputPath,
+      cache: args.cache,
+      mode,
+    });
+
+    if (!args.quiet) {
+      console.log(`done! ${buffer.byteLength} bytes → ${outputPath}`);
+    }
+  },
+});

package/src/cli/commands/studio.ts

@@ -0,0 +1,47 @@
+import { resolve } from "node:path";
+import { defineCommand } from "citty";
+import { createStudioServer } from "../../studio/server";
+
+export const studioCmd = defineCommand({
+  meta: {
+    name: "studio",
+    description: "launch varg studio - visual editor for workflows",
+  },
+  args: {
+    file: {
+      type: "positional",
+      description: "initial file to open",
+      required: false,
+    },
+    cache: {
+      type: "string",
+      description: "cache directory",
+      default: ".cache/ai",
+    },
+    port: {
+      type: "string",
+      description: "port to run on",
+      default: "8282",
+    },
+  },
+  run: async ({ args }) => {
+    const initialFile = args.file ? resolve(args.file) : undefined;
+    const cacheDir = args.cache;
+    const port = Number.parseInt(args.port, 10);
+
+    console.log("varg studio starting...");
+    console.log(`cache folder: ${cacheDir}`);
+    if (initialFile) {
+      console.log(`initial file: ${initialFile}`);
+    }
+
+    const server = createStudioServer({ cacheDir, initialFile, port });
+
+    console.log(`\nopen http://localhost:${server.port}`);
+    console.log("  /editor - code editor");
+    console.log("  /cache  - cache viewer");
+
+    // Keep process alive
+    await new Promise(() => {});
+  },
+});

package/src/cli/index.ts

@@ -23,6 +23,7 @@ import {
   showRunHelp,
   showTargetHelp,
   showWhichHelp,
+  studioCmd,
   whichCmd,
 } from "./commands";
 
@@ -92,15 +93,18 @@ if (hasHelp) {
   }
 }
 
+const pkg = await import("../../package.json");
+
 const main = defineCommand({
   meta: {
     name: "varg",
-    version: "0.3.0",
+    version: pkg.version,
     description: "ai video infrastructure from your terminal",
   },
   subCommands: {
     run: runCmd,
     render: renderCmd,
+    studio: studioCmd,
     list: listCmd,
     ls: listCmd,
     find: findCmd,

package/src/react/examples/branching.tsx

@@ -1,5 +1,5 @@
-import { elevenlabs } from "../../ai-sdk/providers/elevenlabs-provider";
-import { fal } from "../../ai-sdk/providers/fal-provider";
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs";
+import { fal } from "../../ai-sdk/providers/fal";
 import { Animate, Clip, Image, Render, Speech, Title } from "..";
 
 // Non-linear tree: multiple clips with independent branches

package/src/react/examples/captions-demo.tsx

@@ -1,4 +1,4 @@
-import { elevenlabs } from "../../ai-sdk/providers/elevenlabs-provider";
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs";
 import { Captions, Clip, Image, Render, render, Speech } from "..";
 
 async function main() {

package/src/react/examples/character-video.tsx

@@ -1,5 +1,5 @@
-import { elevenlabs } from "../../ai-sdk/providers/elevenlabs-provider";
-import { fal } from "../../ai-sdk/providers/fal-provider";
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs";
+import { fal } from "../../ai-sdk/providers/fal";
 import { Animate, Clip, Image, Music, Render, render } from "..";
 
 const MADI_REF =

package/src/react/examples/grid.tsx

@@ -1,4 +1,4 @@
-import { fal } from "../../ai-sdk/providers/fal-provider";
+import { fal } from "../../ai-sdk/providers/fal";
 import { Clip, Grid, Image, Render, render, Title } from "..";
 
 const CHARACTER_PROMPTS = [

package/src/react/examples/madi.tsx

@@ -1,5 +1,5 @@
-import { elevenlabs } from "../../ai-sdk/providers/elevenlabs-provider";
-import { fal } from "../../ai-sdk/providers/fal-provider";
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs";
+import { fal } from "../../ai-sdk/providers/fal";
 import { Animate, Clip, Image, Music, Render } from "..";
 
 const MADI_REF =

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

@@ -1,4 +1,4 @@
-import { elevenlabs } from "../../ai-sdk/providers/elevenlabs-provider";
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs";
 import { Clip, Image, Music, Render, render } from "..";
 
 async function main() {

package/src/react/examples/orange-portrait.tsx

@@ -1,4 +1,4 @@
-import { fal } from "../../ai-sdk/providers/fal-provider";
+import { fal } from "../../ai-sdk/providers/fal";
 import { Clip, Image, Render, Video } from "..";
 
 // character: young woman, short dark brown bob with wispy bangs, oval face, fair skin,

package/src/react/examples/split.tsx

@@ -1,4 +1,4 @@
-import { fal } from "../../ai-sdk/providers/fal-provider";
+import { fal } from "../../ai-sdk/providers/fal";
 import { Clip, Image, Render, render, SplitLayout as Split, Title } from "..";
 
 async function main() {

package/src/react/examples/video-grid.tsx

@@ -1,4 +1,4 @@
-import { fal } from "../../ai-sdk/providers/fal-provider";
+import { fal } from "../../ai-sdk/providers/fal";
 import { Clip, Grid, Render, render, Title, Video } from "..";
 
 async function main() {

package/src/react/react.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { existsSync, unlinkSync } from "node:fs";
-import { fal } from "../ai-sdk/providers/fal-provider";
+import { fal } from "../ai-sdk/providers/fal";
 import {
   Animate,
   Captions,

package/src/react/renderers/clip.ts

@@ -32,9 +32,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 +92,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,
@@ -220,7 +227,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/render.ts

@@ -1,7 +1,12 @@
-import { generateImage } from "ai";
+import { generateImage, wrapImageModel } from "ai";
 import { withCache } from "../../ai-sdk/cache";
 import { fileCache } from "../../ai-sdk/file-cache";
 import { generateVideo } from "../../ai-sdk/generate-video";
+import {
+  imagePlaceholderFallbackMiddleware,
+  placeholderFallbackMiddleware,
+  wrapVideoModel,
+} from "../../ai-sdk/middleware";
 import { editly } from "../../ai-sdk/providers/editly";
 import type {
   AudioTrack,
@@ -14,6 +19,7 @@ import type {
   ClipProps,
   MusicProps,
   OverlayProps,
+  RenderMode,
   RenderOptions,
   RenderProps,
   SpeechProps,
@@ -48,17 +54,75 @@ export async function renderRoot(
   const props = element.props as RenderProps;
   const progress = createProgressTracker(options.quiet ?? false);
 
+  const mode: RenderMode = options.mode ?? "default";
+  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 wrapGenerateImage: typeof generateImage = async (opts) => {
+    if (
+      typeof opts.model === "string" ||
+      opts.model.specificationVersion !== "v3"
+    ) {
+      return generateImage(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;
+  };
+
+  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;
+  };
+
   const ctx: RenderContext = {
     width: props.width ?? 1920,
     height: props.height ?? 1080,
     fps: props.fps ?? 30,
     cache: options.cache ? fileCache({ dir: options.cache }) : undefined,
     generateImage: options.cache
-      ? withCache(generateImage, { storage: fileCache({ dir: options.cache }) })
-      : generateImage,
+      ? withCache(wrapGenerateImage, {
+          storage: fileCache({ dir: options.cache }),
+        })
+      : wrapGenerateImage,
     generateVideo: options.cache
-      ? withCache(generateVideo, { storage: fileCache({ dir: options.cache }) })
-      : generateVideo,
+      ? withCache(wrapGenerateVideo, {
+          storage: fileCache({ dir: options.cache }),
+        })
+      : wrapGenerateVideo,
     tempFiles: [],
     progress,
     pending: new Map(),
@@ -238,6 +302,18 @@ 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`,
+      );
+    }
+  }
+
   const result = await Bun.file(finalOutPath).arrayBuffer();
   return new Uint8Array(result);
 }

package/src/react/types.ts

@@ -75,6 +75,10 @@ export interface RenderProps extends BaseProps {
 export interface ClipProps extends BaseProps {
   duration?: number | "auto";
   transition?: TransitionOptions;
+  /** Start trim point in seconds (e.g., 1 to start from 1 second) */
+  cutFrom?: number;
+  /** End trim point in seconds (e.g., 3 to end at 3 seconds) */
+  cutTo?: number;
   children?: VargNode;
 }
 
@@ -206,10 +210,13 @@ export interface PackshotProps extends BaseProps {
   duration?: number;
 }
 
+export type RenderMode = "strict" | "default" | "preview";
+
 export interface RenderOptions {
   output?: string;
   cache?: string;
   quiet?: boolean;
+  mode?: RenderMode;
 }
 
 export interface ElementPropsMap {

package/tsconfig.json

@@ -6,7 +6,7 @@
     "module": "ESNext",
     "moduleDetection": "force",
     "jsx": "react-jsx",
-    "jsxImportSource": "@/react/runtime",
+    "jsxImportSource": "vargai",
     "allowJs": true,
 
     // Bundler mode
@@ -30,7 +30,9 @@
     // Base URL for imports
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": ["./src/*"],
+      "vargai/jsx-runtime": ["./src/react/runtime/jsx-runtime.ts"],
+      "vargai/jsx-dev-runtime": ["./src/react/runtime/jsx-dev-runtime.ts"]
     }
   },
   "include": ["src/**/*"],

package/src/cli/commands/render.tsx

@@ -1,71 +0,0 @@
-import { defineCommand } from "citty";
-import { render } from "../../react/render";
-import type { VargElement } from "../../react/types";
-
-export const renderCmd = defineCommand({
-  meta: {
-    name: "render",
-    description: "render a react component to video",
-  },
-  args: {
-    file: {
-      type: "positional",
-      description: "component file (.tsx)",
-      required: true,
-    },
-    output: {
-      type: "string",
-      alias: "o",
-      description: "output path",
-    },
-    cache: {
-      type: "string",
-      alias: "c",
-      description: "cache directory",
-      default: ".cache/ai",
-    },
-    quiet: {
-      type: "boolean",
-      alias: "q",
-      description: "minimal output",
-      default: false,
-    },
-  },
-  async run({ args }) {
-    const file = args.file as string;
-
-    if (!file) {
-      console.error("usage: varg render <component.tsx> [-o output.mp4]");
-      process.exit(1);
-    }
-
-    const resolvedPath = Bun.resolveSync(file, process.cwd());
-    const mod = await import(resolvedPath);
-    const component: VargElement = mod.default;
-
-    if (!component || component.type !== "render") {
-      console.error("error: default export must be a <Render> element");
-      process.exit(1);
-    }
-
-    const outputPath =
-      args.output ??
-      `output/${file
-        .replace(/\.tsx?$/, "")
-        .split("/")
-        .pop()}.mp4`;
-
-    if (!args.quiet) {
-      console.log(`rendering ${file} → ${outputPath}`);
-    }
-
-    const buffer = await render(component, {
-      output: outputPath,
-      cache: args.cache,
-    });
-
-    if (!args.quiet) {
-      console.log(`done! ${buffer.byteLength} bytes → ${outputPath}`);
-    }
-  },
-});

package/src/react/cli.ts

@@ -1,52 +0,0 @@
-#!/usr/bin/env bun
-
-import { parseArgs } from "node:util";
-import { render } from "./render";
-import type { VargElement } from "./types";
-
-const { values, positionals } = parseArgs({
-  args: Bun.argv.slice(2),
-  options: {
-    output: { type: "string", short: "o" },
-    cache: { type: "string", short: "c", default: ".cache/ai" },
-    quiet: { type: "boolean", short: "q", default: false },
-  },
-  allowPositionals: true,
-});
-
-const [file] = positionals;
-
-if (!file) {
-  console.error("usage: bun react/cli.ts <component.tsx> [-o output.mp4]");
-  process.exit(1);
-}
-
-const resolvedPath = Bun.resolveSync(file, process.cwd());
-const mod = await import(resolvedPath);
-const component: VargElement = mod.default;
-
-if (!component || component.type !== "render") {
-  console.error("error: default export must be a <Render> element");
-  process.exit(1);
-}
-
-const outputPath =
-  values.output ??
-  `output/${file
-    .replace(/\.tsx?$/, "")
-    .split("/")
-    .pop()}.mp4`;
-
-if (!values.quiet) {
-  console.log(`rendering ${file} → ${outputPath}`);
-}
-
-const buffer = await render(component, {
-  output: outputPath,
-  cache: values.cache,
-  quiet: values.quiet,
-});
-
-if (!values.quiet) {
-  console.log(`done! ${buffer.byteLength} bytes → ${outputPath}`);
-}