book-kit 0.0.0-stage → 0.6.0

package/commands/audit-chapter-lengths.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+/**
+ * Audit chapter lengths for balance and readability.
+ * Flags chapters that are significantly longer or shorter than recommended ranges.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import * as yaml from 'js-yaml';
+import { isNonChapter } from '../lib/structure.js';
+import { pathFor } from '../lib/config.js';
+import { isMain } from '../lib/is-main.js';
+
+// Recommended word count range for content chapters. The chapter-lengths
+// validator (validators/chapter-lengths.js) uses these as its defaults.
+const MIN_WORDS = 500;
+const MAX_WORDS = 2500;
+
+// Section-opener heading marker. Section openers carry `{.section-opener}` on
+// their H1 (the same marker the print/EPUB CSS and the section-intro
+// validators key off).
+// Matching the marker — rather than a hardcoded filename list — keeps this in
+// sync automatically when chapters are renamed or sections are added.
+const SECTION_OPENER_RE = /^#\s+.*\{[^}]*\.section-opener[^}]*\}/m;
+
+/**
+ * Strip common Markdown/Pandoc markup from content, preserving visible text where possible.
+ * This is a heuristic, not a full Markdown parser, but is sufficient for word-count auditing.
+ * @param {string} content - Raw Markdown/Pandoc content
+ * @returns {string} Plaintext-ish content with markup removed
+ */
+function stripMarkup(content) {
+  let stripped = content;
+
+  // Remove fenced code blocks (``` or ~~~, any language)
+  stripped = stripped.replace(/```[\s\S]*?```/g, ' ');
+  stripped = stripped.replace(/~~~[\s\S]*?~~~/g, ' ');
+
+  // Remove inline code marked with backticks
+  stripped = stripped.replace(/`[^`]*`/g, ' ');
+
+  // Images: keep alt text, drop URLs
+  stripped = stripped.replace(/!\[([^\]]*)\]\([^)]+\)/g, '$1 ');
+
+  // Links: keep link text, drop URLs
+  stripped = stripped.replace(/\[([^\]]*)\]\([^)]+\)/g, '$1 ');
+
+  // Emphasis and strong emphasis markers (*, _, **, __)
+  stripped = stripped.replace(/(\*\*|__)(.*?)\1/g, '$2');
+  stripped = stripped.replace(/(\*|_)(.*?)\1/g, '$2');
+
+  // Headings: remove leading #'s
+  stripped = stripped.replace(/^#{1,6}\s+/gm, '');
+
+  // Blockquotes: remove leading ">"
+  stripped = stripped.replace(/^\s{0,3}>\s?/gm, '');
+
+  // List markers: -, *, +, or numbered lists at line start
+  stripped = stripped.replace(/^\s{0,3}([-*+]|\d+\.)\s+/gm, '');
+
+  // ::: blocks (e.g., Pandoc-style fenced divs)
+  // [^\S\n]* (not \s*) so the match can't cross the newline and swallow the
+  // paragraph that follows the fence line
+  stripped = stripped.replace(/^:::[^\S\n]*[^\n]*$/gm, ' ');
+
+  // Inline attributes in braces, e.g., {.class}, {#id}
+  stripped = stripped.replace(/\{[.#][^}]*\}/g, '');
+
+  // Collapse all remaining whitespace
+  stripped = stripped.replace(/\s+/g, ' ').trim();
+
+  return stripped;
+}
+
+/**
+ * Count words in a string, excluding Markdown/Pandoc markup
+ * @param {string} content - Text content
+ * @returns {number} Word count
+ */
+function countWords(content) {
+  const plain = stripMarkup(content);
+  return plain.length === 0
+    ? 0
+    : plain.split(/\s+/).filter(word => word.length > 0).length;
+}
+
+/**
+ * Check if a file should be excluded from length auditing
+ * @param {string} filePath - Path to chapter file
+ * @returns {boolean} True if file should be excluded
+ */
+// Structural pages, takeaways collections, and scratch drafts aren't chapters
+// (see lib/structure.js).
+function isExcluded(filePath) {
+  return isNonChapter(filePath);
+}
+
+/**
+ * Check if content belongs to a section introduction.
+ *
+ * Section openers are intentionally short (≈300–500 words; they frame a section
+ * rather than stand alone), so they're exempt from the min-word floor. They're
+ * identified by the `{.section-opener}` class on their H1 heading.
+ * @param {string} content - Raw chapter content
+ * @returns {boolean} True if content is a section intro
+ */
+function isSectionIntro(content) {
+  return SECTION_OPENER_RE.test(content);
+}
+
+/**
+ * Parse index.yml to get chapter list and section mapping
+ * @param {string} indexPath - Path to index.yml
+ * @returns {{files: string[], sections: Object<string, string>}} Chapter files and section mapping
+ */
+function parseIndex(indexPath = pathFor('index')) {
+  if (!fs.existsSync(indexPath)) {
+    return { files: [], sections: {} };
+  }
+
+  const indexContent = fs.readFileSync(indexPath, 'utf8');
+  const index = yaml.load(indexContent);
+  const files = index['input-files'] || [];
+
+  const lines = indexContent.split('\n');
+  let currentSection = '';
+  const sections = {};
+  for (const line of lines) {
+    const sectionMatch = line.match(/^\s*#\s+(.+)/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1].trim();
+      continue;
+    }
+    const fileMatch = line.match(/^\s*-\s+(.+)/);
+    if (fileMatch) {
+      sections[fileMatch[1].trim()] = currentSection;
+    }
+  }
+
+  return { files, sections };
+}
+
+/**
+ * Audit chapter lengths and return warnings
+ * @param {string} indexPath - Path to index.yml
+ * @param {{min_words?: number, max_words?: number}} [options] - Word count range
+ * @returns {{warnings: string[], stats: Object}} Audit results
+ */
+function auditChapterLengths(indexPath = pathFor('index'), { min_words = MIN_WORDS, max_words = MAX_WORDS } = {}) {
+  const { files, sections } = parseIndex(indexPath);
+  const baseDir = path.dirname(path.resolve(indexPath));
+  const warnings = [];
+  const chapters = [];
+
+  for (const file of files) {
+    if (isExcluded(file)) {
+      continue;
+    }
+
+    const resolvedPath = path.resolve(baseDir, file);
+    if (!fs.existsSync(resolvedPath)) {
+      continue;
+    }
+
+    const content = fs.readFileSync(resolvedPath, 'utf8');
+    if (isSectionIntro(content)) {
+      continue;
+    }
+
+    const wordCount = countWords(content);
+    const section = sections[file] || 'Unknown';
+
+    chapters.push({ file, wordCount, section });
+
+    if (wordCount > max_words) {
+      warnings.push(
+        `Chapter too long (${wordCount} words, max ${max_words}): ${file} [${section}]`
+      );
+    } else if (wordCount < min_words) {
+      warnings.push(
+        `Chapter too short (${wordCount} words, min ${min_words}): ${file} [${section}]`
+      );
+    }
+  }
+
+  const counts = chapters.map(c => c.wordCount);
+  const total = counts.reduce((a, b) => a + b, 0);
+  const stats = {
+    chapterCount: chapters.length,
+    totalWords: total,
+    averageWords: chapters.length > 0 ? Math.round(total / chapters.length) : 0,
+    minWords: chapters.length > 0 ? Math.min(...counts) : 0,
+    maxWords: chapters.length > 0 ? Math.max(...counts) : 0,
+  };
+
+  return { warnings, stats, chapters };
+}
+
+/**
+ * Print audit results to console
+ * @param {string} indexPath - Path to index.yml
+ * @returns {number} Number of warnings
+ */
+function printAudit(indexPath = pathFor('index')) {
+  const { warnings, stats } = auditChapterLengths(indexPath);
+
+  console.log(`Chapter length audit (${stats.chapterCount} content chapters)`);
+  console.log(`  Range: ${MIN_WORDS}–${MAX_WORDS} words`);
+  console.log(`  Average: ${stats.averageWords} words`);
+  console.log(`  Min: ${stats.minWords} words`);
+  console.log(`  Max: ${stats.maxWords} words`);
+  console.log('');
+
+  if (warnings.length === 0) {
+    console.log('✓ All chapters within recommended length range');
+  } else {
+    for (const warning of warnings) {
+      console.log(`⚠ ${warning}`);
+    }
+    console.log(`\n⚠ ${warnings.length} chapter(s) outside recommended range`);
+  }
+
+  return warnings.length;
+}
+
+// Export for testing
+export {
+  MIN_WORDS,
+  MAX_WORDS,
+  countWords,
+  isExcluded,
+  isSectionIntro,
+  parseIndex,
+  auditChapterLengths,
+  printAudit
+};
+
+// Run if executed directly
+if (isMain(import.meta.url)) {
+  const indexPath = process.argv[2] || pathFor('index');
+  const warningCount = printAudit(indexPath);
+  process.exit(warningCount > 0 ? 1 : 0);
+}

package/commands/check-epub-size.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * EPUB size budget checker.
+ * Fails CI if any EPUB exceeds its size threshold.
+ *
+ * Usage: book-kit check-epub-size [--ci]
+ *   --ci: exit with non-zero code on budget violation (default: warn only)
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import { relative } from 'node:path';
+import { loadConfig, outputFile } from '../lib/config.js';
+
+const config = loadConfig();
+const rootDir = config.root;
+const ci = process.argv.includes('--ci');
+
+// Size budget in bytes, from checks.epub_max_mb (MB = 1024 × 1024 bytes).
+const budget = (config.checks?.epub_max_mb ?? 2) * 1024 * 1024;
+
+// The retail EPUBs always; the advance reader copies when they've been built.
+const budgets = Object.fromEntries(
+  ['.epub', '-kindle.epub', '-arc.epub', '-kindle-arc.epub']
+    .map((suffix) => outputFile(suffix, config))
+    .filter((file, i) => i < 2 || existsSync(file))
+    .map((file) => [relative(rootDir, file), budget]),
+);
+
+function formatSize(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${bytes} B`;
+}
+
+let violations = 0;
+
+console.log('EPUB Size Budget Report');
+console.log('═══════════════════════');
+
+for (const [file, budget] of Object.entries(budgets)) {
+  const path = `${rootDir}/${file}`;
+  try {
+    const { size } = statSync(path);
+    const pct = ((size / budget) * 100).toFixed(1);
+    const status = size > budget ? '❌ OVER' : size > budget * 0.9 ? '⚠️  WARN' : '✅ OK';
+
+    console.log(`\n${file}:`);
+    console.log(`  Size:   ${formatSize(size)}`);
+    console.log(`  Budget: ${formatSize(budget)}`);
+    console.log(`  Usage:  ${pct}%  ${status}`);
+
+    if (size > budget) {
+      violations++;
+      console.log(`  → Exceeds budget by ${formatSize(size - budget)}`);
+    }
+  } catch {
+    console.log(`\n${file}: not found (skipped)`);
+  }
+}
+
+console.log('\n───────────────────────');
+if (violations > 0) {
+  console.log(`${violations} file(s) exceeded their size budget.`);
+  if (ci) process.exit(1);
+} else {
+  console.log('All files within budget.');
+}

