@arraypress/covers 1.0.0 → 1.3.1

package/src/platform/load.js

@@ -0,0 +1,71 @@
+/**
+ * Loading bytes from anything: bytes, Blobs and Responses, `data:` URIs,
+ * paths (Node), URLs (fetched where allowed), or a `configure({ load })`
+ * hook.
+ *
+ * @module platform/load
+ */
+
+import { isBytes, u8, fromDataUri, node, isNode } from '@logomarks/image-effects/platform';
+import { settings } from './settings.js';
+
+/** @returns {boolean} */
+const networkAllowed = () => settings.network ?? !isNode();
+
+/** @returns {typeof fetch} */
+function fetcher() {
+  const f = settings.fetch ?? globalThis.fetch;
+  if (!f) throw new Error('No fetch available to load a URL: pass bytes, or configure({ fetch })');
+  return f;
+}
+
+/**
+ * Whatever a loader handed back, as bytes.
+ *
+ * @param {any} v
+ * @returns {Promise<Uint8Array>}
+ */
+async function asBytes(v) {
+  if (isBytes(v)) return u8(v);
+  if (typeof v?.arrayBuffer === 'function') {
+    if (typeof v.ok === 'boolean' && !v.ok) throw new Error(`Couldn't load ${v.url}: HTTP ${v.status}`);
+    return new Uint8Array(await v.arrayBuffer());
+  }
+  throw new TypeError('A loader must return bytes, an ArrayBuffer, a Blob or a Response');
+}
+
+/**
+ * Load bytes: an image, font, audio file or icon set.
+ *
+ * @param {any} src - Bytes, a Blob, a Response, a `data:` URI, a URL, or a path (Node).
+ * @param {'image' | 'font' | 'audio' | 'icons' | 'file'} [kind='file'] - What it is (for errors and the loader).
+ * @returns {Promise<Uint8Array>} The bytes (a Node Buffer when read from disk).
+ */
+export async function loadBytes(src, kind = 'file') {
+  if (isBytes(src)) return u8(src);
+  if (src && typeof src === 'object' && !(src instanceof URL)) return asBytes(src);
+  if (settings.load) {
+    const r = await settings.load(src, { kind });
+    if (r != null) return asBytes(r);
+  }
+  const s = String(src instanceof URL ? src.href : src);
+  const data = fromDataUri(s);
+  if (data) return data;
+  if (/^https?:/i.test(s)) {
+    if (!networkAllowed()) {
+      throw new TypeError(kind === 'image'
+        ? 'Image src must be a local file or bytes: covers never fetch from the network (allow it with configure({ network: true }))'
+        : `${kind} "${s}" is a URL, and covers doesn't fetch from the network in Node unless asked: configure({ network: true }) or pass bytes`);
+    }
+    return asBytes(await fetcher()(s));
+  }
+  const fsp = node('fs/promises');
+  const isFileUrl = s.startsWith('file:');
+  if (fsp && (isFileUrl || !/^[a-z][\w+.-]*:/i.test(s))) return fsp.readFile(isFileUrl ? new URL(s) : s);
+  // A browser: a relative or absolute URL, against the page.
+  const base = /** @type {any} */ (globalThis).document?.baseURI ?? /** @type {any} */ (globalThis).location?.href;
+  if (base || /^[a-z][\w+.-]*:/i.test(s)) return asBytes(await fetcher()(new URL(s, base).href));
+  throw new Error(`Can't load ${kind} "${s}" here: pass bytes, or give covers a loader with configure({ load })`);
+}
+
+export { asBytes };

package/src/platform/no-harfbuzz.d.ts

@@ -0,0 +1,2 @@
+// What #harfbuzz resolves to in Workers: importing it fails.
+export {};

package/src/platform/no-harfbuzz.js

@@ -0,0 +1,11 @@
+/**
+ * What `#harfbuzz` resolves to in Cloudflare Workers (the `workerd` and
+ * `worker` export conditions): harfbuzzjs needs to compile WebAssembly
+ * trampolines at runtime, which Workers forbid, and its loader imports
+ * `node:module`. Importing this fails, so text falls back to the built-in
+ * JavaScript outliner (`sfnt.js`).
+ *
+ * @module no-harfbuzz
+ */
+
+throw new Error('HarfBuzz is not available in Cloudflare Workers; covers draws text with its JavaScript outliner there');

package/src/platform/settings.d.ts

@@ -0,0 +1,28 @@
+// Global settings.
+import type { FontSource } from '../index.js';
+
+/** Global settings: how files load, where HarfBuzz comes from, how text is drawn. */
+export interface Settings {
+  /** Load a file (an image, font, audio or icon set): return bytes, an ArrayBuffer, a Blob or a Response, or undefined to fall through. */
+  load?: (src: unknown, info: { kind: string }) => unknown;
+  /** Allow fetching http(s) URLs (default: yes in browsers and Workers, no in Node). */
+  network?: boolean;
+  fetch?: typeof fetch;
+  /** HarfBuzz's wasm: a URL, bytes, a compiled `WebAssembly.Module`, a `Response`, or a promise of one. */
+  harfbuzz?: unknown;
+  /** `'auto'` (HarfBuzz where it runs, else the JavaScript outliner), `'harfbuzz'`, `'js'`. */
+  shaper?: 'auto' | 'harfbuzz' | 'js';
+  text?: 'outline' | 'live';
+  /** Where icon sets load from outside Node: a URL template with `{prefix}`, or a function. */
+  icons?: string | ((prefix: string) => string);
+  /** Fonts for every cover. */
+  fonts?: FontSource[];
+}
+
+
+/** The current settings. */
+export const settings: Settings;
+/** Fonts registered for every cover. */
+export const registry: FontSource[];
+/** Configure loading, HarfBuzz and text rendering (merges with what's set). */
+export function configure(options: Settings): void;

