@arraypress/covers 1.0.0 → 1.3.1

package/src/animate/index.d.ts

@@ -0,0 +1,9 @@
+// Animation: motion that plays in the SVG, and keyframes drawn a frame at a time.
+export { renderMotion } from './motion.js';
+export type { Motion, MotionPreset, MotionScope } from './motion.js';
+export { motionList, progress, easing, MOTION_PRESETS } from './timing.js';
+export type { Easing, ResolvedMotion } from './timing.js';
+export { createSheet, nameSheet } from './sheet.js';
+export type { Sheet } from './sheet.js';
+export { animate, isAnimated, valueAt, interpolate } from './keyframes.js';
+export type { Keyframes, Ease } from './keyframes.js';

package/src/animate/index.js

@@ -0,0 +1,11 @@
+/**
+ * Animation: `motion` plays in the SVG itself (CSS keyframes, no script);
+ * keyframes draw one frame at a time (`renderSvg(cover, { t })`).
+ *
+ * @module animate
+ */
+
+export { renderMotion } from './motion.js';
+export { motionList, progress, easing, MOTION_PRESETS } from './timing.js';
+export { createSheet, nameSheet } from './sheet.js';
+export { animate, isAnimated, valueAt, interpolate } from './keyframes.js';

package/src/animate/keyframes.d.ts

@@ -0,0 +1,21 @@
+// Keyframes against time, for frames drawn one at a time.
+
+/** A keyframed value. */
+export interface Keyframes<T = unknown> {
+  /** `[t, value]` pairs (seconds), or `{ t, value, ease }`. */
+  keyframes: ([number, T] | [number, T, Ease] | { t: number; value: T; ease?: Ease })[];
+  ease?: Ease;
+  /** Repeat over the cover's `loop` (or the last key); `'pingpong'` goes back and forth. */
+  loop?: boolean | 'pingpong';
+}
+/** Easing curves. */
+export type Ease = 'linear' | 'in' | 'out' | 'inOut' | 'step';
+
+/** Whether a value has keyframes anywhere in it. */
+export function isAnimated(v: unknown): boolean;
+/** A keyframed value at time `t` (seconds). */
+export function valueAt<T>(k: Keyframes<T>, t: number, duration?: number): T;
+/** A value with every keyframed part resolved at `t`. */
+export function animate<T>(v: T, t: number, duration?: number): T;
+/** Two values `f` (0–1) of the way between them: numbers, colours (OKLab), same-unit lengths, arrays and objects of them. */
+export function interpolate<T>(a: T, b: T, f: number): T;

package/src/animate/keyframes.js

