@tomako/tools-runtime 0.1.0

package/src/lib/tools/og-image-generator-render.ts

@@ -0,0 +1,448 @@
+import type { CSSProperties } from "react";
+
+import {
+  buildOgImageFileName,
+  getOgImageMimeType,
+  OG_IMAGE_PRESET_META,
+  parseOgImageTags,
+  type OgImageGeneratorInput,
+  type OgImageGridColor,
+} from "../../lib/tools/og-image-generator-schema";
+
+export type GeneratedOgImage = {
+  url: string;
+  blob: Blob;
+  fileName: string;
+  width: number;
+  height: number;
+  format: OgImageGeneratorInput["format"];
+};
+
+const GRID_COLOR_MAP: Record<OgImageGridColor, string> = {
+  black: "#111111",
+  white: "#FFFFFF",
+  gray: "#8A8A8A",
+};
+
+export function previewBackground(input: OgImageGeneratorInput): string {
+  if (input.backgroundMode === "solid") return input.backgroundColor;
+  if (input.template === "minimal") return `linear-gradient(135deg, ${input.templateBackgroundColor} 0%, #FFFFFF 100%)`;
+  if (input.template === "split") {
+    return `linear-gradient(105deg, ${input.primaryColor} 0%, ${input.backgroundColor} 66%, ${input.accentColor} 66%)`;
+  }
+  return `linear-gradient(135deg, ${input.primaryColor} 0%, ${input.backgroundColor} 58%, ${input.accentColor} 100%)`;
+}
+
+export function previewGridStyle(input: OgImageGeneratorInput): CSSProperties | undefined {
+  if (input.gridPattern === "none" || input.gridOpacity <= 0) return undefined;
+  const color = GRID_COLOR_MAP[input.gridColor];
+  const alpha = input.gridOpacity;
+  const rgba = hexToRgba(color, alpha);
+  if (input.gridPattern === "dots") {
+    return {
+      backgroundImage: `radial-gradient(${rgba} 1px, transparent 1px)`,
+      backgroundSize: "5% 8%",
+      filter: input.gridBlurRadius > 0 ? `blur(${input.gridBlurRadius / 10}px)` : undefined,
+    };
+  }
+  if (input.gridPattern === "graph") {
+    return {
+      backgroundImage: `linear-gradient(${rgba} 1px, transparent 1px), linear-gradient(90deg, ${rgba} 1px, transparent 1px), linear-gradient(${hexToRgba(color, alpha * 1.4)} 2px, transparent 2px), linear-gradient(90deg, ${hexToRgba(color, alpha * 1.4)} 2px, transparent 2px)`,
+      backgroundSize: "5% 8%, 5% 8%, 20% 32%, 20% 32%",
+      filter: input.gridBlurRadius > 0 ? `blur(${input.gridBlurRadius / 10}px)` : undefined,
+    };
+  }
+  return {
+    backgroundImage: `linear-gradient(${rgba} 1px, transparent 1px), linear-gradient(90deg, ${rgba} 1px, transparent 1px)`,
+    backgroundSize: "5% 8%",
+    filter: input.gridBlurRadius > 0 ? `blur(${input.gridBlurRadius / 10}px)` : undefined,
+  };
+}
+
+export async function renderOgImage(input: OgImageGeneratorInput): Promise<GeneratedOgImage> {
+  const meta = OG_IMAGE_PRESET_META[input.preset];
+  const canvas = document.createElement("canvas");
+  canvas.width = meta.width;
+  canvas.height = meta.height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Canvas unavailable");
+
+  await drawImage(ctx, input, meta.width, meta.height);
+
+  const blob = await new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (value) => {
+        if (value) resolve(value);
+        else reject(new Error("Canvas export failed"));
+      },
+      getOgImageMimeType(input.format),
+      input.format === "png" ? undefined : 0.92,
+    );
+  });
+
+  return {
+    url: URL.createObjectURL(blob),
+    blob,
+    fileName: buildOgImageFileName(input),
+    width: meta.width,
+    height: meta.height,
+    format: input.format,
+  };
+}
+
+async function drawImage(
+  ctx: CanvasRenderingContext2D,
+  input: OgImageGeneratorInput,
+  width: number,
+  height: number,
+) {
+  drawBackground(ctx, input, width, height);
+  drawGridOverlay(ctx, input, width, height);
+  drawNoise(ctx, input, width, height);
+
+  if (input.template === "split") {
+    ctx.fillStyle = input.accentColor;
+    ctx.fillRect(width * 0.66, 0, width * 0.34, height);
+  } else if (input.template === "quote") {
+    ctx.globalAlpha = 0.22;
+    ctx.fillStyle = "#FFFFFF";
+    ctx.font = `700 ${Math.round(width / 4)}px Georgia, serif`;
+    ctx.fillText("\"", width * 0.72, height * 0.48);
+    ctx.globalAlpha = 1;
+  } else if (!input.decorImageDataUrl) {
+    drawShape(
+      ctx,
+      width * 0.72,
+      height * 0.18,
+      width * 0.24,
+      height * 0.38,
+      input.template === "minimal" ? input.accentColor : "rgba(255,255,255,0.22)",
+      input.template === "editorial" ? -0.12 : 0.12,
+    );
+    drawCircle(
+      ctx,
+      width * 0.82,
+      height * 0.72,
+      Math.min(width, height) * 0.08,
+      input.template === "minimal" ? input.primaryColor : input.accentColor,
+    );
+  }
+
+  await drawDecorImage(ctx, input, width, height);
+
+  const logoSize = Math.round(height * 0.078);
+  await drawLogo(ctx, input, width * 0.08, height * 0.09, logoSize);
+  drawTagPills(ctx, input, parseOgImageTags(input.tags), width * 0.08 + logoSize + width * 0.018, height * 0.105, width * 0.56, height);
+
+  const titleSize = Math.round(input.titleTypography.fontSize * (width / 1200));
+  const titleLineHeight = Math.round(titleSize * 1.12);
+  ctx.fillStyle = input.titleTypography.color;
+  ctx.font = `${input.titleTypography.fontWeight} ${titleSize}px ${fontStack(input.titleTypography.fontFamily)}`;
+  drawWrappedText(
+    ctx,
+    input.title,
+    width * 0.08,
+    height * 0.42,
+    width * 0.66,
+    titleLineHeight,
+    input.preset === "xHeader" ? 2 : 3,
+  );
+
+  if (input.subtitle) {
+    ctx.globalAlpha = input.template === "minimal" ? 0.72 : 0.84;
+    ctx.fillStyle = input.template === "minimal" ? "#444444" : "rgba(255,255,255,0.82)";
+    ctx.font = `500 ${Math.round(width / 42)}px ${fontStack("Inter")}`;
+    drawWrappedText(ctx, input.subtitle, width * 0.08, height * 0.69, width * 0.56, Math.round(width / 30), 2);
+    ctx.globalAlpha = 1;
+  }
+
+  ctx.fillStyle = input.template === "minimal" ? "#555555" : "rgba(255,255,255,0.68)";
+  ctx.font = `700 ${Math.round(width / 70)}px ${fontStack("Inter")}`;
+  ctx.textAlign = "right";
+  ctx.fillText(`${width} x ${height}`, width * 0.92, height * 0.14);
+  ctx.textAlign = "left";
+}
+
+function drawBackground(ctx: CanvasRenderingContext2D, input: OgImageGeneratorInput, width: number, height: number) {
+  if (input.backgroundMode === "solid") {
+    ctx.fillStyle = input.backgroundColor;
+    ctx.fillRect(0, 0, width, height);
+    return;
+  }
+
+  const bg = ctx.createLinearGradient(0, 0, width, height);
+  if (input.template === "minimal") {
+    bg.addColorStop(0, input.templateBackgroundColor);
+    bg.addColorStop(1, "#FFFFFF");
+  } else if (input.template === "split") {
+    bg.addColorStop(0, input.primaryColor);
+    bg.addColorStop(1, input.backgroundColor);
+  } else {
+    bg.addColorStop(0, input.primaryColor);
+    bg.addColorStop(0.58, input.backgroundColor);
+    bg.addColorStop(1, input.accentColor);
+  }
+  ctx.fillStyle = bg;
+  ctx.fillRect(0, 0, width, height);
+}
+
+function drawGridOverlay(ctx: CanvasRenderingContext2D, input: OgImageGeneratorInput, width: number, height: number) {
+  if (input.gridPattern === "none" || input.gridOpacity <= 0) return;
+
+  const overlay = document.createElement("canvas");
+  overlay.width = width;
+  overlay.height = height;
+  const overlayCtx = overlay.getContext("2d");
+  if (!overlayCtx) return;
+
+  const color = GRID_COLOR_MAP[input.gridColor];
+  overlayCtx.strokeStyle = color;
+  overlayCtx.fillStyle = color;
+  overlayCtx.globalAlpha = input.gridOpacity;
+  overlayCtx.lineWidth = Math.max(1, width / 1200);
+
+  if (input.gridPattern === "dots") {
+    const stepX = width / 20;
+    const stepY = height / 12;
+    const radius = Math.max(1.5, width / 800);
+    for (let x = stepX; x < width; x += stepX) {
+      for (let y = stepY; y < height; y += stepY) {
+        overlayCtx.beginPath();
+        overlayCtx.arc(x, y, radius, 0, Math.PI * 2);
+        overlayCtx.fill();
+      }
+    }
+  } else {
+    const stepX = width / 20;
+    const stepY = height / 12;
+    for (let x = stepX; x < width; x += stepX) {
+      overlayCtx.beginPath();
+      overlayCtx.moveTo(x, 0);
+      overlayCtx.lineTo(x, height);
+      overlayCtx.stroke();
+    }
+    for (let y = stepY; y < height; y += stepY) {
+      overlayCtx.beginPath();
+      overlayCtx.moveTo(0, y);
+      overlayCtx.lineTo(width, y);
+      overlayCtx.stroke();
+    }
+    if (input.gridPattern === "graph") {
+      overlayCtx.globalAlpha = Math.min(1, input.gridOpacity * 1.35);
+      overlayCtx.lineWidth = Math.max(2, width / 600);
+      for (let x = stepX * 4; x < width; x += stepX * 4) {
+        overlayCtx.beginPath();
+        overlayCtx.moveTo(x, 0);
+        overlayCtx.lineTo(x, height);
+        overlayCtx.stroke();
+      }
+      for (let y = stepY * 4; y < height; y += stepY * 4) {
+        overlayCtx.beginPath();
+        overlayCtx.moveTo(0, y);
+        overlayCtx.lineTo(width, y);
+        overlayCtx.stroke();
+      }
+    }
+  }
+
+  const blurPx = (input.gridBlurRadius / 100) * Math.min(width, height) * 0.04;
+  ctx.save();
+  if (blurPx > 0) ctx.filter = `blur(${blurPx}px)`;
+  ctx.drawImage(overlay, 0, 0);
+  ctx.restore();
+}
+
+function drawNoise(ctx: CanvasRenderingContext2D, input: OgImageGeneratorInput, width: number, height: number) {
+  if (input.noise <= 0) return;
+  const pixels = Math.floor(width * height * input.noise * 0.08);
+  ctx.save();
+  for (let index = 0; index < pixels; index += 1) {
+    const x = Math.random() * width;
+    const y = Math.random() * height;
+    const tone = Math.random() > 0.5 ? 255 : 0;
+    ctx.globalAlpha = input.noise * 0.35;
+    ctx.fillStyle = `rgb(${tone}, ${tone}, ${tone})`;
+    ctx.fillRect(x, y, 1.2, 1.2);
+  }
+  ctx.restore();
+}
+
+async function drawDecorImage(ctx: CanvasRenderingContext2D, input: OgImageGeneratorInput, width: number, height: number) {
+  if (!input.decorImageDataUrl) return;
+  try {
+    const image = await loadImage(input.decorImageDataUrl);
+    const maxWidth = width * 0.28;
+    const maxHeight = height * 0.34;
+    const fit = fitInside(image.width, image.height, maxWidth, maxHeight);
+    const x = width * 0.68;
+    const y = height * 0.58;
+    ctx.save();
+    ctx.shadowColor = "rgba(0,0,0,0.22)";
+    ctx.shadowBlur = Math.max(12, width / 80);
+    ctx.drawImage(image, x, y, fit.width, fit.height);
+    ctx.restore();
+  } catch {
+    // Ignore broken decor uploads in export.
+  }
+}
+
+async function drawLogo(ctx: CanvasRenderingContext2D, input: OgImageGeneratorInput, x: number, y: number, size: number) {
+  ctx.save();
+  ctx.fillStyle = "rgba(255,255,255,0.92)";
+  roundRect(ctx, x, y, size, size, Math.round(size * 0.22));
+  ctx.fill();
+
+  if (input.logoDataUrl) {
+    try {
+      const image = await loadImage(input.logoDataUrl);
+      const fit = fitInside(image.width, image.height, size * 0.72, size * 0.72);
+      ctx.drawImage(image, x + (size - fit.width) / 2, y + (size - fit.height) / 2, fit.width, fit.height);
+      ctx.restore();
+      return;
+    } catch {
+      // Fall back to text mark below.
+    }
+  }
+
+  ctx.fillStyle = "#111111";
+  ctx.font = `800 ${Math.round(size * 0.44)}px ${fontStack("Inter")}`;
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+  ctx.fillText((input.logoText || input.brand || "T").slice(0, 2), x + size / 2, y + size / 2);
+  ctx.textAlign = "left";
+  ctx.textBaseline = "alphabetic";
+  ctx.restore();
+}
+
+function drawTagPills(
+  ctx: CanvasRenderingContext2D,
+  input: OgImageGeneratorInput,
+  tags: string[],
+  x: number,
+  y: number,
+  maxWidth: number,
+  height: number,
+) {
+  if (!tags.length) return;
+  const fontSize = Math.round(input.tagTypography.fontSize * (height / 630));
+  ctx.save();
+  ctx.font = `${input.tagTypography.fontWeight} ${fontSize}px ${fontStack(input.tagTypography.fontFamily)}`;
+  ctx.textBaseline = "middle";
+  let cursor = x;
+  for (const tag of tags.slice(0, 3)) {
+    const pillWidth = Math.min(ctx.measureText(tag).width + height * 0.055, maxWidth);
+    if (cursor + pillWidth > x + maxWidth) break;
+    ctx.fillStyle = "rgba(255,255,255,0.88)";
+    ctx.strokeStyle = input.tagTypography.color;
+    ctx.lineWidth = Math.max(2, height / 240);
+    roundRect(ctx, cursor, y, pillWidth, height * 0.052, height * 0.026);
+    ctx.fill();
+    ctx.stroke();
+    ctx.fillStyle = input.tagTypography.color;
+    ctx.fillText(tag, cursor + height * 0.024, y + height * 0.026);
+    cursor += pillWidth + height * 0.012;
+  }
+  ctx.restore();
+}
+
+function drawWrappedText(
+  ctx: CanvasRenderingContext2D,
+  text: string,
+  x: number,
+  y: number,
+  maxWidth: number,
+  lineHeight: number,
+  maxLines: number,
+) {
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines: string[] = [];
+  let line = "";
+
+  for (const word of words) {
+    const candidate = line ? `${line} ${word}` : word;
+    if (ctx.measureText(candidate).width > maxWidth && line) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = candidate;
+    }
+    if (lines.length === maxLines) break;
+  }
+  if (line && lines.length < maxLines) lines.push(line);
+
+  lines.forEach((item, index) => ctx.fillText(item, x, y + index * lineHeight));
+}
+
+function drawShape(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  color: string,
+  rotate: number,
+) {
+  ctx.save();
+  ctx.translate(x + width / 2, y + height / 2);
+  ctx.rotate(rotate);
+  ctx.fillStyle = color;
+  roundRect(ctx, -width / 2, -height / 2, width, height, Math.min(width, height) * 0.12);
+  ctx.fill();
+  ctx.restore();
+}
+
+function drawCircle(ctx: CanvasRenderingContext2D, x: number, y: number, radius: number, color: string) {
+  ctx.fillStyle = color;
+  ctx.beginPath();
+  ctx.arc(x, y, radius, 0, Math.PI * 2);
+  ctx.fill();
+}
+
+function roundRect(ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, radius: number) {
+  ctx.beginPath();
+  ctx.moveTo(x + radius, y);
+  ctx.lineTo(x + width - radius, y);
+  ctx.quadraticCurveTo(x + width, y, x + width, y + radius);
+  ctx.lineTo(x + width, y + height - radius);
+  ctx.quadraticCurveTo(x + width, y + height, x + width - radius, y + height);
+  ctx.lineTo(x + radius, y + height);
+  ctx.quadraticCurveTo(x, y + height, x, y + height - radius);
+  ctx.lineTo(x, y + radius);
+  ctx.quadraticCurveTo(x, y, x + radius, y);
+  ctx.closePath();
+}
+
+function fitInside(sourceWidth: number, sourceHeight: number, maxWidth: number, maxHeight: number) {
+  const ratio = Math.min(maxWidth / sourceWidth, maxHeight / sourceHeight);
+  return {
+    width: sourceWidth * ratio,
+    height: sourceHeight * ratio,
+  };
+}
+
+function loadImage(src: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const image = new Image();
+    image.onload = () => resolve(image);
+    image.onerror = () => reject(new Error("Image load failed"));
+    image.src = src;
+  });
+}
+
+function fontStack(family: OgImageGeneratorInput["tagTypography"]["fontFamily"]): string {
+  if (family === "Georgia") return "Georgia, serif";
+  if (family === "Helvetica") return "Helvetica, Arial, sans-serif";
+  if (family === "Arial") return "Arial, sans-serif";
+  return "Inter, Arial, sans-serif";
+}
+
+function hexToRgba(hex: string, alpha: number): string {
+  const normalized = hex.replace("#", "");
+  const value = normalized.length === 3
+    ? normalized.split("").map((char) => char + char).join("")
+    : normalized;
+  const red = Number.parseInt(value.slice(0, 2), 16);
+  const green = Number.parseInt(value.slice(2, 4), 16);
+  const blue = Number.parseInt(value.slice(4, 6), 16);
+  return `rgba(${red}, ${green}, ${blue}, ${alpha})`;
+}

