book-cover-generator 1.5.0 → 1.6.0

package/README.md

@@ -31,7 +31,7 @@ Generate book covers from a **title** and an **author**. 34 styles, 28 palettes
 
 ## The web app
 
-On [covers.otsirh.dev](https://covers.otsirh.dev) you type a title and author (press Enter in the title to break its line where you want), and if you like a subtitle, a series line ("Book Two of the Ember Cycle") and a credit ("Translated by…"). Then you choose:
+On [covers.otsirh.dev](https://covers.otsirh.dev) you type a title and author (press Enter in the title to break its line where you want), and if you like a subtitle, a series line ("Book Two of the Ember Cycle"), a credit ("Translated by…") and a badge ("Winner of the Hugo Award", set as a seal in a corner clear of the text). Then you choose:
 
 - **a style**, from a rail that previews your book in all 34 styles. Eleven styles let you pin a choice the variation otherwise makes, such as Silhouette's city or forest, or where Aurora puts the title;
 - **title type**: any of the nine fonts instead of the style's, and the title in capitals or as typed. It stays when you change style, so the rail shows every style in your type;
@@ -41,6 +41,10 @@ On [covers.otsirh.dev](https://covers.otsirh.dev) you type a title and author (p
 
 **Store size** shrinks the preview to the size a store lists covers at, to check the title still reads. **Randomize** reshuffles everything, except what you've locked. Undo and redo step back and forth through your designs, and so do the browser's Back and Forward buttons. **Copy link** shares the exact design, because the URL holds every setting. The export panel tells you which size suits Kindle, print or audiobook covers.
 
+**Mockup** shows and downloads the cover as a 3D book, a flat shot, on an e-reader, or on a social card (a 1200 × 630 link preview, a square post or a story, with a line such as "Out now").
+
+**Many covers** takes a list of books (one per line as `Title | Author | Subtitle`, or a CSV with a title column) and makes them all with the design you have, as PNG or SVG in one ZIP. With a fixed variation they share one look, as a series does; switch on "A different palette for each" for a set in several colours.
+
 **Keep** saves a design to a tray under the preview, together with the cover as it was drawn, so a later version of the app can't change it. **Download all** saves every kept design as a PNG in one ZIP file. **Export** saves the kept designs to a file, and **Import** adds them in another browser.
 
 The app works offline once it has loaded.
@@ -106,11 +110,13 @@ npx book-cover-generator --list   # all styles and palettes
 npx book-cover-generator "Bright Machines" --bg 0b132b --ink f8f9fa --accent ff6b6b,4ecdc4 --format ebook --width 1600 -o cover.svg
 # any size, and the choices as JSON (with the SVG, when there is no -o)
 npx book-cover-generator "Neon Tide" --size 1800x2700 --json
+# a cover for every book in a list (CSV with a header row, JSON lines, or "Title | Author" lines), one look for all
+npx book-cover-generator --batch books.csv --style minimal --seed series --out-dir covers
 # twelve variations to choose from: ideas/cover-1.svg … ideas/cover-12.svg (seeds 1 to 12)
 npx book-cover-generator "Salt and Static" --count 12 -o ideas/cover.svg
 ```
 
-Options: `-s/--style`, `-p/--palette`, `--bg`, `--ink`, `--accent`, `--subtitle`, `--texture`, `--seed`, `--format` (`paperback`, `ebook` or `square`), `--width`, `--height`, `--size`, `--lang`, `--series`, `--credit`, `--font`, `--case upper|normal`, `--variant name=value` (`--list` shows each style's), `-o/--out`, `--count`, `--json`, `--list`, `--help`.
+Options: `-s/--style`, `-p/--palette`, `--bg`, `--ink`, `--accent`, `--subtitle`, `--texture`, `--seed`, `--format` (`paperback`, `ebook` or `square`), `--width`, `--height`, `--size`, `--lang`, `--series`, `--credit`, `--badge`, `--font`, `--case upper|normal`, `--variant name=value` (`--list` shows each style's), `-o/--out`, `--count`, `--batch <file|->`, `--out-dir`, `--json`, `--list`, `--help`.
 
 ## API
 
@@ -118,7 +124,7 @@ Options: `-s/--style`, `-p/--palette`, `--bg`, `--ink`, `--accent`, `--subtitle`
 
 Returns the SVG markup.
 
-### `createCover(options) → { svg, body, style, palette, seed, width, height, lang }`
+### `createCover(options) → { svg, body, style, palette, colors, seed, width, height, lang, variants, title, author }`
 
 Same as `generateCover`, but also tells you which style and palette were chosen. This is useful when either one was random. `body` is the markup inside the outer `<svg>`, for nesting the cover in a larger SVG (its ids are unique to the cover, so several can share a document).
 
@@ -129,6 +135,7 @@ Same as `generateCover`, but also tells you which style and palette were chosen.
 | `subtitle`  | `string`           | `''`                   | optional subtitle or tagline                      |
 | `series`    | `string`           | `''`                   | a series line above the title                     |
 | `credit`    | `string`           | `''`                   | a credit under the subtitle ("Translated by…")    |
+| `badge`     | `string`           | `''`                   | a seal in a corner clear of the text              |
 | `texture`   | `boolean`          | `false`                | adds a fine film grain                            |
 | `style`     | `string`           | `'random'`             | a style id, see `styles`                          |
 | `palette`   | `string \| object` | `'random'`             | a palette id, or `{ bg, ink, accents: [...] }`    |
@@ -153,6 +160,8 @@ Titles and subtitles longer than 300 characters (authors: 200) are cut. With `'r
 - `pickStyle(options)`: the style id `createCover` would use for these options (resolving `'random'` from the seed), without drawing the cover
 - `registerStyle({ id, name, description, group, prefer, render(ctx) })`: add your own style (see below). Replacing a built-in style takes `registerStyle(style, { replace: true })`; `unregisterStyle(id)` removes a style or brings the built-in back
 - `registerPalette({ id, name, bg, ink, accents })`: add a palette to use by id, as `palette: 'brand'` (`{ replace: true }` for a built-in id); `unregisterPalette(id)` removes it. Registered styles and palettes can also be picked by `'random'`, so registering one changes what a seed gives
+- `parseBookList(text)`: a list of books (CSV with commas, semicolons or tabs and a header row naming a `title` column, JSON lines, or one "Title | Author | Subtitle" per line) as cover options, one per book
+- `noteText(x0, y0, x1, y1)` and `recordText(draw)`: note where a custom style writes its own text (so a badge stays clear of it), and collect what `draw` notes
 - `version`: the library's version (artwork for a seed can change between minor versions)
 - `sizeLimits` (`{ min: 50, max: 10000, ratio: 3 }`) and `formats` (`paperback`, `ebook` and `square` as `[width, height]` at 600 px wide): the sizes covers can have, and the app's shapes
 - `titleBlock`, `authorFit`: the typography the built-in styles use (a title with its lead line and subtitle, and the author line)
@@ -164,6 +173,18 @@ Titles and subtitles longer than 300 characters (authors: 200) are cut. With `'r
 
 Types are included. `CoverOptions`, `Cover`, `StyleId`, `PaletteId`, `StyleGroup`, `StyleContext`, `CoverStyle`, `TitleBlock` and the rest are exported from the main entry point, and style and palette ids autocomplete.
 
+### Mockups
+
+```js
+import { createCover, createMockup } from 'book-cover-generator';
+
+const cover = createCover({ title: 'Neon Tide', author: 'Kai Moreno' });
+const { svg, width, height } = createMockup(cover, { kind: 'book' }); // or 'flat', 'ereader'
+const card = createMockup(cover, { kind: 'card', text: 'Out now' }); // 1200 × 630; also 'square', 'story'
+```
+
+Product shots (`flat`, `book`, `ereader`) follow the cover's size on a light backdrop (`background` to change it); social cards have fixed sizes and take the cover's colours. `mockupKinds` lists them.
+
 ### Export helpers (browser)
 
 ```js
@@ -206,6 +227,7 @@ generateCover({
 - `p`: the palette, with `bg`, `ink`, `accents`, plus `paper` (lighter) and `night` (darker)
 - `id(name)`: makes ids that are unique per cover, for gradients and filters
 - `titleFont`, `titleCase`: the cover's `font` and `titleCase`, or null; `titleBlock` follows them, so a style that sets its title with it gets them for free
+- Text drawn with `drawText`, `drawStack` or `titleBlock` is noted, so a badge stays clear of it; a style that writes its own text elements can call `noteText(x0, y0, x1, y1)`
 - `choose(name, values)`: picks one of `values` as `rng.pick` would, unless the cover pins the variant `name`. Declare what can be pinned in the style's `variants`: `{ mood: { label: 'Mood', values: { calm: 'Calm', loud: 'Loud' } } }`
 
 ```js

package/bin/book-cover.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { parseArgs } from 'node:util';
-import { createCover, listStyles, palettes, formats } from '../src/index.js';
+import { createCover, listStyles, palettes, formats, parseBookList } from '../src/index.js';
 
 const HELP = `Usage: book-cover "<title>" ["<author>"] [options]
 
@@ -19,6 +20,7 @@ Options:
       --subtitle <text> a subtitle or tagline
       --series <text>   a series line above the title ("Book Two of …")
       --credit <text>   a credit under the subtitle ("Translated by …")
+      --badge <text>    a seal in a corner clear of the text ("Bestseller")
       --texture         add a fine film-grain texture
       --seed <value>    seed for the artwork (default: title + author)
       --format <shape>  paperback (2:3, the default), ebook (5:8) or square
@@ -26,6 +28,13 @@ Options:
       --height <px>     height (default: from the format)
       --size <WxH>      width and height at once, e.g. 1600x2560
       --lang <tag>      language of the text, e.g. ja or zh-Hant (default: inferred)
+      --batch <file>    a cover for each book in a list (- reads stdin): CSV or
+                        TSV with a header row (title, author, subtitle, series,
+                        credit, badge, style, palette, seed, font, case, lang,
+                        width, height, texture), JSON lines, or one book per
+                        line as "Title | Author | Subtitle"; the other options
+                        apply to every book the list doesn't say otherwise for
+      --out-dir <dir>   where --batch writes its covers (default: here)
   -o, --out <file>      write SVG to a file instead of stdout
       --count <n>       write n variations (seeds 1…n, or <seed>-1…), named
                         cover-1.svg… from --out (or put {n} or {seed} in it)
@@ -38,7 +47,8 @@ Examples:
   book-cover "The Lighthouse Keeper" "Mara Ellison" -s artdeco -o cover.svg
   book-cover "Neon Tide" "Kai Moreno" --style retro --palette synth --size 1600x2560 > cover.svg
   book-cover "Bright Machines" --bg 0b132b --ink f8f9fa --accent ff6b6b,4ecdc4 --format ebook -o cover.svg
-  book-cover "Salt and Static" "J. R. Okafor" --count 12 -o ideas/cover.svg`;
+  book-cover "Salt and Static" "J. R. Okafor" --count 12 -o ideas/cover.svg
+  book-cover --batch books.csv --style minimal --seed series --out-dir covers`;
 
 let args;
 try {
@@ -56,6 +66,7 @@ try {
       subtitle: { type: 'string' },
       series: { type: 'string' },
       credit: { type: 'string' },
+      badge: { type: 'string' },
       texture: { type: 'boolean' },
       seed: { type: 'string' },
       format: { type: 'string' },
@@ -64,6 +75,8 @@ try {
       size: { type: 'string' },
       lang: { type: 'string' },
       out: { type: 'string', short: 'o' },
+      batch: { type: 'string' },
+      'out-dir': { type: 'string' },
       count: { type: 'string' },
       json: { type: 'boolean' },
       list: { type: 'boolean' },
@@ -77,33 +90,43 @@ try {
 
 const { values, positionals } = args;
 
-if (values.help) {
-  console.log(HELP);
-  process.exit(0);
-}
-
-if (values.list) {
-  console.log('Styles:');
-  for (const s of listStyles()) {
-    console.log(`  ${s.id.padEnd(14)} ${s.description}`);
-    for (const v of s.variants) {
-      console.log(`  ${''.padEnd(14)}   --variant ${v.name}=${v.values.map((x) => x.value).join('|')}`);
+/**
+ * Help, the list, and checks of the arguments: whether to go on and make covers. (Exit codes are
+ * set, not exited with, so output piped elsewhere is written in full first.)
+ */
+function preflight() {
+  if (values.help) {
+    console.log(HELP);
+    return false;
+  }
+  if (values.list) {
+    console.log('Styles:');
+    for (const s of listStyles()) {
+      console.log(`  ${s.id.padEnd(14)} ${s.description}`);
+      for (const v of s.variants) {
+        console.log(`  ${''.padEnd(14)}   --variant ${v.name}=${v.values.map((x) => x.value).join('|')}`);
+      }
     }
+    console.log('\nPalettes:');
+    for (const p of palettes) console.log(`  ${p.id.padEnd(14)} ${p.name}${p.dark ? ' (dark)' : ''}`);
+    return false;
   }
-  console.log('\nPalettes:');
-  for (const p of palettes) console.log(`  ${p.id.padEnd(14)} ${p.name}${p.dark ? ' (dark)' : ''}`);
-  process.exit(0);
-}
-
-if (!positionals.length) {
-  console.error(HELP);
-  process.exit(1);
-}
-if (positionals.length > 2) {
-  console.error(
-    `Expected a title and an author, got ${positionals.length} arguments. Quote values with spaces: book-cover "The Lighthouse Keeper" "Mara Ellison"`,
-  );
-  process.exit(1);
+  /** @param {string} message */
+  const fail = (message) => {
+    console.error(message);
+    process.exitCode = 1;
+    return false;
+  };
+  if (values.batch !== undefined && positionals.length) {
+    return fail('--batch takes the titles from its list: give no title on the command line');
+  }
+  if (!positionals.length && values.batch === undefined) return fail(HELP);
+  if (positionals.length > 2) {
+    return fail(
+      `Expected a title and an author, got ${positionals.length} arguments. Quote values with spaces: book-cover "The Lighthouse Keeper" "Mara Ellison"`,
+    );
+  }
+  return true;
 }
 
 /**
@@ -208,41 +231,120 @@ function fileFor(out, n, total, seed) {
  */
 const safeName = (seed) => seed.replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^[.-]+/, '') || 'cover';
 
-try {
-  const total = count();
-  const options = {
-    title: positionals[0],
-    author: positionals[1] ?? '',
-    subtitle: values.subtitle,
-    series: values.series,
-    credit: values.credit,
-    texture: values.texture,
-    style: values.style,
-    palette: palette(),
-    lang: values.lang,
-    variants: variants(),
-    font: values.font,
-    titleCase: /** @type {'upper' | 'normal' | undefined} */ (values.case),
-    ...dimensions(),
-  };
-  for (let n = 1; n <= total; n++) {
-    // One cover: the seed given (or the title's). Several: seeds 1…n, or <seed>-1…<seed>-n.
-    const seed = total === 1 ? values.seed : values.seed ? `${values.seed}-${n}` : String(n);
-    const cover = createCover({ ...options, seed });
-    const { style, palette: paletteId, width, height, lang } = cover;
-    const choices = { style, palette: paletteId, seed: cover.seed, width, height, lang, variants: cover.variants };
-    if (values.out) {
-      const file = fileFor(values.out, n, total, cover.seed);
+/** A title as part of a file name: lower case, accents off Latin letters, dashes between words. @param {string} title */
+function slug(title) {
+  const words = title
+    .normalize('NFKD')
+    .replace(/(\p{Script=Latin})[\u0300-\u036f]+/gu, '$1')
+    .normalize('NFC')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{M}\p{N}]+/gu, '-')
+    .replace(/^-+/, '');
+  return Array.from(words).slice(0, 60).join('').replace(/-+$/, '') || 'cover';
+}
+
+/**
+ * Write a cover for each book in the --batch list into --out-dir; the command line's options
+ * apply to every book the list doesn't say otherwise for.
+ * @param {import('../src/index.js').CoverOptions} defaults
+ */
+function batch(defaults) {
+  if (values.count !== undefined || values.out !== undefined) {
+    throw new Error('--batch writes a file per book into --out-dir: use it without --out or --count');
+  }
+  const source = /** @type {string} */ (values.batch);
+  const books = parseBookList(readFileSync(source === '-' ? 0 : source, 'utf8'));
+  if (!books.length) {
+    throw new Error(
+      `No books in ${source === '-' ? 'the input' : source}: a title per line, or a CSV with a "title" column`,
+    );
+  }
+  const dir = values['out-dir'] ?? '.';
+  mkdirSync(dir, { recursive: true });
+  const digits = String(books.length).length;
+  let failed = 0;
+  books.forEach((book, i) => {
+    const n = i + 1;
+    try {
+      // A size in the list replaces the command line's.
+      const sized = book.width !== undefined || book.height !== undefined;
+      const cover = createCover({
+        ...defaults,
+        ...(sized ? { width: undefined, height: undefined } : {}),
+        ...book,
+        seed: book.seed ?? values.seed,
+      });
+      const file = join(dir, `${String(n).padStart(digits, '0')}-${slug(cover.title)}.svg`);
       writeFileSync(file, cover.svg);
-      if (values.json) process.stdout.write(JSON.stringify({ file, ...choices }) + '\n');
-      else console.error(`Wrote ${file} (style: ${style}, palette: ${paletteId}, ${width}x${height})`);
-    } else if (values.json) {
-      process.stdout.write(JSON.stringify({ ...choices, svg: cover.svg }) + '\n');
-    } else {
-      process.stdout.write(cover.svg + '\n');
+      const { style, palette: paletteId, seed, width, height } = cover;
+      if (values.json)
+        process.stdout.write(JSON.stringify({ file, style, palette: paletteId, seed, width, height }) + '\n');
+    } catch (err) {
+      failed += 1;
+      console.error(`Book ${n} ("${book.title}"): ${err instanceof Error ? err.message : String(err)}`);
+    }
+  });
+  console.error(`Wrote ${books.length - failed} of ${books.length} covers to ${dir}`);
+  if (failed) process.exitCode = 1;
+}
+
+function run() {
+  try {
+    if (values.batch !== undefined) {
+      batch({
+        subtitle: values.subtitle,
+        series: values.series,
+        credit: values.credit,
+        badge: values.badge,
+        texture: values.texture,
+        style: values.style,
+        palette: palette(),
+        lang: values.lang,
+        variants: variants(),
+        font: values.font,
+        titleCase: /** @type {'upper' | 'normal' | undefined} */ (values.case),
+        ...dimensions(),
+      });
+      return;
+    }
+    const total = count();
+    const options = {
+      title: positionals[0],
+      author: positionals[1] ?? '',
+      subtitle: values.subtitle,
+      series: values.series,
+      credit: values.credit,
+      badge: values.badge,
+      texture: values.texture,
+      style: values.style,
+      palette: palette(),
+      lang: values.lang,
+      variants: variants(),
+      font: values.font,
+      titleCase: /** @type {'upper' | 'normal' | undefined} */ (values.case),
+      ...dimensions(),
+    };
+    for (let n = 1; n <= total; n++) {
+      // One cover: the seed given (or the title's). Several: seeds 1…n, or <seed>-1…<seed>-n.
+      const seed = total === 1 ? values.seed : values.seed ? `${values.seed}-${n}` : String(n);
+      const cover = createCover({ ...options, seed });
+      const { style, palette: paletteId, width, height, lang } = cover;
+      const choices = { style, palette: paletteId, seed: cover.seed, width, height, lang, variants: cover.variants };
+      if (values.out) {
+        const file = fileFor(values.out, n, total, cover.seed);
+        writeFileSync(file, cover.svg);
+        if (values.json) process.stdout.write(JSON.stringify({ file, ...choices }) + '\n');
+        else console.error(`Wrote ${file} (style: ${style}, palette: ${paletteId}, ${width}x${height})`);
+      } else if (values.json) {
+        process.stdout.write(JSON.stringify({ ...choices, svg: cover.svg }) + '\n');
+      } else {
+        process.stdout.write(cover.svg + '\n');
+      }
     }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
   }
-} catch (err) {
-  console.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
 }
+
+if (preflight()) run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "book-cover-generator",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Generate SVG book covers from a title and an author. 34 styles, 28 palettes, seeded randomizer, zero dependencies.",
   "keywords": [
     "book",

package/src/badge.js

@@ -0,0 +1,85 @@
+// A badge on the cover: a seal ("Winner of the …", "10th Anniversary Edition") set in a corner
+// clear of the text.
+
+import { n, mix, escapeXml } from './core.js';
+import { FONTS, fitText, drawText } from './text.js';
+import { strongAccents, textColor } from './styles/util.js';
+
+/** @typedef {import('./text.js').TextBox} TextBox */
+
+/** How much of the square around a circle a box covers. @param {number} cx @param {number} cy @param {number} r @param {TextBox} b */
+function overlap(cx, cy, r, b) {
+  const w = Math.min(cx + r, b.x1) - Math.max(cx - r, b.x0);
+  const h = Math.min(cy + r, b.y1) - Math.max(cy - r, b.y0);
+  return w > 0 && h > 0 ? w * h : 0;
+}
+
+/**
+ * The seal: a star-edged disc with a ring and the text inside, tilted a little, in the first
+ * corner (then side) clear of the text, smaller if it must be; else where it covers least.
+ * @param {import('./index.js').StyleContext} c
+ * @param {string} text
+ * @param {TextBox[]} boxes the text already on the cover
+ */
+export function drawBadge(c, text, boxes) {
+  const { W, H, S, u, m, p } = c;
+  /** Where a seal of radius r could go: corners first, then the middle of each side. @param {number} r */
+  const spots = (r) => {
+    const inset = m * 0.5 + r;
+    return [
+      [W - inset, inset],
+      [inset, inset],
+      [W - inset, H - inset],
+      [inset, H - inset],
+      [W - inset, H / 2],
+      [inset, H / 2],
+    ];
+  };
+  const pad = S * 0.01;
+  /** @type {[number, number, number] | null} */
+  let place = null;
+  for (const scale of [1, 0.85, 0.7]) {
+    const r = S * 0.12 * scale;
+    const free = spots(r).find(([x, y]) => boxes.every((b) => overlap(x, y, r + pad, b) === 0));
+    if (free) {
+      place = [free[0], free[1], r];
+      break;
+    }
+  }
+  if (!place) {
+    const r = S * 0.084;
+    const covered = (/** @type {number[]} */ [x, y]) => boxes.reduce((sum, b) => sum + overlap(x, y, r, b), 0);
+    const best = spots(r).reduce((a, b) => (covered(b) < covered(a) ? b : a));
+    place = [best[0], best[1], r];
+  }
+  const [cx, cy, r] = place;
+
+  const fill = strongAccents(p, p.bg, 1.5)[0];
+  const ink = textColor(p, fill, [p.paper, p.night]);
+  const points = [];
+  const spikes = 28;
+  for (let i = 0; i < spikes * 2; i++) {
+    const a = (i / (spikes * 2)) * Math.PI * 2;
+    const rr = i % 2 ? r * 0.9 : r;
+    points.push(`${n(cx + Math.cos(a) * rr)},${n(cy + Math.sin(a) * rr)}`);
+  }
+  const fit = fitText(text, {
+    font: FONTS.sans,
+    weight: 700,
+    upper: true,
+    letterSpacing: 0.04,
+    maxWidth: r * 1.25,
+    maxHeight: r * 1.05,
+    maxSize: r * 0.3,
+    maxLines: 4,
+    lineHeight: 1.05,
+  });
+  const edge = mix(fill, p.night, 0.35);
+  return (
+    `<g transform="rotate(-8 ${n(cx)} ${n(cy)})" aria-label="${escapeXml(text)}">` +
+    `<polygon points="${points.join(' ')}" fill="${fill}" stroke="${edge}" stroke-width="${n(1.2 * u)}"/>` +
+    `<circle cx="${n(cx)}" cy="${n(cy)}" r="${n(r * 0.76)}" fill="none" stroke="${ink}" stroke-width="${n(1.4 * u)}" opacity="0.7"/>` +
+    drawText(fit, { x: cx, y: cy - fit.height / 2, anchor: 'middle', fill: ink }) +
+    '</g>'
+  );
+}

package/src/books.js

@@ -0,0 +1,143 @@
+// A list of books, as people paste or export it, read into cover options: CSV or TSV with a
+// header row, JSON lines, or one book per line ("Title | Author | Subtitle").
+
+/** The columns a list may have, by the names it may give them, and how each is read. */
+const COLUMNS = /** @type {const} */ ({
+  title: 'title',
+  author: 'author',
+  subtitle: 'subtitle',
+  series: 'series',
+  credit: 'credit',
+  badge: 'badge',
+  style: 'style',
+  palette: 'palette',
+  seed: 'seed',
+  font: 'font',
+  case: 'titleCase',
+  titlecase: 'titleCase',
+  lang: 'lang',
+  width: 'width',
+  height: 'height',
+  texture: 'texture',
+});
+
+/** Separators of a plain line: a tab, or a bar or dash with spaces around it. */
+const LINE_SEPARATOR = /\t| \| | — | – /;
+
+/**
+ * Split CSV (or TSV) text into rows of fields: quoted fields may hold the delimiter, quotes ("")
+ * and line breaks.
+ * @param {string} text @param {string} delimiter
+ * @returns {string[][]}
+ */
+function csvRows(text, delimiter) {
+  /** @type {string[][]} */
+  const rows = [];
+  /** @type {string[]} */
+  let row = [];
+  let field = '';
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '"' && text[i + 1] === '"') {
+        field += '"';
+        i++;
+      } else if (ch === '"') quoted = false;
+      else field += ch;
+    } else if (ch === '"' && field === '') quoted = true;
+    else if (ch === delimiter) {
+      row.push(field);
+      field = '';
+    } else if (ch === '\n' || ch === '\r') {
+      if (ch === '\r' && text[i + 1] === '\n') i++;
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = '';
+    } else field += ch;
+  }
+  if (field !== '' || row.length) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows.filter((r) => r.some((f) => f.trim()));
+}
+
+/**
+ * Cover options from a row's named values: known columns only, trimmed, empty ones left out,
+ * numbers and switches read as such.
+ * @param {Record<string, unknown>} named
+ * @returns {import('./index.js').CoverOptions}
+ */
+function optionsFrom(named) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [key, raw] of Object.entries(named)) {
+    const option = COLUMNS[/** @type {keyof typeof COLUMNS} */ (key.trim().toLowerCase())];
+    if (!option || raw == null) continue;
+    if (option === 'texture') {
+      const v = String(raw).trim().toLowerCase();
+      if (v) out.texture = raw === true || ['1', 'true', 'yes', 'y', 'on'].includes(v);
+      continue;
+    }
+    // (Numbers stay numbers for sizes and the seed; any other column is text, a title of 1984 too.)
+    const value = typeof raw === 'number' && option !== 'title' ? raw : String(raw).trim();
+    if (value === '') continue;
+    if (option === 'width' || option === 'height') out[option] = Number(value);
+    else out[option] = option === 'seed' ? value : String(value);
+  }
+  return /** @type {import('./index.js').CoverOptions} */ (out);
+}
+
+/**
+ * Read a list of books into cover options, one per book (rows without a title are left out):
+ *
+ * - CSV or TSV whose first row names its columns (`title`, `author`, `subtitle`, `series`,
+ *   `credit`, `badge`, `style`, `palette`, `seed`, `font`, `case`, `lang`, `width`, `height`,
+ *   `texture`; others are ignored);
+ * - JSON lines, one object per book, with the same names;
+ * - else one book per line: "Title | Author | Subtitle" (a tab, or " — " or " – ", also separates).
+ *
+ * @param {string} text
+ * @returns {import('./index.js').CoverOptions[]}
+ */
+export function parseBookList(text) {
+  const src = String(text ?? '').replace(/^\uFEFF/, '');
+  // (Each with its line number in the text, for errors.)
+  const lines = src
+    .split(/\r\n|[\r\n]/)
+    .map((line, i) => ({ line, number: i + 1 }))
+    .filter(({ line }) => line.trim());
+  if (!lines.length) return [];
+  /** @type {import('./index.js').CoverOptions[]} */
+  let books;
+  if (lines.every(({ line }) => line.trim().startsWith('{'))) {
+    books = lines.map(({ line, number }) => {
+      let value;
+      try {
+        value = JSON.parse(line);
+      } catch {
+        throw new SyntaxError(`Line ${number} is not valid JSON`);
+      }
+      return value && typeof value === 'object' ? optionsFrom(value) : {};
+    });
+  } else {
+    // A header row names a "title" column, separated by tabs, commas or semicolons (as
+    // spreadsheets in many countries save CSV).
+    const first = lines[0].line;
+    const delimiter = ['\t', ',', ';'].find((d) =>
+      (csvRows(first, d)[0] ?? []).some((name) => name.trim().toLowerCase() === 'title'),
+    );
+    if (delimiter) {
+      const [names, ...rows] = csvRows(src, delimiter);
+      books = rows.map((row) => optionsFrom(Object.fromEntries(names.map((name, i) => [name, row[i] ?? '']))));
+    } else {
+      books = lines.map(({ line }) => {
+        const [title, author, subtitle] = line.split(LINE_SEPARATOR);
+        return optionsFrom({ title, author, subtitle });
+      });
+    }
+  }
+  return books.filter((book) => typeof book.title === 'string' && book.title.trim());
+}

package/src/index.d.ts

@@ -4,7 +4,7 @@ import type { FontSpec, FONTS } from './text.js';
 
 export type { Rng } from './core.js';
 export type { Palette, PaletteId } from './palettes.js';
-export type { FontSpec, FitOptions, TextFit, DrawOptions, TextSpec, TextMeasurer } from './text.js';
+export type { FontSpec, FitOptions, TextFit, DrawOptions, TextSpec, TextMeasurer, TextBox } from './text.js';
 export type { StackFit, TitleBlock, TitleBlockOptions } from './type.js';
 export { palettes } from './palettes.js';
 export {
@@ -17,11 +17,36 @@ export {
   textBottom,
   textGroupAttrs,
   markExtent,
+  noteText,
+  recordText,
 } from './text.js';
 export { titleBlock, authorFit, fitStack, drawStack, splitLead } from './type.js';
 export { strongAccents, textColor, tintText, fitTitleWith, textPanel, TEXT_CONTRAST } from './styles/util.js';
 export * as svgUtils from './core.js';
 
+export type MockupKind = 'flat' | 'book' | 'ereader' | 'card' | 'square' | 'story';
+/** The kinds of mockup `createMockup` makes. */
+export declare const mockupKinds: readonly MockupKind[];
+export interface MockupOptions {
+  /** Default `'book'`. `card` is 1200 × 630, `square` 1080 × 1080, `story` 1080 × 1920; the others follow the cover's size. */
+  kind?: MockupKind;
+  /** A hex colour behind it. Product shots default to a light studio grey, social cards to the cover's colours. */
+  background?: string;
+  /** A line for social cards, such as `'Out now'` (up to 80 characters). */
+  text?: string;
+}
+/**
+ * Read a list of books into cover options, one per book with a title: CSV or TSV whose first row
+ * names its columns (title, author, subtitle, series, credit, badge, style, palette, seed, font,
+ * case, lang, width, height, texture), JSON lines, or one book per line ("Title | Author | Subtitle").
+ */
+export declare function parseBookList(text: string): CoverOptions[];
+/** The cover as a product shot (flat, book, e-reader) or on a social card, as SVG. */
+export declare function createMockup(
+  cover: Cover,
+  options?: MockupOptions,
+): { svg: string; width: number; height: number };
+
 /** This version of the library, such as `'1.4.0'`. Artwork for a seed can change between minor versions. */
 export declare const version: string;
 /** The sizes a cover can have: each side `min` to `max` px, and neither more than `ratio` times the other. */
@@ -92,6 +117,8 @@ export interface CoverOptions {
   series?: string;
   /** A credit set on a line of its own under the subtitle, such as `'Translated by Edith Grossman'`. Up to 120 characters. */
   credit?: string;
+  /** A seal set in a corner clear of the text, such as `'Winner of the Hugo Award'`. Up to 60 characters. */
+  badge?: string;
   /** Add a fine film-grain texture over the cover. Default `false`. */
   texture?: boolean;
   /** A style id, a registered custom style, or `'random'` (default; picked from the seed). */
@@ -132,6 +159,8 @@ export interface Cover {
   style: string;
   /** The palette that was used (`'custom'` for a custom palette). */
   palette: string;
+  /** The palette's colours, as the cover used them. */
+  colors: { bg: string; ink: string; accents: string[]; dark: boolean };
   seed: string;
   width: number;
   height: number;
@@ -139,6 +168,9 @@ export interface Cover {
   lang: string;
   /** The value of each of the style's variants this cover has, pinned or picked by the seed. */
   variants: Record<string, string>;
+  /** The title as set (line breaks as "\n"), and the author, after cleaning. */
+  title: string;
+  author: string;
 }
 
 /** A choice a style lets you pin, such as Silhouette's scene. */

package/src/index.js

@@ -5,7 +5,8 @@
 
 import { createRng, hashString, isHex, luminance, escapeXml, stripInvalidXml, grain } from './core.js';
 import { palettes } from './palettes.js';
-import { BREAKING_SPACE, FONTS, LINE_BREAK, clipGraphemes } from './text.js';
+import { BREAKING_SPACE, FONTS, LINE_BREAK, clipGraphemes, recordText } from './text.js';
+import { drawBadge } from './badge.js';
 import { styleList } from './styles/index.js';
 
 export { palettes } from './palettes.js';
@@ -19,13 +20,17 @@ export {
   textBottom,
   textGroupAttrs,
   markExtent,
+  noteText,
+  recordText,
 } from './text.js';
 export { titleBlock, authorFit, fitStack, drawStack, splitLead } from './type.js';
 export { strongAccents, textColor, tintText, fitTitleWith, textPanel, TEXT_CONTRAST } from './styles/util.js';
 export * as svgUtils from './core.js';
+export { createMockup, mockupKinds } from './mockups.js';
+export { parseBookList } from './books.js';
 
 /** This version of the library (artwork for a seed can change between minor versions). */
-export const version = '1.5.0';
+export const version = '1.6.0';
 
 /** The sizes a cover can have: each side `min` to `max` px, and neither more than `ratio` times the other. */
 export const sizeLimits = Object.freeze({ min: 50, max: 10000, ratio: 3 });
@@ -371,9 +376,10 @@ export function createCover(options = {}) {
   const subtitle = cleanText(options.subtitle, 300);
   const series = cleanText(options.series, 120);
   const credit = cleanText(options.credit, 120);
+  const badge = cleanText(options.badge, 60);
   const W = dimension(options.width, 600, 'width');
   const H = dimension(options.height, W * 1.5, 'height');
-  const lang = resolveLang(options.lang, `${title} ${subtitle} ${author} ${series} ${credit}`);
+  const lang = resolveLang(options.lang, `${title} ${subtitle} ${author} ${series} ${credit} ${badge}`);
   const { ratio } = sizeLimits;
   if (W / H > ratio || H / W > ratio) {
     throw new RangeError(`The aspect ratio must be between 1:${ratio} and ${ratio}:1, got ${W}×${H}`);
@@ -402,6 +408,7 @@ export function createCover(options = {}) {
         ...(Object.keys(pins).length ? [pins] : []),
         ...(titleType.font || titleType.titleCase ? [options.font ?? '', titleType.titleCase ?? ''] : []),
         ...(series || credit ? [series, credit] : []),
+        ...(badge ? [badge] : []),
       ]),
     ).toString(36);
   /** The variants the style chose (or was given). @type {Record<string, string>} */
@@ -435,7 +442,10 @@ export function createCover(options = {}) {
     },
   };
 
-  let body = style.render(ctx);
+  // The text the style draws is recorded, so a badge can go where there is none.
+  const { result: drawn, boxes } = recordText(() => style.render(ctx));
+  let body = drawn;
+  if (badge) body += drawBadge(ctx, badge, boxes);
   if (options.texture) {
     // Film grain over the whole cover. Styles paint their own backgrounds, so lay
     // dark and light specks (from different noise) to show on any colour.
@@ -445,14 +455,28 @@ export function createCover(options = {}) {
   }
   const label = escapeXml(
     `${title.replace(/\n/g, ' ')}${subtitle ? `: ${subtitle}` : ''}${author ? ` by ${author}` : ''}` +
-      `${series ? ` (${series})` : ''}${credit ? `. ${credit}` : ''}`,
+      `${series ? ` (${series})` : ''}${credit ? `. ${credit}` : ''}${badge ? `. ${badge}` : ''}`,
   );
   // (Both spellings: `lang` is SVG 2's, `xml:lang` what older renderers read.)
   const langAttrs = lang ? ` lang="${lang}" xml:lang="${lang}"` : '';
   const svg =
     `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}"${langAttrs} role="img" aria-label="${label}">` +
     `<title>${label}</title>${body}</svg>`;
-  return { svg, body, style: styleId, palette: palette.id, seed, width: W, height: H, lang, variants: chosen };
+  const colors = { bg: palette.bg, ink: palette.ink, accents: [...palette.accents], dark: palette.dark };
+  return {
+    svg,
+    body,
+    style: styleId,
+    palette: palette.id,
+    colors,
+    seed,
+    width: W,
+    height: H,
+    lang,
+    variants: chosen,
+    title,
+    author,
+  };
 }
 
 /**

package/src/mockups.js

@@ -0,0 +1,229 @@
+// Mockups: a cover shown as a product (a flat shot, a book, an e-reader) or on a social card,
+// for listings and cover reveals. Each is an SVG with the cover nested in it.
+
+import { n, mix, escapeXml, hashString, contrast, readable } from './core.js';
+import { FONTS, fitText, drawText, textBottom } from './text.js';
+
+/** The kinds of mockup, with the size of each (or how it follows the cover's). */
+export const mockupKinds = Object.freeze(['flat', 'book', 'ereader', 'card', 'square', 'story']);
+
+/** The neutral backdrop of the product shots. */
+const STUDIO = '#ecebe7';
+
+/**
+ * The cover nested at a place and size.
+ * @param {import('./index.js').Cover} cover @param {number} x @param {number} y @param {number} w @param {number} h
+ */
+const nest = (cover, x, y, w, h) =>
+  `<svg x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" viewBox="0 0 ${cover.width} ${cover.height}" preserveAspectRatio="none" overflow="hidden">${cover.body}</svg>`;
+
+/**
+ * A soft shadow under a shape: blurred black, offset down.
+ * @param {string} id @param {number} blur @param {number} dy @param {number} opacity
+ */
+const shadow = (id, blur, dy, opacity) =>
+  `<filter id="${id}" x="-30%" y="-30%" width="160%" height="160%">` +
+  `<feGaussianBlur in="SourceAlpha" stdDeviation="${n(blur)}"/><feOffset dy="${n(dy)}"/>` +
+  `<feComponentTransfer><feFuncA type="linear" slope="${opacity}"/></feComponentTransfer>` +
+  `<feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge></filter>`;
+
+/**
+ * The cover as a product or a social card.
+ *
+ * - `flat`: the cover on a backdrop with a soft shadow.
+ * - `book`: a book turned a little, its spine showing.
+ * - `ereader`: the cover on an e-reader's screen.
+ * - `card` (1200 × 630, a link preview), `square` (1080 × 1080) and `story` (1080 × 1920): the
+ *   cover on a background in its colours, with the title and author, and `text` if given ("Out now").
+ *
+ * @param {import('./index.js').Cover} cover  from createCover
+ * @param {{ kind?: string, background?: string, text?: string }} [options]
+ * @returns {{ svg: string, width: number, height: number }}
+ */
+export function createMockup(cover, { kind = 'book', background, text = '' } = {}) {
+  if (!cover || typeof cover.body !== 'string' || !(cover.width > 0) || !(cover.height > 0)) {
+    throw new TypeError('createMockup: pass a cover from createCover');
+  }
+  if (!mockupKinds.includes(kind)) {
+    throw new RangeError(`Unknown mockup "${kind}". Available: ${mockupKinds.join(', ')}`);
+  }
+  if (background != null && !/^#(?:[0-9a-f]{3}){1,2}$/i.test(background)) {
+    throw new RangeError(`createMockup: background must be a hex colour, got ${JSON.stringify(background)}`);
+  }
+  // Ids unique to this cover and kind of mockup, so several can share a page.
+  const tag = `mk${hashString(cover.svg).toString(36)}-${kind}`;
+  const id = (/** @type {string} */ name) => `${tag}-${name}`;
+  const { width: CW, height: CH, colors } = cover;
+  const words = String(text).replace(/\s+/g, ' ').trim().slice(0, 80);
+  const label = escapeXml(`${cover.title.replace(/\n/g, ' ')}${cover.author ? ` by ${cover.author}` : ''}`);
+
+  // (The cover's language too, so Chinese characters keep that language's forms.)
+  const lang = cover.lang ? ` lang="${escapeXml(cover.lang)}" xml:lang="${escapeXml(cover.lang)}"` : '';
+  /** @param {number} W @param {number} H @param {string} inner */
+  const wrap = (W, H, inner) => ({
+    svg:
+      `<svg xmlns="http://www.w3.org/2000/svg" width="${Math.round(W)}" height="${Math.round(H)}" viewBox="0 0 ${n(W)} ${n(H)}"${lang} role="img" aria-label="${label}">` +
+      `<title>${label}</title>${inner}</svg>`,
+    width: Math.round(W),
+    height: Math.round(H),
+  });
+
+  if (kind === 'flat') {
+    const pad = Math.min(CW, CH) * 0.14;
+    const W = CW + pad * 2;
+    const H = CH + pad * 2;
+    const u = Math.min(CW, CH) / 600;
+    return wrap(
+      W,
+      H,
+      `<defs>${shadow(id('shadow'), 14 * u, 10 * u, 0.32)}</defs>` +
+        `<rect width="${n(W)}" height="${n(H)}" fill="${background ?? STUDIO}"/>` +
+        `<g filter="url(#${id('shadow')})">${nest(cover, pad, pad, CW, CH)}</g>`,
+    );
+  }
+
+  if (kind === 'book') {
+    // The front turned a little away (narrower, its far edge higher), with the spine at its left.
+    const turn = 0.9;
+    const rise = 0.07;
+    const spine = CW * 0.075;
+    const pad = Math.min(CW, CH) * 0.16;
+    const W = spine + CW * turn + pad * 2;
+    const H = CH + CW * rise + pad * 2;
+    const x0 = pad + spine;
+    const y0 = pad + CW * rise;
+    const u = Math.min(CW, CH) / 600;
+    const spineFill = mix(colors.bg, '#000000', 0.32);
+    const sag = spine * 0.32;
+    return wrap(
+      W,
+      H,
+      `<defs>${shadow(id('soft'), 22 * u, 0, 1)}` +
+        `<linearGradient id="${id('gloss')}" x1="0" y1="0" x2="1" y2="0">` +
+        `<stop offset="0" stop-color="#000" stop-opacity="0.28"/><stop offset="0.04" stop-color="#fff" stop-opacity="0.16"/>` +
+        `<stop offset="0.09" stop-color="#000" stop-opacity="0.05"/><stop offset="0.6" stop-color="#fff" stop-opacity="0"/>` +
+        `<stop offset="1" stop-color="#fff" stop-opacity="0.08"/></linearGradient>` +
+        `<linearGradient id="${id('spine')}" x1="0" y1="0" x2="1" y2="0">` +
+        `<stop offset="0" stop-color="#000" stop-opacity="0.3"/><stop offset="0.7" stop-color="#fff" stop-opacity="0.08"/>` +
+        `<stop offset="1" stop-color="#000" stop-opacity="0.25"/></linearGradient></defs>` +
+        `<rect width="${n(W)}" height="${n(H)}" fill="${background ?? STUDIO}"/>` +
+        // The shadow on the floor.
+        `<ellipse cx="${n(x0 + (CW * turn) / 2)}" cy="${n(y0 + CH - CW * rise * 0.3)}" rx="${n((CW * turn) / 2 + spine)}" ry="${n(CW * 0.035)}" fill="#000" opacity="0.28" filter="url(#${id('soft')})"/>` +
+        `<polygon points="${n(x0 - spine)},${n(y0 + sag)} ${n(x0)},${n(y0)} ${n(x0)},${n(y0 + CH)} ${n(x0 - spine)},${n(y0 + CH - sag)}" fill="${spineFill}"/>` +
+        `<polygon points="${n(x0 - spine)},${n(y0 + sag)} ${n(x0)},${n(y0)} ${n(x0)},${n(y0 + CH)} ${n(x0 - spine)},${n(y0 + CH - sag)}" fill="url(#${id('spine')})"/>` +
+        `<g transform="matrix(${turn} ${-rise} 0 1 ${n(x0)} ${n(y0)})">${nest(cover, 0, 0, CW, CH)}` +
+        `<rect width="${CW}" height="${CH}" fill="url(#${id('gloss')})"/></g>`,
+    );
+  }
+
+  if (kind === 'ereader') {
+    const side = CW * 0.07;
+    const top = CH * 0.07;
+    const bottom = CH * 0.12;
+    const pad = Math.min(CW, CH) * 0.14;
+    const DW = CW + side * 2;
+    const DH = CH + top + bottom;
+    const W = DW + pad * 2;
+    const H = DH + pad * 2;
+    const u = Math.min(CW, CH) / 600;
+    return wrap(
+      W,
+      H,
+      `<defs>${shadow(id('shadow'), 16 * u, 12 * u, 0.35)}</defs>` +
+        `<rect width="${n(W)}" height="${n(H)}" fill="${background ?? STUDIO}"/>` +
+        `<g filter="url(#${id('shadow')})"><rect x="${n(pad)}" y="${n(pad)}" width="${n(DW)}" height="${n(DH)}" rx="${n(CW * 0.06)}" fill="#1c1c1e"/></g>` +
+        `<rect x="${n(pad + 2 * u)}" y="${n(pad + 2 * u)}" width="${n(DW - 4 * u)}" height="${n(DH - 4 * u)}" rx="${n(CW * 0.055)}" fill="none" stroke="#3a3a3c" stroke-width="${n(1.5 * u)}"/>` +
+        nest(cover, pad + side, pad + top, CW, CH) +
+        `<rect x="${n(pad + DW / 2 - CW * 0.08)}" y="${n(pad + DH - bottom / 2 - 2 * u)}" width="${n(CW * 0.16)}" height="${n(4 * u)}" rx="${n(2 * u)}" fill="#3a3a3c"/>`,
+    );
+  }
+
+  // Social cards: fixed sizes, in the cover's colours.
+  const [W, H] = { card: [1200, 630], square: [1080, 1080], story: [1080, 1920] }[
+    /** @type {'card' | 'square' | 'story'} */ (kind)
+  ];
+  const bg = background ?? mix(colors.bg, colors.dark ? '#000000' : colors.ink, colors.dark ? 0.35 : 0.08);
+  // Whichever of near-black and near-white reads better on it.
+  const ink = readable(bg, ['#141414', '#f7f5f0']);
+  const u = Math.min(W, H) / 600;
+  // Where the cover goes (as large as its area allows), where the words go, and their sizes.
+  const layout = {
+    card: { area: { x: 70, y: 63, w: 460, h: 504 }, below: 0, margin: 0, sizes: [64, 24, 28] },
+    square: { area: { x: 120, y: 70, w: W - 240, h: 594 }, below: 60, margin: 70, sizes: [56, 26, 30] },
+    story: { area: { x: 120, y: 240, w: W - 240, h: 980 }, below: 110, margin: 220, sizes: [72, 30, 36] },
+  }[/** @type {'card' | 'square' | 'story'} */ (kind)];
+  const { area } = layout;
+  const [titleSize, authorSize, noteSize] = layout.sizes;
+  const scale = Math.min(area.w / CW, area.h / CH);
+  const cw = CW * scale;
+  const ch = CH * scale;
+  const cx = kind === 'card' ? area.x + (area.w - cw) / 2 : (W - cw) / 2;
+  const cy = area.y + (area.h - ch) / 2;
+  let s =
+    `<defs>${shadow(id('shadow'), 18 * u, 14 * u, 0.4)}</defs>` +
+    `<rect width="${W}" height="${H}" fill="${bg}"/>` +
+    `<g filter="url(#${id('shadow')})">${nest(cover, cx, cy, cw, ch)}</g>`;
+  // The words: beside the cover on a card, under it otherwise.
+  const box =
+    kind === 'card'
+      ? { x: 590, y: 120, w: 540, h: 390, anchor: 'start' }
+      : {
+          x: W / 2,
+          y: cy + ch + layout.below,
+          w: W - 200,
+          h: H - (cy + ch + layout.below) - layout.margin,
+          anchor: 'middle',
+        };
+  const title = fitText(cover.title, {
+    font: FONTS.serif,
+    weight: 700,
+    maxWidth: box.w,
+    maxHeight: box.h * 0.55,
+    maxSize: titleSize,
+    maxLines: 4,
+    lineHeight: 1.08,
+  });
+  const author = cover.author
+    ? fitText(cover.author, {
+        font: FONTS.sans,
+        weight: 600,
+        upper: true,
+        letterSpacing: 0.12,
+        maxWidth: box.w,
+        maxSize: authorSize,
+        maxLines: 2,
+      })
+    : null;
+  const note = words
+    ? fitText(words, {
+        font: FONTS.sans,
+        weight: 700,
+        maxWidth: box.w,
+        maxSize: noteSize,
+        maxLines: 2,
+      })
+    : null;
+  const gap = kind === 'card' ? 22 : 18 * u;
+  const blockH =
+    textBottom(title, 0) + (author ? gap + textBottom(author, 0) : 0) + (note ? gap * 1.6 + textBottom(note, 0) : 0);
+  let y = kind === 'card' ? box.y + (box.h - blockH) / 2 : box.y + Math.max(0, (box.h - blockH) / 2);
+  const anchor = /** @type {'start' | 'middle'} */ (box.anchor);
+  s += drawText(title, { x: box.x, y, anchor, fill: ink });
+  y = textBottom(title, y);
+  if (author) {
+    y += gap;
+    s += drawText(author, { x: box.x, y, anchor, fill: ink, opacity: 0.8 });
+    y = textBottom(author, y);
+  }
+  if (note) {
+    y += gap * 1.6;
+    s += drawText(note, {
+      x: box.x,
+      y,
+      anchor,
+      // An accent if one reads on the background (3:1, for large bold text), else the ink.
+      fill: colors.accents.find((a) => contrast(a, bg) >= 3) ?? ink,
+    });
+  }
+  return wrap(W, H, s);
+}

package/src/styles/pattern.js

@@ -18,7 +18,7 @@ import {
   shadowFilter,
   linearGradient,
 } from '../core.js';
-import { FONTS, fitText, drawText, textBottom, typedLines } from '../text.js';
+import { FONTS, fitText, drawText, textBottom, typedLines, noteText } from '../text.js';
 import { titleBlock, authorFit } from '../type.js';
 import { strongAccents, textPanel } from './util.js';
 
@@ -849,6 +849,7 @@ function drawPixelText(fit, x, y, anchor, color) {
     const w = (ln.length * 6 - 1) * q;
     const x0 = anchor === 'middle' ? x - w / 2 : x;
     const y0 = y + li * 10 * q;
+    noteText(x0, y0, x0 + w, y0 + 7 * q);
     [...ln].forEach((ch, ci) => {
       const glyph = PIXEL_FONT[ch];
       if (!glyph) return;

package/src/styles/vintage.js

@@ -22,6 +22,7 @@ import {
   textGroupAttrs,
   baselineOf,
   typedLines,
+  noteText,
 } from '../text.js';
 import { titleBlock, authorFit } from '../type.js';
 import { strongAccents, flower, initialChars, textPanel, textColor } from './util.js';
@@ -283,6 +284,8 @@ const TYPED_BY_LETTER =
 function typedLine(str, x, y, size, weight, rng, color, anchor = 'start') {
   const spec = { font: FONTS.mono, weight };
   const width = measureText(str, size, spec);
+  const left = anchor === 'middle' ? x - width / 2 : x;
+  noteText(left, y - size * 0.8, left + width, y + size * 0.3);
   if (!TYPED_BY_LETTER.test(str)) {
     // Keep joining, conjuncts and direction intact: one run of text, no per-letter jitter.
     return `<text x="${n(x)}" y="${n(y)}" ${textGroupAttrs({ ...spec, size, fill: color, anchor })}>${escapeXml(str)}</text>`;

package/src/text.d.ts

@@ -56,6 +56,17 @@ export declare const BREAKING_SPACE: RegExp;
 export declare const LINE_BREAK: RegExp;
 /** The number of lines text was typed on: 1 without line breaks. */
 export declare function typedLines(text: string): number;
+/** Where some text was drawn. */
+export interface TextBox {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+/** Note that text was drawn in this box (drawText and drawStack do it), so a badge can be placed clear of it. */
+export declare function noteText(x0: number, y0: number, x1: number, y1: number): void;
+/** Run `draw` and collect the boxes of the text it draws. */
+export declare function recordText<T>(draw: () => T): { result: T; boxes: TextBox[] };
 /** The start of a string, cut between user-perceived characters (`units`: count UTF-16 code units). */
 export declare function clipGraphemes(str: string, max: number, options?: { units?: boolean }): string;
 /** Split a string into user-perceived characters. */

package/src/text.js

@@ -864,6 +864,8 @@ export const baselineOf = (fit, y, i) => y + fit.size * ((fit.above ?? 0) + fit.
  */
 export function drawText(fit, { x, y, anchor = 'start', fill = '#000', opacity, attrs = '' }) {
   if (!fit.lines.length) return '';
+  const left = anchor === 'middle' ? x - fit.width / 2 : anchor === 'end' ? x - fit.width : x;
+  noteText(left, y, left + fit.width, textBottom(fit, y));
   const { size, font, weight, italic, letterSpacing } = fit;
   const ls = letterSpacing * size;
   const dx = spacingShift(anchor, ls);
@@ -874,5 +876,34 @@ export function drawText(fit, { x, y, anchor = 'start', fill = '#000', opacity,
   return `<g ${a}>${rows}</g>`;
 }
 
+/** @typedef {{ x0: number, y0: number, x1: number, y1: number }} TextBox  where some text was drawn */
+
+/** The text drawn while a cover renders (see recordText), or null when nothing records it. @type {TextBox[] | null} */
+let textBoxes = null;
+
+/**
+ * Note that text was drawn in this box, so a badge can be placed clear of it. drawText and
+ * drawStack do this themselves; styles that write their own text elements call it.
+ * @param {number} x0 @param {number} y0 @param {number} x1 @param {number} y1
+ */
+export function noteText(x0, y0, x1, y1) {
+  if (textBoxes && [x0, y0, x1, y1].every(Number.isFinite)) textBoxes.push({ x0, y0, x1, y1 });
+}
+
+/**
+ * Run `draw` and collect the boxes of the text it draws.
+ * @template T @param {() => T} draw @returns {{ result: T, boxes: TextBox[] }}
+ */
+export function recordText(draw) {
+  const outer = textBoxes;
+  textBoxes = [];
+  try {
+    const result = draw();
+    return { result, boxes: textBoxes };
+  } finally {
+    textBoxes = outer;
+  }
+}
+
 /** Visual bottom of a fit placed at `y`, including descenders (and marks below). */
 export const textBottom = (fit, y) => (fit.lines.length ? y + fit.height + fit.size * (fit.below ?? DESCENT) : y);

package/src/type.js

@@ -14,6 +14,7 @@ import {
   measureText,
   textBottom,
   textGroupAttrs,
+  noteText,
   spacingShift,
   defaultMinSize,
   checkBox,
@@ -142,6 +143,8 @@ export function fitStack(text, o) {
  * @param {import('./text.js').DrawOptions & { lineFills?: (string | undefined)[] }} o
  */
 export function drawStack(fit, { x, y, anchor = 'start', fill = '#000', opacity, attrs = '', lineFills = [] }) {
+  const left = anchor === 'middle' ? x - fit.width / 2 : anchor === 'end' ? x - fit.width : x;
+  noteText(left, y, left + fit.width, y + fit.height + fit.descent);
   const a = textGroupAttrs({ font: fit.font, weight: fit.weight, italic: fit.italic, fill, anchor, opacity, attrs });
   let baseline = y;
   const rows = fit.lines.map(({ text, size, above = 0 }, i) => {