Performance Issue: Main single-page specification is slow

[YutaKyle]

What is the issue with the HTML Standard?

⚠️ Performance Issue: Main single-page specification loads whole spec at root URL

Description

Navigating to the root URL (https://html.spec.whatwg.org/) loads the entire HTML Living Standard as a single, monolithic document. This creates severe browser performance issues, especially on lower-spec hardware or mobile devices.

Impact / Symptoms

• High Memory Consumption: Loads over 15 MB of raw HTML and hundreds of thousands of DOM nodes in a single frame.
• Browser Freezing/Crashing: Tabs often hang, become unresponsive during rendering, or crash due to memory limits.
• Sluggish Native Search: Using Ctrl+F causes massive layout recalculation and severe input lag.

Suggested Solutions

• Consider making the /multipage/ version the default landing view, or prominent default redirect.
• Add an explicit, high-visibility banner at the top of the single-page view suggesting visitors switch to the /multipage/ or /dev/ edition if they experience page lag.

[nektro]

fwiw the link to multipage is enlarged and clickable the entire time the main site is loading

[zcorpan]

Changing the URLs seems like a non-option. Why is it more of an issue that the single-page version is at /?

We could maybe make some tweaks to address performance issues with the single-page version. Open to suggestions.

Find-in-page shouldn't cause a layout recalc (assuming find-in-page doesn't open a sidebar or so).

[zcorpan]

Analysis using https://mozdoctor.quick.mozilla.cloud/ if anyone wants to try optimizations:

Pre-diagnosis context

MozDoctor

What is going wrong on this page?

You

This page is slow to load. Figure out why.

MozDoctor

I’ll reproduce a fresh load with timing instrumentation, separate network transfer from parsing/rendering/script work, and then compare the same URL in clean Firefox and Chrome if those tools are available. The page is unusually large, so the key question is whether the delay is server/network time, main-thread processing, or something specific to this Firefox profile.

MozDoctor

The current reload completed in about 1.04 s, with first content at 0.27 s—so the reported slowness is not reproduced from the warm cache. One concrete outlier is already clear: the main HTML expands from 2.18 MB compressed to 15.6 MB and creates about 334,000 elements, 67,000 links, and 4.1 million visible-text characters. I’m now forcing a cache-distinct load while recording Firefox’s main thread; that will test whether the expensive part is downloading, parsing the giant document, or later layout/style work.

MozDoctor

The cache-distinct primary Firefox load still reached first content in 0.39 s and finished in 1.40 s. The 2.18 MB compressed response itself was available by 0.21 s; most of the remaining time was local processing, with DOMContentLoaded delayed until 1.39 s. I’m now measuring the same cache-cold URL and 893×949 viewport in a clean Firefox Nightly profile and headless Chrome to establish whether this is profile-, Firefox-, or page-size-specific.

MozDoctor

The comparison isolates two effects:

• Clean Firefox, first visit: first content 2.26 s, load 3.35 s.
• The same clean Firefox, immediate repeat: first content 0.18 s, load 0.92 s.
• Chrome, first visit: first content 1.33 s, load 2.76 s.

So this is not an extension/profile regression; cold-cache cost dominates, and both engines reproduce it. Chrome’s trace directly reports an excessive DOM: 334,167 elements, with individual layout passes up to 217 ms and style recalculations up to 270 ms. I’m running the decisive counterfactual now: the site’s multipage edition in the same clean Firefox, with connection and shared styles already warm. If that collapses the timing with the same content/site styling, it pins the cause on the one-page document’s scale.

You

I've enabled "Allow remote automation" in Safari now if you want to compare with Safari

MozDoctor

Thanks—that’s useful as a third-engine control. Since both Firefox and Chrome already show the same large-document cost, Safari can confirm whether the delay is page-wide rather than a Gecko/Blink coincidence; it must run headed, so you may briefly see the comparison window. I’ll load only this public URL at the same viewport, record the timing/DOM counts, then close Safari.

MozDoctor

Safari’s browser-control endpoint is not exposed to this diagnostic session despite the setting change, so I can’t safely drive or time it here. That does not block the cause: I’ll complete the required Firefox-version comparison using the isolated headless browser, then restore the user’s tab to the exact original URL.

MozDoctor

