mimeforge 0.0.0-stage → 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+export interface Config {
+    out?: string;
+    font?: string;
+    body?: string;
+    /** Accent per category (`pdf`) or extension (`.docx`). */
+    colors?: Record<string, string>;
+    accent?: string;
+    labelCase?: 'upper' | 'lower' | 'none';
+    /** false = bodies only. */
+    label?: boolean;
+    /** Raster sizes for `--png`. */
+    png?: number[];
+}
+export declare const CONFIG_FILE = "mimeforge.config.json";
+/**
+ * Load a config file (`path`, or `./mimeforge.config.json` when it exists). Relative `out`, `font` and `body`
+ * paths are resolved against the config file's directory.
+ */
+export declare function loadConfig(path?: string): {
+    file: string;
+    config: Config;
+} | undefined;

package/dist/config.js

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+export const CONFIG_FILE = 'mimeforge.config.json';
+/**
+ * Load a config file (`path`, or `./mimeforge.config.json` when it exists). Relative `out`, `font` and `body`
+ * paths are resolved against the config file's directory.
+ */
+export function loadConfig(path) {
+    const file = path ? resolve(path) : resolve(CONFIG_FILE);
+    if (!existsSync(file)) {
+        if (path)
+            throw new Error(`Config file not found: ${path}`);
+        return undefined;
+    }
+    let config;
+    try {
+        config = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`Invalid JSON in ${file}: ${e.message}`);
+    }
+    const dir = dirname(file);
+    for (const k of ['out', 'font', 'body']) {
+        const v = config[k];
+        // "monogram" is the built-in font name, not a path
+        if (typeof v === 'string' && !(k === 'font' && v === 'monogram'))
+            config[k] = resolve(dir, v);
+    }
+    return { file, config };
+}

package/dist/font.d.ts

@@ -0,0 +1,47 @@
+/** Design grid of the label, in SVG units (one "pixel" of a 48 px render of the 32-unit canvas). */
+export declare const GRID: number;
+/** Natural cap height of label text, in SVG units (9 grid cells). */
+export declare const CAP_HEIGHT: number;
+export interface LabelLayout {
+    /** Path data. Coordinates are multiplied by `unitScale` to get SVG units. Origin = top-left of the cap box. */
+    d: string;
+    unitScale: number;
+    /** Size of the text box in SVG units (after `unitScale`). */
+    width: number;
+    height: number;
+    /** If set, the label should be positioned on multiples of this value (pixel fonts). */
+    grid?: number;
+}
+export interface LabelFont {
+    name: string;
+    /** Layout `text` at `scale` (1 = natural size). */
+    layout(text: string, scale: number): LabelLayout;
+    /** Can this font draw the character? */
+    has(ch: string): boolean;
+}
+export interface BitmapFontData {
+    name: string;
+    cols: number;
+    rows: number;
+    /** Extra rows below the baseline (descenders). Default 0. */
+    descender?: number;
+    /** Advance in cells (glyph width + spacing). */
+    advance: number;
+    /** char → rows of '#'/'.'; `rows + descender` rows each, `cols` characters wide. */
+    glyphs: Record<string, string[]>;
+    author?: string;
+    license?: string;
+    source?: string;
+}
+/**
+ * Pixel font drawn as rectangles. The `rows` cap rows are stretched to `capCells` rows (whole cells, so the
+ * stretch doubles a few rows) while columns stay 1 cell wide.
+ */
+export declare function bitmapFont(data: BitmapFontData, capCells?: number): LabelFont;
+/** Any vector font: glyph outlines become SVG paths, scaled so the cap height equals `CAP_HEIGHT`. */
+export declare function outlineFont(buffer: Buffer, name: string): LabelFont;
+export declare const BUILTIN_FONT = "monogram";
+/**
+ * `spec`: undefined | "monogram" (built in) | path to a bitmap-font `.json` | path to a `.ttf` / `.otf` / `.woff`.
+ */
+export declare function loadFont(spec?: string): LabelFont;

package/dist/font.js