@@ -0,0 +1,119 @@
+/**
+ * Keyframes, for frames drawn one at a time: any layer option can be
+ * keyframed against `t` (seconds), and `renderSvg(cover, { t })` draws the
+ * frame at that time. Static covers have no keyframes and ignore `t`, so
+ * nothing changes for them. (Motion that plays in the SVG itself is
+ * `motion`; see ./motion.js.)
+ *
+ * ```json
+ * { "type": "text", "content": "{name}",
+ *   "opacity": { "keyframes": [[0, 0], [0.6, 1]], "ease": "out" },
+ *   "transform": { "rotate": { "keyframes": [[0, -4], [2, 4]], "loop": "pingpong" } } }
+ * ```
+ *
+ * Numbers interpolate; colours mix in OKLab; lengths with the same unit
+ * (`"4vmin"` → `"9vmin"`) interpolate; anything else holds until the next
+ * key. `loop: true` repeats over the cover's `loop` (seconds; or the last key),
+ * `'pingpong'` goes back and forth.
+ *
+ * @module animate/keyframes
+ */
+
+import { mixOklab, toHex } from '@logomarks/image-effects/color';
+
+/** @param {unknown} v @returns {v is { keyframes: any[] }} */
+const isKeyed = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v) && Array.isArray(/** @type {any} */ (v).keyframes);
+
+/**
+ * Whether a layer has keyframes anywhere in its options.
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export function isAnimated(v) {
+  if (isKeyed(v)) return true;
+  if (Array.isArray(v)) return v.some(isAnimated);
+  if (v && typeof v === 'object' && !(v instanceof Uint8Array)) return Object.values(v).some(isAnimated);
+  return false;
+}
+
+/** Easing curves on 0–1. */
+const EASE = /** @type {Record<string, (x: number) => number>} */ ({
+  linear: (x) => x,
+  in: (x) => x * x * x,
+  out: (x) => 1 - (1 - x) ** 3,
+  inOut: (x) => (x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2),
+  step: () => 0,
+});
+
+/**
+ * Two values `f` of the way between them: numbers, colours (OKLab),
+ * same-unit lengths, and arrays and objects of them; anything else holds
+ * until `f` reaches 1.
+ *
+ * @param {any} a @param {any} b @param {number} f
+ * @returns {any}
+ */
+export function interpolate(a, b, f) {
+  if (typeof a === 'number' && typeof b === 'number') return a + (b - a) * f;
+  if (typeof a === 'string' && typeof b === 'string') {
+    const la = /^(-?[\d.]+)(vmin|vmax|vw|vh|px|%)$/.exec(a);
+    const lb = /^(-?[\d.]+)(vmin|vmax|vw|vh|px|%)$/.exec(b);
+    if (la && lb && la[2] === lb[2]) return `${+la[1] + (+lb[1] - +la[1]) * f}${la[2]}`;
+    try {
+      return mixOklab(toHex(a), toHex(b), f);
+    } catch {
+      return f < 1 ? a : b;
+    }
+  }
+  if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) return a.map((x, i) => interpolate(x, b[i], f));
+  if (a && b && typeof a === 'object' && typeof b === 'object') return Object.fromEntries(Object.keys(a).map((k) => [k, k in b ? interpolate(a[k], b[k], f) : a[k]]));
+  return f < 1 ? a : b;
+}
+
+/**
+ * A keyframed value at time `t`.
+ *
+ * @param {{ keyframes: any[], ease?: string, loop?: boolean | 'pingpong' }} k
+ * @param {number} t
+ * @param {number} [duration]
+ * @returns {any}
+ */
+export function valueAt(k, t, duration) {
+  const keys = k.keyframes.map((x) => (Array.isArray(x) ? { t: x[0], value: x[1], ease: x[2] } : x)).sort((a, b) => a.t - b.t);
+  if (!keys.length) return undefined;
+  const end = duration ?? keys[keys.length - 1].t;
+  let time = t;
+  if (k.loop && end > 0) {
+    time = ((t % end) + end) % end;
+    if (k.loop === 'pingpong' && Math.floor(t / end) % 2 === 1) time = end - time;
+  }
+  if (time <= keys[0].t) return keys[0].value;
+  for (let i = 1; i < keys.length; i++) {
+    if (time <= keys[i].t) {
+      const a = keys[i - 1];
+      const b = keys[i];
+      const ease = EASE[b.ease ?? k.ease ?? 'inOut'] ?? EASE.inOut;
+      return interpolate(a.value, b.value, ease((time - a.t) / Math.max(1e-9, b.t - a.t)));
+    }
+  }
+  return keys[keys.length - 1].value;
+}
+
+/**
+ * A layer with every keyframed option resolved at `t`.
+ *
+ * @template T
+ * @param {T} v
+ * @param {number} t - Seconds.
+ * @param {number} [duration] - The cover's `loop` length in seconds (loops wrap at it).
+ * @returns {T}
+ */
+export function animate(v, t, duration) {
+  if (isKeyed(v)) return valueAt(v, t, duration);
+  if (Array.isArray(v)) return /** @type {any} */ (v.map((x) => animate(x, t, duration)));
+  if (v && typeof v === 'object' && !(v instanceof Uint8Array) && isAnimated(v)) {
+    return /** @type {any} */ (Object.fromEntries(Object.entries(v).map(([k, x]) => [k, animate(x, t, duration)])));
+  }
+  return v;
+}

