@arraypress/covers 1.0.0 → 1.1.0

package/src/layers/shape.js

@@ -0,0 +1,115 @@
+/**
+ * The `shape` layer.
+ *
+ * @module layers/shape
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { toHex } from '../color.js';
+import { paint } from '../effects/paint.js';
+import { presetStrokes } from '../effects/paint-presets.js';
+import { wrap, pos } from './util.js';
+import { geometry } from './geometry.js';
+import { soften } from './soft.js';
+
+/** Kinds drawn around a centre, whose `rotate` turns their points (about the centre). */
+const POLAR = ['star', 'burst', 'scallop', 'rays', 'sector'];
+
+/** Kinds that are lines unless closed: no fill by default. */
+const isOpen = (/** @type {any} */ s) => s.kind === 'line' || s.kind === 'polyline' || (s.kind === 'wave' && !s.band) || (s.kind === 'arch' && s.open);
+
+/**
+ * `shape` — one exact shape, or `items` of them: rectangles (with deckled,
+ * torn, zigzag or wavy `edge`s), circles, ellipses, lines, polygons, stars,
+ * bursts, scallops, rays, rings, sectors, arches (open: an arc), waves, raw
+ * paths and the print format's `cut`. Each takes `fill` and `stroke` (a
+ * colour, a gradient, a tile or a preset), `strokeWidth`, `dash`,
+ * `dashOffset`, `linecap`, `linejoin`, `fillRule`, `opacity`, `rotate`
+ * (about its centre, or `origin`), `soft` (a blur, drawn padded so it never
+ * shows a square edge) and `strokes` (stacked keylines, widest first).
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {Promise<import('../layers.js').Markup>}
+ */
+export async function shape(layer, ctx) {
+  const items = layer.items ?? [layer];
+  let defs = '';
+  let body = '';
+  for (let i = 0; i < items.length; i++) {
+    const raw = items[i];
+    const s = layer.items ? { fill: layer.fill, stroke: layer.stroke, strokeWidth: layer.strokeWidth, dash: layer.dash, dashOffset: layer.dashOffset, linecap: layer.linecap, linejoin: layer.linejoin, strokes: layer.strokes, soft: layer.soft, ...raw } : raw;
+    const polar = POLAR.includes(s.kind) && s.origin == null;
+    const g = /** @type {any} */ (geometry(polar ? s : { ...s, rotate: undefined }, ctx));
+    const open = g.el ?? `<path d="${g.d}"`;
+    const fp = paint(s.fill, isOpen(s) ? 'none' : ctx.palette.text, { id: `${ctx.id}s${i}f`, box: g.box, canvas: ctx.canvas });
+    const sp = s.stroke ? paint(s.stroke, 'none', { id: `${ctx.id}s${i}k`, box: g.box, canvas: ctx.canvas }) : null;
+    let own = fp.defs + (sp?.defs ?? '');
+    const sw = s.strokeWidth != null ? len(s.strokeWidth, ctx.canvas) : sp ? len('0.2vmin', ctx.canvas) : undefined;
+    const tr = [rotation(s, g, ctx, polar), g.transform].filter(Boolean).join(' ') || undefined;
+    const common = { 'fill-rule': s.fillRule, opacity: s.opacity != null && s.opacity < 1 ? s.opacity : undefined, transform: tr };
+    let markup = '';
+    const strokes = s.strokes ?? presetStrokes(s.fill);
+    if (strokes) {
+      const sorted = [...strokes].sort((a, b) => len(b.width, ctx.canvas) - len(a.width, ctx.canvas));
+      for (const k of sorted) markup += `${open}${attrs({ fill: 'none', stroke: toHex(k.color), 'stroke-width': len(k.width, ctx.canvas), 'stroke-linejoin': 'round', 'stroke-dasharray': k.dash ? dashArray(k.dash, len(k.width, ctx.canvas), ctx) : undefined, ...common })}/>`;
+    }
+    markup += `${open}${attrs({ fill: fp.value, stroke: sp?.value, 'stroke-width': sp ? sw : undefined, 'stroke-dasharray': s.dash ? dashArray(s.dash, sw ?? 1, ctx) : undefined, 'stroke-dashoffset': s.dash && s.dashOffset != null ? len(s.dashOffset, ctx.canvas) : undefined, 'stroke-linecap': s.linecap ?? (s.dash === 'dotted' ? 'round' : undefined), 'stroke-linejoin': s.linejoin, ...common })}/>`;
+    if (s.soft) {
+      // The blur's reach, round the shape's bounds (turned, when it's turned).
+      const soft = await soften({ defs: own, body: markup }, reach(g.box, s, tr ? s.rotate ?? 0 : 0, sw), len(s.soft, ctx.canvas), ctx, `${ctx.id}s${i}b`);
+      own = soft.defs;
+      markup = soft.body;
+    }
+    defs += own;
+    body += markup;
+  }
+  return { defs, body: wrap(layer, body) };
+}
+
+/**
+ * A dash pattern: `'dashed'`, `'dotted'`, or lengths `[on, off, …]`.
+ *
+ * @param {any} dash @param {number} width - The stroke width (dashed and dotted scale with it).
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+export function dashArray(dash, width, ctx) {
+  if (Array.isArray(dash)) return dash.map((/** @type {any} */ d) => num(len(d, ctx.canvas))).join(' ');
+  return dash === 'dotted' ? `0 ${num(width * 2.4)}` : `${num(width * 3)} ${num(width * 2.4)}`;
+}
+
+/**
+ * The rotation of a shape: about its centre, or `origin` (`[x, y]`, px or
+ * `'%'`). Polar kinds turn their points about the centre instead.
+ *
+ * @param {any} s @param {{ box: { x: number, y: number, width: number, height: number } }} g
+ * @param {import('../layers.js').RenderContext} ctx @param {boolean} polar
+ * @returns {string | undefined}
+ */
+function rotation(s, g, ctx, polar) {
+  if (!s.rotate || polar) return undefined;
+  const [ox, oy] = s.origin != null
+    ? (Array.isArray(s.origin) ? [pos(s.origin[0], 'x', ctx.canvas), pos(s.origin[1], 'y', ctx.canvas)] : [pos(s.origin.x, 'x', ctx.canvas), pos(s.origin.y, 'y', ctx.canvas)])
+    : [g.box.x + g.box.width / 2, g.box.y + g.box.height / 2];
+  return `rotate(${num(s.rotate, 3)} ${num(ox)} ${num(oy)})`;
+}
+
+/**
+ * The box a shape can paint in: its bounds (turned, when turned about its
+ * centre) plus its stroke.
+ *
+ * @param {{ x: number, y: number, width: number, height: number }} box
+ * @param {any} s @param {number} rotate @param {number | undefined} sw
+ * @returns {{ x: number, y: number, width: number, height: number }}
+ */
+function reach(box, s, rotate, sw) {
+  const a = (rotate * Math.PI) / 180;
+  const w = s.origin == null ? Math.abs(box.width * Math.cos(a)) + Math.abs(box.height * Math.sin(a)) : Math.hypot(box.width, box.height) * 2;
+  const h = s.origin == null ? Math.abs(box.width * Math.sin(a)) + Math.abs(box.height * Math.cos(a)) : w;
+  const stroke = (sw ?? 0) + Math.max(0, ...(s.strokes ?? []).map((/** @type {any} */ k) => (typeof k.width === 'number' ? k.width : 0)));
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  return { x: cx - w / 2 - stroke, y: cy - h / 2 - stroke, width: w + 2 * stroke, height: h + 2 * stroke };
+}

