@arraypress/covers 1.0.0 → 1.3.1

package/src/json-recipe.js

@@ -21,6 +21,8 @@
  * |---|---|
  * | `"@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) |
+ * | `"{layout.title.bottom}"`, `"{layout.title.bottom + 12}"` | where an earlier text layer's block landed (`top`, `bottom`, `left`, `right`, `width`, `height`, `x`, `y`, `baseline`, `size`, `lines`), filled in when drawn |
+ * | `"{#col * 40}"` | inside a `repeat`: an expression over the instance (`i`, `row`, `col`, `n`, `odd`, …), filled when drawn |
  * | `"{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) |
@@ -40,6 +42,10 @@
  * is the palette's, `aspect` the canvas's: `wide`, `square` or `tall`),
  * `{ "not": c }`, `{ "all": [...] }`, `{ "any": [...] }`.
  *
+ * Fonts: `"fonts": [{ "name": "Fraunces", "src": "fonts/Fraunces.woff2", "weight": [100, 900] }]`
+ * declares the faces a recipe uses (a path beside the recipe file, or a URL),
+ * so a caller needn't register them.
+ *
  * 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.
@@ -47,33 +53,45 @@
  * @module json-recipe
  */
 
-import { readFileSync } from 'node:fs';
+import { readTextSync, node } from './platform/index.js';
 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 { createRng } from '@logomarks/image-effects/rng';
+import { len } from '@logomarks/image-effects/length';
+import { ANCHORS } from './geometry.js';
+import { toHex, mixOklab, mixOklch, onBackground, gradientAt } from '@logomarks/image-effects/color';
 import { LAYERS, toneColor } from './layers.js';
-import { LAYER_OPTIONS, COMMON } from './layer-options.js';
+import { LAYER_OPTIONS, COMMON, MOTION_OPTIONS } from './layer-options.js';
+import { EFFECT_OPTIONS, EFFECT_COMMON, MASK_GRADIENTS } from '@logomarks/image-effects';
+import { shapesOnly } from './layers/svg.js';
+import { LAYOUT_FIELDS } from './type/layout-ref.js';
+import { MOTION_PRESETS } from './animate/timing.js';
 
 /** Options every recipe can read without declaring them. */
-const CONTENT = ['title', 'label', 'icon', 'image'];
+const CONTENT = ['title', 'label', 'icon', 'image', 'name', 'mark', 'photo', 'cutout', 'date', 'dates', 'time', 'venue', 'address', 'lines', 'lineup', 'tracklist', 'price', 'meta', 'page'];
 
 /** `@` tokens. */
 const PALETTE = ['bg', 'text', 'accent', 'onAccent', 'muted', 'surface', 'mode', 'colors'];
-const CANVAS = ['width', 'height', 'u'];
+const CANVAS = ['width', 'height', 'u', 'bleed', 'safe', 'mm', 'dpi', 'trimWidth', 'trimHeight', 'safeX', 'safeY', 'safeWidth', 'safeHeight'];
 
 /** 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],
+  join: [1, 2], upper: [1, 1], lower: [1, 1], slice: [2, 3],
 });
 
+/** Layer options holding nested layers. */
+const NESTED = ['layers', 'mask', 'knockout', 'clip'];
+
+/** svg-layer options holding raw markup (their `{{name}}` slots are filled; nothing else is touched). */
+const MARKUP = ['markup', 'defs'];
+
 /** 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']);
+const TOP = new Set(['$schema', 'name', 'description', 'params', 'requires', 'vars', 'output', 'layers', 'pages', 'fonts']);
 
 /** Recipes defined from the same JSON object are reused. */
 const defined = new WeakMap();
@@ -139,11 +157,17 @@ export function defineRecipe(json) {
 export function loadRecipe(path) {
   let json;
   try {
-    json = JSON.parse(readFileSync(path, 'utf8'));
+    json = JSON.parse(readTextSync(path));
   } 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$/, '');
+  // Fonts given as paths are beside the recipe.
+  const p = node('path');
+  if (isPlain(json) && Array.isArray(json.fonts) && p) {
+    const dir = p.dirname(path instanceof URL ? path.pathname : String(path));
+    json.fonts = json.fonts.map((/** @type {any} */ f) => (isPlain(f) && typeof f.src === 'string' && !/^[a-z][\w+.-]*:|^\//i.test(f.src) ? { ...f, src: p.resolve(dir, f.src) } : f));
+  }
   return defineRecipe(json);
 }
 
@@ -158,7 +182,7 @@ export function loadRecipe(path) {
  * @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.
+ * @property {() => import('@logomarks/image-effects/rng').Rng} rng - The current stream.
  */
 
 /**
@@ -189,18 +213,60 @@ function build(json, name, options, c) {
     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));
+    layers.push(/** @type {any} */ (resolveLayer(own, layer)));
   }
   return layers;
 }
 
