logomarks 0.0.0-stage → 1.0.0

package/src/cover/index.d.ts

@@ -0,0 +1,49 @@
+import type { Mark } from '../brand/mark.js';
+
+/** What a recipe is built from. */
+export interface CoverBrand {
+	/** The mark's SVG. */
+	mark: string;
+	/** The brand colour. */
+	color: string;
+	/** Whether the cover has a title (the mark moves out of its way). */
+	titled: boolean;
+}
+
+/** A curated recipe: what it looks like, and its `@arraypress/covers` options. */
+export interface CoverRecipe {
+	about: string;
+	options: (b: CoverBrand) => Record<string, unknown>;
+}
+
+/** What to draw. */
+export interface CoverOptions {
+	mark: Mark;
+	/** One of `RECIPES` (`mark`). */
+	recipe?: string;
+	title?: string;
+	/** A small line over the title. */
+	label?: string;
+	/** The brand colour (the site's yellow). */
+	color?: string;
+	/** `og` (1200 × 630, the default), `1:1`, `16:9`, `4:5`, `3:2`, `4:3`, `2:1`, `9:16`, any `w:h`, or a number. */
+	aspect?: string | number;
+	/** Pixels wide (1200). */
+	width?: number;
+	/** Drives every random choice (the mark's slug). */
+	seed?: string;
+}
+
+/** A cover. */
+export interface Cover {
+	png: Uint8Array;
+	/** The SVG, text as outlines. */
+	svg: string;
+	width: number;
+	height: number;
+}
+
+/** The curated recipes, by name. */
+export const RECIPES: Record<string, CoverRecipe>;
+/** A cover with the mark on it, as PNG (resvg) and SVG. Throws a TypeError for an unknown recipe. */
+export function cover(o: CoverOptions): Promise<Cover>;

package/src/cover/index.js

@@ -0,0 +1,63 @@
+/**
+ * @module logomarks/cover
+ *
+ * Covers (blog headers, Open Graph cards, posts) with the mark on them, from
+ * `@arraypress/covers` recipes: a curated handful that suit a mark. The
+ * cover is SVG with its text as outlines; resvg draws the PNG.
+ */
+
+import { renderSvg, resolvePalette } from '@arraypress/covers';
+import { palette as makePalette, DEFAULT_COLOR } from '@logomarks/brand-kit';
+import { render } from '../raster/render.js';
+
+/** The mark laid over a recipe that has no icon of its own: centred, or top left when there's a title. */
+const overlay = (/** @type {string} */ mark, /** @type {boolean} */ titled, /** @type {string} */ color) => ({
+	type: 'icon',
+	svg: mark,
+	size: titled ? '14vmin' : '20vmin',
+	anchor: titled ? 'top-left' : 'center',
+	color,
+});
+
+/**
+ * The curated recipes: each one's covers options from the mark and the brand.
+ *
+ * @type {Record<string, import('./index.js').CoverRecipe>}
+ */
+export const RECIPES = {
+	mark: { about: 'The mark centred on the brand colour.', options: ({ mark }) => ({ recipe: 'mark', icon: mark }) },
+	gradient: { about: 'The mark on a gradient from the brand colour.', options: ({ mark }) => ({ recipe: 'mark', icon: mark, background: 'gradient' }) },
+	tile: { about: 'The mark on a raised tile over a soft tint, a glow and rings.', options: ({ mark }) => ({ recipe: 'iconTile', icon: mark }) },
+	stripes: { about: 'A band of tapering stripes and the mark on a disc at its edge.', options: ({ mark }) => ({ recipe: 'stripes', icon: mark }) },
+	aurora: { about: 'Soft sweeps of the brand’s hues, the mark over them.', options: (b) => ({ recipe: 'aurora', ...mesh(b) }) },
+	grid: { about: 'The same sweeps under a dotted grid.', options: (b) => ({ recipe: 'gridTitle', ...mesh(b) }) },
+	cutout: { about: 'A matte field, cut-paper shapes and the mark drawn by hand.', options: ({ mark }) => ({ recipe: 'cutout', icon: mark }) },
+};
+
+/**
+ * The mesh recipes' palette (the brand's own tints, so the sweeps stay in its hue) and the mark laid over them.
+ *
+ * @param {import('./index.js').CoverBrand} b The brand.
+ * @returns {object} The covers options.
+ */
+function mesh({ mark, color, titled }) {
+	const p = makePalette(color);
+	const palette = { accent: p.primary, colors: [p.primary, p.scale['300'], p.scale['700']] };
+	return { palette, mesh: { hueSpan: 60 }, layers: [overlay(mark, titled, titled ? resolvePalette(palette).text : '#FFFFFF')] };
+}
+
+/**
+ * A cover.
+ *
+ * @param {import('./index.js').CoverOptions} o The mark, the recipe, the words and the size.
+ * @returns {Promise<import('./index.js').Cover>} The PNG and the SVG.
+ * @throws {TypeError} For a recipe that isn't one of `RECIPES`.
+ */
+export async function cover({ mark, recipe = 'mark', title, label, color = DEFAULT_COLOR, aspect = 'og', width = 1200, seed }) {
+	const r = RECIPES[recipe];
+	if (!r) throw new TypeError(`no recipe "${recipe}": one of ${Object.keys(RECIPES).join(', ')}`);
+	const options = { palette: color, ...r.options({ mark: mark.svg, color, titled: Boolean(title) }) };
+	const svg = await renderSvg(/** @type {never} */ ({ seed: seed ?? mark.slug, aspect, width, ...(title && { title }), ...(label && { label }), ...options }));
+	const out = await render(svg, { png: true });
+	return { png: /** @type {Uint8Array} */ (out.png), svg, width: out.width, height: out.height };
+}

