perf: walker based transformHtmlTemplate - #581

🔗 Linked issue

#572, #578

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Users are advised to use the transformHtmlTemplate() when modifying the HTML to add the Unhead tags. This function accounts for the HTML containing tags that may duplicate or cause inefficient loading by stripping tags, adding them into Unhead and then re-rendering them out.

This function was powered by regex and is performing very slow (#572) for large HTML files. This is due to the regex itself requiring several passes of the entire underlying HTML.

We can solve this using a custom HTML parser but they're mostly overkill for what we need to do, which is just extract text from the <head>. I had experience working on a custom HTML parser for https://github.com/harlan-zw/mdream, which is fairly well tested, so we copy the relevant implementation. In this PR we migrate transformHtmlTemplate() to use this new parser.

We also expose a function transformHtmlTemplateRaw() which assumes the HTML template does NOT contain any head data that may duplicate or cause order issues. This avoids any sort of HTML parsing and just does simple insertions of the unhead tags at the relevant positions.

Benchmarks

Basic HTML Template: +21% (85K → 103K hz)
Complex HTML Template: +1,120% (352 → 4,296 hz)
Multiple Head Pushes: +19% (53K → 63K hz)
Large HTML Template: +47% (35K → 51K hz)

The complex template scenario saw a 12x speedup, dropping from 2.8s to 0.23s mean execution time. All other cases improved 19-47% with better consistency (lower RME values).

New

     name                           hz     min     max    mean     p75     p99    p995    p999     rme  samples
   · basic html template    103,275.56  0.0089  3.8059  0.0097  0.0095  0.0151  0.0281  0.0465  ±0.78%   103276
   · complex html template    4,295.57  0.2000  1.2383  0.2328  0.2168  0.9921  1.0337  1.0933  ±1.45%     4296
   · multiple head pushes    63,484.76  0.0146  1.7504  0.0158  0.0157  0.0196  0.0234  0.0593  ±0.36%    63485
   · large html template     51,415.89  0.0181  0.1130  0.0194  0.0195  0.0227  0.0264  0.0628  ±0.11%    51416

Previous

     name                          hz     min     max    mean     p75     p99    p995    p999     rme  samples
   · basic html template    85,495.99  0.0098  4.1463  0.0117  0.0112  0.0311  0.0479  0.0880  ±0.88%    85496
   · complex html template     351.89  2.0355  7.4135  2.8418  2.7711  5.4990  5.9402  6.6077  ±1.98%     1000
   · multiple head pushes   53,470.29  0.0160  0.4117  0.0187  0.0187  0.0291  0.0330  0.1252  ±0.29%    53471
   · large html template    34,972.13  0.0251  0.2645  0.0286  0.0283  0.0461  0.0493  0.1339  ±0.23%    34973