@arraypress/covers 1.0.0 → 1.1.0

package/src/effects/optics.d.ts

@@ -0,0 +1,10 @@
+// Light on the lens and the film.
+import type { Effect } from './index.js';
+import type { RenderContext } from '../render/context.js';
+
+/** The `vignette` effect's filter primitives. */
+export function vignette(fx: Extract<Effect, { kind: 'vignette' }>, ctx: RenderContext): string;
+/** The `lightLeak` effect's filter primitives. */
+export function lightLeak(fx: Extract<Effect, { kind: 'lightLeak' }>, ctx: RenderContext): string;
+/** The `lensFlare` effect's filter primitives. */
+export function lensFlare(fx: Extract<Effect, { kind: 'lensFlare' }>, ctx: RenderContext): string;

package/src/effects/optics.js

@@ -0,0 +1,213 @@
+/**
+ * Light on the lens and the film, as SVG filters: `vignette` (edges
+ * darkened, or lightened, by shape, size, softness and colour),
+ * `lightLeak` (warm light fogging the film from an edge) and `lensFlare`
+ * (a soft glow at the light, ghosts along the line through the centre,
+ * an optional anamorphic streak).
+ *
+ * Their light is drawn from small greyscale images (a radial falloff
+ * computed here) that the filter scales and tints, so they stay smooth at
+ * any size and cost no more at 3000 px than at 300.
+ *
+ * @module effects/optics
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { encodePng, pngUri } from '../png.js';
+import { createRng } from '../rng.js';
+import { rgb, mat } from './util.js';
+import { fraction, smoothstep } from './buffer.js';
+
+/** @type {Map<string, string>} */
+const SPRITES = new Map();
+
+/**
+ * A greyscale sprite from a radial profile, cached: `profile(r)` for r
+ * from 0 (centre) to 1 (edge of the square).
+ *
+ * @param {string} key
+ * @param {(r: number) => number} profile
+ * @param {number} [size=96]
+ * @param {number} [aspect=1] - Width over height of the sprite's pixels.
+ * @returns {string} A data URI.
+ */
+function sprite(key, profile, size = 96, aspect = 1) {
+  const id = `${key}:${size}:${aspect}`;
+  const hit = SPRITES.get(id);
+  if (hit) return hit;
+  const w = Math.round(size * Math.max(1, aspect));
+  const h = Math.round(size / Math.min(1, aspect));
+  const px = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const r = Math.hypot(((x + 0.5) / w) * 2 - 1, ((y + 0.5) / h) * 2 - 1);
+      px[y * w + x] = Math.round(255 * Math.min(1, Math.max(0, profile(r))));
+    }
+  }
+  const uri = pngUri(encodePng(px, w, h, 1));
+  SPRITES.set(id, uri);
+  return uri;
+}
+
+/** The sprites flares and leaks are drawn from. */
+const GLOW = () => sprite('glow', (r) => Math.exp(-6 * r * r) * (1 - smoothstep(0.85, 1, r)));
+const GHOST = () => sprite('ghost', (r) => (1 - smoothstep(0.78, 0.96, r)) * (0.55 + 0.45 * smoothstep(0.3, 0.9, r)));
+const RING = () => sprite('ring', (r) => Math.exp(-(((r - 0.86) / 0.05) ** 2)));
+const SOFT = () => sprite('soft', (r) => 1 - smoothstep(0, 1, r));
+const STREAK = () => sprite('streak', (r) => Math.exp(-5 * r * r) * (1 - smoothstep(0.9, 1, r)), 64, 8);
+
+/**
+ * One sprite placed and tinted: an feImage over a box, its grey becoming
+ * the alpha of a colour (light, for adding up).
+ *
+ * @param {string} href
+ * @param {{ x: number, y: number, width: number, height: number }} box
+ * @param {[number, number, number]} c - 0–1 channels.
+ * @param {number} o - Opacity.
+ * @param {string} result
+ * @returns {string}
+ */
+function light(href, box, c, o, result) {
+  return `<feImage${attrs({ href, ...box, preserveAspectRatio: 'none' })}/>`
+    + `<feColorMatrix type="matrix" values="${mat([0, 0, 0, 0, c[0], 0, 0, 0, 0, c[1], 0, 0, 0, 0, c[2], o, 0, 0, 0, 0])}" color-interpolation-filters="sRGB" result="${result}"/>`;
+}
+
+/**
+ * Lights added together, screened over the layer and kept to its shape.
+ *
+ * @param {string[]} names - Their results.
+ * @returns {string}
+ */
+function screenOn(names) {
+  let out = '';
+  let acc = names[0];
+  for (let i = 1; i < names.length; i++) {
+    out += `<feComposite in="${acc}" in2="${names[i]}" operator="arithmetic" k2="1" k3="1" result="la${i}"/>`;
+    acc = `la${i}`;
+  }
+  return `${out}<feBlend in="${acc}" in2="SourceGraphic" mode="screen"/><feComposite in2="SourceAlpha" operator="in"/>`;
+}
+
+/**
+ * `vignette`: `shape` (`'ellipse'` following the canvas, `'circle'`, or
+ * `'rect'`, a soft rounded rectangle), `size` (where it starts, 0–1 of
+ * the way to the corners), `softness` (0–1), `amount` (0–1) and `color`
+ * (black; white for a faded print), about `center`.
+ *
+ * @param {import('./index.js').Effect & { kind: 'vignette' }} fx
+ * @param {import('../render/context.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function vignette(fx, ctx) {
+  const { width: W, height: H } = ctx;
+  const shape = fx.shape ?? 'ellipse';
+  if (!['ellipse', 'circle', 'rect'].includes(shape)) throw new TypeError(`Unknown vignette shape "${shape}" (ellipse, circle, rect)`);
+  const size = fx.size ?? 0.55;
+  const soft = Math.max(0.02, fx.softness ?? 0.6);
+  const [cx, cy] = fraction(/** @type {any} */ (fx.center), [0.5, 0.5]);
+  // The image covers the canvas; distance 1 is a corner (from the centre).
+  const n = 128;
+  const ax = shape === 'circle' ? Math.max(W, H) / Math.hypot(W, H) * Math.SQRT2 : 1;
+  const px = new Uint8Array(n * n);
+  for (let j = 0; j < n; j++) {
+    for (let i = 0; i < n; i++) {
+      let u = ((i + 0.5) / n - cx) * 2;
+      let v = ((j + 0.5) / n - cy) * 2;
+      if (shape === 'circle') { u *= (W / Math.max(W, H)) * ax; v *= (H / Math.max(W, H)) * ax; }
+      const d = shape === 'rect' ? (Math.abs(u) ** 6 + Math.abs(v) ** 6) ** (1 / 6) : Math.hypot(u, v) / Math.SQRT2;
+      px[j * n + i] = Math.round(255 * smoothstep(size, size + soft * (1.15 - size) + 0.05, d));
+    }
+  }
+  const [r, g, b] = rgb(fx.color ?? '#000000');
+  const a = fx.amount ?? 0.6;
+  return `<feImage${attrs({ href: pngUri(encodePng(px, n, n, 1)), x: 0, y: 0, width: W, height: H, preserveAspectRatio: 'none' })}/>`
+    + `<feColorMatrix type="matrix" values="${mat([0, 0, 0, 0, r, 0, 0, 0, 0, g, 0, 0, 0, 0, b, a, 0, 0, 0, 0])}" color-interpolation-filters="sRGB" result="vg"/>`
+    + '<feComposite in="vg" in2="SourceGraphic" operator="atop"/>';
+}
+
+/**
+ * `lightLeak`: warm light fogging the film from an `edge` (`'left'`,
+ * `'right'`, `'top'`, `'bottom'`, or seeded), a few soft blobs in
+ * `colors`, screened on at `intensity`.
+ *
+ * @param {import('./index.js').Effect & { kind: 'lightLeak' }} fx
+ * @param {import('../render/context.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function lightLeak(fx, ctx) {
+  const { width: W, height: H } = ctx;
+  const rng = createRng(`leak:${fx.seed ?? ctx.rng.int(1, 9999)}`);
+  const edge = fx.edge ?? rng.pick(['left', 'right', 'top', 'bottom']);
+  if (!['left', 'right', 'top', 'bottom'].includes(edge)) throw new TypeError(`Unknown lightLeak edge "${edge}" (left, right, top, bottom)`);
+  const colors = (fx.colors ?? ['#ff4d1a', '#ff9a2e', '#ffd36b', '#ff2a5c']).map(rgb);
+  const k = fx.intensity ?? 0.85;
+  const across = edge === 'left' || edge === 'right';
+  const long = across ? H : W;
+  const short = across ? W : H;
+  const count = 3 + rng.int(0, 2);
+  let out = '';
+  const names = [];
+  for (let i = 0; i < count; i++) {
+    const along = rng.range(-0.1, 1.1) * long;
+    const depth = rng.range(-0.18, 0.12) * short;
+    const rl = rng.range(0.35, 0.75) * long;
+    const rs = rng.range(0.25, 0.55) * short * (i === 0 ? 1.4 : 1);
+    const x = across ? (edge === 'left' ? depth : W - depth) : along;
+    const y = across ? along : (edge === 'top' ? depth : H - depth);
+    const box = across ? { x: x - rs, y: y - rl, width: 2 * rs, height: 2 * rl } : { x: x - rl, y: y - rs, width: 2 * rl, height: 2 * rs };
+    out += light(SOFT(), box, colors[i % colors.length], k * rng.range(0.55, 1), `lk${i}`);
+    names.push(`lk${i}`);
+  }
+  // The hot core at the very edge.
+  const core = across ? { x: (edge === 'left' ? 0 : W) - short * 0.12, y: rng.range(0.1, 0.6) * H, width: short * 0.24, height: H * 0.5 } : { x: rng.range(0.1, 0.6) * W, y: (edge === 'top' ? 0 : H) - short * 0.12, width: W * 0.5, height: short * 0.24 };
+  out += light(GLOW(), core, [1, 0.85, 0.62], k * 0.55, 'lkc');
+  names.push('lkc');
+  return out + screenOn(names);
+}
+
+/**
+ * `lensFlare`: a light at `at` (fractions), its glow (`size`), a faint
+ * halo ring, ghosts along the line through the centre (seeded sizes and
+ * tints), an anamorphic `streak` when asked, all at `intensity` and
+ * tinted toward `color`.
+ *
+ * @param {import('./index.js').Effect & { kind: 'lensFlare' }} fx
+ * @param {import('../render/context.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function lensFlare(fx, ctx) {
+  const { width: W, height: H } = ctx;
+  const rng = createRng(`flare:${fx.seed ?? ctx.rng.int(1, 9999)}`);
+  const [fx0, fy0] = fraction(/** @type {any} */ (fx.at), [0.78, 0.22]);
+  const sx = fx0 * W;
+  const sy = fy0 * H;
+  const size = len(fx.size, ctx.canvas, '22vmin');
+  const k = fx.intensity ?? 0.8;
+  const tint = rgb(fx.color ?? '#ffd9a8');
+  /** @param {number} r @returns {[number, number, number]} A tint nudged toward a hue. */
+  const nudge = (r) => /** @type {[number, number, number]} */ (tint.map((v, i) => Math.min(1, v * (0.7 + 0.6 * [r, 1 - r, 0.5 + r / 2][i]))));
+  const box = (/** @type {number} */ x, /** @type {number} */ y, /** @type {number} */ r) => ({ x: x - r, y: y - r, width: 2 * r, height: 2 * r });
+  let out = light(GLOW(), box(sx, sy, size), tint, k, 'f0');
+  const names = ['f0'];
+  out += light(GLOW(), box(sx, sy, size * 0.22), [1, 1, 1], k, 'f1');
+  names.push('f1');
+  out += light(RING(), box(sx, sy, size * 1.6), nudge(0.7), k * 0.12, 'f2');
+  names.push('f2');
+  // Ghosts: along the line from the light through the centre and beyond.
+  const dx = W / 2 - sx;
+  const dy = H / 2 - sy;
+  const ghosts = fx.ghosts ?? 6;
+  for (let i = 0; i < ghosts; i++) {
+    const t = [0.35, 0.62, 0.9, 1.25, 1.55, 1.9, 2.2, 0.15][i % 8] + rng.range(-0.05, 0.05);
+    const r = size * rng.range(0.07, 0.32);
+    out += light(GHOST(), box(sx + dx * t, sy + dy * t, r), nudge(rng.next()), k * rng.range(0.05, 0.16), `g${i}`);
+    names.push(`g${i}`);
+  }
+  if (fx.streak) {
+    const s = typeof fx.streak === 'number' ? fx.streak : 1;
+    out += light(STREAK(), { x: sx - W * 0.7 * s, y: sy - size * 0.06, width: W * 1.4 * s, height: size * 0.12 }, [0.75, 0.85, 1], k * 0.7, 'fs');
+    names.push('fs');
+  }
+  return out + screenOn(names);
+}

