@arraypress/covers 0.0.0-stage → 1.1.0

package/src/render/group.js

@@ -0,0 +1,67 @@
+/**
+ * The `group` layer: a nested stack on its own design grid.
+ *
+ * @module render/group
+ */
+
+import { attrs, esc, num } from '../svg.js';
+import { pos } from '../layers/util.js';
+import { scaledReport } from './report.js';
+import { IDENTITY, compose } from '../effects/transform.js';
+
+/**
+ * `group` — a stack of layers drawn as one: in a box (`x`, `y`, `width`,
+ * `height`, px), on its own design grid (`viewBox: [x, y, w, h]`, so a
+ * flyer drawn on a 400×500 grid keeps its numbers at any output size), and
+ * fitted by `fit` (`'contain'`, `'cover'`, `'stretch'`, `'width'`, `'height'`).
+ * The group's own `transform`, `effects` and masks apply to the whole
+ * (effects and masks in the grid's units, through `decorate`).
+ *
+ * @param {any} layer
+ * @param {any} ctx
+ * @param {(m: { defs: string, body: string }, gctx: any) => Promise<{ defs: string, body: string }>} [decorate] - Wraps the children, in the grid's units.
+ * @returns {Promise<{ defs: string, body: string }>}
+ */
+export async function renderGroup(layer, ctx, decorate) {
+  const bx = pos(layer.x ?? 0, 'x', ctx.canvas);
+  const by = pos(layer.y ?? 0, 'y', ctx.canvas);
+  const bw = layer.width != null ? pos(layer.width, 'x', ctx.canvas) : ctx.width - bx;
+  const bh = layer.height != null ? pos(layer.height, 'y', ctx.canvas) : ctx.height - by;
+  const vb = layer.viewBox ? (Array.isArray(layer.viewBox) ? layer.viewBox : String(layer.viewBox).split(/[\s,]+/).map(Number)) : [0, 0, bw, bh];
+  const [vx, vy, vw, vh] = vb;
+  const fit = layer.fit ?? 'contain';
+  let sx = bw / vw;
+  let sy = bh / vh;
+  if (fit === 'contain') sx = sy = Math.min(sx, sy);
+  else if (fit === 'cover') sx = sy = Math.max(sx, sy);
+  else if (fit === 'width') sy = sx;
+  else if (fit === 'height') sx = sy;
+  const [ax, ay] = alignOf(layer.align);
+  const tx = bx + (bw - vw * sx) * ax;
+  const ty = by + (bh - vh * sy) * ay;
+  const k = Math.min(sx, sy);
+  /** @type {import('../effects/transform.js').Affine} Grid units to the box. */
+  const grid = [sx, 0, 0, sy, tx - vx * sx, ty - vy * sy];
+  const parts = await ctx.stack(layer.layers ?? [], { tag: 'g', width: vw, height: vh, scale: k, res: Math.max(sx, sy), matrix: grid });
+  let defs = parts.map((/** @type {any} */ p) => p.defs).join('');
+  let body = parts.map((/** @type {any} */ p) => p.body).join('');
+  if (decorate) {
+    const gctx = { ...ctx, width: vw, height: vh, canvas: { width: vw, height: vh }, inset: undefined, scale: (ctx.scale ?? 1) * k, res: (ctx.res ?? 1) * Math.max(sx, sy), report: scaledReport(ctx.report, k), matrix: compose(ctx.matrix ?? IDENTITY, grid) };
+    ({ defs, body } = await decorate({ defs, body }, gctx));
+  }
+  const identity = tx === 0 && ty === 0 && sx === 1 && sy === 1 && vx === 0 && vy === 0;
+  if (!identity) body = `<g transform="translate(${num(tx, 3)} ${num(ty, 3)}) scale(${num(sx, 6)} ${num(sy, 6)})${vx || vy ? ` translate(${num(-vx, 3)} ${num(-vy, 3)})` : ''}">${body}</g>`;
+  if (fit === 'cover' || layer.clipToBox) {
+    defs += `<clipPath id="${ctx.id}gc"><rect${attrs({ x: bx, y: by, width: bw, height: bh })}/></clipPath>`;
+    body = `<g clip-path="url(#${ctx.id}gc)">${body}</g>`;
+  }
+  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 { defs, body: a ? `<g${a}>${body}</g>` : body };
+}
+
+/** @param {string | undefined} a @returns {[number, number]} */
+export function alignOf(a = 'center') {
+  const x = a.includes('left') ? 0 : a.includes('right') ? 1 : 0.5;
+  const y = a.includes('top') ? 0 : a.includes('bottom') ? 1 : 0.5;
+  return [x, y];
+}

