@turntrout/subfont 1.6.0 → 1.7.0

package/README.md

@@ -55,27 +55,27 @@ subfont path/to/index.html -i --cache
 
 ## Options
 
-|               Flag | Default | Description                                                  |
-| -----------------: | :-----: | :----------------------------------------------------------- |
-|   `-i, --in-place` |   off   | Modify files in-place                                        |
-|     `-o, --output` |         | Output directory                                             |
-|           `--root` |         | Path to web root (deduced from input files if not specified) |
-| `--canonical-root` |         | URI root where the site will be deployed                     |
-|  `-r, --recursive` |   off   | Crawl linked pages                                           |
-|        `--dynamic` |   off   | Trace with headless browser                                  |
-|        `--dry-run` |   off   | Preview without writing                                      |
-|      `--fallbacks` |   on    | Load the full original font for characters not in the subset |
-|   `--font-display` | `swap`  | `auto`/`block`/`swap`/`fallback`/`optional`                  |
-|           `--text` |         | Extra characters for every subset                            |
-|    `--cache [dir]` |   off   | Cache subset results to disk between runs                    |
-|  `--concurrency N` |         | Max worker threads (capped by available memory, ~50 MB each) |
-|   `--chrome-flags` |         | Custom Chrome flags for `--dynamic`                          |
-|    `--source-maps` |   off   | Preserve CSS source maps (slower)                            |
-|         `--strict` |   off   | Exit non-zero if any warnings are emitted                    |
-|     `-s, --silent` |   off   | Suppress all console output                                  |
-|      `-d, --debug` |   off   | Verbose timing and font glyph detection info                 |
-|  `--relative-urls` |   off   | Emit relative URLs instead of root-relative                  |
-|     `--inline-css` |   off   | Inline the subset @font-face CSS into HTML                   |
+|               Flag | Default | Description                                                                           |
+| -----------------: | :-----: | :------------------------------------------------------------------------------------ |
+|   `-i, --in-place` |   off   | Modify files in-place                                                                 |
+|     `-o, --output` |         | Output directory                                                                      |
+|           `--root` |         | Path to web root (deduced from input files if not specified)                          |
+| `--canonical-root` |         | URI root where the site will be deployed                                              |
+|  `-r, --recursive` |   off   | Crawl linked pages                                                                    |
+|        `--dynamic` |   off   | Trace with headless browser                                                           |
+|        `--dry-run` |   off   | Preview without writing                                                               |
+|      `--fallbacks` |   on    | Async-load the full original font as a fallback for dynamic content                   |
+|   `--font-display` | `swap`  | `auto`/`block`/`swap`/`fallback`/`optional`                                           |
+|           `--text` |         | Extra characters for every subset                                                     |
+|    `--cache [dir]` |   off   | Cache subset results to disk between runs                                             |
+|  `--concurrency N` |  auto   | Max worker threads (defaults to CPU count, capped by available memory at ~50 MB each) |
+|   `--chrome-flags` |         | Custom Chrome flags for `--dynamic` (comma-separated)                                 |
+|    `--source-maps` |   off   | Preserve CSS source maps (slower)                                                     |
+|         `--strict` |   off   | Exit non-zero if any warnings are emitted                                             |
+|     `-s, --silent` |   off   | Suppress all console output                                                           |
+|      `-d, --debug` |   off   | Verbose timing and font glyph detection info                                          |
+|  `--relative-urls` |   off   | Emit relative URLs instead of root-relative                                           |
+|     `--inline-css` |   off   | Inline the subset @font-face CSS into HTML                                            |
 
 Run `subfont --help` for the full list.
 
@@ -113,28 +113,28 @@ with `log`, `warn`, and `error` methods — e.g. the global `console`). Pass
 
 The `options` object accepts the following keys:
 
