@arraypress/covers 1.0.0 → 1.3.1

package/src/render/key.js

@@ -0,0 +1,90 @@
+/**
+ * Content-hash cache keys (Web Crypto: the same keys on every platform).
+ *
+ * @module render/key
+ */
+
+import { loadBytes, hexDigest, u8, isBytes } from '../platform/index.js';
+import { fontBytes } from '../fonts.js';
+import { cover } from '../render.js';
+import { VERSION } from '../version.js';
+
+/**
+ * A stable cache key for a cover and its output options: a SHA-256 of the
+ * resolved cover (font and image bytes hashed by content), the output
+ * format and quality, and this package's version.
+ *
+ * @param {import('../index.js').CoverOptions | import('../index.js').Cover} input - The cover.
+ * @param {import('../index.js').RenderImageOptions} [options]
+ * @returns {Promise<string>} 40 hex characters.
+ *
+ * @example
+ * await coverKey({ recipe: 'aurora', seed: 'a' }, { format: 'webp' }); // 'f3a9…'
+ */
+export async function coverKey(input, options = {}) {
+  const c = cover(input);
+  const head = `covers@${VERSION}\n${options.format ?? 'webp'}:${options.quality ?? ''}:${options.effort ?? ''}:${options.lossless ?? c.output?.lossless ?? ''}\n`;
+  // Files a layer reads (an image's src, a mesh's photo, a waveform's audio) are hashed by content.
+  const file = async (/** @type {any} */ v) => (typeof v === 'string' && !v.startsWith('data:') ? digest(await loadBytes(v)) : isBytes(v) ? digest(v) : v);
+  const layers = await Promise.all(c.layers.map(async (l) => {
+    const x = /** @type {any} */ (l);
+    if (l.type === 'image') return { ...l, src: await file(x.src) };
+    if (l.type === 'mesh' && x.from) return { ...l, from: await file(x.from) };
+    if (l.type === 'waveform' && x.audio) return { ...l, audio: await file(x.audio) };
+    return l;
+  }));
+  const body = await hashBytes({
+    width: c.width,
+    height: c.height,
+    seed: c.seed,
+    palette: c.palette,
+    layers,
+    radius: c.radius,
+    fonts: await Promise.all(c.fonts.map(async (f) => ({ ...f, data: await digest(f.data ?? await fontBytes(f)) }))),
+    ...(c.print ? { print: c.print } : {}),
+    ...(c.side && c.side !== 'front' ? { side: c.side } : {}),
+  });
+  return (await hexDigest('SHA-256', head + stable(body))).slice(0, 40);
+}
+
+/** @param {Uint8Array | ArrayBuffer} data @returns {Promise<string>} SHA-1 hex. */
+function digest(data) {
+  return hexDigest('SHA-1', u8(data));
+}
+
+/**
+ * Replace every byte array in a value with its SHA-1 (what {@link stable}
+ * writes for bytes), so the hashing itself can stay synchronous.
+ *
+ * @param {unknown} v
+ * @returns {Promise<unknown>}
+ */
+async function hashBytes(v) {
+  if (isBytes(v)) return { [BYTES]: await digest(/** @type {any} */ (v)) };
+  if (Array.isArray(v)) return Promise.all(v.map(hashBytes));
+  if (v && typeof v === 'object' && !(v instanceof URL)) {
+    const out = /** @type {Record<string, unknown>} */ ({});
+    for (const [k, x] of Object.entries(v)) out[k] = await hashBytes(x);
+    return out;
+  }
+  return v;
+}
+
+const BYTES = Symbol('bytes');
+
+/**
+ * JSON with sorted keys and bytes hashed, for hashing.
+ *
+ * @param {unknown} v
+ * @returns {string}
+ */
+function stable(v) {
+  if (v && typeof v === 'object' && BYTES in v) return JSON.stringify(/** @type {any} */ (v)[BYTES]);
+  if (Array.isArray(v)) return `[${v.map(stable).join(',')}]`;
+  if (v instanceof URL) return JSON.stringify(v.href);
+  if (v && typeof v === 'object') {
+    return `{${Object.keys(v).sort().filter((k) => /** @type {any} */ (v)[k] !== undefined).map((k) => `${JSON.stringify(k)}:${stable(/** @type {any} */ (v)[k])}`).join(',')}}`;
+  }
+  if (typeof v === 'function') return JSON.stringify(String(v));
+  return JSON.stringify(v) ?? 'null';
+}

