backend-manager 5.2.18 → 5.3.0

package/src/manager/libraries/ai/index.js

@@ -92,6 +92,39 @@ AI.prototype.request = async function (options) {
   return result;
 };
 
+/**
+ * Generate an image. Dispatches to the provider's image() method.
+ *
+ * Currently only OpenAI (gpt-image-2) implements image generation.
+ *
+ *   const ai = Manager.AI(assistant);
+ *   const { buffer } = await ai.image({ prompt: 'a flat vector rocket', size: '1024x1024' });
+ *
+ * @param {object} options
+ * @param {string}  options.prompt        - Image description (required)
+ * @param {'openai'} [options.provider='openai']
+ * @param {string} [options.model]        - default gpt-image-2
+ * @param {string} [options.size]         - 1024x1024 | 1536x1024 | 1024x1536 | auto
+ * @param {string} [options.quality]      - low | medium | high | auto
+ * @param {string} [options.background]   - transparent | opaque | auto
+ * @param {number} [options.n]            - how many images (default 1)
+ * @param {string} [options.apiKey]
+ * @returns {Promise<{buffer, b64, mime, revisedPrompt, model, size, quality, raw}>}
+ */
+AI.prototype.image = async function (options) {
+  const self = this;
+  const opts = options || {};
+  const provider = opts.provider || DEFAULT_PROVIDER;
+
+  const client = self._getProvider(provider, opts.apiKey);
+
+  if (typeof client.image !== 'function') {
+    throw new Error(`AI provider "${provider}" does not support image generation`);
+  }
+
+  return client.image(opts);
+};
+
 AI.prototype._getProvider = function (provider, apiKey) {
   const self = this;
 

package/src/manager/libraries/ai/providers/openai.js

@@ -9,6 +9,7 @@ const mimeTypes = require('mime-types');
 // Constants
 const DEFAULT_MODEL = 'gpt-5.4-mini';
 const MODERATION_MODEL = 'omni-moderation-latest';
+const IMAGE_DEFAULT_MODEL = 'gpt-image-2';
 
 // OpenAI model pricing table (per 1M tokens)
 // https://platform.openai.com/docs/pricing
@@ -395,10 +396,12 @@ OpenAI.prototype.request = function (options) {
     // Reasons
     options.reasoning = options.reasoning || undefined;
 
-    // Tools (e.g. built-in web_search). Opt-in — when omitted, no tools are sent
-    // and behavior is identical to a plain request.
+    // Tools — nested, opt-in. `tools.list` is an array of tool definitions (built-in
+    // hosted tools like `{ type: 'web_search' }`, OR custom function tools like
+    // `{ type: 'function', name, parameters }`); `tools.choice` maps to `tool_choice`
+    // (`auto` | `required` | `none` | a specific tool). When omitted/empty, no tools
+    // are sent and behavior is identical to a plain request.
     options.tools = options.tools || undefined;
-    options.toolChoice = options.toolChoice || undefined;
 
     // Format prompt
     //
@@ -512,6 +515,100 @@ OpenAI.prototype.request = function (options) {
   });
 }
 
