@arraypress/covers 1.0.0 → 1.1.0

package/src/effects/index.js

@@ -0,0 +1,277 @@
+/**
+ * Effects: what any layer takes as `effects: [{ kind, … }]`, applied in
+ * order (innermost first) in the layer's own coordinates. Three sorts:
+ *
+ * - **Filters**: one SVG `<filter>` each, over the canvas padded so blurs
+ *   and glows don't clip (colour, light, detail, grain…).
+ * - **Pixels**: what filters can't do (spin and zoom blur, bokeh,
+ *   distortions, pixel sorting, ASCII…), drawn once at the layer's
+ *   resolution, processed on a typed array and embedded (`pixels.js`).
+ * - **Copies**: the layer's own markup drawn again (`extrude`, `mirror`),
+ *   so vectors stay vectors.
+ *
+ * Any of them takes a `mask` (`mask.js`): a gradient or layers saying
+ * where, and how much, it applies.
+ *
+ * @module effects
+ */
+
+import { num } from '../svg.js';
+import { len } from '../geometry.js';
+import { filterElement } from './util.js';
+import { blur, shadow, border } from './light.js';
+import { rough, wear, xerox, grit } from './ink.js';
+import { duotone, levels, saturate, matrix, threshold, photocopy } from './tone.js';
+import { halftone } from './halftone.js';
+import { dither, ditherRaster } from './dither.js';
+import { expandDropShadows } from './drop-shadow.js';
+import { extrude } from './extrude.js';
+import { roundBorder } from './round-border.js';
+import { separableMorphology, bounded, filterReach } from './region.js';
+import { curves, gradientMap, posterize, invert, hue, colorBalance, channelMixer, sepia, vibrance } from './grade.js';
+import { look } from './looks.js';
+import { bloom, halation } from './glow.js';
+import { vignette, lightLeak, lensFlare } from './optics.js';
+import { grain, paper, dust } from './film.js';
+import { scanlines, crt, vhs, jpeg } from './screen.js';
+import { sketch, edges, emboss, sharpen } from './detail.js';
+import { chromatic, chromaticRadial, glitch, pixelate } from './digital.js';
+import { spin, zoom, rays } from './polar.js';
+import { lens, tilt } from './lens.js';
+import { motion as motionPixels } from './motion.js';
+import { wave, ripple, twirl, bulge, fisheye, kaleidoscope, glass, displace } from './distort.js';
+import { sort, stretch } from './sort.js';
+import { newsprint } from './newsprint.js';
+import { ascii } from './ascii.js';
+import { mirror } from './symmetry.js';
+import { pixelEffect } from './pixels.js';
+import { gradientImage, lerpPrimitives, maskOverlay, RESOLVED } from './mask.js';
+import { EFFECT_OPTIONS } from './options.js';
+
+export { transformAttr } from './transform.js';
+export { paint } from './paint.js';
+export { expandDropShadows } from './drop-shadow.js';
+export { EFFECT_OPTIONS, EFFECT_COMMON } from './options.js';
+export { checkMask, RESOLVED, maskImage } from './mask.js';
+
+/** Scripts, event-handler attributes (a name starting `on`) and `javascript:` URLs. */
+const UNSAFE = /<script|(?:^|[\s"'/])on[a-z]+\s*=|javascript:/i;
+
+/**
+ * `filter`: raw primitives, the escape hatch. `{{seed}}` is a seeded
+ * number, `{{id}}` the layer's id prefix. `feDropShadow` is spelled out
+ * as primitives, so its `in` is honoured everywhere (librsvg ignores it).
+ *
+ * @param {{ markup?: string }} fx
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+function raw(fx, ctx) {
+  const markup = String(fx.markup ?? '');
+  if (UNSAFE.test(markup)) throw new TypeError('Filter markup may not contain scripts or event handlers');
+  return expandDropShadows(markup.replace(/\{\{seed\}\}/g, () => String(ctx.rng.int(1, 9999))).replace(/\{\{id\}\}/g, ctx.id));
+}
+
+/** Effects drawn as one filter (every kind but `motion`), by name. @type {Record<string, (fx: any, ctx: import('../layers.js').RenderContext) => string>} */
+const KINDS = {
+  blur, shadow, glow: shadow, border, wear, rough, warp: rough, xerox, photocopy, duotone, grayscale: levels, levels, saturate, matrix, grit, halftone, dither, threshold, filter: raw,
+  curves, gradientMap, posterize, invert, hue, colorBalance, channelMixer, sepia, look,
+  bloom, halation, vignette, lightLeak, lensFlare,
+  grain, paper, scanlines,
+  sketch, edges, emboss, sharpen,
+  chromatic, rgbSplit: chromatic,
+};
+
+/** Effects computed on pixels, by name. @type {Record<string, (img: import('./buffer.js').Pixels, fx: any, ctx: any) => any>} */
+const PIXEL = {
+  zoom, spin, rays, lens, tilt, motion: motionPixels,
+  wave, ripple, twirl, bulge, pinch: bulge, fisheye, kaleidoscope, glass, displace,
+  sort, stretch, vibrance, dust, crt, vhs, jpeg, newsprint,
+  chromatic: chromaticRadial, glitch, pixelate, mosaic: pixelate, ascii,
+};
+
+/** Effects drawn as copies of the layer's markup. @type {Record<string, (fx: any, m: { defs: string, body: string }, ctx: any, id: string) => { defs: string, body: string }>} */
+const COPIES = { extrude, mirror };
+
+/**
+ * What a pixel effect falls back to where nothing can draw pixels (a
+ * Worker): a filter close to it (`tilt`: a Gaussian through its band), or
+ * nothing (the layer is drawn without it).
+ *
+ * @type {Record<string, (fx: any, ctx: any) => string>}
+ */
+const FALLBACK = {
+  lens: (fx, ctx) => blur({ kind: 'blur', radius: len(fx.radius, ctx.canvas, '1.2vmin') * 0.5 }, ctx),
+  // A Gaussian through the band (an effect's own mask is mixed on top).
+  tilt: (fx, ctx) => blur({ kind: 'blur', radius: len(fx.radius, ctx.canvas, '1.4vmin') * 0.7 }, ctx)
+    + (fx.mask ? '' : lerpPrimitives(gradientImage({ gradient: 'band', center: fx.center, angle: fx.angle, from: fx.width ?? '8vmin', to: len(fx.width ?? '8vmin', ctx.canvas) + len(fx.falloff ?? '22vmin', ctx.canvas) }, ctx, 0.25))),
+};
+
+/** Every effect kind, for validation and docs. */
+export const EFFECTS = Object.freeze(Object.keys(EFFECT_OPTIONS));
+
+/** Effects computed outside SVG filters (on pixels, or as copies of the markup), always. */
+export const RASTER_EFFECTS = Object.freeze(['dither', 'extrude', ...Object.keys(COPIES).filter((k) => k !== 'extrude'), ...Object.keys(PIXEL).filter((k) => k !== 'chromatic' && k !== 'motion')]);
+
+/** @param {any} fx @returns {any} An effect given as a string, as an object. */
+const asEffect = (fx) => (typeof fx === 'string' ? { kind: fx } : fx);
+
+/**
+ * Whether an effect is computed on pixels: the pixel kinds, `chromatic`
+ * with `mode: 'radial'`, and `motion` when rasterising (librsvg can't
+ * blur along a turned axis, and the pixel blur holds the edge).
+ *
+ * @param {any} fx
+ * @param {{ raster?: boolean }} [ctx]
+ * @returns {boolean}
+ */
+export function isPixel(fx, ctx) {
+  const e = asEffect(fx);
+  if (!e || !Object.hasOwn(PIXEL, e.kind)) return false;
+  if (e.kind === 'chromatic') return e.mode === 'radial';
+  if (e.kind === 'motion') return Boolean(ctx?.raster);
+  return true;
+}
+
+/**
+ * Whether an effect needs something that draws pixels (so `renderSvg`
+ * loads sharp in Node): pixel effects, `dither`, a round `border`.
+ *
+ * @param {any} fx
+ * @returns {boolean}
+ */
+export function needsPixels(fx) {
+  const e = asEffect(fx);
+  return Boolean(e) && (isPixel(e) || e.kind === 'dither' || (e.kind === 'border' && e.shape === 'circle'));
+}
+
+/**
+ * Whether an effect is drawn without an SVG filter (pixels, copies, a
+ * round `border`).
+ *
+ * @param {any} fx
+ * @param {{ raster?: boolean }} [ctx]
+ * @returns {boolean}
+ */
+export const isRaster = (fx, ctx) => {
+  const e = asEffect(fx);
+  return Boolean(e) && (e.kind === 'dither' || Object.hasOwn(COPIES, e.kind) || isPixel(e, ctx) || (e.kind === 'border' && e.shape === 'circle'));
+};
+
+/**
+ * An effect drawn without an SVG filter: on pixels, as copies, or a round
+ * `border`; with its `mask` (a pixel mix, or for copies an SVG mask).
+ * Undefined where nothing can draw pixels (its filter is used instead).
+ *
+ * @param {any} fx
+ * @param {{ defs: string, body: string }} m
+ * @param {import('../layers.js').RenderContext} ctx
+ * @param {number} i - The effect's index (for unique ids).
+ * @returns {Promise<{ defs: string, body: string } | undefined>}
+ */
+export async function rasterEffect(fx, m, ctx, i) {
+  const id = `${ctx.id}x${i}`;
+  if (isPixel(fx, ctx)) return pixelEffect(fx, m, ctx, (img) => PIXEL[fx.kind](img, fx, ctx));
+  let out;
+  if (Object.hasOwn(COPIES, fx.kind)) out = COPIES[fx.kind](fx, m, ctx, id);
+  else if (fx.kind === 'border') out = await roundBorder(fx, m, ctx);
+  else out = await ditherRaster(fx, m, ctx, id);
+  if (!out || !fx.mask) return out;
+  return maskOverlay(m.body, out, fx.mask, ctx, `${id}m`);
+}
+
+/** Region padding by kind, as a fraction of the canvas. */
+const PAD = /** @type {Record<string, number>} */ ({ blur: 0.25, shadow: 0.25, glow: 0.25, warp: 0.25, bloom: 0.25, lens: 0.25, tilt: 0.25 });
+
+/**
+ * Wrap markup in a layer's filter effects.
+ *
+ * `motion` (a directional blur at any `angle`) blurs along x in a frame
+ * turned to the angle; every other kind is one filter. A pixel effect
+ * here (nothing could draw pixels) takes its fallback filter, or is left
+ * out.
+ *
+ * Each takes `colorSpace` (`'sRGB'`, the default, or `'linearRGB'`, the
+ * SVG default a browser's own filters use), `pad` and `mask`: a gradient
+ * mask is mixed inside the filter; a layer mask too when it has been
+ * drawn as an image, else the effect is drawn over the layer through an
+ * SVG mask.
+ *
+ * @param {string} body
+ * @param {import('./index.js').Effect | import('./index.js').Effect[]} list
+ * @param {import('../layers.js').RenderContext} ctx
+ * @param {number} [start=0] - Index of the first effect (ids stay unique when a list is applied in runs).
+ * @param {{ x: number, y: number, width: number, height: number }} [content] - The box the layer paints, when known: filters that stay inside their source get a region that size (plus their padding) instead of the canvas.
+ * @param {string} [prior=''] - The defs drawn so far (an SVG mask fallback repeats the layer).
+ * @returns {{ defs: string, body: string }}
+ * @throws {TypeError} On an unknown kind.
+ */
+export function applyEffects(body, list, ctx, start = 0, content, prior = '') {
+  const effects = Array.isArray(list) ? list : [list];
+  let defs = '';
+  let out = body;
+  /** What the layer paints so far (grows with each effect's padding), when known. */
+  let painted = content;
+  effects.forEach((e, i) => {
+    if (!e) return;
+    const fx = /** @type {any} */ (asEffect(e));
+    const id = `${ctx.id}x${start + i}`;
+    const before = out;
+    const mask = fx.mask;
+    // A layer mask not drawn as an image: the effect goes over the layer through an SVG mask.
+    const overlay = mask && mask.layers && !mask[RESOLVED]?.image;
+    /** @param {number} pad @param {number} [angle] @returns {string} The mix with the source, for a mask. */
+    const mix = (pad, angle = 0) => (!mask || overlay ? '' : lerpPrimitives(mask.layers ? mask[RESOLVED].image : gradientImage(mask, ctx, pad, angle)));
+    if (fx.kind === 'motion') {
+      const a = fx.angle ?? 0;
+      const c = `${num(ctx.width / 2)} ${num(ctx.height / 2)}`;
+      const pad = fx.pad ?? 0.3;
+      defs += filterElement(id, ctx, pad, `<feGaussianBlur stdDeviation="${num(len(fx.length ?? '3vmin', ctx.canvas))} ${num(len(fx.spread ?? 0, ctx.canvas))}"/>${mix(pad, a)}`, fx.colorSpace);
+      out = `<g transform="rotate(${num(a)} ${c})"><g filter="url(#${id})"><g transform="rotate(${num(-a)} ${c})">${out}</g></g></g>`;
+      painted = undefined;
+    } else {
+      const make = Object.hasOwn(KINDS, fx.kind) ? KINDS[fx.kind] : FALLBACK[fx.kind];
+      if (!make) {
+        if (Object.hasOwn(PIXEL, fx.kind) || Object.hasOwn(COPIES, fx.kind)) return;
+        throw new TypeError(`Unknown effect "${fx.kind}" (${EFFECTS.join(', ')})`);
+      }
+      const pad = fx.pad ?? PAD[fx.kind] ?? 0.05;
+      let primitives = make(fx, ctx);
+      if (!primitives) return;
+      primitives += mix(pad);
+      // For librsvg: separable morphology, and a region the size of what's painted.
+      if (/** @type {any} */ (ctx).raster) primitives = separableMorphology(primitives);
+      const region = painted && bounded(primitives) ? grow(painted, pad, ctx) : undefined;
+      // How far it reaches at the output's resolution (renderImage's tiles overlap by that).
+      /** @type {any} */ (ctx).noteReach?.(filterReach(primitives) * (/** @type {any} */ (ctx).res ?? 1));
+      painted = region;
+      defs += filterElement(id, ctx, pad, primitives, fx.colorSpace, region);
+      out = `<g filter="url(#${id})">${out}</g>`;
+    }
+    if (overlay) {
+      const got = maskOverlay(before, { defs: prior + defs, body: out }, mask, ctx, `${id}m`);
+      defs = got.defs.slice(prior.length);
+      out = got.body;
+      painted = undefined;
+    }
+  });
+  return { defs, body: out };
+}
+
+/**
+ * A painted box grown by an effect's padding, inside the canvas's padded region.
+ *
+ * @param {{ x: number, y: number, width: number, height: number }} box
+ * @param {number} pad - Fraction of the canvas.
+ * @param {{ width: number, height: number }} ctx
+ * @returns {{ x: number, y: number, width: number, height: number }}
+ */
+function grow(box, pad, ctx) {
+  const px = ctx.width * pad;
+  const py = ctx.height * pad;
+  const x0 = Math.max(-px, box.x - px);
+  const y0 = Math.max(-py, box.y - py);
+  const x1 = Math.min(ctx.width + px, box.x + box.width + px);
+  const y1 = Math.min(ctx.height + py, box.y + box.height + py);
+  return { x: x0, y: y0, width: Math.max(0, x1 - x0), height: Math.max(0, y1 - y0) };
+}

package/src/effects/ink.d.ts

@@ -0,0 +1,12 @@
+// Ink and print effects.
+import type { Effect } from './index.js';
+import type { RenderContext } from '../render/context.js';
+
+/** The `rough | warp` effect's filter primitives. */
+export function rough(fx: Extract<Effect, { kind: 'rough' | 'warp' }>, ctx: RenderContext): string;
+/** The `wear` effect's filter primitives. */
+export function wear(fx: Extract<Effect, { kind: 'wear' }>, ctx: RenderContext): string;
+/** The `xerox` effect's filter primitives. */
+export function xerox(fx: Extract<Effect, { kind: 'xerox' }>, ctx: RenderContext): string;
+/** The `grit` effect's filter primitives. */
+export function grit(fx: Extract<Effect, { kind: 'grit' }>, ctx: RenderContext): string;

package/src/effects/ink.js

@@ -0,0 +1,70 @@
+/**
+ * Ink and print effects: displacement (rough, warp), riso drum wear,
+ * photocopied vector ink, and grit.
+ *
+ * @module effects/ink
+ */
+
+import { num } from '../svg.js';
+import { len } from '../geometry.js';
+import { mat, seedOf, displace } from './util.js';
+
+/**
+ * `rough` (a fine wobble) and `warp` (a melting distortion).
+ *
+ * @param {import('./index.js').Effect & { kind: 'rough' | 'warp' }} fx
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function rough(fx, ctx) {
+  const warp = fx.kind === 'warp';
+  return displace(fx.frequency ?? (warp ? [0.005, 0.011] : 0.9), fx.octaves ?? 2, seedOf(ctx, fx), len(fx.scale, ctx.canvas, warp ? '8vmin' : '0.26vmin'));
+}
+
+/**
+ * `wear`: riso drum wear. Edges a touch rough (`rough`), coverage uneven
+ * (`uneven`), specks where the drum missed (`specks`).
+ *
+ * @param {import('./index.js').Effect & { kind: 'wear' }} fx
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function wear(fx, ctx) {
+  const uneven = fx.uneven ?? 0.4;
+  const specks = fx.specks ?? 1;
+  const s1 = seedOf(ctx, fx);
+  const s2 = ctx.rng.int(1, 9999);
+  const s3 = ctx.rng.int(1, 9999);
+  return displace(0.9, 2, s1, len(fx.rough, ctx.canvas, '0.26vmin'), 'rough')
+    + `<feTurbulence type="fractalNoise" baseFrequency="0.02 0.05" numOctaves="3" seed="${s2}" result="lo"/>`
+    + `<feColorMatrix in="lo" type="matrix" values="${mat([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, uneven, 0, 0, 0, 1.16 - uneven])}" result="even"/>`
+    + `<feTurbulence type="fractalNoise" baseFrequency="0.7" numOctaves="1" seed="${s3}" result="sp"/>`
+    + `<feColorMatrix in="sp" type="matrix" values="${mat([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -16 * specks, 13.2 + (1 - specks) * 3])}" result="holes"/>`
+    + '<feComposite in="even" in2="holes" operator="arithmetic" k1="1" result="cover"/><feComposite in="rough" in2="cover" operator="in"/>';
+}
+
+/**
+ * `xerox`: photocopied vector ink, a wobble and toner dropout.
+ *
+ * @param {import('./index.js').Effect & { kind: 'xerox' }} fx
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function xerox(fx, ctx) {
+  const s1 = seedOf(ctx, fx);
+  const s2 = ctx.rng.int(1, 9999);
+  return displace(1.1, 2, s1, len(fx.rough, ctx.canvas, '0.32vmin'), 'w')
+    + `<feTurbulence type="fractalNoise" baseFrequency="0.6" numOctaves="1" seed="${s2}" result="d"/><feColorMatrix in="d" type="matrix" values="${mat([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -14, 10.6 + (fx.dropout != null ? (0.5 - fx.dropout) * 4 : 0)])}" result="h"/><feComposite in="w" in2="h" operator="in"/>`;
+}
+
+/**
+ * `grit`: noise added to the colour (`amount`), kept inside the source.
+ *
+ * @param {import('./index.js').Effect & { kind: 'grit' }} fx
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function grit(fx, ctx) {
+  const a = fx.amount ?? 0.14;
+  return `<feTurbulence type="fractalNoise" baseFrequency="${num(fx.frequency ?? 0.9, 3)}" numOctaves="1" seed="${seedOf(ctx, fx)}" result="g"/><feComposite in="SourceGraphic" in2="g" operator="arithmetic" k2="1" k3="${num(a, 3)}" k4="${num(-a / 2, 3)}"/><feComposite in2="SourceAlpha" operator="in"/>`;
+}

package/src/effects/lens.d.ts

@@ -0,0 +1,14 @@
+// Optical blurs on pixels: lens bokeh and tilt-shift.
+import type { Effect } from './index.js';
+import type { Pixels } from './buffer.js';
+
+/** One row of an aperture: its span (pixel offsets) and how much of the row it fills. */
+export interface Span { dy: number; l: number; r: number; wgt: number }
+/** An aperture (a disc, or a polygon of `blades` sides) as anti-aliased spans. */
+export function aperture(R: number, blades: number, rotation: number): Span[];
+/** Convolve premultiplied float RGBA with an aperture. */
+export function convolveSpans(src: Float32Array, w: number, h: number, spans: Span[]): Float32Array;
+/** `lens`: a lens blur with bokeh. */
+export function lens(img: Pixels, fx: Extract<Effect, { kind: 'lens' }>, ctx: object): Uint8ClampedArray;
+/** `tilt`: tilt-shift. */
+export function tilt(img: Pixels, fx: Extract<Effect, { kind: 'tilt' }>, ctx: object): Uint8ClampedArray;

package/src/effects/lens.js

@@ -0,0 +1,277 @@
+/**
+ * Optical blurs on pixels: `lens` (out of focus through an aperture, with
+ * bright highlights blooming into bokeh discs or polygons) and `tilt`
+ * (tilt-shift: a sharp band, the blur growing away from it).
+ *
+ * The lens blur works in linear light with highlights boosted (so a
+ * small light spreads into a bright disc, as it does through glass) and
+ * convolves with the aperture's exact shape a row at a time: each row of
+ * the shape is a span, summed from running totals, so the cost is one
+ * lookup per row of the kernel, not per pixel of it. Large radii work on
+ * a smaller copy (bokeh has no fine detail) and scale back.
+ *
+ * @module effects/lens
+ */
+
+import { TO_LINEAR, toSrgb, px, pointPx, smoothstep, gaussian, shrink, bilinear, premultiplied, unpremultiply, enlarge } from './buffer.js';
+
+/** The kernel radius a lens blur works at, px (larger radii work on a smaller copy). */
+const WORK_RADIUS = 10;
+
+/**
+ * One row of the aperture: the span it covers (pixel offsets, fractional)
+ * and how much of the row's height it fills.
+ *
+ * @typedef {{ dy: number, l: number, r: number, wgt: number }} Span
+ */
+
+/**
+ * The aperture as spans: a disc (`blades` 0) or a polygon of `blades`
+ * sides turned `rotation` degrees, radius `R`. Each row is the average
+ * of four sub-rows, so its top and bottom edges are anti-aliased too.
+ *
+ * @param {number} R
+ * @param {number} blades
+ * @param {number} rotation
+ * @returns {Span[]}
+ */
+export function aperture(R, blades, rotation) {
+  const n = Math.ceil(R + 0.5);
+  /** @type {[number, number][]} */
+  const poly = [];
+  if (blades >= 3) {
+    for (let k = 0; k < blades; k++) {
+      const a = ((rotation - 90) * Math.PI) / 180 + (2 * Math.PI * k) / blades;
+      poly.push([R * Math.cos(a), R * Math.sin(a)]);
+    }
+  }
+  /** @param {number} y @returns {[number, number] | null} */
+  const at = (y) => {
+    if (!poly.length) {
+      if (Math.abs(y) >= R) return null;
+      const s = Math.sqrt(R * R - y * y);
+      return [-s, s];
+    }
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (let k = 0; k < poly.length; k++) {
+      const [x0, y0] = poly[k];
+      const [x1, y1] = poly[(k + 1) % poly.length];
+      if ((y0 <= y && y1 >= y) || (y1 <= y && y0 >= y)) {
+        const x = y1 === y0 ? x0 : x0 + ((y - y0) / (y1 - y0)) * (x1 - x0);
+        lo = Math.min(lo, x);
+        hi = Math.max(hi, x);
+      }
+    }
+    return lo <= hi ? [lo, hi] : null;
+  };
+  /** @type {Span[]} */
+  const spans = [];
+  for (let dy = -n; dy <= n; dy++) {
+    let l = 0;
+    let r = 0;
+    let hits = 0;
+    for (let s = 0; s < 4; s++) {
+      const got = at(dy - 0.5 + (s + 0.5) / 4);
+      if (!got) continue;
+      l += got[0];
+      r += got[1];
+      hits++;
+    }
+    if (hits) spans.push({ dy, l: l / hits, r: r / hits, wgt: hits / 4 });
+  }
+  return spans;
+}
+
+/**
+ * Convolve premultiplied float RGBA with an aperture, edges held.
+ *
+ * @param {Float32Array} src - Interleaved RGBA.
+ * @param {number} w
+ * @param {number} h
+ * @param {Span[]} spans
+ * @returns {Float32Array}
+ */
+export function convolveSpans(src, w, h, spans) {
+  const pad = Math.ceil(Math.max(...spans.map((s) => Math.max(-s.l, s.r)))) + 2;
+  const pw = w + 2 * pad;
+  // Running totals along each row (edge held), one more than the row.
+  const sums = new Float32Array(h * (pw + 1) * 4);
+  for (let y = 0; y < h; y++) {
+    const base = y * (pw + 1) * 4;
+    for (let x = 0; x < pw; x++) {
+      const sx = Math.min(w - 1, Math.max(0, x - pad));
+      const i = (y * w + sx) * 4;
+      const o = base + (x + 1) * 4;
+      sums[o] = sums[o - 4] + src[i];
+      sums[o + 1] = sums[o - 3] + src[i + 1];
+      sums[o + 2] = sums[o - 2] + src[i + 2];
+      sums[o + 3] = sums[o - 1] + src[i + 3];
+    }
+  }
+  // Each span: whole pixels [L, R], and part of the pixel either side.
+  const rows = spans.map((s) => {
+    const L = Math.ceil(s.l + 0.5);
+    const R = Math.floor(s.r - 0.5);
+    const cover = (/** @type {number} */ dx) => Math.max(0, Math.min(dx + 0.5, s.r) - Math.max(dx - 0.5, s.l));
+    return { dy: s.dy, L, R, wgt: s.wgt, pl: L - 1 === R + 1 ? cover(L - 1) : cover(L - 1), pr: L - 1 === R + 1 ? 0 : cover(R + 1), full: R >= L };
+  });
+  let total = 0;
+  for (const r of rows) total += r.wgt * ((r.full ? r.R - r.L + 1 : 0) + r.pl + r.pr);
+  const norm = 1 / total;
+  const out = new Float32Array(w * h * 4);
+  const acc = new Float64Array(4);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      acc[0] = acc[1] = acc[2] = acc[3] = 0;
+      for (let k = 0; k < rows.length; k++) {
+        const r = rows[k];
+        let yy = y + r.dy;
+        if (yy < 0) yy = 0; else if (yy >= h) yy = h - 1;
+        const base = yy * (pw + 1) * 4;
+        const wg = r.wgt;
+        if (r.full) {
+          const a = base + (x + r.L + pad) * 4;
+          const b = base + (x + r.R + pad + 1) * 4;
+          acc[0] += (sums[b] - sums[a]) * wg;
+          acc[1] += (sums[b + 1] - sums[a + 1]) * wg;
+          acc[2] += (sums[b + 2] - sums[a + 2]) * wg;
+          acc[3] += (sums[b + 3] - sums[a + 3]) * wg;
+        }
+        if (r.pl) {
+          const sx = x + r.L - 1;
+          const i = (yy * w + (sx < 0 ? 0 : sx >= w ? w - 1 : sx)) * 4;
+          const f = r.pl * wg;
+          acc[0] += src[i] * f; acc[1] += src[i + 1] * f; acc[2] += src[i + 2] * f; acc[3] += src[i + 3] * f;
+        }
+        if (r.pr) {
+          const sx = x + r.R + 1;
+          const i = (yy * w + (sx < 0 ? 0 : sx >= w ? w - 1 : sx)) * 4;
+          const f = r.pr * wg;
+          acc[0] += src[i] * f; acc[1] += src[i + 1] * f; acc[2] += src[i + 2] * f; acc[3] += src[i + 3] * f;
+        }
+      }
+      const o = (y * w + x) * 4;
+      out[o] = acc[0] * norm; out[o + 1] = acc[1] * norm; out[o + 2] = acc[2] * norm; out[o + 3] = acc[3] * norm;
+    }
+  }
+  return out;
+}
+
+/**
+ * `lens`: a lens blur. `radius` (the aperture), `blades` (0 round, else
+ * that many sides), `rotation`, and the highlights: everything brighter
+ * than `threshold` is boosted by `highlights` before blurring, so lights
+ * become bright bokeh shapes.
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'lens' }} fx
+ * @param {any} ctx
+ * @returns {Uint8ClampedArray}
+ */
+export function lens(img, fx, ctx) {
+  const { data, width: w, height: h } = img;
+  const R = px(fx.radius, ctx, img, '1.2vmin');
+  if (R < 0.5) return data;
+  const f = Math.max(1, Math.floor(R / WORK_RADIUS));
+  const sw = Math.ceil(w / f);
+  const sh = Math.ceil(h / f);
+  const t = fx.threshold ?? 0.75;
+  const gain = 8 * (fx.highlights ?? 1);
+  // Linear, premultiplied, highlights boosted, averaged into f×f cells.
+  const work = new Float32Array(sw * sh * 4);
+  const count = new Float32Array(sw * sh);
+  for (let y = 0; y < h; y++) {
+    const row = ((y / f) | 0) * sw;
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 4;
+      const a = data[i + 3] / 255;
+      const c = row + ((x / f) | 0);
+      count[c]++;
+      if (!a) continue;
+      const lum = (0.2126 * data[i] + 0.7152 * data[i + 1] + 0.0722 * data[i + 2]) / 255;
+      const s = smoothstep(t, 1, lum);
+      const k = a * (1 + gain * s * s);
+      const o = c * 4;
+      work[o] += TO_LINEAR[data[i]] * k;
+      work[o + 1] += TO_LINEAR[data[i + 1]] * k;
+      work[o + 2] += TO_LINEAR[data[i + 2]] * k;
+      work[o + 3] += a;
+    }
+  }
+  for (let c = 0; c < count.length; c++) { const k = 1 / count[c]; work[c * 4] *= k; work[c * 4 + 1] *= k; work[c * 4 + 2] *= k; work[c * 4 + 3] *= k; }
+  const blurred = convolveSpans(work, sw, sh, aperture(R / f, fx.blades ?? 0, fx.rotation ?? 0));
+  const small = new Uint8ClampedArray(sw * sh * 4);
+  for (let i = 0; i < blurred.length; i += 4) {
+    const a = blurred[i + 3];
+    if (a <= 1e-4) continue;
+    small[i] = toSrgb(blurred[i] / a);
+    small[i + 1] = toSrgb(blurred[i + 1] / a);
+    small[i + 2] = toSrgb(blurred[i + 2] / a);
+    small[i + 3] = a * 255 + 0.5;
+  }
+  return f === 1 ? small : enlarge(small, sw, sh, w, h);
+}
+
+/**
+ * `tilt`: tilt-shift. Sharp within `width` of a line through `center` at
+ * `angle`, the blur growing over `falloff` beyond it to `radius`; with
+ * `saturate` for the toy-town look.
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'tilt' }} fx
+ * @param {any} ctx
+ * @returns {Uint8ClampedArray}
+ */
+export function tilt(img, fx, ctx) {
+  const { width: w, height: h } = img;
+  const sigma = px(fx.radius, ctx, img, '1.4vmin');
+  const band = px(fx.width, ctx, img, '8vmin');
+  const falloff = Math.max(1, px(fx.falloff, ctx, img, '22vmin'));
+  const [cx, cy] = pointPx(fx.center, img);
+  const a = ((fx.angle ?? 0) * Math.PI) / 180;
+  const nx = -Math.sin(a);
+  const ny = Math.cos(a);
+  const src = premultiplied(img);
+  // A sharp level and three blurred ones (worked small: a wide blur has no
+  // detail to lose); each pixel mixes the two either side of its blur,
+  // read straight from the small copies.
+  const steps = [0, 0.25, 0.5, 1];
+  const levels = steps.slice(1).map((k) => {
+    const f = Math.max(1, Math.min(8, Math.floor((sigma * k) / 6)));
+    const small = f > 1 ? shrink(src, w, h, f) : { data: new Uint8ClampedArray(src), width: w, height: h };
+    gaussian(small.data, small.width, small.height, 4, (sigma * k) / f);
+    return { ...small, f };
+  });
+  const out = new Uint8ClampedArray(src.length);
+  const lo = new Float32Array(4);
+  const hi = new Float32Array(4);
+  /** @param {number} k @param {number} x @param {number} y @param {Float32Array} to */
+  const read = (k, x, y, to) => {
+    if (k === 0) { const i = (y * w + x) * 4; to[0] = src[i]; to[1] = src[i + 1]; to[2] = src[i + 2]; to[3] = src[i + 3]; return; }
+    const l = levels[k - 1];
+    bilinear(l.data, l.width, l.height, (x + 0.5) / l.f - 0.5, (y + 0.5) / l.f - 0.5, to, 0);
+  };
+  const sat = fx.saturate ?? 1;
+  for (let y = 0, i = 0; y < h; y++) {
+    for (let x = 0; x < w; x++, i += 4) {
+      const d = Math.abs((x + 0.5 - cx) * nx + (y + 0.5 - cy) * ny);
+      const s = smoothstep(band, band + falloff, d);
+      if (s <= 0) { out[i] = src[i]; out[i + 1] = src[i + 1]; out[i + 2] = src[i + 2]; out[i + 3] = src[i + 3]; } else {
+        let k = 1;
+        while (k < steps.length - 1 && steps[k] < s) k++;
+        const t = (s - steps[k - 1]) / (steps[k] - steps[k - 1]);
+        read(k - 1, x, y, lo);
+        read(k, x, y, hi);
+        for (let c = 0; c < 4; c++) out[i + c] = lo[c] + (hi[c] - lo[c]) * t;
+      }
+      if (sat !== 1) {
+        const l = 0.2126 * out[i] + 0.7152 * out[i + 1] + 0.0722 * out[i + 2];
+        out[i] = l + (out[i] - l) * sat;
+        out[i + 1] = l + (out[i + 1] - l) * sat;
+        out[i + 2] = l + (out[i + 2] - l) * sat;
+      }
+    }
+  }
+  return img.opaque ? out : unpremultiply(out);
+}

package/src/effects/light.d.ts

@@ -0,0 +1,10 @@
+// Blur, shadow, glow and die-cut borders.
+import type { Effect } from './index.js';
+import type { RenderContext } from '../render/context.js';
+
+/** The `blur` effect's filter primitives. */
+export function blur(fx: Extract<Effect, { kind: 'blur' }>, ctx: RenderContext): string;
+/** The `shadow | glow` effect's filter primitives. */
+export function shadow(fx: Extract<Effect, { kind: 'shadow' | 'glow' }>, ctx: RenderContext): string;
+/** The `border` effect's filter primitives. */
+export function border(fx: Extract<Effect, { kind: 'border' }>, ctx: RenderContext): string;