@gobing-ai/knowledge-kit 0.0.28 → 0.0.29

package/plugins/generations/image-gen/src/compose/chromium.ts

@@ -0,0 +1,147 @@
+/**
+ * Task 0180 (F616) — Chromium-based card composer (Playwright).
+ *
+ * Default `CardComposer` implementation. Launches Chromium headless, renders
+ * the HTML card, measures every [data-field] box against the safe area (R2),
+ * and screenshots the result. The browser is always closed in `finally`.
+ *
+ * Font loading: uses `page.route()` to serve fonts from disk by URL, keeping
+ * the HTML small. The HTML references fonts by a stable `kk-font://` URL
+ * scheme; the route intercept fulfils each request with the disk bytes.
+ *
+ * The transport is Playwright's default; under Bun 1.3.14 a Chromium launch
+ * cycle can occasionally hang (leaving the browser's process tree behind),
+ * so the E2E test skips under `bun test` and the evidence script runs each
+ * variant pair in its own subprocess with a bounded timeout + retry.
+ *
+ * Missing Playwright or Chromium surfaces as an actionable error naming the
+ * install command.
+ */
+
+import { join } from 'node:path';
+import { readBytes } from '../bytes';
+import type { CardComposer, CardInput } from './card';
+import { cardHtml } from './card';
+
+const FONTS_DIR = join(import.meta.dir, '..', '..', 'assets', 'fonts');
+
+/** Stable URL prefix for font routes; never hits the network. */
+const FONT_ROUTE_BASE = 'http://kk-fonts.local/';
+
+/**
+ * Build a map of fontName → route URL. The HTML references these URLs;
+ * `page.route()` intercepts and returns the disk bytes.
+ */
+function fontRouteUrls(fontNames: string[]): Map<string, string> {
+    const map = new Map<string, string>();
+    for (const name of fontNames) {
+        map.set(name, `${FONT_ROUTE_BASE}${encodeURIComponent(name)}`);
+    }
+    return map;
+}
+
+/**
+ * Playwright-based card composer. Inject in tests; the default export is used
+ * in production via `makeChromiumComposer()`.
+ */
+export class ChromiumComposer implements CardComposer {
+    async compose(input: CardInput): Promise<Uint8Array> {
+        // Dynamic import so missing Playwright gives a clear error at call time.
+        let chromium: import('playwright').BrowserType;
+        try {
+            const pw = await import('playwright');
+            chromium = pw.chromium;
+        } catch (err: unknown) {
+            throw new Error(
+                `compose: Playwright is not installed. Run: bunx playwright install chromium\n(${err instanceof Error ? err.message : String(err)})`,
+            );
+        }
+
+        const fontNames = [input.compose.fonts.headline, input.compose.fonts.body];
+        const fontUrls = fontRouteUrls(fontNames);
+
+        // Build HTML with font URLs (small — no base64 inline).
+        const html = cardHtml(input, fontUrls);
+
+        let browser: import('playwright').Browser | undefined;
+        try {
+            try {
+                browser = await chromium.launch({ headless: true });
+            } catch (err: unknown) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`compose: Chromium browser not found. Run: bunx playwright install chromium\n(${msg})`);
+            }
+
+            const page = await browser.newPage({
+                viewport: { width: input.width, height: input.height },
+                deviceScaleFactor: 1,
+            });
+
+            // Serve fonts from disk via route interception; no network, no base64 blob.
+            await page.route(`${FONT_ROUTE_BASE}**`, async (route) => {
+                const url = new URL(route.request().url());
+                const fontName = decodeURIComponent(url.pathname.slice(1));
+                const fontPath = join(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' });
+            // Wait for fonts to load; passed as a string expression to avoid DOM lib dependency.
+            await page.evaluate('document.fonts.ready');
+
+            // R2: measure every [data-field] box against the safe area.
+            const { safeArea, illustrationHeight } = input.compose;
+            const safeLeft = safeArea;
+            const safeTop = illustrationHeight + safeArea;
+            const safeRight = input.width - safeArea;
+            const safeBottom = input.height - safeArea;
+
+            // Passed as a string to avoid requiring DOM lib in tsconfig; args injected by value.
+            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)) as Array<{
+                field: string;
+                rect: { top: number; left: number; bottom: number; right: number };
+            }>;
+
+            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();
+        }
+    }
+}
+
+/** Factory function that returns the default Chromium composer singleton. */
+export function makeChromiumComposer(): CardComposer {
+    return new ChromiumComposer();
+}

package/plugins/generations/image-gen/src/compose/cmap.ts

