book-cover-generator 1.7.0 → 1.8.0

package/README.md

@@ -5,9 +5,10 @@
 [![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)**
 
@@ -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. 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 { handlePayload } 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 {unknown} message */
+  const answer = (message) => {
+    if (message) process.stdout.write(`${JSON.stringify(message)}\n`);
+  };
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      answer({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+      return;
+    }
+    answer(handlePayload(message, { writeFile }));
+  });
+}
+
 if (preflight()) run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "book-cover-generator",
-  "version": "1.7.0",
+  "version": "1.8.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/element.d.ts

@@ -0,0 +1,21 @@
+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.
+ */
+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,134 @@
+// <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). 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}';
+/** 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'];
+
+  /** 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 = '';
+
+  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;
+    this.#render();
+  }
+
+  attributeChangedCallback() {
+    // (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 = this.cover.author
+        ? `Cover: ${this.cover.title.replace(/\n/g, ' ')} by ${this.cover.author}`
+        : `Cover: ${this.cover.title.replace(/\n/g, ' ')}`;
+      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.js

@@ -31,7 +31,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.8.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 });

package/src/link.js

@@ -3,7 +3,7 @@
 // design the app stored) and gives the field's value, or undefined for one it can't read: the app
 // drops it, the API says so. (Not part of the library's API.)
 
-import { styleIdFor, palettes, formats, sizeLimits } from './index.js';
+import { styleIdFor, palettes, formats, sizeLimits, version } from './index.js';
 import { LINE_BREAK, clipGraphemes } from './text.js';
 import {
   idFor,
@@ -14,6 +14,8 @@ import {
   CUSTOM_PALETTE,
   CUSTOM_SIZE,
   VARIANT,
+  customColors,
+  hex,
 } from './shared.js';
 
 /** Line breaks as spaces (a single-line field: the cover spaces them). @param {unknown} v */
@@ -78,9 +80,200 @@ export const LINK = {
   },
 };
 
