@arraypress/covers 1.1.0 → 1.4.0

package/src/index.d.ts

@@ -4,9 +4,9 @@
  * WebP / PNG / AVIF / JPEG.
  */
 
-/** A CSS colour: hex (3/4/6/8 digits), `rgb()`/`rgba()` or `hsl()`/`hsla()`. Alpha is ignored. */
-import type { LayerTransform, Effect, EffectKind, EffectMask } from './effects/index.js';
-import type { Paint } from './effects/paint.js';
+import type { Effect as AnyEffect, EffectKind, EffectMask as AnyEffectMask, Color, Length, Rng } from '@logomarks/image-effects';
+import type { LayerTransform } from './render/transform.js';
+import type { Paint } from './paint/index.js';
 import type { TextPath } from './type/path.js';
 import type { GroupLayer } from './render/group.js';
 import type { DefsLayer, UseLayer } from './render/use.js';
@@ -14,31 +14,34 @@ import type { RepeatLayer } from './layers/repeat.js';
 import type { TextSpan } from './type/spans.js';
 import type { GlyphControl } from './type/glyphs.js';
 import type { Cut } from './formats/cut.js';
-import type { ShapeLayer, SvgLayer, TableLayer, BarcodeLayer, PerforationLayer, TearLayer, TextureLayer } from './layers/index.js';
+import type { ShapeLayer, SvgLayer, TableLayer, BarcodeLayer, PerforationLayer, TearLayer, TextureLayer, MosaicLayer, MarksLayer } from './layers/index.js';
 import type { Zones, PrintInfo, FormatName } from './formats/index.js';
+import type { Motion, MotionPreset, Easing } from './animate/index.js';
 
-export type { RepeatLayer, DefsLayer, UseLayer, TextSpan, GlyphControl, Cut };
-export type { LayerTransform, Effect, EffectKind, EffectMask, Paint, TextPath, GroupLayer, ShapeLayer, SvgLayer, TableLayer, BarcodeLayer, PerforationLayer, TearLayer, TextureLayer, Zones, PrintInfo, FormatName };
+export type { RepeatLayer, DefsLayer, UseLayer, TextSpan, GlyphControl, Cut, Motion, MotionPreset, Easing };
+export type { Color, Length, Rng, LayerTransform, EffectKind, Paint, TextPath, GroupLayer, ShapeLayer, SvgLayer, TableLayer, BarcodeLayer, PerforationLayer, TearLayer, TextureLayer, MosaicLayer, MarksLayer, Zones, PrintInfo, FormatName };
 export type { ShapeSpec, TableCell } from './layers/index.js';
 export type { Format } from './formats/index.js';
 export type { LintIssue } from './lint/index.js';
 export type { Settings } from './platform/index.js';
 
 export { safeBox } from './formats/index.js';
-export { rasterize } from './raster/index.js';
-import type { RasterizeOptions } from './raster/index.js';
+export { rasterize } from '@logomarks/image-effects/raster';
+import type { RasterizeOptions } from '@logomarks/image-effects/raster';
 export type { RasterizeOptions };
 export { lint } from './lint/index.js';
 export { kit, KIT_FORMATS } from './kit/index.js';
 export { FORMATS } from './formats/index.js';
 export { configure } from './platform/index.js';
-export { EFFECTS, EFFECT_OPTIONS } from './effects/index.js';
-export { valueAt } from './animate/index.js';
+export { EFFECTS, EFFECT_OPTIONS } from '@logomarks/image-effects';
+export { valueAt, MOTION_PRESETS } from './animate/index.js';
+export { toHex, toOklch, fromOklch, mixOklab, mixOklch, onBackground, gradientAt } from '@logomarks/image-effects/color';
+export { createRng, hashString } from '@logomarks/image-effects/rng';
 
