@arraypress/covers 1.0.0 → 1.3.1

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/paint/index.d.ts

@@ -0,0 +1,49 @@
+// Paints: a colour, 'none', or a gradient over a shape's bounds.
+import type { Color, Length } from '../index.js';
+
+/** A gradient over a shape's bounds. */
+export interface GradientPaint {
+  type: 'linear' | 'radial';
+  colors: Color[];
+  stops?: number[];
+  opacities?: number[];
+  /** Linear: CSS degrees. Default 180 (top to bottom). */
+  angle?: number;
+  /** `'reflect'` / `'repeat'` with a `length` run: holographic foil, stripes. */
+  spread?: 'pad' | 'reflect' | 'repeat';
+  length?: Length;
+  cx?: number; cy?: number; r?: Length; fx?: number; fy?: number;
+  /** Radial: elliptical radii (lengths, or fractions ≤ 1 of the box). */
+  rx?: Length; ry?: Length;
+}
+
+/** A pattern repeated over a shape. */
+export interface TilePaint {
+  type: 'tile';
+  kind?: 'checker' | 'stripes' | 'dots' | 'grid' | 'custom';
+  /** One cell (or `[width, height]`). Default `'4vmin'`. */
+  size?: Length | [Length, Length];
+  /** `[ground, ink]`; the ground may be `'none'`. */
+  colors?: [Color | 'none', Color];
+  /** The stripe, dot or line share of a cell. */
+  ratio?: number;
+  /** Degrees. */
+  angle?: number;
+  /** `custom`: the tile's markup (sanitised). */
+  markup?: string;
+}
+
+/** A named paint (`'chrome'`, `'steel'`, `'gold'`): a reflected-horizon gradient with its keyline; fields override it. */
+export interface PresetPaint extends Partial<Omit<GradientPaint, 'type'>> {
+  preset: 'chrome' | 'steel' | 'gold';
+  type?: 'linear' | 'radial';
+  /** The keyline it brings (`false` for none). */
+  keyline?: false | { color: Color; width: Length }[];
+}
+
+/** A fill or stroke: a colour, `'none'`, a gradient, a tile or a preset. */
+export type Paint = Color | 'none' | GradientPaint | TilePaint | PresetPaint;
+
+
+/** A paint as an SVG fill value, plus any gradient it needs in `<defs>`. */
+export function paint(v: Paint | undefined, fallback: string, o: { id: string; box: { x: number; y: number; width: number; height: number }; canvas: { width: number; height: number } }): { defs: string; value: string };

package/src/paint/index.js