package/src/edit/combine.d.ts

@@ -0,0 +1,31 @@
+import type { Edited } from './doc.js';
+
+/** A way two marks combine. */
+export type CombineOp = 'union' | 'subtract' | 'intersect' | 'exclude' | 'place';
+
+/** Where the second mark goes, on the 512 canvas: scaled and turned about its centre, flipped, then moved. */
+export interface Placement {
+	/** A factor (1). */
+	scale?: number;
+	/** Degrees, clockwise (0). */
+	rotate?: number;
+	flip?: 'horizontal' | 'vertical';
+	/** Units across (0). */
+	x?: number;
+	/** Units down (0). */
+	y?: number;
+}
+
+/** How to combine. */
+export interface CombineOptions {
+	/** `union`, `subtract` (the second cut out of the first), `intersect`, `exclude`, or `place` (both, as they are). */
+	op: CombineOp;
+	transform?: Placement;
+	/** The result's name, for the checks. */
+	name?: string;
+}
+
+/** The ways two marks combine. */
+export const COMBINE_OPS: readonly CombineOp[];
+/** Two marks combined, fitted and checked; a RangeError for an unknown op, an Error when nothing is left. */
+export function combineMarks(a: string, b: string, o: CombineOptions): Edited;

package/src/edit/combine.js

