Merge remote-tracking branch 'origin/main' into claude/4238-rsc-compression

* origin/main:
  Generate Tailwind as a layout-owned pack (#4182)
  [Pro] Test rejected RSC replacement retry notifications (#4250)

Author: justin808

.lychee.toml

@@ -88,6 +88,8 @@ exclude = [
   '^https://vite-ruby\.netlify\.app/?$',     # Intermittent connection resets from CI
   '^https://www\.developerway\.com/posts/react-server-components-performance$', # Returns 503 from CI
   '^https://webaim\.org/techniques/css/invisiblecontent/?$', # Returns 504 from CI
+  '^https://compiledcssinjs\.com/?$', # Times out during automated link checks
+  '^https://vanilla-extract\.style/?$', # Times out during automated link checks
 
   # ============================================================================
   # PLANNED DEPLOYMENTS NOT YET LIVE

CHANGELOG.md

@@ -60,6 +60,8 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
   [PR 4249](https://github.com/shakacode/react_on_rails/pull/4249) by
   [justin808](https://github.com/justin808).
 
+- **Generated Tailwind apps load Tailwind from the layout.** The install generator now declares Tailwind through a layout-owned pack instead of component-owned imports, keeps generated layout head metadata mobile/CSP-ready, and warns safely when custom layouts need manual pack-tag replacement. [PR 4182](https://github.com/shakacode/react_on_rails/pull/4182) by [ihabadham](https://github.com/ihabadham).
+
 - **[Pro]** **Rspack RSC dev-server setup is easier to diagnose and customize**:
   Generated RSC helper code now verifies client-reference discovery support
   through the sibling `rscWebpackConfig.js` file instead of assuming

docs/oss/building-features/styling-with-tailwind.md

@@ -39,29 +39,41 @@ It also creates `app/javascript/stylesheets/application.css`:
 
 <!-- prettier-ignore -->
 ```css
-@import "tailwindcss";
+@import "tailwindcss" source("../..");
 ```
 
-The generated `HelloWorld.client.jsx` or `HelloWorld.client.tsx` imports that CSS
-file and uses Tailwind utility classes. The shared `commonWebpackConfig.js`
-template inserts `postcss-loader` after `css-loader` and configures
-`@tailwindcss/postcss`, regardless of whether the project uses Webpack or Rspack.
+The generator also creates `app/javascript/packs/react_on_rails_tailwind.js`
+to import the Tailwind stylesheet and declares that pack from
+`app/views/layouts/react_on_rails_default.html.erb`:
+
+```erb
+<% prepend_javascript_pack_tag "react_on_rails_tailwind" %>
+<%= stylesheet_pack_tag "react_on_rails_tailwind", media: "all" %>
+<%= javascript_pack_tag %>
+```
+
+The generated `HelloWorld.client.jsx` or `HelloWorld.client.tsx` uses Tailwind
+utility classes but does not import the global stylesheet. The shared
+`commonWebpackConfig.js` template inserts `postcss-loader` after `css-loader`
+and configures `@tailwindcss/postcss`, regardless of whether the project uses
+Webpack or Rspack.
 
 ## Server Rendering Without a Flash of Unstyled Content
 
-The generated example keeps two pieces together:
+The generated example keeps three pieces together:
 
 1. `app/views/hello_world/index.html.erb` renders the component with
    `prerender: true`.
-2. `app/views/layouts/react_on_rails_default.html.erb` keeps
-   `<%= stylesheet_pack_tag %>` in the document head before
+2. `app/javascript/packs/react_on_rails_tailwind.js` imports the Tailwind
+   stylesheet as an app-level pack.
+3. `app/views/layouts/react_on_rails_default.html.erb` keeps
+   `<%= stylesheet_pack_tag "react_on_rails_tailwind", media: "all" %>` before
    `<%= javascript_pack_tag %>`.
 
-When React on Rails auto-loads the generated component pack, it appends the
-generated component stylesheet pack. In a production build, Shakapacker emits
-that stylesheet as an extracted CSS `<link>` in the SSR HTML. Do not remove the
-empty `stylesheet_pack_tag`; it is the placeholder React on Rails uses to insert
-component CSS and avoid a Tailwind flash of unstyled content.
+Tailwind is layout-owned because it is global app styling. The generated
+components only reference Tailwind class names. Do not move the Tailwind CSS
+import back into a generated component; pages that use Tailwind classes but do
+not load that component would then depend on the wrong pack for global styles.
 
 In development, CSS can be injected by the dev server instead of extracted as a
 static link. Use a production build when validating the no-FOUC path.
@@ -76,8 +88,9 @@ npm install tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postc
 yarn add tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postcss-loader@^8.2.1
 ```
 
-Then create a CSS entry, import it from your client component or client pack,
-and add `postcss-loader` after `css-loader` in your shared bundler config:
+Then create a CSS entry, import it from an app-level client pack that your
+layout declares, and add `postcss-loader` after `css-loader` in your shared
+bundler config:
 
 ```javascript
 {
@@ -90,8 +103,9 @@ and add `postcss-loader` after `css-loader` in your shared bundler config:
 }
 ```
 
-Keep the SSR view prerendered and keep `stylesheet_pack_tag` in the layout head
-so the generated component CSS can be emitted before the JavaScript runs.
+Keep the SSR view prerendered and keep the Tailwind stylesheet pack tag in the
+layout head so the app-level Tailwind CSS can be emitted before the JavaScript
+runs when Shakapacker is configured to emit stylesheet links.
 
 Tailwind v3 projects should use Tailwind's v3 PostCSS setup instead of this v4
 recipe.

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

@@ -302,36 +302,46 @@ three-bundle architecture.
 
 **How Tailwind works with RSC:**
 
-1. Tailwind runs as a PostCSS plugin during the client bundle build only.
-2. It scans all files listed in its `content` configuration for utility class names.
-3. The generated CSS is extracted into the client stylesheet.
+1. Tailwind/PostCSS follows each bundle's CSS loader pipeline when CSS imports are processed, but
+   only the client bundle emits browser-loadable CSS.
+2. Tailwind scans configured source roots for utility class names. Tailwind v4 uses CSS `@source`
+   directives; Tailwind v3 uses the `content` array.
+3. The generated CSS is delivered through a layout-owned client pack.
 4. Server Components and Client Components both use Tailwind class names as plain strings.
-5. The CSS loads from the Rails layout's `stylesheet_pack_tag`.
+5. The CSS loads according to the Rails layout's Shakapacker pack tags.
 
-**Critical configuration:** The Tailwind `content` array must include all directories that contain
-files using Tailwind classes, including React component files and ERB views:
+**Critical configuration:** Tailwind must scan every directory that contains utility class names,
+including React component files and ERB views. Tailwind v4 configures those roots from CSS
+`@source` directives; Tailwind v3 uses the `content` array.
 
 #### Tailwind CSS v4 (new apps)
 
 The React on Rails generator supports Tailwind v4 via `--tailwind`. Tailwind v4 uses a CSS-first
 configuration model:
 
+<!-- prettier-ignore -->
 ```css
-/* app/javascript/styles/application.css */
-@import 'tailwindcss';
+/* app/javascript/stylesheets/application.css */
+@import "tailwindcss" source("../..");
 ```
 
 ```js
-// postcss.config.mjs
-export default {
-  plugins: {
-    '@tailwindcss/postcss': {},
-  },
-};
+// app/javascript/packs/react_on_rails_tailwind.js
+import '../stylesheets/application.css';
+```
+
+The generated React on Rails layout declares that pack from the layout:
+
+```erb
+<% prepend_javascript_pack_tag "react_on_rails_tailwind" %>
+<%= stylesheet_pack_tag "react_on_rails_tailwind", media: "all" %>
+<%= javascript_pack_tag %>
 ```
 
-Tailwind v4 auto-discovers source files without a `content` configuration. It scans the project
-tree automatically.
+Tailwind v4 uses CSS-level source discovery. The generated stylesheet points at the Rails `app/`
+directory by default so Tailwind scans app source without scanning the whole repository, build
+output, logs, or runtime directories. If your components live outside that source tree, add
+additional Tailwind `@source` lines to the stylesheet.
 
 #### Tailwind CSS v3 (existing apps)
 

llms-full-pro.txt

@@ -5680,36 +5680,46 @@ three-bundle architecture.
 
 **How Tailwind works with RSC:**
 
-1. Tailwind runs as a PostCSS plugin during the client bundle build only.
-2. It scans all files listed in its `content` configuration for utility class names.
-3. The generated CSS is extracted into the client stylesheet.
+1. Tailwind/PostCSS follows each bundle's CSS loader pipeline when CSS imports are processed, but
+   only the client bundle emits browser-loadable CSS.
+2. Tailwind scans configured source roots for utility class names. Tailwind v4 uses CSS `@source`
+   directives; Tailwind v3 uses the `content` array.
+3. The generated CSS is delivered through a layout-owned client pack.
 4. Server Components and Client Components both use Tailwind class names as plain strings.
-5. The CSS loads from the Rails layout's `stylesheet_pack_tag`.
+5. The CSS loads according to the Rails layout's Shakapacker pack tags.
 
-**Critical configuration:** The Tailwind `content` array must include all directories that contain
-files using Tailwind classes, including React component files and ERB views:
+**Critical configuration:** Tailwind must scan every directory that contains utility class names,
+including React component files and ERB views. Tailwind v4 configures those roots from CSS
+`@source` directives; Tailwind v3 uses the `content` array.
 
 #### Tailwind CSS v4 (new apps)
 
 The React on Rails generator supports Tailwind v4 via `--tailwind`. Tailwind v4 uses a CSS-first
 configuration model:
 
+<!-- prettier-ignore -->
 ```css
-/* app/javascript/styles/application.css */
-@import 'tailwindcss';
+/* app/javascript/stylesheets/application.css */
+@import "tailwindcss" source("../..");
 ```
 
 ```js
-// postcss.config.mjs
-export default {
-  plugins: {
-    '@tailwindcss/postcss': {},
-  },
-};
+// app/javascript/packs/react_on_rails_tailwind.js
+import '../stylesheets/application.css';
+```
+
+The generated React on Rails layout declares that pack from the layout:
+
+```erb
+<% prepend_javascript_pack_tag "react_on_rails_tailwind" %>
+<%= stylesheet_pack_tag "react_on_rails_tailwind", media: "all" %>
+<%= javascript_pack_tag %>
 ```
 
-Tailwind v4 auto-discovers source files without a `content` configuration. It scans the project
-tree automatically.
+Tailwind v4 uses CSS-level source discovery. The generated stylesheet points at the Rails `app/`
+directory by default so Tailwind scans app source without scanning the whole repository, build
+output, logs, or runtime directories. If your components live outside that source tree, add
+additional Tailwind `@source` lines to the stylesheet.
 
 #### Tailwind CSS v3 (existing apps)
 

llms-full.txt

@@ -9020,29 +9020,41 @@ It also creates `app/javascript/stylesheets/application.css`:
 
 <!-- prettier-ignore -->
 ```css
-@import "tailwindcss";
+@import "tailwindcss" source("../..");
 ```
 
-The generated `HelloWorld.client.jsx` or `HelloWorld.client.tsx` imports that CSS
-file and uses Tailwind utility classes. The shared `commonWebpackConfig.js`
-template inserts `postcss-loader` after `css-loader` and configures
-`@tailwindcss/postcss`, regardless of whether the project uses Webpack or Rspack.
+The generator also creates `app/javascript/packs/react_on_rails_tailwind.js`
+to import the Tailwind stylesheet and declares that pack from
+`app/views/layouts/react_on_rails_default.html.erb`:
+
+```erb
+<% prepend_javascript_pack_tag "react_on_rails_tailwind" %>
+<%= stylesheet_pack_tag "react_on_rails_tailwind", media: "all" %>
+<%= javascript_pack_tag %>
+```
+
+The generated `HelloWorld.client.jsx` or `HelloWorld.client.tsx` uses Tailwind
+utility classes but does not import the global stylesheet. The shared
+`commonWebpackConfig.js` template inserts `postcss-loader` after `css-loader`
+and configures `@tailwindcss/postcss`, regardless of whether the project uses
+Webpack or Rspack.
 
 ## Server Rendering Without a Flash of Unstyled Content
 
-The generated example keeps two pieces together:
+The generated example keeps three pieces together:
 
 1. `app/views/hello_world/index.html.erb` renders the component with
    `prerender: true`.
-2. `app/views/layouts/react_on_rails_default.html.erb` keeps
-   `<%= stylesheet_pack_tag %>` in the document head before
+2. `app/javascript/packs/react_on_rails_tailwind.js` imports the Tailwind
+   stylesheet as an app-level pack.
+3. `app/views/layouts/react_on_rails_default.html.erb` keeps
+   `<%= stylesheet_pack_tag "react_on_rails_tailwind", media: "all" %>` before
    `<%= javascript_pack_tag %>`.
 
-When React on Rails auto-loads the generated component pack, it appends the
-generated component stylesheet pack. In a production build, Shakapacker emits
-that stylesheet as an extracted CSS `<link>` in the SSR HTML. Do not remove the
-empty `stylesheet_pack_tag`; it is the placeholder React on Rails uses to insert
-component CSS and avoid a Tailwind flash of unstyled content.
+Tailwind is layout-owned because it is global app styling. The generated
+components only reference Tailwind class names. Do not move the Tailwind CSS
+import back into a generated component; pages that use Tailwind classes but do
+not load that component would then depend on the wrong pack for global styles.
 
 In development, CSS can be injected by the dev server instead of extracted as a
 static link. Use a production build when validating the no-FOUC path.
@@ -9057,8 +9069,9 @@ npm install tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postc
 yarn add tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postcss-loader@^8.2.1
 ```
 
-Then create a CSS entry, import it from your client component or client pack,
-and add `postcss-loader` after `css-loader` in your shared bundler config:
+Then create a CSS entry, import it from an app-level client pack that your
+layout declares, and add `postcss-loader` after `css-loader` in your shared
+bundler config:
 
 ```javascript
 {
@@ -9071,8 +9084,9 @@ and add `postcss-loader` after `css-loader` in your shared bundler config:
 }
 ```
 
-Keep the SSR view prerendered and keep `stylesheet_pack_tag` in the layout head
-so the generated component CSS can be emitted before the JavaScript runs.
+Keep the SSR view prerendered and keep the Tailwind stylesheet pack tag in the
+layout head so the app-level Tailwind CSS can be emitted before the JavaScript
+runs when Shakapacker is configured to emit stylesheet links.
 
 Tailwind v3 projects should use Tailwind's v3 PostCSS setup instead of this v4
 recipe.

packages/react-on-rails-pro/tests/boundedCacheProvider.client.test.tsx

@@ -1467,4 +1467,93 @@ describe('RSCRoute successful-version error reset', () => {
     const key = createRSCPayloadKey('Card', { id: 0 });
     await waitFor(() => expect(rscApi.successfulVersions[key]).toBeGreaterThan(0));
   });
+
+  it('p. rejected replacement loads evict their promise and restore the evicted-success marker', async () => {
+    type PendingEntry = Deferred & { args: GetServerComponentArgs };
+    const pending: PendingEntry[] = [];
+    getServerComponent = jest.fn((..._args: [GetServerComponentArgs]) => {
+      const d = makeDeferred();
+      pending.push({ ...d, args: _args[0] });
+      return d.promise;
+    });
+    RSCProvider = createRSCProvider({ getServerComponent });
+
+    let rscApi!: ReturnType<typeof useRSC>;
+    const Probe = () => {
+      rscApi = useRSC();
+      return null;
+    };
+    await renderInAct(
+      <RSCProvider>
+        <Probe />
+      </RSCProvider>,
+    );
+
+    const startLoad = async (id: number) => {
+      let promise!: Promise<React.ReactNode>;
+      await act(async () => {
+        promise = rscApi.getComponent('Card', { id });
+        await Promise.resolve();
+      });
+      return { promise, deferred: findPendingForId(pending, id) };
+    };
+
+    const resolveLoad = async (started: Awaited<ReturnType<typeof startLoad>>, payload: React.ReactNode) => {
+      await act(async () => {
+        started.deferred.resolve(payload);
+        await started.promise;
+        // Unlike peers k-o, flush the timer-scheduled unpin after each resolve;
+        // otherwise the fill loop keeps every entry pinned and never records
+        // the evicted-success marker that the retry assertions depend on.
+        await flushMacrotasks();
+      });
+    };
+
+    const rejectLoad = async (started: Awaited<ReturnType<typeof startLoad>>, message: string) => {
+      void started.promise.catch(() => undefined);
+      await act(async () => {
+        started.deferred.reject(new Error(message));
+        await expect(started.promise).rejects.toThrow(message);
+        // evictPromiseIfRejected removes the cached promise via setTimeout(0),
+        // so wait one macrotask before asserting the slot is free.
+        await flushMacrotasks();
+      });
+    };
+
+    // Give ids 0..CACHE_CAP a successful payload. Loading the (cap+1)-th key
+    // evicts id 0 and records its "last successful payload was evicted" marker.
+    for (let id = 0; id <= CACHE_CAP; id += 1) {
+      // eslint-disable-next-line no-await-in-loop
+      const started = await startLoad(id);
+      // eslint-disable-next-line no-await-in-loop
+      await resolveLoad(started, <span>{`initial ${id}`}</span>);
+    }
+
+    const key = createRSCPayloadKey('Card', { id: 0 });
+    expect(rscApi.successfulVersions[key] ?? 0).toBe(0);
+
+    // Start id 0's replacement load while its evicted-success marker is
+    // present, then churn enough other successful evictions to push that marker
+    // out of the bounded marker LRU before the replacement rejects. The retry
+    // below only notifies routes if the rejection path restores the marker from
+    // the in-flight latch.
+    const failedReplacement = await startLoad(0);
+    for (let id = CACHE_CAP + 1; id <= CACHE_CAP + MARKER_CAP + 2; id += 1) {
+      // eslint-disable-next-line no-await-in-loop
+      const started = await startLoad(id);
+      // eslint-disable-next-line no-await-in-loop
+      await resolveLoad(started, <span>{`marker churn ${id}`}</span>);
+    }
+
+    await rejectLoad(failedReplacement, 'replacement boom 0');
+
+    expect(fetchCount(0)).toBe(2);
+    expect(rscApi.successfulVersions[key] ?? 0).toBe(0);
+
+    const retryReplacement = await startLoad(0);
+    expect(fetchCount(0)).toBe(3);
+    await resolveLoad(retryReplacement, <span>replacement after rejection</span>);
+
+    await waitFor(() => expect(rscApi.successfulVersions[key]).toBeGreaterThan(0));
+  });
 });