@vibeframe/mcp-server 0.113.2 → 0.113.4

package/dist/index.js

@@ -471698,6 +471698,7 @@ var init_storyboard_edit = __esm({
       "narration",
       "backdrop",
       "video",
+      "keyframe",
       "motion",
       "voice",
       "music",
@@ -471707,7 +471708,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;
   }
 });
@@ -472626,6 +472627,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"]
     };
@@ -472673,6 +472675,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":
@@ -472694,6 +472708,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"
   });
 }
@@ -472844,6 +472860,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);
@@ -472852,7 +472869,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({
@@ -472870,11 +472887,20 @@ 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 keyframeCache2 = keyframePrompt ? keyframeCacheDescriptor({
+      beatId: beat.id,
+      cue: keyframePrompt,
+      provider: resolved.image.resolved,
+      quality: imageQuality,
+      size: imageSize2,
+      ratio: imageRatio
     }) : null;
     const musicCache = musicPrompt && !musicReference ? musicCacheDescriptor({
       beatId: beat.id,
@@ -472911,6 +472937,19 @@ async function createBuildPlan(opts) {
       cost: backdropCostUsd(imageQuality),
       active: includeAssets
     }) : null;
+    const keyframe = keyframePrompt && !opts.skipKeyframe ? assetPlan({
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframePrompt,
+      provider: resolved.image.resolved,
+      path: `assets/keyframe-${beat.id}.png`,
+      cache: keyframeCache2,
+      reference: null,
+      projectDir,
+      force: opts.force,
+      cost: backdropCostUsd(imageQuality),
+      active: includeAssets
+    }) : null;
     const video = videoCue && !opts.skipVideo ? assetPlan({
       kind: "video",
       beatId: beat.id,
@@ -472943,7 +472982,7 @@ async function createBuildPlan(opts) {
     }) : null;
     const compositionPath = `compositions/scene-${beat.id}.html`;
     const compositionExists = existsSync33(join30(projectDir, compositionPath));
-    for (const asset of [narration, backdrop, video, music]) {
+    for (const asset of [narration, backdrop, keyframe, video, music]) {
       if (!asset) continue;
       if (asset.referenceError) {
         missing.add("assets");
@@ -472968,6 +473007,8 @@ async function createBuildPlan(opts) {
     if (narration?.willGenerate) noteProviderNeed(resolved.narration, "Narration");
     if (backdrop?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
       noteProviderNeed(resolved.image, "Backdrop generation");
+    if (keyframe?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
+      noteProviderNeed(resolved.image, "Keyframe generation");
     if (video?.willGenerate) noteProviderNeed(resolved.video, "Video generation");
     if (music?.willGenerate) noteProviderNeed(resolved.music, "Music generation");
     if (!compositionExists) missing.add("compositions");
@@ -472981,7 +473022,7 @@ async function createBuildPlan(opts) {
       heading: beat.heading,
       durationSec: beat.duration ?? null,
       cues: cue,
-      assets: { narration, backdrop, video, music },
+      assets: { narration, backdrop, keyframe, video, music },
       composition: {
         path: compositionPath,
         exists: compositionExists
@@ -473197,6 +473238,7 @@ function providerResolutionsForPlan(resolved, beats, opts, includeAssets) {
   return [
     includeAssets && !opts.skipNarration && needsProvider("narration") ? resolved.narration : null,
     includeAssets && !opts.skipBackdrop && needsProvider("backdrop") ? resolved.image : null,
+    includeAssets && !opts.skipKeyframe && needsProvider("keyframe") ? resolved.image : null,
     includeAssets && !opts.skipVideo && needsProvider("video") ? resolved.video : null,
     includeAssets && !opts.skipMusic && needsProvider("music") ? resolved.music : null,
     resolved.composer ?? null
@@ -473771,6 +473813,7 @@ async function executeSceneBuild(opts) {
     skipNarration: opts.skipNarration,
     skipBackdrop: opts.skipBackdrop,
     skipVideo: opts.skipVideo,
+    skipKeyframe: opts.skipKeyframe,
     skipMusic: opts.skipMusic,
     ttsProvider: opts.ttsProvider,
     voice: opts.voice,
@@ -473956,6 +473999,7 @@ async function executeSceneBuild(opts) {
         skipNarration: opts.skipNarration ?? false,
         skipBackdrop: opts.skipBackdrop ?? false,
         skipVideo: opts.skipVideo ?? false,
+        skipKeyframe: opts.skipKeyframe ?? false,
         skipMusic: opts.skipMusic ?? false,
         force: opts.force ?? false,
         onProgress,
@@ -474332,10 +474376,11 @@ async function executeSceneBuild(opts) {
   });
 }
 async function buildBeatPrimitives(beat, ctx) {
+  const keyframe = ctx.skipKeyframe ? await skipped("keyframe", beat.id, "--skip-keyframe", ctx) : await dispatchKeyframe(beat, ctx);
   const [narration, backdrop, video, music] = await Promise.all([
     ctx.skipNarration ? skipped("narration", beat.id, "--skip-narration", ctx) : dispatchNarration(beat, ctx),
     ctx.skipBackdrop ? skipped("backdrop", beat.id, "--skip-backdrop", ctx) : dispatchBackdrop(beat, ctx),
-    ctx.skipVideo ? skipped("video", beat.id, "--skip-video", ctx) : dispatchVideo(beat, ctx),
+    ctx.skipVideo ? skipped("video", beat.id, "--skip-video", ctx) : dispatchVideo(beat, ctx, keyframe),
     ctx.skipMusic ? skipped("music", beat.id, "--skip-music", ctx) : dispatchMusic(beat, ctx)
   ]);
   return {
@@ -474379,6 +474424,8 @@ async function buildBeatPrimitives(beat, ctx) {
       videoMetadataPath: video.metadataPath,
       videoFreshness: video.freshness,
       videoSourcePath: video.sourcePath,
+      keyframeStatus: keyframe.status,
+      keyframePath: keyframe.path,
       musicStatus: music.status,
       musicPath: music.path,
       musicJobId: music.job?.id,
@@ -474823,6 +474870,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 = join31(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 (existsSync35(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 = join31(ctx.projectDir, cache.path);
+  if (existsSync35(cacheAbs) && !ctx.force) {
+    await mkdir13(dirname18(abs), { recursive: true });
+    await copyFile4(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 = join31(ctx.projectDir, relPath);
+    if (existsSync35(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 mkdir13(dirname18(abs), { recursive: true });
+  await writeFile20(abs, generated.buffer);
+  await mkdir13(dirname18(cacheAbs), { recursive: true });
+  await writeFile20(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) {
@@ -474843,10 +474996,25 @@ function imageProviderKeyInfo(provider) {
   if (provider === "grok") return { configKey: "xai", envVar: "XAI_API_KEY" };
   return { configKey: "openai", envVar: "OPENAI_API_KEY" };
 }
-async function dispatchVideo(beat, ctx) {
+async function dispatchKeyframe(beat, ctx) {
+  const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
+  if (!keyframeCue) return { status: "no-cue" };
+  const characterRefsRel = beatCharacterNames(beat.cues).map((name) => ctx.characterPaths?.get(name)).filter((p2) => typeof p2 === "string");
+  const kf = await ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel);
+  if (kf.status === "failed") {
+    ctx.onProgress({ type: "keyframe-failed", beatId: beat.id, error: kf.error });
+    return { status: "failed", error: kf.error };
+  }
+  ctx.onProgress(
+    kf.status === "cached" ? { type: "keyframe-cached", beatId: beat.id, path: kf.rel } : { type: "keyframe-generated", beatId: beat.id, path: kf.rel, provider: ctx.imageProvider }
+  );
+  return { status: kf.status, path: kf.rel, provider: ctx.imageProvider };
+}
+async function dispatchVideo(beat, ctx, keyframe) {
   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((p2) => typeof p2 === "string");
   const characterRefsAbs = characterRefsRel.map((p2) => join31(ctx.projectDir, p2));
@@ -474857,7 +475025,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 (existsSync35(abs) && !ctx.force) {
@@ -474909,6 +475080,13 @@ async function dispatchVideo(beat, ctx) {
       freshness: "fresh"
     };
   }
+  const keyframeImageRel = keyframeCue && (keyframe.status === "generated" || keyframe.status === "cached") ? keyframe.path : void 0;
+  if (keyframeCue && !keyframeImageRel) {
+    const reason = keyframe.status === "failed" ? `keyframe unavailable: ${keyframe.error ?? "generation failed"}` : "keyframe not generated (build without --skip-keyframe first)";
+    ctx.onProgress({ type: "video-skipped", beatId: beat.id, reason });
+    return { status: "skipped" };
+  }
+  const keyframeImageAbs = keyframeImageRel ? join31(ctx.projectDir, keyframeImageRel) : void 0;
   loadSceneBuildEnv(ctx.projectDir);
   const result = await executeVideoGenerate({
     prompt: prompt3,
@@ -474917,7 +475095,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) {
@@ -474959,7 +475140,7 @@ async function dispatchVideo(beat, ctx) {
     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,
@@ -475286,6 +475467,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),
@@ -499542,7 +499724,7 @@ var server2 = new Server(
   {
     name: "vibeframe",
     // Stamped with the package version by build.js at bundle time.
-    version: "0.113.2"
+    version: "0.113.4"
   },
   {
     capabilities: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/mcp-server",
-  "version": "0.113.2",
+  "version": "0.113.4",
   "description": "VibeFrame MCP Server - AI-native video editing via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -60,8 +60,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/cli": "0.113.2",
-    "@vibeframe/core": "0.113.2"
+    "@vibeframe/cli": "0.113.4",
+    "@vibeframe/core": "0.113.4"
   },
   "engines": {
     "node": ">=20"