@@ -0,0 +1,103 @@
+/**
+ * @module logomarks/edit/combine
+ *
+ * Two marks made one: the second placed over the first (scaled, turned,
+ * moved), then joined, cut, crossed or exclusive-ored with the editor's
+ * curve-keeping booleans, or simply placed.
+ */
+
+import { insertSvg, newParts, duplicateParts, deleteParts, booleanParts, scaleParts, rotateParts, flipParts, moveParts } from '@logomarks/editor/ops';
+import { parts } from '@logomarks/editor/model';
+import { toDoc, finish } from './doc.js';
+
+/** The ways two marks combine. */
+export const COMBINE_OPS = /** @type {const} */ (['union', 'subtract', 'intersect', 'exclude', 'place']);
+
+/** The ids of a document's parts. */
+const idsOf = (/** @type {import('@logomarks/editor').Doc} */ doc) => parts(doc).map((p) => p.id);
+
+/**
+ * Copies of some parts, in place.
+ *
+ * @param {import('@logomarks/editor').Doc} doc The document.
+ * @param {string[]} ids The parts.
+ * @returns {{ doc: import('@logomarks/editor').Doc, ids: string[] }} The document with them, and the copies' ids.
+ */
+function copy(doc, ids) {
+	const next = duplicateParts(doc, ids);
+	return { doc: next, ids: newParts(doc, next) };
+}
+
+/**
+ * Every `keep` part with every `cut` part taken out of it (a part is one
+ * boolean operand, so each takes fresh copies of the cutters); the cutters
+ * are left as they were.
+ *
+ * @param {import('@logomarks/editor').Doc} doc The document.
+ * @param {string[]} keep The parts to cut.
+ * @param {string[]} cut The parts to cut with.
+ * @returns {{ doc: import('@logomarks/editor').Doc, ids: string[] }} The document, and what is left of `keep`.
+ */
+function cutOut(doc, keep, cut) {
+	const left = [];
+	for (const id of keep) {
+		const c = copy(doc, cut);
+		const next = booleanParts(c.doc, 'subtract', [id, ...c.ids]);
+		left.push(...newParts(c.doc, next));
+		doc = next;
+	}
+	return { doc, ids: left };
+}
+
+/** Each boolean, from a document holding both marks' parts. @type {Record<string, (doc: import('@logomarks/editor').Doc, a: string[], b: string[]) => import('@logomarks/editor').Doc>} */
+const COMBINE = {
+	place: (doc) => doc,
+	union: (doc, a, b) => booleanParts(doc, 'union', [...a, ...b]),
+	subtract: (doc, a, b) => deleteParts(cutOut(doc, a, b).doc, b),
+	// A ∩ B = A − (A − B)
+	intersect: (doc, a, b) => {
+		const a2 = copy(doc, a);
+		const outside = cutOut(a2.doc, a2.ids, b);
+		return deleteParts(cutOut(outside.doc, a, outside.ids).doc, [...b, ...outside.ids]);
+	},
+	// (A − B) ∪ (B − A), each cut with copies of the other as it was
+	exclude: (doc, a, b) => {
+		const a2 = copy(doc, a), b2 = copy(a2.doc, b);
+		const left = cutOut(b2.doc, a, b2.ids);
+		return deleteParts(cutOut(left.doc, b, a2.ids).doc, [...a2.ids, ...b2.ids]);
+	},
+};
+
+/**
+ * The second mark placed: scaled and turned about its own centre, flipped, then moved.
+ *
+ * @param {import('@logomarks/editor').Doc} doc The document.
+ * @param {string[]} ids Its parts.
+ * @param {import('./combine.js').Placement} t How.
+ * @returns {import('@logomarks/editor').Doc} The document.
+ */
+function place(doc, ids, { scale = 1, rotate = 0, flip, x = 0, y = 0 } = {}) {
+	let d = scale === 1 ? doc : scaleParts(doc, ids, scale);
+	if (rotate) d = rotateParts(d, ids, rotate);
+	if (flip) d = flipParts(d, ids, flip);
+	return x || y ? moveParts(d, ids, x, y) : d;
+}
+
+/**
+ * Two marks combined.
+ *
+ * @param {string} a The first mark.
+ * @param {string} b The second, on the same 512 canvas.
+ * @param {import('./combine.js').CombineOptions} o The op and where the second goes.
+ * @returns {import('./doc.js').Edited} The SVG and the checks.
+ * @throws {RangeError} For an unknown op, or when nothing is left.
+ */
+export function combineMarks(a, b, { op, transform, name }) {
+	const run = COMBINE[op];
+	if (!run) throw new RangeError(`no op "${op}": one of ${COMBINE_OPS.join(', ')}`);
+	const doc = toDoc(a);
+	toDoc(b);
+	const both = insertSvg(doc, b);
+	const bIds = newParts(doc, both);
+	return finish(run(place(both, bIds, transform), idsOf(doc), bIds), name);
+}

