Polish browser API docs and add live example

Author: aurorascharff

src/content/reference/react-dom/browser.md

@@ -3,6 +3,8 @@ title: browser
 version: canary
 ---
 
+<Intro>
+
 <Canary>
 
 **The `browser` API is currently only available in React’s Canary and Experimental channels.**
@@ -11,12 +13,10 @@ version: canary
 
 </Canary>
 
-<Intro>
-
-`browser` lets you skip rendering part of a React tree on the server, leaving its nearest Suspense fallback in place until that content renders in the browser.
+`browser` lets you render part of a React tree only in the browser.
 
 ```js
-use(browser(reason?));
+use(browser(reason?))
 ```
 
 </Intro>
@@ -41,24 +41,24 @@ function BrowserOnly() {
 }
 ```
 
-During server rendering, `use(browser())` stops rendering the component and renders the fallback of the closest [`<Suspense>`](/reference/react/Suspense) boundary instead. In the browser, it has no effect, so the component renders normally.
+During server rendering, `use(browser())` stops rendering the component and leaves the closest [`<Suspense>`](/reference/react/Suspense) boundary's fallback in its place. In the browser, `use(browser())` returns `undefined`, so the component renders normally.
 
 [See more examples below.](#usage)
 
 #### Parameters {/*parameters*/}
 
-* **optional** `reason`: A string or function that provides diagnostic information about why rendering should happen only in the browser. React calls a reason function each time a server renderer encounters the value returned by `browser`; it never calls it in the browser. Use a function for values that are expensive to create, such as `() => new Error(...)`. The resulting value becomes the `cause` of the `Error` passed to `onBrowserBailout`.
+* **optional** `reason`: A string or function that explains why the content needs to render in the browser. If you pass a function, React calls it each time a server renderer encounters the value returned by `browser`. React does not call it in the browser. Use a function for values that are expensive to create, such as `() => new Error(...)`. The string or the function's return value becomes the `cause` of the `Error` passed to `onBrowserBailout`.
 
 #### Returns {/*returns*/}
 
-`browser` returns an opaque value. Pass this value to `use` in a component, or use it as the reason when [aborting a server render](#aborting-pending-server-rendering-for-the-browser). In the browser, passing this value to `use` returns `undefined`.
+`browser` returns a value that you can pass to `use` in a component or use as the reason when [aborting a server render](#aborting-pending-server-rendering-for-the-browser). In the browser, passing this value to `use` returns `undefined`.
 
 #### Caveats {/*caveats*/}
 
-* A component that passes a value returned by `browser` to `use` during server rendering must have a `<Suspense>` boundary above it. Otherwise, the entire server render will fail.
-* `browser` is not available in a `react-server` environment. You can use it while server-rendering Client Components, but you cannot import it in a [React Server Component](/reference/rsc/server-components).
-* Calling `browser()` by itself does not check the current environment or affect rendering. To trigger its behavior, pass the return value to `use` or use it to abort a server render. This means you can create the value at module scope and reuse it.
-* To defer a component, pass the value returned by `browser` to `use`. Do not throw the value directly.
+* `use(browser())` must be inside a `<Suspense>` boundary during server rendering. Without one, the server render fails.
+* `browser` is not available in a `react-server` environment. You can use it while rendering Client Components on the server, but you cannot import it in a [React Server Component](/reference/rsc/server-components).
+* Calling `browser()` by itself has no effect. You can create the value at module scope and reuse it.
+* To skip rendering a component on the server, pass the value returned by `browser` to `use`. Do not throw it.
 
 ---
 
@@ -68,16 +68,20 @@ During server rendering, `use(browser())` stops rendering the component and rend
 
 Call `use` with the value returned by `browser` to skip rendering a component on the server:
 
-```js
+Press **Render on the server** to see the fallback first. The demo waits briefly before hydrating and showing the browser-only editor.
+
+<Sandpack>
+
+```js src/App.js active
 import { Suspense, use } from 'react';
 import { browser } from 'react-dom';
 
 function BrowserOnlyEditor() {
   use(browser('The editor requires browser APIs.'));
-  return <Editor />;
+  return <label>Draft: <input /></label>;
 }
 
-export default function Page() {
+export default function App() {
   return (
     <Suspense fallback={<p>Loading editor...</p>}>
       <BrowserOnlyEditor />
@@ -86,13 +90,122 @@ export default function Page() {
 }
 ```
 
