@arraypress/covers 1.0.0 → 1.1.0

package/src/effects/dither.js

@@ -0,0 +1,147 @@
+/**
+ * An ordered (Bayer) dither in two colours, optionally pixelated first:
+ * computed on pixels where something can rasterise (the layer drawn once
+ * at one pixel per cell, thresholded here, embedded with nearest-neighbour
+ * scaling), else as an SVG filter.
+ *
+ * @module effects/dither
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { encodePng, encodePngAsync, pngUri } from '../png.js';
+import { pixelsOf } from '../raster/index.js';
+import { LUMA, rgb, mat } from './util.js';
+
+/** Bayer matrices. */
+const BAYER = {
+  bayer4: [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5],
+  bayer8: (() => {
+    const m4 = [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5];
+    const out = new Array(64);
+    for (let y = 0; y < 8; y++) for (let x = 0; x < 8; x++) {
+      const base = m4[(y % 4) * 4 + (x % 4)];
+      const q = (y >> 2) * 2 + (x >> 2);
+      out[y * 8 + x] = base * 4 + [0, 2, 3, 1][q];
+    }
+    return out;
+  })(),
+};
+
+/**
+ * An ordered (Bayer) dither in two colours, optionally pixelated to a
+ * visible cell first. The threshold matrix is a tiny PNG tiled with feTile.
+ *
+ * @param {any} fx - `{ ink, paper, cell, contrast, brightness, pixelate, weights, matrix }`.
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function dither(fx, ctx) {
+  const [ir, ig, ib] = rgb(fx.ink ?? '#0b0b0b');
+  const [pr, pg, pb] = rgb(fx.paper ?? '#f4f1ea');
+  const c = Math.max(1, len(fx.cell, ctx.canvas, '0.65vmin'));
+  const contrast = fx.contrast ?? 1.45;
+  const bright = fx.brightness ?? 0.06;
+  const wts = fx.weights ?? LUMA;
+  const { n, px } = thresholds(fx);
+  const tile = pngUri(encodePng(px, n, n, 1));
+  let out = '';
+  let src = 'SourceGraphic';
+  if (fx.pixelate !== false) {
+    const d = Math.max(0.3, c / 2 - 0.3);
+    out += `<feFlood flood-color="#fff" x="${num(c / 2 - 0.3, 3)}" y="${num(c / 2 - 0.3, 3)}" width="0.6" height="0.6" result="dot"/><feComposite in="dot" in2="dot" operator="over" x="0" y="0" width="${num(c, 3)}" height="${num(c, 3)}" result="cell"/><feTile in="cell" result="grid"/>`
+      + `<feComposite in="SourceGraphic" in2="grid" operator="in" result="sample"/><feMorphology in="sample" operator="dilate" radius="${num(d, 3)}" result="px"/>`;
+    src = 'px';
+  }
+  const o = 0.5 - contrast * 0.5 + bright;
+  const row = wts.map((/** @type {number} */ x) => x * contrast);
+  out += `<feColorMatrix in="${src}" type="matrix" values="${mat([...row, 0, o, ...row, 0, o, ...row, 0, o, 0, 0, 0, 1, 0])}" result="lum"/>`
+    + `<feImage${attrs({ href: tile, x: 0, y: 0, width: c * n, height: c * n, preserveAspectRatio: 'none', 'image-rendering': 'pixelated', result: 'b' })}/><feTile in="b" result="bt"/>`
+    + '<feComposite in="lum" in2="bt" operator="arithmetic" k2="1" k3="1" k4="-0.5"/>'
+    + `<feComponentTransfer><feFuncR type="discrete" tableValues="${num(ir, 3)} ${num(pr, 3)}"/><feFuncG type="discrete" tableValues="${num(ig, 3)} ${num(pg, 3)}"/><feFuncB type="discrete" tableValues="${num(ib, 3)} ${num(pb, 3)}"/><feFuncA type="discrete" tableValues="1 1"/></feComponentTransfer>`
+    + '<feComposite in2="SourceGraphic" operator="in"/>';
+  return out;
+}
+
+/**
+ * The threshold matrix as 8-bit greys (the filter's tile, and the raster's thresholds).
+ *
+ * @param {any} fx
+ * @returns {{ n: number, px: Uint8Array }}
+ */
+function thresholds(fx) {
+  const matrix = /** @type {number[]} */ ((/** @type {any} */ (BAYER))[fx.matrix ?? 'bayer4'] ?? BAYER.bayer4);
+  const n = Math.round(Math.sqrt(matrix.length));
+  const px = new Uint8Array(n * n);
+  matrix.forEach((v, i) => { px[i] = Math.round((1 - (v + 0.5) / (n * n)) * 255); });
+  return { n, px };
+}
+
+/**
+ * The dither on pixels: the layer is drawn once at one pixel per cell
+ * (`pixelate`, the default) or at output resolution, thresholded against
+ * the matrix here, and embedded scaled up nearest-neighbour. Where the
+ * layer isn't opaque the result is clipped to its shape. The same
+ * arithmetic as the filter (sRGB, `contrast`, `brightness`, `weights`).
+ *
+ * @param {any} fx
+ * @param {{ defs: string, body: string }} m - The layer's markup so far.
+ * @param {import('../layers.js').RenderContext} ctx
+ * @param {string} id
+ * @returns {Promise<{ defs: string, body: string } | undefined>} Undefined where nothing can rasterise.
+ */
+export async function ditherRaster(fx, m, ctx, id) {
+  const c = Math.max(1e-3, len(fx.cell, ctx.canvas, '0.65vmin'));
+  // Pixels per unit: one per cell, or the output's resolution (at least one per cell).
+  const ppu = fx.pixelate === false ? Math.max(1 / c, /** @type {any} */ (ctx).res ?? 1) : 1 / c;
+  const w = Math.max(1, Math.ceil(ctx.width * ppu));
+  const h = Math.max(1, Math.ceil(ctx.height * ppu));
+  const uw = w / ppu;
+  const uh = h / ppu;
+  const doc = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${num(uw, 4)} ${num(uh, 4)}" preserveAspectRatio="none">${m.defs ? `<defs>${m.defs}</defs>` : ''}${m.body}</svg>`;
+  let src;
+  try {
+    src = await pixelsOf(doc, w, h, /** @type {any} */ (ctx).sharp);
+  } catch {
+    src = undefined;
+  }
+  if (!src) return undefined;
+
+  const ink = rgb(fx.ink ?? '#0b0b0b').map((v) => Math.round(v * 255));
+  const paper = rgb(fx.paper ?? '#f4f1ea').map((v) => Math.round(v * 255));
+  const contrast = fx.contrast ?? 1.45;
+  const o = 0.5 - contrast * 0.5 + (fx.brightness ?? 0.06);
+  const [wr, wg, wb] = /** @type {number[]} */ (fx.weights ?? LUMA).map((x) => (x * contrast) / 255);
+  const { n, px: t } = thresholds(fx);
+  const cellPx = c * ppu;
+  const out = new Uint8Array(w * h * 4);
+  let opaque = true;
+  for (let y = 0; y < h; y++) {
+    const ty = (Math.floor(y / cellPx + 1e-6) % n) * n;
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 4;
+      const a = src[i + 3];
+      if (a < 255) opaque = false;
+      if (!a) continue;
+      // Ink where luminance and threshold fall short of 1 (the filter's discrete step at 0.5 after −0.5).
+      const lum = src[i] * wr + src[i + 1] * wg + src[i + 2] * wb + o;
+      const col = lum + t[ty + (Math.floor(x / cellPx + 1e-6) % n)] / 255 < 1 ? ink : paper;
+      out[i] = col[0]; out[i + 1] = col[1]; out[i + 2] = col[2]; out[i + 3] = 255;
+    }
+  }
+  const png = opaque ? await encodePngAsync(rgbOf(out), w, h, 3) : await encodePngAsync(out, w, h, 4);
+  const image = `<image${attrs({ x: 0, y: 0, width: num(uw, 4), height: num(uh, 4), preserveAspectRatio: 'none', 'image-rendering': 'pixelated', style: 'image-rendering:pixelated', href: pngUri(png) })}/>`;
+  if (opaque) return { defs: '', body: image };
+  // Clipped to the layer's own shape (its alpha, at full resolution).
+  const region = { x: -uw, y: -uh, width: uw * 3, height: uh * 3 };
+  const defs = `${m.defs}<filter${attrs({ id: `${id}w`, filterUnits: 'userSpaceOnUse', ...region })}><feColorMatrix type="matrix" values="0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 1 0"/></filter>`
+    + `<mask${attrs({ id: `${id}m`, maskUnits: 'userSpaceOnUse', ...region })}><g filter="url(#${id}w)">${m.body}</g></mask>`;
+  return { defs, body: `<g mask="url(#${id}m)">${image}</g>` };
+}
+
+/** @param {Uint8Array} rgba @returns {Uint8Array} The RGB channels. */
+function rgbOf(rgba) {
+  const out = new Uint8Array((rgba.length / 4) * 3);
+  for (let i = 0, j = 0; i < rgba.length; i += 4, j += 3) { out[j] = rgba[i]; out[j + 1] = rgba[i + 1]; out[j + 2] = rgba[i + 2]; }
+  return out;
+}