package/src/edit/doc.d.ts

@@ -0,0 +1,34 @@
+import type { Doc } from '@logomarks/editor';
+import type { Report } from '../checks/index.js';
+
+/** One part of a mark, by index in drawing order. */
+export interface PartInfo {
+	/** What an op's `parts` names it by. */
+	index: number;
+	/** `[x0, y0, x1, y1]` on the 512 canvas. */
+	box: [number, number, number, number];
+	centre: [number, number];
+	/** Square units, holes taken out. */
+	area: number;
+	/** How many holes it has. */
+	holes: number;
+	/** 0 the mark's colour, 1 the second tone. */
+	tone: number;
+}
+
+/** An edited mark: fitted and checked. */
+export interface Edited {
+	/** 512 canvas, longest side 448, centred. */
+	svg: string;
+	/** The house checks on it. */
+	checks: Report;
+}
+
+/** A mark as an editable document; throws when it has no filled shapes. */
+export function toDoc(svg: string): Doc;
+/** Every part, by index in drawing order. */
+export function listParts(doc: Doc): PartInfo[];
+/** Part indices as ids (none: every part); a RangeError for one the mark doesn't have. */
+export function partIds(doc: Doc, indices: readonly number[] | undefined): string[];
+/** A result fitted (448 on 512, centred) and checked; throws when nothing is left. */
+export function finish(doc: Doc, name?: string): Edited;

package/src/edit/doc.js

@@ -0,0 +1,96 @@
+/**
+ * @module logomarks/edit/doc
+ *
+ * A mark as an editable document (`@logomarks/editor`'s model, no
+ * DOM), its parts listed by index, and a result finished the house way:
+ * fitted to 448 on the 512 canvas, centred, and checked (fit, specks,
+ * slivers, pin-holes, gaps).
+ */
+
+import { parseSvg, parts as partsOf, partBounds, ring } from '@logomarks/editor/model';
+import { exportSvg } from '@logomarks/editor/export';
+import { fitMark } from '@logomarks/core/fit';
+import { area } from '@logomarks/core/geometry';
+import { check } from '../checks/index.js';
+import { round } from '../util/round.js';
+
+/**
+ * A mark as a document.
+ *
+ * @param {string} svg The mark.
+ * @returns {import('@logomarks/editor').Doc} The document.
+ * @throws {Error} When it has no filled shapes.
+ */
+export function toDoc(svg) {
+	const doc = parseSvg(svg);
+	if (!partsOf(doc).length) throw new Error('the mark has no filled shapes');
+	return doc;
+}
+
+/**
+ * A contour's area.
+ *
+ * @param {import('@logomarks/editor').Contour} c The contour.
+ * @returns {number} Square units.
+ */
+const contourArea = (c) => area(ring(c).map((p) => [p.x, p.y]));
+
+/**
+ * Every part, by index in drawing order: what the ops' `parts` refer to.
+ *
+ * @param {import('@logomarks/editor').Doc} doc The document.
+ * @returns {import('./doc.js').PartInfo[]} The parts.
+ */
+export function listParts(doc) {
+	return partsOf(doc).map((p, index) => {
+		const [x0, y0, x1, y1] = partBounds(p);
+		return {
+			index,
+			box: [x0, y0, x1, y1].map((v) => round(v, 1)),
+			centre: [round((x0 + x1) / 2, 1), round((y0 + y1) / 2, 1)],
+			area: round(contourArea(p.outer) - p.holes.reduce((s, h) => s + contourArea(h), 0)),
+			holes: p.holes.length,
+			tone: p.outer.tone ?? 0,
+		};
+	});
+}
+
+/**
+ * Part indices as ids; none (or undefined) is every part.
+ *
+ * @param {import('@logomarks/editor').Doc} doc The document.
+ * @param {readonly number[] | undefined} indices The indices.
+ * @returns {string[]} The ids.
+ * @throws {RangeError} For an index the mark doesn't have.
+ */
+export function partIds(doc, indices) {
+	const all = partsOf(doc);
+	if (!indices?.length) return all.map((p) => p.id);
+	return indices.map((i) => {
+		if (!Number.isInteger(i) || !all[i]) throw new RangeError(`no part ${i}: the mark has ${all.length} (0–${all.length - 1}); list_parts shows them`);
+		return all[i].id;
+	});
+}
+
+/**
+ * Whether a document is coloured beyond `currentColor` (a second tone, or a fill).
+ *
+ * @param {import('@logomarks/editor').Doc} doc The document.
+ * @returns {boolean} True when it is.
+ */
+const coloured = (doc) => doc.fill !== 'currentColor' || partsOf(doc).some((p) => p.outer.tone);
+
+/**
+ * A result finished: fitted (448 on 512, centred, by marks-kit; a coloured
+ * one by the editor's own fit, which keeps its fills) and checked.
+ *
+ * @param {import('@logomarks/editor').Doc} doc The document.
+ * @param {string} [name] The mark's name, for the report.
+ * @returns {import('./doc.js').Edited} The SVG and the checks.
+ * @throws {Error} When nothing is left.
+ */
+export function finish(doc, name = 'mark') {
+	if (!partsOf(doc).length) throw new Error('nothing is left of the mark');
+	const svg = coloured(doc) ? exportSvg(doc, { fit: true, tones: 'var' }) : fitMark(exportSvg(doc)).svg;
+	return { svg, checks: check(svg, { name }) };
+}

