@arraypress/covers 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,79 @@
+/**
+ * Recipes: named layer stacks.
+ *
+ * A recipe is a function from the cover's options (and the canvas) to a
+ * list of layers, each with an `id`. Call it through
+ * `cover({ recipe: 'gridTitle', title: '…' })`. Any option named after a
+ * layer id customises that layer:
+ *
+ * - a **string** is the layer's content: `title: 'Hello'`, `icon: 'lucide:feather'`
+ * - an **object** is merged into the layer: `mesh: { blur: '16vmax' }`,
+ *   `title: { content: 'Hello', size: 96 }`
+ * - **`false`** removes it: `grain: false`
+ *
+ * Extra `layers` passed with a recipe are painted on top of its stack.
+ *
+ * The built-ins are JSON documents (`recipes/<name>.json`) defined with
+ * {@link import('./json-recipe.js').defineRecipe}, the same format a theme
+ * can write its own styles in.
+ *
+ * Sizes are written against `u`, the geometric mean of the canvas sides,
+ * so a 1200×630 card and a 1200×1200 square get proportionate type.
+ *
+ * @module recipes
+ */
+
+import { defineRecipe } from './json-recipe.js';
+import { BUILTIN_JSON } from './builtins.js';
+
+/**
+ * What a recipe receives besides the options.
+ *
+ * @typedef {object} RecipeContext
+ * @property {number} width - Canvas width.
+ * @property {number} height - Canvas height.
+ * @property {import('./index.js').Palette} palette - Resolved palette.
+ * @property {import('./rng.js').Rng} rng - The cover's random stream (for recipe-level choices).
+ * @property {number} u - The design unit: `sqrt(width × height)`.
+ * @property {string} seed - The cover's seed (JSON recipes seed each layer's draws from it).
+ */
+
+/**
+ * The text content of a string-or-object option.
+ *
+ * @param {unknown} v
+ * @returns {string | undefined}
+ */
+export function contentOf(v) {
+  if (typeof v === 'string') return v;
+  if (v && typeof v === 'object' && 'content' in v) return /** @type {any} */ (v).content;
+  return undefined;
+}
+
+/** 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', 'brand'];
+
+/** Every built-in recipe, by name, defined from its JSON document. */
+export const recipes = Object.freeze(Object.fromEntries(BUILT_IN.map((name) => [
+  name,
+  // A fresh copy: the documents are shared module data.
+  defineRecipe(structuredClone(/** @type {any} */ (BUILTIN_JSON)[name])),
+])));
+
+/**
+ * Apply per-layer options to a recipe's stack (see the module docs).
+ *
+ * @param {import('./index.js').Layer[]} layers - The recipe's layers.
+ * @param {Record<string, unknown>} options - The cover options.
+ * @returns {import('./index.js').Layer[]} The customised stack.
+ */
+export function applyOverrides(layers, options) {
+  return layers.flatMap((layer) => {
+    if (!layer.id || !Object.hasOwn(options, layer.id)) return [layer];
+    const v = options[layer.id];
+    if (v === false || v === null) return [];
+    if (v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Uint8Array)) return [/** @type {any} */ ({ ...layer, ...v, type: layer.type })];
+    return [layer];
+  });
+}
+

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;

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