@mevdragon/vidfarm-devcli 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Developer CLI for running the Vidfarm local template platform.",
   "type": "module",
   "bin": {
@@ -8,13 +8,12 @@
     "vidfarm-devcli": "dist/src/cli.js"
   },
   "files": [
-    "dist",
+    "dist/src",
+    "dist/templates/template_0000",
     "templates/template_0000",
     "README.md",
-    "SKILL.director.md",
     "SKILL.developer.md",
-    "PLATFORM_SPEC.md",
-    "AWS_REMOTION_HANDOFF.md",
+    "GETTING_STARTED.developers.md",
     ".env.example"
   ],
   "publishConfig": {
@@ -22,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

@@ -2,12 +2,12 @@
 
 Standalone GitHub-distributable package for the Vidfarm `template_0000` starter template.
 
-This package exists for two operational reasons:
+This package exists to give third-party developers a concrete example of the Vidfarm template contract.
 
-- keep the template code in its own private GitHub repo for manual admin review/import
-- preserve the exact checked-in config and build shape the release admin will later promote to shared Remotion AWS and the production Docker image
+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.
 
-Developers should treat this repo as an authoring and review unit, not as an authorized deployment unit.
+When a template is ready, it is handed off for Vidfarm admin review and approval before it becomes available on the hosted platform.
 
 Every new template should keep its source-format research checked in:
 
@@ -15,33 +15,21 @@ Every new template should keep its source-format research checked in:
 - `research/preview/` for the screenshots or source video the DNA analyzers inspect
 - `src/template-dna.ts` for the generated viral and visual DNA that feed the published template metadata
 
-The production release flow is:
-
-1. developer pushes template code to GitHub
-2. admin reviews the repo and selects a commit from `production`
-3. admin publishes the approved Remotion site bundle to shared AWS
-4. admin imports and activates the approved commit in Vidfarm
-5. admin rebuilds and redeploys the production Docker image
-
-Template authors do not publish directly to shared Remotion Lambda and do not directly promote templates into production Docker.
-
 Production integration settings are checked into `template.config.json`. AI agents and developers should treat that file as the source of truth for:
 
 - project identity
 - `template_id` as the self-issued UUIDv4 platform identifier
 - `slug_id` as the human-readable stable slug
-- GitHub repo target
-- production source branch
-- Remotion region/function/bucket/site/composition settings
-- release control expectations for admin promotion
+- 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
 
 - `SKILL.md` for customer AI-agent usage
 - `src/template.ts` for the Vidfarm platform contract
-- `src/remotion/*` for local and cloud video rendering
+- `src/remotion/*` for local video rendering
 - `src/lib/images.ts` for non-cropping portrait normalization
-- `composition.json` sample props for cloud render smoke tests
+- `composition.json` sample props for local render tests
 
 ## Template behavior
 
@@ -87,35 +75,3 @@ vidfarm analyze-visual-dna --template-dir .
 ```
 
 If you scaffold a template with `vidfarm generate-template` and provide `--source-preview-dir`, the CLI will run both analyzers automatically unless `--skip-dna-analysis` is set.
-
-## Shared Remotion AWS
-
-Expected shared infra:
-
-- region: stored in `template.config.json`
-- function: stored in `template.config.json`
-- bucket: stored in `template.config.json`
-
-The only runtime secrets expected from the execution environment are AWS credentials. The production Remotion topology is intentionally checked into `template.config.json`, not spread across `.env` values.
-
-These shared-AWS operations are release-admin tasks. Template developers should not run them against the shared production AWS account.
-
-Release admin create-site:
-
-```bash
-npm run admin:create-site
-```
-
-Release admin cloud render smoke test:
-
-```bash
-npm run admin:render:cloud
-```
-
-Release admin cloud render from a real stage-1 manifest:
-
-```bash
-npm run admin:render:cloud -- --manifest /abs/path/to/template-0000.json
-```
-
-Use the manifest mode when you want the cloud render verification to include the actual composited slide frames with text overlays, not just the static sample props.

package/templates/template_0000/SKILL.md

@@ -5,8 +5,8 @@ Use this template when the customer wants a fast vertical slideshow for TikTok-s
 Operational rule:
 
 - template developers author and test this template locally
-- only the release admin publishes the approved Remotion site bundle to shared AWS
-- only the release admin promotes the approved template into production Docker
+- the hosted platform later runs the approved template behind the standard Vidfarm API wrapper
+- a Vidfarm admin reviews and approves the template before it is made available in production
 
 Inputs:
 
@@ -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`
@@ -51,7 +83,7 @@ Allowed text background colors:
 - `light_gray`
 - `dark_gray`
 
-REST API routes for this template:
+Typical routes for this template:
 
 - `GET /templates/template_0000`
 - `GET /templates/template_0000/skill`

package/templates/template_0000/package.json

@@ -2,19 +2,16 @@
   "name": "vidfarm_template_0000",
   "version": "1.0.0",
   "private": true,
-  "description": "Standalone Vidfarm template_0000 project for authoring, admin review, and controlled production promotion.",
+  "description": "Standalone Vidfarm template_0000 starter project for local template authoring.",
   "type": "module",
   "scripts": {
     "check": "tsc -p tsconfig.json --noEmit",
     "build": "tsc -p tsconfig.json",
-    "studio": "remotion studio src/remotion/index.tsx",
-    "admin:create-site": "node ./scripts/create-site.mjs",
-    "admin:render:cloud": "node ./scripts/render-cloud.mjs"
+    "studio": "remotion studio src/remotion/index.tsx"
   },
   "dependencies": {
     "@remotion/bundler": "4.0.355",
     "@remotion/cli": "4.0.355",
-    "@remotion/lambda": "4.0.355",
     "@remotion/renderer": "4.0.355",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
@@ -22,7 +19,7 @@
     "sharp": "^0.34.2"
   },
   "devDependencies": {
-    "@mevdragon/vidfarm-devcli": "^0.2.0",
+    "@mevdragon/vidfarm-devcli": "^0.2.2",
     "@types/node": "^24.0.1",
     "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",

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;