@arraypress/covers 1.0.0 → 1.3.1

package/src/fonts.js

@@ -3,31 +3,43 @@
  *
  * Text is shaped by HarfBuzz (`harfbuzzjs`, WebAssembly) and drawn as
  * outlines, so the rendered cover never depends on fonts installed on the
- * build machine. Inter (Latin, 400/500/600/700, about 120 KB of WOFF) ships
- * in `fonts/` and is always available as the family `Inter`.
+ * build machine. Where HarfBuzz can't run (Cloudflare Workers) a small
+ * JavaScript TrueType reader (`sfnt.js`) draws the outlines instead. Inter
+ * (Latin, 400/500/600/700, about 120 KB of WOFF) ships in `fonts/` and is
+ * always available as the family `Inter`.
  *
- * Accepted formats: TrueType/OpenType (`.ttf`/`.otf`) and WOFF (`.woff`).
- * WOFF2 is rejected with a clear error: it needs Brotli plus glyph-table
- * reconstruction, which isn't worth carrying for a build tool.
+ * A font is `{ name, data | src, weight, style }`: bytes, or a `src` loaded
+ * like any file (a path in Node, a URL, or through `configure({ load })`).
+ * Variable fonts take a weight range (`weight: [100, 900]`) and their axes
+ * are set per text layer (`axes: { wdth: 75, SOFT: 100 }`); a variable
+ * font's `wght` follows the layer's `weight`.
+ *
+ * Accepted formats: TrueType/OpenType (`.ttf`/`.otf`), WOFF (`.woff`) and
+ * WOFF2 (`.woff2`: Brotli from the platform, Node's zlib or a browser's
+ * `DecompressionStream('brotli')`, and the glyph tables rebuilt in
+ * JavaScript). Where there's no Brotli (most Workers), convert WOFF2 to TTF
+ * first (`scripts/woff2-to-ttf.mjs`).
  *
  * @module fonts
  */
 
-import { readFileSync } from 'node:fs';
-import { inflateSync } from 'node:zlib';
+import { shaperModule, loadBytes, inflate, unbrotli, unbrotliSync, packageFileSync, registry, node, u8 } from './platform/index.js';
+import { parseSfnt } from './type/sfnt.js';
+import { woff2Directory, woff2ToSfnt } from './type/woff2.js';
 
-/** @type {Promise<typeof import('harfbuzzjs')> | undefined} */
-let hbPromise;
+/** @param {Uint8Array} b @returns {boolean} Whether bytes are WOFF2. */
+const isWoff2 = (b) => b.length >= 4 && b[0] === 0x77 && b[1] === 0x4f && b[2] === 0x46 && b[3] === 0x32;
 
 /**
  * Load HarfBuzz once (its WebAssembly initialises on import, so it's
- * imported lazily: covers with no text never pay for it).
+ * imported lazily: covers with no text never pay for it). Undefined where
+ * it can't run (Workers), or with `configure({ shaper: 'js' })`: text then
+ * uses the JavaScript outliner.
  *
- * @returns {Promise<typeof import('harfbuzzjs')>} The harfbuzzjs module.
+ * @returns {Promise<typeof import('harfbuzzjs') | undefined>} The harfbuzzjs module.
  */
 export function harfbuzz() {
-  hbPromise ??= import('harfbuzzjs');
-  return hbPromise;
+  return shaperModule();
 }
 
 /** Bundled weights of Inter. */