@@ -0,0 +1,66 @@
+/**
+ * Paints: a colour, `'none'`, a linear or radial gradient laid over a
+ * shape's bounds (reflected foil with `spread` and `length`; elliptical
+ * radial fields with `rx`/`ry`), a `tile` pattern (checker, stripes, dots,
+ * grid or a custom tile), or a named preset (`'chrome'`).
+ *
+ * @module paint
+ */
+
+import { attrs, num } from '@logomarks/image-effects/svg';
+import { len } from '@logomarks/image-effects/length';
+import { toHex } from '@logomarks/image-effects/color';
+import { PRESETS } from './presets.js';
+import { tile } from './tile.js';
+
+/**
+ * A fill or stroke: a colour, `'none'`, a gradient object
+ * `{ type: 'linear' | 'radial', colors, stops?, opacities?, angle?, spread?: 'pad' | 'reflect' | 'repeat', length?, cx?, cy?, r?, rx?, ry? }`,
+ * a tile `{ type: 'tile', kind, size, colors, … }`, or a preset
+ * `{ preset: 'chrome', … }` (its fields override the preset's), laid over
+ * `box` (the shape's bounds, else the canvas). `length` sets a linear
+ * gradient's run in px (with `reflect` it repeats: holographic foil).
+ *
+ * @param {any} v - The paint.
+ * @param {string} fallback - Used when `v` is unset.
+ * @param {{ id: string, box: { x: number, y: number, width: number, height: number }, canvas: { width: number, height: number } }} o
+ * @returns {{ defs: string, value: string }}
+ */
+export function paint(v, fallback, o) {
+  if (v == null || v === '') return { defs: '', value: fallback };
+  if (typeof v === 'string') return { defs: '', value: v === 'none' || v === 'currentColor' || v.startsWith('url(') ? v : toHex(v) };
+  if (v.preset != null) {
+    const base = PRESETS[v.preset];
+    if (!base) throw new TypeError(`Unknown paint preset "${v.preset}" (${Object.keys(PRESETS).join(', ')})`);
+    const { preset, keyline, ...own } = v;
+    return paint({ ...base, ...own }, fallback, o);
+  }
+  if (v.type === 'tile') return tile(v, o);
+  const colors = (v.colors ?? []).map(toHex);
+  if (colors.length < 2) throw new TypeError('A gradient paint needs two or more colours');
+  const offsets = v.stops ?? colors.map((/** @type {string} */ _, /** @type {number} */ i) => i / (colors.length - 1));
+  const stops = colors.map((c, i) => `<stop${attrs({ offset: num(offsets[i], 4), 'stop-color': c, 'stop-opacity': v.opacities?.[i] != null && v.opacities[i] < 1 ? num(v.opacities[i], 3) : undefined })}/>`).join('');
+  const { box } = o;
+  const spread = v.spread && v.spread !== 'pad' ? v.spread : undefined;
+  if (v.type === 'radial') {
+    const cx = box.x + (v.cx ?? 0.5) * box.width;
+    const cy = box.y + (v.cy ?? 0.5) * box.height;
+    // Elliptical: rx and ry (lengths, or fractions ≤ 1 of the box's width and height).
+    const radius = (/** @type {any} */ r, /** @type {number} */ side) => (typeof r === 'number' && r <= 1 ? r * side : len(r, o.canvas));
+    const rx = v.rx != null ? radius(v.rx, box.width) : undefined;
+    const ry = v.ry != null ? radius(v.ry, box.height) : undefined;
+    const r = rx ?? ry ?? (v.r != null ? len(v.r, o.canvas) : Math.hypot(box.width, box.height) / 2);
+    const squash = rx != null && ry != null && rx > 0 ? ry / rx : 1;
+    const gradientTransform = squash !== 1 ? `translate(${num(cx)} ${num(cy)}) scale(1 ${num(squash, 5)}) translate(${num(-cx)} ${num(-cy)})` : undefined;
+    return { defs: `<radialGradient${attrs({ id: o.id, gradientUnits: 'userSpaceOnUse', cx, cy, r, fx: v.fx != null ? box.x + v.fx * box.width : undefined, fy: v.fy != null ? box.y + v.fy * box.height : undefined, spreadMethod: spread, gradientTransform })}>${stops}</radialGradient>`, value: `url(#${o.id})` };
+  }
+  const a = ((v.angle ?? 180) * Math.PI) / 180;
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  const L = v.length != null ? len(v.length, o.canvas) : Math.abs(box.width * Math.sin(a)) + Math.abs(box.height * Math.cos(a));
+  const dx = (Math.sin(a) * L) / 2;
+  const dy = (-Math.cos(a) * L) / 2;
+  const x1 = v.length != null ? box.x : cx - dx;
+  const y1 = v.length != null ? box.y : cy - dy;
+  return { defs: `<linearGradient${attrs({ id: o.id, gradientUnits: 'userSpaceOnUse', x1, y1, x2: x1 + 2 * dx, y2: y1 + 2 * dy, spreadMethod: spread })}>${stops}</linearGradient>`, value: `url(#${o.id})` };
+}

package/src/paint/presets.d.ts