package/commands/check-pdf-page-count.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+/**
+ * Lock the print PDF's page count to a known value so it can't drift, and
+ * check its page size against print.trim.
+ *
+ * The page count is load-bearing launch metadata: it drives the print spine
+ * width (and therefore the cover wrap), the page-count tier that sets the
+ * gutter margin, and the figure the designer and distributors are given. A
+ * silent change to chapter length, CSS, or fonts can shift it by a page or
+ * two — enough to make a pre-cut spine wrong. This gate fails loudly when the
+ * built PDF no longer matches EXPECTED_PAGE_COUNT.
+ *
+ * Usage:
+ *   book-kit check-pdf-page-count [path-to-pdf]
+ *
+ * Defaults to the print PDF (outputFile('.pdf')). The PDF/X file is the same
+ * interior, so it shares the same expected count.
+ *
+ * To change the locked value INTENTIONALLY (e.g. after deliberate content
+ * changes), update print.page_count in book.config.yml, then recut the cover
+ * spine and update the page count wherever the book is listed.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { loadConfig, outputFile } from '../lib/config.js';
+import { isMain } from '../lib/is-main.js';
+
+const __filename = fileURLToPath(import.meta.url);
+
+// The locked page count for the print interior (`print.page_count` in
+// book.config.yml; null disables the check).
+//
+// Lock it once the book is final: the page count drives the cover spine width,
+// the gutter-margin tier, and distributor metadata, so a silent drift (a
+// pandoc or WeasyPrint upgrade, a hyphenation change, a cascade reorder) can
+// invalidate a print cover. Pandoc's version is the dominant lever on
+// pagination, which is why toolchain.json pins it. Perfect-bound interiors
+// must have an even page count.
+export function expectedPageCount(config = loadConfig()) {
+  return config.print.page_count ?? null;
+}
+
+/**
+ * Count pages in a PDF without any external dependency.
+ *
+ * Counts page objects (`/Type /Page`, excluding the `/Pages` tree node) in the
+ * raw PDF. This matches pdfinfo/qpdf for the WeasyPrint-generated output, which
+ * writes uncompressed page objects. If a future toolchain change emits an
+ * object-stream / compressed-xref PDF, the page objects would be hidden inside
+ * compressed streams and this count would collapse — so we throw rather than
+ * silently report 0, pointing at the likely cause.
+ *
+ * @param {string} pdfPath absolute or relative path to the PDF
+ * @returns {number} page count
+ */
+export function countPdfPages(pdfPath) {
+  const raw = readFileSync(pdfPath, 'latin1');
+  // `/Type /Page` but not `/Type /Pages` (the page-tree root). The trailing
+  // \b after "Page" fails when followed by "s" (both word chars), so `/Pages`
+  // is excluded; it matches when "Page" is followed by /, whitespace, etc.
+  const pages = (raw.match(/\/Type\s*\/Page\b/g) || []).length;
+
+  if (pages === 0) {
+    throw new Error(
+      `Counted 0 pages in ${pdfPath}. The PDF may now use object streams / ` +
+        `a compressed cross-reference table, hiding page objects from this ` +
+        `text-based counter. Update countPdfPages() (e.g. use pdfinfo/qpdf).`
+    );
+  }
+
+  return pages;
+}
+
+/**
+ * Every distinct page size in a PDF, in points, from its `/MediaBox` entries
+ * (same uncompressed-object caveat as countPdfPages).
+ *
+ * @param {string} pdfPath
+ * @returns {Array<[number, number]>} [width, height] pairs
+ */
+export function pdfPageSizes(pdfPath) {
+  const raw = readFileSync(pdfPath, 'latin1');
+  const sizes = new Map();
+  for (const [, box] of raw.matchAll(/\/MediaBox\s*\[([^\]]*)\]/g)) {
+    const [x0, y0, x1, y1] = box.trim().split(/\s+/).map(Number);
+    const size = [Math.abs(x1 - x0), Math.abs(y1 - y0)];
+    sizes.set(size.join('x'), size);
+  }
+  return [...sizes.values()];
+}
+
+/**
+ * Page sizes that don't match print.trim (inches; a PDF point is 1/72 in).
+ * print.trim is what the book tells printers and retailers; the CSS @page
+ * size is what WeasyPrint actually lays out, so a mismatch between the two
+ * would ship a wrong-sized interior.
+ *
+ * @returns {string[]} one message per mismatched size; empty when they agree
+ */
+export function trimMismatches(sizes, trim) {
+  if (!Array.isArray(trim) || trim.length !== 2) return [];
+  const [w, h] = trim.map((inches) => inches * 72);
+  const near = (a, b) => Math.abs(a - b) < 1;
+  return sizes
+    .filter(([pw, ph]) => !(near(pw, w) && near(ph, h)))
+    .map(([pw, ph]) => `${+(pw / 72).toFixed(3)}×${+(ph / 72).toFixed(3)} in`);
+}
+
+/** CLI entry point. */
+function main() {
+  const arg = process.argv[2];
+  const pdfPath = arg ? resolve(arg) : outputFile('.pdf');
+  const EXPECTED_PAGE_COUNT = expectedPageCount();
+
+  if (!existsSync(pdfPath)) {
+    console.error(`❌ PDF not found: ${pdfPath}`);
+    console.error('   Build it first (e.g. `just pdf`), then re-run this check.');
+    process.exit(1);
+  }
+
+  const actual = countPdfPages(pdfPath);
+
+  const trim = loadConfig().print.trim;
+  const wrongSizes = trimMismatches(pdfPageSizes(pdfPath), trim);
+  if (wrongSizes.length > 0) {
+    console.error(`❌ Page size mismatch: ${pdfPath} has ${wrongSizes.join(', ')} pages; print.trim is ${trim[0]}×${trim[1]} in.`);
+    console.error('   Make the @page size in the book\'s CSS match print.trim (or fix print.trim).');
+    process.exit(1);
+  }
+
+  if (EXPECTED_PAGE_COUNT === null) {
+    console.log(`ℹ️  ${pdfPath}: ${actual} pages (no lock; set print.page_count in book.config.yml to lock it).`);
+    return;
+  }
+
+  if (actual !== EXPECTED_PAGE_COUNT) {
+    console.error(
+      `❌ Page count drift: ${pdfPath} has ${actual} pages, expected ${EXPECTED_PAGE_COUNT}.`
+    );
+    console.error(
+      '   The print page count is locked because it drives the spine width,'
+    );
+    console.error(
+      '   gutter-margin tier, and distributor metadata. If this change is'
+    );
+    console.error(
+      '   intentional, update print.page_count in book.config.yml,'
+    );
+    console.error('   then recut the cover spine and refresh the metadata to match.');
+    process.exit(1);
+  }
+
+  console.log(`✅ ${pdfPath}: ${actual} pages (matches locked value ${EXPECTED_PAGE_COUNT}).`);
+}
+
+// Run as CLI only when invoked directly, not when imported by tests.
+if (isMain(import.meta.url)) {
+  main();
+}

