webfont 12.2.0 → 12.4.0

package/README.md

@@ -16,7 +16,7 @@ See **[FEATURES.md](./FEATURES.md)** for the canonical capability list (what is
 ## Features
 
 - **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);
+- **TTF encoding**: one or more `.ttf` files → `ttf` (pass-through), `svg` (SVG font), `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/));
@@ -30,7 +30,7 @@ webfont runs one of three pipelines depending on matched input files. They canno
 | 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. |
+| **TTF encoding** | One or more `.ttf` files | `ttf`, `svg` (SVG font), `eot`, `woff`, and/or `woff2` per input | Auto-detected. Default when SVG-pipeline `formats` are still configured: `woff` + `woff2` (`svg` is opt-in). 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**
@@ -157,6 +157,13 @@ const subset = await webfont({
   formats: ["woff2"],
 });
 
+// TTF → SVG font (legacy format; opt-in, pure JS via fonteditor-core)
+const svgFont = await webfont({
+  files: "path/to/font.ttf",
+  formats: ["svg"],
+});
+// svgFont.svg → SVG font as a string
+
 // Batch: multiple TTF files in one run
 const batch = await webfont({
   files: ["fonts/Inter-Regular.ttf", "fonts/Inter-Bold.ttf"],
@@ -190,6 +197,71 @@ const remote = await webfont({
 });
 ```
 
+### Autohinting
+
+webfont does not bundle a hinting engine — [`ttfautohint`](https://www.freetype.org/ttfautohint/) is a native binary, so it stays out of the core install. Run it yourself through the [`ttfPostProcess`](#ttfpostprocess) hook: it receives the generated **TTF before** WOFF/WOFF2/EOT are derived, so the hinted outlines flow into every format.
+
+**Option A — npm wrapper (no system install).** The [`ttfautohint`](https://www.npmjs.com/package/ttfautohint) package ships a prebuilt binary and a Buffer API:
+
+```bash
+npm i -D ttfautohint
+```
+
+```js
+import { webfont } from "webfont";
+import TTFAutohint from "ttfautohint";
+
+await webfont({
+  files: "src/svg-icons/**/*.svg",
+  formats: ["ttf", "woff", "woff2", "eot"],
+  // `icon: true` applies icon-font-tuned hinting metrics
+  ttfPostProcess: (ttf) => TTFAutohint.transform(ttf, { icon: true }),
+});
+```
+
+`TTFAutohint.transform(buffer, options)` returns the hinted `Buffer`, which webfont uses as the TTF and as the source for the other formats.
+
+**Option B — system binary (no extra npm dependency).** If `ttfautohint` is already installed (Homebrew, apt, …), pipe the buffer through it:
+
+```js
+import { execFileSync } from "node:child_process";
+import { webfont } from "webfont";
+
+const autohint = (ttf) =>
+  execFileSync("ttfautohint", ["-W", "-i", "-s", "-x", "24", "-l", "12", "-r", "48"], {
+    input: ttf,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+await webfont({
+  files: "src/svg-icons/**/*.svg",
+  formats: ["ttf", "woff2"],
+  ttfPostProcess: (ttf) => autohint(ttf),
+});
+```
+
+**CLI.** Flags can't carry a function, but webfont loads a JS config via cosmiconfig — put the hook in `webfont.config.js`:
+
+```js
+// webfont.config.js
+const TTFAutohint = require("ttfautohint");
+
+module.exports = {
+  files: "src/svg-icons/**/*.svg",
+  formats: ["ttf", "woff2"],
+  ttfPostProcess: (ttf) => TTFAutohint.transform(ttf, { icon: true }),
+};
+```
+
+then run `webfont`.
+
+Notes:
+
+- The hook is **opt-in**; webfont core stays free of native dependencies.
+- CI must have the binary available — the npm wrapper installs one; the system-binary option requires `ttfautohint` on `PATH`.
+- The callback may be async: return a `Promise<Buffer | Uint8Array>` if your tool is asynchronous.
+- See [#749](https://github.com/itgalaxy/webfont/issues/749) for autohinting tracking and a possible first-party companion package.
+
 ### Options
 
 #### `files`
@@ -227,7 +299,7 @@ const remote = await webfont({
 - 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.
+  - **TTF input**: `svg` (SVG font), `ttf`, `eot`, `woff`, and/or `woff2`. `svg` is **opt-in** (not in the default `woff` + `woff2` set); **`otf` is 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.
@@ -439,7 +511,7 @@ Do **not** use `Math.random()` in `fontName` — that renames both font files an
 
 - Type: `function`
 - Default: `undefined`
-- Description: Post-process the generated **TTF** buffer **after** it is built and **before** webfont derives WOFF/WOFF2/EOT from it (SVG pipeline only). The callback receives `(ttf, { fontName, formats })` and returns the new font bytes (`Buffer` or `Uint8Array`, sync or async). Every derived format is produced from the returned buffer. This is a **caller-owned** extension point — webfont bundles nothing here, so optional/native steps such as **autohinting** (`ttfautohint`) live in **your** project or a separate package, keeping the core free of native dependencies (same philosophy as [`glyphContentTransformFn`](#glyphcontenttransformfn) and [ADR 0011](docs/adr/0011-no-svg-outline-stroke-dependency.md); see [#749](https://github.com/itgalaxy/webfont/issues/749)).
+- Description: Post-process the generated **TTF** buffer **after** it is built and **before** webfont derives WOFF/WOFF2/EOT from it (SVG pipeline only). The callback receives `(ttf, { fontName, formats })` and returns the new font bytes (`Buffer` or `Uint8Array`, sync or async). Every derived format is produced from the returned buffer. This is a **caller-owned** extension point — webfont bundles nothing here, so optional/native steps such as **autohinting** (`ttfautohint`) live in **your** project or a separate package, keeping the core free of native dependencies (same philosophy as [`glyphContentTransformFn`](#glyphcontenttransformfn) and [ADR 0011](docs/adr/0011-no-svg-outline-stroke-dependency.md); see [#749](https://github.com/itgalaxy/webfont/issues/749)). See the [Autohinting](#autohinting) recipe for npm-wrapper, system-binary, and CLI variants.
 - Example (autohinting — **install the hinting tool in your app**, not in webfont):
 
   ```js
@@ -480,6 +552,24 @@ Do **not** use `Math.random()` in `fontName` — that renames both font files an
 
 `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.
 
+#### TypeScript
+
+`Result` and `ResultConfig` are exported from the package entry, so you can annotate `webfont()` output directly instead of relying on `ReturnType` inference:
+
+```ts
+import { webfont, type Result, type ResultConfig } from "webfont";
+
+const result: Result = await webfont({
+  files: "src/svg-icons/**/*.svg",
+});
+
+const config: ResultConfig | undefined = result.config;
+
+if (config?.filePath) {
+  console.log(`Loaded config from ${config.filePath}`);
+}
+```
+
 #### `result.config.filePath`
 
 - Type: `string` | `undefined`