@@ -37,34 +49,115 @@ const BUNDLED = [400, 500, 600, 700];
 let bundled;
 
 /**
- * The bundled Inter faces, read from disk once per process.
+ * The bundled Inter faces: read from disk in Node (once per process),
+ * else from an embedded module the first time one is drawn.
  *
  * @returns {import('./index.js').FontSource[]} Inter 400/500/600/700.
  */
 export function bundledFonts() {
-  bundled ??= BUNDLED.map((weight) => ({
-    name: 'Inter',
-    weight,
-    style: 'normal',
+  bundled ??= BUNDLED.map((weight) => {
     // A URL, not `.pathname`: a path with a space would be percent-encoded.
-    data: readFileSync(new URL(`../fonts/inter-latin-${weight}.woff`, import.meta.url)),
-  }));
+    const data = packageFileSync(`fonts/inter-latin-${weight}.woff`);
+    return /** @type {import('./index.js').FontSource} */ (data ? { name: 'Inter', weight, style: 'normal', data } : { name: 'Inter', weight, style: 'normal', src: `covers:inter-${weight}` });
+  });
   return bundled;
 }
 
 /**
- * Turn font bytes into a bare sfnt (TrueType/OpenType) HarfBuzz can read.
+ * Every font a cover can use: its own, the registered ones, then Inter.
+ *
+ * @param {import('./index.js').FontSource[]} own
+ * @returns {import('./index.js').FontSource[]}
+ */
+export function fontPool(own) {
+  return [...own, ...registry, ...bundledFonts()];
+}
+
+/**
+ * Register a font for every cover (by bytes or by `src`).
+ *
+ * @param {import('./index.js').FontSource} font
+ * @returns {void}
  *
- * @param {Uint8Array | ArrayBuffer} input - `.ttf`, `.otf` or `.woff` bytes.
+ * @example
+ * registerFont({ name: 'Fraunces', src: '/fonts/Fraunces.ttf', weight: [100, 900] });
+ */
+export function registerFont(font) {
+  if (!font?.name || (font.data == null && font.src == null)) throw new TypeError('registerFont() needs { name, data } or { name, src }');
+  registry.push(font);
+}
+
+/** @type {Map<string, Promise<Uint8Array>>} */
+const fetched = new Map();
+
+/**
+ * A font source's bytes (as given; still WOFF if it was).
+ *
+ * @param {import('./index.js').FontSource} source
+ * @returns {Promise<Uint8Array>}
+ */
+export function fontBytes(source) {
+  if (source.data != null) return Promise.resolve(u8(source.data));
+  const src = String(source.src);
+  let p = fetched.get(src);
+  if (!p) {
+    const m = /^covers:inter-(\d+)$/.exec(src);
+    p = m
+      ? import('./inter-data.js').then((d) => d.inter(Number(m[1])))
+      : loadBytes(source.src, 'font');
+    fetched.set(src, p);
+  }
+  return p;
+}
+
+/**
+ * Turn font bytes into a bare sfnt (TrueType/OpenType) HarfBuzz can read,
+ * synchronously (Node, where zlib is synchronous).
+ *
+ * @param {Uint8Array | ArrayBuffer} input - `.ttf`, `.otf`, `.woff` or `.woff2` bytes.
  * @returns {Uint8Array} sfnt bytes.
- * @throws {TypeError} On WOFF2 or bytes that aren't a font.
+ * @throws {TypeError} On bytes that aren't a font.
  */
 export function decodeFont(input) {
-  const buf = input instanceof Uint8Array ? input : new Uint8Array(input);
+  const z = node('zlib');
+  if (!z) throw new Error('decodeFont() is synchronous only in Node; use decodeFontAsync()');
+  const bytes = u8(input);
+  if (isWoff2(bytes)) return woff2ToSfnt(bytes, unbrotliSync(woff2Directory(bytes).payload));
+  /** @type {Uint8Array | undefined} */
+  let out;
+  const gen = woffToSfnt(input);
+  let step = gen.next();
+  while (!step.done) step = gen.next(z.inflateSync(step.value));
+  out = step.value;
+  return out;
+}
+
+/**
+ * {@link decodeFont} on any platform (`DecompressionStream` outside Node).
+ *
+ * @param {Uint8Array | ArrayBuffer} input
+ * @returns {Promise<Uint8Array>}
+ */
+export async function decodeFontAsync(input) {
+  const bytes = u8(input);
+  if (isWoff2(bytes)) return woff2ToSfnt(bytes, await unbrotli(woff2Directory(bytes).payload));
+  const gen = woffToSfnt(input);
+  let step = gen.next();
+  while (!step.done) step = gen.next(await inflate(step.value));
+  return step.value;
+}
+
+/**
+ * The WOFF → sfnt conversion, yielding each compressed table to be inflated.
+ *
+ * @param {Uint8Array | ArrayBuffer} input
+ * @returns {Generator<Uint8Array, Uint8Array, Uint8Array>}
+ */
+function* woffToSfnt(input) {
+  const buf = u8(input);
   const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
   if (buf.byteLength < 12) throw new TypeError('Font data is too short to be a font');
   const tag = view.getUint32(0);
-  if (tag === 0x774f4632) throw new TypeError('WOFF2 fonts are not supported: pass a .woff, .ttf or .otf');
   if (tag !== 0x774f4646) {
     // 0x00010000 TrueType, 'OTTO' CFF, 'true' old Apple TrueType.
     if (tag === 0x00010000 || tag === 0x4f54544f || tag === 0x74727565) return buf;
@@ -89,7 +182,7 @@ export function decodeFont(input) {
   while (pow * 2 <= count) { pow *= 2; log++; }
 
   const headerSize = 12 + 16 * count;
-  const pad = (n) => (n + 3) & ~3;
+  const pad = (/** @type {number} */ n) => (n + 3) & ~3;
   const total = tables.reduce((sum, t) => sum + pad(t.origLength), headerSize);
   const out = new Uint8Array(total);
   const ov = new DataView(out.buffer);
@@ -100,9 +193,10 @@ export function decodeFont(input) {
   ov.setUint16(10, count * 16 - pow * 16);
 
   let offset = headerSize;
-  tables.forEach((t, i) => {
+  for (let i = 0; i < tables.length; i++) {
+    const t = tables[i];
     const src = buf.subarray(t.offset, t.offset + t.compLength);
-    const data = t.compLength < t.origLength ? inflateSync(src) : src;
+    const data = t.compLength < t.origLength ? yield src : src;
     out.set(data, offset);
     const rec = 12 + i * 16;
     ov.setUint32(rec, t.tag);
@@ -110,10 +204,21 @@ export function decodeFont(input) {
     ov.setUint32(rec + 8, offset);
     ov.setUint32(rec + 12, t.origLength);
     offset += pad(t.origLength);
-  });
+  }
   return out;
 }
 
+/**
+ * A shaped glyph, in font units.
+ *
+ * @typedef {object} RunGlyph
+ * @property {number} gid
+ * @property {number} cluster
+ * @property {number} xAdvance
+ * @property {number} xOffset
+ * @property {number} yOffset
+ */
+
 /**
  * A loaded face, ready to shape with.
  *
@@ -121,51 +226,108 @@ export function decodeFont(input) {
  * @property {string} name - Family name.
  * @property {number} weight - Weight.
  * @property {string} style - `'normal'` or `'italic'`.
- * @property {any} font - The harfbuzzjs `Font`.
+ * @property {any} font - The harfbuzzjs `Font`, or the JS face.
  * @property {number} upem - Units per em.
  * @property {number} ascender - In font units.
  * @property {number} descender - In font units (negative).
  * @property {number} capHeight - In font units.
  * @property {Map<number, (string | number)[]>} paths - Glyph outline cache.
+ * @property {(text: string) => RunGlyph[]} shapeRun - Shape one line.
+ * @property {(gid: number) => string} glyphToPath - Outline, font units, y up.
+ * @property {Record<string, { min: number, default: number, max: number }>} axes - The font's variation axes.
+ * @property {Record<string, number>} variations - The axis values in use.
+ * @property {import('./index.js').FontSource} source - Where it came from.
  */
 
-/** @type {WeakMap<object, Promise<LoadedFont>>} */
+/** Faces by font bytes (then by variation settings). @type {WeakMap<object, Map<string, Promise<LoadedFont>>>} */
 const loaded = new WeakMap();
 
 /**
- * Load one font source (cached per data buffer, so the bundled faces and a
- * caller's reused buffers are decoded once per process).
+ * Load one font source, optionally at a variation (cached per data buffer
+ * and settings, so the bundled faces and a caller's reused buffers are
+ * decoded once per process).
  *
  * @param {import('./index.js').FontSource} source - The font.
+ * @param {Record<string, number>} [variations] - Axis values (`{ wght: 650, wdth: 80 }`).
  * @returns {Promise<LoadedFont>} The loaded face.
  */
-export function loadFont(source) {
-  const key = /** @type {object} */ (source.data);
-  let p = loaded.get(key);
+export async function loadFont(source, variations) {
+  const bytes = await fontBytes(source);
+  const vkey = variations && Object.keys(variations).length ? JSON.stringify(Object.entries(variations).sort()) : '';
+  let byVar = loaded.get(bytes);
+  if (!byVar) loaded.set(bytes, (byVar = new Map()));
+  let p = byVar.get(vkey);
   if (!p) {
     p = (async () => {
-      const hb = await harfbuzz();
-      const face = new hb.Face(new hb.Blob(decodeFont(source.data)));
-      const font = new hb.Font(face);
-      const ext = font.hExtents();
-      const cap = font.getMetricPosition?.(hb.MetricsTag.CAP_HEIGHT);
-      const upem = face.upem;
+      const sfnt = await decodeFontAsync(bytes);
+      const hb = await shaperModule();
+      if (hb) {
+        const face = new hb.Face(new hb.Blob(sfnt));
+        const font = new hb.Font(face);
+        const axes = vkey && typeof face.getAxisInfos === 'function' ? face.getAxisInfos() : {};
+        /** @type {Record<string, number>} */
+        const used = {};
+        if (vkey && variations) {
+          const list = [];
+          for (const [tag, value] of Object.entries(variations)) {
+            const a = axes[tag];
+            if (!a) continue;
+            used[tag] = Math.min(a.max, Math.max(a.min, value));
+            list.push(new hb.Variation(tag, used[tag]));
+          }
+          if (list.length) font.setVariations(list);
+        }
+        const ext = font.hExtents();
+        const cap = font.getMetricPosition?.(hb.MetricsTag.CAP_HEIGHT);
+        const upem = face.upem;
+        return {
+          name: source.name,
+          weight: 400,
+          style: 'normal',
+          font,
+          upem,
+          ascender: ext.ascender,
+          descender: ext.descender,
+          capHeight: cap || capFromGlyph(font) || upem * 0.7,
+          paths: new Map(),
+          axes,
+          variations: used,
+          source,
+          glyphToPath: (/** @type {number} */ gid) => font.glyphToPath(gid),
+          shapeRun: (/** @type {string} */ text) => {
+            const buffer = new hb.Buffer();
+            buffer.addText(text);
+            buffer.guessSegmentProperties();
+            hb.shape(font, buffer);
+            const infos = buffer.getGlyphInfos();
+            const positions = buffer.getGlyphPositions();
+            return infos.map((/** @type {any} */ info, /** @type {number} */ i) => ({ gid: info.codepoint, cluster: info.cluster, xAdvance: positions[i].xAdvance, xOffset: positions[i].xOffset, yOffset: positions[i].yOffset }));
+          },
+        };
+      }
+      const js = parseSfnt(sfnt);
       return {
         name: source.name,
-        weight: source.weight ?? 400,
-        style: source.style ?? 'normal',
-        font,
-        upem,
-        ascender: ext.ascender,
-        descender: ext.descender,
-        capHeight: cap || capFromGlyph(font) || upem * 0.7,
+        weight: 400,
+        style: 'normal',
+        font: js,
+        upem: js.upem,
+        ascender: js.ascender,
+        descender: js.descender,
+        capHeight: js.capHeight || capFromJs(js) || js.upem * 0.7,
         paths: new Map(),
+        axes: js.axes,
+        variations: {},
+        source,
+        glyphToPath: js.glyphToPath,
+        shapeRun: (/** @type {string} */ text) => js.shape(text).map((g) => ({ gid: g.gid, cluster: g.cluster, xAdvance: g.advance, xOffset: 0, yOffset: 0 })),
       };
     })();
-    loaded.set(key, p);
+    byVar.set(vkey, p);
   }
+  const f = await p;
   // The same bytes can be registered under another name or weight.
-  return p.then((f) => ({ ...f, name: source.name, weight: source.weight ?? 400, style: source.style ?? 'normal' }));
+  return { ...f, name: source.name, weight: Array.isArray(source.weight) ? (variations?.wght ?? 400) : source.weight ?? 400, style: source.style ?? 'normal', source };
 }
 
 /**
@@ -180,9 +342,21 @@ function capFromGlyph(font) {
   return ext ? ext.yBearing : undefined;
 }
 
+/** @param {import('./type/sfnt.js').JsFace} js @returns {number | undefined} */
+function capFromJs(js) {
+  const gid = js.shape('H')[0]?.gid;
+  if (!gid) return undefined;
+  const ys = [...js.glyphToPath(gid).matchAll(/-?[\d.]+,(-?[\d.]+)/g)].map((m) => +m[1]);
+  return ys.length ? Math.max(...ys) : undefined;
+}
+
+/** @param {import('./index.js').FontSource} s @returns {[number, number]} */
+const weightRange = (s) => (Array.isArray(s.weight) ? [s.weight[0], s.weight[1]] : [s.weight ?? 400, s.weight ?? 400]);
+
 /**
  * Pick the face for a family, weight and style: the closest weight within
- * the family (CSS's matching rule, simplified), falling back to Inter.
+ * the family (CSS's matching rule, simplified; a variable font's range
+ * matches any weight inside it), falling back to Inter.
  *
  * @param {import('./index.js').FontSource[]} sources - The available fonts.
  * @param {string} family - Wanted family.
@@ -196,5 +370,23 @@ export function pickFont(sources, family, weight, style = 'normal') {
   if (!pool.length) pool = sources;
   const styled = pool.filter((s) => (s.style ?? 'normal') === style);
   if (styled.length) pool = styled;
-  return pool.reduce((best, s) => (Math.abs((s.weight ?? 400) - weight) < Math.abs((best.weight ?? 400) - weight) ? s : best));
+  const dist = (/** @type {import('./index.js').FontSource} */ s) => {
+    const [lo, hi] = weightRange(s);
+    return weight < lo ? lo - weight : weight > hi ? weight - hi : 0;
+  };
+  return pool.reduce((best, s) => (dist(s) < dist(best) ? s : best));
+}
+
+/**
+ * The variation settings for a layer: its `axes`, with `wght` following
+ * the weight on a variable font.
+ *
+ * @param {import('./index.js').FontSource} source
+ * @param {number} weight
+ * @param {Record<string, number> | undefined} axes
+ * @returns {Record<string, number> | undefined}
+ */
+export function variationsFor(source, weight, axes) {
+  const v = { ...(Array.isArray(source.weight) ? { wght: weight } : {}), ...(source.axes ?? {}), ...(axes ?? {}) };
+  return Object.keys(v).length ? v : undefined;
 }

package/src/formats/cut.d.ts

@@ -0,0 +1,10 @@
+// Die-cut outlines for print formats.
+
+/** A die-cut: a plain trim, 3 mm corners, a circle, corners in mm, or a path drawn from its grid into the trim. */
+export type Cut = 'rect' | 'rounded' | 'circle' | { radius: number } | { d: string; viewBox?: [number, number, number, number] };
+
+/** One path segment, canvas px. */
+export interface Segment { cmd: 'M' | 'L' | 'C' | 'Z'; pts: number[] }
+
+/** The cut outline round a box (px per mm for corner radii; `outset` grows the radii with the box). */
+export function cutPath(cut: Cut | undefined, box: { x: number; y: number; width: number; height: number }, mm: number, outset?: number): Segment[];

package/src/formats/cut.js

@@ -0,0 +1,77 @@
+/**
+ * Die-cut outlines for print formats: a plain trim, rounded corners, a
+ * circle, or any path, as Bézier segments in canvas px (so a layer can
+ * draw or clip to it in its own units).
+ *
+ * @module formats/cut
+ */
+
+import { flattenPath } from '../flatten.js';
+
+/** A circle's quarter as a cubic Bézier (control-point distance per radius). */
+const K = 0.5522847498;
+
+/**
+ * @typedef {{ cmd: 'M' | 'L' | 'C' | 'Z', pts: number[] }} Segment
+ */
+
+/**
+ * The cut outline round a box.
+ *
+ * `cut`: `'rect'` (or none), `'rounded'` (3 mm corners), `'circle'` (an
+ * ellipse in the box), `{ radius }` (corners in mm), or `{ d, viewBox }`
+ * (a die path drawn from its grid into the box).
+ *
+ * @param {any} cut
+ * @param {{ x: number, y: number, width: number, height: number }} box - The trim (grown by any outset), px.
+ * @param {number} mm - px per millimetre.
+ * @param {number} [outset=0] - How far the box was grown (corner radii grow with it).
+ * @returns {Segment[]}
+ */
+export function cutPath(cut, box, mm, outset = 0) {
+  const { x, y, width: w, height: h } = box;
+  if (cut === 'circle') return ellipse(x + w / 2, y + h / 2, w / 2, h / 2);
+  if (cut && typeof cut === 'object' && cut.d) return custom(cut, box);
+  const r = cut === 'rounded' ? 3 * mm + outset : cut && typeof cut === 'object' && cut.radius != null ? cut.radius * mm + outset : 0;
+  return rounded(x, y, w, h, Math.max(0, Math.min(r, w / 2, h / 2)));
+}
+
+/** @param {number} x @param {number} y @param {number} w @param {number} h @param {number} r @returns {Segment[]} */
+function rounded(x, y, w, h, r) {
+  if (r <= 0) return [{ cmd: 'M', pts: [x, y] }, { cmd: 'L', pts: [x + w, y] }, { cmd: 'L', pts: [x + w, y + h] }, { cmd: 'L', pts: [x, y + h] }, { cmd: 'Z', pts: [] }];
+  const k = r * (1 - K);
+  return [
+    { cmd: 'M', pts: [x + r, y] }, { cmd: 'L', pts: [x + w - r, y] }, { cmd: 'C', pts: [x + w - k, y, x + w, y + k, x + w, y + r] },
+    { cmd: 'L', pts: [x + w, y + h - r] }, { cmd: 'C', pts: [x + w, y + h - k, x + w - k, y + h, x + w - r, y + h] },
+    { cmd: 'L', pts: [x + r, y + h] }, { cmd: 'C', pts: [x + k, y + h, x, y + h - k, x, y + h - r] },
+    { cmd: 'L', pts: [x, y + r] }, { cmd: 'C', pts: [x, y + k, x + k, y, x + r, y] }, { cmd: 'Z', pts: [] },
+  ];
+}
+
+/** @param {number} cx @param {number} cy @param {number} rx @param {number} ry @returns {Segment[]} */
+function ellipse(cx, cy, rx, ry) {
+  const kx = rx * K;
+  const ky = ry * K;
+  return [
+    { cmd: 'M', pts: [cx, cy - ry] },
+    { cmd: 'C', pts: [cx + kx, cy - ry, cx + rx, cy - ky, cx + rx, cy] },
+    { cmd: 'C', pts: [cx + rx, cy + ky, cx + kx, cy + ry, cx, cy + ry] },
+    { cmd: 'C', pts: [cx - kx, cy + ry, cx - rx, cy + ky, cx - rx, cy] },
+    { cmd: 'C', pts: [cx - rx, cy - ky, cx - kx, cy - ry, cx, cy - ry] },
+    { cmd: 'Z', pts: [] },
+  ];
+}
+
+/** @param {{ d: string, viewBox?: number[] }} cut @param {{ x: number, y: number, width: number, height: number }} box @returns {Segment[]} */
+function custom(cut, box) {
+  const [vx, vy, vw, vh] = cut.viewBox ?? [0, 0, box.width, box.height];
+  const sx = box.width / vw;
+  const sy = box.height / vh;
+  /** @type {Segment[]} */
+  const out = [];
+  for (const sub of flattenPath(String(cut.d), Math.min(vw, vh) / 400)) {
+    sub.points.forEach(([px, py], i) => out.push({ cmd: i ? 'L' : 'M', pts: [box.x + (px - vx) * sx, box.y + (py - vy) * sy] }));
+    if (sub.closed) out.push({ cmd: 'Z', pts: [] });
+  }
+  return out;
+}

package/src/formats/index.d.ts

@@ -0,0 +1,6 @@
+// Formats: named sizes, safe zones, print set-up.
+export { FORMATS, avatarZones } from './presets.js';
+export type { Zones, Format, FormatName } from './presets.js';
+export { zonesOverlay, scaleZones, safeBox } from './zones.js';
+export { resolveFormat, printMarks, toPx } from './print.js';
+export type { PrintInfo } from './print.js';

package/src/formats/index.js

@@ -0,0 +1,9 @@
+/**
+ * Formats: named sizes, safe zones, print set-up.
+ *
+ * @module formats
+ */
+
+export { FORMATS, avatarZones } from './presets.js';
+export { zonesOverlay, scaleZones, safeBox } from './zones.js';
+export { resolveFormat, printMarks, toPx } from './print.js';

package/src/formats/presets.d.ts

@@ -0,0 +1,41 @@
+// The named formats, as data.
+
+/** Where a platform crops or covers an image, px of the canvas. */
+export interface Zones {
+  /** `[x, y, w, h]`: anchored text and icons are laid out inside it. */
+  safe: [number, number, number, number];
+  avoid?: { name: string; rect?: [number, number, number, number]; circle?: [number, number, number] }[];
+  crops?: { name: string; rect: [number, number, number, number] }[];
+  /** Where the numbers come from. */
+  source?: string;
+}
+
+
+/** The named formats. */
+export type FormatName =
+  | 'release' | 'spotify-canvas' | 'bandcamp-header'
+  | 'instagram-post' | 'instagram-square' | 'instagram-story' | 'instagram-reel' | 'youtube-thumbnail' | 'youtube-banner' | 'og'
+  | 'avatar' | 'x-avatar' | 'youtube-avatar' | 'x-header' | 'linkedin-banner' | 'linkedin-company' | 'facebook-cover'
+  | 'twitch-banner' | 'discord-banner' | 'discord-profile' | 'bluesky-banner' | 'pinterest' | 'tiktok-cover'
+  | 'flyer' | 'a6' | 'a5' | 'a4' | 'a3' | 'a2'
+  | 'business-card' | 'business-card-us' | 'letterhead' | 'letterhead-us' | 'compliment-slip'
+  | 'sticker' | 'sticker-square' | 'ticket' | 'badge' | 'lanyard-pass';
+
+
+/** A format: a size in a unit, with print defaults or safe zones. */
+export interface Format {
+  width: number;
+  height: number;
+  unit: 'px' | 'mm' | 'in';
+  label: string;
+  bleed?: number;
+  safe?: number;
+  cut?: import('./cut.js').Cut;
+  zones?: Zones;
+}
+
+
+/** The named formats. */
+export const FORMATS: Readonly<Record<FormatName, Readonly<Format>>>;
+/** The zones of a circle-cropped avatar of side `n`. */
+export function avatarZones(n: number): Zones;

package/src/formats/presets.js

@@ -0,0 +1,89 @@
+/**
+ * The named formats, as data: release covers, social posts and banners
+ * with their safe zones, flyers and posters, and print stationery.
+ *
+ * Zone figures are official where a platform publishes them (YouTube Help,
+ * Meta, LinkedIn); otherwise they're community measurements, and each
+ * format's `zones.source` says which.
+ *
+ * @module formats/presets
+ */
+
+/**
+ * @typedef {object} Format
+ * @property {number} width - In `unit`.
+ * @property {number} height - In `unit`.
+ * @property {'px' | 'mm' | 'in'} unit
+ * @property {string} label - What it is.
+ * @property {number} [bleed] - Default bleed, in mm (print).
+ * @property {number} [safe] - Default safe margin inside the trim, in mm (print).
+ * @property {string} [cut] - A die-cut shape: `'circle'` or `'rounded'`.
+ * @property {import('./index.js').Zones} [zones] - Where the platform crops or covers the image (screen formats, px).
+ */
+
+/**
+ * Safe zones, in px of the format's canvas.
+ *
+ * @typedef {object} Zones
+ * @property {[number, number, number, number]} safe - `[x, y, w, h]`: where type and marks are seen on every device; anchored text and icons are laid out inside it.
+ * @property {{ name: string, rect?: [number, number, number, number], circle?: [number, number, number] }[]} [avoid] - Areas covered by the platform's UI or the avatar.
+ * @property {{ name: string, rect: [number, number, number, number] }[]} [crops] - What one device shows.
+ * @property {string} source - Where the numbers come from (official, or a community measurement).
+ */
+
+/** A circle crop: the visible circle and the square inside it (with a little air). @param {number} n @returns {import('./index.js').Zones} */
+export const avatarZones = (n) => {
+  const side = Math.round((n / Math.SQRT2) * 0.94);
+  const o = Math.round((n - side) / 2);
+  return { safe: [o, o, side, side], avoid: [], crops: [{ name: 'circle', rect: [0, 0, n, n] }], source: 'Every listed platform crops avatars to a circle (X, Instagram, Threads, LinkedIn, YouTube, TikTok, Bluesky); the safe square is the one inscribed in it.' };
+};
+
+/** @type {Readonly<Record<string, Readonly<Format>>>} */
+export const FORMATS = Object.freeze({
+  // Release and streaming
+  release: { width: 3000, height: 3000, unit: 'px', label: 'Release cover art (Spotify, Apple Music, Bandcamp; 3000×3000)' },
+  'spotify-canvas': { width: 1080, height: 1920, unit: 'px', label: 'Spotify Canvas (9:16; a still frame or the poster for one)', zones: { safe: [60, 320, 960, 1040], avoid: [{ name: 'track info and controls', rect: [0, 1360, 1080, 560] }, { name: 'header', rect: [0, 0, 1080, 320] }], source: 'Spotify asks that Canvas carries no text and keeps its focus central; the player UI covers the bottom third (measured).' } },
+  'bandcamp-header': { width: 975, height: 180, unit: 'px', label: 'Bandcamp custom header (975 wide, 40–180 tall)' },
+  // Social
+  'instagram-post': { width: 1080, height: 1350, unit: 'px', label: 'Instagram post, 4:5 (1080×1350)', zones: { safe: [54, 135, 972, 1080], crops: [{ name: 'profile grid (3:4)', rect: [0, 0, 1080, 1350] }, { name: 'square', rect: [0, 135, 1080, 1080] }], source: '1080×1350 is Instagram\'s portrait size; older grid and some previews crop to the central square, so key type stays in it.' } },
+  'instagram-square': { width: 1080, height: 1080, unit: 'px', label: 'Instagram post, 1:1 (1080×1080)', zones: { safe: [54, 54, 972, 972], source: '1080×1080 is Instagram\'s square size.' } },
+  'instagram-story': { width: 1080, height: 1920, unit: 'px', label: 'Instagram story, 9:16 (1080×1920)', zones: { safe: [65, 250, 950, 1420], avoid: [{ name: 'profile and progress', rect: [0, 0, 1080, 250] }, { name: 'reply bar', rect: [0, 1670, 1080, 250] }], source: 'Meta: keep about 14% (250 px) at the top and bottom of a story free of text and logos.' } },
+  'instagram-reel': { width: 1080, height: 1920, unit: 'px', label: 'Instagram reel or reel cover, 9:16 (1080×1920)', zones: { safe: [65, 269, 950, 979], avoid: [{ name: 'top UI', rect: [0, 0, 1080, 269] }, { name: 'caption and buttons', rect: [0, 1248, 1080, 672] }, { name: 'action buttons', rect: [1015, 900, 65, 1020] }], crops: [{ name: 'profile grid (3:4)', rect: [0, 240, 1080, 1440] }], source: 'Meta: keep 14% at the top, 35% at the bottom and 6% at the sides of a reel free of text and logos.' } },
+  'youtube-thumbnail': { width: 1280, height: 720, unit: 'px', label: 'YouTube thumbnail, 16:9 (1280×720)', zones: { safe: [64, 48, 1152, 600], avoid: [{ name: 'duration', rect: [1100, 640, 180, 80] }], source: 'YouTube Help: 1280×720 (16:9). The duration badge over the bottom right is measured.' } },
+  og: { width: 1200, height: 630, unit: 'px', label: 'Open Graph card (link previews)', zones: { safe: [60, 40, 1080, 550], source: 'Open Graph cards show whole at 1.91:1; some clients crop to a square in the middle, so key type sits centrally.' } },
+  // Avatars: every platform crops to a circle.
+  avatar: { width: 1080, height: 1080, unit: 'px', label: 'Avatar, circle-cropped (X, Instagram, Threads, LinkedIn, YouTube, TikTok, Bluesky)', zones: avatarZones(1080) },
+  'x-avatar': { width: 400, height: 400, unit: 'px', label: 'X profile photo (400×400, shown as a circle)', zones: avatarZones(400) },
+  'youtube-avatar': { width: 800, height: 800, unit: 'px', label: 'YouTube profile picture (800×800, circle)', zones: avatarZones(800) },
+  // Banners and headers
+  'x-header': { width: 1500, height: 500, unit: 'px', label: 'X (Twitter) header (1500×500)', zones: { safe: [420, 60, 930, 380], avoid: [{ name: 'avatar', circle: [215, 470, 175] }], crops: [{ name: 'mobile', rect: [150, 50, 1200, 400] }], source: '1500×500 is X\'s upload size. The avatar overlapping the bottom left and the ~60 px trimmed top and bottom (and the narrower mobile view) are community measurements; X publishes no safe zone.' } },
+  'linkedin-banner': { width: 1584, height: 396, unit: 'px', label: 'LinkedIn personal background (1584×396)', zones: { safe: [600, 40, 940, 316], avoid: [{ name: 'avatar', circle: [300, 380, 230] }], source: '1584×396 is LinkedIn\'s recommended size; the profile photo over the bottom left is measured from the desktop profile.' } },
+  'linkedin-company': { width: 1128, height: 191, unit: 'px', label: 'LinkedIn company page cover (1128×191)', zones: { safe: [40, 24, 1048, 143], source: '1128×191 is LinkedIn\'s recommended size; the logo sits below the cover, not on it.' } },
+  'youtube-banner': { width: 2560, height: 1440, unit: 'px', label: 'YouTube channel art (2560×1440; the 1546×423 centre shows on every device)', zones: { safe: [507, 508, 1546, 423], crops: [{ name: 'tv', rect: [0, 0, 2560, 1440] }, { name: 'desktop', rect: [0, 508, 2560, 423] }, { name: 'tablet', rect: [352, 508, 1855, 423] }, { name: 'mobile', rect: [507, 508, 1546, 423] }], source: 'YouTube Help: upload at least 2048×1152 and keep text and logos in the 1235×338 centre (scaled here to 2560×1440: 1546×423).' } },
+  'facebook-cover': { width: 1640, height: 924, unit: 'px', label: 'Facebook page cover (16:9 upload: phones show it all, desktop a 2.63:1 band)', zones: { safe: [80, 150, 1480, 624], crops: [{ name: 'desktop', rect: [0, 150, 1640, 624] }, { name: 'mobile', rect: [0, 0, 1640, 924] }], avoid: [{ name: 'desktop profile picture', circle: [220, 774, 170] }], source: 'Meta Help: the cover shows at 820×312 on desktop and 640×360 on phones; this canvas is the 16:9 shape at 2×, with the desktop band in the middle.' } },
+  'twitch-banner': { width: 1200, height: 480, unit: 'px', label: 'Twitch profile banner (1200×480)', zones: { safe: [60, 40, 1080, 400], source: '1200×480 is Twitch\'s recommended size.' } },
+  'discord-banner': { width: 960, height: 540, unit: 'px', label: 'Discord server banner (960×540)', zones: { safe: [48, 40, 864, 460], source: '960×540 (16:9) is Discord\'s recommended size.' } },
+  'discord-profile': { width: 680, height: 240, unit: 'px', label: 'Discord profile banner (680×240)', zones: { safe: [34, 20, 612, 150], avoid: [{ name: 'avatar', circle: [110, 240, 80] }], source: '680×240 is Discord\'s recommended size; the avatar overlapping the bottom left is measured.' } },
+  'bluesky-banner': { width: 3000, height: 1000, unit: 'px', label: 'Bluesky profile banner (3000×1000)', zones: { safe: [600, 80, 2250, 760], avoid: [{ name: 'avatar', circle: [330, 960, 300] }], source: '3000×1000 is Bluesky\'s banner size; the avatar over the bottom left is measured.' } },
+  // Posts
+  pinterest: { width: 1000, height: 1500, unit: 'px', label: 'Pinterest pin (2:3, 1000×1500)', zones: { safe: [60, 60, 880, 1300], avoid: [{ name: 'save button', rect: [780, 1360, 220, 140] }], source: 'Pinterest recommends 1000×1500 (2:3). The UI over the lower right is measured.' } },
+  'tiktok-cover': { width: 1080, height: 1920, unit: 'px', label: 'TikTok video cover (1080×1920; the profile grid crops it to 3:4)', zones: { safe: [60, 240, 900, 1080], avoid: [{ name: 'top UI', rect: [0, 0, 1080, 240] }, { name: 'caption and sound', rect: [0, 1320, 1080, 600] }, { name: 'action buttons', rect: [960, 760, 120, 1160] }], crops: [{ name: 'profile grid', rect: [0, 240, 1080, 1440] }], source: 'TikTok publishes its safe zones as template files; these margins are the commonly measured ones (240 px top, ~600 px bottom, 120 px right), with the 3:4 grid crop.' } },
+  // Flyers and posters
+  flyer: { width: 1600, height: 2000, unit: 'px', label: 'Digital flyer, 4:5' },
+  a6: { width: 105, height: 148, unit: 'mm', label: 'A6 flyer', bleed: 3, safe: 4 },
+  a5: { width: 148, height: 210, unit: 'mm', label: 'A5 flyer', bleed: 3, safe: 5 },
+  a4: { width: 210, height: 297, unit: 'mm', label: 'A4 flyer or poster', bleed: 3, safe: 5 },
+  a3: { width: 297, height: 420, unit: 'mm', label: 'A3 poster', bleed: 3, safe: 8 },
+  a2: { width: 420, height: 594, unit: 'mm', label: 'A2 poster', bleed: 3, safe: 10 },
+  // Stationery
+  'business-card': { width: 85, height: 55, unit: 'mm', label: 'Business card (85×55 mm)', bleed: 3, safe: 3 },
+  'business-card-us': { width: 3.5, height: 2, unit: 'in', label: 'Business card (3.5×2 in)', bleed: 3, safe: 3 },
+  letterhead: { width: 210, height: 297, unit: 'mm', label: 'Letterhead (A4)', bleed: 3, safe: 15 },
+  'letterhead-us': { width: 8.5, height: 11, unit: 'in', label: 'Letterhead (US Letter)', bleed: 3, safe: 15 },
+  'compliment-slip': { width: 210, height: 99, unit: 'mm', label: 'Compliment slip (⅓ A4)', bleed: 3, safe: 8 },
+  sticker: { width: 60, height: 60, unit: 'mm', label: 'Sticker, die-cut round (60 mm)', bleed: 2, safe: 3, cut: 'circle' },
+  'sticker-square': { width: 60, height: 60, unit: 'mm', label: 'Sticker, die-cut rounded square (60 mm)', bleed: 2, safe: 3, cut: 'rounded' },
+  ticket: { width: 5.5, height: 2, unit: 'in', label: 'Event ticket (5.5×2 in), 3 mm corners', bleed: 3, safe: 3, cut: { radius: 3 } },
+  badge: { width: 54, height: 85.6, unit: 'mm', label: 'ID badge, CR80 portrait (54×85.6 mm)', bleed: 2, safe: 3, cut: 'rounded' },
+  'lanyard-pass': { width: 105, height: 148, unit: 'mm', label: 'Lanyard pass (A6 portrait), 4 mm corners', bleed: 3, safe: 5, cut: { radius: 4 } },
+});