package/src/animate/marquee.d.ts

@@ -0,0 +1,30 @@
+// `marquee`: text on a path running along it.
+import type { ResolvedMotion } from './timing.js';
+import type { Sheet } from './sheet.js';
+
+/** The motion, as the text layer gets it. */
+export interface MarqueeMotion extends ResolvedMotion {
+  /** Playing (CSS), or a still. */
+  live: boolean;
+  /** The still's time, seconds (none: at rest). */
+  t?: number;
+  sheet?: Sheet;
+}
+
+/** Text laid out on its path. */
+export interface MarqueeText {
+  /** The shaped line (`glyphs[i].x` from its start). */
+  run: { glyphs: { gid: number; x: number; face?: unknown; paint?: string }[] };
+  /** Each glyph's middle, from the line's start. */
+  mids: number[];
+  /** Where the line starts along the path, px. */
+  start: number;
+  sampler: { length: number; at(s: number): { x: number; y: number; tx: number; ty: number } };
+  /** The layer's id in the document (names the glyphs' defs). */
+  id: string;
+  /** Glyph `i` drawn in its own frame: its middle on the baseline at 0, 0. */
+  glyph(i: number): string;
+}
+
+/** The marquee's part: `shift` (px) to move a still's start by, or (playing) the glyphs' defs and copies. */
+export function marquee(m: MarqueeMotion, o: MarqueeText): { shift: number; defs: string; body?: string };

package/src/animate/marquee.js

