vargai 0.4.0-alpha4 → 0.4.0-alpha40

package/src/react/layouts/slot.tsx

@@ -0,0 +1,85 @@
+import type {
+  CropPosition,
+  ResizeMode,
+} from "../../ai-sdk/providers/editly/types";
+import type { VargElement } from "../types";
+
+type SlotFit = "cover" | "contain" | "contain-blur" | "fill";
+
+type SlotPosition =
+  | "center"
+  | "top"
+  | "bottom"
+  | "left"
+  | "right"
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right";
+
+interface SlotProps {
+  class?: string;
+  fit?: SlotFit;
+  position?: SlotPosition;
+  children: VargElement;
+}
+
+interface ParsedSlotClass {
+  fit?: SlotFit;
+  position?: SlotPosition;
+}
+
+function parseSlotClass(classString?: string): ParsedSlotClass {
+  if (!classString) return {};
+  const result: ParsedSlotClass = {};
+
+  for (const cls of classString.trim().split(/\s+/)) {
+    if (cls === "fit-cover") result.fit = "cover";
+    else if (cls === "fit-contain") result.fit = "contain";
+    else if (cls === "fit-contain-blur") result.fit = "contain-blur";
+    else if (cls === "fit-fill") result.fit = "fill";
+    else if (cls === "pos-center") result.position = "center";
+    else if (cls === "pos-top") result.position = "top";
+    else if (cls === "pos-bottom") result.position = "bottom";
+    else if (cls === "pos-left") result.position = "left";
+    else if (cls === "pos-right") result.position = "right";
+    else if (cls === "pos-top-left") result.position = "top-left";
+    else if (cls === "pos-top-right") result.position = "top-right";
+    else if (cls === "pos-bottom-left") result.position = "bottom-left";
+    else if (cls === "pos-bottom-right") result.position = "bottom-right";
+  }
+  return result;
+}
+
+function slotFitToResize(fit: SlotFit): ResizeMode {
+  switch (fit) {
+    case "cover":
+      return "cover";
+    case "contain":
+      return "contain";
+    case "contain-blur":
+      return "contain-blur";
+    case "fill":
+      return "stretch";
+  }
+}
+
+export const Slot = ({
+  class: className,
+  fit,
+  position,
+  children,
+}: SlotProps) => {
+  const parsed = parseSlotClass(className);
+  const resolvedFit = fit ?? parsed.fit ?? "cover";
+  const resolvedPosition = position ?? parsed.position ?? "center";
+
+  return {
+    ...children,
+    props: {
+      ...children.props,
+      resize: slotFitToResize(resolvedFit),
+      cropPosition: resolvedPosition as CropPosition,
+    },
+  } as VargElement;
+};

package/src/react/layouts/split.tsx

