logomarks 0.0.0-stage → 1.1.0

package/src/brand/fonts.d.ts

@@ -0,0 +1,61 @@
+/** A bundled typeface. */
+export interface Font {
+	/** Its name (`Inter`). */
+	name: string;
+	/** The face's family, as an SVG names it with `weight` (`Inter SemiBold`, `IBM Plex Mono`). */
+	family: string;
+	/** The one weight bundled. */
+	weight: number;
+	/** Its file in `data/fonts/`. */
+	file: string;
+	/** Letter-spacing for a name, in em. */
+	tracking: number;
+	/** Its name on Google Fonts, where to get the other weights. */
+	google: string;
+}
+
+/** The typefaces a brand's name can be set in (all SIL OFL 1.1). */
+export const FONTS: {
+	readonly inter: Font;
+	readonly 'space-grotesk': Font;
+	readonly 'instrument-sans': Font;
+	readonly 'bricolage-grotesque': Font;
+	readonly 'instrument-serif': Font;
+	readonly fraunces: Font;
+	readonly cagliostro: Font;
+	readonly limelight: Font;
+	readonly shrikhand: Font;
+	readonly 'plex-mono': Font;
+};
+
+/** A typeface's id. */
+export type FontId = keyof typeof FONTS;
+
+/** The name's typeface when none is asked for: `inter`. */
+export const DEFAULT_FONT: FontId;
+/** The labels' family, IBM Plex Mono (regular and semibold, by weight). */
+export const LABEL_FONT: string;
+/** A file bundled whole, as published: where it comes from, and its sha256. */
+export interface Upstream {
+	url: string;
+	sha256: string;
+}
+/** The files bundled whole (the faces with a Reserved Font Name), by file. */
+export const UPSTREAM: Readonly<Record<string, Upstream>>;
+/** Every bundled font file. */
+export function fontFiles(): URL[];
+/** A typeface by id or name, any case; null when it isn't bundled. */
+export function fontId(name: string): FontId | null;
+
+/** A bundled face as `@logomarks/brand-kit` takes it. */
+export interface BrandFont {
+	name: string;
+	/** The TrueType file's bytes. */
+	data: Uint8Array;
+	weight: number;
+	/** Letter-spacing for a name, in em. */
+	tracking: number;
+}
+
+/** A bundled face as `@logomarks/brand-kit` takes it: name, bytes (read once), weight and tracking. */
+export function brandFont(id?: FontId): BrandFont;

package/src/brand/fonts.js