@@ -0,0 +1,93 @@
+/**
+ * `marquee`: text on a path running along it, one repeat of its words per
+ * `duration`, looping seamlessly for as long as it shows (back toward the
+ * path's start; `direction: 'reverse'` runs it forward).
+ *
+ * The text is outlines, so the moving offset can't be a `textPath`
+ * attribute. Each glyph is drawn once (in its own frame, centred on the
+ * baseline) and placed by copies (`<use>`). Every copy runs the same
+ * keyframes, the path sampled as `translate() rotate()` stops, over a track
+ * as long as the text; the copies differ only in their delay. So a copy
+ * that leaves one end comes back in at the other, a whole number of repeats
+ * away, where the same glyph was: the loop never shows a seam. The still
+ * (and reduced motion) is each copy's own `transform`.
+ *
+ * @module animate/marquee
+ */
+
+import { num } from '@logomarks/image-effects/svg';
+import { NS } from './sheet.js';
+
+/** Most px between two keyframes along the track. */
+const STEP = 8;
+
+/**
+ * The marquee's part in drawing text on a path.
+ *
+ * @param {import('./marquee.js').MarqueeMotion} m - The motion (and whether it plays, and the still's time).
+ * @param {import('./marquee.js').MarqueeText} o - The laid-out text.
+ * @returns {{ shift: number, defs: string, body?: string }} `shift`: px to move the start by for a still; `body`: the playing glyphs.
+ * @throws {TypeError} When the text doesn't repeat, or the direction alternates.
+ */
+export function marquee(m, o) {
+  if (m.direction.startsWith('alternate')) throw new TypeError('motion: a marquee runs one way (direction normal or reverse)');
+  const glyphs = o.run.glyphs;
+  const period = periodOf(glyphs);
+  const unit = glyphs[period].x - glyphs[0].x;
+  const dir = m.direction === 'reverse' ? 1 : -1;
+  const phase = m.t == null ? 0 : (((m.t - m.delay) / m.duration) % 1 + 1) % 1;
+  if (!m.live) return { shift: dir * unit * phase, defs: '' };
+
+  const units = Math.ceil(glyphs.length / period);
+  const span = units * unit;
+  // The track: half a repeat before the first glyph, so no copy starts exactly at its end.
+  const from = o.start + o.mids[0] - unit / 2;
+  const steps = Math.max(8, Math.min(400, Math.ceil(span / STEP)));
+  const place = (/** @type {number} */ s) => {
+    const at = o.sampler.at(s);
+    return { x: at.x, y: at.y, a: (Math.atan2(at.ty, at.tx) * 180) / Math.PI };
+  };
+  const frames = Array.from({ length: steps + 1 }, (_, i) => {
+    const p = place(from + (span * i) / steps);
+    return /** @type {[number, string]} */ ([i / steps, `transform:translate(${num(p.x)}px,${num(p.y)}px) rotate(${num(p.a, 2)}deg)`]);
+  });
+  const loop = units * m.duration;
+  const cls = m.sheet.animation(frames, `${num(loop, 3)}s linear 0s infinite ${dir > 0 ? 'normal' : 'reverse'} both`);
+
+  let defs = '';
+  for (let j = 0; j < period; j++) defs += `<g id="${NS}${o.id}q${j}">${o.glyph(j)}</g>`;
+  let body = '';
+  for (let k = 0; k < units; k++) {
+    for (let j = 0; j < period; j++) {
+      const s0 = o.start + o.mids[j] + k * unit;
+      const f0 = (s0 - from) / span;
+      // CSS progress f0 at t = 0, shifted by the motion's own delay; written in (−loop, 0].
+      const lead = dir > 0 ? m.delay - f0 * loop : m.delay + f0 * loop;
+      const delay = lead - loop * Math.ceil(lead / loop);
+      const still = from + ((((s0 - from + dir * unit * phase) % span) + span) % span);
+      const p = place(still);
+      body += `<use href="#${NS}${o.id}q${j}" class="${cls}" transform="translate(${num(p.x)} ${num(p.y)}) rotate(${num(p.a, 2)})" style="animation-delay:${num(delay, 3)}s"/>`;
+    }
+  }
+  return { shift: 0, defs, body };
+}
+
+/**
+ * The text's repeat, in glyphs: the shortest run the rest repeats, glyph
+ * for glyph and at the same spacing.
+ *
+ * @param {any[]} glyphs
+ * @returns {number}
+ * @throws {TypeError} When it doesn't repeat at least twice.
+ */
+function periodOf(glyphs) {
+  const same = (/** @type {any} */ a, /** @type {any} */ b) => a.gid === b.gid && a.face === b.face && a.paint === b.paint;
+  // Twice over, give or take a trailing space.
+  for (let p = 1; p * 2 <= glyphs.length + 1; p++) {
+    const step = glyphs[p].x - glyphs[0].x;
+    let ok = true;
+    for (let i = 0; ok && i + p < glyphs.length; i++) ok = same(glyphs[i], glyphs[i + p]) && Math.abs(glyphs[i + p].x - glyphs[i].x - step) < 0.01;
+    if (ok) return p;
+  }
+  throw new TypeError('motion: a marquee needs its words repeated along the path (at least twice), so it can loop');
+}

package/src/animate/morph.d.ts

@@ -0,0 +1,8 @@
+// `vary`: layer options drawn frame by frame and played as outline morphs.
+import type { ResolvedMotion } from './timing.js';
+import type { MotionScope } from './motion.js';
+
+/** `vary`'s values at progress `p` (0–1), merged into the layer. */
+export function varied<L>(layer: L, vary: Record<string, unknown>, p: number, ease: (x: number) => number): L;
+/** A layer drawn with `vary`: the still, and when live each changing outline keyframed (`d: path()`). */
+export function morph(layer: any, m: ResolvedMotion, o: MotionScope): Promise<{ defs: string; body: string }>;

package/src/animate/morph.js