-During server rendering, React includes the `Loading editor...` fallback in the HTML. When the app renders in the browser, `use(browser())` continues immediately and React renders the `Editor` instead.
+```js src/Document.js hidden
+import App from './App.js';
+
+export default function Document() {
+  return (
+    <html lang="en">
+      <head>
+        <title>Article editor</title>
+      </head>
+      <body>
+        <h1>Article editor</h1>
+        <App />
+      </body>
+    </html>
+  );
+}
+```
+
+```js src/index.js
+import { hydrateRoot } from 'react-dom/client';
+import { renderToReadableStream } from 'react-dom/server';
+import Document from './Document.js';
+import { flushReadableStreamToFrame } from './demo-helpers.js';
+import './styles.css';
+
+async function main(frame) {
+  const stream = await renderToReadableStream(<Document />);
+  await flushReadableStreamToFrame(stream, frame);
+
+  // Wait so both the fallback and hydrated content are visible.
+  await new Promise(resolve => setTimeout(resolve, 1200));
+  hydrateRoot(frame.contentDocument, <Document />);
+}
+
+const renderButton = document.getElementById('render');
+renderButton.addEventListener('click', () => {
+  renderButton.disabled = true;
+  main(document.getElementById('preview'));
+}, { once: true });
+```
+
+```js src/demo-helpers.js hidden
+export async function flushReadableStreamToFrame(readable, frame) {
+  const doc = frame.contentWindow.document;
+  const decoder = new TextDecoder();
+  for await (const chunk of readable) {
+    doc.write(decoder.decode(chunk, { stream: true }));
+  }
+  doc.close();
+}
+```
+
+```html public/index.html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Browser-only rendering</title>
+</head>
+<body>
+  <button id="render">Render on the server</button>
+  <br /><br />
+  <iframe id="preview" title="Rendered page"></iframe>
+</body>
+</html>
+```
+
+```css src/styles.css hidden
+iframe {
+  width: 100%;
+  height: 180px;
+  border: 1px solid #aaa;
+}
+```
+
+```json package.json hidden
+{
+  "dependencies": {
+    "react": "canary",
+    "react-dom": "canary",
+    "react-scripts": "latest"
+  },
+  "scripts": {
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "test": "react-scripts test --env=jsdom",
+    "eject": "react-scripts eject"
+  }
+}
+```
+
+</Sandpack>
+
+<Note>
+
+In a React Server Components app, `use(browser())` must be called from a Client Component. If your framework uses Server Components by default, add the [`'use client'`](/reference/rsc/use-client) directive to that file or move the call to a child Client Component:
+
+```js {1}
+'use client';
+
+import { use } from 'react';
+import { browser } from 'react-dom';
+
+export default function BrowserOnlyEditor() {
+  use(browser('The editor requires browser APIs.'));
+  return <Editor />;
+}
+```
+
+</Note>
 
 ---
 
 ### Conditionally rendering in the browser {/*conditionally-rendering-in-the-browser*/}
 
-Like other calls to [`use`](/reference/react/use), `use(browser())` can be called conditionally, including inside a custom Hook. For example, you can wrap a Suspense-enabled data-fetching library's `useQuery` to render initial data on the server, but defer to the browser when that data is missing:
+Like other calls to [`use`](/reference/react/use), you can call `use(browser())` conditionally or inside a custom Hook. For example, you can wrap a Suspense-enabled data-fetching library's `useQuery` and skip server rendering when initial data is missing:
 
 ```js {3}
 function useBrowserQuery(query, options) {
@@ -112,13 +225,13 @@ function ProductDetails({ productId, initialData }) {
 }
 ```
 