package/src/lib/tools/og-image-generator-schema.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+
+export const ogImageFormats = ["png", "jpeg", "webp"] as const;
+export const ogImagePresets = ["openGraph", "xHeader", "blogFeatured"] as const;
+export const ogImageTemplates = ["launch", "editorial", "minimal", "bold", "split", "quote"] as const;
+export const ogImageFontFamilies = ["Inter", "Georgia", "Arial", "Helvetica"] as const;
+export const ogImageFontWeights = ["400", "500", "600", "700", "800"] as const;
+export const ogImageGridPatterns = ["none", "grid", "graph", "dots"] as const;
+export const ogImageGridColors = ["black", "white", "gray"] as const;
+export const ogImageBackgroundModes = ["gradient", "solid"] as const;
+
+export type OgImageFormat = (typeof ogImageFormats)[number];
+export type OgImagePreset = (typeof ogImagePresets)[number];
+export type OgImageTemplate = (typeof ogImageTemplates)[number];
+export type OgImageFontFamily = (typeof ogImageFontFamilies)[number];
+export type OgImageFontWeight = (typeof ogImageFontWeights)[number];
+export type OgImageGridPattern = (typeof ogImageGridPatterns)[number];
+export type OgImageGridColor = (typeof ogImageGridColors)[number];
+export type OgImageBackgroundMode = (typeof ogImageBackgroundModes)[number];
+
+export const OG_IMAGE_PRESET_META: Record<
+  OgImagePreset,
+  { width: number; height: number; filename: string }
+> = {
+  openGraph: { width: 1200, height: 630, filename: "open-graph-image" },
+  xHeader: { width: 1500, height: 500, filename: "x-header-image" },
+  blogFeatured: { width: 1600, height: 900, filename: "blog-featured-image" },
+};
+
+export const ogImageTypographySchema = z.object({
+  fontFamily: z.enum(ogImageFontFamilies),
+  fontWeight: z.enum(ogImageFontWeights),
+  fontSize: z.number().min(10).max(120),
+  color: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+});
+
+export type OgImageTypography = z.infer<typeof ogImageTypographySchema>;
+
+export const DEFAULT_TAG_TYPOGRAPHY: OgImageTypography = {
+  fontFamily: "Inter",
+  fontWeight: "800",
+  fontSize: 18,
+  color: "#111111",
+};
+
+export const DEFAULT_TITLE_TYPOGRAPHY: OgImageTypography = {
+  fontFamily: "Inter",
+  fontWeight: "700",
+  fontSize: 56,
+  color: "#FFFFFF",
+};
+
+export const ogImageGeneratorInputSchema = z.object({
+  sourceUrl: z.string().trim().url().optional().or(z.literal("")),
+  brief: z.string().trim().max(420).optional(),
+  preset: z.enum(ogImagePresets),
+  template: z.enum(ogImageTemplates),
+  format: z.enum(ogImageFormats),
+  title: z.string().trim().min(4).max(90),
+  subtitle: z.string().trim().max(150).optional(),
+  brand: z.string().trim().max(32).optional(),
+  tags: z.string().trim().max(96).optional(),
+  logoText: z.string().trim().max(12).optional(),
+  logoName: z.string().trim().max(80).optional(),
+  logoDataUrl: z.string().regex(/^data:image\//).max(1_200_000).optional(),
+  decorImageName: z.string().trim().max(80).optional(),
+  decorImageDataUrl: z.string().regex(/^data:image\//).max(1_200_000).optional(),
+  primaryColor: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  accentColor: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  templateBackgroundColor: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  tagTypography: ogImageTypographySchema,
+  titleTypography: ogImageTypographySchema,
+  backgroundMode: z.enum(ogImageBackgroundModes),
+  backgroundColor: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  gridPattern: z.enum(ogImageGridPatterns),
+  gridColor: z.enum(ogImageGridColors),
+  gridOpacity: z.number().min(0).max(1),
+  gridBlurRadius: z.number().min(0).max(100),
+  noise: z.number().min(0).max(1),
+});
+
+export type OgImageGeneratorInput = z.infer<typeof ogImageGeneratorInputSchema>;
+
+export const ogImageMetadataSchema = z.object({
+  url: z.string().url(),
+  finalUrl: z.string().url().optional(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  siteName: z.string().optional(),
+  image: z.string().url().optional(),
+});
+
+export type OgImageMetadata = z.infer<typeof ogImageMetadataSchema>;
+
+export const ogImageAgentSuggestionSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().trim().min(4).max(90),
+  subtitle: z.string().trim().max(150).optional(),
+  brand: z.string().trim().max(32).optional(),
+  tags: z.string().trim().max(96).optional(),
+  logoText: z.string().trim().max(12).optional(),
+  template: z.enum(ogImageTemplates),
+  primaryColor: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  accentColor: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  rationale: z.string().trim().max(220),
+  safeAreaNote: z.string().trim().max(180).optional(),
+});
+
+export const ogImageAgentResultSchema = z.object({
+  promptId: z.string().optional(),
+  promptVersion: z.string().optional(),
+  summary: z.string().trim().max(360),
+  suggestions: z.array(ogImageAgentSuggestionSchema).min(1).max(6),
+  metadata: ogImageMetadataSchema.optional(),
+  usageNotes: z.array(z.string().trim().min(1).max(220)).default([]),
+  limitations: z.array(z.string().trim().min(1).max(220)).default([]),
+  generatedAt: z.string().optional(),
+});
+
+export type OgImageAgentSuggestion = z.infer<typeof ogImageAgentSuggestionSchema>;
+export type OgImageAgentResult = z.infer<typeof ogImageAgentResultSchema>;
+
+export function getOgImageMimeType(format: OgImageFormat): string {
+  if (format === "jpeg") return "image/jpeg";
+  if (format === "webp") return "image/webp";
+  return "image/png";
+}
+
+export function buildOgImageFileName(input: Pick<OgImageGeneratorInput, "preset" | "format">): string {
+  const extension = input.format === "jpeg" ? "jpg" : input.format;
+  return `${OG_IMAGE_PRESET_META[input.preset].filename}.${extension}`;
+}
+
+export function parseOgImageTags(value?: string): string[] {
+  return (value ?? "")
+    .split(/[,\n]/)
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .slice(0, 5);
+}

package/src/lib/tools/ops-catalog.ts

@@ -0,0 +1,102 @@
+import { unstable_cache } from "next/cache";
+
+import {
+  getToolSpec,
+  listToolSpecs,
+} from "../../features/tools/spec-registry";
+import type { ToolSpec, ToolStatus } from "../../features/tools/types";
+import type { AppLocale } from "../../i18n/locale";
+
+import { fetchToolOpsCatalog as fetchToolOpsCatalogFromPortal } from "../../host/server";
+import type { ToolOpsRecord } from "../../host/server";
+import { resolveToolLocaleCopy } from "../../lib/tools/resolve-tool-locale-copy";
+
+/**
+ * Portal catalog is the only publish-status source.
+ * Build phase returns [] so `pnpm build` never depends on Portal (fail closed at runtime).
+ */
+export async function fetchToolOpsCatalog(): Promise<ToolOpsRecord[]> {
+  if (process.env.NEXT_PHASE === "phase-production-build") {
+    return [];
+  }
+
+  try {
+    return await unstable_cache(
+      async () => fetchToolOpsCatalogFromPortal(),
+      ["tools-ops-catalog-v3"],
+      { tags: ["tools-catalog"], revalidate: 60 },
+    )();
+  } catch (error) {
+    console.warn("[tool-ops] portal catalog fetch failed; fail closed", error);
+    return [];
+  }
+}
+
+export function getOpsRow(
+  catalog: ToolOpsRecord[],
+  slug: string,
+): ToolOpsRecord | undefined {
+  return catalog.find((row) => row.slug === slug);
+}
+
+/** No catalog row → draft (not visible in production). Never reads frontend spec. */
+export function getEffectiveStatus(
+  slug: string,
+  catalog: ToolOpsRecord[],
+): ToolStatus {
+  return getOpsRow(catalog, slug)?.status ?? "draft";
+}
+
+export async function getEffectiveStatusForSlug(slug: string): Promise<ToolStatus> {
+  if (!getToolSpec(slug)) {
+    return "draft";
+  }
+  const catalog = await fetchToolOpsCatalog();
+  return getEffectiveStatus(slug, catalog);
+}
+
+export async function listIndexedToolSpecs(): Promise<ToolSpec[]> {
+  const catalog = await fetchToolOpsCatalog();
+  if (catalog.length === 0) {
+    return [];
+  }
+
+  const specsBySlug = new Map(listToolSpecs().map((spec) => [spec.slug, spec]));
+
+  return catalog
+    .filter((row) => row.status === "published" && row.showOnIndex)
+    .sort(
+      (left, right) =>
+        left.indexSort - right.indexSort ||
+        left.slug.localeCompare(right.slug),
+    )
+    .flatMap((row) => {
+      const spec = specsBySlug.get(row.slug);
+      return spec ? [spec] : [];
+    });
+}
+
+export function isToolFeaturedOnIndex(
+  spec: ToolSpec,
+  catalog: ToolOpsRecord[],
+): boolean {
+  const row = getOpsRow(catalog, spec.slug);
+  if (row) {
+    return row.featured;
+  }
+  return Boolean(spec.seo.featured);
+}
+
+export function getEffectiveCategory(
+  spec: ToolSpec,
+  locale: AppLocale,
+  catalog: ToolOpsRecord[],
+): string {
+  const row = getOpsRow(catalog, spec.slug);
+  const localized =
+    locale === "zh" ? row?.categoryZh?.trim() : row?.categoryEn?.trim();
+  if (localized) {
+    return localized;
+  }
+  return resolveToolLocaleCopy(spec, locale).category;
+}