vargai 0.4.0-alpha80 → 0.4.0-alpha82

package/package.json

@@ -71,7 +71,7 @@
     "zod": "^4.2.1"
   },
   "sideEffects": false,
-  "version": "0.4.0-alpha80",
+  "version": "0.4.0-alpha82",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",

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

@@ -84,22 +84,40 @@ export async function generatePlaceholder(
   const { $ } = await import("bun");
 
   try {
+    let ffmpegResult: Awaited<ReturnType<typeof $>>;
+
     if (type === "audio") {
-      await $`ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t ${duration} -c:a libmp3lame ${outputPath}`.quiet();
+      ffmpegResult =
+        await $`ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t ${duration} -c:a libmp3lame ${outputPath}`
+          .quiet()
+          .nothrow();
     } 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();
+      ffmpegResult =
+        await $`ffmpeg -y -f lavfi -i ${colorInput} -vf ${drawLabel},${drawPrompt} -frames:v 1 -update 1 ${outputPath}`
+          .quiet()
+          .nothrow();
     } 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();
+      ffmpegResult =
+        await $`ffmpeg -y -f lavfi -i ${colorInput} -vf ${drawLabel},${drawPrompt} -c:v libx264 -preset ultrafast -pix_fmt yuv420p ${outputPath}`
+          .quiet()
+          .nothrow();
+    }
+
+    if (ffmpegResult.exitCode !== 0) {
+      const stderr = ffmpegResult.stderr.toString().trim();
+      throw new Error(
+        `ffmpeg placeholder failed (exit ${ffmpegResult.exitCode}): ${stderr || "unknown error"}`,
+      );
     }
 
     const data = await Bun.file(outputPath).bytes();

package/src/ai-sdk/providers/editly/backends/local.ts

@@ -1,3 +1,5 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { $ } from "bun";
 import { File } from "../../../file";
 import type {
@@ -86,14 +88,20 @@ export class LocalBackend implements FFmpegBackend {
       outputPath,
     ];
 
+    // Ensure the output directory exists (ffmpeg cannot create directories)
+    mkdirSync(dirname(outputPath), { recursive: true });
+
     if (verbose) {
       console.log("ffmpeg", ffmpegArgs.join(" "));
     }
 
-    const result = await $`ffmpeg ${ffmpegArgs}`.quiet();
+    const result = await $`ffmpeg ${ffmpegArgs}`.quiet().nothrow();
 
     if (result.exitCode !== 0) {
-      throw new Error(`ffmpeg failed with exit code ${result.exitCode}`);
+      const stderr = result.stderr.toString().trim();
+      throw new Error(
+        `ffmpeg failed (exit ${result.exitCode}): ${stderr || "unknown error"}`,
+      );
     }
 
     return { output: { type: "file", path: outputPath } };

package/src/ai-sdk/providers/editly/editly.test.ts

@@ -1409,4 +1409,114 @@ describe("editly", () => {
       }),
     ).rejects.toThrow("produced no video output");
   });
