@arraypress/covers 1.0.0 → 1.1.0

package/src/effects/screen.js

@@ -0,0 +1,212 @@
+/**
+ * Screens and signals: `scanlines` (a filter: dark lines across the
+ * layer), and on pixels `crt` (a tube's RGB phosphor mask, scanlines and
+ * curvature), `vhs` (tape: smeared, shifted chroma, line jitter, tracking
+ * noise, snow) and `jpeg` (real JPEG compression, as crunchy as you like,
+ * blocks at any size).
+ *
+ * @module effects/screen
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { encodePng, pngUri } from '../png.js';
+import { createRng } from '../rng.js';
+import { jpegRoundTrip } from '../raster/index.js';
+import { px, seedFor, bilinear, shrink, gaussian, smoothstep, hash2 } from './buffer.js';
+
+/**
+ * `scanlines`: dark lines every `spacing` (a length), `thickness` of each
+ * period (0–1), `amount` dark (0–1), across the layer.
+ *
+ * @param {import('./index.js').Effect & { kind: 'scanlines' }} fx
+ * @param {import('../render/context.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function scanlines(fx, ctx) {
+  const { width: W, height: H } = ctx;
+  const spacing = Math.max(0.5, len(fx.spacing, ctx.canvas, '0.5vmin'));
+  const t = Math.min(0.95, Math.max(0.05, fx.thickness ?? 0.45));
+  const a = fx.amount ?? 0.45;
+  // One column of the pattern, eight samples a line, stretched across.
+  const rows = Math.min(8192, Math.max(2, Math.ceil((H / spacing) * 8)));
+  const col = new Uint8Array(rows);
+  for (let y = 0; y < rows; y++) {
+    const p = (((y + 0.5) * H) / rows / spacing) % 1;
+    const d = Math.abs(p - 0.5) * 2;
+    col[y] = Math.round(255 * (1 - a * (1 - smoothstep(t - 0.12, t + 0.12, d))));
+  }
+  return `<feImage${attrs({ href: pngUri(encodePng(col, 1, rows, 1)), x: 0, y: 0, width: W, height: H, preserveAspectRatio: 'none', result: 'sl' })}/>`
+    + '<feBlend in="sl" in2="SourceGraphic" mode="multiply"/><feComposite in2="SourceAlpha" operator="in"/>';
+}
+
+/**
+ * `crt`: a cathode-ray tube. `mask` (`'aperture'`: vertical RGB stripes,
+ * `'shadow'`: staggered triads), its triad `size` (a length), `amount`
+ * (0–1), `scanlines` (0–1) and barrel `curvature` (0–1, with the corners
+ * going dark).
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'crt' }} fx
+ * @param {any} ctx
+ * @returns {Uint8ClampedArray}
+ */
+export function crt(img, fx, ctx) {
+  const { data, width: w, height: h } = img;
+  const size = Math.max(3, px(fx.size, ctx, img, '0.45vmin'));
+  const amount = fx.amount ?? 0.75;
+  const lines = fx.scanlines ?? 0.45;
+  const curve = fx.curvature ?? 0;
+  const shadow = (fx.mask ?? 'aperture') === 'shadow';
+  if (!['aperture', 'shadow'].includes(fx.mask ?? 'aperture')) throw new TypeError(`Unknown crt mask "${fx.mask}" (aperture, shadow)`);
+  const out = new Uint8ClampedArray(data.length);
+  const tmp = new Float32Array(4);
+  const cx = (w - 1) / 2;
+  const cy = (h - 1) / 2;
+  const k = curve * 0.25;
+  // Mask brightness lost, given back so the mean holds.
+  const gain = 1 / (1 - amount * 0.55) / (1 - lines * 0.3);
+  const lineH = size;
+  for (let y = 0, o = 0; y < h; y++) {
+    for (let x = 0; x < w; x++, o += 4) {
+      let sx = x;
+      let sy = y;
+      let edge = 1;
+      if (k) {
+        const u = (x - cx) / cx;
+        const v = (y - cy) / cy;
+        const r2 = u * u + v * v;
+        sx = cx + u * (1 + k * r2) * cx;
+        sy = cy + v * (1 + k * r2) * cy;
+        if (sx < 0 || sy < 0 || sx > w - 1 || sy > h - 1) { out[o + 3] = 255; continue; }
+        edge = smoothstep(0, 0.04, Math.min(sx / w, sy / h, 1 - sx / w, 1 - sy / h) * 4);
+      }
+      bilinear(data, w, h, sx, sy, tmp, 0);
+      // Which phosphor this pixel is: a third of a triad each.
+      const col = (x / size) * 3;
+      const row = shadow ? y / lineH + (Math.floor(x / size) % 2) * 0.5 : y / lineH;
+      const ph = col - Math.floor(col);
+      const sub = Math.floor(col) % 3;
+      const soft = 1 - Math.abs(ph - 0.5) * 2 * 0.5;
+      const scan = 1 - lines * (1 - Math.sin(Math.PI * (row - Math.floor(row))) ** 2);
+      for (let c = 0; c < 3; c++) {
+        const m = c === sub ? soft : 1 - amount;
+        out[o + c] = tmp[c] * (1 - amount + amount * m) * scan * gain * edge;
+      }
+      out[o + 3] = tmp[3];
+    }
+  }
+  return out;
+}
+
+/**
+ * `vhs`: a tape played back. Chroma smeared by `bleed` and shifted by
+ * `shift` (lengths), lines jittered (`jitter`, a length), a tracking band
+ * of torn lines (`tracking`, 0–1), `noise` (0–1) and a little softness;
+ * seeded.
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'vhs' }} fx
+ * @param {any} ctx
+ * @returns {Uint8ClampedArray}
+ */
+export function vhs(img, fx, ctx) {
+  const { data, width: w, height: h } = img;
+  const seed = seedFor(fx, ctx);
+  const rng = createRng(`vhs:${seed}`);
+  const bleed = px(fx.bleed, ctx, img, '0.9vmin');
+  const shift = px(fx.shift, ctx, img, '0.35vmin');
+  const jitter = px(fx.jitter, ctx, img, '0.12vmin');
+  const tracking = fx.tracking ?? 0.5;
+  const noise = fx.noise ?? 0.35;
+  // YIQ: luma kept sharp-ish, chroma smeared along the line.
+  const Y = new Float32Array(w * h);
+  const IQ = new Float32Array(w * h * 2);
+  for (let p = 0, i = 0; p < Y.length; p++, i += 4) {
+    const r = data[i];
+    const g = data[i + 1];
+    const b = data[i + 2];
+    Y[p] = 0.299 * r + 0.587 * g + 0.114 * b;
+    IQ[p * 2] = 0.596 * r - 0.274 * g - 0.322 * b;
+    IQ[p * 2 + 1] = 0.211 * r - 0.523 * g + 0.312 * b;
+  }
+  gaussian(Y, w, h, 1, px('0.06vmin', ctx, img, 0), 0);
+  gaussian(IQ, w, h, 2, Math.max(1, bleed), 0);
+  // Per-line offsets: a gentle wobble, and a tracking band that tears.
+  const offs = new Float32Array(h);
+  const band = rng.range(0.62, 0.9) * h;
+  const bandH = h * (0.04 + 0.08 * tracking);
+  for (let y = 0; y < h; y++) {
+    let o = (hash2(y >> 1, 0, seed) - 0.5) * 2 * jitter + Math.sin(y / (h / 7) + rng.next() * 0.02) * jitter * 0.5;
+    const t = Math.abs(y - band) / bandH;
+    if (tracking && t < 1) o += (1 - t) ** 2 * tracking * px('4vmin', ctx, img, 0) * (hash2(y >> 2, 1, seed) - 0.3);
+    offs[y] = o;
+  }
+  const out = new Uint8ClampedArray(data.length);
+  for (let y = 0; y < h; y++) {
+    const o = offs[y];
+    const t = Math.abs(y - band) / bandH;
+    const torn = tracking && t < 1 ? (1 - t) * tracking : 0;
+    for (let x = 0; x < w; x++) {
+      const sx = Math.min(w - 1, Math.max(0, x - o));
+      const x0 = sx | 0;
+      const f = sx - x0;
+      const x1 = Math.min(w - 1, x0 + 1);
+      const yv = Y[y * w + x0] * (1 - f) + Y[y * w + x1] * f;
+      const cxp = Math.min(w - 1, Math.max(0, sx - shift));
+      const c0 = cxp | 0;
+      const cf = cxp - c0;
+      const c1 = Math.min(w - 1, c0 + 1);
+      const iv = IQ[(y * w + c0) * 2] * (1 - cf) + IQ[(y * w + c1) * 2] * cf;
+      const qv = IQ[(y * w + c0) * 2 + 1] * (1 - cf) + IQ[(y * w + c1) * 2 + 1] * cf;
+      // Snow: fine noise everywhere, white streaks in the torn band.
+      let n = (hash2(x, y, seed) - 0.5) * 60 * noise;
+      if (torn && hash2(x >> 3, y, seed + 1) > 1 - torn * 0.35) n += 160 * torn * hash2(x, y, seed + 2);
+      const yy = yv + n;
+      const i = (y * w + x) * 4;
+      out[i] = yy + 0.956 * iv + 0.621 * qv;
+      out[i + 1] = yy - 0.272 * iv - 0.647 * qv;
+      out[i + 2] = yy - 1.106 * iv + 1.703 * qv;
+      out[i + 3] = data[i + 3];
+    }
+  }
+  return out;
+}
+
+/**
+ * `jpeg`: through a real JPEG encoder at `quality` (1–100) and back,
+ * `passes` times (each re-save slightly shifted, as images degrade when
+ * passed round), its 8-pixel blocks drawn `block` big (a length: bigger
+ * is crunchier), colour subsampled unless `subsample: false`.
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'jpeg' }} fx
+ * @param {any} ctx
+ * @returns {Promise<import('./pixels.js').PixelResult | Uint8ClampedArray>}
+ */
+export async function jpeg(img, fx, ctx) {
+  const { data, width: w, height: h } = img;
+  const b = Math.max(1, Math.round(px(fx.block, ctx, img, '0.4vmin')));
+  const q = Math.max(1, Math.min(100, Math.round(fx.quality ?? 12)));
+  const passes = Math.max(1, Math.min(8, Math.round(fx.passes ?? 1)));
+  const small = b > 1 ? shrink(data, w, h, b) : { data: new Uint8ClampedArray(data), width: w, height: h };
+  let cur = small.data;
+  for (let p = 0; p < passes; p++) {
+    const got = await jpegRoundTrip(cur, small.width, small.height, Math.max(1, q - p * 2), fx.subsample !== false, ctx.sharp);
+    if (!got) return data;
+    // Later passes see the image a pixel over, so their blocks fall differently.
+    if (p < passes - 1) {
+      const shifted = new Uint8ClampedArray(got.length);
+      const sw = small.width;
+      for (let y = 0; y < small.height; y++) for (let x = 0; x < sw; x++) {
+        const s = (Math.min(small.height - 1, y + 1) * sw + Math.min(sw - 1, x + 1)) * 4;
+        shifted.set(got.subarray(s, s + 4), (y * sw + x) * 4);
+      }
+      cur = shifted;
+    } else cur = got;
+  }
+  for (let i = 3; i < cur.length; i += 4) cur[i] = 255;
+  if (b === 1) return cur;
+  // Embedded at one pixel per JPEG pixel, scaled up crisp.
+  return { data: cur, width: small.width, height: small.height, pixelated: true };
+}

