logomarks 0.0.0-stage → 1.0.0

package/src/sheet/grid.js

@@ -0,0 +1,32 @@
+/**
+ * @module logomarks/sheet/grid
+ *
+ * A plain contact sheet: marks in a grid, light on dark, each labelled with
+ * its name (what batchsheet.mjs and peek.mjs drew), for a quick look at a
+ * whole batch before the full review cards.
+ */
+
+import { render } from '../raster/render.js';
+import { text, panel, mark } from './draw.js';
+import { COLORS } from './theme.js';
+
+/** A cell's width and height, in pixels. */
+const W = 190, H = 220;
+
+/**
+ * The marks in a labelled grid, `cols` across.
+ *
+ * @param {readonly { name: string, svg: string }[]} marks The marks.
+ * @param {{ cols?: number }} [o] How many across (8).
+ * @returns {Promise<Uint8Array>} The sheet as a PNG.
+ */
+export async function gridSheet(marks, { cols = 8 } = {}) {
+	const across = Math.max(1, Math.min(cols, marks.length)), rows = Math.ceil(marks.length / across);
+	const cells = marks.map((m, i) => {
+		const x = (i % across) * W, y = Math.floor(i / across) * H;
+		return panel(x + 6, y + 6, W - 12, H - 12, COLORS.card, { r: 12 }) + mark(m.svg, x + 30, y + 22, W - 60, COLORS.darkInk) + text(x + W / 2, y + H - 24, m.name, { size: 13, color: COLORS.text, anchor: 'middle' });
+	});
+	const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${across * W}" height="${rows * H}"><rect width="100%" height="100%" fill="${COLORS.page}"/>${cells.join('')}</svg>`;
+	const { png } = await render(svg, { text: true, png: true });
+	return /** @type {Uint8Array} */ (png);
+}

package/src/sheet/index.d.ts

@@ -0,0 +1,31 @@
+import type { Report } from '../checks/index.js';
+import type { Match } from '../similar/nearest.js';
+import type { MarkIndex } from '../similar/store.js';
+
+/** A mark for the sheet. */
+export interface SheetMark {
+	/** Its name, usually its file's slug. */
+	name: string;
+	svg: string;
+}
+
+/** How to check the marks. */
+export interface SheetOptions {
+	/** The live marks (the bundled index). */
+	index?: MarkIndex;
+	/** Warnings fail a mark too (false). */
+	strict?: boolean;
+	/** Finding ids to leave out. */
+	ignore?: string[];
+}
+
+/** A rendered sheet. */
+export interface Sheet {
+	png: Uint8Array;
+	svg: string;
+	/** Each mark's check and nearest live marks (itself left out). */
+	marks: { name: string; report: Report; matches: Match[] }[];
+}
+
+/** Review cards for a set of marks, rendered to one PNG. */
+export function sheet(marks: readonly SheetMark[], o?: SheetOptions): Promise<Sheet>;

package/src/sheet/index.js

@@ -0,0 +1,47 @@
+/**
+ * @module logomarks/sheet
+ *
+ * `sheet`: review cards for a set of marks, one under another, rendered to a
+ * PNG for an AI (or a person) to look at.
+ */
+
+import { check } from '../checks/index.js';
+import { similar } from '../similar/nearest.js';
+import { loadIndex } from '../similar/store.js';
+import { render } from '../raster/render.js';
+import { COLORS, CARD } from './theme.js';
+import { card } from './card.js';
+import { text } from './draw.js';
+
+/** The page's margin and the space between cards. */
+const MARGIN = 16;
+
+/** The title strip's height. */
+const TITLE = 44;
+
+/**
+ * A review sheet.
+ *
+ * @param {readonly import('./index.js').SheetMark[]} marks The marks, each with its name.
+ * @param {import('./index.js').SheetOptions} [o] Checks and neighbours.
+ * @returns {Promise<import('./index.js').Sheet>} The sheet as PNG and SVG, and each mark's report and neighbours.
+ */
+export async function sheet(marks, { index = loadIndex(), strict = false, ignore = [] } = {}) {
+	/** @type {import('./index.js').Sheet['marks']} */
+	const results = [];
+	let y = MARGIN + TITLE, cards = '';
+	for (const { name, svg } of marks) {
+		const report = check(svg, { name, strict, ignore });
+		const matches = report.size ? await similar(svg, { top: 3, index, exclude: name }) : [];
+		const c = await card({ name, svg, report, matches, index }, y);
+		cards += `<g transform="translate(${MARGIN} 0)">${c.svg}</g>`;
+		y += c.height + MARGIN;
+		results.push({ name, report, matches });
+	}
+	const width = CARD.width + 2 * MARGIN;
+	const failed = results.filter((r) => !r.report.ok).length;
+	const title = text(MARGIN + 4, MARGIN + 24, `Logomarks review · ${marks.length} mark${marks.length === 1 ? '' : 's'} · ${failed ? `${failed} failing` : 'all passing'} · live set of ${index.marks.length} (${index.built})`, { size: 14, color: COLORS.muted });
+	const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${y}" viewBox="0 0 ${width} ${y}"><rect width="${width}" height="${y}" fill="${COLORS.page}"/>${title}${cards}</svg>`;
+	const png = /** @type {Uint8Array} */ ((await render(svg, { text: true, png: true })).png);
+	return { png, svg, marks: results };
+}