@@ -0,0 +1,99 @@
+/**
+ * `vary`: layer options that change over the motion, drawn frame by frame
+ * and played as outline morphs.
+ *
+ * ```json
+ * "motion": { "vary": { "axes": { "wdth": [62, 150] } }, "duration": 2.8, "easing": "inOut", "direction": "alternate" }
+ * ```
+ *
+ * Every leaf of `vary` is a list of stops (numbers, colours, same-unit
+ * lengths). The layer is drawn at `frames` points per stop (default 12),
+ * with the easing applied; the frames must differ only in their outlines
+ * (`d`), which become CSS `d: path(…)` keyframes. Outlines interpolate
+ * point by point, which is how a variable font interpolates between its
+ * masters, so a width axis breathes as the font itself would draw it
+ * (exact at every frame, linear between frames a few percent apart).
+ *
+ * @module animate/morph
+ */
+
+import { atStops } from './tracks.js';
+import { easing, progress, cssTiming } from './timing.js';
+
+/** A path's `d` attribute, captured. */
+const D = / d="([^"]*)"/g;
+
+/**
+ * `vary`'s values at progress `p`, merged into the layer.
+ *
+ * @param {any} layer
+ * @param {any} vary
+ * @param {number} p
+ * @param {(x: number) => number} ease
+ * @returns {any}
+ */
+export function varied(layer, vary, p, ease) {
+  const merge = (/** @type {any} */ base, /** @type {any} */ v) => {
+    if (Array.isArray(v)) return atStops(v, p, ease);
+    if (!v || typeof v !== 'object') throw new TypeError('motion: every value in vary is a list of stops ([from, to, …])');
+    const out = { ...(base && typeof base === 'object' ? base : {}) };
+    for (const [k, x] of Object.entries(v)) out[k] = merge(out[k], x);
+    return out;
+  };
+  return merge(layer, vary);
+}
+
+/**
+ * A layer drawn with `vary`: a still at `t`, or (live) the still with each
+ * outline that changes keyframed.
+ *
+ * @param {any} layer - Without its motion.
+ * @param {import('./timing.js').ResolvedMotion} m
+ * @param {import('./motion.js').MotionScope} o
+ * @returns {Promise<{ defs: string, body: string }>}
+ * @throws {TypeError} When the frames differ in more than their outlines.
+ */
+export async function morph(layer, m, o) {
+  const ease = easing(m.easing);
+  const still = o.t == null ? layer : varied(layer, m.vary, progress(m, o.t), ease);
+  if (!o.live) return o.draw(still);
+  const stops = Math.max(...leaves(m.vary).map((l) => l.length));
+  const count = Math.max(1, Math.round(m.frames ?? 12)) * Math.max(1, stops - 1);
+  /** @type {{ p: number, ds: string[] }[]} */
+  const frames = [];
+  const name = layer.id ?? layer.type;
+  /** @type {string | undefined} */
+  let shape;
+  const check = (/** @type {{ defs: string, body: string }} */ f) => {
+    shape ??= strip(f);
+    if (strip(f) !== shape) throw new TypeError(`motion: vary on "${name}" changes more than its outlines, so it can't play as a morph`);
+  };
+  for (let i = 0; i <= count; i++) {
+    const p = i / count;
+    const f = await o.draw(varied(layer, m.vary, p, ease));
+    check(f);
+    frames.push({ p, ds: [...f.body.matchAll(D)].map((x) => x[1]) });
+  }
+  // The still last, so what the layer leaves behind (its layout box, its stream) is the still's.
+  const rest = await o.draw(still);
+  check(rest);
+  let slot = -1;
+  const body = rest.body.replace(D, (whole) => {
+    slot += 1;
+    const ds = frames.map((f) => f.ds[slot]);
+    if (ds.every((d) => d === ds[0])) return whole;
+    if (ds.some((d) => commands(d) !== commands(ds[0]))) throw new TypeError(`motion: vary on "${name}" changes an outline's shape (not just its points), so it can't morph`);
+    const cls = o.sheet.animation(frames.map((f) => [f.p, `d:path("${f.ds[slot]}")`]), cssTiming(m, { linear: true }));
+    return ` class="${cls}"${whole}`;
+  });
+  return { ...rest, body };
+}
+
+/** @param {{ defs: string, body: string }} m @returns {string} Markup with every outline blanked. */
+const strip = (m) => `${m.defs}\n${m.body}`.replace(D, ' d=""');
+
+/** @param {string} d @returns {string} A path's commands, without their numbers. */
+const commands = (d) => d.replace(/[^A-Za-z]/g, '');
+
+/** @param {any} v @returns {any[][]} Every stop list in `vary`. */
+const leaves = (v) => (Array.isArray(v) ? [v] : Object.values(v ?? {}).flatMap(leaves));

