Hydration: detect when index.html is altered between the server and the client #51160

Which @angular/* package(s) are relevant/related to the feature request?

core

Description

The non-destructive hydration expects the DOM tree to have the same structure in both places. This also includes whitespaces and comment nodes that Angular produces during the rendering on the server. Those whitespaces and nodes must be present in the HTML generated by the server-side rendering process. This is also documented at: https://angular.io/guide/hydration#constraints.

In practice, some CDNs (example) have mechanisms to remove all comment nodes and spaces from all text nodes from HTML while serving the content (there are also cases where this type of optimization is performed at the build step). Those mechanisms are frequently enabled by default. This leads to situations where an application worked in dev mode correctly, but started failing in production. Since the production code is also minified, it makes it hard to look at the stack trace and identify the origin of the problem.

This feature requests proposes that we add a special detection mechanism for such cases. For example, we can do the following:

• on the server, while serializing DOM, add a comment node to a well known location (e.g. as a first node in the <body>)
• on the client (both in dev and prod modes), before starting hydration process, verify the presence of those "marker" nodes and throw an error if they are not present
• we should also add an error guide for this error, so that the link to the guide is present in production mode

One of the examples where this issue becomes a hard-to-debug problem: #50133 (comment)