package/src/effects/options.d.ts

@@ -0,0 +1,6 @@
+// Every effect kind's options, with descriptions.
+
+/** Options every effect takes. */
+export const EFFECT_COMMON: Readonly<Record<string, string>>;
+/** Each kind's options: name → description. */
+export const EFFECT_OPTIONS: Readonly<Record<string, Readonly<Record<string, string>>>>;

package/src/effects/options.js

@@ -0,0 +1,106 @@
+/**
+ * Every effect kind's options, with one-line descriptions. `defineRecipe`
+ * rejects kinds and options not listed here, `scripts/schema.mjs` builds
+ * the JSON Schema's autocomplete from it, and the README's table follows
+ * it. Add an option to an effect, add it here.
+ *
+ * @module effects/options
+ */
+
+/** Options every effect takes. @type {Record<string, string>} */
+export const EFFECT_COMMON = {
+  kind: 'The effect.',
+  mask: '{ gradient: linear | radial | band, from, to, center, angle, aspect, invert, ease } or { layers, invert }: where the effect applies.',
+  colorSpace: 'sRGB (default) | linearRGB: where filter primitives do their arithmetic.',
+  pad: 'Filter region padding, a fraction of the canvas.',
+};
+
+const BLUR_CENTRE = 'Centre, [x, y] fractions. Default [0.5, 0.5].';
+
+/** @type {Record<string, Record<string, string>>} */
+export const EFFECT_OPTIONS = {
+  // 1.1's first set.
+  blur: { radius: 'Length.', x: 'Length (an axis-aligned blur).', y: 'Length.', edge: 'duplicate: hold the edge.' },
+  motion: { angle: 'Degrees.', length: 'Length: the blur along the angle (a standard deviation).', spread: 'Length across.' },
+  shadow: { x: 'Length.', y: 'Length.', blur: 'Length.', color: 'Colour.', opacity: '0–1.', spread: 'Length.' },
+  glow: { x: 'Length.', y: 'Length.', blur: 'Length.', color: 'Colour.', opacity: '0–1.', spread: 'Length.' },
+  border: { width: 'Length.', color: 'Colour.', line: 'true or a colour: the cut line.', lineWidth: 'Length.', shape: 'die | circle', cx: 'Length.', cy: 'Length.' },
+  wear: { rough: 'Length.', uneven: '0–1.', specks: '0–1.', seed: 'Number.' },
+  rough: { scale: 'Length.', frequency: 'Number or [x, y].', octaves: 'Number.', seed: 'Number.' },
+  warp: { scale: 'Length.', frequency: 'Number or [x, y].', octaves: 'Number.', seed: 'Number.' },
+  xerox: { rough: 'Length.', dropout: '0–1.', seed: 'Number.' },
+  photocopy: { ink: 'Colour.', contrast: 'Number.', lift: 'Number.', noise: '0–1.', frequency: 'Number.', seed: 'Number.' },
+  duotone: { colors: 'Two or more, shadows first.', contrast: 'Number.' },
+  grayscale: { slope: 'Number.', intercept: 'Number.', contrast: 'Number.', brightness: 'Number.', black: 'Input black point, 0–1.', white: 'Input white point, 0–1.', gamma: 'Midtones (>1 lighter).', output: '[lo, hi] output range, 0–1.' },
+  levels: { slope: 'Number.', intercept: 'Number.', contrast: 'Number.', brightness: 'Number.', black: 'Input black point, 0–1.', white: 'Input white point, 0–1.', gamma: 'Midtones (>1 lighter).', output: '[lo, hi] output range, 0–1.' },
+  saturate: { amount: 'Number (1 unchanged).' },
+  matrix: { values: '20 numbers.' },
+  grit: { amount: '0–1.', frequency: 'Number.', seed: 'Number.' },
+  halftone: { ink: 'Colour.', cell: 'Length.', angle: 'Degrees.', contrast: 'Number.', lift: 'Number.', softness: 'Number.', shape: 'dot (default) | line | square | diamond | cross' },
+  dither: { ink: 'Colour.', paper: 'Colour.', cell: 'Length.', contrast: 'Number.', brightness: 'Number.', pixelate: 'Boolean.', weights: '[r, g, b].', matrix: 'bayer4 | bayer8' },
+  threshold: { level: '0–1.', ink: 'Colour.', paper: 'Colour or none.' },
+  filter: { markup: 'Raw filter primitives.' },
+  extrude: { depth: 'Length.', angle: 'Degrees.', offset: '[x, y] lengths.', steps: 'Number.', color: 'Colour.', to: 'Colour.' },
+
+  // Blurs.
+  zoom: { center: BLUR_CENTRE, amount: '0–0.95: how much of the way to the centre each point is smeared. Default 0.2.' },
+  spin: { center: BLUR_CENTRE, angle: 'Degrees of rotation. Default 12.' },
+  tilt: { center: 'A point on the sharp line, [x, y] fractions.', angle: 'Degrees (0: a horizontal band).', width: 'Length: half the sharp band. Default "8vmin".', falloff: 'Length over which the blur grows. Default "22vmin".', radius: 'Length: the strongest blur. Default "1.4vmin".', saturate: 'Number (the miniature look: 1.2).' },
+  lens: { radius: 'Length: the aperture. Default "1.2vmin".', blades: '0 (round) or 3–12 sides.', rotation: 'Degrees.', highlights: 'Boost of the bright parts (bokeh). Default 1.', threshold: '0–1: what counts as a highlight. Default 0.75.' },
+
+  // Distortions.
+  wave: { amplitude: 'Length.', wavelength: 'Length.', angle: 'Degrees the wave travels.', phase: '0–1 of a period.', shape: 'sine | triangle | square' },
+  ripple: { center: BLUR_CENTRE, amplitude: 'Length.', wavelength: 'Length.', phase: '0–1.', radius: 'Length it fades out by.' },
+  twirl: { center: BLUR_CENTRE, angle: 'Degrees at the centre. Default 180.', radius: 'Length.' },
+  bulge: { center: BLUR_CENTRE, amount: '0–1.', radius: 'Length.' },
+  pinch: { center: BLUR_CENTRE, amount: '0–1.', radius: 'Length.' },
+  fisheye: { center: BLUR_CENTRE, amount: '0–1. Default 0.6.' },
+  glass: { texture: 'frosted | reeded | pebbled', size: 'Length: grain, rib or lump.', amount: 'Frosted, pebbled: a length; reeded: 0–1.', angle: 'Reeded: rib angle, degrees.', shade: 'Reeded: rib shading, 0–1.', seed: 'Number or string.' },
+  displace: { amount: 'Length.', map: '{ layers }: displace by their luminance (default seeded noise).', mode: 'gradient (default) | channels', size: 'Noise: length.', octaves: 'Noise detail.', seed: 'Number or string.' },
+  kaleidoscope: { segments: 'Wedges. Default 8.', center: BLUR_CENTRE, angle: 'Degrees: where the source wedge starts (default -90, up).', scale: 'Zoom of the source. Default 1.' },
+  mirror: { keep: 'left | right | top | bottom | top-left | top-right | bottom-left | bottom-right', at: 'The mirror line: a fraction, or [x, y].' },
+  stretch: { at: '0–1: the row or column.', direction: 'down | up | left | right', length: '0–1 of the way to the edge.', fade: '0–1.' },
+  sort: { direction: 'horizontal | vertical', threshold: '[lo, hi] luminance, 0–1.', by: 'luma | hue | saturation', reverse: 'Boolean.', length: '0–1: break runs at seeded lengths.', seed: 'Number or string.' },
+
+  // Colour.
+  curves: { points: '[[in, out], …] 0–1, all channels.', red: 'Points.', green: 'Points.', blue: 'Points.' },
+  gradientMap: { colors: 'Shadows to highlights.', stops: 'Positions, 0–1.', space: 'srgb | oklab' },
+  posterize: { levels: 'Tones per channel. Default 4.' },
+  invert: { amount: '0–1. Default 1.' },
+  hue: { angle: 'Degrees.', saturation: '-1–1.', lightness: '-1–1.' },
+  vibrance: { amount: '-1–1. Default 0.5.', saturation: '-1–1.' },
+  colorBalance: { shadows: '[r, g, b], -1–1.', midtones: '[r, g, b].', highlights: '[r, g, b].' },
+  channelMixer: { red: '[r, g, b, constant].', green: 'Row.', blue: 'Row.', monochrome: 'Boolean.', gray: 'Row (monochrome).' },
+  sepia: { amount: '0–1.' },
+  look: { name: 'fade | crossProcess | bleachBypass | tealOrange | warmFilm | coolFilm | noir', amount: '0–1.' },
+
+  // Light.
+  bloom: { threshold: '0–1.', radius: 'Length.', intensity: 'Number.', color: 'Tint.' },
+  halation: { threshold: '0–1.', radius: 'Length.', intensity: 'Number.', color: 'Default red-orange.' },
+  vignette: { shape: 'ellipse | circle | rect', size: '0–1: where it starts.', softness: '0–1.', amount: '0–1.', color: 'Default black.', center: BLUR_CENTRE },
+  lightLeak: { edge: 'left | right | top | bottom (default seeded)', colors: 'Colours.', intensity: 'Number.', seed: 'Number or string.' },
+  lensFlare: { at: 'The light, [x, y] fractions.', size: 'Length.', intensity: 'Number.', color: 'Tint.', ghosts: 'Count. Default 6.', streak: 'true or a width factor: an anamorphic streak.', seed: 'Number or string.' },
+  rays: { center: 'The light, [x, y] fractions (default the brightest patch).', threshold: '0–1.', length: 'How far rays reach, a fraction of the frame. Default 0.5.', intensity: 'Number.', color: 'Tint.' },
+
+  // Texture and print.
+  grain: { amount: '0–1.', size: 'Length.', color: 'Boolean: colour grain.', seed: 'Number.' },
+  dust: { amount: '0–1.', scratches: 'Count.', color: 'light | dark | mixed', seed: 'Number or string.' },
+  paper: { texture: 'paper | canvas', scale: 'Length.', amount: '0–1.', angle: 'Light azimuth, degrees.', seed: 'Number.' },
+  scanlines: { spacing: 'Length.', thickness: '0–1.', amount: '0–1.' },
+  crt: { mask: 'aperture | shadow', size: 'Length: a triad.', amount: '0–1.', scanlines: '0–1.', curvature: '0–1.' },
+  vhs: { shift: 'Length: chroma shift.', bleed: 'Length: chroma smear.', jitter: 'Length.', tracking: '0–1.', noise: '0–1.', seed: 'Number or string.' },
+  jpeg: { quality: '1–100. Default 12.', block: 'Length: a JPEG pixel.', passes: 'Re-saves, 1–8.', subsample: 'Boolean. Default true.' },
+  newsprint: { cell: 'Length: the screen.', angles: '[c, m, y, k] degrees.', paper: 'Colour.', gain: 'Dot gain, 0–0.3.', gcr: '0–1.' },
+
+  // Digital.
+  chromatic: { amount: 'Length.', angle: 'Degrees (directional).', mode: 'directional (default) | radial', center: BLUR_CENTRE },
+  rgbSplit: { amount: 'Length.', angle: 'Degrees.' },
+  glitch: { amount: '0–1.', shift: 'Length.', slices: 'Count.', blocks: 'Count.', seed: 'Number or string.' },
+  pixelate: { size: 'Length.', shape: 'square | hex' },
+  mosaic: { size: 'Length.', shape: 'square | hex' },
+  ascii: { cell: 'Length.', ramp: 'Characters, sparse to dense.', color: 'source | a colour.', background: 'Colour or none.', invert: 'Boolean.', contrast: 'Number.' },
+  emboss: { angle: 'Degrees.', amount: 'Number.', radius: 'Length.', color: 'Boolean: over the layer.' },
+  edges: { radius: 'Length.', amount: 'Number.', style: 'ink | glow', color: 'Ink colour.', mono: 'Boolean.' },
+  sketch: { radius: 'Length.', darkness: '0–1.', color: 'Boolean: coloured pencil.' },
+  sharpen: { amount: 'Number.', radius: 'Length.' },
+};

