@arraypress/covers 1.4.0 → 1.6.1

package/src/layers/construction.d.ts

@@ -0,0 +1,34 @@
+// The `construction` layer.
+import type { Color, Length, BaseLayer } from '../index.js';
+import type { RenderContext, Markup } from '../render/context.js';
+
+export interface ConstructionLayer extends BaseLayer {
+  type: 'construction';
+  /** The mark's paths, on a 512 grid. */
+  markup: string;
+  /** The box the sheet fills (default the canvas); the mark is centred in it. */
+  x?: Length | `${number}%`; y?: Length | `${number}%`; width?: Length | `${number}%`; height?: Length | `${number}%`;
+  /** The share of the box's shorter side the mark's longest side takes. Default 0.6. */
+  size?: number;
+  /** Grid cells across the mark's longest side; 0 none. Default 8. */
+  grid?: number;
+  /** The most circles read from its curves. Default 6. */
+  circles?: number;
+  /** The most lines read from its straight edges. Default 6. */
+  lines?: number;
+  /** The guides. Default the palette's accent. */
+  color?: Color;
+  /** Default `color`. */
+  gridColor?: Color;
+  /** Default 0.3. */
+  gridOpacity?: number;
+  /** Default the palette's text; `'none'` leaves the mark out. */
+  markColor?: Color | 'none';
+  /** The guides' opacity over the mark, 0–1. Default 0.4. */
+  over?: number;
+  /** Guide width. Default `'0.15vmin'`. */
+  stroke?: Length;
+}
+
+/** Draw a mark over its own construction: grid, box, centre cross, its circles and lines. */
+export function construction(layer: ConstructionLayer, ctx: RenderContext): Markup;

package/src/layers/construction.js