@@ -18,3 +18,21 @@ export const SplitLayout = ({
     {right}
   </Grid>
 );
+
+export const Split = ({
+  direction = "horizontal",
+  children,
+}: {
+  direction?: "horizontal" | "vertical";
+  children: VargElement[];
+}) => {
+  if (children.length === 0) return null;
+  return (
+    <Grid
+      columns={direction === "horizontal" ? children.length : 1}
+      rows={direction === "vertical" ? children.length : 1}
+    >
+      {children}
+    </Grid>
+  );
+};

package/src/react/react.test.ts

@@ -1,8 +1,7 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, mock, 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", () => {
@@ -157,6 +157,55 @@ describe("varg-react render", () => {
 
     expect(render(root)).rejects.toThrow("model");
   });
+
+  test("parallel failures preserve successful results and report all errors", async () => {
+    let callCount = 0;
+    const mockModel = {
+      specificationVersion: "v3" as const,
+      provider: "mock",
+      modelId: "mock-model",
+      maxImagesPerCall: 1,
+      doGenerate: mock(async () => {
+        callCount++;
+        if (callCount === 2) {
+          throw new Error("Request Timeout");
+        }
+        return {
+          images: [new Uint8Array([0x89, 0x50, 0x4e, 0x47])],
+          warnings: [],
+          response: {
+            timestamp: new Date(),
+            modelId: "mock",
+            headers: undefined,
+          },
+        };
+      }),
+    };
+
+    const root = Render({
+      width: 720,
+      height: 720,
+      children: [
+        Clip({
+          duration: 1,
+          children: [Image({ prompt: "first", model: mockModel })],
+        }),
+        Clip({
+          duration: 1,
+          children: [Image({ prompt: "second", model: mockModel })],
+        }),
+        Clip({
+          duration: 1,
+          children: [Image({ prompt: "third", model: mockModel })],
+        }),
+      ],
+    });
+
+    const error = await render(root, { quiet: true }).catch((e) => e);
+    expect(error.message).toContain("1 of 3 clips failed");
+    expect(error.message).toContain("Request Timeout");
+    expect(callCount).toBe(3);
+  });
 });
 
 describe("layout renderers", () => {

package/src/react/renderers/burn-captions.ts

@@ -0,0 +1,95 @@
+import { localBackend } from "@/ai-sdk/providers/editly";
+import type {
+  FFmpegBackend,
+  FFmpegOutput,
+} from "../../ai-sdk/providers/editly/backends/types";
+import { uploadBuffer } from "../../providers/storage";
+
+/**
+ * Resolves an FFmpegOutput to a string path/URL, uploading local files if needed.
+ *
+ * - URL input → returns URL as-is
+ * - File input + shouldUpload=false → returns local path
+ * - File input + shouldUpload=true → uploads to storage, returns URL
+ */
+async function resolveInputPathMaybeUpload(
+  input: FFmpegOutput,
+  options: { shouldUpload: boolean },
+): Promise<string> {
+  if (input.type === "url") return input.url;
+  if (!options.shouldUpload) return input.path;
+
+  const buffer = await Bun.file(input.path).arrayBuffer();
+  return uploadBuffer(
+    buffer,
+    `tmp/${Date.now()}-${input.path.split("/").pop()}`,
+    "application/octet-stream",
+  );
+}
+
+export interface CaptionOverlayOptions {
+  video: FFmpegOutput;
+  assPath: string;
+  outputPath: string;
+  backend?: FFmpegBackend;
+  verbose?: boolean;
+}
+
+/**
+ * Burns ASS subtitle captions onto a video using FFmpeg.
+ *
+ * {@link burnCaptions} composites the subtitle file directly into the video frames,
+ * producing a new video with hardcoded captions. Supports both local and cloud
+ * FFmpeg backends - when using a cloud backend, input files are automatically
+ * uploaded to storage.
+ *
+ * @param options - Configuration for the caption burn operation
+ * @param options.video - Source video as {@link FFmpegOutput} (file path or URL)
+ * @param options.assPath - Path to the ASS subtitle file to burn
+ * @param options.outputPath - Destination path for the output video (defaults to "output.mp4")
+ * @param options.backend - Optional {@link FFmpegBackend} for cloud processing; uses local FFmpeg if omitted
+ * @param options.verbose - Enable verbose FFmpeg logging
+ *
+ * @returns Promise resolving to {@link FFmpegOutput} containing the path or URL of the captioned video
+ *
+ * @throws May throw if FFmpeg execution fails, input files are missing, or upload fails for cloud backends
+ *
+ * @example
+ * ```ts
+ * const result = await burnCaptions({
+ *   video: { type: "file", path: "input.mp4" },
+ *   assPath: "captions.ass",
+ *   outputPath: "output-with-captions.mp4",
+ * });
+ * ```
+ */
+export async function burnCaptions(
+  options: CaptionOverlayOptions,
+): Promise<FFmpegOutput> {
+  const { video, assPath, outputPath = "output.mp4", verbose } = options;
+  const captions: FFmpegOutput = { type: "file", path: assPath };
+
+  const isCloud = options.backend !== undefined;
+
+  const videoInput = await resolveInputPathMaybeUpload(video, {
+    shouldUpload: isCloud,
+  });
+  const assInput = await resolveInputPathMaybeUpload(captions, {
+    shouldUpload: isCloud,
+  });
+
+  const backend = options.backend ?? localBackend;
+
+  // FFmpeg filter syntax requires escaping backslashes and colons
+  const escapedAssPath = assInput.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
+
+  const result = await backend.run({
+    inputs: [videoInput, assInput],
+    videoFilter: `subtitles=${escapedAssPath}`,
+    outputArgs: ["-crf", "18", "-preset", "fast", "-c:a", "copy"],
+    outputPath,
+    verbose,
+  });
+
+  return result.output;
+}

package/src/react/renderers/cache.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ImageModelV3 } from "@ai-sdk/provider";
+import { withCache } from "../../ai-sdk/cache";
+import { fileCache } from "../../ai-sdk/file-cache";
+import type { VideoModelV3 } from "../../ai-sdk/video-model";
+import { Image, Video } from "../elements";
+import type { RenderContext } from "./context";
+import { renderImage } from "./image";
+import { renderVideo } from "./video";
+
+function makeTempDir(): string {
+  return mkdtempSync(join(tmpdir(), "varg-cache-test-"));
+}
+
+function cleanupTempDir(dir: string) {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+function createImageModel(): ImageModelV3 {
+  return {
+    specificationVersion: "v3",
+    provider: "test",
+    modelId: "test-image",
+    maxImagesPerCall: 1,
+    async doGenerate() {
+      return {
+        images: [new Uint8Array([1, 2, 3])],
+        warnings: [],
+        response: {
+          timestamp: new Date(),
+          modelId: "test-image",
+          headers: undefined,
+        },
+      };
+    },
+  };
+}
+
+function createVideoModel(): VideoModelV3 {
+  return {
+    specificationVersion: "v3",
+    provider: "test",
+    modelId: "test-video",
+    maxVideosPerCall: 1,
+    async doGenerate() {
+      return {
+        videos: [new Uint8Array([9, 9, 9])],
+        warnings: [],
+        response: {
+          timestamp: new Date(),
+          modelId: "test-video",
+          headers: undefined,
+        },
+      };
+    },
+  };
+}
+
+type GenerateImageOptions = Parameters<RenderContext["generateImage"]>[0];
+type GenerateVideoOptions = Parameters<RenderContext["generateVideo"]>[0];
+
+function createContext(
+  cacheDir: string,
+  counters: { imageCalls: number; videoCalls: number },
+): RenderContext {
+  const storage = fileCache({ dir: cacheDir });
+
+  const generateImage = withCache(async (_opts: GenerateImageOptions) => {
+    counters.imageCalls += 1;
+    return {
+      images: [
+        {
+          uint8Array: new Uint8Array([1, 2, 3]),
+          mimeType: "image/png",
+        },
+      ],
+      warnings: [],
+    };
+  });
+
+  const generateVideo = withCache(async (_opts: GenerateVideoOptions) => {
+    counters.videoCalls += 1;
+    const first = new Uint8Array([9, 9, 9]);
+    return {
+      video: { uint8Array: first, mimeType: "video/mp4" },
+      videos: [{ uint8Array: first, mimeType: "video/mp4" }],
+      warnings: [],
+    };
+  });
+
+  return {
+    width: 1080,
+    height: 1920,
+    fps: 30,
+    cache: storage,
+    generateImage: generateImage as unknown as RenderContext["generateImage"],
+    generateVideo: generateVideo as unknown as RenderContext["generateVideo"],
+    tempFiles: [],
+    pending: new Map(),
+  };
+}
+
+describe("render cache behavior", () => {
+  test("reuses cached video across separate contexts when only trim/layout differ", async () => {
+    const cacheDir = makeTempDir();
+    const counters = { imageCalls: 0, videoCalls: 0 };
+
+    const model = createVideoModel();
+    const imageModel = createImageModel();
+
+    const base = Video({
+      prompt: "walk forward",
+      model,
+      aspectRatio: "9:16",
+    });
+
+    const variant = Video({
+      prompt: "walk forward",
+      model,
+      aspectRatio: "9:16",
+      cutFrom: 0.5,
+      cutTo: 2.5,
+      left: "10%",
+      width: "80%",
+      keepAudio: true,
+      volume: 0.5,
+    });
+
+    try {
+      const ctx1 = createContext(cacheDir, counters);
+      await renderVideo(base, ctx1);
+
+      const ctx2 = createContext(cacheDir, counters);
+      await renderVideo(variant, ctx2);
+    } finally {
+      cleanupTempDir(cacheDir);
+    }
+
+    expect(counters.videoCalls).toBe(1);
+  });
+
+  test("reuses cached image across separate contexts when only layout differs", async () => {
+    const cacheDir = makeTempDir();
+    const counters = { imageCalls: 0, videoCalls: 0 };
+
+    const videoModel = createVideoModel();
+    const imageModel = createImageModel();
+
+    const base = Image({
+      prompt: "sunset over mountains",
+      model: imageModel,
+      aspectRatio: "16:9",
+    });
+
+    const variant = Image({
+      prompt: "sunset over mountains",
+      model: imageModel,
+      aspectRatio: "16:9",
+      left: "5%",
+      top: "5%",
+      width: "90%",
+      height: "90%",
+      resize: "cover",
+      zoom: "in",
+    });
+
+    try {
+      const ctx1 = createContext(cacheDir, counters);
+      await renderImage(base, ctx1);
+
+      const ctx2 = createContext(cacheDir, counters);
+      await renderImage(variant, ctx2);
+    } finally {
+      cleanupTempDir(cacheDir);
+    }
+
+    expect(counters.imageCalls).toBe(1);
+  });
+});

package/src/react/renderers/captions.ts

@@ -69,14 +69,14 @@ interface SubtitleStyle {
 const STYLE_PRESETS: Record<string, SubtitleStyle> = {
   tiktok: {
     fontName: "Montserrat",
-    fontSize: 32,
+    fontSize: 72,
     primaryColor: "&HFFFFFF",
     outlineColor: "&H000000",
-    backColor: "&H80000000",
+    backColor: "&H00000000",
     bold: true,
-    outline: 3,
+    outline: 4,
     shadow: 0,
-    marginV: 50,
+    marginV: 480,
     alignment: 2,
   },
   karaoke: {
@@ -164,10 +164,17 @@ function formatAssTime(seconds: number): string {
   return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}.${String(cs).padStart(2, "0")}`;
 }
 
-function convertSrtToAss(srtContent: string, style: SubtitleStyle): string {
+function convertSrtToAss(
+  srtContent: string,
+  style: SubtitleStyle,
+  width: number,
+  height: number,
+): string {
   const assHeader = `[Script Info]
 Title: Generated Subtitles
 ScriptType: v4.00+
+PlayResX: ${width}
+PlayResY: ${height}
 WrapStyle: 0
 ScaledBorderAndShadow: yes
 YCbCr Matrix: TV.601
@@ -193,6 +200,12 @@ Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
   return assHeader + assDialogues;
 }
 
+const POSITION_ALIGNMENT: Record<string, number> = {
+  top: 8,
+  center: 5,
+  bottom: 2,
+};
+
 function colorToAss(color: string): string {
   if (color.startsWith("&H")) return color;
 
@@ -280,15 +293,21 @@ export async function renderCaptions(
   const styleName = props.style ?? "tiktok";
   const baseStyle = STYLE_PRESETS[styleName] ?? STYLE_PRESETS.tiktok!;
 
+  const alignment = props.position
+    ? (POSITION_ALIGNMENT[props.position] ?? baseStyle.alignment)
+    : baseStyle.alignment;
+
   const style: SubtitleStyle = {
     ...baseStyle,
     fontSize: props.fontSize ?? baseStyle.fontSize,
     primaryColor: props.color
       ? colorToAss(props.color)
       : baseStyle.primaryColor,
+    alignment,
+    marginV: props.position === "center" ? 0 : baseStyle.marginV,
   };
 
-  const assContent = convertSrtToAss(srtContent, style);
+  const assContent = convertSrtToAss(srtContent, style, ctx.width, ctx.height);
   const assPath = `/tmp/varg-captions-${Date.now()}.ass`;
   writeFileSync(assPath, assContent);
   ctx.tempFiles.push(assPath);

package/src/react/renderers/clip.ts

@@ -8,17 +8,17 @@ import type {
   VideoLayer,
 } from "../../ai-sdk/providers/editly/types";
 import type {
-  AnimateProps,
   ClipProps,
   ImageProps,
+  MusicProps,
   SpeechProps,
   VargElement,
   VargNode,
   VideoProps,
 } from "../types";
-import { renderAnimate } from "./animate";
 import type { RenderContext } from "./context";
 import { renderImage } from "./image";
+import { renderMusic } from "./music";
 import { renderPackshot } from "./packshot";
 import { renderSlider } from "./slider";
 import { renderSpeech } from "./speech";
@@ -26,6 +26,7 @@ import { renderSplit } from "./split";
 import { renderSubtitle } from "./subtitle";
 import { renderSwipe } from "./swipe";
 import { renderTitle } from "./title";
+import { resolvePath } from "./utils";
 import { renderVideo } from "./video";
 
 type PendingLayer =
@@ -92,7 +93,7 @@ async function renderClipLayers(
                 type: "video",
                 path,
                 resizeMode: props.resize,
-                // Video-level cutFrom/cutTo take precedence over clip-level
+                cropPosition: props.cropPosition,
                 cutFrom: props.cutFrom ?? clipOptions?.cutFrom,
                 cutTo: props.cutTo ?? clipOptions?.cutTo,
                 mixVolume: props.keepAudio ? (props.volume ?? 1) : 0,
@@ -106,25 +107,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",
@@ -157,6 +139,35 @@ async function renderClipLayers(
         break;
       }
 
+      case "music": {
+        const props = element.props as MusicProps;
+        pending.push({
+          type: "async",
+          promise: (async () => {
+            let path: string;
+            if (props.src) {
+              path = resolvePath(props.src);
+            } else if (props.prompt) {
+              const result = await renderMusic(
+                element as VargElement<"music">,
+                ctx,
+              );
+              path = result.path;
+            } else {
+              throw new Error("Music requires either src or prompt");
+            }
+            return {
+              type: "audio",
+              path,
+              mixVolume: props.volume ?? 1,
+              cutFrom: props.cutFrom,
+              cutTo: props.cutTo,
+            } as AudioLayer;
+          })(),
+        });
+        break;
+      }
+
       case "split": {
         pending.push({
           type: "async",
@@ -215,11 +226,31 @@ async function renderClipLayers(
     }
   }
 
-  const layers = await Promise.all(
-    pending.map((p) => (p.type === "sync" ? p.layer : p.promise)),
+  const layerResults = await Promise.allSettled(
+    pending.map((p) =>
+      p.type === "sync" ? Promise.resolve(p.layer) : p.promise,
+    ),
   );
 
-  return layers;
+  const failures = layerResults
+    .map((r, i) =>
+      r.status === "rejected" ? { index: i, reason: r.reason } : null,
+    )
+    .filter(Boolean) as { index: number; reason: Error }[];
+
+  if (failures.length > 0) {
+    if (failures.length === 1 && failures[0]) {
+      throw failures[0].reason;
+    }
+    const errors = failures
+      .map((f) => f.reason?.message || "Unknown error")
+      .join("; ");
+    throw new Error(
+      `${failures.length} of ${layerResults.length} layers failed: ${errors}`,
+    );
+  }
+
+  return layerResults.map((r) => (r as PromiseFulfilledResult<Layer>).value);
 }
 
 export async function renderClip(