-| Option          | Type                | Default  | Description                                                                                                  |
-| --------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
-| `inputFiles`    | `string[]`          | `[]`     | HTML entry points (file paths or URLs). At least one is required unless `root` is given.                     |
-| `root`          | `string`            | deduced  | Path or URL to the web root. Deduced from `inputFiles` if omitted.                                           |
-| `canonicalRoot` | `string`            | —        | URI root where the site will be deployed (used to rewrite absolute URLs).                                    |
-| `output`        | `string`            | —        | Output directory. Mutually exclusive with `inPlace`.                                                         |
-| `inPlace`       | `boolean`           | `false`  | Modify input files in place.                                                                                 |
-| `dryRun`        | `boolean`           | `false`  | Trace and compute subsets but do not write any files.                                                        |
-| `recursive`     | `boolean`           | `false`  | Crawl linked pages starting from `inputFiles`.                                                               |
-| `dynamic`       | `boolean`           | `false`  | Trace JS-rendered content in headless Chrome (via puppeteer).                                                |
-| `fallbacks`     | `boolean`           | `true`   | Keep the full original font for characters outside the subset.                                               |
-| `fontDisplay`   | `string`            | `'swap'` | `font-display` CSS value: `auto`, `block`, `swap`, `fallback`, or `optional`.                                |
-| `text`          | `string`            | —        | Extra characters to include in every subset.                                                                 |
-| `inlineCss`     | `boolean`           | `false`  | Inline the subset `@font-face` CSS into the HTML document.                                                   |
-| `relativeUrls`  | `boolean`           | `false`  | Emit relative URLs instead of root-relative URLs.                                                            |
-| `sourceMaps`    | `boolean`           | `false`  | Preserve CSS source maps (slower).                                                                           |
-| `concurrency`   | `number`            | auto     | Max parallel tracing workers. Capped by available memory (~50 MB per worker).                                |
-| `chromeFlags`   | `string[]`          | `[]`     | Extra Chrome flags forwarded to puppeteer when `dynamic` is set.                                             |
-| `cache`         | `boolean \| string` | `false`  | Cache subset results between runs. Pass a path to customize the cache directory; `true` uses the OS tmp dir. |
-| `strict`        | `boolean`           | `false`  | Resolve with a non-zero exit (via the CLI) if any warnings are emitted.                                      |
-| `silent`        | `boolean`           | `false`  | Suppress all log output to `console`.                                                                        |
-| `debug`         | `boolean`           | `false`  | Emit verbose timing and glyph-detection info.                                                                |
+| Option          | Type                | Default  | Description                                                                                                                                |
+| --------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `inputFiles`    | `string[]`          | `[]`     | HTML entry points (file paths or URLs). At least one is required unless `root` is given.                                                   |
+| `root`          | `string`            | deduced  | Path or URL to the web root. Deduced from `inputFiles` if omitted.                                                                         |
+| `canonicalRoot` | `string`            | —        | URI root where the site will be deployed (used to rewrite absolute URLs).                                                                  |
+| `output`        | `string`            | —        | Output directory. Mutually exclusive with `inPlace`.                                                                                       |
+| `inPlace`       | `boolean`           | `false`  | Modify input files in place.                                                                                                               |
+| `dryRun`        | `boolean`           | `false`  | Trace and compute subsets but do not write any files.                                                                                      |
+| `recursive`     | `boolean`           | `false`  | Crawl linked pages starting from `inputFiles`.                                                                                             |
+| `dynamic`       | `boolean`           | `false`  | Trace JS-rendered content in headless Chrome (via puppeteer).                                                                              |
+| `fallbacks`     | `boolean`           | `true`   | Async-load the full original font as a fallback for dynamic content.                                                                       |
+| `fontDisplay`   | `string`            | `'swap'` | `font-display` CSS value: `auto`, `block`, `swap`, `fallback`, or `optional`.                                                              |
+| `text`          | `string`            | —        | Extra characters to include in every subset.                                                                                               |
+| `inlineCss`     | `boolean`           | `false`  | Inline the subset `@font-face` CSS into the HTML document.                                                                                 |
+| `relativeUrls`  | `boolean`           | `false`  | Emit relative URLs instead of root-relative URLs.                                                                                          |
+| `sourceMaps`    | `boolean`           | `false`  | Preserve CSS source maps (slower).                                                                                                         |
+| `concurrency`   | `number`            | auto     | Max parallel tracing workers. Defaults to CPU count, capped by available memory (~50 MB per worker).                                       |
+| `chromeFlags`   | `string[]`          | `[]`     | Extra Chrome flags forwarded to puppeteer when `dynamic` is set.                                                                           |
+| `cache`         | `boolean \| string` | `false`  | Cache subset results between runs. Pass a path to customize the cache directory; `true` uses `.subfont-cache` inside the `root` directory. |
+| `strict`        | `boolean`           | `false`  | Resolve with a non-zero exit (via the CLI) if any warnings are emitted.                                                                    |
+| `silent`        | `boolean`           | `false`  | Suppress all log output to `console`.                                                                                                      |
+| `debug`         | `boolean`           | `false`  | Emit verbose timing and glyph-detection info.                                                                                              |
 
 ## License
 

package/lib/FontTracerPool.js

@@ -5,14 +5,18 @@ const { Worker } = require('worker_threads');
  * Worker pool for running fontTracer in parallel across pages.
  * Each worker re-parses HTML with jsdom and runs fontTracer independently.
  */
