@arraypress/covers 0.0.0-stage → 1.1.0

package/src/lint/image-size.d.ts

@@ -0,0 +1,4 @@
+// An image's pixel size from its header.
+
+/** Width and height of a PNG, JPEG, WebP or GIF, without decoding it. */
+export function imageSize(b: Uint8Array): { width: number; height: number } | undefined;

package/src/lint/image-size.js

@@ -0,0 +1,34 @@
+/**
+ * An image's pixel size from its header, without decoding it.
+ *
+ * @module lint/image-size
+ */
+
+/**
+ * An image's pixel size from its header (PNG, JPEG, WebP, GIF).
+ *
+ * @param {Uint8Array} b
+ * @returns {{ width: number, height: number } | undefined}
+ */
+export function imageSize(b) {
+  const v = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  if (b[0] === 0x89 && b[1] === 0x50) return { width: v.getUint32(16), height: v.getUint32(20) };
+  if (b[0] === 0x47 && b[1] === 0x49) return { width: v.getUint16(6, true), height: v.getUint16(8, true) };
+  if (b[0] === 0xff && b[1] === 0xd8) {
+    let i = 2;
+    while (i + 9 < b.length) {
+      if (b[i] !== 0xff) { i++; continue; }
+      const m = b[i + 1];
+      if (m >= 0xc0 && m <= 0xcf && m !== 0xc4 && m !== 0xc8 && m !== 0xcc) return { width: v.getUint16(i + 7), height: v.getUint16(i + 5) };
+      i += 2 + v.getUint16(i + 2);
+    }
+    return undefined;
+  }
+  if (String.fromCharCode(b[0], b[1], b[2], b[3]) === 'RIFF' && String.fromCharCode(b[8], b[9], b[10], b[11]) === 'WEBP') {
+    const kind = String.fromCharCode(b[12], b[13], b[14], b[15]);
+    if (kind === 'VP8X') return { width: 1 + (b[24] | (b[25] << 8) | (b[26] << 16)), height: 1 + (b[27] | (b[28] << 8) | (b[29] << 16)) };
+    if (kind === 'VP8L') { const x = v.getUint32(21, true); return { width: (x & 0x3fff) + 1, height: ((x >> 14) & 0x3fff) + 1 }; }
+    if (kind === 'VP8 ') return { width: v.getUint16(26, true) & 0x3fff, height: v.getUint16(28, true) & 0x3fff };
+  }
+  return undefined;
+}

package/src/lint/index.d.ts

@@ -0,0 +1,16 @@
+// Release cover art checks.
+import type { Cover, CoverOptions } from '../index.js';
+export { imageSize } from './image-size.js';
+
+/** A problem `lint` found. */
+export interface LintIssue {
+  rule: 'aspect' | 'resolution' | 'url' | 'handle' | 'contact' | 'price' | 'promo' | 'platform' | 'date' | 'physical' | 'legibility' | 'metadata' | 'barcode' | 'upscaled';
+  severity: 'error' | 'warning';
+  message: string;
+  layer?: string;
+  text?: string;
+}
+
+
+/** Check a cover against Spotify's artwork requirements and distributors' content rules. */
+export function lint(input: CoverOptions | Cover, options?: { target?: 'spotify' | 'release'; artist?: string; title?: string; size?: number }): Promise<{ ok: boolean; target: string; issues: LintIssue[] }>;

package/src/lint/index.js

