@arraypress/covers 1.0.0 → 1.3.1

package/src/layers/texture.js

@@ -0,0 +1,106 @@
+/**
+ * The `texture` layer: paper, creases, concrete, speck, wood, folds, dust.
+ *
+ * @module layers/texture
+ */
+
+import { attrs, num } from '@logomarks/image-effects/svg';
+import { len } from '@logomarks/image-effects/length';
+import { toHex } from '@logomarks/image-effects/color';
+import { pos, wrap } from './util.js';
+
+
+/**
+ * `texture` — a surface laid over (or under) the artwork: `paper` (fibres),
+ * `creases` (pasted paper lit from the side; soft-light), `concrete`,
+ * `speck` (white specks), `wood`, `folds` (straight fold lines with a lit
+ * and a shaded side), `dust` (seeded specks of dirt). `color`, `opacity`,
+ * `blend`, `frequency`, `octaves` and `region` adjust it.
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {import('../layers.js').Markup}
+ */
+export function texture(layer, ctx) {
+  const { width: w, height: h, rng } = ctx;
+  const kind = layer.kind ?? 'paper';
+  const id = `${ctx.id}t`;
+  const seed = layer.seed ?? rng.int(1, 9999);
+  const rgb = (/** @type {string} */ c) => [1, 3, 5].map((i) => num(parseInt(toHex(c).slice(i, i + 2), 16) / 255, 3));
+  const f = (/** @type {any} */ v, /** @type {string} */ d) => (v == null ? d : [].concat(v).map((x) => num(x, 4)).join(' '));
+  const rect = (/** @type {string} */ extra = '') => `<rect${attrs({ width: w, height: h, filter: `url(#${id})` })}${extra}/>`;
+  const region = `${attrs({ id, x: 0, y: 0, width: w, height: h, filterUnits: 'userSpaceOnUse', 'color-interpolation-filters': 'sRGB' })}`;
+  let defs = '';
+  let body = '';
+  let blend = layer.blend;
+  let opacity = layer.opacity;
+  // Feature sizes are tuned on a 400 px wide sheet; scale with the canvas.
+  const k = 400 / Math.min(w, h * 0.8);
+  const fq = (/** @type {number[]} */ ...v) => v.map((x) => x * k);
+  switch (kind) {
+    case 'paper': {
+      const [r, g, b] = rgb(layer.color ?? '#73664d');
+      defs = `<filter${region}><feTurbulence type="fractalNoise" baseFrequency="${f(layer.frequency, fq(0.55, 0.3).map((x) => num(x, 4)).join(' '))}" numOctaves="${layer.octaves ?? 3}" seed="${seed}"/><feColorMatrix type="matrix" values="0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  0 0 0 -0.9 ${num(0.5 * (layer.amount ?? 1), 3)}"/></filter>`;
+      body = rect();
+      break;
+    }
+    case 'creases':
+      defs = `<filter${region}><feTurbulence type="turbulence" baseFrequency="${f(layer.frequency, fq(0.006, 0.022).map((x) => num(x, 4)).join(' '))}" numOctaves="${layer.octaves ?? 3}" seed="${seed}" result="t"/><feDiffuseLighting in="t" surfaceScale="${num(layer.depth ?? 3.4, 3)}" lighting-color="#fff" result="lit"><feDistantLight azimuth="${layer.azimuth ?? 225}" elevation="${layer.elevation ?? 38}"/></feDiffuseLighting><feColorMatrix in="lit" type="saturate" values="0"/></filter>`;
+      body = rect();
+      blend ??= 'soft-light';
+      opacity ??= 0.95;
+      break;
+    case 'concrete': {
+      const [r, g, b] = rgb(layer.color ?? '#857f7a');
+      defs = `<filter${region}><feTurbulence type="fractalNoise" baseFrequency="${f(layer.frequency, fq(0.035, 0.05).map((x) => num(x, 4)).join(' '))}" numOctaves="${layer.octaves ?? 4}" seed="${seed}"/><feColorMatrix type="matrix" values="0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  0.6 0.6 0.6 0 -0.4"/></filter>`;
+      body = rect();
+      break;
+    }
+    case 'speck': {
+      const [r, g, b] = rgb(layer.color ?? '#ffffff');
+      defs = `<filter${region}><feTurbulence type="fractalNoise" baseFrequency="${f(layer.frequency, num(0.7 * k, 4))}" numOctaves="1" seed="${seed}"/><feColorMatrix type="matrix" values="0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  0 0 0 -12 7.3"/></filter>`;
+      body = rect();
+      opacity ??= 0.25;
+      break;
+    }
+    case 'wood': {
+      const [r, g, b] = rgb(layer.color ?? '#6b4224');
+      defs = `<filter${region}><feTurbulence type="fractalNoise" baseFrequency="${f(layer.frequency, fq(0.006, 0.16).map((x) => num(x, 4)).join(' '))}" numOctaves="${layer.octaves ?? 4}" seed="${seed}"/><feColorMatrix type="matrix" values="0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  1.4 0 0 0 -0.45"/></filter>`;
+      body = rect();
+      break;
+    }
+    case 'folds': {
+      // Straight folds: a lit side and a shaded side either side of each line.
+      const xs = layer.x ?? [];
+      const ys = layer.y ?? (layer.x ? [] : [0.5]);
+      const bw = len(layer.width, ctx.canvas, '1.6vmin');
+      const strength = layer.strength ?? 0.35;
+      const band = (/** @type {boolean} */ vertical, /** @type {number} */ at, /** @type {number} */ i) => {
+        const gid = `${id}${vertical ? 'v' : 'h'}${i}`;
+        const p = vertical ? at * w : at * h;
+        defs += `<linearGradient${attrs({ id: gid, gradientUnits: 'userSpaceOnUse', x1: vertical ? p - bw : 0, y1: vertical ? 0 : p - bw, x2: vertical ? p + bw : 0, y2: vertical ? 0 : p + bw })}><stop offset="0" stop-color="#000" stop-opacity="0"/><stop offset="0.48" stop-color="#000" stop-opacity="${num(strength, 3)}"/><stop offset="0.52" stop-color="#fff" stop-opacity="${num(strength * 1.4, 3)}"/><stop offset="1" stop-color="#fff" stop-opacity="0"/></linearGradient>`;
+        body += vertical ? `<rect${attrs({ x: p - bw, y: 0, width: bw * 2, height: h, fill: `url(#${gid})` })}/>` : `<rect${attrs({ x: 0, y: p - bw, width: w, height: bw * 2, fill: `url(#${gid})` })}/>`;
+      };
+      xs.forEach((/** @type {number} */ x, /** @type {number} */ i) => band(true, x, i));
+      ys.forEach((/** @type {number} */ y, /** @type {number} */ i) => band(false, y, i));
+      blend ??= 'soft-light';
+      break;
+    }
+    case 'dust': {
+      const n = layer.count ?? 70;
+      const c = toHex(layer.color ?? ctx.palette.text);
+      const [lo, hi] = (layer.size ?? ['0.06vmin', '0.26vmin']).map((/** @type {any} */ v) => len(v, ctx.canvas));
+      for (let i = 0; i < n; i++) body += `<circle${attrs({ cx: rng.next() * w, cy: rng.next() * h, r: lo + rng.next() * (hi - lo) })}/>`;
+      body = `<g fill="${c}">${body}</g>`;
+      break;
+    }
+    default:
+      throw new TypeError(`Unknown texture "${kind}" (paper, creases, concrete, speck, wood, folds, dust)`);
+  }
+  if (layer.region) {
+    const rg = layer.region;
+    defs += `<clipPath id="${id}c"><rect${attrs({ x: pos(rg.x ?? 0, 'x', ctx.canvas), y: pos(rg.y ?? 0, 'y', ctx.canvas), width: pos(rg.width ?? '100%', 'x', ctx.canvas), height: pos(rg.height ?? '100%', 'y', ctx.canvas) })}/></clipPath>`;
+    body = `<g clip-path="url(#${id}c)">${body}</g>`;
+  }
+  return { defs, body: wrap({ blend, opacity }, body) };
+}

package/src/layers/util.d.ts

@@ -0,0 +1,8 @@
+// Helpers the poster layers share.
+
+/** A coordinate: px, `'50%'` of the canvas along `axis`, or a length. */
+export function pos(v: unknown, axis: 'x' | 'y', canvas: { width: number; height: number }): number;
+/** Markup wrapped in the layer's opacity and blend (when it has them). */
+export function wrap(layer: { opacity?: number; blend?: string }, body: string): string;
+/** The text of a string-or-object option. */
+export function contentOf(v: unknown): string | undefined;

package/src/layers/util.js

@@ -0,0 +1,61 @@
+/**
+ * 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 '@logomarks/image-effects/svg';
+import { len } from '@logomarks/image-effects/length';
+
+/**
+ * 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);
+}
+
+/**
+ * Opacity and blend-mode attributes shared by every layer.
+ *
+ * @param {{ opacity?: number, blend?: string }} layer - The layer.
+ * @returns {Record<string, string | number | undefined>} Attributes for the layer's group.
+ */
+export function layerAttrs(layer) {
+  return {
+    opacity: layer.opacity != null && layer.opacity < 1 ? Math.max(0, layer.opacity) : undefined,
+    style: layer.blend && layer.blend !== 'normal' ? `mix-blend-mode:${layer.blend}` : undefined,
+  };
+}
+
+/**
+ * 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,25 @@
  * @module layers
  */
 
-import { readFile } from 'node:fs/promises';
-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 { loadBytes, toBase64 } from './platform/index.js';
+import { attrs, esc, num } from '@logomarks/image-effects/svg';
+import { imageMime } from '@logomarks/image-effects';
+import { len } from '@logomarks/image-effects/length';
+import { place, anchorAlign, unit, regionPx } from './geometry.js';
+import { toHex, mixOklab, toOklch, fromOklch } from '@logomarks/image-effects/color';
 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, layerAttrs } from './layers/util.js';
+import { paint } from './paint/index.js';
+import { imageSize } from './lint/image-size.js';
 
 /**
  * Everything a layer renderer needs.
@@ -34,7 +42,7 @@ import { ink, dither, contour, waveform, tiles, rule } from './print.js';
  * @property {number} height - Canvas height in px.
  * @property {{ width: number, height: number }} canvas - The same, as an object.
  * @property {import('./index.js').Palette} palette - The resolved palette.
- * @property {import('./rng.js').Rng} rng - This layer's own random stream.
+ * @property {import('@logomarks/image-effects/rng').Rng} rng - This layer's own random stream.
  * @property {string} id - A unique id prefix for this layer's defs.
  * @property {import('./index.js').FontSource[]} fonts - Available fonts (Inter last).
  * @property {any} [sharp] - The `sharp` module, when available.
@@ -406,35 +414,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 mime = sniff(bytes);
-  let preserve = `${alignFor(focus)} ${fit === 'contain' ? 'meet' : 'slice'}`;
+  let bytes = typeof layer.src === 'string' || layer.src instanceof URL ? await readSource(layer.src) : await loadBytes(layer.src, 'image');
+  let mime = imageMime(bytes);
+  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 +458,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 +466,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,27 +546,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);
-}
-
-/**
- * Sniff an image's MIME type from its first bytes.
- *
- * @param {Uint8Array} b - Image bytes.
- * @returns {string | undefined} The MIME type.
- */
-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');
-  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';
-  return undefined;
+  return loadBytes(src, 'image');
 }
 
 // ---------------------------------------------------------------------------
@@ -766,7 +808,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 +822,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 +853,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 +867,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 +896,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 +941,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 +976,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 +1026,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[] }>;