package/src/render/report.d.ts

@@ -0,0 +1,5 @@
+// Scaling what a render reports.
+import type { DrawnText, DrawnImage } from './context.js';
+
+/** A report hook for a stack drawn `k` times larger (text sizes become canvas px). */
+export function scaledReport(report: ((e: DrawnText | DrawnImage) => void) | undefined, k: number): ((e: DrawnText | DrawnImage) => void) | undefined;

package/src/render/report.js

@@ -0,0 +1,19 @@
+/**
+ * What a render reports for `lint`, scaled to canvas px.
+ *
+ * @module render/report
+ */
+
+/**
+ * A report hook for a stack drawn `k` times larger: text sizes become
+ * canvas px (the box is dropped, being in the stack's own units). Other
+ * entries carry their own scale and pass through.
+ *
+ * @param {((e: any) => void) | undefined} report
+ * @param {number} k
+ * @returns {((e: any) => void) | undefined}
+ */
+export function scaledReport(report, k) {
+  if (!report || k === 1) return report;
+  return (e) => report(e.kind === 'text' ? { ...e, size: e.size * k, capHeight: e.capHeight * k, box: null } : e);
+}

package/src/render/transform.d.ts

@@ -0,0 +1,36 @@
+// A layer's `transform` option as an SVG transform.
+import type { Length } from '../index.js';
+
+/** A transform any layer takes (about `origin`, default the canvas centre). */
+export interface LayerTransform {
+  translate?: [Length, Length] | { x?: Length; y?: Length };
+  /** Degrees. */
+  rotate?: number;
+  scale?: number | [number, number];
+  skewX?: number;
+  skewY?: number;
+  /** `'x'` flips left–right, `'y'` top–bottom. */
+  mirror?: 'x' | 'y' | 'both';
+  /** `[x, y]` px, or `'center'`. */
+  origin?: [Length, Length] | { x?: Length; y?: Length } | 'center';
+}
+
+/** A transform's `origin` in px (`'center'`, the default, is the canvas centre). */
+export function originOf(origin: LayerTransform['origin'], canvas: { width: number; height: number }): [number, number];
+/** A `transform` option as an SVG transform string (a string is used as written). */
+export function transformAttr(t: LayerTransform | string | undefined, canvas: { width: number; height: number }): string | undefined;
+
+/** An affine matrix `[a, b, c, d, e, f]`, as SVG's `matrix()`. */
+export type Affine = [number, number, number, number, number, number];
+/** A transform (string or object form) as one matrix. */
+export function transformMatrix(t: LayerTransform | string | undefined, canvas: { width: number; height: number }): Affine;
+/** How much a matrix enlarges what it draws: smallest and largest stretch, and their geometric mean. */
+export function stretchOf(m: Affine): { min: number; max: number; mean: number };
+/** The inverse of an affine matrix. */
+export function invert(m: Affine): Affine;
+/** A point through an affine matrix. */
+export function apply(m: Affine, x: number, y: number): [number, number];
+/** The identity matrix. */
+export const IDENTITY: Readonly<Affine>;
+/** `m × n`: `n` applied first, in `m`'s space. */
+export function compose(m: Affine, n: Affine): Affine;

package/src/render/transform.js

