@arraypress/covers 1.0.0 → 1.1.0

package/src/effects/grade.js

@@ -0,0 +1,274 @@
+/**
+ * Colour grading, as SVG filters: `curves` (a smooth tone curve through
+ * points, per channel too), `gradientMap` (tones mapped through a
+ * gradient of any number of stops), `posterize`, `invert`, `hue` (hue,
+ * saturation and lightness), `colorBalance` (shadows, midtones and
+ * highlights pushed toward a colour), `channelMixer` and `sepia`; and
+ * `vibrance` on pixels (it weighs each pixel by how saturated it already
+ * is, which no colour matrix can).
+ *
+ * @module effects/grade
+ */
+
+import { num } from '../svg.js';
+import { mixOklab, toHex } from '../color.js';
+import { LUMA, rgb, mat } from './util.js';
+
+/** Entries in a tone table (the filter interpolates between them). */
+const TABLE = 128;
+
+/**
+ * A monotone cubic through points (Fritsch–Carlson), sampled as a table.
+ *
+ * @param {[number, number][]} points - `[input, output]`, 0–1.
+ * @param {number} [n=TABLE]
+ * @returns {number[]}
+ */
+export function curveTable(points, n = TABLE) {
+  const p = [...points].map(([x, y]) => [Number(x), Number(y)]).sort((a, b) => a[0] - b[0]);
+  if (p.length === 0) return Array.from({ length: n }, (_, i) => i / (n - 1));
+  if (p.length === 1) return Array.from({ length: n }, () => p[0][1]);
+  const k = p.length;
+  const d = [];
+  for (let i = 0; i < k - 1; i++) d.push((p[i + 1][1] - p[i][1]) / (p[i + 1][0] - p[i][0] || 1e-9));
+  const m = [d[0]];
+  for (let i = 1; i < k - 1; i++) m.push(d[i - 1] * d[i] <= 0 ? 0 : (d[i - 1] + d[i]) / 2);
+  m.push(d[k - 2]);
+  for (let i = 0; i < k - 1; i++) {
+    if (d[i] === 0) { m[i] = 0; m[i + 1] = 0; continue; }
+    const a = m[i] / d[i];
+    const b = m[i + 1] / d[i];
+    const s = a * a + b * b;
+    if (s > 9) { const t = 3 / Math.sqrt(s); m[i] = t * a * d[i]; m[i + 1] = t * b * d[i]; }
+  }
+  return Array.from({ length: n }, (_, j) => {
+    const x = j / (n - 1);
+    if (x <= p[0][0]) return clamp(p[0][1]);
+    if (x >= p[k - 1][0]) return clamp(p[k - 1][1]);
+    let i = 0;
+    while (x > p[i + 1][0]) i++;
+    const h = p[i + 1][0] - p[i][0];
+    const t = (x - p[i][0]) / h;
+    const t2 = t * t;
+    const t3 = t2 * t;
+    return clamp((2 * t3 - 3 * t2 + 1) * p[i][1] + (t3 - 2 * t2 + t) * h * m[i] + (-2 * t3 + 3 * t2) * p[i + 1][1] + (t3 - t2) * h * m[i + 1]);
+  });
+}
+
+/** @param {number} v @returns {number} */
+const clamp = (v) => Math.min(1, Math.max(0, v));
+
+/**
+ * A component transfer from three tables (R, G, B), alpha untouched.
+ *
+ * @param {number[][]} tables
+ * @returns {string}
+ */
+export const transfer = (tables) => `<feComponentTransfer>${['R', 'G', 'B'].map((ch, i) => `<feFunc${ch} type="table" tableValues="${tables[i].map((v) => num(v, 4)).join(' ')}"/>`).join('')}</feComponentTransfer>`;
+
+/**
+ * `curves`: `points` for all three channels (`[[0, 0], [0.25, 0.2],
+ * [0.75, 0.82], [1, 1]]` is an S-curve), and `red`, `green`, `blue` on
+ * top of it, each `[input, output]` pairs, 0–1.
+ *
+ * @param {import('./index.js').Effect & { kind: 'curves' }} fx
+ * @returns {string}
+ */
+export function curves(fx) {
+  const master = curveTable(fx.points ?? [[0, 0], [1, 1]]);
+  const chan = [fx.red, fx.green, fx.blue].map((pts) => (pts ? curveTable(pts) : null));
+  return transfer(chan.map((c) => (c ? master.map((v) => c[Math.round(v * (TABLE - 1))]) : master)));
+}
+
+/**
+ * `gradientMap`: luminance mapped through a gradient: `colors` (shadows
+ * first), at `stops` (0–1, even by default), mixed in `space`
+ * (`'srgb'` like Photoshop, or `'oklab'`).
+ *
+ * @param {import('./index.js').Effect & { kind: 'gradientMap' }} fx
+ * @returns {string}
+ */
+export function gradientMap(fx) {
+  const colors = (fx.colors ?? ['#120c2b', '#d6336c', '#ffe9a8']).map((c) => toHex(c));
+  const stops = fx.stops ?? colors.map((_, i) => i / Math.max(1, colors.length - 1));
+  const lum = `<feColorMatrix type="matrix" values="${mat([...LUMA, 0, 0, ...LUMA, 0, 0, ...LUMA, 0, 0, 0, 0, 0, 1, 0])}"/>`;
+  const n = 64;
+  const samples = Array.from({ length: n }, (_, j) => sampleGradient(colors, stops, j / (n - 1), fx.space ?? 'srgb'));
+  return lum + transfer([0, 1, 2].map((c) => samples.map((s) => s[c])));
+}
+
+/**
+ * A gradient's colour at `t`, as 0–1 channels.
+ *
+ * @param {string[]} colors
+ * @param {number[]} stops
+ * @param {number} t
+ * @param {'srgb' | 'oklab'} space
+ * @returns {[number, number, number]}
+ */
+export function sampleGradient(colors, stops, t, space) {
+  if (t <= stops[0]) return rgb(colors[0]);
+  for (let i = 0; i < colors.length - 1; i++) {
+    if (t <= stops[i + 1]) {
+      const k = (t - stops[i]) / (stops[i + 1] - stops[i] || 1);
+      if (space === 'oklab') return rgb(mixOklab(colors[i], colors[i + 1], k));
+      const a = rgb(colors[i]);
+      const b = rgb(colors[i + 1]);
+      return [a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k, a[2] + (b[2] - a[2]) * k];
+    }
+  }
+  return rgb(colors[colors.length - 1]);
+}
+
+/**
+ * `posterize`: `levels` tones per channel.
+ *
+ * @param {import('./index.js').Effect & { kind: 'posterize' }} fx
+ * @returns {string}
+ */
+export function posterize(fx) {
+  const n = Math.max(2, Math.round(fx.levels ?? 4));
+  const t = Array.from({ length: n }, (_, i) => num(i / (n - 1), 4)).join(' ');
+  return `<feComponentTransfer>${['R', 'G', 'B'].map((ch) => `<feFunc${ch} type="discrete" tableValues="${t}"/>`).join('')}</feComponentTransfer>`;
+}
+
+/**
+ * `invert`: a negative, `amount` of the way (default 1).
+ *
+ * @param {import('./index.js').Effect & { kind: 'invert' }} fx
+ * @returns {string}
+ */
+export function invert(fx) {
+  const a = fx.amount ?? 1;
+  return `<feComponentTransfer>${['R', 'G', 'B'].map((ch) => `<feFunc${ch} type="table" tableValues="${num(a, 4)} ${num(1 - a, 4)}"/>`).join('')}</feComponentTransfer>`;
+}
+
+/**
+ * `hue`: turn hues by `angle` degrees, `saturation` (-1 grey to 1 double)
+ * and `lightness` (-1 black to 1 white), as Photoshop's Hue/Saturation.
+ *
+ * @param {import('./index.js').Effect & { kind: 'hue' }} fx
+ * @returns {string}
+ */
+export function hue(fx) {
+  let out = '';
+  if (fx.angle) out += `<feColorMatrix type="hueRotate" values="${num(fx.angle, 3)}"/>`;
+  if (fx.saturation) out += `<feColorMatrix type="saturate" values="${num(Math.max(0, 1 + fx.saturation), 4)}"/>`;
+  const l = fx.lightness ?? 0;
+  if (l) {
+    const slope = l > 0 ? 1 - l : 1 + l;
+    const icpt = l > 0 ? l : 0;
+    out += `<feComponentTransfer>${['R', 'G', 'B'].map((ch) => `<feFunc${ch} type="linear" slope="${num(slope, 4)}" intercept="${num(icpt, 4)}"/>`).join('')}</feComponentTransfer>`;
+  }
+  return out || '<feOffset dx="0" dy="0"/>';
+}
+
+/**
+ * How much a tone (0–1) belongs to the shadows, midtones and highlights
+ * (GIMP's colour-balance weights).
+ *
+ * @param {number} v
+ * @returns {[number, number, number]}
+ */
+function zones(v) {
+  const a = 0.25;
+  const b = 0.333;
+  const s = 0.7;
+  const shadows = clamp((v - b) / -a + 0.5) * s;
+  const mids = clamp((v - b) / a + 0.5) * clamp((v + b - 1) / -a + 0.5) * s;
+  const highs = clamp((v + b - 1) / a + 0.5) * s;
+  return [shadows, mids, highs];
+}
+
+/**
+ * The tables of a colour balance: each zone's `[red, green, blue]` push
+ * (-1–1; `[0.1, 0, -0.1]` is warmer), per channel.
+ *
+ * @param {{ shadows?: number[], midtones?: number[], highlights?: number[] }} fx
+ * @returns {number[][]}
+ */
+export function balanceTables(fx) {
+  const z = [fx.shadows ?? [0, 0, 0], fx.midtones ?? [0, 0, 0], fx.highlights ?? [0, 0, 0]];
+  const n = 64;
+  return [0, 1, 2].map((c) => Array.from({ length: n }, (_, j) => {
+    const v = j / (n - 1);
+    const w = zones(v);
+    return clamp(v + 0.5 * (w[0] * (z[0][c] ?? 0) + w[1] * (z[1][c] ?? 0) + w[2] * (z[2][c] ?? 0)));
+  }));
+}
+
+/**
+ * `colorBalance`: `shadows`, `midtones` and `highlights`, each a
+ * `[red, green, blue]` push, -1–1 (Photoshop's sliders over 100).
+ *
+ * @param {import('./index.js').Effect & { kind: 'colorBalance' }} fx
+ * @returns {string}
+ */
+export const colorBalance = (fx) => transfer(balanceTables(fx));
+
+/**
+ * `channelMixer`: each output channel as a mix of the inputs, `red`,
+ * `green`, `blue` (`[r, g, b]` or `[r, g, b, constant]`); `monochrome`
+ * mixes one grey from `gray` (default Rec. 709).
+ *
+ * @param {import('./index.js').Effect & { kind: 'channelMixer' }} fx
+ * @returns {string}
+ */
+export function channelMixer(fx) {
+  const row = (/** @type {number[] | undefined} */ r, /** @type {number[]} */ d) => {
+    const v = r ?? d;
+    return [v[0] ?? 0, v[1] ?? 0, v[2] ?? 0, 0, v[3] ?? 0];
+  };
+  if (fx.monochrome) {
+    const g = row(fx.gray, LUMA);
+    return `<feColorMatrix type="matrix" values="${mat([...g, ...g, ...g, 0, 0, 0, 1, 0])}"/>`;
+  }
+  return `<feColorMatrix type="matrix" values="${mat([...row(fx.red, [1, 0, 0]), ...row(fx.green, [0, 1, 0]), ...row(fx.blue, [0, 0, 1]), 0, 0, 0, 1, 0])}"/>`;
+}
+
+/**
+ * `sepia`: the classic brown tone, `amount` of the way (default 1).
+ *
+ * @param {import('./index.js').Effect & { kind: 'sepia' }} fx
+ * @returns {string}
+ */
+export function sepia(fx) {
+  const a = Math.min(1, Math.max(0, fx.amount ?? 1));
+  const s = [0.393, 0.769, 0.189, 0.349, 0.686, 0.168, 0.272, 0.534, 0.131];
+  const id = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+  const m = s.map((v, i) => id[i] + (v - id[i]) * a);
+  return `<feColorMatrix type="matrix" values="${mat([m[0], m[1], m[2], 0, 0, m[3], m[4], m[5], 0, 0, m[6], m[7], m[8], 0, 0, 0, 0, 0, 1, 0])}"/>`;
+}
+
+/**
+ * `vibrance` on pixels: saturation raised most where it's lowest (muted
+ * colours come up, saturated ones and skin hold), `amount` -1–1, then
+ * `saturation` evenly, as Lightroom's pair.
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'vibrance' }} fx
+ * @returns {Uint8ClampedArray}
+ */
+export function vibrance(img, fx) {
+  const d = img.data;
+  const v = fx.amount ?? 0.5;
+  const s = 1 + (fx.saturation ?? 0);
+  const out = new Uint8ClampedArray(d.length);
+  for (let i = 0; i < d.length; i += 4) {
+    const r = d[i];
+    const g = d[i + 1];
+    const b = d[i + 2];
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const sat = (max - min) / 255;
+    // Skin (red above green above blue) is held back.
+    const skin = r > g && g > b ? 0.5 : 1;
+    const k = s * (1 + v * (1 - sat) * (v > 0 ? skin : 1));
+    const l = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    out[i] = l + (r - l) * k;
+    out[i + 1] = l + (g - l) * k;
+    out[i + 2] = l + (b - l) * k;
+    out[i + 3] = d[i + 3];
+  }
+  return out;
+}

