@arraypress/covers 0.0.0-stage → 1.0.0

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * @arraypress/covers — build-time cover images for posts, products and
+ * pages: soft mesh gradients, grain, patterns, stripes, shapes, icons and
+ * type, from one seed, as SVG or WebP/PNG/AVIF/JPEG.
+ *
+ * @module @arraypress/covers
+ */
+
+export { cover, renderSvg, renderImage, coverKey, MIME, DEFAULT_QUALITY, VERSION } from './render.js';
+export { recipes } from './recipes.js';
+export { defineRecipe, loadRecipe } from './json-recipe.js';
+export { palettes, resolvePalette, derivePalette } from './palette.js';
+export { toHex, toOklch, fromOklch, mixOklab, mixOklch, onBackground, gradientAt } from './color.js';
+export { registerIcons } from './icons.js';
+export { resolveSize, ASPECTS } from './geometry.js';
+export { createRng, hashString } from './rng.js';
+export { LAYERS as layers } from './layers.js';
+export { extractPalette } from './extract.js';
+export { RISO_INKS } from './print.js';

package/src/json-recipe.js

@@ -0,0 +1,458 @@
+/**
+ * Declarative recipes: a cover style written as JSON.
+ *
+ * ```json
+ * {
+ *   "$schema": "https://unpkg.com/@arraypress/covers/schema/recipe.schema.json",
+ *   "name": "poster",
+ *   "params": { "background": "solid" },
+ *   "vars": { "ink": { "readable": "@accent" } },
+ *   "layers": [
+ *     { "id": "bg", "type": "solid", "color": "@accent", "when": { "background": "solid" } },
+ *     { "id": "bg", "type": "linear", "colors": ["@accent", "@colors.1"], "when": { "background": "gradient" } },
+ *     { "id": "title", "type": "text", "content": "{title}", "color": "$ink", "when": "title" }
+ *   ]
+ * }
+ * ```
+ *
+ * Values are resolved when the cover is built:
+ *
+ * | Form | Means |
+ * |---|---|
+ * | `"@bg"` … | palette fields (`bg`, `text`, `accent`, `onAccent`, `muted`, `surface`, `mode`, `colors`, `colors.N`) and canvas numbers (`width`, `height`, `u`) |
+ * | `"$name"`, `"$name.0"` | a value from `vars` (and an item or field of it) |
+ * | `"{title}"` | a param or content option (`title`, `label`, `icon`, `image`); `"{opt.x}"` any cover option. A whole-string token keeps the value's type; inside a longer string it's interpolated. |
+ * | `{ "mix": [a, b, t, space?] }` | two colours mixed in OKLab (or `"oklch"`: hue the short way, stays vivid) |
+ * | `{ "readable": c }` | white, or near-black on a light colour (`[c, light, dark]` to choose) |
+ * | `{ "readable": [bgs, ratio, prefer] }` | `prefer` (`"white"`, `"black"`, a colour) if it clears `ratio` on every background, else the better of white / near-black |
+ * | `{ "tone": [color, { l: [min, max], c: [min, max] }] }` | the colour pulled into an OKLCH band (its hue kept) |
+ * | `{ "gradientUnder": [colors, angle, size] }` | the colours a centred square of `size` covers in a linear gradient |
+ * | `{ "pick": [...] }`, `{ "range": [min, max] }`, `{ "int": [min, max] }` | seeded choices |
+ * | `{ "add" \| "sub" \| "mul" \| "div" \| "min" \| "max": [a, b, …] }` | arithmetic; lengths like `"54vw"` become pixels |
+ * | `{ "ramp": [from, to, steps, amount?] }` | `steps` colours from `from` toward `to` |
+ * | `{ "taper": [ratio, steps] }` | `[1, ratio, ratio², …]` |
+ * | `{ "length": value }` | characters in a string (or a number's digits), items in an array |
+ * | `{ "reverse": [...] }` | the array backwards |
+ * | `{ "if": cond, "then": a, "else": b }` | a choice (only the chosen side is evaluated) |
+ *
+ * Conditions (`when` on a layer, `if`): `"title"` (the option is set),
+ * `{ "background": "gradient" }` (a param or option equals a value; `mode`
+ * is the palette's, `aspect` the canvas's: `wide`, `square` or `tall`),
+ * `{ "not": c }`, `{ "all": [...] }`, `{ "any": [...] }`.
+ *
+ * Seeding: `vars` draw from the cover's recipe stream in order; draws inside
+ * a layer use that layer's own stream, so adding a layer never changes
+ * another's choices.
+ *
+ * @module json-recipe
+ */
+
+import { readFileSync } from 'node:fs';
+import { readableText } from '@arraypress/color-utils';
+import { createRng } from './rng.js';
+import { len } from './geometry.js';
+import { toHex, mixOklab, mixOklch, onBackground, gradientAt } from './color.js';
+import { LAYERS, toneColor } from './layers.js';
+import { LAYER_OPTIONS, COMMON } from './layer-options.js';
+
+/** Options every recipe can read without declaring them. */
+const CONTENT = ['title', 'label', 'icon', 'image'];
+
+/** `@` tokens. */
+const PALETTE = ['bg', 'text', 'accent', 'onAccent', 'muted', 'surface', 'mode', 'colors'];
+const CANVAS = ['width', 'height', 'u'];
+
+/** Value operators, by name, with their argument arity. */
+const OPS = /** @type {Record<string, [number, number]>} */ ({
+  mix: [3, 4], readable: [1, 3], gradientUnder: [3, 3], tone: [2, 2], length: [1, 1], pick: [1, Infinity], range: [2, 2], int: [2, 2],
+  add: [1, Infinity], sub: [2, Infinity], mul: [1, Infinity], div: [2, 2], min: [1, Infinity], max: [1, Infinity],
+  ramp: [3, 4], taper: [2, 2], reverse: [1, 1],
+});
+
+/** Keys of a layer that aren't layer options. */
+const LAYER_META = new Set(['id', 'type', 'when']);
+
+/** Top-level keys of a recipe document. */
+const TOP = new Set(['$schema', 'name', 'description', 'params', 'requires', 'vars', 'output', 'layers']);
+
+/** Recipes defined from the same JSON object are reused. */
+const defined = new WeakMap();
+
+/**
+ * The value of a content-like option for conditions: a string, number or
+ * bytes as-is; an override object's `content`, `name`, `svg` or `src`.
+ *
+ * @param {unknown} v
+ * @returns {unknown}
+ */
+function valueOf(v) {
+  if (v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Uint8Array)) {
+    const o = /** @type {any} */ (v);
+    return o.content ?? o.name ?? o.svg ?? o.src;
+  }
+  return v;
+}
+
+/** @param {unknown} v @returns {boolean} */
+const truthy = (v) => {
+  const x = valueOf(v);
+  return x !== undefined && x !== null && x !== false && x !== '' && !(Array.isArray(x) && x.length === 0);
+};
+
+/** @param {unknown} v @returns {v is Record<string, any>} */
+const isPlain = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Uint8Array);
+
+/**
+ * Turn a JSON recipe into a recipe function. The document is validated
+ * first; any problem throws with the recipe's name and the JSON path.
+ *
+ * @param {import('./index.js').RecipeJson} json - The recipe document.
+ * @returns {import('./index.js').Recipe} The recipe (with `.recipeName` and `.json`).
+ * @throws {TypeError} On an invalid document.
+ *
+ * @example
+ * const poster = defineRecipe({ name: 'poster', layers: [{ type: 'solid', color: '@accent' }] });
+ * await renderSvg({ recipe: poster, seed: 'x' });
+ */
+export function defineRecipe(json) {
+  if (defined.has(json)) return defined.get(json);
+  validate(json);
+  const name = json.name ?? 'custom';
+  /** @type {any} */
+  const recipe = (/** @type {Record<string, unknown>} */ options, /** @type {any} */ c) => build(json, name, options ?? {}, c);
+  recipe.recipeName = name;
+  recipe.json = json;
+  defined.set(json, recipe);
+  return recipe;
+}
+
+/**
+ * Read and define a JSON recipe file (synchronous, for use in configs).
+ *
+ * @param {string | URL} path - A `.json` file.
+ * @returns {import('./index.js').Recipe} The recipe.
+ * @throws {TypeError} On invalid JSON or an invalid recipe (the message names the file).
+ *
+ * @example
+ * const house = loadRecipe('./src/covers/house.json');
+ */
+export function loadRecipe(path) {
+  let json;
+  try {
+    json = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new TypeError(`Couldn't read recipe ${String(path)}: ${/** @type {Error} */ (err).message}`);
+  }
+  if (isPlain(json) && !json.name) json.name = String(path).split('/').pop()?.replace(/\.json$/, '');
+  return defineRecipe(json);
+}
+
+// ---------------------------------------------------------------------------
+// Building
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} Scope
+ * @property {string} name
+ * @property {Record<string, unknown>} options
+ * @property {Record<string, unknown>} params
+ * @property {Record<string, unknown>} vars
+ * @property {any} c - The recipe context.
+ * @property {() => import('./rng.js').Rng} rng - The current stream.
+ */
+
+/**
+ * Expand a recipe document into layers.
+ *
+ * @param {import('./index.js').RecipeJson} json
+ * @param {string} name
+ * @param {Record<string, unknown>} options
+ * @param {any} c
+ * @returns {import('./index.js').Layer[]}
+ */
+function build(json, name, options, c) {
+  const params = { ...(json.params ?? {}) };
+  for (const k of Object.keys(params)) if (options[k] !== undefined) params[k] = options[k];
+  /** @type {Scope} */
+  const scope = { name, options, params, vars: {}, c, rng: () => c.rng };
+
+  for (const req of json.requires ?? []) {
+    if (!truthy(lookup(scope, req))) throw new TypeError(`Recipe "${name}" needs the "${req}" option`);
+  }
+  for (const [k, v] of Object.entries(json.vars ?? {})) scope.vars[k] = resolve(scope, v);
+
+  /** @type {Record<string, number>} */
+  const seen = {};
+  const layers = [];
+  for (const layer of json.layers) {
+    const n = (seen[layer.type] = (seen[layer.type] ?? -1) + 1);
+    let stream;
+    const own = { ...scope, rng: () => (stream ??= createRng(`${c.seed ?? ''}:recipe:${layer.id ?? `${layer.type}#${n}`}`)) };
+    if (layer.when !== undefined && !test(own, layer.when)) continue;
+    /** @type {Record<string, unknown>} */
+    const out = { ...(layer.id ? { id: layer.id } : {}), type: layer.type };
+    for (const [k, v] of Object.entries(layer)) {
+      if (LAYER_META.has(k)) continue;
+      const r = resolve(own, v);
+      if (r !== undefined) out[k] = r;
+    }
+    layers.push(/** @type {any} */ (out));
+  }
+  return layers;
+}
+
+/**
+ * Look up a template name: a param, a content option, or `opt.<key>`.
+ *
+ * @param {Scope} s
+ * @param {string} key
+ * @returns {unknown}
+ */
+function lookup(s, key) {
+  if (key.startsWith('opt.')) return s.options[key.slice(4)];
+  if (Object.hasOwn(s.params, key)) return s.params[key];
+  return s.options[key];
+}
+
+/**
+ * Resolve one value.
+ *
+ * @param {Scope} s
+ * @param {unknown} v
+ * @returns {unknown}
+ */
+function resolve(s, v) {
+  if (typeof v === 'string') return resolveString(s, v);
+  if (Array.isArray(v)) return v.map((x) => resolve(s, x));
+  if (!isPlain(v)) return v;
+  if ('if' in v) return test(s, v.if) ? resolve(s, v.then) : resolve(s, v.else);
+  const keys = Object.keys(v);
+  if (keys.length === 1 && Object.hasOwn(OPS, keys[0])) return op(s, keys[0], v[keys[0]]);
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [k, x] of Object.entries(v)) {
+    const r = resolve(s, x);
+    if (r !== undefined) out[k] = r;
+  }
+  return out;
+}
+
+/**
+ * @param {Scope} s
+ * @param {string} str
+ * @returns {unknown}
+ */
+function resolveString(s, str) {
+  if (str.startsWith('@@') || str.startsWith('$$')) return str.slice(1);
+  if (str.startsWith('@')) {
+    const [head, idx] = str.slice(1).split('.');
+    if (CANVAS.includes(head)) return s.c[head];
+    const p = s.c.palette;
+    if (head === 'colors' && idx !== undefined) return p.colors[Number(idx) % p.colors.length];
+    return head === 'colors' ? p.colors.slice() : p[head];
+  }
+  if (str.startsWith('$')) {
+    const [head, ...path] = str.slice(1).split('.');
+    return path.reduce((/** @type {any} */ acc, k) => acc?.[k], s.vars[head]);
+  }
+  const whole = str.match(/^\{([\w.]+)\}$/);
+  if (whole) return lookup(s, whole[1]);
+  return str.replace(/\{([\w.]+)\}/g, (_, k) => {
+    const x = valueOf(lookup(s, k));
+    return x == null ? '' : String(x);
+  });
+}
+
+/**
+ * Evaluate an operator.
+ *
+ * @param {Scope} s
+ * @param {string} name
+ * @param {any} raw - Its arguments, unresolved.
+ * @returns {unknown}
+ */
+function op(s, name, raw) {
+  if (name === 'reverse') {
+    const arr = resolve(s, raw);
+    if (!Array.isArray(arr)) throw new TypeError(`Recipe "${s.name}": "reverse" needs an array`);
+    return arr.slice().reverse();
+  }
+  if (name === 'pick') {
+    const items = Array.isArray(raw) ? raw : resolve(s, raw);
+    return resolve(s, s.rng().pick(/** @type {unknown[]} */ (items)));
+  }
+  const args = /** @type {any[]} */ ([].concat(resolve(s, raw)));
+  const nums = () => args.map((a) => (typeof a === 'number' ? a : len(a, s.c)));
+  switch (name) {
+    case 'readable': {
+      // [backgrounds, ratio, prefer]: prefer a colour that clears a ratio (3 for icons).
+      if (typeof args[1] === 'number') return onBackground(args[0], args[1], args[2] ?? 'white');
+      return readableText(toHex(args[0]), args[1] ? toHex(args[1]) : '#ffffff', args[2] ? toHex(args[2]) : '#111111');
+    }
+    case 'length': return Array.isArray(resolve(s, raw)) ? /** @type {unknown[]} */ (resolve(s, raw)).length : String(args[0] ?? '').length;
+    case 'tone': return toneColor(toHex(args[0]), args[1] ?? {});
+    case 'gradientUnder': {
+      // The colours a centred square of `size` sits on in a linear gradient at `angle`.
+      const [colors, angle, size] = args;
+      const box = typeof size === 'number' ? size : len(size, s.c);
+      const a = (Number(angle) * Math.PI) / 180;
+      const line = Math.abs(s.c.width * Math.sin(a)) + Math.abs(s.c.height * Math.cos(a));
+      const half = ((box / 2) * (Math.abs(Math.sin(a)) + Math.abs(Math.cos(a)))) / line;
+      return [-1, -0.5, 0, 0.5, 1].map((k) => gradientAt(colors, 0.5 + k * half));
+    }
+    case 'mix': {
+      const mixer = args[3] === 'oklch' ? mixOklch : mixOklab;
+      if (args[3] !== undefined && args[3] !== 'oklch' && args[3] !== 'oklab') throw new TypeError(`Recipe "${s.name}": mix space must be "oklab" or "oklch"`);
+      return mixer(toHex(args[0]), toHex(args[1]), Number(args[2]));
+    }
+    case 'range': { const [a, b] = nums(); return s.rng().range(a, b); }
+    case 'int': { const [a, b] = nums(); return s.rng().int(a, b); }
+    case 'add': return nums().reduce((a, b) => a + b);
+    case 'sub': return nums().reduce((a, b) => a - b);
+    case 'mul': return nums().reduce((a, b) => a * b);
+    case 'div': { const [a, b] = nums(); return a / b; }
+    case 'min': return Math.min(...nums());
+    case 'max': return Math.max(...nums());
+    case 'ramp': {
+      const [from, to, steps, amount = 1] = args;
+      return Array.from({ length: steps }, (_, i) => mixOklab(toHex(from), toHex(to), (i / steps) * amount));
+    }
+    case 'taper': { const [ratio, steps] = nums(); return Array.from({ length: steps }, (_, i) => ratio ** i); }
+    default: throw new TypeError(`Unknown operator "${name}"`);
+  }
+}
+
+/**
+ * Evaluate a condition.
+ *
+ * @param {Scope} s
+ * @param {unknown} cond
+ * @returns {boolean}
+ */
+function test(s, cond) {
+  if (typeof cond === 'string') return truthy(lookup(s, cond));
+  if (typeof cond === 'boolean') return cond;
+  if (!isPlain(cond)) return false;
+  if ('not' in cond) return !test(s, cond.not);
+  if ('all' in cond) return cond.all.every((/** @type {unknown} */ c) => test(s, c));
+  if ('any' in cond) return cond.any.some((/** @type {unknown} */ c) => test(s, c));
+  return Object.entries(cond).every(([k, want]) => {
+    const ratio = s.c.width / s.c.height;
+    const have = k === 'mode' ? s.c.palette.mode
+      : k === 'aspect' ? (ratio > 1.15 ? 'wide' : ratio < 0.87 ? 'tall' : 'square')
+      : valueOf(lookup(s, k));
+    return Array.isArray(want) ? want.includes(have) : have === want;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Check a recipe document, throwing on the first problem.
+ *
+ * @param {any} json
+ * @returns {void}
+ * @throws {TypeError}
+ */
+export function validate(json) {
+  if (!isPlain(json)) throw new TypeError('A JSON recipe must be an object');
+  const name = typeof json.name === 'string' ? json.name : 'custom';
+  const fail = (/** @type {string} */ path, /** @type {string} */ msg) => {
+    throw new TypeError(`Recipe "${name}": ${path ? `${path}: ` : ''}${msg}`);
+  };
+
+  for (const k of Object.keys(json)) if (!TOP.has(k)) fail(k, `unknown key (expected ${[...TOP].join(', ')})`);
+  if (json.params !== undefined && !isPlain(json.params)) fail('params', 'must be an object of defaults');
+  if (json.output !== undefined && !(isPlain(json.output) && Object.keys(json.output).every((k) => k === 'lossless'))) fail('output', 'is { "lossless": true | false }');
+  if (json.vars !== undefined && !isPlain(json.vars)) fail('vars', 'must be an object');
+  if (json.requires !== undefined && !(Array.isArray(json.requires) && json.requires.every((/** @type {unknown} */ r) => typeof r === 'string'))) fail('requires', 'must be an array of option names');
+  if (!Array.isArray(json.layers) || json.layers.length === 0) fail('layers', 'must be a non-empty array');
+
+  const names = new Set([...Object.keys(json.params ?? {}), ...CONTENT]);
+  const vars = new Set();
+  const checkName = (/** @type {string} */ path, /** @type {string} */ key) => {
+    if (!key.startsWith('opt.') && !names.has(key)) {
+      fail(path, `unknown param "${key}" (declare it in "params", or use "{opt.${key}}" for any cover option)`);
+    }
+  };
+
+  const checkCond = (/** @type {string} */ path, /** @type {any} */ c) => {
+    if (typeof c === 'string') return checkName(path, c);
+    if (typeof c === 'boolean') return;
+    if (!isPlain(c) || Object.keys(c).length === 0) return fail(path, 'a condition is an option name, { "not": … }, { "all": [...] }, { "any": [...] } or { "option": value }');
+    if ('not' in c) return checkCond(`${path}.not`, c.not);
+    for (const k of ['all', 'any']) {
+      if (k in c) {
+        if (!Array.isArray(c[k])) return fail(`${path}.${k}`, 'must be an array of conditions');
+        return c[k].forEach((/** @type {unknown} */ x, /** @type {number} */ i) => checkCond(`${path}.${k}[${i}]`, x));
+      }
+    }
+    for (const k of Object.keys(c)) if (k !== 'mode' && k !== 'aspect') checkName(`${path}.${k}`, k);
+  };
+
+  const checkValue = (/** @type {string} */ path, /** @type {any} */ v) => {
+    if (typeof v === 'string') {
+      if (v.startsWith('@@') || v.startsWith('$$')) return;
+      if (v.startsWith('@')) {
+        const [head, idx, extra] = v.slice(1).split('.');
+        const ok = extra === undefined && (CANVAS.includes(head) ? idx === undefined : PALETTE.includes(head) && (idx === undefined || (head === 'colors' && /^\d+$/.test(idx))));
+        if (!ok) fail(path, `unknown token "${v}" (use @${PALETTE.join(', @')}, @colors.N, @${CANVAS.join(', @')})`);
+        return;
+      }
+      if (v.startsWith('$')) {
+        const head = v.slice(1).split('.')[0];
+        if (!vars.has(head)) fail(path, `unknown var "${v}" (declare it in "vars" first)`);
+        return;
+      }
+      for (const m of v.matchAll(/\{([^{}]*)\}/g)) {
+        if (!/^[\w.]+$/.test(m[1])) fail(path, `bad template "{${m[1]}}"`);
+        checkName(path, m[1]);
+      }
+      return;
+    }
+    if (Array.isArray(v)) return v.forEach((x, i) => checkValue(`${path}[${i}]`, x));
+    if (!isPlain(v)) return;
+    if ('if' in v) {
+      for (const k of Object.keys(v)) if (!['if', 'then', 'else'].includes(k)) fail(path, `unexpected "${k}" in an "if" (use if, then, else)`);
+      if (!('then' in v)) fail(path, '"if" needs a "then"');
+      checkCond(`${path}.if`, v.if);
+      checkValue(`${path}.then`, v.then);
+      if ('else' in v) checkValue(`${path}.else`, v.else);
+      return;
+    }
+    const keys = Object.keys(v);
+    if (keys.length === 1 && Object.hasOwn(OPS, keys[0])) {
+      const [lo, hi] = OPS[keys[0]];
+      const arg = v[keys[0]];
+      const count = Array.isArray(arg) ? arg.length : 1;
+      // `reverse` takes one array (literal or computed); the rest take argument lists.
+      if (keys[0] !== 'reverse' && (count < lo || count > hi)) fail(`${path}.${keys[0]}`, `takes ${lo === hi ? lo : `${lo}${hi === Infinity ? '+' : `–${hi}`}`} argument${hi === 1 ? '' : 's'}, got ${count}`);
+      if (keys[0] === 'mix' && typeof arg[3] === 'string' && !['oklab', 'oklch'].includes(arg[3])) fail(`${path}.mix`, 'the space is "oklab" or "oklch"');
+      if (keys[0] === 'pick' && Array.isArray(arg) && arg.length === 0) fail(`${path}.pick`, 'needs at least one item');
+      return checkValue(`${path}.${keys[0]}`, arg);
+    }
+    for (const [k, x] of Object.entries(v)) checkValue(`${path}.${k}`, x);
+  };
+
+  for (const [k, v] of Object.entries(json.params ?? {})) checkValue(`params.${k}`, v);
+  for (const r of json.requires ?? []) checkName('requires', r);
+  for (const [k, v] of Object.entries(json.vars ?? {})) {
+    checkValue(`vars.${k}`, v);
+    vars.add(k);
+  }
+  json.layers.forEach((/** @type {any} */ layer, /** @type {number} */ i) => {
+    const path = `layers[${i}]${layer?.id ? ` (${layer.id})` : ''}`;
+    if (!isPlain(layer)) return fail(path, 'must be an object');
+    if (!Object.hasOwn(LAYERS, layer.type)) fail(`${path}.type`, `unknown layer type "${layer.type}" (${Object.keys(LAYERS).join(', ')})`);
+    if (layer.id !== undefined && typeof layer.id !== 'string') fail(`${path}.id`, 'must be a string');
+    if (layer.when !== undefined) checkCond(`${path}.when`, layer.when);
+    const known = { ...LAYER_OPTIONS[layer.type], ...COMMON };
+    for (const [k, v] of Object.entries(layer)) {
+      if (LAYER_META.has(k)) continue;
+      if (!Object.hasOwn(known, k)) fail(`${path}.${k}`, `"${layer.type}" layers have no option "${k}" (${Object.keys(known).join(', ')})`);
+      checkValue(`${path}.${k}`, v);
+    }
+  });
+}

package/src/layer-options.js

@@ -0,0 +1,37 @@
+/**
+ * Every layer type's option names, with one-line descriptions. The JSON
+ * recipe validator rejects names not listed here, and
+ * `scripts/schema.mjs` builds the JSON Schema's autocomplete from it.
+ * Add an option to a layer, add it here.
+ *
+ * @module layer-options
+ */
+
+/** @type {Record<string, Record<string, string>>} Layer options, by type: name → description. */
+export const LAYER_OPTIONS = {
+  solid: { color: 'Fill. Default @bg.' },
+  linear: { colors: 'Two or more colours.', opacities: 'Per-stop opacity.', angle: 'CSS degrees (0 = up). Default seeded.', ease: 'Smoothstep stops. Default true.' },
+  radial: { colors: 'Centre → edge.', x: 'Centre x, 0–1.', y: 'Centre y, 0–1.', radius: 'Length. Default "80vmax".', ease: 'Default true.' },
+  mesh: { colors: 'Blob colours.', hues: 'Distinct colours to use. Default 3.', hueSpan: 'Keep the colours within this many degrees of hue (OKLCH): neighbouring hues only.', count: 'Blobs. Default 4.', blur: 'Length. Default "11vmax".', spread: '0–1. Default 1 (sweep), 0.7 (ring).', size: '[min, max] radius, fractions of the longer side.', base: 'Fill under the fields: "auto" (a gradient across the sweep between the first two colours; default), "bg", a colour, or null.', arrangement: 'sweep (default: long fields along one direction) | ring', angle: 'Sweep direction in degrees. Default seeded.', streak: 'How much more the sweep blurs along than across. Default 1.5.', tone: '{ l: [min, max], c: [min, max] }: pull colours into an OKLCH band.', fold: 'true or { color, to, position, bend, softness, sheen }: a second field meeting the first along a soft curve.', streaks: 'Thin light motion streaks along the sweep. Default 0.', from: 'A photo (path or bytes) to take the colours from (needs sharp).', blobs: 'Explicit [{ x, y, r, squash, rotate, color, opacity }].' },
+  stripes: { direction: 'vertical | horizontal | diagonal', angle: 'For diagonal.', count: 'Stripes. Default 8.', widths: 'even | random | taper | [weights]', taper: 'Ratio for widths: taper.', colors: 'Cycled.', gap: 'Length.', radius: 'Length.', region: '{ x, y, width, height } fractions.', regionRadius: 'Length.' },
+  image: { src: 'A local path, data: URI or bytes ("{image}").', fit: 'cover | contain', focus: 'An anchor, attention or entropy.', region: 'Fractions.', duotone: 'true or [shadow, highlight].', grayscale: 'boolean', normalize: 'Stretch tones first.', tint: 'A colour or { color, amount, blend }.', blur: 'Length.' },
+  grain: { amount: '0–1. Default 0.08.', size: 'Grain px. Default 1.', monochrome: 'Default true.', vary: '"edges": heavier toward the edges (spray paint).' },
+  pattern: { kind: 'grid | dots | lines | rings | waves', size: 'Cell. Length.', stroke: 'Length.', color: 'Default @text.', angle: 'For lines.', center: '{ x, y } fractions.', wavelength: 'Length.', amplitude: 'Length.', fade: 'none | radial | edges | top | bottom | left | right', dash: 'dotted | dashed | [on, off] lengths.', divisions: 'Grid/lines: N equal cells (inner lines only) instead of size.', gaps: '[{ x, y, width, height }] fractions the lines break around.', region: 'Fractions.' },
+  shapes: { kind: 'circle | square | pill | mixed', count: 'Default 6.', size: '[min, max] lengths.', colors: 'Cycled.', placement: 'scatter | row | column', items: '[{ kind, x, y, size, color, rotate, opacity }]', region: 'Fractions.', rotate: 'Tilt squares and pills.', radius: 'Square corner, fraction of size.', outline: 'true or a width.' },
+  icon: { name: 'Iconify name ("lucide:feather") or raw SVG ("{icon}").', svg: 'Raw SVG.', path: 'A path d.', viewBox: '[x, y, w, h] for path.', size: 'Length. Default "24vmin".', color: 'Default the accent on a tile, else @text.', strokeWidth: 'Stroke icons.', anchor: 'One of nine anchors.', position: '{ x, y } fractions.', offset: '{ x, y } lengths.', margin: 'Length.', tile: 'true or { size, radius, color, shadow, border }.' },
+  text: { content: 'The text ("{title}").', font: 'Family. Default Inter.', weight: 'Default 600.', style: 'normal | italic', size: 'Length.', minSize: 'Shrink toward this before truncating.', lineHeight: 'Default 1.12.', letterSpacing: 'Em. Default -0.02.', color: 'Default @text.', align: 'left | center | right', anchor: 'Default bottom-left.', position: '{ x, y } fractions.', offset: '{ x, y } lengths.', margin: 'Length.', maxWidth: 'Length.', maxLines: 'Default 3.', ellipsis: "Default '…'.", balance: 'Default true.', transform: 'none | uppercase | lowercase', label: 'A string or { content, size, weight, color, letterSpacing, transform, gap }.', background: 'A colour or { color, radius, padding, opacity }.' },
+  diagram: { icon: 'One icon (Iconify name or raw SVG), drawn as white line-art.', nodes: '[{ icon, shape: square | circle | none, size, brackets }]', layout: 'single | row | triangle | square | stack | hub', arrows: 'true | false | loop | both | cycle', shape: 'For a single icon: none (default) | square | circle.', size: 'Node size. Length.', gap: 'Space between nodes. Length.', stroke: 'Line width. Default "0.3vmin".', color: 'Line colour. Default white.', radius: 'Tile corner radius.', iconScale: 'Icon size inside a tile, 0–1. Default 0.44.', position: '{ x, y } centre, fractions.', grid: 'true or { divisions, opacity, stroke, color, pad }: a dotted grid that breaks around the drawing.' },
+  paper: { count: 'Shapes in the collage. Default 4.', kind: 'mixed | rect | square | circle | blob | arch | pill', color: 'Default #faf9f5 (paper).', region: 'Where the collage sits, fractions.', items: '[{ kind, x, y, width, height, size, rotate, color }] placed in the region.', wobble: 'How rough the cut edges are, 0–1. Default 0.5.' },
+  scribble: { icon: 'An icon to re-draw by hand (Iconify name or raw SVG).', graph: 'true or { nodes, dot }: a hand-drawn node graph instead.', color: 'Default #faf9f5.', stroke: 'Line width. Default "1.3vmin".', size: 'Length. Default "46vmin".', position: '{ x, y } centre, fractions.', wobble: '0–1. Default 0.5.' },
+  ink: { color: 'The ink: a colour or riso:pink | blue | yellow | teal | red | green | orange | purple | navy | black.', shapes: '[{ kind: circle | ring | half | arch | band | rect | text, x, y, r, size, width, height, thickness, rotate, content, … }]', offset: '{ x, y }: misregistration. Default seeded, 0.3–1% of the short side.', texture: 'grain (default) | halftone | none', speckle: 'Grain: share of paper showing through. Default 0.09.', cell: 'Halftone cell. Length.', dot: 'Halftone dot radius, fraction of the cell.', angle: 'Halftone screen angle: 0 or 45 (default seeded).', density: '[min, max]: uneven ink across the sheet. Default [0.78, 1].' },
+  dither: { colors: '[ground, ink] or [c0, c1, c2] (two dithered bands).', source: 'field (default, noise) | linear | radial', shape: 'none | circle | sphere | arch', size: 'Shape size. Length.', center: '{ x, y } fractions.', matrix: 'bayer4 (default) | bayer8 | noise', cell: 'Pixel size. Length. Default "0.9vmin".', angle: 'For linear.', scale: 'Noise feature size.', gamma: 'Tone curve.', range: '[lo, hi] of the field.' },
+  contour: { levels: 'Isolines. Default 20.', color: 'Default @text.', stroke: 'Default "0.14vmin".', highlight: 'Level to draw in the accent (default seeded), or false.', highlightColor: 'Default @accent.', index: 'Every Nth line thicker. Default 5 (0: none).', indexWeight: 'Index line weight multiple.', scale: 'Noise feature size.', octaves: 'Noise detail.', resolution: 'Grid cells across the short side.' },
+  waveform: { peaks: 'Peak values (any scale).', audio: 'An audio file to decode at build (needs @arraypress/waveform-gen).', bars: 'Bars. Default 88.', style: 'mirrored (default) | bars | line | dots', color: 'Default @accent.', region: 'Fractions.', gap: 'Gap between bars, fraction. Default 0.4.', round: 'Rounded bars. Default true.', stroke: 'Line style width.', caption: 'true (the duration) or text under the wave.', duration: 'Seconds (for the caption).', captionSize: 'Length.', captionColor: 'Default @text.' },
+  tiles: { cols: 'Columns. Default from the series.', rows: 'Rows. Default to keep cells near square.', series: 'Seeds the grid rhythm shared by a series.', colors: 'Shape and cell colours.', ground: 'The page colour among them.', kinds: 'Subset of quarter, half, circle, square, triangle.', merge: 'A 2×2 merged cell. Default true.', region: 'Fractions.' },
+  rule: { y: 'Height, fraction. Default 0.15.', from: '{ x, y } fractions.', to: '{ x, y } fractions.', inset: 'Side inset. Length.', color: 'Default @text.', stroke: 'Default "0.12vmin".' },
+  frame: { inset: 'Length.', radius: 'Length.', stroke: 'Length.', color: 'Default @text.', fill: 'A colour (a card).' },
+};
+
+/** @type {Record<string, string>} Options every layer takes (besides type, id and when). */
+export const COMMON = { opacity: '0–1.', blend: 'A CSS mix-blend-mode.', seed: "This layer's own random stream." };
+