@arraypress/covers 1.3.1 → 1.5.1

package/src/layers/isolines.js

@@ -0,0 +1,271 @@
+/**
+ * Isolines of a sampled field (marching squares) and a mark's signed
+ * distance field, for contour lines drawn round a mark.
+ *
+ * @module layers/isolines
+ */
+
+import { fill, distance } from '@logomarks/core/raster';
+
+/**
+ * @typedef {object} DistanceField
+ * @property {Float32Array} values - Signed distance in mark units, row by row: positive outside the mark, negative inside.
+ * @property {number} width - Samples across.
+ * @property {number} height - Samples down.
+ * @property {number} x0 - The mark x of the first column's centre.
+ * @property {number} y0 - The mark y of the first row's centre.
+ * @property {number} step - Mark units between samples.
+ */
+
+/**
+ * A mark's signed distance field over its box plus `reach` round it,
+ * `samples` across its longest side. Its rings are filled and measured by
+ * `@logomarks/core`'s scanline fill and Euclidean distance transform; that
+ * measures to pixel centres, so where a line will be traced (samples near
+ * one of `levels`) the distance is then measured exactly, to the rings'
+ * edges, and the lines come out smooth.
+ *
+ * @param {import('./mark-geometry.js').MarkGeometry} geo
+ * @param {number} reach - Mark units round the box the field must cover.
+ * @param {number[]} [levels] - The distances lines will be traced at (mark units).
+ * @param {number} [samples=500]
+ * @returns {DistanceField}
+ */
+export function distanceField(geo, reach, levels = [], samples = 500) {
+  const { box } = geo;
+  const scale = samples / Math.max(box.width, box.height);
+  const pad = reach + 4 / scale;
+  const frame = {
+    x0: box.x - pad,
+    y0: box.y - pad,
+    scale,
+    width: Math.ceil((box.width + 2 * pad) * scale),
+    height: Math.ceil((box.height + 2 * pad) * scale),
+  };
+  const bm = fill(geo.paths, frame);
+  const out = distance(bm, 0);
+  const inside = distance(bm, 1);
+  const values = new Float32Array(out.length);
+  // Pixel centres: half a pixel either side of the edge between ink and empty.
+  for (let i = 0; i < values.length; i++) values[i] = (bm.data[i] ? 0.5 - inside[i] : out[i] - 0.5) / scale;
+  const x0 = frame.x0 + 0.5 / scale;
+  const y0 = frame.y0 + 0.5 / scale;
+  if (levels.length) exactNear(values, frame.width, { x0, y0, step: 1 / scale }, geo, levels);
+  return { values, width: frame.width, height: frame.height, x0, y0, step: 1 / scale };
+}
+
+/**
+ * Measure the samples within two samples of a level exactly: the distance
+ * to the nearest edge of the mark's rings, its sign kept. Edges are binned
+ * so each sample looks only at those within its rough distance.
+ *
+ * @param {Float32Array} values - Rough signed distances (changed).
+ * @param {number} w - Samples across.
+ * @param {{ x0: number, y0: number, step: number }} at - Where the samples are.
+ * @param {import('./mark-geometry.js').MarkGeometry} geo
+ * @param {number[]} levels
+ */
+function exactNear(values, w, { x0, y0, step }, geo, levels) {
+  /** @type {number[]} x1, y1, x2, y2 per edge */
+  const edges = [];
+  for (const p of geo.paths) {
+    for (const ring of p.rings) {
+      for (let i = 0; i < ring.length; i++) {
+        const a = ring[i], b = ring[(i + 1) % ring.length];
+        if (a[0] !== b[0] || a[1] !== b[1]) edges.push(a[0], a[1], b[0], b[1]);
+      }
+    }
+  }
+  const { box } = geo;
+  const size = Math.max(box.width, box.height);
+  const cell = size / 32;
+  const bx = box.x - size, by = box.y - size;
+  const cols = Math.ceil((box.width + 2 * size) / cell);
+  const rows = Math.ceil((box.height + 2 * size) / cell);
+  /** @type {number[][]} */
+  const bins = Array.from({ length: cols * rows }, () => []);
+  for (let e = 0; e < edges.length; e += 4) {
+    const c0 = Math.floor((Math.min(edges[e], edges[e + 2]) - bx) / cell), c1 = Math.floor((Math.max(edges[e], edges[e + 2]) - bx) / cell);
+    const r0 = Math.floor((Math.min(edges[e + 1], edges[e + 3]) - by) / cell), r1 = Math.floor((Math.max(edges[e + 1], edges[e + 3]) - by) / cell);
+    for (let r = Math.max(0, r0); r <= Math.min(rows - 1, r1); r++) for (let c = Math.max(0, c0); c <= Math.min(cols - 1, c1); c++) bins[r * cols + c].push(e);
+  }
+  const band = 2 * step;
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    if (!levels.some((l) => Math.abs(v - l) <= band)) continue;
+    const x = x0 + (i % w) * step, y = y0 + Math.floor(i / w) * step;
+    // The nearest edge is no further than the rough distance and a sample or two.
+    const R = Math.abs(v) + band;
+    let best = R * R;
+    const c0 = Math.max(0, Math.floor((x - R - bx) / cell)), c1 = Math.min(cols - 1, Math.floor((x + R - bx) / cell));
+    const r0 = Math.max(0, Math.floor((y - R - by) / cell)), r1 = Math.min(rows - 1, Math.floor((y + R - by) / cell));
+    for (let r = r0; r <= r1; r++) {
+      for (let c = c0; c <= c1; c++) {
+        for (const e of bins[r * cols + c]) {
+          const ax = edges[e], ay = edges[e + 1], dx = edges[e + 2] - ax, dy = edges[e + 3] - ay;
+          const t = Math.max(0, Math.min(1, ((x - ax) * dx + (y - ay) * dy) / (dx * dx + dy * dy)));
+          const ex = ax + t * dx - x, ey = ay + t * dy - y;
+          const d2 = ex * ex + ey * ey;
+          if (d2 < best) best = d2;
+        }
+      }
+    }
+    values[i] = Math.sign(v || 1) * Math.sqrt(best);
+  }
+}
+
+/**
+ * The lines where a field crosses `level`, as polylines of sample
+ * coordinates (`[column, row]`), closed ones ending on their first point.
+ * Marching squares, saddles split by the cell's mean; crossings are
+ * chained by the grid edge they sit on, so the joins are exact.
+ *
+ * @param {ArrayLike<number>} f - Values row by row.
+ * @param {number} w - Columns.
+ * @param {number} h - Rows.
+ * @param {number} level
+ * @returns {number[][][]}
+ *
+ * @example
+ * isolines([0, 0, 0, 0, 1, 0, 0, 0, 0], 3, 3, 0.5); // one closed diamond round the middle sample
+ */
+export function isolines(f, w, h, level) {
+  // Edge ids: horizontal (i, j)–(i + 1, j) is j·w + i; vertical (i, j)–(i, j + 1) is w·h + j·w + i.
+  const V = w * h;
+  /** @type {Map<number, number[]>} */
+  const at = new Map();
+  /** @type {number[][]} */
+  const segs = [];
+  const link = (/** @type {number} */ a, /** @type {number} */ b) => {
+    const s = segs.push([a, b]) - 1;
+    for (const e of [a, b]) {
+      const list = at.get(e);
+      if (list) list.push(s); else at.set(e, [s]);
+    }
+  };
+  for (let j = 0; j < h - 1; j++) {
+    for (let i = 0; i < w - 1; i++) {
+      const a = f[j * w + i] - level;
+      const b = f[j * w + i + 1] - level;
+      const c = f[(j + 1) * w + i + 1] - level;
+      const d = f[(j + 1) * w + i] - level;
+      const code = (a > 0 ? 8 : 0) | (b > 0 ? 4 : 0) | (c > 0 ? 2 : 0) | (d > 0 ? 1 : 0);
+      if (code === 0 || code === 15) continue;
+      const top = j * w + i;
+      const bottom = (j + 1) * w + i;
+      const left = V + j * w + i;
+      const right = V + j * w + i + 1;
+      const mid = a + b + c + d > 0;
+      switch (code) {
+        case 1: case 14: link(left, bottom); break;
+        case 2: case 13: link(bottom, right); break;
+        case 3: case 12: link(left, right); break;
+        case 4: case 11: link(top, right); break;
+        case 6: case 9: link(top, bottom); break;
+        case 7: case 8: link(left, top); break;
+        case 5: if (mid) { link(left, top); link(bottom, right); } else { link(left, bottom); link(top, right); } break;
+        case 10: if (mid) { link(left, bottom); link(top, right); } else { link(left, top); link(bottom, right); } break;
+      }
+    }
+  }
+  const point = (/** @type {number} */ e) => {
+    if (e < V) {
+      const i = e % w, j = Math.floor(e / w);
+      const p = f[e] - level, q = f[e + 1] - level;
+      return [i + p / (p - q), j];
+    }
+    const k = e - V, i = k % w, j = Math.floor(k / w);
+    const p = f[k] - level, q = f[k + w] - level;
+    return [i, j + p / (p - q)];
+  };
+  const used = new Uint8Array(segs.length);
+  /** @type {number[][][]} */
+  const out = [];
+  for (let s = 0; s < segs.length; s++) {
+    if (used[s]) continue;
+    used[s] = 1;
+    const edges = [segs[s][0], segs[s][1]];
+    for (const forward of [true, false]) {
+      for (;;) {
+        const tip = forward ? edges[edges.length - 1] : edges[0];
+        const next = (at.get(tip) ?? []).find((n) => !used[n]);
+        if (next === undefined) break;
+        used[next] = 1;
+        const other = segs[next][0] === tip ? segs[next][1] : segs[next][0];
+        if (forward) edges.push(other); else edges.unshift(other);
+      }
+    }
+    if (edges.length > 2) out.push(edges.map(point));
+  }
+  return out;
+}
+
+/**
+ * A polyline simplified within `tol` (Douglas-Peucker; a closed one split
+ * at its farthest point so both halves keep their ends), then smoothed by
+ * two rounds of Chaikin (corners rounded by at most `round`), as path data.
+ *
+ * @param {number[][]} pts - Canvas units; closed when the last is the first.
+ * @param {number} [tol=0.25]
+ * @param {number} [round=0.6]
+ * @returns {string}
+ */
+export function smoothLine(pts, tol = 0.25, round = 0.6) {
+  const first = pts[0];
+  const last = pts[pts.length - 1];
+  const closed = pts.length > 3 && Math.hypot(first[0] - last[0], first[1] - last[1]) < 1e-9;
+  /** @type {number[][]} */
+  let p;
+  if (closed) {
+    let far = 0, fd = -1;
+    pts.forEach((q, i) => { const d = Math.hypot(q[0] - first[0], q[1] - first[1]); if (d > fd) { fd = d; far = i; } });
+    p = [...simplify(pts.slice(0, far + 1), tol).slice(0, -1), ...simplify(pts.slice(far), tol).slice(0, -1)];
+    if (p.length < 3) return '';
+  } else {
+    p = simplify(pts, tol);
+  }
+  // Chaikin, twice: each edge cut a quarter of the way in from both ends (a
+  // closed ring wraps round), but never more than `round` from a corner, so a
+  // long straight run meeting a sharp cusp keeps its point instead of a bevel.
+  let q = p;
+  for (const r of [round, round / 2]) {
+    const n = q.length;
+    const next = closed ? [] : [q[0]];
+    for (let i = 0; i < (closed ? n : n - 1); i++) {
+      const a = q[i], b = q[(i + 1) % n];
+      const t = Math.min(0.25, r / (Math.hypot(b[0] - a[0], b[1] - a[1]) || 1));
+      next.push([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t], [b[0] + (a[0] - b[0]) * t, b[1] + (a[1] - b[1]) * t]);
+    }
+    if (!closed) next.push(q[n - 1]);
+    q = next;
+  }
+  const f = (/** @type {number} */ v) => (Math.round(v * 100) / 100).toString();
+  return `M${q.map((pt) => `${f(pt[0])} ${f(pt[1])}`).join('L')}${closed ? 'Z' : ''}`;
+}
+
+/**
+ * Douglas-Peucker on an open run: points within `tol` of the line between
+ * the kept ones go; the ends stay.
+ *
+ * @param {number[][]} pts
+ * @param {number} tol
+ * @returns {number[][]}
+ */
+function simplify(pts, tol) {
+  if (pts.length < 3) return pts.slice();
+  const keep = new Uint8Array(pts.length);
+  keep[0] = keep[pts.length - 1] = 1;
+  const stack = [[0, pts.length - 1]];
+  while (stack.length) {
+    const [i, j] = /** @type {number[]} */ (stack.pop());
+    const [ax, ay] = pts[i], [bx, by] = pts[j];
+    const L = Math.hypot(bx - ax, by - ay) || 1e-12;
+    let far = -1, fd = tol;
+    for (let k = i + 1; k < j; k++) {
+      const d = L > 1e-9 ? Math.abs((bx - ax) * (ay - pts[k][1]) - (ax - pts[k][0]) * (by - ay)) / L : Math.hypot(pts[k][0] - ax, pts[k][1] - ay);
+      if (d > fd) { fd = d; far = k; }
+    }
+    if (far >= 0) { keep[far] = 1; stack.push([i, far], [far, j]); }
+  }
+  return pts.filter((_, k) => keep[k]);
+}

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

