@gobing-ai/knowledge-kit 0.0.27 → 0.0.29

package/plugins/generations/image-gen/dist/index.js

@@ -21809,8 +21809,332 @@ function findProjectRoot(startDir) {
 }
 var init_file_system_node = () => {};
 
+// ../../plugins/generations/image-gen/src/bytes.ts
+import { readFile, writeFile } from "fs/promises";
+async function writeBytes(path2, bytes) {
+  await writeFile(path2, bytes);
+}
+async function readBytes(path2) {
+  return new Uint8Array(await readFile(path2));
+}
+function imageDimensions(bytes) {
+  const PNG_SIG = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (bytes.byteLength < 24) {
+    throw new Error("imageDimensions: not a PNG \u2014 buffer too small");
+  }
+  for (let i = 0;i < 8; i++) {
+    if (bytes[i] !== PNG_SIG[i]) {
+      throw new Error("imageDimensions: not a PNG \u2014 invalid signature");
+    }
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const ihdrLength = view.getUint32(8, false);
+  if (ihdrLength !== 13 || bytes[12] !== 73 || bytes[13] !== 72 || bytes[14] !== 68 || bytes[15] !== 82) {
+    throw new Error("imageDimensions: not a PNG \u2014 IHDR chunk not found at offset 8");
+  }
+  const width = view.getUint32(16, false);
+  const height = view.getUint32(20, false);
+  return { width, height };
+}
+var init_bytes = () => {};
+
+// ../../plugins/generations/image-gen/src/compose/card.ts
+function assertCoverage(input, fonts) {
+  const headlineCover = fonts.get(input.compose.fonts.headline);
+  const bodyCover = fonts.get(input.compose.fonts.body);
+  if (headlineCover === undefined) {
+    throw new Error(`compose: headline font '${input.compose.fonts.headline}' not loaded`);
+  }
+  if (bodyCover === undefined) {
+    throw new Error(`compose: body font '${input.compose.fonts.body}' not loaded`);
+  }
+  const checkField = (text, fieldName, covers) => {
+    for (const ch of text) {
+      const cp = ch.codePointAt(0);
+      if (cp === undefined)
+        continue;
+      if (cp <= 32 || cp === 160 || cp >= 8192 && cp <= 8207 || cp === 12288) {
+        continue;
+      }
+      if (!covers(cp)) {
+        const hex3 = `U+${cp.toString(16).toUpperCase().padStart(4, "0")}`;
+        const fontName = fieldName.startsWith("points") ? input.compose.fonts.body : input.compose.fonts.headline;
+        throw new Error(`compose: ${fieldName} has ${hex3} '${ch}' not covered by ${fontName}`);
+      }
+    }
+  };
+  checkField(input.headline, "headline", headlineCover);
+  for (const [i, point] of input.points.entries()) {
+    checkField(point, `points[${i}]`, bodyCover);
+  }
+}
+function assertTextFreePrompt(prompt, copy, sources) {
+  const hit = (text) => {
+    const headline = copy.headline.trim();
+    if (headline.length >= 2 && text.includes(headline))
+      return `the headline '${headline}'`;
+    for (const point of copy.points) {
+      const trimmed = point.trim();
+      if (trimmed.length >= 2 && text.includes(trimmed))
+        return `point '${trimmed}'`;
+    }
+    const han = /\p{Script=Han}/u.exec(text);
+    if (han !== null) {
+      const cp = (han[0]?.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, "0");
+      return `Han character '${han[0]}' (U+${cp})`;
+    }
+    return null;
+  };
+  const fail = (source, what2) => {
+    throw new Error(`compose: the illustration prompt must stay text-free \u2014 ${source} contributes ${what2} (card copy is typeset, never prompted)`);
+  };
+  for (const { source, text } of sources) {
+    const what2 = hit(text);
+    if (what2 !== null)
+      fail(source, what2);
+  }
+  const what = hit(prompt);
+  if (what !== null)
+    fail("the composed prompt", what);
+}
+function cardHtml(input, fontUrls) {
+  const { compose: cfg, width, height, illustration } = input;
+  const { safeArea, headlineMinPx, bodyMinPx, illustrationHeight, palette } = cfg;
+  const headlineFont = fontUrls.get(cfg.fonts.headline) ?? "";
+  const bodyFont = fontUrls.get(cfg.fonts.body) ?? "";
+  const headlineStartPx = headlineMinPx * 1.5;
+  const textPanelHeight = height - illustrationHeight;
+  const safeWidth = width - safeArea * 2;
+  const illustrationSrc = illustration ? `data:${illustration.mime};base64,${Buffer.from(illustration.bytes).toString("base64")}` : "";
+  const pointsHtml = input.points.map((pt, i) => `<div class="point" data-field="points[${i}]" style="font-size:${bodyMinPx}px;">${escHtml(pt)}</div>`).join(`
+`);
+  return `<!DOCTYPE html>
+<html lang="zh-Hans">
+<head>
+<meta charset="utf-8">
+<style>
+@font-face {
+  font-family: 'NotoSansSC-Bold';
+  src: url('${headlineFont}') format('opentype');
+  font-weight: bold;
+  font-style: normal;
+}
+@font-face {
+  font-family: 'NotoSansSC-Regular';
+  src: url('${bodyFont}') format('opentype');
+  font-weight: normal;
+  font-style: normal;
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+html, body {
+  width: ${width}px;
+  height: ${height}px;
+  overflow: hidden;
+  background: ${palette.background};
+}
+.card {
+  width: ${width}px;
+  height: ${height}px;
+  display: flex;
+  flex-direction: column;
+  background: ${palette.background};
+}
+.illustration-band {
+  width: ${width}px;
+  height: ${illustrationHeight}px;
+  flex-shrink: 0;
+  overflow: hidden;
+  background: ${palette.background};
+}
+.illustration-band img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+.text-panel {
+  width: ${width}px;
+  height: ${textPanelHeight}px;
+  flex-shrink: 0;
+  padding: ${safeArea}px;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-start;
+  overflow: hidden;
+  background: ${palette.background};
+}
+.headline {
+  font-family: 'NotoSansSC-Bold', sans-serif;
+  font-weight: bold;
+  color: ${palette.text};
+  line-height: 1.3;
+  margin-bottom: ${Math.round(safeArea / 2)}px;
+  word-break: break-all;
+  white-space: normal;
+  /* font-size is set inline with JS fit-step */
+  font-size: ${headlineStartPx}px;
+}
+.points-container {
+  display: flex;
+  flex-direction: column;
+  gap: ${Math.round(bodyMinPx * 0.5)}px;
+}
+.point {
+  font-family: 'NotoSansSC-Regular', sans-serif;
+  font-weight: normal;
+  color: ${palette.text};
+  line-height: 1.5;
+  word-break: break-all;
+  white-space: normal;
+}
+.safe-area-sentinel {
+  position: absolute;
+  top: ${illustrationHeight + safeArea}px;
+  left: ${safeArea}px;
+  width: ${safeWidth}px;
+  height: ${textPanelHeight - safeArea * 2}px;
+  pointer-events: none;
+}
+</style>
+</head>
+<body>
+<div class="card">
+  <div class="illustration-band">
+    ${illustrationSrc ? `<img src="${illustrationSrc}" alt="">` : `<div style="width:100%;height:100%;background:${palette.background};"></div>`}
+  </div>
+  <div class="text-panel">
+    <div class="headline" data-field="headline" id="headline">${escHtml(input.headline)}</div>
+    <div class="points-container">
+      ${pointsHtml}
+    </div>
+  </div>
+</div>
+<div class="safe-area-sentinel" id="safe-area-sentinel"></div>
+<script>
+(function () {
+  // Step headline font down from start until it fits, never below floor.
+  var headline = document.getElementById('headline');
+  var headlineMinPx = ${headlineMinPx};
+  var headlineStartPx = ${headlineStartPx};
+  var safeWidth = ${safeWidth};
+  var panelHeight = ${textPanelHeight - safeArea * 2};
+  var size = headlineStartPx;
+  while (size > headlineMinPx) {
+    headline.style.fontSize = size + 'px';
+    if (headline.scrollWidth <= safeWidth && headline.scrollHeight <= panelHeight) break;
+    size -= 4;
+  }
+  headline.style.fontSize = Math.max(size, headlineMinPx) + 'px';
+})();
+</script>
+</body>
+</html>`;
+}
+function escHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+// ../../plugins/generations/image-gen/src/compose/chromium.ts
+var exports_chromium = {};
+__export(exports_chromium, {
+  makeChromiumComposer: () => makeChromiumComposer,
+  ChromiumComposer: () => ChromiumComposer
+});
+import { join as join3 } from "path";
+function fontRouteUrls(fontNames) {
+  const map2 = new Map;
+  for (const name of fontNames) {
+    map2.set(name, `${FONT_ROUTE_BASE}${encodeURIComponent(name)}`);
+  }
+  return map2;
+}
+
+class ChromiumComposer {
+  async compose(input) {
+    let chromium;
+    try {
+      const pw = await import("playwright");
+      chromium = pw.chromium;
+    } catch (err) {
+      throw new Error(`compose: Playwright is not installed. Run: bunx playwright install chromium
+(${err instanceof Error ? err.message : String(err)})`);
+    }
+    const fontNames = [input.compose.fonts.headline, input.compose.fonts.body];
+    const fontUrls = fontRouteUrls(fontNames);
+    const html = cardHtml(input, fontUrls);
+    let browser;
+    try {
+      try {
+        browser = await chromium.launch({ headless: true });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`compose: Chromium browser not found. Run: bunx playwright install chromium
+(${msg})`);
+      }
+      const page = await browser.newPage({
+        viewport: { width: input.width, height: input.height },
+        deviceScaleFactor: 1
+      });
+      await page.route(`${FONT_ROUTE_BASE}**`, async (route) => {
+        const url2 = new URL(route.request().url());
+        const fontName = decodeURIComponent(url2.pathname.slice(1));
+        const fontPath = join3(FONTS_DIR, fontName);
+        try {
+          const bytes = await readBytes(fontPath);
+          await route.fulfill({
+            status: 200,
+            contentType: "font/otf",
+            body: Buffer.from(bytes)
+          });
+        } catch {
+          await route.abort();
+        }
+      });
+      await page.setContent(html, { waitUntil: "domcontentloaded" });
+      await page.evaluate("document.fonts.ready");
+      const { safeArea, illustrationHeight } = input.compose;
+      const safeLeft = safeArea;
+      const safeTop = illustrationHeight + safeArea;
+      const safeRight = input.width - safeArea;
+      const safeBottom = input.height - safeArea;
+      const overflowExpr = `
+                (function(safeLeft, safeTop, safeRight, safeBottom) {
+                    var results = [];
+                    var els = Array.from(document.querySelectorAll('[data-field]'));
+                    for (var i = 0; i < els.length; i++) {
+                        var el = els[i];
+                        var field = el.dataset.field || '';
+                        var rect = el.getBoundingClientRect();
+                        if (rect.left < safeLeft || rect.top < safeTop || rect.right > safeRight || rect.bottom > safeBottom) {
+                            results.push({ field: field, rect: { top: rect.top, left: rect.left, bottom: rect.bottom, right: rect.right } });
+                        }
+                    }
+                    return results;
+                })(${safeLeft}, ${safeTop}, ${safeRight}, ${safeBottom})
+            `;
+      const overflows = await page.evaluate(overflowExpr);
+      if (overflows.length > 0) {
+        const fields = overflows.map((o) => o.field).join(", ");
+        throw new Error(`compose: text overflows the safe area for field(s): ${fields} (safe area: ${safeArea}px inset)`);
+      }
+      const screenshot = await page.screenshot({ type: "png", animations: "disabled" });
+      return new Uint8Array(screenshot);
+    } finally {
+      await browser?.close();
+    }
+  }
+}
+function makeChromiumComposer() {
+  return new ChromiumComposer;
+}
+var FONTS_DIR, FONT_ROUTE_BASE = "http://kk-fonts.local/";
+var init_chromium = __esm(() => {
+  init_bytes();
+  FONTS_DIR = join3(import.meta.dir, "..", "..", "assets", "fonts");
+});
+
 // ../../plugins/generations/image-gen/src/index.ts
