@arraypress/covers 1.0.0 → 1.1.0

package/src/layers/expr.js

@@ -0,0 +1,121 @@
+/**
+ * Per-instance values for `repeat`: `{#…}` expressions over the instance's
+ * variables (`i`, `row`, `col`, `n`, `rows`, `cols`, `angle`, `x`, `y`,
+ * `odd`), with `+ - * / %`, parentheses, comparisons, `a ? b : c` and
+ * `min`, `max`, `abs`, `floor`, `round`, `sin`, `cos`, `pick(i, a, b, …)`.
+ * No other code runs: it's a small parser, not `eval`.
+ *
+ * @module layers/expr
+ */
+
+/** Functions an expression can call. */
+const FNS = /** @type {Record<string, (...a: any[]) => any>} */ ({
+  min: Math.min, max: Math.max, abs: Math.abs, floor: Math.floor, ceil: Math.ceil, round: Math.round,
+  sin: (/** @type {number} */ d) => Math.sin((d * Math.PI) / 180), cos: (/** @type {number} */ d) => Math.cos((d * Math.PI) / 180),
+  pick: (/** @type {number} */ i, /** @type {any[]} */ ...xs) => xs[((Math.floor(i) % xs.length) + xs.length) % xs.length],
+});
+
+/** @param {string} src @returns {string[]} */
+function tokens(src) {
+  const out = [];
+  const re = /\s*(?:(\d*\.?\d+(?:e[+-]?\d+)?)|([A-Za-z_]\w*)|('[^']*'|"[^"]*")|(<=|>=|==|!=|&&|\|\||[-+*/%()?:,<>!]))/gy;
+  let m;
+  let at = 0;
+  while (at < src.length && (m = re.exec(src))) {
+    out.push(m[0].trim());
+    at = re.lastIndex;
+  }
+  if (src.slice(at).trim()) throw new TypeError(`Can't read "${src.slice(at).trim()}" in {#${src}}`);
+  return out;
+}
+
+/**
+ * Evaluate an expression.
+ *
+ * @param {string} src
+ * @param {Record<string, number | string | boolean>} vars
+ * @returns {any}
+ * @throws {TypeError} On an unknown name or bad syntax.
+ */
+export function evaluate(src, vars) {
+  const t = tokens(src);
+  let k = 0;
+  const peek = () => t[k];
+  const take = (/** @type {string} */ want) => { if (t[k] !== want) throw new TypeError(`Expected "${want}" in {#${src}}`); k++; };
+  /** @returns {any} */
+  const ternary = () => {
+    const c = or();
+    if (peek() !== '?') return c;
+    k++;
+    const a = ternary();
+    take(':');
+    const b = ternary();
+    return c ? a : b;
+  };
+  const or = () => { let v = and(); while (peek() === '||') { k++; const r = and(); v = v || r; } return v; };
+  const and = () => { let v = cmp(); while (peek() === '&&') { k++; const r = cmp(); v = v && r; } return v; };
+  const cmp = () => {
+    let v = add();
+    while (['<', '>', '<=', '>=', '==', '!='].includes(peek())) {
+      const op = t[k++];
+      const r = add();
+      v = op === '<' ? v < r : op === '>' ? v > r : op === '<=' ? v <= r : op === '>=' ? v >= r : op === '==' ? v === r : v !== r;
+    }
+    return v;
+  };
+  const add = () => { let v = mul(); while (peek() === '+' || peek() === '-') { const op = t[k++]; const r = mul(); v = op === '+' ? v + r : v - r; } return v; };
+  const mul = () => { let v = unary(); while (peek() === '*' || peek() === '/' || peek() === '%') { const op = t[k++]; const r = unary(); v = op === '*' ? v * r : op === '/' ? v / r : ((v % r) + r) % r; } return v; };
+  /** @returns {any} */
+  const unary = () => {
+    if (peek() === '-') { k++; return -unary(); }
+    if (peek() === '!') { k++; return !unary(); }
+    return atom();
+  };
+  const atom = () => {
+    const tok = t[k++];
+    if (tok === undefined) throw new TypeError(`Unexpected end of {#${src}}`);
+    if (tok === '(') { const v = ternary(); take(')'); return v; }
+    if (/^\d|^\./.test(tok)) return Number(tok);
+    if (/^['"]/.test(tok)) return tok.slice(1, -1);
+    if (peek() === '(') {
+      if (!Object.hasOwn(FNS, tok)) throw new TypeError(`Unknown function "${tok}" in {#${src}} (${Object.keys(FNS).join(', ')})`);
+      k++;
+      const args = [];
+      if (peek() !== ')') { args.push(ternary()); while (peek() === ',') { k++; args.push(ternary()); } }
+      take(')');
+      return FNS[tok](...args);
+    }
+    if (!Object.hasOwn(vars, tok)) throw new TypeError(`Unknown name "${tok}" in {#${src}} (${Object.keys(vars).join(', ')})`);
+    return vars[tok];
+  };
+  const v = ternary();
+  if (k < t.length) throw new TypeError(`Unexpected "${t[k]}" in {#${src}}`);
+  return v;
+}
+
+/** A whole-value expression, or one inside a string. */
+const WHOLE = /^\{#([^{}]+)\}$/;
+const INSIDE = /\{#([^{}]+)\}/g;
+
+/**
+ * A value with its `{#…}` expressions evaluated (a whole-string expression
+ * keeps its type). Nested layers are left alone: an inner `repeat` fills
+ * its own.
+ *
+ * @param {any} v
+ * @param {Record<string, number | string | boolean>} vars
+ * @returns {any}
+ */
+export function fill(v, vars) {
+  if (typeof v === 'string') {
+    const whole = WHOLE.exec(v);
+    if (whole) return evaluate(whole[1], vars);
+    return v.includes('{#') ? v.replace(INSIDE, (_, e) => String(evaluate(e, vars))) : v;
+  }
+  if (Array.isArray(v)) return v.map((x) => fill(x, vars));
+  if (v && typeof v === 'object' && !(v instanceof Uint8Array)) {
+    if (v.type === 'repeat') return v;
+    return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, fill(x, vars)]));
+  }
+  return v;
+}

package/src/layers/geometry.d.ts

@@ -0,0 +1,6 @@
+// Shape geometry for the `shape` layer.
+import type { ShapeSpec } from './shape.js';
+import type { RenderContext } from '../render/context.js';
+
+/** A shape's path data (or an opening element tag), bounds and transform. */
+export function geometry(s: ShapeSpec, ctx: RenderContext): { d?: string; el?: string; transform?: string; box: { x: number; y: number; width: number; height: number } };

package/src/layers/geometry.js

@@ -0,0 +1,238 @@
+/**
+ * Shape geometry for the `shape` layer: path data (or an element) and
+ * bounds for each kind, and jittered edges for deckled, torn and zigzag
+ * paper.
+ *
+ * @module layers/geometry
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { pos } from './util.js';
+import { cutPath } from '../formats/cut.js';
+import { invert, apply } from '../effects/transform.js';
+
+
+/**
+ * Seeded jitter along a polyline, for deckled, torn or zigzag edges.
+ *
+ * @param {[number, number]} a @param {[number, number]} b
+ * @param {{ kind: string, size: number, step: number }} e
+ * @param {import('../rng.js').Rng} rng
+ * @returns {[number, number][]} Points from a (exclusive) to b (inclusive).
+ */
+function edgePoints(a, b, e, rng) {
+  const L = Math.hypot(b[0] - a[0], b[1] - a[1]);
+  const n = Math.max(2, Math.round(L / e.step));
+  const nx = -(b[1] - a[1]) / L;
+  const ny = (b[0] - a[0]) / L;
+  const out = /** @type {[number, number][]} */ ([]);
+  for (let i = 1; i <= n; i++) {
+    const t = i / n;
+    let off = 0;
+    if (i < n) {
+      if (e.kind === 'zigzag') off = (i % 2 ? 1 : -1) * e.size / 2;
+      else if (e.kind === 'wave') off = Math.sin(t * n * Math.PI) * e.size / 2;
+      else if (e.kind === 'scallop') off = -Math.abs(Math.sin(t * n * Math.PI / 2)) * e.size;
+      else off = (rng.next() - 0.5) * e.size * (e.kind === 'torn' ? 2 : 1);
+    }
+    out.push([a[0] + (b[0] - a[0]) * t + nx * off, a[1] + (b[1] - a[1]) * t + ny * off]);
+  }
+  return out;
+}
+
+/**
+ * One shape's path data and bounds.
+ *
+ * @param {any} s - The shape.
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {{ d?: string, el?: string, box: { x: number, y: number, width: number, height: number } }}
+ */
+export function geometry(s, ctx) {
+  const c = ctx.canvas;
+  const X = (/** @type {any} */ v, /** @type {any} */ f = 0) => pos(v ?? f, 'x', c);
+  const Y = (/** @type {any} */ v, /** @type {any} */ f = 0) => pos(v ?? f, 'y', c);
+  const L = (/** @type {any} */ v, /** @type {any} */ f = 0) => len(v, c, f);
+  const kind = s.kind ?? 'rect';
+  const P = (/** @type {number} */ x, /** @type {number} */ y) => `${num(x)} ${num(y)}`;
+  switch (kind) {
+    case 'rect': {
+      const x = X(s.x);
+      const y = Y(s.y);
+      const w = s.width != null ? X(s.width) : c.width - x;
+      const h = s.height != null ? Y(s.height) : c.height - y;
+      const box = { x, y, width: w, height: h };
+      if (s.edge) {
+        const e = typeof s.edge === 'string' ? { kind: s.edge } : s.edge;
+        const size = L(e.size, e.kind === 'deckle' ? '0.6vmin' : '1.2vmin');
+        const step = L(e.step, e.kind === 'zigzag' ? size : e.kind === 'deckle' ? '0.9vmin' : '2vmin');
+        const sides = new Set(e.sides ?? ['top', 'right', 'bottom', 'left']);
+        const corners = /** @type {[number, number][]} */ ([[x, y], [x + w, y], [x + w, y + h], [x, y + h]]);
+        const names = ['top', 'right', 'bottom', 'left'];
+        let d = `M${P(x, y)}`;
+        for (let k = 0; k < 4; k++) {
+          const a = corners[k];
+          const b = corners[(k + 1) % 4];
+          if (sides.has(names[k])) for (const q of edgePoints(a, b, { kind: e.kind, size, step }, ctx.rng)) d += `L${P(q[0], q[1])}`;
+          else d += `L${P(b[0], b[1])}`;
+        }
+        return { d: `${d}Z`, box };
+      }
+      return { el: `<rect${attrs({ x, y, width: w, height: h, rx: s.radius != null ? L(s.radius) : undefined })}`, box };
+    }
+    case 'circle': {
+      const cx = X(s.cx, '50%');
+      const cy = Y(s.cy, '50%');
+      const r = L(s.r, '20vmin');
+      return { el: `<circle${attrs({ cx, cy, r })}`, box: { x: cx - r, y: cy - r, width: 2 * r, height: 2 * r } };
+    }
+    case 'ellipse': {
+      const cx = X(s.cx, '50%');
+      const cy = Y(s.cy, '50%');
+      const rx = L(s.rx, '20vmin');
+      const ry = L(s.ry, '12vmin');
+      return { el: `<ellipse${attrs({ cx, cy, rx, ry })}`, box: { x: cx - rx, y: cy - ry, width: 2 * rx, height: 2 * ry } };
+    }
+    case 'line': {
+      const x1 = X(s.x1);
+      const y1 = Y(s.y1);
+      const x2 = X(s.x2, '100%');
+      const y2 = Y(s.y2, s.y1 ?? 0);
+      return { d: `M${P(x1, y1)}L${P(x2, y2)}`, box: { x: Math.min(x1, x2), y: Math.min(y1, y2), width: Math.abs(x2 - x1), height: Math.abs(y2 - y1) } };
+    }
+    case 'polygon':
+    case 'polyline': {
+      const pts = (s.points ?? []).map((/** @type {any} */ q) => [X(q[0]), Y(q[1])]);
+      const xs = pts.map((/** @type {number[]} */ q) => q[0]);
+      const ys = pts.map((/** @type {number[]} */ q) => q[1]);
+      return { d: pts.map((/** @type {number[]} */ q, /** @type {number} */ i) => `${i ? 'L' : 'M'}${P(q[0], q[1])}`).join('') + (kind === 'polygon' ? 'Z' : ''), box: { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) } };
+    }
+    case 'star':
+    case 'burst':
+    case 'scallop':
+    case 'rays':
+    case 'ring':
+    case 'sector': {
+      const cx = X(s.cx, '50%');
+      const cy = Y(s.cy, '50%');
+      const r = L(s.r, '20vmin');
+      const rot = ((s.rotate ?? 0) * Math.PI) / 180;
+      const box = { x: cx - r, y: cy - r, width: 2 * r, height: 2 * r };
+      const at = (/** @type {number} */ a, /** @type {number} */ rr) => P(cx + rr * Math.sin(a + rot), cy - rr * Math.cos(a + rot));
+      if (kind === 'ring') {
+        const r2 = L(s.inner, r * 0.6);
+        return { d: `M${P(cx - r, cy)}a${num(r)} ${num(r)} 0 1 0 ${num(2 * r)} 0a${num(r)} ${num(r)} 0 1 0 ${num(-2 * r)} 0ZM${P(cx - r2, cy)}a${num(r2)} ${num(r2)} 0 1 1 ${num(2 * r2)} 0a${num(r2)} ${num(r2)} 0 1 1 ${num(-2 * r2)} 0Z`, box };
+      }
+      if (kind === 'sector') {
+        // A pie slice, `start` to `end` degrees (0 at 12 o'clock, clockwise): quarter and half discs.
+        const a0 = ((s.start ?? 0) * Math.PI) / 180;
+        const a1 = ((s.end ?? 90) * Math.PI) / 180;
+        const large = Math.abs(a1 - a0) > Math.PI ? 1 : 0;
+        return { d: `M${P(cx, cy)}L${at(a0, r)}A${num(r)} ${num(r)} 0 ${large} 1 ${at(a1, r)}Z`, box };
+      }
+      if (kind === 'rays') {
+        const n = s.count ?? 24;
+        let d = '';
+        for (let i = 0; i < n; i += 2) {
+          const a0 = (i / n) * Math.PI * 2;
+          const a1 = ((i + 1) / n) * Math.PI * 2;
+          d += `M${P(cx, cy)}L${at(a0, r)}L${at(a1, r)}Z`;
+        }
+        return { d, box };
+      }
+      if (kind === 'scallop') {
+        const bumps = s.points ?? 12;
+        const depth = L(s.depth, r * 0.08);
+        let d = '';
+        for (let deg = 0; deg <= 360; deg += 2) {
+          const a = (deg * Math.PI) / 180;
+          d += `${deg ? 'L' : 'M'}${at(a, r - depth + depth * Math.cos(a * bumps))}`;
+        }
+        return { d: `${d}Z`, box };
+      }
+      const n = s.points ?? (kind === 'burst' ? 16 : 5);
+      const inner = s.inner != null ? (s.inner <= 1 ? r * s.inner : L(s.inner)) : r * (kind === 'burst' ? 0.8 : 0.42);
+      let d = '';
+      for (let i = 0; i < n * 2; i++) d += `${i ? 'L' : 'M'}${at((i / (n * 2)) * Math.PI * 2, i % 2 ? inner : r)}`;
+      return { d: `${d}Z`, box };
+    }
+    case 'arch': {
+      // A window: straight sides, a round top.
+      const x = X(s.x);
+      const y = Y(s.y);
+      const w = X(s.width, '40%');
+      const h = Y(s.height, '50%');
+      const r = w / 2;
+      // `open`: the arc and its sides only (a stroked arch).
+      return { d: `M${P(x, y + h)}V${num(y + r)}A${num(r)} ${num(r)} 0 0 1 ${P(x + w, y + r)}V${num(y + h)}${s.open ? '' : 'Z'}`, box: { x, y, width: w, height: h } };
+    }
+    case 'wave': {
+      const x1 = X(s.x1);
+      const x2 = X(s.x2, '100%');
+      const y = Y(s.y, '50%');
+      const amp = L(s.amplitude, '2vmin');
+      const wl = L(s.wavelength, '20vmin');
+      const ph = s.phase ?? 0;
+      let d = '';
+      for (let x = x1, i = 0; x <= x2 + 0.01; x += Math.max(1, wl / 32), i++) d += `${i ? 'L' : 'M'}${P(x, y + Math.sin(((x - x1) / wl) * Math.PI * 2 + ph) * amp)}`;
+      if (s.band) {
+        const bh = L(s.band);
+        let back = '';
+        for (let x = x2; x >= x1 - 0.01; x -= Math.max(1, wl / 32)) back += `L${P(x, y + bh + Math.sin(((x - x1) / wl) * Math.PI * 2 + ph) * amp)}`;
+        d += `${back}Z`;
+      }
+      return { d, box: { x: x1, y: y - amp, width: x2 - x1, height: 2 * amp } };
+    }
+    case 'path': {
+      // Path data, optionally drawn from a viewBox into a box (x, y, width, height).
+      const d = String(s.d ?? '');
+      if (s.viewBox) {
+        const [vx, vy, vw, vh] = s.viewBox;
+        const x = X(s.x);
+        const y = Y(s.y);
+        const w = s.width != null ? X(s.width) : vw;
+        const h = s.height != null ? Y(s.height) : (w / vw) * vh;
+        return { d, box: { x, y, width: w, height: h }, el: undefined, ...{ transform: `translate(${num(x)} ${num(y)}) scale(${num(w / vw, 5)} ${num(h / vh, 5)}) translate(${num(-vx)} ${num(-vy)})` } };
+      }
+      return { d, box: { x: 0, y: 0, width: c.width, height: c.height } };
+    }
+    case 'cut': {
+      // The print format's die-cut (the trim's corners or shape), in this layer's units.
+      return cutGeometry(/** @type {any} */ (ctx).cut, L(s.outset, 0), /** @type {any} */ (ctx).matrix, c);
+    }
+    default:
+      throw new TypeError(`Unknown shape kind "${kind}" (rect, circle, ellipse, line, polygon, polyline, star, burst, scallop, rays, ring, sector, arch, wave, path, cut)`);
+  }
+}
+
+/**
+ * The cut outline, from canvas px into the layer's units (through the
+ * inverse of everything drawn above it). Without a print format, the canvas.
+ *
+ * @param {{ x: number, y: number, width: number, height: number, cut?: any, mm?: number } | undefined} cut - Trim box and cut, canvas px.
+ * @param {number} outset - Grow (or, negative, shrink) the outline, in the layer's units.
+ * @param {import('../effects/transform.js').Affine | undefined} matrix - Layer units to canvas px.
+ * @param {{ width: number, height: number }} canvas
+ * @returns {{ d: string, box: { x: number, y: number, width: number, height: number } }}
+ */
+function cutGeometry(cut, outset, matrix, canvas) {
+  const inv = matrix ? invert(matrix) : undefined;
+  const k = matrix ? Math.sqrt(Math.abs(matrix[0] * matrix[3] - matrix[1] * matrix[2])) : 1;
+  const trim = cut ?? { x: 0, y: 0, width: canvas.width * k, height: canvas.height * k };
+  const o = outset * k;
+  const box = { x: trim.x - o, y: trim.y - o, width: trim.width + 2 * o, height: trim.height + 2 * o };
+  const segs = cutPath(cut?.cut, box, (cut?.mm ?? 1) * 1, o);
+  const at = (/** @type {number} */ x, /** @type {number} */ y) => (inv ? apply(inv, x, y) : [x, y]);
+  let d = '';
+  const xs = [];
+  const ys = [];
+  for (const seg of segs) {
+    d += seg.cmd;
+    for (let i = 0; i < seg.pts.length; i += 2) {
+      const [X, Y] = at(seg.pts[i], seg.pts[i + 1]);
+      xs.push(X); ys.push(Y);
+      d += `${i ? ' ' : ''}${num(X)} ${num(Y)}`;
+    }
+  }
+  return { d, box: { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) } };
+}

