@arraypress/covers 1.0.0 → 1.1.0

package/src/render/grain.js

@@ -0,0 +1,113 @@
+/**
+ * Raster grain for `renderImage`: seeded pixel noise blended in JS (librsvg's
+ * feTurbulence is ~20× slower at cover sizes).
+ *
+ * @module render/grain
+ */
+
+import { VARY_FLOOR, VARY_PEAK } from '../layers.js';
+
+/**
+ * Seeded film-grain values, one per pixel (three with `monochrome: false`),
+ * at `size` px per grain (upscaled smoothly). Each value is the mean of two
+ * uniform draws, a triangular distribution: fewer harsh extremes than flat
+ * noise, closer to film.
+ *
+ * @param {any} sharp - The sharp module.
+ * @param {number} width @param {number} height
+ * @param {import('../index.js').GrainLayer} layer
+ * @param {import('../rng.js').Rng} rng - The layer's stream.
+ * @returns {Promise<{ data: Buffer, channels: 1 | 3 }>} Full-size noise.
+ */
+export async function noise(sharp, width, height, layer, rng) {
+  const size = Math.max(1, layer.size ?? 1);
+  const channels = layer.monochrome === false ? 3 : 1;
+  const nw = Math.ceil(width / size);
+  const nh = Math.ceil(height / size);
+  const data = Buffer.alloc(nw * nh * channels);
+  // xorshift32 seeded from the layer's stream: one 32-bit draw gives two
+  // values, so 1.4M pixels cost a few milliseconds.
+  let x = (rng.next() * 4294967296) >>> 0 || 1;
+  for (let i = 0; i < data.length; i++) {
+    x ^= x << 13; x ^= x >>> 17; x ^= x << 5;
+    data[i] = ((x & 255) + ((x >>> 8) & 255)) >>> 1;
+  }
+  if (nw === width && nh === height) return { data, channels };
+  const out = await sharp(data, { raw: { width: nw, height: nh, channels } })
+    .resize(width, height, { kernel: 'cubic', fit: 'fill' })
+    .raw()
+    .toBuffer();
+  return { data: out, channels };
+}
+
+/** Separable blend modes (W3C Compositing Level 1), channel values 0–1. */
+const BLENDS = /** @type {Record<string, (b: number, s: number) => number>} */ ({
+  normal: (_b, s) => s,
+  multiply: (b, s) => b * s,
+  screen: (b, s) => b + s - b * s,
+  overlay: (b, s) => (b <= 0.5 ? 2 * b * s : 1 - 2 * (1 - b) * (1 - s)),
+  'soft-light': (b, s) => {
+    if (s <= 0.5) return b - (1 - 2 * s) * b * (1 - b);
+    const d = b <= 0.25 ? ((16 * b - 12) * b + 4) * b : Math.sqrt(b);
+    return b + (2 * s - 1) * (d - b);
+  },
+});
+
+/**
+ * A 256×256 lookup (backdrop × noise → result) for one blend and strength:
+ * cheaper than the blend maths per pixel.
+ *
+ * @param {(b: number, s: number) => number} blend
+ * @param {number} amount
+ * @returns {Uint8Array}
+ */
+function grainTable(blend, amount) {
+  const table = new Uint8Array(65536);
+  for (let b = 0; b < 256; b++) {
+    for (let s = 0; s < 256; s++) {
+      const cb = b / 255;
+      table[(b << 8) | s] = Math.round((cb + amount * (blend(cb, s / 255) - cb)) * 255);
+    }
+  }
+  return table;
+}
+
+/**
+ * Blend grain into RGBA pixels in place, at the layer's `amount`.
+ * Done in JS rather than with sharp's `composite` blend modes, whose
+ * overlay with a partly transparent layer flattens the noise to almost
+ * nothing (measured σ 0.5 against the expected 5.9 on mid grey).
+ *
+ * @param {Buffer} pixels - RGBA pixels (modified).
+ * @param {{ data: Buffer, channels: 1 | 3, width: number, height: number }} grain - Noise from {@link noise}, and the canvas size.
+ * @param {import('../index.js').GrainLayer} layer - The grain layer.
+ * @returns {void}
+ */
+export function applyGrain(pixels, grain, layer) {
+  const amount = Math.max(0, Math.min(1, (layer.amount ?? 0.08) * (layer.opacity ?? 1)));
+  const blend = BLENDS[layer.blend ?? 'overlay'];
+  if (!blend) throw new TypeError(`Unknown grain blend "${layer.blend}" (${Object.keys(BLENDS).join(', ')})`);
+  const table = grainTable(blend, amount);
+  const { data, channels } = grain;
+  if (layer.vary === 'edges') {
+    // Heavier toward the edges: per-pixel strength from the centre out, as in the SVG mask.
+    const { width, height } = grain;
+    const peak = Math.min(1, amount * VARY_PEAK);
+    const tables = Array.from({ length: 17 }, (_, k) => grainTable(blend, peak * (VARY_FLOOR + (1 - VARY_FLOOR) * (k / 16))));
+    const half = Math.hypot(width, height) / 2;
+    for (let y = 0, i = 0, j = 0; y < height; y++) {
+      for (let x = 0; x < width; x++, i += 4, j += channels) {
+        const t = tables[Math.min(16, Math.round((Math.hypot(x - width / 2, y - height / 2) / half) * 16))];
+        pixels[i] = t[(pixels[i] << 8) | data[j]];
+        pixels[i + 1] = t[(pixels[i + 1] << 8) | data[j + (channels === 3 ? 1 : 0)]];
+        pixels[i + 2] = t[(pixels[i + 2] << 8) | data[j + (channels === 3 ? 2 : 0)]];
+      }
+    }
+    return;
+  }
+  for (let i = 0, j = 0; i < pixels.length; i += 4, j += channels) {
+    pixels[i] = table[(pixels[i] << 8) | data[j]];
+    pixels[i + 1] = table[(pixels[i + 1] << 8) | data[j + (channels === 3 ? 1 : 0)]];
+    pixels[i + 2] = table[(pixels[i + 2] << 8) | data[j + (channels === 3 ? 2 : 0)]];
+  }
+}

package/src/render/group.d.ts

@@ -0,0 +1,23 @@
+// The `group` layer.
+import type { Length, Layer, BaseLayer, Anchor } from '../index.js';
+import type { RenderContext, Markup } from './context.js';
+
+/** `group`: a stack drawn as one, on its own design grid. */
+export interface GroupLayer extends BaseLayer {
+  type: 'group';
+  layers: Layer[];
+  /** The children's coordinate grid, e.g. `[0, 0, 400, 500]`. */
+  viewBox?: [number, number, number, number];
+  x?: Length | `${number}%`; y?: Length | `${number}%`; width?: Length | `${number}%`; height?: Length | `${number}%`;
+  /** Default `'contain'`. */
+  fit?: 'contain' | 'cover' | 'stretch' | 'width' | 'height';
+  /** Where a fitted grid sits. Default `'center'`. */
+  align?: Anchor;
+  clipToBox?: boolean;
+}
+
+
+/** Draw a group: its stack on its grid, fitted into its box. */
+export function renderGroup(layer: GroupLayer, ctx: RenderContext, decorate?: (m: Markup, gctx: RenderContext) => Promise<Markup>): Promise<Markup>;
+/** An anchor as fractions `[x, y]` of the free space. */
+export function alignOf(a?: string): [number, number];

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