@gobing-ai/knowledge-kit 0.0.28 → 0.0.30

package/plugins/generations/image-gen/package.json

@@ -9,6 +9,7 @@
         "@gobing-ai/kk-core": "workspace:*",
         "@gobing-ai/ts-runtime": "catalog:",
         "@gobing-ai/ts-utils": "catalog:",
+        "playwright": "catalog:",
         "zod": "4.4.3"
     },
     "devDependencies": {

package/plugins/generations/image-gen/presets/formats/daily-news-cover.yaml

@@ -1,5 +1,5 @@
 name: daily-news-cover
-description: Daily AI news episode cover — fixed composition and palette; subject is the only per-run input
+description: Daily AI tech-sharing episode cover — fixed composition and palette; subject is the only per-run input
 job: cover
 aspectRatio: '21:9'
 width: 1344
@@ -12,7 +12,7 @@ variables:
         description: One concrete visual scene for the day's lead story (objects, settings, symbols)
         default: a glowing network of connected nodes rising above a quiet city at dawn
 template: |-
-    Ultrawide editorial cover illustration for a daily AI news podcast episode.
+    Ultrawide editorial cover illustration for a daily AI tech-sharing podcast episode.
     Scene: {{subject | a glowing network of connected nodes rising above a quiet city at dawn}}.
     Composition: one central focal subject, generous negative space in the upper third, uncluttered background.
     Color palette: deep navy background with electric blue and warm amber accents.

package/plugins/generations/image-gen/presets/formats/xhs-card.yaml

@@ -3,6 +3,8 @@ description: >-
   Xiaohongshu (XHS) knowledge card — 3:4 portrait image-text card with large
   Chinese headline and short bullet points. Adapted from baoyu-xhs-images
   (MIT © Jim Liu); see plugins/kk/skills/xhs-images/references/card-layouts.md.
+  Task 0180: card copy is typeset from Noto Sans SC via headless Chromium;
+  the provider prompt generates the illustration only.
 job: free
 aspectRatio: '3:4'
 width: 1080
@@ -11,12 +13,23 @@ defaultStyle: xhs-knowledge
 keywords:
     - xiaohongshu-style
     - image-text card layout
-    - large-font title (Chinese-friendly)
     - fresh clean design
     - flat illustration accents with geometric decorations
-    - crisp legible text hierarchy
     - professional color grading
 outputFilename: 'card-{{index | 01}}.png'
+compose:
+    engine: text-card
+    safeArea: 72
+    headlineMinPx: 64
+    bodyMinPx: 36
+    illustrationHeight: 640
+    palette:
+        background: '#FFFFFF'
+        text: '#1F2328'
+        accent: '#FF2442'
+    fonts:
+        headline: NotoSansSC-Bold.otf
+        body: NotoSansSC-Regular.otf
 variables:
     role:
         description: Card role in the series (cover, content, closing)
@@ -33,9 +46,6 @@ variables:
     subject:
         description: Visual scene or metaphor illustrated on the card
         default: clean flat illustration of the core concept
-    language:
-        description: On-card text language
-        default: 简体中文
     index:
         description: Card number in the series (zero-padded)
         default: '01'
@@ -45,11 +55,9 @@ variables:
 template: |-
     Xiaohongshu-style knowledge card, portrait 3:4, for a card series.
     Card role: {{role | content}}. Layout: {{layout | definition}}.
-    On-card headline in {{language | 简体中文}}, extra-large bold type: "{{headline}}".
-    Bullet points (short lines, generous line spacing, keep on-card text minimal):
-    {{points}}
     Visual scene: {{subject | clean flat illustration of the core concept}},
     rendered as flat illustration accents with subtle geometric decorations.
-    Fresh clean design, strong text hierarchy, comfortable margins, no watermark,
-    no extra UI chrome. 8K quality, crisp details, professional color grading.
-    {{content}}
+    Pure illustration, no text, no letters, no numerals, no captions — the text
+    band is typeset separately. Fresh clean design, comfortable margins, no
+    watermark, no extra UI chrome. 8K quality, crisp details, professional color
+    grading. {{content}}

package/plugins/generations/image-gen/presets/styles/xhs-knowledge.yaml

@@ -4,4 +4,5 @@ description: >-
   background, clean information layout, soft accent colors, rounded card zones.
   Adapted from baoyu-xhs-images "knowledge card" style guidance (MIT © Jim Liu);
   see plugins/kk/skills/xhs-images/references/card-layouts.md.
-modifiers: simple clean light background, rounded rectangle card zones, soft pastel accent colors, large legible Chinese typography, generous whitespace, flat geometric decorations, subtle drop shadows, fresh and professional
+modifiers: simple clean light background, rounded rectangle card zones, soft pastel accent colors, generous whitespace, flat geometric decorations, subtle drop shadows, fresh and professional
+negative: text, letters, numbers, Chinese characters, captions, watermark, logo

package/plugins/generations/image-gen/scripts/compose-e2e-artifact.ts

@@ -0,0 +1,135 @@
+/**
+ * Standalone E2E compose evidence (task 0180 Plan item 9).
+ *
+ * Composes the fixed card twice per variant, asserts byte-identical SHA-256,
+ * asserts 1080x1440, and writes the PNG artifacts to .spur/run/0180/.
+ *
+ * Usage:
+ *   bun scripts/compose-e2e-artifact.ts            # all variants
+ *   bun scripts/compose-e2e-artifact.ts without    # one variant (no illustration)
+ *   bun scripts/compose-e2e-artifact.ts with       # one variant (fixture illustration)
+ *   bun scripts/compose-e2e-artifact.ts r2         # 0181 R2: good card + overflow refusal
+ *
+ * Each variant runs in its own subprocess (the wrapper spawns `bun <self>
+ * <variant>`): under Bun 1.3.14 a third Chromium compose cycle within one
+ * process can hang the Playwright driver, while a two-compose pair is stable.
+ * Production composes one card per image-gen invocation, so the per-process
+ * pair matches the real spend path.
+ */
+import { join } from 'node:path';
+import { imageDimensions } from '../src/bytes';
+import { makeChromiumComposer } from '../src/compose/chromium';
+
+const OUT_DIR = '.spur/run/0180';
+const OUT_DIR_0181 = '.spur/run/0181';
+const FIXTURE_PNG = new Uint8Array([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00,
+    0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xde, 0x00, 0x00, 0x00, 0x0c, 0x49,
+    0x44, 0x41, 0x54, 0x08, 0xd7, 0x63, 0xf8, 0xcf, 0xc0, 0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0xe2, 0x21, 0xbc, 0x33,
+    0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
+]);
+const COMPOSE_CFG = {
+    engine: 'text-card' as const,
+    safeArea: 72,
+    headlineMinPx: 64,
+    bodyMinPx: 36,
+    illustrationHeight: 640,
+    palette: { background: '#FFFFFF', text: '#1F2328', accent: '#FF2442' },
+    fonts: { headline: 'NotoSansSC-Bold.otf', body: 'NotoSansSC-Regular.otf' },
+};
+
+async function sha256(bytes: Uint8Array): Promise<string> {
+    const digest = await crypto.subtle.digest('SHA-256', bytes as unknown as ArrayBuffer);
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+
+function input(variant: 'without' | 'with') {
+    const base = {
+        headline: '微服务拆分的三个原则',
+        points: ['先按业务边界划分服务', '再按团队规模调整粒度', '最后用网关收敛入口'],
+        role: 'content' as const,
+        compose: COMPOSE_CFG,
+        width: 1080,
+        height: 1440,
+    };
+    return variant === 'with' ? { ...base, illustration: { bytes: FIXTURE_PNG, mime: 'image/png' } } : base;
+}
+
+async function runPair(variant: 'without' | 'with'): Promise<void> {
+    console.log(`[${variant}] composing (1/2)...`);
+    const composer = makeChromiumComposer();
+    const first = await composer.compose(input(variant));
+    console.log(`[${variant}] composing (2/2)...`);
+    const second = await composer.compose(input(variant));
+
+    const dims = imageDimensions(first);
+    if (dims?.width !== 1080 || dims?.height !== 1440) {
+        throw new Error(`[${variant}] composed PNG is not 1080x1440: ${JSON.stringify(dims)}`);
+    }
+    const sha1 = await sha256(first);
+    const sha2 = await sha256(second);
+    if (sha1 !== sha2) {
+        throw new Error(`[${variant}] SHA-256 mismatch across identical compose: ${sha1} vs ${sha2}`);
+    }
+    const outPath = join(OUT_DIR, `card-${variant}-illustration.png`);
+    await Bun.write(outPath, first);
+    console.log(`[${variant}] OK ${first.length}B ${dims.width}x${dims.height} sha256=${sha1} -> ${outPath}`);
+}
+
+async function runR2(): Promise<void> {
+    // 0181 R2 evidence: the no-illustration compose is a real card (R2 makes the
+    // illustration decoration, not a legibility dependency), and an overflowing
+    // headline is refused by the live safe-area check before any PNG exists.
+    const composer = makeChromiumComposer();
+    console.log('[r2] composing the no-illustration card (1/2)...');
+    const good = await composer.compose(input('without'));
+    const dims = imageDimensions(good);
+    if (dims?.width !== 1080 || dims?.height !== 1440) {
+        throw new Error(`[r2] composed PNG is not 1080x1440: ${JSON.stringify(dims)}`);
+    }
+    console.log('[r2] composing an overflowing headline (2/2) — expecting a safe-area refusal...');
+    let refusal = '';
+    try {
+        await composer.compose({ ...input('without'), headline: '拆'.repeat(200) });
+    } catch (err: unknown) {
+        refusal = err instanceof Error ? err.message : String(err);
+    }
+    if (!refusal.includes('overflows the safe area')) {
+        throw new Error(`[r2] overflowing headline was not refused: ${refusal || 'composed without error'}`);
+    }
+    const outPath = join(OUT_DIR_0181, 'card-r2-no-illustration.png');
+    await Bun.write(outPath, good);
+    console.log(`[r2] OK ${good.length}B ${dims.width}x${dims.height}; overflow refused; -> ${outPath}`);
+}
+
+const variant = process.argv[2];
+if (variant === 'without' || variant === 'with') {
+    await runPair(variant);
+} else if (variant === 'r2') {
+    await runR2();
+} else if (variant === undefined) {
+    // Bounded: a Chromium cycle can occasionally hang under Bun 1.3.14 (driver
+    // contention right after a sibling subprocess); timeout + one clean retry.
+    for (const v of ['without', 'with', 'r2'] as const) {
+        let proc = Bun.spawnSync(['bun', import.meta.path, v], { stdout: 'pipe', stderr: 'pipe', timeout: 120_000 });
+        if (proc.exitCode !== 0) {
+            console.log(`[${v}] attempt 1 failed (exit ${proc.exitCode}); retrying once...`);
+            proc = Bun.spawnSync(['bun', import.meta.path, v], { stdout: 'pipe', stderr: 'pipe', timeout: 120_000 });
+        }
+        const out = new TextDecoder().decode(proc.stdout);
+        const err = new TextDecoder().decode(proc.stderr);
+        if (out) process.stdout.write(out);
+        if (proc.exitCode !== 0) {
+            process.stderr.write(err);
+            process.exit(proc.exitCode ?? 1);
+        }
+    }
+    console.log(
+        'E2E compose artifacts written (.spur/run/0180 both variants, .spur/run/0181 R2) — SHA-256 deterministic.',
+    );
+} else {
+    console.error(`Unknown variant: ${variant} (expected without|with)`);
+    process.exit(1);
+}

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

@@ -17,3 +17,119 @@ export async function writeBytes(path: string, bytes: Uint8Array): Promise<void>
 export async function readBytes(path: string): Promise<Uint8Array> {
     return new Uint8Array(await readFile(path));
 }
+
+/**
+ * Task 0180 (PNG) + task 0182 (JPEG/WebP, `null` contract) — pure header-only dimension
+ * reader. Reads `width`/`height` from PNG (IHDR), JPEG (SOF0–SOF15 except DHT/DAC/JPG)
+ * and WebP (VP8 lossy, VP8L lossless, VP8X extended) bytes; no decode. Returns `null`
+ * when the bytes cannot be parsed — the caller decides whether that is fatal (the compose
+ * canvas assertion) or a WARN with dimensions omitted (artifact recording, R3: the bytes
+ * are already paid for).
+ */
+export function imageDimensions(bytes: Uint8Array): { width: number; height: number } | null {
+    if (isPng(bytes)) return pngDimensions(bytes);
+    if (isJpeg(bytes)) return jpegDimensions(bytes);
+    if (isWebp(bytes)) return webpDimensions(bytes);
+    return null;
+}
+
+function isPng(b: Uint8Array): boolean {
+    const PNG_SIG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    if (b.byteLength < 24) return false;
+    for (let i = 0; i < 8; i++) {
+        if (b[i] !== PNG_SIG[i]) return false;
+    }
+    return true;
+}
+
+function pngDimensions(b: Uint8Array): { width: number; height: number } | null {
+    // IHDR chunk: offset 8 = chunk data length (must be 13), offset 12 = 'IHDR' tag.
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    const ihdrLength = view.getUint32(8, false);
+    if (ihdrLength !== 13 || view.getUint32(12, false) !== 0x49484452) {
+        return null;
+    }
+    return { width: view.getUint32(16, false), height: view.getUint32(20, false) };
+}
+
+function isJpeg(b: Uint8Array): boolean {
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    // SOI + the first marker's 0xFF prefix.
+    return b.byteLength >= 4 && view.getUint16(0, false) === 0xffd8 && view.getUint8(2) === 0xff;
+}
+
+function jpegDimensions(b: Uint8Array): { width: number; height: number } | null {
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    let at = 2; // after SOI
+    while (at + 4 <= b.byteLength) {
+        if (view.getUint8(at) !== 0xff) return null; // marker desync — not a parseable JPEG stream
+        const marker = view.getUint8(at + 1);
+        at += 2;
+        // Standalone markers (TEM, RSTn) carry no length segment.
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+        if (at + 2 > b.byteLength) return null;
+        const length = view.getUint16(at, false);
+        if (length < 2) return null;
+        // SOF0–SOF15 minus DHT (C4), JPG (C8) and DAC (CC) carry the canvas.
+        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isSof) {
+            // SOF segment: length(2) precision(1) height(2) width(2).
+            if (at + 7 > b.byteLength) return null;
+            return { height: view.getUint16(at + 3, false), width: view.getUint16(at + 5, false) };
+        }
+        at += length;
+    }
+    return null;
+}
+
+function isWebp(b: Uint8Array): boolean {
+    if (b.byteLength < 20) return false;
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    return view.getUint32(0, true) === 0x46464952 && view.getUint32(8, true) === 0x50424557; // 'RIFF' 'WEBP'
+}
+
+function webpDimensions(b: Uint8Array): { width: number; height: number } | null {
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    // Walk the RIFF chunks after the 12-byte file header until a size-bearing chunk appears.
+    let at = 12;
+    while (at + 8 <= b.byteLength) {
+        const id = String.fromCharCode(
+            view.getUint8(at),
+            view.getUint8(at + 1),
+            view.getUint8(at + 2),
+            view.getUint8(at + 3),
+        );
+        const size = view.getUint32(at + 4, true);
+        const body = at + 8;
+        if (id === 'VP8 ') {
+            // Lossy: frame tag (3) + sync code 0x9d 0x01 0x2a + 14-bit LE width/height.
+            if (size < 10 || body + 10 > b.byteLength) return null;
+            if (
+                view.getUint8(body + 3) !== 0x9d ||
+                view.getUint8(body + 4) !== 0x01 ||
+                view.getUint8(body + 5) !== 0x2a
+            ) {
+                return null;
+            }
+            return {
+                width: view.getUint16(body + 6, true) & 0x3fff,
+                height: view.getUint16(body + 8, true) & 0x3fff,
+            };
+        }
+        if (id === 'VP8L') {
+            // Lossless: signature 0x2f, then 14-bit width-1 / height-1 packed little-endian.
+            if (size < 5 || body + 5 > b.byteLength || view.getUint8(body) !== 0x2f) return null;
+            const bits = view.getUint32(body + 1, true);
+            return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+        }
+        if (id === 'VP8X') {
+            // Extended: 4 flag/reserved bytes, then 24-bit LE width-1 / height-1.
+            if (size < 10 || body + 10 > b.byteLength) return null;
+            const width = view.getUint8(body + 4) | (view.getUint8(body + 5) << 8) | (view.getUint8(body + 6) << 16);
+            const height = view.getUint8(body + 7) | (view.getUint8(body + 8) << 8) | (view.getUint8(body + 9) << 16);
+            return { width: width + 1, height: height + 1 };
+        }
+        at = body + size + (size % 2); // RIFF chunks pad to even sizes
+    }
+    return null;
+}

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

@@ -0,0 +1,294 @@
+/**
+ * Task 0180 (F616) — card HTML builder and coverage asserter.
+ *
+ * `CardComposer` is the seam: tests inject a stub; `chromium.ts` is the default.
+ * `cardHtml` builds a self-contained HTML document with @font-face data: URLs
+ * and [data-field] attributes on every text element so the Chromium composer can
+ * measure overflow. No external requests, no system fonts.
+ */
+
+/** The compose block declared in a format preset's YAML. */
+export interface ComposeBlock {
+    engine: 'text-card';
+    safeArea: number;
+    headlineMinPx: number;
+    bodyMinPx: number;
+    illustrationHeight: number;
+    palette: { background: string; text: string; accent: string };
+    fonts: { headline: string; body: string };
+}
+
+/** The full input to one compose call. */
+export interface CardInput {
+    headline: string;
+    points: string[];
+    role: string;
+    compose: ComposeBlock;
+    width: number;
+    height: number;
+    /** Raw provider illustration, if available; absent on the pre-spend probe. */
+    illustration?: { bytes: Uint8Array; mime: string };
+}
+
+/** Injectable seam: compose one card PNG from the input. */
+export interface CardComposer {
+    compose(input: CardInput): Promise<Uint8Array>;
+}
+
+/**
+ * R4 — check every character of headline and points against the font's cmap.
+ * Whitespace and line breaks are exempt. Throws loud on the first uncovered
+ * character, naming the field, the code point (U+HHHH form), and the glyph char.
+ *
+ * @param input  The card input whose text is checked.
+ * @param fonts  Map from font filename → coverage predicate. Keys must include
+ *               `compose.fonts.headline` and `compose.fonts.body`.
+ */
+export function assertCoverage(input: CardInput, fonts: Map<string, (cp: number) => boolean>): void {
+    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: string, fieldName: string, covers: (cp: number) => boolean): void => {
+        for (const ch of text) {
+            const cp = ch.codePointAt(0);
+            if (cp === undefined) continue;
+            // Exempt whitespace and newlines (U+0000–U+0020, U+00A0, U+2000–U+200F, etc.)
+            if (cp <= 0x20 || cp === 0xa0 || (cp >= 0x2000 && cp <= 0x200f) || cp === 0x3000) {
+                continue;
+            }
+            if (!covers(cp)) {
+                const hex = `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 ${hex} '${ch}' not covered by ${fontName}`);
+            }
+        }
+    };
+
+    checkField(input.headline, 'headline', headlineCover);
+    for (const [i, point] of input.points.entries()) {
+        checkField(point, `points[${i}]`, bodyCover);
+    }
+}
+
+/** One named segment that contributed to the composed prompt, for source-naming. */
+export interface TextFreeSource {
+    source: string;
+    text: string;
+}
+
+/**
+ * Task 0181 (F616 R1) — a compose format's illustration prompt must stay
+ * text-free: no Han character anywhere, and never the headline or any point as
+ * a literal substring (trimmed, length >= 2, so Latin-script card copy is
+ * caught too). Numerals and ordinary Latin words are fine: the negative prompt
+ * tells the model what to draw, not what it may contain.
+ *
+ * `sources` are checked in call order so a violation is attributed to the
+ * offending contributor (template, style preset, extra, a named var); when no
+ * single segment explains the hit, the composed `prompt` itself is named.
+ * Call this BEFORE any font IO, compose, or provider spend.
+ */
+export function assertTextFreePrompt(
+    prompt: string,
+    copy: { headline: string; points: string[] },
+    sources: TextFreeSource[],
+): void {
+    const hit = (text: string): string | null => {
+        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: string, what: string): never => {
+        throw new Error(
+            `compose: the illustration prompt must stay text-free — ${source} contributes ${what} (card copy is typeset, never prompted)`,
+        );
+    };
+    for (const { source, text } of sources) {
+        const what = hit(text);
+        if (what !== null) fail(source, what);
+    }
+    const what = hit(prompt);
+    if (what !== null) fail('the composed prompt', what);
+}
+
+/**
+ * Build the self-contained HTML card document.
+ *
+ * Layout: illustration band (top, `object-fit: cover`) + text panel (below).
+ * All text is in fixed px inside the safe-area inset. @font-face references fonts
+ * by the URLs in `fontUrls` (data: URLs, local file:// URLs, or route URLs).
+ *
+ * Fit rule for headline: starts at `headlineMinPx * 1.5`, steps down 4px until
+ * it fits the safe-area width, never below `headlineMinPx`. Bullets use `bodyMinPx`.
+ *
+ * @param input     Card input.
+ * @param fontUrls  Map from font filename → URL string (any scheme accepted by the browser).
+ */
+export function cardHtml(input: CardInput, fontUrls: Map<string, string>): string {
+    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) ?? '';
+
+    // Headline starts at 1.5x the minimum and steps down by 4px.
+    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('\n');
+
+    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: string): string {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}