book-cover-generator 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,7 @@
 # Book Cover Generator
 
 [![CI](https://github.com/otsirh/book-cover-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/otsirh/book-cover-generator/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/book-cover-generator)](https://www.npmjs.com/package/book-cover-generator)
 [![Website](https://img.shields.io/website?url=https%3A%2F%2Fcovers.otsirh.dev&label=covers.otsirh.dev)](https://covers.otsirh.dev)
 ![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
 ![Types](https://img.shields.io/badge/types-included-blue)
@@ -30,9 +31,10 @@ 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, then 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") and a credit ("Translated by…"). Then you choose:
 
-- **a style**, from a rail that previews your book in all 34 styles;
+- **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;
 - **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).
@@ -58,7 +60,7 @@ The single-key shortcuts can be turned off under the controls (for example with
 
 ```html
 <script type="module">
-  import { generateCover } from 'https://cdn.jsdelivr.net/gh/otsirh/book-cover-generator@1/src/index.js';
+  import { generateCover } from 'https://cdn.jsdelivr.net/npm/book-cover-generator@1/src/index.js';
 
   document.body.innerHTML = generateCover({
     title: 'The Lighthouse Keeper',
@@ -74,7 +76,7 @@ The single-key shortcuts can be turned off under the controls (for example with
 ### Node / bundlers
 
 ```sh
-npm install "github:otsirh/book-cover-generator#semver:^1"
+npm install book-cover-generator
 ```
 
 ```js
@@ -95,20 +97,20 @@ writeFileSync('cover.svg', svg);
 ### CLI
 
 ```sh
-npx github:otsirh/book-cover-generator "The Lighthouse Keeper" "Mara Ellison" --style artdeco -o cover.svg
-npx github:otsirh/book-cover-generator --list   # all styles and palettes
+npx book-cover-generator "The Lighthouse Keeper" "Mara Ellison" --style artdeco -o cover.svg
+npx book-cover-generator --list   # all styles and palettes
 ```
 
 ```sh
 # your own colours (the # is optional), as an eBook 1600 px wide
-npx github:otsirh/book-cover-generator "Bright Machines" --bg 0b132b --ink f8f9fa --accent ff6b6b,4ecdc4 --format ebook --width 1600 -o cover.svg
+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 github:otsirh/book-cover-generator "Neon Tide" --size 1800x2700 --json
+npx book-cover-generator "Neon Tide" --size 1800x2700 --json
 # twelve variations to choose from: ideas/cover-1.svg … ideas/cover-12.svg (seeds 1 to 12)
-npx github:otsirh/book-cover-generator "Salt and Static" --count 12 -o ideas/cover.svg
+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`, `-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`, `--font`, `--case upper|normal`, `--variant name=value` (`--list` shows each style's), `-o/--out`, `--count`, `--json`, `--list`, `--help`.
 
 ## API
 
@@ -120,18 +122,23 @@ Returns the SVG markup.
 
 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).
 
-| option     | type               | default                | notes                                          |
-| ---------- | ------------------ | ---------------------- | ---------------------------------------------- |
-| `title`    | `string`           | `'Untitled'`           |                                                |
-| `author`   | `string`           | `''`                   | optional                                       |
-| `subtitle` | `string`           | `''`                   | optional subtitle or tagline                   |
-| `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: [...] }` |
-| `seed`     | `string \| number` | hash of title + author | controls every random choice                   |
-| `width`    | `number`           | `600`                  | px, 50–10000; aspect ratio 1:3 to 3:1          |
-| `height`   | `number`           | `width × 1.5`          | px, 50–10000                                   |
-| `lang`     | `string`           | inferred               | language of the text, such as `'ja'`           |
+| option      | type               | default                | notes                                             |
+| ----------- | ------------------ | ---------------------- | ------------------------------------------------- |
+| `title`     | `string`           | `'Untitled'`           | a line break (`\n`) breaks the title's line there |
+| `author`    | `string`           | `''`                   | optional                                          |
+| `subtitle`  | `string`           | `''`                   | optional subtitle or tagline                      |
+| `series`    | `string`           | `''`                   | a series line above the title                     |
+| `credit`    | `string`           | `''`                   | a credit under the subtitle ("Translated by…")    |
+| `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: [...] }`    |
+| `seed`      | `string \| number` | hash of title + author | controls every random choice                      |
+| `width`     | `number`           | `600`                  | px, 50–10000; aspect ratio 1:3 to 3:1             |
+| `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' }`      |
+| `font`      | `string`           | the style's            | the title's font, one of `FONTS`                  |
+| `titleCase` | `string`           | the style's            | `'upper'` (capitals) or `'normal'` (as typed)     |
 
 `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.
 
@@ -140,7 +147,7 @@ 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 }]`
+- `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
 - `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
@@ -190,7 +197,7 @@ generateCover({
 
 `render(ctx)` returns SVG markup without the outer `<svg>` element. `ctx` contains:
 
-- `title`, `author`, `subtitle` (may be empty)
+- `title`, `author`, `subtitle` (may be empty; a credit follows the subtitle on a line of its own), `series` (set by `titleBlock` above the title)
 - `W`, `H`: the size of the cover
 - `u`: a scale unit (1 at a short side of 600px)
 - `m`: the suggested margin
@@ -198,6 +205,8 @@ generateCover({
 - `rng`: seeded random with `next`, `float`, `int`, `bool`, `pick`, `shuffle`
 - `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
+- `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
 import { registerStyle, titleBlock, authorFit, drawText, FONTS } from 'book-cover-generator';

package/bin/book-cover.js

@@ -11,7 +11,14 @@ Options:
       --bg <hex>        your own colours instead of a palette: background,
       --ink <hex>       text,
       --accent <hex>    and accents (repeat it, or separate them with commas)
+      --variant <n=v>   pin one of the style's choices, e.g. scene=forest
+                        (repeat it; --list shows each style's)
+      --font <name>     the title's font: serif, didone, garamond, sans,
+                        geometric, humanist, condensed, display or mono
+      --case <how>      the title in capitals (upper) or as typed (normal)
       --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 …")
       --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
@@ -43,7 +50,12 @@ try {
       bg: { type: 'string' },
       ink: { type: 'string' },
       accent: { type: 'string', multiple: true },
+      variant: { type: 'string', multiple: true },
+      font: { type: 'string' },
+      case: { type: 'string' },
       subtitle: { type: 'string' },
+      series: { type: 'string' },
+      credit: { type: 'string' },
       texture: { type: 'boolean' },
       seed: { type: 'string' },
       format: { type: 'string' },
@@ -72,7 +84,12 @@ if (values.help) {
 
 if (values.list) {
   console.log('Styles:');
-  for (const s of listStyles()) console.log(`  ${s.id.padEnd(14)} ${s.description}`);
+  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)' : ''}`);
   process.exit(0);
@@ -148,6 +165,18 @@ process.stdout.on('error', (err) => {
   throw err;
 });
 
+/** The pinned variants from --variant name=value. */
+function variants() {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const pair of values.variant ?? []) {
+    const m = /^\s*([^=\s]+)\s*=\s*(\S+)\s*$/.exec(pair);
+    if (!m) throw new RangeError(`--variant must look like scene=forest, got "${pair}"`);
+    out[m[1]] = m[2];
+  }
+  return out;
+}
+
 /** How many covers to write: --count, 1 by default. */
 function count() {
   if (values.count === undefined) return 1;
@@ -185,10 +214,15 @@ try {
     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++) {
@@ -196,7 +230,7 @@ try {
     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 };
+    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);

package/package.json

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

package/src/index.d.ts

@@ -1,5 +1,6 @@
 import type { Rng } from './core.js';
 import type { Palette, PaletteId } from './palettes.js';
+import type { FontSpec, FONTS } from './text.js';
 
 export type { Rng } from './core.js';
 export type { Palette, PaletteId } from './palettes.js';
@@ -87,6 +88,10 @@ export interface CoverOptions {
   author?: string;
   /** A subtitle or tagline, set small under the title. Up to 300 characters are used. */
   subtitle?: string;
+  /** A series line set small above the title, such as `'Book Two of the Ember Cycle'`. Up to 120 characters. */
+  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;
   /** 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). */
@@ -104,6 +109,19 @@ export interface CoverOptions {
    * that language's glyphs. Default: `'ja'` for text with kana, `'ko'` for text with Hangul, else none.
    */
   lang?: string;
+  /**
+   * Choices to pin instead of leaving them to the seed, such as `{ scene: 'forest' }` for
+   * Silhouette (see each style's `variants` in `listStyles()`). Names the style doesn't have
+   * are ignored; a value it doesn't offer throws.
+   */
+  variants?: Readonly<Record<string, string>>;
+  /**
+   * The title's font, one of `FONTS` (`'didone'`, `'geometric'`…), instead of the style's. Styles
+   * that draw their own lettering (Typewriter, Pixel) keep theirs.
+   */
+  font?: keyof typeof FONTS | (string & {});
+  /** Set the title in capitals (`'upper'`) or as typed (`'normal'`) instead of as the style does. */
+  titleCase?: 'upper' | 'normal';
 }
 
 export interface Cover {
@@ -119,6 +137,15 @@ export interface Cover {
   height: number;
   /** The language set on the cover (given or inferred), or `''`. */
   lang: string;
+  /** The value of each of the style's variants this cover has, pinned or picked by the seed. */
+  variants: Record<string, string>;
+}
+
+/** A choice a style lets you pin, such as Silhouette's scene. */
+export interface StyleVariant {
+  name: string;
+  label: string;
+  values: { value: string; label: string }[];
 }
 
 export interface StyleInfo {
@@ -127,6 +154,8 @@ export interface StyleInfo {
   description: string;
   /** The family the style belongs to; `'Custom'` for registered styles without one. */
   group: StyleGroup | (string & {});
+  /** The choices you can pin with `createCover({ variants })`; empty for styles without any. */
+  variants: StyleVariant[];
 }
 
 /** A palette as seen by styles, with derived light/dark colours. */
@@ -143,8 +172,10 @@ export interface ResolvedPalette extends Palette {
 export interface StyleContext {
   readonly title: string;
   readonly author: string;
-  /** Empty when there is no subtitle. */
+  /** Empty when there is no subtitle. A credit, if any, follows on a line of its own (after "\n"). */
   readonly subtitle: string;
+  /** The series line, or empty. `titleBlock` sets it above the title. */
+  readonly series: string;
   /** Cover width in px. */
   readonly W: number;
   /** Cover height in px. */
@@ -160,6 +191,15 @@ export interface StyleContext {
   readonly p: ResolvedPalette;
   /** Make an id that is unique to this cover, for gradients, filters, masks… */
   id(name: string): string;
+  /**
+   * Pick one of `values` for the variant `name`, as `rng.pick(values)` would, unless the cover
+   * pins it (`createCover({ variants: { [name]: value } })`). Repeat a value to make it likelier.
+   */
+  choose<T extends string>(name: string, values: readonly T[]): T;
+  /** The title font the cover asks for (`createCover`'s `font`), or null; `titleBlock` follows it. */
+  readonly titleFont: FontSpec | null;
+  /** The title case the cover asks for (`titleCase`), or null; `titleBlock` follows it. */
+  readonly titleCase: 'upper' | 'normal' | null;
 }
 
 export interface CoverStyle {
@@ -169,6 +209,11 @@ export interface CoverStyle {
   group?: StyleGroup | (string & {});
   /** Background preference when the palette is picked automatically. */
   prefer?: 'light' | 'dark';
+  /**
+   * The choices `render` makes with `ctx.choose(name, values)` that people can pin, with labels:
+   * `{ scene: { label: 'Scene', values: { city: 'City', forest: 'Forest' } } }`.
+   */
+  variants?: Readonly<Record<string, { label?: string; values: Readonly<Record<string, string>> }>>;
   /** Return SVG markup without the outer `<svg>` element. */
   render(ctx: StyleContext): string;
 }

package/src/index.js

@@ -5,7 +5,7 @@
 
 import { createRng, hashString, isHex, luminance, escapeXml, stripInvalidXml, grain } from './core.js';
 import { palettes } from './palettes.js';
-import { BREAKING_SPACE, clipGraphemes } from './text.js';
+import { BREAKING_SPACE, FONTS, LINE_BREAK, clipGraphemes } from './text.js';
 import { styleList } from './styles/index.js';
 
 export { palettes } from './palettes.js';
@@ -25,7 +25,7 @@ export { strongAccents, textColor, tintText, fitTitleWith, textPanel, TEXT_CONTR
 export * as svgUtils from './core.js';
 
 /** This version of the library (artwork for a seed can change between minor versions). */
-export const version = '1.4.0';
+export const version = '1.5.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 });
@@ -40,6 +40,35 @@ export const formats = Object.freeze({
 /** An id as registries take it: a string, not empty, without spaces at either end. @param {unknown} id */
 const isId = (id) => typeof id === 'string' && id !== '' && id === id.trim();
 
+/** A name or value as people read it: 'bouquet' → 'Bouquet'. @param {string} id */
+const labelFor = (id) => id.charAt(0).toUpperCase() + id.slice(1);
+
+/**
+ * A style's variants (the choices it lets you pin), checked and in one shape: each with its
+ * name, a label, and its values with theirs.
+ * @param {string} id the style's id, for errors
+ * @param {import('./index.js').CoverStyle['variants']} variants
+ * @returns {import('./index.js').StyleVariant[]}
+ */
+function variantsOf(id, variants) {
+  if (variants == null) return [];
+  if (typeof variants !== 'object') throw new TypeError(`Style "${id}": variants must be an object`);
+  return Object.entries(variants).map(([name, spec]) => {
+    const values = spec && typeof spec === 'object' && !Array.isArray(spec) ? spec.values : null;
+    const entries = values && typeof values === 'object' ? Object.entries(values) : [];
+    if (!isId(name) || !entries.length || !entries.every(([v, l]) => isId(v) && typeof l === 'string')) {
+      throw new TypeError(
+        `Style "${id}": variant "${name}" needs { values: { value: 'Label', … } } with at least one value`,
+      );
+    }
+    return {
+      name,
+      label: typeof spec.label === 'string' ? spec.label : labelFor(name),
+      values: entries.map(([value, label]) => ({ value, label: label || labelFor(value) })),
+    };
+  });
+}
+
 /**
  * A registry entry: the style's details with defaults filled in, and a render that calls
  * the style's own method on the style itself (so class styles keep `this` and private fields).
@@ -52,9 +81,33 @@ const entryFor = (style) => ({
   description: style.description ?? '',
   group: style.group ?? 'Custom',
   prefer: style.prefer,
+  variants: variantsOf(style.id, style.variants),
   render: (/** @type {import('./index.js').StyleContext} */ ctx) => style.render(ctx),
 });
 
+/**
+ * The variants pinned for a style: the given ones it has (others are ignored, so the same
+ * options can go to any style), each checked against the values it offers.
+ * @param {unknown} given @param {ReturnType<typeof entryFor>} style
+ * @returns {Record<string, string>}
+ */
+function pinnedVariants(given, style) {
+  if (given == null) return {};
+  if (typeof given !== 'object') throw new TypeError('variants must be an object such as { scene: "forest" }');
+  /** @type {Record<string, string>} */
+  const pins = {};
+  for (const variant of style.variants) {
+    const value = /** @type {Record<string, unknown>} */ (given)[variant.name];
+    if (value == null || value === '') continue;
+    if (!variant.values.some((v) => v.value === value)) {
+      const offered = variant.values.map((v) => v.value).join(', ');
+      throw new RangeError(`Style "${style.id}" has no ${variant.name} "${String(value)}". Available: ${offered}`);
+    }
+    pins[variant.name] = /** @type {string} */ (value);
+  }
+  return pins;
+}
+
 const builtInStyles = new Map(styleList.map((s) => [s.id, entryFor(s)]));
 const registry = new Map(builtInStyles);
 /** The palettes, as this module changes them (registering adds to the list everyone sees). */
@@ -64,7 +117,13 @@ const builtInPalettes = new Map(paletteList.map((p) => [p.id, p]));
 
 /** Metadata for every available style: [{ id, name, description, group }] */
 export function listStyles() {
-  return [...registry.values()].map(({ id, name, description, group }) => ({ id, name, description, group }));
+  return [...registry.values()].map(({ id, name, description, group, variants }) => ({
+    id,
+    name,
+    description,
+    group,
+    variants: variants.map((v) => ({ ...v, values: v.values.map((x) => ({ ...x })) })),
+  }));
 }
 
 /** Ids of every available style. */
@@ -191,17 +250,23 @@ function resolvePalette(palette, rng, style) {
   return normalizePalette(found);
 }
 
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CONTROL = /[\u0000-\u001F\u007F-\u009F]/g;
+
 /**
  * Collapse control characters and whitespace, drop anything illegal in XML and
  * cap the length (so huge inputs can't make layout slow).
  * @param {unknown} value
  * @param {number} max  maximum length in characters
+ * @param {{ breaks?: boolean }} [options]
  */
-function cleanText(value, max) {
-  // eslint-disable-next-line no-control-regex -- matching control characters is the point
-  const text = stripInvalidXml(String(value ?? '').replace(/[\u0000-\u001F\u007F-\u009F]/g, ' '))
-    .replace(BREAKING_SPACE, ' ')
-    .trim();
+function cleanText(value, max, { breaks = false } = {}) {
+  // With `breaks`, line breaks stay (as "\n", one between lines): the title's lines break there.
+  const text = String(value ?? '')
+    .split(breaks ? LINE_BREAK : /(?!)/)
+    .map((line) => stripInvalidXml(line.replace(CONTROL, ' ')).replace(BREAKING_SPACE, ' ').trim())
+    .filter(Boolean)
+    .join('\n');
   // Cut between visible characters (segmenting lazily), so an emoji or accented letter is never split.
   return text.length > max ? clipGraphemes(text, max).trimEnd() : text;
 }
@@ -228,6 +293,29 @@ function dimension(value, fallback, name) {
   return Math.round(v);
 }
 
+/** Ways to set a title's letters: in capitals, or as typed. */
+const TITLE_CASES = ['upper', 'normal'];
+
+/**
+ * The title's font and case, if the options set them (else each style's own).
+ * @param {import('./index.js').CoverOptions} options
+ * @returns {{ font: import('./text.js').FontSpec | null, titleCase: 'upper' | 'normal' | null }}
+ */
+function typeOptions(options) {
+  const font = /** @type {unknown} */ (options.font);
+  const titleCase = /** @type {unknown} */ (options.titleCase);
+  if (font != null && font !== '' && !Object.hasOwn(FONTS, /** @type {string} */ (font))) {
+    throw new RangeError(`Unknown font "${String(font)}". Available: ${Object.keys(FONTS).join(', ')}`);
+  }
+  if (titleCase != null && titleCase !== '' && !TITLE_CASES.includes(/** @type {string} */ (titleCase))) {
+    throw new RangeError(`titleCase must be 'upper' or 'normal', got ${JSON.stringify(titleCase)}`);
+  }
+  return {
+    font: font ? FONTS[/** @type {keyof typeof FONTS} */ (font)] : null,
+    titleCase: titleCase ? /** @type {'upper' | 'normal'} */ (titleCase) : null,
+  };
+}
+
 /** A BCP 47 language tag, loosely: `ja`, `zh-Hant`, `pt-BR`, `sr-Latn-RS`. */
 const LANG_TAG = /^[a-z]{2,3}(?:-[a-z\d]{1,8})*$/i;
 const KANA = /[\p{Script=Hiragana}\p{Script=Katakana}]/u;
@@ -255,9 +343,11 @@ function resolveLang(lang, text) {
  * @param {Pick<import('./index.js').CoverOptions, 'title' | 'author' | 'seed' | 'style'>} options
  */
 function resolveText(options) {
-  const title = cleanText(options.title, 300) || 'Untitled';
+  const title = cleanText(options.title, 300, { breaks: true }) || 'Untitled';
   const author = cleanText(options.author, 200);
-  const seed = options.seed == null || options.seed === '' ? `${title}␟${author}` : String(options.seed);
+  // (A line break in the title doesn't change the seed it makes: same words, same artwork.)
+  const seed =
+    options.seed == null || options.seed === '' ? `${title.replace(/\n/g, ' ')}␟${author}` : String(options.seed);
   return { title, author, seed, styleId: resolveStyle(options.style, createRng(`${seed}|style`)) };
 }
 
@@ -279,9 +369,11 @@ export function pickStyle(options = {}) {
 export function createCover(options = {}) {
   const { title, author, seed, styleId } = resolveText(options);
   const subtitle = cleanText(options.subtitle, 300);
+  const series = cleanText(options.series, 120);
+  const credit = cleanText(options.credit, 120);
   const W = dimension(options.width, 600, 'width');
   const H = dimension(options.height, W * 1.5, 'height');
-  const lang = resolveLang(options.lang, `${title} ${subtitle} ${author}`);
+  const lang = resolveLang(options.lang, `${title} ${subtitle} ${author} ${series} ${credit}`);
   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}`);
@@ -291,23 +383,56 @@ export function createCover(options = {}) {
   const [paper, night] =
     luminance(palette.bg) >= luminance(palette.ink) ? [palette.bg, palette.ink] : [palette.ink, palette.bg];
 
+  const pins = pinnedVariants(options.variants, style);
+  const titleType = typeOptions(options);
   const uid =
     'bc' +
-    hashString(JSON.stringify([title, author, subtitle, seed, styleId, palette, W, H, !!options.texture])).toString(36);
+    hashString(
+      // (Pins only when there are some, so ids of covers without them stay as they were.)
+      JSON.stringify([
+        title,
+        author,
+        subtitle,
+        seed,
+        styleId,
+        palette,
+        W,
+        H,
+        !!options.texture,
+        ...(Object.keys(pins).length ? [pins] : []),
+        ...(titleType.font || titleType.titleCase ? [options.font ?? '', titleType.titleCase ?? ''] : []),
+        ...(series || credit ? [series, credit] : []),
+      ]),
+    ).toString(36);
+  /** The variants the style chose (or was given). @type {Record<string, string>} */
+  const chosen = {};
+  const rng = createRng(`${seed}|${styleId}`);
   const short = Math.min(W, H);
   /** @type {import('./index.js').StyleContext} */
   const ctx = {
     title,
     author,
-    subtitle,
+    // A credit ("Translated by …") is a line of its own under the subtitle, so every style sets it.
+    subtitle: [subtitle, credit].filter(Boolean).join('\n'),
+    series,
     W,
     H,
     S: short,
     u: short / 600,
     m: short * 0.07,
-    rng: createRng(`${seed}|${styleId}`),
+    rng,
     p: { ...palette, paper, night },
     id: (name) => `${uid}-${name}`,
+    titleFont: titleType.font,
+    titleCase: titleType.titleCase,
+    // The seed's pick is always drawn, so pinning a variant changes nothing drawn before it.
+    choose: (name, values) => {
+      const picked = rng.pick(values);
+      const pin = pins[name];
+      const value = pin !== undefined && values.includes(/** @type {any} */ (pin)) ? /** @type {any} */ (pin) : picked;
+      chosen[name] = value;
+      return value;
+    },
   };
 
   let body = style.render(ctx);
@@ -318,13 +443,16 @@ export function createCover(options = {}) {
     const light = grain(ctx, { opacity: 0.08, light: true, id: 'texture-light', seed: 11 });
     body += `<defs>${dark.defs}${light.defs}</defs>${dark.layer}${light.layer}`;
   }
-  const label = escapeXml(`${title}${subtitle ? `: ${subtitle}` : ''}${author ? ` by ${author}` : ''}`);
+  const label = escapeXml(
+    `${title.replace(/\n/g, ' ')}${subtitle ? `: ${subtitle}` : ''}${author ? ` by ${author}` : ''}` +
+      `${series ? ` (${series})` : ''}${credit ? `. ${credit}` : ''}`,
+  );
   // (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 };
+  return { svg, body, style: styleId, palette: palette.id, seed, width: W, height: H, lang, variants: chosen };
 }
 
 /**