package/src/sheet/theme.d.ts

@@ -0,0 +1,8 @@
+/** The sheet's colours. */
+export const COLORS: Readonly<Record<'page' | 'card' | 'line' | 'text' | 'muted' | 'dark' | 'darkInk' | 'light' | 'lightInk' | 'error' | 'warning' | 'info' | 'pass', string>>;
+/** The sheet's typeface (bundled). */
+export const FONT: string;
+/** Card geometry in pixels. */
+export const CARD: Readonly<{ width: number; pad: number; gap: number; head: number; large: number; chips: number; neighbour: number; badge: number }>;
+/** How much each chip size is magnified beside its actual size. */
+export const ZOOM: Readonly<Record<32 | 16, number>>;

package/src/sheet/theme.js

@@ -0,0 +1,45 @@
+/**
+ * @module logomarks/sheet/theme
+ *
+ * The review sheet's colours, type and sizes, in one place.
+ */
+
+/** Colours: a dark page, the two grounds a mark is judged on, and the verdict colours. */
+export const COLORS = {
+	page: '#0c0c0c',
+	card: '#171717',
+	line: '#2a2a2a',
+	text: '#f2f2f2',
+	muted: '#8c8c8c',
+	dark: '#000000',
+	darkInk: '#f4f4f2',
+	light: '#f4f4f2',
+	lightInk: '#111111',
+	error: '#ff5c64',
+	warning: '#f5b941',
+	info: '#8c8c8c',
+	pass: '#5cffc0',
+};
+
+/** The typeface (bundled). */
+export const FONT = 'IBM Plex Mono';
+
+/** Card geometry in pixels. */
+export const CARD = {
+	width: 1400,
+	pad: 24,
+	gap: 16,
+	/** The header row. */
+	head: 56,
+	/** The large views' side. */
+	large: 300,
+	/** The chips column's width. */
+	chips: 236,
+	/** A neighbour tile's side. */
+	neighbour: 140,
+	/** A badge's height. */
+	badge: 28,
+};
+
+/** How much each chip is magnified beside its actual size, so its pixels can be seen. */
+export const ZOOM = { 32: 3, 16: 4 };

package/src/similar/folder.d.ts

@@ -0,0 +1,20 @@
+import type { MarkIndex } from './store.js';
+
+/** What indexOf() takes. */
+export interface FolderOptions {
+	/** Letter signatures too (false). */
+	letters?: boolean;
+	/** Names and tags by slug (from a marks.json). */
+	about?: Record<string, { name: string; tags: string[] }>;
+	/** The files are candidates: every one's holes are compared, and each match says so. */
+	candidate?: boolean;
+}
+
+/** A badge's slug (any family). */
+export function isBadge(slug: string): boolean;
+/** An index of SVG files. */
+export function indexOf(files: readonly string[], o?: FolderOptions): Promise<MarkIndex>;
+/** An index of every SVG in a folder, named from the marks.json beside it. */
+export function folderIndex(dir: string, o?: { letters?: boolean }): Promise<MarkIndex>;
+/** Two indexes as one. */
+export function joinIndexes(a: MarkIndex, b: MarkIndex): MarkIndex;

