From f7c624dd221f80000a56b9a099f87f9ec3ccfb20 Mon Sep 17 00:00:00 2001
From: Kartik Pant <kartikpant.kp69@gmail.com>
Date: Thu, 9 Apr 2026 18:31:20 +0530
Subject: [PATCH 1/3] docs: add hydration debugging guide

---
 src/content/learn/render-and-commit.md | 42 ++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/content/learn/render-and-commit.md b/src/content/learn/render-and-commit.md
index d7d8f301eee..efe6dad3120 100644
--- a/src/content/learn/render-and-commit.md
+++ b/src/content/learn/render-and-commit.md
@@ -194,6 +194,48 @@ export default function App() {
 </Sandpack>
 
 This works because during this last step, React only updates the content of `<h1>` with the new `time`. It sees that the `<input>` appears in the JSX in the same place as last time, so React doesn't touch the `<input>`—or its `value`!
+## Debugging Hydration Mismatches
+
+Hydration mismatches can occur when the HTML rendered on the server differs from what React renders on the client.
+
+### Common causes
+
+- Non-deterministic values such as:
+  - `Math.random()`
+  - `Date.now()`
+- Using browser-only APIs like `window` or `document` during render
+- Differences between server and client environments
+- Asynchronous or inconsistent data
+
+### Example
+
+```jsx
+function App() {
+  return <div>{Math.random()}</div>;
+}
+```
+
+### How to fix
+- Move non-deterministic logic into `useEffect`
+- Ensure consistent data between server and client
+- Guard browser-specific code:
+```jsx
+if (typeof window !== "undefined") {
+  // client-only logic
+}
+```
+
+### Debugging checklist
+- Is the output deterministic?
+- Is any browser-only API used during render?
+- Is server data identical to client data?
+- Are there time-based values?
+
+### Best practices
+- Keep rendering logic pure
+- Avoid side effects during render
+- Use client-only rendering when necessary
+
 ## Epilogue: Browser paint {/*epilogue-browser-paint*/}
 
 After rendering is done and React updated the DOM, the browser will repaint the screen. Although this process is known as "browser rendering", we'll refer to it as "painting" to avoid confusion throughout the docs.

From 9a560edf657a4ec28b1a9c1ead8cd6a22deafc08 Mon Sep 17 00:00:00 2001
From: Kartik Pant <kartikpant.kp69@gmail.com>
Date: Thu, 9 Apr 2026 18:36:02 +0530
Subject: [PATCH 2/3] docs: fix heading IDs for CI

---
 src/content/learn/render-and-commit.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/content/learn/render-and-commit.md b/src/content/learn/render-and-commit.md
index efe6dad3120..9a4fbd8ef7d 100644
--- a/src/content/learn/render-and-commit.md
+++ b/src/content/learn/render-and-commit.md
@@ -194,11 +194,11 @@ export default function App() {
 </Sandpack>
 
 This works because during this last step, React only updates the content of `<h1>` with the new `time`. It sees that the `<input>` appears in the JSX in the same place as last time, so React doesn't touch the `<input>`—or its `value`!
-## Debugging Hydration Mismatches
+## Debugging Hydration Mismatches {/*debugging-hydration-mismatches*/}
 
 Hydration mismatches can occur when the HTML rendered on the server differs from what React renders on the client.
 
-### Common causes
+### Common causes {/*common-causes*/}
 
 - Non-deterministic values such as:
   - `Math.random()`
@@ -207,7 +207,7 @@ Hydration mismatches can occur when the HTML rendered on the server differs from
 - Differences between server and client environments
 - Asynchronous or inconsistent data
 
-### Example
+### Example {/*example*/}
 
 ```jsx
 function App() {
@@ -215,7 +215,7 @@ function App() {
 }
 ```
 
-### How to fix
+### How to fix {/*how-to-fix*/}
 - Move non-deterministic logic into `useEffect`
 - Ensure consistent data between server and client
 - Guard browser-specific code:
@@ -225,13 +225,13 @@ if (typeof window !== "undefined") {
 }
 ```
 
-### Debugging checklist
+### Debugging checklist {/*debugging-checklist*/}
 - Is the output deterministic?
 - Is any browser-only API used during render?
 - Is server data identical to client data?
 - Are there time-based values?
 
-### Best practices
+### Best practices {/*best-practices*/}
 - Keep rendering logic pure
 - Avoid side effects during render
 - Use client-only rendering when necessary

From d28f4e6221c331159dd4a4ecd981605e3515e634 Mon Sep 17 00:00:00 2001
From: Kartik Pant <kartikpant.kp69@gmail.com>
Date: Thu, 9 Apr 2026 18:41:23 +0530
Subject: [PATCH 3/3] docs: suppress impure function lint for hydration example

---
 src/content/learn/render-and-commit.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/learn/render-and-commit.md b/src/content/learn/render-and-commit.md
index 9a4fbd8ef7d..2d88e67fbfe 100644
--- a/src/content/learn/render-and-commit.md
+++ b/src/content/learn/render-and-commit.md
@@ -209,7 +209,7 @@ Hydration mismatches can occur when the HTML rendered on the server differs from
 
 ### Example {/*example*/}
 
-```jsx
+```jsx {expectedErrors: {'react-compiler': [2]}}
 function App() {
   return <div>{Math.random()}</div>;
 }