package/src/layers/index.d.ts

@@ -0,0 +1,18 @@
+// The poster layers (1.1).
+export { shape } from './shape.js';
+export type { ShapeLayer, ShapeSpec } from './shape.js';
+export { svg, sanitize, shapesOnly } from './svg.js';
+export type { SvgLayer } from './svg.js';
+export { table } from './table.js';
+export type { TableLayer, TableCell } from './table.js';
+export { barcode } from './barcode.js';
+export type { BarcodeLayer } from './barcode.js';
+export { code128 } from './code128.js';
+export { perforation } from './perforation.js';
+export type { PerforationLayer } from './perforation.js';
+export { tear } from './tear.js';
+export type { TearLayer } from './tear.js';
+export { texture } from './texture.js';
+export type { TextureLayer } from './texture.js';
+export { expandRepeat } from './repeat.js';
+export type { RepeatLayer } from './repeat.js';

package/src/layers/index.js

@@ -0,0 +1,15 @@
+/**
+ * The poster layers (1.1): one module each.
+ *
+ * @module layers
+ */
+
+export { shape } from './shape.js';
+export { svg, sanitize, shapesOnly } from './svg.js';
+export { table } from './table.js';
+export { barcode } from './barcode.js';
+export { code128 } from './code128.js';
+export { perforation } from './perforation.js';
+export { tear } from './tear.js';
+export { texture } from './texture.js';
+export { expandRepeat } from './repeat.js';