@@ -0,0 +1,137 @@
+/**
+ * The `construction` layer.
+ *
+ * @module layers/construction
+ */
+
+import { attrs, num } from '@logomarks/image-effects/svg';
+import { toHex } from '@logomarks/image-effects/color';
+import { len } from '@logomarks/image-effects/length';
+import { wrap } from './util.js';
+import { markGuides } from './guides.js';
+import { layerBox, fitMark, markPaths } from './mark-draw.js';
+
+/**
+ * `construction` — a mark drawn over its own construction, as a
+ * construction sheet draws it: a light dashed square grid behind (its
+ * cells a fraction of the mark's size, centred on it), the mark's bounding
+ * box, a centre cross, the circles inscribed in its box and round its
+ * outline, the circles its curves are drawn on (each centre marked) and
+ * the lines its straight edges lie on, run across the box, all dashed in
+ * one thin accent. The guides are read from the mark's own paths
+ * (`markGuides`). Where the mark covers them they show faintly over it.
+ *
+ * Options: `markup` (512 grid), `x`, `y`, `width`, `height` (the box the
+ * sheet fills; default the canvas), `size` (the share of the box's
+ * shorter side the mark's longest side takes, 0.6), `grid` (cells across
+ * the mark's longest side, 8; 0 none), `circles` and `lines` (the most of
+ * each, 6), `color` (the guides; default the accent), `gridColor`
+ * (default `color`), `gridOpacity` (0.3), `markColor` (default `text`;
+ * `'none'` leaves the mark out), `over` (the guides' opacity over the
+ * mark, 0.4), `stroke` (px, `'0.15vmin'`).
+ *
+ * @param {any} layer
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {import('../layers.js').Markup}
+ *
+ * @example
+ * { type: 'construction', markup: mark, x: 24, y: 60, width: 352, height: 380, color: '#3b82f6', markColor: '#f4f4f2' }
+ */
+export function construction(layer, ctx) {
+  const g = markGuides(layer.markup, { circles: layer.circles ?? 6, lines: layer.lines ?? 6 });
+  if (!g) return { defs: '', body: '' };
+  const area = layerBox(layer, ctx);
+  const fit = fitMark(g.box, area, layer.size ?? 0.6);
+  const { k } = fit;
+  const X = (/** @type {number} */ x) => x * k + fit.dx;
+  const Y = (/** @type {number} */ y) => y * k + fit.dy;
+  const color = layer.color ? toHex(layer.color) : ctx.palette.accent;
+  const sw = len(layer.stroke, ctx.canvas, '0.15vmin');
+  const dash = `${num(sw * 6)} ${num(sw * 4)}`;
+  const line = (/** @type {Record<string, any>} */ a) => `<path${attrs({ fill: 'none', ...a })}/>`;
+
+  // The box, its centre and the mark's longest side, canvas units.
+  const bx = X(g.box.x), by = Y(g.box.y), bw = g.box.width * k, bh = g.box.height * k;
+  const cx = bx + bw / 2, cy = by + bh / 2;
+  const side = Math.max(bw, bh);
+  const { x: ax, y: ay, width: aw, height: ah } = area;
+
+  // The grid: cells of side / grid, lines through the mark's centre.
+  let grid = '';
+  const cells = Math.round(layer.grid ?? 8);
+  if (cells > 0) {
+    const u = side / cells;
+    let d = '';
+    for (let x = cx - Math.floor((cx - ax) / u) * u; x <= ax + aw + 1e-6; x += u) d += `M${num(x)} ${num(ay)}V${num(ay + ah)}`;
+    for (let y = cy - Math.floor((cy - ay) / u) * u; y <= ay + ah + 1e-6; y += u) d += `M${num(ax)} ${num(y)}H${num(ax + aw)}`;
+    grid = line({ d, stroke: layer.gridColor ? toHex(layer.gridColor) : color, 'stroke-width': num(sw * 0.8, 3), 'stroke-dasharray': `${num(sw * 3)} ${num(sw * 3)}`, opacity: num(layer.gridOpacity ?? 0.3, 3) });
+  }
+
+  // Keylines: the box (solid), the centre cross and the inscribed and circumscribed circles (dashed, lighter).
+  let keys = line({ d: `M${num(bx)} ${num(by)}h${num(bw)}v${num(bh)}h${num(-bw)}Z`, stroke: color, 'stroke-width': num(sw, 3) });
+  keys += line({ d: `M${num(ax)} ${num(cy)}H${num(ax + aw)}M${num(cx)} ${num(ay)}V${num(ay + ah)}`, stroke: color, 'stroke-width': num(sw, 3), 'stroke-dasharray': dash, opacity: 0.6 });
+  keys += line({ d: circlePath(cx, cy, g.inscribed * k) + circlePath(cx, cy, g.circumscribed * k), stroke: color, 'stroke-width': num(sw, 3), 'stroke-dasharray': dash, opacity: 0.6 });
+
+  // The mark's own circles, each centre marked, and its edges' lines across the box.
+  let d = '';
+  let ticks = '';
+  const t = sw * 4;
+  for (const c of g.circles) {
+    const [x, y] = [X(c.cx), Y(c.cy)];
+    d += circlePath(x, y, c.r * k);
+    ticks += `M${num(x - t)} ${num(y)}h${num(2 * t)}M${num(x)} ${num(y - t)}v${num(2 * t)}`;
+  }
+  let lines = '';
+  for (const l of g.lines) {
+    const seg = clipLine(X(l.x), Y(l.y), Math.cos(l.angle), Math.sin(l.angle), area);
+    if (seg) lines += `M${num(seg[0])} ${num(seg[1])}L${num(seg[2])} ${num(seg[3])}`;
+  }
+  let guides = keys;
+  if (d) guides += line({ d, stroke: color, 'stroke-width': num(sw, 3), 'stroke-dasharray': dash });
+  if (lines) guides += line({ d: lines, stroke: color, 'stroke-width': num(sw, 3), 'stroke-dasharray': dash, opacity: 0.75 });
+  if (ticks) guides += line({ d: ticks, stroke: color, 'stroke-width': num(sw, 3) });
+
+  const clip = `${ctx.id}k`;
+  const maskId = `${ctx.id}m`;
+  let defs = `<clipPath id="${clip}"><rect${attrs({ x: ax, y: ay, width: aw, height: ah })}/></clipPath>`;
+  let body = `${grid}${guides}`;
+  const markColor = layer.markColor === 'none' ? null : layer.markColor ? toHex(layer.markColor) : ctx.palette.text;
+  if (markColor) {
+    const paths = markPaths(layer.markup, fit).map((p) => `<path${attrs({ d: p.d, 'fill-rule': p.evenodd ? 'evenodd' : undefined })}/>`).join('');
+    body += `<g fill="${markColor}">${paths}</g>`;
+    const over = layer.over ?? 0.4;
+    if (over > 0) {
+      defs += `<mask id="${maskId}" maskUnits="userSpaceOnUse"${attrs({ x: ax, y: ay, width: aw, height: ah })}><g fill="#fff">${paths}</g></mask>`;
+      body += `<g mask="url(#${maskId})" opacity="${num(over, 3)}">${guides}</g>`;
+    }
+  }
+  return { defs, body: wrap(layer, `<g clip-path="url(#${clip})">${body}</g>`) };
+}
+
+/**
+ * A circle as path data (two arcs), so circles share one path.
+ *
+ * @param {number} cx @param {number} cy @param {number} r
+ * @returns {string}
+ */
+function circlePath(cx, cy, r) {
+  return `M${num(cx - r)} ${num(cy)}a${num(r)} ${num(r)} 0 1 0 ${num(2 * r)} 0a${num(r)} ${num(r)} 0 1 0 ${num(-2 * r)} 0Z`;
+}
+
+/**
+ * The part of the line through (x, y) along (ux, uy) inside a box
+ * (Liang–Barsky), or null when it misses.
+ *
+ * @param {number} x @param {number} y @param {number} ux @param {number} uy
+ * @param {{ x: number, y: number, width: number, height: number }} box
+ * @returns {number[] | null} `[x1, y1, x2, y2]`.
+ */
+function clipLine(x, y, ux, uy, box) {
+  let t0 = -Infinity, t1 = Infinity;
+  for (const [p, q] of [[-ux, x - box.x], [ux, box.x + box.width - x], [-uy, y - box.y], [uy, box.y + box.height - y]]) {
+    if (Math.abs(p) < 1e-12) { if (q < 0) return null; continue; }
+    const r = q / p;
+    if (p < 0) t0 = Math.max(t0, r); else t1 = Math.min(t1, r);
+  }
+  return t0 < t1 ? [x + ux * t0, y + uy * t0, x + ux * t1, y + uy * t1] : null;
+}