package/src/effects/drop-shadow.d.ts

@@ -0,0 +1,4 @@
+// feDropShadow as the primitives it stands for.
+
+/** Replace every `<feDropShadow>` in filter markup with blur, offset, flood, composite and merge (its `in` honoured). */
+export function expandDropShadows(markup: string): string;

package/src/effects/drop-shadow.js

@@ -0,0 +1,45 @@
+/**
+ * `feDropShadow` spelled out as the primitives it stands for, so its `in`
+ * is honoured (librsvg ignores `in` on `feDropShadow` and shadows the
+ * source graphic, which silently drops whatever the chain built before it).
+ *
+ * @module effects/drop-shadow
+ */
+
+import { attrs } from '../svg.js';
+
+/** @param {string} s @returns {Record<string, string>} An element's attributes. */
+function attributes(s) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const m of s.matchAll(/([\w:-]+)\s*=\s*("([^"]*)"|'([^']*)')/g)) out[m[1]] = m[3] ?? m[4];
+  return out;
+}
+
+/**
+ * Replace every `<feDropShadow>` in filter markup with blur, offset, flood,
+ * composite and merge. Without an `in`, it takes the previous result (or
+ * the source graphic), exactly as `feDropShadow` does.
+ *
+ * @param {string} markup - Filter primitives.
+ * @returns {string}
+ *
+ * @example
+ * expandDropShadows('<feDropShadow in="felt" dy="2" stdDeviation="1"/>');
+ */
+export function expandDropShadows(markup) {
+  let n = 0;
+  return markup.replace(/<feDropShadow\b([^>]*?)\/?>(?:\s*<\/feDropShadow>)?/gi, (_, raw) => {
+    const a = attributes(raw);
+    const k = `ds${n++}`;
+    const shared = { x: a.x, y: a.y, width: a.width, height: a.height, 'color-interpolation-filters': a['color-interpolation-filters'] };
+    // An identity offset names the input when none is given (the previous result).
+    const input = a.in ?? `${k}i`;
+    const pick = a.in ? '' : `<feOffset${attrs({ dx: 0, dy: 0, result: input })}/>`;
+    return `${pick}<feGaussianBlur${attrs({ in: input, stdDeviation: a.stdDeviation ?? 2, ...shared })}/>`
+      + `<feOffset${attrs({ dx: a.dx ?? 2, dy: a.dy ?? 2, result: `${k}o`, ...shared })}/>`
+      + `<feFlood${attrs({ 'flood-color': a['flood-color'] ?? '#000', 'flood-opacity': a['flood-opacity'] ?? 1, ...shared })}/>`
+      + `<feComposite${attrs({ in2: `${k}o`, operator: 'in', result: `${k}s`, ...shared })}/>`
+      + `<feMerge${attrs({ result: a.result, ...shared })}><feMergeNode in="${k}s"/><feMergeNode in="${input}"/></feMerge>`;
+  });
+}

