Parsing, DOM, and CSSOM Construction

## Two different finish lines A page load has two milestones that people routinely conflate. `DOMContentLoaded` means *the document has been parsed*. `load` means *the document and everything it referenced has arrived*. They can be milliseconds apart on a text page and many seconds apart on a page with large images. ## What has to be true before DOMContentLoaded The HTML parser consumes the response incrementally and appends nodes to the DOM as it goes. `DOMContentLoaded` is dispatched on `document` when the parser reaches the end of the document — the DOM tree is final, nothing more will be appended by the parser. Two things can push that moment later: - **A parser-blocking classic script.** The parser stops at the script, hands control to the JavaScript engine, and only resumes afterwards. The DOM cannot be complete until that finishes. - **`defer` scripts.** Deferred scripts are guaranteed to run after parsing completes and *before* `DOMContentLoaded`, in document order. So the event waits for them. `async` scripts are not waited for. An async script may execute before or after `DOMContentLoaded` depending purely on when its download finishes — that non-determinism is the whole point of `async`. ## What DOMContentLoaded does not wait for Images, `<iframe>` documents, videos, fonts and stylesheets are all *subresources*. Their loading is independent of parsing, so `DOMContentLoaded` fires without them. This is exactly why it is the right hook for most initialisation: your query selectors and event wiring only need nodes to exist. There is one indirect coupling worth knowing. A pending stylesheet does not block the parser from building the DOM, but it *does* block a following synchronous script from executing — the script might call `getComputedStyle()`, so the browser makes it wait for the CSSOM. Since the parser is in turn waiting on that script, a slow stylesheet can delay `DOMContentLoaded` transitively. The event still has no direct dependency on CSS. ## The load event `load` fires on `window` once the document is complete and every dependent resource has either loaded or failed. A 404 image does not hang `load` forever — a failed fetch also settles the resource. Because `load` waits for the slowest image on the page, it is a poor signal for "the app is ready" and a decent signal for "final layout with real image dimensions exists". ## document.readyState The same timeline is exposed as a string on `document`: ```js document.readyState; // "loading" while the parser is running // -> "interactive" when parsing is done (DOMContentLoaded fires just after) // -> "complete" when subresources are done (load fires just after) ``` A `readystatechange` event fires on each transition. ## The late-listener trap These are one-shot events, not sticky flags. If your script runs after the event has already been dispatched — a dynamically injected script, a bundle loaded very late — the listener never fires and your initialisation silently never happens. The standard guard is: ```js function init() { /* ... */ } if (document.readyState === 'loading') { document.addEventListener('DOMContentLoaded', init); } else { init(); } ``` ## Where to attach what - DOM wiring, event delegation, hydration of markup: `DOMContentLoaded` (or simply a `defer`red script, which runs at effectively the same point and needs no listener at all). - Measuring an element whose size depends on a loaded image, or firing analytics that should reflect a fully drawn page: `load`. - Cleanup and "the user is leaving" work: neither of these — the page-lifecycle events exist for that. ## Historical note jQuery's `$(document).ready()` and `$(window).on('load')` map onto exactly these two events, which is where a lot of the confusion originated: plenty of code used `load` when it only ever needed `ready`, and paid for it with a visibly late initialisation on image-heavy pages.