package/src/similar/folder.js

@@ -0,0 +1,66 @@
+/**
+ * @module logomarks/similar/folder
+ *
+ * An index built on the spot, for comparing against marks that aren't in the
+ * bundled one: a folder of SVGs (the site's svg folder while a batch is
+ * drawn), or the candidates themselves (each against the others). Names, tags
+ * come from a `marks.json` beside the folder when there is one; the letter
+ * signatures cover badges (their holes) and letter and number marks (their ink),
+ * as the bundled index does.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { outlineSignature, letterSignatures } from './signature.js';
+import { slugOf } from '../util/files.js';
+
+/** A badge, whose letter is its holes (every family: Badge, Pixel Badge, Stencil Badge …). */
+export const isBadge = (/** @type {string} */ slug) => /(^|-)badge-/.test(slug);
+
+/**
+ * An index of SVG files.
+ *
+ * @param {readonly string[]} files The marks' files.
+ * @param {import('./folder.js').FolderOptions} [o] Letter signatures too, names and tags by slug, and a tag for each.
+ * @returns {Promise<import('./store.js').MarkIndex>} The index (its marks carry only slug, name, svg and outline).
+ */
+export async function indexOf(files, { letters = false, about = {}, candidate = false } = {}) {
+	/** @type {import('./store.js').MarkIndex} */
+	const index = { built: new Date().toISOString().slice(0, 10), marks: [], letters: [] };
+	for (const file of files) {
+		const svg = fs.readFileSync(file, 'utf8');
+		const slug = slugOf(file), a = about[slug];
+		const i = index.marks.push(/** @type {import('./store.js').IndexedMark} */ ({ slug, name: a?.name ?? slug, svg, outline: await outlineSignature(svg), ...(candidate && { candidate: true }), ...(a && { tags: a.tags }) })) - 1;
+		if (!letters) continue;
+		const lettery = candidate || a?.tags.includes('letter') || a?.tags.includes('number');
+		if (!isBadge(slug) && !lettery) continue;
+		const { holes, ink } = await letterSignatures(svg);
+		if ((isBadge(slug) || candidate) && holes) index.letters.push({ mark: i, kind: 'hole', sig: holes });
+		else if (lettery && !candidate) index.letters.push({ mark: i, kind: 'ink', sig: ink });
+	}
+	return index;
+}
+
+/**
+ * An index of every SVG in a folder, named from the `marks.json` beside it when there is one.
+ *
+ * @param {string} dir The folder.
+ * @param {{ letters?: boolean }} [o] Letter signatures too.
+ * @returns {Promise<import('./store.js').MarkIndex>} The index.
+ */
+export async function folderIndex(dir, { letters = false } = {}) {
+	const files = fs.readdirSync(dir).filter((f) => f.endsWith('.svg')).sort().map((f) => path.join(dir, f));
+	const list = path.join(dir, '..', 'marks.json');
+	/** @type {Record<string, { name: string, tags: string[] }>} */
+	const about = fs.existsSync(list) ? Object.fromEntries(JSON.parse(fs.readFileSync(list, 'utf8')).map((/** @type {{ slug: string, name: string, tags: string[] }} */ m) => [m.slug, m])) : {};
+	return indexOf(files, { letters, about });
+}
+
+/**
+ * Two indexes as one (the second's letters renumbered).
+ *
+ * @param {import('./store.js').MarkIndex} a The first.
+ * @param {import('./store.js').MarkIndex} b The second.
+ * @returns {import('./store.js').MarkIndex} Both.
+ */
+export const joinIndexes = (a, b) => ({ built: a.built, marks: [...a.marks, ...b.marks], letters: [...a.letters, ...b.letters.map((l) => ({ ...l, mark: l.mark + a.marks.length }))] });

package/src/similar/nearest.d.ts