package/src/effects/paint-presets.d.ts

@@ -0,0 +1,10 @@
+// Named paints: chrome, steel and gold, painted as a reflected horizon.
+import type { GradientPaint } from './paint.js';
+import type { Color, Length } from '../index.js';
+
+/** Paint presets, by name. */
+export const PRESETS: Readonly<Record<'chrome' | 'steel' | 'gold', Readonly<GradientPaint>>>;
+/** The keyline metal paints bring: a thin light edge, then a dark one. */
+export const KEYLINE: readonly { readonly color: Color; readonly width: Length }[];
+/** The keyline a fill brings with it (a preset's, unless `keyline: false`). */
+export function presetStrokes(fill: unknown): { color: Color; width: Length }[] | undefined;

package/src/effects/paint-presets.js

@@ -0,0 +1,47 @@
+/**
+ * Named paints. `chrome` is Y2K chrome as it's painted by hand: a
+ * reflected horizon, not a lighting filter. Sky at the top, a sharp dark
+ * horizon a little past the middle, warm ground below it, and a light
+ * bounce at the very bottom. Pair it with a light keyline (`strokes`).
+ *
+ * @module effects/paint-presets
+ */
+
+/** Paint presets, by name. A paint `{ preset, …fields }` overrides any of them. */
+export const PRESETS = Object.freeze({
+  chrome: Object.freeze({
+    type: 'linear',
+    angle: 180,
+    colors: ['#f4f8ff', '#9fc3ef', '#e8f1ff', '#2b3446', '#7a5a3c', '#d9b48a', '#fff6e6'],
+    stops: [0, 0.34, 0.545, 0.555, 0.62, 0.86, 1],
+  }),
+  /** The same horizon, cooler: steel. */
+  steel: Object.freeze({
+    type: 'linear',
+    angle: 180,
+    colors: ['#ffffff', '#b9c4d4', '#eef2f7', '#30363f', '#5d6672', '#c7ced8', '#ffffff'],
+    stops: [0, 0.34, 0.545, 0.555, 0.62, 0.86, 1],
+  }),
+  /** Gold leaf: the horizon in warm metal. */
+  gold: Object.freeze({
+    type: 'linear',
+    angle: 180,
+    colors: ['#fff6d6', '#e9c46a', '#fff1c2', '#6b4210', '#a8701f', '#f2cf73', '#fff8e0'],
+    stops: [0, 0.34, 0.545, 0.555, 0.62, 0.86, 1],
+  }),
+});
+
+/** The keyline that goes round metal paints: a thin light edge, then a dark one (widest first, under the fill). */
+export const KEYLINE = Object.freeze([Object.freeze({ color: '#0b0f18', width: '0.9vmin' }), Object.freeze({ color: '#ffffff', width: '0.35vmin' })]);
+
+/**
+ * The keyline a fill brings with it: a preset paint's, unless the paint
+ * says `keyline: false` (or gives its own `keyline` list).
+ *
+ * @param {any} fill
+ * @returns {{ color: string, width: string | number }[] | undefined}
+ */
+export function presetStrokes(fill) {
+  if (!fill || typeof fill !== 'object' || fill.preset == null || fill.keyline === false) return undefined;
+  return Array.isArray(fill.keyline) ? fill.keyline : [...KEYLINE];
+}