package/src/layers/focal.d.ts

@@ -0,0 +1,8 @@
+// Placing a photo on a point of it: a focus [x, y], or a cut-out's head.
+
+/** A cut-out's head (the alpha-weighted centre of the top 45% of its opaque rows), 0–1 in the photo; null with no transparency. */
+export function subjectFocus(sharp: any, bytes: Uint8Array): Promise<[number, number] | null>;
+/** The drawn box (relative to the box) that centres a point of a `sw` × `sh` photo; `cover` keeps the box filled except sideways when `free` (a cut-out). */
+export function focalBox(box: { width: number; height: number }, sw: number, sh: number, fit: 'cover' | 'contain', point: [number, number], free?: boolean): { x: number; y: number; width: number; height: number };
+/** A `W` × `H` raster with the photo drawn at a box (raster pixels), the rest clear, as a sharp pipeline. */
+export function drawAt(sharp: any, bytes: Uint8Array, W: number, H: number, at: { x: number; y: number; width: number; height: number }): Promise<any>;

package/src/layers/focal.js

@@ -0,0 +1,109 @@
+/**
+ * Placing a photo on a point of it: a focus `[x, y]` (0–1 in the photo),
+ * or `'subject'`, a cut-out's head, found from its transparency. Used by
+ * the `image` layer when sharp is there to draw the pixels.
+ *
+ * @module layers/focal
+ */
+
+/** The share of a cut-out's opaque height, from its top, taken as its head. */
+const HEAD = 0.45;
+/** Rows and columns the transparency is read at. */
+const PROBE = 160;
+
+/**
+ * Where a cut-out's head is: the alpha-weighted centre of the top 45% of
+ * its opaque rows, as `[x, y]` fractions of the photo. Null for a photo
+ * with no transparency to read (an ordinary photo: no subject to find).
+ *
+ * @param {any} sharp - The sharp module.
+ * @param {Uint8Array} bytes
+ * @returns {Promise<[number, number] | null>}
+ *
+ * @example
+ * await subjectFocus(sharp, cutoutPng); // [0.56, 0.21]
+ */
+export async function subjectFocus(sharp, bytes) {
+  const meta = await sharp(bytes).metadata();
+  if (!meta.hasAlpha) return null;
+  const { data, info } = await sharp(bytes).rotate().ensureAlpha().resize(PROBE, PROBE, { fit: 'fill' }).raw().toBuffer({ resolveWithObject: true });
+  const { width: w, height: h, channels: c } = info;
+  const alpha = (/** @type {number} */ x, /** @type {number} */ y) => data[(y * w + x) * c + 3] / 255;
+  // The opaque rows: those with a few solid pixels.
+  const rows = [];
+  for (let y = 0; y < h; y++) {
+    let s = 0;
+    for (let x = 0; x < w; x++) s += alpha(x, y);
+    if (s >= 2) rows.push(y);
+  }
+  let clear = false;
+  for (let i = 3; i < data.length && !clear; i += c) clear = data[i] < 250;
+  if (!rows.length || !clear) return null;
+  const top = rows[0];
+  const bottom = rows[rows.length - 1];
+  const end = top + Math.max(1, Math.round((bottom - top + 1) * HEAD));
+  let sum = 0, sx = 0, sy = 0;
+  for (let y = top; y < end; y++) {
+    for (let x = 0; x < w; x++) {
+      const a = alpha(x, y);
+      sum += a; sx += a * (x + 0.5); sy += a * (y + 0.5);
+    }
+  }
+  return sum ? [sx / sum / w, sy / sum / h] : null;
+}
+
+/**
+ * Where a photo of `sw` × `sh` is drawn in a box so a point of it is
+ * centred: scaled to `fit` (cover or contain), then moved so the point
+ * sits on the box's centre. `cover` keeps the box filled (the move is
+ * held to the photo's overflow), except sideways for a cut-out
+ * (`free`), whose transparent sides show the ground; `contain` keeps it
+ * inside the box.
+ *
+ * @param {{ width: number, height: number }} box - Its size (any units).
+ * @param {number} sw @param {number} sh - The photo's size.
+ * @param {'cover' | 'contain'} fit
+ * @param {[number, number]} point - 0–1 in the photo.
+ * @param {boolean} [free=false] - Move freely sideways (a cut-out).
+ * @returns {{ x: number, y: number, width: number, height: number }} The photo's drawn box, relative to the box.
+ *
+ * @example
+ * focalBox({ width: 400, height: 500 }, 1000, 1000, 'cover', [0.3, 0]); // { x: 0, y: 0, width: 500, height: 500 }: held at the left edge
+ * focalBox({ width: 400, height: 500 }, 1000, 1000, 'cover', [0.3, 0], true); // { x: 50, … }: a cut-out, centred on 0.3
+ */
+export function focalBox(box, sw, sh, fit, [fx, fy], free = false) {
+  const k = fit === 'contain' ? Math.min(box.width / sw, box.height / sh) : Math.max(box.width / sw, box.height / sh);
+  const width = sw * k;
+  const height = sh * k;
+  let x = box.width / 2 - fx * width;
+  let y = box.height / 2 - fy * height;
+  /** Held between a and b (in either order). */
+  const hold = (/** @type {number} */ v, /** @type {number} */ a, /** @type {number} */ b) => Math.min(Math.max(a, b), Math.max(Math.min(a, b), v));
+  if (!free || fit === 'contain') x = hold(x, 0, box.width - width);
+  y = hold(y, 0, box.height - height);
+  return { x, y, width, height };
+}
+
+/**
+ * Draw a photo into a `W` × `H` raster at a drawn box (raster pixels), the
+ * rest transparent: resized, the visible part cut out and laid on a clear
+ * canvas. Returns a sharp pipeline of the result.
+ *
+ * @param {any} sharp
+ * @param {Uint8Array} bytes
+ * @param {number} W @param {number} H
+ * @param {{ x: number, y: number, width: number, height: number }} at - Raster pixels.
+ * @returns {Promise<any>}
+ */
+export async function drawAt(sharp, bytes, W, H, at) {
+  const rw = Math.max(1, Math.round(at.width));
+  const rh = Math.max(1, Math.round(at.height));
+  const ox = Math.round(at.x);
+  const oy = Math.round(at.y);
+  const left = Math.max(0, -ox), top = Math.max(0, -oy);
+  const width = Math.min(rw, W - ox) - left, height = Math.min(rh, H - oy) - top;
+  const canvas = sharp({ create: { width: W, height: H, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } });
+  if (width <= 0 || height <= 0) return sharp(await canvas.png().toBuffer());
+  const part = await sharp(bytes).rotate().ensureAlpha().resize(rw, rh, { fit: 'fill' }).extract({ left, top, width, height }).png().toBuffer();
+  return sharp(await canvas.composite([{ input: part, left: Math.max(0, ox), top: Math.max(0, oy) }]).png().toBuffer());
+}