package/src/effects/halftone.d.ts

@@ -0,0 +1,8 @@
+// The riso halftone.
+import type { Effect } from './index.js';
+import type { RenderContext } from '../render/context.js';
+
+/** The `halftone` effect's filter primitives. */
+export function halftone(fx: Extract<Effect, { kind: 'halftone' }>, ctx: RenderContext): string;
+/** Halftone screen shapes. */
+export const HALFTONE_SHAPES: readonly ('dot' | 'line' | 'square' | 'diamond' | 'cross')[];

package/src/effects/halftone.js

@@ -0,0 +1,95 @@
+/**
+ * The riso halftone: darkness against a rotated dot screen, thresholded
+ * softly, flooded with the ink.
+ *
+ * @module effects/halftone
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { encodePng, pngUri } from '../png.js';
+import { deflateSync } from '../platform/index.js';
+import { LUMA, mat, flood } from './util.js';
+
+/**
+ * A riso halftone in one ink: darkness against a rotated dot screen,
+ * thresholded softly, flooded with the ink and clipped to the source.
+ * The screen is one canvas-sized image (no tile seams at any angle).
+ *
+ * @param {any} fx - `{ ink, cell, angle, contrast, lift, softness, shape }`.
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function halftone(fx, ctx) {
+  const cell = len(fx.cell, ctx.canvas, '1.3vmin');
+  const angle = fx.angle ?? 15;
+  const c = fx.contrast ?? 1.15;
+  const lift = fx.lift ?? -0.05;
+  const soft = fx.softness ?? 9;
+  const { width: w, height: h } = ctx;
+  const href = screenHref(w, h, cell, angle, fx.shape ?? 'dot');
+  const k = (/** @type {number} */ v) => -c * v;
+  return `<feColorMatrix in="SourceGraphic" type="matrix" values="${mat([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, k(LUMA[0]), k(LUMA[1]), k(LUMA[2]), 0, c + lift])}" result="d"/>`
+    + `<feImage${attrs({ href, x: 0, y: 0, width: w, height: h, preserveAspectRatio: 'none', result: 'scr' })}/>`
+    + `<feColorMatrix in="scr" type="matrix" values="${mat([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...LUMA, 0, 0])}" result="t"/>`
+    + '<feComposite in="d" in2="t" operator="arithmetic" k2="1" k3="-1" k4="0.5"/>'
+    + `<feComponentTransfer><feFuncA type="linear" slope="${num(soft, 3)}" intercept="${num(-(soft - 1) / 2, 3)}"/></feComponentTransfer>`
+    + `<feColorMatrix type="matrix" values="${flood(fx.ink ?? '#0078bf')}"/><feComposite in2="SourceAlpha" operator="in"/>`;
+}
+
+/**
+ * Screen shapes: distance from a cell's centre (-0.5–0.5 each way) to
+ * 0–1, the order in which a cell fills with ink.
+ *
+ * @type {Record<string, (x: number, y: number) => number>}
+ */
+const SHAPES = {
+  dot: (x, y) => Math.min(1, Math.hypot(x, y) / 0.5),
+  line: (x, y) => Math.abs(y) / 0.5,
+  square: (x, y) => Math.max(Math.abs(x), Math.abs(y)) / 0.5,
+  diamond: (x, y) => (Math.abs(x) + Math.abs(y)) / 1,
+  cross: (x, y) => Math.min(Math.abs(x), Math.abs(y)) / 0.5,
+};
+
+/** Halftone screen shapes. */
+export const HALFTONE_SHAPES = Object.freeze(Object.keys(SHAPES));
+
+/**
+ * The halftone screen: dots as radial ramps (black at the centre to #efefef
+ * at the edge) on a grid turned to `angle`, over the whole canvas; or
+ * lines, squares, diamonds or crosses (`shape`). A PNG where the platform
+ * deflates synchronously (Node, whose librsvg can't load an SVG inside
+ * feImage); an SVG data URI elsewhere (browsers draw it).
+ *
+ * @param {number} w @param {number} h @param {number} cell @param {number} angle
+ * @param {string} [shape='dot']
+ * @returns {string}
+ */
+function screenHref(w, h, cell, angle, shape = 'dot') {
+  if (!Object.hasOwn(SHAPES, shape)) throw new TypeError(`Unknown halftone shape "${shape}" (${HALFTONE_SHAPES.join(', ')})`);
+  if (shape !== 'dot' || deflateSync(new Uint8Array(1))) {
+    const f = SHAPES[shape];
+    // Enough pixels for ~8 per cell, at most ~1.6 MP (the ramps upscale smoothly).
+    const s = Math.min(Math.max(1, 8 / cell), Math.sqrt(1.6e6 / (w * h)));
+    const pw = Math.max(1, Math.round(w * s));
+    const ph = Math.max(1, Math.round(h * s));
+    const px = new Uint8Array(pw * ph);
+    const a = (-angle * Math.PI) / 180;
+    const cos = Math.cos(a);
+    const sin = Math.sin(a);
+    const c = cell * s;
+    for (let y = 0; y < ph; y++) {
+      for (let x = 0; x < pw; x++) {
+        const u = (x + 0.5) * cos - (y + 0.5) * sin;
+        const v = (x + 0.5) * sin + (y + 0.5) * cos;
+        const fx = ((u % c) + c) % c - c / 2;
+        const fy = ((v % c) + c) % c - c / 2;
+        const d = shape === 'dot' ? Math.min(1, Math.hypot(fx, fy) / (c / 2)) : Math.min(1, f(fx / c, fy / c));
+        px[y * pw + x] = Math.round(239 * d);
+      }
+    }
+    return pngUri(encodePng(px, pw, ph, 1));
+  }
+  const screen = `<svg xmlns='http://www.w3.org/2000/svg' width='${num(w)}' height='${num(h)}' viewBox='0 0 ${num(w)} ${num(h)}'><defs><radialGradient id='g'><stop offset='0' stop-color='#000'/><stop offset='1' stop-color='#efefef'/></radialGradient><pattern id='p' width='${num(cell, 3)}' height='${num(cell, 3)}' patternUnits='userSpaceOnUse' patternTransform='rotate(${num(angle)})'><rect width='${num(cell, 3)}' height='${num(cell, 3)}' fill='#efefef'/><circle cx='${num(cell / 2, 3)}' cy='${num(cell / 2, 3)}' r='${num(cell / 2, 3)}' fill='url(#g)'/></pattern></defs><rect x='${num(-w / 4)}' y='${num(-h / 4)}' width='${num(w * 1.5)}' height='${num(h * 1.5)}' fill='url(#p)'/></svg>`;
+  return `data:image/svg+xml,${encodeURIComponent(screen)}`;
+}