package/src/effects/paint.d.ts

@@ -0,0 +1,49 @@
+// Paints: a colour, 'none', or a gradient over a shape's bounds.
+import type { Color, Length } from '../index.js';
+
+/** A gradient over a shape's bounds. */
+export interface GradientPaint {
+  type: 'linear' | 'radial';
+  colors: Color[];
+  stops?: number[];
+  opacities?: number[];
+  /** Linear: CSS degrees. Default 180 (top to bottom). */
+  angle?: number;
+  /** `'reflect'` / `'repeat'` with a `length` run: holographic foil, stripes. */
+  spread?: 'pad' | 'reflect' | 'repeat';
+  length?: Length;
+  cx?: number; cy?: number; r?: Length; fx?: number; fy?: number;
+  /** Radial: elliptical radii (lengths, or fractions ≤ 1 of the box). */
+  rx?: Length; ry?: Length;
+}
+
+/** A pattern repeated over a shape. */
+export interface TilePaint {
+  type: 'tile';
+  kind?: 'checker' | 'stripes' | 'dots' | 'grid' | 'custom';
+  /** One cell (or `[width, height]`). Default `'4vmin'`. */
+  size?: Length | [Length, Length];
+  /** `[ground, ink]`; the ground may be `'none'`. */
+  colors?: [Color | 'none', Color];
+  /** The stripe, dot or line share of a cell. */
+  ratio?: number;
+  /** Degrees. */
+  angle?: number;
+  /** `custom`: the tile's markup (sanitised). */
+  markup?: string;
+}
+
+/** A named paint (`'chrome'`, `'steel'`, `'gold'`): a reflected-horizon gradient with its keyline; fields override it. */
+export interface PresetPaint extends Partial<Omit<GradientPaint, 'type'>> {
+  preset: 'chrome' | 'steel' | 'gold';
+  type?: 'linear' | 'radial';
+  /** The keyline it brings (`false` for none). */
+  keyline?: false | { color: Color; width: Length }[];
+}
+
+/** A fill or stroke: a colour, `'none'`, a gradient, a tile or a preset. */
+export type Paint = Color | 'none' | GradientPaint | TilePaint | PresetPaint;
+
+
+/** A paint as an SVG fill value, plus any gradient it needs in `<defs>`. */
+export function paint(v: Paint | undefined, fallback: string, o: { id: string; box: { x: number; y: number; width: number; height: number }; canvas: { width: number; height: number } }): { defs: string; value: string };