@@ -0,0 +1,127 @@
+/**
+ * Checks for release cover art before it goes to a distributor.
+ *
+ * Spotify's own requirements (Spotify for Artists, "Cover art
+ * requirements"): square (1:1), 640–10000 px on each side, sRGB, and never
+ * upscaled. 3000×3000 is the size distributors and the other stores ask
+ * for. The content rules come from the distributors that deliver to
+ * Spotify (and Apple Music): no URLs, social handles or contact details, no
+ * prices or promotional wording ("out now", "free download"), no release
+ * dates or other time frames, no store or platform names and logos, no
+ * barcodes or QR codes, and text that matches the release's metadata.
+ * Those are reported as errors when a distributor would reject the art,
+ * warnings when it may.
+ *
+ * `lint` also renders the cover to measure what it draws, through every
+ * group, transform and stretch: text whose smallest capitals are under 4 px
+ * tall at a 64 px thumbnail (the size Spotify lists use) is flagged, and so
+ * are images drawn larger than their pixels (or embedded smaller than
+ * drawn). Store names that are also words ("Tidal Archive") and day
+ * names in titles ("Second Sun") need a cue to count; text spelled from
+ * the artist and title (a letter per layer, a knocked-out word) matches.
+ *
+ * @module lint
+ */
+
+import { cover, renderReport } from '../render.js';
+import { RULES } from './rules.js';
+import { imageSize } from './image-size.js';
+
+export { imageSize };
+
+/** Glyphs set narrower than this (justification) read smaller than their cap height. */
+const SQUEEZE = 0.6;
+
+/**
+ * @typedef {object} LintIssue
+ * @property {string} rule
+ * @property {'error' | 'warning'} severity
+ * @property {string} message
+ * @property {string} [layer] - The layer's id, when it has one.
+ * @property {string} [text] - The text that tripped the rule.
+ */
+
+/**
+ * Check a cover against a target's artwork rules.
+ *
+ * @param {import('../index.js').CoverOptions | import('../index.js').Cover} input
+ * @param {{ target?: 'spotify' | 'release', artist?: string, title?: string, size?: number }} [options] - `artist`, `title`: the release metadata the text should match. `size`: the delivery size (default 3000).
+ * @returns {Promise<{ ok: boolean, target: string, issues: LintIssue[] }>}
+ *
+ * @example
+ * const { ok, issues } = await lint({ recipe: myCover, format: 'release', title: 'Night Garden' }, { target: 'spotify' });
+ */
+export async function lint(input, options = {}) {
+  const target = options.target ?? 'spotify';
+  if (target !== 'spotify' && target !== 'release') throw new TypeError(`Unknown lint target "${target}" (spotify, release)`);
+  const c = cover(input);
+  /** @type {LintIssue[]} */
+  const issues = [];
+  const add = (/** @type {LintIssue} */ i) => issues.push(i);
+
+  // Spotify's requirements.
+  if (c.width !== c.height) add({ rule: 'aspect', severity: 'error', message: `Cover art must be square (1:1); this is ${c.width}×${c.height}.` });
+  const side = Math.min(c.width, c.height);
+  if (side < 640) add({ rule: 'resolution', severity: 'error', message: `Cover art must be at least 640 px on each side; this is ${c.width}×${c.height}.` });
+  else if (side < (options.size ?? 3000)) add({ rule: 'resolution', severity: 'warning', message: `Deliver ${options.size ?? 3000}×${options.size ?? 3000} (stores and distributors ask for it); this is ${c.width}×${c.height}. Render with format: 'release'.` });
+  if (Math.max(c.width, c.height) > 10000) add({ rule: 'resolution', severity: 'error', message: 'Cover art must be at most 10000 px on each side.' });
+
+  // What's drawn (sizes in canvas px, through every group and transform).
+  const { svg, drawn } = await renderReport(c);
+  const texts = drawn.filter((d) => d.kind === 'text').map((d) => ({ ...d }));
+  // Raw SVG text the layer system didn't set.
+  for (const m of svg.matchAll(/<text\b[^>]*>([^<]+)<\/text>/g)) texts.push({ kind: 'text', content: m[1], size: undefined, capHeight: undefined });
+
+  for (const t of texts) {
+    const content = String(t.content ?? '');
+    for (const [rule, severity, re, what] of RULES) {
+      const m = re.exec(content);
+      if (m) add({ rule, severity, layer: t.id, text: m[0].trim(), message: `Text contains ${what}: "${m[0].trim()}". Distributors reject cover art with ${what}.` });
+    }
+    // Legibility at a 64 px thumbnail: the block's smallest capitals as drawn,
+    // narrowed by a heavy squeeze (justification scaling glyphs under 60% wide).
+    if (t.capHeight != null) {
+      const squeeze = (t.squeeze ?? 1) < SQUEEZE ? Math.sqrt(t.squeeze / SQUEEZE) : 1;
+      const thumb = (t.capHeight * squeeze * 64) / Math.max(c.width, c.height);
+      if (thumb < 4) add({ rule: 'legibility', severity: 'warning', layer: t.id, text: content.slice(0, 40), message: `"${content.slice(0, 40)}${content.length > 40 ? '…' : ''}" is ${thumb.toFixed(1)} px tall (capitals) at a 64 px thumbnail; under 4 px it can't be read.` });
+    }
+  }
+
+  // Text that isn't the release's metadata. Text that is part of it (a
+  // letter, a word knocked out of a shape) passes; so does anything spelled
+  // inside the artist and title.
+  if (options.artist || options.title) {
+    const meta = `${options.artist ?? ''} ${options.title ?? ''}`.toLowerCase();
+    const allowed = new Set(meta.split(/[^\p{L}\p{N}]+/u).filter(Boolean));
+    const squashed = meta.replace(/[^\p{L}\p{N}]+/gu, '');
+    const seen = new Set();
+    for (const t of texts) {
+      const text = String(t.content ?? '').toLowerCase();
+      const letters = text.replace(/[^\p{L}\p{N}]+/gu, '');
+      if (!letters || squashed.includes(letters) || seen.has(text)) continue;
+      seen.add(text);
+      const extra = text.split(/[^\p{L}\p{N}]+/u).filter((w) => w && !allowed.has(w));
+      if (extra.length) add({ rule: 'metadata', severity: 'warning', layer: t.id, text: extra.slice(0, 6).join(' '), message: `Text doesn't match the release metadata (${extra.slice(0, 6).join(', ')}${extra.length > 6 ? ', …' : ''}). Stores ask that cover text matches the artist and title.` });
+    }
+  }
+
+  // Barcodes and QR codes.
+  const walk = (/** @type {any[]} */ list, /** @type {(l: any) => void} */ fn) => list.forEach((l) => { fn(l); for (const k of ['layers', 'mask', 'knockout', 'clip']) if (Array.isArray(l[k])) walk(l[k], fn); });
+  walk(c.layers, (l) => {
+    if (l.type === 'barcode') add({ rule: 'barcode', severity: 'error', layer: l.id, message: 'Cover art can\'t carry a barcode or QR code.' });
+  });
+
+  // Images drawn bigger than their pixels (at the delivery size), or
+  // embedded at fewer pixels than they're drawn at.
+  const delivery = (options.size ?? 3000) / Math.max(c.width, c.height);
+  for (const im of drawn.filter((d) => d.kind === 'image' && d.source)) {
+    const bw = im.drawn.width * delivery;
+    const bh = im.drawn.height * delivery;
+    // Output pixels per source pixel: contain fits the whole image, cover fills the box.
+    const grow = im.fit === 'contain' ? Math.min(bw / im.source.width, bh / im.source.height) : im.fit === 'stretch' ? Math.max(bw / im.source.width, bh / im.source.height) : Math.max(bw / im.source.width, bh / im.source.height);
+    if (grow > 1.05) add({ rule: 'upscaled', severity: 'warning', layer: im.id, message: `An image (${im.source.width}×${im.source.height}) is drawn ${grow.toFixed(1)}× its size at ${options.size ?? 3000}×${options.size ?? 3000}: it will look soft. Spotify asks for art that isn't upscaled.` });
+    else if (im.embedded && Math.max(im.embedded.width / im.drawn.width, im.embedded.height / im.drawn.height) < 0.95) add({ rule: 'upscaled', severity: 'warning', layer: im.id, message: `An image is embedded at ${im.embedded.width}×${im.embedded.height} but drawn at ${Math.round(im.drawn.width)}×${Math.round(im.drawn.height)}: it was downsampled and will look soft.` });
+  }
+
+  return { ok: !issues.some((i) => i.severity === 'error'), target, issues };
+}

