Docs: first-principles RSC CSS streaming explanation with diagrams

[justin808]

Summary

Stage 2 of the RSC CSS first-principles engagement (from the 2026-07-07 review discussion): upgrade the canonical CSS doc so an engineer who knows traditional SSR but has never seen RSC internals can correctly answer how streamed RSC CSS actually works. Docs-only — no source files touched (17.0 source freeze respected).

docs/pro/react-server-components/css-and-styling.md (upgraded in place)

• New first-principles "How CSS reaches the browser" section built on the three browser rules the design depends on (head links render-block; in-body pending stylesheets block later inline scripts; preloads never block).
• Three Mermaid diagrams: streamed-response timeline (what blocks what), module map (every TS + Ruby module touching CSS and the data flowing between them), and the two CSS paths (preload promotion vs Flight-chunk inference) converging on the rsc-css bucket.
• New sections: what determines head CSS at first paint; what blocks first paint and what does not; what makes a streamed boundary wait for its own CSS; the exact conditions under which the FOUC pipeline silently does nothing (missing loadable-stats.json, chunk-name/filename shape mismatches, the 100ms fail-open deferral timeout, Rspack stats gap, auto_load_bundle off, external Fizz runtime); and the React-internals coupling inventory ($RC( scraping, hidden-boundary markup, Flight wire format, destination.flush()).

Mechanism corrections (three docs)

The docs previously attributed streamed-reveal CSS gating to React ("React delays committing the streamed content until stylesheets are ready"). Verified against react-dom 19.2.7 source: React's CSS-aware reveal path ($RR) only engages for <link precedence> rendered inside a boundary, which the automatic pipeline never does; a style preinit hint never attaches to boundary state and post-shell degrades to a bare preload. The real gate is stream ordering plus the HTML spec's stylesheet-blocks-scripts rule. Corrected in css-and-styling.md, critical-resource-hints.md, and rsc-troubleshooting.md.

Housekeeping

• Dated status note on internal/analysis/rsc-fouc-shakaperf-investigation.md: its implementation comparison is superseded (the ror-rsc tree-wrapping bridge no longer exists in code); links the ShakaPerf first-visible capture follow-up filed as First-visible capture mode / in-test capture hook for transient FOUC report cards shakaperf#55.
• llms-full.txt / llms-full-pro.txt regenerated.
• Follow-up (separate PR, task chip created): move the 11-file docs/oss/migrating/rsc-* cluster under docs/pro/ so the llms-full split classifies it as Pro content.

Verification

• All behavioral claims verified against react-dom 19.2.7 / react-server-dom-webpack 19.2.7 sources and the current implementation (file:function citations in the doc).
• All 3 Mermaid blocks parse-validated with mermaid@11 (parse(): block 1/2/3 OK). Note: first use of Mermaid in docs/ — the docs website may need @docusaurus/theme-mermaid enabled; GitHub renders natively.
• prettier --check clean on all edited files; node script/generate-llms-full.mjs --check reports current (74 URLs, 8 sidebar sections validated).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified how streamed RSC stylesheet <link> tags are injected so they remain render-blocking via browser pending-stylesheet behavior until CSS loads, reducing flash-of-unstyled-content.
  • Expanded preinit guidance for as: 'style', including when style hints become render-blocking (before shell flush) vs non-blocking (after), and a caveat that reveal gating isn’t controlled by preinit.
  • Reworked the “How CSS reaches the browser” explanation with a streamed timeline, two late-CSS delivery paths, React 19+ data-precedence behavior, and updated known limitations (100ms fail-open timing, legitimate duplicate rsc-css hrefs).
  • Refreshed RSC troubleshooting and Pro resource-hint guidance.

Merge qualification (auto_merge_when_gates_pass)

• Release-mode gate: tracker Release gate: react_on_rails 17.0.0 #3823 Agent Release Mode: development; PR targets main (docs-only). Development mode applies the standard merge qualification — satisfied: CI green on current head, zero unresolved review threads, evidence below. Accelerated-RC confidence block/threshold not applicable.
• Merge authority: granted by maintainer in-session ("Per /pr-batch merge_authority: auto_merge_when_gates_pass").

Confidence note:

• Validated: prettier --check clean on all edited files; node script/generate-llms-full.mjs --check current (74 URLs, 8 sidebar sections); all 3 Mermaid blocks parse-validated with mermaid@11; full CI green on every pushed head (42/42, 41/41, 41/41; final head f226fdefd: 41/41 green, 0 unresolved threads at merge time).
• Evidence: CI check runs on this PR; review threads all resolved with per-thread evidence replies (Greptile Mermaid P1 verified moot against reactonrails.com origin/main docusaurus.config.ts:99,110; CodeRabbit stale-follow-ups fixed in 0feddc962; claude-bot restatement trimmed in 77630f039; Codex first-paint qualification fixed in aa44b7062; claude-bot intro-contradiction fixed in f226fdefd).
• Remaining UNKNOWN facts: whether SSR-side Flight hint replay always lands in the Fizz request context, and whether real app builds use string vs numeric webpack chunk ids — both flagged as open items from the Stage 1 investigation; neither affects the correctness of this documentation or merge safety (docs-only change).
• Residual risk: none beyond normal docs review; no source files touched (17.0 source freeze respected).

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The PR expands RSC stylesheet documentation with precise stream ordering, browser blocking behavior, preinit timing, CSS delivery paths, reveal gating, failure modes, limitations, and updated implementation notes.

Changes

Streamed RSC CSS pipeline

Layer / File(s)	Summary
Streamed CSS pipeline and limitations docs/pro/react-server-components/css-and-styling.md, docs/oss/migrating/rsc-troubleshooting.md, llms-full-pro.txt, llms-full.txt	Documents browser blocking rules, streamed CSS delivery paths, module handoffs, reveal gating, silent no-op conditions, duplicate stylesheet links, React version behavior, and inline $RC( script requirements.

Resource hint timing

Layer / File(s)	Summary
Resource hint timing docs/pro/react-server-components/critical-resource-hints.md, llms-full-pro.txt	Explains when preinit style hints become blocking stylesheet links, when they become non-blocking preloads, and why they do not gate automatically discovered client-reference CSS.

Current implementation notes

Layer / File(s)	Summary
Current implementation notes internal/analysis/rsc-fouc-shakaperf-investigation.md	Marks the earlier implementation comparison as historical, describes the current preinit and injectRSCPayload design, resolves follow-up items, and adds the related ShakaPerf issue reference.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• shakacode/react_on_rails#4143: Updates overlapping RSC CSS documentation around rsc-css link injection and render-blocking behavior.
• shakacode/react_on_rails#4481: Updates related RSC critical resource hint and preinit guidance.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the docs-only change and mentions the new first-principles RSC CSS streaming explanation and diagrams.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/rsc-css-streaming-docs-c8b3f8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR expands the RSC CSS streaming docs and regenerates the LLM docs outputs. The main changes are:

• Rewrites the Pro CSS and styling guide with first-principles streaming behavior.
• Adds Mermaid diagrams for the response timeline, CSS paths, and module map.
• Corrects RSC stylesheet gating descriptions in related docs.
• Adds a dated status note to the ShakaPerf investigation.
• Regenerates llms-full.txt and llms-full-pro.txt.

Confidence Score: 4/5

The docs update is mostly safe, but the new diagrams depend on Mermaid support in the published docs site.

• The changed source links resolve to the target guide and heading.
• The inspected generated LLM docs match the edited source sections.
• The new Mermaid fences can render as raw code if the downstream Docusaurus app does not enable Mermaid.

docs/pro/react-server-components/css-and-styling.md

Important Files Changed

Filename	Overview
docs/pro/react-server-components/css-and-styling.md	Large rewrite of the RSC CSS streaming guide with new Mermaid diagrams; the diagram rendering depends on downstream docs-site Mermaid support.
docs/pro/react-server-components/critical-resource-hints.md	Updates preinit guidance to separate stylesheet precedence from streamed boundary reveal gating.
docs/oss/migrating/rsc-troubleshooting.md	Corrects the RSC stylesheet injection explanation and links to the expanded Pro guide.
internal/analysis/rsc-fouc-shakaperf-investigation.md	Adds a dated note that points readers from the old investigation to the current CSS streaming design.
llms-full.txt	Regenerated OSS LLM docs include the inspected troubleshooting update.
llms-full-pro.txt	Regenerated Pro LLM docs include the inspected CSS and critical-resource-hints updates.

_{Reviews (1): Last reviewed commit: "Docs: first-principles RSC CSS streaming..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/analysis/rsc-fouc-shakaperf-investigation.md`:
- Line 225: Reconcile the stale follow-up entries 3–4 with the current status:
mark them as completed or historical, and note that the downstream bridge is
obsolete and the relevant unit tests already exist. Ensure the investigation’s
follow-up list no longer presents removing the bridge or adding those tests as
future work.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6895d2b3-4aa0-4389-9092-eed6f2dcff7a

📥 Commits

Reviewing files that changed from the base of the PR and between 92b29df and a92380c.

📒 Files selected for processing (6)

• docs/oss/migrating/rsc-troubleshooting.md
• docs/pro/react-server-components/critical-resource-hints.md
• docs/pro/react-server-components/css-and-styling.md
• internal/analysis/rsc-fouc-shakaperf-investigation.md
• llms-full-pro.txt
• llms-full.txt

[claude]

Review: Docs — first-principles RSC CSS streaming explanation

This is a docs-only PR (plus regenerated llms-full*.txt), and it's unusually well-verified for a docs change. I independently checked the specific implementation claims against the current source (not just trusting the PR description) and spot-checked link/anchor integrity.

Technical accuracy — spot-checked against source ✅

All of the specific file/function/constant references I could verify from this repo check out exactly:

• stream.rb#stream_view_containing_react_components streams the rendered layout (head included) as the first chunk — confirmed at react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb:217-278.
• helper.rb#load_pack_for_generated_component → append_stylesheet_pack_tag("generated/...") gated on auto_load_bundle — confirmed at react_on_rails/lib/react_on_rails/helper.rb:438-455.
• injectRSCPayload.ts: RSC_CLIENT_STYLESHEET_INFERENCE_TIMEOUT_MS = 100, LOADABLE_STATS_INITIAL_READ_RETRY_DELAY_MS = 100 → LOADABLE_STATS_MAX_READ_RETRY_DELAY_MS = 30_000, RSC_CLIENT_CHUNK_NAME_WITH_JS_ASSET regex, REACT_SUSPENSE_REVEAL_SCRIPT, findReactSuspenseRevealSplitIndex, promoteStylesheetPreloadTag — all present and matching the doc's description (packages/react-on-rails-pro/src/injectRSCPayload.ts).
• rscDomMarkers.ts / rscHydrationDom.ts — RSC_STYLESHEET_PRECEDENCE = 'rsc-css', prepareRSCHydrationRoot with href+precedence dedup — confirmed.
• ClientSideRenderer.ts — STYLESHEET_LOAD_TIMEOUT_MS = 10_000 and waitForGeneratedComponentStylesheets — confirmed.
• pro_helper.rb#generated_stylesheet_hrefs_json → data-generated-stylesheet-hrefs, gated on Pro + auto_load_bundle — confirmed.
• packages/react-on-rails-pro/tests/injectRSCPayload.test.ts (referenced from internal/analysis/rsc-fouc-shakaperf-investigation.md) exists (2203 lines).
• The claim that no ror-rsc precedence-bridge code remains is accurate — the handful of remaining ror-rsc string hits in the repo are unrelated (a tmpdir prefix, a benchmark app directory name, and a comment noting the old approach was reverted), not live implementation.

Two claims reference the external react-on-rails-rsc package (flight-stylesheet-hints.ts / withStylesheetHints Proxy, and the preinit call inside getReactServerComponent.client.ts's payload-replay path) whose source isn't vendored in this repo, so I couldn't independently verify those specific file/function names — worth double-checking against that package's actual source if you have it handy, since it's the one part of the "coupling to React internals" story I couldn't confirm end-to-end from this checkout. Everything else lines up.

Link/anchor integrity ✅

• All new/updated cross-doc links resolve correctly: docs/oss/migrating/rsc-troubleshooting.md's ../../pro/react-server-components/css-and-styling.md#how-css-reaches-the-browser, critical-resource-hints.md's ./css-and-styling.md#..., and internal/analysis/...'s ../../docs/pro/... all point at the right file and the anchor's heading exists.
• No stale references to the removed "Path 1 / Path 2" heading IDs remain anywhere in the repo (old anchor text fully retired, not just relabeled inconsistently).
• No duplicate heading text was introduced that would create anchor collisions.
• llms-full.txt / llms-full-pro.txt regeneration is consistent with the source doc edits (spot-checked the CSS section appears the correct number of times in each, matching the Pro/OSS split).

One real risk, already self-flagged

This is the first use of Mermaid in docs/, and the PR description correctly notes the live docs site may need @docusaurus/theme-mermaid enabled or the three diagrams will render as raw code blocks. I can't check the docs-site config from this repo (it's not here), so this is worth confirming/tracking before merge rather than assuming GitHub's native rendering is representative of the published site.

Minor nit

The FOUC-pipeline "silently does nothing" table and the "coupling to React internals" section are excellent additions for debugging, but they push css-and-styling.md further toward "deep internals reference" than "guide." Not a blocker — the audience (engineers debugging a flicker) is exactly who needs this — just flag it if the intent is to eventually split "how it works" from "how to debug it" into separate docs as the file keeps growing.

Summary

Substance is strong: this replaces a previously incorrect mechanism explanation ("React delays committing...") with one that's verified against react-dom 19.2.7 source and matches this repo's actual implementation in every place I could check. No source files are touched, so there's no runtime/security/performance surface to review beyond the docs themselves.

[claude]

Review: Docs — first-principles RSC CSS streaming explanation

Overview

Docs-only PR (6 files, no source changes) that rewrites docs/pro/react-server-components/css-and-styling.md's CSS-delivery section from a two-path summary into a first-principles explanation with 3 Mermaid diagrams, and propagates a mechanism correction ("React delays committing streamed content" → "stream ordering + the browser's stylesheet-blocks-scripts rule gates it") into critical-resource-hints.md and rsc-troubleshooting.md. llms-full.txt/llms-full-pro.txt are regenerated in lockstep, and a dated status note is added to the internal ShakaPerf investigation doc.

Verification I did

Since this PR's core value is technical accuracy, I cross-checked every file:function citation against the actual source in this repo rather than just reading prose:

• packages/react-on-rails-pro/src/injectRSCPayload.ts: confirmed RSC_CLIENT_STYLESHEET_INFERENCE_TIMEOUT_MS = 100, RSC_CLIENT_CHUNK_NAME_WITH_JS_ASSET (matches "clientN","js/clientN-<hash>.chunk.js"), RSC_CLIENT_CHUNK_STYLESHEET_PATH (matches /css/clientN-*.css), REACT_SUSPENSE_REVEAL_SCRIPT ($RC(), findReactSuspenseRevealSplitIndex, promoteStylesheetPreloadTag, applyStreamedStylesheetPreloadGating, loadRSCClientChunkStylesheetHrefsByChunkName, and the destination.flush()/setTimeout(0) fallback comment block — all exist and match the doc's description.
• react_on_rails/lib/react_on_rails/helper.rb: load_pack_for_generated_component calls append_stylesheet_pack_tag("generated/#{...}") as described.
• react_on_rails/lib/react_on_rails/pro_helper.rb: generated_stylesheet_hrefs_json does return unless render_options.auto_load_bundle — confirms the doc's "requires auto_load_bundle" claim.
• react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb#stream_view_containing_react_components and packages/react-on-rails-pro/src/rscHydrationDom.ts#prepareRSCHydrationRoot / ClientSideRenderer.ts#waitForGeneratedComponentStylesheets all exist as cited.
• All relative markdown links resolve correctly given the actual directory layout (docs/oss/migrating/rsc-troubleshooting.md → ../../pro/..., internal/analysis/... → ../../docs/pro/...), and all #anchor links match the target headings' GitHub-slug form.
• grep -rl "mermaid" docs confirms this is indeed the first Mermaid usage under docs/, supporting the PR description's self-flagged risk about @docusaurus/theme-mermaid.
• The three "mechanism correction" edits are applied consistently — no leftover "React hoists"/"React delays committing" language remains anywhere in the diff.

I can't verify the React-internals claims themselves ($RR/completeBoundaryWithStyles only engaging for in-boundary <link precedence>, the 19.2 $RB/$RV batching change) since react-dom source isn't vendored in this repo — these rest on the author's stated verification against react-dom 19.2.7/react-server-dom-webpack 19.2.7 sources.

Quality notes

• Diagrams are well-formed: quotes inside Mermaid node labels are correctly escaped as " to avoid breaking node-label parsing, arrow style (solid ->> for requests, dashed -->> for responses/async) is used consistently, and both flowcharts/sequence diagram read cleanly.
• The "why two paths exist" framing (Path A racy / Path B closes the race) is a genuinely useful mental model that wasn't present before.
• Left one inline nit: the "Known limitations" section restates the fail-open timeout, duplicate-href, and $RC( coupling facts a third time (after "Where the late CSS comes from" and "Coupling to React internals" / the silently-does-nothing table). Not incorrect — just consider trimming to a pointer given the doc already cross-links back.

Risks / things to confirm before merge (already flagged by the author, worth double-checking)

• Confirm the docs site actually renders the new Mermaid blocks (needs @docusaurus/theme-mermaid or equivalent) — GitHub renders them natively so this PR's own preview will look fine either way.
• The React-internals claims are effectively unverifiable from this repo; worth a second pair of eyes from someone who can check against a real react-dom 19.2.7 checkout if there's any doubt.

No security or performance concerns — this is a documentation-only change with no source or config files touched.

[claude]

Review: Docs-only RSC CSS streaming rewrite

Reviewed the full diff (docs/pro/react-server-components/css-and-styling.md, critical-resource-hints.md, docs/oss/migrating/rsc-troubleshooting.md, internal/analysis/rsc-fouc-shakaperf-investigation.md, and the regenerated llms-full*.txt). This is a docs-only change (no source files touched), so the review focused on technical accuracy, internal consistency, and cross-reference correctness rather than runtime concerns.

Verification performed

I cross-checked every code-level claim in the rewritten section against the actual source in this repo:

• injectRSCPayload.ts: confirmed RSC_CLIENT_CHUNK_NAME_WITH_JS_ASSET, REACT_SUSPENSE_REVEAL_SCRIPT, RSC_CLIENT_STYLESHEET_INFERENCE_TIMEOUT_MS (100ms), LOADABLE_STATS_MAX_READ_RETRY_DELAY_MS (30s), promoteStylesheetPreloadTag, applyStreamedStylesheetPreloadGating, loadRSCClientChunkStylesheetHrefsByChunkName, findReactSuspenseRevealSplitIndex — all exist and match the described behavior.
• ClientSideRenderer.ts: confirmed waitForGeneratedComponentStylesheets and STYLESHEET_LOAD_TIMEOUT_MS = 10_000 (doc says "up to 10s") — matches.
• rscHydrationDom.ts: confirmed prepareRSCHydrationRoot dedups by href + data-precedence — matches the "two paths, one bucket" dedup claim exactly.
• react_on_rails/lib/react_on_rails/helper.rb (load_pack_for_generated_component → append_stylesheet_pack_tag) and pro_helper.rb (generated_stylesheet_hrefs_json) — both exist as described.
• react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb#stream_view_containing_react_components — exists as described.

All anchor links added (#how-css-reaches-the-browser, #where-the-late-css-comes-from-two-paths-one-bucket, #when-the-fouc-pipeline-silently-does-nothing, #coupling-to-react-internals-what-breaks-where) correctly match the generated GitHub slug for their headers, and all cross-file relative links resolve to real files.

llms-full regeneration

The docs/oss vs docs/pro split is preserved correctly: css-and-styling.md (Pro doc) is fully duplicated only in llms-full-pro.txt, while llms-full.txt (OSS) only picks up the rsc-troubleshooting.md correction, consistent with the current OSS/Pro classification. This confirms the noted follow-up (moving docs/oss/migrating/rsc-* under docs/pro/) is correctly scoped as a separate PR and not silently half-applied here.

Strengths

• The correction itself (React does not gate streamed reveal on CSS; the gate is stream ordering + the HTML "stylesheet blocks scripts" rule) is a real, verifiable fix to a previously misleading claim, and it's now applied consistently across all three docs that repeated the old explanation (css-and-styling.md, critical-resource-hints.md, rsc-troubleshooting.md) — no orphaned old wording found in the diff.
• The "When the FOUC pipeline silently does nothing" table is genuinely useful — it captures real failure modes (chunk-name mismatch, CSS filename mismatch, Rspack stats gap, external Fizz runtime) that are easy to trip over and hard to diagnose without reading the transform source.
• The "Coupling to React internals" section appropriately flags this as a maintenance-fragile area ("re-verify on every React upgrade, including minors") — good practice for documenting an implementation that scrapes Fizz's HTML output as text.
• Good discipline on the internal/analysis file: rather than rewriting history, it adds a dated status note and marks stale follow-ups as resolved with links, which keeps the investigation's still-valid evidence (ShakaPerf results, test patterns) intact.

Minor observations (non-blocking)

• The doc leans on citing internal React behavior ($RR/completeBoundaryWithStyles, React's external Fizz runtime removing inline scripts) that isn't verifiable from this repo — the PR description says these were checked against react-dom 19.2.7 source directly, which is reasonable, but worth double-checking again on the next React minor bump given the doc's own warning about the $RC( literal already having shifted shape in 19.2 ($RB/$RV batching).
• flight-stylesheet-hints.ts (Path A, cited from react-on-rails-rsc) lives in a separate package/repo not present in this checkout, so I could not independently verify that citation — only the React on Rails Pro (injectRSCPayload.ts) side was checkable here.
• Nit: the new head-CSS bullet list duplicates "generated/" pack terminology already used elsewhere in the doc (e.g. "Auto-loaded component packs" section further down) — not a correctness issue, just a first-principles section reiterating what's explained in more depth later. Fine given the stated goal of the section (self-contained first-principles read), but a "see also" back-link there could avoid the reader feeling they're reading the same explanation twice.

Overall: this is an unusually well-verified documentation PR — every internal-behavior claim I checked against source held up, and the corrected mental model (browser-spec gating, not React-feature gating) is accurate and clearly explained. No blocking issues found.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77630f039c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Review: RSC CSS streaming docs (Stage 2)

Docs-only change, no source touched — reviewed for accuracy, internal consistency, and link integrity rather than code correctness/security/perf (not applicable here).

Overview

Substantially rewrites docs/pro/react-server-components/css-and-styling.md's "How CSS reaches the browser" section from first principles (three browser rules, timeline/module-map/two-paths Mermaid diagrams, a "what's not gated" table, a "coupling to React internals" inventory), and corrects a mechanism misattribution ("React delays committing streamed content" → actually stream ordering + the HTML spec's stylesheet-blocks-scripts rule) in three docs. llms-full.txt / llms-full-pro.txt are regenerated to match.

Strengths

• Every cross-reference and anchor link I checked resolves correctly, including the cross-file links from rsc-troubleshooting.md and critical-resource-hints.md into the new css-and-styling.md sections, and the pre-existing anchor into #rsc-stylesheet-cascade-order-end-of-head-precedence (untouched, still valid).
• No dangling references to the removed "Path 1"/"Path 2" headers anywhere else in the docs tree.
• All three Mermaid diagrams are structurally balanced (subgraph/end and loop/end counts match) and use properly escaped quotes inside labels.
• The llms-full.txt/llms-full-pro.txt regeneration is a faithful mirror of the three edited docs, correctly split by Pro vs. OSS classification (css-and-styling.md + critical-resource-hints.md → llms-full-pro.txt; rsc-troubleshooting.md → llms-full.txt).
• Cited TS/Ruby symbols (injectRSCPayload.ts, ClientSideRenderer.ts, rscHydrationDom.ts, helper.rb, pro_helper.rb, stream.rb, etc.) all exist in the repo at the referenced paths.

Issue found

Left an inline comment on docs/oss/migrating/rsc-troubleshooting.md: the corrected paragraph about render-blocking now contradicts the sentence directly above it (outside this diff's hunk), which still attributes the render-blocking behavior itself to React 19's data-precedence support. Per the new (correct) explanation, render-blocking is a plain browser HTML-spec mechanism independent of data-precedence/React version — only the hydration-time hoisting/dedup of the tags actually needs React 19. Worth a follow-up tweak, and note the same paragraph is mirrored in llms-full.txt so a fix needs regenerating that file too. Minor — doesn't block merge on its own.

Not verified

I didn't independently re-verify the React 19.2.7 internals claims ($RC(/$RR/$RB/$RV, completeBoundaryWithStyles, Fizz flush ordering) against the React source — the PR description states these were checked against react-dom/react-server-dom-webpack 19.2.7, and I have no reason to doubt that given the specificity and internal consistency of the write-up.

[claude]

Review

This is a docs-only PR (no application/source code touched) that rewrites docs/pro/react-server-components/css-and-styling.md into a first-principles explanation of RSC CSS streaming, corrects a mechanism attribution in two other docs, regenerates the llms-full.txt / llms-full-pro.txt mirrors, and adds a status note to the internal ShakaPerf investigation doc. Since the requested review dimensions (bugs, security, performance) don't map cleanly onto prose, I focused on verifying the technical/factual claims against the actual implementation and checking internal consistency.

Verified against source — all checked out:

• RSC_CLIENT_STYLESHEET_INFERENCE_TIMEOUT_MS = 100 and the 100ms → 30s loadable-stats retry backoff (LOADABLE_STATS_INITIAL_READ_RETRY_DELAY_MS / LOADABLE_STATS_MAX_READ_RETRY_DELAY_MS) in packages/react-on-rails-pro/src/injectRSCPayload.ts match the doc's claims.
• The $RC( reveal-script regex, the "clientN","js/clientN-<hash>.chunk.js" Flight wire pattern, and the css/clientN-*.css href filter all match what's described in "Coupling to React internals" and the "silently does nothing" table.
• promoteStylesheetPreloadTag / applyStreamedStylesheetPreloadGating (Path A) and the destination.flush() + setTimeout(0) fallback comments in the same file match the doc's Path A/B description.
• Ruby-side references (helper.rb#load_pack_for_generated_component, pro_helper.rb#generated_stylesheet_hrefs_json, stream.rb#stream_view_containing_react_components) all resolve to the correct files/functions.
• waitForGeneratedComponentStylesheets, prepareRSCHydrationRoot, and RSC_STYLESHEET_PRECEDENCE in ClientSideRenderer.ts / rscHydrationDom.ts / rscDomMarkers.ts all exist as described.

Internal consistency:

• New heading anchors (#how-css-reaches-the-browser, #where-the-late-css-comes-from-two-paths-one-bucket, #when-the-fouc-pipeline-silently-does-nothing, #coupling-to-react-internals-what-breaks-where) all match their generated GitHub-flavored-markdown slugs.
• Cross-file relative links (rsc-troubleshooting.md → ../../pro/react-server-components/css-and-styling.md#..., internal/analysis/... → ../../docs/pro/...) resolve to the correct real paths.
• docs/pro/react-server-components/css-and-styling.md and its mirrored sections in llms-full.txt/llms-full-pro.txt are byte-identical, so the manual regeneration was done correctly (I wasn't able to run node script/generate-llms-full.mjs --check myself in this sandbox — the hosted check-llms-full CI workflow will re-verify this on push).

Nothing to flag. No factual errors, broken internal links, or inconsistencies found. The new caveats (fail-open 100ms deferral, dual-path duplicate stylesheet emission, React-internals coupling table) are a genuine improvement — they turn previously-implicit assumptions into an explicit, greppable inventory that should make future React upgrades easier to audit.