@turntrout/subfont 1.6.0 → 1.7.0

package/lib/subsetFonts.js

@@ -16,6 +16,7 @@ const unicodeRange = require('./unicodeRange');
 const getFontInfo = require('./getFontInfo');
 const collectTextsByPage = require('./collectTextsByPage');
 
+const escapeJsStringLiteral = require('./escapeJsStringLiteral');
 const {
   maybeCssQuote,
   getFontFaceDeclarationText,
@@ -55,18 +56,6 @@ function getParents(asset, assetQuery) {
   return parents;
 }
 
-// Escape a value for safe inclusion in any JS string context (single-quoted,
-// double-quoted, or template literal). Uses JSON.stringify for robust escaping
-// of backslashes, quotes, newlines, U+2028, U+2029, etc.
-// The < escape prevents </script> from closing an inline script tag.
-function escapeJsStringLiteral(str) {
-  return JSON.stringify(str)
-    .slice(1, -1)
-    .replace(/'/g, "\\'")
-    .replace(/`/g, '\\x60')
-    .replace(/</g, '\\x3c');
-}
-
 function countUniqueFontUrls(htmlOrSvgAssetTextsWithProps) {
   const urls = new Set();
   for (const item of htmlOrSvgAssetTextsWithProps) {
@@ -225,8 +214,8 @@ const validFontDisplayValues = [
 
 const warnAboutMissingGlyphs = require('./warnAboutMissingGlyphs');
 
-// Extract subset CSS asset creation/caching into a standalone function
-// to reduce cyclomatic complexity of the main injection loop.
+// Create (or retrieve from disk cache) the subset CSS asset for a set of
+// fontUsages, relocating the font binary to its hashed URL under subsetUrl.
 async function getOrCreateSubsetCssAsset({
   assetGraph,
   subsetCssText,
@@ -322,7 +311,8 @@ async function getOrCreateSubsetCssAsset({
   return cssAsset;
 }
 
-// Extract subset font preload insertion to reduce injection loop complexity.
+// Insert <link rel="preload"> hints for every woff2 subset flagged as
+// preload-worthy, so the browser starts fetching them during HTML parse.
 function addSubsetFontPreloads({
   cssAsset,
   fontUsages,
@@ -373,6 +363,104 @@ function addSubsetFontPreloads({
   return insertionPoint;
 }
 
+// Skip Google Fonts populate when no Google Fonts references exist —
+// otherwise assetgraph spends ~30s network-walking for nothing on sites
+// that only self-host. Returns whether the populate ran so callers can
+// annotate their phase timing.
+async function populateGoogleFontsIfPresent(assetGraph) {
+  const hasGoogleFonts =
+    assetGraph.findRelations({
+      to: { url: { $regex: googleFontsCssUrlRegex } },
+    }).length > 0;
+  if (!hasGoogleFonts) return false;
+
+  await assetGraph.populate({
+    followRelations: {
+      $or: [
+        { to: { url: { $regex: googleFontsCssUrlRegex } } },
+        {
+          type: 'CssFontFaceSrc',
+          from: { url: { $regex: googleFontsCssUrlRegex } },
+        },
+      ],
+    },
+  });
+  return true;
+}
+
+// Strip every original @font-face rule when --no-fallbacks is set. The
+// severed assets are returned via the `potentiallyOrphanedAssets` set so
+// the final orphan sweep can remove anything left dangling.
+function removeOriginalFontFaceRules(
+  htmlOrSvgAssets,
+  fontFaceDeclarationsByHtmlOrSvgAsset,
+  potentiallyOrphanedAssets
+) {
+  for (const htmlOrSvgAsset of htmlOrSvgAssets) {
+    const accumulatedFontFaceDeclarations =
+      fontFaceDeclarationsByHtmlOrSvgAsset.get(htmlOrSvgAsset);
+    for (const { relations } of accumulatedFontFaceDeclarations) {
+      for (const relation of relations) {
+        potentiallyOrphanedAssets.add(relation.to);
+        if (relation.node.parentNode) {
+          relation.node.parentNode.removeChild(relation.node);
+        }
+        relation.remove();
+      }
+    }
+    htmlOrSvgAsset.markDirty();
+  }
+}
+
+// Rewrite CSS source-map relations to the caller's chosen hrefType so they
+// align with the rest of the emitted assets. Only invoked when sourceMaps is
+// enabled — subsetFonts normally skips source-map serialization for speed.
+async function rewriteCssSourceMaps(assetGraph, hrefType) {
+  await assetGraph.serializeSourceMaps(undefined, {
+    type: 'Css',
+    outgoingRelations: {
+      $where: (relations) =>
+        relations.some((relation) => relation.type === 'CssSourceMappingUrl'),
+    },
+  });
+  for (const relation of assetGraph.findRelations({
+    type: 'SourceMapSource',
+  })) {
+    relation.hrefType = hrefType;
+  }
+  for (const relation of assetGraph.findRelations({
+    type: 'CssSourceMappingUrl',
+    hrefType: { $in: ['relative', 'inline'] },
+  })) {
+    relation.hrefType = hrefType;
+  }
+}
+
+// Remove assets whose last incoming relation was severed during subset
+// injection (original @font-face rules, merged Google Fonts CSS, etc.) so
+// the emitted site doesn't ship with dangling files.
+function removeOrphanedAssets(assetGraph, potentiallyOrphanedAssets) {
+  for (const asset of potentiallyOrphanedAssets) {
+    if (asset.incomingRelations.length === 0) {
+      assetGraph.removeAsset(asset);
+    }
+  }
+}
+
+// Shape the per-page fontUsages into the external fontInfo report: strip
+// internal bookkeeping (subsets buffer, feature-tag scratch) and flatten
+// each page to { assetFileName, fontUsages }.
+function buildFontInfoReport(htmlOrSvgAssetTextsWithProps) {
+  return htmlOrSvgAssetTextsWithProps.map(({ fontUsages, htmlOrSvgAsset }) => ({
+    assetFileName: htmlOrSvgAsset.nonInlineAncestor.urlOrDescription,
+    fontUsages: fontUsages.map((fontUsage) =>
+      (({ subsets, hasFontFeatureSettings, fontFeatureTags, ...rest }) => rest)(
+        fontUsage
+      )
+    ),
+  }));
+}
+
 async function subsetFonts(
   assetGraph,
   {
@@ -415,34 +503,8 @@ async function subsetFonts(
   }
   timings.applySourceMaps = applySourceMapsPhase.end();
 
-  // Only run Google Fonts populate if there are actually Google Fonts
-  // references in the graph. This avoids ~30s of wasted work on sites
-  // that use only self-hosted fonts.
-  const hasGoogleFonts =
-    assetGraph.findRelations({
-      to: { url: { $regex: googleFontsCssUrlRegex } },
-    }).length > 0;
-
   const googlePopulatePhase = trackPhase('populate (google fonts)');
-  if (hasGoogleFonts) {
-    await assetGraph.populate({
-      followRelations: {
-        $or: [
-          {
-            to: {
-              url: { $regex: googleFontsCssUrlRegex },
-            },
-          },
-          {
-            type: 'CssFontFaceSrc',
-            from: {
-              url: { $regex: googleFontsCssUrlRegex },
-            },
-          },
-        ],
-      },
-    });
-  }
+  const hasGoogleFonts = await populateGoogleFontsIfPresent(assetGraph);
   timings['populate (google fonts)'] = googlePopulatePhase.end(
     hasGoogleFonts ? null : 'skipped, no Google Fonts found'
   );
@@ -478,26 +540,14 @@ async function subsetFonts(
   timings.collectTextsByPageDetails = subTimings;
 
   const omitFallbacksPhase = trackPhase('omitFallbacks processing');
-
   const potentiallyOrphanedAssets = new Set();
   if (omitFallbacks) {
-    for (const htmlOrSvgAsset of htmlOrSvgAssets) {
-      const accumulatedFontFaceDeclarations =
-        fontFaceDeclarationsByHtmlOrSvgAsset.get(htmlOrSvgAsset);
-      // Remove the original @font-face rules:
-      for (const { relations } of accumulatedFontFaceDeclarations) {
-        for (const relation of relations) {
-          potentiallyOrphanedAssets.add(relation.to);
-          if (relation.node.parentNode) {
-            relation.node.parentNode.removeChild(relation.node);
-          }
-          relation.remove();
-        }
-      }
-      htmlOrSvgAsset.markDirty();
-    }
+    removeOriginalFontFaceRules(
+      htmlOrSvgAssets,
+      fontFaceDeclarationsByHtmlOrSvgAsset,
+      potentiallyOrphanedAssets
+    );
   }
-
   timings['omitFallbacks processing'] = omitFallbacksPhase.end();
 
   const codepointPhase = trackPhase('codepoint generation');
@@ -652,22 +702,26 @@ async function subsetFonts(
 
   // Insert subsets:
 
-  // Pre-compute which fontUrls are used (with text) on every page,
-  // so we can avoid O(pages × fontUsages) checks inside the font loop.
+  // Pre-compute which fontUrls are used (with text) on every page.
+  // Set intersection: O(pages × fonts_per_page) vs the old every+some approach.
   const fontUrlsUsedOnEveryPage = new Set();
   if (htmlOrSvgAssetTextsWithProps.length > 0) {
-    // Start with all fontUrls from the first page
     const firstPageFontUrls = new Set();
     for (const fu of htmlOrSvgAssetTextsWithProps[0].fontUsages) {
       if (fu.pageText) firstPageFontUrls.add(fu.fontUrl);
     }
     for (const fontUrl of firstPageFontUrls) {
-      if (
-        htmlOrSvgAssetTextsWithProps.every(({ fontUsages }) =>
-          fontUsages.some((fu) => fu.pageText && fu.fontUrl === fontUrl)
-        )
-      ) {
-        fontUrlsUsedOnEveryPage.add(fontUrl);
+      fontUrlsUsedOnEveryPage.add(fontUrl);
+    }
+    for (let i = 1; i < htmlOrSvgAssetTextsWithProps.length; i++) {
+      const pageFontUrls = new Set();
+      for (const fu of htmlOrSvgAssetTextsWithProps[i].fontUsages) {
+        if (fu.pageText) pageFontUrls.add(fu.fontUrl);
+      }
+      for (const fontUrl of fontUrlsUsedOnEveryPage) {
+        if (!pageFontUrls.has(fontUrl)) {
+          fontUrlsUsedOnEveryPage.delete(fontUrl);
+        }
       }
     }
   }
@@ -676,6 +730,12 @@ async function subsetFonts(
   // addAsset/minify/removeAsset cycles for pages sharing identical CSS.
   const subsetCssAssetCache = new Map();
 
+  // Cache the heavy CSS-text assembly (including base64-encoded font data)
+  // keyed by the shared accumulatedFontFaceDeclarations array. Pages grouped
+  // under the same stylesheet config produce byte-identical output, so this
+  // collapses the per-page string build from O(pages) to O(unique configs).
+  const subsetCssTextCache = new WeakMap();
+
   // Pre-index relations by source asset to avoid O(allRelations) scans
   // in the per-page injection loop below. Build indices once, then use
   // O(1) lookups per page instead of repeated assetGraph.findRelations.
@@ -773,11 +833,19 @@ async function subsetFonts(
     }
     numFontUsagesWithSubset += subsetFontUsages.length;
 
-    let subsetCssText = getFontUsageStylesheet(subsetFontUsages);
-    const unusedVariantsCss = getUnusedVariantsStylesheet(
-      fontUsages,
-      accumulatedFontFaceDeclarations
-    );
+    let cssTextParts = subsetCssTextCache.get(accumulatedFontFaceDeclarations);
+    if (!cssTextParts) {
+      cssTextParts = {
+        subset: getFontUsageStylesheet(subsetFontUsages),
+        unused: getUnusedVariantsStylesheet(
+          fontUsages,
+          accumulatedFontFaceDeclarations
+        ),
+      };
+      subsetCssTextCache.set(accumulatedFontFaceDeclarations, cssTextParts);
+    }
+    let subsetCssText = cssTextParts.subset;
+    const unusedVariantsCss = cssTextParts.unused;
     if (!inlineCss && !omitFallbacks) {
       // This can go into the same stylesheet because we won't reload all __subset suffixed families in the JS preload fallback
       subsetCssText += unusedVariantsCss;
@@ -971,11 +1039,16 @@ async function subsetFonts(
 
   const googleCleanupPhase = trackPhase('Google Fonts + cleanup');
 
-  // Async load Google Web Fonts CSS
-  const googleFontStylesheets = assetGraph.findAssets({
-    type: 'Css',
-    url: { $regex: googleFontsCssUrlRegex },
-  });
+  // Async load Google Web Fonts CSS.  Skip the regex findAssets scan and
+  // the surrounding loop entirely when no Google Fonts were detected up
+  // front — the final detach loop below still runs because other phases
+  // (lazy fallback CSS) populate relationsToRemove.
+  const googleFontStylesheets = hasGoogleFonts
+    ? assetGraph.findAssets({
+        type: 'Css',
+        url: { $regex: googleFontsCssUrlRegex },
+      })
+    : [];
   const selfHostedGoogleCssByUrl = new Map();
   for (const googleFontStylesheet of googleFontStylesheets) {
     const seenPages = new Set(); // Only do the work once for each font on each page
@@ -1053,7 +1126,7 @@ async function subsetFonts(
 
   // Use subsets in font-family:
 
-  const webfontNameMap = {};
+  const webfontNameMap = Object.create(null);
 
   for (const { fontUsages } of htmlOrSvgAssetTextsWithProps) {
     for (const { subsets, fontFamilies, props } of fontUsages) {
@@ -1067,6 +1140,7 @@ async function subsetFonts(
   }
 
   let customPropertyDefinitions; // Avoid computing this unless necessary
+  const cssAssetsDirtiedByCustomProps = new Set();
   // Inject subset font name before original webfont in SVG font-family attributes
   const svgAssets = assetGraph.findAssets({ type: 'Svg' });
   for (const svgAsset of svgAssets) {
@@ -1105,7 +1179,10 @@ async function subsetFonts(
     type: 'Css',
     isLoaded: true,
   });
-  let changesMadeToCustomPropertyDefinitions = false;
+  const parseTreeToAsset = new Map();
+  for (const cssAsset of cssAssets) {
+    parseTreeToAsset.set(cssAsset.parseTree, cssAsset);
+  }
   for (const cssAsset of cssAssets) {
     let changesMade = false;
     cssAsset.eachRuleInParseTree((cssRule) => {
@@ -1133,7 +1210,10 @@ async function subsetFonts(
             );
             if (modifiedValue !== relatedCssRule.value) {
               relatedCssRule.value = modifiedValue;
-              changesMadeToCustomPropertyDefinitions = true;
+              const ownerAsset = parseTreeToAsset.get(relatedCssRule.root());
+              if (ownerAsset) {
+                cssAssetsDirtiedByCustomProps.add(ownerAsset);
+              }
             }
           }
         }
@@ -1190,60 +1270,23 @@ async function subsetFonts(
     }
   }
 
-  // This is a bit crude, could be more efficient if we tracked the containing asset in findCustomPropertyDefinitions
-  if (changesMadeToCustomPropertyDefinitions) {
-    for (const cssAsset of cssAssets) {
-      cssAsset.markDirty();
-    }
+  for (const dirtiedAsset of cssAssetsDirtiedByCustomProps) {
+    dirtiedAsset.markDirty();
   }
 
   timings['inject subset font-family'] = injectPhase.end();
 
   const orphanCleanupPhase = trackPhase('source maps + orphan cleanup');
   if (sourceMaps) {
-    await assetGraph.serializeSourceMaps(undefined, {
-      type: 'Css',
-      outgoingRelations: {
-        $where: (relations) =>
-          relations.some((relation) => relation.type === 'CssSourceMappingUrl'),
-      },
-    });
-    for (const relation of assetGraph.findRelations({
-      type: 'SourceMapSource',
-    })) {
-      relation.hrefType = hrefType;
-    }
-    for (const relation of assetGraph.findRelations({
-      type: 'CssSourceMappingUrl',
-      hrefType: { $in: ['relative', 'inline'] },
-    })) {
-      relation.hrefType = hrefType;
-    }
-  }
-
-  for (const asset of potentiallyOrphanedAssets) {
-    if (asset.incomingRelations.length === 0) {
-      assetGraph.removeAsset(asset);
-    }
+    await rewriteCssSourceMaps(assetGraph, hrefType);
   }
-
+  removeOrphanedAssets(assetGraph, potentiallyOrphanedAssets);
   timings['source maps + orphan cleanup'] = orphanCleanupPhase.end();
 
-  // Hand out some useful info about the detected subsets:
   return {
-    fontInfo: htmlOrSvgAssetTextsWithProps.map(
-      ({ fontUsages, htmlOrSvgAsset }) => ({
-        assetFileName: htmlOrSvgAsset.nonInlineAncestor.urlOrDescription,
-        fontUsages: fontUsages.map((fontUsage) =>
-          (({ subsets, hasFontFeatureSettings, fontFeatureTags, ...rest }) =>
-            rest)(fontUsage)
-        ),
-      })
-    ),
+    fontInfo: buildFontInfoReport(htmlOrSvgAssetTextsWithProps),
     timings,
   };
 }
 
 module.exports = subsetFonts;
-// Exported for testing
-module.exports._escapeJsStringLiteral = escapeJsStringLiteral;

package/lib/unquote.js

@@ -1,10 +1,15 @@
 function unescapeCssString(str) {
   return str.replace(
     /\\([0-9a-f]{1,6})(\s?)/gi,
-    ($0, hexChars, followingWhitespace) =>
-      `${String.fromCodePoint(parseInt(hexChars, 16))}${
-        hexChars.length === 6 ? followingWhitespace : ''
-      }`
+    ($0, hexChars, followingWhitespace) => {
+      try {
+        return `${String.fromCodePoint(parseInt(hexChars, 16))}${
+          hexChars.length === 6 ? followingWhitespace : ''
+        }`;
+      } catch {
+        return $0;
+      }
+    }
   );
 }
 

package/lib/warnAboutMissingGlyphs.js

@@ -42,6 +42,41 @@ async function warnAboutMissingGlyphs(
     accumulatedFontFaceDeclarations,
   } of htmlOrSvgAssetTextsWithProps) {
     let linesAndColumns;
+    // Dedupe scans for the same missing char across different fontUsages on
+    // this page. On KaTeX-heavy pages the same symbol is often missing in
+    // several font-families, and each scan is an O(N) walk of the HTML text.
+    const charLookupCache = new Map();
+    const lookupChar = (char) => {
+      let cached = charLookupCache.get(char);
+      if (cached) return cached;
+      let firstLocation;
+      let occurrences = 0;
+      if (char.length > 0) {
+        const sourceText = htmlOrSvgAsset.text;
+        let searchIdx = 0;
+        while (true) {
+          const charIdx = sourceText.indexOf(char, searchIdx);
+          if (charIdx === -1) break;
+          occurrences++;
+          if (occurrences === 1) {
+            if (!linesAndColumns) {
+              linesAndColumns = new LinesAndColumns(sourceText);
+            }
+            const position = linesAndColumns.locationForIndex(charIdx);
+            firstLocation = `${htmlOrSvgAsset.urlOrDescription}:${
+              position.line + 1
+            }:${position.column + 1}`;
+          }
+          searchIdx = charIdx + char.length;
+        }
+      }
+      if (!firstLocation) {
+        firstLocation = `${htmlOrSvgAsset.urlOrDescription} (generated content)`;
+      }
+      cached = { firstLocation, occurrences };
+      charLookupCache.set(char, cached);
+      return cached;
+    };
     for (const fontUsage of fontUsages) {
       if (!fontUsage.subsets) continue;
       const subsetBuffer = Object.values(fontUsage.subsets)[0];
@@ -63,31 +98,7 @@ async function warnAboutMissingGlyphs(
           // Report only the first location plus a count of remaining
           // occurrences. A character like U+200B can appear thousands of
           // times on a page and per-occurrence lines drown the log.
-          let firstLocation;
-          let occurrences = 0;
-          if (char.length > 0) {
-            const sourceText = htmlOrSvgAsset.text;
-            let searchIdx = 0;
-            while (true) {
-              const charIdx = sourceText.indexOf(char, searchIdx);
-              if (charIdx === -1) break;
-              occurrences++;
-              if (occurrences === 1) {
-                if (!linesAndColumns) {
-                  linesAndColumns = new LinesAndColumns(sourceText);
-                }
-                const position = linesAndColumns.locationForIndex(charIdx);
-                firstLocation = `${htmlOrSvgAsset.urlOrDescription}:${
-                  position.line + 1
-                }:${position.column + 1}`;
-              }
-              searchIdx = charIdx + char.length;
-            }
-          }
-
-          if (!firstLocation) {
-            firstLocation = `${htmlOrSvgAsset.urlOrDescription} (generated content)`;
-          }
+          const { firstLocation, occurrences } = lookupChar(char);
 
           missingGlyphsErrors.push({
             codePoint,

package/lib/wasmQueue.js

@@ -5,10 +5,14 @@
 let queue = Promise.resolve();
 
 function enqueue(fn) {
-  return (queue = queue.then(
+  // Chain fn after the previous task settles. Both handlers wrap fn() in
+  // an arrow to avoid leaking the previous result/error as an argument.
+  // The error handler ensures a prior rejection doesn't block the queue.
+  queue = queue.then(
     () => fn(),
     () => fn()
-  ));
+  );
+  return queue;
 }
 
 module.exports = enqueue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turntrout/subfont",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Automatically subset web fonts to only the characters used on your pages. Fork of Munter/subfont with modern defaults.",
   "engines": {
     "node": ">=18.0.0"
@@ -57,7 +57,6 @@
     "jsdom": "^25.0.0",
     "lines-and-columns": "^1.1.6",
     "memoizesync": "^1.1.1",
-    "p-limit": "^3.0.0",
     "parse5": "^7.0.0",
     "postcss": "^8.3.11",
     "postcss-value-parser": "^4.0.2",