Clarify browser-only rendering guidance

Author: aurorascharff

src/content/reference/react-dom/client/hydrateRoot.md

@@ -319,6 +319,8 @@ export default function App() {
 
 This way the initial render pass will render the same content as the server, avoiding mismatches, but an additional pass will happen synchronously right after hydration.
 
+This approach is useful when you need different content on the server and in the browser. If a component should not render on the server at all, React Canary's [`browser`](/reference/react-dom/browser) API lets you mark it as browser-only without waiting for an Effect.
+
 <Pitfall>
 
 This approach makes hydration slower because your components have to render twice. Be mindful of the user experience on slow connections. The JavaScript code may load significantly later than the initial HTML render, so rendering a different UI immediately after hydration may also feel jarring to the user.

src/content/reference/react/Suspense.md

@@ -2372,6 +2372,8 @@ function Chat() {
 
 The server HTML will include the loading indicator. It will be replaced by the `Chat` component on the client.
 
+In React Canary, call [`use(browser())`](/reference/react/use#use-browser) instead of throwing an error to mark a component as browser-only.
+
 ---
 
 ### <CanaryBadge /> Providing a fallback for browser-only content {/*providing-a-fallback-for-browser-only-content*/}

src/content/reference/react/apis.md

@@ -27,7 +27,7 @@ In addition to [Hooks](/reference/react/hooks) and [Components](/reference/react
 
 To read a value from a resource, use this API:
 
-* [`use`](/reference/react/use) lets you read the value of a resource like a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [context](/learn/passing-data-deeply-with-context).
+* [`use`](/reference/react/use) lets you read the value of a resource like a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [context](/learn/passing-data-deeply-with-context). In Canary, you can also pass it the value returned by [`browser`](/reference/react-dom/browser) to mark a component as browser-only during server rendering.
 ```js
 function MessageComponent({ messagePromise }) {
   const message = use(messagePromise);

src/content/reference/react/use.md

@@ -4,7 +4,7 @@ title: use
 
 <Intro>
 
-`use` is a React API that lets you read the value of a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [context](/learn/passing-data-deeply-with-context).
+`use` is a React API that lets you read the value of a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [context](/learn/passing-data-deeply-with-context). In Canary, you can also pass `use` the value returned by [`browser`](/reference/react-dom/browser) to mark a component as browser-only during server rendering.
 
 ```js
 const value = use(resource);
@@ -1326,6 +1326,8 @@ async function getData(url) {
 
 ---
 
+## Usage (`browser`) {/*usage-browser*/}
+
 ### <CanaryBadge /> Rendering a component only in the browser {/*rendering-a-component-only-in-the-browser*/}
 
 Pass the value returned by [`browser`](/reference/react-dom/browser) to `use` inside a component that should only render in the browser.

src/content/reference/react/useLayoutEffect.md

@@ -734,7 +734,7 @@ However, if you're running into this problem, you have a few different options:
 
 - Replace `useLayoutEffect` with [`useEffect`.](/reference/react/useEffect) This tells React that it's okay to display the initial render result without blocking the paint (because the original HTML will become visible before your Effect runs).
 
-- Alternatively, [mark your component as client-only.](/reference/react/Suspense#providing-a-fallback-for-server-errors-and-client-only-content) This tells React to replace its content up to the closest [`<Suspense>`](/reference/react/Suspense) boundary with a loading fallback (for example, a spinner or a glimmer) during server rendering.
+- Alternatively, [mark your component as client-only.](/reference/react/Suspense#providing-a-fallback-for-server-errors-and-client-only-content) This tells React to replace its content up to the closest [`<Suspense>`](/reference/react/Suspense) boundary with a loading fallback (for example, a spinner or a glimmer) during server rendering. In React Canary, use the [`browser`](/reference/react-dom/browser) API instead of throwing an error to mark the component as browser-only.
 
 - Alternatively, you can render a component with `useLayoutEffect` only after hydration. Keep a boolean `isMounted` state that's initialized to `false`, and set it to `true` inside a `useEffect` call. Your rendering logic can then be like `return isMounted ? <RealContent /> : <FallbackContent />`. On the server and during the hydration, the user will see `FallbackContent` which should not call `useLayoutEffect`. Then React will replace it with `RealContent` which runs on the client only and can include `useLayoutEffect` calls.