package/src/effects/sort.d.ts

@@ -0,0 +1,8 @@
+// Pixel sorting and pixel stretch.
+import type { Effect } from './index.js';
+import type { Pixels } from './buffer.js';
+
+/** `sort`, on pixels. */
+export function sort(img: Pixels, fx: Extract<Effect, { kind: 'sort' }>, ctx: object): Uint8ClampedArray;
+/** `stretch`, on pixels. */
+export function stretch(img: Pixels, fx: Extract<Effect, { kind: 'stretch' }>): Uint8ClampedArray;

package/src/effects/sort.js

@@ -0,0 +1,125 @@
+/**
+ * Glitch-art pixel moves: `sort` (runs of pixels within a brightness
+ * range sorted along rows or columns, Kim Asendorf's pixel sorting) and
+ * `stretch` (one row or column smeared to the edge).
+ *
+ * @module effects/sort
+ */
+
+import { seedFor, luma } from './buffer.js';
+import { createRng } from '../rng.js';
+
+/**
+ * A sort key, 0–255: luminance, hue or saturation.
+ *
+ * @param {Uint8ClampedArray} d
+ * @param {number} i
+ * @param {'luma' | 'hue' | 'saturation'} by
+ * @returns {number}
+ */
+function keyOf(d, i, by) {
+  if (by === 'luma') return luma(d, i) | 0;
+  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);
+  if (by === 'saturation') return max ? ((255 * (max - min)) / max) | 0 : 0;
+  if (max === min) return 0;
+  const c = max - min;
+  const hh = max === r ? ((g - b) / c + 6) % 6 : max === g ? (b - r) / c + 2 : (r - g) / c + 4;
+  return ((hh / 6) * 255) | 0;
+}
+
+/**
+ * `sort`: along `direction` (`'horizontal'` rows, `'vertical'` columns),
+ * every run of pixels whose luminance lies within `threshold` (`[lo, hi]`,
+ * 0–1) is sorted by `by` (`'luma'`, `'hue'`, `'saturation'`), dark to
+ * light unless `reverse`. `length` (0–1 of the line) breaks long runs at
+ * seeded points.
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'sort' }} fx
+ * @param {any} ctx
+ * @returns {Uint8ClampedArray}
+ */
+export function sort(img, fx, ctx) {
+  const { data, width: w, height: h } = img;
+  const vertical = (fx.direction ?? 'horizontal') === 'vertical';
+  const by = fx.by ?? 'luma';
+  if (!['luma', 'hue', 'saturation'].includes(by)) throw new TypeError(`Unknown sort key "${by}" (luma, hue, saturation)`);
+  const [lo, hi] = (fx.threshold ?? [0.25, 0.85]).map((v) => v * 255);
+  const rng = createRng(`sort:${seedFor(fx, ctx)}`);
+  const n = vertical ? h : w;
+  const lines = vertical ? w : h;
+  const cap = fx.length ? Math.max(2, fx.length * n) : Infinity;
+  const out = new Uint8ClampedArray(data);
+  const u32 = new Uint32Array(out.buffer);
+  const keys = new Uint8Array(n);
+  const inside = new Uint8Array(n);
+  const px = new Uint32Array(n);
+  const counts = new Uint32Array(256);
+  const buf = new Uint32Array(n);
+  for (let l = 0; l < lines; l++) {
+    const at = (/** @type {number} */ k) => (vertical ? k * w + l : l * w + k);
+    for (let k = 0; k < n; k++) {
+      const p = at(k);
+      px[k] = u32[p];
+      const lu = luma(out, p * 4);
+      inside[k] = lu >= lo && lu <= hi ? 1 : 0;
+      keys[k] = inside[k] ? keyOf(out, p * 4, by) : 0;
+    }
+    let k = 0;
+    while (k < n) {
+      if (!inside[k]) { k++; continue; }
+      // A run: as far as the range holds, or the seeded cap.
+      const limit = cap === Infinity ? n : k + Math.max(2, Math.round(cap * rng.range(0.4, 1)));
+      let e = k;
+      while (e < n && e < limit && inside[e]) e++;
+      // Counting sort of [k, e).
+      counts.fill(0);
+      for (let j = k; j < e; j++) counts[keys[j]]++;
+      let acc = 0;
+      for (let c = 0; c < 256; c++) { const t = counts[c]; counts[c] = acc; acc += t; }
+      for (let j = k; j < e; j++) buf[counts[keys[j]]++] = px[j];
+      const len = e - k;
+      for (let j = 0; j < len; j++) u32[at(k + j)] = buf[fx.reverse ? len - 1 - j : j];
+      k = e;
+    }
+  }
+  return out;
+}
+
+/**
+ * `stretch`: the row or column at `at` (0–1) smeared toward `direction`
+ * (`'down'`, `'up'`, `'left'`, `'right'`) for `length` of the way to the
+ * edge (default all of it), fading out by `fade` (0–1).
+ *
+ * @param {import('./buffer.js').Pixels} img
+ * @param {import('./index.js').Effect & { kind: 'stretch' }} fx
+ * @returns {Uint8ClampedArray}
+ */
+export function stretch(img, fx) {
+  const { data, width: w, height: h } = img;
+  const dir = fx.direction ?? 'down';
+  if (!['down', 'up', 'left', 'right'].includes(dir)) throw new TypeError(`Unknown stretch direction "${dir}" (down, up, left, right)`);
+  const vertical = dir === 'down' || dir === 'up';
+  const n = vertical ? h : w;
+  const lines = vertical ? w : h;
+  const from = Math.min(n - 1, Math.max(0, Math.round((fx.at ?? 0.5) * (n - 1))));
+  const sign = dir === 'down' || dir === 'right' ? 1 : -1;
+  const room = sign > 0 ? n - 1 - from : from;
+  const reach = Math.round(room * Math.min(1, Math.max(0, fx.length ?? 1)));
+  const fade = Math.min(1, Math.max(0, fx.fade ?? 0));
+  const out = new Uint8ClampedArray(data);
+  for (let l = 0; l < lines; l++) {
+    const s = (vertical ? from * w + l : l * w + from) * 4;
+    for (let k = 1; k <= reach; k++) {
+      const pos = from + sign * k;
+      const o = (vertical ? pos * w + l : l * w + pos) * 4;
+      const t = fade * (k / Math.max(1, reach));
+      for (let c = 0; c < 4; c++) out[o + c] = data[s + c] + (data[o + c] - data[s + c]) * t;
+    }
+  }
+  return out;
+}

