vargai 0.4.0-alpha.1 → 0.4.0-alpha2

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,8 @@
     "lint-staged": "^16.2.7"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5",
+    "ai": "^6.0.0"
   },
   "dependencies": {
     "@ai-sdk/fal": "^1.0.23",
@@ -62,7 +63,7 @@
     "replicate": "^1.4.0",
     "zod": "^4.2.1"
   },
-  "version": "0.4.0-alpha.1",
+  "version": "0.4.0-alpha2",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.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/cli/commands/render.tsx

@@ -1,6 +1,6 @@
 import { defineCommand } from "citty";
 import { render } from "../../react/render";
-import type { VargElement } from "../../react/types";
+import type { RenderMode, VargElement } from "../../react/types";
 
 export const renderCmd = defineCommand({
   meta: {
@@ -30,6 +30,16 @@ export const renderCmd = defineCommand({
       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;
@@ -55,13 +65,26 @@ export const renderCmd = defineCommand({
         .split("/")
         .pop()}.mp4`;
 
+    const mode: RenderMode = args.strict
+      ? "strict"
+      : args.preview
+        ? "preview"
+        : "default";
+
     if (!args.quiet) {
-      console.log(`rendering ${file} → ${outputPath}`);
+      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) {

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/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

@@ -206,10 +206,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 {