@arraypress/covers 1.0.0 → 1.1.0

package/src/png.js

@@ -6,7 +6,8 @@
  * @module png
  */
 
-import { deflateSync } from 'node:zlib';
+import { deflateSync, deflate } from './platform/index.js';
+import { concat, toBase64 } from './platform/bytes.js';
 
 /** CRC-32 table (PNG's polynomial). */
 const CRC = (() => {
@@ -26,52 +27,100 @@ function crc32(bytes) {
   return (c ^ 0xffffffff) >>> 0;
 }
 
-/** @param {string} type @param {Uint8Array} data @returns {Buffer} */
+/** @param {string} type @param {Uint8Array} data @returns {Uint8Array} */
 function chunk(type, data) {
-  const out = Buffer.alloc(12 + data.length);
-  out.writeUInt32BE(data.length, 0);
-  out.write(type, 4, 'latin1');
-  Buffer.from(data).copy(out, 8);
-  out.writeUInt32BE(crc32(out.subarray(4, 8 + data.length)), 8 + data.length);
+  const out = new Uint8Array(12 + data.length);
+  const v = new DataView(out.buffer);
+  v.setUint32(0, data.length);
+  for (let i = 0; i < 4; i++) out[4 + i] = type.charCodeAt(i);
+  out.set(data, 8);
+  v.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
   return out;
 }
 
 /**
- * Encode pixels as a PNG.
+ * The filtered scanlines and header of a PNG.
+ *
+ * @param {Uint8Array} pixels @param {number} width @param {number} height @param {1 | 3 | 4} channels
+ * @returns {{ raw: Uint8Array, ihdr: Uint8Array }}
+ */
+function scanlines(pixels, width, height, channels) {
+  const stride = width * channels;
+  const raw = new Uint8Array((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0;
+    raw.set(pixels.subarray(y * stride, y * stride + stride), y * (stride + 1) + 1);
+  }
+  const ihdr = new Uint8Array(13);
+  const v = new DataView(ihdr.buffer);
+  v.setUint32(0, width);
+  v.setUint32(4, height);
+  ihdr[8] = 8;
+  ihdr[9] = /** @type {Record<number, number>} */ ({ 1: 0, 3: 2, 4: 6 })[channels];
+  return { raw, ihdr };
+}
+
+const SIGNATURE = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * zlib "stored" blocks: valid, uncompressed. The synchronous fallback where
+ * the platform has no synchronous deflate (browsers, Workers).
+ *
+ * @param {Uint8Array} data
+ * @returns {Uint8Array}
+ */
+function stored(data) {
+  const parts = [new Uint8Array([0x78, 0x01])];
+  for (let i = 0; i < data.length || i === 0; i += 65535) {
+    const block = data.subarray(i, i + 65535);
+    const last = i + 65535 >= data.length ? 1 : 0;
+    parts.push(new Uint8Array([last, block.length & 255, block.length >> 8, ~block.length & 255, (~block.length >> 8) & 255]), block);
+    if (last) break;
+  }
+  let a = 1;
+  let b = 0;
+  for (const x of data) { a = (a + x) % 65521; b = (b + a) % 65521; }
+  const adler = new Uint8Array(4);
+  new DataView(adler.buffer).setUint32(0, ((b << 16) | a) >>> 0);
+  parts.push(adler);
+  return concat(parts);
+}
+
+/**
+ * Encode pixels as a PNG (synchronously: zlib in Node, stored blocks where
+ * there's no synchronous deflate; {@link encodePngAsync} compresses
+ * everywhere).
  *
  * @param {Uint8Array} pixels - Row-major samples.
  * @param {number} width
  * @param {number} height
  * @param {1 | 3 | 4} [channels=4] - Grey, RGB or RGBA.
- * @returns {Buffer} PNG bytes.
+ * @returns {Uint8Array} PNG bytes.
  *
  * @example
  * encodePng(new Uint8Array([0, 255]), 2, 1, 1); // a black and a white pixel
  */
 export function encodePng(pixels, width, height, channels = 4) {
-  const stride = width * channels;
-  const raw = Buffer.alloc((stride + 1) * height);
-  for (let y = 0; y < height; y++) {
-    raw[y * (stride + 1)] = 0;
-    Buffer.from(pixels.buffer, pixels.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1);
-  }
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(width, 0);
-  ihdr.writeUInt32BE(height, 4);
-  ihdr[8] = 8;
-  ihdr[9] = { 1: 0, 3: 2, 4: 6 }[channels];
-  return Buffer.concat([
-    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
-    chunk('IHDR', ihdr),
-    chunk('IDAT', deflateSync(raw, { level: 9 })),
-    chunk('IEND', new Uint8Array(0)),
-  ]);
+  const { raw, ihdr } = scanlines(pixels, width, height, channels);
+  return concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', deflateSync(raw) ?? stored(raw)), chunk('IEND', new Uint8Array(0))]);
+}
+
+/**
+ * Encode pixels as a PNG, compressed on every platform (Node's zlib, else
+ * `CompressionStream`).
+ *
+ * @param {Uint8Array} pixels @param {number} width @param {number} height @param {1 | 3 | 4} [channels=4]
+ * @returns {Promise<Uint8Array>}
+ */
+export async function encodePngAsync(pixels, width, height, channels = 4) {
+  const { raw, ihdr } = scanlines(pixels, width, height, channels);
+  return concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', await deflate(raw)), chunk('IEND', new Uint8Array(0))]);
 }
 
 /**
  * A PNG as a data URI.
  *
- * @param {Buffer} png
+ * @param {Uint8Array} png
  * @returns {string}
  */
-export const pngUri = (png) => `data:image/png;base64,${png.toString('base64')}`;
+export const pngUri = (png) => `data:image/png;base64,${toBase64(png)}`;

package/src/print.js

@@ -9,7 +9,7 @@ import { attrs, num, layerAttrs, esc } from './svg.js';
 import { len, regionPx } from './geometry.js';
 import { toHex } from './color.js';
 import { createRng } from './rng.js';
-import { encodePng, pngUri } from './png.js';
+import { encodePngAsync, pngUri } from './png.js';
 import { text as textLayer } from './layers.js';
 
 /** Classic risograph inks, by name (`'riso:pink'`). Approximations, not trademarks. */
@@ -126,7 +126,7 @@ export async function ink(layer, ctx) {
     for (let i = 0; i < px.length; i++) px[i] = rng.next() < hole ? 0 : 255;
     // Clump the holes a little (riso misses ink in specks, not single pixels).
     for (let i = 0; i < px.length; i++) if (px[i] === 0 && rng.next() < 0.5) px[(i + 1) % px.length] = 0;
-    defs += `<pattern${attrs({ id: `${id}t`, patternUnits: 'userSpaceOnUse', width: size, height: size })}><image${attrs({ width: size, height: size, href: pngUri(encodePng(px, size, size, 1)) })}/></pattern>`;
+    defs += `<pattern${attrs({ id: `${id}t`, patternUnits: 'userSpaceOnUse', width: size, height: size })}><image${attrs({ width: size, height: size, href: pngUri(await encodePngAsync(px, size, size, 1)) })}/></pattern>`;
     defs += `<mask${attrs({ id: `${id}tm`, maskUnits: 'userSpaceOnUse', ...bleed })}><rect${attrs({ ...bleed, fill: `url(#${id}t)` })}/></mask>`;
     inner = `<g mask="url(#${id}tm)">${inner}</g>`;
   } else if (texture === 'halftone') {
@@ -153,7 +153,7 @@ export async function ink(layer, ctx) {
         px[y * T + x] = Math.round((hit / 4) * 255);
       }
     }
-    defs += `<pattern${attrs({ id: `${id}t`, patternUnits: 'userSpaceOnUse', width: T, height: T })}><image${attrs({ width: T, height: T, href: pngUri(encodePng(px, T, T, 1)) })}/></pattern>`;
+    defs += `<pattern${attrs({ id: `${id}t`, patternUnits: 'userSpaceOnUse', width: T, height: T })}><image${attrs({ width: T, height: T, href: pngUri(await encodePngAsync(px, T, T, 1)) })}/></pattern>`;
     defs += `<mask${attrs({ id: `${id}tm`, maskUnits: 'userSpaceOnUse', ...bleed })}><rect${attrs({ ...bleed, fill: `url(#${id}t)` })}/></mask>`;
     inner = `<g mask="url(#${id}tm)">${inner}</g>`;
   }
@@ -242,9 +242,9 @@ const BAYER8 = (() => {
  *
  * @param {import('./index.js').DitherLayer} layer
  * @param {import('./layers.js').RenderContext} ctx
- * @returns {import('./layers.js').Markup}
+ * @returns {Promise<import('./layers.js').Markup>}
  */
-export function dither(layer, ctx) {
+export async function dither(layer, ctx) {
   const { width: w, height: h, rng, palette: p } = ctx;
   const cell = Math.max(1, Math.round(len(layer.cell, ctx.canvas, '0.9vmin')));
   const cw = Math.ceil(w / cell);
@@ -309,7 +309,7 @@ export function dither(layer, ctx) {
       px[i] = c[0]; px[i + 1] = c[1]; px[i + 2] = c[2];
     }
   }
-  const body = `<image${attrs({ x: 0, y: 0, width: cw * cell, height: chh * cell, preserveAspectRatio: 'none', 'image-rendering': 'optimizeSpeed', style: 'image-rendering:pixelated', href: pngUri(encodePng(px, cw, chh, 3)) })}/>`;
+  const body = `<image${attrs({ x: 0, y: 0, width: cw * cell, height: chh * cell, preserveAspectRatio: 'none', 'image-rendering': 'optimizeSpeed', style: 'image-rendering:pixelated', href: pngUri(await encodePngAsync(px, cw, chh, 3)) })}/>`;
   return { defs: '', body: wrap(layer, body) };
 }
 
@@ -515,7 +515,8 @@ export async function waveform(layer, ctx) {
   if (!peaks && layer.audio) {
     let gen;
     try {
-      gen = await import('@arraypress/waveform-gen');
+      const name = '@arraypress/waveform-gen';
+      gen = await import(/* @vite-ignore */ name);
     } catch {
       throw new Error('Decoding audio needs @arraypress/waveform-gen: npm install @arraypress/waveform-gen (or pass peaks)');
     }

package/src/raster/index.d.ts

@@ -0,0 +1,24 @@
+// Rasterising in the browser.
+
+/** Browser raster options. */
+export interface RasterizeOptions {
+  /** Default `'png'`. */
+  format?: 'png' | 'jpeg' | 'webp';
+  /** 0–1 (JPEG, WebP). Default 0.9. */
+  quality?: number;
+  /** Output width or height, px (the other follows), or a `scale`. */
+  width?: number;
+  height?: number;
+  scale?: number;
+  /** A colour under the art (JPEG defaults to the page colour). */
+  background?: string;
+}
+
+/** Rasterise an SVG string in a browser page. */
+export function rasterize(svg: string, options?: RasterizeOptions): Promise<Blob>;
+/** RGBA pixels of an SVG at a size: sharp in Node, a canvas in a page, undefined elsewhere. */
+export function pixelsOf(svg: string, w: number, h: number, sharp?: unknown): Promise<Uint8Array | undefined>;
+/** Encode RGBA pixels for embedding: JPEG where opaque (unless `lossless`), else PNG. */
+export function encodePixels(data: Uint8Array | Uint8ClampedArray, w: number, h: number, o?: { opaque?: boolean; lossless?: boolean; quality?: number }, sharp?: unknown): Promise<{ mime: 'image/jpeg' | 'image/png'; bytes: Uint8Array }>;
+/** Pixels through a real JPEG encoder and back; undefined where none is available. */
+export function jpegRoundTrip(data: Uint8ClampedArray, w: number, h: number, quality: number, subsample: boolean, sharp?: unknown): Promise<Uint8ClampedArray | undefined>;

package/src/raster/index.js

@@ -0,0 +1,171 @@
+/**
+ * Rasterising without sharp: an SVG drawn into a canvas in the browser,
+ * encoded as PNG, JPEG or WebP. `renderImage()` stays the Node path (sharp,
+ * with its grain and padded-blur handling); this is the browser one.
+ *
+ * The SVG is decoded by the browser as an `<img>` (so it needs a page:
+ * `document` and `Image`), drawn onto an `OffscreenCanvas` when there is
+ * one (else a `<canvas>`), and encoded with `convertToBlob` / `toBlob`.
+ *
+ * @module raster
+ */
+
+const MIMES = /** @type {const} */ ({ png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' });
+
+/**
+ * Decode an SVG string into a drawable image (browser).
+ *
+ * @param {string} svg
+ * @returns {Promise<HTMLImageElement>}
+ */
+async function decodeSvg(svg) {
+  const g = /** @type {any} */ (globalThis);
+  if (typeof g.Image !== 'function' || typeof g.document === 'undefined') {
+    throw new Error('rasterize() needs a browser page (Image and canvas). In Node use renderImage(); in a Worker return the SVG, or rasterise it with a wasm renderer.');
+  }
+  const url = URL.createObjectURL(new Blob([svg], { type: 'image/svg+xml' }));
+  try {
+    const img = new g.Image();
+    img.decoding = 'sync';
+    img.src = url;
+    await img.decode();
+    return img;
+  } finally {
+    // Revoked after decode: the decoded image keeps its pixels.
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+  }
+}
+
+/**
+ * A 2D canvas of a size.
+ *
+ * @param {number} w @param {number} h
+ * @returns {{ canvas: any, ctx: CanvasRenderingContext2D }}
+ */
+function canvasOf(w, h) {
+  const g = /** @type {any} */ (globalThis);
+  const canvas = typeof g.OffscreenCanvas === 'function' ? new g.OffscreenCanvas(w, h) : Object.assign(g.document.createElement('canvas'), { width: w, height: h });
+  return { canvas, ctx: canvas.getContext('2d') };
+}
+
+/**
+ * Rasterise an SVG in the browser.
+ *
+ * @param {string} svg - An SVG document (from `renderSvg`).
+ * @param {{ format?: 'png' | 'jpeg' | 'webp', quality?: number, width?: number, height?: number, scale?: number, background?: string }} [options]
+ * @returns {Promise<Blob>}
+ *
+ * @example
+ * const blob = await rasterize(await renderSvg(cover), { format: 'webp', quality: 0.9 });
+ * img.src = URL.createObjectURL(blob);
+ */
+export async function rasterize(svg, options = {}) {
+  const format = options.format ?? 'png';
+  if (!Object.hasOwn(MIMES, format)) throw new TypeError(`Unknown format "${format}" (png, jpeg, webp)`);
+  const vw = Number(/\bwidth="([\d.]+)"/.exec(svg)?.[1] ?? 1200);
+  const vh = Number(/\bheight="([\d.]+)"/.exec(svg)?.[1] ?? 1200);
+  const scale = options.scale ?? (options.width ? options.width / vw : options.height ? options.height / vh : 1);
+  const w = Math.max(1, Math.round(vw * scale));
+  const h = Math.max(1, Math.round(vh * scale));
+  const img = await decodeSvg(svg);
+  const { canvas, ctx } = canvasOf(w, h);
+  if (format === 'jpeg' || options.background) {
+    ctx.fillStyle = options.background ?? /fill="(#[0-9a-f]{6})"/i.exec(svg)?.[1] ?? '#ffffff';
+    ctx.fillRect(0, 0, w, h);
+  }
+  ctx.drawImage(img, 0, 0, w, h);
+  const type = MIMES[format];
+  const quality = options.quality ?? (format === 'png' ? undefined : 0.9);
+  if (typeof canvas.convertToBlob === 'function') return canvas.convertToBlob({ type, quality });
+  return new Promise((resolve, reject) => canvas.toBlob((/** @type {Blob | null} */ b) => (b ? resolve(b) : reject(new Error('Canvas encoding failed'))), type, quality));
+}
+
+/**
+ * RGBA pixels of an SVG at a size: sharp in Node, a canvas in a page.
+ * Undefined where neither is available (a Worker).
+ *
+ * @param {string} svg
+ * @param {number} w
+ * @param {number} h
+ * @param {any} [sharp] - The sharp module, when loaded.
+ * @returns {Promise<Uint8Array | undefined>}
+ */
+export async function pixelsOf(svg, w, h, sharp) {
+  if (sharp) {
+    const out = await sharp(new TextEncoder().encode(svg)).resize(w, h, { fit: 'fill' }).ensureAlpha().raw().toBuffer();
+    return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+  }
+  const g = /** @type {any} */ (globalThis);
+  if (typeof g.Image !== 'function' || typeof g.document === 'undefined') return undefined;
+  const img = await decodeSvg(svg);
+  const { ctx } = canvasOf(w, h);
+  ctx.drawImage(img, 0, 0, w, h);
+  return new Uint8Array(ctx.getImageData(0, 0, w, h).data.buffer);
+}
+
+/**
+ * Encode RGBA pixels for embedding: JPEG where they're opaque (smaller),
+ * PNG where they aren't or where `lossless` (flat colour, crisp cells).
+ * sharp in Node, a canvas in a page, else the in-library PNG encoder.
+ *
+ * @param {Uint8Array | Uint8ClampedArray} data - RGBA, unpremultiplied.
+ * @param {number} w
+ * @param {number} h
+ * @param {{ opaque?: boolean, lossless?: boolean, quality?: number }} [o]
+ * @param {any} [sharp]
+ * @returns {Promise<{ mime: 'image/jpeg' | 'image/png', bytes: Uint8Array }>}
+ */
+export async function encodePixels(data, w, h, o = {}, sharp) {
+  const jpeg = Boolean(o.opaque) && !o.lossless;
+  const quality = o.quality ?? 92;
+  if (sharp) {
+    let img = sharp(data, { raw: { width: w, height: h, channels: 4 } });
+    if (o.opaque) img = img.removeAlpha();
+    const out = jpeg ? await img.jpeg({ quality, chromaSubsampling: '4:4:4' }).toBuffer() : await img.png({ compressionLevel: 6 }).toBuffer();
+    return { mime: jpeg ? 'image/jpeg' : 'image/png', bytes: new Uint8Array(out.buffer, out.byteOffset, out.byteLength) };
+  }
+  const g = /** @type {any} */ (globalThis);
+  if (typeof g.OffscreenCanvas === 'function' || typeof g.document !== 'undefined') {
+    const { canvas, ctx } = canvasOf(w, h);
+    ctx.putImageData(new g.ImageData(new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength), w, h), 0, 0);
+    const type = jpeg ? 'image/jpeg' : 'image/png';
+    const blob = typeof canvas.convertToBlob === 'function'
+      ? await canvas.convertToBlob({ type, quality: quality / 100 })
+      : await new Promise((resolve, reject) => canvas.toBlob((/** @type {Blob | null} */ b) => (b ? resolve(b) : reject(new Error('Canvas encoding failed'))), type, quality / 100));
+    return { mime: type, bytes: new Uint8Array(await blob.arrayBuffer()) };
+  }
+  const { encodePngAsync } = await import('../png.js');
+  return { mime: 'image/png', bytes: await encodePngAsync(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), w, h, 4) };
+}
+
+/**
+ * Pixels through a real JPEG encoder and back (compression artefacts):
+ * libjpeg through sharp in Node, the browser's own encoder in a page.
+ * Undefined where neither is available.
+ *
+ * @param {Uint8ClampedArray} data - RGBA (alpha ignored).
+ * @param {number} w
+ * @param {number} h
+ * @param {number} quality - 1–100.
+ * @param {boolean} subsample - 4:2:0 chroma (blocky colour).
+ * @param {any} [sharp]
+ * @returns {Promise<Uint8ClampedArray | undefined>} RGBA, opaque.
+ */
+export async function jpegRoundTrip(data, w, h, quality, subsample, sharp) {
+  if (sharp) {
+    const jpg = await sharp(data, { raw: { width: w, height: h, channels: 4 } }).removeAlpha().jpeg({ quality, chromaSubsampling: subsample ? '4:2:0' : '4:4:4' }).toBuffer();
+    const out = await sharp(jpg).ensureAlpha().raw().toBuffer();
+    return new Uint8ClampedArray(out.buffer, out.byteOffset, out.byteLength);
+  }
+  const g = /** @type {any} */ (globalThis);
+  if (typeof g.createImageBitmap !== 'function' || (typeof g.OffscreenCanvas !== 'function' && typeof g.document === 'undefined')) return undefined;
+  const { canvas, ctx } = canvasOf(w, h);
+  ctx.putImageData(new g.ImageData(new Uint8ClampedArray(data), w, h), 0, 0);
+  const blob = typeof canvas.convertToBlob === 'function'
+    ? await canvas.convertToBlob({ type: 'image/jpeg', quality: quality / 100 })
+    : await new Promise((resolve) => canvas.toBlob(resolve, 'image/jpeg', quality / 100));
+  const bitmap = await g.createImageBitmap(blob);
+  ctx.clearRect(0, 0, w, h);
+  ctx.drawImage(bitmap, 0, 0);
+  return new Uint8ClampedArray(ctx.getImageData(0, 0, w, h).data.buffer);
+}

package/src/recipes.js

@@ -23,8 +23,8 @@
  * @module recipes
  */
 
-import { readFileSync } from 'node:fs';
 import { defineRecipe } from './json-recipe.js';
+import { BUILTIN_JSON } from './builtins.js';
 
 /**
  * What a recipe receives besides the options.
@@ -51,12 +51,13 @@ export function contentOf(v) {
 }
 
 /** The built-in recipe names (each is `recipes/<name>.json`). */
-const BUILT_IN = ['aurora', 'gridTitle', 'iconTile', 'bigType', 'stripes', 'duotone', 'mark', 'diagram', 'cutout', 'riso', 'dither', 'contour', 'waveform', 'bauhaus', 'issue', 'photo'];
+const BUILT_IN = ['aurora', 'gridTitle', 'iconTile', 'bigType', 'stripes', 'duotone', 'mark', 'diagram', 'cutout', 'riso', 'dither', 'contour', 'waveform', 'bauhaus', 'issue', 'photo', 'brand'];
 
 /** Every built-in recipe, by name, defined from its JSON document. */
 export const recipes = Object.freeze(Object.fromEntries(BUILT_IN.map((name) => [
   name,
-  defineRecipe(JSON.parse(readFileSync(new URL(`../recipes/${name}.json`, import.meta.url), 'utf8'))),
+  // A fresh copy: the documents are shared module data.
+  defineRecipe(structuredClone(/** @type {any} */ (BUILTIN_JSON)[name])),
 ])));
 
 /**

package/src/render/backdrop.d.ts

@@ -0,0 +1,6 @@
+// The colour under a box, for auto contrast.
+import type { Cover, Layer } from '../index.js';
+import type { Markup } from './context.js';
+
+/** A sampler: the average colour (`#rrggbb`) under a box of the parts drawn so far, or undefined where nothing can rasterise. */
+export function backdropSampler(c: Cover, sharp: unknown, documentFor: (c: Cover, parts: Markup[]) => string, loadSharp: (required: boolean) => Promise<unknown>): (box: { x: number; y: number; width: number; height: number }, parts: (Markup & { layer: Layer })[]) => Promise<string | undefined>;

package/src/render/backdrop.js

@@ -0,0 +1,55 @@
+/**
+ * What's under a box: the layers drawn so far, rendered small and averaged,
+ * for `color: 'auto'`.
+ *
+ * @module render/backdrop
+ */
+
+import { toHex } from '../color.js';
+import { pixelsOf } from '../raster/index.js';
+
+/**
+ * The average colour under a box, from the layers drawn so far: rendered
+ * small (sharp in Node, a canvas in a page) and averaged. Undefined where
+ * nothing can rasterise (a Worker): the text keeps to the palette.
+ *
+ * @param {import('../index.js').Cover} c
+ * @param {any} sharp
+ * @param {(c: any, parts: any[]) => string} documentFor - Assembles an SVG from rendered parts.
+ * @param {(required: boolean) => Promise<any>} loadSharp
+ * @returns {(box: { x: number, y: number, width: number, height: number }, parts: any[]) => Promise<string | undefined>}
+ */
+export function backdropSampler(c, sharp, documentFor, loadSharp) {
+  return async (box, parts) => {
+    if (!parts.length) return undefined;
+    const s = Math.min(1, 240 / Math.max(c.width, c.height));
+    const w = Math.max(1, Math.round(c.width * s));
+    const h = Math.max(1, Math.round(c.height * s));
+    let px;
+    try {
+      px = await pixelsOf(documentFor(/** @type {any} */ ({ ...c, radius: undefined, alt: undefined, print: undefined, overlay: undefined }), parts), w, h, sharp ?? await loadSharp(false));
+    } catch {
+      px = undefined;
+    }
+    if (!px) {
+      // Analytic fallback: the last full-canvas solid colour.
+      const solid = [...parts].reverse().find((p) => p.layer.type === 'solid' && !p.layer.area);
+      return solid ? toHex(solid.layer.color ?? c.palette.bg) : undefined;
+    }
+    const x0 = Math.max(0, Math.floor(box.x * s));
+    const y0 = Math.max(0, Math.floor(box.y * s));
+    const x1 = Math.min(w, Math.ceil((box.x + box.width) * s));
+    const y1 = Math.min(h, Math.ceil((box.y + box.height) * s));
+    let r = 0; let g = 0; let b = 0; let n = 0;
+    for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) {
+      const i = (y * w + x) * 4;
+      const a = px[i + 3] / 255;
+      // Unpainted pixels read as the page colour.
+      const bg = c.palette.bg;
+      const br = parseInt(bg.slice(1, 3), 16); const bgc = parseInt(bg.slice(3, 5), 16); const bb = parseInt(bg.slice(5, 7), 16);
+      r += px[i] * a + br * (1 - a); g += px[i + 1] * a + bgc * (1 - a); b += px[i + 2] * a + bb * (1 - a); n++;
+    }
+    if (!n) return undefined;
+    return '#' + [r, g, b].map((v) => Math.round(v / n).toString(16).padStart(2, '0')).join('');
+  };
+}

package/src/render/content.d.ts

@@ -0,0 +1,5 @@
+// Where a layer paints, for content-sized filter regions.
+import type { Markup, RenderContext } from './context.js';
+
+/** The box a layer's markup paints, in its units (drawn small with sharp); undefined when it can't be probed. */
+export function contentBox(m: Markup, ctx: RenderContext): Promise<{ x: number; y: number; width: number; height: number } | undefined>;

package/src/render/content.js

@@ -0,0 +1,58 @@
+/**
+ * Where a layer paints: its markup drawn small and the box round every
+ * pixel it covers, so filters can work over that box instead of the whole
+ * canvas (in `renderImage`, where librsvg's cost is per pixel of region).
+ *
+ * @module render/content
+ */
+
+import { num } from '../svg.js';
+
+/** The probe's longer side, px. */
+const PROBE = 256;
+
+/** Markup carrying more embedded data than this isn't probed (decoding it would cost more than it saves). */
+const MAX_PROBE_BYTES = 400_000;
+
+/**
+ * The box a layer's markup paints, in its units: drawn at most 256 px
+ * across over the canvas and half again round it, one probe pixel of slack
+ * on every side. Undefined when it can't be probed (no sharp, heavy
+ * embedded images) or paints nothing.
+ *
+ * @param {{ defs: string, body: string }} m
+ * @param {any} ctx
+ * @returns {Promise<{ x: number, y: number, width: number, height: number } | undefined>}
+ */
+export async function contentBox(m, ctx) {
+  if (!ctx.raster || !ctx.sharp || m.body.length + m.defs.length > MAX_PROBE_BYTES) return undefined;
+  const ox = -ctx.width / 2;
+  const oy = -ctx.height / 2;
+  const uw = ctx.width * 2;
+  const uh = ctx.height * 2;
+  const s = PROBE / Math.max(uw, uh);
+  const w = Math.max(1, Math.round(uw * s));
+  const h = Math.max(1, Math.round(uh * s));
+  const doc = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="${num(ox, 4)} ${num(oy, 4)} ${num(uw, 4)} ${num(uh, 4)}" preserveAspectRatio="none">${m.defs ? `<defs>${m.defs}</defs>` : ''}${m.body}</svg>`;
+  let px;
+  try {
+    px = await ctx.sharp(new TextEncoder().encode(doc)).ensureAlpha().raw().toBuffer();
+  } catch {
+    return undefined;
+  }
+  let x0 = w;
+  let y0 = h;
+  let x1 = -1;
+  let y1 = -1;
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+    if (!px[(y * w + x) * 4 + 3]) continue;
+    if (x < x0) x0 = x;
+    if (x > x1) x1 = x;
+    if (y < y0) y0 = y;
+    if (y > y1) y1 = y;
+  }
+  if (x1 < 0) return undefined;
+  // Anything touching the probe's edge may run further: the whole region then.
+  if (x0 === 0 || y0 === 0 || x1 === w - 1 || y1 === h - 1) return undefined;
+  return { x: ox + (x0 - 1) / s, y: oy + (y0 - 1) / s, width: (x1 - x0 + 3) / s, height: (y1 - y0 + 3) / s };
+}

package/src/render/context.d.ts

@@ -0,0 +1,82 @@
+// What a layer renderer receives and returns (types only).
+import type { Palette, Rng, FontSource, Layer } from '../index.js';
+
+/** A rendered layer: markup for `<defs>` and for the body. */
+export interface Markup {
+  defs: string;
+  body: string;
+  /** Mesh layers: the blur's 3σ padding, for the padded raster path. */
+  pad?: number;
+  /** Mesh layers: the finest blur, px. */
+  finest?: number;
+}
+
+/** A text block as drawn, reported to `lint`. */
+export interface DrawnText {
+  kind: 'text';
+  id?: string;
+  content: string;
+  /** Type size, canvas px (the first line, stretched). */
+  size: number;
+  /** The smallest line's capital height, canvas px (stretched, through every group and transform). */
+  capHeight: number;
+  box: { x: number; y: number; width: number; height: number } | null;
+  /** The narrowest horizontal scale a line was set at (justification, stretch). */
+  squeeze?: number;
+}
+
+/** An image as drawn, reported to `lint`. */
+export interface DrawnImage {
+  kind: 'image';
+  id?: string;
+  /** Its box at the cover's size, canvas px. */
+  drawn: { width: number; height: number };
+  /** The source's pixels. */
+  source?: { width: number; height: number };
+  /** The pixels embedded. */
+  embedded?: { width: number; height: number };
+  fit: 'cover' | 'contain' | 'stretch';
+}
+
+/** Everything a layer renderer needs. */
+export interface RenderContext {
+  /** Canvas width, px (a group's grid width inside a group). */
+  width: number;
+  height: number;
+  canvas: { width: number; height: number };
+  palette: Palette;
+  /** This layer's own seeded stream. */
+  rng: Rng;
+  /** A unique id prefix for this layer's defs. */
+  id: string;
+  /** Available fonts, Inter last. */
+  fonts: FontSource[];
+  /** The sharp module, when loaded (Node). */
+  sharp?: unknown;
+  /** Print: bleed plus safe margin, px (anchored text and icons default their margin to it). */
+  inset?: number;
+  /** `'live'` draws text as `<text>`. */
+  textRender?: 'outline' | 'live';
+  /** Collects what was drawn, for `lint`. */
+  report?: (entry: DrawnText | DrawnImage) => void;
+  /** Canvas px per unit here, the larger axis (images and raster effects resample for it). */
+  res?: number;
+  /** This context's units to canvas px. */
+  matrix?: [number, number, number, number, number, number];
+  /** Drawn for `renderImage` (librsvg): effects may take their faster forms. */
+  raster?: boolean;
+  /** The print format's trim and die-cut, canvas px. */
+  cut?: { x: number; y: number; width: number; height: number; cut?: import('../formats/cut.js').Cut; mm: number };
+  /** Where text blocks landed, by layer id, for `{layout.<id>.<field>}`. */
+  layout?: Map<string, Record<string, number>>;
+  /** Named layers (`defs`) and drawn copies, for `use`. */
+  defs?: Map<string, unknown>;
+  /** Identity of the document being rendered (one `@font-face` per face per document). */
+  doc?: object;
+  /** The average colour under a box (`color: 'auto'`), top-level layers only. */
+  backdrop?: (box: { x: number; y: number; width: number; height: number }) => Promise<string | undefined>;
+  /** Render a nested stack (groups, masks). */
+  stack?: (layers: Layer[], sub: { tag: string; width?: number; height?: number; scale?: number; res?: number; matrix?: [number, number, number, number, number, number] }) => Promise<(Markup & { layer: Layer })[]>;
+  /** A group's scale to canvas px. */
+  scale?: number;
+}

package/src/render/grain.d.ts

@@ -0,0 +1,7 @@
+// Raster grain for renderImage.
+import type { GrainLayer, Rng } from '../index.js';
+
+/** Seeded film-grain values at full size (one channel, or three with `monochrome: false`). */
+export function noise(sharp: unknown, width: number, height: number, layer: GrainLayer, rng: Rng): Promise<{ data: Uint8Array; channels: 1 | 3 }>;
+/** Blend grain into RGBA pixels in place. */
+export function applyGrain(pixels: Uint8Array, grain: { data: Uint8Array; channels: 1 | 3; width: number; height: number }, layer: GrainLayer): void;