package/src/edit/glitch.d.ts

@@ -0,0 +1,48 @@
+import type { Edited } from './doc.js';
+
+/** A glitch preset. */
+export type GlitchPreset = 'shear' | 'slice' | 'bands' | 'stepped' | 'lane';
+
+/** A glitch's settings. */
+export interface GlitchOptions {
+	preset: GlitchPreset;
+	/** The cut's direction in degrees, clockwise from across (the mark's own slope for a shear; across the lanes for a lane change; else 0). */
+	angle?: number;
+	/** Where the first cut crosses, 0–1 across the mark (seeded). */
+	place?: number;
+	/** How far the sides end up from each other along the cut (44); a band's largest nudge. */
+	slide?: number;
+	/** The gap at each cut (22). */
+	gap?: number;
+	/** Cuts for a slice (1–3), bands for bands (3–5); seeded. */
+	cuts?: number;
+	/** Places the cuts (1): the same seed gives the same bytes. */
+	seed?: number;
+	/** The mark's name, for the checks. */
+	name?: string;
+}
+
+/** A glitch edition. */
+export interface Glitched extends Edited {
+	glitch: {
+		preset: GlitchPreset;
+		seed: number;
+		/** The cut direction used. */
+		angle: number;
+		cuts: number;
+		pieces: number;
+		/** Placements tried before the one used. */
+		nudged: number;
+		/** Stray pieces dropped. */
+		removed: number;
+		/** A lane change's lane pitch, else null. */
+		pitch: number | null;
+	};
+}
+
+/** The presets by name, and the editor's own. */
+export const PRESETS: Readonly<Record<GlitchPreset, 'shear' | 'slice' | 'bandShift' | 'stepped' | 'laneChange'>>;
+/** What each preset does. */
+export const PRESET_ABOUT: Record<GlitchPreset, string>;
+/** A glitch edition, fitted and checked; a RangeError for an unknown preset or no clean cut. */
+export function glitchMark(svg: string, o: GlitchOptions): Glitched;

package/src/edit/glitch.js