@@ -0,0 +1,32 @@
+import type { MarkIndex } from './store.js';
+
+/** How close a live mark is: `near-copy` (0.9+ by outline), `too-close` (0.72+), or `ok`. */
+export type Verdict = 'near-copy' | 'too-close' | 'ok';
+
+/** A live mark near the candidate. */
+export interface Match {
+	slug: string;
+	name: string;
+	/** Overlap, 0–1, the best of 8 rotations and flips. */
+	score: number;
+	verdict: Verdict;
+	/** What was compared: the outline, or a badge's knocked-out letter against a badge's hole or a letter mark's ink. */
+	by: 'outline' | 'letter (hole)' | 'letter (ink)';
+	/** Another candidate, not a live mark (`similar --each`). */
+	candidate?: true;
+}
+
+/** What to compare. */
+export interface SimilarOptions {
+	/** How many to return (5). */
+	top?: number;
+	/** Compare the candidate's knocked-out letter (its holes) instead of its outline (false). */
+	letters?: boolean;
+	/** The live marks (the bundled index). */
+	index?: MarkIndex;
+	/** A slug to leave out (the candidate itself). */
+	exclude?: string;
+}
+
+/** The live marks nearest a candidate, closest first. With `letters`, an empty list when it has no holes. */
+export function similar(svg: string, o?: SimilarOptions): Promise<Match[]>;

package/src/similar/nearest.js

@@ -0,0 +1,60 @@
+/**
+ * @module logomarks/similar/nearest
+ *
+ * The live marks nearest a candidate, by outline (dupcheck.mjs) or, for a
+ * letter badge, by its knocked-out letter (holecheck.mjs).
+ */
+
+import { SIMILAR, LETTERS } from '../rules.js';
+import { outlineSignature, letterSignatures, variants, iou } from './signature.js';
+import { loadIndex } from './store.js';
+
+/**
+ * How close a score is.
+ *
+ * @param {number} score The score.
+ * @param {{ tooClose: number, nearCopy: number }} t The thresholds.
+ * @returns {import('./nearest.js').Verdict} The verdict.
+ */
+const verdict = (score, t) => (score >= t.nearCopy ? 'near-copy' : score >= t.tooClose ? 'too-close' : 'ok');
+
+/**
+ * The best score of a candidate's 8 variants against one stored signature.
+ *
+ * @param {Float32Array[]} vs The candidate's variants.
+ * @param {Float32Array} sig The stored signature.
+ * @returns {number} The score.
+ */
+const best = (vs, sig) => vs.reduce((m, v) => Math.max(m, iou(v, sig)), 0);
+
+/**
+ * The live marks nearest a candidate.
+ *
+ * @param {string} svg The candidate.
+ * @param {import('./nearest.js').SimilarOptions} [o] How many, and what to compare.
+ * @returns {Promise<import('./nearest.js').Match[]>} The nearest, closest first.
+ */
+export async function similar(svg, { top = 5, letters = false, index = loadIndex(), exclude } = {}) {
+	/** @type {import('./nearest.js').Match[]} */
+	let out;
+	if (letters) {
+		const { holes } = await letterSignatures(svg);
+		if (!holes) return [];
+		const vs = variants(holes);
+		out = index.letters.map((l) => {
+			const m = index.marks[l.mark], score = best(vs, l.sig);
+			return { slug: m.slug, name: m.name, score, verdict: verdict(score, LETTERS), by: l.kind === 'hole' ? 'letter (hole)' : 'letter (ink)', ...(m.candidate && { candidate: true }) };
+		});
+	} else {
+		const vs = variants(await outlineSignature(svg));
+		out = index.marks.map((m) => {
+			const score = best(vs, m.outline);
+			return { slug: m.slug, name: m.name, score, verdict: verdict(score, SIMILAR), by: 'outline', ...(m.candidate && { candidate: true }) };
+		});
+	}
+	return out
+		.filter((m) => m.slug !== exclude)
+		.sort((a, b) => b.score - a.score)
+		.slice(0, top)
+		.map((m) => ({ ...m, score: Math.round(m.score * 1000) / 1000 }));
+}

package/src/similar/signature.d.ts

@@ -0,0 +1,12 @@
+/** A 3×3 box blur of a square image of side `N`, averaging only pixels inside it. */
+export function blur(a: Float32Array, N: number): Float32Array;
+/** A mark's 48 px coverage (0–1), before the blur: what the index stores. */
+export function outlineCoverage(svg: string): Promise<Float32Array>;
+/** A mark's outline signature: 48 px coverage, blurred 3×3. */
+export function outlineSignature(svg: string): Promise<Float32Array>;
+/** A mark's holes (null when it has none) and its ink, each cropped to its box at 40 px. */
+export function letterSignatures(svg: string): Promise<{ holes: Float32Array | null; ink: Float32Array }>;
+/** A square image in all 8 rotations and flips. */
+export function variants(a: Float32Array): Float32Array[];
+/** Overlap (IoU) of two images: the sum of minima over the sum of maxima. */
+export function iou(a: ArrayLike<number>, b: ArrayLike<number>): number;