+/**
+ * Resolve one layer's options (and any layers nested in it).
+ *
+ * @param {Scope} s
+ * @param {any} layer
+ * @returns {Record<string, unknown>}
+ */
+function resolveLayer(s, layer) {
+  /** @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;
+    let r;
+    if (NESTED.includes(k) && Array.isArray(v) && v.every((x) => isPlain(x) && typeof x.type === 'string')) {
+      r = v.filter((x) => x.when === undefined || test(s, x.when)).map((x) => resolveLayer(s, x));
+    } else if (k === 'layer' && isPlain(v) && typeof v.type === 'string') {
+      r = resolveLayer(s, v);
+    } else if (layer.type === 'svg' && MARKUP.includes(k) && typeof v === 'string') {
+      r = fillSlots(s, v);
+    } else {
+      r = resolve(s, v);
+    }
+    if (r !== undefined) out[k] = r;
+  }
+  return out;
+}
+
+/**
+ * Fill `{{name}}` slots in raw markup: options and params (escaped; a
+ * markup value such as `{{mark}}` between elements goes in as sanitised
+ * shapes), vars (`{{$name}}`). Palette and canvas tokens (`{{@accent}}`), `{{id}}` and
+ * `{{seed}}` are left for the layer to fill when it's drawn.
+ *
+ * @param {Scope} s
+ * @param {string} markup
+ * @returns {string}
+ */
+function fillSlots(s, markup) {
+  return markup.replace(/\{\{\s*([$\w.]+)\s*\}\}/g, (m, k, at) => {
+    if (k === 'id' || k === 'seed') return m;
+    const v = k.startsWith('$') ? resolveString(s, k) : valueOf(lookup(s, k));
+    if (v == null) return '';
+    // Between elements, a value that is markup (a mark's paths) goes in as shapes; anything else is text.
+    const inTag = markup.lastIndexOf('<', at) > markup.lastIndexOf('>', at);
+    if (!inTag && /^\s*</.test(String(v))) return shapesOnly(String(v));
+    return String(v).replace(/[&<>"']/g, (ch) => /** @type {Record<string, string>} */ ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+  });
+}
+
 /**
  * Look up a template name: a param, a content option, or `opt.<key>`.
  *
@@ -211,7 +277,11 @@ function build(json, name, options, c) {
 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];
+  if (Object.hasOwn(s.options, key) || !key.includes('.')) return s.options[key];
+  // A path into an option: "lineup.0", "meta.venue".
+  const [head, ...rest] = key.split('.');
+  const base = Object.hasOwn(s.params, head) ? s.params[head] : s.options[head];
+  return rest.reduce((/** @type {any} */ acc, k) => acc?.[k], base);
 }
 
 /**
@@ -255,9 +325,12 @@ function resolveString(s, str) {
     const [head, ...path] = str.slice(1).split('.');
     return path.reduce((/** @type {any} */ acc, k) => acc?.[k], s.vars[head]);
   }
+  // Layout references are filled in when the cover is drawn.
+  if (/^\{layout\.[\w-]+\.\w+\s*(?:[+-]\s*[\d.]+)?\}$/.test(str)) return str;
   const whole = str.match(/^\{([\w.]+)\}$/);
   if (whole) return lookup(s, whole[1]);
