mimeforge 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project uses [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] - 2026-10-08
+
+- Fallback icon: `mimeforge default` and `mimeforge --all` write `default.svg` (generic body without a label), and
+  `--png` adds `<size>/default.png`; library: `renderDefaultIcon()`. For apps that need a file to point at when an
+  extension has no icon.
+- PNG export no longer loads system fonts: `--all --png 16` takes about half a second instead of minutes.
+
+## [0.1.2] - 2026-10-08
+
+Documentation only.
+
+- README: separate install paths (npx, global, project dependency, from source), a "use it in a project" example,
+  library install and ESM notes
+
 ## [0.1.1] - 2026-10-08
 
 Maintenance release, the first one published through GitHub Actions (npm Trusted Publishing). No code changes.

package/README.md

@@ -29,40 +29,95 @@ And, frankly, why not? :)
 
 ## Contents
 
-[Quick start](#quick-start) · [Everyday use](#everyday-use) · [Customize](#customize) ([colors](#change-colors) · [label](#change-the-label) · [font](#change-the-font) · [bodies](#change-the-bodies) · [config file](#use-a-config-file) · [PNG](#export-png)) · [Edge cases](#edge-cases) · [Library API](#library-api) · [CLI reference](#cli-reference) · [Categories](#categories) · [Development](#development)
+[Quick start](#quick-start) · [Static hosts](#use-it-on-a-static-host-with-a-fallback-icon) · [Everyday use](#everyday-use) · [Customize](#customize) ([colors](#change-colors) · [label](#change-the-label) · [font](#change-the-font) · [bodies](#change-the-bodies) · [config file](#use-a-config-file) · [PNG](#export-png)) · [Edge cases](#edge-cases) · [Library API](#library-api) · [CLI reference](#cli-reference) · [Categories](#categories) · [Development](#development)
 
 ## Quick start
 
 Requires Node.js 20 or newer.
 
+**Try it, nothing to install:**
+
 ```bash
-npx mimeforge pdf docx webm -o icons     # no install needed
-npm i mimeforge                          # or add it to a project (CLI + library)
+npx mimeforge pdf docx webm -o icons
 ```
 
-To work from source instead:
+This writes `icons/pdf.svg`, `icons/docx.svg` and `icons/webm.svg`. Use them like any image:
+
+```html
+<img src="icons/pdf.svg" width="32" height="32" alt="PDF">
+```
+
+**Install:**
+
+```bash
+npm i -g mimeforge     # a global `mimeforge` command
+npm i mimeforge        # or as a dependency of your project (CLI via npx, plus the library API)
+```
+
+**From source** (to hack on it):
 
 ```bash
 git clone https://github.com/reachdevel/mimeforge.git
 cd mimeforge
-npm install          # also builds the project
+npm install            # also builds the project
 node dist/cli.js pdf docx webm -o icons
 ```
 
-This writes `icons/pdf.svg`, `icons/docx.svg` and `icons/webm.svg`. Use them like any image:
+The examples below use the `mimeforge` command. Without a global install, put `npx` in front of it
+(`npx mimeforge --all`); from a source checkout use `node dist/cli.js` or run `npm link` once.
 
-```html
-<img src="icons/pdf.svg" width="32" height="32" alt="PDF">
+### Use it in a project
+
+Generate the icons at build time, so your app only ships the SVGs it needs:
+
+```json
+{
+  "scripts": {
+    "icons": "mimeforge --all -o public/icons"
+  },
+  "devDependencies": {
+    "mimeforge": "^0.1.1"
+  }
+}
+```
+
+Then `npm run icons` and reference `/icons/<ext>.svg`. `public/icons/manifest.json` maps every extension to its
+category, which is handy for lookups. If you only show a few types, list them instead of `--all`. To render icons at
+runtime instead (a server, a build plugin), use the [library API](#library-api).
+
+### Use it on a static host (with a fallback icon)
+
+If your app serves a prebuilt set of files, say `/m/<size>/<ext>.png`, generate the whole set once:
+
+```bash
+mimeforge --all --png 16,20,32,48 -o m
+```
+
+```
+m/pdf.svg            m/16/pdf.png   m/20/pdf.png   m/32/pdf.png   m/48/pdf.png
+m/default.svg        m/16/default.png  …            the fallback, see below
+m/manifest.json      { "pdf": "pdf", "gdoc": "word", … }   every known extension and its category
 ```
 
-The examples below use `mimeforge`. Install it globally with `npm i -g mimeforge`, use `npx mimeforge`, or (from a
-source checkout) run `npm link` once or replace `mimeforge` with `node dist/cli.js`.
+Extensions MimeForge does not know (a `.hoppa` file) have no file of their own. `default.svg` and
+`<size>/default.png` are the fallback for those: the generic page with a question mark and **no label** (an unknown
+extension cannot be named). Point your app at it when an icon is missing:
+
+```js
+const manifest = await (await fetch('/m/manifest.json')).json();
+const src = ext in manifest ? `/m/32/${ext}.png` : '/m/32/default.png';
+```
+
+or let the browser do it: `<img src="/m/32/hoppa.png" onerror="this.onerror=null;this.src='/m/32/default.png'">`.
+To give one unknown extension its own icon instead, generate it explicitly (`mimeforge hoppa`, which draws the generic
+body with the label `HOPPA`) or, from code, with a category of your choice (`renderIcon('hoppa', { category: 'archive' })`).
 
 ## Everyday use
 
 ```bash
 mimeforge pdf docx webm -o icons        # a few icons
-mimeforge --all -o icons                # every known extension, plus icons/manifest.json (ext → category)
+mimeforge --all -o icons                # every known extension, plus icons/default.svg and icons/manifest.json (ext → category)
+mimeforge default -o icons              # only the fallback icon: generic body, no label
 mimeforge --list                        # which extension gets which category
 mimeforge --test-run                    # visual check, see below
 ```
@@ -182,7 +237,7 @@ optional dependency `@resvg/resvg-js` (installed by default; if it is missing, M
 
 | Situation | What happens |
 |---|---|
-| Unknown extension (`mimeforge xyz`) | generic body (question mark) with the label `XYZ` |
+| Unknown extension (`mimeforge xyz`) | generic body (question mark) with the label `XYZ`; for a label-less fallback file use `mimeforge default` (also written by `--all`) |
 | Long extension (`webmanifest`) | up to 6 letters are drawn at full size; longer text is scaled down proportionally to fit the label, and below about a third of the size letters are dropped from the end |
 | Light accent color | label text switches to a dark ink when white would have less than 3:1 contrast |
 | Character the font does not have | skipped |
@@ -199,10 +254,13 @@ how to change it.
 
 ## Library API
 
+Install with `npm i mimeforge`. The package is ESM, so use `import` (from CommonJS: `const { renderIcon } = await import('mimeforge')`).
+
 ```ts
-import { renderIcon, loadFont, loadBodies, createPalette } from 'mimeforge';
+import { renderIcon, renderDefaultIcon, loadFont, loadBodies, createPalette } from 'mimeforge';
 
 renderIcon('pdf').svg;                                    // SVG string
+renderDefaultIcon().svg;                                  // fallback icon: generic body, no label
 renderIcon('docx', { accent: '#0a7', label: 'WORD' }).svg; // custom accent and label text
 
 renderIcon('xyz', {
@@ -214,15 +272,15 @@ renderIcon('xyz', {
 });
 ```
 
-`renderIcon` returns `{ svg, ext, category, accent }`. Other exports: `categoryFor`, `allExtensions`, `CATEGORIES`,
-`DEFAULT_PALETTE`, `validateBody`, `renderLabel`, `bitmapFont`, `outlineFont` (see `src/index.ts`).
-The package is ESM only.
+`renderIcon` returns `{ svg, ext, category, accent }`. Other exports: `renderDefaultIcon`, `categoryFor`, `allExtensions`, `CATEGORIES`,
+`DEFAULT_PALETTE`, `validateBody`, `renderLabel`, `bitmapFont`, `outlineFont` (see `src/index.ts`). Types are included.
 
 ## CLI reference
 
 ```
 mimeforge <ext...> [options]        write <out>/<ext>.svg for the given extensions
-mimeforge --all [options]           every known extension + manifest.json
+mimeforge --all [options]           every known extension + default.svg + manifest.json
+mimeforge default [options]         only the fallback icon (generic body, no label)
 mimeforge --test-run [options]      HTML preview page (default dir: out/test-run)
 ```
 

package/dist/cli.js

@@ -8,13 +8,14 @@ import { renderPng } from './png.js';
 import { loadFont } from './font.js';
 import { allExtensions, categoryFor } from './mime.js';
 import { createPalette } from './palette.js';
-import { renderIcon } from './render.js';
+import { renderDefaultIcon, renderIcon } from './render.js';
 import { testRun } from './testrun.js';
 import { ROOT } from './paths.js';
 const HELP = `MimeForge – generate file-type icons (SVG) from file extensions
 
 Usage
   mimeforge <ext...> [options]           write <out>/<ext>.svg for the given extensions
+                                         ("default" = the fallback icon without a label)
   mimeforge --all [options]              every known extension (mime-db + extras) + manifest.json
   mimeforge --test-run [options]         write an HTML page with all body types at 16/48/128 px
 
@@ -107,21 +108,22 @@ async function main() {
     const out = resolve(values.out ?? cfg.out ?? 'out');
     mkdirSync(out, { recursive: true });
     const pngSizes = (values.png ? values.png.split(',').map(Number) : cfg.png ?? []).filter((n) => Number.isFinite(n) && n > 0);
-    const exts = values.all ? allExtensions() : positionals.map((e) => e.toLowerCase().replace(/^\./, ''));
+    const exts = values.all ? [...allExtensions(), 'default'] : positionals.map((e) => e.toLowerCase().replace(/^\./, ''));
     const manifest = {};
     let bytes = 0;
     for (const ext of exts) {
-        const r = renderIcon(ext, opts);
+        const r = ext === 'default' ? renderDefaultIcon(opts) : renderIcon(ext, opts);
         writeFileSync(join(out, `${ext}.svg`), r.svg);
         for (const size of pngSizes) {
             mkdirSync(join(out, String(size)), { recursive: true });
             writeFileSync(join(out, String(size), `${ext}.png`), await renderPng(r.svg, size));
         }
-        manifest[ext] = r.category;
+        if (ext !== 'default')
+            manifest[ext] = r.category;
         bytes += r.svg.length;
     }
     if (values.all)
         writeFileSync(join(out, 'manifest.json'), JSON.stringify(manifest, null, 1));
-    console.log(`${exts.length} icon(s) → ${out}  (${(bytes / 1024).toFixed(0)} KB total, ${(bytes / exts.length / 1024).toFixed(1)} KB avg)`);
+    console.log(`${exts.length} icon(s)${values.all ? ' (incl. default)' : ''} → ${out}  (${(bytes / 1024).toFixed(0)} KB total, ${(bytes / exts.length / 1024).toFixed(1)} KB avg)`);
 }
 main().catch((e) => fail(e.message));

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { renderIcon, type RenderOptions, type RenderResult } from './render.js';
+export { renderIcon, renderDefaultIcon, 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';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { renderIcon } from './render.js';
+export { renderIcon, renderDefaultIcon } 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';

package/dist/png.js

@@ -7,5 +7,6 @@ export async function renderPng(svg, size) {
     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();
+    // Our icons contain no <text>, so skip loading system fonts (it dominates the render time).
+    return new mod.Resvg(svg, { fitTo: { mode: 'width', value: size }, font: { loadSystemFonts: false } }).render().asPng();
 }

package/dist/render.d.ts

@@ -24,3 +24,8 @@ export interface RenderResult {
     accent: string;
 }
 export declare function renderIcon(extension: string, opts?: RenderOptions): RenderResult;
+/**
+ * The fallback icon for extensions that have no icon of their own: the generic body without a label
+ * (an unknown extension cannot be named). Written as `default.svg` by `mimeforge --all`.
+ */
+export declare function renderDefaultIcon(opts?: RenderOptions): RenderResult;

package/dist/render.js

@@ -21,3 +21,10 @@ export function renderIcon(extension, opts = {}) {
     }
     return { svg: svg.replace(/>\s*\n\s*</g, '><').trim() + '\n', ext, category, accent };
 }
+/**
+ * The fallback icon for extensions that have no icon of their own: the generic body without a label
+ * (an unknown extension cannot be named). Written as `default.svg` by `mimeforge --all`.
+ */
+export function renderDefaultIcon(opts = {}) {
+    return renderIcon('default', { ...opts, category: 'generic', label: false });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mimeforge",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Generate file-type icons as SVG from a file extension: 24 bundled bodies, extension labels, pluggable fonts, bodies and colors.",
   "author": {
     "name": "Levent Kurt",