Prerendering detection & handle differential versions

Author: bookernath

packages/core/src/app/checkout/CheckoutPage.tsx

@@ -59,6 +59,7 @@ import type CheckoutStepStatus from './CheckoutStepStatus';
 import CheckoutStepType from './CheckoutStepType';
 import type CheckoutSupport from './CheckoutSupport';
 import mapToCheckoutProps from './mapToCheckoutProps';
+import { type CheckoutRefreshAPI, createCheckoutRefreshAPI, createPrerenderingChangeHandler, PrerenderingStalenessDetector } from './prerenderingStalenessDetector';
 
 const Billing = lazy(() =>
     retry(
@@ -181,12 +182,22 @@ class Checkout extends Component<
 
     private embeddedMessenger?: EmbeddedCheckoutMessenger;
     private unsubscribeFromConsignments?: () => void;
+    private prerenderingStalenessDetector = new PrerenderingStalenessDetector();
+    private checkoutRefreshAPI?: CheckoutRefreshAPI;
 
     componentWillUnmount(): void {
         if (this.unsubscribeFromConsignments) {
             this.unsubscribeFromConsignments();
             this.unsubscribeFromConsignments = undefined;
         }
+        
+        // Clean up prerendering staleness detector
+        this.prerenderingStalenessDetector.reset();
+
+        // Clean up global API
+        if (typeof window !== 'undefined' && (window as any).checkoutRefreshAPI === this.checkoutRefreshAPI) {
+            delete (window as any).checkoutRefreshAPI;
+        }
 
         window.removeEventListener('beforeunload', this.handleBeforeExit);
         this.handleBeforeExit();
@@ -195,11 +206,13 @@ class Checkout extends Component<
     async componentDidMount(): Promise<void> {
         const {
             analyticsTracker,
+            checkoutId,
             containerId,
             createEmbeddedMessenger,
             data,
             embeddedStylesheet,
             extensionService,
+            loadCheckout,
             loadPaymentMethodByIds,
             subscribeToConsignments,
         } = this.props;
@@ -248,14 +261,47 @@ class Checkout extends Component<
             messenger.postLoaded();
 
             if (document.prerendering) {
-                document.addEventListener('prerenderingchange', () => {
+                // Capture initial snapshot when page is prerendered
+                this.prerenderingStalenessDetector.captureInitialSnapshot(data);
+                
+                // Set up enhanced prerenderingchange handler
+                const prerenderingChangeHandler = createPrerenderingChangeHandler(
+                    this.prerenderingStalenessDetector,
+                    loadCheckout,
+                    () => data,
+                    checkoutId,
+                    (wasStale) => {
+                        // Log for debugging - this could be removed in production
+                        if (wasStale) {
+                            // eslint-disable-next-line no-console
+                            console.debug('Checkout data was refreshed due to staleness after prerendering');
+                        }
+                    }
+                );
+                
+                document.addEventListener('prerenderingchange', async () => {
                     analyticsTracker.checkoutBegin();
+                    // Refresh checkout data in background if needed
+                    await prerenderingChangeHandler();
                 }, { once: true });
             }
             else {
                 analyticsTracker.checkoutBegin();
             }
 
+            // Set up global checkout refresh API
+            this.checkoutRefreshAPI = createCheckoutRefreshAPI(
+                this.prerenderingStalenessDetector,
+                loadCheckout,
+                () => data,
+                checkoutId
+            );
+
+            // Expose API globally for external use
+            if (typeof window !== 'undefined') {
+                (window as any).checkoutRefreshAPI = this.checkoutRefreshAPI;
+            }
+
             const consignments = data.getConsignments();
             const cart = data.getCart();
 

packages/core/src/app/checkout/PRERENDERING_STALENESS.md

@@ -0,0 +1,109 @@
+# Prerendering Staleness Detection
+
+This document describes the implementation of staleness detection for prerendered checkout pages.
+
+## Overview
+
+When using prerendering with Speculation Rules, checkout pages may become stale if the cart state changes after prerendering but before the user navigates to the checkout. This implementation automatically detects and refreshes stale checkout data without causing jank for users.
+
+## Implementation
+
+### Core Components
+
+1. **PrerenderingStalenessDetector**: Captures and compares checkout snapshots
+2. **Prerendering Change Handler**: Handles the `prerenderingchange` event
+3. **Global Refresh API**: Exposed on `window.checkoutRefreshAPI` for external use
+
+### Detection Strategy
+
+The system compares these key identifiers to detect staleness:
+
+- Cart ID
+- Cart updated time
+- Cart item count (physical + digital + gift certificates)
+- Cart base amount  
+- Checkout ID
+- Number of consignments
+
+### Usage
+
+#### Automatic Detection (Built-in)
+
+The implementation automatically:
+
+1. Captures initial snapshot when a page is prerendered
+2. Listens for the `prerenderingchange` event
+3. Refreshes checkout data in the background if changes are detected
+4. Logs when refresh occurs due to staleness
+
+#### Manual Refresh API
+
+The global API is available at `window.checkoutRefreshAPI`:
+
+```typescript
+// Check if checkout data is stale
+const isStale = window.checkoutRefreshAPI?.isCheckoutStale();
+
+// Force refresh checkout data
+const result = await window.checkoutRefreshAPI?.refreshCheckout(true);
+console.log('Refresh success:', result.success, 'Was stale:', result.wasStale);
+
+// Get current snapshot for debugging
+const snapshot = window.checkoutRefreshAPI?.getCurrentSnapshot();
+console.log('Current checkout state:', snapshot);
+```
+
+#### External Integration Examples
+
+```javascript
+// Example: Refresh when cart is modified in another tab
+window.addEventListener('storage', async (e) => {
+  if (e.key === 'cart_modified') {
+    const result = await window.checkoutRefreshAPI?.refreshCheckout();
+    if (result?.wasStale) {
+      console.log('Checkout was refreshed due to cart changes');
+    }
+  }
+});
+
+// Example: Periodic staleness check
+setInterval(async () => {
+  if (window.checkoutRefreshAPI?.isCheckoutStale()) {
+    await window.checkoutRefreshAPI.refreshCheckout();
+  }
+}, 30000); // Check every 30 seconds
+```
+
+## Files Modified
+
+- `packages/core/src/app/checkout/prerenderingStalenessDetector.ts` - Core implementation
+- `packages/core/src/app/checkout/CheckoutPage.tsx` - Integration with checkout page
+- `packages/core/types/dom.extended.d.ts` - Type definitions for global API
+
+## Benefits
+
+1. **Seamless UX**: No jank when checkout data hasn't changed
+2. **Automatic Updates**: Stale data is refreshed transparently
+3. **External API**: Allows custom refresh triggers from external code
+4. **Debugging Support**: Comprehensive logging and inspection capabilities
+
+## Edge Cases Handled
+
+- Missing cart/checkout data
+- Network failures during refresh (graceful degradation)
+- Multiple rapid refresh attempts
+- Component unmounting during refresh
+- API cleanup on page navigation
+
+## Testing
+
+Comprehensive test coverage includes:
+- Staleness detection accuracy
+- Error handling
+- API functionality
+- Integration with existing prerendering flow
+
+Run tests with:
+```bash
+npx jest packages/core/src/app/checkout/prerenderingStalenessDetector.test.ts --config=packages/core/jest.config.js
+```