package/src/effects/index.d.ts

@@ -0,0 +1,125 @@
+// Effects: filters, pixel effects and copies any layer takes.
+import type { Color, Length, Layer } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+export { transformAttr } from './transform.js';
+export type { LayerTransform } from './transform.js';
+export { paint } from './paint.js';
+export type { Paint } from './paint.js';
+
+/** A point as fractions of the canvas, `[x, y]` or `{ x, y }`. */
+export type Point = [number, number] | { x: number; y: number };
+
+/** Where an effect applies (see {@link EffectMask}). */
+export type { EffectMask } from './mask.js';
+import type { EffectMask } from './mask.js';
+import type { LookName } from './looks.js';
+
+/** A seed: a number, or any string (hashed). */
+type Seed = number | string;
+
+/** An effect (see the README's Effects table for each kind). */
+export type Effect = (
+  | { kind: 'blur'; radius?: Length; x?: Length; y?: Length; edge?: 'duplicate' }
+  | { kind: 'motion'; angle?: number; length?: Length; spread?: Length }
+  | { kind: 'shadow' | 'glow'; x?: Length; y?: Length; blur?: Length; color?: Color; opacity?: number; spread?: Length }
+  | { kind: 'border'; width?: Length; color?: Color; line?: boolean | Color; lineWidth?: Length; shape?: 'die' | 'circle'; cx?: Length; cy?: Length }
+  | { kind: 'wear'; rough?: Length; uneven?: number; specks?: number; seed?: number }
+  | { kind: 'rough' | 'warp'; scale?: Length; frequency?: number | [number, number]; octaves?: number; seed?: number }
+  | { kind: 'xerox'; rough?: Length; dropout?: number; seed?: number }
+  | { kind: 'photocopy'; ink?: Color; contrast?: number; lift?: number; noise?: number; frequency?: number; seed?: number }
+  | { kind: 'duotone'; colors?: Color[]; contrast?: number }
+  | { kind: 'grayscale' | 'levels'; slope?: number; intercept?: number; contrast?: number; brightness?: number; black?: number; white?: number; gamma?: number; output?: [number, number] }
+  | { kind: 'saturate'; amount?: number }
+  | { kind: 'matrix'; values: string | number[] }
+  | { kind: 'grit'; amount?: number; frequency?: number; seed?: number }
+  | { kind: 'halftone'; ink?: Color; cell?: Length; angle?: number; contrast?: number; lift?: number; softness?: number; shape?: 'dot' | 'line' | 'square' | 'diamond' | 'cross' }
+  | { kind: 'dither'; ink?: Color; paper?: Color; cell?: Length; contrast?: number; brightness?: number; pixelate?: boolean; weights?: [number, number, number]; matrix?: 'bayer4' | 'bayer8' }
+  | { kind: 'threshold'; level?: number; ink?: Color; paper?: Color | 'none' }
+  | { kind: 'filter'; markup: string }
+  | { kind: 'extrude'; depth?: Length; angle?: number; offset?: [Length, Length]; steps?: number; color?: Color; to?: Color }
+  // Blurs (pixels).
+  | { kind: 'zoom'; center?: Point; amount?: number }
+  | { kind: 'spin'; center?: Point; angle?: number }
+  | { kind: 'tilt'; center?: Point; angle?: number; width?: Length; falloff?: Length; radius?: Length; saturate?: number }
+  | { kind: 'lens'; radius?: Length; blades?: number; rotation?: number; highlights?: number; threshold?: number }
+  // Distortions (pixels; mirror is copies).
+  | { kind: 'wave'; amplitude?: Length; wavelength?: Length; angle?: number; phase?: number; shape?: 'sine' | 'triangle' | 'square' }
+  | { kind: 'ripple'; center?: Point; amplitude?: Length; wavelength?: Length; phase?: number; radius?: Length }
+  | { kind: 'twirl'; center?: Point; angle?: number; radius?: Length }
+  | { kind: 'bulge' | 'pinch'; center?: Point; amount?: number; radius?: Length }
+  | { kind: 'fisheye'; center?: Point; amount?: number }
+  | { kind: 'glass'; texture?: 'frosted' | 'reeded' | 'pebbled'; size?: Length; amount?: Length; angle?: number; shade?: number; seed?: Seed }
+  | { kind: 'displace'; amount?: Length; map?: { layers: Layer[] }; mode?: 'gradient' | 'channels'; size?: Length; octaves?: number; seed?: Seed }
+  | { kind: 'kaleidoscope'; segments?: number; center?: Point; angle?: number; scale?: number }
+  | { kind: 'mirror'; keep?: 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'; at?: number | Point }
+  | { kind: 'stretch'; at?: number; direction?: 'down' | 'up' | 'left' | 'right'; length?: number; fade?: number }
+  | { kind: 'sort'; direction?: 'horizontal' | 'vertical'; threshold?: [number, number]; by?: 'luma' | 'hue' | 'saturation'; reverse?: boolean; length?: number; seed?: Seed }
+  // Colour (filters; vibrance on pixels).
+  | { kind: 'curves'; points?: [number, number][]; red?: [number, number][]; green?: [number, number][]; blue?: [number, number][] }
+  | { kind: 'gradientMap'; colors?: Color[]; stops?: number[]; space?: 'srgb' | 'oklab' }
+  | { kind: 'posterize'; levels?: number }
+  | { kind: 'invert'; amount?: number }
+  | { kind: 'hue'; angle?: number; saturation?: number; lightness?: number }
+  | { kind: 'vibrance'; amount?: number; saturation?: number }
+  | { kind: 'colorBalance'; shadows?: [number, number, number]; midtones?: [number, number, number]; highlights?: [number, number, number] }
+  | { kind: 'channelMixer'; red?: number[]; green?: number[]; blue?: number[]; monochrome?: boolean; gray?: number[] }
+  | { kind: 'sepia'; amount?: number }
+  | { kind: 'look'; name?: LookName; amount?: number }
+  // Light.
+  | { kind: 'bloom'; threshold?: number; radius?: Length; intensity?: number; color?: Color }
+  | { kind: 'halation'; threshold?: number; radius?: Length; intensity?: number; color?: Color }
+  | { kind: 'vignette'; shape?: 'ellipse' | 'circle' | 'rect'; size?: number; softness?: number; amount?: number; color?: Color; center?: Point }
+  | { kind: 'lightLeak'; edge?: 'left' | 'right' | 'top' | 'bottom'; colors?: Color[]; intensity?: number; seed?: Seed }
+  | { kind: 'lensFlare'; at?: Point; size?: Length; intensity?: number; color?: Color; ghosts?: number; streak?: boolean | number; seed?: Seed }
+  | { kind: 'rays'; center?: Point; threshold?: number; length?: number; intensity?: number; color?: Color }
+  // Texture and print.
+  | { kind: 'grain'; amount?: number; size?: Length; color?: boolean; seed?: number }
+  | { kind: 'dust'; amount?: number; scratches?: number; color?: 'light' | 'dark' | 'mixed'; seed?: Seed }
+  | { kind: 'paper'; texture?: 'paper' | 'canvas'; scale?: Length; amount?: number; angle?: number; seed?: number }
+  | { kind: 'scanlines'; spacing?: Length; thickness?: number; amount?: number }
+  | { kind: 'crt'; mask?: 'aperture' | 'shadow'; size?: Length; amount?: number; scanlines?: number; curvature?: number }
+  | { kind: 'vhs'; shift?: Length; bleed?: Length; jitter?: Length; tracking?: number; noise?: number; seed?: Seed }
+  | { kind: 'jpeg'; quality?: number; block?: Length; passes?: number; subsample?: boolean }
+  | { kind: 'newsprint'; cell?: Length; angles?: [number, number, number, number]; paper?: Color; gain?: number; gcr?: number }
+  // Digital.
+  | { kind: 'chromatic'; amount?: Length; angle?: number; mode?: 'directional' | 'radial'; center?: Point }
+  | { kind: 'rgbSplit'; amount?: Length; angle?: number }
+  | { kind: 'glitch'; amount?: number; shift?: Length; slices?: number; blocks?: number; seed?: Seed }
+  | { kind: 'pixelate' | 'mosaic'; size?: Length; shape?: 'square' | 'hex' }
+  | { kind: 'ascii'; cell?: Length; ramp?: string; color?: 'source' | Color; background?: Color | 'none'; invert?: boolean; contrast?: number }
+  | { kind: 'emboss'; angle?: number; amount?: number; radius?: Length; color?: boolean }
+  | { kind: 'edges'; radius?: Length; amount?: number; style?: 'ink' | 'glow'; color?: Color; mono?: boolean }
+  | { kind: 'sketch'; radius?: Length; darkness?: number; color?: boolean }
+  | { kind: 'sharpen'; amount?: number; radius?: Length }
+) & {
+  /** Where the effect applies: a gradient or layers (white: full). */
+  mask?: EffectMask;
+  /** Where filter primitives do their arithmetic. Default `'sRGB'`; `'linearRGB'` is the SVG default browsers' own filters use. */
+  colorSpace?: 'sRGB' | 'linearRGB';
+  /** Filter region padding, a fraction of the canvas on each side. */
+  pad?: number;
+};
+
+/** An effect's kind. */
+export type EffectKind = Effect['kind'];
+
+/** Every effect kind. */
+export const EFFECTS: readonly EffectKind[];
+/** Every kind's options, with descriptions (validation, the schema, docs). */
+export { EFFECT_OPTIONS, EFFECT_COMMON } from './options.js';
+export { checkMask, RESOLVED, maskImage } from './mask.js';
+
+/** Effects always drawn without an SVG filter (on pixels, or as copies). */
+export const RASTER_EFFECTS: readonly EffectKind[];
+/** Whether an effect is computed on pixels (`chromatic` only radial; `motion` only when rasterising). */
+export function isPixel(fx: Effect | EffectKind | undefined, ctx?: { raster?: boolean }): boolean;
+/** Whether an effect needs something that draws pixels (sharp, a canvas). */
+export function needsPixels(fx: Effect | EffectKind | undefined): boolean;
+/** Whether an effect is drawn without an SVG filter (pixels, copies, a round `border`). */
+export function isRaster(fx: Effect | EffectKind | undefined, ctx?: { raster?: boolean }): boolean;
+/** Such an effect's markup, with its mask; undefined where nothing can draw pixels (its filter is used). */
+export function rasterEffect(fx: Effect, m: Markup, ctx: RenderContext, i: number): Promise<Markup | undefined>;
+export { expandDropShadows } from './drop-shadow.js';
+
+/** Wrap markup in a layer's filter effects, in order (innermost first); `content`: the box the layer paints; `prior`: the defs so far. */
+export function applyEffects(body: string, list: Effect | Effect[], ctx: RenderContext, start?: number, content?: { x: number; y: number; width: number; height: number }, prior?: string): { defs: string; body: string };