Docs: first-principles RSC CSS streaming explanation with diagrams

docs/oss/migrating/rsc-troubleshooting.md

@@ -418,9 +418,13 @@ render-blocking behavior.
 
 For RSC pages, React on Rails Pro injects
 `<link rel="stylesheet" data-precedence="rsc-css">` tags for CSS hrefs whose client chunk names appear
-in the current Flight payload. These links are **render-blocking** for the streamed RSC tree: React
-delays committing the streamed content until the referenced stylesheets are ready, which prevents a
-flash of unstyled content (FOUC) as the tree streams in.
+in the current Flight payload. These links are **render-blocking** for the streamed RSC tree: the
+streaming pipeline places each link in the byte stream ahead of React's inline boundary-reveal
+script, and the browser's stylesheet-blocks-scripts rule holds that script until the CSS has
+loaded, which prevents a flash of unstyled content (FOUC) as the tree streams in. (The gate is
+stream ordering plus browser behavior — React itself does not delay streamed reveals for this CSS.
+See [How CSS reaches the browser](../../pro/react-server-components/css-and-styling.md#how-css-reaches-the-browser)
+for the full mechanism.)
 
 ### Per-reference broadcast multiplication (fixed in the 19.2 line)
 

docs/pro/react-server-components/critical-resource-hints.md

@@ -61,12 +61,18 @@ user input, query parameters, or other request-derived values directly to these
 
 Use hints only for resources that are genuinely needed for the first viewport or early interaction:
 
-- Use `preinit` with `as: 'style'` for critical CSS that should participate in React's stylesheet precedence and
-  streamed boundary reveal behavior. Pass `precedence: 'rsc-css'` when authored critical CSS should
+- Use `preinit` with `as: 'style'` for critical CSS that should participate in React's stylesheet
+  precedence groups. Pass `precedence: 'rsc-css'` when authored critical CSS should
   join the same bucket React on Rails Pro uses for automatically discovered client-reference CSS. Use
   a different explicit `precedence` only when authored critical CSS must be ordered separately, and
   avoid doing that for an `href` that automatic client-reference CSS discovery also emits because
   React dedupes stylesheet preinit hints by URL.
+  Timing caveat: a style `preinit` is emitted as a real stylesheet link only when it reaches the
+  HTML render **before the shell flushes**. After the shell, Fizz emits it as a non-blocking
+  `<link rel="preload">`, and a `preinit` hint never makes a streamed Suspense boundary wait for
+  that CSS — boundary-reveal gating for automatically discovered client-reference CSS is done by
+  the Pro streaming pipeline, not by `preinit`. See
+  [How CSS reaches the browser](./css-and-styling.md#how-css-reaches-the-browser).
 - Use `preload` with `as: 'style'` when you only need to start downloading a stylesheet early.
 - Use `preload` with `as: 'font'` for fonts used by the LCP text. Include the real production font
   URL, `type`, and `crossOrigin` when the font request needs it.