refactor: Improve hydration mismatch errors for third-party scripts

Improves error messages shown during hydration mismatches to better
surface cases where third-party scripts or browser extensions have
modified the DOM outside of Angular's control.

Fixed angular#59224

Author: aparzi

packages/core/src/hydration/error_handling.ts

@@ -14,10 +14,14 @@ import {HOST, LView, TVIEW} from '../render3/interfaces/view';
 import {getParentRElement} from '../render3/node_manipulation';
 import {unwrapRNode} from '../render3/util/view_utils';
 
+import {readPatchedData} from '../render3/context_discovery';
 import {markRNodeAsHavingHydrationMismatch} from './utils';
 
 const AT_THIS_LOCATION = '<-- AT THIS LOCATION';
 
+const HYDRATION_GUIDE_URL = 'https://angular.dev/guide/hydration';
+const THIRD_PARTY_SCRIPTS_URL = `${HYDRATION_GUIDE_URL}#third-party-scripts-with-dom-manipulation`;
+
 /**
  * Retrieves a user friendly string for a given TNodeType for use in
  * friendly error messages
@@ -100,7 +104,19 @@ export function validateMatchingNode(
     }
 
     const footer = getHydrationErrorFooter(componentClassName);
-    const message = header + expected + actual + getHydrationAttributeNote() + footer;
+    let message = header + expected + actual + getHydrationAttributeNote() + footer;
+
+    // Check both when a mismatching node is found AND when the expected node is missing,
+    // since third-party scripts can both inject extra nodes and remove existing ones.
+    if (!node || (node && isLikelyExternalSourceNode(node))) {
+      message +=
+        `Note: It looks like this mismatch may have been caused by a third-party script or ` +
+        `browser extension that modified the DOM outside of Angular's control. ` +
+        `Angular hydration does not support nodes injected or removed outside of the Angular-managed DOM. ` +
+        `Consider using \`afterNextRender\` to delay script execution until after hydration completes. ` +
+        `More info: ${THIRD_PARTY_SCRIPTS_URL}\n\n`;
+    }
+
     throw new RuntimeError(RuntimeErrorCode.HYDRATION_NODE_MISMATCH, message);
   }
 }
@@ -413,11 +429,32 @@ function getHydrationErrorFooter(componentClassName?: string): string {
     `To fix this problem:\n` +
     `  * check ${componentInfo} component for hydration-related issues\n` +
     `  * check to see if your template has valid HTML structure\n` +
+    `  * check if there are any third-party scripts that manipulate the DOM. More info: ${THIRD_PARTY_SCRIPTS_URL}\n` +
     `  * or skip hydration by adding the \`ngSkipHydration\` attribute ` +
     `to its host node in a template\n\n`
   );
 }
 
+/**
+ * Checks if a given RNode is likely to have been added by a third-party script
+ * or browser extension, by checking whether Angular has any knowledge of it
+ * via patched data. Nodes created and managed by Angular will always have
+ * patched data attached to them.
+ */
+function isLikelyExternalSourceNode(rNode: RNode): boolean {
+  const node = rNode as Node;
+  if (node.nodeType !== Node.ELEMENT_NODE) {
+    return false;
+  }
+  // If Angular has patched this node, it was created within Angular's context.
+  if (readPatchedData(node as HTMLElement)) {
+    return false;
+  }
+  // No patched data means Angular has no record of this node —
+  // it was likely injected by a third-party script or browser extension.
+  return true;
+}
+
 /**
  * An attribute related note for hydration errors
  */

packages/platform-server/test/full_app_hydration_spec.ts

@@ -6197,10 +6197,51 @@ describe('platform-server full application hydration integration', () => {
           expect(message).toContain('During hydration Angular expected <b> but found <span>');
           expect(message).toContain('<b>…</b>  <-- AT THIS LOCATION');
           expect(message).toContain('<span>…</span>  <-- AT THIS LOCATION');
+          expect(message).toContain(
+            'check if there are any third-party scripts that manipulate the DOM. More info: https://angular.dev/guide/hydration#third-party-scripts-with-dom-manipulation',
+          );
           verifyNodeHasMismatchInfo(doc);
         });
       });
 
+      it('should suggest afterNextRender if a third-party script injected a node', async () => {
+        @Component({
+          selector: 'app',
+          template: `<div>Original content</div>`,
+          standalone: true,
+        })
+        class SimpleComponent {
+          private doc = inject(DOCUMENT);
+          ngAfterViewInit() {
+            const div = this.doc.querySelector('div');
+            const ins = this.doc.createElement('ins');
+            ins.setAttribute('data-ad-client', 'ca-pub-1234');
+            ins.textContent = 'Ad content';
+            div?.parentNode?.insertBefore(ins, div);
+          }
+        }
+
+        const html = await ssr(SimpleComponent);
+        resetTViewsFor(SimpleComponent);
+
+        await prepareEnvironmentAndHydrate(doc, html, SimpleComponent, {
+          envProviders: [withNoopErrorHandler()],
+        }).catch((err: unknown) => {
+          const message = (err as Error).message;
+          expect(message).toContain('During hydration Angular expected <div> but found <ins>');
+          expect(message).toContain(
+            'check if there are any third-party scripts that manipulate the DOM. More info: https://angular.dev/guide/hydration#third-party-scripts-with-dom-manipulation',
+          );
+          expect(message).toContain(
+            'Note: It looks like this node was injected by a third-party script or browser extension',
+          );
+          expect(message).toContain(
+            'Angular hydration does not support nodes injected outside of the Angular-managed DOM',
+          );
+          expect(message).toContain('Consider using `afterNextRender` to delay script execution');
+        });
+      });
+
       it('should handle <ng-container> node mismatch', async () => {
         @Component({
           selector: 'app',