@@ -0,0 +1,10 @@
+// Named paints: chrome, steel and gold, painted as a reflected horizon.
+import type { GradientPaint } from './index.js';
+import type { Color, Length } from '../index.js';
+
+/** Paint presets, by name. */
+export const PRESETS: Readonly<Record<'chrome' | 'steel' | 'gold', Readonly<GradientPaint>>>;
+/** The keyline metal paints bring: a thin light edge, then a dark one. */
+export const KEYLINE: readonly { readonly color: Color; readonly width: Length }[];
+/** The keyline a fill brings with it (a preset's, unless `keyline: false`). */
+export function presetStrokes(fill: unknown): { color: Color; width: Length }[] | undefined;

package/src/paint/presets.js

@@ -0,0 +1,47 @@
+/**
+ * Named paints. `chrome` is Y2K chrome as it's painted by hand: a
+ * reflected horizon, not a lighting filter. Sky at the top, a sharp dark
+ * horizon a little past the middle, warm ground below it, and a light
+ * bounce at the very bottom. Pair it with a light keyline (`strokes`).
+ *
+ * @module paint/presets
+ */
+
+/** Paint presets, by name. A paint `{ preset, …fields }` overrides any of them. */
+export const PRESETS = Object.freeze({
+  chrome: Object.freeze({
+    type: 'linear',
+    angle: 180,
+    colors: ['#f4f8ff', '#9fc3ef', '#e8f1ff', '#2b3446', '#7a5a3c', '#d9b48a', '#fff6e6'],
+    stops: [0, 0.34, 0.545, 0.555, 0.62, 0.86, 1],
+  }),
+  /** The same horizon, cooler: steel. */
+  steel: Object.freeze({
+    type: 'linear',
+    angle: 180,
+    colors: ['#ffffff', '#b9c4d4', '#eef2f7', '#30363f', '#5d6672', '#c7ced8', '#ffffff'],
+    stops: [0, 0.34, 0.545, 0.555, 0.62, 0.86, 1],
+  }),
+  /** Gold leaf: the horizon in warm metal. */
+  gold: Object.freeze({
+    type: 'linear',
+    angle: 180,
+    colors: ['#fff6d6', '#e9c46a', '#fff1c2', '#6b4210', '#a8701f', '#f2cf73', '#fff8e0'],
+    stops: [0, 0.34, 0.545, 0.555, 0.62, 0.86, 1],
+  }),
+});
+
+/** The keyline that goes round metal paints: a thin light edge, then a dark one (widest first, under the fill). */
+export const KEYLINE = Object.freeze([Object.freeze({ color: '#0b0f18', width: '0.9vmin' }), Object.freeze({ color: '#ffffff', width: '0.35vmin' })]);
+
+/**
+ * The keyline a fill brings with it: a preset paint's, unless the paint
+ * says `keyline: false` (or gives its own `keyline` list).
+ *
+ * @param {any} fill
+ * @returns {{ color: string, width: string | number }[] | undefined}
+ */
+export function presetStrokes(fill) {
+  if (!fill || typeof fill !== 'object' || fill.preset == null || fill.keyline === false) return undefined;
+  return Array.isArray(fill.keyline) ? fill.keyline : [...KEYLINE];
+}

package/src/paint/tile.d.ts

@@ -0,0 +1,7 @@
+// Tile paints.
+import type { TilePaint } from './index.js';
+
+/** Tile kinds. */
+export const TILES: readonly ('checker' | 'stripes' | 'dots' | 'grid' | 'custom')[];
+/** A tile paint as a `<pattern>` and its fill value. */
+export function tile(v: TilePaint, o: { id: string; box: { x: number; y: number; width: number; height: number }; canvas: { width: number; height: number } }): { defs: string; value: string };

package/src/paint/tile.js

