@arraypress/covers 0.0.0-stage → 1.1.0

package/src/formats/print.js

@@ -0,0 +1,117 @@
+/**
+ * Named formats: release covers, social posts, flyers and print stationery,
+ * alongside `aspect`.
+ *
+ * Screen formats are pixel sizes. Print formats are a trim size in
+ * millimetres or inches, rendered at `dpi` (300 by default) with a bleed
+ * (3 mm by default) and a safe area inside the trim; `cropMarks: true`
+ * adds a slug with crop marks round the bleed. The layers are drawn on the
+ * bleed box (trim plus bleed on every side), so backgrounds run off the
+ * edge, and text and icons keep their default margins inside the safe area.
+ *
+ * @module formats/print
+ */
+
+import { FORMATS } from './presets.js';
+import { scaleZones } from './zones.js';
+import { cutPath } from './cut.js';
+
+/** @param {number} v @param {string} unit @param {number} dpi @returns {number} px */
+export function toPx(v, unit, dpi) {
+  return unit === 'mm' ? (v / 25.4) * dpi : unit === 'in' ? v * dpi : v;
+}
+
+/**
+ * The print set-up of a cover, in px.
+ *
+ * @typedef {object} PrintInfo
+ * @property {number} dpi
+ * @property {'mm' | 'in'} unit - The format's unit.
+ * @property {number} trimWidth - px.
+ * @property {number} trimHeight - px.
+ * @property {number} bleed - px on each side.
+ * @property {number} safe - px inside the trim on each side.
+ * @property {number} slug - px of slug outside the bleed (crop marks), 0 without.
+ * @property {boolean} cropMarks
+ * @property {import('./cut.js').Cut} [cut] - Die-cut shape.
+ * @property {boolean} cutLine - Draw the die line.
+ * @property {number} mm - px per millimetre.
+ */
+
+/**
+ * Resolve a cover's `format` (a name or a custom `{ width, height, unit }`)
+ * to its canvas and print set-up.
+ *
+ * @param {any} o - Cover options: `format`, `dpi`, `bleed` (mm, or `false`), `safe` (mm), `cropMarks`, `cutLine`.
+ * @returns {{ width: number, height: number, print?: PrintInfo, format?: string, zones?: import('./index.js').Zones } | undefined}
+ */
+export function resolveFormat(o) {
+  if (o.format == null) return undefined;
+  const f = typeof o.format === 'string' ? FORMATS[o.format] : { unit: 'px', ...o.format };
+  if (!f) throw new RangeError(`Unknown format "${o.format}". Formats: ${Object.keys(FORMATS).join(', ')}`);
+  const name = typeof o.format === 'string' ? o.format : undefined;
+  if (f.unit === 'px') {
+    // A screen format: one side given scales the zones and the other side.
+    const k = o.width && !o.height ? o.width / f.width : 1;
+    const zones = f.zones ? scaleZones(f.zones, k) : undefined;
+    return { width: Math.round(f.width * k), height: Math.round(f.height * k), format: name, zones };
+  }
+  const dpi = o.dpi ?? 300;
+  const mm = dpi / 25.4;
+  const trimWidth = Math.round(toPx(f.width, f.unit, dpi));
+  const trimHeight = Math.round(toPx(f.height, f.unit, dpi));
+  const bleed = o.bleed === false ? 0 : Math.round((o.bleed ?? f.bleed ?? 3) * mm);
+  const safe = Math.round((o.safe ?? f.safe ?? 3) * mm);
+  const cropMarks = Boolean(o.cropMarks);
+  const slug = cropMarks ? Math.round(Math.max(6, (o.bleed === false ? 0 : o.bleed ?? f.bleed ?? 3) + 3) * mm) : 0;
+  return {
+    width: trimWidth + 2 * bleed,
+    height: trimHeight + 2 * bleed,
+    format: name,
+    print: { dpi, unit: /** @type {'mm' | 'in'} */ (f.unit), trimWidth, trimHeight, bleed, safe, slug, cropMarks, cut: o.cut ?? f.cut, cutLine: Boolean(o.cutLine), mm },
+  };
+}
+
+/**
+ * Crop marks in the slug, a die line, and the document's outer size.
+ *
+ * @param {PrintInfo} p
+ * @param {number} w - Bleed-box width, px.
+ * @param {number} h - Bleed-box height, px.
+ * @returns {{ marks: string, cut: string }} Markup: marks in slug coordinates (the bleed box starts at `slug`), and the die line in bleed-box coordinates.
+ */
+export function printMarks(p, w, h) {
+  const n = (/** @type {number} */ v) => Math.round(v * 100) / 100;
+  let marks = '';
+  if (p.cropMarks) {
+    const s = p.slug;
+    const b = p.bleed;
+    const len = s - b - p.mm;
+    const gap = b + p.mm;
+    const stroke = Math.max(0.5, 0.25 * p.mm);
+    const xs = [s + b, s + w - b];
+    const ys = [s + b, s + h - b];
+    let d = '';
+    for (const x of xs) for (const y of ys) {
+      const dx = x < s + w / 2 ? -1 : 1;
+      const dy = y < s + h / 2 ? -1 : 1;
+      d += `M${n(x + dx * gap)} ${n(y)}h${n(dx * len)}M${n(x)} ${n(y + dy * gap)}v${n(dy * len)}`;
+    }
+    marks = `<path d="${d}" fill="none" stroke="#000" stroke-width="${n(stroke)}"/>`;
+  }
+  let cut = '';
+  if (p.cutLine) {
+    const x = p.bleed;
+    const y = p.bleed;
+    const cw = p.trimWidth;
+    const ch = p.trimHeight;
+    const custom = p.cut && typeof p.cut === 'object';
+    const shape = custom
+      ? `<path d="${cutPath(p.cut, { x, y, width: cw, height: ch }, p.mm).map((g) => g.cmd + g.pts.map(n).join(' ')).join('')}"`
+      : p.cut === 'circle'
+      ? `<ellipse cx="${n(x + cw / 2)}" cy="${n(y + ch / 2)}" rx="${n(cw / 2)}" ry="${n(ch / 2)}"`
+      : `<rect x="${n(x)}" y="${n(y)}" width="${n(cw)}" height="${n(ch)}"${p.cut === 'rounded' ? ` rx="${n(3 * p.mm)}"` : ''}`;
+    cut = `${shape} fill="none" stroke="#ec008c" stroke-width="${n(Math.max(0.5, 0.25 * p.mm))}" id="CutContour"/>`;
+  }
+  return { marks, cut };
+}

