@arraypress/covers 0.0.0-stage → 1.0.0

package/src/astro.d.ts

@@ -0,0 +1,31 @@
+import type { CoverOptions, Cover, MIME } from './index.js';
+
+export interface CoverEndpointOptions<T> {
+  /** The entries to make covers for, e.g. `() => getCollection('posts')`. */
+  getEntries: () => T[] | Promise<T[]>;
+  /** An entry's cover. */
+  cover: (entry: T) => CoverOptions | Cover | Promise<CoverOptions | Cover>;
+  /** An entry's slug. Default `entry.id ?? entry.slug`. */
+  slug?: (entry: T) => string;
+  /** The route param, matching the file name (`[slug].webp.ts`). Default `'slug'`. */
+  param?: string;
+  /** Default `'webp'`; match the file name's extension. */
+  format?: keyof typeof MIME;
+  quality?: number;
+  /** Content-hash cache: `true` (default) for `node_modules/.cache/covers`, a directory, or `false`. */
+  cache?: boolean | string;
+}
+
+export interface CoverRouteContext<T> {
+  params: Record<string, string | undefined>;
+  props?: { entry?: T };
+}
+
+/** `getStaticPaths` and `GET` for `src/pages/covers/[slug].webp.ts`. */
+export function coverEndpoint<T>(options: CoverEndpointOptions<T>): {
+  getStaticPaths: () => Promise<{ params: Record<string, string>; props: { entry: T } }[]>;
+  GET: (context: CoverRouteContext<T>) => Promise<Response>;
+};
+
+/** `'/covers/<slug>.webp'`. */
+export function coverUrl(slug: string, options?: { base?: string; format?: keyof typeof MIME }): string;

package/src/astro.js

@@ -0,0 +1,86 @@
+/**
+ * Astro helpers: a static endpoint that renders one cover per entry.
+ *
+ * ```ts
+ * // src/pages/covers/[slug].webp.ts
+ * import { getCollection } from 'astro:content';
+ * import { coverEndpoint } from '@arraypress/covers/astro';
+ *
+ * export const { getStaticPaths, GET } = coverEndpoint({
+ *   getEntries: () => getCollection('posts'),
+ *   cover: (post) => ({ recipe: 'gridTitle', seed: post.id, title: post.data.title }),
+ * });
+ * ```
+ *
+ * `astro build` writes `dist/covers/<slug>.webp` for every entry; `astro
+ * dev` renders on request. Renders are cached by content hash in
+ * `node_modules/.cache/covers`, so an unchanged cover is read back instead
+ * of drawn again, across builds.
+ *
+ * No Astro import: the endpoint is plain `getStaticPaths` / `GET`
+ * functions, so this module works with any Astro version (and is easy to
+ * test).
+ *
+ * @module @arraypress/covers/astro
+ */
+
+import { renderImage, MIME } from './index.js';
+
+/**
+ * Build `getStaticPaths` and `GET` for a cover route.
+ *
+ * @template T
+ * @param {import('./astro.js').CoverEndpointOptions<T>} options
+ * @returns {{ getStaticPaths: () => Promise<{ params: Record<string, string>, props: { entry: T } }[]>, GET: (context: { params: Record<string, string | undefined>, props?: { entry?: T } }) => Promise<Response> }}
+ *
+ * @example
+ * export const { getStaticPaths, GET } = coverEndpoint({
+ *   getEntries: () => getCollection('posts'),
+ *   cover: (post) => ({ recipe: 'aurora', seed: post.id, title: post.data.title, palette: 'dusk' }),
+ * });
+ */
+export function coverEndpoint(options) {
+  const { getEntries, cover } = options;
+  if (typeof getEntries !== 'function' || typeof cover !== 'function') {
+    throw new TypeError('coverEndpoint() needs getEntries and cover functions');
+  }
+  const param = options.param ?? 'slug';
+  const slugOf = options.slug ?? ((/** @type {any} */ e) => String(e.id ?? e.slug));
+  const format = options.format ?? 'webp';
+  const cache = options.cache ?? true;
+
+  const getStaticPaths = async () => {
+    const entries = await getEntries();
+    return entries.map((entry) => ({ params: { [param]: slugOf(entry) }, props: { entry } }));
+  };
+
+  /** @param {{ params: Record<string, string | undefined>, props?: { entry?: any } }} context */
+  const GET = async ({ params, props }) => {
+    let entry = props?.entry;
+    // On-demand routes get no props: look the entry up by its slug.
+    if (entry === undefined) entry = (await getEntries()).find((e) => slugOf(e) === params[param]);
+    if (entry === undefined) return new Response('Not found', { status: 404 });
+    const body = await renderImage(await cover(entry), { format, quality: options.quality, cache });
+    return new Response(new Uint8Array(body), {
+      headers: { 'Content-Type': MIME[format], 'Content-Length': String(body.length) },
+    });
+  };
+
+  return { getStaticPaths, GET };
+}
+
+/**
+ * The URL of an entry's cover, for `<img src>` and `og:image`.
+ *
+ * @param {string} slug - The entry's slug (the route param).
+ * @param {{ base?: string, format?: keyof typeof MIME }} [options] - Route base (default `'/covers'`) and extension (default `'webp'`).
+ * @returns {string} e.g. `'/covers/my-post.webp'`.
+ *
+ * @example
+ * coverUrl(post.id); // '/covers/hello-world.webp'
+ */
+export function coverUrl(slug, options = {}) {
+  const base = (options.base ?? '/covers').replace(/\/+$/, '');
+  const path = String(slug).split('/').map(encodeURIComponent).join('/');
+  return `${base}/${path}.${options.format ?? 'webp'}`;
+}