@@ -0,0 +1,55 @@
+/**
+ * Tile paints: a pattern repeated over a shape (checker, stripes, dots,
+ * grid), or a custom tile of markup.
+ *
+ * @module paint/tile
+ */
+
+import { attrs, num } from '@logomarks/image-effects/svg';
+import { len } from '@logomarks/image-effects/length';
+import { toHex } from '@logomarks/image-effects/color';
+import { sanitize } from '../layers/svg.js';
+
+/** Tile kinds. */
+export const TILES = Object.freeze(['checker', 'stripes', 'dots', 'grid', 'custom']);
+
+/**
+ * A tile paint as a `<pattern>`: `{ type: 'tile', kind, size, colors: [ground, ink], ratio, angle, markup }`.
+ * `size` is one cell (a length, default `'4vmin'`); `ratio` the stripe,
+ * dot or line share of it; `angle` turns the pattern; a `custom` tile draws
+ * `markup` (sanitised) in a `size` square (or `[width, height]`). The
+ * pattern starts at the shape's top-left corner. `colors[0]` may be
+ * `'none'` for a transparent ground.
+ *
+ * @param {any} v
+ * @param {{ id: string, box: { x: number, y: number, width: number, height: number }, canvas: { width: number, height: number } }} o
+ * @returns {{ defs: string, value: string }}
+ */
+export function tile(v, o) {
+  const kind = v.kind ?? 'checker';
+  if (!TILES.includes(kind)) throw new TypeError(`Unknown tile kind "${kind}" (${TILES.join(', ')})`);
+  const [sw, sh] = Array.isArray(v.size) ? v.size.map((/** @type {any} */ s) => len(s, o.canvas)) : [len(v.size, o.canvas, '4vmin'), len(v.size, o.canvas, '4vmin')];
+  const [ground, ink] = [v.colors?.[0] ?? '#ffffff', v.colors?.[1] ?? '#111111'].map((c) => (c === 'none' ? 'none' : toHex(c)));
+  const ratio = v.ratio ?? (kind === 'dots' ? 0.6 : kind === 'grid' ? 0.08 : 0.5);
+  let w = sw;
+  let h = sh;
+  let body = ground === 'none' ? '' : `<rect${attrs({ width: num(kind === 'checker' ? 2 * sw : sw, 4), height: num(kind === 'checker' ? 2 * sh : sh, 4), fill: ground })}/>`;
+  if (kind === 'checker') {
+    w = 2 * sw;
+    h = 2 * sh;
+    body += `<path${attrs({ d: `M0 0h${num(sw, 4)}v${num(sh, 4)}h${num(-sw, 4)}ZM${num(sw, 4)} ${num(sh, 4)}h${num(sw, 4)}v${num(sh, 4)}h${num(-sw, 4)}Z`, fill: ink })}/>`;
+  } else if (kind === 'stripes') {
+    body += `<rect${attrs({ width: num(sw * ratio, 4), height: num(sh, 4), fill: ink })}/>`;
+  } else if (kind === 'dots') {
+    body += `<ellipse${attrs({ cx: num(sw / 2, 4), cy: num(sh / 2, 4), rx: num((sw * ratio) / 2, 4), ry: num((sh * ratio) / 2, 4), fill: ink })}/>`;
+  } else if (kind === 'grid') {
+    body += `<path${attrs({ d: `M0 0H${num(sw, 4)}M0 0V${num(sh, 4)}`, stroke: ink, 'stroke-width': num(Math.min(sw, sh) * ratio * 2, 4), fill: 'none' })}/>`;
+  } else {
+    body += sanitize(String(v.markup ?? ''));
+  }
+  const turn = v.angle ? ` rotate(${num(v.angle, 3)})` : '';
+  return {
+    defs: `<pattern${attrs({ id: o.id, patternUnits: 'userSpaceOnUse', width: num(w, 4), height: num(h, 4), patternTransform: `translate(${num(o.box.x)} ${num(o.box.y)})${turn}` })}>${body}</pattern>`,
+    value: `url(#${o.id})`,
+  };
+}

package/src/palette.js