@@ -0,0 +1,93 @@
+/**
+ * @module logomarks/brand/fonts
+ *
+ * The bundled typefaces, all SIL Open Font License, as plain TrueType (resvg
+ * reads it) in `data/fonts/` (`scripts/fonts.js` writes them): Fontsource's
+ * latin subsets, except the faces with a Reserved Font Name, bundled whole
+ * (see {@link UPSTREAM}). IBM Plex Mono sets the sheets' labels; the rest set
+ * a brand's name. Four are for restaurants: Fraunces (a warm serif: bistros,
+ * wine bars), Cagliostro (a flared sans, set wide), Limelight (art deco) and
+ * Shrikhand (retro chunky: diners, brunch, ice cream).
+ * Each file is one face. An SVG names it by `family` and `weight`: most files
+ * are a family of their own (`Inter SemiBold`), but Plex Mono's two share
+ * `IBM Plex Mono`, so the weight picks the semibold. `brandFont()` hands a face
+ * to `@logomarks/brand-kit` as bytes, with its name and weight.
+ */
+
+import fs from 'node:fs';
+
+/** The typefaces a brand's name can be set in, by id. */
+export const FONTS = {
+	inter: { name: 'Inter', family: 'Inter SemiBold', weight: 600, file: 'Inter-SemiBold.ttf', tracking: -0.02, google: 'Inter' },
+	'space-grotesk': { name: 'Space Grotesk', family: 'Space Grotesk SemiBold', weight: 600, file: 'SpaceGrotesk-SemiBold.ttf', tracking: -0.02, google: 'Space Grotesk' },
+	'instrument-sans': { name: 'Instrument Sans', family: 'Instrument Sans SemiBold', weight: 600, file: 'InstrumentSans-SemiBold.ttf', tracking: -0.015, google: 'Instrument Sans' },
+	'bricolage-grotesque': { name: 'Bricolage Grotesque', family: 'Bricolage Grotesque SemiBold', weight: 600, file: 'BricolageGrotesque-SemiBold.ttf', tracking: -0.02, google: 'Bricolage Grotesque' },
+	'instrument-serif': { name: 'Instrument Serif', family: 'Instrument Serif', weight: 400, file: 'InstrumentSerif-Regular.ttf', tracking: -0.01, google: 'Instrument Serif' },
+	fraunces: { name: 'Fraunces', family: 'Fraunces SemiBold', weight: 600, file: 'Fraunces-SemiBold.ttf', tracking: -0.02, google: 'Fraunces' },
+	cagliostro: { name: 'Cagliostro', family: 'Cagliostro', weight: 400, file: 'Cagliostro-Regular.ttf', tracking: 0.3, google: 'Cagliostro' },
+	limelight: { name: 'Limelight', family: 'Limelight', weight: 400, file: 'Limelight-Regular.ttf', tracking: 0.06, google: 'Limelight' },
+	shrikhand: { name: 'Shrikhand', family: 'Shrikhand', weight: 400, file: 'Shrikhand-Regular.ttf', tracking: 0, google: 'Shrikhand' },
+	'plex-mono': { name: 'IBM Plex Mono', family: 'IBM Plex Mono', weight: 600, file: 'IBMPlexMono-SemiBold.ttf', tracking: -0.02, google: 'IBM Plex Mono' },
+};
+
+/** The name's typeface when none is asked for. */
+export const DEFAULT_FONT = 'inter';
+
+/** The labels' family (the review sheet and the brand sheet), regular and semibold by weight. */
+export const LABEL_FONT = 'IBM Plex Mono';
+
+/** google/fonts at one commit, where the whole files come from. */
+const GOOGLE_FONTS = 'https://raw.githubusercontent.com/google/fonts/24ddc1f324cac5d9f5aedca126d298f56e3f1640/ofl';
+
+/**
+ * The files bundled whole, byte for byte as published, by file: the faces
+ * with a Reserved Font Name, which the OFL lets no Modified Version (a subset
+ * is one) carry. `scripts/fonts.js` fetches each and checks its sha256, and
+ * its licence comes from the `OFL.txt` beside it. (The studio's webfonts are
+ * Fontsource's subsets, the usual web-font distribution; this is about the
+ * files the package ships.)
+ */
+export const UPSTREAM = {
+	'Cagliostro-Regular.ttf': { url: `${GOOGLE_FONTS}/cagliostro/Cagliostro-Regular.ttf`, sha256: '0d205e9a9b34691dca50064ea681404157f1747e39b592fce978b2a32bd5fb61' },
+	'Limelight-Regular.ttf': { url: `${GOOGLE_FONTS}/limelight/Limelight-Regular.ttf`, sha256: 'f5bf8a9159adfc5b9c756c85d812a4fd1299b8916fefdf39ad4b24ade6d8d0cf' },
+	'IBMPlexMono-SemiBold.ttf': { url: `${GOOGLE_FONTS}/ibmplexmono/IBMPlexMono-SemiBold.ttf`, sha256: 'd3c38e55c78f5b0f28009fddba4834ec503278936a5986032424c9bd2d23aa46' },
+	'IBMPlexMono-Regular.ttf': { url: `${GOOGLE_FONTS}/ibmplexmono/IBMPlexMono-Regular.ttf`, sha256: '6a3412f058c7d8dfd9170c41e85ade48e5156ecb89356110ca57a0a27734af46' },
+};
+
+/** Every bundled file: the brand faces and Plex Mono's regular, for labels. */
+const FILES = [...new Set([...Object.values(FONTS).map((f) => f.file), 'IBMPlexMono-Regular.ttf'])];
+
+/**
+ * Where every bundled font file is.
+ *
+ * @returns {URL[]} The files.
+ */
+export const fontFiles = () => FILES.map((f) => new URL(`../../data/fonts/${f}`, import.meta.url));
+
+/**
+ * A typeface by id or name, any case (`space-grotesk`, `Space Grotesk`).
+ *
+ * @param {string} name The id or name.
+ * @returns {import('./fonts.js').FontId | null} Its id, or null when it isn't bundled.
+ */
+export function fontId(name) {
+	const key = name.trim().toLowerCase().replace(/\s+/g, '-');
+	if (key in FONTS) return /** @type {import('./fonts.js').FontId} */ (key);
+	const hit = Object.entries(FONTS).find(([, f]) => f.name.toLowerCase().replace(/\s+/g, '-') === key);
+	return hit ? /** @type {import('./fonts.js').FontId} */ (hit[0]) : null;
+}
+
+/** @type {Map<string, Uint8Array>} */
+const bytes = new Map();
+
+/**
+ * A bundled face as `@logomarks/brand-kit` takes it: its name, its bytes (read once), its weight and tracking.
+ *
+ * @param {import('./fonts.js').FontId} [id] The face (inter).
+ * @returns {import('./fonts.js').BrandFont} The font.
+ */
+export function brandFont(id = DEFAULT_FONT) {
+	const f = FONTS[id];
+	if (!bytes.has(f.file)) bytes.set(f.file, new Uint8Array(fs.readFileSync(new URL(`../../data/fonts/${f.file}`, import.meta.url))));
+	return { name: f.name, data: /** @type {Uint8Array} */ (bytes.get(f.file)), weight: f.weight, tracking: f.tracking };
+}