+
+  // Per-clip overlay tests (feature/per-clip-overlay)
+
+  test("clip-local video overlay with start/stop timing", async () => {
+    const outPath = "output/editly-test-clip-overlay-timing.mp4";
+    if (existsSync(outPath)) unlinkSync(outPath);
+
+    await editly({
+      outPath,
+      width: 1280,
+      height: 720,
+      fps: 30,
+      clips: [
+        {
+          duration: 4,
+          layers: [
+            { type: "fill-color", color: "#1a1a2e" },
+            {
+              type: "video",
+              path: VIDEO_1,
+              width: "30%",
+              height: "30%",
+              left: "68%",
+              top: "2%",
+              start: 1,
+              stop: 3,
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(existsSync(outPath)).toBe(true);
+    const info = await ffprobe(outPath);
+    expect(info.duration).toBeCloseTo(4, 0);
+  });
+
+  test("clip-local image overlay with start/stop timing", async () => {
+    const outPath = "output/editly-test-clip-image-overlay-timing.mp4";
+    if (existsSync(outPath)) unlinkSync(outPath);
+
+    await editly({
+      outPath,
+      width: 1280,
+      height: 720,
+      fps: 30,
+      clips: [
+        {
+          duration: 4,
+          layers: [
+            { type: "fill-color", color: "#1a1a2e" },
+            {
+              type: "image-overlay",
+              path: IMAGE_SQUARE,
+              position: "top-right",
+              width: "20%",
+              start: 1,
+              stop: 3,
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(existsSync(outPath)).toBe(true);
+    const info = await ffprobe(outPath);
+    expect(info.duration).toBeCloseTo(4, 0);
+  });
+
+  test("clip-local overlay only appears in its clip, not in others", async () => {
+    const outPath = "output/editly-test-clip-overlay-scoped.mp4";
+    if (existsSync(outPath)) unlinkSync(outPath);
+
+    await editly({
+      outPath,
+      width: 1280,
+      height: 720,
+      fps: 30,
+      clips: [
+        {
+          duration: 2,
+          layers: [{ type: "fill-color", color: "#ff0000" }],
+          transition: { name: "fade", duration: 0.3 },
+        },
+        {
+          duration: 2,
+          layers: [
+            { type: "fill-color", color: "#00ff00" },
+            {
+              type: "image-overlay",
+              path: IMAGE_SQUARE,
+              position: "center",
+              width: "30%",
+              start: 0.5,
+              stop: 1.5,
+            },
+          ],
+          transition: { name: "fade", duration: 0.3 },
+        },
+        {
+          duration: 2,
+          layers: [{ type: "fill-color", color: "#0000ff" }],
+        },
+      ],
+    });
+
+    expect(existsSync(outPath)).toBe(true);
+    const info = await ffprobe(outPath);
+    expect(info.duration).toBeGreaterThan(4);
+  });
 });

package/src/ai-sdk/providers/editly/index.ts

@@ -168,6 +168,15 @@ function isImageOverlayLayer(layer: Layer): boolean {
   return layer.type === "image-overlay";
 }
 
+/**
+ * Clip-local image overlay: has start/stop timing (from <Overlay start end> inside <Clip>).
+ * These should be composited within their clip with enable expressions.
+ */
+function isClipLocalImageOverlay(layer: Layer): boolean {
+  if (!isImageOverlayLayer(layer)) return false;
+  return layer.start !== undefined || layer.stop !== undefined;
+}
+
 function isOverlayLayer(layer: Layer): boolean {
   return isVideoOverlayLayer(layer) || isImageOverlayLayer(layer);
 }
@@ -216,6 +225,10 @@ function buildBaseClipFilter(
     (l) => l && isClipLocalVideoOverlay(l),
   ) as VideoLayer[];
 
+  const clipLocalImageOverlays = clip.layers.filter(
+    (l) => l && isClipLocalImageOverlay(l),
+  ) as ImageOverlayLayer[];
+
   for (let i = 0; i < baseLayers.length; i++) {
     const layer = baseLayers[i];
     if (!layer) continue;
@@ -253,7 +266,10 @@ function buildBaseClipFilter(
     }
   }
 
-  if (!baseLabel && clipLocalOverlays.length > 0) {
+  if (
+    !baseLabel &&
+    (clipLocalOverlays.length > 0 || clipLocalImageOverlays.length > 0)
+  ) {
     const fillFilter = getFillColorFilter(
       { type: "fill-color", color: "#000000" },
       inputIdx,
@@ -295,12 +311,50 @@ function buildBaseClipFilter(
       width,
       height,
       outputLabel,
+      clip.duration,
     );
     filters.push(positionFilter);
     baseLabel = outputLabel;
     inputIdx++;
   }
 
+  // Composite clip-local image overlays (from <Overlay start end> inside <Clip>)
+  for (let i = 0; i < clipLocalImageOverlays.length; i++) {
+    const layer = clipLocalImageOverlays[i];
+    if (!layer) continue;
+
+    if (!baseLabel) {
+      throw new Error(
+        `Clip ${clipIndex} is missing a base layer for image overlay placement`,
+      );
+    }
+
+    const imgFilter = getImageOverlayFilter(
+      layer,
+      inputIdx,
+      width,
+      height,
+      clip.duration,
+    );
+
+    inputs.push(layer.path);
+    filters.push(imgFilter.filterComplex);
+
+    const outputLabel = `clip${clipIndex}imgov${i}`;
+    const posFilter = getImageOverlayPositionFilter(
+      baseLabel,
+      imgFilter.outputLabel,
+      layer,
+      width,
+      height,
+      outputLabel,
+      clip.duration,
+    );
+    filters.push(posFilter);
+    baseLabel = outputLabel;
+    inputIdx++;
+  }
+
   if (!baseLabel) {
     throw new Error(
       `Clip ${clipIndex} produced no video output — ensure it has at least one visual layer (video, image, or fill-color)`,
@@ -356,7 +410,12 @@ function collectImageOverlays(
 
   for (const clip of clips) {
     for (const layer of clip.layers) {
-      if (layer && isImageOverlayLayer(layer)) {
+      // Skip clip-local image overlays (with start/stop) — they are composited per-clip
+      if (
+        layer &&
+        isImageOverlayLayer(layer) &&
+        !isClipLocalImageOverlay(layer)
+      ) {
         const imgLayer = layer as ImageOverlayLayer;
         const key = `${imgLayer.path}:${JSON.stringify(imgLayer.position ?? "")}:${imgLayer.width ?? ""}:${imgLayer.height ?? ""}`;
         const existing = overlays.get(key);

package/src/ai-sdk/providers/editly/layers.ts

@@ -247,6 +247,7 @@ export function getOverlayFilter(
   width: number,
   height: number,
   outputLabel: string,
+  clipDuration?: number,
 ): string {
   const baseX = layer.left !== undefined ? parseSize(layer.left, width) : 0;
   const baseY = layer.top !== undefined ? parseSize(layer.top, height) : 0;
@@ -266,7 +267,8 @@ export function getOverlayFilter(
     yExpr = `${baseY}-overlay_h`;
   }
 
-  return `[${baseLabel}][${overlayLabel}]overlay=${xExpr}:${yExpr}:shortest=1[${outputLabel}]`;
+  const enable = getEnableExpr(layer.start, layer.stop, clipDuration ?? 9999);
+  return `[${baseLabel}][${overlayLabel}]overlay=${xExpr}:${yExpr}:shortest=1${enable}[${outputLabel}]`;
 }
 
 export function getImageFilter(
@@ -594,9 +596,11 @@ export function getImageOverlayPositionFilter(
   width: number,
   height: number,
   outputLabel: string,
+  clipDuration?: number,
 ): string {
   const { x, y } = resolvePositionForOverlay(layer.position, width, height);
-  return `[${baseLabel}][${overlayLabel}]overlay=${x}:${y}:shortest=1[${outputLabel}]`;
+  const enable = getEnableExpr(layer.start, layer.stop, clipDuration ?? 9999);
+  return `[${baseLabel}][${overlayLabel}]overlay=${x}:${y}:shortest=1${enable}[${outputLabel}]`;
 }
 
 function getEnableExpr(

package/src/cli/commands/render.tsx

@@ -1,7 +1,7 @@
 /** @jsxImportSource react */
 
-import { existsSync, mkdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { defineCommand } from "citty";
 import { Box, Text } from "ink";
 import { render } from "../../react/render";
@@ -11,12 +11,22 @@ import { renderStatic } from "../ui/render.ts";
 
 const AUTO_IMPORTS = `/** @jsxImportSource vargai */
 import { Captions, Clip, Image, Music, Overlay, Packshot, Render, Slider, Speech, Split, Subtitle, Swipe, TalkingHead, Title, Video, Grid } from "vargai/react";
-import { fal, elevenlabs, replicate } from "vargai/ai";
+import { fal, elevenlabs, replicate, varg } from "vargai/ai";
 `;
 
 async function detectDefaultModels(): Promise<DefaultModels | undefined> {
   const defaults: DefaultModels = {};
 
+  // Gateway provider — single key for all models (recommended)
+  if (process.env.VARG_API_KEY) {
+    const { varg } = await import("../../ai-sdk/providers/varg");
+    defaults.image = varg.imageModel("nano-banana-pro");
+    defaults.video = varg.videoModel("kling-v3");
+    defaults.speech = varg.speechModel("eleven_v3");
+    defaults.music = varg.musicModel("music_v1");
+  }
+
+  // Direct providers override gateway when available
   const falKey = process.env.FAL_API_KEY ?? process.env.FAL_KEY;
   if (falKey) {
     const { fal } = await import("../../ai-sdk/providers/fal");
@@ -26,7 +36,7 @@ async function detectDefaultModels(): Promise<DefaultModels | undefined> {
 
   if (process.env.ELEVENLABS_API_KEY) {
     const { elevenlabs } = await import("../../ai-sdk/providers/elevenlabs");
-    defaults.speech = elevenlabs.speechModel("eleven_multilingual_v2");
+    defaults.speech = elevenlabs.speechModel("eleven_v3");
     defaults.music = elevenlabs.musicModel("music_v1");
   }
 
@@ -73,13 +83,23 @@ async function loadComponent(filePath: string): Promise<VargElement> {
 
   if (hasVargaiImport) {
     const tmpFile = `${tmpDir}/${Date.now()}.tsx`;
-    await Bun.write(tmpFile, source);
+    // Resolve @jsxImportSource to absolute path so it works from the cache dir
+    const runtimeDir = resolve(pkgDir, "src/react/runtime");
+    const resolvedSource = source.replace(
+      /@jsxImportSource\s+vargai/,
+      `@jsxImportSource ${runtimeDir}`,
+    );
+    await Bun.write(tmpFile, resolvedSource);
 
     try {
       const mod = await import(tmpFile);
       return resolveDefaultExport(mod);
     } finally {
-      (await Bun.file(tmpFile).exists()) && (await Bun.write(tmpFile, ""));
+      try {
+        unlinkSync(tmpFile);
+      } catch {
+        /* ignore cleanup errors */
+      }
     }
   }
 
@@ -96,7 +116,11 @@ async function loadComponent(filePath: string): Promise<VargElement> {
     const mod = await import(tmpFile);
     return resolveDefaultExport(mod);
   } finally {
-    (await Bun.file(tmpFile).exists()) && (await Bun.write(tmpFile, ""));
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      /* ignore cleanup errors */
+    }
   }
 }
 
@@ -166,6 +190,9 @@ async function runRender(
     .pop();
   const outputPath = (args.output as string) ?? `output/${basename}.mp4`;
 
+  // Ensure the output directory exists (ffmpeg cannot create directories)
+  mkdirSync(dirname(outputPath), { recursive: true });
+
   if (!args.quiet) {
     const modeLabel = mode === "preview" ? " (fast)" : "";
     console.log(`rendering ${file} → ${outputPath}${modeLabel}`);

package/src/react/renderers/clip.ts

@@ -12,6 +12,7 @@ import type {
   ClipProps,
   ImageProps,
   MusicProps,
+  OverlayProps,
   SpeechProps,
   VargElement,
   VargNode,
@@ -231,11 +232,79 @@ async function renderClipLayers(
       }
 
       case "overlay": {
-        console.warn(
-          "[varg] Warning: <Overlay> placed inside <Clip> will be ignored. " +
-            "Move <Overlay> to be a sibling of <Clip> inside <Render>. " +
-            "See: https://github.com/vargHQ/sdk/issues/45",
-        );
+        const overlayProps = element.props as OverlayProps;
+        for (const overlayChild of element.children) {
+          if (
+            !overlayChild ||
+            typeof overlayChild !== "object" ||
+            !("type" in overlayChild)
+          )
+            continue;
+          const overlayChildElement = overlayChild as VargElement;
+
+          if (overlayChildElement.type === "image") {
+            const hasPosition =
+              overlayProps.left !== undefined ||
+              overlayProps.top !== undefined ||
+              overlayProps.width !== undefined ||
+              overlayProps.height !== undefined;
+
+            pending.push({
+              type: "async",
+              promise: renderImage(
+                overlayChildElement as VargElement<"image">,
+                ctx,
+              )
+                .then((file) => ctx.backend.resolvePath(file))
+                .then((path) =>
+                  hasPosition
+                    ? ({
+                        type: "image-overlay",
+                        path,
+                        width: overlayProps.width,
+                        height: overlayProps.height,
+                        position: {
+                          x: overlayProps.left ?? 0,
+                          y: overlayProps.top ?? 0,
+                        },
+                        start: overlayProps.start,
+                        stop: overlayProps.end,
+                      } as ImageOverlayLayer)
+                    : ({
+                        type: "image",
+                        path,
+                        start: overlayProps.start,
+                        stop: overlayProps.end,
+                      } as ImageLayer),
+                ),
+            });
+          } else if (overlayChildElement.type === "video") {
+            pending.push({
+              type: "async",
+              promise: renderVideo(
+                overlayChildElement as VargElement<"video">,
+                ctx,
+              )
+                .then((file) => ctx.backend.resolvePath(file))
+                .then(
+                  (path) =>
+                    ({
+                      type: "video",
+                      path,
+                      mixVolume: overlayProps.keepAudio
+                        ? (overlayProps.volume ?? 1)
+                        : 0,
+                      left: overlayProps.left,
+                      top: overlayProps.top,
+                      width: overlayProps.width,
+                      height: overlayProps.height,
+                      start: overlayProps.start,
+                      stop: overlayProps.end,
+                    }) as VideoLayer,
+                ),
+            });
+          }
+        }
         break;
       }
     }

package/src/react/renderers/render.ts

@@ -246,12 +246,24 @@ export async function renderRoot(
     // offsets (they all start at the container's position in the timeline).
     const firstLeafClipIndex = clipIndexCounter; // before recursion increments it
 
-    // Recurse into child clips
+    // Collect overlays from container level — these get injected into each
+    // child clip so the overlay appears across all inner clips.
+    const containerOverlays: VargElement[] = [];
+    for (const el of nonClipChildren) {
+      if (el.type === "overlay") {
+        containerOverlays.push(el);
+      }
+    }
+
+    // Recurse into child clips, injecting container-level overlays
     for (const childClip of childClips) {
+      if (containerOverlays.length > 0) {
+        childClip.children = [...childClip.children, ...containerOverlays];
+      }
       flattenClip(childClip);
     }
 
-    // Process non-clip children at the container level
+    // Process remaining non-clip children at the container level
     for (const el of nonClipChildren) {
       if (el.type === "captions") {
         hoistedCaptions.push({
@@ -264,6 +276,7 @@ export async function renderRoot(
           clipIndex: firstLeafClipIndex,
         });
       }
+      // overlay: already handled above (distributed to child clips)
       // Image/Video at container level: not supported yet (would need
       // background layer spanning all child clips — a future feature)
     }

package/src/react/resolve.ts

@@ -276,7 +276,16 @@ async function sliceAudio(
 
   // Fallback: no backend (top-level `await` outside render()) — use local ffmpeg directly.
   const inputPath = await file.toTempFile();
-  await $`ffmpeg -y -ss ${start} -i ${inputPath} -t ${duration} -acodec libmp3lame -q:a 2 ${outPath}`.quiet();
+  const sliceResult =
+    await $`ffmpeg -y -ss ${start} -i ${inputPath} -t ${duration} -acodec libmp3lame -q:a 2 ${outPath}`
+      .quiet()
+      .nothrow();
+  if (sliceResult.exitCode !== 0) {
+    const stderr = sliceResult.stderr.toString().trim();
+    throw new Error(
+      `ffmpeg audio slice failed (exit ${sliceResult.exitCode}): ${stderr || "unknown error"}`,
+    );
+  }
 
   const sliced = await Bun.file(outPath).arrayBuffer();
   try {

package/src/react/types.ts

@@ -121,6 +121,10 @@ export interface ClipProps extends BaseProps {
 }
 
 export interface OverlayProps extends BaseProps, PositionProps, AudioProps {
+  /** Start time in seconds (relative to parent clip). Only used when inside a <Clip>. */
+  start?: number;
+  /** End time in seconds (relative to parent clip). Only used when inside a <Clip>. */
+  end?: number;
   children?: VargNode;
 }
 

package/src/react/warnings.test.ts

@@ -3,7 +3,7 @@ import { existsSync, unlinkSync, writeFileSync } from "node:fs";
 
 describe("warnings", () => {
   test(
-    "issue #45: warns when Overlay is placed inside Clip",
+    "issue #45: Overlay inside Clip renders without warning",
     async () => {
       const script = `
 import { Clip, Image, Overlay, Render, render } from "./src/react/index";
@@ -45,8 +45,10 @@ await render(
       unlinkSync(tmpFile);
 
       const output = stdout + stderr;
-      expect(output).toContain("Overlay");
-      expect(output).toContain("Clip");
+      // <Overlay> inside <Clip> is now valid — no warning should be emitted
+      expect(output).not.toContain(
+        "<Overlay> placed inside <Clip> will be ignored",
+      );
       expect(existsSync("output/test-issue-45.mp4")).toBe(true);
     },
     { timeout: 15000 },