@@ -0,0 +1,43 @@
+/**
+ * @module logomarks/edit/glitch
+ *
+ * A glitch edition of a mark in one step (`@logomarks/editor`'s
+ * `glitch`): cut with the house gap and the pieces slid, the cuts placed by
+ * a seed, so the same seed gives the same bytes.
+ */
+
+import { glitch, GLITCH_DEFAULTS } from '@logomarks/editor/ops';
+import { toDoc, finish } from './doc.js';
+
+/** The presets by the names the CLI and the tools use, and the editor's own. */
+export const PRESETS = /** @type {const} */ ({ shear: 'shear', slice: 'slice', bands: 'bandShift', stepped: 'stepped', lane: 'laneChange' });
+
+/** What each preset does. */
+export const PRESET_ABOUT = {
+	shear: 'one cut along the mark’s own slope, the sides slid apart',
+	slice: '1–3 parallel cuts, alternate bands slid',
+	bands: '3–5 bands across, each nudged by a seeded amount',
+	stepped: 'a stair-step cut, the sides slid apart',
+	lane: 'one cut across a Track mark’s lanes, one side slid one lane',
+};
+
+/**
+ * A glitch edition.
+ *
+ * @param {string} svg The mark.
+ * @param {import('./glitch.js').GlitchOptions} o The preset and its settings.
+ * @returns {import('./glitch.js').Glitched} The SVG, the checks, and what the glitch did.
+ * @throws {RangeError} For an unknown preset, or when no placement cuts the mark cleanly.
+ */
+export function glitchMark(svg, { preset, angle, place, slide, gap, cuts, seed = GLITCH_DEFAULTS.seed, name }) {
+	const kind = PRESETS[preset];
+	if (!kind) throw new RangeError(`no preset "${preset}": one of ${Object.keys(PRESETS).join(', ')}`);
+	// Unset settings may be undefined: vector-editor 0.2.2 and later keep its defaults for them.
+	const r = glitch(toDoc(svg), [], kind, { angle, position: place, offset: slide, gap, count: cuts, seed });
+	if (r.rejected) throw new RangeError(`no clean ${preset} for this mark at seed ${seed}: every placement left a speck or a sliver. Try another seed, angle or place.`);
+	if (!r.cuts.length) throw new RangeError(preset === 'lane' ? 'a lane change needs a Track mark (parallel lines with a gap); none was found' : `the ${preset} cut misses the mark: try another place or angle`);
+	return {
+		...finish(r.doc, name),
+		glitch: { preset, seed, angle: Math.round(r.angle * 10) / 10, cuts: r.cuts.length, pieces: r.pieces.length, nudged: r.nudged, removed: r.removed, pitch: r.pitch },
+	};
+}

package/src/edit/index.d.ts

@@ -0,0 +1,8 @@
+export { glitchMark, PRESETS, PRESET_ABOUT } from './glitch.js';
+export type { GlitchPreset, GlitchOptions, Glitched } from './glitch.js';
+export { editMark, markParts, OPS } from './ops.js';
+export type { EditOp, OpName, OpSpec, EditResult } from './ops.js';
+export { combineMarks, COMBINE_OPS } from './combine.js';
+export type { CombineOp, CombineOptions, Placement } from './combine.js';
+export type { Edited, PartInfo } from './doc.js';
+export { markPreview, partsPreview } from './preview.js';

package/src/edit/index.js

@@ -0,0 +1,11 @@
+/**
+ * @module logomarks/edit
+ *
+ * The editor's operations without the editor: glitch editions, a list of
+ * edits by part, and two marks combined, each fitted and checked.
+ */
+
+export { glitchMark, PRESETS, PRESET_ABOUT } from './glitch.js';
+export { editMark, markParts, OPS } from './ops.js';
+export { combineMarks, COMBINE_OPS } from './combine.js';
+export { markPreview, partsPreview } from './preview.js';

package/src/edit/ops.d.ts