The alternate Firefox launch is taking far longer than the page itself did in either existing browser, which points to the comparison launcher rather than the website. I’ll give that isolated startup one short recovery attempt; if it remains unavailable, I’ll record the version comparison as an infrastructure gap rather than misattribute the delay.

MozDoctor

The primary tab is restored to the original URL, but the timing probe is currently stalled—unlike the earlier 1.0–1.4 s loads. This began only after the failed alternate-Firefox launcher, so I’m treating it as temporary diagnostic resource contention, not new evidence about the site. I’ll stop the stalled probe, tear down the remaining comparison workload, and verify the primary tab independently.

MozDoctor

The slowdown is caused primarily by the enormous One-Page Version, not a Firefox extension or server failure.

Environment	First content	Load complete
Firefox Nightly, clean profile, first visit	2.26 s	3.35 s
Same Firefox, cached repeat	0.18 s	0.92 s
Chrome, first visit	1.33 s	2.76 s
Firefox multipage edition	0.30 s	0.41 s

Causal evidence:

• The one-page response expands from 2.18 MB compressed to 15.59 MB.
• It creates roughly 334,000 elements, including 67,000 links and 10,471 direct body children.
• Chrome’s trace measured repeated layout passes of 40–217 ms and style recalculations of 40–270 ms.
• There are also 64 non-lazy images and three non-lazy iframes, which prolong the loading indicator.
• The equivalent multipage landing document is only 155 KB decoded with 4,467 elements—about 100× less HTML and 75× fewer elements—and completed in 0.41 s.
• There were no console errors or failed network requests. Initial connection and stylesheet caching affect first-visit time, but they are secondary to the document’s scale.

This reproduces in clean Firefox and Chrome, so it is not profile-specific, Firefox-only, or user-agent targeting. Safari control was unavailable to the diagnostic tooling despite Remote Automation being enabled; the alternate Firefox launcher also failed before starting.

Best workaround: use the site’s Multipage Version (/multipage/) or Version for Web Devs (/dev/) instead of the one-page edition. The active tab has been restored to https://html.spec.whatwg.org/; its final cached load completed in 1.24 s, with content visible after 55 ms.

You

I know it's big and has lots of nodes. Tell me something I don't know. Where is the time spent? How would you optimize this page (without switching to multipage or similar). This page is useful as a "monster perf test", but it doesn't need to do unnecessarily wasteful things, so I'm looking for things to change to make the page faster and use less memory. Be creative; I can change the build tooling for the spec.

MozDoctor

You’re right—the previous diagnosis stopped one layer too early. I’ll break the load into streaming/decompression, HTML tokenization/tree building, stylesheet matching, frame construction/layout, painting, deferred scripts, images/iframes, and memory retention. Then I’ll test build-level counterfactuals on the same one-page content—especially DOM-shape changes, hidden/offscreen sections, link density, and eagerly loaded examples—to identify changes that preserve the single-document artifact.

MozDoctor

The deeper Firefox profile is already overturning one assumption: JavaScript is negligible—about 4.3 ms total execution and 0.23 ms compilation. The dominant markers are 401 ms of style work spread across 307 flushes, 107 ms of explicit HTML tree-operation batches, 2,345 interruptible reflow markers, 171 synchronous reflows, five long tasks totaling 813 ms, and a 442 ms browser-hang interval. I’m decoding the sampled stacks now because several of those markers overlap; that will give non-double-counted time by phase and identify which DOM patterns trigger the repeated flushes.

MozDoctor

I found a specific build/runtime bug, not just “too many nodes”: the deferred html-dfn.js adds dfnEnabled to <body> after parsing. That class only enables cursor: pointer, but the selector starts at body.dfnEnabled …, so Firefox invalidates styles across essentially the whole 334k-node document immediately before DOMContentLoaded. The profile’s 442 ms post-parse hang is a refresh-driver layout containing ~312 ms of reflow and ~125 ms of style work; the script itself takes only milliseconds. I’m testing that exact class toggle as a controlled intervention, then I’ll look for other high-fanout late mutations and DOM-shape waste.

MozDoctor

A much larger lever worked: I rebuilt the same one-page HTML in-memory with 23 chapter wrappers and content-visibility:auto. It still contains all 334,204 elements and all fragment targets, but Firefox load time fell from roughly 0.95 s to 0.40 s in the blob-controlled runs. This attacks frame construction/layout, not parsing or content. The tradeoff is scroll geometry: naïve fixed intrinsic sizes make the initial scroll height approximate, so the build should emit per-chapter containment metadata or use remembered intrinsic sizes. I’m profiling this variant and testing fragment navigation/find behavior before recommending the exact shape.