package/src/similar/signature.js

@@ -0,0 +1,42 @@
+/**
+ * @module logomarks/similar/signature
+ *
+ * What two marks are compared by (dupcheck.mjs and holecheck.mjs), rendered with
+ * the CLI's renderer and measured by @logomarks/core: the outline (48 px,
+ * blurred 3×3) and the letter (a badge's holes or a letter mark's ink, cropped
+ * to 40 px), both compared by overlap (IoU) in all 8 rotations and flips.
+ */
+
+import { blur, variants, iou, outlineSignature as signatureOf, letterSignatures as lettersOf } from '@logomarks/core/similar';
+import { SIMILAR, LETTERS } from '../rules.js';
+import { coverage } from '../raster/render.js';
+
+export { blur, variants, iou };
+
+/**
+ * A mark's coverage at the signature's size (48 px), before the blur: what the index stores.
+ *
+ * @param {string} svg The mark.
+ * @returns {Promise<Float32Array>} Coverage 0–1.
+ */
+export const outlineCoverage = (svg) => coverage(svg, SIMILAR.size);
+
+/**
+ * A mark's outline signature: 48 px, blurred.
+ *
+ * @param {string} svg The mark.
+ * @returns {Promise<Float32Array>} The signature.
+ */
+export async function outlineSignature(svg) {
+	return signatureOf(await outlineCoverage(svg), SIMILAR.size);
+}
+
+/**
+ * A mark's letter signatures: its holes (null when it has none) and its ink, cropped to 40 px.
+ *
+ * @param {string} svg The mark.
+ * @returns {Promise<import('./signature.js').LetterSignatures>} The signatures.
+ */
+export async function letterSignatures(svg) {
+	return lettersOf(await coverage(svg, LETTERS.render), LETTERS.render, LETTERS.size);
+}

package/src/similar/store.d.ts

@@ -0,0 +1,67 @@
+import type { Packed } from '@arraypress/search';
+
+/** What a live mark is: what `findMarks` searches. */
+export interface MarkAbout {
+	/** Shape tags: round, square, letter, number, symmetric, radial, solid, light, wide, tall, new. */
+	tags: string[];
+	/** The board it is in (bold, archive, geometric, grid). */
+	collection: string;
+	/** Its family's style (letter, badge, iso, line, grid, glitch, animal …). */
+	style: string;
+	/** Its mood words (minimal, technical, calm, premium …). */
+	mood: string[];
+	/** The letter or number it shows, for letter marks. */
+	letter?: string;
+	/** What it looks like, in a sentence. */
+	description: string;
+	/** The kinds of business it suits, best fit first (may be empty). */
+	industries: string[];
+}
+
+/** A live mark in the index. */
+export interface IndexedMark extends MarkAbout {
+	slug: string;
+	name: string;
+	/** The mark's SVG. */
+	svg: string;
+	/** Its outline signature: 48 px coverage, blurred. */
+	outline: Float32Array;
+	/** A candidate compared alongside (`similar --each`), not a live mark. */
+	candidate?: true;
+}
+
+/** A letter signature: a badge's holes or a letter mark's ink. */
+export interface IndexedLetter {
+	/** The mark's position in `marks`. */
+	mark: number;
+	kind: 'hole' | 'ink';
+	/** The signature, 40 px, values 0–1. */
+	sig: Float32Array;
+}
+
+/** The live marks and their signatures. */
+export interface MarkIndex {
+	/** When it was built (YYYY-MM-DD). */
+	built: string;
+	marks: IndexedMark[];
+	letters: IndexedLetter[];
+	/** The board's search over `marks`, in the same order (a packed @arraypress/search index); only the bundled index has it. */
+	search?: Packed;
+}
+
+/** What an index is written from. */
+export interface IndexInput {
+	marks: ({ slug: string; name: string; svg: string } & MarkAbout)[];
+	/** One 48 px coverage per mark (values 0–1), before the blur. */
+	coverages: ArrayLike<number>[];
+	letters: { mark: number; kind: 'hole' | 'ink'; sig: ArrayLike<number> }[];
+	/** The board's search over `marks`, packed. */
+	search: Packed;
+}
+
+/** Where the bundled index lives. */
+export const INDEX_FILE: URL;
+/** Writes an index (brotli) and returns its size in bytes. */
+export function writeIndex(input: IndexInput, file?: string | URL): number;
+/** Reads an index, once per file. Throws when it is missing or from another version. */
+export function loadIndex(file?: string | URL): MarkIndex;