-import { dirname as dirname3 } from "path";
+import { dirname as dirname3, join as join4 } from "path";
 import { parseArgs } from "util";
 
 // ../../packages/kk-core/src/kinds.ts
@@ -21908,14 +22232,141 @@ init_config();
 if (false) {}
 // ../../plugins/generations/image-gen/src/index.ts
 init_dist();
+init_bytes();
 
-// ../../plugins/generations/image-gen/src/bytes.ts
-import { readFile, writeFile } from "fs/promises";
-async function writeBytes(path2, bytes) {
-  await writeFile(path2, bytes);
+// ../../plugins/generations/image-gen/src/compose/cmap.ts
+function u16(view, offset) {
+  return view.getUint16(offset, false);
+}
+function u32(view, offset) {
+  return view.getUint32(offset, false);
+}
+function tag(view, offset) {
+  return String.fromCharCode(view.getUint8(offset), view.getUint8(offset + 1), view.getUint8(offset + 2), view.getUint8(offset + 3));
+}
+function assertBytes(view, offset, needed, context2) {
+  if (offset + needed > view.byteLength) {
+    throw new Error(`compose: truncated font \u2014 expected ${needed} bytes at offset ${offset} (${context2})`);
+  }
+}
+function findCmapTable(view) {
+  assertBytes(view, 0, 12, "sfnt header");
+  const magic = u32(view, 0);
+  if (magic !== 65536 && magic !== 1330926671 && magic !== 1953658213) {
+    throw new Error(`compose: not a valid sfnt font (magic 0x${magic.toString(16).padStart(8, "0")})`);
+  }
+  const numTables = u16(view, 4);
+  assertBytes(view, 12, numTables * 16, "sfnt table directory");
+  for (let i = 0;i < numTables; i++) {
+    const base = 12 + i * 16;
+    if (tag(view, base) === "cmap") {
+      const offset = u32(view, base + 8);
+      const length = u32(view, base + 12);
+      return { offset, length };
+    }
+  }
+  throw new Error("compose: truncated font \u2014 cmap table not found in sfnt directory");
+}
+function coverageFormat4(view, subtableOffset) {
+  assertBytes(view, subtableOffset, 14, "cmap format 4 header");
+  const length = u16(view, subtableOffset + 2);
+  assertBytes(view, subtableOffset, length, "cmap format 4 body");
+  const segCount = u16(view, subtableOffset + 6) / 2;
+  const endCodesBase = subtableOffset + 14;
+  assertBytes(view, endCodesBase, segCount * 2 + 2 + segCount * 2 + segCount * 2 + segCount * 2, "cmap format 4 segments");
+  const startCodesBase = endCodesBase + segCount * 2 + 2;
+  const idDeltaBase = startCodesBase + segCount * 2;
+  const idRangeOffsetBase = idDeltaBase + segCount * 2;
+  return (cp) => {
+    if (cp > 65535)
+      return false;
+    let lo = 0;
+    let hi = segCount - 1;
+    while (lo <= hi) {
+      const mid = lo + hi >>> 1;
+      const endCode = u16(view, endCodesBase + mid * 2);
+      if (endCode < cp) {
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    if (lo >= segCount)
+      return false;
+    const startCode = u16(view, startCodesBase + lo * 2);
+    if (cp < startCode)
+      return false;
+    const idRangeOffset = u16(view, idRangeOffsetBase + lo * 2);
+    if (idRangeOffset === 0) {
+      const idDelta = u16(view, idDeltaBase + lo * 2);
+      return (cp + idDelta & 65535) !== 0;
+    }
+    const glyphIdAddr = idRangeOffsetBase + lo * 2 + idRangeOffset + (cp - startCode) * 2;
+    if (glyphIdAddr + 2 > view.byteLength)
+      return false;
+    const glyphId = u16(view, glyphIdAddr);
+    return glyphId !== 0;
+  };
+}
+function coverageFormat12(view, subtableOffset) {
+  assertBytes(view, subtableOffset, 16, "cmap format 12 header");
+  const numGroups = u32(view, subtableOffset + 12);
+  assertBytes(view, subtableOffset + 16, numGroups * 12, "cmap format 12 groups");
+  const groupsBase = subtableOffset + 16;
+  return (cp) => {
+    let lo = 0;
+    let hi = numGroups - 1;
+    while (lo <= hi) {
+      const mid = lo + hi >>> 1;
+      const base = groupsBase + mid * 12;
+      const startChar = u32(view, base);
+      const endChar = u32(view, base + 4);
+      if (endChar < cp) {
+        lo = mid + 1;
+      } else if (startChar > cp) {
+        hi = mid - 1;
+      } else {
+        const startGlyph = u32(view, base + 8);
+        return startGlyph + (cp - startChar) !== 0;
+      }
+    }
+    return false;
+  };
 }
-async function readBytes(path2) {
-  return new Uint8Array(await readFile(path2));
+function glyphCoverage(fontBytes) {
+  if (fontBytes.byteLength < 12) {
+    throw new Error("compose: truncated font \u2014 too small for sfnt header");
+  }
+  const view = new DataView(fontBytes.buffer, fontBytes.byteOffset, fontBytes.byteLength);
+  const { offset: cmapOffset } = findCmapTable(view);
+  assertBytes(view, cmapOffset, 4, "cmap table header");
+  const numSubtables = u16(view, cmapOffset + 2);
+  assertBytes(view, cmapOffset + 4, numSubtables * 8, "cmap encoding records");
+  let fmt4Offset;
+  let fmt12Offset;
+  for (let i = 0;i < numSubtables; i++) {
+    const recBase = cmapOffset + 4 + i * 8;
+    const platformId = u16(view, recBase);
+    const encodingId = u16(view, recBase + 2);
+    const subtableOffset = cmapOffset + u32(view, recBase + 4);
+    if (subtableOffset + 2 > view.byteLength)
+      continue;
+    const fmt = u16(view, subtableOffset);
+    if (fmt === 12 && (platformId === 3 || platformId === 0)) {
+      fmt12Offset = subtableOffset;
+    }
+    if (fmt === 4 && (platformId === 3 || platformId === 0) && encodingId !== 10) {
+      if (fmt4Offset === undefined)
+        fmt4Offset = subtableOffset;
+    }
+  }
+  if (fmt12Offset !== undefined) {
+    return coverageFormat12(view, fmt12Offset);
+  }
+  if (fmt4Offset !== undefined) {
+    return coverageFormat4(view, fmt4Offset);
+  }
+  throw new Error("compose: truncated font \u2014 no usable cmap subtable (format 4 or 12) found");
 }
 
 // ../../plugins/generations/image-gen/src/job.ts
@@ -21993,6 +22444,15 @@ var PresetSourceSchema = exports_external.object({
   extractedAt: exports_external.string().optional(),
   confidence: exports_external.enum(["high", "medium", "low"]).optional()
 });
+var ComposeConfigSchema = exports_external.object({
+  engine: exports_external.literal("text-card"),
+  safeArea: exports_external.number(),
+  headlineMinPx: exports_external.number(),
+  bodyMinPx: exports_external.number(),
+  illustrationHeight: exports_external.number(),
+  palette: exports_external.object({ background: exports_external.string(), text: exports_external.string(), accent: exports_external.string() }),
+  fonts: exports_external.object({ headline: exports_external.string(), body: exports_external.string() })
+});
 var FormatPresetSchema = exports_external.object({
   name: exports_external.string(),
   description: exports_external.string(),
@@ -22004,7 +22464,10 @@ var FormatPresetSchema = exports_external.object({
   keywords: exports_external.array(exports_external.string()),
   outputFilename: exports_external.string(),
   variables: exports_external.record(exports_external.string(), exports_external.object({ description: exports_external.string(), default: exports_external.string() })),
-  template: exports_external.string()
+  template: exports_external.string(),
+  compose: ComposeConfigSchema.optional()
+}).refine((data) => data.compose === undefined || data.width !== undefined && data.height !== undefined, {
+  message: "A format preset with a compose block requires both width and height to be declared"
 });
 var StylePresetSchema = exports_external.object({
   name: exports_external.string(),
@@ -22157,6 +22620,7 @@ function loadPresets() {
 import { Buffer as Buffer3 } from "buffer";
 
 // ../../plugins/generations/image-gen/src/providers/refs.ts
+init_bytes();
 import { extname as extname2 } from "path";
 function mimeForPath(path2) {
   const ext = extname2(path2).toLowerCase();
@@ -22178,6 +22642,7 @@ async function refToDataUri(path2) {
 }
 
 // ../../plugins/generations/image-gen/src/providers/seedream.ts
+init_bytes();
 import { Buffer as Buffer2 } from "buffer";
 
 // ../../plugins/generations/image-gen/src/providers/timeouts.ts
@@ -22376,9 +22841,11 @@ var createAgnes = (options) => {
 };
 
 // ../../plugins/generations/image-gen/src/providers/azure.ts
+init_bytes();
 import { extname as extname3 } from "path";
 
 // ../../plugins/generations/image-gen/src/providers/openai.ts
+init_bytes();
 import { Buffer as Buffer4 } from "buffer";
 import { basename as basename2 } from "path";
 var DEFAULT_MODEL3 = "gpt-image-2";
@@ -22788,6 +23255,7 @@ var createAzure = (options) => {
 };
 
 // ../../plugins/generations/image-gen/src/providers/codex-cli.ts
+init_bytes();
 import { spawn } from "child_process";
 import { randomBytes } from "crypto";
 import { access as access2, mkdir, rm, writeFile as writeFile2 } from "fs/promises";
@@ -23312,6 +23780,7 @@ import { execFileSync } from "child_process";
 import { randomUUID } from "crypto";
 import { tmpdir as tmpdir2 } from "os";
 import { join as join2 } from "path";
+init_bytes();
 var GOOGLE_MULTIMODAL_MODELS = [
   "gemini-3-pro-image",
   "gemini-3.1-flash-image",
@@ -23435,7 +23904,12 @@ header = ${curlQuote(`x-goog-api-key: ${apiKey}`)}
           "-d",
           "@-",
           url2
-        ], { input: JSON.stringify(body), encoding: "utf8", timeout: 310000 });
+        ], {
+          input: JSON.stringify(body),
+          encoding: "utf8",
+          timeout: 310000,
+          stdio: ["pipe", "pipe", "pipe"]
+        });
       } catch (error51) {
         const e = error51;
         const details = (typeof e.stderr === "string" ? e.stderr.trim() : "") || e.message || "curl request failed";
@@ -23761,6 +24235,7 @@ var createJimeng = (options) => {
 };
 
 // ../../plugins/generations/image-gen/src/providers/minimax.ts
+init_bytes();
 import { Buffer as Buffer7 } from "buffer";
 var DEFAULT_MODEL9 = "image-01";
 var MAX_REFERENCE_IMAGE_BYTES = 10 * 1024 * 1024;
@@ -24891,6 +25366,65 @@ async function processGeneratorIO(inputPath, outputPath, options = {}) {
     }
     if (spec.job === "illustration")
       assertAnchorPlan(doc2?.body ?? "", positions, prompts.length);
+    let _chromiumComposer;
+    const resolveComposer = async () => {
+      if (options.composer !== undefined)
+        return options.composer;
+      if (_chromiumComposer !== undefined)
+        return _chromiumComposer;
+      const { makeChromiumComposer: makeChromiumComposer2 } = await Promise.resolve().then(() => (init_chromium(), exports_chromium));
+      _chromiumComposer = makeChromiumComposer2();
+      return _chromiumComposer;
+    };
+    if (format.compose !== undefined) {
+      const cfg = format.compose;
+      if (spec.job !== "free") {
+        throw new Error(`compose: format '${format.name}' has a compose block but the job is '${spec.job}' \u2014 compose formats require job: free`);
+      }
+      const vars = spec.vars ?? {};
+      const headline = vars.headline ?? format.variables.headline?.default ?? "";
+      if (!headline.trim()) {
+        throw new Error(`compose: format '${format.name}' requires a non-empty vars.headline`);
+      }
+      const pointsRaw = vars.points ?? format.variables.points?.default ?? "";
+      const points = pointsRaw.split(`
+`).filter((l) => l.trim() !== "");
+      const promptVars = { subject: doc2?.body ?? "", ...spec.vars ?? {} };
+      const textFreeSources = [
+        { source: "the format template", text: format.template },
+        {
+          source: `the style preset '${style.name}'`,
+          text: [style.modifiers, style.negative].filter((part) => part !== "").join(", ")
+        },
+        { source: "spec.extra", text: spec.extra ?? "" },
+        ...Object.entries(promptVars).filter(([name]) => name !== "headline" && name !== "points" && name !== "index").map(([name, value]) => ({ source: `vars.${name}`, text: String(value) }))
+      ];
+      assertTextFreePrompt(prompts[0] ?? "", { headline, points }, textFreeSources);
+      const fontsDir = join4(import.meta.dir, "..", "assets", "fonts");
+      const fontNames = [cfg.fonts.headline, cfg.fonts.body];
+      const fontBytesMap = new Map;
+      for (const name of fontNames) {
+        fontBytesMap.set(name, new Uint8Array(await readBytes(join4(fontsDir, name))));
+      }
+      const coverageMap = new Map;
+      for (const [name, bytes] of fontBytesMap) {
+        coverageMap.set(name, glyphCoverage(bytes));
+      }
+      if (format.width == null || format.height == null) {
+        throw new Error(`image-gen: format '${format.name}' declares no canvas size; compose requires width and height`);
+      }
+      const cardInput = {
+        headline,
+        points,
+        role: vars.role ?? format.variables.role?.default ?? "content",
+        compose: cfg,
+        width: format.width,
+        height: format.height
+      };
+      assertCoverage(cardInput, coverageMap);
+      const composer2 = await resolveComposer();
+      await composer2.compose(cardInput);
+    }
     const resolveProvider = options.providerResolver ?? defaultProviderResolver;
     const primary = resolveProvider(spec);
     const built = new Map;
@@ -24998,17 +25532,64 @@ async function processGeneratorIO(inputPath, outputPath, options = {}) {
           throw new Error(`Illustration anchor must occur exactly once in the source body, found ${parts.length - 1}: '${anchor.slice(0, 50)}'`);
         }
       }
-      const path2 = artifactPath(outputPath, stem, format.name, index + 1, result.extension);
-      await writeBytes(path2, result.bytes);
-      written.push(path2);
+      let artifactPathValue;
+      let artifactBytes;
+      let artifactWidth;
+      let artifactHeight;
+      let illustrationMeta;
+      if (format.compose !== undefined) {
+        const illustrationArtifactPath = artifactPath(outputPath, stem, `${format.name}-illustration`, index + 1, result.extension);
+        await writeBytes(illustrationArtifactPath, result.bytes);
+        written.push(illustrationArtifactPath);
+        const vars = spec.vars ?? {};
+        const headline = vars.headline ?? format.variables.headline?.default ?? "";
+        const pointsRaw = vars.points ?? format.variables.points?.default ?? "";
+        const points = pointsRaw.split(`
+`).filter((l) => l.trim() !== "");
+        if (format.width == null || format.height == null) {
+          throw new Error(`image-gen: format '${format.name}' declares no canvas size; compose requires width and height`);
+        }
+        const cardInput = {
+          headline,
+          points,
+          role: vars.role ?? format.variables.role?.default ?? "content",
+          compose: format.compose,
+          width: format.width,
+          height: format.height,
+          illustration: { bytes: result.bytes, mime: `image/${result.extension}` }
+        };
+        const composer2 = await resolveComposer();
+        const cardBytes = await composer2.compose(cardInput);
+        const cardPath = artifactPath(outputPath, stem, format.name, index + 1, "png");
+        await writeBytes(cardPath, cardBytes);
+        written.push(cardPath);
+        const dims = imageDimensions(cardBytes);
+        if (dims.width !== format.width || dims.height !== format.height) {
+          throw new Error(`compose: card dimensions ${dims.width}x${dims.height} do not match format canvas ${format.width}x${format.height}`);
+        }
+        artifactPathValue = cardPath;
+        artifactBytes = cardBytes.byteLength;
+        artifactWidth = dims.width;
+        artifactHeight = dims.height;
+        illustrationMeta = { path: illustrationArtifactPath, bytes: result.bytes.byteLength };
+      } else {
+        const path2 = artifactPath(outputPath, stem, format.name, index + 1, result.extension);
+        await writeBytes(path2, result.bytes);
+        written.push(path2);
+        artifactPathValue = path2;
+        artifactBytes = result.bytes.byteLength;
+      }
       const artifact = {
-        path: path2,
+        path: artifactPathValue,
         format: format.name,
         style: style.name,
         provider: result.provider,
         model: result.model,
         prompt,
-        bytes: result.bytes.byteLength
+        bytes: artifactBytes,
+        ...artifactWidth !== undefined ? { width: artifactWidth } : {},
+        ...artifactHeight !== undefined ? { height: artifactHeight } : {},
+        ...illustrationMeta !== undefined ? { illustration: illustrationMeta } : {}
       };
       if (spec.seed !== undefined) {
         artifact.seed = spec.seed;
@@ -25019,10 +25600,10 @@ async function processGeneratorIO(inputPath, outputPath, options = {}) {
         const altText = `Illustration ${index + 1}`;
         const markdown = `${anchor}
 
-![${altText}](${path2})`;
+![${altText}](${artifactPathValue})`;
         captions.push({
           index: index + 1,
-          path: path2,
+          path: artifactPathValue,
           caption: anchor,
           altText,
           anchor