package/src/lint/rules.d.ts

@@ -0,0 +1,5 @@
+// The text rules lint applies.
+import type { LintIssue } from './index.js';
+
+/** `[rule, severity, pattern, what it is]`. */
+export const RULES: readonly [LintIssue['rule'], LintIssue['severity'], RegExp, string][];

package/src/lint/rules.js

@@ -0,0 +1,19 @@
+/**
+ * The text rules `lint` applies: what distributors reject on cover art.
+ *
+ * @module lint/rules
+ */
+
+/** Text rules: id, severity, pattern, what's wrong. */
+export const RULES = /** @type {[string, 'error' | 'warning', RegExp, string][]} */ ([
+  ['url', 'error', /\b(?:https?:\/\/|www\.)\S+|\b[a-z0-9][a-z0-9-]*\.(?:com|net|org|io|co|uk|fm|app|dev|me|tv|music|shop|store|info|biz|xyz|fair|art|band|live|link|studio|club|gg|ly|to|de|fr|nl)\b/i, 'a website address'],
+  ['handle', 'error', /(?:^|[\s(])@[A-Za-z0-9_.]{2,}/, 'a social media handle'],
+  ['contact', 'error', /[\w.+-]+@[\w-]+\.[\w.]+|(?:\+\d{1,3}[ .-]?)?(?:\(\d{2,5}\)[ .-]?|\d{2,5}[ .-])\d{3,4}[ .-]?\d{3,4}\b/, 'contact details (email or phone)'],
+  ['price', 'error', /[$£€¥]\s?\d|\b\d+(?:[.,]\d+)?\s?(?:usd|eur|gbp)\b|\bfree(?:\s+(?:download|entry|in|stream))?\b|\bbuy now\b|\bon sale\b/i, 'a price or a sales line'],
+  ['promo', 'error', /\b(?:out now|coming soon|new (?:single|album|ep|music)|available (?:now|everywhere)|pre-?(?:save|order)|stream (?:it )?now|listen now)\b/i, 'promotional wording'],
+  // Brand names that are only ever the platform; "Tidal" is also a word, so it counts with a cue ("on Tidal", "stream Tidal") or on its own.
+  ['platform', 'error', /\b(?:spotify|apple music|itunes|youtube|bandcamp|soundcloud|deezer|amazon music|tiktok|instagram)\b|\b(?:on|via|stream(?:ing)?(?:\s+on)?|listen(?:\s+on)?|available\s+on|find\s+us\s+on|follow\s+(?:us\s+)?on)\s+tidal\b|^\s*tidal\s*$/im, 'a store or platform name'],
+  // Months and short day names count next to a number ("Sat 14", "14 March"); a full day name counts alone; "Second Sun" doesn't.
+  ['date', 'warning', /\b(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?\s+\d{1,2}(?:st|nd|rd|th)?\b|\b\d{1,2}(?:st|nd|rd|th)?\s+(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\b|\b\d{1,2}[./-]\d{1,2}[./-]\d{2,4}\b|\b(?:mon|tues?|wed|thu(?:rs?)?|fri|sat|sun)\.?,?\s+\d{1,2}\b|\b\d{1,2}(?:st|nd|rd|th)?,?\s+(?:mon|tues?|wed|thu(?:rs?)?|fri|sat|sun)\b|\b(?:mon|tues|wednes|thurs|fri|satur|sun)day\b|\b(?:today|tonight|this (?:week|weekend|friday))\b/i, 'a date or time frame'],
+  ['physical', 'warning', /\b(?:cd|vinyl|cassette|lp|7")\b/i, 'a physical format'],
+]);

package/src/node.d.ts

@@ -0,0 +1,2 @@
+// @arraypress/covers/node: the same API, with Node's modules installed up front.
+export * from './index.js';

package/src/node.js

@@ -0,0 +1,20 @@
+/**
+ * `@arraypress/covers/node`: the same API, with Node's modules installed
+ * up front. Needed only on Node older than 20.16 (no
+ * `process.getBuiltinModule`), or in a bundle where you want the file
+ * system wired in explicitly.
+ *
+ * @module @arraypress/covers/node
+ */
+
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as zlib from 'node:zlib';
+import * as path from 'node:path';
+import * as module from 'node:module';
+import * as url from 'node:url';
+import { installNode } from './platform/index.js';
+
+installNode({ fs, fsp, zlib, path, module, url });
+
+export * from './index.js';

package/src/palette.js

@@ -0,0 +1,185 @@
+/**
+ * Palettes: the colours a cover draws with.
+ *
+ * Every layer reads its default colours from one resolved palette:
+ *
+ * - `bg`      the page colour under everything
+ * - `colors`  the colours of gradients, blobs, stripes and shapes
+ * - `text`    type (readable on `bg`)
+ * - `accent`  the one strong colour (icons, labels, spots)
+ * - `onAccent` white, or near-black when the accent is light: for marks on the accent
+ * - `muted`   secondary type (`text` mixed toward `bg`)
+ * - `surface` raised things that sit on `bg` (icon tiles, pills)
+ * - `mode`    `'light'` or `'dark'`, from `bg`
+ *
+ * A palette can be written as a preset name, an array (`[bg, ...colors]`),
+ * a partial object, or derived from a theme's tokens with
+ * {@link derivePalette}.
+ *
+ * @module palette
+ */
+
+import { relativeLuminance, contrastRatio, readableOn, readableText } from '@arraypress/color-utils';
+import { toHex, toOklch, fromOklch, mixOklab } from './color.js';
+
+/**
+ * Curated presets. Each is a full palette; the light ones pair with the
+ * dark ones of the same family (`paper`/`ink`, `dawn`/`dusk`, …).
+ *
+ * @type {Readonly<Record<string, Readonly<import('./index.js').PaletteInput>>>}
+ */
+export const palettes = Object.freeze({
+  paper: { bg: '#f3efe7', colors: ['#f0a98a', '#a9bdf2', '#f3d27e', '#b7dcc4'], text: '#1c1a17', accent: '#c9502a' },
+  ink: { bg: '#0c0d12', colors: ['#3d5afe', '#ff6b3d', '#9b4dff', '#12b5a0'], text: '#f4f4f6', accent: '#8ea0ff' },
+  dawn: { bg: '#fbf1ee', colors: ['#ff9f87', '#ffc7d9', '#c9b6ff', '#ffd9a8'], text: '#2a1714', accent: '#e0533d' },
+  dusk: { bg: '#100b1c', colors: ['#6a3df0', '#ff7a59', '#d1408f', '#2b3fd6'], text: '#f7f3ff', accent: '#ff9c7e' },
+  ocean: { bg: '#eef4f7', colors: ['#7fb8f0', '#8de0cf', '#b9c9ff', '#d7f0ff'], text: '#0f1d29', accent: '#1f6fd1' },
+  ember: { bg: '#140c08', colors: ['#ff5a1f', '#ffb020', '#d6264f', '#7a2b10'], text: '#fff4ea', accent: '#ffb35c' },
+  moss: { bg: '#f1f3ea', colors: ['#a8cf8e', '#e6d48a', '#7fbfa8', '#cfe3b5'], text: '#18200f', accent: '#3f7d2c' },
+  carbon: { bg: '#0a0a0b', colors: ['#3a3a40', '#5b5b66', '#26262b', '#8a8a96'], text: '#fafafa', accent: '#e4e4e7' },
+  mono: { bg: '#f4f4f5', colors: ['#d4d4d8', '#e4e4e7', '#a1a1aa', '#fafafa'], text: '#18181b', accent: '#18181b' },
+});
+
+/**
+ * Derive a full palette from a theme's tokens (or just an accent).
+ *
+ * Gradient colours are built in OKLCH around the accent's hue: one near the
+ * accent, two neighbours (±40°) and a quiet complement, set pastel on light
+ * backgrounds and deep on dark ones. Missing `bg` is a faint tint of the
+ * accent (light) or a near-black of its hue (dark); missing `text` is a
+ * near-black or near-white of the same hue that clears 7:1 on `bg`.
+ *
+ * @param {object} tokens
+ * @param {string} tokens.accent - The theme's accent (hex, `rgb()` or `hsl()`).
+ * @param {string} [tokens.bg] - The theme's background.
+ * @param {string} [tokens.text] - The theme's text colour.
+ * @param {string[]} [tokens.colors] - Gradient colours to use as-is instead of deriving them.
+ * @param {'light' | 'dark'} [tokens.mode] - Force a mode (default: from `bg`, else light).
+ * @returns {import('./index.js').Palette} A resolved palette.
+ *
+ * @example
+ * derivePalette({ accent: '#2563eb', bg: '#fdfdfd', text: '#1d1d1f' });
+ * derivePalette({ accent: 'rgb(209 254 23)', mode: 'dark' });
+ */
+export function derivePalette({ accent, bg, text, colors, mode } = /** @type {any} */ ({})) {
+  if (!accent) throw new TypeError('derivePalette() needs an accent');
+  const acc = toHex(accent);
+  const a = toOklch(acc);
+  const resolvedMode = mode ?? (bg ? modeOf(toHex(bg)) : 'light');
+  const dark = resolvedMode === 'dark';
+  const hue = a.c < 0.02 ? 260 : a.h; // a grey accent has no meaningful hue
+  const chroma = Math.min(1, a.c / 0.12); // greys stay grey
+
+  const base = bg ? toHex(bg) : fromOklch(dark ? { l: 0.16, c: 0.018 * chroma, h: hue } : { l: 0.975, c: 0.014 * chroma, h: hue });
+
+  const derived = dark
+    ? [
+        { l: 0.6, c: 0.17, h: hue },
+        { l: 0.48, c: 0.15, h: hue + 40 },
+        { l: 0.64, c: 0.13, h: hue - 40 },
+        { l: 0.36, c: 0.09, h: hue + 180 },
+      ]
+    : [
+        { l: 0.8, c: 0.12, h: hue },
+        { l: 0.87, c: 0.08, h: hue + 40 },
+        { l: 0.83, c: 0.1, h: hue - 40 },
+        { l: 0.92, c: 0.045, h: hue + 180 },
+      ];
+
+  return finish({
+    bg: base,
+    colors: colors?.length ? colors.map(toHex) : derived.map((c) => fromOklch({ ...c, c: c.c * chroma })),
+    text: text ? toHex(text) : undefined,
+    accent: acc,
+  });
+}
+
+/**
+ * Resolve any palette input to a full {@link import('./index.js').Palette}.
+ *
+ * - `undefined` → the `paper` preset
+ * - a preset name (`'dusk'`) → that preset
+ * - a single colour (`'#2563eb'`) → {@link derivePalette} from it
+ * - an array → `[bg, ...colors]` (a one-item array is an accent)
+ * - an object → missing fields filled in (only `accent` → derived)
+ *
+ * @param {import('./index.js').PaletteInput} [input] - The palette.
+ * @returns {import('./index.js').Palette} The resolved palette.
+ * @throws {TypeError} On an unknown preset name or an unparseable colour.
+ *
+ * @example
+ * resolvePalette('dusk').mode;                    // 'dark'
+ * resolvePalette(['#0b0b0f', '#ff6a3d', '#3d5afe']).text; // a near-white
+ */
+export function resolvePalette(input) {
+  if (input == null) return resolvePalette(palettes.paper);
+  if (typeof input === 'string') {
+    if (Object.hasOwn(palettes, input)) return resolvePalette(palettes[input]);
+    try {
+      return derivePalette({ accent: input });
+    } catch {
+      throw new TypeError(`Unknown palette "${input}". Presets: ${Object.keys(palettes).join(', ')}`);
+    }
+  }
+  if (Array.isArray(input)) {
+    if (input.length === 0) return resolvePalette(undefined);
+    if (input.length === 1) return derivePalette({ accent: input[0] });
+    const [bg, ...colors] = input.map(toHex);
+    return finish({ bg, colors, accent: colors[0] });
+  }
+  if (typeof input === 'object') {
+    if (!input.bg && !input.colors && input.accent) return derivePalette(/** @type {any} */ (input));
+    if (!input.colors?.length && input.accent) return derivePalette(/** @type {any} */ (input));
+    const bg = toHex(input.bg ?? '#ffffff');
+    const colors = (input.colors?.length ? input.colors : [input.accent ?? (modeOf(bg) === 'dark' ? '#ffffff' : '#000000')]).map(toHex);
+    return finish({
+      bg,
+      colors,
+      text: input.text ? toHex(input.text) : undefined,
+      accent: input.accent ? toHex(input.accent) : colors[0],
+      muted: input.muted ? toHex(input.muted) : undefined,
+      surface: input.surface ? toHex(input.surface) : undefined,
+      onAccent: input.onAccent ? toHex(input.onAccent) : undefined,
+    });
+  }
+  throw new TypeError('A palette is a preset name, a colour, an array of colours or an object');
+}
+
+/**
+ * `'light'` or `'dark'` for a background.
+ *
+ * @param {string} bg - `#rrggbb`.
+ * @returns {'light' | 'dark'} The mode.
+ */
+export function modeOf(bg) {
+  // 0.18 is where black and white text have equal contrast on a surface.
+  return relativeLuminance(bg) > 0.18 ? 'light' : 'dark';
+}
+
+/**
+ * Fill the derived fields of a partial palette.
+ *
+ * @param {{ bg: string, colors: string[], accent: string, text?: string, muted?: string, surface?: string, onAccent?: string }} p
+ * @returns {import('./index.js').Palette} The palette.
+ */
+function finish(p) {
+  const mode = modeOf(p.bg);
+  const dark = mode === 'dark';
+  const { h, c } = toOklch(p.accent);
+  const tint = Math.min(0.02, c * 0.15);
+  let text = p.text;
+  if (!text) {
+    text = fromOklch(dark ? { l: 0.97, c: tint * 0.5, h } : { l: 0.2, c: tint, h });
+    if (contrastRatio(text, p.bg) < 7) text = readableOn(text, [p.bg], { toward: dark ? '#ffffff' : '#000000', ratio: 7 });
+  }
+  return Object.freeze({
+    mode,
+    bg: p.bg,
+    colors: Object.freeze(p.colors.slice()),
+    text,
+    accent: p.accent,
+    onAccent: p.onAccent ?? readableText(p.accent, '#ffffff', '#111111'),
+    muted: p.muted ?? mixOklab(text, p.bg, 0.38),
+    surface: p.surface ?? (dark ? mixOklab(p.bg, text, 0.07) : mixOklab(p.bg, '#ffffff', 0.75)),
+  });
+}

package/src/platform/bytes.d.ts

@@ -0,0 +1,22 @@
+// Byte helpers without Buffer.
+
+/** Bytes as a Uint8Array view. */
+export function u8(v: Uint8Array | ArrayBuffer | ArrayBufferView): Uint8Array;
+/** Whether a value is bytes. */
+export function isBytes(v: unknown): v is Uint8Array | ArrayBuffer;
+/** Base64-encode bytes. */
+export function toBase64(bytes: Uint8Array | ArrayBuffer): string;
+/** Decode base64. */
+export function fromBase64(s: string): Uint8Array;
+/** Each byte as one character. */
+export function latin1(b: Uint8Array): string;
+/** Decode UTF-8. */
+export function utf8(b: Uint8Array | ArrayBuffer): string;
+/** Encode UTF-8. */
+export function encodeUtf8(s: string): Uint8Array;
+/** Join byte arrays. */
+export function concat(parts: Uint8Array[]): Uint8Array;
+/** A `data:` URI's bytes, or undefined when it isn't one. */
+export function fromDataUri(uri: string): Uint8Array | undefined;
+/** A hex digest with Web Crypto. */
+export function hexDigest(algo: 'SHA-1' | 'SHA-256', data: Uint8Array | string): Promise<string>;

package/src/platform/bytes.js

@@ -0,0 +1,103 @@
+/**
+ * Byte helpers that work the same in Node, browsers and Workers (no
+ * `Buffer`). Where Node's `Buffer` is present it's used for speed; the
+ * output is identical either way.
+ *
+ * @module bytes
+ */
+
+const B = /** @type {any} */ (globalThis).Buffer;
+
+/**
+ * Bytes as a `Uint8Array` view.
+ *
+ * @param {Uint8Array | ArrayBuffer | ArrayBufferView} v
+ * @returns {Uint8Array}
+ */
+export function u8(v) {
+  if (v instanceof Uint8Array) return v;
+  if (v instanceof ArrayBuffer) return new Uint8Array(v);
+  if (ArrayBuffer.isView(v)) return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+  throw new TypeError('Expected bytes (Uint8Array or ArrayBuffer)');
+}
+
+/** @param {unknown} v @returns {v is Uint8Array | ArrayBuffer} */
+export const isBytes = (v) => v instanceof Uint8Array || v instanceof ArrayBuffer || ArrayBuffer.isView(v);
+
+/**
+ * Base64-encode bytes.
+ *
+ * @param {Uint8Array | ArrayBuffer} bytes
+ * @returns {string}
+ */
+export function toBase64(bytes) {
+  const b = u8(bytes);
+  if (B) return B.from(b.buffer, b.byteOffset, b.byteLength).toString('base64');
+  let out = '';
+  for (let i = 0; i < b.length; i += 0x8000) out += String.fromCharCode.apply(null, /** @type {any} */ (b.subarray(i, i + 0x8000)));
+  return btoa(out);
+}
+
+/**
+ * Decode base64.
+ *
+ * @param {string} s
+ * @returns {Uint8Array}
+ */
+export function fromBase64(s) {
+  if (B) return new Uint8Array(B.from(s, 'base64'));
+  const bin = atob(s.replace(/\s+/g, ''));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/** @param {Uint8Array} b @returns {string} Each byte as one char. */
+export function latin1(b) {
+  let s = '';
+  for (let i = 0; i < b.length; i++) s += String.fromCharCode(b[i]);
+  return s;
+}
+
+/** @param {Uint8Array | ArrayBuffer} b @returns {string} */
+export const utf8 = (b) => new TextDecoder().decode(u8(b));
+
+/** @param {string} s @returns {Uint8Array} */
+export const encodeUtf8 = (s) => new TextEncoder().encode(s);
+
+/**
+ * Join byte arrays.
+ *
+ * @param {Uint8Array[]} parts
+ * @returns {Uint8Array}
+ */
+export function concat(parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+}
+
+/**
+ * Decode a `data:` URI.
+ *
+ * @param {string} uri
+ * @returns {Uint8Array | undefined} Its bytes, or undefined when it isn't one.
+ */
+export function fromDataUri(uri) {
+  const m = /^data:([^,]*?),(.*)$/s.exec(uri);
+  if (!m) return undefined;
+  return /;base64$/i.test(m[1]) ? fromBase64(m[2]) : encodeUtf8(decodeURIComponent(m[2]));
+}
+
+/**
+ * Hex digest with Web Crypto (Node 20+, browsers, Workers).
+ *
+ * @param {'SHA-1' | 'SHA-256'} algo
+ * @param {Uint8Array | string} data
+ * @returns {Promise<string>}
+ */
+export async function hexDigest(algo, data) {
+  const buf = await globalThis.crypto.subtle.digest(algo, typeof data === 'string' ? encodeUtf8(data) : u8(data));
+  return Array.from(new Uint8Array(buf), (x) => x.toString(16).padStart(2, '0')).join('');
+}

package/src/platform/compress.d.ts

@@ -0,0 +1,12 @@
+// zlib on every platform.
+
+/** zlib-deflate synchronously (Node), else undefined. */
+export function deflateSync(data: Uint8Array): Uint8Array | undefined;
+/** zlib-deflate (Node's zlib, else CompressionStream). */
+export function deflate(data: Uint8Array): Promise<Uint8Array>;
+/** zlib-inflate. */
+export function inflate(data: Uint8Array): Promise<Uint8Array>;
+/** Brotli-decompress synchronously (Node), else undefined. */
+export function unbrotliSync(data: Uint8Array): Uint8Array | undefined;
+/** Brotli-decompress (Node's zlib, else DecompressionStream('brotli') where there is one), else undefined. */
+export function unbrotli(data: Uint8Array): Promise<Uint8Array | undefined>;

package/src/platform/compress.js

@@ -0,0 +1,81 @@
+/**
+ * zlib deflate and inflate: Node's zlib, else `CompressionStream` and
+ * `DecompressionStream` (browsers, Workers). For PNG textures and WOFF.
+ *
+ * @module platform/compress
+ */
+
+import { node } from './node.js';
+
+/**
+ * zlib-deflate synchronously, when the platform can (Node).
+ *
+ * @param {Uint8Array} data
+ * @returns {Uint8Array | undefined}
+ */
+export function deflateSync(data) {
+  const z = node('zlib');
+  return z ? z.deflateSync(data, { level: 9 }) : undefined;
+}
+
+/**
+ * zlib-deflate: Node's zlib, else `CompressionStream` (browsers, Workers).
+ * The two may differ in bytes but both are valid zlib streams.
+ *
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array>}
+ */
+export async function deflate(data) {
+  return deflateSync(data) ?? stream(data, new CompressionStream('deflate'));
+}
+
+/**
+ * zlib-inflate (WOFF tables).
+ *
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array>}
+ */
+export async function inflate(data) {
+  const z = node('zlib');
+  return z ? z.inflateSync(data) : stream(data, new DecompressionStream('deflate'));
+}
+
+/**
+ * @param {Uint8Array} data
+ * @param {TransformStream} ts
+ * @returns {Promise<Uint8Array>}
+ */
+async function stream(data, ts) {
+  const out = new Response(new Blob([/** @type {any} */ (data)]).stream().pipeThrough(ts));
+  return new Uint8Array(await out.arrayBuffer());
+}
+
+/**
+ * Brotli-decompress synchronously, when the platform can (Node's zlib).
+ *
+ * @param {Uint8Array} data
+ * @returns {Uint8Array | undefined}
+ */
+export function unbrotliSync(data) {
+  const z = node('zlib');
+  if (!z?.brotliDecompressSync) return undefined;
+  const out = z.brotliDecompressSync(data);
+  return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+}
+
+/**
+ * Brotli-decompress (WOFF2): Node's zlib, else `DecompressionStream('brotli')`
+ * where the runtime has it. Undefined where neither can.
+ *
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array | undefined>}
+ */
+export async function unbrotli(data) {
+  const sync = unbrotliSync(data);
+  if (sync) return sync;
+  try {
+    return await stream(data, new DecompressionStream(/** @type {any} */ ('brotli')));
+  } catch {
+    return undefined;
+  }
+}

package/src/platform/harfbuzz.d.ts

@@ -0,0 +1,9 @@
+// HarfBuzz, loaded once.
+
+/** The harfbuzzjs module (its own types need Emscripten's; covers uses a handful of its classes). */
+export type HarfBuzzModule = object;
+
+/** harfbuzzjs, with its wasm from `configure({ harfbuzz })` when given. */
+export function harfbuzz(): Promise<HarfBuzzModule>;
+/** harfbuzzjs where it runs (and isn't switched off), else undefined: text then uses the JavaScript outliner. */
+export function shaperModule(): Promise<HarfBuzzModule | undefined>;