@@ -0,0 +1,139 @@
+/**
+ * A layer's `transform` option as an SVG transform.
+ *
+ * @module render/transform
+ */
+
+import { num } from '@logomarks/image-effects/svg';
+import { pos } from '../layers/util.js';
+
+/**
+ * A layer's `transform` as an SVG transform string.
+ *
+ * Object form: `translate` (`[x, y]` or `{ x, y }`, lengths), `rotate`
+ * (degrees), `scale` (a number or `[sx, sy]`), `skewX`, `skewY`, `mirror`
+ * (`'x'` flips left–right, `'y'` top–bottom), all about `origin` (`[x, y]`
+ * px or `'center'`, the default). A string is used as written.
+ *
+ * @param {any} t
+ * @param {{ width: number, height: number }} canvas
+ * @returns {string | undefined}
+ */
+export function transformAttr(t, canvas) {
+  if (!t) return undefined;
+  if (typeof t === 'string') return t;
+  const parts = [];
+  const tr = Array.isArray(t.translate) ? { x: t.translate[0], y: t.translate[1] } : t.translate;
+  if (tr) parts.push(`translate(${num(pos(tr.x ?? 0, 'x', canvas))} ${num(pos(tr.y ?? 0, 'y', canvas))})`);
+  const o = originOf(t.origin, canvas);
+  const inner = [];
+  if (t.rotate) inner.push(`rotate(${num(t.rotate, 3)})`);
+  let [sx, sy] = t.scale == null ? [1, 1] : Array.isArray(t.scale) ? t.scale : [t.scale, t.scale];
+  if (t.mirror === 'x' || t.mirror === 'both') sx = -sx;
+  if (t.mirror === 'y' || t.mirror === 'both') sy = -sy;
+  if (sx !== 1 || sy !== 1) inner.push(`scale(${num(sx, 4)} ${num(sy, 4)})`);
+  if (t.skewX) inner.push(`skewX(${num(t.skewX, 3)})`);
+  if (t.skewY) inner.push(`skewY(${num(t.skewY, 3)})`);
+  if (inner.length) parts.push(`translate(${num(o[0])} ${num(o[1])}) ${inner.join(' ')} translate(${num(-o[0])} ${num(-o[1])})`);
+  return parts.length ? parts.join(' ') : undefined;
+}
+
+/**
+ * A transform's `origin` in px: `[x, y]` or `{ x, y }` (px, `'%'` or
+ * lengths), or `'center'` (the default).
+ *
+ * @param {unknown} origin
+ * @param {{ width: number, height: number }} canvas
+ * @returns {[number, number]}
+ */
+export function originOf(origin, canvas) {
+  if (origin === undefined || origin === 'center') return [canvas.width / 2, canvas.height / 2];
+  const o = /** @type {any} */ (origin);
+  return Array.isArray(o) ? [pos(o[0], 'x', canvas), pos(o[1], 'y', canvas)] : [pos(o.x, 'x', canvas), pos(o.y, 'y', canvas)];
+}
+
+/** @typedef {[number, number, number, number, number, number]} Affine - `[a, b, c, d, e, f]`, as SVG's `matrix()`. */
+
+/** @param {Affine} m @param {Affine} n @returns {Affine} `m × n`. */
+const multiply = (m, n) => [
+  m[0] * n[0] + m[2] * n[1], m[1] * n[0] + m[3] * n[1],
+  m[0] * n[2] + m[2] * n[3], m[1] * n[2] + m[3] * n[3],
+  m[0] * n[4] + m[2] * n[5] + m[4], m[1] * n[4] + m[3] * n[5] + m[5],
+];
+
+/** @param {string} name @param {number[]} v @returns {Affine} One SVG transform function as a matrix. */
+function fn(name, v) {
+  const r = ((v[0] ?? 0) * Math.PI) / 180;
+  switch (name) {
+    case 'translate': return [1, 0, 0, 1, v[0] ?? 0, v[1] ?? 0];
+    case 'scale': return [v[0] ?? 1, 0, 0, v[1] ?? v[0] ?? 1, 0, 0];
+    case 'rotate': {
+      const m = /** @type {Affine} */ ([Math.cos(r), Math.sin(r), -Math.sin(r), Math.cos(r), 0, 0]);
+      if (v.length < 3) return m;
+      return multiply(multiply([1, 0, 0, 1, v[1], v[2]], m), [1, 0, 0, 1, -v[1], -v[2]]);
+    }
+    case 'skewX': return [1, 0, Math.tan(r), 1, 0, 0];
+    case 'skewY': return [1, Math.tan(r), 0, 1, 0, 0];
+    case 'matrix': return /** @type {Affine} */ (v.slice(0, 6));
+    default: return [1, 0, 0, 1, 0, 0];
+  }
+}
+
+/**
+ * A transform (an SVG transform string, or the object form) as one matrix.
+ *
+ * @param {any} t
+ * @param {{ width: number, height: number }} canvas
+ * @returns {Affine}
+ */
+export function transformMatrix(t, canvas) {
+  const s = transformAttr(t, canvas);
+  /** @type {Affine} */
+  let m = [1, 0, 0, 1, 0, 0];
+  if (!s) return m;
+  for (const [, name, args] of s.matchAll(/(\w+)\s*\(([^)]*)\)/g)) m = multiply(m, fn(name, args.split(/[\s,]+/).filter(Boolean).map(Number)));
+  return m;
+}
+
+/**
+ * How much a matrix enlarges what it draws: its smallest and largest
+ * stretch (singular values), and their geometric mean.
+ *
+ * @param {Affine} m
+ * @returns {{ min: number, max: number, mean: number }}
+ */
+export function stretchOf(m) {
+  const [a, b, c, d] = m;
+  const sum = a * a + b * b + c * c + d * d;
+  const det = Math.abs(a * d - b * c);
+  const root = Math.sqrt(Math.max(0, sum * sum - 4 * det * det));
+  return { min: Math.sqrt((sum - root) / 2), max: Math.sqrt((sum + root) / 2), mean: Math.sqrt(det) };
+}
+
+/**
+ * The inverse of an affine matrix.
+ *
+ * @param {Affine} m
+ * @returns {Affine}
+ */
+export function invert(m) {
+  const [a, b, c, d, e, f] = m;
+  const det = a * d - b * c || 1e-12;
+  return [d / det, -b / det, -c / det, a / det, (c * f - d * e) / det, (b * e - a * f) / det];
+}
+
+/**
+ * A point through an affine matrix.
+ *
+ * @param {Affine} m @param {number} x @param {number} y
+ * @returns {[number, number]}
+ */
+export function apply(m, x, y) {
+  return [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]];
+}
+
+/** The identity matrix. @type {Affine} */
+export const IDENTITY = Object.freeze(/** @type {Affine} */ ([1, 0, 0, 1, 0, 0]));
+
+/** @param {Affine} m @param {Affine} n @returns {Affine} `m` then `n` (n applied first, in m's space). */
+export const compose = (m, n) => multiply(m, n);