@@ -0,0 +1,51 @@
+import type { Doc } from '@logomarks/editor';
+import type { Edited, PartInfo } from './doc.js';
+
+/** An op's name. */
+export type OpName = 'delete' | 'move' | 'rotate' | 'scale' | 'flip' | 'round' | 'offset' | 'mirror' | 'radial' | 'union' | 'subtract' | 'color' | 'tone';
+
+/** One op: its name, the parts it acts on, and its settings. */
+export interface EditOp {
+	op: OpName;
+	/** Part indices (from `markParts` / list_parts) at the time it runs; none: every part. */
+	parts?: number[];
+	/** move: units. */
+	dx?: number;
+	dy?: number;
+	/** rotate: degrees, clockwise. */
+	angle?: number;
+	/** scale: a factor, or `[sx, sy]`. */
+	by?: number | [number, number];
+	/** rotate, scale, flip: the centre to turn about (the parts' own centre). */
+	about?: [number, number];
+	/** flip: `horizontal` or `vertical`; mirror: `vertical` (left matches right), `horizontal` or `both`. */
+	axis?: 'horizontal' | 'vertical' | 'both';
+	/** round: the corner radius. */
+	radius?: number;
+	/** offset: grow (positive) or shrink (negative), in units. */
+	distance?: number;
+	/** offset: how corners turn (miter). */
+	join?: 'miter' | 'round';
+	/** radial: how many copies about the centre. */
+	count?: number;
+	/** color, tone: hex. */
+	color?: string;
+}
+
+/** An op's description and how it runs. */
+export interface OpSpec {
+	about: string;
+	run: (doc: Doc, ids: string[], op: EditOp) => Doc;
+}
+
+/** An edited mark, with its parts after. */
+export interface EditResult extends Edited {
+	parts: PartInfo[];
+}
+
+/** Every op, by name. */
+export const OPS: Record<OpName, OpSpec>;
+/** A mark edited by ops in order, fitted and checked; a RangeError naming the op that failed. */
+export function editMark(svg: string, ops: readonly EditOp[], o?: { name?: string }): EditResult;
+/** A mark's parts, by index. */
+export function markParts(svg: string): PartInfo[];

package/src/edit/ops.js