package/src/layers/perforation.d.ts

@@ -0,0 +1,14 @@
+// The `perforation` layer.
+import type { Color, Length, BaseLayer, Anchor } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+
+export interface PerforationLayer extends BaseLayer {
+  type: 'perforation';
+  kind?: 'holes' | 'dashes' | 'notches';
+  x?: Length | `${number}%`; x1?: Length | `${number}%`; y1?: Length | `${number}%`; x2?: Length | `${number}%`; y2?: Length | `${number}%`;
+  size?: Length; gap?: Length; inset?: Length; color?: Color; strokeWidth?: Length;
+}
+
+
+/** Draw a tear-off line. */
+export function perforation(layer: PerforationLayer, ctx: RenderContext): Markup;

package/src/layers/perforation.js

@@ -0,0 +1,47 @@
+/**
+ * The `perforation` layer.
+ *
+ * @module layers/perforation
+ */
+
+import { attrs, num } from '../svg.js';
+import { len } from '../geometry.js';
+import { toHex } from '../color.js';
+import { pos, wrap } from './util.js';
+
+
+/**
+ * `perforation` — a tear-off line: `holes` (punched dots), `dashes` or
+ * `notches` (half-circle bites at both ends), from `x1, y1` to `x2, y2`.
+ * In a layer's `knockout` it punches real holes through it.
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {import('../layers.js').Markup}
+ */
+export function perforation(layer, ctx) {
+  const x1 = pos(layer.x1 ?? layer.x ?? '50%', 'x', ctx.canvas);
+  const y1 = pos(layer.y1 ?? 0, 'y', ctx.canvas);
+  const x2 = pos(layer.x2 ?? layer.x ?? '50%', 'x', ctx.canvas);
+  const y2 = pos(layer.y2 ?? '100%', 'y', ctx.canvas);
+  const color = layer.color ? toHex(layer.color) : ctx.palette.text;
+  const kind = layer.kind ?? 'holes';
+  const L = Math.hypot(x2 - x1, y2 - y1);
+  const size = len(layer.size, ctx.canvas, kind === 'notches' ? '1.6vmin' : '0.25vmin');
+  const gap = len(layer.gap, ctx.canvas, kind === 'dashes' ? '0.8vmin' : '1.2vmin');
+  let body = '';
+  if (kind === 'dashes') {
+    body = `<path${attrs({ d: `M${num(x1)} ${num(y1)}L${num(x2)} ${num(y2)}`, stroke: color, 'stroke-width': len(layer.strokeWidth, ctx.canvas, '0.2vmin'), 'stroke-dasharray': `${num(gap)} ${num(gap * 0.8)}`, fill: 'none' })}/>`;
+  } else if (kind === 'notches') {
+    body = `<circle${attrs({ cx: x1, cy: y1, r: size, fill: color })}/><circle${attrs({ cx: x2, cy: y2, r: size, fill: color })}/>`;
+  } else {
+    const inset = len(layer.inset, ctx.canvas, gap);
+    const n = Math.max(1, Math.floor((L - 2 * inset) / gap));
+    for (let i = 0; i <= n; i++) {
+      const t = (inset + i * ((L - 2 * inset) / n)) / L;
+      body += `<circle${attrs({ cx: x1 + (x2 - x1) * t, cy: y1 + (y2 - y1) * t, r: size })}/>`;
+    }
+    body = `<g fill="${color}">${body}</g>`;
+  }
+  return { defs: '', body: wrap(layer, body) };
+}

