@gobing-ai/knowledge-kit 0.0.28 → 0.0.30

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);
@@ -301,7 +390,10 @@ export async function processGeneratorIO(
         const captions: CaptionEntry[] = [];
         const attempts: ProviderAttempt[] = [];
         let at = 0; // sticky index into `order`
-        const generateWithFallback = async (image: number, prompt: string): Promise<ImageResult> => {
+        const generateWithFallback = async (
+            image: number,
+            prompt: string,
+        ): Promise<{ result: ImageResult; sizeRequest: 'exact' | 'aspect' }> => {
             const start = attempts.length; // this image's failed attempts begin here (R5 summarises the slice)
             for (;;) {
                 const name = order[at];
@@ -312,17 +404,26 @@ export async function processGeneratorIO(
                 const provider = at === 0 ? primary : createCandidate(name);
                 // spec.model is provider-specific (D6): only the requested provider receives it.
                 const model = at === 0 ? (spec.model ?? provider.defaultModel()) : provider.defaultModel();
+                // 0182 R1/R4: the exact-size gate runs per candidate, with that candidate's own
+                // model and its own capability report. Without it the request keeps today's
+                // aspect-only shape (R2); on the exact path aspectRatio is omitted (R1 — MiniMax
+                // reads width/height only when aspect_ratio is absent).
+                const exact =
+                    format.width !== undefined &&
+                    format.height !== undefined &&
+                    provider.exactSize?.(model, format.width, format.height) === true;
                 const request: ImageRequest = {
                     prompt,
                     model,
-                    aspectRatio: format.aspectRatio,
+                    ...(exact ? { width: format.width, height: format.height } : { aspectRatio: format.aspectRatio }),
                     ...(spec.referenceImages !== undefined && spec.referenceImages.length > 0
                         ? { referenceImages: spec.referenceImages }
                         : {}),
                 };
                 try {
                     provider.validate?.(request);
-                    return await provider.generate(request);
+                    const result = await provider.generate(request);
+                    return { result, sizeRequest: exact ? 'exact' : 'aspect' };
                 } catch (err: unknown) {
                     if (spec.fallback === undefined) {
                         throw err; // D6 R1: strict mode propagates the original error, unwrapped.
@@ -352,7 +453,22 @@ export async function processGeneratorIO(
         };
         let body = doc?.body ?? '';
         for (const [index, prompt] of prompts.entries()) {
-            const result = await generateWithFallback(index + 1, prompt);
+            const { result, sizeRequest } = await generateWithFallback(index + 1, prompt);
+            // 0182 R3: measure the raw provider delivery once — both branches read it. A declared
+            // canvas that came back different (or unparseable) warns and never fails: the bytes
+            // are already paid for, and failing would delete them through the cleanup path.
+            const delivered = imageDimensions(result.bytes);
+            if (format.width !== undefined && format.height !== undefined) {
+                if (delivered === null) {
+                    echoError(
+                        `WARN image-gen: ${result.provider}/${result.model} delivered unparseable image bytes; dimensions omitted`,
+                    );
+                } else if (delivered.width !== format.width || delivered.height !== format.height) {
+                    echoError(
+                        `WARN image-gen: ${result.provider}/${result.model} delivered ${delivered.width}x${delivered.height}; format '${format.name}' declares ${format.width}x${format.height}`,
+                    );
+                }
+            }
             // Re-check against the spliced body; the pre-spend plan check is assertAnchorPlan (0169).
             let anchor: string | undefined;
             if (spec.job === 'illustration') {
@@ -367,17 +483,99 @@ 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 === null) {
+                    throw new Error(
+                        `compose: composed card dimensions are unparseable; format '${format.name}' requires ${format.width}x${format.height}`,
+                    );
+                }
+                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,
+                    // 0182 R3/R5: the raw provider delivery, measured from its own bytes.
+                    ...(delivered !== null ? { width: delivered.width, height: delivered.height } : {}),
+                };
+            } else {
+                // Non-compose: existing path (R6); the artifact records the delivered size (0182 R3).
+                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;
+                artifactWidth = delivered?.width;
+                artifactHeight = delivered?.height;
+            }
+
             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,
+                sizeRequest,
+                ...(artifactWidth !== undefined ? { width: artifactWidth } : {}),
+                ...(artifactHeight !== undefined ? { height: artifactHeight } : {}),
+                ...(illustrationMeta !== undefined ? { illustration: illustrationMeta } : {}),
             };
             if (spec.seed !== undefined) {
                 artifact.seed = spec.seed;
@@ -386,10 +584,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

@@ -76,9 +76,21 @@ export interface ImageArtifact {
     /** The exact prompt string sent. */
     prompt: string;
     seed?: number;
+    /**
+     * 0182 R3: what the provider was asked for — 'exact' when the request carried the
+     * preset's declared width/height (the provider reported it could honour them for this
+     * model), 'aspect' for the aspect-only shape. Present on every written artifact.
+     */
+    sizeRequest?: 'exact' | 'aspect';
     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). */