@@ -0,0 +1,102 @@
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+import opentype from 'opentype.js';
+import { assetPath } from './paths.js';
+/** Design grid of the label, in SVG units (one "pixel" of a 48 px render of the 32-unit canvas). */
+export const GRID = 2 / 3;
+/** Natural cap height of label text, in SVG units (9 grid cells). */
+export const CAP_HEIGHT = 9 * GRID;
+const num = (v) => String(+v.toFixed(3));
+/**
+ * Pixel font drawn as rectangles. The `rows` cap rows are stretched to `capCells` rows (whole cells, so the
+ * stretch doubles a few rows) while columns stay 1 cell wide.
+ */
+export function bitmapFont(data, capCells = 9) {
+    const desc = data.descender ?? 0;
+    const rowStart = (r) => (r <= data.rows ? Math.round((r * capCells) / data.rows) : capCells + (r - data.rows));
+    const glyphPath = (rows, x0) => {
+        let d = '';
+        for (let r = 0; r < data.rows + desc; r++) {
+            const line = rows[r] ?? '';
+            const y = rowStart(r), h = rowStart(r + 1) - y;
+            for (let c = 0; c < data.cols;) {
+                if (line[c] !== '#') {
+                    c++;
+                    continue;
+                }
+                let e = c;
+                while (e < data.cols && line[e] === '#')
+                    e++;
+                d += `M${x0 + c} ${y}h${e - c}v${h}h${c - e}z`;
+                c = e;
+            }
+        }
+        return d;
+    };
+    return {
+        name: data.name,
+        has: (ch) => ch === ' ' || ch in data.glyphs,
+        layout(text, scale) {
+            const cell = GRID * scale;
+            let d = '';
+            [...text].forEach((ch, i) => { const g = data.glyphs[ch]; if (g)
+                d += glyphPath(g, i * data.advance); });
+            const n = [...text].length;
+            return {
+                d, unitScale: cell, grid: cell,
+                width: (data.advance * (n - 1) + data.cols) * cell, height: capCells * cell,
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------- outline fonts (TTF / OTF / WOFF)
+/** Serialize an opentype.js path ourselves (its `toPathData` can emit NaN for some coordinates). */
+function pathData(p) {
+    return p.commands.map((c) => {
+        switch (c.type) {
+            case 'M':
+            case 'L': return `${c.type}${num(c.x)} ${num(c.y)}`;
+            case 'Q': return `Q${num(c.x1)} ${num(c.y1)} ${num(c.x)} ${num(c.y)}`;
+            case 'C': return `C${num(c.x1)} ${num(c.y1)} ${num(c.x2)} ${num(c.y2)} ${num(c.x)} ${num(c.y)}`;
+            default: return 'Z';
+        }
+    }).join('');
+}
+/** Any vector font: glyph outlines become SVG paths, scaled so the cap height equals `CAP_HEIGHT`. */
+export function outlineFont(buffer, name) {
+    const font = opentype.parse(buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength));
+    const capUnits = font.charToGlyph('H').getBoundingBox().y2 || font.unitsPerEm * 0.7;
+    const k = CAP_HEIGHT / capUnits; // svg units per font unit
+    return {
+        name,
+        has: (ch) => font.charToGlyph(ch).index !== 0,
+        layout(text, scale) {
+            const glyphs = [...text].map((c) => font.charToGlyph(c));
+            let x = 0;
+            const placed = glyphs.map((g) => { const px = x; x += g.advanceWidth * k; return px; });
+            const first = glyphs[0]?.getBoundingBox().x1 ?? 0;
+            const last = glyphs[glyphs.length - 1];
+            const right = last ? placed[placed.length - 1] + last.getBoundingBox().x2 * k : 0;
+            const left = first * k;
+            let d = '';
+            glyphs.forEach((g, i) => { d += pathData(g.getPath(placed[i] - left, CAP_HEIGHT, k * font.unitsPerEm)); });
+            return { d, unitScale: scale, width: (right - left) * scale, height: CAP_HEIGHT * scale };
+        },
+    };
+}
+// ---------------------------------------------------------------- loading
+export const BUILTIN_FONT = 'monogram';
+/**
+ * `spec`: undefined | "monogram" (built in) | path to a bitmap-font `.json` | path to a `.ttf` / `.otf` / `.woff`.
+ */
+export function loadFont(spec) {
+    if (!spec || spec === BUILTIN_FONT) {
+        return bitmapFont(JSON.parse(readFileSync(assetPath('fonts', 'monogram.json'), 'utf8')));
+    }
+    const ext = extname(spec).toLowerCase();
+    if (ext === '.json')
+        return bitmapFont(JSON.parse(readFileSync(spec, 'utf8')));
+    if (['.ttf', '.otf', '.woff'].includes(ext))
+        return outlineFont(readFileSync(spec), spec.split('/').pop() ?? spec);
+    throw new Error(`Unsupported font "${spec}". Use "monogram", a bitmap-font .json, or a .ttf/.otf/.woff file.`);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { renderIcon, type RenderOptions, type RenderResult } from './render.js';
+export { CATEGORIES, classify, classifyMime, isCategory, type Category } from './categories.js';
+export { allExtensions, categoryFor, extToMime } from './mime.js';
+export { DEFAULT_PALETTE, createPalette, accentFor, type Palette } from './palette.js';
+export { loadBodies, validateBody, recolor, DEFAULT_TOKENS, type BodySet, type BodyTokens } from './body.js';
+export { loadFont, bitmapFont, outlineFont, GRID, CAP_HEIGHT, type LabelFont, type LabelLayout, type BitmapFontData } from './font.js';
+export { renderLabel, DEFAULT_LABEL, type LabelConfig } from './label.js';
+export { contrast, tint, labelTextColor, normalizeHex } from './color.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { renderIcon } from './render.js';
+export { CATEGORIES, classify, classifyMime, isCategory } from './categories.js';
+export { allExtensions, categoryFor, extToMime } from './mime.js';
+export { DEFAULT_PALETTE, createPalette, accentFor } from './palette.js';
+export { loadBodies, validateBody, recolor, DEFAULT_TOKENS } from './body.js';
+export { loadFont, bitmapFont, outlineFont, GRID, CAP_HEIGHT } from './font.js';
+export { renderLabel, DEFAULT_LABEL } from './label.js';
+export { contrast, tint, labelTextColor, normalizeHex } from './color.js';

package/dist/label.d.ts

@@ -0,0 +1,18 @@
+import { type LabelFont } from './font.js';
+export interface LabelConfig {
+    /** Label band: horizontal center is x=16; `width` and bottom edge in SVG units. */
+    bandWidth: number;
+    bandBottom: number;
+    /** Vertical padding between text and band edge, in grid cells. */
+    padCells: number;
+    /** Maximum text width in SVG units; longer text is scaled down. */
+    innerWidth: number;
+    /** Smallest scale before letters are dropped. */
+    minScale: number;
+    cornerRadius: number;
+    textLight: string;
+    textDark: string;
+}
+export declare const DEFAULT_LABEL: LabelConfig;
+/** SVG fragment (band + text) for `text` in the 32×32 canvas. */
+export declare function renderLabel(text: string, font: LabelFont, accent: string, cfg?: LabelConfig): string;

package/dist/label.js

@@ -0,0 +1,36 @@
+import { labelTextColor } from './color.js';
+import { CAP_HEIGHT, GRID } from './font.js';
+export const DEFAULT_LABEL = {
+    bandWidth: 26, bandBottom: 28, padCells: 2, innerWidth: 24, minScale: 0.35, cornerRadius: 1,
+    textLight: '#FFFFFF', textDark: '#1B1F24',
+};
+const num = (v) => String(+v.toFixed(3));
+const snap = (v, grid) => (grid ? Math.round(v / grid) * grid : v);
+/** SVG fragment (band + text) for `text` in the 32×32 canvas. */
+export function renderLabel(text, font, accent, cfg = DEFAULT_LABEL) {
+    let chars = [...text].filter((c) => font.has(c));
+    if (!chars.length)
+        return '';
+    let scale = 1;
+    let layout = font.layout(chars.join(''), 1);
+    if (layout.width > cfg.innerWidth) {
+        scale = cfg.innerWidth / layout.width;
+        // below the minimum scale we drop trailing letters instead of shrinking further
+        while (scale < cfg.minScale && chars.length > 1) {
+            chars = chars.slice(0, -1);
+            const l = font.layout(chars.join(''), 1);
+            scale = Math.min(1, cfg.innerWidth / l.width);
+        }
+        scale = Math.max(scale, cfg.minScale);
+        layout = font.layout(chars.join(''), scale);
+    }
+    const pad = cfg.padCells * GRID;
+    const bandH = CAP_HEIGHT + 2 * pad;
+    const bandTop = cfg.bandBottom - bandH;
+    const tx = snap(16 - layout.width / 2, layout.grid);
+    const ty = snap(bandTop + (bandH - layout.height) / 2, layout.grid);
+    const fill = labelTextColor(accent, cfg.textLight, cfg.textDark);
+    const band = `<rect x="${num(16 - cfg.bandWidth / 2)}" y="${num(bandTop)}" width="${cfg.bandWidth}" height="${num(bandH)}" rx="${cfg.cornerRadius}" fill="${accent}"/>`;
+    const txt = `<path transform="translate(${num(tx)} ${num(ty)}) scale(${num(layout.unitScale)})" d="${layout.d}" fill="${fill}"/>`;
+    return `<g id="label">${band}${txt}</g>`;
+}

package/dist/mime.d.ts

@@ -0,0 +1,6 @@
+import { type Category } from './categories.js';
+/** extension → all registered mime types, built from the `mime-db` package (MIT). */
+export declare function extToMime(): Map<string, string[]>;
+export declare function categoryFor(ext: string): Category;
+/** Every extension we know about (mime-db + our own overrides), sorted. */
+export declare function allExtensions(): string[];

package/dist/mime.js

@@ -0,0 +1,28 @@
+import { createRequire } from 'node:module';
+import { classify, EXT_OVERRIDES } from './categories.js';
+const require = createRequire(import.meta.url);
+let cache;
+/** extension → all registered mime types, built from the `mime-db` package (MIT). */
+export function extToMime() {
+    if (cache)
+        return cache;
+    const db = require('mime-db');
+    const map = new Map();
+    for (const [mime, info] of Object.entries(db))
+        for (const ext of info.extensions ?? []) {
+            const list = map.get(ext);
+            if (list)
+                list.push(mime);
+            else
+                map.set(ext, [mime]);
+        }
+    return (cache = map);
+}
+export function categoryFor(ext) {
+    const e = ext.toLowerCase().replace(/^\./, '');
+    return classify(e, extToMime().get(e));
+}
+/** Every extension we know about (mime-db + our own overrides), sorted. */
+export function allExtensions() {
+    return [...new Set([...extToMime().keys(), ...EXT_OVERRIDES.keys()])].sort();
+}

package/dist/palette.d.ts

@@ -0,0 +1,13 @@
+import { type Category } from './categories.js';
+/** Default accent per category. Everything here can be overridden (per category or per extension). */
+export declare const DEFAULT_PALETTE: Readonly<Record<Category, string>>;
+export interface Palette {
+    categories: Record<Category, string>;
+    /** Per-extension overrides (lowercase, no dot). */
+    extensions: Record<string, string>;
+}
+/**
+ * Build a palette from overrides. Keys are category names (`pdf`) or extensions with a leading dot (`.docx`).
+ */
+export declare function createPalette(overrides?: Record<string, string>): Palette;
+export declare function accentFor(palette: Palette, ext: string, category: Category): string;

package/dist/palette.js

@@ -0,0 +1,32 @@
+import { CATEGORIES, isCategory } from './categories.js';
+import { normalizeHex } from './color.js';
+/** Default accent per category. Everything here can be overridden (per category or per extension). */
+export const DEFAULT_PALETTE = {
+    generic: '#990000', text: '#999999', code: '#2F7F8F', data: '#336699', pdf: '#D64545', word: '#2B6CB0',
+    sheet: '#217346', slides: '#D24726', image: '#999900', audio: '#1E9E5A', video: '#8E44AD', archive: '#996600',
+    font: '#7B4B94', ebook: '#B5651D', database: '#5B6770', executable: '#444B57', security: '#B8860B',
+    model3d: '#4B6CB7', geo: '#99CC00', mail: '#2E86AB', science: '#009999',
+    disk: '#00796B', design: '#C2185B', game: '#E08A00',
+};
+/**
+ * Build a palette from overrides. Keys are category names (`pdf`) or extensions with a leading dot (`.docx`).
+ */
+export function createPalette(overrides = {}) {
+    const categories = { ...DEFAULT_PALETTE };
+    const extensions = {};
+    for (const [key, value] of Object.entries(overrides)) {
+        const hex = normalizeHex(value);
+        if (key.startsWith('.'))
+            extensions[key.slice(1).toLowerCase()] = hex;
+        else if (isCategory(key))
+            categories[key] = hex;
+        else
+            throw new Error(`Unknown color key "${key}". Use a category (${CATEGORIES.join(', ')}) or ".ext".`);
+    }
+    for (const c of CATEGORIES)
+        categories[c] = normalizeHex(categories[c]);
+    return { categories, extensions };
+}
+export function accentFor(palette, ext, category) {
+    return palette.extensions[ext.toLowerCase().replace(/^\./, '')] ?? palette.categories[category];
+}

package/dist/paths.d.ts

@@ -0,0 +1,3 @@
+/** Package root. Works from both `src/` and `dist/` (both sit one level below the root). */
+export declare const ROOT: string;
+export declare const assetPath: (...parts: string[]) => string;

package/dist/paths.js

@@ -0,0 +1,5 @@
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+/** Package root. Works from both `src/` and `dist/` (both sit one level below the root). */
+export const ROOT = fileURLToPath(new URL('..', import.meta.url));
+export const assetPath = (...parts) => join(ROOT, 'assets', ...parts);

package/dist/png.d.ts

@@ -0,0 +1,2 @@
+/** Rasterize an SVG string. Needs the optional dependency `@resvg/resvg-js`. */
+export declare function renderPng(svg: string, size: number): Promise<Buffer>;

package/dist/png.js

@@ -0,0 +1,11 @@
+/** Rasterize an SVG string. Needs the optional dependency `@resvg/resvg-js`. */
+export async function renderPng(svg, size) {
+    let mod;
+    try {
+        mod = (await import('@resvg/resvg-js'));
+    }
+    catch {
+        throw new Error('PNG export needs the optional dependency @resvg/resvg-js (npm i @resvg/resvg-js).');
+    }
+    return new mod.Resvg(svg, { fitTo: { mode: 'width', value: size } }).render().asPng();
+}

package/dist/render.d.ts

@@ -0,0 +1,26 @@
+import { type BodySet, type BodyTokens } from './body.js';
+import type { Category } from './categories.js';
+import { type LabelFont } from './font.js';
+import { type LabelConfig } from './label.js';
+import { type Palette } from './palette.js';
+export interface RenderOptions {
+    font?: LabelFont;
+    bodies?: BodySet;
+    palette?: Palette;
+    /** Force this accent for the icon (wins over the palette). */
+    accent?: string;
+    /** Force a category (skip mime lookup). */
+    category?: Category;
+    /** Text on the label: default is the extension; `false` draws no label. */
+    label?: string | false;
+    labelCase?: 'upper' | 'lower' | 'none';
+    labelConfig?: Partial<LabelConfig>;
+    tokens?: BodyTokens;
+}
+export interface RenderResult {
+    svg: string;
+    ext: string;
+    category: Category;
+    accent: string;
+}
+export declare function renderIcon(extension: string, opts?: RenderOptions): RenderResult;

package/dist/render.js

@@ -0,0 +1,23 @@
+import { loadBodies, recolor, DEFAULT_TOKENS } from './body.js';
+import { normalizeHex } from './color.js';
+import { loadFont } from './font.js';
+import { DEFAULT_LABEL, renderLabel } from './label.js';
+import { categoryFor } from './mime.js';
+import { accentFor, createPalette } from './palette.js';
+let defaults;
+const getDefaults = () => (defaults ??= { font: loadFont(), bodies: loadBodies(), palette: createPalette() });
+export function renderIcon(extension, opts = {}) {
+    const d = getDefaults();
+    const ext = extension.toLowerCase().replace(/^\./, '');
+    const category = opts.category ?? categoryFor(ext);
+    const accent = opts.accent ? normalizeHex(opts.accent) : accentFor(opts.palette ?? d.palette, ext, category);
+    const tokens = opts.tokens ?? DEFAULT_TOKENS;
+    let svg = recolor((opts.bodies ?? d.bodies).svg(category), accent, tokens);
+    if (opts.label !== false) {
+        const raw = opts.label ?? ext;
+        const text = opts.labelCase === 'lower' ? raw.toLowerCase() : opts.labelCase === 'none' ? raw : raw.toUpperCase();
+        const frag = renderLabel(text, opts.font ?? d.font, accent, { ...DEFAULT_LABEL, ...opts.labelConfig });
+        svg = svg.replace(/<\/svg>\s*$/, `${frag}</svg>`);
+    }
+    return { svg: svg.replace(/>\s*\n\s*</g, '><').trim() + '\n', ext, category, accent };
+}

package/dist/testrun.d.ts

@@ -0,0 +1,12 @@
+import { type Category } from './categories.js';
+import { type RenderOptions } from './render.js';
+/** One representative extension per body type. */
+export declare const SAMPLES: Record<Category, string>;
+export interface TestRunInfo {
+    font: string;
+    body: string;
+    warnings: string[];
+    missing?: string[];
+}
+/** Writes `<out>/svg/*.svg` and `<out>/index.html`. Returns the path of the HTML file. */
+export declare function testRun(outDir: string, opts: RenderOptions, info: TestRunInfo): string;

package/dist/testrun.js

@@ -0,0 +1,70 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CATEGORIES } from './categories.js';
+import { renderIcon } from './render.js';
+import { accentFor, createPalette } from './palette.js';
+/** One representative extension per body type. */
+export const SAMPLES = {
+    generic: 'dat', text: 'txt', code: 'py', data: 'json', pdf: 'pdf', word: 'docx', sheet: 'xlsx', slides: 'pptx',
+    image: 'png', audio: 'mp3', video: 'mp4', archive: 'zip', font: 'ttf', ebook: 'epub', database: 'sqlite',
+    executable: 'exe', security: 'pem', model3d: 'glb', geo: 'kml', mail: 'eml', science: 'cif',
+    disk: 'iso', design: 'psd', game: 'rom',
+};
+/** Label stress test: different lengths, widest letters, digits. */
+const STRESS = ['go', 'pdf', 'docx', 'webm', 'xhtml', 'mmmm', 'json5', 'svgz', 'webmanifest', 'appinstaller'];
+const SIZES = [16, 48, 128];
+/** Writes `<out>/svg/*.svg` and `<out>/index.html`. Returns the path of the HTML file. */
+export function testRun(outDir, opts, info) {
+    const svgDir = join(outDir, 'svg');
+    mkdirSync(svgDir, { recursive: true });
+    const palette = opts.palette ?? createPalette();
+    const write = (ext) => {
+        const r = renderIcon(ext, opts);
+        writeFileSync(join(svgDir, `${ext}.svg`), r.svg);
+        return { file: `svg/${ext}.svg`, accent: r.accent, category: r.category };
+    };
+    const imgs = (file, alt) => SIZES.map((s) => `<figure><img src="${file}" width="${s}" height="${s}" alt="${alt}"><figcaption>${s}px</figcaption></figure>`).join('');
+    const bodyCards = CATEGORIES.map((cat) => {
+        const ext = SAMPLES[cat];
+        const r = write(ext);
+        const accent = opts.accent ?? accentFor(palette, ext, cat);
+        return `<section class="card"><h3>${cat}<small>.${ext}</small></h3><div class="row">${imgs(r.file, cat)}</div>` +
+            `<p class="sw"><i style="background:${accent}"></i>${accent}</p></section>`;
+    }).join('\n');
+    const stress = STRESS.map((ext) => {
+        const r = write(ext);
+        return `<section class="card"><h3>.${ext}<small>${r.category}</small></h3><div class="row">${imgs(r.file, ext)}</div></section>`;
+    }).join('\n');
+    const missingNote = info.missing?.length ? `<div class="warn"><b>No own body yet</b> (drawn with the generic body): ${info.missing.join(', ')}</div>` : '';
+    const warn = missingNote + (info.warnings.length ? `<div class="warn"><b>Body warnings</b><ul>${info.warnings.map((w) => `<li>${w}</li>`).join('')}</ul></div>` : '');
+    const html = `<!doctype html>
+<html lang="en"><meta charset="utf-8"><title>MimeForge test run</title>
+<style>
+:root{--bg:#fff;--fg:#1b1f24;--card:#f6f7f9;--line:#e2e5e9}
+body.dark{--bg:#1e2227;--fg:#e8eaed;--card:#272c33;--line:#363c45}
+body{font:14px/1.4 system-ui,sans-serif;margin:24px;background:var(--bg);color:var(--fg)}
+h1{margin:0 0 4px;font-size:20px}h2{margin:28px 0 10px;font-size:16px}
+.meta{color:#8a919a;margin-bottom:12px}.meta b{color:var(--fg)}
+.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(250px,1fr));gap:12px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px}
+.card h3{margin:0 0 8px;font-size:13px}.card h3 small{color:#8a919a;margin-left:6px;font-weight:400}
+.row{display:flex;align-items:flex-end;gap:16px}
+figure{margin:0;text-align:center}figcaption{font-size:11px;color:#8a919a;margin-top:2px}
+.sw{margin:8px 0 0;font:12px ui-monospace,monospace;color:#8a919a}.sw i{display:inline-block;width:12px;height:12px;border-radius:3px;margin-right:6px;vertical-align:-2px}
+button{font:inherit;padding:4px 10px;border-radius:6px;border:1px solid var(--line);background:var(--card);color:var(--fg);cursor:pointer}
+.warn{background:#fff3cd;color:#664d03;padding:8px 12px;border-radius:8px;margin:12px 0}
+</style>
+<body>
+<h1>MimeForge · test run</h1>
+<div class="meta">font: <b>${info.font}</b> · body: <b>${info.body}</b> · icons are plain &lt;img src="svg/…"&gt; at 16 / 48 / 128 px <button onclick="document.body.classList.toggle('dark')">toggle dark</button></div>
+${warn}
+<h2>Body types (${CATEGORIES.length})</h2>
+<div class="grid">${bodyCards}</div>
+<h2>Label length stress test</h2>
+<div class="grid">${stress}</div>
+</body></html>
+`;
+    const file = join(outDir, 'index.html');
+    writeFileSync(file, html);
+    return file;
+}

package/docs/bodies.md

@@ -0,0 +1,86 @@
+# Bodies
+
+A **body** is the SVG that holds the page shape and the type emblem (the PDF flame, the music note, …). MimeForge adds
+the colored extension **label** on top and recolors the body with the icon's accent color.
+
+MimeForge ships 24 bodies in `assets/bodies/`, one per [category](categories.md). You can replace all of them or just
+some, with `--body`.
+
+## Using your own bodies
+
+```bash
+mimeforge --test-run --body ./my-bodies      # a directory of <category>.svg
+mimeforge --all --body ./one-shape.svg       # one SVG for every category
+```
+
+- **Directory:** file names are category names (`pdf.svg`, `code.svg`, …, see the list in [categories.md](categories.md)).
+  A category without a file falls back to your `generic.svg`, then to the bundled body. Other file names are ignored.
+- **Single file:** used for every category.
+
+`mimeforge --test-run --body …` shows every category with your bodies, so you can check them at 16, 48 and 128 px.
+
+## The contract
+
+| Rule | Why |
+|---|---|
+| The root is `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">` | the label geometry uses the same 32×32 space |
+| The accent color appears literally as **`#FF00FF`** everywhere the category color should be used | it is replaced by the icon's accent |
+| The lighter tint appears literally as **`#FF99FF`** (optional) | it is replaced by the accent mixed 55 % towards white |
+| Leave the **label zone** empty: x 3 to 29, y 19.3 to 28 | the label band is drawn there, on top of the body |
+| Use plain shapes with solid fills. No gradients, filters, masks, clip paths, `<style>`, `<text>` | identical rendering everywhere, tiny files |
+| The file ends with `</svg>` | the label is inserted just before it |
+
+MimeForge warns on stderr when a body breaks the first, second or last rule.
+
+The placeholder colors can be changed in the library API: `loadBodies(path, { accent: '#123456', tint: '#abcdef' })`.
+
+## Skeleton of a bundled body
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+<g id="page">
+<path d="M7.5 2.5H19.5L26.5 9.5V27.5A2 2 0 0 1 24.5 29.5H7.5A2 2 0 0 1 5.5 27.5V4.5A2 2 0 0 1 7.5 2.5Z" fill="#FFFFFF" stroke="#B8BFC7" stroke-linejoin="round"/>
+</g>
+<g id="emblem">
+  <!-- emblem, drawn in accent #FF00FF and tint #FF99FF -->
+</g>
+<g id="fold">
+<path d="M19.5 2.5V7.5Q19.5 9.5 21.5 9.5H26.5Z" fill="#E3E7EB"/>
+<path d="M19.5 2.5V7.5Q19.5 9.5 21.5 9.5H26.5Z" fill="none" stroke="#B8BFC7" stroke-linejoin="round"/>
+</g>
+</svg>
+```
+
+The bundled set uses these conventions (you do not have to):
+
+- page x 5 to 27, y 2 to 30 (22 × 28 units), 1 unit outline `#B8BFC7`, rounded corners of radius 2
+- the folded corner is its own group, drawn last, so it covers parts of the emblem that reach the corner
+- emblem inside x 9 to 23, y 6 to 18, bold shapes (at least 2 units wide), at most about three shapes, readable at 16 px
+- neutrals `#FFFFFF`, `#E3E7EB`, `#B8BFC7`; a shape that should look cut out of an accent shape is painted `#FFFFFF`
+
+## Generating new bodies with an AI design tool
+
+The bundled bodies were designed with an AI design tool. A prompt template that works well, with the skeleton
+attached as a reference (replace the bracketed parts):
+
+```text
+I have a family of file-type icon bodies in one flat style (reference SVGs attached). I need [N] more in exactly the
+same style: [names]. Each is the same document-page silhouette with a category emblem. The extension label is added
+later by code, so draw no text or letters.
+
+Rules: solid fills only (no gradients, shadows, filters, masks, clip-paths, styles, classes, opacity tricks); bold
+shapes with round caps and joins, minimum feature and gap size 2 units, at most about 3 shapes, readable at 16x16 px.
+viewBox 0 0 32 32. The accent color is the literal #FF00FF and its lighter tint the literal #FF99FF; besides those only
+#FFFFFF, #E3E7EB, #B8BFC7, #5B6470. Use the attached skeleton verbatim for the "page" and "fold" groups and design only
+the contents of "emblem". Keep the emblem inside x 9-23, y 6-18 and nothing below y = 18 (a label band covers y 19.3-28).
+The folded corner is drawn last and covers whatever reaches it.
+
+Emblems:
+1. [name]: [what to draw]
+...
+
+First deliver one preview sheet only: the new icons at 32 px and 16 px on white and on dark gray, next to three of the
+attached icons so I can judge consistency. I will ask for the SVG files after reviewing it.
+```
+
+Then run `mimeforge --test-run --body ./new-bodies` and check the colors, the 16 px rendering and the warnings.