package/src/layers/guides.d.ts

@@ -0,0 +1,38 @@
+// A mark's construction, read from its paths.
+
+/** A circle the mark's curves are drawn on. */
+export interface GuideCircle {
+  cx: number;
+  cy: number;
+  r: number;
+  /** How much of it the mark draws, radians. */
+  sweep: number;
+}
+
+/** A line the mark's straight edges lie on. */
+export interface GuideLine {
+  /** Radians, 0–π. */
+  angle: number;
+  /** A point on it. */
+  x: number;
+  y: number;
+  /** The mark's edges on it, in total. */
+  length: number;
+}
+
+/** A mark's construction, in its own (512 grid) units. */
+export interface MarkGuides {
+  /** Its real bounds. */
+  box: { x: number; y: number; width: number; height: number };
+  /** The radius of the circle in its box. */
+  inscribed: number;
+  /** The radius of the circle round its outline, from the box's centre. */
+  circumscribed: number;
+  /** Its curves' circles, the most drawn first. */
+  circles: GuideCircle[];
+  /** Its straight edges' lines, the longest first. */
+  lines: GuideLine[];
+}
+
+/** Read a mark's construction (null when it draws nothing); at most `circles` and `lines` of each (6). */
+export function markGuides(markup: string, options?: { circles?: number; lines?: number }): MarkGuides | null;

