@arraypress/covers 1.0.0 → 1.1.0

package/src/layers/util.js

@@ -0,0 +1,48 @@
+/**
+ * Small helpers the poster layers share: coordinates in px or `'%'`, the
+ * opacity/blend wrapper, and the text of a string-or-object option.
+ *
+ * @module layers/util
+ */
+
+import { attrs, esc } from '../svg.js';
+import { len } from '../geometry.js';
+
+/**
+ * A coordinate: px as a number, `'50%'` of the canvas along `axis`, or a
+ * length (`'4vmin'`).
+ *
+ * @param {unknown} v
+ * @param {'x' | 'y'} axis
+ * @param {{ width: number, height: number }} canvas
+ * @returns {number} px
+ */
+export function pos(v, axis, canvas) {
+  if (typeof v === 'string' && v.trim().endsWith('%')) return (parseFloat(v) / 100) * (axis === 'x' ? canvas.width : canvas.height);
+  return len(/** @type {any} */ (v), canvas, 0);
+}
+
+/**
+ * Wrap markup in a group with the layer's `opacity` and `blend` (only when
+ * it has them).
+ *
+ * @param {{ opacity?: number, blend?: string }} layer
+ * @param {string} body
+ * @returns {string}
+ */
+export function wrap(layer, body) {
+  const a = attrs({ opacity: layer.opacity != null && layer.opacity < 1 ? Math.max(0, layer.opacity) : undefined, style: layer.blend && layer.blend !== 'normal' ? `mix-blend-mode:${esc(layer.blend)}` : undefined });
+  return a ? `<g${a}>${body}</g>` : body;
+}
+
+/**
+ * The text of a string-or-object option (`'Hello'` or `{ content: 'Hello' }`).
+ *
+ * @param {unknown} v
+ * @returns {string | undefined}
+ */
+export function contentOf(v) {
+  if (typeof v === 'string' || typeof v === 'number') return String(v);
+  if (v && typeof v === 'object' && 'content' in v) return /** @type {any} */ (v).content;
+  return undefined;
+}

package/src/layers.js

@@ -14,17 +14,24 @@
  * @module layers
  */
 
-import { readFile } from 'node:fs/promises';
+import { loadBytes } from './platform/index.js';
+import { toBase64, latin1, utf8 } from './platform/bytes.js';
 import { attrs, esc, layerAttrs, num } from './svg.js';
 import { len, place, anchorAlign, unit, regionPx } from './geometry.js';
 import { toHex, mixOklab, toOklch, fromOklch } from './color.js';
 import { harfbuzz, loadFont, pickFont } from './fonts.js';
-import { layout, runPath } from './text.js';
+import { layout, runPath, caseText } from './text.js';
 import { resolveIcon, parseSvgIcon } from './icons.js';
 import { gridPath } from './grid.js';
 import { diagram } from './diagram.js';
 import { paper, scribble } from './handmade.js';
 import { ink, dither, contour, waveform, tiles, rule } from './print.js';
