Fix Activity prose width and caveat grouping

Author: aurorascharff

src/content/reference/react/Activity.md

@@ -38,92 +38,52 @@ import { Activity } from 'react';
 
 An Activity boundary supports two modes:
 
-- In `visible` mode, React renders the children and runs the setup functions for
-  their `useEffect` and `useLayoutEffect` calls.
-- In `hidden` mode, React hides the children and runs the cleanup functions for
-  their `useEffect` and `useLayoutEffect` calls. React preserves their state and
-  renders updates at a lower priority than updates to visible content.
+- In `visible` mode, React renders the children, attaches their refs, and runs the setup functions for their `useEffect` and `useLayoutEffect` calls.
+- In `hidden` mode, React hides the children, detaches their refs, and runs the cleanup functions for their `useEffect` and `useLayoutEffect` calls. React preserves their state and renders updates at a lower priority than updates to visible content.
 
-When a hidden Activity boundary becomes visible, React reveals its children with
-their previous state and runs their Effect setup functions again.
+When a hidden Activity boundary becomes visible, React reveals its children with their previous state and runs their Effect setup functions again.
 
-In React DOM, hiding an Activity boundary applies `display: none` to the nearest
-DOM elements inside the boundary. React preserves those elements while the
-boundary remains mounted.
+In React DOM, hiding an Activity boundary applies `display: none` to the nearest DOM elements inside the boundary. React preserves those elements while the boundary remains mounted.
+
+Insertion Effects created with [`useInsertionEffect`](/reference/react/useInsertionEffect) remain connected while an Activity boundary is hidden because styles may still be needed by the preserved DOM.
 
 #### Props {/*props*/}
 