package/src/brand/mark.d.ts

@@ -0,0 +1,53 @@
+import type { MarkIndex, IndexedMark } from '../similar/store.js';
+
+/** A mark to build on. */
+export interface Mark {
+	slug: string;
+	name: string;
+	/** The SVG: 512 canvas, filled paths in `currentColor`. */
+	svg: string;
+	/** Whether it is a live Logomark (CC0) rather than a file. */
+	live: boolean;
+}
+
+/** How to draw a mark on a square. */
+export interface TileOptions {
+	/** The side in pixels. */
+	size: number;
+	/** The mark's colour. */
+	color: string;
+	/** A ground behind it (transparent otherwise). */
+	ground?: string;
+	/** Space round the 512 canvas, as a fraction of it (0). */
+	pad?: number;
+	/** The ground's corner radius, as a fraction of its side (0). */
+	radius?: number;
+}
+
+/** Where a live mark's page is: this and its slug. */
+export const MARK_URL: string;
+
+/** A mark that wasn't found; `suggestions` holds the closest slugs. */
+export class MarkNotFound extends Error {
+	constructor(ref: string, suggestions: string[]);
+	suggestions: string[];
+}
+
+/** Text as a slug. */
+export function slugify(s: string): string;
+/** A slug as a name. */
+export function titleCase(slug: string): string;
+/** A live mark by slug or name, any case. */
+export function findMark(ref: string, index?: MarkIndex): IndexedMark | undefined;
+/** The live slugs closest to a query. */
+export function suggest(ref: string, index?: MarkIndex, n?: number): string[];
+/** A live mark by slug or name, or an SVG file fitted to the standard. Throws `MarkNotFound`. */
+export function loadMark(ref: string, index?: MarkIndex): Mark;
+/** The mark's paths in a colour, in a `<g>`, without the `<svg>`. */
+export function markBody(svg: string, color: string): string;
+/** The mark as a file, the fill on the root (`currentColor` by default). */
+export function paint(svg: string, color?: string): string;
+/** The mark on a square (transparent, or on a ground with rounded corners), as SVG. */
+export function tile(svg: string, o: TileOptions): string;
+/** The mark drawn to a square PNG. */
+export function markPng(svg: string, o: TileOptions): Promise<Uint8Array>;

package/src/brand/mark.js