package/src/effects/symmetry.d.ts

@@ -0,0 +1,6 @@
+// Mirror, as copies of the markup.
+import type { Effect } from './index.js';
+import type { Markup } from '../render/context.js';
+
+/** `mirror`: one side reflected onto the other. */
+export function mirror(fx: Extract<Effect, { kind: 'mirror' }>, m: Markup, ctx: { width: number; height: number; res?: number }, id: string): Markup;

package/src/effects/symmetry.js

@@ -0,0 +1,74 @@
+/**
+ * `mirror`, drawn as copies of the layer's own markup (so vector art
+ * stays vector): one half reflected onto the other, or one quarter onto
+ * all four. (`kaleidoscope` is on pixels, in `distort.js`: its wedges
+ * need the frame filled past the layer's edge.)
+ *
+ * @module effects/symmetry
+ */
+
+import { attrs, num } from '../svg.js';
+import { fraction } from './buffer.js';
+
+/**
+ * A copy of the source drawn through a transform, clipped to a polygon.
+ *
+ * @param {string} src - The source's id.
+ * @param {string} clip - The clip path's id.
+ * @param {string} [transform]
+ * @returns {string}
+ */
+const copy = (src, clip, transform) => `<g clip-path="url(#${clip})"><use${attrs({ href: `#${src}`, transform })}/></g>`;
+
+/** @param {string} id @param {[number, number][]} pts @returns {string} */
+const clipPath = (id, pts) => `<clipPath${attrs({ id, clipPathUnits: 'userSpaceOnUse' })}><polygon points="${pts.map(([x, y]) => `${num(x, 3)},${num(y, 3)}`).join(' ')}"/></clipPath>`;
+
+/**
+ * `mirror`: `keep` one side (`'left'`, `'right'`, `'top'`, `'bottom'`) and
+ * reflect it onto the other across a line at `at` (0–1), or a quarter
+ * (`'top-left'`, …) onto all four.
+ *
+ * @param {import('./index.js').Effect & { kind: 'mirror' }} fx
+ * @param {{ defs: string, body: string }} m
+ * @param {any} ctx
+ * @param {string} id
+ * @returns {{ defs: string, body: string }}
+ */
+export function mirror(fx, m, ctx, id) {
+  const keep = fx.keep ?? 'left';
+  const KEEP = ['left', 'right', 'top', 'bottom', 'top-left', 'top-right', 'bottom-left', 'bottom-right'];
+  if (!KEEP.includes(keep)) throw new TypeError(`Unknown mirror side "${keep}" (${KEEP.join(', ')})`);
+  const { width: W, height: H } = ctx;
+  const [fx0, fy0] = fraction(/** @type {any} */ (fx.at), [0.5, 0.5]);
+  const ax = (typeof fx.at === 'number' ? fx.at : fx0) * W;
+  const ay = (typeof fx.at === 'number' ? fx.at : fy0) * H;
+  const P = Math.max(W, H);
+  // A hair of overlap past the line hides the anti-aliased seam.
+  const e = 0.5 / ((ctx.res ?? 1) || 1);
+  const sx = keep.includes('left') ? -1 : keep.includes('right') ? 1 : 0;
+  const sy = keep.includes('top') ? -1 : keep.includes('bottom') ? 1 : 0;
+  /** @param {number} qx @param {number} qy @returns {[number, number][]} The quadrant (or half) on that side. */
+  const region = (qx, qy) => {
+    const x0 = qx < 0 ? -P : qx > 0 ? ax - e : -P;
+    const x1 = qx < 0 ? ax + e : qx > 0 ? W + P : W + P;
+    const y0 = qy < 0 ? -P : qy > 0 ? ay - e : -P;
+    const y1 = qy < 0 ? ay + e : qy > 0 ? H + P : H + P;
+    return [[x0, y0], [x1, y0], [x1, y1], [x0, y1]];
+  };
+  const src = `${id}s`;
+  let defs = `${m.defs}<g id="${src}">${m.body}</g>`;
+  let body = '';
+  /** @type {[number, number][]} */
+  const flips = [[1, 1]];
+  if (sx) flips.push([-1, 1]);
+  if (sy) flips.push([1, -1]);
+  if (sx && sy) flips.push([-1, -1]);
+  // Mirrored copies first, the kept side on top.
+  flips.reverse().forEach(([fxs, fys], i) => {
+    const clip = `${id}c${i}`;
+    defs += clipPath(clip, region(sx * fxs, sy * fys));
+    const t = fxs === 1 && fys === 1 ? undefined : `translate(${num(fxs === -1 ? 2 * ax : 0, 3)} ${num(fys === -1 ? 2 * ay : 0, 3)}) scale(${fxs} ${fys})`;
+    body += copy(src, clip, t);
+  });
+  return { defs, body };
+}