+import { typeset, wantsType } from './type/index.js';
+import { recordLayout } from './type/layout-ref.js';
+import { shape, svg, table, barcode, perforation, tear, texture } from './layers/index.js';
+import { pos } from './layers/util.js';
+import { paint } from './effects/paint.js';
+import { imageSize } from './lint/image-size.js';
 
 /**
  * Everything a layer renderer needs.
@@ -406,35 +413,31 @@ export function stripes(layer, ctx) {
  */
 export async function image(layer, ctx) {
   if (!layer.src) throw new TypeError('An image layer needs a src (a file path or bytes)');
-  const box = regionPx(layer.region, ctx.canvas);
+  const L = /** @type {any} */ (layer);
+  // 1.1: an explicit box in px (x, y, width, height), as an SVG <image> would take.
+  const box = L.x != null || L.y != null || L.width != null || L.height != null
+    ? { x: pos(L.x ?? 0, 'x', ctx.canvas), y: pos(L.y ?? 0, 'y', ctx.canvas), width: L.width != null ? pos(L.width, 'x', ctx.canvas) : ctx.width, height: L.height != null ? pos(L.height, 'y', ctx.canvas) : ctx.height }
+    : regionPx(layer.region, ctx.canvas);
   const fit = layer.fit ?? 'cover';
   const focus = layer.focus ?? 'center';
-  let bytes = typeof layer.src === 'string' ? await readSource(layer.src) : layer.src;
+  let bytes = typeof layer.src === 'string' || layer.src instanceof URL ? await readSource(layer.src) : await loadBytes(layer.src, 'image');
   let mime = sniff(bytes);
-  let preserve = `${alignFor(focus)} ${fit === 'contain' ? 'meet' : 'slice'}`;
+  let preserve = fit === 'stretch' ? 'none' : `${alignFor(focus)} ${fit === 'contain' ? 'meet' : 'slice'}`;
   let sharpBlurred = false;
 
+  /** Source pixels and what was embedded, for lint. */
+  let source = imageSize(bytes);
+  let embedded = source;
   if (ctx.sharp && mime !== 'image/svg+xml') {
-    const w = Math.round(box.width);
-    const hgt = Math.round(box.height);
-    const position = typeof focus === 'string' && ['attention', 'entropy'].includes(focus) ? focus : (POSITIONS[focus] ?? 'centre');
-    let img = ctx.sharp(bytes).rotate().resize(w, hgt, { fit, position, background: { r: 0, g: 0, b: 0, alpha: 0 } });
-    // Stretch the tones first, so a duotone spans both of its colours.
-    if (layer.normalize ?? Boolean(layer.duotone || layer.grayscale)) img = img.normalise();
-    // Blur here rather than in SVG: sharp clamps at the edges, where an SVG
-    // blur (in librsvg) fades the photo to transparent.
-    if (layer.blur) {
-      img = img.blur(Math.max(0.3, len(layer.blur, ctx.canvas)));
-      sharpBlurred = true;
-    }
-    const meta = await ctx.sharp(bytes).metadata();
-    const alpha = meta.hasAlpha || fit === 'contain';
-    bytes = await (alpha ? img.png() : img.jpeg({ quality: 90 })).toBuffer();
-    mime = alpha ? 'image/png' : 'image/jpeg';
+    const out = await resample(ctx, bytes, box, fit, focus, layer);
+    ({ bytes, mime, source, embedded } = out);
+    sharpBlurred = Boolean(layer.blur);
     preserve = 'none';
   } else if (!mime) {
     throw new TypeError('Unrecognised image format (use PNG, JPEG, WebP, AVIF, GIF or SVG)');
   }
+  const res = /** @type {any} */ (ctx).res ?? 1;
+  /** @type {any} */ (ctx).report?.({ kind: 'image', id: layer.id, drawn: { width: box.width * res, height: box.height * res }, source, embedded, fit });
 
   const p = ctx.palette;
   const id = `${ctx.id}f`;
@@ -454,7 +457,7 @@ export async function image(layer, ctx) {
     ? `<filter${attrs({ id, x: 0, y: 0, width: '100%', height: '100%', 'color-interpolation-filters': 'sRGB' })}>${filters.join('')}</filter>`
     : '';
 
-  let body = `<image${attrs({ x: box.x, y: box.y, width: box.width, height: box.height, preserveAspectRatio: preserve, filter: defs ? `url(#${id})` : undefined, href: `data:${mime};base64,${Buffer.from(bytes).toString('base64')}` })}/>`;
+  let body = `<image${attrs({ x: box.x, y: box.y, width: box.width, height: box.height, preserveAspectRatio: preserve, filter: defs ? `url(#${id})` : undefined, href: `data:${mime};base64,${toBase64(bytes)}` })}/>`;
   if (layer.tint) {
     const t = typeof layer.tint === 'string' ? { color: layer.tint } : layer.tint;
     body += `<rect${attrs({ x: box.x, y: box.y, width: box.width, height: box.height, fill: color(t.color, p.accent), opacity: t.amount ?? 0.35, style: `mix-blend-mode:${t.blend ?? 'multiply'}` })}/>`;
@@ -462,6 +465,64 @@ export async function image(layer, ctx) {
   return { defs, body: wrap(layer, body) };
 }
 
+/** Embeds up to this many pixels at top level are sized to their box, as in 1.0, even past the source's pixels. */
+const CAP_FREE = 4e6;
+
+/**
+ * Resize and crop an image to its box with sharp, at the pixels it's drawn
+ * at (its box times the group and transform scale above it), never above
+ * the source's own pixels (the SVG scales it up instead, so a small photo
+ * isn't embedded at output size). Opaque results are JPEG, even from a
+ * source with an unused alpha channel; PNG only where there's transparency.
+ *
+ * @param {RenderContext} ctx
+ * @param {Uint8Array} bytes
+ * @param {{ width: number, height: number }} box
+ * @param {string} fit
+ * @param {any} focus
+ * @param {import('./index.js').ImageLayer} layer
+ * @returns {Promise<{ bytes: Uint8Array, mime: string, source: { width: number, height: number } | undefined, embedded: { width: number, height: number } }>}
+ */
+async function resample(ctx, bytes, box, fit, focus, layer) {
+  const sharp = /** @type {any} */ (ctx.sharp);
+  const meta = await sharp(bytes).metadata();
+  // EXIF orientations 5–8 turn the image a quarter.
+  const [sw, sh] = (meta.orientation ?? 1) >= 5 ? [meta.height, meta.width] : [meta.width, meta.height];
+  const res = /** @type {any} */ (ctx).res ?? 1;
+  let w = box.width * res;
+  let hgt = box.height * res;
+  // How much the fit would enlarge the source: past 1, embed at the source's
+  // own size. (A top-level image under 4 MP keeps 1.0's box-sized embed, so
+  // 1.0 covers stay byte-identical.)
+  const cap = res !== 1 || w * hgt > CAP_FREE;
+  const grow = !cap || fit === 'stretch' ? 1 : fit === 'contain' ? Math.min(w / sw, hgt / sh) : Math.max(w / sw, hgt / sh);
+  if (grow > 1) { w /= grow; hgt /= grow; }
+  if (cap && fit === 'stretch') { w = Math.min(w, sw); hgt = Math.min(hgt, sh); }
+  w = Math.max(1, Math.round(w));
+  hgt = Math.max(1, Math.round(hgt));
+  const position = typeof focus === 'string' && ['attention', 'entropy'].includes(focus) ? focus : (POSITIONS[focus] ?? 'centre');
+  let img = sharp(bytes).rotate().resize(w, hgt, { fit: fit === 'stretch' ? 'fill' : fit, position, background: { r: 0, g: 0, b: 0, alpha: 0 } });
+  // Stretch the tones first, so a duotone spans both of its colours.
+  if (layer.normalize ?? Boolean(layer.duotone || layer.grayscale)) img = img.normalise();
+  // Blur here rather than in SVG: sharp clamps at the edges, where an SVG
+  // blur (in librsvg) fades the photo to transparent. In the pixels drawn.
+  if (layer.blur) img = img.blur(Math.max(0.3, len(layer.blur, ctx.canvas) * res / Math.max(1, grow)));
+  const embedded = { width: w, height: hgt };
+  const source = { width: sw, height: sh };
+  if (!meta.hasAlpha && fit !== 'contain') return { bytes: await img.jpeg({ quality: 90 }).toBuffer(), mime: 'image/jpeg', source, embedded };
+  // An alpha channel: PNG only if it's used (a letterbox, a cutout).
+  const { data, info } = await img.clone().ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const raw = { raw: { width: info.width, height: info.height, channels: 4 } };
+  let opaque = true;
+  for (let i = 3; i < data.length; i += 4) if (data[i] !== 255) { opaque = false; break; }
+  if (opaque) return { bytes: await sharp(data, raw).removeAlpha().jpeg({ quality: 90 }).toBuffer(), mime: 'image/jpeg', source, embedded };
+  if (fit === 'contain' && !meta.hasAlpha && res === 1 && grow <= 1) {
+    // As 1.0 encoded it (the letterbox's alpha), byte for byte.
+    return { bytes: await img.png().toBuffer(), mime: 'image/png', source, embedded };
+  }
+  return { bytes: await sharp(data, raw).png().toBuffer(), mime: 'image/png', source, embedded };
+}
+
 /** Anchor name to sharp's crop `position`. */
 const POSITIONS = /** @type {Record<string, string>} */ ({
   center: 'centre', top: 'top', bottom: 'bottom', left: 'left', right: 'right',
@@ -484,10 +545,7 @@ function defaultDuotone(p) {
 
 /** @param {string} src @returns {Promise<Uint8Array>} */
 async function readSource(src) {
-  const data = src.match(/^data:[^;,]+;base64,(.*)$/s);
-  if (data) return Buffer.from(data[1], 'base64');
-  if (/^https?:/i.test(src)) throw new TypeError('Image src must be a local file or bytes: covers never fetch from the network');
-  return readFile(src);
+  return loadBytes(src, 'image');
 }
 
 /**
@@ -500,10 +558,10 @@ export function sniff(b) {
   if (b[0] === 0x89 && b[1] === 0x50) return 'image/png';
   if (b[0] === 0xff && b[1] === 0xd8) return 'image/jpeg';
   if (b[0] === 0x47 && b[1] === 0x49) return 'image/gif';
-  const head = Buffer.from(b.subarray(0, 32)).toString('latin1');
+  const head = latin1(b.subarray(0, 32));
   if (head.startsWith('RIFF') && head.slice(8, 12) === 'WEBP') return 'image/webp';
   if (head.slice(4, 12) === 'ftypavif' || head.slice(4, 12) === 'ftypavis') return 'image/avif';
-  if (/^\s*(<\?xml|<svg)/i.test(Buffer.from(b.subarray(0, 256)).toString('utf8'))) return 'image/svg+xml';
+  if (/^\s*(<\?xml|<svg)/i.test(utf8(b.subarray(0, 256)))) return 'image/svg+xml';
   return undefined;
 }
 
@@ -766,7 +824,8 @@ export function icon(layer, ctx) {
   const p = ctx.palette;
   // A name that is markup is a raw SVG (so one `icon` option can carry either).
   const name = typeof layer.name === 'string' ? layer.name.trim() : undefined;
-  const svg = layer.svg ?? (name?.startsWith('<') ? name : undefined);
+  const markup = /** @type {any} */ (layer).markup;
+  const svg = layer.svg ?? (name?.startsWith('<') ? name : undefined) ?? (markup ? `<svg viewBox="${(/** @type {any} */ (layer).viewBox ?? [0, 0, 512, 512]).join(' ')}"><g fill="currentColor">${markup}</g></svg>` : undefined);
   const data = svg
     ? parseSvgIcon(svg)
     : name
@@ -779,8 +838,11 @@ export function icon(layer, ctx) {
   const tileOpts = layer.tile === true ? {} : layer.tile || null;
   const size = len(layer.size, ctx.canvas, tileOpts ? '15vmin' : '24vmin');
   const tileSize = tileOpts ? len(tileOpts.size, ctx.canvas, size / 0.5) : size;
-  const margin = len(layer.margin, ctx.canvas, unit(ctx.canvas) * 0.07);
-  const at = place({ width: tileSize, height: tileSize, canvas: ctx.canvas, anchor: layer.anchor ?? 'center', margin, position: layer.position, offset: layer.offset });
+  const margin = len(layer.margin, ctx.canvas, /** @type {any} */ (ctx).inset ?? unit(ctx.canvas) * 0.07);
+  // 1.1: `x`, `y` place the icon's top-left corner in px (a mark at translate(x y) scale(size / 512)).
+  const at = /** @type {any} */ (layer).x != null || /** @type {any} */ (layer).y != null
+    ? { x: pos(/** @type {any} */ (layer).x ?? 0, 'x', ctx.canvas), y: pos(/** @type {any} */ (layer).y ?? 0, 'y', ctx.canvas) }
+    : place({ width: tileSize, height: tileSize, canvas: ctx.canvas, anchor: layer.anchor ?? 'center', margin, position: layer.position, offset: layer.offset });
 
   let defs = '';
   let body = '';
@@ -807,6 +869,13 @@ export function icon(layer, ctx) {
   const ih = vh * fitScale;
   let inner = data.body;
   if (layer.strokeWidth != null) inner = inner.replace(/stroke-width="[^"]*"/g, `stroke-width="${num(layer.strokeWidth)}"`);
+  // 1.1: `fill` paints the icon with a gradient, tile or preset, laid over its grid.
+  const fill = /** @type {any} */ (layer).fill;
+  if (fill != null && typeof fill === 'object') {
+    const fp = paint(fill, 'currentColor', { id: `${ctx.id}i`, box: { x: vx, y: vy, width: vw, height: vh }, canvas: ctx.canvas });
+    defs += fp.defs;
+    inner = inner.replace(/currentColor/g, fp.value);
+  }
   body += `<svg${attrs({
     x: at.x + (tileSize - iw) / 2,
     y: at.y + (tileSize - ih) / 2,
@@ -814,7 +883,7 @@ export function icon(layer, ctx) {
     height: ih,
     viewBox: `${num(vx)} ${num(vy)} ${num(vw)} ${num(vh)}`,
     overflow: 'visible',
-    color: color(layer.color, tileOpts ? p.accent : p.text),
+    color: typeof /** @type {any} */ (layer).fill === 'string' ? toHex(/** @type {any} */ (layer).fill) : color(layer.color, tileOpts ? p.accent : p.text),
   })}>${inner}</svg>`;
   return { defs, body: wrap(layer, body) };
 }
@@ -843,14 +912,16 @@ function shadowPass(name, blur, dy, opacity) {
  * @returns {Promise<Markup>}
  */
 export async function text(layer, ctx) {
+  // 1.1 options (baseline placement, justification, fitting, paths, live text, auto colour).
+  if (wantsType(layer)) return typeset(layer, ctx);
   // An override object in `content` (a recipe's "{title}") means its content.
   const raw = layer.content && typeof layer.content === 'object' ? /** @type {any} */ (layer.content).content : layer.content;
-  const content = transform(String(raw ?? ''), layer.transform);
+  const content = caseText(String(raw ?? ''), layer.transform);
   if (!content.trim()) return { defs: '', body: '' };
   const hb = await harfbuzz();
   const p = ctx.palette;
   const u = unit(ctx.canvas);
-  const margin = len(layer.margin, ctx.canvas, u * 0.07);
+  const margin = len(layer.margin, ctx.canvas, /** @type {any} */ (ctx).inset ?? u * 0.07);
   const anchor = layer.anchor ?? 'bottom-left';
   const align = layer.align ?? anchorAlign(anchor);
   const bg = layer.background ? (typeof layer.background === 'string' ? { color: layer.background } : layer.background) : null;
@@ -886,7 +957,7 @@ export async function text(layer, ctx) {
     const lsize = len(labelOpts.size, ctx.canvas, Math.max(12, set.size * 0.32, u * 0.02));
     const lset = layout({
       face: lface, hb,
-      text: transform(labelOpts.content, labelOpts.transform ?? 'uppercase'),
+      text: caseText(labelOpts.content, labelOpts.transform ?? 'uppercase'),
       size: lsize,
       letterSpacing: labelOpts.letterSpacing ?? 0.08,
       maxWidth,
@@ -921,14 +992,16 @@ export async function text(layer, ctx) {
   }
   const d = set.lines.map((l, i) => runPath(face, l.run, set.size, lineX(l.run.width), y + cap + i * lh)).join('');
   body += `<path${attrs({ d, fill: color(layer.color, p.text) })}/>`;
+  // Where the block landed, for later layers ({layout.<id>.bottom}); what was drawn, for lint (the label too).
+  recordLayout(ctx, layer.id, { x: left, y: top, width: blockW, height: blockH }, { x: lineX(set.lines[0]?.run.width ?? 0), y: y + cap, baseline: y + cap + (set.lines.length - 1) * lh, size: set.size, lines: set.lines.length });
+  const report = /** @type {any} */ (ctx).report;
+  if (report) {
+    report({ kind: 'text', id: layer.id, content, size: set.size, capHeight: cap, box: { x: at.x, y: at.y, width: boxW, height: boxH } });
+    if (label) report({ kind: 'text', id: layer.id, content: label.set.lines.map((l) => l.text).join('\n'), size: label.set.size, capHeight: label.cap, box: null });
+  }
   return { defs: '', body: wrap(layer, body) };
 }
 
-/** @param {string} s @param {string | undefined} t @returns {string} */
-function transform(s, t) {
-  const clean = s.replace(/[\t\r ]+/g, ' ').replace(/ *\n */g, '\n').trim();
-  return t === 'uppercase' ? clean.toUpperCase() : t === 'lowercase' ? clean.toLowerCase() : clean;
-}
 
 /**
  * Padding as `[vertical, horizontal]` pixels.
@@ -969,4 +1042,15 @@ export function frame(layer, ctx) {
 }
 
 /** Every layer type, by name. */
-export const LAYERS = Object.freeze({ solid, linear, radial, mesh, stripes, image, grain, pattern, shapes, icon, text, frame, diagram, paper, scribble, ink, dither, contour, waveform, tiles, rule });
+/**
+ * `group` (and `repeat`, `defs`, `use`) are drawn by the renderer (they
+ * render nested stacks); this entry registers the type and explains itself
+ * if called directly.
+ *
+ * @returns {never}
+ */
+function group() {
+  throw new TypeError('A group layer is drawn by renderSvg()/renderImage(), not on its own');
+}
+
+export const LAYERS = Object.freeze({ solid, linear, radial, mesh, stripes, image, grain, pattern, shapes, icon, text, frame, diagram, paper, scribble, ink, dither, contour, waveform, tiles, rule, group, shape, svg, table, barcode, perforation, tear, texture, repeat: group, defs: group, use: group });

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/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>;