webfont 11.2.26 → 12.1.0

package/NOTICE.md

@@ -0,0 +1,165 @@
+# webfont — Legal notice
+
+This document covers **copyright and licensing for fonts you process**, **disclaimers** about using the webfont software, **community attribution guidelines**, and **third-party open-source components** bundled with or used by this project.
+
+It does **not** replace the [MIT License](./LICENSE) for the webfont source code. If anything here conflicts with `LICENSE`, `LICENSE` governs the software itself.
+
+**This is not legal advice.** When in doubt about a font or icon license, consult the rights holder or qualified counsel.
+
+---
+
+## 1. webfont software license
+
+The **webfont** program (source code, CLI, and npm package) is licensed under the **[MIT License](./LICENSE)**.
+
+Copyright (c) 2016–present [itgalaxy](https://github.com/itgalaxy).
+
+You may use, copy, modify, and distribute the **software** under the terms of `LICENSE`, provided the copyright and permission notice are preserved in copies or substantial portions.
+
+---
+
+## 2. Disclaimer of warranties and limitation of liability
+
+THE WEBFONT SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+**You are solely responsible** for how you use webfont, what files you pass into it, and what you do with the output.
+
+---
+
+## 3. Fonts and icons you provide (user content)
+
+webfont is a **technical tool**. It does **not**:
+
+- grant any copyright, trademark, or distribution rights in fonts or icons;
+- change the license terms of input or output files;
+- verify that you have permission to use, modify, decompress, convert, or redistribute any font or SVG;
+- remove or replace copyright or license metadata embedded in font files (name tables, etc.).
+
+### 3.1 SVG icon input
+
+If you build a font from **`.svg` icons**, you must have the right to use those artworks (your own work, licensed stock, client assets with permission, open-source icons under compatible terms, etc.).
+
+Generated font files may be subject to the same restrictions as the source icons and to any third-party notices you embed via options such as `metadata` / `copyright`.
+
+### 3.3 TTF to webfont encoding
+
+If you **encode** one or more `.ttf` files to `eot`, `woff`, or `woff2`, you are re-wrapping font data you already hold. That operation:
+
+- does **not** make a restricted or commercial font free to use or share;
+- does **not** bypass foundry EULAs or redistribution terms;
+- preserves copyright/metadata embedded in the source TTF;
+- does **not** merge multiple weights into one file — each input yields separate outputs.
+
+**Only process fonts you are authorized to convert and redistribute** under their license.
+
+### 3.4 WOFF / WOFF2 decompression
+
+If you **decompress** one or more `.woff` or `.woff2` files (from disk or from an `http(s)` URL) to `.ttf` or `.otf`, you are extracting the **SFNT payload** inside each container. That operation:
+
+- does **not** make a restricted or commercial font free to use or share;
+- does **not** bypass foundry EULAs, app terms of service, CDN hotlinking policies, or site download terms;
+- may produce files that are **easier to reuse** than the original webfonts — compliance with the **original font license** remains your obligation;
+- does **not** merge multiple weights into one font file — each input yields a separate output.
+
+**Only process fonts you are authorized to use and download** under their license. For remote URLs, you must also have permission to fetch and store those bytes.
+
+### 3.5 Redistribution of output
+
+Publishing, shipping, or sublicensing fonts produced or extracted with webfont (in apps, websites, PDFs, design assets, npm packages, etc.) is **your responsibility**. The MIT license on webfont does **not** apply to those font files.
+
+---
+
+## 4. Community attribution guidelines
+
+These guidelines help the community use and reference webfont fairly. They are **social expectations**, not additional legal terms beyond `LICENSE`.
+
+### 4.1 Using webfont in your project
+
+- **No attribution required** for normal use (install via npm, run in CI, internal tooling) under the MIT License.
+- **Appreciated** when webfont is a visible part of a product, tutorial, or open-source repo: mention [webfont](https://github.com/itgalaxy/webfont) and link to the repository or [npm package](https://www.npmjs.com/package/webfont).
+
+### 4.2 Tutorials, posts, and courses
+
+When documenting a workflow that centers on webfont, please:
+
+- name the tool (**webfont**) and link to the official repo or npm page;
+- distinguish **webfont the software** (MIT) from **fonts you demonstrate** (which may be proprietary);
+- avoid implying **endorsement** by itgalaxy unless you have written permission.
+
+### 4.3 Forks, wrappers, and hosted services
+
+If you redistribute webfont code, ship a fork, or offer a hosted “font converter” built on webfont:
+
+- comply with the **MIT License** (retain copyright and permission notice);
+- do **not** use the itgalaxy name, logo, or webfont branding to suggest official affiliation without permission;
+- provide **your own** terms and privacy policy for user-uploaded fonts; make clear that **users** must have rights to their files.
+
+### 4.4 Citing underlying libraries
+
+webfont builds on several open-source font libraries (see [Section 5](#5-third-party-open-source-dependencies)). If you publish academic work, a detailed case study, or compliance documentation that discusses **how** conversion is implemented, consider citing those libraries alongside webfont.
+
+---
+
+## 5. Third-party open-source dependencies
+
+webfont depends on the following **runtime** npm packages (direct dependencies). Versions follow `package.json` / `package-lock.json` at release time.
+
+| Package | Typical license | Role in webfont |
+|---------|-----------------|-----------------|
+| [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) | MIT | Configuration file discovery |
+| [deepmerge](https://github.com/TehShrike/deepmerge) | MIT | Option merging |
+| [fontverter](https://github.com/papandreou/fontverter) | BSD-3-Clause | WOFF/WOFF2 → SFNT decompression |
+| [globby](https://github.com/sindresorhus/globby) | MIT | Input file globbing |
+| [meow](https://github.com/sindresorhus/meow) | MIT | CLI argument parsing |
+| [nunjucks](https://github.com/mozilla/nunjucks) | BSD-2-Clause | CSS / SCSS / Styl templates |
+| [p-limit](https://github.com/sindresorhus/p-limit) | MIT | Concurrency limiting |
+| [resolve-from](https://github.com/sindresorhus/resolve-from) | MIT | Module resolution |
+| [svgo](https://github.com/svg/svgo) | MIT | Optional SVG optimization (`optimizeSvg`) |
+| [svg2ttf](https://github.com/fontello/svg2ttf) | MIT | SVG font → TTF |
+| [svgicons2svgfont](https://github.com/nfroidure/svgicons2svgfont) | MIT | SVG icons → SVG font |
+| [ttf2eot](https://github.com/fontello/ttf2eot) | MIT | TTF → EOT |
+| [ttf2woff](https://github.com/fontello/ttf2woff) | MIT | TTF → WOFF |
+| [wawoff2](https://github.com/fontello/wawoff2) | MIT | TTF ↔ WOFF2 compression |
+| [xml2js](https://github.com/Leonidas-from-XIV/node-xml2js) | MIT | SVG XML parsing |
+
+Transitive dependencies (and their licenses) are recorded in `package-lock.json`. For a full license report after install, you can run:
+
+```shell
+npx license-checker --production --direct
+```
+
+(Third-party tool; not maintained by this project.)
+
+### BSD-licensed components
+
+**fontverter** (BSD-3-Clause) and **nunjucks** (BSD-2-Clause) are subject to their own copyright notices and license terms. Redistributions of webfont that include source or substantial portions of those dependencies should preserve their respective notices as required by those licenses.
+
+---
+
+## 6. Test fixtures and examples
+
+Font and SVG files under `src/fixtures/` are intended **for automated tests and documentation examples** only. They are not a grant of rights to use those assets outside this repository. Do not assume fixture fonts or icons are redistributable for your own products.
+
+---
+
+## 7. Keeping this document current
+
+Update **NOTICE.md** in the same pull request when you:
+
+- add or remove **runtime dependencies** that affect licensing or attribution;
+- change **user-facing behavior** around font decompression or output formats in ways that affect legal expectations;
+- publish new **community guidelines** for attribution or acceptable use.
+
+See also [FEATURES.md](./FEATURES.md) (product capabilities) and [CONTRIBUTING.md](./CONTRIBUTING.md) (documentation expectations).
+
+---
+
+## 8. Questions and reports
+
+- **Software bugs and features:** [GitHub Issues](https://github.com/itgalaxy/webfont/issues)
+- **Code of conduct:** [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+- **License of the webfont source:** [LICENSE](./LICENSE)
+
+For font licensing questions about **your** input files, contact the font foundry, vendor, or rights holder — maintainers cannot advise on third-party font EULAs.

package/README.md

@@ -1,28 +1,64 @@
 # webfont
 
 [![NPM version](https://img.shields.io/npm/v/webfont.svg)](https://www.npmjs.org/package/webfont)
-[![Travis Build Status](https://img.shields.io/travis/itgalaxy/webfont/master.svg?label=build)](https://travis-ci.org/itgalaxy/webfont)
-[![Build status](https://ci.appveyor.com/api/projects/status/a8absovr2r44w1oc?svg=true)](https://ci.appveyor.com/project/evilebottnawi/webfont)
+[![Node.js CI](https://github.com/itgalaxy/webfont/actions/workflows/pr.yml/badge.svg)](https://github.com/itgalaxy/webfont/actions/workflows/pr.yml)
 
-Generator of fonts from SVG icons.
+Generator of fonts from SVG icons, with separate modes to **encode** TTF to web formats and **decompress** WOFF/WOFF2 containers to the TTF or OTF inside.
+
+See **[FEATURES.md](./FEATURES.md)** for the canonical capability list (what is stable, in progress, or planned).
+
+**Legal / licensing:** [NOTICE.md](./NOTICE.md) — font copyright, disclaimers, attribution guidelines, and third-party library notices.
+
+**Troubleshooting:** [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — common errors on the current release (including [icons that lose detail after export](./TROUBLESHOOTING.md#icon-details-missing-after-export) due to `fill-rule: evenodd`, #175).
+
+**Migration:** [MIGRATION.md](./MIGRATION.md) — what changed between versions and how to upgrade.
 
 ## Features
 
-- Supported font formats: `WOFF2`, `WOFF`, `EOT`, `TTF` and `SVG`;
-- Support config files: use a `JavaScript`, `JSON` or `YAML` file to specify configuration information for an entire directory and all of its subdirectories;
-- Support all popular browsers, including IE8+;
-- Allows using custom templates (example `css`, `scss`, [`styl`](https://github.com/itgalaxy/webfont/pull/164/) etc);
-- No extra dependencies as `gulp`, `grunt` or other big tools;
-- Tested on all platforms (`linux`, `windows` and `osx`);
-- CLI;
+- **SVG icon pipeline** (default): `.svg` icons → `svg`, `ttf`, `eot`, `woff`, `woff2` (not `otf`);
+- **TTF encoding**: one or more `.ttf` files → `ttf` (pass-through), `eot`, `woff`, and/or `woff2` (auto-detected — no extra flag);
+- **Webfont decompression**: one `.woff` or `.woff2` file → `ttf` and/or `otf` matching the **embedded SFNT flavor** (decompress only — not TTF ↔ OTF transcoding);
+- Config files: `JavaScript`, `JSON`, or `YAML` via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig);
+- Built-in and custom CSS templates (`css`, `scss`, [`styl`](https://github.com/itgalaxy/webfont/pull/164/));
+- CLI and programmatic API (**Node.js build time only** — see [TROUBLESHOOTING](./TROUBLESHOOTING.md#cant-resolve-fs-webpack--react--vite-client-bundle));
 - [Webpack plugin](https://github.com/itgalaxy/webfont-webpack-plugin).
 
+## Input modes
+
+webfont runs one of three pipelines depending on matched input files. They cannot be mixed in a single run.
+
+| Mode | Input | Outputs | Notes |
+|------|--------|---------|--------|
+| **SVG icons** | One or more `.svg` files | `svg`, `ttf`, `eot`, `woff`, `woff2` | Default. Builds TrueType via `svg2ttf`. **`otf` is rejected** — use `ttf`. |
+| **TTF encoding** | One or more `.ttf` files | `ttf`, `eot`, `woff`, and/or `woff2` per input | Auto-detected. Default when SVG-pipeline `formats` are still configured: `woff` + `woff2`. No templates. |
+| **Webfont decompress** | One or more `.woff` / `.woff2` paths, globs, or `http(s)` URLs | `ttf` and/or `otf` per input | One output file per source (basename from filename; collisions get `-woff`/`-woff2`). Not a single merged font. |
+
+**Not supported today**
+
+- Renaming or re-wrapping without matching the real outline format (e.g. requesting `otf` when the WOFF2 holds TrueType).
+- Converting TTF to OTF (or OTF to TTF) — use [FontForge](https://fontforge.org/) or similar.
+- `.otf` as input for webfont encoding (TrueType `.ttf` only today).
+- Templates, `glyphTransformFn`, `glyphContentTransformFn`, or merged multi-weight SFNT output in TTF encoding or webfont decompress mode.
+- Globs that match extension-less or unsupported files together with fonts (the run fails instead of silently ignoring extras).
+
+Every matched path must end in `.svg`, `.ttf`, `.woff`, or `.woff2`. See [FEATURES.md](./FEATURES.md) for test-backed criteria.
+
+### Font licensing
+
+webfont is a technical tool. **Decompressing or generating fonts does not grant you any rights to those fonts.** You must have permission to use, convert, and redistribute every input file and every output file under the applicable license (commercial fonts, app-bundled webfonts, client icons, etc.). The MIT license applies to **this software only**, not to fonts you pass through it.
+
+Full details, disclaimers, community attribution guidelines, and third-party library notices: **[NOTICE.md](./NOTICE.md)**.
+
 ## Table Of Contents
 
 - [Webfont](#webfont)
+  - [Features](#features)
+  - [Input modes](#input-modes)
+  - [Font licensing](#font-licensing)
   - [Installation](#installation)
   - [Usage](#usage)
   - [Options](#options)
+  - [Result](#result)
   - [svgicons2svgfont](#svgicons2svgfont)
 - [Command Line Interface (CLI)](#command-line-interface)
   - [Installation](#cli-installation)
@@ -32,18 +68,23 @@ Generator of fonts from SVG icons.
 - [Roadmap](#roadmap)
 - [Contribution](#contribution)
 - [Changelog](#changelog)
+- [Legal notice](#legal-notice)
 - [License](#license)
 
 ---
 
 ## Installation
 
+Requires **Node.js** >= 24.14.0. Install as a dev dependency and run at **build time** (CLI, npm script, or bundler plugin) — not from browser/React client bundles.
+
 ```shell
 npm install --save-dev webfont
 ```
 
 ## Usage
 
+Node.js only — do not import from client-side app code ([#198](https://github.com/itgalaxy/webfont/issues/198)).
+
 ```js
 import webfont from "webfont";
 
@@ -82,13 +123,67 @@ webfont({
   });
 ```
 
+### TTF encoding examples
+
+```js
+import webfont from "webfont";
+
+// Single local TTF → WOFF + WOFF2 (default when formats unset)
+const encoded = await webfont({
+  files: "path/to/font.ttf",
+});
+
+// Explicit formats
+const subset = await webfont({
+  files: "path/to/font.ttf",
+  formats: ["woff2"],
+});
+
+// Batch: multiple TTF files in one run
+const batch = await webfont({
+  files: ["fonts/Inter-Regular.ttf", "fonts/Inter-Bold.ttf"],
+  formats: ["woff", "woff2"],
+});
+// batch.transcodedFonts → [{ source, woff, woff2 }, …]
+```
+
+### Webfont decompress examples
+
+```js
+import webfont from "webfont";
+
+// Single local file
+const one = await webfont({
+  files: "path/to/font.woff2",
+  formats: ["ttf"],
+});
+
+// Batch: multiple files in one run (one TTF/OTF output per input)
+const batch = await webfont({
+  files: ["fonts/Inter-Regular.woff2", "fonts/Inter-Bold.woff2"],
+  formats: ["ttf"],
+});
+// batch.decompressedFonts → [{ source, ttf }, …]
+
+// Remote URL (http or https)
+const remote = await webfont({
+  files: "https://cdn.example.com/fonts/Inter-Medium.woff2",
+  formats: ["ttf"],
+});
+```
+
 ### Options
 
 #### `files`
 
 - Type: `string` | `array`
 - Description: A file glob, or array of file globs. Ultimately passed to [fast-glob](https://github.com/mrmlnc/fast-glob) to figure out what files you want to get.
-- Note: `node_modules` and `bower_components` are always ignored.
+- **SVG mode**: one or more `.svg` icon paths or globs (default pipeline).
+- **TTF encoding mode**: one or more `.ttf` paths or globs.
+- **Webfont decompress mode**: one or more `.woff` / `.woff2` paths, globs, or `https://…` URLs (see [`formats`](#formats) and [Input modes](#input-modes)).
+- Do not mix `.svg`, `.ttf`, and `.woff` / `.woff2` in the same run.
+- Every matched file must have a supported extension (`.svg`, `.ttf`, `.woff`, `.woff2`); extension-less files such as `LICENSE` are not ignored when matched by a broad glob.
+- `node_modules` and `bower_components` are always ignored.
 
 #### `configFile`
 
@@ -99,6 +194,7 @@ webfont({
   2. a `.webfontrc` file (with or without filename extension: `.json`, `.yaml`, and `.js` are available)
   3. a `webfont.config.js` file exporting a JS `object`.
      The search will begin in the working directory and move up the directory tree until it finds a configuration file.
+- Note: When a configuration file is discovered or loaded, the resolved absolute path is available on `result.config.filePath` (see [Result](#result)).
 
 #### `fontName`
 
@@ -108,16 +204,23 @@ webfont({
 
 #### `formats`
 
-- Type: `array`,
-- Default: `['svg', 'ttf', 'eot', 'woff', 'woff2']`,
-- Possible values: `svg, ttf, eot, woff, woff2`,
+- Type: `array`
+- Default: `['svg', 'ttf', 'eot', 'woff', 'woff2']` (SVG input). For TTF input, defaults to `['woff', 'woff2']` when SVG-pipeline formats are still configured. For WOFF/WOFF2 input, defaults to `['ttf']` when SVG-pipeline formats are still configured.
+- Possible values: `svg`, `ttf`, `otf`, `eot`, `woff`, `woff2`
 - Description: Font file types to generate.
+  - **SVG input**: `svg`, `ttf`, `eot`, `woff`, `woff2` only. **`otf` is not supported** (pipeline uses TrueType outlines).
+  - **TTF input**: `ttf`, `eot`, `woff`, and/or `woff2` only. **`svg` and `otf` are not produced** in this mode.
+  - **WOFF/WOFF2 input**: `ttf` and/or `otf` only — must match the decompressed SFNT flavor inside the file (not arbitrary transcoding). `eot`, `woff`, `woff2`, and `svg` are not produced in this mode.
+- CLI: pass `-f` / `--formats` as a JSON array (for example `'["woff2"]'`) or as a comma-separated list (for example `woff2` or `svg, ttf, woff2`). Invalid format names throw an error.
+- API and config files: `formats` must be an array of the values above; unknown names (for example `icon`) throw before the pipeline runs.
 
 #### `template`
 
-- Type: `string`
+- Type: `string` or `string[]`
 - Default: `null`
-- Possible values: `css`, `scss`, [`styl`](https://github.com/itgalaxy/webfont/pull/164/) (feel free to contribute more).
+- Possible values: `css`, `scss`, `styl`, `html`, `json` (feel free to contribute more), or a path to a custom `.njk` template.
+- Pass an **array** to generate multiple outputs in one run (for example `['html', 'scss']` for preview + styles, #158).
+- CLI: pass `-t` / `--template` as a single name, a JSON array (`'["html","scss"]'`), or a comma-separated list (`html,scss`).
 - Note: If you want to use a custom template use this option pass in a path `string` like this:
 
   ```js
@@ -157,8 +260,69 @@ webfont({
 #### `templateFontName`
 
 - Type: `string`
-- Default: Gets is from `fontName` if not set, but you can specify any value.
-- Description: Template font family name you want.
+- Default: Same as [`fontName`](#fontname) when not set.
+- Description: CSS `font-family` name emitted by built-in templates (`fontFamily` in Nunjucks context). Output **font files** are always named after `fontName` (for example `icons-a.woff2`); built-in templates reference those files with `{{ fontName }}` in `url(...)` while `font-family` uses `{{ fontFamily }}` ([#331](https://github.com/itgalaxy/webfont/issues/331)).
+
+#### `templateCacheString`
+
+- Type: `string`
+- Default: `Date.now()` at generation time
+- Description: Query string appended to font `url(...)` values in built-in templates (before optional `&v=` hash). Use a fixed value (for example `v=1`) when you only need manual cache busting; pair with [`addHashInFontUrl`](#addhashinfonturl) for automatic content-based busting.
+
+#### `addHashInFontUrl`
+
+- Type: `boolean`
+- Default: `false`
+- Description: When `true` and a built-in `template` is used, append `&v=<md5>` to each font URL in the generated CSS/SCSS/Styl. The hash is derived from the SVG font output — it changes only when icon data changes. **Output filenames stay** `fontName.woff2`, `fontName.scss`, etc. (stable `@import` paths).
+- CLI: `--addHashInFontUrl`
+- Addresses browser cache issues without renaming font files on every build ([#125](https://github.com/itgalaxy/webfont/issues/125)).
+
+**Example — stable `webfont.scss`, cache-busted font URLs:**
+
+```shell
+webfont "icons/*.svg" -d dist/icons -t scss --addHashInFontUrl
+```
+
+```js
+import webfont from "webfont";
+
+await webfont({
+  files: "src/icons/**/*.svg",
+  fontName: "webfont",
+  template: "scss",
+  templateFontPath: "./fonts/",
+  addHashInFontUrl: true,
+});
+// Writes dist/icons/webfont.scss and dist/icons/webfont.woff2 (fixed names).
+// SCSS contains url("./fonts/webfont.woff2?...&v=<md5>") — hash updates when icons change.
+```
+
+Do **not** use `Math.random()` in `fontName` — that renames both font files and the stylesheet on every run.
+
+#### `unicodeRange`
+
+- Type: `boolean | string`
+- Default: `false` (omit `unicode-range` from built-in templates)
+- Description: When `true` and a built-in `template` is used, emit a `unicode-range` declaration in `@font-face` so the browser can load only the icon font that owns the code points on the page. With the default `startUnicode` (`0xEA01`), the range is derived from the minimum and maximum allocated code points (for example `U+EA01-EA03`). Pass a CSS value string (for example `U+EA01-EAFF`) to override the computed range. Set to `false` to omit the rule (default).
+- CLI: `--unicode-range` to enable auto-computed range
+- Helps when **multiple icon fonts** share a page ([#322](https://github.com/itgalaxy/webfont/issues/322)) — each `@font-face` can declare which private-use code points it owns so the browser skips downloading fonts that cannot render the glyphs in use.
+- **Ligature trade-off:** computed `unicode-range` covers **private-use code points only** (ligature names are ignored when building the range). If you type icon names with OpenType ligatures (`font-feature-settings: "liga"`), a PUA-only `unicode-range` prevents the browser from applying the icon font to ASCII letters, so ligatures **do not render**. Prefer class + codepoint icons in production when `unicode-range` is enabled, or leave `unicodeRange` at the default `false` if you rely on ligature names.
+
+#### `ligatures`
+
+- Type: `boolean`
+- Default: `false` (ligature glyphs are **not** added unless you opt in)
+- Description: When `true`, each glyph gets a second unicode entry: the icon name with hyphens replaced by underscores (for example `phone-call` → `phone_call`). Browsers can map that character sequence to the icon glyph when OpenType ligatures are enabled (`font-feature-settings: "liga"`).
+- CLI: `--ligatures` to enable ligature glyphs in the font.
+- **Why off by default:** large icon sets (thousands of glyphs) produce huge GSUB tables. **Firefox on Windows** (DirectWrite) can hang or slow dramatically when ligatures are enabled ([#558](https://github.com/itgalaxy/webfont/issues/558)). Prefer **class + private-use codepoint** CSS for MDI-scale fonts. webfont prints a warning when glyph count exceeds 2000 with ligatures enabled.
+
+#### `templateFontLigatures`
+
+- Type: `boolean`
+- Default: `true`
+- Description: When `true` and the built-in **`html`** preview template is used, the generated CSS enables `font-feature-settings: "liga"` on the **Ligature** section (`#icon-ligatures`) so ligature names render as icons instead of invisible/missing glyphs. If you also enable [`unicodeRange`](#unicoderange), the HTML template **omits** `unicode-range` on `@font-face` while ligature preview is on (ligature strings are ASCII; a PUA-only `unicode-range` would block the icon font for those characters). Set to `false` if you inject your own ligature CSS.
+- CLI: `--no-template-font-ligatures` to omit the CSS rule.
+- Requires [`ligatures`](#ligatures) enabled (`--ligatures` / `ligatures: true`). Class-based icons (`.font-name-icon::before` with a private-use codepoint) work without this option.
 
 #### `glyphTransformFn`
 
@@ -190,12 +354,113 @@ webfont({
     });
   ```
 
+#### `glyphContentTransformFn`
+
+- Type: `function`
+- Default: `null`
+- Description: Transform each SVG glyph **before** font generation (SVG pipeline only). Use this hook to preprocess SVGs — for example stroke-based icons converted to filled paths. **webfont does not bundle preprocessors**; install tools such as [`svg-outline-stroke`](https://github.com/elrumordelaluz/outline-stroke) in **your** project and call them from this function (see [ADR 0011](docs/adr/0011-no-svg-outline-stroke-dependency.md)). `glyphTransformFn` only changes metadata; this hook receives the full `GlyphData` (`contents`, `srcPath`, optional `metadata`) and must return the new SVG string.
+- Example (stroke icons, #144 — **install `svg-outline-stroke` in your app**, not in webfont):
+
+  ```js
+  import outlineStroke from "svg-outline-stroke";
+  import webfont from "webfont";
+
+  await webfont({
+    files: "src/svg-icons/**/*.svg",
+    glyphContentTransformFn: async (glyph) => outlineStroke(glyph.contents),
+  });
+  ```
+
+  For better trace quality with `svg-outline-stroke`, use a larger `width` / `height` / `viewBox` on the source SVG (see the library README).
+
+#### `optimizeSvg`
+
+- Type: `boolean`
+- Default: `false`
+- Description: When `true`, run a **conservative** [SVGO](https://github.com/svg/svgo) pass on each SVG **after** diagnostics and **before** `glyphContentTransformFn`. Removes editor cruft (comments, metadata, doctype) without rewriting paths or removing `viewBox`. Does **not** convert stroke-only artwork to fills — pair with [`glyphContentTransformFn`](#glyphcontenttransformfn) for stroke icons ([#327](https://github.com/itgalaxy/webfont/issues/327), [#724](https://github.com/itgalaxy/webfont/issues/724)).
+- CLI: `--optimize-svg`
+- Optional: `svgoConfig` — SVGO `Config` object; when `plugins` is set, it replaces the built-in conservative plugin list.
+
+  ```js
+  import webfont from "webfont";
+
+  await webfont({
+    files: "src/icons/**/*.svg",
+    optimizeSvg: true,
+    glyphContentTransformFn: async (glyph) => {
+      // optional: stroke-to-fill after SVGO cleanup
+      return glyph.contents;
+    },
+  });
+  ```
+
+#### `svgTools` (alpha)
+
+- Type: `{ diagnose?: boolean; onMessage?: (message: string) => void }`
+- Default: `undefined` (disabled)
+- Description: **Alpha.** Scan SVG sources for icon-font incompatibilities before font generation (SVG pipeline only). Does **not** modify SVGs — use [`glyphContentTransformFn`](#glyphcontenttransformfn) to preprocess (for example stroke-to-fill with [`svg-outline-stroke`](https://github.com/elrumordelaluz/outline-stroke), installed in your project). See [ADR 0011](docs/adr/0011-no-svg-outline-stroke-dependency.md).
+  - **`diagnose`:** log warnings for `fill-rule: evenodd`, stroke-only paths (`fill="none"` + `stroke`), and poorly supported elements (`<line>`, `<polyline>`, `<clipPath>`). Results are also returned on `result.svgDiagnostics` when enabled.
+  - **`onMessage`:** optional sink for diagnostic log lines (tests, custom UIs).
+- CLI: `--svg-diagnose` (alpha).
+- Example:
+
+  ```js
+  import webfont from "webfont";
+
+  const result = await webfont({
+    files: "src/icons/**/*.svg",
+    svgTools: { diagnose: true },
+  });
+
+  console.log(result.svgDiagnostics);
+  ```
+
+  See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — “Icon details missing after export”.
+
+#### `metadataProvider`
+
+- Type: `function`
+- Default: built-in metadata service (reads icon names and unicode from SVG files)
+- Description: Custom callback to resolve glyph metadata for each source file. Receives the file path and a Node-style callback `(error, metadata)` where `metadata` is `{ name: string, unicode?: string | string[] }`. When omitted, webfont uses its default metadata reader.
+
+  ```js
+  import webfont from "webfont";
+
+  webfont({
+    files: "src/svg-icons/**/*.svg",
+    metadataProvider: (srcPath, callback) => {
+      callback(null, { name: "custom-icon-name" });
+    },
+  });
+  ```
+
 #### `sort`
 
 - Type: `bool`
 - Default: `true`
 - Description: Whether you want to sort the icons sorted by name.
 
+### Result
+
+`webfont()` resolves to an object with generated font buffers (and optional `template` output). The `config` property contains the **effective options** used for the run (defaults, discovered config, and any options you passed in), plus optional **output metadata** when a configuration file was found or loaded.
+
+#### `result.config.filePath`
+
+- Type: `string` | `undefined`
+- Description: Absolute path to the configuration file that was discovered (`search`) or loaded (`configFile` / CLI `--config`). Omitted when no configuration file was found and defaults were used.
+- Note: Output-only metadata — not an input option. Do not set `filePath` in `.webfontrc`, `package.json`, or the `webfont()` call; values passed that way are ignored.
+- Example:
+
+  ```js
+  const result = await webfont({
+    files: "src/svg-icons/**/*.svg",
+  });
+
+  if (result.config?.filePath) {
+    console.log(`Loaded config from ${result.config.filePath}`);
+  }
+  ```
+
 ---
 
 ## svgicons2svgfont
@@ -277,12 +542,6 @@ These can be appended to [webfont options](#options). These are passed directly
 - Description: The font [metadata](http://www.w3.org/TR/SVG/metadata.html).
   You can set any character data in, but this is the recommended place for a copyright mention.
 
-#### `svgicons2svgfont.log`
-
-- Type: `function`
-- Default: `console.log`
-- Description: Allows you to provide your own logging function. Set to `function(){}` to disable logging.
-
 ---
 
 ## Command Line Interface
@@ -296,7 +555,7 @@ Add the `cli` script to your `package.json` file's `scripts` object:
 ```json
 {
   "scripts": {
-    "webfont": "node node_modules/webfont/dist/cli.js"
+    "webfont": "node node_modules/webfont/dist/cli.mjs"
   }
 }
 ```
@@ -306,7 +565,7 @@ If you're using cross-env:
 ```json
 {
   "scripts": {
-    "webfont": "cross-env node_modules/webfont/dist/cli.js"
+    "webfont": "cross-env node_modules/webfont/dist/cli.mjs"
   }
 }
 ```
@@ -336,7 +595,7 @@ If you're using cross-env:
             The search will begin in the working directory and move up the
             directory tree until a configuration file is found.
 
-        -f, --font-name
+        -u, --fontName
 
             The font family name you want, default: "webfont".
 
@@ -348,9 +607,12 @@ If you're using cross-env:
 
             Output the version number.
 
-        -r, --formats
+        -f, --formats
 
-            Only this formats generate.
+            Font formats to generate. Pass a JSON array (e.g. '["woff2"]') or a
+            comma-separated list (e.g. woff2 or svg, ttf, woff2).
+            SVG input: svg, ttf, eot, woff, woff2 (not otf).
+            WOFF/WOFF2 input: ttf and/or otf matching the embedded SFNT flavor.
 
         -d, --dest
 
@@ -387,6 +649,10 @@ If you're using cross-env:
 
             Tell me everything!.
 
+        --svg-diagnose
+
+            (Alpha) Scan SVG icons for icon-font incompatibilities and log warnings.
+
     For "svgicons2svgfont":
 
         --font-id
@@ -468,10 +734,8 @@ The CLI can exit the process with the following exit codes:
 
 ## Roadmap
 
-- The ability to generate from any type to any type;
-- More tests, include CLI test;
-- Improved docs;
-- Reduce package size (maybe implement `ttf2woff2` with native js library);
+- Arbitrary format transcoding (e.g. TTF ↔ OTF outline conversion) — see [FEATURES.md](./FEATURES.md) (“Arbitrary format transcoding”, planned);
+- Reduce package size (maybe implement `ttf2woff2` with a native JS library);
 - Improve performance (maybe use cache for this).
 
 ## Contribution
@@ -482,6 +746,10 @@ Feel free to push your code if you agree with publishing under the MIT license.
 
 Check our [Changelog](CHANGELOG.md)
 
+## Legal notice
+
+Copyright, disclaimers, font licensing expectations (including WOFF/WOFF2 decompression), community attribution guidelines, and third-party open-source dependencies are documented in **[NOTICE.md](./NOTICE.md)**.
+
 ## License
 
-Check our [License](LICENSE)
+The **webfont software** is licensed under the [MIT License](./LICENSE). That license does **not** apply to fonts or icons you process with the tool — see [NOTICE.md](./NOTICE.md).

package/dist/browser.js

@@ -0,0 +1,4 @@
+//#region src/browser.ts
+var e = () => Promise.reject(/* @__PURE__ */ Error("webfont is Node.js-only (requires fs, globby, and other Node built-ins). Run it at build time via the CLI, a Node script, or the webfont-webpack-plugin — do not import it from client-side React/Vue code. See TROUBLESHOOTING.md (Can't resolve 'fs')."));
+//#endregion
+export { e as default, e as webfont };