package/src/formats/zones.d.ts

@@ -0,0 +1,10 @@
+// Safe zones.
+import type { Zones } from './presets.js';
+import type { PrintInfo } from './print.js';
+
+/** A preview overlay of the zones: safe area dashed green, covered areas red, crops blue. */
+export function zonesOverlay(z: Zones, w: number, h: number): string;
+/** Zones scaled by `k`. */
+export function scaleZones(z: Zones, k: number): Zones;
+/** A cover's safe box, px. */
+export function safeBox(c: { width: number; height: number; print?: PrintInfo; zones?: Zones }): { x: number; y: number; width: number; height: number } | undefined;

package/src/formats/zones.js

@@ -0,0 +1,64 @@
+/**
+ * Safe zones: the box layouts fit into, scaling, and a preview overlay.
+ *
+ * @module formats/zones
+ */
+
+/**
+ * A preview overlay of a format's zones: the safe area dashed, covered
+ * areas tinted red, device crops outlined.
+ *
+ * @param {import('./index.js').Zones} z
+ * @param {number} w @param {number} h
+ * @returns {string} Markup.
+ */
+export function zonesOverlay(z, w, h) {
+  const n = (/** @type {number} */ v) => Math.round(v * 100) / 100;
+  const sw = n(Math.max(1, Math.min(w, h) / 360));
+  let out = '';
+  for (const c of z.crops ?? []) {
+    const [x, y, cw, ch] = c.rect;
+    if (c.name === 'circle') {
+      out += `<path d="M0 0H${n(w)}V${n(h)}H0ZM${n(x)} ${n(y + ch / 2)}a${n(cw / 2)} ${n(ch / 2)} 0 1 0 ${n(cw)} 0a${n(cw / 2)} ${n(ch / 2)} 0 1 0 ${n(-cw)} 0Z" fill="#000" fill-opacity="0.45" fill-rule="evenodd"/>`;
+    } else {
+      out += `<rect x="${n(x)}" y="${n(y)}" width="${n(cw)}" height="${n(ch)}" fill="none" stroke="#00b3ff" stroke-width="${sw}" stroke-dasharray="${n(sw * 2)} ${n(sw * 3)}"/>`;
+    }
+  }
+  for (const a of z.avoid ?? []) {
+    if (a.circle) out += `<circle cx="${n(a.circle[0])}" cy="${n(a.circle[1])}" r="${n(a.circle[2])}" fill="#ff2d55" fill-opacity="0.35" stroke="#ff2d55" stroke-width="${sw}"/>`;
+    if (a.rect) out += `<rect x="${n(a.rect[0])}" y="${n(a.rect[1])}" width="${n(a.rect[2])}" height="${n(a.rect[3])}" fill="#ff2d55" fill-opacity="0.3"/>`;
+  }
+  const [x, y, sw2, sh] = z.safe;
+  out += `<rect x="${n(x)}" y="${n(y)}" width="${n(sw2)}" height="${n(sh)}" fill="none" stroke="#18e05a" stroke-width="${n(sw * 2)}" stroke-dasharray="${n(sw * 8)} ${n(sw * 5)}"/>`;
+  return `<g pointer-events="none">${out}</g>`;
+}
+
+/**
+ * @param {import('./index.js').Zones} z @param {number} k
+ * @returns {import('./index.js').Zones}
+ */
+export function scaleZones(z, k) {
+  if (k === 1) return z;
+  const r = (/** @type {number[]} */ a) => /** @type {any} */ (a.map((v) => Math.round(v * k)));
+  return { ...z, safe: r(z.safe), avoid: z.avoid?.map((a) => ({ ...a, rect: a.rect && r(a.rect), circle: a.circle && r(a.circle) })), crops: z.crops?.map((c) => ({ ...c, rect: r(c.rect) })) };
+}
+
+
+/**
+ * The safe box of a cover, px: a format's safe zone, or a print piece's
+ * trim less its safe margin. Undefined for a plain canvas.
+ *
+ * @param {{ width: number, height: number, print?: import('./index.js').PrintInfo, zones?: import('./index.js').Zones }} c
+ * @returns {{ x: number, y: number, width: number, height: number } | undefined}
+ */
+export function safeBox(c) {
+  if (c.zones) {
+    const [x, y, width, height] = c.zones.safe;
+    return { x, y, width, height };
+  }
+  if (c.print) {
+    const i = c.print.bleed + c.print.safe;
+    return { x: i, y: i, width: c.width - 2 * i, height: c.height - 2 * i };
+  }
+  return undefined;
+}