+/**
+ * Generate an image via OpenAI's image API (gpt-image-2 by default).
+ *
+ * Returns the raw bytes — caller decides what to do with them (upload to a CDN,
+ * embed as a data URL, write to disk, etc.). gpt-image-* always returns base64,
+ * so there's no URL-fetch round trip.
+ *
+ * @param {object} options
+ * @param {string}  options.prompt           - The image description (required)
+ * @param {string} [options.model]           - Image model (default gpt-image-2)
+ * @param {string} [options.size]            - 1024x1024 | 1536x1024 | 1024x1536 | auto (default 1024x1024)
+ * @param {string} [options.quality]         - low | medium | high | auto (default medium)
+ * @param {string} [options.background]      - transparent | opaque | auto
+ * @param {number} [options.n]               - How many images (default 1)
+ * @param {number} [options.timeout]         - ms (default 300000 — image gen is slow)
+ * @param {boolean}[options.log]
+ * @returns {Promise<{buffer: Buffer, b64: string, mime: string, revisedPrompt: string|null, model: string, size: string, quality: string, raw: object}>}
+ *          (or an array of those when n > 1)
+ */
+OpenAI.prototype.image = function (options) {
+  const self = this;
+  const assistant = self.assistant;
+
+  return new Promise(async function (resolve, reject) {
+    options = _.merge({}, options);
+
+    if (!options.prompt) {
+      return reject(assistant.errorify(`image(): {prompt} is required`, { code: 400 }));
+    }
+
+    options.model = options.model || IMAGE_DEFAULT_MODEL;
+    options.size = options.size || '1024x1024';
+    options.quality = options.quality || 'medium';
+    options.n = options.n || 1;
+    options.timeout = typeof options.timeout === 'undefined' ? 300000 : options.timeout;
+    options.log = typeof options.log === 'undefined' ? false : options.log;
+
+    const body = {
+      model: options.model,
+      prompt: options.prompt,
+      size: options.size,
+      quality: options.quality,
+      n: options.n,
+    };
+
+    // background is opt-in (transparent/opaque/auto)
+    if (options.background) {
+      body.background = options.background;
+    }
+
+    if (options.log) {
+      assistant.log(`OpenAI.image(): model=${options.model} size=${options.size} quality=${options.quality} n=${options.n}`);
+    }
+
+    let data;
+    try {
+      data = await fetch('https://api.openai.com/v1/images/generations', {
+        method: 'post',
+        response: 'json',
+        timeout: options.timeout,
+        tries: options.tries || 1,
+        headers: {
+          'Authorization': `Bearer ${self.key}`,
+          'Content-Type': 'application/json',
+        },
+        body: body,
+      });
+    } catch (e) {
+      return reject(assistant.errorify(`OpenAI.image() request failed: ${e.message}`, { code: e.code || 500 }));
+    }
+
+    if (!data?.data?.length) {
+      return reject(assistant.errorify(`OpenAI.image() returned no image data: ${JSON.stringify(data).slice(0, 300)}`, { code: 500 }));
+    }
+
+    const mapItem = (item) => {
+      const b64 = item.b64_json;
+      return {
+        buffer: b64 ? Buffer.from(b64, 'base64') : null,
+        b64: b64 || null,
+        mime: 'image/png',
+        revisedPrompt: item.revised_prompt || null,
+        model: options.model,
+        size: options.size,
+        quality: options.quality,
+        raw: data,
+      };
+    };
+
+    // Single image (the common case) returns one object; n > 1 returns an array.
+    return resolve(options.n === 1 ? mapItem(data.data[0]) : data.data.map(mapItem));
+  });
+};
+
 function tryParse(content) {
   try {
     return JSON5.parse(content);
@@ -983,15 +1080,15 @@ function makeRequest(mode, options, self, promptSegments, message, user, _log) {
         request.body.reasoning = reasoning;
       }
 
-      // Only include tools (e.g. web_search) if provided. When present, the
+      // Only include tools if `tools.list` is a non-empty array. When present, the
       // response output may contain tool-call items (e.g. web_search_call)
       // alongside the message — the message extractor below already ignores
       // non-message items, so this is purely additive.
-      if (Array.isArray(options.tools) && options.tools.length) {
-        request.body.tools = options.tools;
+      if (Array.isArray(options.tools?.list) && options.tools.list.length) {
+        request.body.tools = options.tools.list;
 
-        if (options.toolChoice) {
-          request.body.tool_choice = options.toolChoice;
+        if (options.tools.choice) {
+          request.body.tool_choice = options.tools.choice;
         }
       }
     }

package/src/manager/libraries/content/ghostii.js

@@ -1,10 +1,17 @@
 /**
  * Ghostii article engine — shared helpers for AI article generation + publishing.
  *
- * Ghostii (api.ghostii.ai) writes a full blog article (title, body, header image,
- * categories, keywords) from a free-form description. We then publish it to the
- * brand's website repo via the internal `admin/post` route (commits markdown +
- * images to GitHub).
+ * Ghostii (api.ghostii.ai) is UNOPINIONATED about BEM. It returns a generic,
+ * structured article: a `json` block array ([{ name, content }]) plus `title`,
+ * `description`, `headerImageUrl`, `categories`, `keywords`. It is NOT shaped to
+ * BEM's post format — BEM is responsible for transforming Ghostii's output into
+ * what its `admin/post` route expects.
+ *
+ * `blocksToPost()` is that transform: it digests the JSON blocks and pulls out
+ * the title (heading-1), the header image (first image block), and the clean
+ * body (every remaining block — sections, paragraphs, section images, quotes —
+ * joined as markdown, with NO title or header image embedded, since admin/post
+ * adds those itself from the separate `title`/`headerImageURL` fields).
  *
  * Two consumers:
  *   - events/cron/daily/ghostii-auto-publisher.js — standalone daily article job
@@ -23,12 +30,15 @@ const powertools = require('node-powertools');
  * @param {object} args.brand - Public brand config ({ brand: { url, ... }, github: { ... } })
  * @param {string} args.description - The article brief / prompt content
  * @param {string[]} [args.links] - Optional links to inject into the article body
- * @returns {Promise<object>} { title, description, body, headerImageUrl, categories, keywords }
+ * @returns {Promise<object>} Ghostii's generic article response:
+ *   { title, description, body, json, headerImageUrl, images, categories, keywords, links, outline }
+ *   where `json` is the structured block array ([{ name, content }]) that
+ *   blocksToPost() consumes to build BEM's post shape.
  */
 function writeArticle({ brand, description, links }) {
   return fetch('https://api.ghostii.ai/write/article', {
     method: 'post',
-    timeout: 90000,
+    timeout: 180000,
     tries: 1,
     response: 'json',
     body: {
@@ -36,6 +46,10 @@ function writeArticle({ brand, description, links }) {
       keywords: [''],
       description: description,
       insertLinks: true,
+      research: true,
+      insertImages: true,
+      length: 'long',
+      maxLinks: 6,
       headerImageUrl: 'unsplash',
       url: brand.brand.url,
       sectionQuantity: powertools.random(3, 6, { mode: 'gaussian' }),
@@ -45,13 +59,51 @@ function writeArticle({ brand, description, links }) {
   });
 }
 
+/**
+ * Transform Ghostii's generic JSON block array into BEM's post shape.
+ *
+ * Ghostii returns `json: [{ name, content }]` where name ∈ heading-1..6, image,
+ * paragraph, blockquote, list. BEM's admin/post wants the title + header image as
+ * SEPARATE fields and a body that is ONLY the content below them. So we extract:
+ *   - title       ← first heading-1 block (markdown `#` stripped)
+ *   - headerImageUrl ← first image block's URL
+ *   - body        ← every remaining block, joined as markdown
+ *
+ * @param {Array} json - Ghostii's block array.
+ * @returns {{ title: string, headerImageUrl: string, body: string }}
+ */
+function blocksToPost(json) {
+  const blocks = Array.isArray(json) ? json : [];
+
+  const titleBlock = blocks.find((b) => b.name === 'heading-1');
+  const imageBlock = blocks.find((b) => b.name === 'image');
+
+  // Title: strip the leading markdown heading marker.
+  const title = (titleBlock?.content || '').replace(/^#+\s*/, '').trim();
+
+  // Header image: pull the URL out of `![alt](url)`.
+  const imageMatch = (imageBlock?.content || '').match(/\((.*?)\)\s*$/);
+  const headerImageUrl = imageMatch ? imageMatch[1] : '';
+
+  // Body: everything except the title block and the header-image block.
+  const body = blocks
+    .filter((b) => b !== titleBlock && b !== imageBlock)
+    .map((b) => b.content)
+    .join('\n\n')
+    .trim();
+
+  return { title, headerImageUrl, body };
+}
+
 /**
  * Publish a Ghostii article to the brand's website repo via the admin/post route.
  *
  * @param {object} assistant - BEM assistant instance
  * @param {object} args
  * @param {object} args.brand - Public brand config ({ brand: { url, ... }, github: { user, repo } })
- * @param {object} args.article - The article from writeArticle()
+ * @param {object} args.article - The article from writeArticle(). When it carries a
+ *   `json` block array, the post is reconstructed via blocksToPost() (title + header
+ *   image extracted, body = content only). Falls back to article.{title,body,headerImageUrl}.
  * @param {number} args.id - Post ID (unix timestamp)
  * @param {string} [args.author] - Author slug (admin/post picks a default if unset)
  * @param {string} [args.postPath='ghostii'] - Sub-folder under _posts/{year}/
@@ -61,18 +113,26 @@ async function publishArticle(assistant, { brand, article, id, author, postPath
   const baseUrl = (brand.brand.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
   const apiUrl = `https://api.${baseUrl}`;
 
-  const post = await fetch(`${apiUrl}/backend-manager/admin/post`, {
+  // Transform Ghostii's generic JSON into BEM's post shape (title + header image
+  // as separate fields, body = content only). Fall back to the legacy flat fields
+  // for older Ghostii responses that don't include `json`.
+  const post = blocksToPost(article.json);
+  const title = post.title || article.title;
+  const headerImageUrl = post.headerImageUrl || article.headerImageUrl;
+  const body = article.json ? post.body : article.body;
+
+  const result = await fetch(`${apiUrl}/backend-manager/admin/post`, {
     method: 'POST',
     timeout: 90000,
     tries: 1,
     response: 'json',
     body: {
       backendManagerKey: process.env.BACKEND_MANAGER_KEY,
-      title: article.title,
-      url: article.title, // Slugified on the admin/post endpoint
+      title: title,
+      url: title, // Slugified on the admin/post endpoint
       description: article.description,
-      headerImageURL: article.headerImageUrl,
-      body: article.body,
+      headerImageURL: headerImageUrl,
+      body: body,
       id: id,
       author: author,
       categories: article.categories,
@@ -86,15 +146,15 @@ async function publishArticle(assistant, { brand, article, id, author, postPath
   // admin/post returns the resolved `settings` (incl. the slugified `url` and repo `path`).
   // The post template sets no permalink, so the public URL follows the Jekyll/UJM
   // blog convention: {brand.url}/blog/{slug}.
-  const slug = post?.url || '';
+  const slug = result?.url || '';
   const publicUrl = `${(brand.brand.url || '').replace(/\/$/, '')}/blog/${slug}`;
 
   return {
-    post,
+    post: result,
     url: slug ? publicUrl : null,
     slug,
-    path: post?.path || null,
+    path: result?.path || null,
   };
 }
 
-module.exports = { writeArticle, publishArticle };
+module.exports = { writeArticle, publishArticle, blocksToPost };

package/src/manager/libraries/email/data/disposable-domains.json

@@ -602,6 +602,7 @@
   "beaconmessenger.com",
   "bearsarefuzzy.com",
   "beastmail.space",
+  "beatbok.online",
   "beddly.com",
   "beefmilk.com",
   "beelsil.com",
@@ -1277,6 +1278,7 @@
   "doobb.com",
   "doojazz.com",
   "doquier.tk",
+  "doreact.com",
   "dotapodemail.com",
   "dotman.de",
   "dotmsg.com",
@@ -1832,6 +1834,7 @@
   "freeteenbums.com",
   "freetimer.online",
   "freundin.ru",
+  "friday12.store",
   "friendlymail.co.uk",
   "frm.ovh",
   "front14.org",
@@ -2057,6 +2060,7 @@
   "gowikitv.com",
   "grandmamail.com",
   "grandmasmail.com",
+  "graphicbulk.site",
   "graphicenda.site",
   "grassdev.com",
   "gravityengine.cc",
@@ -2127,6 +2131,7 @@
   "haltospam.com",
   "hamham.uk",
   "handrik.com",
+  "hanghai232.shop",
   "hangxomcuatoilatotoro.ml",
   "happiseektest.com",
   "happy-new-year.top",
@@ -2237,6 +2242,7 @@
   "housereformas.es",
   "hpari.com",
   "hpc.tw",
+  "hqpdf.com",
   "hs.vc",
   "hsmw.net",
   "ht.cx",
@@ -2256,6 +2262,7 @@
   "hushmail.cf",
   "huskion.net",
   "hutudns.com",
+  "huytuyen.click",
   "hvastudiesucces.nl",
   "hwsye.net",
   "hxopi.ru",
@@ -2488,6 +2495,7 @@
   "jdmadventures.com",
   "jdz.ro",
   "je-recycle.info",
+  "jejes.de",
   "jellow.ml",
   "jellyrolls.com",
   "jeoce.com",
@@ -2713,6 +2721,7 @@
   "laste.ml",
   "lastmail.co",
   "lastmail.com",
+  "laulund.info",
   "launders.money",
   "lawlita.com",
   "laxex.ru",
@@ -3162,6 +3171,7 @@
   "midlertidig.com",
   "midlertidig.net",
   "midlertidig.org",
+  "midwestpride.org",
   "mierdamail.com",
   "migmail.net",
   "migmail.pl",
@@ -3375,6 +3385,7 @@
   "nanonym.ch",
   "nanopools.info",
   "naobk.com",
+  "narrowment.com",
   "narsub.online",
   "narsub.shop",
   "naslazhdai.ru",
@@ -3541,6 +3552,7 @@
   "nutpa.net",
   "nuts2trade.com",
   "nvhrw.com",
+  "nvqt304.xyz",
   "nwldx.com",
   "nwytg.com",
   "nwytg.net",
@@ -3583,6 +3595,7 @@
   "oku.ovh",
   "oky.ovh",
   "okzk.com",
+  "oldao.com",
   "olimp-case.ru",
   "oliviadiffuser.store",
   "oloh.ru",
@@ -3593,6 +3606,7 @@
   "omarnasrrr.com",
   "omfg.run",
   "omnievents.org",
+  "omnilog.space",
   "omtecha.com",
   "onbap.com",
   "one-mail.top",
@@ -3821,6 +3835,7 @@
   "powerscrews.com",
   "powlearn.com",
   "pox2.com",
+  "pozima.rest",
   "pp7rvv.com",
   "ppetw.com",
   "pptrvv.com",
@@ -4059,6 +4074,7 @@
   "royaldoodles.org",
   "royalmarket.life",
   "royandk.com",
+  "roybl.com",
   "rppkn.com",
   "rr.nu",
   "rsvhr.com",
@@ -4068,6 +4084,7 @@
   "rudymail.ml",
   "rulersonline.com",
   "rumgel.com",
+  "run.place",
   "runi.ca",
   "rupayamail.com",
   "ruru.be",
@@ -4096,6 +4113,7 @@
   "sahildash.dev",
   "sailmail.io",
   "sajutadollars.com",
+  "salakoais.shop",
   "saleis.live",
   "salmeow.tk",
   "sam1.eu.org",
@@ -4418,6 +4436,7 @@
   "spymail.one",
   "squizzy.de",
   "squizzy.net",
+  "srame.com",
   "sroff.com",
   "sry.li",
   "ssi-bsn.infos.st",
@@ -4815,6 +4834,7 @@
   "trackden.com",
   "tradermail.info",
   "tranceversal.com",
+  "trandigabapoe.shop",
   "trangiabao.click",
   "trangzim.uk",
   "translateid.com",
@@ -5286,6 +5306,7 @@
   "wyoxafp.com",
   "wywnxa.com",
   "wzofit.com",
+  "x-clone.asia",
   "x-lab.net",
   "x0q.net",
   "x1ix.com",
@@ -5294,6 +5315,8 @@
   "xagloo.com",
   "xapimail.top",
   "xbaby69.top",
+  "xbrok.com",
+  "xclone.asia",
   "xcode.ro",
   "xcodes.net",
   "xcompress.com",
@@ -5364,6 +5387,7 @@
   "yeezus.ru",
   "yep.it",
   "yermail.net",
+  "yeummo.io.vn",
   "yhg.biz",
   "ynmrealty.com",
   "yodx.ro",

package/src/manager/libraries/email/generators/lib/image-illustrator.js

@@ -0,0 +1,154 @@
+/**
+ * Image illustrator — AI generates a flat-vector PNG illustration per section
+ * directly via OpenAI's image model (gpt-image-2), no SVG-author-then-rasterize step.
+ *
+ * This is the DEFAULT newsletter illustration method. It replaces the older
+ * svg-illustrator.js approach (AI writes an <svg>, resvg rasterizes it) which is
+ * still available as a fallback via newsletterConfig.method.image = 'svg'.
+ *
+ * Output matches svg-illustrator's contract: { png: Buffer, fallback, meta }.
+ * The newsletter pipeline (image-host.js) only requires `img.png` to be a PNG Buffer.
+ *
+ * Style: clean flat 2D vector illustration (Stripe / Linear / undraw.co aesthetic),
+ * built from the brand palette, on a white background, no text. The prompt mirrors
+ * the validated spike in scripts/.temp/ai-image-test/.
+ */
+const DEFAULT_MODEL = 'gpt-image-2';
+const DEFAULT_SIZE = '1024x1024';     // square reads best for flat section art
+const DEFAULT_QUALITY = 'medium';     // medium is plenty for flat vector; ~40-50s/image
+
+/**
+ * Generate one illustration for a section.
+ *
+ * @param {object} args
+ * @param {string} args.imagePrompt - Visual description from the structure
+ * @param {object} args.brand - { name, tagline, color: { primary, secondary, ... } }
+ * @param {object} args.newsletterConfig - marketing.beehiiv.content
+ * @param {object} args.ai - Manager.AI() instance
+ * @param {object} args.assistant - BEM assistant
+ * @returns {Promise<{png: Buffer, fallback: boolean, meta: object}>}
+ */
+async function generateSectionImage({ imagePrompt, brand, newsletterConfig, ai, assistant }) {
+  const startTime = Date.now();
+  const model = newsletterConfig?.model?.image || DEFAULT_MODEL;
+  const size = newsletterConfig?.image?.size || DEFAULT_SIZE;
+  const quality = newsletterConfig?.image?.quality || DEFAULT_QUALITY;
+
+  const palette = resolvePalette(brand, newsletterConfig);
+  const subject = imagePrompt || 'An abstract geometric shape representing the topic.';
+  const prompt = buildImagePrompt({ brand, palette, subject });
+
+  let png = null;
+  let fallback = false;
+  let revisedPrompt = null;
+  let attempts = 0;
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    attempts++;
+    try {
+      const result = await ai.image({
+        provider: 'openai',
+        model,
+        prompt,
+        size,
+        quality,
+        background: 'opaque',
+      });
+
+      if (result?.png || result?.buffer) {
+        png = result.png || result.buffer;
+        revisedPrompt = result.revisedPrompt || null;
+        break;
+      }
+
+      assistant.log(`Image generation attempt ${attempt + 1} returned no buffer`);
+    } catch (e) {
+      assistant.error(`Image generation attempt ${attempt + 1} failed: ${e.message}`);
+    }
+  }
+
+  // No transparent-PNG placeholder fallback that's valid as an image — if both
+  // attempts fail, return a 1x1 transparent PNG so the pipeline doesn't crash on
+  // a non-Buffer. The caller logs and proceeds.
+  if (!png) {
+    png = TRANSPARENT_PNG;
+    fallback = true;
+  }
+
+  return {
+    png,
+    fallback,
+    meta: {
+      method: 'image',
+      provider: 'openai',
+      model,
+      size,
+      quality,
+      durationMs: Date.now() - startTime,
+      attempts,
+      fallback,
+      revisedPrompt,
+    },
+  };
+}
+
+/**
+ * Resolve brand palette — same precedence as svg-illustrator.js#resolvePalette:
+ * newsletter theme colors → brand.color.* → sensible defaults.
+ */
+function resolvePalette(brand, newsletterConfig) {
+  const theme = newsletterConfig?.theme || {};
+
+  return {
+    primary:   theme.primaryColor   || brand?.color?.primary   || '#4B5BFF',
+    secondary: theme.secondaryColor || brand?.color?.secondary || '#1E1E2A',
+    accent:    theme.accentColor    || brand?.color?.accent    || '#F4F6FA',
+  };
+}
+
+/**
+ * Build the flat-vector art-direction prompt with brand identity + palette baked in.
+ * Mirrors the validated prompt from scripts/.temp/ai-image-test/generate.js.
+ */
+function buildImagePrompt({ brand, palette, subject }) {
+  const { primary, secondary, accent } = palette;
+  const name = brand?.name || 'the brand';
+  const tagline = brand?.tagline ? ` — ${brand.tagline}` : '';
+
+  return [
+    `Minimal flat vector illustration for the newsletter of "${name}"${tagline}.`,
+    '',
+    'STYLE: modern flat 2D vector illustration, like the marketing graphics on',
+    'Stripe, Linear, Vercel, Notion, or undraw.co. Clean geometric shapes with',
+    'flat solid color fills and crisp edges. Simple, friendly, and minimal.',
+    '',
+    'ABSOLUTELY NOT: no photorealism, no 3D renders, no realistic textures, no',
+    'photography, no depth of field, no dramatic lighting, no film grain, no',
+    'shading or gradients beyond a single subtle flat tone shift, no glossy',
+    'reflections, no metallic surfaces. This must look hand-designed in a vector',
+    'tool (Figma/Illustrator), NOT rendered or photographed.',
+    '',
+    'PALETTE (use ONLY these flat colors, plus white):',
+    `- Primary:   ${primary}`,
+    `- Secondary: ${secondary}`,
+    `- Accent:    ${accent}`,
+    'Flat solid fills only. A clean white or very-light background.',
+    '',
+    'COMPOSITION: single clear simple subject, lots of clean negative space,',
+    'centered or rule-of-thirds, uncluttered, plenty of breathing room.',
+    '',
+    'HARD CONSTRAINTS: absolutely NO text, NO words, NO letters, NO numbers,',
+    'NO logos, NO watermarks, NO UI mockups, NO borders or frames.',
+    '',
+    `SUBJECT (the focal scene to illustrate): ${subject}`,
+  ].join('\n');
+}
+
+// 1x1 transparent PNG — last-resort fallback so a failed generation still yields a
+// valid PNG Buffer instead of crashing image-host.js's Buffer check.
+const TRANSPARENT_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+  'base64'
+);
+
+module.exports = { generateSectionImage };