package/src/animate/motion.d.ts

@@ -0,0 +1,59 @@
+// `motion`: a layer moving in the SVG itself, as CSS keyframes.
+import type { Length, TextPath } from '../index.js';
+import type { Easing } from './timing.js';
+import type { Sheet } from './sheet.js';
+
+/** A coordinate: px, `'%'` of the layer's grid, or a length. */
+type Coordinate = Length | `${number}%`;
+
+/** A named motion. */
+export type MotionPreset = 'drift' | 'spin' | 'breathe' | 'blink' | 'marquee';
+
+/** One motion on a layer. A single value moves from the layer at rest to it; a list is stops, evenly spaced in time. */
+export interface Motion {
+  /** Start from a preset's defaults. */
+  preset?: MotionPreset;
+  /** `[x, y]` to move by (px in the layer's grid, `'%'` of it, or lengths), or points to visit. */
+  translate?: [Coordinate, Coordinate] | [Coordinate, Coordinate][];
+  /** Travel a path from where the layer is (the easing spans the whole path). */
+  path?: string | TextPath;
+  /** Degrees to turn to, or a list of angles. */
+  rotate?: number | number[];
+  /** A factor to grow to, or a list (about `origin`). */
+  scale?: number | number[];
+  scaleX?: number | number[];
+  scaleY?: number | number[];
+  /** 0–1 to fade to (times the layer's own opacity), or a list. */
+  opacity?: number | number[];
+  /** What turns and scales are about: `[x, y]` (px, `'%'` or lengths). Default the centre. */
+  origin?: [Coordinate, Coordinate] | { x?: Coordinate; y?: Coordinate } | 'center';
+  /** Layer options as lists of stops (`{ axes: { wdth: [62, 150] } }`), drawn frame by frame and played as outline morphs. */
+  vary?: Record<string, unknown>;
+  /** `vary`: frames drawn per stop. Default 12. */
+  frames?: number;
+  /** Text on a path runs along it, one repeat of its words per `duration` (the words must repeat). */
+  marquee?: boolean;
+  /** Seconds per iteration. Default 2 (or the preset's). */
+  duration?: number;
+  /** Seconds before it starts; negative starts it part-way. */
+  delay?: number;
+  /** Between each pair of stops. Default `'linear'`. */
+  easing?: Easing;
+  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+  /** Default `'infinite'`. */
+  iterations?: number | 'infinite';
+}
+
+/** How a layer with motion is being drawn. */
+export interface MotionScope {
+  /** Playing: CSS keyframes into `sheet`. */
+  live: boolean;
+  /** The still's time, seconds (none: at rest). */
+  t?: number;
+  sheet?: Sheet;
+  /** The layer drawn with its stream from the start (`extra` joins its context). */
+  draw(layer: any, extra?: Record<string, unknown>): Promise<{ defs: string; body: string }>;
+}
+
+/** A layer with its motion: the still (at `t`, or at rest) and, live, the keyframes that play it. */
+export function renderMotion(layer: any, ctx: { canvas: { width: number; height: number } }, o: MotionScope): Promise<{ defs: string; body: string }>;

package/src/animate/motion.js