package/src/geometry.js

@@ -0,0 +1,187 @@
+/**
+ * Canvas size, lengths and anchoring.
+ *
+ * Lengths are pixels when given as numbers, or CSS-style viewport units as
+ * strings: `'6vmin'` (6% of the shorter side), `'4vw'`, `'4vh'`, `'5vmax'`.
+ * Defaults are written in these units, so a cover keeps its proportions at
+ * any output size.
+ *
+ * @module geometry
+ */
+
+/** Named aspect ratios, as `width / height`. */
+export const ASPECTS = Object.freeze({
+  '1:1': 1,
+  '16:9': 16 / 9,
+  '4:5': 4 / 5,
+  '3:2': 3 / 2,
+  '4:3': 4 / 3,
+  '2:1': 2,
+  '9:16': 9 / 16,
+  og: 1200 / 630,
+});
+
+/**
+ * Work out a cover's pixel size from `width`, `height` and `aspect`.
+ *
+ * - both `width` and `height` → used as given
+ * - one side + `aspect` → the other side follows
+ * - `aspect` only → 1200 wide (`'og'` is exactly 1200×630)
+ * - nothing → 1200×1200
+ *
+ * @param {{ width?: number, height?: number, aspect?: string | number }} opts
+ * @returns {{ width: number, height: number }} Integer pixel size.
+ * @throws {RangeError} On a non-positive size or an unreadable aspect.
+ *
+ * @example
+ * resolveSize({ aspect: '16:9' });            // { width: 1200, height: 675 }
+ * resolveSize({ height: 800, aspect: '3:2' }); // { width: 1200, height: 800 }
+ */
+export function resolveSize({ width, height, aspect } = {}) {
+  if (width && height) return checkSize(width, height);
+  const ratio = aspectRatio(aspect ?? (width || height ? undefined : '1:1'));
+  if (ratio == null) return checkSize(width ?? height ?? 1200, height ?? width ?? 1200);
+  if (height && !width) return checkSize(height * ratio, height);
+  return checkSize(width ?? 1200, (width ?? 1200) / ratio);
+}
+
+/**
+ * Parse an aspect: a named one, `'a:b'`, `'a/b'` or a number.
+ *
+ * @param {string | number | undefined} aspect
+ * @returns {number | undefined} `width / height`, or undefined when none was given.
+ * @throws {RangeError} On a string that isn't an aspect.
+ */
+export function aspectRatio(aspect) {
+  if (aspect == null) return undefined;
+  if (typeof aspect === 'number') {
+    if (aspect > 0) return aspect;
+    throw new RangeError(`Invalid aspect ${aspect}`);
+  }
+  if (Object.hasOwn(ASPECTS, aspect)) return ASPECTS[aspect];
+  const m = String(aspect).match(/^\s*(\d+(?:\.\d+)?)\s*[:/x]\s*(\d+(?:\.\d+)?)\s*$/);
+  if (m && +m[1] > 0 && +m[2] > 0) return +m[1] / +m[2];
+  throw new RangeError(`Invalid aspect "${aspect}". Use one of ${Object.keys(ASPECTS).join(', ')} or "w:h".`);
+}
+
+/**
+ * @param {number} w @param {number} h
+ * @returns {{ width: number, height: number }}
+ */
+function checkSize(w, h) {
+  const width = Math.round(w);
+  const height = Math.round(h);
+  if (!(width > 0 && height > 0) || width > 8192 || height > 8192) {
+    throw new RangeError(`Cover size must be 1–8192px per side, got ${width}×${height}`);
+  }
+  return { width, height };
+}
+
+/**
+ * Resolve a length to pixels.
+ *
+ * @param {number | string | undefined | null} value - Pixels, or `'Nvmin'` / `'Nvw'` / `'Nvh'` / `'Nvmax'`.
+ * @param {{ width: number, height: number }} canvas - The canvas size.
+ * @param {number | string} [fallback=0] - Used when `value` is undefined or null.
+ * @returns {number} Pixels.
+ * @throws {TypeError} On a string with an unknown unit.
+ *
+ * @example
+ * len('5vmin', { width: 1200, height: 630 });  // 31.5
+ * len(undefined, canvas, '6vmin');             // the default
+ */
+export function len(value, canvas, fallback = 0) {
+  const v = value ?? fallback;
+  if (typeof v === 'number') return v;
+  const m = String(v).match(/^\s*(-?\d*\.?\d+)\s*(vmin|vmax|vw|vh|px)?\s*$/);
+  if (!m) throw new TypeError(`Invalid length "${v}" (use px numbers or vmin/vmax/vw/vh)`);
+  const n = parseFloat(m[1]);
+  switch (m[2]) {
+    case 'vmin': return (n / 100) * Math.min(canvas.width, canvas.height);
+    case 'vmax': return (n / 100) * Math.max(canvas.width, canvas.height);
+    case 'vw': return (n / 100) * canvas.width;
+    case 'vh': return (n / 100) * canvas.height;
+    default: return n;
+  }
+}
+
+/** The nine anchors, as fractions of the free space along x and y. */
+export const ANCHORS = Object.freeze({
+  'top-left': [0, 0], top: [0.5, 0], 'top-right': [1, 0],
+  left: [0, 0.5], center: [0.5, 0.5], right: [1, 0.5],
+  'bottom-left': [0, 1], bottom: [0.5, 1], 'bottom-right': [1, 1],
+});
+
+/**
+ * Place a box on the canvas.
+ *
+ * With `position` (fractions 0–1 of the canvas, the box's anchor point
+ * goes there), the margin is ignored. Otherwise the box sits at `anchor`
+ * inside the safe area (`margin` in from every edge). `offset` nudges it
+ * either way.
+ *
+ * @param {object} o
+ * @param {number} o.width - Box width.
+ * @param {number} o.height - Box height.
+ * @param {{ width: number, height: number }} o.canvas - The canvas.
+ * @param {import('./index.js').Anchor} [o.anchor='center'] - Where it sits.
+ * @param {number} [o.margin=0] - Safe margin in px.
+ * @param {{ x?: number, y?: number }} [o.position] - Explicit placement (fractions).
+ * @param {{ x?: number | string, y?: number | string }} [o.offset] - Extra shift (lengths).
+ * @returns {{ x: number, y: number }} The box's top-left corner.
+ * @throws {TypeError} On an unknown anchor.
+ */
+export function place({ width, height, canvas, anchor = 'center', margin = 0, position, offset }) {
+  const a = ANCHORS[anchor];
+  if (!a) throw new TypeError(`Unknown anchor "${anchor}". Use ${Object.keys(ANCHORS).join(', ')}.`);
+  let x;
+  let y;
+  if (position && (position.x != null || position.y != null)) {
+    x = (position.x ?? 0.5) * canvas.width - a[0] * width;
+    y = (position.y ?? 0.5) * canvas.height - a[1] * height;
+  } else {
+    x = margin + a[0] * (canvas.width - 2 * margin - width);
+    y = margin + a[1] * (canvas.height - 2 * margin - height);
+  }
+  return { x: x + len(offset?.x, canvas, 0), y: y + len(offset?.y, canvas, 0) };
+}
+
+/**
+ * The anchor's horizontal alignment (`'left'`, `'center'`, `'right'`).
+ *
+ * @param {import('./index.js').Anchor} anchor
+ * @returns {'left' | 'center' | 'right'} Alignment.
+ */
+export function anchorAlign(anchor = 'center') {
+  const fx = ANCHORS[anchor]?.[0] ?? 0.5;
+  return fx === 0 ? 'left' : fx === 1 ? 'right' : 'center';
+}
+
+/**
+ * The shared "design unit" for a canvas: the geometric mean of its sides.
+ * Type and margins scale with it, so a 1200×630 card and a 1200×1200
+ * square get proportionate (not identical) headlines.
+ *
+ * @param {{ width: number, height: number }} canvas
+ * @returns {number} Pixels.
+ */
+export function unit(canvas) {
+  return Math.sqrt(canvas.width * canvas.height);
+}
+
+/**
+ * Resolve a region (fractions of the canvas) to pixels.
+ *
+ * @param {{ x?: number, y?: number, width?: number, height?: number } | undefined} region
+ * @param {{ width: number, height: number }} canvas
+ * @returns {{ x: number, y: number, width: number, height: number }} Pixels.
+ */
+export function regionPx(region, canvas) {
+  const r = region ?? {};
+  return {
+    x: (r.x ?? 0) * canvas.width,
+    y: (r.y ?? 0) * canvas.height,
+    width: (r.width ?? 1 - (r.x ?? 0)) * canvas.width,
+    height: (r.height ?? 1 - (r.y ?? 0)) * canvas.height,
+  };
+}