package/src/color.js

@@ -0,0 +1,246 @@
+/**
+ * Colour parsing and the few colour-space moves palettes need.
+ *
+ * Everything inside the library is a lowercase `#rrggbb` string. Input can
+ * be hex (3, 4, 6 or 8 digits), `rgb()`/`rgba()` or `hsl()`/`hsla()`; alpha
+ * is dropped, since a cover's layers carry their own `opacity`.
+ *
+ * Mixing and contrast come from `@arraypress/color-utils`; this module adds
+ * OKLCH, so derived palettes can rotate hue and set lightness perceptually
+ * instead of in sRGB (where "the same lightness" means very different
+ * things for yellow and blue).
+ *
+ * @module color
+ */
+
+import { hexToRgb, rgbToHex, contrastRatio } from '@arraypress/color-utils';
+
+/**
+ * Parse a CSS colour to `#rrggbb`.
+ *
+ * @param {string} input - `#abc`, `#aabbcc`, `#aabbccdd`, `rgb(…)`, `rgba(…)`, `hsl(…)` or `hsla(…)`.
+ * @returns {string} Lowercase `#rrggbb`.
+ * @throws {TypeError} When the string isn't a colour this function understands.
+ *
+ * @example
+ * toHex('rgb(37 99 235)');   // '#2563eb'
+ * toHex('#FA0');             // '#ffaa00'
+ * toHex('hsl(220 80% 50%)'); // '#1a5ee6'
+ */
+export function toHex(input) {
+  if (typeof input !== 'string') throw new TypeError(`Expected a colour string, got ${typeof input}`);
+  const s = input.trim().toLowerCase();
+
+  const hex = s.match(/^#?([0-9a-f]{3,8})$/);
+  if (hex && [3, 4, 6, 8].includes(hex[1].length)) {
+    let h = hex[1];
+    if (h.length <= 4) h = h.split('').map((c) => c + c).join('');
+    return '#' + h.slice(0, 6);
+  }
+
+  const fn = s.match(/^(rgba?|hsla?)\(([^)]*)\)$/);
+  if (fn) {
+    const parts = fn[2].split(/[\s,/]+/).filter(Boolean);
+    if (parts.length >= 3) {
+      if (fn[1].startsWith('rgb')) {
+        const [r, g, b] = parts.slice(0, 3).map((p) => (p.endsWith('%') ? parseFloat(p) * 2.55 : parseFloat(p)));
+        if ([r, g, b].every(Number.isFinite)) return rgbToHex(r, g, b);
+      } else {
+        const h = parseFloat(parts[0]);
+        const sat = parseFloat(parts[1]) / 100;
+        const l = parseFloat(parts[2]) / 100;
+        if ([h, sat, l].every(Number.isFinite)) return hslToHex(h, sat, l);
+      }
+    }
+  }
+  throw new TypeError(`Unrecognised colour: "${input}"`);
+}
+
+/**
+ * HSL to `#rrggbb`.
+ *
+ * @param {number} h - Hue in degrees.
+ * @param {number} s - Saturation, 0–1.
+ * @param {number} l - Lightness, 0–1.
+ * @returns {string} `#rrggbb`.
+ */
+function hslToHex(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return rgbToHex(f(0) * 255, f(8) * 255, f(4) * 255);
+}
+
+/** @param {number} c - sRGB channel 0–1. @returns {number} Linear channel. */
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+/** @param {number} c - Linear channel. @returns {number} sRGB channel 0–1. */
+const toGamma = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+
+/**
+ * `#rrggbb` to OKLCH.
+ *
+ * @param {string} color - Any colour {@link toHex} accepts.
+ * @returns {{ l: number, c: number, h: number }} Lightness 0–1, chroma (~0–0.37), hue in degrees.
+ *
+ * @example
+ * toOklch('#2563eb'); // { l: 0.546, c: 0.215, h: 262.9 }
+ */
+export function toOklch(color) {
+  const { r, g, b } = hexToRgb(toHex(color));
+  const [lr, lg, lb] = [r, g, b].map((v) => toLinear(v / 255));
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  const h = (Math.atan2(B, A) * 180) / Math.PI;
+  return { l: L, c: Math.hypot(A, B), h: h < 0 ? h + 360 : h };
+}
+
+/**
+ * OKLCH to `#rrggbb`. Out-of-gamut colours are brought in by reducing
+ * chroma (keeping lightness and hue), not by clipping channels, so a
+ * derived colour keeps the hue it was asked for.
+ *
+ * @param {{ l: number, c: number, h: number }} lch - Lightness 0–1, chroma, hue in degrees.
+ * @returns {string} `#rrggbb`.
+ *
+ * @example
+ * fromOklch({ l: 0.7, c: 0.12, h: 30 }); // a soft coral
+ */
+export function fromOklch({ l, c, h }) {
+  const L = Math.max(0, Math.min(1, l));
+  let chroma = Math.max(0, c);
+  for (let i = 0; i < 24; i++) {
+    const rgb = oklabToRgb(L, chroma * Math.cos((h * Math.PI) / 180), chroma * Math.sin((h * Math.PI) / 180));
+    if (rgb.every((v) => v >= -0.0005 && v <= 1.0005) || chroma < 0.001) {
+      return toRgbHex(rgb);
+    }
+    chroma *= 0.9;
+  }
+  return toRgbHex(oklabToRgb(L, 0, 0));
+}
+
+/**
+ * Clamp 0–1 sRGB channels and write them as `#rrggbb`.
+ *
+ * @param {[number, number, number]} rgb
+ * @returns {string}
+ */
+function toRgbHex([r, g, b]) {
+  const c = (/** @type {number} */ v) => Math.max(0, Math.min(1, v)) * 255;
+  return rgbToHex(c(r), c(g), c(b));
+}
+
+/**
+ * OKLab to gamma-encoded sRGB channels (0–1, possibly out of range).
+ *
+ * @param {number} L @param {number} A @param {number} B
+ * @returns {[number, number, number]} sRGB channels.
+ */
+function oklabToRgb(L, A, B) {
+  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3;
+  return [
+    toGamma(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+    toGamma(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+    toGamma(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+  ];
+}
+
+/**
+ * Mix two colours in OKLab (perceptually even, no muddy midpoints).
+ *
+ * @param {string} a - First colour.
+ * @param {string} b - Second colour.
+ * @param {number} t - 0 gives `a`, 1 gives `b`.
+ * @returns {string} `#rrggbb`.
+ *
+ * @example
+ * mixOklab('#ffffff', '#2563eb', 0.1); // a pale blue tint
+ */
+export function mixOklab(a, b, t) {
+  const p = toLab(a);
+  const q = toLab(b);
+  const rgb = oklabToRgb(p[0] + (q[0] - p[0]) * t, p[1] + (q[1] - p[1]) * t, p[2] + (q[2] - p[2]) * t);
+  return toRgbHex(rgb);
+}
+
+/** @param {string} color @returns {[number, number, number]} OKLab. */
+function toLab(color) {
+  const { l, c, h } = toOklch(color);
+  return [l, c * Math.cos((h * Math.PI) / 180), c * Math.sin((h * Math.PI) / 180)];
+}
+
+/**
+ * Mix two colours in OKLCH: lightness and chroma linearly, hue the short
+ * way round. Unlike OKLab, a mix of two far-apart hues stays vivid instead
+ * of passing through grey (orange → blue goes by way of pink, not mud).
+ *
+ * @param {string} a - First colour.
+ * @param {string} b - Second colour.
+ * @param {number} t - 0 gives `a`, 1 gives `b`.
+ * @returns {string} `#rrggbb`.
+ *
+ * @example
+ * mixOklch('#c9502a', '#a9bdf2', 0.5); // a clear rose, not a muddy mauve
+ */
+export function mixOklch(a, b, t) {
+  const p = toOklch(a);
+  const q = toOklch(b);
+  // A near-grey has no meaningful hue: take the other colour's.
+  const ph = p.c < 0.02 ? q.h : p.h;
+  const qh = q.c < 0.02 ? p.h : q.h;
+  const dh = ((qh - ph + 540) % 360) - 180;
+  return fromOklch({ l: p.l + (q.l - p.l) * t, c: p.c + (q.c - p.c) * t, h: (ph + dh * t + 360) % 360 });
+}
+
+/** Near-black used wherever white doesn't read. */
+export const NEAR_BLACK = '#111111';
+
+/**
+ * A colour for a mark on one or more backgrounds: `prefer` when it clears
+ * `ratio` against every one of them, else whichever of white and
+ * near-black has the better worst case.
+ *
+ * For icons and other non-text marks WCAG 1.4.11 asks 3:1 (text needs
+ * 4.5:1), so `onBackground(bg, 3, 'white')` keeps white on mid-tone fills
+ * where a text rule would flip to black.
+ *
+ * @param {string | string[]} backgrounds - The colour(s) under the mark.
+ * @param {number} [ratio=3] - Contrast to clear.
+ * @param {'white' | 'black' | string} [prefer='white'] - The colour to use when it clears `ratio`.
+ * @returns {string} `#rrggbb`.
+ *
+ * @example
+ * onBackground('#e0533d', 3, 'white'); // '#ffffff' (3.6:1)
+ * onBackground('#ffe14d', 3, 'white'); // '#111111'
+ */
+export function onBackground(backgrounds, ratio = 3, prefer = 'white') {
+  const bgs = [].concat(/** @type {any} */ (backgrounds)).map(toHex);
+  const want = prefer === 'white' ? '#ffffff' : prefer === 'black' ? NEAR_BLACK : toHex(prefer);
+  const worst = (/** @type {string} */ c) => Math.min(...bgs.map((b) => contrastRatio(c, b)));
+  if (worst(want) >= ratio) return want;
+  return worst('#ffffff') >= worst(NEAR_BLACK) ? '#ffffff' : NEAR_BLACK;
+}
+
+/**
+ * The colour of an eased multi-stop gradient at `t` (0–1), the way the
+ * `linear` and `radial` layers draw it (smoothstep between stops, in OKLab).
+ *
+ * @param {string[]} colors - Two or more stops, evenly spaced.
+ * @param {number} t - Position along the gradient.
+ * @param {boolean} [ease=true] - Ease between stops.
+ * @returns {string} `#rrggbb`.
+ */
+export function gradientAt(colors, t, ease = true) {
+  const list = colors.map(toHex);
+  if (list.length === 1) return list[0];
+  const n = list.length - 1;
+  const x = Math.max(0, Math.min(1, t)) * n;
+  const i = Math.min(n - 1, Math.floor(x));
+  const f = x - i;
+  return mixOklab(list[i], list[i + 1], ease ? f * f * (3 - 2 * f) : f);
+}

package/src/diagram.js

@@ -0,0 +1,248 @@
+/**
+ * The `diagram` layer: white line-art over a field (the engineering-blog
+ * look). One icon, or a few nodes (icons in outlined square or circle
+ * tiles) joined by arrows, with an optional dotted grid that breaks around
+ * the drawing instead of running through it.
+ *
+ * Layouts (node centres, relative to `position`):
+ *
+ * - `single`   one node
+ * - `row`      2–4 nodes side by side; `arrows: 'loop'` adds an elbow back from the last to the first
+ * - `triangle` one on top, two below; arrows from the top to each (`'both'`: there and back)
+ * - `square`   four corners, arrows round the cycle; a fifth node sits in the middle with dotted spokes and corner brackets
+ * - `stack`    two on top merging into one below
+ * - `hub`      a large first node with the rest around its edge, knocked out of it (a globe with databases)
+ *
+ * Everything is stroked in one colour at one width; stroke icons (Lucide)
+ * are rescaled so their lines match the tiles' lines.
+ *
+ * @module diagram
+ */
+
+import { attrs, num, layerAttrs } from './svg.js';
+import { len } from './geometry.js';
+import { toHex } from './color.js';
+import { resolveIcon, parseSvgIcon } from './icons.js';
+import { gridPath } from './grid.js';
+
+/** A four-point spark: the glyph for a node with no icon. */
+const SPARK = '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';
+
+/**
+ * Resolve a node's icon to markup + viewBox.
+ *
+ * @param {string | undefined} icon - Iconify name, raw SVG, or nothing (the spark).
+ * @returns {{ body: string, viewBox: number[] }}
+ */
+function iconData(icon) {
+  if (typeof icon === 'string' && icon.trim().startsWith('<')) return parseSvgIcon(icon);
+  if (typeof icon === 'string' && icon) return resolveIcon(icon);
+  return { body: `<path fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round" d="${SPARK}"/>`, viewBox: [0, 0, 24, 24] };
+}
+
+/**
+ * An open arrowhead (two strokes) at `to`, pointing away from `from`.
+ *
+ * @param {[number, number]} from @param {[number, number]} to
+ * @param {number} size - Arm length.
+ * @returns {string} Path data.
+ */
+function head(from, to, size) {
+  const a = Math.atan2(to[1] - from[1], to[0] - from[0]);
+  const arm = (t) => [to[0] - size * Math.cos(a + t), to[1] - size * Math.sin(a + t)];
+  const [l, r] = [arm(0.55), arm(-0.55)];
+  return `M${num(l[0])} ${num(l[1])}L${num(to[0])} ${num(to[1])}L${num(r[0])} ${num(r[1])}`;
+}
+
+/**
+ * The `diagram` layer.
+ *
+ * @param {import('./index.js').DiagramLayer} layer
+ * @param {import('./layers.js').RenderContext} ctx
+ * @returns {import('./layers.js').Markup}
+ */
+export function diagram(layer, ctx) {
+  const { width: w, height: h } = ctx;
+  const nodesIn = layer.nodes?.length ? layer.nodes : [{ icon: layer.icon, shape: layer.shape ?? (layer.icon ? 'none' : 'square') }];
+  const n = nodesIn.length;
+  const layout = layer.layout ?? (n === 1 ? 'single' : n === 3 && layer.arrows === 'merge' ? 'stack' : n === 4 && layer.arrows === 'cycle' ? 'square' : 'row');
+  const vmin = Math.min(w, h) / 100;
+  const defaultSize = { single: nodesIn[0].shape === 'none' ? 40 : 22, row: n >= 4 ? 15 : 19, triangle: 19, square: 12, stack: 18, hub: 13 }[layout] ?? 18;
+  const s = len(layer.size, ctx.canvas, defaultSize * vmin);
+  const gap = len(layer.gap, ctx.canvas, s * 0.45);
+  const stroke = len(layer.stroke, ctx.canvas, '0.3vmin');
+  const col = layer.color ? toHex(layer.color) : '#ffffff';
+  const cx = (layer.position?.x ?? 0.5) * w;
+  const cy = (layer.position?.y ?? 0.5) * h;
+  const radius = len(layer.radius, ctx.canvas, s * 0.14);
+  const ah = Math.max(stroke * 3.5, s * 0.09);
+  const pad = s * 0.1;
+
+  // Node centres and sizes.
+  const d = s + gap;
+  /** @type {{ x: number, y: number, size: number, shape: string, icon?: string, brackets?: boolean, knock?: boolean }[]} */
+  const nodes = nodesIn.map((nd, i) => {
+    let x = 0;
+    let y = 0;
+    let size = nd.size != null ? len(nd.size, ctx.canvas) : s;
+    if (layout === 'row') x = (i - (n - 1) / 2) * d;
+    else if (layout === 'triangle') [x, y] = [[0, -d * 0.52], [-d * 0.6, d * 0.5], [d * 0.6, d * 0.5]][i] ?? [0, 0];
+    else if (layout === 'square') {
+      const half = (s + gap * 2.6) / 2 + s * 0.6;
+      [x, y] = [[-half, -half], [half, -half], [half, half], [-half, half], [0, 0]][i] ?? [0, 0];
+    } else if (layout === 'stack') [x, y] = [[-d * 0.58, -d * 0.5], [d * 0.58, -d * 0.5], [0, d * 0.55]][i] ?? [0, 0];
+    else if (layout === 'hub') {
+      if (i === 0) size = nd.size != null ? len(nd.size, ctx.canvas) : s * 3;
+      else {
+        const big = nodesIn[0].size != null ? len(nodesIn[0].size, ctx.canvas) : s * 3;
+        const spots = [[-1, -0.15], [1, -0.15], [0, 0.95], [0, -1]];
+        const [ux, uy] = spots[(i - 1) % spots.length];
+        [x, y] = [(ux * big) / 2, (uy * big) / 2];
+      }
+    }
+    return {
+      x: cx + x,
+      y: cy + y,
+      size,
+      shape: nd.shape ?? (layout === 'hub' ? 'none' : layout === 'square' ? 'circle' : 'square'),
+      icon: nd.icon,
+      brackets: nd.brackets ?? (layout === 'square' && i === 4),
+      knock: layout === 'hub' && i > 0,
+    };
+  });
+
+  /** The point on a node's outline toward another point, padded. */
+  const edge = (/** @type {typeof nodes[number]} */ nd, /** @type {[number, number]} */ toward) => {
+    const dx = toward[0] - nd.x;
+    const dy = toward[1] - nd.y;
+    const r = nd.size / 2 + pad;
+    if (nd.shape === 'circle' || nd.shape === 'none') {
+      const l = Math.hypot(dx, dy) || 1;
+      return /** @type {[number, number]} */ ([nd.x + (dx / l) * r, nd.y + (dy / l) * r]);
+    }
+    const t = r / Math.max(Math.abs(dx), Math.abs(dy), 1e-6);
+    return /** @type {[number, number]} */ ([nd.x + dx * t, nd.y + dy * t]);
+  };
+
+  const lines = [];
+  const dotted = [];
+  /** @param {number} a @param {number} b @param {number} [offset] - Perpendicular shift (for there-and-back pairs). */
+  const arrow = (a, b, offset = 0) => {
+    const A = nodes[a];
+    const B = nodes[b];
+    let p = edge(A, [B.x, B.y]);
+    let q = edge(B, [A.x, A.y]);
+    if (offset) {
+      const l = Math.hypot(q[0] - p[0], q[1] - p[1]) || 1;
+      const [ox, oy] = [(-(q[1] - p[1]) / l) * offset, ((q[0] - p[0]) / l) * offset];
+      p = [p[0] + ox, p[1] + oy];
+      q = [q[0] + ox, q[1] + oy];
+    }
+    lines.push(`M${num(p[0])} ${num(p[1])}L${num(q[0])} ${num(q[1])}${head(p, q, ah)}`);
+  };
+
+  const mode = layer.arrows ?? (layout === 'single' || layout === 'hub' ? false : layout === 'square' ? 'cycle' : true);
+  if (mode) {
+    if (layout === 'row') {
+      for (let i = 0; i < n - 1; i++) arrow(i, i + 1);
+      if (mode === 'loop' && n > 1) {
+        // An elbow under the row, from the last node back to the first.
+        const A = nodes[n - 1];
+        const B = nodes[0];
+        const top = A.y + A.size / 2 + pad;
+        const low = top + gap * 1.1;
+        const r = Math.min(gap * 0.35, s * 0.15);
+        lines.push(`M${num(A.x)} ${num(top)}V${num(low - r)}Q${num(A.x)} ${num(low)} ${num(A.x - r)} ${num(low)}H${num(B.x + r)}Q${num(B.x)} ${num(low)} ${num(B.x)} ${num(low - r)}V${num(top)}${head([B.x, top + 1], [B.x, top], ah)}`);
+      }
+    } else if (layout === 'triangle') {
+      const off = mode === 'both' ? s * 0.12 : 0;
+      for (const b of [1, 2]) {
+        if (nodes[b]) {
+          arrow(0, b, off);
+          if (mode === 'both') arrow(b, 0, off);
+        }
+      }
+    } else if (layout === 'square') {
+      for (let i = 0; i < Math.min(4, n); i++) arrow(i, (i + 1) % Math.min(4, n));
+      if (n > 4) {
+        const C = nodes[4];
+        for (let i = 0; i < 4; i++) {
+          const p = edge(C, [nodes[i].x, nodes[i].y]);
+          const q = edge(nodes[i], [C.x, C.y]);
+          dotted.push(`M${num(p[0])} ${num(p[1])}L${num(q[0])} ${num(q[1])}`);
+        }
+      }
+    } else if (layout === 'stack' && n >= 3) {
+      const [L, R, B] = nodes;
+      const top = L.y + L.size / 2 + pad;
+      const mid = (top + (B.y - B.size / 2 - pad)) / 2;
+      const r = Math.min(gap * 0.3, s * 0.12);
+      lines.push(`M${num(L.x)} ${num(top)}V${num(mid - r)}Q${num(L.x)} ${num(mid)} ${num(L.x + r)} ${num(mid)}H${num(R.x - r)}Q${num(R.x)} ${num(mid)} ${num(R.x)} ${num(mid - r)}V${num(top)}`);
+      const end = B.y - B.size / 2 - pad;
+      lines.push(`M${num(B.x)} ${num(mid)}V${num(end)}${head([B.x, end - 1], [B.x, end], ah)}`);
+    }
+  }
+
+  // Tiles, icons, brackets.
+  let tiles = '';
+  /** @type {string[]} */
+  const icons = [];
+  let knockouts = '';
+  for (const nd of nodes) {
+    const half = nd.size / 2;
+    if (nd.shape === 'square') tiles += `<rect${attrs({ x: nd.x - half, y: nd.y - half, width: nd.size, height: nd.size, rx: Math.min(radius, half) })}/>`;
+    else if (nd.shape === 'circle') tiles += `<circle${attrs({ cx: nd.x, cy: nd.y, r: half })}/>`;
+    if (nd.brackets) {
+      const o = half + pad * 1.6;
+      const arm = nd.size * 0.14;
+      for (const [sx, sy] of [[-1, -1], [1, -1], [1, 1], [-1, 1]]) {
+        const [bx, by] = [nd.x + sx * o, nd.y + sy * o];
+        lines.push(`M${num(bx - sx * arm)} ${num(by)}H${num(bx)}V${num(by - sy * arm)}`);
+      }
+    }
+    if (nd.knock) knockouts += `<circle${attrs({ cx: nd.x, cy: nd.y, r: half * 1.08, fill: '#000' })}/>`;
+    const data = iconData(nd.icon);
+    const [vx, vy, vw, vh] = data.viewBox;
+    const box = nd.shape === 'none' ? nd.size : nd.size * (layer.iconScale ?? 0.44);
+    const k = Math.min(box / vw, box / vh);
+    // Match the icon's line weight to the tiles' (in icon units).
+    const body = data.body.replace(/stroke-width="[^"]*"/g, `stroke-width="${num(stroke / k, 3)}"`);
+    icons.push(`<svg${attrs({ x: nd.x - (vw * k) / 2, y: nd.y - (vh * k) / 2, width: vw * k, height: vh * k, viewBox: `${num(vx)} ${num(vy)} ${num(vw)} ${num(vh)}`, overflow: 'visible', color: col })}>${body}</svg>`);
+  }
+
+  let defs = '';
+  const paint = { fill: 'none', stroke: col, 'stroke-width': stroke, 'stroke-linecap': 'round', 'stroke-linejoin': 'round' };
+  let out = '';
+
+  // The grid behind, broken around every node (and the arrows' span).
+  if (layer.grid) {
+    const g = layer.grid === true ? {} : layer.grid;
+    const div = g.divisions ?? 4;
+    const gpad = len(g.pad, ctx.canvas, s * 0.35);
+    const gaps = nodes.map((nd) => ({ x: nd.x - nd.size / 2 - gpad, y: nd.y - nd.size / 2 - gpad, width: nd.size + gpad * 2, height: nd.size + gpad * 2 }));
+    const xs0 = Math.min(...gaps.map((r) => r.x));
+    const ys0 = Math.min(...gaps.map((r) => r.y));
+    const xs1 = Math.max(...gaps.map((r) => r.x + r.width));
+    const ys1 = Math.max(...gaps.map((r) => r.y + r.height));
+    // Arrows run between nodes: keep the whole drawing's span clear too.
+    if (lines.length) gaps.push({ x: xs0, y: ys0, width: xs1 - xs0, height: ys1 - ys0 + (layout === 'row' && mode === 'loop' ? gap * 1.3 : 0) });
+    const xs = Array.from({ length: div - 1 }, (_, i) => ((i + 1) * w) / div);
+    const ys = Array.from({ length: div - 1 }, (_, i) => ((i + 1) * h) / div);
+    const gs = len(g.stroke, ctx.canvas, '0.3vmin');
+    out += `<path${attrs({ d: gridPath(xs, ys, w, h, gaps), fill: 'none', stroke: g.color ? toHex(g.color) : col, 'stroke-width': gs, 'stroke-linecap': 'round', 'stroke-dasharray': `0 ${num(gs * 3.2)}`, opacity: g.opacity ?? 0.6 })}/>`;
+  }
+
+  if (dotted.length) out += `<path${attrs({ d: dotted.join(''), ...paint, 'stroke-dasharray': `0 ${num(stroke * 3)}` })}/>`;
+  if (lines.length) out += `<path${attrs({ d: lines.join(''), ...paint })}/>`;
+  if (tiles) out += `<g${attrs(paint)}>${tiles}</g>`;
+  if (knockouts) {
+    // The hub is drawn with holes where its satellites sit.
+    const mid = `${ctx.id}k`;
+    defs += `<mask${attrs({ id: mid, maskUnits: 'userSpaceOnUse', x: 0, y: 0, width: w, height: h })}><rect${attrs({ width: w, height: h, fill: '#fff' })}/>${knockouts}</mask>`;
+    icons[0] = `<g mask="url(#${mid})">${icons[0]}</g>`;
+  }
+  out += icons.join('');
+  const a = attrs(layerAttrs(layer));
+  return { defs, body: a ? `<g${a}>${out}</g>` : out };
+}
+