@@ -0,0 +1,21 @@
+// Placing a mark by its real bounds and writing its outline in canvas units.
+import type { RenderContext } from '../render/context.js';
+
+/** A box, canvas or mark units. */
+export interface Box { x: number; y: number; width: number; height: number }
+
+/** A mark placed in an area: canvas x = mark x × k + dx. */
+export interface MarkFit {
+  k: number;
+  dx: number;
+  dy: number;
+  /** The area it was fitted in, canvas units. */
+  area: Box;
+}
+
+/** The layer's box (`x`, `y`, `width`, `height`; default the canvas), canvas units. */
+export function layerBox(layer: { x?: unknown; y?: unknown; width?: unknown; height?: unknown }, ctx: Pick<RenderContext, 'canvas'>): Box;
+/** Fit a mark's bounds (plus `reach` round them) into an area, centred: the longest side takes `share` of the area's shorter side, never past the area. */
+export function fitMark(box: Box, area: Box, share?: number, reach?: number): MarkFit;
+/** A mark's filled shapes as path data in canvas units, each with its fill rule. */
+export function markPaths(markup: string, fit: MarkFit): { d: string; evenodd: boolean }[];

package/src/layers/mark-draw.js

@@ -0,0 +1,93 @@
+/**
+ * Placing a mark by its real bounds and writing its outline in canvas
+ * units, so strokes drawn with it (keylines, contour lines) keep their
+ * width whatever the mark's scale. Shared by the `outline` and
+ * `construction` layers.
+ *
+ * @module layers/mark-draw
+ */
+
+import { num } from '@logomarks/image-effects/svg';
+import { shapes } from '@logomarks/core/svg';
+import { pos } from './util.js';
+
+/**
+ * @typedef {object} MarkFit
+ * @property {number} k - Canvas units a mark unit.
+ * @property {number} dx - Added to a mark x times k.
+ * @property {number} dy - Added to a mark y times k.
+ * @property {{ x: number, y: number, width: number, height: number }} area - The layer's box, canvas units.
+ */
+
+/**
+ * The layer's box (`x`, `y`, `width`, `height`; default the canvas), in
+ * canvas units.
+ *
+ * @param {any} layer
+ * @param {{ canvas: { width: number, height: number } }} ctx
+ * @returns {{ x: number, y: number, width: number, height: number }}
+ */
+export function layerBox(layer, ctx) {
+  return {
+    x: pos(layer.x ?? 0, 'x', ctx.canvas),
+    y: pos(layer.y ?? 0, 'y', ctx.canvas),
+    width: pos(layer.width ?? '100%', 'x', ctx.canvas),
+    height: pos(layer.height ?? '100%', 'y', ctx.canvas),
+  };
+}
+
+/**
+ * Fit a box of mark units (its real bounds, plus `reach` round it) into an
+ * area, centred: the longest side takes `share` of the area's shorter
+ * side, and the whole never passes the area.
+ *
+ * @param {{ x: number, y: number, width: number, height: number }} box - The mark's bounds, mark units.
+ * @param {{ x: number, y: number, width: number, height: number }} area - Canvas units.
+ * @param {number} [share=1] - 0–1.
+ * @param {number} [reach=0] - Mark units drawn round the bounds (contour lines), kept inside too.
+ * @returns {MarkFit}
+ *
+ * @example
+ * fitMark({ x: 96, y: 96, width: 320, height: 320 }, { x: 0, y: 0, width: 400, height: 400 }, 0.5).k; // 0.625
+ */
+export function fitMark(box, area, share = 1, reach = 0) {
+  const w = box.width + 2 * reach;
+  const h = box.height + 2 * reach;
+  const k = Math.min((Math.min(area.width, area.height) * share) / Math.max(w, h), area.width / w, area.height / h);
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  return { k, dx: area.x + area.width / 2 - cx * k, dy: area.y + area.height / 2 - cy * k, area };
+}
+
+/**
+ * A mark's filled shapes as path data in canvas units (each with its fill
+ * rule), through a fit.
+ *
+ * @param {string} markup - The mark's paths (512 grid).
+ * @param {MarkFit} fit
+ * @returns {{ d: string, evenodd: boolean }[]}
+ */
+export function markPaths(markup, { k, dx, dy }) {
+  return shapes(String(markup ?? '')).map((s) => ({ d: segsPath(s.segs, k, dx, dy), evenodd: s.evenodd }));
+}
+
+/**
+ * Absolute segments scaled by `k` and moved by `dx`, `dy`, as path data.
+ *
+ * @param {import('@logomarks/core/svg').Segment[]} segs
+ * @param {number} k @param {number} dx @param {number} dy
+ * @returns {string}
+ */
+function segsPath(segs, k, dx, dy) {
+  const X = (/** @type {number} */ v) => num(v * k + dx, 2);
+  const Y = (/** @type {number} */ v) => num(v * k + dy, 2);
+  return segs.map((s) => {
+    switch (s[0]) {
+      case 'M': case 'L': return `${s[0]}${X(s[1])} ${Y(s[2])}`;
+      case 'C': return `C${X(s[1])} ${Y(s[2])} ${X(s[3])} ${Y(s[4])} ${X(s[5])} ${Y(s[6])}`;
+      case 'Q': return `Q${X(s[1])} ${Y(s[2])} ${X(s[3])} ${Y(s[4])}`;
+      case 'A': return `A${num(s[1] * k, 2)} ${num(s[2] * k, 2)} ${num(s[3])} ${s[4] ? 1 : 0} ${s[5] ? 1 : 0} ${X(s[6])} ${Y(s[7])}`;
+      default: return 'Z';
+    }
+  }).join('');
+}

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 };

