@turntrout/subfont 1.6.0 → 1.7.1

package/lib/collectTextsByPage.js

@@ -41,7 +41,6 @@ const fontFaceTraversalTypes = new Set(['HtmlStyle', 'SvgStyle', 'CssImport']);
 const MIN_PAGES_FOR_WORKER_POOL = 4;
 
 const {
-  extractFeatureTagsFromDecl,
   findFontFamiliesWithFeatureSettings,
   resolveFeatureSettings,
 } = require('./fontFeatureHelpers');
@@ -167,9 +166,10 @@ function computeSnappedGlobalEntries(declarations, globalTextByProps) {
   return entries;
 }
 
-// Build global font usage templates and per-page indices from
-// snapped entries. Mutates the declCache entry for declKey in place.
-function getOrComputeGlobalFontUsages(
+// Fill in fontUsageTemplates/pageTextIndex/preloadIndex on the cached
+// declarations entry. No-op on repeat calls — results are shared across
+// pages that resolve to the same @font-face set.
+function populateGlobalFontUsages(
   cached,
   accumulatedFontFaceDeclarations,
   text
@@ -310,8 +310,9 @@ function getOrComputeGlobalFontUsages(
   cached.preloadIndex = textAndPropsToFontUrl;
 }
 
-// Extract font tracing (worker pool + sequential) to reduce
-// cyclomatic complexity of collectTextsByPage.
+// Trace fonts across the given pages. Uses a worker pool when the workload
+// justifies the thread-startup overhead; otherwise falls back to sequential
+// in-process tracing (required when a HeadlessBrowser is driving things).
 async function tracePages(
   pagesNeedingFullTrace,
   {
@@ -411,16 +412,15 @@ async function tracePages(
   }
 }
 
-// Extract fast-path text extraction to reduce collectTextsByPage complexity.
-// Pages sharing the same CSS configuration reuse the representative's
-// props and only extract visible text content.
+// For each page that shares a representative's CSS configuration, copy the
+// representative's font-variant props and overlay this page's visible text.
+// Returns the number of pages that had to fall back to a full trace
+// (because inline style attributes made the fast path unsafe).
 function processFastPathPages(
   fastPathPages,
-  { memoizedGetCssRulesByProperty, subTimings, trackPhase }
+  { memoizedGetCssRulesByProperty }
 ) {
-  if (fastPathPages.length === 0) return;
-
-  const fastPathPhase = trackPhase('Fast-path extraction');
+  if (fastPathPages.length === 0) return 0;
 
   const repDataCache = new Map();
   function getRepData(representativePd) {
@@ -528,234 +528,205 @@ function processFastPathPages(
       });
     }
   }
-  subTimings['Fast-path extraction'] = fastPathPhase.end(
-    `${fastPathPages.length} pages, ${fastPathFallbacks} fell back to full trace`
-  );
+  return fastPathFallbacks;
 }
 
-async function collectTextsByPage(
-  assetGraph,
-  htmlOrSvgAssets,
-  {
-    text,
-    console,
-    dynamic = false,
-    debug = false,
-    concurrency,
-    chromeArgs = [],
-  } = {}
-) {
-  const htmlOrSvgAssetTextsWithProps = [];
-
-  const memoizedGetCssRulesByProperty = memoizeSync(getCssRulesByProperty);
-
-  const fontFaceDeclarationsByHtmlOrSvgAsset = new Map();
-
-  // Cache stylesheet-dependent results for pages with identical CSS
-  // configurations.
-  const stylesheetResultCache = new Map();
-
-  // Pre-build an index of stylesheet-related relations by source asset
-  // to avoid repeated assetGraph.findRelations scans (O(allRelations) each).
-  const stylesheetRelTypes = [
-    'HtmlStyle',
-    'SvgStyle',
-    'CssImport',
-    'HtmlConditionalComment',
-    'HtmlNoscript',
-  ];
-  const stylesheetRelsByFromAsset = new Map();
+// Pre-build an index of stylesheet-related relations by source asset
+// to avoid repeated assetGraph.findRelations scans (O(allRelations) each).
+const STYLESHEET_REL_TYPES = [
+  'HtmlStyle',
+  'SvgStyle',
+  'CssImport',
+  'HtmlConditionalComment',
+  'HtmlNoscript',
+];
+
+function indexStylesheetRelations(assetGraph) {
+  const byFromAsset = new Map();
   for (const relation of assetGraph.findRelations({
-    type: {
-      $in: stylesheetRelTypes,
-    },
+    type: { $in: STYLESHEET_REL_TYPES },
   })) {
-    let arr = stylesheetRelsByFromAsset.get(relation.from);
+    let arr = byFromAsset.get(relation.from);
     if (!arr) {
       arr = [];
-      stylesheetRelsByFromAsset.set(relation.from, arr);
+      byFromAsset.set(relation.from, arr);
     }
     arr.push(relation);
   }
+  return byFromAsset;
+}
 
-  // Build a cache key by traversing stylesheet relations, capturing
-  // both asset identity and relation context (media, conditionalComment,
-  // noscript) that affect gatherStylesheetsWithPredicates output.
-  function buildStylesheetKey(htmlOrSvgAsset, skipNonFontInlineCss) {
-    const keyParts = [];
-    const visited = new Set();
-    (function traverse(asset, isNoscript) {
-      if (visited.has(asset)) return;
-      if (!asset.isLoaded) return;
-      visited.add(asset);
-      for (const relation of stylesheetRelsByFromAsset.get(asset) || []) {
-        if (relation.type === 'HtmlNoscript') {
-          traverse(relation.to, true);
-        } else if (relation.type === 'HtmlConditionalComment') {
-          keyParts.push(`cc:${relation.condition}`);
-          traverse(relation.to, isNoscript);
-        } else {
-          const target = relation.to;
-          if (
-            skipNonFontInlineCss &&
-            target.isInline &&
-            target.type === 'Css' &&
-            !fontRelevantCssRegex.test(target.text || '')
-          ) {
-            continue;
-          }
-          const media = relation.media || '';
-          keyParts.push(`${target.id}:${media}:${isNoscript ? 'ns' : ''}`);
-          traverse(target, isNoscript);
+// Build a cache key by traversing stylesheet relations, capturing
+// both asset identity and relation context (media, conditionalComment,
+// noscript) that affect gatherStylesheetsWithPredicates output.
+function buildStylesheetKey(
+  htmlOrSvgAsset,
+  skipNonFontInlineCss,
+  stylesheetRelsByFromAsset
+) {
+  const keyParts = [];
+  const visited = new Set();
+  (function traverse(asset, isNoscript) {
+    if (visited.has(asset)) return;
+    if (!asset.isLoaded) return;
+    visited.add(asset);
+    for (const relation of stylesheetRelsByFromAsset.get(asset) || []) {
+      if (relation.type === 'HtmlNoscript') {
+        traverse(relation.to, true);
+      } else if (relation.type === 'HtmlConditionalComment') {
+        keyParts.push(`cc:${relation.condition}`);
+        traverse(relation.to, isNoscript);
+      } else {
+        const target = relation.to;
+        if (
+          skipNonFontInlineCss &&
+          target.isInline &&
+          target.type === 'Css' &&
+          !fontRelevantCssRegex.test(target.text || '')
+        ) {
+          continue;
         }
+        const media = relation.media || '';
+        keyParts.push(`${target.id}:${media}:${isNoscript ? 'ns' : ''}`);
+        traverse(target, isNoscript);
       }
-    })(htmlOrSvgAsset, false);
-    return keyParts.join('\x1d');
-  }
-
-  function getOrComputeStylesheetResults(htmlOrSvgAsset) {
-    const key = buildStylesheetKey(htmlOrSvgAsset);
-    if (stylesheetResultCache.has(key)) {
-      return stylesheetResultCache.get(key);
     }
+  })(htmlOrSvgAsset, false);
+  return keyParts.join('\x1d');
+}
 
-    const stylesheetsWithPredicates = gatherStylesheetsWithPredicates(
-      htmlOrSvgAsset.assetGraph,
-      htmlOrSvgAsset,
-      stylesheetRelsByFromAsset
-    );
+// Walk the stylesheet graph rooted at htmlOrSvgAsset and collect every
+// @font-face declaration into a flat list, preserving the CSS relation node
+// so callers can correlate declarations back to their source rules.
+function collectFontFaceDeclarations(
+  htmlOrSvgAsset,
+  stylesheetRelsByFromAsset
+) {
+  const accumulatedFontFaceDeclarations = [];
+  const visitedAssets = new Set();
+  (function traverseForFontFace(asset) {
+    if (visitedAssets.has(asset)) return;
+    visitedAssets.add(asset);
+
+    if (asset.type === 'Css' && asset.isLoaded) {
+      const seenNodes = new Set();
+      const fontRelations = asset.outgoingRelations.filter(
+        (relation) => relation.type === 'CssFontFaceSrc'
+      );
 
-    // Compute accumulatedFontFaceDeclarations by traversing CSS relations
-    const accumulatedFontFaceDeclarations = [];
-    {
-      const visitedAssets = new Set();
-      (function traverseForFontFace(asset) {
-        if (visitedAssets.has(asset)) return;
-        visitedAssets.add(asset);
-
-        if (asset.type === 'Css' && asset.isLoaded) {
-          const seenNodes = new Set();
-          const fontRelations = asset.outgoingRelations.filter(
-            (relation) => relation.type === 'CssFontFaceSrc'
-          );
+      for (const fontRelation of fontRelations) {
+        const node = fontRelation.node;
+        if (seenNodes.has(node)) continue;
+        seenNodes.add(node);
 
-          for (const fontRelation of fontRelations) {
-            const node = fontRelation.node;
-            if (seenNodes.has(node)) continue;
-            seenNodes.add(node);
-
-            const fontFaceDeclaration = {
-              relations: fontRelations.filter((r) => r.node === node),
-              ...initialValueByProp,
-            };
-
-            node.walkDecls((declaration) => {
-              const propName = declaration.prop.toLowerCase();
-              fontFaceDeclaration[propName] =
-                propName === 'font-family'
-                  ? cssFontParser.parseFontFamily(declaration.value)[0]
-                  : declaration.value;
-            });
-            // Disregard incomplete @font-face declarations (must contain font-family and src per spec):
-            if (fontFaceDeclaration['font-family'] && fontFaceDeclaration.src) {
-              accumulatedFontFaceDeclarations.push(fontFaceDeclaration);
-            }
-          }
-        }
+        const fontFaceDeclaration = {
+          relations: fontRelations.filter((r) => r.node === node),
+          ...initialValueByProp,
+        };
 
-        // Traverse children using the pre-built index
-        const rels = stylesheetRelsByFromAsset.get(asset) || [];
-        for (const rel of rels) {
-          if (
-            fontFaceTraversalTypes.has(rel.type) ||
-            (rel.to && rel.to.type === 'Html' && rel.to.isInline)
-          ) {
-            traverseForFontFace(rel.to);
-          }
+        node.walkDecls((declaration) => {
+          const propName = declaration.prop.toLowerCase();
+          fontFaceDeclaration[propName] =
+            propName === 'font-family'
+              ? cssFontParser.parseFontFamily(declaration.value)[0]
+              : declaration.value;
+        });
+        // Disregard incomplete @font-face declarations (must contain font-family and src per spec):
+        if (fontFaceDeclaration['font-family'] && fontFaceDeclaration.src) {
+          accumulatedFontFaceDeclarations.push(fontFaceDeclaration);
         }
-      })(htmlOrSvgAsset);
-    }
-
-    // Group @font-face declarations that share family/style/weight but have
-    // different unicode-range values. Each group's members cover a disjoint
-    // subset of the Unicode space (common for CJK / large character-set fonts).
-    const comboGroups = new Map();
-    for (const fontFace of accumulatedFontFaceDeclarations) {
-      const comboKey = `${fontFace['font-family']}/${fontFace['font-style']}/${fontFace['font-weight']}`;
-      if (!comboGroups.has(comboKey)) comboGroups.set(comboKey, []);
-      comboGroups.get(comboKey).push(fontFace);
-    }
-    for (const [comboKey, group] of comboGroups) {
-      if (group.length <= 1) continue;
-      const withoutRange = group.filter((d) => !d['unicode-range']);
-      if (withoutRange.length > 0) {
-        throw new Error(
-          `Multiple @font-face with the same font-family/font-style/font-weight combo but missing unicode-range on ${withoutRange.length} of ${group.length} declarations: ${comboKey}`
-        );
       }
     }
 
-    const featureTagsByFamily = new Map();
-    const fontFamiliesWithFeatureSettings = findFontFamiliesWithFeatureSettings(
-      stylesheetsWithPredicates,
-      featureTagsByFamily
-    );
+    const rels = stylesheetRelsByFromAsset.get(asset) || [];
+    for (const rel of rels) {
+      if (
+        fontFaceTraversalTypes.has(rel.type) ||
+        (rel.to && rel.to.type === 'Html' && rel.to.isInline)
+      ) {
+        traverseForFontFace(rel.to);
+      }
+    }
+  })(htmlOrSvgAsset);
+  return accumulatedFontFaceDeclarations;
+}
 
-    const result = {
-      accumulatedFontFaceDeclarations,
-      stylesheetsWithPredicates,
-      fontFamiliesWithFeatureSettings,
-      featureTagsByFamily,
-      fastPathKey: buildStylesheetKey(htmlOrSvgAsset, true),
-    };
-    stylesheetResultCache.set(key, result);
-    return result;
+// Validate that @font-face declarations sharing family/style/weight carry
+// disjoint unicode-range values; throws on incomplete coverage.
+function validateFontFaceComboCoverage(accumulatedFontFaceDeclarations) {
+  const comboGroups = new Map();
+  for (const fontFace of accumulatedFontFaceDeclarations) {
+    const comboKey = `${fontFace['font-family']}/${fontFace['font-style']}/${fontFace['font-weight']}`;
+    if (!comboGroups.has(comboKey)) comboGroups.set(comboKey, []);
+    comboGroups.get(comboKey).push(fontFace);
+  }
+  for (const [comboKey, group] of comboGroups) {
+    if (group.length <= 1) continue;
+    const withoutRange = group.filter((d) => !d['unicode-range']);
+    if (withoutRange.length > 0) {
+      throw new Error(
+        `Multiple @font-face with the same font-family/font-style/font-weight combo but missing unicode-range on ${withoutRange.length} of ${group.length} declarations: ${comboKey}`
+      );
+    }
   }
+}
 
-  const headlessBrowser =
-    dynamic && new HeadlessBrowser({ console, chromeArgs });
-  const globalTextByProps = [];
-  const subTimings = {};
+function computeStylesheetResults(htmlOrSvgAsset, stylesheetRelsByFromAsset) {
+  const stylesheetsWithPredicates = gatherStylesheetsWithPredicates(
+    htmlOrSvgAsset.assetGraph,
+    htmlOrSvgAsset,
+    stylesheetRelsByFromAsset
+  );
 
-  const trackPhase = makePhaseTracker(console, debug);
-  const overallPhase = trackPhase('collectTextsByPage');
+  const accumulatedFontFaceDeclarations = collectFontFaceDeclarations(
+    htmlOrSvgAsset,
+    stylesheetRelsByFromAsset
+  );
+  validateFontFaceComboCoverage(accumulatedFontFaceDeclarations);
 
-  // Pre-compute stylesheet results for all pages
-  const stylesheetPrecompute = trackPhase('Stylesheet precompute');
-  const pageData = [];
-  for (const htmlOrSvgAsset of htmlOrSvgAssets) {
-    const {
-      accumulatedFontFaceDeclarations,
-      stylesheetsWithPredicates,
-      fontFamiliesWithFeatureSettings,
-      featureTagsByFamily,
-      fastPathKey,
-    } = getOrComputeStylesheetResults(htmlOrSvgAsset);
-    fontFaceDeclarationsByHtmlOrSvgAsset.set(
+  const featureTagsByFamily = new Map();
+  const fontFamiliesWithFeatureSettings = findFontFamiliesWithFeatureSettings(
+    stylesheetsWithPredicates,
+    featureTagsByFamily
+  );
+
+  return {
+    accumulatedFontFaceDeclarations,
+    stylesheetsWithPredicates,
+    fontFamiliesWithFeatureSettings,
+    featureTagsByFamily,
+    fastPathKey: buildStylesheetKey(
       htmlOrSvgAsset,
-      accumulatedFontFaceDeclarations
-    );
+      true,
+      stylesheetRelsByFromAsset
+    ),
+  };
+}
 
-    if (accumulatedFontFaceDeclarations.length === 0) {
-      continue;
-    }
+// Strip `-subfont-text` nodes from CSS @font-face declarations once the
+// subset planning is done, so they don't leak to the rendered output.
+function stripSubfontTextNodes(fontFaceDeclarationsByHtmlOrSvgAsset) {
+  for (const fontFaceDeclarations of fontFaceDeclarationsByHtmlOrSvgAsset.values()) {
+    for (const fontFaceDeclaration of fontFaceDeclarations) {
+      const firstRelation = fontFaceDeclaration.relations[0];
+      const subfontTextNode = firstRelation.node.nodes.find(
+        (childNode) =>
+          childNode.type === 'decl' &&
+          childNode.prop.toLowerCase() === '-subfont-text'
+      );
 
-    pageData.push({
-      htmlOrSvgAsset,
-      accumulatedFontFaceDeclarations,
-      stylesheetsWithPredicates,
-      fontFamiliesWithFeatureSettings,
-      featureTagsByFamily,
-      stylesheetCacheKey: fastPathKey,
-    });
+      if (subfontTextNode) {
+        subfontTextNode.remove();
+        firstRelation.from.markDirty();
+      }
+    }
   }
+}
 
-  subTimings['Stylesheet precompute'] = stylesheetPrecompute.end(
-    `${pageData.length} pages with fonts`
-  );
-
-  // Group pages by stylesheet cache key — pages sharing the same CSS
-  // configuration produce identical font-tracer props, only text differs.
+// Split trace work: with a headless browser every page needs a full trace
+// (dynamic content); otherwise one representative per stylesheet group is
+// traced and the rest use fast-path text extraction.
+function planTracing(pageData, hasHeadlessBrowser) {
   const pagesByStylesheetKey = new Map();
   for (const pd of pageData) {
     let group = pagesByStylesheetKey.get(pd.stylesheetCacheKey);
@@ -768,7 +739,7 @@ async function collectTextsByPage(
 
   const pagesNeedingFullTrace = [];
   const fastPathPages = [];
-  if (headlessBrowser) {
+  if (hasHeadlessBrowser) {
     for (const pd of pageData) {
       pagesNeedingFullTrace.push(pd);
     }
@@ -782,91 +753,37 @@ async function collectTextsByPage(
     }
   }
 
-  // Always surface the per-page work breakdown so users can tell at a
-  // glance how much of the run is actual tracing vs cheap CSS-group
-  // reuse. The threshold matches createPageProgress's minTotal so it
-  // only appears on non-trivial runs.
-  if (console && pageData.length >= 5) {
-    console.log(
-      `  ${pageData.length} pages with fonts: ${pagesNeedingFullTrace.length} to trace, ${fastPathPages.length} via cached CSS group (${pagesByStylesheetKey.size} unique groups)`
-    );
-  }
-
-  const tracingStart = Date.now();
-  const fullTracing = trackPhase(
-    `Full tracing (${pagesNeedingFullTrace.length} pages)`
-  );
-  try {
-    await tracePages(pagesNeedingFullTrace, {
-      headlessBrowser,
-      concurrency,
-      console,
-      memoizedGetCssRulesByProperty,
-      debug,
-    });
-
-    subTimings['Full tracing'] = fullTracing.end();
-
-    processFastPathPages(fastPathPages, {
-      memoizedGetCssRulesByProperty,
-      subTimings,
-      trackPhase,
-    });
-
-    const assemblePhase = trackPhase('Result assembly');
-    for (const pd of pageData) {
-      for (const textByPropsEntry of pd.textByProps) {
-        textByPropsEntry.htmlOrSvgAsset = pd.htmlOrSvgAsset;
-      }
-      // Use a loop instead of push(...spread) to avoid stack overflow on large sites
-      for (const entry of pd.textByProps) {
-        globalTextByProps.push(entry);
-      }
-      htmlOrSvgAssetTextsWithProps.push({
-        htmlOrSvgAsset: pd.htmlOrSvgAsset,
-        textByProps: pd.textByProps,
-        accumulatedFontFaceDeclarations: pd.accumulatedFontFaceDeclarations,
-        fontFamiliesWithFeatureSettings: pd.fontFamiliesWithFeatureSettings,
-        featureTagsByFamily: pd.featureTagsByFamily,
-      });
-    }
-    subTimings['Result assembly'] = assemblePhase.end();
-    if (debug && console) {
-      console.log(
-        `[subfont timing] Total tracing+extraction+assembly: ${
-          Date.now() - tracingStart
-        }ms`
-      );
-    }
-  } finally {
-    if (headlessBrowser) {
-      await headlessBrowser.close();
-    }
-  }
-
-  const postProcessPhase = trackPhase('Post-processing total');
+  return {
+    pagesNeedingFullTrace,
+    fastPathPages,
+    uniqueGroupCount: pagesByStylesheetKey.size,
+  };
+}
 
-  // Consolidated cache for per-declarations-key data.
+// Iterate every traced page, snap its text against the @font-face set, and
+// emit fully-formed per-page fontUsages (one entry per font URL + props).
+// Caching is per declarations-key (declCache) and per raw pageText
+// (uniqueCharsCache) so sites with many similar pages stay linear.
+function buildPerPageFontUsages(
+  htmlOrSvgAssetTextsWithProps,
+  globalTextByProps,
+  text
+) {
   const declCache = new Map();
-
-  const perPageLoopPhase = trackPhase('Per-page loop');
+  const uniqueCharsCache = new Map();
   let snappingTime = 0;
   let globalUsageTime = 0;
-
-  // Cache uniqueChars results by raw pageText string to avoid recomputing
-  const uniqueCharsCache = new Map();
   let cloningTime = 0;
 
-  for (const htmlOrSvgAssetTextsWithPropsEntry of htmlOrSvgAssetTextsWithProps) {
+  for (const entry of htmlOrSvgAssetTextsWithProps) {
     const {
       htmlOrSvgAsset,
       textByProps,
       accumulatedFontFaceDeclarations,
       fontFamiliesWithFeatureSettings,
       featureTagsByFamily,
-    } = htmlOrSvgAssetTextsWithPropsEntry;
+    } = entry;
 
-    // Get or compute the snapped global entries for this declarations set
     const declKey = getDeclarationsKey(accumulatedFontFaceDeclarations);
     if (!declCache.has(declKey)) {
       const snapStart = Date.now();
@@ -882,98 +799,260 @@ async function collectTextsByPage(
       snappingTime += Date.now() - snapStart;
     }
 
-    // Precompute global font usage templates and indices once per declarations key
     const declCacheEntry = declCache.get(declKey);
     const globalUsageStart = Date.now();
-    getOrComputeGlobalFontUsages(
+    populateGlobalFontUsages(
       declCacheEntry,
       accumulatedFontFaceDeclarations,
       text
     );
     globalUsageTime += Date.now() - globalUsageStart;
 
-    const fontUsageTemplates = declCacheEntry.fontUsageTemplates;
-    const pageTextIndex = declCacheEntry.pageTextIndex;
-    const textAndPropsToFontUrl = declCacheEntry.preloadIndex;
+    const {
+      fontUsageTemplates,
+      pageTextIndex,
+      preloadIndex: textAndPropsToFontUrl,
+    } = declCacheEntry;
 
-    // Compute preload per fontUrl using inverted index
     const preloadFontUrls = new Set();
-    for (const entry of textByProps) {
-      const fontUrl = textAndPropsToFontUrl.get(entry);
+    for (const textByPropsEntry of textByProps) {
+      const fontUrl = textAndPropsToFontUrl.get(textByPropsEntry);
       if (fontUrl) {
         preloadFontUrls.add(fontUrl);
       }
     }
 
-    // Build per-page fontUsages from precomputed templates
     const cloneStart = Date.now();
     const assetTexts = pageTextIndex.get(htmlOrSvgAsset);
-    htmlOrSvgAssetTextsWithPropsEntry.fontUsages = fontUsageTemplates.map(
-      (template) => {
-        const pageTexts = assetTexts
-          ? assetTexts.get(template.fontUrl)
-          : undefined;
-        let pageTextStr = pageTexts ? pageTexts.join('') : '';
-        if (template.extraTextsStr) {
-          pageTextStr += template.extraTextsStr;
-        }
+    entry.fontUsages = fontUsageTemplates.map((template) => {
+      const pageTexts = assetTexts
+        ? assetTexts.get(template.fontUrl)
+        : undefined;
+      let pageTextStr = pageTexts ? pageTexts.join('') : '';
+      if (template.extraTextsStr) {
+        pageTextStr += template.extraTextsStr;
+      }
 
-        let pageTextUnique = uniqueCharsCache.get(pageTextStr);
-        if (pageTextUnique === undefined) {
-          pageTextUnique = uniqueChars(pageTextStr);
-          uniqueCharsCache.set(pageTextStr, pageTextUnique);
-        }
+      let pageTextUnique = uniqueCharsCache.get(pageTextStr);
+      if (pageTextUnique === undefined) {
+        pageTextUnique = uniqueChars(pageTextStr);
+        uniqueCharsCache.set(pageTextStr, pageTextUnique);
+      }
 
-        const { hasFontFeatureSettings, fontFeatureTags } =
-          resolveFeatureSettings(
-            template.fontFamilies,
-            fontFamiliesWithFeatureSettings,
-            featureTagsByFamily
-          );
+      const { hasFontFeatureSettings, fontFeatureTags } =
+        resolveFeatureSettings(
+          template.fontFamilies,
+          fontFamiliesWithFeatureSettings,
+          featureTagsByFamily
+        );
 
-        return {
-          smallestOriginalSize: template.smallestOriginalSize,
-          smallestOriginalFormat: template.smallestOriginalFormat,
-          texts: template.texts,
-          pageText: pageTextUnique,
-          text: template.text,
-          props: { ...template.props },
-          fontUrl: template.fontUrl,
-          fontFamilies: template.fontFamilies,
-          fontStyles: template.fontStyles,
-          fontStretches: template.fontStretches,
-          fontWeights: template.fontWeights,
-          fontVariationSettings: template.fontVariationSettings,
-          preload: preloadFontUrls.has(template.fontUrl),
-          hasFontFeatureSettings,
-          fontFeatureTags,
-        };
-      }
-    );
+      return {
+        smallestOriginalSize: template.smallestOriginalSize,
+        smallestOriginalFormat: template.smallestOriginalFormat,
+        texts: template.texts,
+        pageText: pageTextUnique,
+        text: template.text,
+        props: { ...template.props },
+        fontUrl: template.fontUrl,
+        fontFamilies: template.fontFamilies,
+        fontStyles: template.fontStyles,
+        fontStretches: template.fontStretches,
+        fontWeights: template.fontWeights,
+        fontVariationSettings: template.fontVariationSettings,
+        preload: preloadFontUrls.has(template.fontUrl),
+        hasFontFeatureSettings,
+        fontFeatureTags,
+      };
+    });
     cloningTime += Date.now() - cloneStart;
   }
 
+  return { snappingTime, globalUsageTime, cloningTime };
+}
+
+// Run computeStylesheetResults once per page, memoizing the result across
+// pages that resolve to the same set of stylesheets. Pages without any
+// @font-face declarations are recorded in the declarations map but skipped
+// from pageData (nothing to trace or subset for them).
+function precomputeStylesheetsForPages(
+  htmlOrSvgAssets,
+  stylesheetRelsByFromAsset,
+  fontFaceDeclarationsByHtmlOrSvgAsset
+) {
+  const stylesheetResultCache = new Map();
+  const pageData = [];
+
+  for (const htmlOrSvgAsset of htmlOrSvgAssets) {
+    const key = buildStylesheetKey(
+      htmlOrSvgAsset,
+      false,
+      stylesheetRelsByFromAsset
+    );
+    let result = stylesheetResultCache.get(key);
+    if (!result) {
+      result = computeStylesheetResults(
+        htmlOrSvgAsset,
+        stylesheetRelsByFromAsset
+      );
+      stylesheetResultCache.set(key, result);
+    }
+
+    fontFaceDeclarationsByHtmlOrSvgAsset.set(
+      htmlOrSvgAsset,
+      result.accumulatedFontFaceDeclarations
+    );
+
+    if (result.accumulatedFontFaceDeclarations.length === 0) {
+      continue;
+    }
+
+    pageData.push({
+      htmlOrSvgAsset,
+      accumulatedFontFaceDeclarations: result.accumulatedFontFaceDeclarations,
+      stylesheetsWithPredicates: result.stylesheetsWithPredicates,
+      fontFamiliesWithFeatureSettings: result.fontFamiliesWithFeatureSettings,
+      featureTagsByFamily: result.featureTagsByFamily,
+      stylesheetCacheKey: result.fastPathKey,
+    });
+  }
+
+  return pageData;
+}
+
+// Flatten traced per-page textByProps into a single globalTextByProps array,
+// tagging each entry with its owning asset so downstream code can map text
+// back to the page that rendered it.
+function flattenTracedPagesIntoGlobal(
+  pageData,
+  htmlOrSvgAssetTextsWithProps,
+  globalTextByProps
+) {
+  for (const pd of pageData) {
+    for (const textByPropsEntry of pd.textByProps) {
+      textByPropsEntry.htmlOrSvgAsset = pd.htmlOrSvgAsset;
+    }
+    // Use a loop instead of push(...spread) to avoid stack overflow on large sites
+    for (const entry of pd.textByProps) {
+      globalTextByProps.push(entry);
+    }
+    htmlOrSvgAssetTextsWithProps.push({
+      htmlOrSvgAsset: pd.htmlOrSvgAsset,
+      textByProps: pd.textByProps,
+      accumulatedFontFaceDeclarations: pd.accumulatedFontFaceDeclarations,
+      fontFamiliesWithFeatureSettings: pd.fontFamiliesWithFeatureSettings,
+      featureTagsByFamily: pd.featureTagsByFamily,
+    });
+  }
+}
+
+async function collectTextsByPage(
+  assetGraph,
+  htmlOrSvgAssets,
+  {
+    text,
+    console,
+    dynamic = false,
+    debug = false,
+    concurrency,
+    chromeArgs = [],
+  } = {}
+) {
+  const htmlOrSvgAssetTextsWithProps = [];
+  const memoizedGetCssRulesByProperty = memoizeSync(getCssRulesByProperty);
+  const fontFaceDeclarationsByHtmlOrSvgAsset = new Map();
+  const stylesheetRelsByFromAsset = indexStylesheetRelations(assetGraph);
+
+  const headlessBrowser =
+    dynamic && new HeadlessBrowser({ console, chromeArgs });
+  const globalTextByProps = [];
+  const subTimings = {};
+
+  const trackPhase = makePhaseTracker(console, debug);
+  const overallPhase = trackPhase('collectTextsByPage');
+
+  const stylesheetPrecompute = trackPhase('Stylesheet precompute');
+  const pageData = precomputeStylesheetsForPages(
+    htmlOrSvgAssets,
+    stylesheetRelsByFromAsset,
+    fontFaceDeclarationsByHtmlOrSvgAsset
+  );
+  subTimings['Stylesheet precompute'] = stylesheetPrecompute.end(
+    `${pageData.length} pages with fonts`
+  );
+
+  // Pages sharing the same CSS configuration produce identical font-tracer
+  // props, only text differs — so we trace one representative and fast-path
+  // the rest. With --dynamic every page is traced individually.
+  const { pagesNeedingFullTrace, fastPathPages, uniqueGroupCount } =
+    planTracing(pageData, Boolean(headlessBrowser));
+
+  // Always surface the per-page work breakdown so users can tell at a
+  // glance how much of the run is actual tracing vs cheap CSS-group
+  // reuse. The threshold matches createPageProgress's minTotal so it
+  // only appears on non-trivial runs.
+  if (console && pageData.length >= 5) {
+    console.log(
+      `  ${pageData.length} pages with fonts: ${pagesNeedingFullTrace.length} to trace, ${fastPathPages.length} via cached CSS group (${uniqueGroupCount} unique groups)`
+    );
+  }
+
+  const tracingStart = Date.now();
+  const fullTracing = trackPhase(
+    `Full tracing (${pagesNeedingFullTrace.length} pages)`
+  );
+  try {
+    await tracePages(pagesNeedingFullTrace, {
+      headlessBrowser,
+      concurrency,
+      console,
+      memoizedGetCssRulesByProperty,
+      debug,
+    });
+
+    subTimings['Full tracing'] = fullTracing.end();
+
+    const fastPathPhase = trackPhase('Fast-path extraction');
+    const fastPathFallbacks = processFastPathPages(fastPathPages, {
+      memoizedGetCssRulesByProperty,
+    });
+    subTimings['Fast-path extraction'] = fastPathPhase.end(
+      `${fastPathPages.length} pages, ${fastPathFallbacks} fell back to full trace`
+    );
+
+    const assemblePhase = trackPhase('Result assembly');
+    flattenTracedPagesIntoGlobal(
+      pageData,
+      htmlOrSvgAssetTextsWithProps,
+      globalTextByProps
+    );
+    subTimings['Result assembly'] = assemblePhase.end();
+    if (debug && console) {
+      console.log(
+        `[subfont timing] Total tracing+extraction+assembly: ${
+          Date.now() - tracingStart
+        }ms`
+      );
+    }
+  } finally {
+    if (headlessBrowser) {
+      await headlessBrowser.close();
+    }
+  }
+
+  const postProcessPhase = trackPhase('Post-processing total');
+  const perPageLoopPhase = trackPhase('Per-page loop');
+  const { snappingTime, globalUsageTime, cloningTime } = buildPerPageFontUsages(
+    htmlOrSvgAssetTextsWithProps,
+    globalTextByProps,
+    text
+  );
   subTimings['Per-page loop'] = perPageLoopPhase.end(
     `snapping: ${snappingTime}ms, globalUsage: ${globalUsageTime}ms, cloning: ${cloningTime}ms`
   );
   subTimings['Post-processing total'] = postProcessPhase.end();
   overallPhase.end();
 
-  for (const fontFaceDeclarations of fontFaceDeclarationsByHtmlOrSvgAsset.values()) {
-    for (const fontFaceDeclaration of fontFaceDeclarations) {
-      const firstRelation = fontFaceDeclaration.relations[0];
-      const subfontTextNode = firstRelation.node.nodes.find(
-        (childNode) =>
-          childNode.type === 'decl' &&
-          childNode.prop.toLowerCase() === '-subfont-text'
-      );
-
-      if (subfontTextNode) {
-        subfontTextNode.remove();
-        firstRelation.from.markDirty();
-      }
-    }
-  }
+  stripSubfontTextNodes(fontFaceDeclarationsByHtmlOrSvgAsset);
   return {
     htmlOrSvgAssetTextsWithProps,
     fontFaceDeclarationsByHtmlOrSvgAsset,
@@ -982,9 +1061,3 @@ async function collectTextsByPage(
 }
 
 module.exports = collectTextsByPage;
-
-// Exported for testing only
-module.exports._extractFeatureTagsFromDecl = extractFeatureTagsFromDecl;
-module.exports._resolveFeatureSettings = resolveFeatureSettings;
-module.exports._findFontFamiliesWithFeatureSettings =
-  findFontFamiliesWithFeatureSettings;