package/src/render/key.d.ts

@@ -0,0 +1,5 @@
+// Content-hash cache keys.
+import type { Cover, CoverOptions, RenderImageOptions } from '../index.js';
+
+/** A stable cache key for a cover and its output options (40 hex characters). */
+export function coverKey(input: CoverOptions | Cover, options?: RenderImageOptions): Promise<string>;

package/src/render/key.js

@@ -0,0 +1,91 @@
+/**
+ * Content-hash cache keys (Web Crypto: the same keys on every platform).
+ *
+ * @module render/key
+ */
+
+import { loadBytes } from '../platform/index.js';
+import { hexDigest, u8, isBytes } from '../platform/bytes.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/tiles.d.ts

@@ -0,0 +1,6 @@
+// Large SVGs with filters, rasterised in tiles.
+
+/** An SVG document's RGBA pixels at its own size (in tiles when large and filtered). */
+export function svgPixels(sharp: unknown, svg: string, width: number, height: number, known?: number): Promise<Uint8Array>;
+/** How far any filter in a document reaches, output px, estimated from its markup. */
+export function reach(svg: string): number;

package/src/render/tiles.js

@@ -0,0 +1,77 @@
+/**
+ * Rasterising a large SVG with filters in tiles.
+ *
+ * librsvg (through libvips) slows down sharply past a few megapixels when
+ * a document has filters: a 3000² displacement map takes ~28 s in one
+ * render and ~5 s as four 1500² tiles. So a large document with filters is
+ * drawn as tiles, each with a margin round it (librsvg clips a filter's
+ * input to the viewport, so a blur or displacement at a tile's edge needs
+ * the pixels beyond it: the margin is the furthest any filter reaches),
+ * cropped and assembled. Tiles render in parallel. A document whose
+ * filters reach further than a tile renders in one piece.
+ *
+ * @module render/tiles
+ */
+
+import { filterReach } from '../effects/region.js';
+
+/** Documents below this many pixels render in one piece. */
+const MIN_TILED = 2.4e6;
+
+/** Tile side, px (before margins). */
+const TILE = 1024;
+
+/**
+ * An SVG document's RGBA pixels at its own size.
+ *
+ * @param {any} sharp
+ * @param {string} svg - A document whose root is `width`×`height` with `viewBox="0 0 width height"`.
+ * @param {number} width
+ * @param {number} height
+ * @param {number} [known=0] - How far the filters the layers drew reach, output px (they report it at their own resolution).
+ * @returns {Promise<Uint8Array>}
+ */
+export async function svgPixels(sharp, svg, width, height, known = 0) {
+  const margin = width * height < MIN_TILED || !/<filter\b/.test(svg) ? Infinity : Math.max(known + 16, reach(svg));
+  // Filters reaching further than a tile (a heavy blur) render in one piece.
+  if (margin > TILE) return sharp(Buffer.from(svg)).ensureAlpha().raw().toBuffer();
+  const open = /^<svg\b[^>]*>/.exec(svg);
+  if (!open) return sharp(Buffer.from(svg)).ensureAlpha().raw().toBuffer();
+  const rest = svg.slice(open[0].length);
+  const root = open[0].replace(/\s(width|height|viewBox)="[^"]*"/g, '').replace(/>$/, '');
+  const out = Buffer.alloc(width * height * 4);
+  /** @type {(() => Promise<void>)[]} */
+  const jobs = [];
+  for (let y = 0; y < height; y += TILE) {
+    for (let x = 0; x < width; x += TILE) {
+      const tw = Math.min(TILE, width - x);
+      const th = Math.min(TILE, height - y);
+      jobs.push(async () => {
+        const vw = tw + 2 * margin;
+        const vh = th + 2 * margin;
+        const doc = `${root} width="${vw}" height="${vh}" viewBox="${x - margin} ${y - margin} ${vw} ${vh}">${rest}`;
+        const px = await sharp(Buffer.from(doc)).ensureAlpha().extract({ left: margin, top: margin, width: tw, height: th }).raw().toBuffer();
+        for (let r = 0; r < th; r++) px.copy(out, ((y + r) * width + x) * 4, r * tw * 4, (r + 1) * tw * 4);
+      });
+    }
+  }
+  // A few at a time: each holds its filter surfaces.
+  const lanes = 4;
+  await Promise.all(Array.from({ length: lanes }, async (_, i) => { for (let j = i; j < jobs.length; j += lanes) await jobs[j](); }));
+  return out;
+}
+
+/**
+ * How far, in output px, any filter in a document reaches, estimated from
+ * the markup: the primitives' reach times the largest scale it's drawn at.
+ * (Effects report their own reach at their own resolution; this covers
+ * filters written by other layers.)
+ *
+ * @param {string} svg
+ * @returns {number}
+ */
+export function reach(svg) {
+  let scale = 1;
+  for (const m of svg.matchAll(/scale\(([^)]*)\)/g)) for (const v of m[1].trim().split(/[\s,]+/)) scale = Math.max(scale, Math.abs(Number(v)) || 0);
+  return Math.ceil(filterReach(svg) * scale) + 16;
+}

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 '../effects/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 '../svg.js';
+import { pos, wrap } from '../layers/util.js';
+import { transformAttr } from '../effects/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,199 @@
+/**
+ * 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 '../svg.js';
+import { applyEffects, transformAttr, rasterEffect, isRaster, RESOLVED, maskImage } from '../effects/index.js';
+import { transformMatrix, stretchOf, compose, IDENTITY } from '../effects/transform.js';
+import { renderGroup } from './group.js';
+import { scaledReport } from './report.js';
+import { contentBox } from './content.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 decorateEffects(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 decorateEffects(m, layer.effects, ctx), layer, ctx);
+}
+
+/**
+ * Effects, in order. Pixel effects are computed on pixels where something
+ * can draw them (sharp, a canvas) and copy effects drawn as copies; the
+ * rest are SVG filters. An effect's layer `mask` is drawn first (as
+ * markup, and as an image for a filter to mix through).
+ *
+ * @param {{ defs: string, body: string }} m
+ * @param {any} list
+ * @param {any} ctx
+ * @returns {Promise<{ defs: string, body: string }>}
+ */
+async function decorateEffects(m, list, ctx) {
+  if (!list) return m;
+  const effects = await Promise.all((Array.isArray(list) ? list : [list]).map((e, i) => withMask(typeof e === 'string' ? { kind: e } : e, ctx, i)));
+  let { defs, body } = m;
+  const filters = async (/** @type {number} */ from, /** @type {number} */ to) => {
+    if (to <= from) return;
+    // In renderImage, filters work over what the layer paints, not the whole canvas.
+    const out = applyEffects(body, effects.slice(from, to), ctx, from, await contentBox({ defs, body }, ctx), defs);
+    defs += out.defs;
+    body = out.body;
+  };
+  let from = 0;
+  for (let i = 0; i < effects.length; i++) {
+    const fx = effects[i];
+    if (!isRaster(fx, ctx)) continue;
+    await filters(from, i);
+    from = i + 1;
+    const raster = await rasterEffect(fx, { defs, body }, ctx, i);
+    if (raster) ({ defs, body } = raster);
+    else await filters(i, i + 1);
+  }
+  await filters(from, effects.length);
+  return { defs, body };
+}
+
+/**
+ * An effect with a layer `mask`: the mask's layers drawn (kept on the
+ * mask), and for a filter effect drawn as an image too, where something
+ * can draw pixels. Other effects come back as they are.
+ *
+ * @param {any} fx
+ * @param {any} ctx
+ * @param {number} i
+ * @returns {Promise<any>}
+ */
+async function withMask(fx, ctx, i) {
+  if (!fx?.mask?.layers || !ctx.stack) return fx;
+  const parts = await ctx.stack(fx.mask.layers, { tag: `fm${i}` });
+  const mask = { ...fx.mask, [RESOLVED]: { defs: parts.map((/** @type {any} */ p) => p.defs).join(''), body: parts.map((/** @type {any} */ p) => p.body).join('') } };
+  if (!isRaster(fx, ctx)) mask[RESOLVED].image = await maskImage(mask, ctx, fx.pad ?? 0.3, fx.kind === 'motion' ? fx.angle ?? 0 : 0);
+  return { ...fx, mask };
+}
+
+/**
+ * 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 };
+}