book-cover-generator 1.7.0 → 1.9.0

package/README.md

@@ -5,11 +5,12 @@
 [![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)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/otsirh/book-cover-generator/badge)](https://scorecard.dev/viewer/?uri=github.com/otsirh/book-cover-generator)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-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.
+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, Node, Deno and Bun.
 
-**[▶ Open the generator](https://covers.otsirh.dev)**
+**[▶ Open the generator](https://covers.otsirh.dev)** · [See every style](https://covers.otsirh.dev/gallery/)
 
 ![Sample covers](docs/preview.png)
 
@@ -23,7 +24,7 @@ Generate book covers from a **title** and an **author**. 39 styles, 28 palettes
   - Geometric: Bauhaus, Split, Blocks, Concentric, Stripes.
   - Pattern: Paper Cut, Halftone, Topographic, Flow Field, Low Poly, Mosaic, Memphis, Pixel.
 - **28 palettes** (15 light, 13 dark), or pass your own. Every style adapts to light and dark palettes.
-- **Typography that responds to the title.** Short titles are set large, a leading "The" or "A" becomes a small line above the title, and some styles stack the words edge to edge. Long titles wrap with balanced lines and shrink to fit. Author names stay readable at thumbnail size. Accents, emoji, Chinese, Japanese and Thai are handled.
+- **Typography that responds to the title.** Short titles are set large, a leading "The" (or another article of three letters or more) becomes a small line above the title, and some styles stack the words edge to edge. Long titles wrap with balanced lines and shrink to fit. Author names stay readable at thumbnail size. Accents, emoji, Chinese, Japanese and Thai are handled.
 - **Subtitle or tagline**, and an optional **paper texture**.
 - **Randomizer.** Every random choice comes from a seed, so the same seed always gives the same cover. If you don't pass a seed, it is derived from the title and author.
 - **Any size.** 2:3 paperback, 5:8 eBook, 1:1 audiobook, or any width × height from 50 to 10,000 px with an aspect ratio between 1:3 and 3:1, such as Kindle's 1600 × 2560 or a print trim size at 300 dpi.
@@ -82,6 +83,42 @@ The query takes the options' own names (`title`, `author`, `subtitle`, `series`,
 
 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.
 
+## On any page: `<book-cover>`
+
+One script, then a cover wherever you write the element:
+
+```html
+<script type="module" src="https://covers.otsirh.dev/src/element.js"></script>
+
+<book-cover cover-title="Dune" author="Frank Herbert" cover-style="retro" seed="1"></book-cover>
+```
+
+Its attributes are the app's link parameters, except the title and the style, which are `cover-title` and `cover-style` (`title` and `style` are HTML's own): `cover-title`, `author`, `subtitle`, `series`, `credit`, `badge`, `cover-style`, `genre`, `palette`, `seed`, `format`, `font`, `case`, `variant`, `texture` (present: on) and `lang` (the language of the text, such as `zh-Hant`). Styles, palettes and fonts may be named as the app's menus name them. With `loading="lazy"`, as on an image, a cover draws only once it comes near the viewport (a page of many covers loads faster); until then it holds the cover's shape and is named for screen readers, and attributes changed meanwhile apply when it draws. The cover is 240 px wide unless you style the element's `width`; it draws again when an attribute changes, and fires `cover` (with the cover) or `cover-error` (with what's wrong). It is drawn in the page, measuring the text with the fonts installed there, and shown as an image, so a page with Trusted Types can show it (its CSP must allow `data:` images). An image can't use the page's web fonts: if the page loads one that a cover's font stack names (such as EB Garamond or Oswald), the text is measured in it but drawn in the system's font, and may fit less well. From npm: `import 'book-cover-generator/element'`.
+
+## From an AI assistant (MCP)
+
+Book Cover Generator is a [Model Context Protocol](https://modelcontextprotocol.io) server, so an assistant such as Claude can make covers for you: "a cover for my horror novel _The Hollow Night_, in red". It answers with a link to the image and one that opens the cover in the app to change and download.
+
+Add it to Claude Code:
+
+```sh
+claude mcp add book-covers -- npx -y book-cover-generator --mcp
+# or, with nothing installed, the hosted server:
+claude mcp add --transport http book-covers https://covers.otsirh.dev/mcp
+```
+
+Or to any client that takes a JSON configuration (Claude Desktop, Cursor and others):
+
+```json
+{
+  "mcpServers": {
+    "book-covers": { "command": "npx", "args": ["-y", "book-cover-generator", "--mcp"] }
+  }
+}
+```
+
+The tools: `create_cover` (a title, and any of author, subtitle, style, genre, palette or your own colours, seed, format, font, pins), `create_mockup` (the same, as a 3D book, on an e-reader or on a social card), `list_styles` and `list_palettes`. Run locally, `create_cover` can also save the SVG to a file (`output`).
+
 ## Library usage
 
 ### Browser (no install)
@@ -101,7 +138,7 @@ A title breaks its line at `%0A`. Anyone may embed the answers (CORS and `Cross-
 
 `@1` gives you the latest 1.x release. Pin an exact version (such as `@1.1.0`) if you need the artwork to never change.
 
-### Node / bundlers
+### Node, Deno, Bun and bundlers
 
 ```sh
 npm install book-cover-generator
@@ -122,6 +159,8 @@ const { svg, style, palette, seed } = createCover({
 writeFileSync('cover.svg', svg);
 ```
 
+In Deno, import `npm:book-cover-generator`; in Bun, `bun add book-cover-generator`. CI checks that Node, Deno and Bun draw the same covers byte for byte.
+
 ### CLI
 
 ```sh
@@ -301,9 +340,10 @@ npm run dev                # http://127.0.0.1:4173
 
 | script                  | what it does                                                      |
 | ----------------------- | ----------------------------------------------------------------- |
-| `npm run check`         | lint, format check, type check, package check and unit tests      |
+| `npm run check`         | lint, format, type and package checks, unit tests and fuzzing     |
 | `npm test`              | unit tests (`node --test`)                                        |
 | `npm run test:coverage` | unit tests with coverage thresholds                               |
+| `npm run test:fuzz`     | property-based fuzzing (fast-check); `FUZZ_RUNS=20` for more      |
 | `npm run test:e2e`      | browser tests in Chromium, Firefox, WebKit and mobile Chrome      |
 | `npm run format`        | format everything with Prettier                                   |
 | `npm run assets`        | regenerate the app icons, the social preview and the README image |

package/bin/book-cover.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
 import { parseArgs } from 'node:util';
-import { createCover, listStyles, palettes, formats, parseBookList, optionsForBook, genres } from '../src/index.js';
+import { createCover, listStyles, palettes, parseBookList, optionsForBook, genres } from '../src/index.js';
 import { hex, slug } from '../src/shared.js';
+import { px, formatSize } from '../src/link.js';
+import { answerPayload } from '../src/mcp.js';
 
 const HELP = `Usage: book-cover "<title>" ["<author>"] [options]
 
@@ -27,7 +30,9 @@ Options:
       --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
+      --format <shape>  paperback (2:3, the default), ebook (5:8), square, or a
+                        shape such as 1600x2560; with --width or --height, that
+                        shape at that width or height
       --width <px>      width  (default 600)
       --height <px>     height (default: from the format)
       --size <WxH>      width and height at once, e.g. 1600x2560
@@ -45,6 +50,8 @@ Options:
       --json            print the choices (and the SVG, without --out) as JSON,
                         one line per cover
       --list            list styles and palettes
+      --mcp             serve the Model Context Protocol on stdin and stdout, so an
+                        AI assistant can make covers (see the README)
       --help            show this help
 
 Examples:
@@ -86,6 +93,7 @@ try {
       json: { type: 'boolean' },
       list: { type: 'boolean' },
       help: { type: 'boolean' },
+      mcp: { type: 'boolean' },
     },
   });
 } catch (err) {
@@ -100,6 +108,10 @@ const { values, positionals } = args;
  * set, not exited with, so output piped elsewhere is written in full first.)
  */
 function preflight() {
+  if (values.mcp) {
+    serveMcp();
+    return false;
+  }
   if (values.help) {
     console.log(HELP);
     return false;
@@ -137,17 +149,6 @@ function preflight() {
   return true;
 }
 
-/**
- * A --width/--height value as a number, reporting what was typed if it isn't one.
- * @param {string | undefined} value @param {string} name
- */
-function size(value, name) {
-  if (value === undefined) return undefined;
-  const number = Number(value);
-  if (!value.trim() || !Number.isFinite(number)) throw new RangeError(`--${name} must be a number, got "${value}"`);
-  return number;
-}
-
 /**
  * Width and height from --format, --width, --height and --size.
  * @returns {{ width?: number, height?: number }}
@@ -161,17 +162,12 @@ function dimensions() {
     if (!m) throw new RangeError(`--size must look like 1600x2560, got "${values.size}"`);
     return { width: Number(m[1]), height: Number(m[2]) };
   }
-  const width = size(values.width, 'width');
-  const height = size(values.height, 'height');
+  const width = values.width === undefined ? undefined : px('--width', values.width);
+  const height = values.height === undefined ? undefined : px('--height', values.height);
   if (values.format === undefined) return { width, height };
-  if (!Object.hasOwn(formats, values.format)) {
-    throw new Error(`Unknown format "${values.format}". Available: ${Object.keys(formats).join(', ')}`);
-  }
-  if (height !== undefined) throw new Error('--format sets the height from the width: use --size for both');
-  // The shape of the app's format, at the width asked for.
-  const [w, h] = formats[/** @type {keyof typeof formats} */ (values.format)];
-  const W = width ?? 600;
-  return { width: W, height: Math.round((W * h) / w) };
+  // A preset or a WxH shape, at the width or height asked for (as the HTTP API reads it).
+  const [w, h] = formatSize(values.format, width, height);
+  return { width: w, height: h };
 }
 
 /** The palette: an id, or your own colours from --bg, --ink and --accent. */
@@ -338,4 +334,36 @@ function run() {
   }
 }
 
+/**
+ * Serve MCP over stdio: a JSON-RPC message per line in, an answer per line out (nothing else on
+ * stdout). A cover can be saved to a file, at an absolute path (the host picks the folder it runs in).
+ */
+function serveMcp() {
+  const lines = createInterface({ input: process.stdin });
+  /** @param {string} path @param {string} data */
+  const writeFile = (path, data) => {
+    // (A host starts the server in a folder of its own choosing: a relative path would land there.)
+    if (!isAbsolute(path)) throw new Error(`output must be an absolute path, got "${path}"`);
+    const file = resolve(path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, data);
+    return file;
+  };
+  /** @param {string | null} text */
+  const send = (text) => {
+    if (text) process.stdout.write(`${text}\n`);
+  };
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }));
+      return;
+    }
+    send(answerPayload(message, { writeFile }));
+  });
+}
+
 if (preflight()) run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "book-cover-generator",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Generate SVG book covers from a title and an author. 39 styles, 28 palettes, seeded randomizer, zero dependencies.",
   "keywords": [
     "book",
@@ -23,7 +23,9 @@
   "license": "MIT",
   "author": "otsirh (https://github.com/otsirh)",
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/element.js"
+  ],
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
@@ -33,6 +35,10 @@
       "types": "./src/browser.d.ts",
       "default": "./src/browser.js"
     },
+    "./element": {
+      "types": "./src/element.d.ts",
+      "default": "./src/element.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./src/index.js",
@@ -51,14 +57,15 @@
     "dev": "node scripts/serve.js 4173",
     "build": "node scripts/build.js",
     "lint": "eslint .",
-    "lint:package": "publint --strict && attw --pack . --profile esm-only",
+    "lint:package": "publint --strict && attw --pack . --profile esm-only && node scripts/check-bundle.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --test",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=src/**/*.js --test-coverage-exclude=src/browser.js --test-coverage-lines=99 --test-coverage-branches=95 --test-coverage-functions=98",
+    "test:fuzz": "node --test fuzz/*.fuzz.js",
     "test:e2e": "playwright test",
-    "check": "npm run lint && npm run format:check && npm run typecheck && npm run lint:package && npm test",
+    "check": "npm run lint && npm run format:check && npm run typecheck && npm run lint:package && npm test && npm run test:fuzz",
     "assets": "node scripts/generate-assets.js",
     "metrics": "node scripts/generate-metrics.js",
     "deploy": "npm run check && npm run test:e2e && wrangler deploy"
@@ -69,7 +76,9 @@
     "@eslint/js": "10.0.1",
     "@playwright/test": "1.65.0",
     "@types/node": "26.6.6",
+    "esbuild": "0.28.2",
     "eslint": "10.14.0",
+    "fast-check": "4.10.2",
     "globals": "17.14.0",
     "prettier": "3.10.0",
     "publint": "0.3.25",

package/src/browser.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./browser.d.ts" */
 // Browser helpers for exporting covers: copy, download, rasterise, zip. (`setDpi` and
 // `zipFiles` also work in Node.)
 

package/src/core.d.ts

@@ -20,7 +20,7 @@ export declare function clamp(v: number, lo: number, hi: number): number;
 export declare function lerp(a: number, b: number, t: number): number;
 export declare function smoothstep(e0: number, e1: number, x: number): number;
 
-export declare function isHex(v: unknown): v is string;
+export declare function isHex(v: unknown): boolean;
 export declare function hexToRgb(hex: string): [number, number, number];
 export declare function rgbToHex(rgb: readonly number[]): string;
 /** Linear blend of two hex colours; `t = 0` is `a`, `t = 1` is `b`. */

package/src/core.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./core.d.ts" */
 // Core utilities: seeded randomness, colour math, noise and SVG helpers.
 
 /** 32-bit string hash (cyrb53 variant folded to 32 bits). */

package/src/element.d.ts

@@ -0,0 +1,22 @@
+import type { CoverOptions, createCover } from './index.js';
+
+/**
+ * `<book-cover>`: a cover on any page, from its attributes (cover-title, author, subtitle, series,
+ * credit, badge, cover-style, genre, palette, seed, format, font, case, texture, variant, lang). It
+ * fires `cover` (detail: the cover) when it draws, and `cover-error` (detail: the error) when the
+ * attributes can't make one. With `loading="lazy"` it draws once it comes near the viewport, as an
+ * image does; until then it holds the cover's shape and is named for screen readers.
+ */
+export declare class BookCover extends HTMLElement {
+  static observedAttributes: string[];
+  /** The cover drawn last, or null (before the first, or after an error). */
+  cover: ReturnType<typeof createCover> | null;
+  /** The cover's options, read from the attributes as the HTTP API reads a link. */
+  options(): CoverOptions;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'book-cover': BookCover;
+  }
+}

package/src/element.js

@@ -0,0 +1,201 @@
+/* @ts-self-types="./element.d.ts" */
+// <book-cover>: a cover on any page, from its attributes.
+//
+//   <script type="module" src="https://covers.otsirh.dev/src/element.js"></script>
+//   <book-cover cover-title="Dune" author="Frank Herbert" cover-style="retro"></book-cover>
+//
+// Attributes: cover-title and cover-style (`title` and `style` are HTML's own: a tooltip, the
+// element's CSS), author, subtitle, series, credit, badge, genre, palette, seed, format (paperback,
+// ebook, square or 1600x2560), font, case, texture (present: on), variant (as in the app's links:
+// scene.forest) and lang (the language of the text, as on any element). With loading="lazy" it
+// draws once it comes near the viewport, as an image does. The cover
+// is drawn as an image (so pages with Trusted Types can show it: the page's CSP must allow data:
+// images), sized by the element's width (240px unless styled).
+
+import { createCover } from './index.js';
+import { svgToDataUrl } from './browser.js';
+import { LINK, optionsFromLink } from './link.js';
+
+/** The attributes that draw the cover, and the link parameter each is. */
+const ATTRIBUTES = /** @type {const} */ ({
+  'cover-title': 'title',
+  author: 'author',
+  subtitle: 'subtitle',
+  series: 'series',
+  credit: 'credit',
+  badge: 'badge',
+  'cover-style': 'style',
+  genre: 'genre',
+  palette: 'palette',
+  seed: 'seed',
+  format: 'format',
+  font: 'font',
+  case: 'case',
+  variant: 'variant',
+  lang: 'lang',
+});
+
+const CSS =
+  ':host{display:inline-block;width:240px;vertical-align:top}:host([hidden]){display:none}' +
+  'img{display:block;width:100%;height:auto}';
+
+/**
+ * How an image of a cover is named: "Cover: Dune by Frank Herbert" (with no title, "Untitled", as
+ * the cover says). @param {string} title @param {string} author
+ */
+const altFor = (title, author) => {
+  const [t, a] = [title, author].map((s) => s.replace(/\s+/g, ' ').trim());
+  return `Cover: ${t || 'Untitled'}${a ? ` by ${a}` : ''}`;
+};
+/** The element's styles as a constructed sheet: a page whose CSP allows no inline styles still applies it. */
+const sheet =
+  typeof CSSStyleSheet !== 'undefined' && 'replaceSync' in CSSStyleSheet.prototype
+    ? (() => {
+        const made = new CSSStyleSheet();
+        made.replaceSync(CSS);
+        return made;
+      })()
+    : null;
+
+// (In Node there is no HTMLElement: the module still loads, and defines nothing.)
+const Base = /** @type {typeof HTMLElement} */ (typeof HTMLElement === 'undefined' ? class {} : HTMLElement);
+
+export class BookCover extends Base {
+  static observedAttributes = [...Object.keys(ATTRIBUTES), 'texture', 'loading'];
+
+  /** The cover drawn last (null before the first, or after an error). @type {ReturnType<typeof createCover> | null} */
+  cover = null;
+  /** @type {HTMLImageElement} */
+  #img;
+  #queued = false;
+  /** Drawn once connected: until then, attributes set (or present when upgraded) wait for it. */
+  #ready = false;
+  /** The options last drawn, to skip drawing them again. */
+  #drawn = '';
+  /** A lazy element waiting to come into view. */
+  #waiting = false;
+  /** Lazy elements wait for this to see them near the viewport (none outside a browser). */
+  static #observer =
+    typeof IntersectionObserver === 'undefined'
+      ? null
+      : new IntersectionObserver(
+          (entries) => {
+            for (const entry of entries) {
+              if (!entry.isIntersecting) continue;
+              const el = /** @type {BookCover} */ (entry.target);
+              BookCover.#observer?.unobserve(el);
+              el.#waiting = false;
+              el.#render();
+            }
+          },
+          { rootMargin: '300px' },
+        );
+
+  constructor() {
+    super();
+    const root = this.attachShadow({ mode: 'open' });
+    if (sheet && 'adoptedStyleSheets' in root) root.adoptedStyleSheets = [sheet];
+    else {
+      const style = document.createElement('style');
+      style.textContent = CSS;
+      root.append(style);
+    }
+    this.#img = document.createElement('img');
+    this.#img.decoding = 'async';
+    this.#img.setAttribute('part', 'image');
+    root.append(this.#img);
+  }
+
+  connectedCallback() {
+    this.#ready = true;
+    // loading="lazy", as on an image: drawn once it comes near the viewport.
+    if (this.#lazy() && !this.cover && BookCover.#observer) {
+      this.#waiting = true;
+      this.#hold();
+      BookCover.#observer.observe(this);
+      return;
+    }
+    this.#render();
+  }
+
+  /** Until it is drawn: named from its attributes, and the cover's own shape held for it. */
+  #hold() {
+    this.#img.alt = altFor(this.getAttribute('cover-title') ?? '', this.getAttribute('author') ?? '');
+    try {
+      const { width = 600, height = width * 1.5 } = this.options();
+      this.#img.style.aspectRatio = `${width} / ${height}`;
+    } catch {
+      this.#img.style.aspectRatio = '2 / 3';
+    }
+  }
+
+  disconnectedCallback() {
+    if (this.#waiting) BookCover.#observer?.unobserve(this);
+    this.#waiting = false;
+  }
+
+  /** Whether it waits to come near the viewport (loading="lazy", in any case, as on an image). */
+  #lazy() {
+    return (this.getAttribute('loading') ?? '').toLowerCase() === 'lazy';
+  }
+
+  attributeChangedCallback(/** @type {string} */ name) {
+    // A waiting cover no longer lazy is drawn at once, as an image is.
+    if (name === 'loading' && this.#waiting && !this.#lazy()) {
+      BookCover.#observer?.unobserve(this);
+      this.#waiting = false;
+    }
+    // A cover still waiting: its name and shape follow the attributes.
+    if (this.#waiting) {
+      this.#hold();
+      return;
+    }
+    // (Several attributes set at once draw once; an element upgraded on the page draws once, when
+    // it connects.)
+    if (!this.#ready || this.#queued || !this.isConnected) return;
+    this.#queued = true;
+    queueMicrotask(() => {
+      this.#queued = false;
+      this.#render();
+    });
+  }
+
+  /** The cover's options, read from the attributes as the HTTP API reads a link. */
+  options() {
+    const q = new URLSearchParams();
+    for (const [attribute, key] of Object.entries(ATTRIBUTES)) {
+      const value = this.getAttribute(attribute);
+      if (value != null) q.set(key, value);
+    }
+    // (Present is on, as a boolean attribute; 0 and false, as links write them, are off.)
+    const texture = this.getAttribute('texture');
+    if (texture !== null) q.set('texture', LINK.texture(texture) === false ? '0' : '1');
+    return optionsFromLink(q);
+  }
+
+  #render() {
+    try {
+      const options = this.options();
+      // (Moved or reconnected with the same attributes: the cover stands.)
+      const key = JSON.stringify(options);
+      if (this.cover && key === this.#drawn) return;
+      this.#drawn = key;
+      this.cover = createCover(options);
+      this.#img.src = svgToDataUrl(this.cover.svg);
+      this.#img.alt = altFor(this.cover.title, this.cover.author);
+      // (Its shape held while the image decodes, so nothing below it moves.)
+      this.#img.style.aspectRatio = `${this.cover.width} / ${this.cover.height}`;
+      this.dispatchEvent(new CustomEvent('cover', { detail: this.cover }));
+    } catch (err) {
+      this.cover = null;
+      this.#drawn = '';
+      this.#img.removeAttribute('src');
+      this.#img.alt = '';
+      this.dispatchEvent(new CustomEvent('cover-error', { detail: err }));
+    }
+  }
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('book-cover')) {
+  customElements.define('book-cover', BookCover);
+}

package/src/index.d.ts

@@ -175,7 +175,7 @@ export interface Cover {
   body: string;
   /** The style that was used. */
   style: string;
-  /** The palette that was used (`'custom'` for a custom palette). */
+  /** The palette that was used: its id, or for a custom palette its own `id` (`'custom'` if it has none). */
   palette: string;
   /** The palette's colours, as the cover used them. */
   colors: { bg: string; ink: string; accents: string[]; dark: boolean };
@@ -228,7 +228,10 @@ export interface ResolvedPalette extends Palette {
 export interface StyleContext {
   readonly title: string;
   readonly author: string;
-  /** Empty when there is no subtitle. A credit, if any, follows on a line of its own (after "\n"). */
+  /**
+   * The subtitle, then the credit ("Translated by …"), if any, on a line of its own (after "\n"):
+   * the credit alone when there is no subtitle, and empty when there is neither.
+   */
   readonly subtitle: string;
   /** The series line, or empty. `titleBlock` sets it above the title. */
   readonly series: string;

package/src/index.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./index.d.ts" */
 // book-cover-generator — generate SVG book covers from a title and an author.
 //
 //   import { generateCover } from 'book-cover-generator';
@@ -31,7 +32,7 @@ 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.7.0';
+export const version = '1.9.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 });
@@ -399,13 +400,15 @@ function dimension(value, fallback, name) {
   return Math.round(v);
 }
 
+/** @typedef {import('./text.js').FontSpec} FontSpec */
+
 /** 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, fontId: string, titleCase: 'upper' | 'normal' | null }}
+ * @returns {{ font: FontSpec | null, fontId: string, titleCase: 'upper' | 'normal' | null }}
  */
 function typeOptions(options) {
   const font = /** @type {unknown} */ (options.font);
@@ -511,9 +514,10 @@ export function createCover(options = {}) {
         H,
         !!options.texture,
         ...(Object.keys(pins).length ? [pins] : []),
-        ...(titleType.font || titleType.titleCase ? [titleType.fontId, titleType.titleCase ?? ''] : []),
-        ...(series || credit ? [series, credit] : []),
-        ...(badge ? [badge] : []),
+        // (Each optional part named, so one can't pass for another: a series of "serif" isn't a font.)
+        ...(titleType.font || titleType.titleCase ? ['font', titleType.fontId, titleType.titleCase ?? ''] : []),
+        ...(series || credit ? ['series', series, credit] : []),
+        ...(badge ? ['badge', badge] : []),
       ]),
     ).toString(36);
   /** The variants the style chose (or was given). @type {Record<string, string>} */