package/src/similar/store.js

@@ -0,0 +1,88 @@
+/**
+ * @module logomarks/similar/store
+ *
+ * The bundled index of live marks: each mark's slug, name and SVG, what it is
+ * (tags, collection, style, mood, letter, description, industries: what
+ * `findMarks` searches), its 48 px coverage (the outline signature before its
+ * blur), and for badges and letter marks a letter signature, and the board's search over them (a packed
+ * @arraypress/search index: `findMarks`). One brotli-compressed file, built by
+ * `npm run index` from the Logomarks data, so `similar` and `sheet` work
+ * offline. Layout: a 4-byte JSON length, the JSON (marks and letters), then
+ * the signature bytes.
+ */
+
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+import { SIMILAR, LETTERS } from '../rules.js';
+import { blur } from './signature.js';
+
+/** Where the bundled index lives. */
+export const INDEX_FILE = new URL('../../data/index.bin', import.meta.url);
+
+/** The file format's version. */
+const VERSION = 3;
+
+/** Letter signatures are quarters (2×2 supersampling): stored ×4. */
+const QUARTERS = 4;
+
+/** @type {Map<string, import('./store.js').MarkIndex>} */
+const cache = new Map();
+
+/**
+ * Writes an index.
+ *
+ * @param {import('./store.js').IndexInput} input The marks and their signatures.
+ * @param {string | URL} [file] Where (the bundled index).
+ * @returns {number} The file's size in bytes.
+ */
+export function writeIndex({ marks, coverages, letters, search }, file = INDEX_FILE) {
+	const head = Buffer.from(JSON.stringify({
+		version: VERSION,
+		built: new Date().toISOString().slice(0, 10),
+		size: SIMILAR.size,
+		letterSize: LETTERS.size,
+		marks: marks.map(({ slug, name, svg, ...about }) => [slug, name, svg, about]),
+		letters: letters.map((l) => [l.mark, l.kind]),
+		search,
+	}));
+	const length = Buffer.alloc(4);
+	length.writeUInt32LE(head.length);
+	const bytes = (/** @type {ArrayLike<number>} */ a, /** @type {number} */ k) => Uint8Array.from(a, (v) => Math.round(v * k));
+	const body = Buffer.concat([length, head, ...coverages.map((c) => bytes(c, 255)), ...letters.map((l) => bytes(l.sig, QUARTERS))]);
+	const out = zlib.brotliCompressSync(body, { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 11 } });
+	fs.writeFileSync(file, out);
+	return out.length;
+}
+
+/**
+ * Reads an index (once per file) and blurs its coverages into outline signatures.
+ *
+ * @param {string | URL} [file] Which (the bundled index).
+ * @returns {import('./store.js').MarkIndex} The index.
+ * @throws {Error} When the file is missing or from another version.
+ */
+export function loadIndex(file = INDEX_FILE) {
+	const key = String(file);
+	const hit = cache.get(key);
+	if (hit) return hit;
+	const body = zlib.brotliDecompressSync(fs.readFileSync(file));
+	const n = body.readUInt32LE(0);
+	const raw = JSON.parse(body.toString('utf8', 4, 4 + n));
+	if (raw.version !== VERSION) throw new Error(`index version ${raw.version}, expected ${VERSION}: run npm run index`);
+	const S = raw.size * raw.size, L = raw.letterSize * raw.letterSize;
+	let at = 4 + n;
+	const take = (/** @type {number} */ len, /** @type {number} */ k) => {
+		const a = Float32Array.from(body.subarray(at, at + len), (v) => v / k);
+		at += len;
+		return a;
+	};
+	/** @type {import('./store.js').MarkIndex} */
+	const index = {
+		built: raw.built,
+		marks: raw.marks.map((/** @type {[string, string, string, import('./store.js').MarkAbout]} */ [slug, name, svg, about]) => ({ slug, name, svg, ...about, outline: blur(take(S, 255), raw.size) })),
+		letters: raw.letters.map((/** @type {[number, 'hole' | 'ink']} */ [mark, kind]) => ({ mark, kind, sig: take(L, QUARTERS) })),
+		search: raw.search,
+	};
+	cache.set(key, index);
+	return index;
+}