package/src/layers/marks.js

@@ -0,0 +1,102 @@
+/**
+ * The `marks` layer.
+ *
+ * @module layers/marks
+ */
+
+import { attrs, num } from '@logomarks/image-effects/svg';
+import { toHex } from '@logomarks/image-effects/color';
+import { pos, wrap } from './util.js';
+import { shapesOnly } from './svg.js';
+import { markGeometry } from './mark-geometry.js';
+
+/** The smallest and largest sheet: 3 × 3 to 10 × 7. */
+const MIN = 3;
+const MAX_COLS = 10;
+const MAX_ROWS = 7;
+
+/**
+ * `marks` — a set of marks on an even grid of square cells, centred in its
+ * box so the margins match, each mark optically sized the same: scaled by
+ * its real bounds (not its 512 grid), to the same area, nudged up a little
+ * where it inks less of that area (an outline looks smaller than a solid
+ * of the same size), and never past its cell. The logofolio sheet.
+ *
+ * Options: `marks` (a list of markup strings, or `{ markup }`), `cols` and
+ * `rows` (default from the count and the box: 3 × 3 up to 10 × 7), `x`,
+ * `y`, `width`, `height` (the box; default the canvas), `size` (the share
+ * of a cell a mark's area takes, 0.5), `optical` (`false` fits each
+ * mark's bounds to the same box instead), `color` (default `text`).
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {import('../layers.js').Markup}
+ *
+ * @example
+ * { type: 'marks', marks: ['<path d="…"/>', '<path d="…"/>'], x: 24, y: 120, width: 352, height: 340, color: '#f2efe8' }
+ */
+export function marks(layer, ctx) {
+  const list = (layer.marks ?? []).map((m) => (m && typeof m === 'object' ? m.markup : m)).filter(Boolean);
+  if (!list.length) return { defs: '', body: '' };
+  const bx = pos(layer.x ?? 0, 'x', ctx.canvas);
+  const by = pos(layer.y ?? 0, 'y', ctx.canvas);
+  const bw = pos(layer.width ?? '100%', 'x', ctx.canvas);
+  const bh = pos(layer.height ?? '100%', 'y', ctx.canvas);
+  const { cols, rows } = sheetGrid(list.length, bw / bh, layer.cols, layer.rows);
+  const cell = Math.min(bw / cols, bh / rows);
+  const ox = bx + (bw - cols * cell) / 2;
+  const oy = by + (bh - rows * cell) / 2;
+  const share = layer.size ?? 0.5;
+  const color = layer.color ? toHex(layer.color) : ctx.palette.text;
+
+  let body = '';
+  list.slice(0, cols * rows).forEach((markup, i) => {
+    const geo = markGeometry(markup);
+    if (!geo) return;
+    const { x, y, width, height } = geo.box;
+    // Optical: the same area (density-weighted, gently), capped at the cell; else the same longest side.
+    const fit = (cell * 0.86) / Math.max(width, height);
+    const k = layer.optical === false ? (cell * Math.sqrt(share)) / Math.max(width, height)
+      : Math.min(fit, (cell * Math.sqrt(share)) / (Math.sqrt(width * height) * (geo.density / 0.5) ** 0.15));
+    const cx = ox + (i % cols + 0.5) * cell;
+    const cy = oy + (Math.floor(i / cols) + 0.5) * cell;
+    body += `<svg${attrs({ x: cx - (width * k) / 2, y: cy - (height * k) / 2, width: width * k, height: height * k, viewBox: `${num(x)} ${num(y)} ${num(width)} ${num(height)}`, overflow: 'visible' })}>${shapesOnly(markup)}</svg>`;
+  });
+  return { defs: '', body: wrap(layer, `<g fill="${color}">${body}</g>`) };
+}
+
+/**
+ * Columns and rows for `n` marks in a box of `aspect` (width / height):
+ * the biggest cells the box allows, less a cost for empty cells (so 25
+ * is 5 × 5, not 6 × 5 with a ragged row), 3 × 3 at the least, 10 × 7 at
+ * the most (marks past 70 are left out). Given ones are kept.
+ *
+ * @param {number} n
+ * @param {number} aspect
+ * @param {number} [cols]
+ * @param {number} [rows]
+ * @returns {{ cols: number, rows: number }}
+ *
+ * @example
+ * sheetGrid(70, 0.8); // { cols: 10, rows: 7 }
+ * sheetGrid(25, 1.6); // { cols: 5, rows: 5 }
+ */
+export function sheetGrid(n, aspect, cols, rows) {
+  if (cols && rows) return { cols: Math.round(cols), rows: Math.round(rows) };
+  if (cols) return { cols: Math.round(cols), rows: Math.max(1, Math.ceil(n / cols)) };
+  if (rows) return { cols: Math.max(1, Math.ceil(n / rows)), rows: Math.round(rows) };
+  // The biggest cells, less a cost for empty ones (a ragged last row).
+  const count = Math.min(n, MAX_COLS * MAX_ROWS);
+  let best = { cols: MAX_COLS, rows: MAX_ROWS };
+  let score = -Infinity;
+  for (let c = MIN; c <= MAX_COLS; c++) {
+    const r = clamp(Math.ceil(count / c), MIN, MAX_ROWS);
+    if (c * r < count) continue;
+    const s = Math.min(aspect / c, 1 / r) * (1 - (1.5 * (c * r - count)) / (c * r));
+    if (s > score + 1e-9) [best, score] = [{ cols: c, rows: r }, s];
+  }
+  return best;
+}
+
+/** @param {number} v @param {number} lo @param {number} hi @returns {number} */
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));