package/src/effects/tile.d.ts

@@ -0,0 +1,7 @@
+// Tile paints.
+import type { TilePaint } from './paint.js';
+
+/** Tile kinds. */
+export const TILES: readonly ('checker' | 'stripes' | 'dots' | 'grid' | 'custom')[];
+/** A tile paint as a `<pattern>` and its fill value. */
+export function tile(v: TilePaint, o: { id: string; box: { x: number; y: number; width: number; height: number }; canvas: { width: number; height: number } }): { defs: string; value: string };

package/src/effects/tile.js

@@ -0,0 +1,55 @@
+/**
+ * Tile paints: a pattern repeated over a shape (checker, stripes, dots,
+ * grid), or a custom tile of markup.
+ *
+ * @module effects/tile
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { toHex } from '../color.js';
+import { sanitize } from '../layers/svg.js';
+
+/** Tile kinds. */
+export const TILES = Object.freeze(['checker', 'stripes', 'dots', 'grid', 'custom']);
+
+/**
+ * A tile paint as a `<pattern>`: `{ type: 'tile', kind, size, colors: [ground, ink], ratio, angle, markup }`.
+ * `size` is one cell (a length, default `'4vmin'`); `ratio` the stripe,
+ * dot or line share of it; `angle` turns the pattern; a `custom` tile draws
+ * `markup` (sanitised) in a `size` square (or `[width, height]`). The
+ * pattern starts at the shape's top-left corner. `colors[0]` may be
+ * `'none'` for a transparent ground.
+ *
+ * @param {any} v
+ * @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 tile(v, o) {
+  const kind = v.kind ?? 'checker';
+  if (!TILES.includes(kind)) throw new TypeError(`Unknown tile kind "${kind}" (${TILES.join(', ')})`);
+  const [sw, sh] = Array.isArray(v.size) ? v.size.map((/** @type {any} */ s) => len(s, o.canvas)) : [len(v.size, o.canvas, '4vmin'), len(v.size, o.canvas, '4vmin')];
+  const [ground, ink] = [v.colors?.[0] ?? '#ffffff', v.colors?.[1] ?? '#111111'].map((c) => (c === 'none' ? 'none' : toHex(c)));
+  const ratio = v.ratio ?? (kind === 'dots' ? 0.6 : kind === 'grid' ? 0.08 : 0.5);
+  let w = sw;
+  let h = sh;
+  let body = ground === 'none' ? '' : `<rect${attrs({ width: num(kind === 'checker' ? 2 * sw : sw, 4), height: num(kind === 'checker' ? 2 * sh : sh, 4), fill: ground })}/>`;
+  if (kind === 'checker') {
+    w = 2 * sw;
+    h = 2 * sh;
+    body += `<path${attrs({ d: `M0 0h${num(sw, 4)}v${num(sh, 4)}h${num(-sw, 4)}ZM${num(sw, 4)} ${num(sh, 4)}h${num(sw, 4)}v${num(sh, 4)}h${num(-sw, 4)}Z`, fill: ink })}/>`;
+  } else if (kind === 'stripes') {
+    body += `<rect${attrs({ width: num(sw * ratio, 4), height: num(sh, 4), fill: ink })}/>`;
+  } else if (kind === 'dots') {
+    body += `<ellipse${attrs({ cx: num(sw / 2, 4), cy: num(sh / 2, 4), rx: num((sw * ratio) / 2, 4), ry: num((sh * ratio) / 2, 4), fill: ink })}/>`;
+  } else if (kind === 'grid') {
+    body += `<path${attrs({ d: `M0 0H${num(sw, 4)}M0 0V${num(sh, 4)}`, stroke: ink, 'stroke-width': num(Math.min(sw, sh) * ratio * 2, 4), fill: 'none' })}/>`;
+  } else {
+    body += sanitize(String(v.markup ?? ''));
+  }
+  const turn = v.angle ? ` rotate(${num(v.angle, 3)})` : '';
+  return {
+    defs: `<pattern${attrs({ id: o.id, patternUnits: 'userSpaceOnUse', width: num(w, 4), height: num(h, 4), patternTransform: `translate(${num(o.box.x)} ${num(o.box.y)})${turn}` })}>${body}</pattern>`,
+    value: `url(#${o.id})`,
+  };
+}