@@ -0,0 +1,151 @@
+/**
+ * @module logomarks/brand/mark
+ *
+ * The mark a brand is built on: a live mark by slug or name (from the
+ * bundled index), or your own SVG, fitted to the standard. Painted in a
+ * colour and drawn at a size.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadIndex } from '../similar/store.js';
+import { fitMark } from '@logomarks/core/fit';
+import { body } from '@logomarks/core/svg';
+import { render } from '../raster/render.js';
+import { CANVAS } from '../rules.js';
+import { round } from '../util/round.js';
+
+/** Where a live mark's page is. */
+export const MARK_URL = 'https://logomarks.ai/marks/';
+
+/** A mark that wasn't found, with the closest slugs. */
+export class MarkNotFound extends Error {
+	/**
+	 * @param {string} ref What was asked for.
+	 * @param {string[]} suggestions The closest slugs.
+	 */
+	constructor(ref, suggestions) {
+		super(`no live mark "${ref}"${suggestions.length ? `: did you mean ${suggestions.join(', ')}?` : ''}`);
+		this.suggestions = suggestions;
+	}
+}
+
+/**
+ * Text as a slug: lower case, words joined by hyphens.
+ *
+ * @param {string} s The text.
+ * @returns {string} The slug.
+ */
+export const slugify = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+/**
+ * A slug as a name: `hex-gem` → `Hex Gem`.
+ *
+ * @param {string} slug The slug.
+ * @returns {string} The name.
+ */
+export const titleCase = (slug) => slug.split('-').filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+
+/**
+ * A live mark by slug or name, any case.
+ *
+ * @param {string} ref The slug (`hex-gem`) or name (`Hex Gem`).
+ * @param {import('../similar/store.js').MarkIndex} [index] The live set (the bundled index).
+ * @returns {import('../similar/store.js').IndexedMark | undefined} The mark.
+ */
+export function findMark(ref, index = loadIndex()) {
+	const slug = slugify(ref);
+	return index.marks.find((m) => m.slug === ref) ?? index.marks.find((m) => m.slug === slug || slugify(m.name) === slug);
+}
+
+/**
+ * The live slugs closest to a query: the most of its words (all of it, run together, counts
+ * double), then the shortest.
+ *
+ * @param {string} ref The query.
+ * @param {import('../similar/store.js').MarkIndex} [index] The live set.
+ * @param {number} [n] How many.
+ * @returns {string[]} The slugs.
+ */
+export function suggest(ref, index = loadIndex(), n = 3) {
+	const words = slugify(ref).split('-').filter(Boolean);
+	const joined = words.join('');
+	return index.marks
+		.map((m) => ({ slug: m.slug, score: words.filter((w) => m.slug.includes(w)).length + (m.slug.replace(/-/g, '').includes(joined) ? 2 : 0) }))
+		.filter((m) => m.score > 0)
+		.sort((a, b) => b.score - a.score || a.slug.length - b.slug.length || a.slug.localeCompare(b.slug))
+		.slice(0, n)
+		.map((m) => m.slug);
+}
+
+/**
+ * A mark from a slug, a name or an SVG file. A file is fitted to the
+ * standard (512 canvas, longest side 448, centred, `currentColor`).
+ *
+ * @param {string} ref A live slug or name, or a path to an SVG.
+ * @param {import('../similar/store.js').MarkIndex} [index] The live set.
+ * @returns {import('./mark.js').Mark} The mark.
+ * @throws {MarkNotFound} When it is neither a file nor a live mark.
+ */
+export function loadMark(ref, index) {
+	if (/\.svg$/i.test(ref) || fs.existsSync(ref)) {
+		const slug = slugify(path.basename(ref).replace(/\.svg$/i, '')) || 'mark';
+		return { slug, name: titleCase(slug), svg: fitMark(fs.readFileSync(ref, 'utf8')).svg, live: false };
+	}
+	const all = index ?? loadIndex();
+	const m = findMark(ref, all);
+	if (!m) throw new MarkNotFound(ref, suggest(ref, all));
+	return { slug: m.slug, name: m.name, svg: m.svg, live: true };
+}
+
+/**
+ * The mark's paths, any `currentColor` in them made a colour.
+ *
+ * @param {string} svg The mark.
+ * @param {string} color The colour.
+ * @returns {string} The paths.
+ */
+const paths = (svg, color) => body(svg).replace(/fill="currentColor"/g, `fill="${color}"`);
+
+/**
+ * The mark's drawing in a colour, in a group, without its `<svg>`: to place in another SVG.
+ *
+ * @param {string} svg The mark.
+ * @param {string} color The fill (`currentColor` keeps it).
+ * @returns {string} Its paths.
+ */
+export const markBody = (svg, color) => `<g fill="${color}">${paths(svg, color)}</g>`;
+
+/**
+ * The mark as a file in a colour (`currentColor` leaves it to the page).
+ *
+ * @param {string} svg The mark.
+ * @param {string} [color] The fill.
+ * @returns {string} The SVG, 512 canvas, the fill on the root.
+ */
+export const paint = (svg, color = 'currentColor') =>
+	`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${CANVAS} ${CANVAS}" fill="${color}">${paths(svg, color)}</svg>\n`;
+
+/**
+ * The mark on a square, transparent or on a ground: the SVG to draw.
+ *
+ * @param {string} svg The mark.
+ * @param {import('./mark.js').TileOptions} o Size and colours.
+ * @returns {string} The SVG.
+ */
+export function tile(svg, { size, color, ground, pad = 0, radius = 0 }) {
+	const at = round(-pad * CANVAS), side = round(CANVAS * (1 + 2 * pad));
+	const bg = ground ? `<rect x="${at}" y="${at}" width="${side}" height="${side}" rx="${round(radius * side)}" fill="${ground}"/>` : '';
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="${at} ${at} ${side} ${side}">${bg}${markBody(svg, color)}</svg>\n`;
+}
+
+/**
+ * The mark drawn to a square PNG, transparent or on a ground.
+ *
+ * @param {string} svg The mark.
+ * @param {import('./mark.js').TileOptions} o Size and colours.
+ * @returns {Promise<Uint8Array>} The PNG.
+ */
+export async function markPng(svg, o) {
+	return /** @type {Uint8Array} */ ((await render(tile(svg, o), { png: true })).png);
+}

package/src/checks/finding.d.ts

@@ -0,0 +1,56 @@
+import type { Box, Point } from '@logomarks/core/geometry';
+
+/** How much a finding matters: errors fail the check; warnings fail it with `--strict`; notes never do. */
+export type Severity = 'error' | 'warning' | 'info';
+
+/** Every finding a check can report. */
+export type FindingId =
+	| 'empty'
+	| 'viewbox'
+	| 'size'
+	| 'centre'
+	| 'clipped'
+	| 'markup'
+	| 'fill'
+	| 'precision'
+	| 'speck'
+	| 'sliver'
+	| 'pinhole'
+	| 'thin'
+	| 'narrow-gap'
+	| 'uneven-gaps'
+	| 'raster-read';
+
+/** What a finding id means. */
+export interface FindingKind {
+	/** Its usual severity. */
+	severity: Severity;
+	/** Whether `--fix` repairs it. */
+	fixable: boolean;
+	/** How to fix it. */
+	fix: string;
+}
+
+/** One thing a check found. */
+export interface Finding {
+	id: FindingId;
+	severity: Severity;
+	/** A plain-English sentence. */
+	message: string;
+	/** Where, as a box on the 512 canvas: `[x0, y0, x1, y1]`. */
+	box?: Box;
+	/** Where, as a point on the canvas. */
+	point?: Point;
+	/** The measured number (an area in square units, a width in units). */
+	value?: number;
+	/** Whether `--fix` repairs it. */
+	fixable: boolean;
+	/** How to fix it. */
+	fix: string;
+}
+
+/** Every finding id and what it means. */
+export const FINDINGS: Readonly<Record<FindingId, FindingKind>>;
+
+/** A finding, its location rounded to one decimal. */
+export function finding(id: FindingId, message: string, o?: { box?: Box; point?: Point; value?: number; severity?: Severity }): Finding;

package/src/checks/finding.js

@@ -0,0 +1,57 @@
+/**
+ * @module logomarks/checks/finding
+ *
+ * The findings a check can report, by id, and a constructor that rounds
+ * locations for output. Ids are stable: an AI can act on them.
+ */
+
+/**
+ * Every finding id: its usual severity, whether `--fix` repairs it, and how
+ * to fix it by hand.
+ *
+ * @type {Record<import('./finding.js').FindingId, import('./finding.js').FindingKind>}
+ */
+export const FINDINGS = {
+	empty: { severity: 'error', fixable: false, fix: 'Draw the mark as filled <path> elements.' },
+	viewbox: { severity: 'error', fixable: true, fix: 'Use viewBox="0 0 512 512" (--fix refits).' },
+	size: { severity: 'error', fixable: true, fix: 'Scale so the longest side is exactly 448 (--fix refits).' },
+	centre: { severity: 'error', fixable: true, fix: 'Centre the outline on (256, 256) (--fix refits).' },
+	clipped: { severity: 'error', fixable: true, fix: 'Part of the outline is outside 0–512 and is cut off (--fix refits).' },
+	markup: { severity: 'error', fixable: false, fix: 'Flatten to filled paths: expand strokes, apply transforms, drop groups, styles, masks, text and images.' },
+	fill: { severity: 'warning', fixable: true, fix: 'Fill with currentColor only; holes are real holes, never a painted background (--fix refits).' },
+	precision: { severity: 'warning', fixable: true, fix: 'Round coordinates to one decimal place (--fix refits).' },
+	speck: { severity: 'error', fixable: false, fix: 'A stray piece a boolean left behind: render it large, and remove it if it is not meant.' },
+	sliver: { severity: 'error', fixable: false, fix: 'A thin leftover piece along a cut: remove it, or grow the cut with a true offset.' },
+	pinhole: { severity: 'error', fixable: false, fix: 'A tiny hole an overlap left: union the overlapping parts, or remove the hole if it is not meant.' },
+	thin: { severity: 'warning', fixable: false, fix: 'Thicken it to at least 10 units, or remove it: it vanishes at 32 px.' },
+	'narrow-gap': { severity: 'warning', fixable: false, fix: 'Open the gap to at least 10 units (the house gap is 22): it closes up at 32 px.' },
+	'uneven-gaps': { severity: 'warning', fixable: false, fix: 'Use one gap width throughout (22), or a clear 1:2 ratio.' },
+	'raster-read': { severity: 'info', fixable: false, fix: 'The vector booleans could not read this mark; small parts were found on a raster, which can miss a speck touching the outline.' },
+};
+
+/**
+ * A finding, with its location rounded to one decimal.
+ *
+ * @param {import('./finding.js').FindingId} id What was found.
+ * @param {string} message A plain-English sentence.
+ * @param {object} [o] Where and how much.
+ * @param {import('@logomarks/core/geometry').Box} [o.box] Where, as a box on the canvas.
+ * @param {import('@logomarks/core/geometry').Point} [o.point] Where, as a point.
+ * @param {number} [o.value] The measured number (an area, a width).
+ * @param {import('./finding.js').Severity} [o.severity] Overrides the usual severity.
+ * @returns {import('./finding.js').Finding} The finding.
+ */
+export function finding(id, message, { box, point, value, severity } = {}) {
+	const r = (/** @type {number} */ v) => Math.round(v * 10) / 10;
+	const kind = FINDINGS[id];
+	return {
+		id,
+		severity: severity ?? kind.severity,
+		message,
+		...(box && { box: /** @type {import('@logomarks/core/geometry').Box} */ (box.map(r)) }),
+		...(point && { point: /** @type {import('@logomarks/core/geometry').Point} */ (point.map(r)) }),
+		...(value !== undefined && { value: r(value) }),
+		fixable: kind.fixable,
+		fix: kind.fix,
+	};
+}

package/src/checks/fit.d.ts

@@ -0,0 +1,5 @@
+import type { Bounds, FilledPath } from '@logomarks/core/svg';
+import type { Finding } from './finding.js';
+
+/** The standard's findings: viewBox, size, centre, clipping, markup, fill colour and precision. */
+export function fitFindings(svg: string, b: Bounds, paths: readonly FilledPath[]): Finding[];

package/src/checks/fit.js

@@ -0,0 +1,46 @@
+/**
+ * @module logomarks/checks/fit
+ *
+ * The standard: the canvas, the fit (longest side 448, centred), nothing
+ * outside the canvas, filled paths only, `currentColor`, one decimal. From
+ * `fit.mjs --check` and `clipcheck.mjs` (measured on the sampled curve, so
+ * control points outside the canvas are not false alarms).
+ */
+
+import { CANVAS, FIT, CENTRE, FIT_TOLERANCE, DECIMALS, FORBIDDEN_MARKUP } from '../rules.js';
+import { viewBox, attr } from '@logomarks/core/svg';
+import { finding } from './finding.js';
+
+const f1 = (/** @type {number} */ v) => v.toFixed(1);
+
+/**
+ * Fit findings for one mark.
+ *
+ * @param {string} svg The file's text.
+ * @param {import('@logomarks/core/svg').Bounds} b Its real outline's box.
+ * @param {readonly import('@logomarks/core/svg').FilledPath[]} paths Its shapes.
+ * @returns {import('./finding.js').Finding[]} What is off.
+ */
+export function fitFindings(svg, b, paths) {
+	const out = [];
+	const vb = viewBox(svg);
+	const box = /** @type {import('@logomarks/core/geometry').Box} */ ([b.x, b.y, b.x + b.w, b.y + b.h]);
+	if (!vb || vb.join(' ') !== `0 0 ${CANVAS} ${CANVAS}`) out.push(finding('viewbox', `The viewBox is "${vb?.join(' ') ?? 'missing'}", not "0 0 ${CANVAS} ${CANVAS}".`));
+	const long = Math.max(b.w, b.h);
+	if (Math.abs(long - FIT) > FIT_TOLERANCE) out.push(finding('size', `The longest side is ${f1(long)}, not ${FIT}.`, { box, value: long }));
+	const cx = b.x + b.w / 2, cy = b.y + b.h / 2;
+	if (Math.abs(cx - CENTRE) > FIT_TOLERANCE || Math.abs(cy - CENTRE) > FIT_TOLERANCE) {
+		out.push(finding('centre', `The outline is centred on (${f1(cx)}, ${f1(cy)}), not (${CENTRE}, ${CENTRE}).`, { point: [cx, cy] }));
+	}
+	if (b.x < -FIT_TOLERANCE || b.y < -FIT_TOLERANCE || b.x + b.w > CANVAS + FIT_TOLERANCE || b.y + b.h > CANVAS + FIT_TOLERANCE) {
+		out.push(finding('clipped', `The outline runs outside the ${CANVAS} canvas, so the viewBox cuts it off.`, { box }));
+	}
+	const markup = FORBIDDEN_MARKUP.exec(svg);
+	if (markup) out.push(finding('markup', `It contains \`${markup[0]}\`: a finished mark is filled paths only.`));
+	const fills = new Set([...svg.matchAll(/<(?:path|circle|ellipse|rect|polygon|svg)\b[^>]*>/g)].map((m) => attr(m[0], 'fill')).filter((v) => v && v !== 'none' && v !== 'currentColor'));
+	if (fills.size) out.push(finding('fill', `It is filled with ${[...fills].join(', ')}, not currentColor.`));
+	else if (!/fill="currentColor"/.test(svg)) out.push(finding('fill', 'Nothing sets fill="currentColor", so it renders black whatever the text colour.'));
+	const long2 = paths.map((p) => p.d).join(' ').match(new RegExp(`\\d\\.\\d{${DECIMALS + 1},}`, 'g'));
+	if (long2) out.push(finding('precision', `${long2.length} coordinate${long2.length > 1 ? 's have' : ' has'} more than ${DECIMALS} decimal place (e.g. ${long2[0]}).`, { value: long2.length }));
+	return out;
+}