@@ -0,0 +1,177 @@
+/**
+ * Task 0180 (F616 R4) — pure sfnt cmap reader, no IO.
+ *
+ * Parses the OpenType/TrueType table directory and the cmap table to build a
+ * code-point → boolean coverage function. Format 12 (full Unicode BMP + SMP,
+ * preferred for CJK) is selected when present; format 4 (BMP only) is the
+ * fallback. A truncated font or a missing cmap throws so callers cannot silently
+ * get a false-negative from a partial read.
+ */
+
+function u16(view: DataView, offset: number): number {
+    return view.getUint16(offset, false);
+}
+
+function u32(view: DataView, offset: number): number {
+    return view.getUint32(offset, false);
+}
+
+function tag(view: DataView, offset: number): string {
+    return String.fromCharCode(
+        view.getUint8(offset),
+        view.getUint8(offset + 1),
+        view.getUint8(offset + 2),
+        view.getUint8(offset + 3),
+    );
+}
+
+function assertBytes(view: DataView, offset: number, needed: number, context: string): void {
+    if (offset + needed > view.byteLength) {
+        throw new Error(`compose: truncated font — expected ${needed} bytes at offset ${offset} (${context})`);
+    }
+}
+
+/** Locate the cmap table in the sfnt directory and return its absolute offset + length. */
+function findCmapTable(view: DataView): { offset: number; length: number } {
+    assertBytes(view, 0, 12, 'sfnt header');
+    // sfnt magic: 0x00010000 (TrueType), 0x4F54544F ('OTTO' — CFF/OTF), or 0x74727565 ('true').
+    const magic = u32(view, 0);
+    if (magic !== 0x00010000 && magic !== 0x4f54544f && magic !== 0x74727565) {
+        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 — cmap table not found in sfnt directory');
+}
+
+/** Build a coverage function from cmap format 4 (BMP segmented). */
+function coverageFormat4(view: DataView, subtableOffset: number): (cp: number) => boolean {
+    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; // skip reservedPad
+    const idDeltaBase = startCodesBase + segCount * 2;
+    const idRangeOffsetBase = idDeltaBase + segCount * 2;
+
+    return (cp: number): boolean => {
+        if (cp > 0xffff) return false;
+        // Binary search over endCode array.
+        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) & 0xffff) !== 0;
+        }
+        // Use the idRangeOffset to index into glyphIdArray.
+        const glyphIdAddr = idRangeOffsetBase + lo * 2 + idRangeOffset + (cp - startCode) * 2;
+        if (glyphIdAddr + 2 > view.byteLength) return false;
+        const glyphId = u16(view, glyphIdAddr);
+        return glyphId !== 0;
+    };
+}
+
+/** Build a coverage function from cmap format 12 (full Unicode, sequential groups). */
+function coverageFormat12(view: DataView, subtableOffset: number): (cp: number) => boolean {
+    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: number): boolean => {
+        // Binary search over startCharCode.
+        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 {
+                // cp is in [startChar, endChar]; glyph is startGlyph + (cp - startChar).
+                const startGlyph = u32(view, base + 8);
+                return startGlyph + (cp - startChar) !== 0;
+            }
+        }
+        return false;
+    };
+}
+
+/**
+ * Parse the cmap table and return a `(cp: number) => boolean` coverage
+ * predicate. Format 12 is preferred (covers all Unicode); format 4 is the
+ * fallback (BMP only). A truncated font or a missing usable subtable throws.
+ */
+export function glyphCoverage(fontBytes: Uint8Array): (cp: number) => boolean {
+    if (fontBytes.byteLength < 12) {
+        throw new Error('compose: truncated font — 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: number | undefined;
+    let fmt12Offset: number | undefined;
+
+    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);
+
+        // Prefer platform 3 (Windows) or platform 0 (Unicode) for format 12.
+        // Accept any platform for format 4 as BMP fallback.
+        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 — no usable cmap subtable (format 4 or 12) found');
+}

package/plugins/generations/image-gen/src/index.ts

@@ -1,9 +1,12 @@
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { type Content, ContentSchema, type Doc, DocListSchema } from '@gobing-ai/kk-core';
 import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import { echoError } from '@gobing-ai/ts-utils';
-import { writeBytes } from './bytes';
+import { imageDimensions, readBytes, writeBytes } from './bytes';
+import type { CardComposer } from './compose/card';
+import { assertCoverage, assertTextFreePrompt, type TextFreeSource } from './compose/card';
+import { glyphCoverage } from './compose/cmap';
 import {
     type CaptionEntry,
     type ImageArtifact,
@@ -26,6 +29,7 @@ import {
     selectProvider,
 } from './providers/types';
 
+export type { CardComposer, CardInput } from './compose/card';
 export * from './job';
 export * from './paths';
 export * from './presets';
@@ -192,6 +196,12 @@ export async function processGeneratorIO(
         providerResolver?: ProviderResolver;
         /** D6 0166: builds fallback candidates by name (tests inject stubs); defaults to the registry. */
         createProvider?: (name: string) => ImageProvider;
+        /**
+         * Task 0180: injectable card composer. Tests supply a stub; the default is the Chromium
+         * composer (same seam style as `providerResolver`). Resolved lazily so missing Playwright
+         * surfaces only when a compose-format job is actually requested.
+         */
+        composer?: CardComposer;
     } = {},
 ): Promise<void> {
     const fs = createNodeFileSystem();
@@ -229,6 +239,85 @@ export async function processGeneratorIO(
         }
         if (spec.job === 'illustration') assertAnchorPlan(doc?.body ?? '', positions, prompts.length);
 
+        // Task 0180 (F616 R4/R5): when the format has a compose block, run pre-spend checks
+        // (coverage + a dry compose with no illustration). This runs on BOTH the dry-run and
+        // spend branches so a missing-glyph or overflow error never bills the provider.
+        let _chromiumComposer: CardComposer | undefined;
+        const resolveComposer = async (): Promise<CardComposer> => {
+            if (options.composer !== undefined) return options.composer;
+            if (_chromiumComposer !== undefined) return _chromiumComposer;
+            // Lazy import: Playwright is a runtime dep, not always needed.
+            const { makeChromiumComposer } = await import('./compose/chromium');
+            _chromiumComposer = makeChromiumComposer();
+            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}' — 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('\n').filter((l: string) => l.trim() !== '');
+
+            // Task 0181 (F616 R1): the provider prompt must stay text-free — card copy is
+            // typeset by the composer. Refusal happens before any font IO, compose, or spend
+            // and names the offending segment (template, style preset, extra, or a named var).
+            const promptVars: Record<string, string> = { subject: doc?.body ?? '', ...(spec.vars ?? {}) };
+            const textFreeSources: TextFreeSource[] = [
+                { 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);
+
+            // Load font bytes once for coverage check.
+            const fontsDir = join(import.meta.dir, '..', 'assets', 'fonts');
+            const fontNames = [cfg.fonts.headline, cfg.fonts.body];
+            const fontBytesMap = new Map<string, Uint8Array>();
+            for (const name of fontNames) {
+                fontBytesMap.set(name, new Uint8Array(await readBytes(join(fontsDir, name))));
+            }
+            const coverageMap = new Map<string, (cp: number) => boolean>();
+            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: fails loud naming field + code point (R4).
+            assertCoverage(cardInput, coverageMap);
+
+            // Dry compose (no illustration): proves Chromium is available and layout fits (R5).
+            const composer = await resolveComposer();
+            await composer.compose(cardInput);
+        }
+
         // Selection must succeed (or fail loud naming the provider) even when nothing is spent.
         const resolveProvider: ProviderResolver = options.providerResolver ?? defaultProviderResolver;
         const primary = resolveProvider(spec);
@@ -367,17 +456,86 @@ export async function processGeneratorIO(
                     );
                 }
             }
