@mevdragon/vidfarm-devcli 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Developer CLI for running the Vidfarm local template platform.",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/OfficeXApp/vidfarm-devcli.git"
+    "url": "git+https://github.com/OfficeXApp/vidfarm.git"
   },
   "engines": {
     "node": ">=22.0.0"

package/templates/template_0000/README.md

@@ -5,6 +5,7 @@ Standalone GitHub-distributable package for the Vidfarm `template_0000` starter
 This package exists to give third-party developers a concrete example of the Vidfarm template contract.
 
 Developers should treat this repo as an authoring and review unit.
+The canonical template implementation lives in `src/template.ts`; the build emits `src/template.js` for runtime loading.
 
 When a template is ready, it is handed off for Vidfarm admin review and approval before it becomes available on the hosted platform.
 
@@ -19,7 +20,7 @@ Production integration settings are checked into `template.config.json`. AI agen
 - project identity
 - `template_id` as the self-issued UUIDv4 platform identifier
 - `slug_id` as the human-readable stable slug
-- the template module path
+- the template module path, which should be the TypeScript source entrypoint `src/template.ts`
 - the local Remotion composition settings used by the starter template
 
 ## Included

package/templates/template_0000/SKILL.md

@@ -18,12 +18,44 @@ Behavior:
 
 - `create_slideshow` generates exact 9:16 images, preserves the exact overlay text, and outputs finished slide frames plus a manifest
 - `render_video` turns explicit finished slide frames into an auto-advancing vertical MP4
+- when chaining operations, pass `result.renderVideoInput` from `create_slideshow` into `render_video` without re-encoding or HTML-escaping the slide URLs
 - reserves space for TikTok UI chrome at the top, right edge, and bottom caption area
 - keeps subjects away from edge crops and avoids cutting off faces, pets, hands, and products
 - prefers centered native-caption placement using image analysis first, with local fallback scoring
 - never uses a full paragraph wash behind captions; when enabled, text backgrounds render as tight chips around the words
 - restricts caption fonts and text background colors to the checked-in starter option lists in `src/style-options.ts`
 
+AI dependency contract for agents:
+
+- the current Vidfarm template standard does not have a first-class `dependencies` field, so this section is the authoritative dependency declaration for this template
+- `defaultProvider`, `textModel`, and `imageModel` are config values, not a validated provider-model matrix
+- agents should keep provider and model choices inside the combinations listed below unless they are intentionally extending runtime support
+
+Documented provider-model combinations for this template:
+
+- `openai`
+  models:
+  `image`: `gpt-image-1`, `gpt-image-2`
+  `text` and `layout_analysis`: `gpt-5.4`
+  planned but not wired here: `sora-2`
+- `gemini`
+  models:
+  `image`: `gemini-3.1-flash-image-preview`, `gemini-2.5-flash-image`
+  `text` and `layout_analysis`: `gemini-3.1-flash-lite`, `gemini-2.5-flash-lite`
+  planned but not wired here: `veo-3.0-generate-001`
+- `openrouter`
+  models:
+  `text` and `layout_analysis`: `qwen/qwen3.6-flash`
+  aspirational image models: `bytedance/seedance-2.0`, `bytedance-seed/seedream-4.5`
+
+Runtime caveats:
+
+- `openrouter` text and layout-analysis calls work through the OpenRouter chat-completions path
+- `openrouter` image generation is not a first-class adapter path in the current runtime, so do not assume `seedance-2.0` or `seedream-4.5` will work end to end without provider-runtime changes
+- OpenAI image generation in the current runtime does not support `image_prompt_attachments`; Gemini is the safest path when reference-image attachments matter
+- OpenAI image generation does not expose an exact native `9:16` output size in the current API. For `template_0000`, use portrait output plus explicit `9:16` framing instructions, then preserve composition with contain-plus-blur normalization instead of crop-zooming.
+- this template does not expose a video-generation operation, so `sora-2` and `veo-3.0-generate-001` are documented here for future dependency planning only
+
 Allowed caption fonts:
 
 - `source_code_pro`

package/templates/template_0000/src/lib/images.js

@@ -4,25 +4,60 @@ export async function normalizeToPortraitFrame(input, target = { width: 1080, he
     const oriented = sharp(buffer, { density: 144 }).rotate();
     const trimmed = await trimFlatBorders(oriented);
     const targetAspect = target.width / target.height;
-    // If the model already returned a near-native vertical frame, avoid the
-    // activity crop pass because it can misread low-detail edges as padding.
     const shouldPreserveFraming = await isCloseToAspect(trimmed, targetAspect, 0.025);
     const cropped = shouldPreserveFraming ? trimmed : await cropToActiveImageRegion(trimmed);
-    const portraitCrop = await cropToPortraitAspect(cropped, targetAspect);
-    const output = await portraitCrop
+    const normalized = await resizeWithBlurredContain(cropped, target, targetAspect);
+    return {
+        bytes: normalized,
+        contentType: "image/png",
+        width: target.width,
+        height: target.height
+    };
+}
+async function resizeWithBlurredContain(image, target, targetAspect) {
+    const metadata = await image.metadata();
+    const width = metadata.width ?? 0;
+    const height = metadata.height ?? 0;
+    if (!width || !height) {
+        return image
+            .resize(target.width, target.height, {
+            fit: "cover",
+            position: sharp.strategy.attention
+        })
+            .png()
+            .toBuffer();
+    }
+    const aspect = width / height;
+    if (Math.abs(aspect - targetAspect) <= 0.015) {
+        return image
+            .resize(target.width, target.height, {
+            fit: "fill"
+        })
+            .png()
+            .toBuffer();
+    }
+    const foreground = await image
+        .clone()
+        .resize(target.width, target.height, {
+        fit: "contain",
+        background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+        .png()
+        .toBuffer();
+    const background = await image
+        .clone()
         .resize(target.width, target.height, {
         fit: "cover",
         position: sharp.strategy.attention
     })
+        .blur(20)
+        .modulate({ brightness: 0.92, saturation: 0.9 })
+        .png()
+        .toBuffer();
+    return sharp(background)
+        .composite([{ input: foreground }])
         .png()
         .toBuffer();
-    const exact = await ensureExactPixelSize(output, target);
-    return {
-        bytes: exact,
-        contentType: "image/png",
-        width: target.width,
-        height: target.height
-    };
 }
 async function isCloseToAspect(image, targetAspect, tolerance) {
     const metadata = await image.metadata();
@@ -77,27 +112,6 @@ async function cropToActiveImageRegion(image) {
     const height = Math.min(sourceHeight - top, Math.max(1, Math.ceil((bounds.height / sampleHeight) * sourceHeight)));
     return image.extract({ left, top, width, height });
 }
-async function cropToPortraitAspect(image, targetAspect) {
-    const metadata = await image.metadata();
-    const sourceWidth = metadata.width ?? 0;
-    const sourceHeight = metadata.height ?? 0;
-    if (!sourceWidth || !sourceHeight) {
-        return image;
-    }
-    const sourceAspect = sourceWidth / sourceHeight;
-    if (Math.abs(sourceAspect - targetAspect) < 0.015) {
-        return image;
-    }
-    const focus = await detectFocusPoint(image, sourceWidth, sourceHeight);
-    if (sourceAspect > targetAspect) {
-        const cropWidth = Math.max(1, Math.min(sourceWidth, Math.round(sourceHeight * targetAspect)));
-        const left = clamp(Math.round(focus.x - cropWidth / 2), 0, sourceWidth - cropWidth);
-        return image.extract({ left, top: 0, width: cropWidth, height: sourceHeight });
-    }
-    const cropHeight = Math.max(1, Math.min(sourceHeight, Math.round(sourceWidth / targetAspect)));
-    const top = clamp(Math.round(focus.y - cropHeight / 2), 0, sourceHeight - cropHeight);
-    return image.extract({ left: 0, top, width: sourceWidth, height: cropHeight });
-}
 function detectActiveBounds(sample, width, height) {
     const rowActivity = new Array(height).fill(0);
     const colActivity = new Array(width).fill(0);
@@ -142,46 +156,6 @@ function detectActiveBounds(sample, width, height) {
         height: croppedHeight
     };
 }
-async function detectFocusPoint(image, sourceWidth, sourceHeight) {
-    const sampleWidth = 120;
-    const sampleHeight = Math.max(1, Math.round((sourceHeight / Math.max(sourceWidth, 1)) * sampleWidth));
-    const sample = await image
-        .clone()
-        .resize(sampleWidth, sampleHeight, { fit: "fill" })
-        .grayscale()
-        .raw()
-        .toBuffer();
-    let weightedX = 0;
-    let weightedY = 0;
-    let totalWeight = 0;
-    for (let y = 0; y < sampleHeight; y += 1) {
-        for (let x = 0; x < sampleWidth; x += 1) {
-            const index = y * sampleWidth + x;
-            const current = sample[index] ?? 0;
-            const left = x > 0 ? sample[index - 1] ?? current : current;
-            const up = y > 0 ? sample[index - sampleWidth] ?? current : current;
-            const right = x < sampleWidth - 1 ? sample[index + 1] ?? current : current;
-            const down = y < sampleHeight - 1 ? sample[index + sampleWidth] ?? current : current;
-            const energy = Math.abs(current - left) +
-                Math.abs(current - right) +
-                Math.abs(current - up) +
-                Math.abs(current - down);
-            const centerBiasX = 1 - Math.abs((x + 0.5) / sampleWidth - 0.5) * 0.45;
-            const centerBiasY = 1 - Math.abs((y + 0.5) / sampleHeight - 0.5) * 0.35;
-            const weight = Math.max(energy, 1) * centerBiasX * centerBiasY;
-            weightedX += (x + 0.5) * weight;
-            weightedY += (y + 0.5) * weight;
-            totalWeight += weight;
-        }
-    }
-    if (totalWeight <= 0) {
-        return { x: sourceWidth / 2, y: sourceHeight / 2 };
-    }
-    return {
-        x: (weightedX / totalWeight / sampleWidth) * sourceWidth,
-        y: (weightedY / totalWeight / sampleHeight) * sourceHeight
-    };
-}
 function findActiveRange(values, minSpan) {
     const mean = values.reduce((sum, value) => sum + value, 0) / Math.max(values.length, 1);
     const max = values.reduce((best, value) => Math.max(best, value), 0);
@@ -226,17 +200,3 @@ function smoothSeries(values, radius) {
 function clamp(value, min, max) {
     return Math.min(Math.max(value, min), max);
 }
-async function ensureExactPixelSize(input, target) {
-    const metadata = await sharp(input).metadata();
-    if (metadata.width === target.width && metadata.height === target.height) {
-        return input;
-    }
-    const exactCrop = await cropToPortraitAspect(sharp(input), target.width / target.height);
-    return exactCrop
-        .resize(target.width, target.height, {
-        fit: "cover",
-        position: sharp.strategy.attention
-    })
-        .png()
-        .toBuffer();
-}

package/templates/template_0000/src/lib/images.ts

@@ -8,26 +8,70 @@ export async function normalizeToPortraitFrame(
   const oriented = sharp(buffer, { density: 144 }).rotate();
   const trimmed = await trimFlatBorders(oriented);
   const targetAspect = target.width / target.height;
-  // If the model already returned a near-native vertical frame, avoid the
-  // activity crop pass because it can misread low-detail edges as padding.
   const shouldPreserveFraming = await isCloseToAspect(trimmed, targetAspect, 0.025);
   const cropped = shouldPreserveFraming ? trimmed : await cropToActiveImageRegion(trimmed);
-  const portraitCrop = await cropToPortraitAspect(cropped, targetAspect);
-  const output = await portraitCrop
+  const normalized = await resizeWithBlurredContain(cropped, target, targetAspect);
+
+  return {
+    bytes: normalized,
+    contentType: "image/png" as const,
+    width: target.width,
+    height: target.height
+  };
+}
+
+async function resizeWithBlurredContain(
+  image: sharp.Sharp,
+  target: { width: number; height: number },
+  targetAspect: number
+) {
+  const metadata = await image.metadata();
+  const width = metadata.width ?? 0;
+  const height = metadata.height ?? 0;
+  if (!width || !height) {
+    return image
+      .resize(target.width, target.height, {
+        fit: "cover",
+        position: sharp.strategy.attention
+      })
+      .png()
+      .toBuffer();
+  }
+
+  const aspect = width / height;
+  if (Math.abs(aspect - targetAspect) <= 0.015) {
+    return image
+      .resize(target.width, target.height, {
+        fit: "fill"
+      })
+      .png()
+      .toBuffer();
+  }
+
+  const foreground = await image
+    .clone()
+    .resize(target.width, target.height, {
+      fit: "contain",
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .png()
+    .toBuffer();
+
+  const background = await image
+    .clone()
     .resize(target.width, target.height, {
       fit: "cover",
       position: sharp.strategy.attention
     })
+    .blur(20)
+    .modulate({ brightness: 0.92, saturation: 0.9 })
     .png()
     .toBuffer();
-  const exact = await ensureExactPixelSize(output, target);
 
-  return {
-    bytes: exact,
-    contentType: "image/png" as const,
-    width: target.width,
-    height: target.height
-  };
+  return sharp(background)
+    .composite([{ input: foreground }])
+    .png()
+    .toBuffer();
 }
 
 async function isCloseToAspect(image: sharp.Sharp, targetAspect: number, tolerance: number) {
@@ -93,31 +137,6 @@ async function cropToActiveImageRegion(image: sharp.Sharp) {
   return image.extract({ left, top, width, height });
 }
 
-async function cropToPortraitAspect(image: sharp.Sharp, targetAspect: number) {
-  const metadata = await image.metadata();
-  const sourceWidth = metadata.width ?? 0;
-  const sourceHeight = metadata.height ?? 0;
-  if (!sourceWidth || !sourceHeight) {
-    return image;
-  }
-
-  const sourceAspect = sourceWidth / sourceHeight;
-  if (Math.abs(sourceAspect - targetAspect) < 0.015) {
-    return image;
-  }
-
-  const focus = await detectFocusPoint(image, sourceWidth, sourceHeight);
-  if (sourceAspect > targetAspect) {
-    const cropWidth = Math.max(1, Math.min(sourceWidth, Math.round(sourceHeight * targetAspect)));
-    const left = clamp(Math.round(focus.x - cropWidth / 2), 0, sourceWidth - cropWidth);
-    return image.extract({ left, top: 0, width: cropWidth, height: sourceHeight });
-  }
-
-  const cropHeight = Math.max(1, Math.min(sourceHeight, Math.round(sourceWidth / targetAspect)));
-  const top = clamp(Math.round(focus.y - cropHeight / 2), 0, sourceHeight - cropHeight);
-  return image.extract({ left: 0, top, width: sourceWidth, height: cropHeight });
-}
-
 function detectActiveBounds(sample: Buffer, width: number, height: number) {
   const rowActivity = new Array<number>(height).fill(0);
   const colActivity = new Array<number>(width).fill(0);
@@ -170,52 +189,6 @@ function detectActiveBounds(sample: Buffer, width: number, height: number) {
   };
 }
 
-async function detectFocusPoint(image: sharp.Sharp, sourceWidth: number, sourceHeight: number) {
-  const sampleWidth = 120;
-  const sampleHeight = Math.max(1, Math.round((sourceHeight / Math.max(sourceWidth, 1)) * sampleWidth));
-  const sample = await image
-    .clone()
-    .resize(sampleWidth, sampleHeight, { fit: "fill" })
-    .grayscale()
-    .raw()
-    .toBuffer();
-
-  let weightedX = 0;
-  let weightedY = 0;
-  let totalWeight = 0;
-
-  for (let y = 0; y < sampleHeight; y += 1) {
-    for (let x = 0; x < sampleWidth; x += 1) {
-      const index = y * sampleWidth + x;
-      const current = sample[index] ?? 0;
-      const left = x > 0 ? sample[index - 1] ?? current : current;
-      const up = y > 0 ? sample[index - sampleWidth] ?? current : current;
-      const right = x < sampleWidth - 1 ? sample[index + 1] ?? current : current;
-      const down = y < sampleHeight - 1 ? sample[index + sampleWidth] ?? current : current;
-      const energy =
-        Math.abs(current - left) +
-        Math.abs(current - right) +
-        Math.abs(current - up) +
-        Math.abs(current - down);
-      const centerBiasX = 1 - Math.abs((x + 0.5) / sampleWidth - 0.5) * 0.45;
-      const centerBiasY = 1 - Math.abs((y + 0.5) / sampleHeight - 0.5) * 0.35;
-      const weight = Math.max(energy, 1) * centerBiasX * centerBiasY;
-      weightedX += (x + 0.5) * weight;
-      weightedY += (y + 0.5) * weight;
-      totalWeight += weight;
-    }
-  }
-
-  if (totalWeight <= 0) {
-    return { x: sourceWidth / 2, y: sourceHeight / 2 };
-  }
-
-  return {
-    x: (weightedX / totalWeight / sampleWidth) * sourceWidth,
-    y: (weightedY / totalWeight / sampleHeight) * sourceHeight
-  };
-}
-
 function findActiveRange(values: number[], minSpan: number) {
   const mean = values.reduce((sum, value) => sum + value, 0) / Math.max(values.length, 1);
   const max = values.reduce((best, value) => Math.max(best, value), 0);
@@ -266,19 +239,3 @@ function smoothSeries(values: number[], radius: number) {
 function clamp(value: number, min: number, max: number) {
   return Math.min(Math.max(value, min), max);
 }
-
-async function ensureExactPixelSize(input: Buffer, target: { width: number; height: number }) {
-  const metadata = await sharp(input).metadata();
-  if (metadata.width === target.width && metadata.height === target.height) {
-    return input;
-  }
-
-  const exactCrop = await cropToPortraitAspect(sharp(input), target.width / target.height);
-  return exactCrop
-    .resize(target.width, target.height, {
-      fit: "cover",
-      position: sharp.strategy.attention
-    })
-    .png()
-    .toBuffer();
-}

package/templates/template_0000/src/template-dna.js

@@ -0,0 +1,9 @@
+// Generated by `vidfarm analyze-viral-dna` and `vidfarm analyze-visual-dna`.
+// Keep source notes in `research/source_notes.md` and reference media in `research/preview/`.
+export const templateLinkToOriginal = "";
+export const templateSourceNotesPath = "research/source_notes.md";
+export const templatePreviewMediaRelativePaths = [];
+export const templateViralDna = "Run `vidfarm analyze-viral-dna --template-dir .` after adding source notes and preview media.";
+export const templateVisualDna = "Run `vidfarm analyze-visual-dna --template-dir .` after adding source notes and preview media.";
+export const templateViralDnaAnalysis = null;
+export const templateVisualDnaAnalysis = null;