@@ -0,0 +1,90 @@
+/**
+ * @module logomarks/edit/ops
+ *
+ * `edit`: a short list of JSON ops run in order on a mark, each one of
+ * `@logomarks/editor`'s pure ops. `parts` are indices in drawing
+ * order as `listParts` gives them, at the time the op runs (a delete
+ * renumbers what follows); none means every part.
+ */
+
+import {
+	deleteParts, moveParts, rotateParts, scaleParts, flipParts, roundParts, offsetParts,
+	setSymmetry, bakeSymmetry, canvasCenter, setPartAttributes, booleanParts,
+} from '@logomarks/editor/ops';
+import { parseColor } from '../util/color.js';
+import { toDoc, partIds, listParts, finish } from './doc.js';
+
+/**
+ * A colour op's hex.
+ *
+ * @param {string} value The colour.
+ * @returns {string} `#RRGGBB`.
+ * @throws {RangeError} When it isn't one.
+ */
+function hex(value) {
+	const c = parseColor(value);
+	if (!c) throw new RangeError(`"${value}" isn't a hex colour`);
+	return c;
+}
+
+/** A centre as the editor takes it. */
+const at = (/** @type {[number, number] | undefined} */ p) => p && { x: p[0], y: p[1] };
+
+/**
+ * Each op: what it does, and how it runs on the document with its parts' ids.
+ *
+ * @type {Record<string, import('./ops.js').OpSpec>}
+ */
+export const OPS = {
+	delete: { about: 'remove parts', run: (doc, ids) => deleteParts(doc, ids) },
+	move: { about: 'move parts by dx, dy units', run: (doc, ids, o) => moveParts(doc, ids, o.dx ?? 0, o.dy ?? 0) },
+	rotate: { about: 'rotate parts by angle degrees, clockwise, about their centre (or about)', run: (doc, ids, o) => rotateParts(doc, ids, o.angle ?? 0, at(o.about)) },
+	scale: { about: 'scale parts by a factor (or [sx, sy]) about their centre (or about)', run: (doc, ids, o) => {
+		const [sx, sy] = Array.isArray(o.by) ? o.by : [o.by ?? 1, o.by ?? 1];
+		return scaleParts(doc, ids, sx, sy, at(o.about));
+	} },
+	flip: { about: 'flip parts horizontally (left to right) or vertically', run: (doc, ids, o) => flipParts(doc, ids, o.axis ?? 'horizontal', at(o.about)) },
+	round: { about: 'round every corner of the parts to radius units (0 takes rounds out)', run: (doc, ids, o) => roundParts(doc, ids, o.radius ?? 0) },
+	offset: { about: 'grow (positive distance) or shrink (negative) the parts; join miter or round', run: (doc, ids, o) => offsetParts(doc, ids, o.distance ?? 0, { join: o.join }) },
+	mirror: { about: 'mirror the whole mark across the centre: vertical (left matches right), horizontal or both; overlaps are unioned', run: (doc, _ids, o) => bakeSymmetry(setSymmetry(doc, { kind: 'mirror', axis: o.axis ?? 'vertical', center: canvasCenter(doc) })) },
+	radial: { about: 'repeat the whole mark count times about the centre', run: (doc, _ids, o) => bakeSymmetry(setSymmetry(doc, { kind: 'radial', count: o.count ?? 4, center: canvasCenter(doc) })) },
+	union: { about: 'join the parts into one', run: (doc, ids) => booleanParts(doc, 'union', ids) },
+	subtract: { about: 'cut the other parts out of the first', run: (doc, ids) => booleanParts(doc, 'subtract', ids) },
+	color: { about: 'paint the whole mark in color (it is currentColor otherwise)', run: (doc, _ids, o) => ({ ...doc, fill: hex(o.color ?? '') }) },
+	tone: { about: 'paint the parts in a second colour: two-tone (written as var(--tone-2, color))', run: (doc, ids, o) => ({ ...setPartAttributes(doc, ids, { tone: 1 }), tones: [doc.fill, hex(o.color ?? '')] }) },
+};
+
+/** The ops that act on the whole mark, so take no `parts`. */
+const WHOLE = new Set(['mirror', 'radial', 'color']);
+
+/**
+ * A mark edited by a list of ops.
+ *
+ * @param {string} svg The mark.
+ * @param {readonly import('./ops.js').EditOp[]} ops The ops, in order.
+ * @param {{ name?: string }} [o] The mark's name, for the checks.
+ * @returns {import('./ops.js').EditResult} The SVG, the checks, and its parts after.
+ * @throws {RangeError} For an unknown op or a part the mark doesn't have (naming the op by its place).
+ */
+export function editMark(svg, ops, { name } = {}) {
+	let doc = toDoc(svg);
+	ops.forEach((op, i) => {
+		const spec = OPS[op.op];
+		try {
+			if (!spec) throw new RangeError(`no op "${op.op}": one of ${Object.keys(OPS).join(', ')}`);
+			doc = spec.run(doc, WHOLE.has(op.op) ? [] : partIds(doc, op.parts), op);
+		} catch (e) {
+			throw new RangeError(`op ${i} (${op.op}): ${/** @type {Error} */ (e).message}`);
+		}
+	});
+	const done = finish(doc, name);
+	return { ...done, parts: listParts(toDoc(done.svg)) };
+}
+
+/**
+ * A mark's parts, by index: what an op's `parts` refer to.
+ *
+ * @param {string} svg The mark.
+ * @returns {import('./doc.js').PartInfo[]} The parts.
+ */
+export const markParts = (svg) => listParts(toDoc(svg));

package/src/edit/preview.d.ts

@@ -0,0 +1,8 @@
+import type { PartInfo } from './doc.js';
+
+/** The preview's side in pixels: 512. */
+export const PREVIEW_SIZE: number;
+/** The mark on white, in its own colours (two tones drawn as their colours). */
+export function markPreview(svg: string): Promise<Uint8Array>;
+/** The mark in grey with each part's box and index. */
+export function partsPreview(svg: string, parts: readonly PartInfo[]): Promise<Uint8Array>;