package/src/layers/repeat.d.ts

@@ -0,0 +1,29 @@
+// The `repeat` layer.
+import type { Length, Layer, BaseLayer } from '../index.js';
+
+/** `repeat`: a layer drawn many times (a grid, a ring, a line), with per-instance `{#…}` values. */
+export interface RepeatLayer extends BaseLayer {
+  type: 'repeat';
+  /** The template (or `layers`, drawn as a group). */
+  layer?: Layer;
+  layers?: Layer[];
+  rows?: number; cols?: number;
+  count?: number;
+  /** `[dx, dy]` between instances (a grid's default divides the canvas). */
+  step?: [Length, Length];
+  x?: Length | `${number}%`; y?: Length | `${number}%`;
+  cx?: Length | `${number}%`; cy?: Length | `${number}%`; radius?: Length;
+  /** Degrees, 0 up, clockwise. */
+  start?: number; sweep?: number;
+  /** Turn each ring instance to its angle (default true). */
+  turn?: boolean;
+  /** Overrides for odd instances (a checkerboard on a grid). */
+  odd?: Record<string, unknown>;
+  /** Overrides taken in turn. */
+  cycle?: Record<string, unknown>[];
+  /** An expression (`{#…}`) that leaves an instance out when true. */
+  skip?: string;
+}
+
+/** The instances of a repeat, as a group of placed copies. */
+export function expandRepeat(layer: RepeatLayer, ctx: { width: number; height: number; canvas: { width: number; height: number } }): Layer;