package/src/checks/index.d.ts

@@ -0,0 +1,33 @@
+import type { Finding } from './finding.js';
+
+export type { Finding, FindingId, Severity } from './finding.js';
+export { FINDINGS } from './finding.js';
+
+/** What to check. */
+export interface CheckOptions {
+	/** The mark's name, usually its file's slug: seeds the booleans and finds reviewed live marks ('mark'). */
+	name?: string;
+	/** Finding ids to leave out, e.g. `['speck']` for a mark whose small parts are meant. */
+	ignore?: string[];
+	/** Warnings fail the check too (false). */
+	strict?: boolean;
+}
+
+/** One mark's check. */
+export interface Report {
+	name: string;
+	/** No errors (and, with `strict`, no warnings). */
+	ok: boolean;
+	errors: number;
+	warnings: number;
+	notes: number;
+	/** The outline's size, or null when there is nothing drawn. */
+	size: { w: number; h: number } | null;
+	/** Most serious first. */
+	findings: Finding[];
+}
+
+/** Checks one mark against the house rules. */
+export function check(svg: string, o?: CheckOptions): Report;
+/** The mark refitted to the grid, or null when there is nothing safe to fix (no fit findings, or markup a refit would drop). */
+export function fix(svg: string, report?: Report): string | null;

package/src/checks/index.js

