Fix initial page startup race for late-loading client bundles

CHANGELOG.md

@@ -26,6 +26,7 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### Fixed
 
+- **Client startup now recovers if initialization begins during `interactive` after `DOMContentLoaded` already fired**: React on Rails now still initializes the page when the client bundle starts in the browser timing window after `DOMContentLoaded` but before the document reaches `complete`. Fixes [Issue 3150](https://github.com/shakacode/react_on_rails/issues/3150). [PR 3151](https://github.com/shakacode/react_on_rails/pull/3151) by [ihabadham](https://github.com/ihabadham).
 - **Doctor accepts TypeScript server bundle entrypoints**: `react_on_rails:doctor` now resolves common source entrypoint suffixes (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`) before warning that the server bundle is missing, preventing false positives when apps use `server-bundle.ts`. [PR 3111](https://github.com/shakacode/react_on_rails/pull/3111) by [justin808](https://github.com/justin808).
 - **Doctor no longer fails custom projects for a missing generated `bin/dev`**: `react_on_rails:doctor` now downgrades a missing official React on Rails `bin/dev` launcher from an error to a warning and adds explicit guidance when a custom `./dev` script is detected, so custom projects can pass diagnostics when their development setup is intentional. Fixes [Issue 3103](https://github.com/shakacode/react_on_rails/issues/3103). [PR 3117](https://github.com/shakacode/react_on_rails/pull/3117) by [justin808](https://github.com/justin808).
 

packages/react-on-rails/src/pageLifecycle.ts

@@ -67,20 +67,33 @@ function initializePageEventListeners(): void {
   }
   isPageLifecycleInitialized = true;
 
-  // Important: replacing this condition with `document.readyState !== 'loading'` is not valid
-  // As the core ReactOnRails needs to ensure that all component bundles are loaded and executed before hydrating them
-  // If the `document.readyState === 'interactive'`, it doesn't guarantee that deferred scripts are executed
-  // the `readyState` can be `'interactive'` while the deferred scripts are still being executed
-  // Which will lead to the error `"Could not find component registered with name <component name>"`
-  // It will happen if this line is reached before the component chunk is executed on browser and reached the line
-  // ReactOnRails.register({ Component });
-  // ReactOnRailsPro is resellient against that type of race conditions, but it won't wait for that state anyway
-  // As it immediately hydrates the components at the page as soon as its html and bundle is loaded on the browser
-  // See pageLifecycle.test.js for unit tests validating this logic
+  // Important: replacing this condition with `document.readyState !== 'loading'` is not valid for
+  // the core page-load sweep. During `interactive`, deferred/module scripts may still be executing,
+  // and a component chunk may not yet have reached `ReactOnRails.register({ Component })`.
+  // Starting hydration too early can trigger "Could not find component registered" errors.
+  //
+  // However, async or dynamically-injected scripts can start after DOMContentLoaded has already fired
+  // while the document is still `interactive`. In that case, waiting only for DOMContentLoaded can miss
+  // initialization entirely, so we recover on the later `complete` transition.
+  //
+  // ReactOnRailsPro's early hydration path is more resilient to the registration race because it can
+  // hydrate components as their HTML and bundles arrive, but this page lifecycle still powers the
+  // fallback page-load sweep. See pageLifecycle.test.js for regression coverage of both cases.
   if (document.readyState === 'complete') {
     setupPageNavigationListeners();
   } else {
-    document.addEventListener('DOMContentLoaded', setupPageNavigationListeners);
+    const initialPageLoadHandler = (event: Event): void => {
+      if (event.type === 'readystatechange' && document.readyState !== 'complete') return;
+      document.removeEventListener('DOMContentLoaded', initialPageLoadHandler);
+      document.removeEventListener('readystatechange', initialPageLoadHandler);
+      setupPageNavigationListeners();
+    };
+
+    document.addEventListener('DOMContentLoaded', initialPageLoadHandler);
+
+    if (document.readyState === 'interactive') {
+      document.addEventListener('readystatechange', initialPageLoadHandler);
+    }
   }
 }
 

packages/react-on-rails/tests/pageLifecycle.test.js

@@ -31,6 +31,9 @@ describe('pageLifecycle', () => {
   // eslint-disable-next-line global-require
   const importPageLifecycle = () => require('../src/pageLifecycle.ts');
 
+  const getEventHandler = (eventName) =>
+    addEventListenerSpy.mock.calls.find((call) => call[0] === eventName)?.[1];
+
   // Helper function to create navigation library mock
   const createNavigationMock = (overrides = {}) => ({
     debugTurbolinks: jest.fn(),
@@ -81,7 +84,7 @@ describe('pageLifecycle', () => {
     expect(addEventListenerSpy).not.toHaveBeenCalledWith('DOMContentLoaded', expect.any(Function));
   });
 
-  it('should wait for DOMContentLoaded when when document.readyState is "interactive"', () => {
+  it('should wait for DOMContentLoaded when document.readyState is "interactive"', () => {
     setReadyState('interactive');
     const callback = jest.fn();
     const { onPageLoaded } = importPageLifecycle();
@@ -92,6 +95,7 @@ describe('pageLifecycle', () => {
     expect(callback).not.toHaveBeenCalled();
     // Verify that a DOMContentLoaded listener was added when readyState is 'interactive'
     expect(addEventListenerSpy).toHaveBeenCalledWith('DOMContentLoaded', expect.any(Function));
+    expect(addEventListenerSpy).toHaveBeenCalledWith('readystatechange', expect.any(Function));
   });
 
   it('should wait for DOMContentLoaded when document.readyState is "loading"', () => {
@@ -272,8 +276,10 @@ describe('pageLifecycle', () => {
     // - It tries to hydrate components BEFORE step 5 completes
     // - ComponentRegistry.get() throws "Could not find component registered with name"
     //
-    // The fix: Use `readyState === 'complete'` to ensure we wait for DOMContentLoaded
-    // (which fires AFTER deferred scripts execute)
+    // The fix: do not initialize immediately during `interactive`.
+    // Wait for DOMContentLoaded (which fires AFTER deferred scripts execute),
+    // and separately recover on the later `complete` transition only if
+    // DOMContentLoaded was already missed before startup ran.
 
     it('should NOT call callbacks immediately when readyState is "interactive" because deferred scripts may not have executed', () => {
       // Simulate the state right after HTML parsing completes but before deferred scripts run
@@ -285,9 +291,9 @@ describe('pageLifecycle', () => {
       const hydrateComponentCallback = jest.fn();
       onPageLoaded(hydrateComponentCallback);
 
-      // CRITICAL: With the correct implementation (readyState === 'complete'),
-      // the callback should NOT be called immediately when readyState is 'interactive'.
-      // This gives deferred scripts time to execute and register components.
+      // CRITICAL: With the correct implementation, the callback should NOT be
+      // called immediately when readyState is 'interactive'. This gives deferred
+      // scripts time to execute and register components before hydration runs.
       expect(hydrateComponentCallback).not.toHaveBeenCalled();
 
       // Instead, a DOMContentLoaded listener should be added
@@ -324,7 +330,7 @@ describe('pageLifecycle', () => {
 
       onPageLoaded(attemptHydration);
 
-      // With correct implementation: callback not called yet, so no error
+      // With the correct implementation: callback not called yet, so no error
       expect(attemptHydration).not.toHaveBeenCalled();
 
       // Simulate deferred script executing (this happens before DOMContentLoaded)
@@ -339,12 +345,12 @@ describe('pageLifecycle', () => {
 
       // Now when DOMContentLoaded fires, the component is registered
       // and hydration succeeds
-      domContentLoadedHandler();
+      domContentLoadedHandler(new Event('DOMContentLoaded'));
       expect(attemptHydration).toHaveBeenCalled();
       // No error thrown because componentRegistered is now true
     });
 
-    it('should handle the case where readyState transitions from interactive to complete', () => {
+    it('should recover when DOMContentLoaded was already missed during interactive by waiting for complete', () => {
       // Start in 'interactive' state (HTML parsed, deferred scripts may be running)
       setReadyState('interactive');
 
@@ -356,18 +362,38 @@ describe('pageLifecycle', () => {
       // Callback should not be called immediately at 'interactive'
       expect(callback).not.toHaveBeenCalled();
       expect(addEventListenerSpy).toHaveBeenCalledWith('DOMContentLoaded', expect.any(Function));
+      expect(addEventListenerSpy).toHaveBeenCalledWith('readystatechange', expect.any(Function));
 
-      // Get the DOMContentLoaded handler
-      const domContentLoadedHandler = addEventListenerSpy.mock.calls.find(
-        (call) => call[0] === 'DOMContentLoaded',
-      )?.[1];
+      // Simulate the case where DOMContentLoaded already fired before startup installed its listener.
+      // The later transition to complete should still recover initialization.
+      const readyStateChangeHandler = getEventHandler('readystatechange');
+      expect(readyStateChangeHandler).toBeDefined();
 
-      // Simulate state transition: deferred scripts complete, then DOMContentLoaded fires
       setReadyState('complete');
-      domContentLoadedHandler();
+      readyStateChangeHandler(new Event('readystatechange'));
 
-      // Now callback should have been called
+      // Now callback should have been called through the complete fallback
       expect(callback).toHaveBeenCalledTimes(1);
     });
+
+    it('should remove both listeners after DOMContentLoaded fires so a later complete cannot re-trigger', () => {
+      setReadyState('interactive');
+
+      const { onPageLoaded } = importPageLifecycle();
+      const callback = jest.fn();
+
+      onPageLoaded(callback);
+
+      const domContentLoadedHandler = getEventHandler('DOMContentLoaded');
+      expect(domContentLoadedHandler).toBeDefined();
+
+      domContentLoadedHandler(new Event('DOMContentLoaded'));
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      // The handler's cleanup is what prevents the later readystatechange→complete
+      // event from firing the callback a second time in real browsers.
+      expect(removeEventListenerSpy).toHaveBeenCalledWith('DOMContentLoaded', expect.any(Function));
+      expect(removeEventListenerSpy).toHaveBeenCalledWith('readystatechange', expect.any(Function));
+    });
   });
 });