package/src/grid.js

@@ -0,0 +1,41 @@
+/**
+ * Grid lines that break around content.
+ *
+ * @module grid
+ */
+
+import { num } from './svg.js';
+
+/**
+ * Path data for full-length grid lines at `xs` (columns) and `ys` (rows),
+ * each broken where it crosses one of the `gaps` rectangles, so a grid can
+ * pass behind content without running through it.
+ *
+ * @param {number[]} xs @param {number[]} ys
+ * @param {number} w @param {number} h
+ * @param {{ x: number, y: number, width: number, height: number }[]} gaps - Pixel rects.
+ * @returns {string} Path data.
+ */
+export function gridPath(xs, ys, w, h, gaps) {
+  const cut = (/** @type {number} */ len, /** @type {[number, number][]} */ holes) => {
+    const runs = [];
+    let at = 0;
+    for (const [a, b] of holes.filter(([a, b]) => b > 0 && a < len).sort((p, q) => p[0] - q[0])) {
+      if (a > at) runs.push([at, a]);
+      at = Math.max(at, b);
+    }
+    if (at < len) runs.push([at, len]);
+    return runs;
+  };
+  let d = '';
+  for (const y of ys) {
+    const holes = gaps.filter((g) => y >= g.y && y <= g.y + g.height).map((g) => /** @type {[number, number]} */ ([g.x, g.x + g.width]));
+    for (const [a, b] of cut(w, holes)) d += `M${num(a)} ${num(y)}H${num(b)}`;
+  }
+  for (const x of xs) {
+    const holes = gaps.filter((g) => x >= g.x && x <= g.x + g.width).map((g) => /** @type {[number, number]} */ ([g.y, g.y + g.height]));
+    for (const [a, b] of cut(h, holes)) d += `M${num(x)} ${num(a)}V${num(b)}`;
+  }
+  return d;
+}
+