package/commands/composite-kindle-emoji.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Generate Kindle-specific emoji PNGs: transparent, but white-safe when flattened.
+
+Background: two approaches have been tried.
+Baking an opaque callout-colored background hid the box on a light-mode e-ink
+Paperwhite, but on Kindle iOS — whose page is pure white and which doesn't paint
+the callout tint behind the image — that baked tint shows as a colored rectangle
+around every callout emoji. Plain transparent RGBA, on the other hand, can flatten
+to Twemoji's *dark slate* transparent-pixel RGB on renderers that drop alpha,
+producing a dark box.
+
+This version takes the middle path that's correct on modern renderers and no worse
+than white anywhere else: keep the original alpha (true transparency, clean edges),
+but rewrite the RGB of fully-transparent pixels to white. So:
+
+  - Renderer honors alpha (Kindle iOS, modern KFX) → genuinely transparent, no box,
+    clean in light / sepia / dark mode. (This is the case we're fixing.)
+  - Renderer flattens alpha (older e-ink) → transparent areas show WHITE, not dark
+    slate: invisible on a white page, at worst a white box in dark/sepia mode.
+
+No per-callout background is baked anymore — that was the source of the iOS colored
+box. All emoji are treated identically.
+
+Input:  SRC_DIR/*.png           (palette/RGBA, transparent, dark-slate under alpha)
+Output: DST_DIR/*.png     (RGBA, transparent, white under alpha)
+"""
+
+import os
+import sys
+
+# Don't leave a __pycache__ in commands/ (it would ship in the npm package).
+sys.dont_write_bytecode = True
+
+try:
+    from PIL import Image
+except ImportError:
+    print("Error: Pillow is required. Install with: pip install Pillow", file=sys.stderr)
+    sys.exit(1)
+
+from _emoji_io import save_if_changed
+
+if len(sys.argv) != 3:
+    print("Usage: composite-kindle-emoji.py SRC_DIR DST_DIR", file=sys.stderr)
+    sys.exit(2)
+SRC_DIR, DST_DIR = sys.argv[1], sys.argv[2]
+
+
+def whiten_transparent(src_path, dst_path):
+    """Keep alpha; set the RGB of fully-transparent pixels to white.
+
+    convert("RGBA") normalizes palette + tRNS sources (which some Kindle
+    renderers mishandle). Image.composite(orig, white, mask) keeps the original
+    channel where the pixel is visible (mask=255) and substitutes white where it
+    is fully transparent (mask=0), leaving the alpha channel untouched so true
+    transparency — and clean anti-aliased edges — survive.
+    """
+    src = Image.open(src_path).convert("RGBA")
+    r, g, b, a = src.split()
+    white = Image.new("L", src.size, 255)
+    # mask: 255 for any visible pixel (alpha > 0), 0 for fully transparent.
+    mask = a.point(lambda v: 255 if v > 0 else 0)
+    r = Image.composite(r, white, mask)
+    g = Image.composite(g, white, mask)
+    b = Image.composite(b, white, mask)
+    return save_if_changed(Image.merge("RGBA", (r, g, b, a)), dst_path)
+
+
+def main():
+    os.makedirs(DST_DIR, exist_ok=True)
+
+    count = written = 0
+    for filename in sorted(os.listdir(SRC_DIR)):
+        if not filename.endswith(".png"):
+            continue
+        written += whiten_transparent(
+            os.path.join(SRC_DIR, filename),
+            os.path.join(DST_DIR, filename),
+        )
+        count += 1
+
+    print(f"Kindle emoji PNGs (transparent, white under alpha) in {DST_DIR}: {count}, {written} rewritten")
+
+
+if __name__ == "__main__":
+    main()

package/commands/composite-print-emoji.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Generate print-specific emoji PNGs: fully opaque, flattened onto the exact
+background each emoji sits on in the PDF.
+
+Why this exists: the print PDF is
+converted to PDF/X-1a:2001 for IngramSpark by commands/convert-pdfx.sh, which runs
+Ghostscript with -dNOTRANSPARENCY. That flag is required — it keeps the
+interior as vector text (without it, Ghostscript rasterizes every page to a
+300 DPI bitmap: ~58 MB, no embedded fonts, no extractable text). But
+-dNOTRANSPARENCY drops each image's soft-mask (SMask) instead of compositing it,
+so a transparent Twemoji PNG loses its alpha and reveals the dark slate RGB
+Twemoji stores in "transparent" pixels — the 💡/👔/💻/🤔 callout labels then
+print as dark boxes.
+
+Fix: hand Ghostscript images that have no alpha at all. Flatten each Twemoji onto
+the solid colour it actually sits on, so there is no SMask to drop and no box to
+reveal — matching pixels above and below:
+
+  - Callout-label emoji (💡 👔 💻 🤔) always sit on the print callout fill
+    (#e8e8e8, set in css/theme/11-print.css). Flatten onto #e8e8e8.
+  - Body-text emoji sit on the white page. Flatten onto white.
+
+Both output sets are fully opaque RGB (mode "RGB", no alpha channel), so
+Ghostscript leaves them untouched and the CMYK conversion treats them as ordinary
+opaque artwork. The callout fill (#e8e8e8) is the same source RGB as the baked
+emoji background, so both convert to the same CMYK and stay seamless.
+
+Only the PDF pipeline uses these (justfile `pdf` recipe). EPUB/Kindle/web keep the
+transparent originals in img/emoji/ (they render alpha correctly).
+
+Input:  SRC_DIR/*.png                (RGBA, transparent, dark-slate under alpha)
+Output: CALLOUT_DST_DIR/*.png        (RGB, opaque, flattened onto #e8e8e8)
+        BODY_DST_DIR/*.png           (RGB, opaque, flattened onto white)
+"""
+
+import os
+import sys
+
+# Don't leave a __pycache__ in commands/ (it would ship in the npm package).
+sys.dont_write_bytecode = True
+
+try:
+    from PIL import Image
+except ImportError:
+    print("Error: Pillow is required. Install with: pip install Pillow", file=sys.stderr)
+    sys.exit(1)
+
+from _emoji_io import save_if_changed
+
+if len(sys.argv) != 4:
+    print("Usage: composite-print-emoji.py SRC_DIR CALLOUT_DST_DIR BODY_DST_DIR", file=sys.stderr)
+    sys.exit(2)
+SRC_DIR = sys.argv[1]
+
+# (output dir, background RGB) — must match the backdrop each emoji sits on.
+# Callout fill #e8e8e8 is defined in the kit theme (css/theme/11-print.css, @media print,
+# all callout classes). Body emoji sit on the white page.
+TARGETS = [
+    (sys.argv[2], (0xE8, 0xE8, 0xE8)),
+    (sys.argv[3], (0xFF, 0xFF, 0xFF)),
+]
+
+
+def flatten_onto(src_path, dst_path, bg_rgb):
+    """Composite a transparent RGBA emoji onto a solid background and drop alpha.
+
+    The result is mode "RGB" (no alpha channel at all), so Ghostscript's
+    -dNOTRANSPARENCY has no soft-mask to discard: the image is already opaque and
+    prints exactly as composited, anti-aliased edges blended into bg_rgb.
+    """
+    src = Image.open(src_path).convert("RGBA")
+    bg = Image.new("RGBA", src.size, bg_rgb + (255,))
+    bg.alpha_composite(src)
+    return save_if_changed(bg.convert("RGB"), dst_path)
+
+
+def main():
+    total = 0
+    for dst_dir, bg_rgb in TARGETS:
+        os.makedirs(dst_dir, exist_ok=True)
+        count = written = 0
+        for filename in sorted(os.listdir(SRC_DIR)):
+            if not filename.endswith(".png"):
+                continue
+            written += flatten_onto(
+                os.path.join(SRC_DIR, filename),
+                os.path.join(dst_dir, filename),
+                bg_rgb,
+            )
+            count += 1
+        print(f"Opaque emoji PNGs (bg #{bg_rgb[0]:02x}{bg_rgb[1]:02x}{bg_rgb[2]:02x}) in {dst_dir}/: {count}, {written} rewritten")
+        total += count
+
+    print(f"Total: {total} print emoji PNGs.")
+
+
+if __name__ == "__main__":
+    main()