Merge remote-tracking branch 'origin/develop' into fix/shopper-agent-product-links-pwa-route

# Conflicts:
#	packages/template-retail-react-app/CHANGELOG.md

Author: ashwinshanker-sf

packages/pwa-kit-create-app/CHANGELOG.md

@@ -1,4 +1,5 @@
 ## v3.22.0-dev
+- [Feature] Keep the generated `ssr.js.hbs` templates in sync with `template-retail-react-app` for Shopper Agent express payments: allow storefront-owned express-payment routes to be embedded in same-origin iframes. [#4063](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/4063)
 - Keep the generated `ssr.js.hbs` template in sync with `template-retail-react-app`: extract the passwordless-login callback handler to a named exported function (`passwordlessLoginCallbackHandler`), add `email_id` claim cross-validation against the request body to prevent email-relay attacks, and differentiate the notification type between `passwordless-registration` and `passwordless-login` based on the `?register=true` query parameter. [#4072](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/4072)
 - [Security] Keep the generated `ssr.js.hbs` templates in sync with `template-retail-react-app`: fix the registration-verification callback guard to check `registrationVerification.callbackURI` instead of `passwordless.mode` (non-extended template variant), and bind the `email_id` claim in the SLAS callback token to the request body to prevent email-relay attacks. [#4067](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/4067)
 - [Bugfix] Temporarily pin transitive Vitest to 4.1.11 in the create-app package and generated extensible apps to avoid an npm 10 dependency resolver crash while the Vitest browser packages require 4.1.11.

packages/pwa-kit-create-app/assets/bootstrap/js/overrides/app/ssr.js.hbs

@@ -573,6 +573,8 @@ const {handler} = runtime.createHandler(options, (app) => {
                 'www.google.com/pay/'
             ],
             'frame-src': [
+                // The Shopper Agent embeds storefront-owned express-payment routes.
+                "'self'",
                 // Allow frames from Salesforce site.com (Needed for MIAW)
                 '*.site.com',
                 // Payment gateways

packages/pwa-kit-create-app/assets/templates/@salesforce/retail-react-app/app/ssr.js.hbs

@@ -608,6 +608,8 @@ const {handler} = runtime.createHandler(options, (app) => {
                 'www.google.com/pay/'
             ],
             'frame-src': [
+                // The Shopper Agent embeds storefront-owned express-payment routes.
+                "'self'",
                 // Allow frames from Salesforce site.com (Needed for MIAW)
                 '*.site.com',
                 // Payment gateways

packages/template-retail-react-app/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## v10.4.0-dev (Oct 20, 2026)
 - [Bugfix] Keep Commerce Client shopper-agent product links on the PWA Kit storefront. The agent backend sends product links as SFRA URLs on the backend origin (e.g. `/en_US/<slug>-<id>.html`), which the widget's `onNavigate` never sees, so clicking a product card left for the SFRA PDP. The storefront now reads the product id from those links in the widget's product slots (cards, product detail title, comparison columns), rewrites their `href` to the PWA product page, and routes plain clicks through the router. Links in agent message text are left alone. When the product id is not certain from the URL (the name slug does not match, or the id contains `-`), it is resolved through Shopper SEO `getUrlMapping`; if that finds no product the link keeps its backend URL rather than pointing at a storefront 404. Port of storefront-next#2944. [#4076](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/4076) (W-23948585)
+- [Feature] Add a neutral Shopper Agent express-payment iframe framework with cart and product routes, a merchant provider lifecycle contract, validated iframe-to-host events, and automatic iframe sizing. [#4063](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/4063)
 - [Changed] Rename `pwakit-notify` notification types to flow-based names: `passwordless-magic-link` → `passwordless-login`, `otp` → `password-registration`. Adds new `passwordless-registration` type for new-user magic-link delivery — intentionally skips the anti-enumeration account-existence check (correct for the new-user registration flow). The cartridge changes are aligned 1-to-1 with sf-next PR #2946. [Security] Cross-validate `email_id` from the SLAS callback JWT against the request body in the passwordless-login callback, preventing email relay via an arbitrary-recipient registration email when `register=true`.
 - [Security] Cross-validate `email_id` and `token` claims in the SLAS callback JWT against the request body in the registration-verification callback (`/registration-verification-callback`), preventing email-relay attacks where a caller with a valid tenant-signed guest token could trigger OTP delivery to an arbitrary address. [#4067](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/4067)
 - [Bugfix] Gate the GLO magic-link auto-submit on `emailFromContext` (email present in router state) rather than the derived `email` variable, so arriving directly via magic link no longer attempts an auto-submit before the user enters their email address. [#4067](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/4067)

packages/template-retail-react-app/app/components/_app-config/index.jsx

@@ -43,6 +43,7 @@ import {withReactQuery} from '@salesforce/pwa-kit-react-sdk/ssr/universal/compon
 import {useCorrelationId} from '@salesforce/pwa-kit-react-sdk/ssr/universal/hooks'
 import {ReactQueryDevtools} from '@tanstack/react-query-devtools'
 import {generateSfdcUserAgent} from '@salesforce/retail-react-app/app/utils/sfdc-user-agent-utils'
+import {isShopperAgentExpressPaymentPath} from '@salesforce/retail-react-app/app/components/shopper-agent/express-payment/routes'
 import {
     DEFAULT_DNT_STATE,
     STORE_LOCATOR_RADIUS,
@@ -102,6 +103,9 @@ const AppConfig = ({children, locals = {}}) => {
     const slasPublicClientProxyEndpoint = `${appOrigin}${getEnvBasePath()}${slasPublicProxyPath}`
 
     const pageDesignerParams = locals.pageDesignerParams || {}
+    const requestPath =
+        typeof window === 'undefined' ? locals.originalUrl : window.location.pathname
+    const isShopperAgentExpressPaymentRoute = isShopperAgentExpressPaymentPath(requestPath)
 
     return (
         <CommerceApiProvider
@@ -137,7 +141,8 @@ const AppConfig = ({children, locals = {}}) => {
                     <ChakraProvider theme={theme}>{children}</ChakraProvider>
                 </StoreLocatorProvider>
             </MultiSiteProvider>
-            <ReactQueryDevtools />
+            {/* The floating devtools launcher can obscure the compact express-payment iframe. */}
+            {!isShopperAgentExpressPaymentRoute && <ReactQueryDevtools />}
         </CommerceApiProvider>
     )
 }

packages/template-retail-react-app/app/components/_app/index.jsx

@@ -101,6 +101,7 @@ import {getCommerceAgentConfig} from '@salesforce/retail-react-app/app/utils/con
 import {getPathWithLocale} from '@salesforce/retail-react-app/app/utils/url'
 import {useShopperAgent} from '@salesforce/retail-react-app/app/hooks/use-shopper-agent'
 import {useCommerceClientPagePush} from '@salesforce/retail-react-app/app/hooks/use-commerce-client-page-push'
+import {isShopperAgentExpressPaymentPath} from '@salesforce/retail-react-app/app/components/shopper-agent/express-payment/routes'
 
 // Code-split the optional, client-only Shopper Agent so the component and its messaging
 // integrations (MIAW / Commerce Client) ship in a separate async chunk instead of the
@@ -650,18 +651,89 @@ ComponentPreviewApp.propTypes = {
 }
 
 /**
- * Selects the app shell by route: the Page Designer component-preview iframe gets a
- * chrome-free surface, every other route gets the full storefront app. Uses `req.url`
- * on the server and `location.pathname` on the client, matching the SSR-safe pattern
- * already used for Page Designer mode detection.
+ * Minimal app surface for express payment content embedded in the Shopper Agent.
+ *
+ * AppConfig still supplies the Commerce API, multisite, and Chakra providers. Keeping
+ * this surface separate prevents the storefront shell and its shopper-state side
+ * effects from running recursively inside the Commerce Client iframe.
+ */
+const ShopperAgentExpressPaymentApp = ({children}) => {
+    const appOrigin = useAppOrigin()
+    const {site, locale} = useMultiSite()
+
+    const targetLocale = getTargetLocale({
+        getUserPreferredLocales: () => [locale?.id || DEFAULT_LOCALE],
+        l10nConfig: site.l10n
+    })
+
+    const {data: messages} = useQuery({
+        queryKey: ['app', 'translations', 'messages', targetLocale],
+        queryFn: () => fetchTranslations(targetLocale, appOrigin),
+        enabled: isServer
+    })
+
+    const currency = locale.preferredCurrency || site.l10n.defaultCurrency
+
+    return (
+        <Box
+            className="sf-app sf-app-shopper-agent-express-payment"
+            data-testid="shopper-agent-express-payment-app"
+            bg="transparent"
+            width="100%"
+        >
+            <IntlProvider
+                onError={(err) => {
+                    if (!messages) return
+                    if (err.code === 'MISSING_TRANSLATION') {
+                        logger.warn('Missing translation', {
+                            namespace: 'ShopperAgentExpressPaymentApp.IntlProvider',
+                            additionalProperties: {errorMessage: err.message}
+                        })
+                        return
+                    }
+                    throw err
+                }}
+                locale={targetLocale}
+                messages={messages}
+                defaultLocale={DEFAULT_LOCALE}
+            >
+                <CurrencyProvider currency={currency}>
+                    <Box as="main" id="app-main" role="main" width="100%">
+                        {children}
+                    </Box>
+                </CurrencyProvider>
+            </IntlProvider>
+        </Box>
+    )
+}
+
+ShopperAgentExpressPaymentApp.propTypes = {
+    children: PropTypes.node
+}
+
+/**
+ * Selects the app shell by route. Embedded iframe routes get their own chrome-free
+ * surface; every other route gets the full storefront app. Uses `req.url` on the
+ * server and `location.pathname` on the client.
  */
 const App = (props) => {
     const location = useLocation()
     const {req} = useServerContext()
     const pathname = req?.url ? req.url.split('?')[0] : location?.pathname || ''
     const isComponentPreview = COMPONENT_PREVIEW_PATH_RE.test(pathname)
 
-    return isComponentPreview ? <ComponentPreviewApp {...props} /> : <StorefrontApp {...props} />
+    if (isComponentPreview) {
+        return <ComponentPreviewApp {...props} />
+    }
+
+    if (
+        getCommerceAgentConfig()?.enabled === 'true' &&
+        isShopperAgentExpressPaymentPath(pathname)
+    ) {
+        return <ShopperAgentExpressPaymentApp {...props} />
+    }
+
+    return <StorefrontApp {...props} />
 }
 
 App.propTypes = {

packages/template-retail-react-app/app/components/_app/index.test.js

@@ -95,6 +95,7 @@ beforeEach(() => {
 })
 
 afterEach(() => {
+    mockConfig.app.commerceAgent.enabled = 'false'
     windowSpy.mockRestore()
     StorefrontPreview.mockClear()
     jest.restoreAllMocks()
@@ -204,6 +205,38 @@ describe('App', () => {
         expect(StorefrontPreview).not.toHaveBeenCalled()
     })
 
+    test('stretches the Shopper Agent express payment surface to the iframe width', () => {
+        useMultiSite.mockImplementation(() => resultUseMultiSite)
+        mockConfig.app.commerceAgent.enabled = 'true'
+        window.history.pushState({}, '', '/Payments-ExpressProduct?pid=product-1&quantity=1')
+
+        renderWithProviders(
+            <App targetLocale={DEFAULT_LOCALE} defaultLocale={DEFAULT_LOCALE} messages={messages}>
+                <p>Express payment child</p>
+            </App>
+        )
+
+        expect(screen.getByTestId('shopper-agent-express-payment-app')).toHaveStyle({
+            width: '100%'
+        })
+    })
+
+    test('uses the normal storefront surface for an express-payment path when Shopper Agent is disabled', async () => {
+        useMultiSite.mockImplementation(() => resultUseMultiSite)
+        window.history.pushState({}, '', '/Payments-ExpressProduct?pid=product-1&quantity=1')
+
+        renderWithProviders(
+            <App targetLocale={DEFAULT_LOCALE} defaultLocale={DEFAULT_LOCALE} messages={messages}>
+                <p>Disabled express payment child</p>
+            </App>
+        )
+
+        await waitFor(() => {
+            expect(screen.getByText('Disabled express payment child')).toBeInTheDocument()
+        })
+        expect(screen.queryByTestId('shopper-agent-express-payment-app')).not.toBeInTheDocument()
+    })
+
     test('SSR-renders the embedded header when its component is only lazily registered', () => {
         // The production regression: `initializeRegistry()` registers *lazy importers*, not
         // eager components, so during SSR `registry.getComponent()` returns null on first

packages/template-retail-react-app/app/components/shopper-agent/express-payment/contract-test-provider.jsx

@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) 2026, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import React, {useEffect, useState} from 'react'
+
+import {Box, Button, Stack, Text} from '@salesforce/retail-react-app/app/components/shared/ui'
+import {expressPaymentProviderPropTypes} from '@salesforce/retail-react-app/app/components/shopper-agent/express-payment/contract'
+
+export const CONTRACT_TEST_ORDER_ID = 'CONTRACT-TEST-ORDER'
+
+/**
+ * Reference provider that demonstrates the iframe context and lifecycle contract.
+ * It is not selected by default. Replace the export in provider.jsx to use it or
+ * connect a merchant payment integration.
+ */
+const ContractTestProvider = ({context, lifecycle}) => {
+    const [status, setStatus] = useState('Available')
+    const [successSubmitted, setSuccessSubmitted] = useState(false)
+
+    useEffect(() => {
+        lifecycle.available()
+    }, [lifecycle])
+
+    const reportAvailable = () => {
+        lifecycle.available()
+        setStatus('Available')
+    }
+
+    const reportUnavailable = () => {
+        lifecycle.unavailable()
+        setStatus('Unavailable')
+    }
+
+    const reportFailure = () => {
+        lifecycle.failure({shopperMessage: 'Contract-test failure'})
+        setStatus('Failure reported; retry remains available')
+    }
+
+    const reportCancellation = () => {
+        lifecycle.cancel({shopperMessage: 'Contract-test cancellation'})
+        setStatus('Cancellation reported; retry remains available')
+    }
+
+    const reportSuccess = () => {
+        lifecycle.success({orderId: CONTRACT_TEST_ORDER_ID})
+        setSuccessSubmitted(true)
+        setStatus('Simulated success submitted; fixture controls are now disabled')
+    }
+
+    return (
+        <Box
+            data-testid="express-payment-contract-test-provider"
+            borderWidth="1px"
+            borderRadius="md"
+            bg="white"
+            p={3}
+        >
+            <Text fontWeight="semibold">Express payment iframe shell is ready</Text>
+            <Text fontSize="sm">
+                {context.surface === 'product'
+                    ? `Product: ${context.productId}, quantity: ${context.quantity}`
+                    : `Cart payment surface, basket: ${context.basket.id || context.basket.status}`}
+            </Text>
+            <Text fontSize="xs">
+                Site: {context.siteId}, locale: {context.locale}, currency: {context.currency}
+            </Text>
+            <Text role="status" aria-live="polite" fontSize="sm" mt={2}>
+                {status}
+            </Text>
+            <Stack direction="row" flexWrap="wrap" spacing={2} mt={3}>
+                <Button size="sm" onClick={reportAvailable} isDisabled={successSubmitted}>
+                    Report available
+                </Button>
+                <Button size="sm" onClick={reportUnavailable} isDisabled={successSubmitted}>
+                    Report unavailable
+                </Button>
+                <Button size="sm" onClick={reportFailure} isDisabled={successSubmitted}>
+                    Report failure
+                </Button>
+                <Button size="sm" onClick={reportCancellation} isDisabled={successSubmitted}>
+                    Report cancellation
+                </Button>
+                <Button size="sm" onClick={reportSuccess} isDisabled={successSubmitted}>
+                    Report simulated success
+                </Button>
+            </Stack>
+        </Box>
+    )
+}
+
+ContractTestProvider.propTypes = expressPaymentProviderPropTypes
+
+export default ContractTestProvider

packages/template-retail-react-app/app/components/shopper-agent/express-payment/contract-test-provider.test.js

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2026, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import React from 'react'
+import {screen, waitFor} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+import {renderWithProviders} from '@salesforce/retail-react-app/app/utils/test-utils'
+import ContractTestProvider, {
+    CONTRACT_TEST_ORDER_ID
+} from '@salesforce/retail-react-app/app/components/shopper-agent/express-payment/contract-test-provider'
+
+const context = {
+    providerApiVersion: 1,
+    mode: 'shopper-agent',
+    surface: 'product',
+    siteId: 'RefArchGlobal',
+    locale: 'en-GB',
+    currency: 'GBP',
+    productId: 'sku-1',
+    quantity: 2
+}
+
+const createLifecycle = () => ({
+    available: jest.fn(),
+    unavailable: jest.fn(),
+    success: jest.fn(),
+    failure: jest.fn(),
+    cancel: jest.fn()
+})
+
+describe('ContractTestProvider', () => {
+    test('reports initial availability and exposes the launch context', async () => {
+        const lifecycle = createLifecycle()
+
+        renderWithProviders(<ContractTestProvider context={context} lifecycle={lifecycle} />)
+
+        expect(screen.getByText('Product: sku-1, quantity: 2')).toBeInTheDocument()
+        await waitFor(() => expect(lifecycle.available).toHaveBeenCalledWith())
+    })
+
+    test('exercises retryable unavailable, failure, and cancellation states', async () => {
+        const user = userEvent.setup()
+        const lifecycle = createLifecycle()
+        renderWithProviders(<ContractTestProvider context={context} lifecycle={lifecycle} />)
+
+        await user.click(screen.getByRole('button', {name: 'Report unavailable'}))
+        expect(lifecycle.unavailable).toHaveBeenCalledTimes(1)
+
+        await user.click(screen.getByRole('button', {name: 'Report failure'}))
+        expect(lifecycle.failure).toHaveBeenCalledWith({shopperMessage: 'Contract-test failure'})
+
+        await user.click(screen.getByRole('button', {name: 'Report cancellation'}))
+        expect(lifecycle.cancel).toHaveBeenCalledWith({
+            shopperMessage: 'Contract-test cancellation'
+        })
+
+        await user.click(screen.getByRole('button', {name: 'Report available'}))
+        expect(lifecycle.available).toHaveBeenLastCalledWith()
+        expect(screen.getByRole('status')).toHaveTextContent('Available')
+    })
+
+    test('reports a clearly fake success and makes the fixture terminal', async () => {
+        const user = userEvent.setup()
+        const lifecycle = createLifecycle()
+        renderWithProviders(<ContractTestProvider context={context} lifecycle={lifecycle} />)
+
+        await user.click(screen.getByRole('button', {name: 'Report simulated success'}))
+
+        expect(lifecycle.success).toHaveBeenCalledWith({orderId: CONTRACT_TEST_ORDER_ID})
+        expect(screen.getByRole('status')).toHaveTextContent(
+            'Simulated success submitted; fixture controls are now disabled'
+        )
+        expect(screen.getByRole('button', {name: 'Report available'})).toBeDisabled()
+    })
+})