package/src/layers/guides.js

@@ -0,0 +1,212 @@
+/**
+ * A mark's construction, read from its paths: the circles its curves are
+ * drawn on and the lines its straight edges lie on, for a construction
+ * sheet.
+ *
+ * @module layers/guides
+ */
+
+import { shapes, bounds, outlinePoints, arcOf, bezierAt } from '@logomarks/core/svg';
+
+/**
+ * @typedef {object} GuideCircle
+ * @property {number} cx @property {number} cy @property {number} r
+ * @property {number} sweep - How much of it the mark draws, radians (2π: all of it).
+ */
+
+/**
+ * @typedef {object} GuideLine
+ * @property {number} angle - Radians, 0–π.
+ * @property {number} x @property {number} y - A point on it (the middle of its longest edge).
+ * @property {number} length - The mark's edges on it, in total.
+ */
+
+/**
+ * @typedef {object} MarkGuides
+ * @property {{ x: number, y: number, width: number, height: number }} box - Its real bounds.
+ * @property {number} inscribed - The radius of the circle in its box, round the box's centre.
+ * @property {number} circumscribed - The radius of the circle round its outline, from the box's centre.
+ * @property {GuideCircle[]} circles - Its curves' circles, the most drawn first.
+ * @property {GuideLine[]} lines - Its straight edges' lines, the longest first.
+ */
+
+/** Read marks, by markup and counts. @type {Map<string, MarkGuides>} */
+const cache = new Map();
+
+/**
+ * Read a mark's construction. A curve counts as part of a circle when
+ * its points lie on the circle through its ends and middle (an arc, or a
+ * Bézier drawn round one); curves on the same circle are added up, and
+ * a circle is kept when the mark draws a good share of it (50° or more)
+ * and it isn't a small corner round. Straight edges on the same line are
+ * added up the same way, and lines along the box's own sides left out.
+ *
+ * @param {string} markup - The mark's paths (512 grid).
+ * @param {{ circles?: number, lines?: number }} [options] - The most of each kept (6 and 6).
+ * @returns {MarkGuides | null} Null when it draws nothing.
+ *
+ * @example
+ * markGuides('<circle cx="256" cy="256" r="200"/>').circles; // [{ cx: 256, cy: 256, r: 200, sweep: 6.28… }]
+ */
+export function markGuides(markup, { circles = 6, lines = 6 } = {}) {
+  const key = `${circles}|${lines}|${markup}`;
+  if (cache.has(key)) return /** @type {MarkGuides} */ (cache.get(key));
+  const filled = shapes(String(markup ?? ''));
+  if (!filled.length) return null;
+  const b = bounds(filled);
+  if (!(b.w > 0 && b.h > 0)) return null;
+  const box = { x: b.x, y: b.y, width: b.w, height: b.h };
+  const size = Math.max(b.w, b.h);
+  const cx = b.x + b.w / 2;
+  const cy = b.y + b.h / 2;
+
+  /** @type {GuideCircle[]} */
+  const arcs = [];
+  /** @type {{ x1: number, y1: number, x2: number, y2: number }[]} */
+  const edges = [];
+  let far = 0;
+  for (const s of filled) {
+    for (const [x, y] of outlinePoints(s.segs)) far = Math.max(far, Math.hypot(x - cx, y - cy));
+    let x = 0, y = 0, sx = 0, sy = 0;
+    for (const seg of s.segs) {
+      switch (seg[0]) {
+        case 'M': x = sx = seg[1]; y = sy = seg[2]; break;
+        case 'L': edges.push({ x1: x, y1: y, x2: seg[1], y2: seg[2] }); x = seg[1]; y = seg[2]; break;
+        case 'C': fitCurve([[x, y], [seg[1], seg[2]], [seg[3], seg[4]], [seg[5], seg[6]]], arcs); x = seg[5]; y = seg[6]; break;
+        case 'Q': fitCurve([[x, y], [seg[1], seg[2]], [seg[3], seg[4]]], arcs); x = seg[3]; y = seg[4]; break;
+        case 'A': {
+          const a = arcOf(x, y, seg.slice(1));
+          if (a && Math.abs(a.rx - a.ry) <= 0.01 * Math.max(a.rx, a.ry)) arcs.push({ cx: a.cx, cy: a.cy, r: (a.rx + a.ry) / 2, sweep: Math.abs(a.sweep) });
+          x = seg[6]; y = seg[7];
+          break;
+        }
+        case 'Z': edges.push({ x1: x, y1: y, x2: sx, y2: sy }); x = sx; y = sy; break;
+      }
+    }
+  }
+
+  const guides = {
+    box,
+    inscribed: Math.min(b.w, b.h) / 2,
+    circumscribed: far,
+    circles: circleGuides(arcs, size).slice(0, Math.max(0, circles)),
+    lines: lineGuides(edges, box).slice(0, Math.max(0, lines)),
+  };
+  if (cache.size > 200) cache.clear();
+  cache.set(key, guides);
+  return guides;
+}
+
+/**
+ * The circle a curve is drawn round, added to `arcs` when its quarter
+ * points lie on it too (within half a unit, or 1% of its radius).
+ *
+ * @param {number[][]} P - A quadratic's 3 points or a cubic's 4.
+ * @param {GuideCircle[]} arcs
+ */
+function fitCurve(P, arcs) {
+  const p0 = P[0];
+  const p1 = /** @type {number[]} */ (bezierAt(/** @type {any} */ (P), 0.5));
+  const p2 = P[P.length - 1];
+  const c = circleThrough(p0, p1, p2);
+  if (!c) return;
+  const tol = Math.max(0.5, c.r * 0.01);
+  for (const u of [0.25, 0.75]) {
+    const [x, y] = bezierAt(/** @type {any} */ (P), u);
+    if (Math.abs(Math.hypot(x - c.cx, y - c.cy) - c.r) > tol) return;
+  }
+  const turn = (/** @type {number[]} */ a, /** @type {number[]} */ b) => {
+    const ux = a[0] - c.cx, uy = a[1] - c.cy, vx = b[0] - c.cx, vy = b[1] - c.cy;
+    return Math.abs(Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy));
+  };
+  arcs.push({ ...c, sweep: turn(p0, p1) + turn(p1, p2) });
+}
+
+/**
+ * The circle through three points, or null when they're (nearly) on a line.
+ *
+ * @param {number[]} a @param {number[]} b @param {number[]} c
+ * @returns {{ cx: number, cy: number, r: number } | null}
+ */
+function circleThrough(a, b, c) {
+  const d = 2 * (a[0] * (b[1] - c[1]) + b[0] * (c[1] - a[1]) + c[0] * (a[1] - b[1]));
+  if (Math.abs(d) < 1e-6) return null;
+  const A = a[0] ** 2 + a[1] ** 2, B = b[0] ** 2 + b[1] ** 2, C = c[0] ** 2 + c[1] ** 2;
+  const cx = (A * (b[1] - c[1]) + B * (c[1] - a[1]) + C * (a[1] - b[1])) / d;
+  const cy = (A * (c[0] - b[0]) + B * (a[0] - c[0]) + C * (b[0] - a[0])) / d;
+  return { cx, cy, r: Math.hypot(a[0] - cx, a[1] - cy) };
+}
+
+/**
+ * Arcs on the same circle added up (centres and radii within 3 units or
+ * 3%); kept when the mark draws 50° or more of it and its radius is 4%
+ * to 120% of the mark's size; the most drawn (by length) first.
+ *
+ * @param {GuideCircle[]} arcs
+ * @param {number} size - The mark's longest side.
+ * @returns {GuideCircle[]}
+ */
+function circleGuides(arcs, size) {
+  /** @type {(GuideCircle & { w: number })[]} */
+  const groups = [];
+  for (const a of arcs) {
+    const near = Math.max(3, a.r * 0.03);
+    const g = groups.find((o) => Math.hypot(o.cx - a.cx, o.cy - a.cy) <= near && Math.abs(o.r - a.r) <= near);
+    if (!g) { groups.push({ ...a, w: a.sweep }); continue; }
+    // A sweep-weighted mean, so the long arcs set the circle.
+    const w = g.w + a.sweep;
+    g.cx = (g.cx * g.w + a.cx * a.sweep) / w;
+    g.cy = (g.cy * g.w + a.cy * a.sweep) / w;
+    g.r = (g.r * g.w + a.r * a.sweep) / w;
+    g.w = w;
+    g.sweep = Math.min(2 * Math.PI, g.sweep + a.sweep);
+  }
+  return groups
+    .filter((g) => g.sweep >= (50 * Math.PI) / 180 && g.r >= size * 0.04 && g.r <= size * 1.2)
+    .sort((p, q) => q.sweep * q.r - p.sweep * p.r || p.cx - q.cx || p.cy - q.cy)
+    .map(({ cx, cy, r, sweep }) => ({ cx, cy, r, sweep }));
+}
+
+/**
+ * Edges on the same line added up (within 0.75° and 1.5 units); kept
+ * when 8% of the mark's size or longer in total and not along a side of
+ * its box; the longest first.
+ *
+ * @param {{ x1: number, y1: number, x2: number, y2: number }[]} edges
+ * @param {{ x: number, y: number, width: number, height: number }} box
+ * @returns {GuideLine[]}
+ */
+function lineGuides(edges, box) {
+  const size = Math.max(box.width, box.height);
+  /** @type {(GuideLine & { rho: number, best: number })[]} */
+  const groups = [];
+  for (const e of edges) {
+    const length = Math.hypot(e.x2 - e.x1, e.y2 - e.y1);
+    if (length < size * 0.02) continue;
+    let angle = Math.atan2(e.y2 - e.y1, e.x2 - e.x1);
+    if (angle < 0) angle += Math.PI;
+    if (angle >= Math.PI - 1e-9) angle -= Math.PI;
+    const x = (e.x1 + e.x2) / 2, y = (e.y1 + e.y2) / 2;
+    const rho = -Math.sin(angle) * x + Math.cos(angle) * y;
+    const g = groups.find((o) => {
+      const da = Math.abs(o.angle - angle);
+      const parallel = Math.min(da, Math.PI - da) < 0.013;
+      // Across 0 and π the line's normal flips, so its offset does too.
+      const apart = da < 0.013 ? Math.abs(o.rho - rho) : Math.abs(o.rho + rho);
+      return parallel && apart <= 1.5;
+    });
+    if (!g) { groups.push({ angle, x, y, length, rho, best: length }); continue; }
+    g.length += length;
+    if (length > g.best) { g.best = length; g.x = x; g.y = y; }
+  }
+  const onSide = (/** @type {GuideLine} */ l) => {
+    const flat = Math.min(l.angle, Math.PI - l.angle) < 0.013;
+    const upright = Math.abs(l.angle - Math.PI / 2) < 0.013;
+    return (flat && (Math.abs(l.y - box.y) < 1.5 || Math.abs(l.y - box.y - box.height) < 1.5))
+      || (upright && (Math.abs(l.x - box.x) < 1.5 || Math.abs(l.x - box.x - box.width) < 1.5));
+  };
+  return groups
+    .filter((g) => g.length >= size * 0.08 && !onSide(g))
+    .sort((p, q) => q.length - p.length || p.angle - q.angle || p.rho - q.rho)
+    .map(({ angle, x, y, length }) => ({ angle, x, y, length }));
+}