@@ -0,0 +1,63 @@
+/**
+ * `motion`: a layer moving in the SVG itself, as CSS keyframes, so a plain
+ * `<img>` or inline SVG plays it with no script.
+ *
+ * ```json
+ * { "type": "mesh", "motion": { "translate": ["5vw", "-4vw"], "scale": 1.08, "origin": ["22%", "66%"],
+ *                               "duration": 26, "easing": "inOut", "direction": "alternate" } }
+ * ```
+ *
+ * A layer takes one motion or a list (or a preset name: `drift`, `spin`,
+ * `breathe`, `blink`, `marquee`). Each moves the whole layer (its effects
+ * and masks with it): `translate` or `path`, `rotate`, `scale`, `opacity`
+ * (see ./tracks.js), or changes it: `vary` (outlines morph; ./morph.js) and
+ * `marquee` (text running along its path; ./marquee.js). Timing is CSS's:
+ * `duration`, `delay` (seconds), `easing`, `direction`, `iterations`.
+ *
+ * Every element keeps its still as plain attributes, which is what shows
+ * under `prefers-reduced-motion` and in renderers without CSS animation:
+ * the layer at rest, or the cover's `poster` frame.
+ *
+ * @module animate/motion
+ */
+
+import { attrs, esc } from '@logomarks/image-effects/svg';
+import { motionList, progress, cssTiming, easing } from './timing.js';
+import { tracks, atStops } from './tracks.js';
+import { morph } from './morph.js';
+
+/**
+ * A layer with its motion: the still at `o.t` (or at rest), and when live,
+ * the keyframes that play it.
+ *
+ * @param {any} layer
+ * @param {any} ctx - The layer's render context (its canvas is the layer's grid).
+ * @param {import('./motion.js').MotionScope} o
+ * @returns {Promise<{ defs: string, body: string }>}
+ * @throws {TypeError} On a motion that can't be drawn (see the modules it uses).
+ */
+export async function renderMotion(layer, ctx, o) {
+  const list = motionList(layer.motion);
+  const blend = layer.blend && layer.blend !== 'normal' ? layer.blend : undefined;
+  // Blend goes on the outermost group (a moving group would otherwise blend only with itself).
+  const base = { ...layer, motion: undefined, blend: undefined };
+  const varies = list.filter((m) => m.vary != null);
+  const runs = list.filter((m) => m.marquee);
+  if (varies.length + runs.length > 1) throw new TypeError(`motion: "${layer.id ?? layer.type}" takes one vary or marquee`);
+  const markup = varies.length
+    ? await morph(base, varies[0], o)
+    : runs.length
+      ? await o.draw(base, { marquee: { ...runs[0], live: o.live, t: o.t, sheet: o.sheet } })
+      : await o.draw(base);
+  let body = markup.body;
+  for (const m of [...list].reverse()) {
+    for (const track of tracks(m, ctx.canvas).reverse()) {
+      const still = o.t == null ? null : track.attr(atStops(track.stops, progress(m, o.t), track.sampled ? (x) => x : easing(m.easing)));
+      const cls = o.live ? o.sheet.animation(track.stops.map((v, i, all) => [all.length > 1 ? i / (all.length - 1) : 0, track.css(v)]), cssTiming(m, { linear: track.sampled })) : undefined;
+      const a = attrs({ class: cls, ...still });
+      if (a) body = `<g${a}>${body}</g>`;
+    }
+  }
+  if (blend) body = `<g style="mix-blend-mode:${esc(blend)}">${body}</g>`;
+  return { ...markup, body };
+}

package/src/animate/sheet.d.ts

@@ -0,0 +1,19 @@
+// The stylesheet an animated SVG carries.
+
+/** The placeholder prefix animation names carry until the document is named. */
+export const NS: string;
+
+/** Keyframes and animation rules, each written once. */
+export interface Sheet {
+  /** Add an animation: `[progress 0–1, CSS declarations]` frames and its timing. Returns the class attribute for the element. */
+  animation(frames: [number, string][], timing: string): string;
+  /** Nothing added yet. */
+  readonly empty: boolean;
+  /** The stylesheet, with the `prefers-reduced-motion` rule that stops it. */
+  css(): string;
+}
+
+/** A stylesheet to collect animations into. */
+export function createSheet(): Sheet;
+/** Give a finished document's animation names their prefix (`cv` and a hash of the document). */
+export function nameSheet(svg: string): string;

package/src/animate/sheet.js