@@ -0,0 +1,57 @@
+/**
+ * @module logomarks/checks
+ *
+ * `check`: every house rule a mark can be measured against, as findings
+ * with ids, severities, plain-English messages and locations. `fix`: the
+ * one safe repair, refitting to the grid.
+ */
+
+import { shapes, bounds } from '@logomarks/core/svg';
+import { fitMark } from '@logomarks/core/fit';
+import { finding } from './finding.js';
+import { fitFindings } from './fit.js';
+import { speckFindings } from './specks.js';
+import { widthFindings } from './widths.js';
+
+/** Severities, most serious first, for sorting. */
+const RANK = { error: 0, warning: 1, info: 2 };
+
+/**
+ * Checks one mark.
+ *
+ * @param {string} svg The file's text.
+ * @param {import('./index.js').CheckOptions} [o] Its name, and what to leave out.
+ * @returns {import('./index.js').Report} The findings, most serious first.
+ */
+export function check(svg, { name = 'mark', ignore = [], strict = false } = {}) {
+	const paths = shapes(svg);
+	/** @type {import('./finding.js').Finding[]} */
+	let findings;
+	/** @type {import('./index.js').Report['size']} */
+	let size = null;
+	if (!paths.length) findings = [finding('empty', 'There are no filled shapes to check.')];
+	else {
+		const b = bounds(paths);
+		size = { w: Math.round(b.w * 10) / 10, h: Math.round(b.h * 10) / 10 };
+		findings = [...fitFindings(svg, b, paths), ...speckFindings(paths, name), ...widthFindings(paths)];
+	}
+	findings = findings.filter((f) => !ignore.includes(f.id)).sort((a, b) => RANK[a.severity] - RANK[b.severity]);
+	const count = (/** @type {import('./finding.js').Severity} */ s) => findings.filter((f) => f.severity === s).length;
+	const errors = count('error'), warnings = count('warning');
+	return { name, ok: errors === 0 && (!strict || warnings === 0), errors, warnings, notes: count('info'), size, findings };
+}
+
+/**
+ * Refits a mark when that is all it needs: the fit findings (size, centre,
+ * clipping, viewBox, fill, precision) are repaired by `fitMark()`; a mark with
+ * groups, transforms or strokes is left alone, since the refit would drop them.
+ *
+ * @param {string} svg The file's text.
+ * @param {import('./index.js').Report} [report] Its report (checked here when not given).
+ * @returns {string | null} The fitted file, or null when there is nothing safe to fix.
+ */
+export function fix(svg, report = check(svg)) {
+	if (report.findings.some((f) => f.id === 'markup' || f.id === 'empty')) return null;
+	if (!report.findings.some((f) => f.fixable)) return null;
+	return fitMark(svg).svg;
+}