package/src/effects/paint.js

@@ -0,0 +1,66 @@
+/**
+ * Paints: a colour, `'none'`, a linear or radial gradient laid over a
+ * shape's bounds (reflected foil with `spread` and `length`; elliptical
+ * radial fields with `rx`/`ry`), a `tile` pattern (checker, stripes, dots,
+ * grid or a custom tile), or a named preset (`'chrome'`).
+ *
+ * @module effects/paint
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { toHex } from '../color.js';
+import { PRESETS } from './paint-presets.js';
+import { tile } from './tile.js';
+
+/**
+ * A fill or stroke: a colour, `'none'`, a gradient object
+ * `{ type: 'linear' | 'radial', colors, stops?, opacities?, angle?, spread?: 'pad' | 'reflect' | 'repeat', length?, cx?, cy?, r?, rx?, ry? }`,
+ * a tile `{ type: 'tile', kind, size, colors, … }`, or a preset
+ * `{ preset: 'chrome', … }` (its fields override the preset's), laid over
+ * `box` (the shape's bounds, else the canvas). `length` sets a linear
+ * gradient's run in px (with `reflect` it repeats: holographic foil).
+ *
+ * @param {any} v - The paint.
+ * @param {string} fallback - Used when `v` is unset.
+ * @param {{ id: string, box: { x: number, y: number, width: number, height: number }, canvas: { width: number, height: number } }} o
+ * @returns {{ defs: string, value: string }}
+ */
+export function paint(v, fallback, o) {
+  if (v == null || v === '') return { defs: '', value: fallback };
+  if (typeof v === 'string') return { defs: '', value: v === 'none' || v === 'currentColor' || v.startsWith('url(') ? v : toHex(v) };
+  if (v.preset != null) {
+    const base = PRESETS[v.preset];
+    if (!base) throw new TypeError(`Unknown paint preset "${v.preset}" (${Object.keys(PRESETS).join(', ')})`);
+    const { preset, keyline, ...own } = v;
+    return paint({ ...base, ...own }, fallback, o);
+  }
+  if (v.type === 'tile') return tile(v, o);
+  const colors = (v.colors ?? []).map(toHex);
+  if (colors.length < 2) throw new TypeError('A gradient paint needs two or more colours');
+  const offsets = v.stops ?? colors.map((/** @type {string} */ _, /** @type {number} */ i) => i / (colors.length - 1));
+  const stops = colors.map((c, i) => `<stop${attrs({ offset: num(offsets[i], 4), 'stop-color': c, 'stop-opacity': v.opacities?.[i] != null && v.opacities[i] < 1 ? num(v.opacities[i], 3) : undefined })}/>`).join('');
+  const { box } = o;
+  const spread = v.spread && v.spread !== 'pad' ? v.spread : undefined;
+  if (v.type === 'radial') {
+    const cx = box.x + (v.cx ?? 0.5) * box.width;
+    const cy = box.y + (v.cy ?? 0.5) * box.height;
+    // Elliptical: rx and ry (lengths, or fractions ≤ 1 of the box's width and height).
+    const radius = (/** @type {any} */ r, /** @type {number} */ side) => (typeof r === 'number' && r <= 1 ? r * side : len(r, o.canvas));
+    const rx = v.rx != null ? radius(v.rx, box.width) : undefined;
+    const ry = v.ry != null ? radius(v.ry, box.height) : undefined;
+    const r = rx ?? ry ?? (v.r != null ? len(v.r, o.canvas) : Math.hypot(box.width, box.height) / 2);
+    const squash = rx != null && ry != null && rx > 0 ? ry / rx : 1;
+    const gradientTransform = squash !== 1 ? `translate(${num(cx)} ${num(cy)}) scale(1 ${num(squash, 5)}) translate(${num(-cx)} ${num(-cy)})` : undefined;
+    return { defs: `<radialGradient${attrs({ id: o.id, gradientUnits: 'userSpaceOnUse', cx, cy, r, fx: v.fx != null ? box.x + v.fx * box.width : undefined, fy: v.fy != null ? box.y + v.fy * box.height : undefined, spreadMethod: spread, gradientTransform })}>${stops}</radialGradient>`, value: `url(#${o.id})` };
+  }
+  const a = ((v.angle ?? 180) * Math.PI) / 180;
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  const L = v.length != null ? len(v.length, o.canvas) : Math.abs(box.width * Math.sin(a)) + Math.abs(box.height * Math.cos(a));
+  const dx = (Math.sin(a) * L) / 2;
+  const dy = (-Math.cos(a) * L) / 2;
+  const x1 = v.length != null ? box.x : cx - dx;
+  const y1 = v.length != null ? box.y : cy - dy;
+  return { defs: `<linearGradient${attrs({ id: o.id, gradientUnits: 'userSpaceOnUse', x1, y1, x2: x1 + 2 * dx, y2: y1 + 2 * dy, spreadMethod: spread })}>${stops}</linearGradient>`, value: `url(#${o.id})` };
+}