package/src/handmade.js

@@ -0,0 +1,253 @@
+/**
+ * Hand-made layers: cut paper and hand-drawn lines.
+ *
+ * - `paper`    flat shapes with scissor-cut edges: the outline is resampled
+ *              into short straight cuts and each cut point nudged off the
+ *              line (seeded), so edges are irregular but never blurry.
+ * - `scribble` an icon re-drawn by hand (its outline flattened, wobbled with
+ *              smooth seeded noise and stroked at a varying width with round
+ *              caps), or a small node graph: a polyline with filled dots.
+ *
+ * @module handmade
+ */
+
+import { attrs, num, layerAttrs } from './svg.js';
+import { len, regionPx } from './geometry.js';
+import { toHex } from './color.js';
+import { resolveIcon, parseSvgIcon } from './icons.js';
+import { flattenBody, densify } from './flatten.js';
+
+/** Off-white paper. */
+export const PAPER = '#faf9f5';
+/** Near-black ink. */
+export const INK = '#141413';
+
+/**
+ * Smooth 1D value noise from a seeded stream: `noise(t)` in [-1, 1].
+ *
+ * @param {import('./rng.js').Rng} rng
+ * @returns {(t: number) => number}
+ */
+function noise1(rng) {
+  const knots = Array.from({ length: 64 }, () => rng.range(-1, 1));
+  return (t) => {
+    const i = Math.floor(t);
+    const f = t - i;
+    const a = knots[((i % 64) + 64) % 64];
+    const b = knots[(((i + 1) % 64) + 64) % 64];
+    const e = f * f * (3 - 2 * f);
+    return a + (b - a) * e;
+  };
+}
+
+/**
+ * Resample a closed outline into scissor cuts: points every `cut` px, each
+ * nudged by up to `wobble` px across the edge.
+ *
+ * @param {[number, number][]} outline - A closed polyline (first point not repeated).
+ * @param {number} cut - Cut length in px.
+ * @param {number} wobble - Max nudge in px.
+ * @param {import('./rng.js').Rng} rng
+ * @returns {string} Path data.
+ */
+function scissor(outline, cut, wobble, rng) {
+  const pts = densify([...outline, outline[0]], cut / 6);
+  /** @type {[number, number][]} */
+  const out = [];
+  let acc = cut;
+  for (let i = 1; i < pts.length; i++) {
+    acc += Math.hypot(pts[i][0] - pts[i - 1][0], pts[i][1] - pts[i - 1][1]);
+    if (acc >= cut * rng.range(0.6, 1.4)) {
+      acc = 0;
+      const [x0, y0] = pts[i - 1];
+      const [x1, y1] = pts[i];
+      const l = Math.hypot(x1 - x0, y1 - y0) || 1;
+      const k = rng.range(-wobble, wobble);
+      out.push([x1 + (-(y1 - y0) / l) * k, y1 + ((x1 - x0) / l) * k]);
+    }
+  }
+  return `M${out.map(([x, y]) => `${num(x)} ${num(y)}`).join('L')}Z`;
+}
+
+/**
+ * A shape's outline, centred on the origin.
+ *
+ * @param {string} kind - rect | square | circle | blob | arch | pill
+ * @param {number} w @param {number} h
+ * @param {import('./rng.js').Rng} rng
+ * @returns {[number, number][]}
+ */
+function outlineOf(kind, w, h, rng) {
+  const ellipse = (rx, ry, bump = 0) => {
+    const n = 72;
+    const wave = noise1(rng);
+    return Array.from({ length: n }, (_, i) => {
+      const a = (i / n) * Math.PI * 2;
+      const r = 1 + bump * wave((i / n) * 5);
+      return /** @type {[number, number]} */ ([Math.cos(a) * rx * r, Math.sin(a) * ry * r]);
+    });
+  };
+  if (kind === 'circle') return ellipse(w / 2, h / 2);
+  if (kind === 'blob') return ellipse(w / 2, h / 2, 0.16);
+  if (kind === 'pill') {
+    const r = Math.min(w, h) / 2;
+    const pts = [];
+    for (let i = 0; i <= 18; i++) { const a = -Math.PI / 2 + (i / 18) * Math.PI; pts.push([w / 2 - r + Math.cos(a) * r, Math.sin(a) * r]); }
+    for (let i = 0; i <= 18; i++) { const a = Math.PI / 2 + (i / 18) * Math.PI; pts.push([-w / 2 + r + Math.cos(a) * r, Math.sin(a) * r]); }
+    return /** @type {[number, number][]} */ (pts);
+  }
+  if (kind === 'arch') {
+    const r = w / 2;
+    const pts = [[w / 2, h / 2], [-w / 2, h / 2]];
+    for (let i = 0; i <= 24; i++) { const a = Math.PI + (i / 24) * Math.PI; pts.push([Math.cos(a) * r, -h / 2 + r + Math.sin(a) * r]); }
+    return /** @type {[number, number][]} */ (pts);
+  }
+  // rect / square: corners slightly off-true, as if cut by eye.
+  const j = () => rng.range(-0.04, 0.04) * Math.min(w, h);
+  return [[-w / 2 + j(), -h / 2 + j()], [w / 2 + j(), -h / 2 + j()], [w / 2 + j(), h / 2 + j()], [-w / 2 + j(), h / 2 + j()]];
+}
+
+/**
+ * The `paper` layer.
+ *
+ * @param {import('./index.js').PaperLayer} layer
+ * @param {import('./layers.js').RenderContext} ctx
+ * @returns {import('./layers.js').Markup}
+ */
+export function paper(layer, ctx) {
+  const { rng } = ctx;
+  const r = regionPx(layer.region ?? { x: 0.2, y: 0.2, width: 0.6, height: 0.6 }, ctx.canvas);
+  const fill = layer.color ? toHex(layer.color) : PAPER;
+  const kinds = layer.kind && layer.kind !== 'mixed' ? [layer.kind] : ['rect', 'blob', 'arch', 'square', 'circle', 'pill'];
+  const wob = layer.wobble ?? 0.5;
+
+  /** @type {{ kind: string, x: number, y: number, w: number, h: number, rot: number, color: string }[]} */
+  let items;
+  if (layer.items?.length) {
+    items = layer.items.map((it, i) => ({
+      kind: it.kind ?? kinds[i % kinds.length],
+      x: r.x + (it.x ?? 0.5) * r.width,
+      y: r.y + (it.y ?? 0.5) * r.height,
+      w: len(it.width ?? it.size, ctx.canvas, r.width * 0.4),
+      h: len(it.height ?? it.size, ctx.canvas, r.height * 0.4),
+      rot: it.rotate ?? rng.range(-4, 4),
+      color: it.color ? toHex(it.color) : fill,
+    }));
+  } else {
+    // A loose collage: cells of a small grid, each shape filling most of its cell.
+    const count = layer.count ?? 4;
+    const cols = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / cols);
+    const cw = r.width / cols;
+    const ch = r.height / rows;
+    items = [];
+    for (let i = 0; i < count; i++) {
+      const kind = kinds[rng.int(0, kinds.length - 1)];
+      const sq = kind === 'square' || kind === 'circle';
+      const fw = cw * rng.range(0.72, 1.02);
+      const fh = sq ? Math.min(fw, ch * 1.02) : ch * rng.range(0.72, 1.02);
+      items.push({
+        kind,
+        x: r.x + cw * ((i % cols) + 0.5) + rng.range(-0.08, 0.08) * cw,
+        y: r.y + ch * (Math.floor(i / cols) + 0.5) + rng.range(-0.08, 0.08) * ch,
+        w: sq ? Math.min(fw, fh) : fw,
+        h: sq ? Math.min(fw, fh) : fh,
+        rot: rng.range(-5, 5),
+        color: fill,
+      });
+    }
+  }
+  const body = items.map((it) => {
+    const size = Math.min(it.w, it.h);
+    const d = scissor(outlineOf(it.kind, it.w, it.h, rng), Math.max(4, size * 0.09), wob * size * 0.018, rng);
+    return `<path${attrs({ d, fill: it.color, transform: `translate(${num(it.x)} ${num(it.y)}) rotate(${num(it.rot)})` })}/>`;
+  }).join('');
+  const a = attrs(layerAttrs(layer));
+  return { defs: '', body: a ? `<g${a}>${body}</g>` : body };
+}
+
+/**
+ * Stroke a polyline by hand: wobbled by smooth noise, drawn in short
+ * overlapping runs whose widths drift, with round caps.
+ *
+ * @param {[number, number][]} pts - Points in px.
+ * @param {object} o
+ * @param {number} o.width - Base stroke width.
+ * @param {number} o.amp - Wobble amplitude in px.
+ * @param {number} o.period - Wobble period in px.
+ * @param {string} o.color
+ * @param {import('./rng.js').Rng} o.rng
+ * @returns {string} Markup.
+ */
+function handLine(pts, { width, amp, period, color, rng }) {
+  const nx = noise1(rng);
+  const ny = noise1(rng);
+  const nw = noise1(rng);
+  const off = rng.range(0, 64);
+  let s = 0;
+  const moved = pts.map((p, i) => {
+    if (i) s += Math.hypot(p[0] - pts[i - 1][0], p[1] - pts[i - 1][1]);
+    return /** @type {[number, number, number]} */ ([p[0] + nx(off + s / period) * amp, p[1] + ny(off + s / period) * amp, s]);
+  });
+  let out = '';
+  const run = Math.max(3, Math.round(moved.length / Math.max(3, s / (period * 0.8))));
+  for (let i = 0; i < moved.length - 1; i += run) {
+    const chunk = moved.slice(i, Math.min(moved.length, i + run + 1));
+    const wdt = width * (0.82 + 0.3 * nw(off + chunk[0][2] / (period * 1.5)));
+    out += `<path${attrs({ d: `M${chunk.map(([x, y]) => `${num(x)} ${num(y)}`).join('L')}`, 'stroke-width': num(wdt) })}/>`;
+  }
+  return `<g${attrs({ fill: 'none', stroke: color, 'stroke-linecap': 'round', 'stroke-linejoin': 'round' })}>${out}</g>`;
+}
+
+/**
+ * The `scribble` layer.
+ *
+ * @param {import('./index.js').ScribbleLayer} layer
+ * @param {import('./layers.js').RenderContext} ctx
+ * @returns {import('./layers.js').Markup}
+ */
+export function scribble(layer, ctx) {
+  const { rng, width: w, height: h } = ctx;
+  const size = len(layer.size, ctx.canvas, '46vmin');
+  const cx = (layer.position?.x ?? 0.5) * w;
+  const cy = (layer.position?.y ?? 0.5) * h;
+  const color = layer.color ? toHex(layer.color) : PAPER;
+  const stroke = len(layer.stroke, ctx.canvas, '1.3vmin');
+  const wob = layer.wobble ?? 0.5;
+  let body = '';
+
+  if (layer.graph) {
+    const g = layer.graph === true ? {} : layer.graph;
+    const n = Math.max(2, Math.min(9, g.nodes ?? rng.int(4, 6)));
+    // Nodes on a jittered lattice so the graph spans the box without clumping.
+    const pts = Array.from({ length: n }, (_, i) => {
+      const a = (i / n) * Math.PI * 2 + rng.range(-0.5, 0.5);
+      const rr = size * 0.5 * rng.range(0.35, 1);
+      return /** @type {[number, number]} */ ([cx + Math.cos(a) * rr, cy + Math.sin(a) * rr]);
+    });
+    pts.sort((p, q) => p[0] - q[0]);
+    const path = [pts[0]];
+    for (let i = 1; i < n; i++) path.push(pts[i]);
+    const lines = [densify(path, size * 0.03)];
+    if (n > 3) lines.push(densify([pts[1], pts[n - 1]], size * 0.03));
+    for (const l of lines) body += handLine(l, { width: stroke, amp: wob * size * 0.006, period: size * 0.12, color, rng });
+    const r = stroke * (g.dot ?? 1.25);
+    body += pts.map(([x, y]) => `<circle${attrs({ cx: x, cy: y, r: r * rng.range(0.9, 1.15), fill: color })}/>`).join('');
+  } else {
+    const icon = layer.icon;
+    const data = typeof icon === 'string' && icon.trim().startsWith('<') ? parseSvgIcon(icon) : typeof icon === 'string' && icon ? resolveIcon(icon) : null;
+    const src = data ?? { body: `<path d="${SPARK_PATH}"/>`, viewBox: [0, 0, 24, 24] };
+    const [vx, vy, vw, vh] = src.viewBox;
+    const k = size / Math.max(vw, vh);
+    const flat = flattenBody(src.body, Math.max(vw, vh) / 90);
+    for (const line of flat.lines) {
+      const pts = line.map(([x, y]) => /** @type {[number, number]} */ ([cx + (x - vx - vw / 2) * k, cy + (y - vy - vh / 2) * k]));
+      body += handLine(pts, { width: stroke, amp: wob * size * 0.01, period: size * 0.16, color, rng });
+    }
+  }
+  const a = attrs(layerAttrs(layer));
+  return { defs: '', body: a ? `<g${a}>${body}</g>` : body };
+}
+
+/** The spark, as an outline to trace when no icon is given. */
+const SPARK_PATH = 'M12 2c.4 4.9 2.1 7.6 7 8.6l3 .4-3 .4c-4.9 1-6.6 3.7-7 8.6-.4-4.9-2.1-7.6-7-8.6L2 11l3-.4c4.9-1 6.6-3.7 7-8.6Z';