package/src/util/color.d.ts

@@ -0,0 +1,2 @@
+/** A typed colour (`#rgb`, `#rrggbb`, `black`, `white`) as `#RRGGBB`; null when it isn't one. */
+export function parseColor(input: string): string | null;

package/src/util/color.js

@@ -0,0 +1,23 @@
+/**
+ * @module logomarks/util/color
+ *
+ * Reading a colour someone typed: `#rgb`, `#rrggbb` (the `#` optional), or
+ * `black` and `white`. Everything else about colour is
+ * `@arraypress/color-utils` and `@logomarks/brand-kit`'s palette.
+ */
+
+/**
+ * A colour as `#RRGGBB`.
+ *
+ * @param {string} input The colour.
+ * @returns {string | null} It, upper case; null when it isn't one.
+ */
+export function parseColor(input) {
+	const s = input.trim().toLowerCase();
+	if (s === 'black') return '#000000';
+	if (s === 'white') return '#FFFFFF';
+	const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/.exec(s);
+	if (!m) return null;
+	const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1];
+	return `#${h.toUpperCase()}`;
+}

package/src/util/files.d.ts

@@ -0,0 +1,8 @@
+/** Every SVG named, folders expanded (sorted, not recursive); throws when a path is missing. */
+export function expandSvgs(paths: readonly string[]): string[];
+/** A mark's name from its file: the slug. */
+export function slugOf(file: string): string;
+/** Writes a file, making its folder. */
+export function writeFile(file: string, data: string | Uint8Array): void;
+/** Writes files by path under a folder; returns how many. */
+export function writeFiles(dir: string, files: Iterable<[string, string | Uint8Array]>): number;

package/src/util/files.js

@@ -0,0 +1,60 @@
+/**
+ * @module logomarks/util/files
+ *
+ * Files in and out: the SVGs a list of paths names (folders expanded), a
+ * mark's name from its file, and writing a file (or a map of them) with
+ * their folders made.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Every SVG named, folders expanded (sorted, not recursive).
+ *
+ * @param {readonly string[]} paths Files and folders.
+ * @returns {string[]} The files, as given (or joined to their folder).
+ * @throws {Error} When a path is missing.
+ */
+export function expandSvgs(paths) {
+	return paths.flatMap((p) => {
+		if (!fs.existsSync(p)) throw new Error(`no such file: ${p}`);
+		if (!fs.statSync(p).isDirectory()) return [p];
+		return fs.readdirSync(p).filter((f) => f.endsWith('.svg')).sort().map((f) => path.join(p, f));
+	});
+}
+
+/**
+ * A mark's name from its file: the slug.
+ *
+ * @param {string} file The file.
+ * @returns {string} Its name without the folder and `.svg`.
+ */
+export const slugOf = (file) => path.basename(file).replace(/\.svg$/i, '');
+
+/**
+ * Writes a file, making its folder.
+ *
+ * @param {string} file Where.
+ * @param {string | Uint8Array} data What.
+ */
+export function writeFile(file, data) {
+	fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+	fs.writeFileSync(file, data);
+}
+
+/**
+ * Writes files by path under a folder.
+ *
+ * @param {string} dir The folder.
+ * @param {Iterable<[string, string | Uint8Array]>} files Each file's path in it and its data.
+ * @returns {number} How many.
+ */
+export function writeFiles(dir, files) {
+	let n = 0;
+	for (const [p, data] of files) {
+		writeFile(path.join(dir, p), data);
+		n++;
+	}
+	return n;
+}

package/src/util/round.d.ts

@@ -0,0 +1,2 @@
+/** A number rounded to `places` decimal places (2), for SVG. */
+export function round(v: number, places?: number): number;