package/src/layers/mosaic.d.ts

@@ -0,0 +1,32 @@
+// The `mosaic` layer.
+import type { Color, Length, BaseLayer } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+import type { PixelGrid } from '@logomarks/core/edit';
+import type { MarkGeometry } from './mark-geometry.js';
+
+export interface MosaicLayer extends BaseLayer {
+  type: 'mosaic';
+  /** The mark's paths, on a 512 grid. */
+  markup: string;
+  /** The box the mosaic is fitted and centred in (default the canvas). */
+  x?: Length | `${number}%`; y?: Length | `${number}%`; width?: Length | `${number}%`; height?: Length | `${number}%`;
+  /** Cells across the mark's longest side, 4–48. Default 10. */
+  cells?: number;
+  /** The gap between cells, a share of a cell. Default 0.12. */
+  gap?: number;
+  /** Cell corner radius, a share of a cell. Default 0. */
+  radius?: number;
+  /** The share of filled cells left out, by the layer's seed (0–0.9). Default 0.12. */
+  drop?: number;
+  /** Default the palette's accent. */
+  color?: Color;
+  /** A small asterisk or dot in one empty cell beside the mark. */
+  accent?: 'asterisk' | 'dot' | false;
+  /** Default `color`. */
+  accentColor?: Color;
+}
+
+/** Draw a mark as a mosaic of square cells. */
+export function mosaic(layer: MosaicLayer, ctx: RenderContext): Markup;
+/** The mosaic's grid over a mark: `cells` across its longest side, centred on its bounds. */
+export function mosaicGrid(geo: MarkGeometry, cells?: number): PixelGrid;