book-cover-generator 1.5.0 → 1.7.0

package/README.md

@@ -7,7 +7,7 @@
 ![Types](https://img.shields.io/badge/types-included-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-Generate book covers from a **title** and an **author**. 34 styles, 28 palettes or your own colours, a seeded randomizer, any size, and export to **SVG, PNG, JPEG or WebP**. The library has no dependencies and ships TypeScript types. It's written as plain ES modules, so it runs in the browser and in Node.
+Generate book covers from a **title** and an **author**. 39 styles, 28 palettes or your own colours, a seeded randomizer, any size, and export to **SVG, PNG, JPEG or WebP**. The library has no dependencies and ships TypeScript types. It's written as plain ES modules, so it runs in the browser and in Node.
 
 **[▶ Open the generator](https://covers.otsirh.dev)**
 
@@ -15,9 +15,9 @@ Generate book covers from a **title** and an **author**. 34 styles, 28 palettes
 
 ## Features
 
-- **34 styles in six families.**
+- **39 styles in six families.**
   - Typographic: Big Type, Minimal, Big Letter, Swiss.
-  - Genre: Thriller, Botanical, Noir, Blueprint.
+  - Genre: Thriller, Botanical, Noir, Blueprint, Hollow (horror), Ribbon (romance), Crest (fantasy), Storybook (children's), Big Idea (non-fiction).
   - Vintage: Art Deco, Classic Paperback, Engraved, Sunburst, Typewriter.
   - Scenic: Landscape, Retro Sun, Silhouette, Constellation, Orbit, Waves, Aurora, Bookshelf.
   - Geometric: Bauhaus, Split, Blocks, Concentric, Stripes.
@@ -31,15 +31,19 @@ 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;
+- **a style**, from a rail that previews your book in all 39 styles (its Genre menu shows only those that suit a genre, and Randomize then stays in it). Fifteen 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;
 - **a palette**, from swatches that show the background, text colour and accents, or **Custom** for your own five colours (it starts from the palette on the cover and shows the text contrast);
 - **a variation**, the seed behind the artwork: the strip under the preview shows six others to click;
 - **a format**: paperback, eBook, square, or **Custom** for any size in pixels, typed in or picked from common sizes (Kindle, print trim sizes at 300 dpi, audiobook, social posts).
 
-**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.
+**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, and **Copy image link** gives the [HTTP API](#http-api) URL that draws it, to put in any page. 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.
 
@@ -54,6 +58,30 @@ Keyboard shortcuts:
 
 The single-key shortcuts can be turned off under the controls (for example with speech input).
 
+## HTTP API
+
+The site draws covers from a URL too, so a page can show one with nothing installed:
+
+```html
+<img src="https://covers.otsirh.dev/api/cover.svg?title=Dune&author=Frank+Herbert&style=retro" alt="Dune" />
+```
+
+- `GET /api/cover.svg` answers with the cover as SVG.
+- `GET /api/mockup.svg` answers with a [mockup](#mockups) of it. Add `kind` (`book`, `flat`, `ereader`, `card`, `square`, `story`), `text` for the line on a card, square or story, and `background`.
+
+The query takes the options' own names (`title`, `author`, `subtitle`, `series`, `credit`, `badge`, `style`, `palette`, `seed`, `genre`, `font`, `lang`, `width`, `height`) and the app's link parameters, so the part of an app link after `#` draws the same design (the server measures text with the widths of the fonts as macOS draws them, so on another system a line can break a little differently from the app's preview):
+
+| parameter             | value                                                                                          |
+| --------------------- | ---------------------------------------------------------------------------------------------- |
+| `format`              | `paperback`, `ebook`, `square`, or a size in px such as `1600x2560`                            |
+| `case`                | the title `upper`, or `normal` (as typed)                                                      |
+| `texture`             | `1` (on) or `0` (off)                                                                          |
+| `variant`             | pinned choices as `name.value`, joined by `-`: `field.pale-emblem.sun`                         |
+| `palette`             | a palette id, or your own colours as `custom-0b132b-f8f9fa-ff6b6b` (background, text, accents) |
+| `bg`, `ink`, `accent` | your own colours, as hex (the `#` is optional; accents separated by commas)                    |
+
+A title breaks its line at `%0A`. Anyone may embed the answers (CORS and `Cross-Origin-Resource-Policy` allow it), and the headers `X-Cover-Style`, `X-Cover-Palette` and `X-Cover-Version` say what was drawn. The same URL always draws the same cover in a version of the library, so answers are cached for a day. Options the library rejects get a `400` with the reason as plain text.
+
 ## Library usage
 
 ### Browser (no install)
@@ -106,11 +134,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`, `--genre`, `--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 +148,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 +159,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: [...] }`    |
@@ -137,9 +168,12 @@ Same as `generateCover`, but also tells you which style and palette were chosen.
 | `height`    | `number`           | `width × 1.5`          | px, 50–10000                                      |
 | `lang`      | `string`           | inferred               | language of the text, such as `'ja'`              |
 | `variants`  | `object`           | `{}`                   | pin a style's choices: `{ scene: 'forest' }`      |
+| `genre`     | `string`           |                        | with a random style, one that suits this genre    |
 | `font`      | `string`           | the style's            | the title's font, one of `FONTS`                  |
 | `titleCase` | `string`           | the style's            | `'upper'` (capitals) or `'normal'` (as typed)     |
 
+Styles, palettes, genres and fonts may be given by id or by name, in any case: `'artdeco'`, `'Art Deco'` and `'ART DECO'` are the same style, and a book list or a link can name them as the app's menus do.
+
 `lang` is set on the cover so Chinese characters get the right glyphs for the language. Without it, text with kana is marked Japanese and text with Hangul Korean; pass `'zh-Hans'`, `'zh-Hant'` or `'ja'` for text in Chinese characters only.
 
 Titles and subtitles longer than 300 characters (authors: 200) are cut. With `'random'`, the style and palette are picked from the seed, so you get the same result every time for the same seed. Some styles prefer dark or light palettes when they pick one themselves. Invalid options throw an error that says what's wrong.
@@ -147,12 +181,17 @@ Titles and subtitles longer than 300 characters (authors: 200) are cut. With `'r
 ### Other exports
 
 - `styles`: array of style ids
-- `listStyles()`: `[{ id, name, description, group, variants }]`. `variants` lists the choices a style lets you pin, as `[{ name, label, values: [{ value, label }] }]`; pin them with `createCover({ variants: { scene: 'forest' } })`, and `createCover` reports the ones it used in `variants`. Names a style lacks are ignored; a value it lacks throws
+- `genres`: `[{ id, name }]`, the genres styles suit: `literary`, `thriller`, `horror`, `romance`, `fantasy`, `children`, `nonfiction`
+- `listStyles()`: `[{ id, name, description, group, variants, genres }]`. `variants` lists the choices a style lets you pin, as `[{ name, label, values: [{ value, label }] }]`; pin them with `createCover({ variants: { scene: 'forest' } })`, and `createCover` reports the ones it used in `variants`. Names a style lacks are ignored. A value no style offers throws; with a style you name, so does a value that style lacks (a style picked at random takes only the pins it can)
 - `palettes`: `[{ id, name, bg, ink, accents, dark? }]`
 - `randomSeed()`: a short random seed string
 - `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
+- `styleIdFor(name)`: the id of the style a name or id names, in any case (`'Art Deco'` → `'artdeco'`), or `undefined`
+- `optionsForBook(book, defaults)`: the options for one of those books over the options every book shares (its own values win; a genre the shared style doesn't suit picks a style that does)
+- `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 +203,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 +257,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
@@ -234,7 +286,7 @@ registerStyle({
 
 ## Notes
 
-- **Fonts.** Covers only use system font stacks (Georgia, Helvetica, Futura, Didot, Impact, Courier and others), each with close matches on Windows, Android and Linux. This is because an SVG drawn into a canvas for PNG/JPEG export can't load web fonts. In the browser, text is measured with a canvas, so it fits exactly. In Node, widths are estimated; plug in a real font engine with `setTextMeasurer` if you need exact fits there.
+- **Fonts.** Covers only use system font stacks (Georgia, Helvetica, Futura, Didot, Impact, Courier and others), each with close matches on Windows, Android and Linux. This is because an SVG drawn into a canvas for PNG/JPEG export can't load web fonts. In the browser, text is measured with a canvas, so it fits exactly. In Node (and the CLI and HTTP API), the built-in fonts are measured from their characters' widths as macOS draws them, so text fits much as it does in the app; fonts of your own are estimated. Plug in a real font engine with `setTextMeasurer` if you need exact fits there.
 - **Deterministic.** The same options always give the same artwork. In Node the SVG is identical every time. In the browser, text is measured with the fonts installed on that computer, so line breaks can differ slightly between machines. Registering a custom style changes which style `style: 'random'` picks for a given seed.
 - **Versioning.** Artwork for a given seed can change in minor releases (a style gets better). Pin an exact version if you need byte-identical covers forever.
 - **Browser support.** Current Chrome, Edge, Firefox and Safari. Every release is tested in Chromium, Firefox and WebKit, including PNG and JPEG export.
@@ -263,7 +315,7 @@ Open `examples/contact-sheet.html?palettes=noir,mint&seeds=a,b` on the dev serve
 
 ```
 src/            the library (plain ES modules + .d.ts types)
-  styles/       the 34 styles, one file per family
+  styles/       the 39 styles, in a file per family
 bin/            the CLI
 site/           the web app (index.html is at the root)
 public/         files served at the site root: headers, 404, icons, manifest, service worker
@@ -271,9 +323,10 @@ test/           unit tests (node --test)
 test-d/         type tests (tsc)
 e2e/            browser tests (Playwright)
 scripts/        build, dev server and asset generation
+worker/         the HTTP API (the site's Worker)
 ```
 
-The site is a static [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) deployment configured in `wrangler.jsonc`, with security headers in `public/_headers`.
+The site is a [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) deployment configured in `wrangler.jsonc`: static assets, with security headers in `public/_headers`, and a Worker (`worker/index.js`) that answers `/api/*`. The dev server answers `/api/*` the same way.
 
 ## Contributing
 

package/bin/book-cover.js

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
-import { writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { parseArgs } from 'node:util';
-import { createCover, listStyles, palettes, formats } from '../src/index.js';
+import { createCover, listStyles, palettes, formats, parseBookList, optionsForBook, genres } from '../src/index.js';
+import { hex, slug } from '../src/shared.js';
 
 const HELP = `Usage: book-cover "<title>" ["<author>"] [options]
 
 Options:
   -s, --style <id>      style id or "random" (default: random from seed)
   -p, --palette <id>    palette id or "random" (default: random from seed)
+      --genre <id>      with a random style, one that suits this genre:
+                        literary, thriller, horror, romance, fantasy, children
+                        or nonfiction
       --bg <hex>        your own colours instead of a palette: background,
       --ink <hex>       text,
       --accent <hex>    and accents (repeat it, or separate them with commas)
@@ -19,6 +24,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 +32,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, genre, 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 +51,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 {
@@ -47,6 +61,7 @@ try {
     options: {
       style: { type: 'string', short: 's' },
       palette: { type: 'string', short: 'p' },
+      genre: { type: 'string' },
       bg: { type: 'string' },
       ink: { type: 'string' },
       accent: { type: 'string', multiple: true },
@@ -56,6 +71,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 +80,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 +95,46 @@ 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}`);
+      if (s.genres.length) console.log(`  ${''.padEnd(14)}   genres: ${s.genres.join(', ')}`);
+      for (const v of s.variants) {
+        console.log(`  ${''.padEnd(14)}   --variant ${v.name}=${v.values.map((x) => x.value).join('|')}`);
+      }
     }
+    console.log('\nGenres (--genre):');
+    for (const g of genres) console.log(`  ${g.id.padEnd(14)} ${g.name}`);
+    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;
 }
 
 /**
@@ -143,9 +174,6 @@ function dimensions() {
   return { width: W, height: Math.round((W * h) / w) };
 }
 
-/** A colour as typed, with the # added (it starts a comment in most shells). @param {string} c */
-const hex = (c) => (c.trim().startsWith('#') ? c.trim() : `#${c.trim()}`);
-
 /** The palette: an id, or your own colours from --bg, --ink and --accent. */
 function palette() {
   const custom = values.bg !== undefined || values.ink !== undefined || values.accent !== undefined;
@@ -208,41 +236,106 @@ 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);
+/**
+ * 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 {
+      // (The book's own values win, a size in the list replaces the command line's, and a genre
+      // --style doesn't suit picks a style that does: see optionsForBook.)
+      const cover = createCover({ ...optionsForBook(book, defaults), 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,
+        genre: values.genre,
+        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,
+      genre: values.genre,
+      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);
+        mkdirSync(dirname(file), { recursive: true });
+        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,7 +1,7 @@
 {
   "name": "book-cover-generator",
-  "version": "1.5.0",
-  "description": "Generate SVG book covers from a title and an author. 34 styles, 28 palettes, seeded randomizer, zero dependencies.",
+  "version": "1.7.0",
+  "description": "Generate SVG book covers from a title and an author. 39 styles, 28 palettes, seeded randomizer, zero dependencies.",
   "keywords": [
     "book",
     "cover",
@@ -60,6 +60,7 @@
     "test:e2e": "playwright test",
     "check": "npm run lint && npm run format:check && npm run typecheck && npm run lint:package && npm test",
     "assets": "node scripts/generate-assets.js",
+    "metrics": "node scripts/generate-metrics.js",
     "deploy": "npm run check && npm run test:e2e && wrangler deploy"
   },
   "devDependencies": {

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>'
+  );
+}