@vibeframe/cli 0.113.2 → 0.113.3

package/dist/commands/_shared/build-cache.d.ts

@@ -1,4 +1,4 @@
-export type BuildAssetKind = "narration" | "backdrop" | "character" | "video" | "music";
+export type BuildAssetKind = "narration" | "backdrop" | "character" | "keyframe" | "video" | "music";
 export interface CacheAssetDescriptor {
     key: string;
     path: string;
@@ -27,6 +27,16 @@ export declare function characterCacheDescriptor(opts: {
     quality: "standard" | "hd";
     size: string;
 }): CacheAssetDescriptor;
+export declare function keyframeCacheDescriptor(opts: {
+    beatId: string;
+    cue: string;
+    provider: string;
+    quality: "standard" | "hd";
+    size: string;
+    ratio?: string;
+    /** Character sheet paths used as edit references — changing them re-keys the keyframe. */
+    characters?: string[];
+}): CacheAssetDescriptor;
 export declare function imageRatioForSize(size: string | undefined): string;
 export declare function videoCacheDescriptor(opts: {
     beatId: string;
@@ -35,6 +45,11 @@ export declare function videoCacheDescriptor(opts: {
     duration: number | undefined;
     /** Character reference image paths — changing them must invalidate the clip. */
     characters?: string[];
+    /**
+     * Keyframe still path for image-to-video mode — changing the keyframe must
+     * invalidate the clip. Omitted for text/reference-to-video clips.
+     */
+    keyframe?: string;
 }): CacheAssetDescriptor;
 export declare function musicCacheDescriptor(opts: {
     beatId: string;

package/dist/commands/_shared/scene-build.d.ts

@@ -168,6 +168,9 @@ export interface BeatBuildOutcome {
     videoMetadataPath?: string;
     videoFreshness?: AssetFreshness;
     videoSourcePath?: string;
+    /** Keyframe still status when the beat uses keyframe → image-to-video mode. */
+    keyframeStatus?: PrimitiveStatus;
+    keyframePath?: string;
     musicStatus: PrimitiveStatus;
     musicPath?: string;
     musicJobId?: string;

package/dist/commands/_shared/storyboard-edit.d.ts

@@ -1,5 +1,5 @@
 import { type Beat } from "./storyboard-parse.js";
-export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "motion", "voice", "music", "asset", "characters"];
+export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset", "characters"];
 export type StoryboardCueKey = (typeof STORYBOARD_CUE_KEYS)[number];
 export interface StoryboardValidationIssue {
     severity: "error" | "warning";

package/dist/commands/_shared/storyboard-parse.d.ts

@@ -113,6 +113,13 @@ export interface BeatCues {
      * reference-to-video generation. A single name or a list.
      */
     characters?: string | string[];
+    /**
+     * Keyframe still prompt. When set, the build generates a keyframe image for
+     * this beat (using the character sheet as an edit reference when `characters`
+     * is also present) and runs Seedance image-to-video on it. The `video` cue,
+     * if present, supplies the motion prompt; otherwise this text is used.
+     */
+    keyframe?: string;
     [key: string]: unknown;
 }
 /** Normalize a beat's `characters` cue to a clean string[] (single or list). */

package/dist/index.js

@@ -31869,6 +31869,7 @@ var init_storyboard_edit = __esm({
       "narration",
       "backdrop",
       "video",
+      "keyframe",
       "motion",
       "voice",
       "music",
@@ -31878,7 +31879,7 @@ var init_storyboard_edit = __esm({
     HEADING_RE2 = /^##\s+(.+?)\s*$/gm;
     LEADING_CUE_RE = /^(\s*)```ya?ml\s*\n([\s\S]*?)\n```\s*(?:\n|$)/;
     ALLOWED_CUE_KEYS = new Set(STORYBOARD_CUE_KEYS);
-    STRING_CUE_KEYS = /* @__PURE__ */ new Set(["narration", "backdrop", "video", "motion", "voice", "music", "asset"]);
+    STRING_CUE_KEYS = /* @__PURE__ */ new Set(["narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset"]);
     MAX_RECOMMENDED_BEAT_SEC = 15;
   }
 });
@@ -60422,6 +60423,7 @@ var init_build_asset_reference = __esm({
       narration: [".mp3", ".wav", ".m4a"],
       backdrop: [".png", ".jpg", ".jpeg", ".webp"],
       character: [".png", ".jpg", ".jpeg", ".webp"],
+      keyframe: [".png", ".jpg", ".jpeg", ".webp"],
       video: [".mp4", ".mov", ".webm"],
       music: [".mp3", ".wav", ".m4a"]
     };
@@ -60469,6 +60471,18 @@ function characterCacheDescriptor(opts) {
     ext: "png"
   });
 }
+function keyframeCacheDescriptor(opts) {
+  return cacheAssetDescriptor("keyframe", {
+    beatId: opts.beatId,
+    cue: opts.cue,
+    provider: opts.provider,
+    quality: opts.quality,
+    size: opts.size,
+    ratio: opts.ratio,
+    characters: opts.characters && opts.characters.length > 0 ? opts.characters : void 0,
+    ext: "png"
+  });
+}
 function imageRatioForSize(size) {
   switch (size) {
     case "1024x1024":
@@ -60490,6 +60504,8 @@ function videoCacheDescriptor(opts) {
     ratio: "16:9",
     // Omit when empty so existing (character-less) clips keep their cache key.
     characters: opts.characters && opts.characters.length > 0 ? opts.characters : void 0,
+    // Omit when absent so existing (non-keyframe) clips keep their cache key.
+    keyframe: opts.keyframe || void 0,
     ext: "mp4"
   });
 }
@@ -60640,6 +60656,7 @@ async function createBuildPlan(opts) {
     const backdropPrompt = stringOrUndefined3(cue.backdrop);
     const augmentedBackdropPrompt = backdropPrompt ? augmentBackdropPrompt(backdropPrompt) : null;
     const videoPrompt = stringOrUndefined3(cue.video);
+    const keyframePrompt = stringOrUndefined3(cue.keyframe);
     const musicPrompt = stringOrUndefined3(cue.music);
     const genericReference = resolveGenericAssetReference(projectDir, cue.asset);
     const narrationReference = resolveTypedAssetReference(projectDir, "narration", cue.narration);
@@ -60648,7 +60665,7 @@ async function createBuildPlan(opts) {
     const musicReference = resolveTypedAssetReference(projectDir, "music", cue.music) ?? (!musicPrompt && genericReference?.kind === "music" ? genericReference : null);
     const narrationCue = narrationText ?? narrationReference?.raw;
     const backdropCue = backdropPrompt ?? backdropReference?.raw;
-    const videoCue = videoPrompt ?? videoReference?.raw;
+    const videoCue = videoPrompt ?? videoReference?.raw ?? keyframePrompt;
     const musicCue = musicPrompt ?? musicReference?.raw;
     const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : resolved.narration.resolved === "openai" ? OPENAI_NARRATION_COST_USD : 0;
     const narrationCache = narrationText && !narrationReference ? narrationCacheDescriptor({
@@ -60666,11 +60683,12 @@ async function createBuildPlan(opts) {
       size: imageSize2,
       ratio: imageRatio
     }) : null;
-    const videoCache = videoPrompt && !videoReference ? videoCacheDescriptor({
+    const videoCache = (videoPrompt || keyframePrompt) && !videoReference ? videoCacheDescriptor({
       beatId: beat.id,
-      cue: videoPrompt,
+      cue: videoPrompt ?? keyframePrompt,
       provider: resolved.video.resolved,
-      duration: beat.duration
+      duration: beat.duration,
+      keyframe: keyframePrompt
     }) : null;
     const musicCache = musicPrompt && !musicReference ? musicCacheDescriptor({
       beatId: beat.id,
@@ -60765,6 +60783,12 @@ async function createBuildPlan(opts) {
     if (backdrop?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
       noteProviderNeed(resolved.image, "Backdrop generation");
     if (video?.willGenerate) noteProviderNeed(resolved.video, "Video generation");
+    if (keyframePrompt && video?.willGenerate) {
+      estimatedCostUsd += backdropCostUsd(imageQuality);
+      providers.add(resolved.image.resolved);
+      if (isSupportedBuildImageProvider(resolved.image.resolved))
+        noteProviderNeed(resolved.image, "Keyframe generation");
+    }
     if (music?.willGenerate) noteProviderNeed(resolved.music, "Music generation");
     if (!compositionExists) missing.add("compositions");
     if (includeCompose && !compositionExists && mode !== "agent") {
@@ -62670,6 +62694,8 @@ async function buildBeatPrimitives(beat, ctx) {
       videoMetadataPath: video.metadataPath,
       videoFreshness: video.freshness,
       videoSourcePath: video.sourcePath,
+      keyframeStatus: video.keyframeStatus,
+      keyframePath: video.keyframePath,
       musicStatus: music.status,
       musicPath: music.path,
       musicJobId: music.job?.id,
@@ -63114,6 +63140,112 @@ async function generateBackdropImage(prompt3, ctx, ratio) {
   });
   return imageBufferFromResult(result);
 }
+async function editKeyframeImage(prompt3, sheetBuffers, ctx, ratio) {
+  loadSceneBuildEnv(ctx.projectDir);
+  const keyInfo = imageProviderKeyInfo(ctx.imageProvider);
+  const apiKey = await getApiKeyFromConfig(keyInfo.configKey, { cwd: ctx.projectDir }) ?? process.env[keyInfo.envVar] ?? "";
+  if (!apiKey) {
+    return {
+      success: false,
+      error: `${keyInfo.envVar} not set \u2014 cannot generate keyframe with ${ctx.imageProvider}`
+    };
+  }
+  if (ctx.imageProvider === "openai") {
+    const provider2 = new OpenAIImageProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.editImage(sheetBuffers, prompt3);
+    return imageBufferFromResult(result2);
+  }
+  if (ctx.imageProvider === "gemini") {
+    const provider2 = new GeminiProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.editImage(sheetBuffers, prompt3, {
+      model: "flash",
+      aspectRatio: ratio
+    });
+    return imageBufferFromResult(result2);
+  }
+  const provider = new GrokProvider();
+  await provider.initialize({ apiKey });
+  const result = await provider.editImage(sheetBuffers[0], prompt3, { aspectRatio: ratio });
+  return imageBufferFromResult(result);
+}
+async function ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel) {
+  const rel = `assets/keyframe-${beat.id}.png`;
+  const abs = join25(ctx.projectDir, rel);
+  const size = ctx.imageSize ?? "1536x1024";
+  const ratio = imageRatioForSize(size);
+  const metadataOptions = { quality: ctx.imageQuality, size, ratio };
+  const cache = keyframeCacheDescriptor({
+    beatId: beat.id,
+    cue: keyframeCue,
+    provider: ctx.imageProvider,
+    quality: ctx.imageQuality,
+    size,
+    ratio,
+    characters: characterRefsRel
+  });
+  if (existsSync49(abs) && !ctx.force) {
+    const metadata = readAssetMetadata(ctx.projectDir, "keyframe", beat.id);
+    if (!metadata || isFreshCanonicalAsset({
+      projectDir: ctx.projectDir,
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframeCue,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key
+    })) {
+      return { status: "cached", rel };
+    }
+  }
+  const cacheAbs = join25(ctx.projectDir, cache.path);
+  if (existsSync49(cacheAbs) && !ctx.force) {
+    await mkdir26(dirname24(abs), { recursive: true });
+    await copyFile5(cacheAbs, abs);
+    await writeAssetMetadata({
+      projectDir: ctx.projectDir,
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframeCue,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key,
+      canonicalPath: rel,
+      cachePath: cache.path
+    });
+    return { status: "cached", rel };
+  }
+  const sheetBuffers = [];
+  for (const relPath of characterRefsRel) {
+    const sheetAbs = join25(ctx.projectDir, relPath);
+    if (existsSync49(sheetAbs)) sheetBuffers.push(await readFile46(sheetAbs));
+  }
+  const imgCtx = {
+    projectDir: ctx.projectDir,
+    imageProvider: ctx.imageProvider,
+    imageSize: size,
+    imageQuality: ctx.imageQuality
+  };
+  const generated = sheetBuffers.length > 0 ? await editKeyframeImage(keyframeCue, sheetBuffers, imgCtx, ratio) : await generateBackdropImage(keyframeCue, imgCtx, ratio);
+  if (!generated.success) return { status: "failed", error: generated.error };
+  await mkdir26(dirname24(abs), { recursive: true });
+  await writeFile50(abs, generated.buffer);
+  await mkdir26(dirname24(cacheAbs), { recursive: true });
+  await writeFile50(cacheAbs, generated.buffer);
+  await writeAssetMetadata({
+    projectDir: ctx.projectDir,
+    kind: "keyframe",
+    beatId: beat.id,
+    cue: keyframeCue,
+    provider: ctx.imageProvider,
+    options: metadataOptions,
+    cacheKey: cache.key,
+    canonicalPath: rel,
+    cachePath: cache.path
+  });
+  return { status: "generated", rel };
+}
 async function imageBufferFromResult(result) {
   const image = result.images?.[0];
   if (!result.success || !image) {
@@ -63137,7 +63269,8 @@ function imageProviderKeyInfo(provider) {
 async function dispatchVideo(beat, ctx) {
   const reference = assetReferenceForBeat(ctx.projectDir, "video", beat);
   if (reference) return referencePrimitiveOutcome("video", beat, ctx, reference);
-  const prompt3 = stringOrUndefined4(beat.cues?.video);
+  const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
+  const prompt3 = stringOrUndefined4(beat.cues?.video) ?? keyframeCue;
   if (!prompt3) return { status: "no-cue" };
   const characterRefsRel = beatCharacterNames(beat.cues).map((name) => ctx.characterPaths?.get(name)).filter((p) => typeof p === "string");
   const characterRefsAbs = characterRefsRel.map((p) => join25(ctx.projectDir, p));
@@ -63148,7 +63281,10 @@ async function dispatchVideo(beat, ctx) {
     cue: prompt3,
     provider: ctx.videoProvider,
     duration: normalizeVideoDuration(beat.duration),
-    characters: characterRefsRel
+    // Keyframe mode keys the clip to the keyframe prompt; refs feed the keyframe,
+    // not the clip directly.
+    characters: keyframeCue ? void 0 : characterRefsRel,
+    keyframe: keyframeCue
   });
   const metadataPath = assetMetadataPath("video", beat.id);
   if (existsSync49(abs) && !ctx.force) {
@@ -63201,6 +63337,19 @@ async function dispatchVideo(beat, ctx) {
     };
   }
   loadSceneBuildEnv(ctx.projectDir);
+  let keyframeStatus;
+  let keyframeRel;
+  let keyframeImageAbs;
+  if (keyframeCue) {
+    const kf = await ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel);
+    if (kf.status === "failed") {
+      ctx.onProgress({ type: "video-failed", beatId: beat.id, error: kf.error });
+      return { status: "failed", error: kf.error };
+    }
+    keyframeStatus = kf.status;
+    keyframeRel = kf.rel;
+    keyframeImageAbs = join25(ctx.projectDir, kf.rel);
+  }
   const result = await executeVideoGenerate({
     prompt: prompt3,
     provider: ctx.videoProvider,
@@ -63208,7 +63357,10 @@ async function dispatchVideo(beat, ctx) {
     ratio: "16:9",
     output: abs,
     wait: false,
-    refImages: characterRefsAbs.length > 0 ? characterRefsAbs : void 0,
+    // Keyframe mode → single init frame (image-to-video); otherwise character
+    // reference-to-video.
+    image: keyframeImageAbs,
+    refImages: keyframeImageAbs ? void 0 : characterRefsAbs.length > 0 ? characterRefsAbs : void 0,
     apiKey: await apiKeyForVideoProvider(ctx.videoProvider, ctx.projectDir)
   });
   if (!result.success || !result.taskId) {
@@ -63243,14 +63395,16 @@ async function dispatchVideo(beat, ctx) {
       cachePath: cache.path,
       cacheKey: cache.key,
       metadataPath,
-      freshness: "fresh"
+      freshness: "fresh",
+      keyframeStatus,
+      keyframePath: keyframeRel
     };
   }
   const job = await createAndWriteJobRecord({
     jobType: "generate-video",
     provider: result.provider ?? ctx.videoProvider,
     providerTaskId: result.taskId,
-    providerTaskType: "text2video",
+    providerTaskType: keyframeImageAbs ? "image2video" : "text2video",
     status: "running",
     projectDir: ctx.projectDir,
     workingDirectory: ctx.projectDir,
@@ -63275,7 +63429,9 @@ async function dispatchVideo(beat, ctx) {
     provider: job.provider,
     cachePath: cache.path,
     cacheKey: cache.key,
-    metadataPath
+    metadataPath,
+    keyframeStatus,
+    keyframePath: keyframeRel
   };
 }
 async function dispatchMusic(beat, ctx) {
@@ -63577,6 +63733,7 @@ function estimateActualAssetCost(outcomes, imageQuality) {
   for (const outcome of outcomes) {
     if (outcome.narrationStatus === "generated") cost += 0.05;
     if (outcome.backdropStatus === "generated") cost += backdropCostUsd(imageQuality);
+    if (outcome.keyframeStatus === "generated") cost += backdropCostUsd(imageQuality);
     if (outcome.videoStatus === "generated" || outcome.videoStatus === "pending") {
       cost += outcome.videoProvider === "seedance" || outcome.videoProvider === "fal" ? estimateSeedanceVideoCostUsd({
         durationSec: normalizeVideoDuration(outcome.sceneDurationSec),
@@ -74662,7 +74819,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.113.2",
+  version: "0.113.3",
   description: "VibeFrame CLI - agentic video workflow runtime",
   private: false,
   license: "MIT",

package/dist/tools/manifest/index.js

@@ -32480,6 +32480,7 @@ var init_storyboard_edit = __esm({
       "narration",
       "backdrop",
       "video",
+      "keyframe",
       "motion",
       "voice",
       "music",
@@ -32489,7 +32490,7 @@ var init_storyboard_edit = __esm({
     HEADING_RE2 = /^##\s+(.+?)\s*$/gm;
     LEADING_CUE_RE = /^(\s*)```ya?ml\s*\n([\s\S]*?)\n```\s*(?:\n|$)/;
     ALLOWED_CUE_KEYS = new Set(STORYBOARD_CUE_KEYS);
-    STRING_CUE_KEYS = /* @__PURE__ */ new Set(["narration", "backdrop", "video", "motion", "voice", "music", "asset"]);
+    STRING_CUE_KEYS = /* @__PURE__ */ new Set(["narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset"]);
     MAX_RECOMMENDED_BEAT_SEC = 15;
   }
 });
@@ -33411,6 +33412,7 @@ var init_build_asset_reference = __esm({
       narration: [".mp3", ".wav", ".m4a"],
       backdrop: [".png", ".jpg", ".jpeg", ".webp"],
       character: [".png", ".jpg", ".jpeg", ".webp"],
+      keyframe: [".png", ".jpg", ".jpeg", ".webp"],
       video: [".mp4", ".mov", ".webm"],
       music: [".mp3", ".wav", ".m4a"]
     };
@@ -33458,6 +33460,18 @@ function characterCacheDescriptor(opts) {
     ext: "png"
   });
 }
+function keyframeCacheDescriptor(opts) {
+  return cacheAssetDescriptor("keyframe", {
+    beatId: opts.beatId,
+    cue: opts.cue,
+    provider: opts.provider,
+    quality: opts.quality,
+    size: opts.size,
+    ratio: opts.ratio,
+    characters: opts.characters && opts.characters.length > 0 ? opts.characters : void 0,
+    ext: "png"
+  });
+}
 function imageRatioForSize(size) {
   switch (size) {
     case "1024x1024":
@@ -33479,6 +33493,8 @@ function videoCacheDescriptor(opts) {
     ratio: "16:9",
     // Omit when empty so existing (character-less) clips keep their cache key.
     characters: opts.characters && opts.characters.length > 0 ? opts.characters : void 0,
+    // Omit when absent so existing (non-keyframe) clips keep their cache key.
+    keyframe: opts.keyframe || void 0,
     ext: "mp4"
   });
 }
@@ -33629,6 +33645,7 @@ async function createBuildPlan(opts) {
     const backdropPrompt = stringOrUndefined3(cue.backdrop);
     const augmentedBackdropPrompt = backdropPrompt ? augmentBackdropPrompt(backdropPrompt) : null;
     const videoPrompt = stringOrUndefined3(cue.video);
+    const keyframePrompt = stringOrUndefined3(cue.keyframe);
     const musicPrompt = stringOrUndefined3(cue.music);
     const genericReference = resolveGenericAssetReference(projectDir, cue.asset);
     const narrationReference = resolveTypedAssetReference(projectDir, "narration", cue.narration);
@@ -33637,7 +33654,7 @@ async function createBuildPlan(opts) {
     const musicReference = resolveTypedAssetReference(projectDir, "music", cue.music) ?? (!musicPrompt && genericReference?.kind === "music" ? genericReference : null);
     const narrationCue = narrationText ?? narrationReference?.raw;
     const backdropCue = backdropPrompt ?? backdropReference?.raw;
-    const videoCue = videoPrompt ?? videoReference?.raw;
+    const videoCue = videoPrompt ?? videoReference?.raw ?? keyframePrompt;
     const musicCue = musicPrompt ?? musicReference?.raw;
     const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : resolved.narration.resolved === "openai" ? OPENAI_NARRATION_COST_USD : 0;
     const narrationCache = narrationText && !narrationReference ? narrationCacheDescriptor({
@@ -33655,11 +33672,12 @@ async function createBuildPlan(opts) {
       size: imageSize2,
       ratio: imageRatio
     }) : null;
-    const videoCache = videoPrompt && !videoReference ? videoCacheDescriptor({
+    const videoCache = (videoPrompt || keyframePrompt) && !videoReference ? videoCacheDescriptor({
       beatId: beat.id,
-      cue: videoPrompt,
+      cue: videoPrompt ?? keyframePrompt,
       provider: resolved.video.resolved,
-      duration: beat.duration
+      duration: beat.duration,
+      keyframe: keyframePrompt
     }) : null;
     const musicCache = musicPrompt && !musicReference ? musicCacheDescriptor({
       beatId: beat.id,
@@ -33754,6 +33772,12 @@ async function createBuildPlan(opts) {
     if (backdrop?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
       noteProviderNeed(resolved.image, "Backdrop generation");
     if (video?.willGenerate) noteProviderNeed(resolved.video, "Video generation");
+    if (keyframePrompt && video?.willGenerate) {
+      estimatedCostUsd += backdropCostUsd(imageQuality);
+      providers.add(resolved.image.resolved);
+      if (isSupportedBuildImageProvider(resolved.image.resolved))
+        noteProviderNeed(resolved.image, "Keyframe generation");
+    }
     if (music?.willGenerate) noteProviderNeed(resolved.music, "Music generation");
     if (!compositionExists) missing.add("compositions");
     if (includeCompose && !compositionExists && mode !== "agent") {
@@ -35164,6 +35188,8 @@ async function buildBeatPrimitives(beat, ctx) {
       videoMetadataPath: video.metadataPath,
       videoFreshness: video.freshness,
       videoSourcePath: video.sourcePath,
+      keyframeStatus: video.keyframeStatus,
+      keyframePath: video.keyframePath,
       musicStatus: music.status,
       musicPath: music.path,
       musicJobId: music.job?.id,
@@ -35608,6 +35634,112 @@ async function generateBackdropImage(prompt3, ctx, ratio) {
   });
   return imageBufferFromResult(result);
 }
+async function editKeyframeImage(prompt3, sheetBuffers, ctx, ratio) {
+  loadSceneBuildEnv(ctx.projectDir);
+  const keyInfo = imageProviderKeyInfo(ctx.imageProvider);
+  const apiKey = await getApiKeyFromConfig(keyInfo.configKey, { cwd: ctx.projectDir }) ?? process.env[keyInfo.envVar] ?? "";
+  if (!apiKey) {
+    return {
+      success: false,
+      error: `${keyInfo.envVar} not set \u2014 cannot generate keyframe with ${ctx.imageProvider}`
+    };
+  }
+  if (ctx.imageProvider === "openai") {
+    const provider2 = new OpenAIImageProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.editImage(sheetBuffers, prompt3);
+    return imageBufferFromResult(result2);
+  }
+  if (ctx.imageProvider === "gemini") {
+    const provider2 = new GeminiProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.editImage(sheetBuffers, prompt3, {
+      model: "flash",
+      aspectRatio: ratio
+    });
+    return imageBufferFromResult(result2);
+  }
+  const provider = new GrokProvider();
+  await provider.initialize({ apiKey });
+  const result = await provider.editImage(sheetBuffers[0], prompt3, { aspectRatio: ratio });
+  return imageBufferFromResult(result);
+}
+async function ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel) {
+  const rel = `assets/keyframe-${beat.id}.png`;
+  const abs = join16(ctx.projectDir, rel);
+  const size = ctx.imageSize ?? "1536x1024";
+  const ratio = imageRatioForSize(size);
+  const metadataOptions = { quality: ctx.imageQuality, size, ratio };
+  const cache = keyframeCacheDescriptor({
+    beatId: beat.id,
+    cue: keyframeCue,
+    provider: ctx.imageProvider,
+    quality: ctx.imageQuality,
+    size,
+    ratio,
+    characters: characterRefsRel
+  });
+  if (existsSync19(abs) && !ctx.force) {
+    const metadata = readAssetMetadata(ctx.projectDir, "keyframe", beat.id);
+    if (!metadata || isFreshCanonicalAsset({
+      projectDir: ctx.projectDir,
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframeCue,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key
+    })) {
+      return { status: "cached", rel };
+    }
+  }
+  const cacheAbs = join16(ctx.projectDir, cache.path);
+  if (existsSync19(cacheAbs) && !ctx.force) {
+    await mkdir10(dirname10(abs), { recursive: true });
+    await copyFile3(cacheAbs, abs);
+    await writeAssetMetadata({
+      projectDir: ctx.projectDir,
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframeCue,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key,
+      canonicalPath: rel,
+      cachePath: cache.path
+    });
+    return { status: "cached", rel };
+  }
+  const sheetBuffers = [];
+  for (const relPath of characterRefsRel) {
+    const sheetAbs = join16(ctx.projectDir, relPath);
+    if (existsSync19(sheetAbs)) sheetBuffers.push(await readFile18(sheetAbs));
+  }
+  const imgCtx = {
+    projectDir: ctx.projectDir,
+    imageProvider: ctx.imageProvider,
+    imageSize: size,
+    imageQuality: ctx.imageQuality
+  };
+  const generated = sheetBuffers.length > 0 ? await editKeyframeImage(keyframeCue, sheetBuffers, imgCtx, ratio) : await generateBackdropImage(keyframeCue, imgCtx, ratio);
+  if (!generated.success) return { status: "failed", error: generated.error };
+  await mkdir10(dirname10(abs), { recursive: true });
+  await writeFile18(abs, generated.buffer);
+  await mkdir10(dirname10(cacheAbs), { recursive: true });
+  await writeFile18(cacheAbs, generated.buffer);
+  await writeAssetMetadata({
+    projectDir: ctx.projectDir,
+    kind: "keyframe",
+    beatId: beat.id,
+    cue: keyframeCue,
+    provider: ctx.imageProvider,
+    options: metadataOptions,
+    cacheKey: cache.key,
+    canonicalPath: rel,
+    cachePath: cache.path
+  });
+  return { status: "generated", rel };
+}
 async function imageBufferFromResult(result) {
   const image = result.images?.[0];
   if (!result.success || !image) {
@@ -35631,7 +35763,8 @@ function imageProviderKeyInfo(provider) {
 async function dispatchVideo(beat, ctx) {
   const reference = assetReferenceForBeat(ctx.projectDir, "video", beat);
   if (reference) return referencePrimitiveOutcome("video", beat, ctx, reference);
-  const prompt3 = stringOrUndefined4(beat.cues?.video);
+  const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
+  const prompt3 = stringOrUndefined4(beat.cues?.video) ?? keyframeCue;
   if (!prompt3) return { status: "no-cue" };
   const characterRefsRel = beatCharacterNames(beat.cues).map((name) => ctx.characterPaths?.get(name)).filter((p) => typeof p === "string");
   const characterRefsAbs = characterRefsRel.map((p) => join16(ctx.projectDir, p));
@@ -35642,7 +35775,10 @@ async function dispatchVideo(beat, ctx) {
     cue: prompt3,
     provider: ctx.videoProvider,
     duration: normalizeVideoDuration(beat.duration),
-    characters: characterRefsRel
+    // Keyframe mode keys the clip to the keyframe prompt; refs feed the keyframe,
+    // not the clip directly.
+    characters: keyframeCue ? void 0 : characterRefsRel,
+    keyframe: keyframeCue
   });
   const metadataPath = assetMetadataPath("video", beat.id);
   if (existsSync19(abs) && !ctx.force) {
@@ -35695,6 +35831,19 @@ async function dispatchVideo(beat, ctx) {
     };
   }
   loadSceneBuildEnv(ctx.projectDir);
+  let keyframeStatus;
+  let keyframeRel;
+  let keyframeImageAbs;
+  if (keyframeCue) {
+    const kf = await ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel);
+    if (kf.status === "failed") {
+      ctx.onProgress({ type: "video-failed", beatId: beat.id, error: kf.error });
+      return { status: "failed", error: kf.error };
+    }
+    keyframeStatus = kf.status;
+    keyframeRel = kf.rel;
+    keyframeImageAbs = join16(ctx.projectDir, kf.rel);
+  }
   const result = await executeVideoGenerate({
     prompt: prompt3,
     provider: ctx.videoProvider,
@@ -35702,7 +35851,10 @@ async function dispatchVideo(beat, ctx) {
     ratio: "16:9",
     output: abs,
     wait: false,
-    refImages: characterRefsAbs.length > 0 ? characterRefsAbs : void 0,
+    // Keyframe mode → single init frame (image-to-video); otherwise character
+    // reference-to-video.
+    image: keyframeImageAbs,
+    refImages: keyframeImageAbs ? void 0 : characterRefsAbs.length > 0 ? characterRefsAbs : void 0,
     apiKey: await apiKeyForVideoProvider(ctx.videoProvider, ctx.projectDir)
   });
   if (!result.success || !result.taskId) {
@@ -35737,14 +35889,16 @@ async function dispatchVideo(beat, ctx) {
       cachePath: cache.path,
       cacheKey: cache.key,
       metadataPath,
-      freshness: "fresh"
+      freshness: "fresh",
+      keyframeStatus,
+      keyframePath: keyframeRel
     };
   }
   const job = await createAndWriteJobRecord({
     jobType: "generate-video",
     provider: result.provider ?? ctx.videoProvider,
     providerTaskId: result.taskId,
-    providerTaskType: "text2video",
+    providerTaskType: keyframeImageAbs ? "image2video" : "text2video",
     status: "running",
     projectDir: ctx.projectDir,
     workingDirectory: ctx.projectDir,
@@ -35769,7 +35923,9 @@ async function dispatchVideo(beat, ctx) {
     provider: job.provider,
     cachePath: cache.path,
     cacheKey: cache.key,
-    metadataPath
+    metadataPath,
+    keyframeStatus,
+    keyframePath: keyframeRel
   };
 }
 async function dispatchMusic(beat, ctx) {
@@ -36071,6 +36227,7 @@ function estimateActualAssetCost(outcomes, imageQuality) {
   for (const outcome of outcomes) {
     if (outcome.narrationStatus === "generated") cost += 0.05;
     if (outcome.backdropStatus === "generated") cost += backdropCostUsd(imageQuality);
+    if (outcome.keyframeStatus === "generated") cost += backdropCostUsd(imageQuality);
     if (outcome.videoStatus === "generated" || outcome.videoStatus === "pending") {
       cost += outcome.videoProvider === "seedance" || outcome.videoProvider === "fal" ? estimateSeedanceVideoCostUsd({
         durationSec: normalizeVideoDuration(outcome.sceneDurationSec),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.113.2",
+  "version": "0.113.3",
   "description": "VibeFrame CLI - agentic video workflow runtime",
   "private": false,
   "license": "MIT",
@@ -83,8 +83,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/ai-providers": "0.113.2",
-    "@vibeframe/core": "0.113.2"
+    "@vibeframe/core": "0.113.3",
+    "@vibeframe/ai-providers": "0.113.3"
   },
   "engines": {
     "node": ">=20"