You

I think I don't like content-visibility:auto because it hides the perf costs, I still want the page to be a useful perf test page. Include it as an option but also look for other approaches to avoid unecessary style invalidations and such and what the relative impact is.

MozDoctor

Agreed. I’ll keep containment as an optional “make it fast” mode, but it changes the benchmark by skipping work. The better target is making the browser do the full render exactly once. I’m narrowing every large style flush to its triggering mutation or resource event and will rank fixes by avoided duplicate work while preserving the monster workload.

MozDoctor

I’ve isolated the big cost buckets and I’m doing one final controlled comparison: identical full DOM with eager versus lazy media. That will separate the document’s intended style/layout stress from unrelated image/iframe work, then I’ll restore and close all temporary pages.

MozDoctor

The media split is now direct: keeping the full 334k-element DOM but marking the 64 images and 3 iframes lazy cut initial requests from 57 to 13 and load completion by about 188 ms in the controlled Chrome run. It also avoids eagerly decoding roughly 5.7 million image pixels (~23 MB RGBA upper bound); the animated canvas iframe alone contributed a measured 115 ms main-thread task. I’m cleaning up the comparison tabs now.

MozDoctor

One important distinction is emerging: the page is not suffering from a framework repeatedly thrashing style. It mostly pays one enormous initial style/layout bill. I found only one material author-caused global invalidation—the deferred dfnEnabled class—and its isolated cost is tens of milliseconds, not hundreds. I’m checking the style-engine stacks now so the recommendations don’t devolve into generic “simplify selectors” advice.

MozDoctor

There is also concrete build-time residue: 14,680 data-* attributes (~486 KB uncompressed markup) are referenced by neither the shipped scripts nor CSS. The runtime-needed attributes are a much smaller subset (data-dfn-type, data-algorithm, and data-var-scope). I’m validating the cost of stripping only the apparently build-only set, while preserving IDs, links, text, and the full rendered DOM.

Diagnosis and recommendation

MozDoctor

Diagnosis

The page is overwhelmingly a style/layout benchmark, not a JavaScript or paint benchmark.

In the Chrome critical-load trace, approximately 72% of the 2.66-second window was spent in style, layout, and pre-paint:

Work	Main-thread time
Style / UpdateLayoutTree	842 ms
Layout	786 ms
Pre-paint	288 ms
HTML parsing	217 ms
Paint	31 ms
Page JavaScript	7 ms

Firefox shows the same shape. In a 2.095-second profile:

• 589 ms was initial network/idle wait.
• 734 ms was inside layout flushing, including 538 ms of reflow.
• 239 ms was style processing.
• 107 ms was parser tree-operation work.
• 15 ms was paint.
• 4.3 ms was page script execution.

These are inclusive profile stacks, so some Firefox figures overlap. The conclusion is nevertheless clear: initial frame construction, styling, and layout dominate.

The document contains about:

• 334,000 elements
• 389,000 text nodes
• 723,000 total DOM nodes
• 67,000 links
• 71,000 IDs
• 15.6 MB decoded HTML

The avoidable style invalidation

At domInteractive, html-dfn.js adds dfnEnabled to <body>. Firefox then runs a 442 ms refresh-driver task containing roughly 125 ms of style and 311 ms of reflow.

That looks damning, but a controlled toggle showed the class itself costs only 36–40 ms. Generating the class in the HTML reduced whole-load time by roughly 27 ms. Most of that 442 ms is the inevitable final full-document render that merely happens to coincide with the script.

Chrome’s invalidation tracking found only six author-scheduled invalidations:

• The global dfnEnabled class: material, tens of milliseconds.
• A title added to one commit link: negligible.
• Four parser-time structural pseudo-class invalidations: negligible.

So there is no hidden loop repeatedly restyling 334k elements. The big bill is the initial calculation itself.

Optimizations I would prioritize

1. Stop representing syntax coloring with 57,256 DOM elements

There are 57,256 custom <c-> elements, mostly syntax-highlighting tokens.

A controlled plain-text-code variant:

• Reduced total nodes from ~723k to ~589k.
• Reduced HTML from 15.59 MB to 14.78 MB.
• Improved Firefox load by approximately 140–175 ms.

I would first coalesce adjacent tokens with identical styling and omit wrappers whose styling is inherited/default. The more ambitious version is one text node per code example plus a run-length-encoded token-offset table rendered with CSS Custom Highlights. That preserves full text layout and painting without making every token a layout-tree object.

This is likely the largest optimization that still leaves the page a genuine full-document rendering stress test.

2. Move hidden MDN compatibility bodies out of the DOM

The 1,060 MDN annotations contain approximately 62,000 elements. Most detailed .feature content is already display:none, so it costs little layout time but substantial DOM memory.

Removing only those hidden bodies:

• Saved about 58,000 elements and 92,000 total nodes.
• Removed 1.78 MB of HTML.
• Improved load by only ~40 ms, because the content was already non-rendered.

Build the detailed compatibility information into a compact JSON/HTML sidecar keyed by annotation ID. Keep the visible buttons/status summaries, then instantiate one reusable popover when clicked.

A <template> is not sufficient: template contents still remain DOM nodes in memory.

3. Lazy-load media while keeping the complete main DOM rendered

Adding loading=lazy to 64 images and 3 iframes left all 334k main-document elements intact but changed the controlled Chrome run from:

• 57 initial requests to 13
• 64 decoded images to 1
• 2 loaded iframes to 0
• 1,567 ms load completion to 1,379 ms

The images represent roughly 5.7 million pixels, or about 23 MB of decoded RGBA surfaces at full residency.

The animated blue-robot canvas iframe alone generated a measured 115 ms main-thread task and approximately 489 ms of Firefox network tail. It is unrelated to testing layout of the specification itself.

Give media explicit dimensions or aspect-ratio so loading it later does not change document geometry. An ?eager-media switch could retain the broader media stress test when desired.

4. Remove build-only markup residue

I found 14,680 attributes—about 486 KB of decoded source—that are referenced by neither the shipped CSS nor runtime scripts:

• data-x-internal
• data-dfn-for
• data-export
• data-lt
• data-noexport

Removing them produced no clear timing improvement: the 935 ms result was within the 924–957 ms baseline variation. It should still reduce transfer, DOM attribute storage, and string memory. Verify that external tooling does not treat these attributes as a published API.

The runtime-used attributes include data-dfn-type, data-algorithm, and data-var-scope; retain those.

5. Strip whitespace text nodes content-model-aware

There are 64,297 whitespace-only text nodes, about 9% of all DOM nodes. Some are significant inside pre/code and between inline phrasing elements, but many around tables, sections, list structure, and top-level blocks are build formatting.

Use an HTML-aware minifier, not a global whitespace regex. Even removing the clearly safe top-level subset should eliminate around ten thousand nodes without changing rendering.

6. Generate final styling state

Generate <body class="dfnEnabled"> directly—or make the cursor rule unconditional—and remove the late class mutation. Also emit the commit link’s title at build time.

Expected saving: around 30–40 ms, plus a cleaner single-render lifecycle. Useful, but not transformative.

7. Fix cold-network overhead

The four stylesheets total only about 49 KB decoded / 13 KB compressed, but on a clean Firefox visit their cross-origin requests occupied roughly 716–832 ms. Inlining this small CSS bundle into the generated document removes a render-blocking cross-origin dependency for first-time visitors.

The 15.6 MB HTML currently transfers as roughly 2.177 MB gzip even when Brotli is accepted. Offline compression measurements were:

Encoding	Size
Current gzip	2.177 MB
Brotli quality 6	1.695 MB
Brotli quality 11	1.407 MB

Because this is a static build artifact, Brotli 11’s slow compression is harmless. That saves about 35% of main-document transfer.

The Essays 1743 fonts are another ~200 KB for one distant example. Subsetting to the actual glyphs and serving WOFF2 would reduce both network and font memory; one cold profile showed font activation contributing approximately 51 ms.

8. Remove the unnecessary animation churn

The multipage-link animation scheduled about 305 single-element style updates in the first several seconds. Style-update CPU was only ~4.25 ms over the first five seconds, so this is low priority, but it is pure noise.

Use a static emphasized state, or animate only a promoted transform while keeping the shadow static.

What did not work