-            const path = artifactPath(outputPath, stem, format.name, index + 1, result.extension);
-            await writeBytes(path, result.bytes);
-            written.push(path);
+
+            let artifactPathValue: string;
+            let artifactBytes: number;
+            let artifactWidth: number | undefined;
+            let artifactHeight: number | undefined;
+            let illustrationMeta: ImageArtifact['illustration'] | undefined;
+
+            if (format.compose !== undefined) {
+                // Task 0180 (F616 R5): compose path.
+                // 1. Write the raw provider illustration.
+                const illustrationArtifactPath = artifactPath(
+                    outputPath,
+                    stem,
+                    `${format.name}-illustration`,
+                    index + 1,
+                    result.extension,
+                );
+                await writeBytes(illustrationArtifactPath, result.bytes);
+                written.push(illustrationArtifactPath);
+
+                // 2. Compose the card over the illustration.
+                const vars = spec.vars ?? {};
+                const headline = vars.headline ?? format.variables.headline?.default ?? '';
+                const pointsRaw = vars.points ?? format.variables.points?.default ?? '';
+                const points = pointsRaw.split('\n').filter((l: string) => 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 composer = await resolveComposer();
+                const cardBytes = await composer.compose(cardInput);
+
+                // 3. Write the composed card.
+                const cardPath = artifactPath(outputPath, stem, format.name, index + 1, 'png');
+                await writeBytes(cardPath, cardBytes);
+                written.push(cardPath);
+
+                // 4. Measure the card dimensions via imageDimensions and assert canvas.
+                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 {
+                // Non-compose: existing path (R6).
+                const path = artifactPath(outputPath, stem, format.name, index + 1, result.extension);
+                await writeBytes(path, result.bytes);
+                written.push(path);
+                artifactPathValue = path;
+                artifactBytes = result.bytes.byteLength;
+            }
+
             const artifact: ImageArtifact = {
-                path,
+                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;
@@ -386,10 +544,10 @@ export async function processGeneratorIO(
             if (anchor !== undefined) {
                 const parts = body.split(anchor);
                 const altText = `Illustration ${index + 1}`;
-                const markdown = `${anchor}\n\n![${altText}](${path})`;
+                const markdown = `${anchor}\n\n![${altText}](${artifactPathValue})`;
                 captions.push({
                     index: index + 1,
-                    path,
+                    path: artifactPathValue,
                     caption: anchor,
                     altText,
                     anchor,

package/plugins/generations/image-gen/src/job.ts

@@ -79,6 +79,12 @@ export interface ImageArtifact {
     width?: number;
     height?: number;
     bytes: number;
+    /**
+     * Task 0180 (F616 R5): when the format has a compose block, the raw provider
+     * illustration is recorded here. `path` on the parent artifact is the composed
+     * card. `xhs-pub` reads only `.path`, so the publish DTO is unchanged.
+     */
+    illustration?: { path: string; width?: number; height?: number; bytes: number };
 }
 
 /** One illustration caption, the wt captions.json payload reduced to what consumers read (R4). */

package/plugins/generations/image-gen/src/presets.ts

@@ -31,6 +31,28 @@ export interface FormatVariable {
     default: string;
 }
 
+/**
+ * Optional compose block in a format preset (task 0180, F616).
+ * When present, image-gen typesets the on-card copy from Noto Sans SC via
+ * headless Chromium instead of generating text as pixels. Requires `width`
+ * and `height` on the format (enforced by FormatPresetSchema refine).
+ */
+export interface ComposeConfig {
+    /** The only v1 engine value; zod literal enforces it. */
+    engine: 'text-card';
+    /** Safe-area inset in px on all sides. */
+    safeArea: number;
+    /** Headline minimum font size in px. */
+    headlineMinPx: number;
+    /** Body/bullets minimum font size in px. */
+    bodyMinPx: number;
+    /** Height in px of the illustration band (top); text panel takes the rest. */
+    illustrationHeight: number;
+    palette: { background: string; text: string; accent: string };
+    /** Font filenames under `assets/fonts/`. */
+    fonts: { headline: string; body: string };
+}
+
 /** R1 — `formats/<name>.yaml`: the job skeleton (template, keywords, variables). */
 export interface FormatPreset {
     /** Filename stem must equal this. */
@@ -51,6 +73,8 @@ export interface FormatPreset {
     variables: Record<string, FormatVariable>;
     /** Prompt body; YAML block scalar, embedded newlines preserved. */
     template: string;
+    /** Optional compose block (0180): when present, image-gen typesets card copy from a real font. */
+    compose?: ComposeConfig;
 }
 
 /** R1 — `styles/<name>.yaml`; `modifiers` is the only required prompt field. */
@@ -76,21 +100,37 @@ const PresetSourceSchema = z.object({
     confidence: z.enum(['high', 'medium', 'low']).optional(),
 });
 
-/** Parse gate for `formats/<name>.yaml`. */
-export const FormatPresetSchema = z.object({
-    name: z.string(),
-    description: z.string(),
-    job: z.enum(['free', 'cover', 'illustration']),
-    aspectRatio: z.string(),
-    width: z.number().optional(),
-    height: z.number().optional(),
-    defaultStyle: z.string(),
-    keywords: z.array(z.string()),
-    outputFilename: z.string(),
-    variables: z.record(z.string(), z.object({ description: z.string(), default: z.string() })),
-    template: z.string(),
+/** The zod schema for the optional compose block (0180). */
+const ComposeConfigSchema = z.object({
+    engine: z.literal('text-card'),
+    safeArea: z.number(),
+    headlineMinPx: z.number(),
+    bodyMinPx: z.number(),
+    illustrationHeight: z.number(),
+    palette: z.object({ background: z.string(), text: z.string(), accent: z.string() }),
+    fonts: z.object({ headline: z.string(), body: z.string() }),
 });
 
+/** Parse gate for `formats/<name>.yaml`. */
+export const FormatPresetSchema = z
+    .object({
+        name: z.string(),
+        description: z.string(),
+        job: z.enum(['free', 'cover', 'illustration']),
+        aspectRatio: z.string(),
+        width: z.number().optional(),
+        height: z.number().optional(),
+        defaultStyle: z.string(),
+        keywords: z.array(z.string()),
+        outputFilename: z.string(),
+        variables: z.record(z.string(), z.object({ description: z.string(), default: z.string() })),
+        template: z.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',
+    });
+
 /** Parse gate for `styles/<name>.yaml`. */
 export const StylePresetSchema = z.object({
     name: z.string(),

package/plugins/kk/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "kk",
-    "version": "0.0.28",
+    "version": "0.0.29",
     "description": "knowledge-kit Claude Code plugin: skills, commands, subagents, hooks, and rules"
 }