package/src/effects/pixels.d.ts

@@ -0,0 +1,24 @@
+// Effects computed on pixels: draw, process, mix through the mask, embed.
+import type { Markup } from '../render/context.js';
+import type { Pixels } from './buffer.js';
+
+/** The most pixels an effect works on. */
+export const MAX_PIXELS: number;
+
+/** What a pixel effect returns. */
+export interface PixelResult {
+  data: Uint8ClampedArray;
+  width: number;
+  height: number;
+  /** Embed as PNG even when opaque. */
+  lossless?: boolean;
+  /** Smaller than the layer: scaled up nearest-neighbour. */
+  pixelated?: boolean;
+}
+
+/** A layer's markup as RGBA pixels, `w`×`h` over its canvas; undefined where nothing can draw. */
+export function drawLayer(m: Markup, ctx: object, w: number, h: number): Promise<Uint8ClampedArray | undefined>;
+/** The raster size for a layer (its pixels as shown, capped). */
+export function rasterSize(ctx: object, cap?: number): { w: number; h: number; scale: number };
+/** Run a pixel effect on a layer's markup; undefined where nothing can draw pixels. */
+export function pixelEffect(fx: { mask?: import('./mask.js').EffectMask }, m: Markup, ctx: object, run: (img: Pixels) => PixelResult | Uint8ClampedArray | Promise<PixelResult | Uint8ClampedArray>, o?: { cap?: number }): Promise<Markup | undefined>;