package/src/layers/index.d.ts

@@ -20,5 +20,11 @@ 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 { outline } from './outline.js';
+export type { OutlineLayer } from './outline.js';
+export { construction } from './construction.js';
+export type { ConstructionLayer } from './construction.js';
+export { markGuides } from './guides.js';
+export type { MarkGuides, GuideCircle, GuideLine } from './guides.js';
 export { expandRepeat } from './repeat.js';
 export type { RepeatLayer } from './repeat.js';

package/src/layers/index.js

@@ -15,4 +15,7 @@ export { texture } from './texture.js';
 export { mosaic, mosaicGrid } from './mosaic.js';
 export { marks, sheetGrid } from './marks.js';
 export { markGeometry } from './mark-geometry.js';
+export { outline } from './outline.js';
+export { construction } from './construction.js';
+export { markGuides } from './guides.js';
 export { expandRepeat } from './repeat.js';

package/src/layers/isolines.d.ts

@@ -0,0 +1,21 @@
+// Isolines of a sampled field, and a mark's signed distance field.
+import type { MarkGeometry } from './mark-geometry.js';
+
+/** A signed distance field over a mark: positive outside, negative inside, mark units. */
+export interface DistanceField {
+  values: Float32Array;
+  width: number;
+  height: number;
+  /** The mark point of the first sample. */
+  x0: number;
+  y0: number;
+  /** Mark units between samples. */
+  step: number;
+}
+
+/** A mark's signed distance field over its box plus `reach`, `samples` across its longest side (500); exact near `levels`, where lines will be traced. */
+export function distanceField(geo: MarkGeometry, reach: number, levels?: number[], samples?: number): DistanceField;
+/** Where a field (row by row, `w` × `h`) crosses `level`: polylines of `[column, row]`, closed ones ending on their first point. */
+export function isolines(f: ArrayLike<number>, w: number, h: number, level: number): number[][][];
+/** A polyline simplified within `tol` and smoothed (two rounds of Chaikin, corners rounded by at most `round`), as path data. */
+export function smoothLine(pts: number[][], tol?: number, round?: number): string;