package/src/render/use.d.ts

@@ -0,0 +1,27 @@
+// Reusable stacks: `defs` and `use`.
+import type { Layer, BaseLayer, Length } from '../index.js';
+import type { LayerTransform } from './transform.js';
+import type { RenderContext, Markup } from './context.js';
+
+/** `defs`: named layers (each with an `id`) that `use` draws; nothing is drawn here. */
+export interface DefsLayer extends BaseLayer { type: 'defs'; layers: Layer[] }
+
+/** `use`: a named layer drawn again, placed. */
+export interface UseLayer extends BaseLayer {
+  type: 'use';
+  /** The `id` of a layer in an earlier `defs`. */
+  ref: string;
+  x?: Length | `${number}%`; y?: Length | `${number}%`;
+  /** Degrees, about the copy's origin. */
+  rotate?: number;
+  scale?: number | [number, number];
+  /** A transform instead of x, y, rotate and scale. */
+  place?: LayerTransform | string;
+  /** Options for this copy only (drawn on its own). */
+  with?: Record<string, unknown>;
+}
+
+/** Register a defs layer's named layers. */
+export function registerDefs(layer: DefsLayer, ctx: RenderContext): Markup;
+/** Draw a named layer, placed. */
+export function renderUse(layer: UseLayer, ctx: RenderContext): Promise<Markup>;

package/src/render/use.js