+/**
+ * @typedef {object} Field
+ * @property {(v: unknown) => unknown} read  the value from a link or a stored design; undefined drops it
+ * @property {(v: any) => string} [write]    the value as a link writes it (default: as it is)
+ * @property {unknown} empty                 the value of a design that leaves it out (see complete())
+ * @property {boolean} [optional]            links may leave it out and still be whole designs
+ * @property {boolean} [omitEmpty]           links leave it out when it is empty
+ */
+
+/**
+ * Every field of a design, in the order links name them. A field added later is `optional`, so
+ * links made before it existed still open as whole designs (with its `empty` value).
+ * @type {Record<string, Field>}
+ */
+export const LINK_FIELDS = {
+  // (Each read by LINK, as the HTTP API reads links too: one link draws one design.)
+  // (Line breaks kept since 1.5.0: the cover breaks the title there.)
+  title: { read: LINK.title, empty: '' },
+  author: { read: LINK.author, empty: '' },
+  // (Optional since 1.2.0: older links left it out when empty.)
+  subtitle: { read: LINK.subtitle, empty: '', optional: true },
+  // (Since 1.5.0.)
+  series: { read: LINK.series, empty: '', optional: true, omitEmpty: true },
+  credit: { read: LINK.credit, empty: '', optional: true, omitEmpty: true },
+  // (Since 1.6.0.)
+  badge: { read: LINK.badge, empty: '', optional: true, omitEmpty: true },
+  style: { read: LINK.style, empty: '' },
+  // (Since 1.5.0.) Checked against the style when used (the app's pinsFor()).
+  variant: { read: LINK.variant, empty: '', optional: true, omitEmpty: true },
+  // (Since 1.5.0.)
+  font: { read: LINK.font, empty: '', optional: true, omitEmpty: true },
+  case: { read: LINK.case, empty: '', optional: true, omitEmpty: true },
+  palette: { read: LINK.palette, empty: 'auto' },
+  seed: { read: LINK.seed, empty: '' },
+  format: { read: LINK.format, empty: 'paperback' },
+  // On or off; any other value (texture=yes) is dropped like other unknown values.
+  texture: { read: LINK.texture, write: (v) => (v ? '1' : '0'), empty: false, optional: true },
+};
+
+/**
+ * A design's link (the part of an app link after #, the HTTP API's query): every field, even when
+ * empty or off, so a link is the whole design, never mistaken for a hand-edited partial one (which
+ * changes only the keys it names); last, the version that drew it (artwork can change between
+ * minor versions).
+ * @param {Record<string, unknown>} design
+ */
+export function writeLink(design) {
+  const q = new URLSearchParams();
+  for (const [key, field] of Object.entries(LINK_FIELDS)) {
+    if (field.omitEmpty && design[key] === field.empty) continue;
+    q.set(key, field.write?.(design[key]) ?? String(design[key]));
+  }
+  q.set('v', version);
+  return q;
+}
+
+/**
+ * Your own colours (background, text, one to three accents) as a link's palette: each as six hex
+ * digits (#abc is #aabbcc; an alpha is dropped).
+ * @param {readonly string[]} colors
+ */
+export const customPalette = (colors) => `custom-${colors.map((c) => sixDigits(c).slice(1)).join('-')}`;
+
+/**
+ * A colour as #rrggbb, lower-case: #abc as #aabbcc, and an alpha (#abcd, #aabbccdd) dropped. Any
+ * other value is left as it is, for the reader to refuse.
+ * @param {string} c
+ */
+export function sixDigits(c) {
+  const h = c.trim().replace(/^#/, '').toLowerCase();
+  if (!/^[0-9a-f]+$/.test(h)) return c;
+  if (h.length === 3 || h.length === 4) return `#${[...h.slice(0, 3)].map((x) => x + x).join('')}`;
+  if (h.length === 6 || h.length === 8) return `#${h.slice(0, 6)}`;
+  return c;
+}
+
+/** A design's pins as a link holds them (sorted by name, so the same pins make the same link). @param {Record<string, string>} pins */
+export const variantOf = (pins) =>
+  Object.keys(pins)
+    .sort()
+    .map((name) => `${name}.${pins[name]}`)
+    .join('-');
+
 /**
  * The value of each key in a query, the last when it is given more than once (as an app link's
  * reader, `Object.fromEntries`, takes it).
  * @param {URLSearchParams} q
  */
 export const lastValues = (q) => /** @type {Record<string, string>} */ (Object.fromEntries(q));
+
+/** A size in px, as the CLI reads one (the library checks its range), else an error naming the parameter. @param {string} key @param {string} raw */
+export function px(key, raw) {
+  const value = Number(raw);
+  if (!raw.trim() || !Number.isFinite(value)) throw new RangeError(`${key} must be a number, got "${raw}"`);
+  return value;
+}
+
+/**
+ * A cover's size from a format (a preset, or any WxH shape) and a width or height that scales it,
+ * as the HTTP API and the CLI read them; the format's own size with neither. The library checks
+ * the size it comes to.
+ * @param {string} format @param {number | undefined} width @param {number | undefined} height
+ * @returns {[number, number]}
+ */
+export function formatSize(format, width, height) {
+  const read = format.trim();
+  const size = Object.hasOwn(formats, read)
+    ? formats[/** @type {keyof typeof formats} */ (read)]
+    : CUSTOM_SIZE.exec(read)?.slice(1).map(Number);
+  if (!size) {
+    throw new RangeError(
+      `Unknown format "${format}". Use one of ${Object.keys(formats).join(', ')}, or a size such as 1600x2560`,
+    );
+  }
+  if (width !== undefined && height !== undefined) {
+    throw new RangeError('A format sets the shape: give it a width or a height, not both');
+  }
+  const [w, h] = size;
+  if (width !== undefined) return [width, Math.round((width * h) / w)];
+  if (height !== undefined) return [Math.round((height * w) / h), height];
+  return [w, h];
+}
+
+/**
+ * Cover options from a link's query (the HTTP API's). The app's link parameters are read as the
+ * app reads them, the last of a repeated one too, except that a value the app would drop is an
+ * error here. Also the library's option names (`titleCase`, `genre`, `lang`, `width`, `height`)
+ * and your own colours as `bg`, `ink` and `accent` (hex, the # optional, accents separated by
+ * commas).
+ * @param {URLSearchParams} q
+ * @returns {import('./index.js').CoverOptions}
+ */
+export function optionsFromLink(q) {
+  const v = lastValues(q);
+  /** A parameter's value, if it has one. @param {string} key */
+  const given = (key) => (v[key] != null && v[key] !== '' ? v[key] : undefined);
+  /** @type {Record<string, unknown>} */
+  const o = {};
+  for (const key of /** @type {const} */ (['title', 'author', 'subtitle', 'series', 'credit', 'badge', 'seed'])) {
+    const value = given(key) === undefined ? undefined : LINK[key](v[key]);
+    if (value) o[key] = value;
+  }
+  // Styles, fonts and palettes the reader doesn't know go to the library as typed: it picks for
+  // 'random', and says what's wrong with the others.
+  for (const key of /** @type {const} */ (['style', 'font'])) {
+    const raw = given(key);
+    if (raw !== undefined) o[key] = LINK[key](raw) ?? raw;
+  }
+  for (const key of ['genre', 'lang']) if (given(key) !== undefined) o[key] = given(key);
+  const palette = given('palette');
+  if (palette !== undefined) {
+    const read = LINK.palette(palette);
+    const colors = read ? customColors(read) : null;
+    if (colors) o.palette = { bg: colors[0], ink: colors[1], accents: colors.slice(2) };
+    else if (read !== 'auto') o.palette = read ?? palette;
+  }
+  const caseKey = given('case') !== undefined ? 'case' : 'titleCase';
+  const titleCase = given(caseKey);
+  if (titleCase !== undefined) {
+    o.titleCase = LINK.case(titleCase);
+    if (!o.titleCase) throw new RangeError(`${caseKey} is upper or normal, got "${titleCase}"`);
+  }
+  const texture = given('texture');
+  if (texture !== undefined) {
+    o.texture = LINK.texture(texture);
+    if (o.texture === undefined) throw new RangeError('texture is 1 (on) or 0 (off)');
+  }
+  const variant = given('variant');
+  if (variant !== undefined) {
+    const pairs = LINK.variant(variant);
+    if (!pairs) {
+      throw new RangeError('variant is name.value pairs joined by "-", such as scene.forest or field.pale-emblem.sun');
+    }
+    o.variants = Object.fromEntries(pairs.split('-').map((pair) => pair.split('.')));
+  }
+  const width = given('width') === undefined ? undefined : px('width', /** @type {string} */ (given('width')));
+  const height = given('height') === undefined ? undefined : px('height', /** @type {string} */ (given('height')));
+  const format = given('format');
+  if (format !== undefined) [o.width, o.height] = formatSize(format, width, height);
+  else {
+    if (width !== undefined) o.width = width;
+    if (height !== undefined) o.height = height;
+  }
+  const [bg, ink, accent] = [given('bg'), given('ink'), given('accent')];
+  if (bg || ink || accent) {
+    if (!bg || !ink || !accent) throw new RangeError('Your own colours need bg, ink and accent');
+    o.palette = {
+      bg: hex(bg),
+      ink: hex(ink),
+      accents: accent
+        .split(',')
+        .filter((c) => c.trim())
+        .map(hex),
+    };
+  }
+  return /** @type {import('./index.js').CoverOptions} */ (o);
+}

package/src/mcp.js

@@ -0,0 +1,378 @@
+// A Model Context Protocol server, so AI assistants can make covers: `book-cover --mcp` speaks it
+// over stdio, and the site's Worker over HTTP at /mcp. This module only answers messages; the
+// transports are theirs. (Not part of the library's API.)
+
+import { createCover, createMockup, listStyles, palettes, genres, formats, mockupKinds, version } from './index.js';
+import { optionsFromLink, writeLink, customPalette, variantOf, sixDigits } from './link.js';
+import { idFor } from './shared.js';
+
+/** The site that draws covers from links, and edits them. */
+export const SITE = 'https://covers.otsirh.dev';
+/** Protocol versions this server speaks, newest first. */
+const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+const INSTRUCTIONS =
+  'Makes book covers. create_cover draws one from a title (and an author, a style or a genre, a palette…) and ' +
+  'answers with a link to the image (an SVG) and a link that opens it in the editor at covers.otsirh.dev, where ' +
+  'it can be changed and downloaded as PNG or JPEG. Give the same seed to keep a cover, another for a variation. ' +
+  'list_styles and list_palettes show the choices; create_mockup shows a cover as a 3D book, on an e-reader or ' +
+  'on a social card.';
+
+/**
+ * @typedef {{ base?: string, writeFile?: (path: string, data: string) => string }} Context
+ * `base`: the site links point to; `writeFile`: where a local server can save a file (it answers
+ * the path written), else undefined.
+ */
+
+/** @param {Context} ctx */
+function designProperties(ctx) {
+  /** @type {Record<string, object>} */
+  const properties = {
+    title: { type: 'string', description: "The book's title. A line break (\\n) breaks its line on the cover." },
+    author: { type: 'string', description: "The author's name." },
+    subtitle: { type: 'string', description: 'A subtitle or tagline.' },
+    series: { type: 'string', description: 'A series line above the title, such as "Book Two of the Ember Cycle".' },
+    credit: { type: 'string', description: 'A credit under the subtitle, such as "Translated by Ann Lee".' },
+    badge: { type: 'string', description: 'A seal in a corner, such as "Winner of the Hugo Award".' },
+    style: {
+      type: 'string',
+      description: 'A style, by id or name (see list_styles), or "random" (the default: the seed picks one).',
+    },
+    genre: {
+      type: 'string',
+      description: `With no style, pick one that suits a genre: ${genres.map((g) => `${g.id} (${g.name})`).join(', ')}.`,
+    },
+    palette: {
+      type: 'string',
+      description: 'A palette, by id or name (see list_palettes), or "auto" (the default: the seed picks one).',
+    },
+    colors: {
+      type: 'object',
+      description: 'Your own colours instead of a palette, as hex.',
+      properties: {
+        bg: { type: 'string', description: 'Background, such as #0b132b.' },
+        ink: { type: 'string', description: 'Text.' },
+        accents: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 3 },
+      },
+      required: ['bg', 'ink', 'accents'],
+    },
+    seed: {
+      type: ['string', 'number'],
+      description: 'Every random choice comes from it: the same seed draws the same cover; another, a variation.',
+    },
+    format: {
+      type: 'string',
+      description: `${Object.keys(formats).join(', ')}, or a size in px such as 1600x2560 (Kindle). Default: paperback (2:3).`,
+    },
+    font: {
+      type: 'string',
+      description:
+        "The title's font instead of the style's: serif, didone, garamond, sans, geometric, humanist, condensed, display or mono.",
+    },
+    case: { type: 'string', enum: ['upper', 'normal'], description: 'The title in capitals, or as typed.' },
+    texture: { type: 'boolean', description: 'A fine film grain.' },
+    variants: {
+      type: 'object',
+      additionalProperties: { type: 'string' },
+      description: 'Choices a style lets you pin, as list_styles shows them, such as { "scene": "forest" }.',
+    },
+    svg: { type: 'boolean', description: 'Also answer with the SVG markup (large).' },
+  };
+  if (ctx.writeFile) properties.output = { type: 'string', description: 'An absolute path to save the SVG to.' };
+  return properties;
+}
+
+/** @param {Context} ctx */
+function tools(ctx) {
+  const design = designProperties(ctx);
+  return [
+    {
+      name: 'create_cover',
+      title: 'Create a book cover',
+      description:
+        'Draw a book cover. Answers with links to the image and to edit it in the app, and the style, palette and seed it used.',
+      inputSchema: { type: 'object', properties: design, required: ['title'] },
+      annotations: { readOnlyHint: !ctx.writeFile, openWorldHint: false },
+    },
+    {
+      name: 'create_mockup',
+      title: 'Create a mockup of a cover',
+      description:
+        'Draw a cover as a product shot (a 3D book, flat, on an e-reader) or on a social card with a line of text.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          ...design,
+          kind: { type: 'string', enum: [...mockupKinds], description: 'Default: book.' },
+          text: { type: 'string', description: 'The line on a card, square or story, such as "Out now".' },
+        },
+        required: ['title'],
+      },
+      annotations: { readOnlyHint: !ctx.writeFile, openWorldHint: false },
+    },
+    {
+      name: 'list_styles',
+      title: 'List the cover styles',
+      description: 'The styles, with their genres and the choices each lets you pin.',
+      inputSchema: {
+        type: 'object',
+        properties: { genre: { type: 'string', description: 'Only styles that suit this genre.' } },
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+      name: 'list_palettes',
+      title: 'List the colour palettes',
+      description: 'The palettes, light and dark, with their colours.',
+      inputSchema: { type: 'object', properties: {} },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  ];
+}
+
+/** Whether the arguments give a seed (else the cover's comes from its title). @param {Record<string, unknown>} args */
+const seedGiven = (args) => typeof args.seed === 'number' || (typeof args.seed === 'string' && args.seed.trim() !== '');
+
+/** A tool's arguments as a link's query, read as the HTTP API reads one. @param {Record<string, unknown>} args */
+function queryFrom(args) {
+  const q = new URLSearchParams();
+  if (seedGiven(args)) q.set('seed', String(args.seed).trim());
+  for (const key of [
+    'title',
+    'author',
+    'subtitle',
+    'series',
+    'credit',
+    'badge',
+    'style',
+    'genre',
+    'palette',
+    'format',
+    'font',
+    'case',
+  ]) {
+    const value = args[key];
+    if (value != null && value !== '') q.set(key, String(value));
+  }
+  if (typeof args.texture === 'boolean') q.set('texture', args.texture ? '1' : '0');
+  if (args.variants && typeof args.variants === 'object') {
+    // (An empty pin leaves the choice to the seed, as the library takes it.)
+    const pairs = Object.entries(args.variants)
+      .filter(([, value]) => value != null && value !== '')
+      .map(([name, value]) => `${name}.${String(value)}`);
+    if (pairs.length) q.set('variant', pairs.join('-'));
+  }
+  const colors = /** @type {{ bg?: unknown, ink?: unknown, accents?: unknown } | undefined} */ (args.colors);
+  if (colors && typeof colors === 'object') {
+    if (!Array.isArray(colors.accents) || colors.accents.length < 1 || colors.accents.length > 3) {
+      throw new RangeError('colors.accents is a list of one to three colours');
+    }
+    // (Each as #rrggbb, as the link of the cover will write it: the two draw the same bytes.)
+    q.set('bg', sixDigits(String(colors.bg ?? '')));
+    q.set('ink', sixDigits(String(colors.ink ?? '')));
+    q.set('accent', colors.accents.map((c) => sixDigits(String(c))).join(','));
+  }
+  return q;
+}
+
+/**
+ * The link of the cover drawn, written as the app writes its links from the options it was drawn
+ * with (not the tool's arguments), with what the seed chose written out: the app and the API draw
+ * that cover.
+ * @param {import('./index.js').CoverOptions} options @param {ReturnType<typeof createCover>} cover
+ */
+function linkOf(options, cover) {
+  /** @type {Record<string, string>} */
+  const pinned = {};
+  for (const name of Object.keys(options.variants ?? {}).map((n) => n.toLowerCase())) {
+    if (cover.variants[name]) pinned[name] = cover.variants[name];
+  }
+  const own = options.palette && typeof options.palette === 'object' ? options.palette : null;
+  const preset = Object.entries(formats).find(([, [w, h]]) => w === cover.width && h === cover.height);
+  return writeLink({
+    title: cover.title,
+    author: cover.author,
+    subtitle: options.subtitle ?? '',
+    series: options.series ?? '',
+    credit: options.credit ?? '',
+    badge: options.badge ?? '',
+    style: cover.style,
+    variant: variantOf(pinned),
+    font: options.font ?? '',
+    case: options.titleCase ?? '',
+    palette: own ? customPalette([own.bg, own.ink, ...(own.accents ?? [])]) : cover.palette,
+    // (A seed from the title stays one: the app reads an empty seed so.)
+    seed: options.seed != null ? cover.seed : '',
+    format: preset ? preset[0] : `${cover.width}x${cover.height}`,
+    texture: options.texture === true,
+  });
+}
+
+/** Text for a tool's answer. @param {string} body */
+const text = (body) => ({ type: 'text', text: body });
+
+/**
+ * Run a tool: its answer (an error is an answer with isError, so the assistant can fix the call).
+ * @param {string} tool @param {Record<string, unknown>} args @param {Context} ctx
+ */
+function callTool(tool, args, ctx) {
+  const base = ctx.base ?? SITE;
+  try {
+    if (tool === 'list_styles') {
+      const genre = typeof args.genre === 'string' && args.genre ? args.genre : null;
+      const genreId = genre ? idFor(genre, genres) : null;
+      if (genre && !genreId)
+        throw new RangeError(`Unknown genre "${genre}". Available: ${genres.map((g) => g.id).join(', ')}`);
+      const styles = listStyles().filter((s) => !genreId || s.genres.includes(genreId));
+      const lines = styles.map((s) => {
+        const pins = s.variants.map((v) => `${v.name}: ${v.values.map((x) => x.value).join(', ')}`).join('; ');
+        return `- ${s.id} (${s.name}, ${s.group}): ${s.description} Genres: ${s.genres.join(', ') || 'none'}.${pins ? ` Pins: ${pins}.` : ''}`;
+      });
+      return {
+        content: [text(`${styles.length} styles:\n${lines.join('\n')}`)],
+        structuredContent: {
+          styles: styles.map(({ id, name, group, description, genres: suits, variants }) => ({
+            id,
+            name,
+            group,
+            description,
+            genres: suits,
+            variants: variants.map((v) => ({ name: v.name, values: v.values.map((x) => x.value) })),
+          })),
+        },
+      };
+    }
+    if (tool === 'list_palettes') {
+      const lines = palettes.map(
+        (p) =>
+          `- ${p.id} (${p.name}, ${p.dark ? 'dark' : 'light'}): ${p.bg} background, ${p.ink} text, ${p.accents.join(' ')}`,
+      );
+      return {
+        content: [text(`${palettes.length} palettes:\n${lines.join('\n')}`)],
+        structuredContent: {
+          palettes: palettes.map(({ id, name, bg, ink, accents, dark }) => ({
+            id,
+            name,
+            bg,
+            ink,
+            accents,
+            dark: !!dark,
+          })),
+        },
+      };
+    }
+    if (tool !== 'create_cover' && tool !== 'create_mockup') return null;
+    if (typeof args.title !== 'string' || !args.title.trim()) throw new TypeError('A cover needs a title');
+    const options = optionsFromLink(queryFrom(args));
+    const cover = createCover(options);
+    const link = linkOf(options, cover);
+    let [width, height] = [cover.width, cover.height];
+    const edit = `${base}/#${link}`;
+    let image = `${base}/api/cover.svg?${link}`;
+    let svg = cover.svg;
+    let what = `"${cover.title.replace(/\n/g, ' ')}"${cover.author ? ` by ${cover.author}` : ''}`;
+    if (tool === 'create_mockup') {
+      const kind = typeof args.kind === 'string' && args.kind ? args.kind : 'book';
+      const line = typeof args.text === 'string' ? args.text : '';
+      const mockup = createMockup(cover, { kind: /** @type {import('./index.js').MockupKind} */ (kind), text: line });
+      ({ svg, width, height } = mockup);
+      const extra = new URLSearchParams({ kind, ...(line ? { text: line } : {}) });
+      image = `${base}/api/mockup.svg?${link}&${extra}`;
+      what = `${/^[aeiou]/.test(kind) ? 'an' : 'a'} ${kind} mockup of ${what}`;
+    }
+    const saved =
+      typeof args.output === 'string' && args.output && ctx.writeFile ? ctx.writeFile(args.output, svg) : null;
+    const styleName = listStyles().find((s) => s.id === cover.style)?.name ?? cover.style;
+    const paletteName = palettes.find((p) => p.id === cover.palette)?.name ?? 'your own colours';
+    const seed = options.seed != null ? `seed ${cover.seed}` : 'seed from the title';
+    const content = [
+      text(
+        `Drew ${what} in the ${styleName} style (${cover.style}), palette ${paletteName}, ${seed} (${width} × ${height} px).\n` +
+          `Image (SVG): ${image}\nEdit, or download as PNG or JPEG: ${edit}` +
+          (saved ? `\nSaved to ${saved}` : ''),
+      ),
+    ];
+    if (args.svg === true) content.push(text(svg));
+    return {
+      content,
+      structuredContent: {
+        style: cover.style,
+        palette: cover.palette,
+        // (Null when it comes from the title: give the title again to keep the cover.)
+        seed: options.seed != null ? cover.seed : null,
+        // (The image's size: a mockup's, for a mockup.)
+        width,
+        height,
+        variants: cover.variants,
+        imageUrl: image,
+        editUrl: edit,
+        ...(saved ? { file: saved } : {}),
+      },
+    };
+  } catch (err) {
+    return { content: [text(err instanceof Error ? err.message : String(err))], isError: true };
+  }
+}
+
+/** The most messages a batch may hold (a batch is one request: each message draws a cover). */
+export const MAX_BATCH = 20;
+
+/**
+ * Answer what a client sent: one message, or a batch (older protocol versions), as each
+ * transport receives them. Null when nothing needs an answer (notifications only).
+ * @param {unknown} payload @param {Context} [ctx]
+ */
+export function handlePayload(payload, ctx = {}) {
+  if (!Array.isArray(payload)) return handleMessage(payload, ctx);
+  if (!payload.length) return failure(null, -32600, 'An empty batch');
+  if (payload.length > MAX_BATCH) return failure(null, -32600, `A batch holds at most ${MAX_BATCH} messages`);
+  const answers = payload.map((m) => handleMessage(m, ctx)).filter(Boolean);
+  return answers.length ? answers : null;
+}
+
+/** @param {unknown} id @param {unknown} result */
+const ok = (id, result) => ({ jsonrpc: '2.0', id, result });
+/** @param {unknown} id @param {number} code @param {string} message */
+const failure = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+/**
+ * Answer one JSON-RPC message: a response, or null for a notification (which has none).
+ * @param {unknown} message @param {Context} [ctx]
+ */
+export function handleMessage(message, ctx = {}) {
+  if (!message || typeof message !== 'object' || Array.isArray(message))
+    return failure(null, -32600, 'Invalid request');
+  const { jsonrpc, id, method, params } = /** @type {Record<string, any>} */ (message);
+  if (jsonrpc !== '2.0' || typeof method !== 'string') {
+    return 'id' in message ? failure(id ?? null, -32600, 'Invalid request') : null;
+  }
+  // A notification (initialized, cancelled…) has no answer.
+  if (!('id' in message)) return null;
+  switch (method) {
+    case 'initialize': {
+      const asked = params?.protocolVersion;
+      return ok(id, {
+        protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'book-cover-generator', title: 'Book Cover Generator', version },
+        instructions: INSTRUCTIONS,
+      });
+    }
+    case 'ping':
+      return ok(id, {});
+    case 'tools/list':
+      return ok(id, { tools: tools(ctx) });
+    case 'tools/call': {
+      const name = params?.name;
+      // (Arguments may be left out, but not given as something other than an object.)
+      const args = params?.arguments === undefined ? {} : params.arguments;
+      if (typeof name !== 'string' || typeof args !== 'object' || args === null) {
+        return failure(id, -32602, 'tools/call needs a tool name and its arguments');
+      }
+      const answer = callTool(name, args, ctx);
+      return answer ? ok(id, answer) : failure(id, -32602, `Unknown tool "${name}"`);
+    }
+    default:
+      return failure(id, -32601, `Method not found: ${method}`);
+  }
+}