package/src/layers/repeat.js

@@ -0,0 +1,90 @@
+/**
+ * `repeat`: one layer (or a stack) drawn many times, so tile grids, rings
+ * of marks and poster walls are data, not generator scripts.
+ *
+ * - A grid: `rows` × `cols`, `step: [dx, dy]` apart (default the canvas
+ *   divided by the count), starting at `x`, `y`.
+ * - A ring: `count` round `cx`, `cy` at `radius`, from `start` degrees (0
+ *   up, clockwise) over `sweep` (default 360), each turned to its angle
+ *   (`turn: false` keeps them upright).
+ * - A line: `count` instances `step: [dx, dy]` apart.
+ *
+ * Each instance is the template (`layer`, or `layers` as a group) placed at
+ * its point, with `{#…}` expressions filled in from its variables: `i`,
+ * `n` (the count), `row`, `col`, `rows`, `cols`, `x`, `y`, `angle` and
+ * `odd` (a checkerboard on a grid, every other one otherwise). `odd` holds
+ * overrides for odd instances, `cycle` a list of overrides taken in turn,
+ * and `skip` an expression that leaves an instance out.
+ *
+ * @module layers/repeat
+ */
+
+import { num } from '../svg.js';
+import { len } from '../geometry.js';
+import { pos } from './util.js';
+import { fill, evaluate } from './expr.js';
+
+/**
+ * The instances of a repeat, as a group of placed copies.
+ *
+ * @param {any} layer
+ * @param {{ width: number, height: number, canvas: { width: number, height: number } }} ctx
+ * @returns {any} A `group` layer.
+ */
+export function expandRepeat(layer, ctx) {
+  const template = layer.layer ?? { type: 'group', layers: layer.layers ?? [] };
+  const places = points(layer, ctx);
+  const grid = layer.rows != null || layer.cols != null;
+  const key = layer.seed ?? layer.id ?? 'repeat';
+  const layers = [];
+  places.forEach((p, i) => {
+    const odd = grid ? (p.row + p.col) % 2 === 1 : i % 2 === 1;
+    const vars = { i, n: places.length, row: p.row, col: p.col, rows: p.rows, cols: p.cols, x: p.x, y: p.y, angle: p.angle, odd };
+    if (layer.skip != null && evaluate(String(layer.skip).replace(/^\{#|\}$/g, ''), vars)) return;
+    let one = { ...template };
+    if (odd && layer.odd) one = { ...one, ...layer.odd };
+    if (layer.cycle?.length) one = { ...one, ...layer.cycle[i % layer.cycle.length] };
+    const turn = p.angle && layer.turn !== false ? ` rotate(${num(p.angle, 3)})` : '';
+    layers.push({ type: 'group', seed: `${key}#${i}`, transform: `translate(${num(p.x, 3)} ${num(p.y, 3)})${turn}`, layers: [fill(one, vars)] });
+  });
+  return { type: 'group', layers, opacity: layer.opacity, blend: layer.blend };
+}
+
+/**
+ * Where the instances go.
+ *
+ * @param {any} l
+ * @param {{ width: number, height: number, canvas: { width: number, height: number } }} ctx
+ * @returns {{ x: number, y: number, row: number, col: number, rows: number, cols: number, angle: number }[]}
+ */
+function points(l, ctx) {
+  const c = ctx.canvas;
+  const x0 = pos(l.x ?? 0, 'x', c);
+  const y0 = pos(l.y ?? 0, 'y', c);
+  if (l.rows != null || l.cols != null) {
+    const rows = Math.max(1, Math.round(l.rows ?? 1));
+    const cols = Math.max(1, Math.round(l.cols ?? 1));
+    const dx = l.step ? len(l.step[0], c) : (c.width - x0) / cols;
+    const dy = l.step ? len(l.step[1], c) : (c.height - y0) / rows;
+    const out = [];
+    for (let row = 0; row < rows; row++) for (let col = 0; col < cols; col++) out.push({ x: x0 + col * dx, y: y0 + row * dy, row, col, rows, cols, angle: 0 });
+    return out;
+  }
+  const count = Math.max(0, Math.round(l.count ?? 0));
+  if (l.radius != null) {
+    const cx = pos(l.cx ?? '50%', 'x', c);
+    const cy = pos(l.cy ?? '50%', 'y', c);
+    const r = len(l.radius, c);
+    const sweep = l.sweep ?? 360;
+    const start = l.start ?? 0;
+    // A full circle doesn't put the last on the first.
+    const stepA = count > 1 ? sweep / (Math.abs(sweep) >= 360 ? count : count - 1) : 0;
+    return Array.from({ length: count }, (_, i) => {
+      const angle = start + i * stepA;
+      const a = (angle * Math.PI) / 180;
+      return { x: cx + r * Math.sin(a), y: cy - r * Math.cos(a), row: 0, col: i, rows: 1, cols: count, angle };
+    });
+  }
+  const [dx, dy] = l.step ? [len(l.step[0], c), len(l.step[1], c)] : [0, 0];
+  return Array.from({ length: count }, (_, i) => ({ x: x0 + i * dx, y: y0 + i * dy, row: 0, col: i, rows: 1, cols: count, angle: 0 }));
+}

package/src/layers/shape.d.ts

@@ -0,0 +1,46 @@
+// The `shape` layer.
+import type { Color, Length, BaseLayer, Anchor } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+import type { Paint } from '../effects/paint.js';
+
+/** One exact shape (see the README's `shape` table). */
+export interface ShapeSpec {
+  kind?: 'rect' | 'circle' | 'ellipse' | 'line' | 'polygon' | 'polyline' | 'star' | 'burst' | 'scallop' | 'rays' | 'ring' | 'sector' | 'arch' | 'wave' | 'path' | 'cut';
+  x?: Length | `${number}%`; y?: Length | `${number}%`; width?: Length | `${number}%`; height?: Length | `${number}%`;
+  cx?: Length | `${number}%`; cy?: Length | `${number}%`; r?: Length; rx?: Length; ry?: Length;
+  x1?: Length | `${number}%`; y1?: Length | `${number}%`; x2?: Length | `${number}%`; y2?: Length | `${number}%`;
+  points?: number | [Length, Length][];
+  inner?: Length; count?: number; start?: number; end?: number; depth?: Length;
+  amplitude?: Length; wavelength?: Length; phase?: number; band?: Length;
+  d?: string; viewBox?: [number, number, number, number];
+  radius?: Length;
+  edge?: 'deckle' | 'torn' | 'zigzag' | 'wave' | 'scallop' | { kind: 'deckle' | 'torn' | 'zigzag' | 'wave' | 'scallop'; size?: Length; step?: Length; sides?: ('top' | 'right' | 'bottom' | 'left')[] };
+  rotate?: number;
+  /** Rotate about this point (px or `'%'`) instead of the centre. */
+  origin?: [Length | `${number}%`, Length | `${number}%`] | { x?: Length | `${number}%`; y?: Length | `${number}%` };
+  /** `arch`: the arc and its sides only (stroked). */
+  open?: boolean;
+  /** A blur radius, drawn padded: soft orbs with no edge fade or square edge. */
+  soft?: Length;
+  /** `cut`: grow (or shrink) the format's die-cut outline. */
+  outset?: Length;
+  /** Where the dash pattern starts. */
+  dashOffset?: Length;
+  fill?: Paint; stroke?: Paint; strokeWidth?: Length;
+  strokes?: { color: Color; width: Length; dash?: Length[] }[];
+  dash?: 'dashed' | 'dotted' | Length[];
+  linecap?: 'butt' | 'round' | 'square'; linejoin?: 'miter' | 'round' | 'bevel'; fillRule?: 'nonzero' | 'evenodd';
+  opacity?: number;
+}
+
+export interface ShapeLayer extends BaseLayer, Omit<ShapeSpec, 'opacity'> {
+  type: 'shape';
+  /** Several shapes in one layer (layer-level fill, stroke, … are their defaults). */
+  items?: ShapeSpec[];
+}
+
+
+/** Draw one shape, or `items` of them. */
+export function shape(layer: ShapeLayer, ctx: RenderContext): Promise<Markup>;
+/** A dash pattern as an SVG `stroke-dasharray`. */
+export function dashArray(dash: 'dashed' | 'dotted' | Length[], width: number, ctx: RenderContext): string;