-  return str.replace(/\{([\w.]+)\}/g, (_, k) => {
+  return str.replace(/\{([\w.]+)\}/g, (m, k) => {
+    if (k.startsWith('layout.')) return m;
     const x = valueOf(lookup(s, k));
     return x == null ? '' : String(x);
   });
@@ -281,6 +354,10 @@ function op(s, name, raw) {
     const items = Array.isArray(raw) ? raw : resolve(s, raw);
     return resolve(s, s.rng().pick(/** @type {unknown[]} */ (items)));
   }
+  if (name === 'join' || name === 'slice' || name === 'upper' || name === 'lower') {
+    const a = Array.isArray(raw) && (name !== 'upper' && name !== 'lower') ? raw.map((x) => resolve(s, x)) : [resolve(s, raw)];
+    return op2(name, /** @type {any[]} */ (a));
+  }
   const args = /** @type {any[]} */ ([].concat(resolve(s, raw)));
   const nums = () => args.map((a) => (typeof a === 'number' ? a : len(a, s.c)));
   switch (name) {
@@ -338,7 +415,9 @@ function test(s, cond) {
   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
+    const have = k === 'page' ? s.options.page ?? 'front'
+      : k === 'format' ? s.c.format
+      : 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;
@@ -367,13 +446,21 @@ export function validate(json) {
   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.pages !== undefined && !(Array.isArray(json.pages) && json.pages.every((/** @type {unknown} */ p) => typeof p === 'string'))) fail('pages', 'must be an array of page names (["front", "back"])');
   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');
+  if (json.fonts !== undefined) {
+    if (!Array.isArray(json.fonts)) fail('fonts', 'must be an array of { name, src, weight, style, axes }');
+    json.fonts.forEach((/** @type {any} */ f, /** @type {number} */ i) => {
+      if (!isPlain(f) || typeof f.name !== 'string' || typeof f.src !== 'string') fail(`fonts[${i}]`, 'needs a name and a src (a path, beside the recipe, or a URL)');
+      for (const k of Object.keys(f)) if (!['name', 'src', 'weight', 'style', 'axes', 'fallback'].includes(k)) fail(`fonts[${i}].${k}`, 'unknown key (name, src, weight, style, axes, fallback)');
+    });
+  }
 
   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)) {
+    if (!key.startsWith('opt.') && !names.has(key.split('.')[0])) {
       fail(path, `unknown param "${key}" (declare it in "params", or use "{opt.${key}}" for any cover option)`);
     }
   };
@@ -389,7 +476,7 @@ export function validate(json) {
         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);
+    for (const k of Object.keys(c)) if (k !== 'mode' && k !== 'aspect' && k !== 'page' && k !== 'format') checkName(`${path}.${k}`, k);
   };
 
   const checkValue = (/** @type {string} */ path, /** @type {any} */ v) => {
@@ -407,6 +494,13 @@ export function validate(json) {
         return;
       }
       for (const m of v.matchAll(/\{([^{}]*)\}/g)) {
+        // `{#…}`: a repeat instance's expression, filled when drawn.
+        if (m[1].startsWith('#')) continue;
+        if (/^layout\.[\w-]+\.\w+\s*(?:[+-]\s*[\d.]+)?$/.test(m[1])) {
+          const field = m[1].split('.')[2].replace(/[\s+-].*$/, '');
+          if (!LAYOUT_FIELDS.includes(/** @type {any} */ (field))) fail(path, `unknown layout field "${field}" (${LAYOUT_FIELDS.join(', ')})`);
+          continue;
+        }
         if (!/^[\w.]+$/.test(m[1])) fail(path, `bad template "{${m[1]}}"`);
         checkName(path, m[1]);
       }
@@ -442,8 +536,7 @@ export function validate(json) {
     checkValue(`vars.${k}`, v);
     vars.add(k);
   }
-  json.layers.forEach((/** @type {any} */ layer, /** @type {number} */ i) => {
-    const path = `layers[${i}]${layer?.id ? ` (${layer.id})` : ''}`;
+  const checkLayer = (/** @type {string} */ path, /** @type {any} */ layer) => {
     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');
@@ -452,7 +545,88 @@ export function validate(json) {
     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);
+      if (k === 'effects') {
+        checkEffects(`${path}.effects`, v);
+      } else if (k === 'motion') {
+        checkMotion(`${path}.motion`, v);
+      } else if (NESTED.includes(k) && Array.isArray(v) && v.every((x) => isPlain(x) && typeof x.type === 'string')) {
+        v.forEach((x, j) => checkLayer(`${path}.${k}[${j}]${x.id ? ` (${x.id})` : ''}`, x));
+      } else if (k === 'layer' && isPlain(v) && typeof v.type === 'string') {
+        checkLayer(`${path}.layer`, v);
+      } else if (layer.type === 'svg' && MARKUP.includes(k) && typeof v === 'string') {
+        for (const m of v.matchAll(/\{\{\s*([$@\w.]+)\s*\}\}/g)) {
+          const t = m[1];
+          if (t === 'id' || t === 'seed' || t.startsWith('@')) continue;
+          if (t.startsWith('$')) { if (!vars.has(t.slice(1).split('.')[0])) fail(`${path}.${k}`, `unknown var "{{${t}}}"`); continue; }
+          checkName(`${path}.${k}`, t);
+        }
+      } else {
+        checkValue(`${path}.${k}`, v);
+        checkAnchor(`${path}.${k}`, layer.type, k, v);
+      }
     }
-  });
+  };
+  // Effects: known kinds, their options, masks and nested layers (computed values are checked when drawn).
+  const checkEffects = (/** @type {string} */ path, /** @type {any} */ v) => {
+    if (!Array.isArray(v)) return checkValue(path, v);
+    v.forEach((e, i) => {
+      const at = `${path}[${i}]`;
+      if (typeof e === 'string') {
+        if (!/[{$@]/.test(e) && !Object.hasOwn(EFFECT_OPTIONS, e)) fail(at, `unknown effect "${e}" (${Object.keys(EFFECT_OPTIONS).join(', ')})`);
+        return;
+      }
+      if (!isPlain(e) || typeof e.kind !== 'string' || 'if' in e) return checkValue(at, e);
+      if (!/[{$@]/.test(e.kind) && !Object.hasOwn(EFFECT_OPTIONS, e.kind)) fail(`${at}.kind`, `unknown effect "${e.kind}" (${Object.keys(EFFECT_OPTIONS).join(', ')})`);
+      const known = { ...(EFFECT_OPTIONS[e.kind] ?? {}), ...EFFECT_COMMON };
+      for (const [k, x] of Object.entries(e)) {
+        if (Object.hasOwn(EFFECT_OPTIONS, e.kind) && !Object.hasOwn(known, k)) fail(`${at}.${k}`, `"${e.kind}" effects have no option "${k}" (${Object.keys(known).join(', ')})`);
+        if (k === 'mask' && isPlain(x)) checkEffectMask(`${at}.mask`, x);
+        else if (k === 'map' && isPlain(x) && Array.isArray(x.layers)) x.layers.forEach((/** @type {any} */ l, /** @type {number} */ j) => checkLayer(`${at}.map.layers[${j}]`, l));
+        else checkValue(`${at}.${k}`, x);
+      }
+    });
+  };
+  // Motion: known presets and options (values are checked as values).
+  const checkMotion = (/** @type {string} */ path, /** @type {any} */ v) => {
+    (Array.isArray(v) ? v : [v]).forEach((m, i) => {
+      const at = Array.isArray(v) ? `${path}[${i}]` : path;
+      const preset = typeof m === 'string' ? m : m?.preset;
+      if (typeof preset === 'string' && !/[{$@]/.test(preset) && !Object.hasOwn(MOTION_PRESETS, preset)) fail(at, `unknown motion preset "${preset}" (${Object.keys(MOTION_PRESETS).join(', ')})`);
+      if (!isPlain(m)) return checkValue(at, m);
+      for (const [k, x] of Object.entries(m)) {
+        if (!Object.hasOwn(MOTION_OPTIONS, k)) fail(`${at}.${k}`, `motions have no option "${k}" (${Object.keys(MOTION_OPTIONS).join(', ')})`);
+        checkValue(`${at}.${k}`, x);
+      }
+    });
+  };
+  const checkEffectMask = (/** @type {string} */ path, /** @type {any} */ m) => {
+    const keys = ['gradient', 'from', 'to', 'center', 'angle', 'aspect', 'invert', 'ease', 'layers'];
+    for (const k of Object.keys(m)) if (!keys.includes(k)) fail(`${path}.${k}`, `unknown mask option (${keys.join(', ')})`);
+    if (Array.isArray(m.layers)) return m.layers.forEach((/** @type {any} */ l, /** @type {number} */ j) => checkLayer(`${path}.layers[${j}]`, l));
+    if (typeof m.gradient !== 'string' || (!/[{$@]/.test(m.gradient) && !MASK_GRADIENTS.includes(m.gradient))) fail(`${path}.gradient`, `"${m.gradient}" (${MASK_GRADIENTS.join(', ')}), or give layers`);
+    for (const [k, x] of Object.entries(m)) checkValue(`${path}.${k}`, x);
+  };
+  // Anchors, as literal strings (templates are checked when drawn).
+  const checkAnchor = (/** @type {string} */ path, /** @type {string} */ type, /** @type {string} */ k, /** @type {any} */ v) => {
+    if (typeof v !== 'string' || /[{$@]/.test(v)) return;
+    const allowed = k === 'anchor' || (k === 'align' && type === 'group') ? Object.keys(ANCHORS) : k === 'focus' && type === 'image' ? [...Object.keys(ANCHORS), 'attention', 'entropy'] : null;
+    if (allowed && !allowed.includes(v)) fail(path, `unknown anchor "${v}" (${allowed.join(', ')})`);
+  };
+  json.layers.forEach((/** @type {any} */ layer, /** @type {number} */ i) => checkLayer(`layers[${i}]${layer?.id ? ` (${layer.id})` : ''}`, layer));
+}
+
+/**
+ * The string and list operators.
+ *
+ * @param {string} name
+ * @param {any[]} args
+ * @returns {unknown}
+ */
+function op2(name, args) {
+  switch (name) {
+    case 'join': return Array.isArray(args[0]) ? args[0].map((x) => valueOf(x)).join(args[1] ?? ' ') : String(valueOf(args[0]) ?? '');
+    case 'upper': return String(valueOf(args[0]) ?? '').toUpperCase();
+    case 'lower': return String(valueOf(args[0]) ?? '').toLowerCase();
+    default: return Array.isArray(args[0]) || typeof args[0] === 'string' ? args[0].slice(args[1], args[2]) : args[0];
+  }
 }

package/src/kit/index.d.ts

@@ -0,0 +1,20 @@
+// A brand kit in one call.
+import type { CoverOptions, Recipe, RecipeJson, RecipeName, FormatName } from '../index.js';
+
+/** The formats a kit renders by default, by group. */
+export const KIT_FORMATS: Readonly<{ social: readonly FormatName[]; release: readonly FormatName[]; print: readonly FormatName[] }>;
+
+/** One rendered piece: SVG (or image bytes), or its pages. */
+export type KitFile = string | Uint8Array | Record<string, string | Uint8Array>;
+
+/** Render a brand on many formats at once. */
+export function kit(brand: CoverOptions, options?: {
+  formats?: FormatName[];
+  /** One recipe for all, or by format (with `default`). Default the built-in `brand`. */
+  recipe?: RecipeName | Recipe | RecipeJson | Partial<Record<FormatName | 'default', RecipeName | Recipe | RecipeJson>>;
+  /** Pages per format (business cards are `['front', 'back']` by default). */
+  pages?: Partial<Record<FormatName, string[]>>;
+  /** `'svg'` (default) or an image format (Node). */
+  render?: 'svg' | 'webp' | 'png' | 'jpeg' | 'avif';
+  overlay?: boolean;
+}): Promise<Partial<Record<FormatName, KitFile>>>;

package/src/kit/index.js

@@ -0,0 +1,58 @@
+/**
+ * A brand kit: one brand, every format, one call.
+ *
+ * @module kit
+ */
+
+import { renderSvg, renderPages, renderImage } from '../render.js';
+
+/** The formats a kit renders by default. */
+export const KIT_FORMATS = Object.freeze({
+  social: ['avatar', 'x-header', 'linkedin-banner', 'linkedin-company', 'youtube-banner', 'youtube-thumbnail', 'facebook-cover', 'instagram-post', 'instagram-square', 'instagram-story', 'instagram-reel', 'tiktok-cover', 'pinterest', 'twitch-banner', 'discord-banner', 'bluesky-banner', 'og'],
+  release: ['release', 'spotify-canvas', 'bandcamp-header'],
+  print: ['business-card', 'letterhead', 'compliment-slip', 'sticker', 'ticket', 'lanyard-pass'],
+});
+
+/** Formats printed on both sides by default. */
+const TWO_SIDED = new Set(['business-card', 'business-card-us']);
+
+/**
+ * Render a brand on many formats at once.
+ *
+ * `brand` is any cover options shared by every piece: `name`, `tagline`,
+ * `palette`, `mark` (path markup on a 512 grid), `photo`, `fonts`, `lines`
+ * (contact lines), `person` and `role`, … `recipe` is one recipe for all
+ * formats (the built-in `brand` by default) or a map from format to recipe
+ * (with `default`). Two-sided formats (business cards, or any in `pages`)
+ * come back as `{ front, back }`.
+ *
+ * @param {Record<string, any>} brand
+ * @param {{ formats?: string[], recipe?: any, pages?: Record<string, string[]>, render?: 'svg' | 'webp' | 'png' | 'jpeg' | 'avif', overlay?: boolean }} [options]
+ * @returns {Promise<Record<string, any>>} By format: an SVG string (or image bytes), or `{ front, back }`.
+ *
+ * @example
+ * const files = await kit({ name: 'Hollow Fern', palette: { accent: '#2f6b4f' }, mark }, { formats: ['avatar', 'x-header', 'business-card'] });
+ * files['business-card'].back; // '<svg …'
+ */
+export async function kit(brand, options = {}) {
+  const formats = options.formats ?? [...KIT_FORMATS.social, ...KIT_FORMATS.release, ...KIT_FORMATS.print];
+  const pick = (/** @type {string} */ f) => {
+    const r = options.recipe;
+    if (r && typeof r === 'object' && !Array.isArray(r) && !r.layers) return r[f] ?? r.default ?? 'brand';
+    return r ?? 'brand';
+  };
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const format of formats) {
+    const input = { seed: brand.seed ?? brand.name ?? 'brand', ...brand, recipe: pick(format), format, overlay: options.overlay };
+    const pages = options.pages?.[format] ?? (TWO_SIDED.has(format) ? ['front', 'back'] : null);
+    const render = options.render ?? 'svg';
+    if (pages) {
+      if (render === 'svg') out[format] = await renderPages(input, { pages });
+      else out[format] = Object.fromEntries(await Promise.all(pages.map(async (page) => [page, await renderImage({ ...input, page }, { format: render })])));
+    } else {
+      out[format] = render === 'svg' ? await renderSvg(input) : await renderImage(input, { format: render });
+    }
+  }
+  return out;
+}

package/src/layer-options.js

@@ -14,12 +14,14 @@ export const LAYER_OPTIONS = {
   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.' },
+  image: { x: 'Box left, px or "%" (with y, width, height: an explicit box instead of region).', y: 'Box top.', width: 'Box width.', height: 'Box height.', src: 'A local path, data: URI, URL (where allowed) or bytes ("{image}").', fit: 'cover | contain | stretch', 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 }.' },
+  icon: { fill: 'A gradient, tile or preset paint for the icon (instead of color).', markup: 'Inner SVG markup on a 512 grid (a mark\'s paths); viewBox overrides the grid.', x: 'Left, px (with y: placed by its top-left corner).', y: 'Top, px.', 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 }.',
+    x: 'First baseline x, px or "%" (like SVG <text>; align is the text-anchor).', y: 'First baseline y.', width: 'Justify every line to this width (like textLength).', justify: 'Justify every line to maxWidth.', lengthAdjust: 'spacingAndGlyphs (default: scale) | spacing', fit: 'width (the block fills width) | lines (each line fills width) | words (a word a line, the widest filling width) | wrap (wrap at width, then fill it) | shrink', stretch: '[sx, sy] or sy: stretch about the first baseline.', axes: 'Variable-font axes: { wdth: 50, SOFT: 100, WONK: 1, opsz: 144 }.', stroke: 'Outline colour.', strokeWidth: 'Outline width.', strokes: '[{ color, width }]: keylines, widest first, under the fill.', fill: 'A colour, a gradient, or "none" (outline type).', path: 'Text on a path: { kind: circle | arc | ellipse | wave, cx, cy, r, start, end, direction } or { d }.', startOffset: 'Along the path: 0–1 or px. Default 0.5 (centred).', fitPath: 'Space the text to fill the path (a ring); a number leaves that gap.', dy: 'Shift off the path.', render: 'outline (default) | live (<text> with @font-face)', autoColors: '[light, dark] for color: "auto". Default ["#ffffff", "#0b0b0b"].', autoThreshold: 'color: "auto" takes the dark colour above this backdrop luma (0–1). Default 0.72.', lines: 'Reserved.',
+    spans: '[{ content, font, weight, style, axes, scale, size, color, letterSpacing, dy }]: mixed runs on the same lines.', glyphs: '{ scale, scaleX, scaleY, dx, dy, rotate, color, origin, advance }: per-glyph arrays (cycled; spaces skipped).', fallback: 'A family (or list) for characters the font lacks; then fonts registered with fallback: true, then the built-in symbols.', split: 'words: a word a line.', dash: 'Dashes on the stroke: [on, off] lengths, dashed or dotted.', extrude: 'A depth, or { depth, angle, color, to, steps }: block extrusion.', maxHeight: 'Shrink the block to this height.' },
   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.' },
@@ -30,8 +32,45 @@ export const LAYER_OPTIONS = {
   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).' },
+  repeat: { layer: 'The layer to repeat (or layers, drawn as a group). {#…} expressions use i, n, row, col, rows, cols, x, y, angle, odd.', layers: 'Several layers to repeat as one.', rows: 'Grid rows.', cols: 'Grid columns.', count: 'Instances in a ring or a line.', step: '[dx, dy] between instances (a grid divides the canvas by default).', x: 'Where the first instance goes.', y: 'Where the first instance goes.', cx: 'Ring centre x.', cy: 'Ring centre y.', radius: 'Ring radius.', start: 'Ring start, degrees (0 = up, clockwise).', sweep: 'Ring sweep, degrees. Default 360.', turn: 'Turn ring instances to their angle. Default true.', odd: 'Overrides for odd instances (a checkerboard on a grid).', cycle: '[overrides] taken in turn.', skip: 'An expression ({#…}): leave the instance out when true.' },
+  defs: { layers: 'Layers with ids, for use layers to draw (nothing is drawn here).' },
+  use: { ref: 'The id of a layer in an earlier defs layer.', x: 'Where the copy goes.', y: 'Where the copy goes.', rotate: 'Degrees, about the copy\'s origin.', scale: 'A number or [sx, sy].', place: 'A transform instead of x, y, rotate and scale.', with: 'Options for this copy only.' },
+  group: { layers: 'The layers inside.', viewBox: '[x, y, w, h]: its own design grid (children use its units).', x: 'Box left, px.', y: 'Box top.', width: 'Box width.', height: 'Box height.', fit: 'contain (default) | cover | stretch | width | height', align: 'Where a fitted grid sits: center, top-left, …', clipToBox: 'Clip to the box.' },
+  shape: { kind: 'rect | circle | ellipse | line | polygon | polyline | star | burst | scallop | rays | ring | sector | arch | wave | path | cut (the print format\'s die-cut)', origin: 'rotate about [x, y] (px or "%") instead of the centre.', open: 'arch: the arc and sides only (stroked).', soft: 'A blur radius: soft orbs, drawn padded (no edge fade, no square edge).', dashOffset: 'Where the dash pattern starts.', outset: 'cut: grow (or shrink) the outline.', items: '[{ kind, … }]: several shapes in one layer.', x: 'px or "%".', y: 'px or "%".', width: 'px.', height: 'px.', cx: 'Centre x.', cy: 'Centre y.', r: 'Radius.', rx: 'Ellipse x radius.', ry: 'Ellipse y radius.', x1: 'Line/wave start x.', y1: 'Line start y.', x2: 'End x.', y2: 'End y.', points: 'Polygon [[x, y], …], or star/burst/scallop point count.', inner: 'Star/burst inner radius (≤1: fraction) or ring inner radius.', count: 'Rays.', start: 'Sector start, degrees (0 = up, clockwise).', end: 'Sector end.', depth: 'Scallop depth.', amplitude: 'Wave height.', wavelength: 'Wave length.', phase: 'Wave phase, radians.', band: 'Wave: fill a band this tall.', d: 'Path data.', viewBox: 'Path: its grid, drawn into x, y, width, height.', radius: 'Rect corner radius.', edge: 'Rect edges: deckle | torn | zigzag | wave | scallop, or { kind, size, step, sides }.', rotate: 'Degrees about its centre.', fill: 'A colour, a gradient { type, colors, stops, opacities, angle, spread, length, rx, ry, … }, a tile { type: "tile", kind: checker | stripes | dots | grid | custom, size, colors, ratio, angle, markup } or a preset { preset: "chrome" | "steel" | "gold" }.', stroke: 'A colour or a gradient.', strokeWidth: 'Length.', strokes: '[{ color, width, dash }]: keylines under the shape.', dash: 'dashed | dotted | [on, off].', linecap: 'butt | round | square', linejoin: 'miter | round | bevel', fillRule: 'nonzero | evenodd' },
+  svg: { markup: 'Raw SVG, drawn in the canvas (or from viewBox). Tokens: {{@accent}}, {{@colors.1}}, {{@width}}, {{id}}, {{seed}}, and in JSON recipes {{title}} or any option.', defs: 'Raw SVG for <defs>.', viewBox: '[x, y, w, h] of the markup.', x: 'Box left.', y: 'Box top.', width: 'Box width.', height: 'Box height.', fit: 'contain (default) | cover | stretch', align: 'xMidYMid etc.' },
+  table: { rows: 'Rows: arrays of cells, or objects read by column key ("{tracklist}"). A cell is text or { content, weight, size, color, align, … }.', columns: '[{ x, align, width, key, weight, size, color, font, letterSpacing, transform, opacity }]', x: 'Left, px.', y: 'First baseline, px.', size: 'Type size. Default "2.2vmin".', lineHeight: 'Line step inside a cell.', rowHeight: 'Fixed row step.', rowGap: 'Extra space between rows.', font: 'Family.', weight: 'Default 400.', style: 'normal | italic', axes: 'Variable axes.', color: 'Default @text.', letterSpacing: 'Em.', header: 'Style for the first row.', rules: 'true or { at: between | each | top, color, width, opacity, x1, x2, above }.', columnWidth: 'Column step when columns give no x.' },
+  barcode: { value: 'Text to encode (Code 128).', content: 'Same as value.', kind: 'code128 (default) | seeded (decorative)', x: 'px.', y: 'px.', width: 'px.', height: 'px.', color: 'Default @text.', text: 'true (the value) or text under the bars.', size: 'Text size.', font: 'Family.', weight: 'Text weight.', letterSpacing: 'Em.' },
+  perforation: { kind: 'holes (default) | dashes | notches', x: 'A vertical line at x.', x1: 'Start x.', y1: 'Start y.', x2: 'End x.', y2: 'End y.', size: 'Hole or notch radius.', gap: 'Spacing.', inset: 'Space before the first hole.', color: 'Default @text (or punch it with knockout).', strokeWidth: 'Dashes width.' },
+  tear: { from: '[x, y] where the tear starts (edge to edge).', to: '[x, y] where it ends.', side: 'Which side keeps the sheet: above (default) | below | left | right', color: 'The sheet (a colour, a gradient, or "none" for just the edge).', sheetOpacity: 'The sheet\'s opacity.', step: 'Spacing of the jagged points.', jitter: 'How jagged.', rip: 'false, or { color, width, opacity }: the torn white edge.', fibres: 'false, or { color, width, opacity, length: [min, max], spread }.', ripColor: 'Colour of the rip and fibres. Default #fff6fb.' },
+  texture: { kind: 'paper | creases | concrete | speck | wood | folds | dust', color: 'Fibre, aggregate or dust colour.', amount: 'Paper: fibre density.', frequency: 'Noise frequency (number or [x, y]).', octaves: 'Noise octaves.', depth: 'Creases: relief.', azimuth: 'Creases: light direction.', elevation: 'Creases: light height.', x: 'Folds: vertical fold positions, fractions.', y: 'Folds: horizontal fold positions, fractions.', width: 'Folds: band width.', strength: 'Folds: shading.', count: 'Dust: specks.', size: 'Dust: [min, max] radius.', region: 'Clip to { x, y, width, height } (px or "%").' },
 };
 
 /** @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." };
+export const COMMON = {
+  opacity: '0–1.', blend: 'A CSS mix-blend-mode.', seed: "This layer's own random stream.",
+  transform: '{ translate, rotate, scale, skewX, skewY, mirror: x | y, origin } (on text, a case keyword is still the case).',
+  effects: '[{ kind, mask, colorSpace, … }]: filters, pixel effects and copies, in order (see docs/effects.md; kinds in EFFECTS).',
+  mask: 'Layers whose luminance masks this one (white shows).', knockout: 'Layers cut out of this one.', clip: 'Layers this one shows only inside.',
+  area: 'trim | safe | bleed, or { x, y, width, height } fractions: draw the layer in that box.',
+  motion: 'A motion, a preset name (drift | spin | breathe | blink | marquee), or a list: plays in the SVG as CSS keyframes (see MOTION_OPTIONS).',
+};
+
+/** @type {Record<string, string>} A motion's options. */
+export const MOTION_OPTIONS = {
+  preset: 'drift | spin | breathe | blink | marquee: its defaults, under whatever else is set.',
+  translate: '[x, y] to move by (px in the layer\'s grid, "%" or lengths), or a list of points [[0, 0], [x, y], …].',
+  path: 'Travel a path from where the layer is: path data, { d }, or a text-path kind ({ kind: circle | ellipse | arc | wave, … }).',
+  rotate: 'Degrees to turn to, or a list of angles.',
+  scale: 'A factor to grow to, or a list.', scaleX: 'Horizontal factor, or a list.', scaleY: 'Vertical factor, or a list.',
+  opacity: '0–1 to fade to (times the layer\'s own), or a list.',
+  origin: '[x, y] the turn and scale are about (px, "%" or lengths). Default the centre.',
+  vary: 'Layer options as lists of stops ({ axes: { wdth: [62, 150] } }): drawn frame by frame, played as outline morphs.',
+  frames: 'vary: frames drawn per stop. Default 12.',
+  marquee: 'true: text on a path runs along it, one repeat of its words per duration (they must repeat).',
+  duration: 'Seconds per iteration. Default 2 (or the preset\'s).',
+  delay: 'Seconds before it starts; negative starts it part-way.',
+  easing: 'linear | ease | in | out | inOut | step, or [x1, y1, x2, y2]: between each pair of stops.',
+  direction: 'normal | reverse | alternate | alternate-reverse',
+  iterations: 'A number, or "infinite" (the default).',
+};
 

package/src/layers/barcode.d.ts

@@ -0,0 +1,19 @@
+// The `barcode` layer.
+import type { Color, Length, BaseLayer, Anchor } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+
+export interface BarcodeLayer extends BaseLayer {
+  type: 'barcode';
+  /** Encoded as Code 128 (set B). */
+  value?: string;
+  content?: string;
+  kind?: 'code128' | 'seeded';
+  x?: Length | `${number}%`; y?: Length | `${number}%`; width?: Length | `${number}%`; height?: Length | `${number}%`;
+  color?: Color;
+  text?: boolean | string;
+  size?: Length; font?: string; weight?: number; letterSpacing?: number;
+}
+
+
+/** Draw a Code 128 barcode (or decorative bars). */
+export function barcode(layer: BarcodeLayer, ctx: RenderContext): Promise<Markup>;

package/src/layers/barcode.js

@@ -0,0 +1,63 @@
+/**
+ * The `barcode` layer.
+ *
+ * @module layers/barcode
+ */
+
+import { attrs, num } from '@logomarks/image-effects/svg';
+import { len } from '@logomarks/image-effects/length';
+import { toHex } from '@logomarks/image-effects/color';
+import { faceFor, setLine } from '../type/line.js';
+import { pos, wrap, contentOf } from './util.js';
+import { code128 } from './code128.js';
+
+/**
+ * `barcode` — a real Code 128 barcode of `value` (scannable at print
+ * sizes), or `kind: 'seeded'` decorative bars. `x`, `y`, `width`, `height`
+ * in px; `color`; `text: true` (the value under it) or any text; `quiet`
+ * zones are left to you.
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {Promise<import('../layers.js').Markup>}
+ */
+export async function barcode(layer, ctx) {
+  const x = pos(layer.x ?? '10%', 'x', ctx.canvas);
+  const y = pos(layer.y ?? '80%', 'y', ctx.canvas);
+  const w = layer.width != null ? pos(layer.width, 'x', ctx.canvas) : ctx.width * 0.3;
+  const h = layer.height != null ? pos(layer.height, 'y', ctx.canvas) : ctx.height * 0.08;
+  const color = layer.color ? toHex(layer.color) : ctx.palette.text;
+  /** @type {number[]} */
+  let widths;
+  if (layer.kind === 'seeded') {
+    widths = [];
+    let total = 0;
+    const target = 100;
+    while (total < target) {
+      const bar = ctx.rng.pick([0.7, 1.1, 1.6, 2.3]);
+      const gap = ctx.rng.pick([0.7, 1.1, 1.7]);
+      widths.push(bar, gap);
+      total += bar + gap;
+    }
+    widths.pop();
+  } else {
+    widths = code128(String(layer.value ?? contentOf(layer.content) ?? '0000'));
+  }
+  const total = widths.reduce((a, b) => a + b, 0);
+  const k = w / total;
+  let d = '';
+  let at = x;
+  widths.forEach((m, i) => {
+    if (i % 2 === 0) d += `M${num(at, 3)} ${num(y)}h${num(m * k, 3)}v${num(h)}h${num(-m * k, 3)}Z`;
+    at += m * k;
+  });
+  let body = `<path${attrs({ d, fill: color })}/>`;
+  if (layer.text) {
+    const label = layer.text === true ? String(layer.value ?? '') : String(layer.text);
+    const size = len(layer.size, ctx.canvas, h * 0.18);
+    const face = await faceFor(ctx, { font: layer.font, weight: layer.weight ?? 400 });
+    const line = setLine({ face, text: label, size, tracking: (layer.letterSpacing ?? 0.1) * size, x: x + w / 2, y: y + h + size * 1.1, align: 'center' });
+    body += `<path${attrs({ d: line.d, fill: color })}/>`;
+  }
+  return { defs: '', body: wrap(layer, body) };
+}

package/src/layers/code128.d.ts

@@ -0,0 +1,4 @@
+// Code 128 (set B).
+
+/** Module widths (bar, space, bar, …) for a string, start to stop with its check symbol. */
+export function code128(value: string): number[];