package/src/effects/extrude.d.ts

@@ -0,0 +1,5 @@
+// The `extrude` effect.
+import type { RenderContext, Markup } from '../render/context.js';
+
+/** A layer drawn again behind itself, a step further each time, in a darker colour. */
+export function extrude(fx: { kind: 'extrude'; depth?: import('../index.js').Length; angle?: number; offset?: [import('../index.js').Length, import('../index.js').Length]; steps?: number; color?: string; to?: string }, m: Markup, ctx: RenderContext, id: string): Markup;

package/src/effects/extrude.js

@@ -0,0 +1,55 @@
+/**
+ * `extrude`: a layer drawn again and again behind itself, a step further
+ * each time, in a darker colour: block type and 3D marks in one effect.
+ *
+ * @module effects/extrude
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { mixOklab, toHex } from '../color.js';
+import { filterElement, flood } from './util.js';
+
+/**
+ * The extrusion: `steps` copies (default enough for a solid side at the
+ * output size, at most 64) along `angle` (degrees, 0 up, 90 right;
+ * default 135) to `depth` (a length, default `'3vmin'`), or along `[x, y]`
+ * (`offset`). Copies are `color` (default near-black), fading to `to` at
+ * the far end; the layer is drawn on top. The markup is written once and
+ * reused (`<use>`).
+ *
+ * @param {any} fx - `{ kind: 'extrude', depth, angle, offset, steps, color, to }`.
+ * @param {{ defs: string, body: string }} m
+ * @param {import('../layers.js').RenderContext} ctx
+ * @param {string} id
+ * @returns {{ defs: string, body: string }}
+ */
+export function extrude(fx, m, ctx, id) {
+  const [ox, oy] = fx.offset
+    ? [len(fx.offset[0], ctx.canvas), len(fx.offset[1], ctx.canvas)]
+    : (() => {
+        const d = len(fx.depth, ctx.canvas, '3vmin');
+        const a = ((fx.angle ?? 135) * Math.PI) / 180;
+        return [Math.sin(a) * d, -Math.cos(a) * d];
+      })();
+  const reach = Math.hypot(ox, oy);
+  const res = /** @type {any} */ (ctx).res ?? 1;
+  const steps = Math.max(1, Math.round(fx.steps ?? Math.min(64, Math.max(6, Math.ceil(reach * res)))));
+  const near = toHex(fx.color ?? '#141414');
+  const far = fx.to ? toHex(fx.to) : near;
+  // Colour bands (far first): one recolouring filter per band.
+  const bands = Math.min(steps, far === near ? 1 : 8);
+  const pad = reach / Math.min(ctx.width, ctx.height) + 0.05;
+  let defs = `${m.defs}<g id="${id}s">${m.body}</g>`;
+  let body = '';
+  for (let b = 0; b < bands; b++) {
+    const from = Math.floor((b * steps) / bands);
+    const to = Math.floor(((b + 1) * steps) / bands);
+    const color = mixOklab(far, near, bands === 1 ? 1 : b / (bands - 1));
+    defs += filterElement(`${id}e${b}`, ctx, pad, `<feColorMatrix in="SourceGraphic" type="matrix" values="${flood(color)}"/>`);
+    let copies = '';
+    for (let i = steps - from; i > steps - to; i--) copies += `<use${attrs({ href: `#${id}s`, transform: `translate(${num((ox * i) / steps, 3)} ${num((oy * i) / steps, 3)})` })}/>`;
+    body += `<g filter="url(#${id}e${b})">${copies}</g>`;
+  }
+  return { defs, body: `${body}<use href="#${id}s"/>` };
+}