+const DEFAULT_TASK_TIMEOUT_MS = 60_000;
+
 class FontTracerPool {
-  constructor(numWorkers) {
+  constructor(numWorkers, { taskTimeoutMs = DEFAULT_TASK_TIMEOUT_MS } = {}) {
     this._workerPath = pathModule.join(__dirname, 'fontTracerWorker.js');
     this._numWorkers = numWorkers;
+    this._taskTimeoutMs = taskTimeoutMs;
     this._workers = [];
     this._idle = [];
     this._pendingTasks = [];
     this._taskCallbacks = new Map();
+    this._taskTimers = new Map();
     this._taskByWorker = new Map(); // track which taskId each worker is processing
     this._nextTaskId = 0;
   }
@@ -46,8 +50,17 @@ class FontTracerPool {
     await Promise.all(initPromises);
   }
 
+  _clearTaskTimer(taskId) {
+    const timer = this._taskTimers.get(taskId);
+    if (timer) {
+      clearTimeout(timer);
+      this._taskTimers.delete(taskId);
+    }
+  }
+
   _onWorkerMessage(worker, msg) {
     this._taskByWorker.delete(worker);
+    this._clearTaskTimer(msg.taskId);
     const cb = this._taskCallbacks.get(msg.taskId);
     if (cb) {
       this._taskCallbacks.delete(msg.taskId);
@@ -78,6 +91,7 @@ class FontTracerPool {
       const taskId = this._taskByWorker.get(worker);
       this._taskByWorker.delete(worker);
       if (taskId !== undefined) {
+        this._clearTaskTimer(taskId);
         const cb = this._taskCallbacks.get(taskId);
         if (cb) {
           this._taskCallbacks.delete(taskId);
@@ -101,6 +115,33 @@ class FontTracerPool {
     }
   }
 
+  _startTaskTimer(taskId) {
+    if (this._taskTimeoutMs <= 0) return;
+    const timer = setTimeout(() => {
+      this._taskTimers.delete(taskId);
+      const cb = this._taskCallbacks.get(taskId);
+      if (cb) {
+        this._taskCallbacks.delete(taskId);
+        cb.reject(
+          new Error(
+            `Font tracing task ${taskId} timed out after ${this._taskTimeoutMs}ms`
+          )
+        );
+      }
+      // Terminate the hung worker so it doesn't permanently consume a pool
+      // slot. _onWorkerExit will remove it from _workers and _idle.
+      for (const [worker, tid] of this._taskByWorker) {
+        if (tid === taskId) {
+          this._taskByWorker.delete(worker);
+          worker.terminate();
+          break;
+        }
+      }
+    }, this._taskTimeoutMs);
+    timer.unref();
+    this._taskTimers.set(taskId, timer);
+  }
+
   _dispatchPending() {
     while (this._idle.length > 0 && this._pendingTasks.length > 0) {
       const worker = this._idle.pop();
@@ -108,6 +149,7 @@ class FontTracerPool {
       this._taskByWorker.set(worker, task.message.taskId);
       try {
         worker.postMessage(task.message);
+        this._startTaskTimer(task.message.taskId);
       } catch (err) {
         // postMessage can fail synchronously (e.g. structured clone error).
         // Return the worker to the idle pool and reject the task.
@@ -149,6 +191,12 @@ class FontTracerPool {
   }
 
   async destroy() {
+    // Clear all task timers
+    for (const timer of this._taskTimers.values()) {
+      clearTimeout(timer);
+    }
+    this._taskTimers.clear();
+
     // Reject any tasks still waiting in the queue
     for (const task of this._pendingTasks) {
       const cb = this._taskCallbacks.get(task.message.taskId);

package/lib/HeadlessBrowser.js

@@ -13,8 +13,12 @@ async function transferResults(jsHandle) {
   const results = await jsHandle.jsonValue();
   for (const [i, result] of results.entries()) {
     const resultHandle = await jsHandle.getProperty(String(i));
-    const elementHandle = await resultHandle.getProperty('node');
-    result.node = elementHandle;
+    try {
+      const elementHandle = await resultHandle.getProperty('node');
+      result.node = elementHandle;
+    } finally {
+      await resultHandle.dispose();
+    }
   }
   return results;
 }
@@ -193,7 +197,11 @@ class HeadlessBrowser {
         /* istanbul ignore next */
         () => fontTracer(document)
       );
-      return await transferResults(jsHandle);
+      try {
+        return await transferResults(jsHandle);
+      } finally {
+        await jsHandle.dispose();
+      }
     } finally {
       await page.close();
     }