package/src/effects/tone.d.ts

@@ -0,0 +1,16 @@
+// Tone and colour.
+import type { Effect } from './index.js';
+import type { RenderContext } from '../render/context.js';
+
+/** The `duotone` effect's filter primitives. */
+export function duotone(fx: Extract<Effect, { kind: 'duotone' }>, ctx: RenderContext): string;
+/** The `grayscale | levels` effect's filter primitives. */
+export function levels(fx: Extract<Effect, { kind: 'grayscale' | 'levels' }>, ctx: RenderContext): string;
+/** The `saturate` effect's filter primitives. */
+export function saturate(fx: Extract<Effect, { kind: 'saturate' }>, ctx: RenderContext): string;
+/** The `matrix` effect's filter primitives. */
+export function matrix(fx: Extract<Effect, { kind: 'matrix' }>, ctx: RenderContext): string;
+/** The `threshold` effect's filter primitives. */
+export function threshold(fx: Extract<Effect, { kind: 'threshold' }>, ctx: RenderContext): string;
+/** The `photocopy` effect's filter primitives. */
+export function photocopy(fx: Extract<Effect, { kind: 'photocopy' }>, ctx: RenderContext): string;

package/src/effects/tone.js

@@ -0,0 +1,117 @@
+/**
+ * Tone and colour: duotone and tritone ramps, greyscale and levels,
+ * saturation, a raw colour matrix, a one-ink threshold, and a photo
+ * through a copier.
+ *
+ * @module effects/tone
+ */
+
+import { esc, num } from '../svg.js';
+import { LUMA, rgb, mat, flood, seedOf } from './util.js';
+
+/**
+ * A linear transfer on R, G and B.
+ *
+ * @param {number} slope @param {number} intercept
+ * @returns {string}
+ */
+const linear = (slope, intercept) => `<feComponentTransfer>${['R', 'G', 'B'].map((ch) => `<feFunc${ch} type="linear" slope="${num(slope, 3)}" intercept="${num(intercept, 3)}"/>`).join('')}</feComponentTransfer>`;
+
+/**
+ * `duotone`: greyscale, optional `contrast`, then a tone ramp through two or
+ * more `colors` (shadows first).
+ *
+ * @param {import('./index.js').Effect & { kind: 'duotone' }} fx
+ * @returns {string}
+ */
+export function duotone(fx) {
+  const cols = (fx.colors ?? ['#1b0d06', '#f6e6c4']).map(rgb);
+  const pre = fx.contrast != null ? linear(fx.contrast, (1 - fx.contrast) / 2) : '';
+  return `<feColorMatrix type="saturate" values="0"/>${pre}<feComponentTransfer>${['R', 'G', 'B'].map((ch, i) => `<feFunc${ch} type="table" tableValues="${cols.map((c) => num(c[i], 3)).join(' ')}"/>`).join('')}</feComponentTransfer>`;
+}
+
+/**
+ * `grayscale` and `levels`: a linear tone curve (`slope`, `intercept`, or
+ * `contrast` and `brightness`), greyscale first for `grayscale`.
+ *
+ * @param {import('./index.js').Effect & { kind: 'grayscale' | 'levels' }} fx
+ * @returns {string}
+ */
+export function levels(fx) {
+  const gray = fx.kind === 'grayscale';
+  if (fx.black != null || fx.white != null || fx.gamma != null || fx.output != null) return inputLevels(fx, gray);
+  const slope = fx.slope ?? fx.contrast ?? (gray ? 1 : 1.25);
+  const intercept = fx.intercept ?? (fx.brightness != null ? fx.brightness : fx.contrast != null ? (1 - fx.contrast) / 2 : gray ? 0 : -0.1);
+  return `${gray ? '<feColorMatrix type="saturate" values="0"/>' : ''}${slope !== 1 || intercept !== 0 ? linear(slope, intercept) : ''}`;
+}
+
+/**
+ * Photoshop's Levels: input `black` and `white` points (0–1), `gamma`
+ * for the midtones (above 1 lightens), and an `output` range.
+ *
+ * @param {any} fx
+ * @param {boolean} gray
+ * @returns {string}
+ */
+function inputLevels(fx, gray) {
+  const b = fx.black ?? 0;
+  const w = Math.max(b + 1e-3, fx.white ?? 1);
+  const [lo, hi] = fx.output ?? [0, 1];
+  const g = Math.max(0.01, fx.gamma ?? 1);
+  const funcs = (/** @type {string} */ f) => ['R', 'G', 'B'].map((ch) => `<feFunc${ch} ${f}/>`).join('');
+  return `${gray ? '<feColorMatrix type="saturate" values="0"/>' : ''}<feComponentTransfer>${funcs(`type="linear" slope="${num(1 / (w - b), 4)}" intercept="${num(-b / (w - b), 4)}"`)}</feComponentTransfer>`
+    + `<feComponentTransfer>${funcs(`type="gamma" amplitude="${num(hi - lo, 4)}" exponent="${num(1 / g, 4)}" offset="${num(lo, 4)}"`)}</feComponentTransfer>`;
+}
+
+/**
+ * `saturate`.
+ *
+ * @param {import('./index.js').Effect & { kind: 'saturate' }} fx
+ * @returns {string}
+ */
+export const saturate = (fx) => `<feColorMatrix type="saturate" values="${num(fx.amount ?? 1.4, 3)}"/>`;
+
+/**
+ * `matrix`: a raw 4×5 colour matrix.
+ *
+ * @param {import('./index.js').Effect & { kind: 'matrix' }} fx
+ * @returns {string}
+ */
+export const matrix = (fx) => `<feColorMatrix type="matrix" values="${esc(Array.isArray(fx.values) ? fx.values.join(' ') : String(fx.values))}"/>`;
+
+/**
+ * `threshold`: one ink where the image is darker than `level`, on `paper`
+ * (or transparent).
+ *
+ * @param {import('./index.js').Effect & { kind: 'threshold' }} fx
+ * @returns {string}
+ */
+export function threshold(fx) {
+  const ink = rgb(fx.ink ?? '#000000');
+  const steps = 64;
+  const cut = Math.round((fx.level ?? 0.5) * steps);
+  const table = (/** @type {number} */ a, /** @type {number} */ b) => Array.from({ length: steps }, (_, k) => num(k < cut ? a : b, 3)).join(' ');
+  if (fx.paper && fx.paper !== 'none') {
+    const paper = rgb(fx.paper);
+    const lum = `<feColorMatrix type="matrix" values="${mat([...LUMA, 0, 0, ...LUMA, 0, 0, ...LUMA, 0, 0, 0, 0, 0, 1, 0])}"/>`;
+    return `${lum}<feComponentTransfer>${['R', 'G', 'B'].map((ch, i) => `<feFunc${ch} type="discrete" tableValues="${table(ink[i], paper[i])}"/>`).join('')}</feComponentTransfer><feComposite in2="SourceAlpha" operator="in"/>`;
+  }
+  return `<feColorMatrix type="matrix" values="${flood(fx.ink ?? '#000000', [...LUMA, 0, 0])}"/><feComponentTransfer><feFuncA type="discrete" tableValues="${table(1, 0)}"/></feComponentTransfer><feComposite in2="SourceAlpha" operator="in"/>`;
+}
+
+/**
+ * `photocopy`: a photo through a copier, dark becoming solid `ink` with a
+ * noisy hard threshold.
+ *
+ * @param {import('./index.js').Effect & { kind: 'photocopy' }} fx
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function photocopy(fx, ctx) {
+  const gain = fx.contrast ?? 0.5;
+  const noise = fx.noise ?? 0.9;
+  return `<feColorMatrix in="SourceGraphic" type="matrix" values="${mat([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -gain, -gain, -gain, 0, 0.75 + gain + (fx.lift ?? 0)])}" result="ink"/>`
+    + `<feTurbulence type="fractalNoise" baseFrequency="${num(fx.frequency ?? 0.85, 3)}" seed="${seedOf(ctx, fx)}" result="n"/><feColorMatrix in="n" type="matrix" values="${mat([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, noise, -noise / 2])}" result="nn"/>`
+    + '<feComposite in="ink" in2="nn" operator="arithmetic" k2="1" k3="1"/><feComponentTransfer><feFuncA type="discrete" tableValues="0 0 1 1"/></feComponentTransfer>'
+    + `<feColorMatrix type="matrix" values="${flood(fx.ink ?? '#16040d')}"/><feComposite in2="SourceAlpha" operator="in"/>`;
+}

package/src/effects/transform.d.ts

@@ -0,0 +1,35 @@
+// A layer's `transform` option as an SVG transform.
+import type { Length } from '../index.js';
+
+/** A transform any layer takes (about `origin`, default the canvas centre). */
+export interface LayerTransform {
+  translate?: [Length, Length] | { x?: Length; y?: Length };
+  /** Degrees. */
+  rotate?: number;
+  scale?: number | [number, number];
+  skewX?: number;
+  skewY?: number;
+  /** `'x'` flips left–right, `'y'` top–bottom. */
+  mirror?: 'x' | 'y' | 'both';
+  /** `[x, y]` px, or `'center'`. */
+  origin?: [Length, Length] | { x?: Length; y?: Length } | 'center';
+}
+
+
+/** A `transform` option as an SVG transform string (a string is used as written). */
+export function transformAttr(t: LayerTransform | string | undefined, canvas: { width: number; height: number }): string | undefined;
+
+/** An affine matrix `[a, b, c, d, e, f]`, as SVG's `matrix()`. */
+export type Affine = [number, number, number, number, number, number];
+/** A transform (string or object form) as one matrix. */
+export function transformMatrix(t: LayerTransform | string | undefined, canvas: { width: number; height: number }): Affine;
+/** How much a matrix enlarges what it draws: smallest and largest stretch, and their geometric mean. */
+export function stretchOf(m: Affine): { min: number; max: number; mean: number };
+/** The inverse of an affine matrix. */
+export function invert(m: Affine): Affine;
+/** A point through an affine matrix. */
+export function apply(m: Affine, x: number, y: number): [number, number];
+/** The identity matrix. */
+export const IDENTITY: Readonly<Affine>;
+/** `m × n`: `n` applied first, in `m`'s space. */
+export function compose(m: Affine, n: Affine): Affine;