package/src/effects/film.d.ts

@@ -0,0 +1,11 @@
+// Film grain, paper, dust and scratches.
+import type { Effect } from './index.js';
+import type { RenderContext } from '../render/context.js';
+import type { Pixels } from './buffer.js';
+
+/** The `grain` effect's filter primitives. */
+export function grain(fx: Extract<Effect, { kind: 'grain' }>, ctx: RenderContext): string;
+/** The `paper` effect's filter primitives. */
+export function paper(fx: Extract<Effect, { kind: 'paper' }>, ctx: RenderContext): string;
+/** `dust`, on pixels. */
+export function dust(img: Pixels, fx: Extract<Effect, { kind: 'dust' }>, ctx: object): Uint8ClampedArray;

package/src/effects/film.js

@@ -0,0 +1,204 @@
+/**
+ * Film and paper: `grain` (film grain as a filter, overlaid so it lives in
+ * the midtones as real grain does; monochrome or colour), `paper` (the
+ * layer printed on paper or canvas: a lit relief overlaid) and `dust`
+ * (specks, hairs and scratches, seeded, drawn on pixels).
+ *
+ * @module effects/film
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { encodePng, pngUri } from '../png.js';
+import { createRng } from '../rng.js';
+import { mat, seedOf } from './util.js';
+import { px, seedFor } from './buffer.js';
+
+/**
+ * `grain`: film grain, `amount` (0–1), `size` (a length: the grain), and
+ * `color` (true: each channel its own grain, as colour film; default
+ * monochrome). Overlaid, so it's strongest in the midtones.
+ *
+ * @param {import('./index.js').Effect & { kind: 'grain' }} fx
+ * @param {import('../render/context.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function grain(fx, ctx) {
+  const size = Math.max(0.05, len(fx.size, ctx.canvas, '0.09vmin'));
+  const a = (fx.amount ?? 0.35) * 1.5;
+  const mono = !fx.color;
+  // Noise centred on mid-grey with its spread set by amount.
+  const row = (/** @type {number} */ c) => (mono ? [a, 0, 0, 0, 0.5 - a / 2] : [c === 0 ? a : 0, c === 1 ? a : 0, c === 2 ? a : 0, 0, 0.5 - a / 2]);
+  return `<feTurbulence type="fractalNoise" baseFrequency="${num(0.5 / size, 4)}" numOctaves="2" seed="${seedOf(ctx, fx)}" result="gn"/>`
+    + `<feColorMatrix in="gn" type="matrix" values="${mat([...row(0), ...row(1), ...row(2), 0, 0, 0, 0, 1])}" result="gc"/>`
+    + '<feBlend in="gc" in2="SourceGraphic" mode="overlay"/><feComposite in2="SourceAlpha" operator="in"/>';
+}
+
+/** @type {Map<string, string>} */
+const WEAVES = new Map();
+
+/**
+ * A tile of canvas weave as heights: over-under threads, 2×2 to the tile.
+ *
+ * @returns {string} A data URI.
+ */
+function weave() {
+  const hit = WEAVES.get('w');
+  if (hit) return hit;
+  const n = 32;
+  const out = new Uint8Array(n * n);
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      const u = (x + 0.5) / n;
+      const v = (y + 0.5) / n;
+      // Warp and weft threads, each a rounded ridge; which is on top alternates.
+      const warp = Math.cos(Math.PI * ((u * 2) % 1 - 0.5)) ** 0.6;
+      const weft = Math.cos(Math.PI * ((v * 2) % 1 - 0.5)) ** 0.6;
+      const top = (Math.floor(u * 2) + Math.floor(v * 2)) % 2 === 0;
+      out[y * n + x] = Math.round(255 * (top ? 0.25 + 0.75 * warp * (0.6 + 0.4 * weft) : 0.25 + 0.75 * weft * (0.6 + 0.4 * warp)));
+    }
+  }
+  const uri = pngUri(encodePng(out, n, n, 1));
+  WEAVES.set('w', uri);
+  return uri;
+}
+
+/**
+ * `paper`: printed on a surface. `texture` `'paper'` (fibrous, uneven) or
+ * `'canvas'` (a woven tooth), `scale` (a length: the fibres, or a thread
+ * pair), `amount` (0–1), lit from `angle`; the lit relief is overlaid.
+ *
+ * @param {import('./index.js').Effect & { kind: 'paper' }} fx
+ * @param {import('../render/context.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function paper(fx, ctx) {
+  const texture = fx.texture ?? 'paper';
+  if (texture !== 'paper' && texture !== 'canvas') throw new TypeError(`Unknown paper texture "${texture}" (paper, canvas)`);
+  const amount = fx.amount ?? 0.5;
+  const az = fx.angle ?? 225;
+  let relief;
+  if (texture === 'canvas') {
+    const s = len(fx.scale, ctx.canvas, '0.9vmin');
+    relief = `<feImage${attrs({ href: weave(), x: 0, y: 0, width: s, height: s, preserveAspectRatio: 'none', result: 'pt' })}/><feTile in="pt"/>`
+      + '<feColorMatrix type="luminanceToAlpha" color-interpolation-filters="sRGB" result="ph"/>';
+  } else {
+    const s = len(fx.scale, ctx.canvas, '0.45vmin');
+    relief = `<feTurbulence type="fractalNoise" baseFrequency="${num(1 / s, 4)} ${num(0.6 / s, 4)}" numOctaves="4" seed="${seedOf(ctx, fx)}"/>`
+      + '<feColorMatrix type="luminanceToAlpha" color-interpolation-filters="sRGB" result="ph"/>';
+  }
+  const depth = texture === 'canvas' ? 3 : 2.5;
+  // Lit flat, the surface is sin(elevation) grey; that maps to 0.5 (no change under overlay).
+  const elev = 50;
+  const flat = Math.sin((elev * Math.PI) / 180);
+  const k = (texture === 'canvas' ? 0.8 : 0.7) * amount;
+  const row = (/** @type {number} */ c) => [c === 0 ? k / flat : 0, c === 1 ? k / flat : 0, c === 2 ? k / flat : 0, 0, 0.5 - k];
+  return relief
+    + `<feDiffuseLighting in="ph" surfaceScale="${num(depth, 3)}" diffuseConstant="1" lighting-color="#fff" color-interpolation-filters="sRGB" result="pl"><feDistantLight azimuth="${num(az)}" elevation="${elev}"/></feDiffuseLighting>`
+    // Lit ridges lighten, shaded ones darken: the relief overlaid.
+    + `<feColorMatrix in="pl" type="matrix" values="${mat([...row(0), ...row(1), ...row(2), 0, 0, 0, 0, 1])}" result="pm"/>`
+    + '<feBlend in="pm" in2="SourceGraphic" mode="overlay"/><feComposite in2="SourceAlpha" operator="in"/>';
+}
+
+/**
+ * Stamp an anti-aliased stroke (a polyline of `[x, y]` points) or speck
+ * into a coverage buffer.
+ *
+ * @param {Float32Array} cov
+ * @param {number} w
+ * @param {number} h
+ * @param {[number, number][]} pts
+ * @param {number} r - Half-width, px.
+ * @param {number} o - Opacity.
+ * @returns {void}
+ */
+function stroke(cov, w, h, pts, r, o) {
+  for (let s = 0; s < pts.length - (pts.length > 1 ? 1 : 0); s++) {
+    const [x0, y0] = pts[s];
+    const [x1, y1] = pts.length > 1 ? pts[s + 1] : pts[s];
+    const dx = x1 - x0;
+    const dy = y1 - y0;
+    const l2 = dx * dx + dy * dy || 1e-9;
+    const bx0 = Math.max(0, Math.floor(Math.min(x0, x1) - r - 1));
+    const bx1 = Math.min(w - 1, Math.ceil(Math.max(x0, x1) + r + 1));
+    const by0 = Math.max(0, Math.floor(Math.min(y0, y1) - r - 1));
+    const by1 = Math.min(h - 1, Math.ceil(Math.max(y0, y1) + r + 1));
+    for (let y = by0; y <= by1; y++) {
+      for (let x = bx0; x <= bx1; x++) {
+        const t = Math.max(0, Math.min(1, ((x + 0.5 - x0) * dx + (y + 0.5 - y0) * dy) / l2));
+        const d = Math.hypot(x + 0.5 - x0 - t * dx, y + 0.5 - y0 - t * dy);
+        const c = Math.max(0, Math.min(1, r + 0.5 - d)) * o;
+        const i = y * w + x;
+        if (c > cov[i]) cov[i] = c;
+      }
+    }
+  }
+}
+
+/**
+ * `dust`: dust and scratches on film, seeded: specks (`amount`, 0–1),
+ * curling hairs, and `scratches` running down the frame; `color`
+ * `'light'` (dust on a negative prints white), `'dark'`, or `'mixed'`.
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'dust' }} fx
+ * @param {any} ctx
+ * @returns {Uint8ClampedArray}
+ */
+export function dust(img, fx, ctx) {
+  const { data, width: w, height: h } = img;
+  const rng = createRng(`dust:${seedFor(fx, ctx)}`);
+  const unit = px('0.1vmin', ctx, img, 0);
+  const amount = fx.amount ?? 0.5;
+  const mode = fx.color ?? 'mixed';
+  if (!['light', 'dark', 'mixed'].includes(mode)) throw new TypeError(`Unknown dust color "${mode}" (light, dark, mixed)`);
+  const light = new Float32Array(w * h);
+  const dark = new Float32Array(w * h);
+  const pick = () => (mode === 'light' ? light : mode === 'dark' ? dark : rng.chance(0.7) ? light : dark);
+  const specks = Math.round(amount * 260);
+  for (let i = 0; i < specks; i++) {
+    const x = rng.range(0, w);
+    const y = rng.range(0, h);
+    const r = unit * rng.range(0.3, 1) * (rng.chance(0.08) ? 3.5 : 1);
+    // A clump of two or three dots, so specks aren't perfect circles.
+    const buf = pick();
+    const o = rng.range(0.35, 0.95);
+    for (let k = 0, n = rng.int(1, 3); k < n; k++) stroke(buf, w, h, [[x + rng.range(-r, r), y + rng.range(-r, r)]], r * rng.range(0.5, 1), o);
+  }
+  const hairs = Math.round(amount * 9);
+  for (let i = 0; i < hairs; i++) {
+    /** @type {[number, number][]} */
+    const pts = [[rng.range(0, w), rng.range(0, h)]];
+    let a = rng.range(0, Math.PI * 2);
+    const seg = unit * rng.range(3, 7);
+    for (let k = 0, n = rng.int(12, 40); k < n; k++) {
+      a += rng.range(-0.35, 0.35);
+      const [px0, py0] = pts[pts.length - 1];
+      pts.push([px0 + Math.cos(a) * seg, py0 + Math.sin(a) * seg]);
+    }
+    stroke(pick(), w, h, pts, unit * rng.range(0.25, 0.5), rng.range(0.5, 0.9));
+  }
+  const scratches = fx.scratches ?? Math.round(amount * 4);
+  for (let i = 0; i < scratches; i++) {
+    let x = rng.range(0, w);
+    const y0 = rng.chance(0.5) ? 0 : rng.range(0, h * 0.6);
+    const y1 = rng.chance(0.5) ? h : rng.range(y0 + h * 0.2, h);
+    /** @type {[number, number][]} */
+    const pts = [];
+    for (let y = y0; y <= y1; y += h / 24) { pts.push([x, y]); x += rng.range(-0.6, 0.6) * unit; }
+    stroke(rng.chance(0.75) ? light : dark, w, h, pts, unit * rng.range(0.15, 0.4), rng.range(0.3, 0.7));
+  }
+  const out = new Uint8ClampedArray(data);
+  for (let p = 0, i = 0; p < light.length; p++, i += 4) {
+    const l = light[p];
+    const d = dark[p];
+    if (!l && !d) continue;
+    for (let c = 0; c < 3; c++) {
+      let v = out[i + c];
+      v += (250 - v) * l;
+      v -= (v - 12) * d;
+      out[i + c] = v;
+    }
+  }
+  return out;
+}

