@turntrout/subfont 1.7.0 → 1.8.0

package/CLAUDE.md

@@ -7,25 +7,29 @@ subfont is a CLI tool and Node.js library that speeds up initial page paint by a
 ## Development Commands
 
 ```bash
-pnpm install          # Install dependencies
-pnpm test             # Run mocha tests + lint
-pnpm run lint         # ESLint + Prettier check
-pnpm run coverage     # Run tests with nyc coverage
+pnpm install             # Install dependencies
+pnpm run build           # Compile TypeScript (src/ → lib/)
+pnpm test                # Build + run mocha tests + lint
+pnpm run lint            # ESLint + Prettier check
+pnpm run typecheck       # TypeScript type checking (no emit)
+pnpm run coverage        # Run tests with nyc coverage
 pnpm run check-coverage  # Verify coverage thresholds
 ```
 
 ## Code Style
 
+- **Language**: TypeScript (strict mode, ES2022 target, CommonJS output)
 - **Formatter**: Prettier with single quotes, trailing commas (es5)
-- **Linter**: ESLint via neostandard + eslint-config-prettier
-- **Rules**: `prefer-template`, `prefer-const` (destructuring: all)
+- **Linter**: ESLint via neostandard + eslint-config-prettier + typescript-eslint
+- **Rules**: `prefer-template`, `prefer-const` (destructuring: all), `@typescript-eslint/no-explicit-any` (error in .ts files)
 - **Tests**: Mocha with `unexpected` assertion library (not chai/jest)
 - No exclusive tests (`describe.only`, `it.only`) — enforced by eslint-plugin-mocha
 
 ## Project Structure
 
-- `lib/` — Source code (entry: `lib/subfont.js`, CLI: `lib/cli.js`)
-- `test/` — Mocha test files
+- `src/` — TypeScript source code (entry: `src/subfont.ts`, CLI: `src/cli.ts`)
+- `lib/` — Compiled JavaScript output (generated by `tsc`, not checked in)
+- `test/` — Mocha test files (JavaScript, run against compiled `lib/`)
 - `testdata/` — HTML fixtures and font files for tests
 - `cases/` — Additional test case data
 
@@ -34,20 +38,42 @@ pnpm run check-coverage  # Verify coverage thresholds
 - Built on **assetgraph** for HTML/CSS asset graph traversal
 - Uses **puppeteer-core** for headless browser font tracing
 - **font-tracer** traces which fonts are used on each page
-- **harfbuzzjs** for WOFF2 subsetting (via direct WASM calls in `lib/subsetFontWithGlyphs.js`)
-- `lib/subsetFonts.js` — Main orchestration logic
-- `lib/FontTracerPool.js` — Manages puppeteer browser pool for parallel tracing
+- **harfbuzzjs** for WOFF2 subsetting (via direct WASM calls in `src/subsetFontWithGlyphs.ts`)
+- `src/collectTextsByPage.ts` — Font text collection and tracing orchestration
+- `src/subsetGeneration.ts` — Subset generation with disk caching
+- `src/FontTracerPool.ts` — Worker thread pool for parallel font tracing
 
 ## Testing Notes
 
 - Tests have a 5-minute timeout (configured in `.mocharc.yml`)
 - Tests use `httpception` for HTTP mocking and `unexpected` for assertions
 - Some tests require puppeteer browser binaries (installed via `pnpm install`)
-- Coverage thresholds are enforced via `nyc check-coverage`
+- Coverage thresholds: branches 70%, lines 80%, functions 75%, statements 80%
+- Coverage excludes: `lib/cli.js`, `lib/fontConverterWorker.js`, `lib/fontTracerWorker.js`
 
 ## Conventions
 
-- CommonJS modules (`require`/`module.exports`), not ESM
+- TypeScript source in `src/`, compiled to CommonJS in `lib/`
 - Node.js >= 18 required
 - Use `const` by default; `let` only when reassignment is needed
 - Template literals preferred over string concatenation