I tested hiding the body until parsing completed, then revealing it once. That was slower:

• Normal full-DOM variant: approximately 957 ms
• Render-gated variant: approximately 1,101 ms

It also delayed first contentful paint. Coalescing everything into one giant render does not make the total render cheaper.

content-visibility:auto remains an effective user-facing option:

• Firefox load: approximately 957 → 397 ms
• Reflow: approximately 478 → 28 ms
• Fragment navigation revealed individual sections in 10–211 ms

But it changes the benchmark exactly as you suspected: initial scroll geometry is estimated and most full-document layout is deferred. I would keep it as an opt-in “fast reading” mode, not the canonical monster test.

CSS contain:layout style section roots could localize future reflows without skipping initial rendering, but this page has almost no meaningful post-load invalidation after the dfnEnabled mutation is removed. It is unlikely to materially improve initial load and risks changing counters, margin collapsing, and floats.

Recommended build order

I’d implement this in order:

1. Coalesce or replace <c-> syntax-token elements.
2. Move hidden MDN details to a sidecar and reusable popover.
3. Lazy-load dimensioned media and pause the canvas demo offscreen.
4. Generate dfnEnabled and other final attributes statically.
5. Strip safe whitespace nodes and unused build metadata.
6. Inline the small CSS bundle, precompress with Brotli, and subset fonts.
7. Remove or compositor-isolate the attention animation.

That keeps the one-page document a serious 250k+-element full-render benchmark while removing work that tests token-wrapper proliferation, hidden metadata storage, media decoding, and late root invalidation rather than the HTML specification itself.

The issue reproduced in the active Firefox profile, clean Firefox, and Chrome. Firefox was slower, but both engines showed the same causal cost distribution, so this is not a Firefox-specific failure. All temporary comparison tabs are closed and the original Firefox page has been restored.

[zcorpan]

For the <c-> elements we could try a Custom Highlight highlighter (maybe highlight lazily?).

[zcorpan]

4. Remove build-only markup residue

This should not be done because those attributes are used by other tooling (to enable cross-spec references for example).

[zcorpan]

Task list for the recommendations in comment #5367466383:

• Stop representing syntax coloring with 57,256 <c-> elements. Coalesce adjacent same-styled tokens / drop redundant wrappers, or move to one text node per code block + CSS Custom Highlights. Largest single win (~140–175ms). Follow-up floats trying a Custom Highlight highlighter, possibly lazily: comment.
  • @tabatkins said they can look into this.
• Move hidden MDN compatibility bodies out of the DOM into a sidecar JSON keyed by annotation ID (or maybe have the data in a data-* attribute for each MDN annotation), instantiated as one reusable popover on click (saves ~58k elements / 1.78MB HTML).
  • Implementation plan and PRs: Optimize MDN panels wattsi#169
• Lazy-load dimensioned media (64 images, 3 iframes incl. the animated canvas demo) while keeping the full 334k-element DOM intact for the perf-test purpose.
  • Meta: lazy-load the spec's own images and iframes #12867
  • Lazy-load the tracking vector images wattsi#172
• Remove build-only markup residue (data-x-internal, data-dfn-for, data-export, data-lt, data-noexport). Should not be done — these attributes are used by other tooling: comment.
• Strip whitespace-only text nodes (~64k, ~9% of all nodes) with an HTML-aware minifier rather than a blanket regex.
  • Drop whitespace-only text nodes that cannot render wattsi#173
• Generate final styling state at build time — emit <body class="dfnEnabled"> (or make the cursor rule unconditional, or use @media (scripting: enabled)) and the commit-link title statically instead of via late script mutation, avoiding the late whole-document style invalidation. Minor win (~30–40ms).
  • Meta: remove the dfnEnabled class on body #12905
  • Meta: set commit-snapshot-link title attribute in markup #12904
  • Don't set the commit-snapshot-link title with script whatwg.org#507
• Reduce cold-network overhead — inline the small CSS bundle to avoid a render-blocking cross-origin request, precompress the built HTML with Brotli 11 (~35% smaller than gzip), and subset the Essays1743 font to WOFF2.
  • Issue about Brotli: We should enable Brotli! misc-server#24
  • Meta: subset custom font for #table-example-1 #12924
• Remove the multipage-link attention animation (pure style-update noise).
  • PR: Remove the animation for the multipage link whatwg.org#505