package/src/checks/specks.d.ts

@@ -0,0 +1,5 @@
+import type { FilledPath } from '@logomarks/core/svg';
+import type { Finding } from './finding.js';
+
+/** Specks, slivers and pin-holes, smallest first; `name` (the slug) seeds the jitter and finds reviewed marks. */
+export function speckFindings(paths: readonly FilledPath[], name: string): Finding[];

package/src/checks/specks.js

@@ -0,0 +1,38 @@
+/**
+ * @module logomarks/checks/specks
+ *
+ * Stray specks, slivers and pin-holes a boolean left behind (speckcheck.mjs).
+ * The mark is read as vectors (its filled area, by booleans); when the
+ * booleans can't read it, as a scanline raster at 8 px a unit. Small parts
+ * are reported unless they are tiny (two outlines touching), hairline
+ * (invisible) or repeated (a dot field). A reviewed live mark's findings come
+ * back as notes.
+ */
+
+import { SPECKS, REVIEWED } from '../rules.js';
+import { markParts, smallParts } from '@logomarks/core/analyse';
+import { finding } from './finding.js';
+
+/**
+ * A mark's specks, slivers and pin-holes, smallest first.
+ *
+ * @param {readonly import('@logomarks/core/svg').FilledPath[]} paths The mark's shapes.
+ * @param {string} name The mark's name (its slug: seeds the booleans' jitter, and finds a reviewed mark).
+ * @returns {import('./finding.js').Finding[]} Specks, slivers and pin-holes, smallest first.
+ */
+export function speckFindings(paths, name) {
+	/** @type {import('./finding.js').Finding[]} */
+	const out = [];
+	const read = markParts(paths, { seed: name });
+	if (read.raster) out.push(finding('raster-read', 'The booleans could not read this mark, so small parts were found on a raster (which can miss a speck touching the outline).'));
+	const reviewed = REVIEWED[/** @type {keyof typeof REVIEWED} */ (name)];
+	for (const p of smallParts(read.parts, { piece: SPECKS.piece, hole: SPECKS.hole, raster: read.raster })) {
+		if (p.skip) continue;
+		const o = { box: p.box, value: p.area, ...(reviewed && { severity: /** @type {const} */ ('info') }) };
+		const note = reviewed ? ` Reviewed and kept: ${reviewed}.` : '';
+		if (p.kind === 'hole') out.push(finding('pinhole', `A pin-hole of ${p.area.toFixed(1)} sq units.${note}`, o));
+		else if (p.width < SPECKS.sliver) out.push(finding('sliver', `A sliver ${p.width.toFixed(2)} wide (${p.area.toFixed(1)} sq units).${note}`, o));
+		else out.push(finding('speck', `A stray piece of ${p.area.toFixed(1)} sq units.${note}`, o));
+	}
+	return out;
+}