book-cover-generator 1.8.0 → 1.9.1

package/README.md

@@ -10,7 +10,7 @@
 
 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)
 
@@ -24,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.
@@ -93,7 +93,7 @@ One script, then a cover wherever you write the element:
 <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'`.
+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)
 

package/bin/book-cover.js

@@ -6,7 +6,7 @@ import { parseArgs } from 'node:util';
 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';
+import { answerPayload } from '../src/mcp.js';
 
 const HELP = `Usage: book-cover "<title>" ["<author>"] [options]
 
@@ -349,9 +349,9 @@ function serveMcp() {
     writeFileSync(file, data);
     return file;
   };
-  /** @param {unknown} message */
-  const answer = (message) => {
-    if (message) process.stdout.write(`${JSON.stringify(message)}\n`);
+  /** @param {string | null} text */
+  const send = (text) => {
+    if (text) process.stdout.write(`${text}\n`);
   };
   lines.on('line', (line) => {
     if (!line.trim()) return;
@@ -359,10 +359,10 @@ function serveMcp() {
     try {
       message = JSON.parse(line);
     } catch {
-      answer({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+      send(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }));
       return;
     }
-    answer(handlePayload(message, { writeFile }));
+    send(answerPayload(message, { writeFile }));
   });
 }
 

package/package.json

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

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-types.d.ts

@@ -0,0 +1,19 @@
+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.
+ *
+ * (The class alone: Deno and JSR use these types, as a package there may not declare global ones.
+ * element.d.ts adds the tag to `document.createElement`'s types for TypeScript from npm.)
+ */
+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;
+}

package/src/element.d.ts

@@ -1,18 +1,8 @@
-import type { CoverOptions, createCover } from './index.js';
+// The types of book-cover-generator/element from npm: the class, and the tag in
+// `document.createElement('book-cover')`'s types.
+import { BookCover } from './element-types.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;
-}
+export { BookCover };
 
 declare global {
   interface HTMLElementTagNameMap {

package/src/element.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./element-types.d.ts" */
 // <book-cover>: a cover on any page, from its attributes.
 //
 //   <script type="module" src="https://covers.otsirh.dev/src/element.js"></script>
@@ -6,7 +7,8 @@
 // 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
+// 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).
 
@@ -36,6 +38,15 @@ const ATTRIBUTES = /** @type {const} */ ({
 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
@@ -50,7 +61,7 @@ const sheet =
 const Base = /** @type {typeof HTMLElement} */ (typeof HTMLElement === 'undefined' ? class {} : HTMLElement);
 
 export class BookCover extends Base {
-  static observedAttributes = [...Object.keys(ATTRIBUTES), 'texture'];
+  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;
@@ -61,6 +72,24 @@ export class BookCover extends Base {
   #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();
@@ -79,10 +108,48 @@ export class BookCover extends Base {
 
   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();
   }
 
-  attributeChangedCallback() {
+  /** 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;
@@ -115,9 +182,9 @@ export class BookCover extends Base {
       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.#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;

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.8.0';
+export const version = '1.9.1';
 
 /** 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>} */

package/src/mcp.js

@@ -185,7 +185,7 @@ 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];
+    if (Object.hasOwn(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);
@@ -330,8 +330,24 @@ export function handlePayload(payload, ctx = {}) {
   return answers.length ? answers : null;
 }
 
+/**
+ * The answer to what a client sent as the JSON text to send back, or null for none. Whatever goes
+ * wrong while answering is an internal error, not a crash of the server.
+ * @param {unknown} payload @param {Context} [ctx]
+ */
+export function answerPayload(payload, ctx = {}) {
+  try {
+    const answer = handlePayload(payload, ctx);
+    return answer ? JSON.stringify(answer) : null;
+  } catch {
+    return JSON.stringify(failure(null, -32603, 'Internal error'));
+  }
+}
+
 /** @param {unknown} id @param {unknown} result */
 const ok = (id, result) => ({ jsonrpc: '2.0', id, result });
+/** An id as JSON-RPC allows it, so it can be sent back: a string, a number or null. @param {unknown} id */
+const validId = (id) => id === null || typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id));
 /** @param {unknown} id @param {number} code @param {string} message */
 const failure = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
 
@@ -343,11 +359,17 @@ 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;
+  const hasId = 'id' in message;
+  // A response (this server sends no requests, so it answers none): nothing to say.
+  if (jsonrpc === '2.0' && !('method' in message) && hasId && ('result' in message || 'error' in message)) {
+    return null;
+  }
+  // Not a request: an error, with its id if it is one JSON-RPC allows (else null, as for none).
+  if (jsonrpc !== '2.0' || typeof method !== 'string' || (hasId && !validId(id))) {
+    return failure(hasId && validId(id) ? id : null, -32600, 'Invalid request');
   }
   // A notification (initialized, cancelled…) has no answer.
-  if (!('id' in message)) return null;
+  if (!hasId) return null;
   switch (method) {
     case 'initialize': {
       const asked = params?.protocolVersion;

package/src/mockups.js

@@ -10,9 +10,19 @@ export const mockupKinds = Object.freeze(['flat', 'book', 'ereader', 'card', 'sq
 /** The neutral backdrop of the product shots. */
 const STUDIO = '#ecebe7';
 
+/**
+ * The cover's markup with its ids made a mockup's own (the mockup's tag before the cover's `bc…-`
+ * prefix), so the cover and its mockups, or two mockups of it, can share a page.
+ * @param {string} body @param {string} tag
+ */
+const ownIds = (body, tag) => {
+  const uid = /\bid="(bc[0-9a-z]+)-/.exec(body)?.[1];
+  return uid ? body.replace(new RegExp(`(id="|url\\(#|href="#)${uid}-`, 'g'), `$1${tag}-${uid}-`) : body;
+};
+
 /**
  * The cover nested at a place and size.
- * @param {import('./index.js').Cover} cover @param {number} x @param {number} y @param {number} w @param {number} h
+ * @param {{ width: number, height: number, body: string }} cover @param {number} x @param {number} y @param {number} w @param {number} h
  */
 const nest = (cover, x, y, w, h) =>
   `<svg x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" viewBox="0 0 ${cover.width} ${cover.height}" preserveAspectRatio="none" overflow="hidden">${cover.body}</svg>`;
