@mevdragon/vidfarm-devcli 0.1.0 → 0.2.0

package/templates/template_0000/src/template.ts

@@ -0,0 +1,1747 @@
+import { z } from "zod";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import sharp from "sharp";
+import { normalizeToPortraitFrame } from "./lib/images.js";
+import {
+  defineTemplate,
+  type ProviderType,
+  type TemplateJobContext,
+} from "./sdk.js";
+import {
+  TEMPLATE_FONT_IDS,
+  TEMPLATE_FONT_OPTIONS,
+  TEMPLATE_TEXT_BACKGROUND_COLOR_IDS,
+  TEMPLATE_TEXT_BACKGROUND_COLOR_OPTIONS,
+  type TemplateFontId,
+  type TemplateTextBackgroundColorId,
+} from "./style-options.js";
+import { templateLinkToOriginal, templateVisualDna, templateViralDna } from "./template-dna.js";
+
+const TEMPLATE_ID = "4c7a7e1a-7f35-4f30-9f86-9c8a63c7f2db";
+const TEMPLATE_SLUG_ID = "template_0000";
+const COMPOSITION_ID = "template-0000";
+const TEMPLATE_PREVIEW_MEDIA = [
+  "https://vidfarmprodstack-vidfarmbucket335ee12f-0vsvtd5earqy.s3.us-east-1.amazonaws.com/templates/template-0000/about/preview-01.jpg",
+] as const;
+const FRAME = { width: 1080, height: 1920 } as const;
+const TIKTOK_SAFE_AREA = {
+  left: 78,
+  right: 248,
+  top: 196,
+  bottom: 408,
+} as const;
+const NATIVE_UI_TEXT_ZONE = {
+  minCenterXPercent: 0.38,
+  maxCenterXPercent: 0.62,
+  minCenterYPercent: 0.2,
+  maxCenterYPercent: 0.58,
+} as const;
+const TEXT_BACKGROUND_NONE = "none" as const;
+
+const legacySlideInputSchema = z.union([
+  z.tuple([z.string().min(3), z.string().min(1)]),
+  z.tuple([
+    z.string().min(3),
+    z.string().min(1),
+    z.number().int().min(500).max(30000),
+  ]),
+]);
+const structuredSlideInputSchema = z.object({
+  image_prompt: z.string().min(3),
+  image_prompt_attachments: z.array(z.string().url()).max(12).default([]),
+  caption: z.string().min(1),
+  duration_ms: z.number().int().min(500).max(30000).default(4000),
+});
+const slideInputSchema = z.union([
+  legacySlideInputSchema,
+  structuredSlideInputSchema,
+]);
+const createSlideshowInputSchema = z.object({
+  slides: z.array(slideInputSchema).min(1).max(20),
+  meta_details_prompt: z.string().min(8).max(4000).optional(),
+});
+const renderSlideSchema = z.object({
+  imageUrl: z.string().url(),
+  durationMs: z.number().int().min(500).max(30000),
+});
+const renderVideoInputSchema = z.object({
+  slides: z.array(renderSlideSchema).min(1).max(20),
+});
+const supportedImageProviders = ["openai", "gemini", "openrouter"] as const;
+type ImageProvider = (typeof supportedImageProviders)[number];
+
+type Layout = {
+  zone: "top" | "center" | "bottom";
+  align: "left" | "center" | "right";
+  maxWidthPercent: number;
+  anchorXPercent?: number;
+  anchorYPercent?: number;
+  justification: string;
+};
+
+type SlideOutput = {
+  index: number;
+  imagePrompt: string;
+  imagePromptAttachments: string[];
+  overlayText: string;
+  durationMs: number;
+  backgroundImageUrl: string | null;
+  frameImageUrl: string | null;
+  prompt: string;
+  revisedPrompt: string | null;
+  layout: Layout;
+};
+
+type MetaDetails = {
+  title: string;
+  description: string;
+  pinned_comment: string;
+  location: string;
+  song: string;
+};
+
+type TextStyleSpec = {
+  fontId: TemplateFontId;
+  fontFamily: string;
+  backgroundColorId:
+    | TemplateTextBackgroundColorId
+    | typeof TEXT_BACKGROUND_NONE;
+  backgroundColorHex: string | null;
+};
+
+type SlideshowManifest = {
+  templateId: string;
+  size: { width: number; height: number; aspectRatio: "9:16" };
+  textStyle: {
+    fontId: TemplateFontId;
+    fontFamily: string;
+    fill: string;
+    backgroundColorId:
+      | TemplateTextBackgroundColorId
+      | typeof TEXT_BACKGROUND_NONE;
+    backgroundColorHex: string | null;
+    shadow: string;
+    availableFonts: typeof TEMPLATE_FONT_OPTIONS;
+    availableBackgroundColors: typeof TEMPLATE_TEXT_BACKGROUND_COLOR_OPTIONS;
+  };
+  safeArea: typeof TIKTOK_SAFE_AREA;
+  metaDetails: MetaDetails;
+  slides: SlideOutput[];
+};
+
+const remotionEntryPoint = resolveRemotionEntryPoint();
+const templateRuntimeConfig = resolveTemplateRuntimeConfig();
+const remotionRuntimeConfig = {
+  serveUrl: templateRuntimeConfig.remotion?.serve_url ?? undefined,
+};
+const skillPath = resolveSkillPath();
+const overlayFonts = resolveOverlayFonts();
+
+export const template0000Definition = defineTemplate({
+  id: TEMPLATE_ID,
+  slugId: TEMPLATE_SLUG_ID,
+  version: "1.0.0",
+  about: {
+    title: "Template 0000",
+    description:
+      "Starter TikTok-safe slideshow template with staged image generation, text compositing, and optional Remotion video rendering.",
+    viral_dna: templateViralDna,
+    visual_dna: templateVisualDna,
+    preview_media: [...TEMPLATE_PREVIEW_MEDIA],
+    link_to_original: templateLinkToOriginal,
+  },
+  skillPath,
+  configSchema: z.object({
+    defaultProvider: z.enum(supportedImageProviders).default("gemini"),
+    textModel: z.string().optional(),
+    imageModel: z.string().optional(),
+    captionFont: z.enum(TEMPLATE_FONT_IDS).default("montserrat"),
+    captionBackgroundColor: z
+      .enum([TEXT_BACKGROUND_NONE, ...TEMPLATE_TEXT_BACKGROUND_COLOR_IDS])
+      .default(TEXT_BACKGROUND_NONE),
+    renderCompositionId: z.string().default(COMPOSITION_ID),
+  }),
+  operations: {
+    create_slideshow: {
+      description:
+        "Generate TikTok-safe 9:16 background images, composite the exact overlay text into finished slide frames, and save a manifest.",
+      inputSchema: createSlideshowInputSchema,
+      workflow: "createSlideshowWorkflow",
+      webhookSupport: true,
+      smokeTestPayload: {
+        slides: [
+          ["a founder at a desk", "Launch faster", 2400],
+          {
+            image_prompt: "close-up product photo",
+            image_prompt_attachments: [
+              "https://images.unsplash.com/photo-1520607162513-77705c0f0d4a?auto=format&fit=crop&w=1080&q=80",
+            ],
+            caption: "Built in-house",
+            duration_ms: 3200,
+          },
+        ],
+        meta_details_prompt:
+          "Target US TikTok skincare and startup audiences. Make the hook curiosity-driven, natural, and UGC-native.",
+      },
+    },
+    render_video: {
+      description:
+        "Turn finished slideshow frames into an auto-advancing vertical video using Remotion.",
+      inputSchema: renderVideoInputSchema,
+      workflow: "renderVideoWorkflow",
+      webhookSupport: true,
+      smokeTestPayload: {
+        slides: [
+          {
+            imageUrl:
+              "https://images.unsplash.com/photo-1519389950473-47ba0277781c?auto=format&fit=crop&w=1080&q=80",
+            durationMs: 2400,
+          },
+          {
+            imageUrl:
+              "https://images.unsplash.com/photo-1520607162513-77705c0f0d4a?auto=format&fit=crop&w=1080&q=80",
+            durationMs: 3200,
+          },
+        ],
+      },
+    },
+  },
+  jobs: {
+    async createSlideshowWorkflow(ctx, input) {
+      const payload = createSlideshowInputSchema.parse(input);
+      ctx.logger.progress(0.04, "Starting template_0000 slideshow image stage");
+      const provider = parseImageProvider(ctx.templateConfig.defaultProvider);
+      const textModel = String(
+        ctx.templateConfig.textModel ?? defaultTextModelForProvider(provider),
+      );
+      const imageModel = String(
+        ctx.templateConfig.imageModel ?? defaultImageModelForProvider(provider),
+      );
+      const textStyle = resolveTextStyleSpec(ctx.templateConfig);
+
+      const slides: SlideOutput[] = [];
+      for (const [index, rawSlide] of payload.slides.entries()) {
+        const { imagePrompt, imagePromptAttachments, overlayText, durationMs } =
+          normalizeSlideInput(rawSlide);
+        ctx.logger.progress(
+          0.08 + (index / payload.slides.length) * 0.42,
+          `Generating slide ${index + 1} image`,
+        );
+        const image = await generatePortraitCandidateImage(ctx, {
+          provider,
+          imageModel,
+          imagePrompt,
+          imagePromptAttachments,
+          overlayText,
+        });
+        await ctx.billing.record({
+          type: "ai_generation",
+          costUsd: 0.04,
+          metadata: {
+            stage: "image_generation",
+            slideIndex: index,
+            model: imageModel,
+          },
+        });
+
+        ctx.logger.progress(
+          0.13 + (index / payload.slides.length) * 0.3,
+          `Normalizing slide ${index + 1} to strict 9:16 portrait`,
+        );
+        const normalizedImage = await normalizeToPortraitFrame(
+          image.bytes,
+          FRAME,
+        );
+
+        const backgroundArtifact = await ctx.storage.putBuffer(
+          `backgrounds/slide-${pad2(index + 1)}.png`,
+          normalizedImage.bytes,
+          {
+            contentType: normalizedImage.contentType,
+            kind: "image",
+            metadata: {
+              slideIndex: index,
+              prompt: image.prompt,
+              revisedPrompt: image.revisedPrompt,
+              width: normalizedImage.width,
+              height: normalizedImage.height,
+              aspectRatio: "9:16",
+            },
+          },
+        );
+
+        ctx.logger.progress(
+          0.18 + (index / payload.slides.length) * 0.28,
+          `Scoring TikTok-safe text layout for slide ${index + 1}`,
+        );
+        const layout = await chooseSlideLayout(ctx, {
+          provider,
+          model: textModel,
+          imageBytes: normalizedImage.bytes,
+          imageUrl: backgroundArtifact.url,
+          overlayText,
+        });
+
+        ctx.logger.progress(
+          0.24 + (index / payload.slides.length) * 0.28,
+          `Compositing caption into slide ${index + 1}`,
+        );
+        const frameBytes = await renderFinishedSlide(
+          normalizedImage.bytes,
+          overlayText,
+          layout,
+          textStyle,
+        );
+        const frameArtifact = await ctx.storage.putBuffer(
+          `slides/slide-${pad2(index + 1)}.png`,
+          frameBytes,
+          {
+            contentType: "image/png",
+            kind: "image",
+            metadata: {
+              slideIndex: index,
+              overlayText,
+              layout,
+              aspectRatio: "9:16",
+              kind: "finished_slide_frame",
+            },
+          },
+        );
+
+        slides.push({
+          index,
+          imagePrompt,
+          imagePromptAttachments,
+          overlayText,
+          durationMs,
+          backgroundImageUrl: backgroundArtifact.url,
+          frameImageUrl: frameArtifact.url,
+          prompt: image.prompt,
+          revisedPrompt: image.revisedPrompt,
+          layout,
+        });
+      }
+
+      ctx.logger.progress(0.72, "Generating post metadata");
+      const metaDetails = await generateMetaDetails(ctx, {
+        provider,
+        textModel,
+        slides,
+        metaDetailsPrompt: payload.meta_details_prompt,
+      });
+      await ctx.billing.record({
+        type: "ai_generation",
+        costUsd: 0.01,
+        metadata: { stage: "meta_details_generation", model: textModel },
+      });
+
+      ctx.logger.progress(0.78, "Saving slideshow manifest");
+      const manifest: SlideshowManifest = {
+        templateId: TEMPLATE_ID,
+        size: { width: FRAME.width, height: FRAME.height, aspectRatio: "9:16" },
+        textStyle: {
+          fontId: textStyle.fontId,
+          fontFamily: textStyle.fontFamily,
+          fill: "#ffffff",
+          backgroundColorId: textStyle.backgroundColorId,
+          backgroundColorHex: textStyle.backgroundColorHex,
+          shadow: "soft native TikTok-style black drop shadow",
+          availableFonts: TEMPLATE_FONT_OPTIONS,
+          availableBackgroundColors: TEMPLATE_TEXT_BACKGROUND_COLOR_OPTIONS,
+        },
+        safeArea: TIKTOK_SAFE_AREA,
+        metaDetails,
+        slides,
+      };
+      const manifestArtifact = await ctx.storage.putJson(
+        `manifests/${TEMPLATE_ID}.json`,
+        manifest,
+      );
+      const files = slides
+        .flatMap((slide) => [slide.backgroundImageUrl, slide.frameImageUrl])
+        .filter((value): value is string => Boolean(value));
+      if (manifestArtifact.url) {
+        files.push(manifestArtifact.url);
+      }
+
+      ctx.logger.progress(1, "Slideshow images complete", {
+        fileCount: files.length,
+      });
+
+      return {
+        progress: 1,
+        output: {
+          files,
+          manifest: manifestArtifact,
+          ...metaDetails,
+          metaDetails,
+          metaDetailsInput: {
+            meta_details_prompt: payload.meta_details_prompt ?? null,
+            slides: slides.map((slide) => ({
+              index: slide.index,
+              imagePrompt: slide.imagePrompt,
+              imagePromptAttachments: slide.imagePromptAttachments,
+              overlayText: slide.overlayText,
+              durationMs: slide.durationMs,
+            })),
+          },
+          renderVideoInput: {
+            slides: slides
+              .map((slide) =>
+                slide.frameImageUrl
+                  ? {
+                      imageUrl: slide.frameImageUrl,
+                      durationMs: slide.durationMs,
+                    }
+                  : null,
+              )
+              .filter(
+                (slide): slide is { imageUrl: string; durationMs: number } =>
+                  Boolean(slide),
+              ),
+          },
+          slides,
+        },
+      };
+    },
+    async renderVideoWorkflow(ctx, input) {
+      const payload = renderVideoInputSchema.parse(input);
+      const compositionId = String(
+        ctx.templateConfig.renderCompositionId ?? COMPOSITION_ID,
+      );
+      ctx.logger.progress(0.08, "Preparing slideshow frames for video render");
+      const slides = await resolveSlidesForRender(payload);
+
+      ctx.logger.progress(0.56, "Submitting Remotion render");
+      const render = await ctx.remotion.render({
+        compositionId,
+        serveUrl: remotionRuntimeConfig.serveUrl,
+        entryPoint: remotionEntryPoint,
+        outputKey: "renders/final.mp4",
+        inputProps: {
+          slides,
+          fps: 30,
+        },
+      });
+      await ctx.billing.record({
+        type: "render",
+        costUsd: 0.35,
+        metadata: render.metadata,
+      });
+
+      const files = slides.map((slide) => slide.imageUrl);
+      if (render.outputUrl) {
+        files.push(render.outputUrl);
+      }
+
+      ctx.logger.progress(1, "Slideshow video complete", {
+        fileCount: files.length,
+        renderId: render.renderId,
+      });
+
+      return {
+        progress: 1,
+        output: {
+          files,
+          render,
+          slides,
+        },
+      };
+    },
+  },
+});
+
+const IMAGE_PROMPT_SYSTEM_WRAPPER = [
+  "Create an exact 9:16 portrait slideshow image for a TikTok-style vertical video.",
+  "The composition must be designed for strict full-frame mobile portrait output at 1080x1920.",
+  "Hold the camera vertically. The generated image itself must be tall portrait, not a landscape image placed inside a vertical canvas.",
+  "Return only the background scene or subject image. This is not a phone screenshot, social app mockup, or UI composition.",
+  "Do not produce square, landscape, or loose portrait framing.",
+  "Do not letterbox, pillarbox, add borders, or leave empty margins.",
+  "Crop tighter if needed so the frame reads as a native vertical shot. Avoid fake poster framing, inset postcards, or giant blank padding.",
+  "Do not sacrifice the vertical composition just to keep the entire subject visible.",
+  "Leave less important negative space near the top edge, right edge, and lower portion of the frame so later video overlays can sit there without covering the subject.",
+  "Keep the right edge visually quieter and avoid placing important details there.",
+  "Keep the top edge visually quieter and avoid placing important details there.",
+  "Keep the lower portion visually quieter and avoid placing important details there.",
+  "Reserve one clean editorial text lane in the upper-left or center-left portion of the frame for the overlay.",
+  "That reserved lane is empty space only. Do not render the overlay or any placeholder text.",
+  "Do not render any phone UI, social media UI, app chrome, search bars, tabs, buttons, likes, comments, avatars, battery icons, status bars, frames, stickers, or interface elements.",
+  "Do not render any words, letters, captions, subtitles, titles, logos, signage, labels, watermarks, or typography inside the image.",
+  "The final image must contain zero visible text unless part of the scene itself.",
+  "Use cinematic lighting, crisp detail, and framing that already fits an exact 9:16 portrait frame, unless otherwise specified.",
+  "Avoid giant blank ceiling, wall, floor, or sky bands that make the frame feel padded or zoomed out.",
+].join("\n");
+
+function buildImagePrompt(
+  imagePrompt: string,
+  overlayText: string,
+  imagePromptAttachments: string[] = [],
+) {
+  return [
+    IMAGE_PROMPT_SYSTEM_WRAPPER,
+    `User visual prompt: ${imagePrompt}`,
+    ...(imagePromptAttachments.length
+      ? [
+          `Use the attached reference media as visual guidance for subject matter, style, composition, or product details, but still return one fresh final image.`,
+        ]
+      : []),
+    `Reserve room for a short editorial overlay approximately ${overlayText.length} characters long, but do not render the overlay text itself.`,
+  ].join("\n");
+}
+
+async function generatePortraitCandidateImage(
+  ctx: Parameters<
+    typeof template0000Definition.jobs.createSlideshowWorkflow
+  >[0],
+  input: {
+    provider: ImageProvider;
+    imageModel: string;
+    imagePrompt: string;
+    imagePromptAttachments: string[];
+    overlayText: string;
+  },
+) {
+  const attempts = [
+    buildImagePrompt(
+      input.imagePrompt,
+      input.overlayText,
+      input.imagePromptAttachments,
+    ),
+    [
+      buildImagePrompt(
+        input.imagePrompt,
+        input.overlayText,
+        input.imagePromptAttachments,
+      ),
+      "Critical correction: the previous output risked being too wide.",
+      "Return a true full-frame mobile portrait composition.",
+      "Do not create a landscape scene floating inside a vertical canvas.",
+      "The subject and horizon should already be composed for 9:16 viewing.",
+      "Tighter framing is preferred over wide empty margins.",
+    ].join("\n"),
+    [
+      buildImagePrompt(
+        input.imagePrompt,
+        input.overlayText,
+        input.imagePromptAttachments,
+      ),
+      "Critical correction: return an unmistakably vertical composition.",
+      "Push the camera closer if needed so the frame reads as native 9:16 portrait.",
+      "No inset landscape window, no postcard composition, no wide aerial framing.",
+      "Use a clean magazine-style composition with one obvious text lane.",
+    ].join("\n"),
+    [
+      buildImagePrompt(
+        input.imagePrompt,
+        input.overlayText,
+        input.imagePromptAttachments,
+      ),
+      "Critical correction: the previous output likely had empty padding or weak mobile framing.",
+      "Fill the frame with a real handheld-phone portrait composition.",
+      "No white bars, no blank top or bottom bands, and no subject floating in the middle of excess space.",
+      "Crop decisively and favor a native social-video camera distance.",
+    ].join("\n"),
+  ];
+
+  let best: {
+    bytes: Uint8Array;
+    contentType: string;
+    revisedPrompt: string | null;
+    prompt: string;
+    score: number;
+  } | null = null;
+
+  for (const prompt of attempts) {
+    const image = await ctx.providers.generateImage({
+      provider: input.provider,
+      model: input.imageModel,
+      prompt,
+      promptAttachments: input.imagePromptAttachments,
+      size: sourceImageSizeForProvider(input.provider),
+      aspectRatio: "9:16",
+      imageSize: sourceImageOutputSizeForProvider(
+        input.provider,
+        input.imageModel,
+      ),
+    });
+    const score = await portraitScore(image.bytes);
+    if (!best || score < best.score) {
+      best = { ...image, prompt, score };
+    }
+    if (score <= 0.16) {
+      break;
+    }
+  }
+
+  if (!best) {
+    throw new Error("No image candidate was generated.");
+  }
+
+  return best;
+}
+
+function defaultLayout(): Layout {
+  return {
+    zone: "center",
+    align: "center",
+    maxWidthPercent: 58,
+    anchorXPercent: 0.5,
+    anchorYPercent: 0.28,
+    justification:
+      "Default placement uses a centered TikTok-native text zone in the middle third of the safe frame.",
+  };
+}
+
+function parseImageProvider(value: unknown): ImageProvider {
+  if (typeof value === "string" && isImageProvider(value)) {
+    return value;
+  }
+  return "gemini";
+}
+
+function isImageProvider(value: unknown): value is ImageProvider {
+  return (
+    typeof value === "string" &&
+    supportedImageProviders.includes(value as ImageProvider)
+  );
+}
+
+function sourceImageSizeForProvider(provider: ImageProvider) {
+  if (provider === "openai") {
+    return "1024x1792";
+  }
+  return "1080x1920";
+}
+
+function defaultImageModelForProvider(provider: ImageProvider) {
+  if (provider === "openai") {
+    return "gpt-image-1";
+  }
+  if (provider === "openrouter") {
+    return "bytedance-seed/seedream-4.5";
+  }
+  return "gemini-3.1-flash-image-preview";
+}
+
+function defaultTextModelForProvider(provider: ImageProvider) {
+  if (provider === "openai") {
+    return "gpt-4.1-mini";
+  }
+  if (provider === "openrouter") {
+    return "openai/gpt-4.1-mini";
+  }
+  return "gemini-3.1-flash-lite";
+}
+
+function sourceImageOutputSizeForProvider(
+  provider: ImageProvider,
+  model: string,
+) {
+  if (provider === "openrouter") {
+    return "2K" as const;
+  }
+  if (provider !== "gemini") {
+    return undefined;
+  }
+  if (
+    model === "gemini-3.1-flash-image-preview" ||
+    model === "gemini-3-pro-image-preview"
+  ) {
+    return "1K" as const;
+  }
+  return undefined;
+}
+
+function resolveTextStyleSpec(config: Record<string, unknown>): TextStyleSpec {
+  const fontId = isTemplateFontId(config.captionFont)
+    ? config.captionFont
+    : "montserrat";
+  const backgroundColorId =
+    config.captionBackgroundColor === TEXT_BACKGROUND_NONE ||
+    isTemplateBackgroundColorId(config.captionBackgroundColor)
+      ? config.captionBackgroundColor
+      : TEXT_BACKGROUND_NONE;
+  const fontOption =
+    TEMPLATE_FONT_OPTIONS.find((option) => option.id === fontId) ??
+    TEMPLATE_FONT_OPTIONS[1];
+  const backgroundOption =
+    backgroundColorId && backgroundColorId !== TEXT_BACKGROUND_NONE
+      ? (TEMPLATE_TEXT_BACKGROUND_COLOR_OPTIONS.find(
+          (option) => option.id === backgroundColorId,
+        ) ?? null)
+      : null;
+
+  return {
+    fontId,
+    fontFamily: fontOption.family,
+    backgroundColorId: backgroundColorId ?? TEXT_BACKGROUND_NONE,
+    backgroundColorHex: backgroundOption?.hex ?? null,
+  };
+}
+
+function isTemplateFontId(value: unknown): value is TemplateFontId {
+  return (
+    typeof value === "string" &&
+    TEMPLATE_FONT_IDS.includes(value as TemplateFontId)
+  );
+}
+
+function isTemplateBackgroundColorId(
+  value: unknown,
+): value is TemplateTextBackgroundColorId {
+  return (
+    typeof value === "string" &&
+    TEMPLATE_TEXT_BACKGROUND_COLOR_IDS.includes(
+      value as TemplateTextBackgroundColorId,
+    )
+  );
+}
+
+function pad2(value: number) {
+  return String(value).padStart(2, "0");
+}
+
+async function resolveSlidesForRender(
+  input: z.infer<typeof renderVideoInputSchema>,
+) {
+  return input.slides;
+}
+
+const slideshowManifestSchema = z.object({
+  templateId: z.string(),
+  size: z.object({
+    width: z.number(),
+    height: z.number(),
+    aspectRatio: z.literal("9:16"),
+  }),
+  textStyle: z.object({
+    fontId: z.enum(TEMPLATE_FONT_IDS),
+    fontFamily: z.string(),
+    fill: z.string(),
+    backgroundColorId: z.enum([
+      TEXT_BACKGROUND_NONE,
+      ...TEMPLATE_TEXT_BACKGROUND_COLOR_IDS,
+    ]),
+    backgroundColorHex: z.string().nullable(),
+    shadow: z.string(),
+    availableFonts: z.array(
+      z.object({
+        id: z.enum(TEMPLATE_FONT_IDS),
+        label: z.string(),
+        family: z.string(),
+        assetFile: z.string(),
+      }),
+    ),
+    availableBackgroundColors: z.array(
+      z.object({
+        id: z.enum(TEMPLATE_TEXT_BACKGROUND_COLOR_IDS),
+        label: z.string(),
+        hex: z.string(),
+      }),
+    ),
+  }),
+  safeArea: z.object({
+    left: z.number(),
+    right: z.number(),
+    top: z.number(),
+    bottom: z.number(),
+  }),
+  metaDetails: z.object({
+    title: z.string(),
+    description: z.string(),
+    pinned_comment: z.string(),
+    location: z.string(),
+    song: z.string(),
+  }),
+  slides: z.array(
+    z.object({
+      index: z.number(),
+      imagePrompt: z.string(),
+      imagePromptAttachments: z.array(z.string().url()),
+      overlayText: z.string(),
+      durationMs: z.number().int(),
+      backgroundImageUrl: z.string().url().nullable(),
+      frameImageUrl: z.string().url().nullable(),
+      prompt: z.string(),
+      revisedPrompt: z.string().nullable(),
+      layout: z.object({
+        zone: z.enum(["top", "center", "bottom"]),
+        align: z.enum(["left", "center", "right"]),
+        maxWidthPercent: z.number(),
+        anchorXPercent: z.number().optional(),
+        anchorYPercent: z.number().optional(),
+        justification: z.string(),
+      }),
+    }),
+  ),
+});
+
+function normalizeSlideInput(input: z.infer<typeof slideInputSchema>) {
+  if (Array.isArray(input)) {
+    return {
+      imagePrompt: input[0],
+      imagePromptAttachments: [],
+      overlayText: input[1],
+      durationMs: input[2] ?? 4000,
+    };
+  }
+
+  return {
+    imagePrompt: input.image_prompt,
+    imagePromptAttachments: input.image_prompt_attachments,
+    overlayText: input.caption,
+    durationMs: input.duration_ms,
+  };
+}
+
+async function generateMetaDetails(
+  ctx: TemplateJobContext,
+  input: {
+    provider: ImageProvider;
+    textModel: string;
+    slides: SlideOutput[];
+    metaDetailsPrompt?: string;
+  },
+): Promise<MetaDetails> {
+  const prompt = buildMetaDetailsPrompt(input.slides, input.metaDetailsPrompt);
+  const response = await ctx.providers.generateText({
+    provider: input.provider,
+    model: input.textModel,
+    prompt,
+    temperature: 0.7,
+  });
+  return parseMetaDetailsResponse(response.text, input.slides);
+}
+
+function buildMetaDetailsPrompt(
+  slides: SlideOutput[],
+  metaDetailsPrompt?: string,
+) {
+  return [
+    "You are writing TikTok post metadata for a vertical slideshow video.",
+    "Return only valid JSON with exactly these string keys: title, description, pinned_comment, location, song.",
+    "Do not include markdown fences or commentary.",
+    "Keep title under 90 characters.",
+    "Keep description under 300 characters.",
+    "Keep pinned_comment under 120 characters.",
+    "Keep location under 80 characters.",
+    "Keep song under 120 characters.",
+    "Write concise, high-performing, native-feeling TikTok social copy.",
+    "Use the slide captions and visual prompts to infer the post theme.",
+    metaDetailsPrompt
+      ? `Additional user guidance:\n${metaDetailsPrompt}`
+      : "No extra user guidance was supplied.",
+    "Slides:",
+    ...slides.map((slide) =>
+      [
+        `Slide ${slide.index + 1}:`,
+        `caption=${slide.overlayText}`,
+        `image_prompt=${slide.imagePrompt}`,
+        slide.imagePromptAttachments.length
+          ? `attachments=${slide.imagePromptAttachments.join(", ")}`
+          : "attachments=none",
+        `duration_ms=${slide.durationMs}`,
+      ].join("\n"),
+    ),
+  ].join("\n\n");
+}
+
+function parseMetaDetailsResponse(
+  raw: string,
+  slides: SlideOutput[],
+): MetaDetails {
+  const fallback = buildFallbackMetaDetails(slides);
+  const cleaned = raw
+    .trim()
+    .replace(/^```json\s*/i, "")
+    .replace(/^```\s*/i, "")
+    .replace(/\s*```$/i, "");
+  try {
+    const parsed = z
+      .object({
+        title: z.string().min(1),
+        description: z.string().min(1),
+        pinned_comment: z.string().min(1),
+        location: z.string().min(1),
+        song: z.string().min(1),
+      })
+      .parse(JSON.parse(cleaned));
+    return parsed;
+  } catch {
+    return fallback;
+  }
+}
+
+function buildFallbackMetaDetails(slides: SlideOutput[]): MetaDetails {
+  const leadCaption = slides[0]?.overlayText ?? "Watch this";
+  const supportingCaption =
+    slides[1]?.overlayText ?? slides[0]?.imagePrompt ?? "See the full story";
+  return {
+    title: truncateText(leadCaption, 90),
+    description: truncateText(`${leadCaption}. ${supportingCaption}.`, 300),
+    pinned_comment: truncateText(
+      `Which slide hit hardest: "${leadCaption}" or "${supportingCaption}"?`,
+      120,
+    ),
+    location: "United States",
+    song: "Original Sound",
+  };
+}
+
+function truncateText(value: string, maxLength: number) {
+  if (value.length <= maxLength) {
+    return value;
+  }
+  return `${value.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+
+async function renderFinishedSlide(
+  imageBytes: Uint8Array,
+  overlayText: string,
+  layout: Layout,
+  textStyle: TextStyleSpec,
+) {
+  const layers = await buildTextLayers(overlayText, layout, textStyle);
+  return sharp(Buffer.from(imageBytes)).composite(layers).png().toBuffer();
+}
+
+async function buildTextLayers(
+  overlayText: string,
+  layout: Layout,
+  textStyle: TextStyleSpec,
+) {
+  const safeWidth =
+    FRAME.width - TIKTOK_SAFE_AREA.left - TIKTOK_SAFE_AREA.right;
+  const blockWidth = Math.round(
+    safeWidth * clamp(layout.maxWidthPercent / 100, 0.4, 0.62),
+  );
+  const { fontSize, lines, lineHeight } = fitLinesToBlock(
+    overlayText,
+    blockWidth,
+    textStyle.fontId,
+  );
+  const blockHeight = Math.round(lines.length * lineHeight + 10);
+  const { left: x, top: y } = resolveTextBlockRect(
+    layout,
+    blockWidth,
+    blockHeight,
+  );
+  const rawLayers = (
+    await Promise.all(
+      lines.map(async (line, index) =>
+        buildLineLayers({
+          line,
+          lineIndex: index,
+          lineHeight,
+          fontSize,
+          blockWidth,
+          blockX: x,
+          blockY: y,
+          layout,
+          textStyle,
+        }),
+      ),
+    )
+  ).flat();
+
+  const clippedLayers = await Promise.all(
+    rawLayers.map((layer) => clipCompositeLayer(layer)),
+  );
+  return clippedLayers.filter((layer): layer is NonNullable<typeof layer> =>
+    Boolean(layer),
+  );
+}
+
+function fitLinesToBlock(
+  text: string,
+  blockWidth: number,
+  fontId: TemplateFontId,
+) {
+  let fontSize = pickFontSize(text, fontId);
+  let lineHeight = pickLineHeight(fontSize, fontId);
+  let maxChars = approximateMaxChars(blockWidth, fontSize);
+  let lines = wrapText(text, maxChars);
+
+  while (
+    (lines.length > 6 || longestLine(lines) > maxChars + 1) &&
+    fontSize > 34
+  ) {
+    fontSize -= 3;
+    lineHeight = pickLineHeight(fontSize, fontId);
+    maxChars = approximateMaxChars(blockWidth, fontSize);
+    lines = wrapText(text, maxChars);
+  }
+
+  return { fontSize, lines, lineHeight };
+}
+
+function pickFontSize(text: string, fontId: TemplateFontId) {
+  if (fontId === "yesteryear") {
+    if (text.length <= 22) {
+      return 74;
+    }
+    if (text.length <= 38) {
+      return 64;
+    }
+    return 54;
+  }
+  if (fontId === "dm_serif_display") {
+    if (text.length <= 22) {
+      return 66;
+    }
+    if (text.length <= 38) {
+      return 58;
+    }
+    return 48;
+  }
+  if (text.length <= 22) {
+    return 58;
+  }
+  if (text.length <= 38) {
+    return 52;
+  }
+  if (text.length <= 62) {
+    return 46;
+  }
+  if (text.length <= 96) {
+    return 40;
+  }
+  return 36;
+}
+
+function pickLineHeight(fontSize: number, fontId: TemplateFontId) {
+  if (fontId === "yesteryear") {
+    return Math.round(fontSize * 1.04);
+  }
+  if (fontId === "dm_serif_display") {
+    return Math.round(fontSize * 1.08);
+  }
+  return Math.round(fontSize * 1.12);
+}
+
+function approximateMaxChars(blockWidth: number, fontSize: number) {
+  return clamp(Math.floor(blockWidth / Math.max(20, fontSize * 0.42)), 12, 34);
+}
+
+async function buildLineLayers(input: {
+  line: string;
+  lineIndex: number;
+  lineHeight: number;
+  fontSize: number;
+  blockWidth: number;
+  blockX: number;
+  blockY: number;
+  layout: Layout;
+  textStyle: TextStyleSpec;
+}) {
+  const lineTop = input.blockY + input.lineIndex * input.lineHeight;
+  const shadowPadding = 40;
+  const fontAsset = overlayFonts[input.textStyle.fontId];
+  const measured = await renderTrimmedTextBuffer({
+    text: input.line,
+    blockWidth: input.blockWidth,
+    lineHeight: input.lineHeight,
+    fontSize: input.fontSize,
+    fontFamily: input.textStyle.fontFamily,
+    fontPath: fontAsset.path,
+    color: "#ffffff",
+  });
+
+  const lineLeft =
+    input.layout.align === "center"
+      ? input.blockX + Math.round((input.blockWidth - measured.width) / 2)
+      : input.layout.align === "right"
+        ? input.blockX + input.blockWidth - measured.width
+        : input.blockX;
+
+  const layers: Array<{ input: Buffer; left: number; top: number }> = [];
+  if (input.textStyle.backgroundColorHex) {
+    const chip = await buildTextChip({
+      width: measured.width,
+      height: measured.height,
+      fill: input.textStyle.backgroundColorHex,
+    });
+    layers.push({
+      input: chip,
+      left: lineLeft - 14,
+      top: lineTop - 8,
+    });
+  }
+
+  const shadowFar = await renderShadowLayer({
+    textBuffer: measured.buffer,
+    width: measured.width,
+    height: measured.height,
+    shadowPadding,
+    blur: 8,
+  });
+  const shadowNear = await renderShadowLayer({
+    textBuffer: measured.buffer,
+    width: measured.width,
+    height: measured.height,
+    shadowPadding,
+    blur: 2.4,
+  });
+
+  layers.push(
+    {
+      input: shadowFar,
+      left: lineLeft - shadowPadding,
+      top: lineTop - shadowPadding + 8,
+    },
+    {
+      input: shadowNear,
+      left: lineLeft - shadowPadding,
+      top: lineTop - shadowPadding + 4,
+    },
+    { input: measured.buffer, left: lineLeft, top: lineTop },
+  );
+
+  return layers;
+}
+
+async function renderTrimmedTextBuffer(input: {
+  text: string;
+  blockWidth: number;
+  lineHeight: number;
+  fontSize: number;
+  fontFamily: string;
+  fontPath: string;
+  color: string;
+}) {
+  const markupSafe = escapePango(input.text);
+  const rendered = await sharp({
+    text: {
+      text: `<span foreground="${input.color}">${markupSafe}</span>`,
+      rgba: true,
+      width: input.blockWidth + 40,
+      height: input.lineHeight + 28,
+      align: "left",
+      spacing: 0,
+      font: `${input.fontFamily} ${input.fontSize}`,
+      fontfile: input.fontPath,
+    },
+  })
+    .trim()
+    .png()
+    .toBuffer();
+  const metadata = await sharp(rendered).metadata();
+  return {
+    buffer: rendered,
+    width: metadata.width ?? input.blockWidth,
+    height: metadata.height ?? input.lineHeight,
+  };
+}
+
+async function renderShadowLayer(input: {
+  textBuffer: Buffer;
+  width: number;
+  height: number;
+  shadowPadding: number;
+  blur: number;
+}) {
+  return sharp({
+    create: {
+      width: input.width + input.shadowPadding * 2,
+      height: input.height + input.shadowPadding * 2,
+      channels: 4,
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    },
+  })
+    .composite([
+      {
+        input: input.textBuffer,
+        left: input.shadowPadding,
+        top: input.shadowPadding,
+      },
+    ])
+    .modulate({ brightness: 0 })
+    .linear(0, 0)
+    .blur(input.blur)
+    .png()
+    .toBuffer();
+}
+
+async function buildTextChip(input: {
+  width: number;
+  height: number;
+  fill: string;
+}) {
+  const chipWidth = input.width + 28;
+  const chipHeight = input.height + 16;
+  return sharp(
+    Buffer.from(
+      `<svg width="${chipWidth}" height="${chipHeight}" xmlns="http://www.w3.org/2000/svg">
+      <rect x="0" y="0" width="${chipWidth}" height="${chipHeight}" rx="12" ry="12" fill="${input.fill}" fill-opacity="0.86"/>
+    </svg>`,
+    ),
+  )
+    .png()
+    .toBuffer();
+}
+
+function wrapText(text: string, maxChars: number) {
+  const words = text.trim().split(/\s+/).filter(Boolean);
+  const lines: string[] = [];
+  let current = "";
+  for (const word of words) {
+    const candidate = current ? `${current} ${word}` : word;
+    if (candidate.length <= maxChars || !current) {
+      current = candidate;
+      continue;
+    }
+    lines.push(current);
+    current = word;
+  }
+  if (current) {
+    lines.push(current);
+  }
+  return lines.length ? lines : [text];
+}
+
+function longestLine(lines: string[]) {
+  return lines.reduce((longest, line) => Math.max(longest, line.length), 0);
+}
+
+async function portraitScore(input: Uint8Array) {
+  const metadata = await sharp(Buffer.from(input)).rotate().metadata();
+  const width = metadata.width ?? FRAME.width;
+  const height = metadata.height ?? FRAME.height;
+  const aspect = width / height;
+  const thumbnailWidth = 96;
+  const thumbnailHeight = 170;
+  const sample = await sharp(Buffer.from(input))
+    .rotate()
+    .resize(thumbnailWidth, thumbnailHeight, { fit: "fill" })
+    .grayscale()
+    .raw()
+    .toBuffer();
+  const edgeContrast = edgeBandContrast(
+    sample,
+    thumbnailWidth,
+    thumbnailHeight,
+  );
+  return Math.abs(aspect - 9 / 16) + edgeContrast;
+}
+
+async function chooseLayoutFromImage(
+  imageBytes: Uint8Array,
+  overlayText: string,
+): Promise<Layout> {
+  const thumbnailWidth = 108;
+  const thumbnailHeight = 192;
+  const sample = await sharp(Buffer.from(imageBytes))
+    .resize(thumbnailWidth, thumbnailHeight, { fit: "fill" })
+    .grayscale()
+    .raw()
+    .toBuffer();
+
+  const candidates = buildLayoutCandidates(overlayText);
+
+  let best = defaultLayout();
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const estimate = estimateTextBlock(overlayText, candidate);
+    const region = regionForLayout(
+      candidate,
+      estimate.blockWidth,
+      estimate.blockHeight,
+    );
+    const score =
+      scoreLayoutRegion(sample, thumbnailWidth, thumbnailHeight, region) +
+      candidate.stylePenalty;
+    if (score < bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+
+  return {
+    zone: best.zone,
+    align: best.align,
+    maxWidthPercent: best.maxWidthPercent,
+    anchorXPercent: best.anchorXPercent,
+    anchorYPercent: best.anchorYPercent,
+    justification: `${best.justification} Selected by local safe-zone scoring to minimize busy backgrounds and avoid TikTok UI chrome.`,
+  };
+}
+
+async function chooseSlideLayout(
+  ctx: TemplateJobContext,
+  input: {
+    provider: ImageProvider;
+    model: string;
+    imageBytes: Uint8Array;
+    imageUrl: string | null;
+    overlayText: string;
+  },
+) {
+  if (input.imageUrl) {
+    try {
+      const analysis = await ctx.providers.analyzeImageLayout({
+        provider: input.provider,
+        model: input.model,
+        imageUrl: input.imageUrl,
+        overlayText: input.overlayText,
+      });
+      return normalizeAiLayout(analysis);
+    } catch (error) {
+      ctx.logger.warn(
+        "AI layout analysis failed, falling back to local scorer",
+        {
+          provider: input.provider,
+          model: input.model,
+          message: error instanceof Error ? error.message : String(error),
+        },
+      );
+    }
+  }
+  return chooseLayoutFromImage(input.imageBytes, input.overlayText);
+}
+
+function normalizeAiLayout(input: {
+  zone: "top" | "center" | "bottom";
+  align: "left" | "center" | "right";
+  maxWidthPercent: number;
+  justification: string;
+}): Layout {
+  const normalizedAlign = input.align === "right" ? "center" : input.align;
+  const anchorXPercent =
+    normalizedAlign === "center"
+      ? 0.5
+      : normalizedAlign === "left"
+        ? 0.38
+        : 0.62;
+  const anchorYPercent =
+    input.zone === "top" ? 0.18 : input.zone === "bottom" ? 0.38 : 0.28;
+
+  return {
+    zone: input.zone === "bottom" ? "center" : input.zone,
+    align: normalizedAlign,
+    maxWidthPercent: clamp(input.maxWidthPercent, 46, 62),
+    anchorXPercent,
+    anchorYPercent,
+    justification: `${input.justification} Normalized toward centered TikTok-native caption placement.`,
+  };
+}
+
+function estimateTextBlock(text: string, layout: Layout) {
+  const safeWidth =
+    FRAME.width - TIKTOK_SAFE_AREA.left - TIKTOK_SAFE_AREA.right;
+  const centeredBounds = resolveNativeUiTextPaddingBounds();
+  const availableWidth =
+    layout.align === "center"
+      ? FRAME.width - centeredBounds.minLeft * 2
+      : safeWidth;
+  const blockWidth = Math.round(
+    availableWidth * clamp(layout.maxWidthPercent / 100, 0.4, 0.62),
+  );
+  const { fontSize, lines, lineHeight } = fitLinesToBlock(
+    text,
+    blockWidth,
+    "montserrat",
+  );
+  return {
+    blockWidth,
+    blockHeight: Math.round(lines.length * lineHeight + 10),
+    fontSize,
+  };
+}
+
+function regionForLayout(
+  layout: Layout,
+  blockWidth: number,
+  blockHeight: number,
+) {
+  return resolveTextBlockRect(layout, blockWidth, blockHeight);
+}
+
+function resolveTextBlockRect(
+  layout: Layout,
+  blockWidth: number,
+  blockHeight: number,
+) {
+  const safeWidth =
+    FRAME.width - TIKTOK_SAFE_AREA.left - TIKTOK_SAFE_AREA.right;
+  const safeHeight =
+    FRAME.height - TIKTOK_SAFE_AREA.top - TIKTOK_SAFE_AREA.bottom;
+  const centeredBounds = resolveNativeUiTextPaddingBounds(blockWidth);
+  if (
+    layout.anchorXPercent !== undefined &&
+    layout.anchorYPercent !== undefined
+  ) {
+    const centeredX = clamp(
+      Math.round((FRAME.width - blockWidth) / 2),
+      centeredBounds.minLeft,
+      centeredBounds.maxLeft,
+    );
+    return {
+      left:
+        layout.align === "center"
+          ? centeredX
+          : TIKTOK_SAFE_AREA.left +
+            Math.round(
+              (safeWidth - blockWidth) * clamp(layout.anchorXPercent, 0, 1),
+            ),
+      top:
+        TIKTOK_SAFE_AREA.top +
+        Math.round(
+          (safeHeight - blockHeight) * clamp(layout.anchorYPercent, 0, 1),
+        ),
+      width: blockWidth,
+      height: blockHeight,
+    };
+  }
+
+  const x =
+    layout.align === "left"
+      ? TIKTOK_SAFE_AREA.left
+      : layout.align === "center"
+        ? clamp(
+            Math.round((FRAME.width - blockWidth) / 2),
+            centeredBounds.minLeft,
+            centeredBounds.maxLeft,
+          )
+        : FRAME.width - TIKTOK_SAFE_AREA.right - blockWidth;
+  const y =
+    layout.zone === "top"
+      ? TIKTOK_SAFE_AREA.top + 72
+      : layout.zone === "center"
+        ? TIKTOK_SAFE_AREA.top + Math.round(safeHeight * 0.2)
+        : FRAME.height - TIKTOK_SAFE_AREA.bottom - blockHeight - 120;
+
+  return {
+    left: x,
+    top: y,
+    width: blockWidth,
+    height: blockHeight,
+  };
+}
+
+function resolveNativeUiTextPaddingBounds(blockWidth = 0) {
+  const horizontalPadding = Math.round(
+    FRAME.width *
+      ((NATIVE_UI_TEXT_ZONE.maxCenterXPercent -
+        NATIVE_UI_TEXT_ZONE.minCenterXPercent) /
+        2),
+  );
+  return {
+    minLeft: horizontalPadding,
+    maxLeft: Math.max(
+      horizontalPadding,
+      FRAME.width - horizontalPadding - blockWidth,
+    ),
+  };
+}
+
+function scoreLayoutRegion(
+  sample: Buffer,
+  width: number,
+  height: number,
+  region: { left: number; top: number; width: number; height: number },
+) {
+  const inner = sampleStats(sample, width, height, region, 0);
+  const outer = sampleStats(sample, width, height, region, 44);
+  const halo = sampleStats(sample, width, height, region, 110);
+  const edgePenalty =
+    (region.left < 112 ? 6 : 0) +
+    (region.top < 340 ? 18 : 0) +
+    (region.top + region.height > FRAME.height - 560 ? 18 : 0);
+  const readabilityPenalty = Math.max(0, inner.mean - 205) * 0.24;
+  const lowContrastPenalty = Math.abs(inner.mean - outer.mean) < 10 ? 6 : 0;
+  const haloPenalty = halo.detail * 0.35 + halo.variance * 0.01;
+
+  return (
+    inner.detail * 1.35 +
+    inner.variance * 0.022 +
+    outer.detail * 0.45 +
+    readabilityPenalty +
+    lowContrastPenalty +
+    haloPenalty +
+    edgePenalty
+  );
+}
+
+function sampleStats(
+  sample: Buffer,
+  width: number,
+  height: number,
+  region: { left: number; top: number; width: number; height: number },
+  padding: number,
+) {
+  const left = clamp(
+    Math.floor((region.left / FRAME.width) * width),
+    0,
+    width - 1,
+  );
+  const top = clamp(
+    Math.floor((region.top / FRAME.height) * height),
+    0,
+    height - 1,
+  );
+  const right = clamp(
+    Math.ceil(((region.left + region.width) / FRAME.width) * width),
+    left + 1,
+    width,
+  );
+  const bottom = clamp(
+    Math.ceil(((region.top + region.height) / FRAME.height) * height),
+    top + 1,
+    height,
+  );
+  const padX = Math.round((padding / FRAME.width) * width);
+  const padY = Math.round((padding / FRAME.height) * height);
+  const paddedLeft = clamp(left - padX, 0, width - 1);
+  const paddedTop = clamp(top - padY, 0, height - 1);
+  const paddedRight = clamp(right + padX, paddedLeft + 1, width);
+  const paddedBottom = clamp(bottom + padY, paddedTop + 1, height);
+  let total = 0;
+  let totalSq = 0;
+  let detail = 0;
+  let count = 0;
+
+  for (let y = paddedTop; y < paddedBottom; y += 1) {
+    for (let x = paddedLeft; x < paddedRight; x += 1) {
+      if (padding > 0 && x >= left && x < right && y >= top && y < bottom) {
+        continue;
+      }
+      const index = y * width + x;
+      const current = sample[index] ?? 0;
+      const leftPixel = x > 0 ? (sample[index - 1] ?? current) : current;
+      const upPixel = y > 0 ? (sample[index - width] ?? current) : current;
+      total += current;
+      totalSq += current * current;
+      detail += Math.abs(current - leftPixel) + Math.abs(current - upPixel);
+      count += 1;
+    }
+  }
+
+  const mean = total / Math.max(count, 1);
+  const variance = Math.max(0, totalSq / Math.max(count, 1) - mean * mean);
+  return {
+    mean,
+    variance,
+    detail: detail / Math.max(count, 1),
+  };
+}
+
+function edgeBandContrast(sample: Buffer, width: number, height: number) {
+  const bandHeight = Math.max(8, Math.floor(height * 0.16));
+  const top = bandActivity(sample, width, height, 0, bandHeight);
+  const bottom = bandActivity(
+    sample,
+    width,
+    height,
+    height - bandHeight,
+    height,
+  );
+  return (top + bottom) / 220;
+}
+
+function bandActivity(
+  sample: Buffer,
+  width: number,
+  height: number,
+  startY: number,
+  endY: number,
+) {
+  let detail = 0;
+  let count = 0;
+  for (let y = startY; y < endY; y += 1) {
+    for (let x = 1; x < width; x += 1) {
+      const index = y * width + x;
+      const current = sample[index] ?? 0;
+      const prev = sample[index - 1] ?? current;
+      detail += Math.abs(current - prev);
+      count += 1;
+    }
+  }
+  return detail / Math.max(count, 1);
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function escapePango(text: string) {
+  return text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+async function clipCompositeLayer(layer: {
+  input: Buffer;
+  left: number;
+  top: number;
+}) {
+  const metadata = await sharp(layer.input).metadata();
+  const width = metadata.width ?? 0;
+  const height = metadata.height ?? 0;
+  if (!width || !height) {
+    return null;
+  }
+
+  const left = Math.max(0, layer.left);
+  const top = Math.max(0, layer.top);
+  const cropLeft = Math.max(0, -layer.left);
+  const cropTop = Math.max(0, -layer.top);
+  const availableWidth = FRAME.width - left;
+  const availableHeight = FRAME.height - top;
+  const cropWidth = Math.min(width - cropLeft, availableWidth);
+  const cropHeight = Math.min(height - cropTop, availableHeight);
+
+  if (cropWidth <= 0 || cropHeight <= 0) {
+    return null;
+  }
+
+  if (
+    cropLeft === 0 &&
+    cropTop === 0 &&
+    cropWidth === width &&
+    cropHeight === height
+  ) {
+    return {
+      input: layer.input,
+      left,
+      top,
+    };
+  }
+
+  const input = await sharp(layer.input)
+    .extract({
+      left: cropLeft,
+      top: cropTop,
+      width: cropWidth,
+      height: cropHeight,
+    })
+    .png()
+    .toBuffer();
+
+  return {
+    input,
+    left,
+    top,
+  };
+}
+
+function buildLayoutCandidates(
+  overlayText: string,
+): Array<Layout & { stylePenalty: number }> {
+  const prefersCenteredText = overlayText.trim().length <= 42;
+  const widthPercents = prefersCenteredText ? [48, 52, 56] : [50, 54, 58];
+  const centerAnchors = prefersCenteredText
+    ? [0.44, 0.5, 0.56]
+    : [0.42, 0.5, 0.58];
+  const yAnchors = [0.16, 0.22, 0.28, 0.34, 0.4];
+  const candidates: Array<Layout & { stylePenalty: number }> = [];
+
+  for (const maxWidthPercent of widthPercents) {
+    for (const anchorYPercent of yAnchors) {
+      for (const anchorXPercent of centerAnchors) {
+        candidates.push({
+          zone: anchorYPercent < 0.22 ? "top" : "center",
+          align: "center",
+          maxWidthPercent,
+          anchorXPercent,
+          anchorYPercent,
+          justification: "Image-aware centered native TikTok caption zone.",
+          stylePenalty:
+            scoreNativeUiAnchor(anchorXPercent, anchorYPercent) +
+            (prefersCenteredText ? 0 : 4),
+        });
+      }
+    }
+  }
+
+  return candidates;
+}
+
+function scoreNativeUiAnchor(anchorXPercent: number, anchorYPercent: number) {
+  let penalty = 0;
+  if (
+    anchorXPercent < NATIVE_UI_TEXT_ZONE.minCenterXPercent ||
+    anchorXPercent > NATIVE_UI_TEXT_ZONE.maxCenterXPercent
+  ) {
+    penalty += 10;
+  }
+  if (
+    anchorYPercent < NATIVE_UI_TEXT_ZONE.minCenterYPercent ||
+    anchorYPercent > NATIVE_UI_TEXT_ZONE.maxCenterYPercent
+  ) {
+    penalty += 10;
+  }
+  penalty += Math.abs(anchorXPercent - 0.5) * 24;
+  penalty += Math.abs(anchorYPercent - 0.28) * 18;
+  return penalty;
+}
+
+function resolveRemotionEntryPoint() {
+  const builtPath = fileURLToPath(
+    new URL("./remotion/index.js", import.meta.url),
+  );
+  if (existsSync(builtPath)) {
+    return builtPath;
+  }
+  return fileURLToPath(new URL("./remotion/index.tsx", import.meta.url));
+}
+
+function resolveTemplateRuntimeConfig() {
+  const candidates = [
+    fileURLToPath(new URL("../template.config.json", import.meta.url)),
+    path.resolve(process.cwd(), "templates/template_0000/template.config.json"),
+  ];
+
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) {
+      continue;
+    }
+    return JSON.parse(readFileSync(candidate, "utf8")) as {
+      remotion?: {
+        serve_url?: string;
+      };
+    };
+  }
+
+  return {};
+}
+
+function resolveSkillPath() {
+  const builtPath = fileURLToPath(new URL("../SKILL.md", import.meta.url));
+  if (existsSync(builtPath)) {
+    return builtPath;
+  }
+  return path.resolve(process.cwd(), "templates/template_0000/SKILL.md");
+}
+
+function resolveOverlayFonts() {
+  const resolved = Object.fromEntries(
+    TEMPLATE_FONT_OPTIONS.map((option) => {
+      const candidates = [
+        fileURLToPath(
+          new URL(`../assets/${option.assetFile}`, import.meta.url),
+        ),
+        path.resolve(
+          process.cwd(),
+          `templates/template_0000/assets/${option.assetFile}`,
+        ),
+      ];
+
+      for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+          return [option.id, { path: candidate }];
+        }
+      }
+
+      throw new Error(
+        `Could not resolve local overlay font asset for ${option.label}.`,
+      );
+    }),
+  );
+
+  return resolved as Record<TemplateFontId, { path: string }>;
+}