-* `children`: The UI rendered by the Activity boundary. `children` can be any
-  [React node](/reference/react/isValidElement#react-elements-vs-react-nodes).
-* **optional** `mode`: Either `'visible'` or `'hidden'`. Defaults to `'visible'`.
-  See [Modes](#modes) for the behavior of each value.
-* **optional** `name`: A string that identifies the Activity boundary in React
-  Developer Tools.
+* `children`: The UI rendered by the Activity boundary. `children` can be any [React node](/reference/react/isValidElement#react-elements-vs-react-nodes).
+* **optional** `mode`: Either `'visible'` or `'hidden'`. Defaults to `'visible'`. See [Modes](#modes) for the behavior of each value.
+* **optional** `name`: A string that identifies the Activity boundary in React Developer Tools.
 
 #### Caveats {/*caveats*/}
 
-- Hiding an Activity boundary retains its state and DOM nodes, so React does not
-  reclaim all memory associated with the hidden subtree.
-- Browser behavior associated with preserved DOM nodes can continue while the
-  boundary is hidden. For example, audio and video can continue playing. Use an
-  Effect cleanup function to stop this behavior.
-  [See an example below.](#my-hidden-components-have-unwanted-side-effects)
-- React runs cleanup functions for Effects created with `useEffect` and
-  `useLayoutEffect` when an Activity boundary becomes hidden. Insertion Effects
-  created with
-  [`useInsertionEffect`](/reference/react/useInsertionEffect)
-  remain connected because styles may still be needed by the preserved DOM.
-- React detaches refs in a hidden Activity boundary and reattaches them when the
-  boundary becomes visible.
-- Content initially rendered inside `<Activity mode="hidden">` is not included in
-  server-rendered HTML. React renders it on the client at a lower priority after
-  hydrating visible content.
-- React omits text-only output while an Activity boundary is hidden because a text
-  node cannot receive `display: none`. The text appears when the boundary becomes
-  visible.
-- If an Activity boundary is inside
-  [`<ViewTransition>`](/reference/react/ViewTransition),
-  changing it from hidden to visible as part of an update started with
-  [`startTransition`](/reference/react/startTransition) activates the `enter`
-  animation. Changing it from visible to hidden as part of that update activates
-  the `exit` animation.
+- Browser behavior associated with preserved DOM nodes can continue while the boundary is hidden. For example, audio and video can continue playing. Use an Effect cleanup function to stop this behavior. [See an example below.](#my-hidden-components-have-unwanted-side-effects)
+- React omits text-only output while an Activity boundary is hidden because a text node cannot receive `display: none`. The text appears when the boundary becomes visible.
+- If an Activity boundary is inside [`<ViewTransition>`](/reference/react/ViewTransition), changing it from hidden to visible as part of an update started with [`startTransition`](/reference/react/startTransition) activates the `enter` animation. Changing it from visible to hidden as part of that update activates the `exit` animation.
 
 ---
 
 ## Usage {/*usage*/}
 
-Activity is useful when part of the UI may become hidden and visible again. Unlike
-conditional rendering, hiding an Activity boundary preserves both React state and
-the DOM state of its children. Unlike hiding content only with CSS, Activity also
-cleans up the children's Effects and deprioritizes their updates while they are
-hidden.
+Activity is useful when part of the UI may become hidden and visible again. Unlike conditional rendering, hiding an Activity boundary preserves both React state and the DOM state of its children. Unlike hiding content only with CSS, Activity also cleans up the children's Effects and deprioritizes their updates while they are hidden.
 
-Use an Activity boundary when preserving that work is valuable—for example, for a
-tab the user is likely to revisit or a panel that can prepare data in the
-background. If the content is unlikely to become visible again, conditionally
-rendering it may be preferable because unmounting allows React and the browser to
-release its resources.
+Use an Activity boundary when preserving that work is valuable—for example, for a tab the user is likely to revisit or a panel that can prepare data in the background. A hidden boundary retains its state and DOM nodes, so it continues using memory. If the content is unlikely to become visible again, conditionally rendering it may be preferable because unmounting allows React and the browser to release its resources.
 
 ### Preserving state while content is hidden {/*restoring-the-state-of-hidden-components*/}
 
-When this condition becomes false, React removes `<Sidebar>` from the tree and
-discards its state:
+When this condition becomes false, React removes `<Sidebar>` from the tree and discards its state:
 
 ```js
 {isShowingSidebar && <Sidebar />}
 ```
 
-Render the component inside an Activity boundary to preserve its state while it is
-hidden:
+Render the component inside an Activity boundary to preserve its state while it is hidden:
 
 ```js
 <Activity mode={isShowingSidebar ? 'visible' : 'hidden'}>
   <Sidebar />
 </Activity>
 ```
 
-In this example, expand the sidebar, hide it, and show it again. The expanded state
-is preserved.
+In this example, expand the sidebar, hide it, and show it again. The expanded state is preserved.
 
 <Sandpack>
 
@@ -208,21 +168,15 @@ main {
 
 </Sandpack>
 
-Changing `mode` preserves the state of the children. Removing the boundary or
-changing a child's type, key, or position can
-[reset its state](/learn/preserving-and-resetting-state).
+Changing `mode` preserves the state of the children. Removing the boundary or changing a child's type, key, or position can [reset its state](/learn/preserving-and-resetting-state).
 
 ---
 
 ### Preserving DOM state while content is hidden {/*restoring-the-dom-of-hidden-components*/}
 
-An Activity boundary also preserves state held by the browser in DOM nodes. This
-includes an uncontrolled input's current value, scroll position, and media
-playback position.
+An Activity boundary also preserves state held by the browser in DOM nodes. This includes an uncontrolled input's current value, scroll position, and media playback position.
 
-In this example, enter a draft in the Contact section, switch sections, and then
-return to Contact. The `<textarea>` value remains because its DOM node was hidden
-rather than removed.
+In this example, enter a draft in the Contact section, switch sections, and then return to Contact. The `<textarea>` value remains because its DOM node was hidden rather than removed.
 
 <Sandpack>
 
@@ -306,18 +260,13 @@ textarea {
 
 </Sandpack>
 
-Preserving DOM state also means that DOM behavior can continue while content is
-hidden. See [Troubleshooting](#my-hidden-components-have-unwanted-side-effects)
-for DOM behavior that requires explicit cleanup.
+Preserving DOM state also means that DOM behavior can continue while content is hidden. See [Troubleshooting](#my-hidden-components-have-unwanted-side-effects) for DOM behavior that requires explicit cleanup.
 
 ---
 
 ### Pre-rendering content that is likely to become visible {/*pre-rendering-content-thats-likely-to-become-visible*/}
 
-An Activity boundary can also prepare content before the user sees it. Content
-inside a hidden boundary renders at a lower priority without running Effects
-created with `useEffect` or `useLayoutEffect`. This lets the content load code and
-render-time data without delaying updates to visible content:
+An Activity boundary can also prepare content before the user sees it. Content inside a hidden boundary renders at a lower priority without running Effects created with `useEffect` or `useLayoutEffect`. This lets the content load code and render-time data without delaying updates to visible content:
 
 ```js
 <Suspense fallback={<Loading />}>
@@ -327,13 +276,9 @@ render-time data without delaying updates to visible content:
 </Suspense>
 ```
 
-If `Posts` suspends while reading code or data, React continues rendering the rest
-of the page. If that hidden work completes, switching to the Posts tab can reveal
-the content without waiting for the same work again.
+If `Posts` suspends while reading code or data, React continues rendering the rest of the page. If that hidden work completes, switching to the Posts tab can reveal the content without waiting for the same work again.
 
-The following example renders the Posts tab in a hidden Activity boundary when the
-page first loads. Wait briefly before selecting **Posts**. The list is available
-immediately because the hidden render started loading it in the background.
+The following example renders the Posts tab in a hidden Activity boundary when the page first loads. Wait briefly before selecting **Posts**. The list is available immediately because the hidden render started loading it in the background.
 
 <Sandpack>
 
@@ -423,31 +368,21 @@ button {
 
 </Sandpack>
 
-If the user selects Posts before the hidden render finishes, the nearest Suspense
-fallback appears until the data is ready. Activity improves the likely case where
-the background work finishes first; it does not guarantee that the content will
-always be ready.
+If the user selects Posts before the hidden render finishes, the nearest Suspense fallback appears until the data is ready. Activity improves the likely case where the background work finishes first; it does not guarantee that the content will always be ready.
 
 <Note>
 
-Only code and data read during rendering can load during pre-rendering. Activity
-does not run Effects in hidden content, so data fetched inside an Effect does not
-load until the boundary becomes visible.
+Only code and data read during rendering can load during pre-rendering. Activity does not run Effects in hidden content, so data fetched inside an Effect does not load until the boundary becomes visible.
 
-The data source must integrate with Suspense. For example, the component can read a
-cached Promise with [`use`](/reference/react/use). See
-[what activates a Suspense boundary](/reference/react/Suspense#what-activates-a-suspense-boundary).
+The data source must integrate with Suspense. For example, the component can read a cached Promise with [`use`](/reference/react/use). See [what activates a Suspense boundary](/reference/react/Suspense#what-activates-a-suspense-boundary).
 
 </Note>
 
 ---
 
 ### Improving hydration performance {/*speeding-up-interactions-during-page-load*/}
 
-Activity boundaries also divide server-rendered pages into units that React can
-hydrate independently. This is related to the selective hydration behavior of
-[`<Suspense>`](/reference/react/Suspense), but it does not require displaying a
-fallback in the initial UI.
+Activity boundaries also divide server-rendered pages into units that React can hydrate independently. This is related to the selective hydration behavior of [`<Suspense>`](/reference/react/Suspense), but it does not require displaying a fallback in the initial UI.
 
 For example, without a boundary React hydrates this page as one unit:
 
@@ -462,8 +397,7 @@ function Page() {
 }
 ```
 
-Wrapping `Comments` in an always-visible Activity boundary creates a separate
-hydration unit:
+Wrapping `Comments` in an always-visible Activity boundary creates a separate hydration unit:
 
 ```js
 function Page() {
@@ -478,10 +412,7 @@ function Page() {
 }
 ```
 
-The boundary is visible because the `mode` prop defaults to `'visible'`. Its
-server-rendered HTML remains visible, but React can hydrate it independently from
-the surrounding page. If the user interacts with that content before React reaches
-it, React prioritizes hydrating the boundary.
+The boundary is visible because the `mode` prop defaults to `'visible'`. Its server-rendered HTML remains visible, but React can hydrate it independently from the surrounding page. If the user interacts with that content before React reaches it, React prioritizes hydrating the boundary.
 
 You can also use visible and hidden Activity boundaries for tabbed content:
 
@@ -509,34 +440,23 @@ function Page() {
 }
 ```
 
-React does not include initially hidden `<Activity>` content in server-rendered HTML.
-On the client, React hydrates the visible content first and renders the hidden
-content later at a lower priority. Initially visible boundaries are included in the
-server-rendered HTML and can be hydrated independently. This allows the visible tab
-and the controls around it to become interactive without waiting for React to
-render the initially hidden tab.
+React does not include initially hidden `<Activity>` content in server-rendered HTML. On the client, React hydrates the visible content first and renders the hidden content later at a lower priority. Initially visible boundaries are included in the server-rendered HTML and can be hydrated independently. This allows the visible tab and the controls around it to become interactive without waiting for React to render the initially hidden tab.
 
 ---
 
 ## Troubleshooting {/*troubleshooting*/}
 
 ### My hidden components have unwanted side effects {/*my-hidden-components-have-unwanted-side-effects*/}
 
-`<Activity>` hides DOM nodes without removing them. Browser-managed behavior from
-elements such as `<video>`, `<audio>`, and `<iframe>` can therefore continue while
-the boundary is hidden.
+`<Activity>` hides DOM nodes without removing them. Browser-managed behavior from elements such as `<video>`, `<audio>`, and `<iframe>` can therefore continue while the boundary is hidden.
 
 <Pitfall>
 
 ##### Preserved media can continue playing {/*preserved-media-can-continue-playing*/}
 
-Unmounting a `<video>` element stops playback because the browser removes the DOM
-node. Hiding it with Activity preserves the node, so playback continues unless the
-component pauses it explicitly.
+Unmounting a `<video>` element stops playback because the browser removes the DOM node. Hiding it with Activity preserves the node, so playback continues unless the component pauses it explicitly.
 
-Add the corresponding cleanup to an Effect. For behavior that must stop at the
-same time React hides the boundary, use
-[`useLayoutEffect`](/reference/react/useLayoutEffect):
+Add the corresponding cleanup to an Effect. For behavior that must stop at the same time React hides the boundary, use [`useLayoutEffect`](/reference/react/useLayoutEffect):
 
 ```js
 import { useLayoutEffect, useRef } from 'react';
@@ -556,17 +476,11 @@ function VideoPlayer({ src }) {
 }
 ```
 
-React runs the cleanup when an enclosing Activity boundary becomes hidden. Because
-the `<video>` node remains in the DOM, its playback position is preserved for when
-the boundary becomes visible again.
+React runs the cleanup when an enclosing Activity boundary becomes hidden. Because the `<video>` node remains in the DOM, its playback position is preserved for when the boundary becomes visible again.
 
-The `useLayoutEffect` cleanup runs as part of hiding the UI. A cleanup from
-`useEffect` can run later if, for example, a Suspense boundary suspends or a View
-Transition is in progress.
+The `useLayoutEffect` cleanup runs as part of hiding the UI. A cleanup from `useEffect` can run later if, for example, a Suspense boundary suspends or a View Transition is in progress.
 
-This complete example pauses the video when you switch to Home while preserving
-its playback position. When you return to Video, playback can continue from the
-same position without recreating the element or downloading it again.
+This complete example pauses the video when you switch to Home while preserving its playback position. When you return to Video, playback can continue from the same position without recreating the element or downloading it again.
 
 <Sandpack>
 
@@ -651,16 +565,11 @@ video {
 
 ### My hidden components have Effects that are not running {/*my-hidden-components-have-effects-that-arent-running*/}
 
-React runs cleanup functions for Effects created with `useEffect` and
-`useLayoutEffect` when an Activity boundary becomes hidden. It runs their setup
-functions again when the boundary becomes visible.
+React runs cleanup functions for Effects created with `useEffect` and `useLayoutEffect` when an Activity boundary becomes hidden. It runs their setup functions again when the boundary becomes visible.
 
-An Effect inside a hidden Activity boundary cannot remain active. Move ongoing
-work that must continue while the UI is hidden to a component outside the boundary,
-or keep the boundary visible.
+An Effect inside a hidden Activity boundary cannot remain active. Move ongoing work that must continue while the UI is hidden to a component outside the boundary, or keep the boundary visible.
 
-If an Effect controls an external system, return a cleanup function so hiding the
-boundary disconnects from that system:
+If an Effect controls an external system, return a cleanup function so hiding the boundary disconnects from that system:
 
 ```js
 useEffect(() => {
@@ -673,6 +582,4 @@ useEffect(() => {
 }, []);
 ```
 
-Use [`<StrictMode>`](/reference/react/StrictMode) to find Effects that do not clean
-up correctly. Strict Mode performs an additional setup and cleanup cycle in
-development.
+Use [`<StrictMode>`](/reference/react/StrictMode) to find Effects that do not clean up correctly. Strict Mode performs an additional setup and cleanup cycle in development.