-export type Color = string;
-
-/** Pixels, or a viewport unit of the canvas: `'6vmin'`, `'4vw'`, `'4vh'`, `'5vmax'`. */
-export type Length = number | `${number}vmin` | `${number}vmax` | `${number}vw` | `${number}vh` | `${number}px`;
+/** An effect on a layer (image-effects' effects, with masks and maps given as layers). */
+export type Effect = AnyEffect<Layer>;
+/** Where an effect applies: a gradient, or layers. */
+export type EffectMask = AnyEffectMask<Layer>;
 
 /** Where a box sits inside the safe area. */
 export type Anchor =
@@ -136,6 +139,8 @@ export interface BaseLayer {
   clip?: Layer[];
   /** Draw the layer in a box: the print `'trim'` or `'safe'` area, or fractions of the canvas. */
   area?: 'bleed' | 'trim' | 'safe' | Region;
+  /** Move in the SVG itself (CSS keyframes, no script): a motion, a preset name, or a list. */
+  motion?: Motion | MotionPreset | (Motion | MotionPreset)[];
 }
 
 export interface SolidLayer extends BaseLayer {
@@ -305,8 +310,8 @@ export interface PatternLayer extends BaseLayer {
   fade?: 'none' | 'radial' | 'edges' | 'top' | 'bottom' | 'left' | 'right';
   /** Dashed or dotted lines (or `[on, off]` lengths). */
   dash?: 'dashed' | 'dotted' | true | [Length, Length];
-  /** Grid / lines: N equal cells (inner lines only) instead of `size`. */
-  divisions?: number;
+  /** Grid / lines: N equal cells (inner lines only) instead of `size`; `[cols, rows]` for a design grid. */
+  divisions?: number | [number, number];
   /** Regions (fractions) the lines break around. */
   gaps?: Region[];
   region?: Region;
@@ -410,8 +415,8 @@ export interface TextLabel {
 
 export interface TextLayer extends Omit<BaseLayer, 'transform'> {
   type: 'text';
-  /** The text; an array is one line per item. (Optional with `spans`.) */
-  content?: string | string[];
+  /** The text; an array is one line per item, and an item may be a span (`{ content, bold }`: a headline whose lines change weight). (Optional with `spans`.) */
+  content?: string | (string | TextSpan)[];
   /** First baseline x (px or `'%'`): places the text like SVG `<text x y>`, `align` acting as the anchor. */
   x?: Length | `${number}%`;
   y?: Length | `${number}%`;
@@ -465,6 +470,8 @@ export interface TextLayer extends Omit<BaseLayer, 'transform'> {
   font?: string;
   /** Default 600. */
   weight?: number;
+  /** The weight of spans and lines marked `bold: true`. Default 700. */
+  boldWeight?: number;
   style?: 'normal' | 'italic';
   /** Default 6% of the design unit (`sqrt(width × height)`). */
   size?: Length;
@@ -713,7 +720,7 @@ export interface RuleLayer extends BaseLayer {
 }
 
 export type Layer =
-  | GroupLayer | ShapeLayer | SvgLayer | TableLayer | BarcodeLayer | PerforationLayer | TearLayer | TextureLayer
+  | GroupLayer | ShapeLayer | SvgLayer | TableLayer | BarcodeLayer | PerforationLayer | TearLayer | TextureLayer | MosaicLayer | MarksLayer
   | InkLayer | DitherLayer | ContourLayer | WaveformLayer | TilesLayer | RuleLayer
   | DiagramLayer | PaperLayer | ScribbleLayer
   | SolidLayer | LinearLayer | RadialLayer | MeshLayer | StripesLayer | ImageLayer
@@ -934,6 +941,10 @@ export interface CoverOptions extends RecipeOptions {
   textRender?: 'outline' | 'live';
   /** Seconds: the length of an animated cover's loop (keyframes with `loop` wrap at it). */
   loop?: number;
+  /** `false`: `renderSvg` draws a still, no CSS (layers' `motion` at the `poster` time, else at rest). */
+  animate?: boolean;
+  /** Seconds: the frame stills show (`renderImage`, `renderBlob`, `animate: false`, and an animated SVG under reduced motion). Default: the layers at rest. */
+  poster?: number;
 }
 
 /** A resolved cover (from {@link cover}). */
@@ -958,13 +969,16 @@ export interface Cover {
   pages?: string[];
   overlay?: boolean;
   loop?: number;
+  /** `false` when the cover is drawn as a still. */
+  animate?: false;
+  poster?: number;
   textRender?: 'outline' | 'live';
 }
 
 export interface RenderImageOptions {
   /** Default `'webp'`. */
   format?: 'webp' | 'png' | 'avif' | 'jpeg';
-  /** Default 90 for WebP, 72 for AVIF, 88 for JPEG (high enough to keep the grain; see README). */
+  /** Default 90 for WebP, 72 for AVIF, 88 for JPEG (high enough to keep the grain; see docs/performance.md). */
   quality?: number;
   /** Lossless WebP / AVIF (default: the recipe's preference, else lossy). */
   lossless?: boolean;
@@ -974,16 +988,6 @@ export interface RenderImageOptions {
   cache?: boolean | string;
 }
 
-/** Seeded random stream. */
-export interface Rng {
-  next(): number;
-  range(min: number, max: number): number;
-  int(min: number, max: number): number;
-  pick<T>(items: readonly T[]): T;
-  shuffle<T>(items: readonly T[]): T[];
-  chance(p?: number): boolean;
-}
-
 /** An Iconify JSON set (`@iconify-json/<prefix>/icons.json`). */
 export interface IconSet {
   prefix: string;
@@ -998,13 +1002,23 @@ export interface IconSet {
 /** Resolve a cover's size and palette and expand its recipe. Pure and synchronous. */
 export function cover(options: CoverOptions | Cover): Cover;
 
-/** Render to an SVG string (text and icons as outlines; byte-identical for the same input). `t`: the time to draw, in seconds, for keyframed layers. */
-export function renderSvg(input: CoverOptions | Cover, options?: { t?: number }): Promise<string>;
+/** How `renderSvg` draws. */
+export interface RenderSvgOptions {
+  /** A still at this time, in seconds, for keyframed layers and `motion` (instead of playing it). */
+  t?: number;
+  /** `'webp'`: embedded photos and pixel effects re-encoded as WebP where smaller (needs sharp). For SVGs shown in browsers; librsvg (sharp) can't draw WebP. */
+  images?: 'webp';
+  /** WebP quality for photos (JPEG sources), 1–100. Default 82. PNG sources go lossless. */
+  quality?: number;
+}
+
+/** Render to an SVG string (text and icons as outlines; byte-identical for the same input). */
+export function renderSvg(input: CoverOptions | Cover, options?: RenderSvgOptions): Promise<string>;
 
 /** Render each page of a two-sided piece: `{ front, back }`. */
 export function renderPages(input: CoverOptions, options?: { pages?: string[] }): Promise<Record<string, string>>;
 
-/** Render to an image in the browser (a canvas; no sharp). */
+/** Render to an image in the browser (a canvas; no sharp): a still, the `poster` frame or the layers at rest. */
 export function renderBlob(input: CoverOptions | Cover, options?: RasterizeOptions): Promise<Blob>;
 
 /** Register a font for every cover. */
@@ -1043,21 +1057,6 @@ export function resolvePalette(input?: PaletteInput | Palette): Palette;
 /** Derive a palette from a theme's tokens (or just an accent). */
 export function derivePalette(tokens: { accent: Color; bg?: Color; text?: Color; colors?: Color[]; mode?: 'light' | 'dark' }): Palette;
 
-/** Parse a CSS colour to `#rrggbb`. */
-export function toHex(color: Color): string;
-/** A colour in OKLCH (lightness 0–1, chroma, hue in degrees). */
-export function toOklch(color: Color): { l: number; c: number; h: number };
-/** OKLCH to `#rrggbb` (chroma reduced to fit sRGB). */
-export function fromOklch(lch: { l: number; c: number; h: number }): string;
-/** Mix two colours in OKLab. */
-export function mixOklab(a: Color, b: Color, t: number): string;
-/** `prefer` if it clears `ratio` on every background, else the better of white and near-black (3:1 suits icons, WCAG 1.4.11). */
-export function onBackground(backgrounds: Color | Color[], ratio?: number, prefer?: 'white' | 'black' | Color): string;
-/** The colour of an eased multi-stop gradient at t (0–1), as the gradient layers draw it. */
-export function gradientAt(colors: Color[], t: number, ease?: boolean): string;
-/** Mix two colours in OKLCH (hue the short way; stays vivid). */
-export function mixOklch(a: Color, b: Color, t: number): string;
-
 /** Register an Iconify icon set (no `@iconify-json/*` install needed). */
 export function registerIcons(set: IconSet): void;
 
@@ -1067,17 +1066,11 @@ export function resolveSize(options?: { width?: number; height?: number; aspect?
 /** Named aspect ratios (width / height). */
 export const ASPECTS: Readonly<{ '1:1': number; '16:9': number; '4:5': number; '3:2': number; '4:3': number; '2:1': number; '9:16': number; og: number }>;
 
-/** A seeded random stream (for custom recipes). */
-export function createRng(seed: string | number): Rng;
-
 /** Dominant colours of a photo, most common first (needs sharp). */
 export function extractPalette(src: string | Uint8Array, options?: { count?: number }): Promise<string[]>;
 
 /** Classic risograph inks, by name (approximations). */
 export const RISO_INKS: Readonly<Record<'pink' | 'blue' | 'yellow' | 'teal' | 'red' | 'green' | 'orange' | 'purple' | 'navy' | 'black', string>>;
 
-/** Hash a string to a 32-bit unsigned integer. */
-export function hashString(str: string, salt?: number): number;
-
 /** The layer renderers, by type (for introspection). */
 export const layers: Readonly<Record<Layer['type'], (layer: any, context: any) => unknown>>;

package/src/index.js

@@ -10,18 +10,18 @@ export { cover, renderSvg, renderImage, renderPages, renderBlob, coverKey, safeB
 export { recipes } from './recipes.js';
 export { defineRecipe, loadRecipe } from './json-recipe.js';
 export { palettes, resolvePalette, derivePalette } from './palette.js';
-export { toHex, toOklch, fromOklch, mixOklab, mixOklch, onBackground, gradientAt } from './color.js';
+export { toHex, toOklch, fromOklch, mixOklab, mixOklch, onBackground, gradientAt } from '@logomarks/image-effects/color';
 export { registerIcons } from './icons.js';
 export { registerFont } from './fonts.js';
 export { configure } from './platform/index.js';
 export { resolveSize, ASPECTS } from './geometry.js';
 export { FORMATS } from './formats/index.js';
-export { createRng, hashString } from './rng.js';
+export { createRng, hashString } from '@logomarks/image-effects/rng';
 export { LAYERS as layers } from './layers.js';
 export { extractPalette } from './extract.js';
 export { RISO_INKS } from './print.js';
-export { EFFECTS, EFFECT_OPTIONS } from './effects/index.js';
-export { rasterize } from './raster/index.js';
+export { EFFECTS, EFFECT_OPTIONS } from '@logomarks/image-effects';
+export { rasterize } from '@logomarks/image-effects/raster';
 export { lint } from './lint/index.js';
 export { kit, KIT_FORMATS } from './kit/index.js';
-export { valueAt } from './animate/index.js';
+export { valueAt, MOTION_PRESETS } from './animate/index.js';

package/src/inter-data.js

@@ -1,7 +1,7 @@
 // Generated by scripts/generate.mjs from fonts/*.woff. Do not edit.
 // Inter is © The Inter Project Authors, SIL Open Font License 1.1 (fonts/OFL.txt).
 
-import { fromBase64 } from './platform/bytes.js';
+import { fromBase64 } from './platform/index.js';
 
 /** @type {Record<number, string>} */
 const DATA = {

package/src/json-recipe.js

@@ -31,6 +31,7 @@
  * | `{ "gradientUnder": [colors, angle, size] }` | the colours a centred square of `size` covers in a linear gradient |
  * | `{ "pick": [...] }`, `{ "range": [min, max] }`, `{ "int": [min, max] }` | seeded choices |
  * | `{ "add" \| "sub" \| "mul" \| "div" \| "min" \| "max": [a, b, …] }` | arithmetic; lengths like `"54vw"` become pixels |
+ * | `{ "round" \| "floor" \| "ceil": x }` | to a whole number (a grid's row count from the canvas) |
  * | `{ "ramp": [from, to, steps, amount?] }` | `steps` colours from `from` toward `to` |
  * | `{ "taper": [ratio, steps] }` | `[1, ratio, ratio², …]` |
  * | `{ "length": value }` | characters in a string (or a number's digits), items in an array |
@@ -55,15 +56,16 @@
 
 import { readTextSync, node } from './platform/index.js';
 import { readableText } from '@arraypress/color-utils';
-import { createRng } from './rng.js';
-import { len, ANCHORS } 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 { EFFECT_OPTIONS, EFFECT_COMMON } from './effects/options.js';
-import { MASK_GRADIENTS } from './effects/mask.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', 'name', 'mark', 'photo', 'cutout', 'date', 'dates', 'time', 'venue', 'address', 'lines', 'lineup', 'tracklist', 'price', 'meta', 'page'];
@@ -76,6 +78,7 @@ const CANVAS = ['width', 'height', 'u', 'bleed', 'safe', 'mm', 'dpi', 'trimWidth
 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],
+  round: [1, 1], floor: [1, 1], ceil: [1, 1],
   ramp: [3, 4], taper: [2, 2], reverse: [1, 1],
   join: [1, 2], upper: [1, 1], lower: [1, 1], slice: [2, 3],
 });
@@ -181,7 +184,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.
  */
 
 /**
@@ -389,6 +392,9 @@ function op(s, name, raw) {
     case 'div': { const [a, b] = nums(); return a / b; }
     case 'min': return Math.min(...nums());
     case 'max': return Math.max(...nums());
+    case 'round': return Math.round(nums()[0]);
+    case 'floor': return Math.floor(nums()[0]);
+    case 'ceil': return Math.ceil(nums()[0]);
     case 'ramp': {
       const [from, to, steps, amount = 1] = args;
       return Array.from({ length: steps }, (_, i) => mixOklab(toHex(from), toHex(to), (i / steps) * amount));
@@ -546,6 +552,8 @@ export function validate(json) {
       if (!Object.hasOwn(known, k)) fail(`${path}.${k}`, `"${layer.type}" layers have no option "${k}" (${Object.keys(known).join(', ')})`);
       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') {
@@ -583,6 +591,19 @@ export function validate(json) {
       }
     });
   };
+  // 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(', ')})`);

package/src/layer-options.js

@@ -16,12 +16,12 @@ export const LAYER_OPTIONS = {
   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: { 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.' },
+  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; [cols, rows] for a design grid.', 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: { 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 }.',
+  text: { content: 'The text ("{title}"); an array is a line per item, an item may be a span ({ content, bold }).', font: 'Family. Default Inter.', weight: 'Default 600.', boldWeight: 'The weight of spans and lines marked bold: true. Default 700.', 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.' },
+    spans: '[{ content, font, weight, bold, 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.' },
@@ -43,14 +43,36 @@ export const LAYER_OPTIONS = {
   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 "%").' },
+  mosaic: { markup: 'The mark\'s paths (512 grid).', x: 'Box x, px or %.', y: 'Box y.', width: 'Box width (default the canvas).', height: 'Box height.', cells: 'Cells across the mark\'s longest side, 4–48. Default 10.', gap: 'Gap between cells, a share of a cell. Default 0.12.', radius: 'Cell corner radius, a share of a cell. Default 0.', drop: 'Share of filled cells left out (seeded), 0–0.9. Default 0.12.', color: 'Default @accent.', accent: 'asterisk | dot: a small glyph in one empty cell beside the mark.', accentColor: 'Default color.' },
+  marks: { marks: 'The marks: paths on a 512 grid (or { markup }).', cols: 'Default from the count: 3 × 3 up to 10 × 7.', rows: 'Default from the count.', x: 'Box x, px or %.', y: 'Box y.', width: 'Box width (default the canvas).', height: 'Box height.', size: 'Share of a cell a mark\'s area takes. Default 0.5.', optical: 'false: fit each mark\'s bounds to the same box instead. Default true.', color: 'Default @text.' },
 };
 
 /** @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.",
   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 the README\'s Effects table; kinds in EFFECTS).',
+  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.js

@@ -4,9 +4,9 @@
  * @module layers/barcode
  */
 
-import { attrs, num } from '../svg.js';
-import { len } from '../geometry.js';
-import { toHex } from '../color.js';
+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';

package/src/layers/geometry.js

@@ -6,11 +6,11 @@
  * @module layers/geometry
  */
 
-import { attrs, num } from '../svg.js';
-import { len } from '../geometry.js';
+import { attrs, num } from '@logomarks/image-effects/svg';
+import { len } from '@logomarks/image-effects/length';
 import { pos } from './util.js';
 import { cutPath } from '../formats/cut.js';
-import { invert, apply } from '../effects/transform.js';
+import { invert, apply } from '../render/transform.js';
 
 
 /**
@@ -18,7 +18,7 @@ import { invert, apply } from '../effects/transform.js';
  *
  * @param {[number, number]} a @param {[number, number]} b
  * @param {{ kind: string, size: number, step: number }} e
- * @param {import('../rng.js').Rng} rng
+ * @param {import('@logomarks/image-effects/rng').Rng} rng
  * @returns {[number, number][]} Points from a (exclusive) to b (inclusive).
  */
 function edgePoints(a, b, e, rng) {
@@ -211,7 +211,7 @@ export function geometry(s, ctx) {
  *
  * @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 {import('../render/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 } }}
  */

package/src/layers/index.d.ts

@@ -14,5 +14,11 @@ export { tear } from './tear.js';
 export type { TearLayer } from './tear.js';
 export { texture } from './texture.js';
 export type { TextureLayer } from './texture.js';
+export { mosaic, mosaicGrid } from './mosaic.js';
+export type { MosaicLayer } from './mosaic.js';
+export { marks, sheetGrid } from './marks.js';
+export type { MarksLayer } from './marks.js';
+export { markGeometry } from './mark-geometry.js';
+export type { MarkGeometry } from './mark-geometry.js';
 export { expandRepeat } from './repeat.js';
 export type { RepeatLayer } from './repeat.js';

package/src/layers/index.js

@@ -12,4 +12,7 @@ export { code128 } from './code128.js';
 export { perforation } from './perforation.js';
 export { tear } from './tear.js';
 export { texture } from './texture.js';
+export { mosaic, mosaicGrid } from './mosaic.js';
+export { marks, sheetGrid } from './marks.js';
+export { markGeometry } from './mark-geometry.js';
 export { expandRepeat } from './repeat.js';

package/src/layers/mark-geometry.d.ts

@@ -0,0 +1,15 @@
+// A mark's geometry from its markup, read with @logomarks/core.
+import type { FillPath } from '@logomarks/core/raster';
+
+/** A mark read from its paths. */
+export interface MarkGeometry {
+  /** Its filled paths as rings, with their fill rules. */
+  paths: FillPath[];
+  /** Its real bounds, grid units. */
+  box: { x: number; y: number; width: number; height: number };
+  /** The share of its box it inks, 0–1. */
+  density: number;
+}
+
+/** Read a mark (paths on a 512 grid); null when it draws nothing. */
+export function markGeometry(markup: string): MarkGeometry | null;

package/src/layers/mark-geometry.js

@@ -0,0 +1,46 @@
+/**
+ * A mark's geometry from its markup (paths on a 512 grid), read with
+ * `@logomarks/core`: its filled paths as rings, its real bounds, and how
+ * much of that box it inks. Shared by the `mosaic` and `marks` layers.
+ *
+ * @module layers/mark-geometry
+ */
+
+import { shapes, rings, bounds } from '@logomarks/core/svg';
+import { pixelGrid, pixelCoverage } from '@logomarks/core/edit';
+
+/** Read marks, by markup (a sheet of seventy reads each once). @type {Map<string, MarkGeometry>} */
+const cache = new Map();
+
+/**
+ * @typedef {object} MarkGeometry
+ * @property {import('@logomarks/core/raster').FillPath[]} paths - Its filled paths as rings, with their fill rules.
+ * @property {{ x: number, y: number, width: number, height: number }} box - Its real bounds, grid units.
+ * @property {number} density - The share of its box it inks, 0–1.
+ */
+
+/**
+ * Read a mark.
+ *
+ * @param {string} markup - The mark's paths (`<path d="…"/>`, on a 512 grid).
+ * @returns {MarkGeometry | null} Null when it draws nothing.
+ *
+ * @example
+ * markGeometry('<path d="M96 96h320v320H96z"/>').box; // { x: 96, y: 96, width: 320, height: 320 }
+ */
+export function markGeometry(markup) {
+  if (cache.has(markup)) return /** @type {MarkGeometry} */ (cache.get(markup));
+  const filled = shapes(String(markup ?? ''));
+  const paths = filled.map((s) => ({ rings: rings(s.segs), evenodd: s.evenodd })).filter((p) => p.rings.length);
+  if (!paths.length) return null;
+  const b = bounds(filled);
+  const box = { x: b.x, y: b.y, width: Math.max(b.w, 1e-6), height: Math.max(b.h, 1e-6) };
+  // Ink measured on a 48-cell grid over the box: plenty for a density.
+  const grid = pixelGrid(0, box);
+  const cov = pixelCoverage(paths, grid);
+  const density = cov.reduce((a, v) => a + v, 0) / Math.max(1, cov.length);
+  const geo = { paths, box, density };
+  if (cache.size > 500) cache.clear();
+  cache.set(markup, geo);
+  return geo;
+}

package/src/layers/marks.d.ts

@@ -0,0 +1,25 @@
+// The `marks` layer.
+import type { Color, Length, BaseLayer } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+
+export interface MarksLayer extends BaseLayer {
+  type: 'marks';
+  /** The marks: their paths on a 512 grid (or `{ markup }`). */
+  marks: (string | { markup: string })[];
+  /** Default from the count and the box: 3 × 3 up to 10 × 7. */
+  cols?: number;
+  rows?: number;
+  /** The box the grid is centred in (default the canvas). */
+  x?: Length | `${number}%`; y?: Length | `${number}%`; width?: Length | `${number}%`; height?: Length | `${number}%`;
+  /** The share of a cell a mark's area takes. Default 0.5. */
+  size?: number;
+  /** `false`: each mark's bounds fitted to the same box, not optically sized. Default true. */
+  optical?: boolean;
+  /** Default the palette's text. */
+  color?: Color;
+}
+
+/** Draw a set of marks on an even grid, optically sized the same. */
+export function marks(layer: MarksLayer, ctx: RenderContext): Markup;
+/** Columns and rows for `n` marks in a box of `aspect` (3 × 3 to 10 × 7; given ones kept). */
+export function sheetGrid(n: number, aspect: number, cols?: number, rows?: number): { cols: number; rows: number };