@@ -20,7 +20,7 @@
  */
 
 import { relativeLuminance, contrastRatio, readableOn, readableText } from '@arraypress/color-utils';
-import { toHex, toOklch, fromOklch, mixOklab } from './color.js';
+import { toHex, toOklch, fromOklch, mixOklab } from '@logomarks/image-effects/color';
 
 /**
  * Curated presets. Each is a full palette; the light ones pair with the

package/src/platform/files.d.ts

@@ -0,0 +1,6 @@
+// Files read from disk in Node.
+
+/** Read a text file synchronously (Node). */
+export function readTextSync(path: string | URL): string;
+/** A file shipped with the package, from disk (Node), or undefined. */
+export function packageFileSync(rel: string): Uint8Array | undefined;

package/src/platform/files.js

@@ -0,0 +1,41 @@
+/**
+ * Files read from disk in Node: a recipe's JSON, and the fonts that ship
+ * with this package. Node's built-ins come from the image-effects platform
+ * adapter (`process.getBuiltinModule`, or what `@arraypress/covers/node`
+ * installs).
+ *
+ * @module platform/files
+ */
+
+import { node } from '@logomarks/image-effects/platform';
+
+/** This module was loaded from disk (Node, Deno, Bun), not a bundle or a page. */
+const FROM_DISK = String(import.meta.url).startsWith('file:');
+
+/**
+ * Read a text file synchronously (Node only; `loadRecipe`).
+ *
+ * @param {string | URL} path
+ * @returns {string}
+ */
+export function readTextSync(path) {
+  const fs = node('fs');
+  if (!fs) throw new Error('Reading a file synchronously needs Node. In a browser or Worker, fetch the JSON and pass it to defineRecipe().');
+  return fs.readFileSync(path, 'utf8');
+}
+
+/**
+ * Read a file that ships with this package (Node, from disk), or undefined.
+ *
+ * @param {string} rel - Relative to the package root (`'fonts/inter-latin-400.woff'`).
+ * @returns {Uint8Array | undefined}
+ */
+export function packageFileSync(rel) {
+  const fs = node('fs');
+  if (!fs || !FROM_DISK) return undefined;
+  try {
+    return fs.readFileSync(new URL(`../../${rel}`, import.meta.url));
+  } 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>;

package/src/platform/harfbuzz.js

@@ -0,0 +1,80 @@
+/**
+ * HarfBuzz, loaded once and lazily, with its WebAssembly from wherever
+ * `configure({ harfbuzz })` says. `#harfbuzz` is harfbuzzjs, except under
+ * the `workerd` / `worker` conditions, where it's a stub that fails, and
+ * text falls back to the JavaScript outliner.
+ *
+ * @module platform/harfbuzz
+ */
+
+import { isBytes } from '@logomarks/image-effects/platform';
+import { settings } from './settings.js';
+import { loadBytes, asBytes } from './load.js';
+
+/** @type {Promise<any> | undefined} */
+let hbPromise;
+
+/**
+ * Load harfbuzzjs. With `configure({ harfbuzz })` its WebAssembly comes from
+ * there (a URL, bytes, a compiled Module or a Response) instead of the file
+ * next to harfbuzzjs, which a bundler may not have copied.
+ *
+ * harfbuzzjs creates small wasm trampolines at runtime (Emscripten's
+ * `addFunction`), which Cloudflare Workers forbid; there text falls back to
+ * the built-in JavaScript outliner (`fonts/sfnt.js`).
+ *
+ * @returns {Promise<any>} The harfbuzzjs module.
+ */
+export function harfbuzz() {
+  hbPromise ??= (async () => {
+    const src = await settings.harfbuzz;
+    if (src == null) return import('#harfbuzz');
+    const W = /** @type {any} */ (WebAssembly);
+    const { instantiate, instantiateStreaming } = W;
+    /** @param {any} imports */
+    const ours = async (imports) => {
+      if (src instanceof WebAssembly.Module) return { module: src, instance: await instantiate(src, imports) };
+      const bytes = isBytes(src) || typeof src?.arrayBuffer === 'function' ? await asBytes(src) : await loadBytes(src, 'file');
+      return instantiate(bytes, imports);
+    };
+    let used = false;
+    // harfbuzzjs instantiates once, on import: hand it our module then.
+    W.instantiateStreaming = (/** @type {any} */ response, /** @type {any} */ imports) => {
+      if (used) return instantiateStreaming(response, imports);
+      used = true;
+      Promise.resolve(response).catch(() => {});
+      return ours(imports);
+    };
+    W.instantiate = (/** @type {any} */ source, /** @type {any} */ imports) => {
+      if (used || !(source instanceof Uint8Array || source instanceof ArrayBuffer)) return instantiate(source, imports);
+      used = true;
+      return ours(imports);
+    };
+    try {
+      return await import('#harfbuzz');
+    } finally {
+      W.instantiate = instantiate;
+      W.instantiateStreaming = instantiateStreaming;
+    }
+  })();
+  return hbPromise;
+}
+
+/**
+ * Whether outlines come from HarfBuzz: `shaper: 'harfbuzz'`, or `'auto'`
+ * where HarfBuzz loads (everywhere but Workers).
+ *
+ * @returns {Promise<any>} harfbuzzjs, or undefined for the JS outliner.
+ */
+export async function shaperModule() {
+  if (settings.shaper === 'js') return undefined;
+  try {
+    return await harfbuzz();
+  } catch (err) {
+    if (settings.shaper === 'harfbuzz') throw err;
+    hbPromise = Promise.reject(err);
+    hbPromise.catch(() => {});
+    return undefined;
+  }
+}
+

package/src/platform/index.d.ts

@@ -0,0 +1,8 @@
+// The platform adapter.
+export { node, installNode, isNode, deflateSync, deflate, inflate, unbrotli, unbrotliSync, u8, isBytes, toBase64, fromBase64, latin1, utf8, encodeUtf8, concat, fromDataUri, hexDigest } from '@logomarks/image-effects/platform';
+export type { NodeModules } from '@logomarks/image-effects/platform';
+export { readTextSync, packageFileSync } from './files.js';
+export { settings, configure, registry } from './settings.js';
+export type { Settings } from './settings.js';
+export { loadBytes } from './load.js';
+export { harfbuzz, shaperModule } from './harfbuzz.js';

package/src/platform/index.js

@@ -0,0 +1,15 @@
+/**
+ * The platform: everything that differs between Node, a browser and a
+ * Cloudflare Worker, behind one small adapter. Node's built-ins, zlib and
+ * the byte helpers are image-effects' (one registry, so
+ * `@arraypress/covers/node` installs for both); settings, loading, files
+ * and HarfBuzz are covers' own. Nothing here imports a `node:` module.
+ *
+ * @module platform
+ */
+
+export { node, installNode, isNode, deflateSync, deflate, inflate, unbrotli, unbrotliSync, u8, isBytes, toBase64, fromBase64, latin1, utf8, encodeUtf8, concat, fromDataUri, hexDigest } from '@logomarks/image-effects/platform';
+export { readTextSync, packageFileSync } from './files.js';
+export { settings, configure, registry } from './settings.js';
+export { loadBytes } from './load.js';
+export { harfbuzz, shaperModule } from './harfbuzz.js';

package/src/platform/load.d.ts

@@ -0,0 +1,6 @@
+// Loading bytes from anything.
+
+/** Load an image, font, audio file or icon set. */
+export function loadBytes(src: unknown, kind?: 'image' | 'font' | 'audio' | 'icons' | 'file'): Promise<Uint8Array>;
+/** Bytes from what a loader returned (bytes, a Blob or a Response). */
+export function asBytes(v: unknown): Promise<Uint8Array>;