@@ -53,6 +63,7 @@ export function createMockup(cover, { kind = 'book', background, text = '' } = {
   // Ids unique to this cover and kind of mockup, so several can share a page.
   const tag = `mk${hashString(cover.svg).toString(36)}-${kind}`;
   const id = (/** @type {string} */ name) => `${tag}-${name}`;
+  const nested = { width: cover.width, height: cover.height, body: ownIds(cover.body, tag) };
   const { width: CW, height: CH, colors } = cover;
   // (Cut between whole characters: an emoji or accented letter is never split.)
   const words = clipGraphemes(String(text).replace(/\s+/g, ' ').trim(), 80).trim();
@@ -79,7 +90,7 @@ export function createMockup(cover, { kind = 'book', background, text = '' } = {
       H,
       `<defs>${shadow(id('shadow'), 14 * u, 10 * u, 0.32)}</defs>` +
         `<rect width="${n(W)}" height="${n(H)}" fill="${background ?? STUDIO}"/>` +
-        `<g filter="url(#${id('shadow')})">${nest(cover, pad, pad, CW, CH)}</g>`,
+        `<g filter="url(#${id('shadow')})">${nest(nested, pad, pad, CW, CH)}</g>`,
     );
   }
 
@@ -112,7 +123,7 @@ export function createMockup(cover, { kind = 'book', background, text = '' } = {
         `<ellipse cx="${n(x0 + (CW * turn) / 2)}" cy="${n(y0 + CH - CW * rise * 0.3)}" rx="${n((CW * turn) / 2 + spine)}" ry="${n(CW * 0.035)}" fill="#000" opacity="0.28" filter="url(#${id('soft')})"/>` +
         `<polygon points="${n(x0 - spine)},${n(y0 + sag)} ${n(x0)},${n(y0)} ${n(x0)},${n(y0 + CH)} ${n(x0 - spine)},${n(y0 + CH - sag)}" fill="${spineFill}"/>` +
         `<polygon points="${n(x0 - spine)},${n(y0 + sag)} ${n(x0)},${n(y0)} ${n(x0)},${n(y0 + CH)} ${n(x0 - spine)},${n(y0 + CH - sag)}" fill="url(#${id('spine')})"/>` +
-        `<g transform="matrix(${turn} ${-rise} 0 1 ${n(x0)} ${n(y0)})">${nest(cover, 0, 0, CW, CH)}` +
+        `<g transform="matrix(${turn} ${-rise} 0 1 ${n(x0)} ${n(y0)})">${nest(nested, 0, 0, CW, CH)}` +
         `<rect width="${CW}" height="${CH}" fill="url(#${id('gloss')})"/></g>`,
     );
   }
@@ -134,7 +145,7 @@ export function createMockup(cover, { kind = 'book', background, text = '' } = {
         `<rect width="${n(W)}" height="${n(H)}" fill="${background ?? STUDIO}"/>` +
         `<g filter="url(#${id('shadow')})"><rect x="${n(pad)}" y="${n(pad)}" width="${n(DW)}" height="${n(DH)}" rx="${n(CW * 0.06)}" fill="#1c1c1e"/></g>` +
         `<rect x="${n(pad + 2 * u)}" y="${n(pad + 2 * u)}" width="${n(DW - 4 * u)}" height="${n(DH - 4 * u)}" rx="${n(CW * 0.055)}" fill="none" stroke="#3a3a3c" stroke-width="${n(1.5 * u)}"/>` +
-        nest(cover, pad + side, pad + top, CW, CH) +
+        nest(nested, pad + side, pad + top, CW, CH) +
         `<rect x="${n(pad + DW / 2 - CW * 0.08)}" y="${n(pad + DH - bottom / 2 - 2 * u)}" width="${n(CW * 0.16)}" height="${n(4 * u)}" rx="${n(2 * u)}" fill="#3a3a3c"/>`,
     );
   }
@@ -163,7 +174,7 @@ export function createMockup(cover, { kind = 'book', background, text = '' } = {
   let s =
     `<defs>${shadow(id('shadow'), 18 * u, 14 * u, 0.4)}</defs>` +
     `<rect width="${W}" height="${H}" fill="${bg}"/>` +
-    `<g filter="url(#${id('shadow')})">${nest(cover, cx, cy, cw, ch)}</g>`;
+    `<g filter="url(#${id('shadow')})">${nest(nested, cx, cy, cw, ch)}</g>`;
   // The words: beside the cover on a card, under it otherwise.
   const box =
     kind === 'card'

package/src/palettes.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./palettes.d.ts" */
 // Curated palettes. Every palette has a background, an ink colour with strong
 // contrast against it, and three accents. `dark` marks dark backgrounds.
 

package/src/styles/util.js

@@ -1,7 +1,10 @@
+/* @ts-self-types="./util.d.ts" */
 import { n, circle, contrast, readable, clamp, mix, inkCandidates, hexToRgb } from '../core.js';
 import { titleBlock } from '../type.js';
 import { graphemes } from '../text.js';
 
+/** @typedef {import('../type.js').TitleBlock} TitleBlock */
+
 /**
  * The title's characters, upper-cased, from the first that isn't punctuation or a
  * space: an initial skips opening quotes, brackets, "¿" and the like (but keeps
@@ -70,7 +73,7 @@ export function tintText(base, toward, k, bg) {
  * @param {readonly V[]} candidates  layout values, from the most to the least room for the art
  * @param {(value: V) => import('../type.js').TitleBlockOptions} optionsFor
  * @param {number} [minSize]  fraction of the short side
- * @returns {{ block: import('../type.js').TitleBlock, value: V }}
+ * @returns {{ block: TitleBlock, value: V }}
  */
 export function fitTitleWith(c, candidates, optionsFor, minSize = 0.06) {
   let block = titleBlock(c, optionsFor(candidates[0]));

package/src/text.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./text.d.ts" */
 // Text measurement, fitting (wrap + shrink-to-fit) and rendering.
 //
 // Only system font stacks are used so that covers render identically when the
@@ -74,6 +75,8 @@ export const FONTS = {
   },
 };
 
+/** @typedef {import('./text.js').FontSpec} FontSpec */
+
 /* ------------------------------------------------------------- measurement */
 
 /** @type {CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null | undefined} */
@@ -875,7 +878,7 @@ export function fitText(text, opts) {
 /**
  * Attributes shared by every line of a text block, for its wrapping `<g>`.
  * Colours and font names are escaped; `attrs` is raw SVG.
- * @param {{ font: import('./text.js').FontSpec, fill: string, size?: number, weight?: number, italic?: boolean, letterSpacing?: number, anchor?: 'start' | 'middle' | 'end', opacity?: number, attrs?: string }} o
+ * @param {{ font: FontSpec, fill: string, size?: number, weight?: number, italic?: boolean, letterSpacing?: number, anchor?: 'start' | 'middle' | 'end', opacity?: number, attrs?: string }} o
  */
 export function textGroupAttrs({ font, fill, size, weight, italic, letterSpacing, anchor = 'start', opacity, attrs }) {
   let a = `font-family="${escapeXml(font.family)}"`;

package/src/type.d.ts

@@ -38,7 +38,10 @@ export interface TitleBlockOptions {
   letterSpacing?: number;
   lineHeight?: number;
   maxLines?: number;
-  /** Set a leading "The" / "A" / "An" as a small line above the title. Default `true`. */
+  /**
+   * Set a leading article of three letters or more ("The", "Les", "Der") as a small line above the
+   * title; a shorter one ("A", "An", "La") stays with the title. Default `true`.
+   */
   lead?: boolean;
   /** Try a justified stack (each line full width) before regular wrapping. */
   stack?: boolean;

package/src/type.js

@@ -1,3 +1,4 @@
+/* @ts-self-types="./type.d.ts" */
 // Shared cover typography: title blocks and author lines.
 //
 // A title block is an optional small leading article ("THE"), the title itself