vargai 0.4.0-alpha51 → 0.4.0-alpha53

package/CLAUDE.md

@@ -123,3 +123,13 @@ bun --hot ./index.ts
 ```
 
 For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.
+
+## Cache Policy
+
+**NEVER clear or delete the user's cache**, even when debugging.
+
+- Video/image generation costs real money ($0.05–$0.50+ per generation) and takes 60–180 seconds
+- The cache is the user's asset — treat it as production data, not disposable debug state
+- If you need to regenerate, modify the prompt slightly or use a different cache key
+- If cache must be cleared, always ask the user explicitly first
+- Suggest `--no-cache` flag for one-off re-renders instead of deleting cached files

package/package.json

@@ -69,7 +69,8 @@
     "sharp": "^0.34.5",
     "zod": "^4.2.1"
   },
-  "version": "0.4.0-alpha51",
+  "sideEffects": false,
+  "version": "0.4.0-alpha53",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",
@@ -80,6 +81,7 @@
     "./studio": "./src/studio/index.ts",
     "./jsx-runtime": "./src/react/runtime/jsx-runtime.ts",
     "./jsx-dev-runtime": "./src/react/runtime/jsx-dev-runtime.ts",
-    "./editly": "./src/ai-sdk/providers/editly/index.ts"
+    "./editly": "./src/ai-sdk/providers/editly/index.ts",
+    "./file": "./src/ai-sdk/file.ts"
   }
 }

package/src/ai-sdk/cache.ts

@@ -11,7 +11,10 @@ export interface WithCacheOptions {
 
 type CacheKeyDeps = (string | number | boolean | null | undefined)[];
 
-type WithCacheKey<T> = Omit<T, "cacheKey"> & { cacheKey?: CacheKeyDeps };
+type WithCacheKey<T> = Omit<T, "cacheKey" | "skipCacheWrite"> & {
+  cacheKey?: CacheKeyDeps;
+  skipCacheWrite?: boolean;
+};
 
 type CachedFn<T, R> = (options: WithCacheKey<T>) => Promise<R>;
 
@@ -60,7 +63,8 @@ function parseTTL(ttl: number | string | undefined): number | undefined {
   }
 }
 
-function depsToKey(prefix: string, deps: CacheKeyDeps): string {
+/** Build a cache key string from a prefix and an array of dependencies. */
+export function depsToKey(prefix: string, deps: CacheKeyDeps): string {
   const depsStr = deps.map((d) => String(d ?? "")).join(":");
   return prefix ? `${prefix}:${depsStr}` : depsStr;
 }
@@ -116,7 +120,7 @@ export function withCache<T extends object, R>(
   const ttl = parseTTL(options.ttl ?? DEFAULT_TTL);
   const prefix = fn.name || "anonymous";
   return async (opts: WithCacheKey<T>): Promise<R> => {
-    const { cacheKey, ...rest } = opts;
+    const { cacheKey, skipCacheWrite, ...rest } = opts;
 
     if (!cacheKey) {
       return fn(rest as T);
@@ -128,8 +132,10 @@ export function withCache<T extends object, R>(
       return cached as R;
     }
     const result = await fn(rest as T);
-    const flattened = flatten(result);
-    await storage.set(key, flattened, ttl);
+    if (!skipCacheWrite) {
+      const flattened = flatten(result);
+      await storage.set(key, flattened, ttl);
+    }
 
     return result;
   };

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

@@ -1,7 +1,6 @@
 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";
@@ -82,6 +81,8 @@ export async function generatePlaceholder(
     `placeholder_${Date.now()}_${Math.random().toString(36).slice(2)}.${ext}`,
   );
 
+  const { $ } = await import("bun");
+
   try {
     if (type === "audio") {
       await $`ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t ${duration} -c:a libmp3lame ${outputPath}`.quiet();

package/src/react/renderers/render.ts

@@ -1,3 +1,4 @@
+import type { ImageModelV3 } from "@ai-sdk/provider";
 import { generateImage, wrapImageModel } from "ai";
 import { type CacheStorage, withCache } from "../../ai-sdk/cache";
 import type { File, File as VargFile } from "../../ai-sdk/file";
@@ -8,6 +9,7 @@ import {
   placeholderFallbackMiddleware,
   wrapVideoModel,
 } from "../../ai-sdk/middleware";
+
 import { editly, localBackend } from "../../ai-sdk/providers/editly";
 import type {
   AudioTrack,
@@ -58,6 +60,28 @@ function resolveCacheStorage(
   return cache;
 }
 
+function toImageModelV3(
+  model: Parameters<typeof generateImage>[0]["model"],
+): ImageModelV3 {
+  if (typeof model === "object" && model.specificationVersion === "v3") {
+    return model;
+  }
+  // for string IDs and v2 models, create a shell that satisfies the type.
+  // in preview mode the middleware intercepts before doGenerate is called.
+  const modelId = typeof model === "string" ? model : model.modelId;
+  return {
+    specificationVersion: "v3",
+    provider: "placeholder",
+    modelId,
+    maxImagesPerCall: 1,
+    doGenerate: async () => {
+      throw new Error(
+        `toImageModelV3 shell: doGenerate should not be called in preview mode (model: ${modelId})`,
+      );
+    },
+  };
+}
+
 export async function renderRoot(
   element: VargElement<"render">,
   options: RenderOptions,
@@ -84,23 +108,19 @@ export async function renderRoot(
     : generateVideo;
 
   const wrapGenerateImage: typeof generateImage = async (opts) => {
-    if (
-      typeof opts.model === "string" ||
-      opts.model.specificationVersion !== "v3"
-    ) {
-      return cachedGenerateImage(opts);
-    }
-
     if (mode === "preview") {
       trackPlaceholder("image");
-      const wrappedModel = wrapImageModel({
-        model: opts.model,
-        middleware: imagePlaceholderFallbackMiddleware({
-          mode: "preview",
-          onFallback: () => {},
+      return cachedGenerateImage({
+        ...opts,
+        model: wrapImageModel({
+          model: toImageModelV3(opts.model),
+          middleware: imagePlaceholderFallbackMiddleware({
+            mode: "preview",
+            onFallback: () => {},
+          }),
         }),
-      });
-      return generateImage({ ...opts, model: wrappedModel });
+        skipCacheWrite: true,
+      } as Parameters<typeof cachedGenerateImage>[0]);
     }
 
     return cachedGenerateImage(opts);
@@ -109,14 +129,17 @@ export async function renderRoot(
   const wrapGenerateVideo: typeof generateVideo = async (opts) => {
     if (mode === "preview") {
       trackPlaceholder("video");
-      const wrappedModel = wrapVideoModel({
-        model: opts.model,
-        middleware: placeholderFallbackMiddleware({
-          mode: "preview",
-          onFallback: () => {},
+      return cachedGenerateVideo({
+        ...opts,
+        model: wrapVideoModel({
+          model: opts.model,
+          middleware: placeholderFallbackMiddleware({
+            mode: "preview",
+            onFallback: () => {},
+          }),
         }),
-      });
-      return generateVideo({ ...opts, model: wrappedModel });
+        skipCacheWrite: true,
+      } as Parameters<typeof cachedGenerateVideo>[0]);
     }
 
     return cachedGenerateVideo(opts);