package/src/layers/soft.d.ts

@@ -0,0 +1,5 @@
+// Soft (blurred) shapes, drawn padded.
+import type { RenderContext, Markup } from '../render/context.js';
+
+/** Blur markup by `sigma`, padded 3σ round `box` (raster with sharp, else an SVG blur). */
+export function soften(m: Markup, box: { x: number; y: number; width: number; height: number }, sigma: number, ctx: RenderContext, id: string): Promise<Markup>;

package/src/layers/soft.js

@@ -0,0 +1,43 @@
+/**
+ * Soft shapes: a blur drawn padded, so a blurred orb never fades where it
+ * meets the canvas edge (librsvg clips a filter's input to the canvas) or
+ * shows the square edge of a filter region.
+ *
+ * @module layers/soft
+ */
+
+import { attrs, num } from '../svg.js';
+import { toBase64 } from '../platform/bytes.js';
+
+/**
+ * Blur markup by `sigma` (px in the layer's units). In `renderImage`, the markup
+ * is drawn on its own padded canvas (3σ round `box`) at the resolution the
+ * blur needs (about four pixels per σ, never more than the output's), blurred
+ * there, and embedded as an image; elsewhere it's an SVG blur over a filter
+ * region padded the same way.
+ *
+ * @param {{ defs: string, body: string }} m
+ * @param {{ x: number, y: number, width: number, height: number }} box - What the markup paints.
+ * @param {number} sigma
+ * @param {import('../layers.js').RenderContext} ctx
+ * @param {string} id
+ * @returns {Promise<{ defs: string, body: string }>}
+ */
+export async function soften(m, box, sigma, ctx, id) {
+  const pad = 3 * sigma;
+  const r = { x: box.x - pad, y: box.y - pad, width: box.width + 2 * pad, height: box.height + 2 * pad };
+  // Pixels only for renderImage (an SVG keeps its blur as a filter).
+  const sharp = /** @type {any} */ (ctx).raster ? /** @type {any} */ (ctx.sharp) : undefined;
+  if (!sharp || sigma <= 0) {
+    if (sigma <= 0) return m;
+    const filter = `<filter${attrs({ id, filterUnits: 'userSpaceOnUse', ...r, 'color-interpolation-filters': 'sRGB' })}><feGaussianBlur stdDeviation="${num(sigma, 3)}"/></filter>`;
+    return { defs: m.defs + filter, body: `<g filter="url(#${id})">${m.body}</g>` };
+  }
+  const res = /** @type {any} */ (ctx).res ?? 1;
+  const ppu = Math.min(res, Math.max(4 / sigma, 64 / Math.max(r.width, r.height)));
+  const w = Math.max(1, Math.ceil(r.width * ppu));
+  const h = Math.max(1, Math.ceil(r.height * ppu));
+  const doc = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="${num(r.x, 4)} ${num(r.y, 4)} ${num(w / ppu, 4)} ${num(h / ppu, 4)}" preserveAspectRatio="none">${m.defs ? `<defs>${m.defs}</defs>` : ''}${m.body}</svg>`;
+  const png = await sharp(new TextEncoder().encode(doc)).blur(Math.max(0.3, sigma * ppu)).png().toBuffer();
+  return { defs: '', body: `<image${attrs({ x: r.x, y: r.y, width: num(w / ppu, 4), height: num(h / ppu, 4), preserveAspectRatio: 'none', href: `data:image/png;base64,${toBase64(png)}` })}/>` };
+}

package/src/layers/svg.d.ts

@@ -0,0 +1,23 @@
+// The `svg` layer.
+import type { Color, Length, BaseLayer, Anchor } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+
+/** `svg`: raw markup, the escape hatch. */
+export interface SvgLayer extends BaseLayer {
+  type: 'svg';
+  /** Tokens: `{{@accent}}`, `{{@colors.1}}`, `{{@width}}`, `{{id}}`, `{{seed}}`; in JSON recipes `{{title}}` or any option. */
+  markup: string;
+  defs?: string;
+  viewBox?: [number, number, number, number];
+  x?: Length | `${number}%`; y?: Length | `${number}%`; width?: Length | `${number}%`; height?: Length | `${number}%`;
+  fit?: 'contain' | 'cover' | 'stretch';
+  align?: string;
+}
+
+
+/** Strip scripts, foreignObject, event handlers and links out of SVG markup. */
+export function sanitize(s: string): string;
+/** Shapes from a slot's markup (paths and basic shapes with geometry and paint attributes); anything else is escaped. */
+export function shapesOnly(markup: string): string;
+/** Draw raw markup with its tokens filled. */
+export function svg(layer: SvgLayer, ctx: RenderContext): Markup;

package/src/layers/svg.js

@@ -0,0 +1,109 @@
+/**
+ * The `svg` layer: raw markup, sanitised, with render-time tokens.
+ *
+ * @module layers/svg
+ */
+
+import { attrs, esc, num } from '../svg.js';
+import { unit } from '../geometry.js';
+import { pos, wrap } from './util.js';
+import { expandDropShadows } from '../effects/drop-shadow.js';
+import { filterReach } from '../effects/region.js';
+
+
+/**
+ * Remove what an SVG fragment must never carry: scripts, foreign objects,
+ * event handlers and links out (`href`s other than `#…` and `data:`).
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function sanitize(s) {
+  return String(s)
+    .replace(/<script\b[\s\S]*?<\/script\s*>/gi, '')
+    .replace(/<script\b[^>]*\/>/gi, '')
+    .replace(/<foreignObject\b[\s\S]*?<\/foreignObject\s*>/gi, '')
+    .replace(/\son[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+    .replace(/\s(xlink:)?href\s*=\s*("|')(?!#|data:)[^"']*\2/gi, '');
+}
+
+/** Elements a markup slot may carry (shapes and groups). */
+const SHAPES = new Set(['g', 'path', 'circle', 'ellipse', 'rect', 'polygon', 'polyline', 'line']);
+
+/** Attributes a markup slot may carry. */
+const SHAPE_ATTRS = new Set(['d', 'cx', 'cy', 'r', 'rx', 'ry', 'x', 'y', 'width', 'height', 'points', 'x1', 'y1', 'x2', 'y2', 'transform', 'fill', 'stroke', 'stroke-width', 'opacity', 'fill-opacity', 'stroke-opacity', 'fill-rule', 'clip-rule', 'stroke-linecap', 'stroke-linejoin', 'stroke-miterlimit', 'stroke-dasharray', 'stroke-dashoffset']);
+
+/**
+ * Shapes from a slot's markup (a mark's paths): `g`, `path`, `circle`,
+ * `ellipse`, `rect`, `polygon`, `polyline` and `line` with their geometry
+ * and paint attributes are kept; any other element is escaped (inert
+ * text), and other attributes dropped. Paint can't reference anything
+ * outside (`url(…)` is dropped).
+ *
+ * @param {string} markup
+ * @returns {string}
+ */
+export function shapesOnly(markup) {
+  return String(markup).replace(/<\/?([a-zA-Z][\w:-]*)([^>]*)>/g, (tag, name, rest) => {
+    if (!SHAPES.has(name)) return tag.replace(/[&<>"']/g, (ch) => /** @type {Record<string, string>} */ ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+    if (tag.startsWith('</')) return `</${name}>`;
+    const self = /\/\s*$/.test(rest);
+    let kept = '';
+    for (const m of rest.matchAll(/([\w:-]+)\s*=\s*("([^"]*)"|'([^']*)')/g)) {
+      const value = m[3] ?? m[4];
+      if (SHAPE_ATTRS.has(m[1]) && !/url\s*\(|javascript:/i.test(value)) kept += ` ${m[1]}="${esc(value)}"`;
+    }
+    return `<${name}${kept}${self ? '/' : ''}>`;
+  });
+}
+
+/**
+ * Replace render-time tokens in markup: `{{@accent}}` and the other palette
+ * and canvas tokens, `{{id}}` (a prefix unique to this layer, for ids in
+ * `defs`), and `{{seed}}` (a seeded number).
+ *
+ * @param {string} s @param {import('../layers.js').RenderContext} ctx
+ * @returns {string}
+ */
+function tokens(s, ctx) {
+  const p = /** @type {any} */ (ctx.palette);
+  return s.replace(/\{\{\s*([@\w.]+)\s*\}\}/g, (m, k) => {
+    if (k === 'id') return ctx.id;
+    if (k === 'seed') return String(ctx.rng.int(1, 9999));
+    if (k.startsWith('@')) {
+      const [head, idx] = k.slice(1).split('.');
+      if (head === 'width' || head === 'height') return num(ctx[head]);
+      if (head === 'u') return num(unit(ctx.canvas));
+      if (head === 'colors') return esc(p.colors[Number(idx ?? 0) % p.colors.length]);
+      if (Object.hasOwn(p, head)) return esc(String(p[head]));
+    }
+    return m;
+  });
+}
+
+/**
+ * `svg` — raw SVG markup, the escape hatch for anything too bespoke for a
+ * layer. `markup` is drawn in the layer's canvas, or from a `viewBox` into
+ * a box (`x`, `y`, `width`, `height`, `fit`); `defs` go in the document's
+ * defs. Palette and canvas tokens are written `{{@accent}}`, `{{@colors.1}}`,
+ * `{{@width}}`; `{{id}}` prefixes ids; in a JSON recipe `{{title}}` and any
+ * other option is filled in (escaped) too. Scripts, event handlers and
+ * external links are stripped.
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {import('../layers.js').Markup}
+ */
+export function svg(layer, ctx) {
+  const markup = expandDropShadows(sanitize(tokens(String(layer.markup ?? ''), ctx)));
+  const defs = layer.defs ? expandDropShadows(sanitize(tokens(String(layer.defs), ctx))) : '';
+  /** @type {any} */ (ctx).noteReach?.(filterReach(defs + markup) * (/** @type {any} */ (ctx).res ?? 1));
+  let body = markup;
+  if (layer.viewBox) {
+    const vb = Array.isArray(layer.viewBox) ? layer.viewBox : String(layer.viewBox).split(/[\s,]+/).map(Number);
+    const fit = layer.fit ?? 'contain';
+    const par = fit === 'stretch' ? 'none' : `${layer.align ?? 'xMidYMid'} ${fit === 'cover' ? 'slice' : 'meet'}`;
+    body = `<svg${attrs({ x: pos(layer.x ?? 0, 'x', ctx.canvas), y: pos(layer.y ?? 0, 'y', ctx.canvas), width: layer.width != null ? pos(layer.width, 'x', ctx.canvas) : ctx.width, height: layer.height != null ? pos(layer.height, 'y', ctx.canvas) : ctx.height, viewBox: vb.map((/** @type {number} */ v) => num(v, 3)).join(' '), preserveAspectRatio: par, overflow: 'visible' })}>${markup}</svg>`;
+  }
+  return { defs, body: wrap(layer, body) };
+}

package/src/layers/table.d.ts

@@ -0,0 +1,25 @@
+// The `table` layer.
+import type { Color, Length, BaseLayer, Anchor } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+
+/** A table cell: text, or text with its own style. */
+export type TableCell = string | number | { content: string | number; weight?: number; size?: Length; color?: Color; align?: 'left' | 'center' | 'right'; font?: string; opacity?: number; width?: Length };
+
+export interface TableLayer extends BaseLayer {
+  type: 'table';
+  rows: (TableCell[] | string | Record<string, TableCell>)[];
+  columns?: { x?: Length | `${number}%`; align?: 'left' | 'center' | 'right'; width?: Length; key?: string; weight?: number; size?: Length; color?: Color; font?: string; letterSpacing?: number; transform?: 'uppercase'; opacity?: number; lengthAdjust?: 'spacingAndGlyphs' | 'spacing' }[];
+  x?: Length | `${number}%`;
+  /** First baseline. */
+  y?: Length | `${number}%`;
+  size?: Length; lineHeight?: Length; rowHeight?: Length; rowGap?: Length;
+  font?: string; weight?: number; style?: 'normal' | 'italic'; axes?: Record<string, number>;
+  color?: Color; letterSpacing?: number;
+  header?: Record<string, unknown>;
+  rules?: boolean | { at?: 'between' | 'each' | 'top'; color?: Color; width?: Length; opacity?: number; x1?: Length; x2?: Length; above?: number };
+  columnWidth?: Length;
+}
+
+
+/** Draw text on a grid. */
+export function table(layer: TableLayer, ctx: RenderContext): Promise<Markup>;

package/src/layers/table.js

@@ -0,0 +1,80 @@
+/**
+ * The `table` layer: meta grids, lineups, tracklists.
+ *
+ * @module layers/table
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { toHex } from '../color.js';
+import { faceFor, setLine } from '../type/line.js';
+import { pos, wrap, contentOf } from './util.js';
+
+
+/**
+ * `table` — text on a grid: meta blocks, lineups, tracklists, programmes.
+ * `rows` is an array of rows (each an array of cells, or an object read
+ * through each column's `key`); a cell is text (`\n` for more lines) or
+ * `{ content, weight, size, color, align, font, opacity }`. `columns` give
+ * each column's `x` (px or `'%'`), `align`, `width` (justify), `key` and
+ * text style. Rows start at `y` (the first baseline) and step by
+ * `rowHeight`, or by their line count × `lineHeight` plus `rowGap`.
+ * `rules` draws hairlines between or above rows.
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {Promise<import('../layers.js').Markup>}
+ */
+export async function table(layer, ctx) {
+  const rows = /** @type {any[]} */ (layer.rows ?? []);
+  const cols = /** @type {any[]} */ (layer.columns ?? []);
+  const size = len(layer.size, ctx.canvas, '2.2vmin');
+  const lineH = len(layer.lineHeight, ctx.canvas, size * 1.22);
+  const x0 = pos(layer.x ?? 0, 'x', ctx.canvas);
+  let y = pos(layer.y ?? 0, 'y', ctx.canvas);
+  const color = layer.color ? toHex(layer.color) : ctx.palette.text;
+  /** @type {Map<string, string>} */
+  const byColor = new Map();
+  const add = (/** @type {string} */ c, /** @type {string} */ d) => byColor.set(c, (byColor.get(c) ?? '') + d);
+  let rules = '';
+  const r = layer.rules ? (layer.rules === true ? {} : layer.rules) : null;
+  const rx1 = r ? pos(r.x1 ?? layer.x ?? 0, 'x', ctx.canvas) : 0;
+  const rx2 = r ? pos(r.x2 ?? '100%', 'x', ctx.canvas) : 0;
+  const ruleAt = (/** @type {number} */ ry) => { rules += `M${num(rx1)} ${num(ry)}H${num(rx2)}`; };
+
+  for (let ri = 0; ri < rows.length; ri++) {
+    const row = rows[ri];
+    const cells = Array.isArray(row) ? row : typeof row === 'string' || typeof row === 'number' ? [row] : cols.map((c) => row?.[c.key]);
+    if (r && (r.at === 'top' || r.at === 'each') && ri === 0) ruleAt(y - size * (r.above ?? 1.1));
+    let lines = 1;
+    for (let ci = 0; ci < cells.length; ci++) {
+      const cell = cells[ci];
+      if (cell == null || cell === '') continue;
+      const col = { ...(layer.header && ri === 0 ? layer.header : {}), ...(cols[ci] ?? {}) };
+      const o = typeof cell === 'object' && !Array.isArray(cell) ? { ...col, ...cell } : { ...col, content: cell };
+      const text = String(Array.isArray(o.content) ? o.content.join('\n') : contentOf(o.content) ?? o.content);
+      const face = await faceFor(ctx, { font: o.font ?? layer.font, weight: o.weight ?? layer.weight ?? 400, style: o.style ?? layer.style, axes: o.axes ?? layer.axes });
+      const s = len(o.size, ctx.canvas, size);
+      const ls = (o.letterSpacing ?? layer.letterSpacing ?? 0) * s;
+      const cx = o.x != null ? pos(o.x, 'x', ctx.canvas) : x0 + ci * len(layer.columnWidth, ctx.canvas, '20vmin');
+      const parts = (o.transform === 'uppercase' ? text.toUpperCase() : text).split('\n');
+      parts.forEach((t, li) => {
+        const line = setLine({ face, text: t, size: s, tracking: ls, x: cx, y: y + li * lineH, align: o.align ?? 'left', width: o.width != null ? len(o.width, ctx.canvas) : undefined, adjust: o.lengthAdjust });
+        const fill = o.color ? toHex(o.color) : color;
+        add(o.opacity != null ? `${fill}|${o.opacity}` : fill, line.d);
+      });
+      lines = Math.max(lines, parts.length);
+    }
+    const step = layer.rowHeight != null ? len(layer.rowHeight, ctx.canvas) : lines * lineH + len(layer.rowGap, ctx.canvas, size * 0.6);
+    if (r && (r.at === 'between' || r.at == null || r.at === 'each') && ri < rows.length - 1) ruleAt(y + step - size * (r.above ?? 1.1));
+    y += step;
+  }
+  let body = '';
+  if (rules && r) body += `<path${attrs({ d: rules, fill: 'none', stroke: r.color ? toHex(r.color) : color, 'stroke-width': len(r.width, ctx.canvas, '0.12vmin'), opacity: r.opacity })}/>`;
+  for (const [key, d] of byColor) {
+    const [fill, op] = key.split('|');
+    body += `<path${attrs({ d, fill, opacity: op != null ? Number(op) : undefined })}/>`;
+  }
+  /** @type {any} */ (ctx).report?.({ kind: 'text', id: layer.id, content: rows.map((row) => (Array.isArray(row) ? row : Object.values(row ?? {})).map((c) => (typeof c === 'object' && c ? c.content : c)).join(' ')).join('\n'), size, capHeight: size * 0.72, box: null });
+  return { defs: '', body: wrap(layer, body) };
+}

package/src/layers/tear.d.ts

@@ -0,0 +1,21 @@
+// The `tear` layer.
+import type { Color, Length, BaseLayer, Anchor } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+import type { Paint } from '../effects/paint.js';
+
+export interface TearLayer extends BaseLayer {
+  type: 'tear';
+  from?: [Length | `${number}%`, Length | `${number}%`];
+  to?: [Length | `${number}%`, Length | `${number}%`];
+  side?: 'above' | 'below' | 'left' | 'right';
+  color?: Paint;
+  sheetOpacity?: number;
+  step?: Length; jitter?: Length;
+  rip?: false | { color?: Color; width?: Length; opacity?: number };
+  fibres?: false | { color?: Color; width?: Length; opacity?: number; length?: [Length, Length]; spread?: Length };
+  ripColor?: Color;
+}
+
+
+/** Draw torn paper: the sheet, its rip and fibres. */
+export function tear(layer: TearLayer, ctx: RenderContext): Markup;

package/src/layers/tear.js

@@ -0,0 +1,74 @@
+/**
+ * The `tear` layer: torn paper with fibres at the rip.
+ *
+ * @module layers/tear
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { toHex } from '../color.js';
+import { paint } from '../effects/paint.js';
+import { pos, wrap } from './util.js';
+
+
+/**
+ * `tear` — paper torn along a jagged line from `from` to `to` (edge to
+ * edge): the sheet on one `side` (`'above'`, `'below'`, `'left'`, `'right'`)
+ * in `color`, the white core of the rip along the edge (`rip`), and fibres
+ * hanging off it (`fibres`). `step` and `jitter` set the jaggedness. Use
+ * the same `seed` on two tear layers to draw the sheet and its edge
+ * separately (say, the sheet under a knockout and the edge over it).
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {import('../layers.js').Markup}
+ */
+export function tear(layer, ctx) {
+  const { width: w, height: h, rng } = ctx;
+  const P = (/** @type {any} */ q) => /** @type {[number, number]} */ ([pos(q?.[0] ?? q?.x ?? 0, 'x', ctx.canvas), pos(q?.[1] ?? q?.y ?? 0, 'y', ctx.canvas)]);
+  const from = P(layer.from ?? [0, '62%']);
+  const to = P(layer.to ?? ['100%', '36%']);
+  const step = len(layer.step, ctx.canvas, '2vmin');
+  const jitter = len(layer.jitter, ctx.canvas, '4.4vmin');
+  const L = Math.hypot(to[0] - from[0], to[1] - from[1]);
+  const n = Math.max(2, Math.round(L / step));
+  const nx = -(to[1] - from[1]) / L;
+  const ny = (to[0] - from[0]) / L;
+  const pts = [];
+  for (let i = 0; i <= n; i++) {
+    const t = i / n;
+    const j = (rng.next() - 0.5) * jitter;
+    pts.push([from[0] + (to[0] - from[0]) * t + nx * j, from[1] + (to[1] - from[1]) * t + ny * j]);
+  }
+  const line = pts.map((q, i) => `${i ? 'L' : 'M'}${num(q[0], 1)} ${num(q[1], 1)}`).join('');
+  let body = '';
+  const side = layer.side ?? 'above';
+  if (layer.color !== 'none' && layer.color !== false) {
+    const pad = Math.max(w, h);
+    const ext = { above: [0, -pad], below: [0, pad], left: [-pad, 0], right: [pad, 0] }[/** @type {'above'} */ (side)] ?? [0, -pad];
+    const first = pts[0];
+    const last = pts[pts.length - 1];
+    // Extend the ends past the canvas so a line that stops at the edge still closes off the corner.
+    const sx = Math.sign(last[0] - first[0]) || 1;
+    const sy = Math.sign(last[1] - first[1]) || 1;
+    const horizontal = side === 'above' || side === 'below';
+    const d = horizontal
+      ? `M${num(first[0] - sx * pad, 1)} ${num(first[1], 1)}${line.replace(/^M/, 'L')}L${num(last[0] + sx * pad, 1)} ${num(last[1], 1)}L${num(last[0] + sx * pad, 1)} ${num(last[1] + ext[1], 1)}L${num(first[0] - sx * pad, 1)} ${num(first[1] + ext[1], 1)}Z`
+      : `M${num(first[0], 1)} ${num(first[1] - sy * pad, 1)}${line.replace(/^M/, 'L')}L${num(last[0], 1)} ${num(last[1] + sy * pad, 1)}L${num(last[0] + ext[0], 1)} ${num(last[1] + sy * pad, 1)}L${num(first[0] + ext[0], 1)} ${num(first[1] - sy * pad, 1)}Z`;
+    const fp = paint(layer.color, ctx.palette.accent, { id: `${ctx.id}t`, box: { x: 0, y: 0, width: w, height: h }, canvas: ctx.canvas });
+    body += `<path${attrs({ d, fill: fp.value, opacity: layer.sheetOpacity })}/>`;
+  }
+  if (layer.fibres !== false) {
+    const f = layer.fibres && typeof layer.fibres === 'object' ? layer.fibres : {};
+    const [lo, hi] = (f.length ?? ['0.8vmin', '2vmin']).map((/** @type {any} */ v) => len(v, ctx.canvas));
+    const spread = len(f.spread, ctx.canvas, '0.6vmin');
+    const dir = side === 'above' || side === 'left' ? 1 : -1;
+    const d = pts.map((q) => `M${num(q[0], 1)} ${num(q[1], 1)}l${num((rng.next() * 2 - 1) * spread, 1)} ${num(dir * (lo + rng.next() * (hi - lo)), 1)}`).join('');
+    body += `<path${attrs({ d, stroke: toHex(f.color ?? layer.ripColor ?? '#fff6fb'), 'stroke-width': len(f.width, ctx.canvas, '0.44vmin'), 'stroke-linecap': 'round', fill: 'none', opacity: f.opacity ?? 0.85 })}/>`;
+  }
+  if (layer.rip !== false) {
+    const r = layer.rip && typeof layer.rip === 'object' ? layer.rip : {};
+    body += `<path${attrs({ d: line, stroke: toHex(r.color ?? layer.ripColor ?? '#fff6fb'), 'stroke-width': len(r.width, ctx.canvas, '0.7vmin'), fill: 'none', opacity: r.opacity ?? 0.9 })}/>`;
+  }
+  return { defs: '', body: wrap(layer, body) };
+}

package/src/layers/texture.d.ts

@@ -0,0 +1,17 @@
+// The `texture` layer.
+import type { Color, Length, BaseLayer, Anchor } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+
+export interface TextureLayer extends BaseLayer {
+  type: 'texture';
+  kind?: 'paper' | 'creases' | 'concrete' | 'speck' | 'wood' | 'folds' | 'dust';
+  color?: Color; amount?: number; frequency?: number | [number, number]; octaves?: number;
+  depth?: number; azimuth?: number; elevation?: number;
+  x?: number[]; y?: number[]; width?: Length; strength?: number;
+  count?: number; size?: [Length, Length];
+  region?: { x?: Length | `${number}%`; y?: Length | `${number}%`; width?: Length | `${number}%`; height?: Length | `${number}%` };
+}
+
+
+/** Draw a surface texture. */
+export function texture(layer: TextureLayer, ctx: RenderContext): Markup;

package/src/layers/texture.js

@@ -0,0 +1,106 @@
+/**
+ * The `texture` layer: paper, creases, concrete, speck, wood, folds, dust.
+ *
+ * @module layers/texture
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { toHex } from '../color.js';
+import { pos, wrap } from './util.js';
+
+
+/**
+ * `texture` — a surface laid over (or under) the artwork: `paper` (fibres),
+ * `creases` (pasted paper lit from the side; soft-light), `concrete`,
+ * `speck` (white specks), `wood`, `folds` (straight fold lines with a lit
+ * and a shaded side), `dust` (seeded specks of dirt). `color`, `opacity`,
+ * `blend`, `frequency`, `octaves` and `region` adjust it.
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {import('../layers.js').Markup}
+ */
+export function texture(layer, ctx) {
+  const { width: w, height: h, rng } = ctx;
+  const kind = layer.kind ?? 'paper';
+  const id = `${ctx.id}t`;
+  const seed = layer.seed ?? rng.int(1, 9999);
+  const rgb = (/** @type {string} */ c) => [1, 3, 5].map((i) => num(parseInt(toHex(c).slice(i, i + 2), 16) / 255, 3));
+  const f = (/** @type {any} */ v, /** @type {string} */ d) => (v == null ? d : [].concat(v).map((x) => num(x, 4)).join(' '));
+  const rect = (/** @type {string} */ extra = '') => `<rect${attrs({ width: w, height: h, filter: `url(#${id})` })}${extra}/>`;
+  const region = `${attrs({ id, x: 0, y: 0, width: w, height: h, filterUnits: 'userSpaceOnUse', 'color-interpolation-filters': 'sRGB' })}`;
+  let defs = '';
+  let body = '';
+  let blend = layer.blend;
+  let opacity = layer.opacity;
+  // Feature sizes are tuned on a 400 px wide sheet; scale with the canvas.
+  const k = 400 / Math.min(w, h * 0.8);
+  const fq = (/** @type {number[]} */ ...v) => v.map((x) => x * k);
+  switch (kind) {
+    case 'paper': {
+      const [r, g, b] = rgb(layer.color ?? '#73664d');
+      defs = `<filter${region}><feTurbulence type="fractalNoise" baseFrequency="${f(layer.frequency, fq(0.55, 0.3).map((x) => num(x, 4)).join(' '))}" numOctaves="${layer.octaves ?? 3}" seed="${seed}"/><feColorMatrix type="matrix" values="0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  0 0 0 -0.9 ${num(0.5 * (layer.amount ?? 1), 3)}"/></filter>`;
+      body = rect();
+      break;
+    }
+    case 'creases':
+      defs = `<filter${region}><feTurbulence type="turbulence" baseFrequency="${f(layer.frequency, fq(0.006, 0.022).map((x) => num(x, 4)).join(' '))}" numOctaves="${layer.octaves ?? 3}" seed="${seed}" result="t"/><feDiffuseLighting in="t" surfaceScale="${num(layer.depth ?? 3.4, 3)}" lighting-color="#fff" result="lit"><feDistantLight azimuth="${layer.azimuth ?? 225}" elevation="${layer.elevation ?? 38}"/></feDiffuseLighting><feColorMatrix in="lit" type="saturate" values="0"/></filter>`;
+      body = rect();
+      blend ??= 'soft-light';
+      opacity ??= 0.95;
+      break;
+    case 'concrete': {
+      const [r, g, b] = rgb(layer.color ?? '#857f7a');
+      defs = `<filter${region}><feTurbulence type="fractalNoise" baseFrequency="${f(layer.frequency, fq(0.035, 0.05).map((x) => num(x, 4)).join(' '))}" numOctaves="${layer.octaves ?? 4}" seed="${seed}"/><feColorMatrix type="matrix" values="0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  0.6 0.6 0.6 0 -0.4"/></filter>`;
+      body = rect();
+      break;
+    }
+    case 'speck': {
+      const [r, g, b] = rgb(layer.color ?? '#ffffff');
+      defs = `<filter${region}><feTurbulence type="fractalNoise" baseFrequency="${f(layer.frequency, num(0.7 * k, 4))}" numOctaves="1" seed="${seed}"/><feColorMatrix type="matrix" values="0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  0 0 0 -12 7.3"/></filter>`;
+      body = rect();
+      opacity ??= 0.25;
+      break;
+    }
+    case 'wood': {
+      const [r, g, b] = rgb(layer.color ?? '#6b4224');
+      defs = `<filter${region}><feTurbulence type="fractalNoise" baseFrequency="${f(layer.frequency, fq(0.006, 0.16).map((x) => num(x, 4)).join(' '))}" numOctaves="${layer.octaves ?? 4}" seed="${seed}"/><feColorMatrix type="matrix" values="0 0 0 0 ${r}  0 0 0 0 ${g}  0 0 0 0 ${b}  1.4 0 0 0 -0.45"/></filter>`;
+      body = rect();
+      break;
+    }
+    case 'folds': {
+      // Straight folds: a lit side and a shaded side either side of each line.
+      const xs = layer.x ?? [];
+      const ys = layer.y ?? (layer.x ? [] : [0.5]);
+      const bw = len(layer.width, ctx.canvas, '1.6vmin');
+      const strength = layer.strength ?? 0.35;
+      const band = (/** @type {boolean} */ vertical, /** @type {number} */ at, /** @type {number} */ i) => {
+        const gid = `${id}${vertical ? 'v' : 'h'}${i}`;
+        const p = vertical ? at * w : at * h;
+        defs += `<linearGradient${attrs({ id: gid, gradientUnits: 'userSpaceOnUse', x1: vertical ? p - bw : 0, y1: vertical ? 0 : p - bw, x2: vertical ? p + bw : 0, y2: vertical ? 0 : p + bw })}><stop offset="0" stop-color="#000" stop-opacity="0"/><stop offset="0.48" stop-color="#000" stop-opacity="${num(strength, 3)}"/><stop offset="0.52" stop-color="#fff" stop-opacity="${num(strength * 1.4, 3)}"/><stop offset="1" stop-color="#fff" stop-opacity="0"/></linearGradient>`;
+        body += vertical ? `<rect${attrs({ x: p - bw, y: 0, width: bw * 2, height: h, fill: `url(#${gid})` })}/>` : `<rect${attrs({ x: 0, y: p - bw, width: w, height: bw * 2, fill: `url(#${gid})` })}/>`;
+      };
+      xs.forEach((/** @type {number} */ x, /** @type {number} */ i) => band(true, x, i));
+      ys.forEach((/** @type {number} */ y, /** @type {number} */ i) => band(false, y, i));
+      blend ??= 'soft-light';
+      break;
+    }
+    case 'dust': {
+      const n = layer.count ?? 70;
+      const c = toHex(layer.color ?? ctx.palette.text);
+      const [lo, hi] = (layer.size ?? ['0.06vmin', '0.26vmin']).map((/** @type {any} */ v) => len(v, ctx.canvas));
+      for (let i = 0; i < n; i++) body += `<circle${attrs({ cx: rng.next() * w, cy: rng.next() * h, r: lo + rng.next() * (hi - lo) })}/>`;
+      body = `<g fill="${c}">${body}</g>`;
+      break;
+    }
+    default:
+      throw new TypeError(`Unknown texture "${kind}" (paper, creases, concrete, speck, wood, folds, dust)`);
+  }
+  if (layer.region) {
+    const rg = layer.region;
+    defs += `<clipPath id="${id}c"><rect${attrs({ x: pos(rg.x ?? 0, 'x', ctx.canvas), y: pos(rg.y ?? 0, 'y', ctx.canvas), width: pos(rg.width ?? '100%', 'x', ctx.canvas), height: pos(rg.height ?? '100%', 'y', ctx.canvas) })}/></clipPath>`;
+    body = `<g clip-path="url(#${id}c)">${body}</g>`;
+  }
+  return { defs, body: wrap({ blend, opacity }, body) };
+}

package/src/layers/util.d.ts

@@ -0,0 +1,8 @@
+// Helpers the poster layers share.
+
+/** A coordinate: px, `'50%'` of the canvas along `axis`, or a length. */
+export function pos(v: unknown, axis: 'x' | 'y', canvas: { width: number; height: number }): number;
+/** Markup wrapped in the layer's opacity and blend (when it has them). */
+export function wrap(layer: { opacity?: number; blend?: string }, body: string): string;
+/** The text of a string-or-object option. */
+export function contentOf(v: unknown): string | undefined;