+
+## Subset-size efficiency improvements
+
+Whenever you change anything that affects subset output bytes (new
+`hb_subset_input_set` knob, new `DROP_TABLE_TAGS` entry, new flag, new
+gating heuristic, etc.):
+
+1. Re-run `pnpm run build && node scripts/bench-readme.js` (compares
+   against the `subset-font` package upstream Munter/subfont uses) and
+   paste the printed Markdown rows into the README's "Upstream subfont
+   vs `@turntrout/subfont`" table, replacing the previous numbers.
+2. Add the new optimization to the README's optimization-techniques table
+   (one row per knob: name, one-line explanation, gating condition if any).
+3. Bump `SUBSET_CACHE_VERSION` in `src/subsetGeneration.ts` if the change
+   affects bytes deterministically. Skip the bump if the change is purely
+   defensive (e.g. removing a no-op).
+4. Add a regression test in `test/subsetSizeBenchmarks.js` with a hard
+   upper bound on output size for at least one font that exercises the
+   new path. Bound values get bumped only after confirming a regression
+   isn't a real loss.

package/README.md

@@ -2,26 +2,30 @@
 
 [![Build Status](https://github.com/alexander-turner/subfont/actions/workflows/ci.yml/badge.svg)](https://github.com/alexander-turner/subfont/actions/workflows/ci.yml)
 
-A faster fork of [subfont](https://github.com/Munter/subfont) that subsets web fonts to only the characters used on your pages. Adds parallel tracing, disk caching, woff2-only output, and always-on variable font instancing. On [`turntrout.com`](https://github.com/alexander-turner/TurnTrout.com) (382 pages, 20+ font variants), switching to this fork cut font subsetting from [111 minutes](https://github.com/alexander-turner/TurnTrout.com/actions/runs/23470135763) to [28 minutes](https://github.com/alexander-turner/TurnTrout.com/actions/runs/23518006824).
+A faster fork of [subfont](https://github.com/Munter/subfont) that subsets web fonts to only the characters used on your pages. Adds parallel tracing, disk caching, woff2-only output, always-on variable font instancing, and is fully written in TypeScript (the upstream is JavaScript). On [`turntrout.com`](https://github.com/alexander-turner/TurnTrout.com) (382 pages, 20+ font variants), switching to this fork cut font subsetting from [111 minutes](https://github.com/alexander-turner/TurnTrout.com/actions/runs/23470135763) to [28 minutes](https://github.com/alexander-turner/TurnTrout.com/actions/runs/23518006824).
 
 ### Aggressive woff2 subsetting
 
-subfont produces dramatically smaller font files by stripping data that browsers never use:
+`subfont` produces dramatically smaller font files by stripping data that browsers never use:
 
-| Optimization                | Technique                                                                          |
-| --------------------------- | ---------------------------------------------------------------------------------- |
-| Hinting removal             | Strips TrueType hinting instructions (browsers auto-hint)                          |
-| Name table pruning          | Keeps only the 4 IDs browsers read (family, subfamily, full name, PostScript name) |
-| Table stripping             | Drops DSIG, LTSH, VDMX, hdmx, gasp, PCLT                                           |
-| CSS-aware feature filtering | Only collects alternate glyphs for OpenType features actually used in your CSS     |
+| Optimization                 | Technique                                                                               |
+| ---------------------------- | --------------------------------------------------------------------------------------- |
+| Hinting removal              | Strips TrueType hinting instructions (browsers auto-hint)                               |
+| Name table pruning           | Keeps only the 4 IDs browsers read (family, subfamily, full name, PostScript name)      |
+| Name lang-ID filter          | Keeps only en-US name strings; drops Japanese, Russian, Korean, etc.                    |
+| Table stripping              | Drops `DSIG`, `LTSH`, `VDMX`, `hdmx`, `gasp`, `PCLT`                                    |
+| MATH-table drop (gated)      | Drops `MATH` when no math codepoints are used on the page                               |
+| Color-table drop (gated)     | Drops `COLR`/`CPAL`/`SVG `/`CBDT`/`CBLC`/`sbix`/`EBDT`/`EBLC`/`EBSC` when no emoji used |
+| Layout-script filter (gated) | Drops GSUB/GPOS lookups for OpenType scripts the page doesn't render                    |
+| CSS-aware feature retention  | Drops GSUB/GPOS features the page's CSS doesn't reference                               |
 
-On the [`turntrout.com/design`](https://turntrout.com/design) page, a typical font subset (OpenSans, woff2) is **48-68% smaller** than a naive subset of the same glyphs:
+Reproducible benchmark on `testdata/subsetFonts/OpenSans-400.ttf` (run with `node scripts/bench-readme.js`); "upstream" = the [`subset-font`](https://github.com/papandreou/subset-font) package the original [Munter/subfont](https://github.com/Munter/subfont) uses, woff2-compressed:
 
-| Text sample       | Naive subset | subfont | Savings |
-| ----------------- | ------------ | ------- | ------- |
-| Heading (short)   | 2,604 B      | 824 B   | **68%** |
-| Paragraph         | 4,052 B      | 1,840 B | **55%** |
-| Full page charset | 5,268 B      | 2,716 B | **48%** |
+| Text sample       | Upstream subfont | `@turntrout/subfont` | Savings |
+| ----------------- | ---------------- | -------------------- | ------- |
+| Heading (short)   | 2,604 B          | 828 B                | **68%** |
+| Paragraph         | 4,448 B          | 2,072 B              | **53%** |
+| Full page charset | 9,388 B          | 5,500 B              | **41%** |
 
 ## Install
 
@@ -79,6 +83,12 @@ subfont path/to/index.html -i --cache
 
 Run `subfont --help` for the full list.
 
+### Environment variables
+
+| Variable                    | Description                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------ |
+| `PUPPETEER_EXECUTABLE_PATH` | Path to a Chrome/Chromium binary; skips auto-download when `--dynamic` is used |
+
 To include extra characters in a specific font's subset, add `-subfont-text` to its `@font-face`:
 
 ```css

package/lib/FontTracerPool.d.ts

@@ -0,0 +1,38 @@
+interface StylesheetWithPredicates {
+    text?: string;
+    asset?: {
+        text?: string;
+    };
+    predicates?: Record<string, unknown>;
+}
+interface FontTracerPoolOptions {
+    taskTimeoutMs?: number;
+}
+declare class FontTracerPool {
+    private _workerPath;
+    private _numWorkers;
+    private _taskTimeoutMs;
+    private _workers;
+    private _idle;
+    private _pendingTasks;
+    private _taskCallbacks;
+    private _taskTimers;
+    private _taskByWorker;
+    private _nextTaskId;
+    constructor(numWorkers: number, { taskTimeoutMs }?: FontTracerPoolOptions);
+    init(): Promise<void>;
+    private _onWorkerError;
+    private _clearTaskTimer;
+    private _onWorkerMessage;
+    private _onWorkerExit;
+    private _startTaskTimer;
+    private _dispatchPending;
+    /**
+     * Run fontTracer on the given HTML text + stylesheets in a worker.
+     * Returns a promise that resolves to textByProps.
+     */
+    trace(htmlText: string, stylesheetsWithPredicates: StylesheetWithPredicates[]): Promise<unknown>;
+    destroy(): Promise<void>;
+}
+export = FontTracerPool;
+//# sourceMappingURL=FontTracerPool.d.ts.map

package/lib/FontTracerPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FontTracerPool.d.ts","sourceRoot":"","sources":["../src/FontTracerPool.ts"],"names":[],"mappings":"AAkBA,UAAU,wBAAwB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAI1B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAqCD,UAAU,qBAAqB;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,cAAM,cAAc;IAClB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,WAAW,CAAS;gBAG1B,UAAU,EAAE,MAAM,EAClB,EAAE,aAAuC,EAAE,GAAE,qBAA0B;IAcnE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC3B,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,aAAa;IAsCrB,OAAO,CAAC,eAAe;IA2BvB,OAAO,CAAC,gBAAgB;IAsBxB;;;OAGG;IAGH,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,yBAAyB,EAAE,wBAAwB,EAAE,GAEpD,OAAO,CAAC,OAAO,CAAC;IAsBb,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA4C/B;AAED,SAAS,cAAc,CAAC"}