package/src/effects/glow.d.ts

@@ -0,0 +1,8 @@
+// Light spreading from the bright parts.
+import type { Effect } from './index.js';
+import type { RenderContext } from '../render/context.js';
+
+/** The `bloom` effect's filter primitives. */
+export function bloom(fx: Extract<Effect, { kind: 'bloom' }>, ctx: RenderContext): string;
+/** The `halation` effect's filter primitives. */
+export function halation(fx: Extract<Effect, { kind: 'halation' }>, ctx: RenderContext): string;

package/src/effects/glow.js

@@ -0,0 +1,56 @@
+/**
+ * Light that spreads from the bright parts, as SVG filters: `bloom` (the
+ * highlights glowing, at two scales, screened over the layer) and
+ * `halation` (film's red-orange halo round bright edges, where light
+ * bounced off the film base back through the red layer).
+ *
+ * @module effects/glow
+ */
+
+import { num } from '../svg.js';
+import { len } from '../geometry.js';
+import { LUMA, rgb, mat } from './util.js';
+
+/**
+ * `bloom`: what's brighter than `threshold` (0–1), blurred to `radius`
+ * and to three times that, screened over the layer at `intensity`, tinted
+ * by `color` when given. It spreads past the layer's edges (neon type).
+ *
+ * @param {import('./index.js').Effect & { kind: 'bloom' }} fx
+ * @param {import('../render/context.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function bloom(fx, ctx) {
+  const t = Math.min(0.99, fx.threshold ?? 0.65);
+  const r = len(fx.radius, ctx.canvas, '1.6vmin');
+  const k = fx.intensity ?? 0.9;
+  const slope = 1 / (1 - t);
+  const tint = fx.color ? rgb(fx.color) : [1, 1, 1];
+  return `<feComponentTransfer in="SourceGraphic">${['R', 'G', 'B'].map((ch, i) => `<feFunc${ch} type="linear" slope="${num(slope * tint[i], 4)}" intercept="${num(-t * slope * tint[i], 4)}"/>`).join('')}</feComponentTransfer>`
+    + '<feComposite in2="SourceAlpha" operator="in" result="bh"/>'
+    + `<feGaussianBlur in="bh" stdDeviation="${num(r)}" result="b1"/><feGaussianBlur in="bh" stdDeviation="${num(r * 3)}" result="b2"/>`
+    + `<feComposite in="b1" in2="b2" operator="arithmetic" k2="${num(0.6 * k, 3)}" k3="${num(0.7 * k, 3)}" result="bg"/>`
+    + '<feBlend in="bg" in2="SourceGraphic" mode="screen"/>';
+}
+
+/**
+ * `halation`: the highlights above `threshold`, flooded with `color`
+ * (default film's red-orange), blurred to `radius` and screened on at
+ * `intensity`.
+ *
+ * @param {import('./index.js').Effect & { kind: 'halation' }} fx
+ * @param {import('../render/context.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function halation(fx, ctx) {
+  const t = Math.min(0.99, fx.threshold ?? 0.72);
+  const [r, g, b] = rgb(fx.color ?? '#ff3d14');
+  const k = 1 / (1 - t);
+  const i = fx.intensity ?? 1;
+  return `<feColorMatrix in="SourceGraphic" type="matrix" values="${mat([0, 0, 0, 0, r, 0, 0, 0, 0, g, 0, 0, 0, 0, b, LUMA[0] * k, LUMA[1] * k, LUMA[2] * k, 0, -t * k])}"/>`
+    + '<feComposite in2="SourceAlpha" operator="in"/>'
+    + `<feGaussianBlur stdDeviation="${num(len(fx.radius, ctx.canvas, '0.9vmin'))}"/>`
+    + `<feComponentTransfer><feFuncA type="linear" slope="${num(i, 3)}"/></feComponentTransfer>`
+    + '<feComposite in2="SourceAlpha" operator="in" result="hl"/>'
+    + '<feBlend in="hl" in2="SourceGraphic" mode="screen"/>';
+}

package/src/effects/grade.d.ts

@@ -0,0 +1,30 @@
+// Colour grading.
+import type { Effect } from './index.js';
+import type { Pixels } from './buffer.js';
+
+/** A monotone cubic through points, sampled as a table. */
+export function curveTable(points: [number, number][], n?: number): number[];
+/** A component transfer from three tables (R, G, B). */
+export function transfer(tables: number[][]): string;
+/** A gradient's colour at `t`, 0–1 channels. */
+export function sampleGradient(colors: string[], stops: number[], t: number, space: 'srgb' | 'oklab'): [number, number, number];
+/** A colour balance's tables, per channel. */
+export function balanceTables(fx: { shadows?: number[]; midtones?: number[]; highlights?: number[] }): number[][];
+/** The `curves` effect's filter primitives. */
+export function curves(fx: Extract<Effect, { kind: 'curves' }>): string;
+/** The `gradientMap` effect's filter primitives. */
+export function gradientMap(fx: Extract<Effect, { kind: 'gradientMap' }>): string;
+/** The `posterize` effect's filter primitives. */
+export function posterize(fx: Extract<Effect, { kind: 'posterize' }>): string;
+/** The `invert` effect's filter primitives. */
+export function invert(fx: Extract<Effect, { kind: 'invert' }>): string;
+/** The `hue` effect's filter primitives. */
+export function hue(fx: Extract<Effect, { kind: 'hue' }>): string;
+/** The `colorBalance` effect's filter primitives. */
+export function colorBalance(fx: Extract<Effect, { kind: 'colorBalance' }>): string;
+/** The `channelMixer` effect's filter primitives. */
+export function channelMixer(fx: Extract<Effect, { kind: 'channelMixer' }>): string;
+/** The `sepia` effect's filter primitives. */
+export function sepia(fx: Extract<Effect, { kind: 'sepia' }>): string;
+/** `vibrance`, on pixels. */
+export function vibrance(img: Pixels, fx: Extract<Effect, { kind: 'vibrance' }>): Uint8ClampedArray;