book-cover-generator 0.0.0-stage → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 otsirh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,275 @@
-# Temporary Holding Version
+# Book Cover Generator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/otsirh/book-cover-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/otsirh/book-cover-generator/actions/workflows/ci.yml)
+[![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)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Generate book covers from a **title** and an **author**. 34 styles, 28 palettes or your own colours, a seeded randomizer, any size, and export to **SVG, PNG, JPEG or WebP**. The library has no dependencies and ships TypeScript types. It's written as plain ES modules, so it runs in the browser and in Node.
+
+**[▶ Open the generator](https://covers.otsirh.dev)**
+
+![Sample covers](docs/preview.png)
+
+## Features
+
+- **34 styles in six families.**
+  - Typographic: Big Type, Minimal, Big Letter, Swiss.
+  - Genre: Thriller, Botanical, Noir, Blueprint.
+  - Vintage: Art Deco, Classic Paperback, Engraved, Sunburst, Typewriter.
+  - Scenic: Landscape, Retro Sun, Silhouette, Constellation, Orbit, Waves, Aurora, Bookshelf.
+  - 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.
+- **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.
+- **Export.** Download SVG, PNG, JPEG or WebP. PNG and JPEG files record 300 dpi, so print software sizes them right. Copy the image or the SVG, or share it from a phone.
+
+## The web app
+
+On [covers.otsirh.dev](https://covers.otsirh.dev) you type a title and author, then choose:
+
+- **a style**, from a rail that previews your book in all 34 styles;
+- **a palette**, from swatches that show the background, text colour and accents, or **Custom** for your own five colours (it starts from the palette on the cover and shows the text contrast);
+- **a variation**, the seed behind the artwork: the strip under the preview shows six others to click;
+- **a format**: paperback, eBook, square, or **Custom** for any size in pixels, typed in or picked from common sizes (Kindle, print trim sizes at 300 dpi, audiobook, social posts).
+
+**Store size** shrinks the preview to the size a store lists covers at, to check the title still reads. **Randomize** reshuffles everything, except what you've locked. Undo and redo step back and forth through your designs, and so do the browser's Back and Forward buttons. **Copy link** shares the exact design, because the URL holds every setting. The export panel tells you which size suits Kindle, print or audiobook covers.
+
+**Keep** saves a design to a tray under the preview, together with the cover as it was drawn, so a later version of the app can't change it. **Download all** saves every kept design as a PNG in one ZIP file. **Export** saves the kept designs to a file, and **Import** adds them in another browser.
+
+The app works offline once it has loaded.
+
+Keyboard shortcuts:
+
+- `R` randomizes.
+- `←` and `→` step through styles.
+- `[` and `]` step through palettes.
+- `Z` undoes and `Shift+Z` redoes.
+
+The single-key shortcuts can be turned off under the controls (for example with speech input).
+
+## Library usage
+
+### Browser (no install)
+
+```html
+<script type="module">
+  import { generateCover } from 'https://cdn.jsdelivr.net/gh/otsirh/book-cover-generator@1/src/index.js';
+
+  document.body.innerHTML = generateCover({
+    title: 'The Lighthouse Keeper',
+    author: 'Mara Ellison',
+    style: 'artdeco',
+    palette: 'midnight',
+  });
+</script>
+```
+
+`@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
+
+```sh
+npm install "github:otsirh/book-cover-generator#semver:^1"
+```
+
+```js
+import { createCover } from 'book-cover-generator';
+import { writeFileSync } from 'node:fs';
+
+const { svg, style, palette, seed } = createCover({
+  title: 'Neon Tide',
+  author: 'Kai Moreno',
+  style: 'random', // or a style id, see `styles`
+  seed: 42, // same seed, same cover
+  width: 1600,
+  height: 2560,
+});
+writeFileSync('cover.svg', svg);
+```
+
+### CLI
+
+```sh
+npx github:otsirh/book-cover-generator "The Lighthouse Keeper" "Mara Ellison" --style artdeco -o cover.svg
+npx github:otsirh/book-cover-generator --list   # all styles and palettes
+```
+
+```sh
+# your own colours (the # is optional), as an eBook 1600 px wide
+npx github:otsirh/book-cover-generator "Bright Machines" --bg 0b132b --ink f8f9fa --accent ff6b6b,4ecdc4 --format ebook --width 1600 -o cover.svg
+# any size, and the choices as JSON (with the SVG, when there is no -o)
+npx github:otsirh/book-cover-generator "Neon Tide" --size 1800x2700 --json
+# twelve variations to choose from: ideas/cover-1.svg … ideas/cover-12.svg (seeds 1 to 12)
+npx github:otsirh/book-cover-generator "Salt and Static" --count 12 -o ideas/cover.svg
+```
+
+Options: `-s/--style`, `-p/--palette`, `--bg`, `--ink`, `--accent`, `--subtitle`, `--texture`, `--seed`, `--format` (`paperback`, `ebook` or `square`), `--width`, `--height`, `--size`, `--lang`, `-o/--out`, `--count`, `--json`, `--list`, `--help`.
+
+## API
+
+### `generateCover(options) → string`
+
+Returns the SVG markup.
+
+### `createCover(options) → { svg, body, style, palette, seed, width, height, lang }`
+
+Same as `generateCover`, but also tells you which style and palette were chosen. This is useful when either one was random. `body` is the markup inside the outer `<svg>`, for nesting the cover in a larger SVG (its ids are unique to the cover, so several can share a document).
+
+| option     | type               | default                | notes                                          |
+| ---------- | ------------------ | ---------------------- | ---------------------------------------------- |
+| `title`    | `string`           | `'Untitled'`           |                                                |
+| `author`   | `string`           | `''`                   | optional                                       |
+| `subtitle` | `string`           | `''`                   | optional subtitle or tagline                   |
+| `texture`  | `boolean`          | `false`                | adds a fine film grain                         |
+| `style`    | `string`           | `'random'`             | a style id, see `styles`                       |
+| `palette`  | `string \| object` | `'random'`             | a palette id, or `{ bg, ink, accents: [...] }` |
+| `seed`     | `string \| number` | hash of title + author | controls every random choice                   |
+| `width`    | `number`           | `600`                  | px, 50–10000; aspect ratio 1:3 to 3:1          |
+| `height`   | `number`           | `width × 1.5`          | px, 50–10000                                   |
+| `lang`     | `string`           | inferred               | language of the text, such as `'ja'`           |
+
+`lang` is set on the cover so Chinese characters get the right glyphs for the language. Without it, text with kana is marked Japanese and text with Hangul Korean; pass `'zh-Hans'`, `'zh-Hant'` or `'ja'` for text in Chinese characters only.
+
+Titles and subtitles longer than 300 characters (authors: 200) are cut. With `'random'`, the style and palette are picked from the seed, so you get the same result every time for the same seed. Some styles prefer dark or light palettes when they pick one themselves. Invalid options throw an error that says what's wrong.
+
+### Other exports
+
+- `styles`: array of style ids
+- `listStyles()`: `[{ id, name, description, group }]`
+- `palettes`: `[{ id, name, bg, ink, accents, dark? }]`
+- `randomSeed()`: a short random seed string
+- `pickStyle(options)`: the style id `createCover` would use for these options (resolving `'random'` from the seed), without drawing the cover
+- `registerStyle({ id, name, description, group, prefer, render(ctx) })`: add your own style (see below). Replacing a built-in style takes `registerStyle(style, { replace: true })`; `unregisterStyle(id)` removes a style or brings the built-in back
+- `registerPalette({ id, name, bg, ink, accents })`: add a palette to use by id, as `palette: 'brand'` (`{ replace: true }` for a built-in id); `unregisterPalette(id)` removes it. Registered styles and palettes can also be picked by `'random'`, so registering one changes what a seed gives
+- `version`: the library's version (artwork for a seed can change between minor versions)
+- `sizeLimits` (`{ min: 50, max: 10000, ratio: 3 }`) and `formats` (`paperback`, `ebook` and `square` as `[width, height]` at 600 px wide): the sizes covers can have, and the app's shapes
+- `titleBlock`, `authorFit`: the typography the built-in styles use (a title with its lead line and subtitle, and the author line)
+- `fitText`, `drawText`, `fitStack`, `drawStack`, `splitLead`, `measureText`, `setTextMeasurer`, `FONTS`: lower-level text helpers (`fitText` can hyphenate one long word with `hyphenate: px`), and `baselineOf`, `textBottom`, `textGroupAttrs`, `markExtent` for styles that draw text themselves
+- `strongAccents`, `textColor`, `tintText`, `fitTitleWith`, `textPanel`, `TEXT_CONTRAST`: the colour and layout helpers the built-in styles use (accents that stand out, text colours that stay readable, giving up art for a longer title, a panel for title and author)
+- `svgUtils`: the SVG, colour and noise helpers the built-in styles use
+
+### TypeScript
+
+Types are included. `CoverOptions`, `Cover`, `StyleId`, `PaletteId`, `StyleGroup`, `StyleContext`, `CoverStyle`, `TitleBlock` and the rest are exported from the main entry point, and style and palette ids autocomplete.
+
+### Export helpers (browser)
+
+```js
+import { downloadCover, rasterize, copyText, copyImage, zipFiles } from 'book-cover-generator/browser';
+
+await copyText(svg); // copy SVG markup
+await copyImage(svg, { scale: 2 }); // copy a PNG (where canCopyImage() is true)
+await downloadCover(svg, 'svg', 'my-cover'); // my-cover.svg
+await downloadCover(svg, 'png', 'my-cover', { scale: 3, dpi: 300 }); // 1800×2700 PNG that prints at 6 × 9 in
+await downloadCover(svg, 'jpeg', 'my-cover', { width: 1600, quality: 0.9 }); // exactly 1600 px wide
+const name = await downloadCover(svg, 'webp', 'my-cover'); // 'my-cover.png' where WebP can't be made
+const blob = await rasterize(svg, { type: 'image/webp', width: 1600, height: 2560 });
+const zip = await zipFiles([
+  { name: 'cover.png', data: blob },
+  { name: 'cover.svg', data: svg },
+]);
+```
+
+`setDpi(blob, dpi)` records the pixel density in a PNG or JPEG you made yourself. It and `zipFiles` also work in Node.
+
+### Custom palette
+
+```js
+generateCover({
+  title: 'Bright Machines',
+  palette: { bg: '#0b132b', ink: '#f8f9fa', accents: ['#ff6b6b', '#4ecdc4', '#ffe66d'] },
+});
+```
+
+### Custom style
+
+`render(ctx)` returns SVG markup without the outer `<svg>` element. `ctx` contains:
+
+- `title`, `author`, `subtitle` (may be empty)
+- `W`, `H`: the size of the cover
+- `u`: a scale unit (1 at a short side of 600px)
+- `m`: the suggested margin
+- `S`: the short side; base text sizes on it so wide covers work
+- `rng`: seeded random with `next`, `float`, `int`, `bool`, `pick`, `shuffle`
+- `p`: the palette, with `bg`, `ink`, `accents`, plus `paper` (lighter) and `night` (darker)
+- `id(name)`: makes ids that are unique per cover, for gradients and filters
+
+```js
+import { registerStyle, titleBlock, authorFit, drawText, FONTS } from 'book-cover-generator';
+
+registerStyle({
+  id: 'plain',
+  name: 'Plain',
+  group: 'Typographic',
+  render(c) {
+    const title = titleBlock(c, {
+      font: FONTS.serif,
+      maxWidth: c.W - c.m * 2,
+      maxHeight: c.H * 0.5,
+      maxSize: c.S * 0.2,
+    });
+    const author = authorFit(c);
+    return (
+      `<rect width="${c.W}" height="${c.H}" fill="${c.p.bg}"/>` +
+      title.draw({ x: c.m, y: c.m, fill: c.p.ink }) +
+      drawText(author, { x: c.m, y: c.H - c.m - author.height, fill: c.p.ink })
+    );
+  },
+});
+```
+
+## Notes
+
+- **Fonts.** Covers only use system font stacks (Georgia, Helvetica, Futura, Didot, Impact, Courier and others), each with close matches on Windows, Android and Linux. This is because an SVG drawn into a canvas for PNG/JPEG export can't load web fonts. In the browser, text is measured with a canvas, so it fits exactly. In Node, widths are estimated; plug in a real font engine with `setTextMeasurer` if you need exact fits there.
+- **Deterministic.** The same options always give the same artwork. In Node the SVG is identical every time. In the browser, text is measured with the fonts installed on that computer, so line breaks can differ slightly between machines. Registering a custom style changes which style `style: 'random'` picks for a given seed.
+- **Versioning.** Artwork for a given seed can change in minor releases (a style gets better). Pin an exact version if you need byte-identical covers forever.
+- **Browser support.** Current Chrome, Edge, Firefox and Safari. Every release is tested in Chromium, Firefox and WebKit, including PNG and JPEG export.
+
+## Development
+
+```sh
+npm ci                     # install dev tooling (the library itself has no dependencies)
+npx playwright install     # browsers for the end-to-end tests
+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 test`              | unit tests (`node --test`)                                        |
+| `npm run test:coverage` | unit tests with coverage thresholds                               |
+| `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 |
+| `npm run deploy`        | run every check, then build and deploy to Cloudflare (`wrangler`) |
+
+Open `examples/contact-sheet.html?palettes=noir,mint&seeds=a,b` on the dev server to see many covers at once (also `styles`, `titles`, `subtitle`, `w`, `h`, `cols` and `texture=1`).
+
+### Project layout
+
+```
+src/            the library (plain ES modules + .d.ts types)
+  styles/       the 34 styles, one file per family
+bin/            the CLI
+site/           the web app (index.html is at the root)
+public/         files served at the site root: headers, 404, icons, manifest, service worker
+test/           unit tests (node --test)
+test-d/         type tests (tsc)
+e2e/            browser tests (Playwright)
+scripts/        build, dev server and asset generation
+```
+
+The site is a static [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) deployment configured in `wrangler.jsonc`, with security headers in `public/_headers`.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), and report security issues as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/bin/book-cover.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { createCover, listStyles, palettes, formats } from '../src/index.js';
+
+const HELP = `Usage: book-cover "<title>" ["<author>"] [options]
+
+Options:
+  -s, --style <id>      style id or "random" (default: random from seed)
+  -p, --palette <id>    palette id or "random" (default: random from seed)
+      --bg <hex>        your own colours instead of a palette: background,
+      --ink <hex>       text,
+      --accent <hex>    and accents (repeat it, or separate them with commas)
+      --subtitle <text> a subtitle or tagline
+      --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
+      --width <px>      width  (default 600)
+      --height <px>     height (default: from the format)
+      --size <WxH>      width and height at once, e.g. 1600x2560
+      --lang <tag>      language of the text, e.g. ja or zh-Hant (default: inferred)
+  -o, --out <file>      write SVG to a file instead of stdout
+      --count <n>       write n variations (seeds 1…n, or <seed>-1…), named
+                        cover-1.svg… from --out (or put {n} or {seed} in it)
+      --json            print the choices (and the SVG, without --out) as JSON,
+                        one line per cover
+      --list            list styles and palettes
+      --help            show this help
+
+Examples:
+  book-cover "The Lighthouse Keeper" "Mara Ellison" -s artdeco -o cover.svg
+  book-cover "Neon Tide" "Kai Moreno" --style retro --palette synth --size 1600x2560 > cover.svg
+  book-cover "Bright Machines" --bg 0b132b --ink f8f9fa --accent ff6b6b,4ecdc4 --format ebook -o cover.svg
+  book-cover "Salt and Static" "J. R. Okafor" --count 12 -o ideas/cover.svg`;
+
+let args;
+try {
+  args = parseArgs({
+    allowPositionals: true,
+    options: {
+      style: { type: 'string', short: 's' },
+      palette: { type: 'string', short: 'p' },
+      bg: { type: 'string' },
+      ink: { type: 'string' },
+      accent: { type: 'string', multiple: true },
+      subtitle: { type: 'string' },
+      texture: { type: 'boolean' },
+      seed: { type: 'string' },
+      format: { type: 'string' },
+      width: { type: 'string' },
+      height: { type: 'string' },
+      size: { type: 'string' },
+      lang: { type: 'string' },
+      out: { type: 'string', short: 'o' },
+      count: { type: 'string' },
+      json: { type: 'boolean' },
+      list: { type: 'boolean' },
+      help: { type: 'boolean' },
+    },
+  });
+} catch (err) {
+  console.error((err instanceof Error ? err.message : String(err)) + '\n\n' + HELP);
+  process.exit(1);
+}
+
+const { values, positionals } = args;
+
+if (values.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (values.list) {
+  console.log('Styles:');
+  for (const s of listStyles()) console.log(`  ${s.id.padEnd(14)} ${s.description}`);
+  console.log('\nPalettes:');
+  for (const p of palettes) console.log(`  ${p.id.padEnd(14)} ${p.name}${p.dark ? ' (dark)' : ''}`);
+  process.exit(0);
+}
+
+if (!positionals.length) {
+  console.error(HELP);
+  process.exit(1);
+}
+if (positionals.length > 2) {
+  console.error(
+    `Expected a title and an author, got ${positionals.length} arguments. Quote values with spaces: book-cover "The Lighthouse Keeper" "Mara Ellison"`,
+  );
+  process.exit(1);
+}
+
+/**
+ * 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 }}
+ */
+function dimensions() {
+  if (values.size !== undefined) {
+    if (values.width !== undefined || values.height !== undefined || values.format !== undefined) {
+      throw new Error('--size sets the width and height: use it without --width, --height or --format');
+    }
+    const m = /^\s*(\d+(?:\.\d+)?)\s*[x×]\s*(\d+(?:\.\d+)?)\s*$/i.exec(values.size);
+    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');
+  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 colour as typed, with the # added (it starts a comment in most shells). @param {string} c */
+const hex = (c) => (c.trim().startsWith('#') ? c.trim() : `#${c.trim()}`);
+
+/** The palette: an id, or your own colours from --bg, --ink and --accent. */
+function palette() {
+  const custom = values.bg !== undefined || values.ink !== undefined || values.accent !== undefined;
+  if (!custom) return values.palette;
+  if (values.palette !== undefined)
+    throw new Error('Use --palette or your own colours (--bg, --ink, --accent), not both');
+  const accents = (values.accent ?? []).flatMap((a) => a.split(',')).filter((a) => a.trim());
+  if (values.bg === undefined || values.ink === undefined || !accents.length) {
+    throw new Error('Your own colours need --bg, --ink and at least one --accent');
+  }
+  return { bg: hex(values.bg), ink: hex(values.ink), accents: accents.map(hex) };
+}
+
+// A reader that stops early (book-cover … | head) closes the pipe: that's fine, not a crash.
+process.stdout.on('error', (err) => {
+  if (/** @type {NodeJS.ErrnoException} */ (err).code === 'EPIPE') process.exit(0);
+  throw err;
+});
+
+/** How many covers to write: --count, 1 by default. */
+function count() {
+  if (values.count === undefined) return 1;
+  const n = Number(values.count);
+  if (!/^\s*\d+\s*$/.test(values.count) || n < 1 || n > 1000) {
+    throw new RangeError(`--count must be a whole number from 1 to 1000, got "${values.count}"`);
+  }
+  if (n > 1 && !values.out) throw new Error('--count writes files: give --out, e.g. -o covers/cover.svg');
+  return n;
+}
+
+/**
+ * The file for cover `n` of `total`: --out with {n} and {seed} filled in, or (for several
+ * covers) with "-n" before the extension.
+ * @param {string} out @param {number} n @param {number} total @param {string} seed
+ */
+function fileFor(out, n, total, seed) {
+  if (/\{n\}|\{seed\}/.test(out)) return out.replaceAll('{n}', String(n)).replaceAll('{seed}', safeName(seed));
+  if (total === 1) return out;
+  const dot = out.lastIndexOf('.');
+  const slash = Math.max(out.lastIndexOf('/'), out.lastIndexOf('\\'));
+  return dot > slash + 1 ? `${out.slice(0, dot)}-${n}${out.slice(dot)}` : `${out}-${n}`;
+}
+
+/**
+ * A seed as part of a file name: letters, digits, dots, dashes and underscores only (so a seed
+ * can't add folders, leave the folder or break names on Windows), never starting with a dot.
+ * @param {string} seed
+ */
+const safeName = (seed) => seed.replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^[.-]+/, '') || 'cover';
+
+try {
+  const total = count();
+  const options = {
+    title: positionals[0],
+    author: positionals[1] ?? '',
+    subtitle: values.subtitle,
+    texture: values.texture,
+    style: values.style,
+    palette: palette(),
+    lang: values.lang,
+    ...dimensions(),
+  };
+  for (let n = 1; n <= total; n++) {
+    // One cover: the seed given (or the title's). Several: seeds 1…n, or <seed>-1…<seed>-n.
+    const seed = total === 1 ? values.seed : values.seed ? `${values.seed}-${n}` : String(n);
+    const cover = createCover({ ...options, seed });
+    const { style, palette: paletteId, width, height, lang } = cover;
+    const choices = { style, palette: paletteId, seed: cover.seed, width, height, lang };
+    if (values.out) {
+      const file = fileFor(values.out, n, total, cover.seed);
+      writeFileSync(file, cover.svg);
+      if (values.json) process.stdout.write(JSON.stringify({ file, ...choices }) + '\n');
+      else console.error(`Wrote ${file} (style: ${style}, palette: ${paletteId}, ${width}x${height})`);
+    } else if (values.json) {
+      process.stdout.write(JSON.stringify({ ...choices, svg: cover.svg }) + '\n');
+    } else {
+      process.stdout.write(cover.svg + '\n');
+    }
+  }
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "book-cover-generator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "Generate SVG book covers from a title and an author. 34 styles, 28 palettes, seeded randomizer, zero dependencies.",
+  "keywords": [
+    "book",
+    "cover",
+    "book-cover",
+    "svg",
+    "generator",
+    "generative-art",
+    "placeholder",
+    "typescript"
+  ],
+  "homepage": "https://covers.otsirh.dev/",
+  "bugs": {
+    "url": "https://github.com/otsirh/book-cover-generator/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/otsirh/book-cover-generator.git"
+  },
+  "license": "MIT",
+  "author": "otsirh (https://github.com/otsirh)",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./browser": {
+      "types": "./src/browser.d.ts",
+      "default": "./src/browser.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "bin": {
+    "book-cover": "bin/book-cover.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18.3"
+  },
+  "scripts": {
+    "dev": "node scripts/serve.js 4173",
+    "build": "node scripts/build.js",
+    "lint": "eslint .",
+    "lint:package": "publint --strict && attw --pack . --profile esm-only",
+    "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:e2e": "playwright test",
+    "check": "npm run lint && npm run format:check && npm run typecheck && npm run lint:package && npm test",
+    "assets": "node scripts/generate-assets.js",
+    "deploy": "npm run check && npm run test:e2e && wrangler deploy"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@axe-core/playwright": "4.14.0",
+    "@eslint/js": "10.0.1",
+    "@playwright/test": "1.65.0",
+    "@types/node": "26.6.6",
+    "eslint": "10.14.0",
+    "globals": "17.14.0",
+    "prettier": "3.10.0",
+    "publint": "0.3.25",
+    "typescript": "7.0.2",
+    "wrangler": "4.160.1"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true,
+    "workerd@1.20261110.1": true,
+    "fsevents": false
+  },
+  "overrides": {
+    "minimatch": "11.0.8"
+  }
+}

package/src/browser.d.ts

@@ -0,0 +1,52 @@
+export declare function svgToDataUrl(svg: string): string;
+export declare function svgToBlob(svg: string): Blob;
+
+export interface RasterizeOptions {
+  type?: 'image/png' | 'image/jpeg' | 'image/webp';
+  /** Multiplier applied to the SVG's width and height. Default 1. Ignored when `width` or `height` is given. */
+  scale?: number;
+  /** The image's exact width in px. Alone, the height follows the SVG's shape. */
+  width?: number;
+  /** The image's exact height in px. Alone, the width follows the SVG's shape. */
+  height?: number;
+  /** Pixels per inch to record in PNG and JPEG files (what print software reads for the printed size). */
+  dpi?: number;
+  /** 0–1, for JPEG and WebP. Default 0.92. */
+  quality?: number;
+  /** Fill colour behind the cover. JPEG defaults to white. */
+  background?: string;
+}
+
+/** Render SVG markup to an image Blob. Browsers that can't encode `type` return PNG; check `blob.type`. */
+export declare function rasterize(svg: string, opts?: RasterizeOptions): Promise<Blob>;
+/** Trigger a file download for a Blob. */
+export declare function downloadBlob(blob: Blob, filename: string): void;
+
+export type ExportFormat = 'svg' | 'png' | 'jpeg' | 'jpg' | 'webp';
+/**
+ * Download a cover; `basename` gets the right extension appended. Resolves to the file name,
+ * whose extension says what was made (browsers that can't encode WebP make a PNG).
+ */
+export declare function downloadCover(
+  svg: string,
+  format?: ExportFormat,
+  basename?: string,
+  opts?: Omit<RasterizeOptions, 'type'>,
+): Promise<string>;
+/** `'png'`, `'jpg'` or `'webp'` for an image Blob of that type, else undefined. */
+export declare function extensionOf(blob: Blob): 'png' | 'jpg' | 'webp' | undefined;
+/** A copy of a PNG or JPEG Blob that records `dpi` pixels per inch. Other types come back unchanged. Works in Node too. */
+export declare function setDpi(blob: Blob, dpi: number): Promise<Blob>;
+/** A ZIP archive (stored, not compressed) of the given files. Names are UTF-8 and should be unique. Works in Node too. */
+export declare function zipFiles(
+  files: ReadonlyArray<{ name: string; data: Blob | Uint8Array | string }>,
+): Promise<Blob>;
+/** Copy a cover to the clipboard as a PNG. Rejects where `canCopyImage()` is false. */
+export declare function copyImage(
+  svg: string,
+  opts?: Omit<RasterizeOptions, 'type' | 'quality' | 'dpi'>,
+): Promise<void>;
+/** Whether this browser can copy images to the clipboard on this page. */
+export declare function canCopyImage(): boolean;
+/** Copy text to the clipboard, with a fallback for non-secure contexts. */
+export declare function copyText(text: string): Promise<void>;