-On the server, `useBrowserQuery` calls the underlying `useQuery` only when `initialData` is available. Otherwise, `use(browser())` leaves the nearest Suspense fallback in the HTML. In the browser, `use(browser())` continues immediately, so the query library can fetch the data or read it from its client cache.
+On the server, `useBrowserQuery` calls `useQuery` only when `initialData` is available. Otherwise, the closest Suspense boundary's fallback remains in the HTML. In the browser, `use(browser())` returns `undefined`, so the query library can fetch the data or read it from its client cache.
 
 ---
 
 ### Reporting browser-only rendering on the server {/*reporting-browser-only-rendering-on-the-server*/}
 
-Provide `onBrowserBailout` to the server renderer to report browser-only rendering. React does not report a browser-only render recovered by a Suspense boundary to the server renderer's `onError` callback or [`hydrateRoot`'s `onRecoverableError`](/reference/react-dom/client/hydrateRoot#error-logging-in-production) callback. This example also passes an optional reason, which React makes available as the reported error's `cause`:
+Pass an `onBrowserBailout` callback to the server renderer to report browser-only rendering. When React leaves a Suspense fallback for the browser, it does not call the server renderer's `onError` callback or [`hydrateRoot`'s `onRecoverableError`](/reference/react-dom/client/hydrateRoot#error-logging-in-production) callback. This example also passes a reason, which is available as the reported error's `cause`:
 
 ```js
 import { Suspense, use } from 'react';
@@ -147,18 +260,18 @@ const { pipe } = renderToPipeableStream(
 
 `onBrowserBailout` receives two arguments:
 
-1. An `Error` describing the browser-only render. If a reason was supplied to `browser`, it is available as the error's `cause`.
-2. An `errorInfo` object containing the `componentStack` of the browser-only render.
+1. An `Error` describing the browser-only render. If you passed a reason to `browser`, it is available as the error's `cause`.
+2. An `errorInfo` object with a `componentStack` showing where browser-only rendering occurred.
 
-The reason function can return any value. Returning a new `Error` gives the cause its own stack without creating that `Error` during rendering in the browser. React does not serialize the reason into the HTML.
+The reason function can return any value. Return a new `Error` to give the cause its own stack without creating the `Error` in the browser. React does not serialize the reason into the HTML.
 
-If there is no Suspense boundary to provide a fallback, the server render fails. React reports the failure through the renderer's normal error callbacks instead of `onBrowserBailout`.
+If there is no Suspense boundary to provide a fallback, the server render fails. React reports the failure through the renderer's usual error callbacks instead of `onBrowserBailout`.
 
 ---
 
 ### Aborting pending server rendering for the browser {/*aborting-pending-server-rendering-for-the-browser*/}
 
-You can pass the value returned by `browser` as the reason for aborting a server render. This leaves pending Suspense boundaries in their fallback state so React can render their content in the browser:
+Pass the value returned by `browser` as the reason when aborting a server render. React then leaves pending Suspense boundaries in their fallback state and renders their content in the browser:
 
 ```js {1,8}
 import { browser } from 'react-dom';
@@ -174,6 +287,6 @@ const { pipe, abort } = renderToPipeableStream(<App />, {
 });
 ```
 
-Unlike other abort reasons, a value returned by `browser` is not reported to the server renderer's `onError` callback or to `hydrateRoot`'s `onRecoverableError` callback. The server renderer reports each recovered Suspense boundary to `onBrowserBailout` instead.
+A `browser` abort reason does not trigger the server renderer's `onError` callback or `hydrateRoot`'s `onRecoverableError` callback. Instead, the server renderer reports each recovered Suspense boundary to `onBrowserBailout`.
 
 For server rendering APIs that accept an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal), pass `browser()` as the reason to [`AbortController.abort`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort).

src/content/reference/react-dom/index.md

@@ -34,7 +34,7 @@ These APIs can be used to make apps faster by pre-loading resources such as scri
 
 This API controls how components render on the server:
 
-* <CanaryBadge /> [`browser`](/reference/react-dom/browser) lets you skip rendering part of a React tree on the server, leaving its nearest Suspense fallback in place until that content renders in the browser.
+* <CanaryBadge /> [`browser`](/reference/react-dom/browser) lets you render part of a React tree only in the browser.
 
 ---