@@ -0,0 +1,61 @@
+/**
+ * The stylesheet an animated SVG carries: its keyframes and animation
+ * rules (each written once, however many elements share it), and a
+ * `prefers-reduced-motion` rule that stops them all, so what shows is the
+ * SVG's own attributes: the still.
+ *
+ * Names are written with a placeholder prefix while the cover is drawn and
+ * given the document's hash at the end ({@link nameSheet}), so two covers
+ * inlined in one page never share a name unless they're the same cover.
+ *
+ * @module animate/sheet
+ */
+
+import { num } from '@logomarks/image-effects/svg';
+import { hashString } from '@logomarks/image-effects/rng';
+
+/** The placeholder for the document's prefix (outside base64's alphabet). */
+export const NS = '__cv__';
+
+/**
+ * A stylesheet to collect animations into.
+ *
+ * @returns {import('./sheet.js').Sheet}
+ */
+export function createSheet() {
+  /** @type {Map<string, string>} keyframes body → name */
+  const keyframes = new Map();
+  /** @type {Map<string, string>} animation → class */
+  const rules = new Map();
+  return {
+    animation(frames, timing) {
+      const body = frames.map(([p, decl]) => `${num(p * 100, 3)}%{${decl}}`).join('');
+      let name = keyframes.get(body);
+      if (!name) keyframes.set(body, (name = `${NS}k${keyframes.size}`));
+      const anim = `${name} ${timing}`;
+      let cls = rules.get(anim);
+      if (!cls) rules.set(anim, (cls = `${NS}a${rules.size}`));
+      return `${NS} ${cls}`;
+    },
+    get empty() {
+      return rules.size === 0;
+    },
+    css() {
+      let css = `.${NS}{transform-box:view-box;transform-origin:0 0}`;
+      for (const [body, name] of keyframes) css += `@keyframes ${name}{${body}}`;
+      for (const [anim, cls] of rules) css += `.${cls}{animation:${anim}}`;
+      return `${css}@media (prefers-reduced-motion:reduce){.${NS}{animation:none!important}}`;
+    },
+  };
+}
+
+/**
+ * Give a finished document's animation names their prefix: `cv` and a hash
+ * of the document.
+ *
+ * @param {string} svg
+ * @returns {string}
+ */
+export function nameSheet(svg) {
+  return svg.includes(NS) ? svg.replaceAll(NS, `cv${hashString(svg).toString(36)}`) : svg;
+}

package/src/animate/timing.d.ts

@@ -0,0 +1,28 @@
+// Motion timing: presets, defaults, easing, and where a motion is at any time (CSS semantics).
+import type { Motion, MotionPreset } from './motion.js';
+
+/** An easing: CSS's named curves (`in`, `out`, `inOut` are ease-in, ease-out, ease-in-out), a hold (`step`), or a cubic Bézier. */
+export type Easing = 'linear' | 'ease' | 'in' | 'out' | 'inOut' | 'step' | [number, number, number, number];
+
+/** A motion with its preset expanded and every timing option filled in. */
+export interface ResolvedMotion extends Omit<Motion, 'iterations'> {
+  duration: number;
+  delay: number;
+  easing: Easing;
+  direction: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+  /** `Infinity` for `'infinite'`. */
+  iterations: number;
+}
+
+/** Named motions: each is a motion's defaults. */
+export const MOTION_PRESETS: Readonly<Record<MotionPreset, Readonly<Motion>>>;
+/** A layer's `motion` as resolved motions (presets expanded, defaults filled in); throws on an unknown preset, direction or easing. */
+export function motionList(v: unknown): ResolvedMotion[];
+/** An easing as a function on 0–1. */
+export function easing(e: Easing): (x: number) => number;
+/** An easing as CSS writes it. */
+export function cssEasing(e: Easing): string;
+/** How far through its stops a motion is at `t` seconds (0–1, direction applied; `animation-fill-mode: both`). */
+export function progress(m: ResolvedMotion, t: number): number;
+/** A motion's CSS `animation` timing (everything but the name); `linear` when its stops were sampled eased. */
+export function cssTiming(m: ResolvedMotion, o?: { linear?: boolean; delay?: number }): string;