package/src/platform/settings.js

@@ -0,0 +1,51 @@
+/**
+ * Global settings: how files load, where HarfBuzz comes from, how text is
+ * drawn. Set with {@link configure}.
+ *
+ * @module platform/settings
+ */
+
+/**
+ * @typedef {object} Settings
+ * @property {((src: any, info: { kind: string }) => any) | undefined} load - A loader hook; return bytes (or a Response, Blob, ArrayBuffer), or undefined to fall through.
+ * @property {boolean | undefined} network - Allow fetching http(s) URLs.
+ * @property {typeof fetch | undefined} fetch - The fetch to use.
+ * @property {any} harfbuzz - HarfBuzz's wasm: a URL, bytes, a WebAssembly.Module, a Response, or a promise of one.
+ * @property {'auto' | 'harfbuzz' | 'js'} shaper - How text is shaped and outlined.
+ * @property {'outline' | 'live'} text - The default text rendering.
+ * @property {((prefix: string) => string) | string | undefined} icons - Where icon sets load from outside Node: a URL template with `{prefix}`, or a function.
+ */
+
+/** @type {Settings} */
+export const settings = {
+  load: undefined,
+  network: undefined,
+  fetch: undefined,
+  harfbuzz: undefined,
+  shaper: 'auto',
+  text: 'outline',
+  icons: undefined,
+};
+
+/**
+ * Configure how covers loads files, fetches, shapes text and finds
+ * HarfBuzz. Settings are global and merge with what's set already.
+ *
+ * @param {Partial<Settings> & { fonts?: import('../index.js').FontSource[] }} options
+ * @returns {void}
+ *
+ * @example
+ * // A browser app serving the wasm itself:
+ * configure({ harfbuzz: '/wasm/harfbuzz.wasm' });
+ * // A Worker: no wasm compilation at runtime, so text uses the JS outliner.
+ * configure({ shaper: 'js' });
+ */
+export function configure(options = {}) {
+  for (const k of /** @type {(keyof Settings)[]} */ (Object.keys(settings))) {
+    if (Object.hasOwn(options, k)) /** @type {any} */ (settings)[k] = /** @type {any} */ (options)[k];
+  }
+  if (options.fonts) for (const f of options.fonts) registry.push(f);
+}
+
+/** Fonts registered globally (`configure({ fonts })`, `registerFont()`). @type {import('../index.js').FontSource[]} */
+export const registry = [];

package/src/print.js

@@ -5,11 +5,13 @@
  * @module print
  */
 
-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 { attrs, num, esc } from '@logomarks/image-effects/svg';
+import { layerAttrs } from './layers/util.js';
+import { len } from '@logomarks/image-effects/length';
+import { regionPx } from './geometry.js';
+import { toHex } from '@logomarks/image-effects/color';
+import { createRng } from '@logomarks/image-effects/rng';
+import { encodePngAsync, pngUri } from '@logomarks/image-effects/png';
 import { text as textLayer } from './layers.js';
 
 /** Classic risograph inks, by name (`'riso:pink'`). Approximations, not trademarks. */
@@ -126,7 +128,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 +155,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>`;
   }
@@ -181,7 +183,7 @@ export async function ink(layer, ctx) {
 /**
  * Seeded value noise in 2D, smooth, in [0, 1], with octaves.
  *
- * @param {import('./rng.js').Rng} rng
+ * @param {import('@logomarks/image-effects/rng').Rng} rng
  * @param {number} octaves
  * @returns {(x: number, y: number) => number}
  */
@@ -242,9 +244,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 +311,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) };
 }
 
@@ -457,7 +459,7 @@ function smoothPath(pts) {
  * Seeded demo peaks: a smooth loudness envelope with transients. Not audio:
  * pass `peaks` or `audio` for a real episode.
  *
- * @param {import('./rng.js').Rng} rng
+ * @param {import('@logomarks/image-effects/rng').Rng} rng
  * @param {number} n
  * @returns {number[]}
  */
@@ -515,7 +517,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/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.
@@ -33,7 +33,7 @@ import { defineRecipe } from './json-recipe.js';
  * @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 {import('@logomarks/image-effects/rng').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).
  */
@@ -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 '@logomarks/image-effects/color';
+import { pixelsOf } from '@logomarks/image-effects/raster';
+
+/**
+ * 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/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('@logomarks/image-effects/rng').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 '@logomarks/image-effects/svg';
+import { pos } from '../layers/util.js';
+import { scaledReport } from './report.js';
+import { IDENTITY, compose } from './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('./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>;