@@ -0,0 +1,73 @@
+/**
+ * Reusable stacks: a `defs` layer names layers (by `id`) without drawing
+ * them; a `use` layer draws one, placed (`x`, `y`, `scale`, `rotate`, or a
+ * `transform`). A plain `use` draws the same markup every time (it's drawn
+ * once and referenced); `with` overrides options for that copy, which is
+ * drawn on its own.
+ *
+ * @module render/use
+ */
+
+import { attrs, num } from '@logomarks/image-effects/svg';
+import { pos, wrap } from '../layers/util.js';
+import { transformAttr } from './transform.js';
+
+/**
+ * `defs`: register named layers for `use`.
+ *
+ * @param {any} layer
+ * @param {any} ctx
+ * @returns {{ defs: string, body: string }}
+ */
+export function registerDefs(layer, ctx) {
+  for (const l of layer.layers ?? []) {
+    if (!l?.id) throw new TypeError('Every layer in a defs layer needs an id (use refers to it)');
+    ctx.defs.set(l.id, l);
+  }
+  return { defs: '', body: '' };
+}
+
+/**
+ * `use`: draw a named layer, placed.
+ *
+ * @param {any} layer
+ * @param {any} ctx
+ * @returns {Promise<{ defs: string, body: string }>}
+ */
+export async function renderUse(layer, ctx) {
+  const def = ctx.defs?.get(layer.ref);
+  if (!def) throw new TypeError(`use: no layer "${layer.ref}" in a defs layer drawn before it`);
+  const place = placement(layer, ctx);
+  if (layer.with) {
+    const parts = await ctx.stack([{ ...def, ...layer.with }], { tag: 'u' });
+    const body = parts.map((/** @type {any} */ p) => p.body).join('');
+    return { defs: parts.map((/** @type {any} */ p) => p.defs).join(''), body: wrap(layer, place ? `<g transform="${place}">${body}</g>` : body) };
+  }
+  // Drawn once per canvas size, then referenced.
+  const key = `${layer.ref}@${num(ctx.width)}x${num(ctx.height)}`;
+  let drawn = ctx.defs.get(`#${key}`);
+  let defs = '';
+  if (!drawn) {
+    const parts = await ctx.stack([def], { tag: 'u' });
+    drawn = { id: `${ctx.id}u` };
+    ctx.defs.set(`#${key}`, drawn);
+    defs = parts.map((/** @type {any} */ p) => p.defs).join('') + `<g id="${drawn.id}">${parts.map((/** @type {any} */ p) => p.body).join('')}</g>`;
+  }
+  return { defs, body: wrap(layer, `<use${attrs({ href: `#${drawn.id}`, transform: place })}/>`) };
+}
+
+/**
+ * Where a copy goes: `transform` as written, else `x`, `y`, `rotate`
+ * (about the copy's origin) and `scale`.
+ *
+ * @param {any} l @param {any} ctx
+ * @returns {string | undefined}
+ */
+function placement(l, ctx) {
+  if (l.place) return transformAttr(l.place, ctx.canvas);
+  const parts = [];
+  if (l.x != null || l.y != null) parts.push(`translate(${num(pos(l.x ?? 0, 'x', ctx.canvas), 3)} ${num(pos(l.y ?? 0, 'y', ctx.canvas), 3)})`);
+  if (l.rotate) parts.push(`rotate(${num(l.rotate, 3)})`);
+  if (l.scale != null && l.scale !== 1) parts.push(Array.isArray(l.scale) ? `scale(${num(l.scale[0], 4)} ${num(l.scale[1], 4)})` : `scale(${num(l.scale, 4)})`);
+  return parts.length ? parts.join(' ') : undefined;
+}

package/src/render/wrap.d.ts

@@ -0,0 +1,14 @@
+// The options every layer takes on top of its own.
+import type { Layer, Cover } from '../index.js';
+import type { RenderContext, Markup } from './context.js';
+
+/** Options handled for every layer type. */
+export const WRAP_KEYS: readonly ('effects' | 'mask' | 'knockout' | 'clip' | 'area')[];
+/** Case keywords (a text layer's `transform` is its case when it's one of these). */
+export const CASES: ReadonlySet<string>;
+/** Whether a layer uses any of them (1.0 layers take the 1.0 path). */
+export function wrapped(layer: Layer): boolean;
+/** Draw a layer with its area, effects, transform and masks; blend and opacity outermost. */
+export function renderWrapped(layer: Layer, ctx: RenderContext, scope: { c: Cover }, renderOne: (layer: Layer, ctx: RenderContext) => Promise<Markup>): Promise<Markup>;
+/** A layer's effects, then its masks, round its markup (in `ctx`'s units: a group's grid inside a group). */
+export function decorate(m: Markup, layer: Layer, ctx: RenderContext): Promise<Markup>;

package/src/render/wrap.js

@@ -0,0 +1,144 @@
+/**
+ * The options every layer takes on top of its own: `area`, `effects`,
+ * `transform`, `mask`, `knockout` and `clip`.
+ *
+ * @module render/wrap
+ */
+
+import { attrs, esc, num } from '@logomarks/image-effects/svg';
+import { drawEffects, contentBox } from '@logomarks/image-effects';
+import { transformAttr, transformMatrix, stretchOf, compose, IDENTITY } from './transform.js';
+import { renderGroup } from './group.js';
+import { scaledReport } from './report.js';
+
+/** Layer options handled here, for every layer type. */
+export const WRAP_KEYS = ['effects', 'mask', 'knockout', 'clip', 'area'];
+
+/** Text-case keywords (the text layer's `transform` is its case when it's one of these). */
+export const CASES = new Set(['uppercase', 'lowercase', 'none']);
+
+/**
+ * Whether a layer uses the common 1.1 options (so 1.0 layers take exactly
+ * the 1.0 path).
+ *
+ * @param {any} layer
+ * @returns {boolean}
+ */
+export function wrapped(layer) {
+  if (WRAP_KEYS.some((k) => layer[k] != null)) return true;
+  return isGeometric(layer);
+}
+
+/** @param {any} layer @returns {boolean} Whether `transform` is geometry (not a text case). */
+const isGeometric = (layer) => layer.transform != null && !(layer.type === 'text' && typeof layer.transform === 'string' && CASES.has(layer.transform));
+
+/**
+ * A layer with `area`, `effects`, `transform`, `mask`, `knockout` or
+ * `clip`. Blend and opacity go on the outermost group, so a masked or
+ * filtered layer still blends with what's under it. On a `group` with a
+ * `viewBox`, effects and masks work in the group's own grid.
+ *
+ * @param {any} layer
+ * @param {any} ctx
+ * @param {{ c: import('../index.js').Cover }} scope
+ * @param {(layer: any, ctx: any) => Promise<{ defs: string, body: string }>} renderOne - Draws the layer itself.
+ * @returns {Promise<{ defs: string, body: string }>}
+ */
+export async function renderWrapped(layer, ctx, scope, renderOne) {
+  const inner = { ...layer, opacity: undefined, blend: undefined, effects: undefined, mask: undefined, knockout: undefined, clip: undefined, area: undefined };
+  const geometric = isGeometric(layer);
+  if (geometric) inner.transform = undefined;
+  const grid = layer.type === 'group' && layer.viewBox != null;
+
+  const box = areaBox(layer.area, ctx, scope);
+  /** @type {any} */
+  let lctx = box ? { ...ctx, width: box.width, height: box.height, canvas: { width: box.width, height: box.height }, inset: undefined, matrix: compose(ctx.matrix ?? IDENTITY, [1, 0, 0, 1, box.x, box.y]) } : ctx;
+  // What's drawn inside a transform is drawn that much larger (images resample for it, lint measures it).
+  if (geometric) {
+    const t = transformMatrix(layer.transform, lctx.canvas);
+    const k = stretchOf(t);
+    lctx = { ...lctx, matrix: compose(lctx.matrix ?? IDENTITY, t) };
+    if (k.max !== 1 || k.mean !== 1) Object.assign(lctx, { scale: (lctx.scale ?? 1) * k.mean, res: (lctx.res ?? 1) * k.max, report: scaledReport(lctx.report, k.mean) });
+  }
+
+  let { defs, body } = grid
+    ? await renderGroup(inner, lctx, (/** @type {any} */ part, /** @type {any} */ gctx) => decorate(part, layer, gctx))
+    : await drawEffects(await renderOne(inner, lctx), layer.effects, lctx);
+  if (geometric) {
+    const t = transformAttr(layer.transform, lctx.canvas);
+    if (t) body = `<g transform="${t}">${body}</g>`;
+  }
+  if (box) body = `<g transform="translate(${num(box.x)} ${num(box.y)})">${body}</g>`;
+  if (!grid) ({ defs, body } = await decorateMasks({ defs, body }, layer, ctx));
+  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 });
+  if (a) body = `<g${a}>${body}</g>`;
+  return { defs, body };
+}
+
+/**
+ * `area`: the box a layer is drawn in (the trim, the safe area, or
+ * fractions of the canvas), or null for the whole canvas.
+ *
+ * @param {any} a
+ * @param {any} ctx
+ * @param {{ c: import('../index.js').Cover }} scope
+ * @returns {{ x: number, y: number, width: number, height: number } | null}
+ */
+function areaBox(a, ctx, scope) {
+  if (!a || a === 'bleed') return null;
+  if (a === 'trim' || a === 'safe') {
+    const print = /** @type {any} */ (scope.c).print;
+    const inset = print ? print.bleed + (a === 'safe' ? print.safe : 0) : 0;
+    return { x: inset, y: inset, width: ctx.width - 2 * inset, height: ctx.height - 2 * inset };
+  }
+  return { x: (a.x ?? 0) * ctx.width, y: (a.y ?? 0) * ctx.height, width: (a.width ?? 1 - (a.x ?? 0)) * ctx.width, height: (a.height ?? 1 - (a.y ?? 0)) * ctx.height };
+}
+
+/**
+ * A layer's effects, then its masks, round its markup.
+ *
+ * @param {{ defs: string, body: string }} m
+ * @param {any} layer
+ * @param {any} ctx
+ * @returns {Promise<{ defs: string, body: string }>}
+ */
+export async function decorate(m, layer, ctx) {
+  return decorateMasks(await drawEffects(m, layer.effects, ctx), layer, ctx);
+}
+
+/**
+ * Masks: sub-stacks drawn as a luminance mask. `knockout` cuts its layers
+ * out of this one; `clip` shows this one only where they paint; `mask`
+ * uses their luminance as drawn (a white-to-black gradient fades).
+ *
+ * @param {{ defs: string, body: string }} m
+ * @param {any} layer
+ * @param {any} ctx
+ * @returns {Promise<{ defs: string, body: string }>}
+ */
+async function decorateMasks(m, layer, ctx) {
+  let { defs, body } = m;
+  const masks = [['mask', layer.mask], ['knockout', layer.knockout], ['clip', layer.clip]].filter(([, v]) => v != null);
+  for (const [kind, list] of masks) {
+    const sub = await ctx.stack(Array.isArray(list) ? list : [list], { tag: `${kind[0]}` });
+    const mid = `${ctx.id}${kind[0]}m`;
+    const fid = `${ctx.id}${kind[0]}f`;
+    const subDefs = sub.map((/** @type {any} */ p) => p.defs).join('');
+    let subBody = sub.map((/** @type {any} */ p) => p.body).join('');
+    const pad = Math.max(ctx.width, ctx.height);
+    const region = { x: -pad, y: -pad, width: ctx.width + 2 * pad, height: ctx.height + 2 * pad };
+    let mdefs = subDefs;
+    if (kind === 'knockout' || kind === 'clip') {
+      // Whatever the sub-layers paint becomes black (cut) or white (kept), keeping their alpha
+      // (in renderImage, over just what they paint).
+      const v = kind === 'knockout' ? 0 : 1;
+      const painted = await contentBox({ defs: subDefs, body: subBody }, ctx);
+      mdefs += `<filter${attrs({ id: fid, filterUnits: 'userSpaceOnUse', ...(painted ?? region), 'color-interpolation-filters': 'sRGB' })}><feColorMatrix type="matrix" values="0 0 0 0 ${v} 0 0 0 0 ${v} 0 0 0 0 ${v} 0 0 0 1 0"/></filter>`;
+      subBody = `<g filter="url(#${fid})">${subBody}</g>`;
+      if (kind === 'knockout') subBody = `<rect${attrs({ ...region, fill: '#fff' })}/>${subBody}`;
+    }
+    defs += `${mdefs}<mask${attrs({ id: mid, maskUnits: 'userSpaceOnUse', ...region })}>${subBody}</mask>`;
+    body = `<g mask="url(#${mid})">${body}</g>`;
+  }
+  return { defs, body };
+}