` | No wrapper div |
+| Synchronous rendering | Suspense-based lazy loading |
+
+## New Features
+
+### Design Metadata
+
+Components receive `designMetadata` with information for visual editing:
+
+```typescript
+interface ComponentDesignMetadata {
+ id: string // Component instance ID
+ name?: string // Display name
+ isFragment: boolean // Is this a fragment?
+ isVisible: boolean // Is component visible?
+ isLocalized: boolean // Is component localized?
+}
+```
+
+### Design Mode Detection
+
+Use the hook to conditionally render content:
+
+```jsx
+import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'
+
+function MyComponent() {
+ const {isDesignMode, isPreviewMode} = usePageDesignerMode()
+
+ return (
+
+ {isDesignMode && Editing mode}
+ {/* ... */}
+
+ )
+}
+```
+
+Or use the utility functions:
+
+```jsx
+import {isDesignModeActive, isPreviewModeActive} from '@salesforce/commerce-sdk-react/components'
+
+if (isDesignModeActive()) {
+ // In design mode
+}
+```
+
+### Component Registry
+
+```javascript
+import {registry} from '@salesforce/commerce-sdk-react'
+
+// Register with lazy loading
+registry.registerImporter('typeId', () => import('./component'))
+
+// Register with fallback for loading state
+registry.registerImporter('typeId', () => import('./component'), () => import('./skeleton'))
+
+// Get a component
+const Component = registry.getComponent('typeId')
+
+// Preload a component
+await registry.preload('typeId')
+```
+
+## PageDesignerProvider
+
+The provider enables communication with Business Manager's Page Designer for visual editing.
+
+```jsx
+
// 'EDIT' or 'PREVIEW'
+ {children}
+
+```
+
+**When to use:**
+- Wrap your app when loaded inside Page Designer's iframe
+- Use `isDesignModeActive()` or `isPreviewModeActive()` to detect context
+- Only needed for visual editing support
+
+## Template Retail React App Changes
+
+If you're using `template-retail-react-app`, here are the specific changes needed:
+
+### 1. Create the Registry File
+
+Create `app/page-designer/registry.js`:
+
+```javascript
+import {registry} from '@salesforce/commerce-sdk-react'
+
+export function initializeRegistry() {
+ // Commerce Assets
+ registry.registerImporter('commerce_assets.imageTile', () => import('./assets/image-tile'))
+ registry.registerImporter('commerce_assets.imageAndText', () => import('./assets/image-with-text'))
+ registry.registerImporter('commerce_assets.productTile', () => import('./assets/product-tile'))
+
+ // Commerce Layouts
+ registry.registerImporter('commerce_layouts.carousel', () => import('./layouts/carousel'))
+ registry.registerImporter('commerce_layouts.mobileGrid1r1c', () => import('./layouts/mobileGrid1r1c'))
+ registry.registerImporter('commerce_layouts.mobileGrid2r1c', () => import('./layouts/mobileGrid2r1c'))
+ registry.registerImporter('commerce_layouts.mobileGrid2r2c', () => import('./layouts/mobileGrid2r2c'))
+ registry.registerImporter('commerce_layouts.mobileGrid2r3c', () => import('./layouts/mobileGrid2r3c'))
+ registry.registerImporter('commerce_layouts.mobileGrid3r1c', () => import('./layouts/mobileGrid3r1c'))
+ registry.registerImporter('commerce_layouts.mobileGrid3r2c', () => import('./layouts/mobileGrid3r2c'))
+}
+```
+
+### 2. Initialize Registry at Module Load
+
+In `app/components/_app/index.jsx`, add the registry initialization at the top level (outside the component):
+
+```javascript
+import {initializeRegistry} from '@salesforce/retail-react-app/app/page-designer/registry'
+
+// Initialize registry synchronously at module load time so components are available during SSR
+initializeRegistry()
+```
+
+### 3. Add PageDesignerProvider to App
+
+In `app/components/_app/index.jsx`, wrap your app content with `PageDesignerProvider`:
+
+```javascript
+import {PageDesignerProvider} from '@salesforce/commerce-sdk-react/components'
+import {useUsid} from '@salesforce/commerce-sdk-react'
+
+const App = (props) => {
+ const {usid} = useUsid()
+
+ // Detect Page Designer mode from URL
+ const pageDesignerMode = useMemo(() => {
+ const queryParams = location?.search || ''
+ if (queryParams.includes('mode=EDIT')) return 'EDIT'
+ if (queryParams.includes('mode=PREVIEW')) return 'PREVIEW'
+ return undefined
+ }, [])
+
+ return (
+ // ... existing providers ...
+
+ {children}
+
+ )
+}
+```
+
+### 4. Create PageDesignerInit Component
+
+Create `app/components/page-designer-init/index.jsx` to handle design mode behaviors:
+
+```javascript
+import React, {useEffect} from 'react'
+import {Prompt} from 'react-router-dom'
+import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'
+import {useGlobalAnchorBlock} from '@salesforce/retail-react-app/app/hooks/use-global-anchor-block'
+
+export function PageDesignerInit() {
+ const {isDesignMode} = usePageDesignerMode()
+
+ // Block anchor navigation when in design mode
+ useGlobalAnchorBlock(isDesignMode)
+
+ // Load Page Designer styles only in design mode
+ useEffect(() => {
+ if (isDesignMode) {
+ void import('@salesforce/storefront-next-runtime/design/styles.css')
+ }
+ }, [isDesignMode])
+
+ // Block React Router navigation in design mode
+ return (
+
false} />
+ )
+}
+
+export default PageDesignerInit
+```
+
+### 5. Create useGlobalAnchorBlock Hook
+
+Create `app/hooks/use-global-anchor-block.js` to prevent link navigation in design mode:
+
+```javascript
+import {useEffect} from 'react'
+
+export function useGlobalAnchorBlock(enabled = true) {
+ useEffect(() => {
+ if (typeof window === 'undefined' || !enabled) return
+
+ function preventAnchorClicks(event) {
+ const anchor = event.target.closest('a')
+ // Allow links with data-pd-allow-link attribute
+ if (anchor && !anchor.hasAttribute('data-pd-allow-link')) {
+ event.preventDefault()
+ }
+ }
+
+ document.addEventListener('click', preventAnchorClicks)
+ return () => document.removeEventListener('click', preventAnchorClicks)
+ }, [enabled])
+}
+```
+
+### 6. Update Layout Components
+
+Update all layout components to use the new Region API. Example for `mobileGrid2r2c`:
+
+**Before:**
+```jsx
+export const MobileGrid2r2c = ({regions}) => (
+
+ {regions.map((region) => (
+
+ ))}
+
+)
+```
+
+**After:**
+```jsx
+export const MobileGrid2r2c = ({regions}) => (
+
+ {regions.map((region) => {
+ const component = {regions}
+ return (
+
+ )
+ })}
+
+)
+```
+
+### 7. Add PageDesignerInit to App
+
+In `app/components/_app/index.jsx`, render `PageDesignerInit` inside the provider:
+
+```jsx
+
+
+ {children}
+
+```
+
+## Complete Migration Example
+
+**Before (Old API):**
+```jsx
+// page-viewer.jsx
+import {Page} from '@salesforce/commerce-sdk-react/components'
+import ImageTile from './components/image-tile'
+import Banner from './components/banner'
+import TwoColumn from './components/two-column'
+
+const components = {
+ 'commerce_assets.imageTile': ImageTile,
+ 'commerce_assets.banner': Banner,
+ 'commerce_layouts.twoColumn': TwoColumn
+}
+
+function PageViewer({pageData}) {
+ return
+}
+
+// two-column.jsx
+import {Region} from '@salesforce/commerce-sdk-react/components'
+
+function TwoColumn({regions}) {
+ return (
+
+
+
+
+ )
+}
+```
+
+**After (New API):**
+```jsx
+// registry.js
+import {registry} from '@salesforce/commerce-sdk-react'
+
+export function initializeRegistry() {
+ registry.registerImporter('commerce_assets.imageTile', () => import('./assets/image-tile'))
+ registry.registerImporter('commerce_assets.banner', () => import('./assets/banner'))
+ registry.registerImporter('commerce_layouts.twoColumn', () => import('./layouts/two-column'))
+}
+
+// _app/index.jsx
+import {initializeRegistry} from './page-designer/registry'
+initializeRegistry() // At module level, not in useEffect
+
+// page-viewer.jsx
+import {Page} from '@salesforce/commerce-sdk-react/components'
+
+function PageViewer({pageData}) {
+ return
+}
+
+// two-column.jsx
+import {Region} from '@salesforce/commerce-sdk-react/components'
+
+function TwoColumn({component}) {
+ return (
+
+
+
+
+ )
+}
+```
+
+## Troubleshooting
+
+### Components Not Rendering
+
+1. Verify `initializeRegistry()` is called on app startup
+2. Check that component type IDs match exactly (case-sensitive)
+3. Ensure components have a default export
+
+### Region Not Found
+
+1. Verify `regionId` matches the region ID in your page data
+2. For nested regions, pass `component` not `page`
+3. Use `errorElement` prop to handle missing regions gracefully
+
+### Visual Editing Not Working
+
+1. Ensure `PageDesignerProvider` wraps your content
+2. Verify `targetOrigin` matches your Business Manager URL
+3. Check browser console for postMessage errors
diff --git a/packages/commerce-sdk-react/PAGE_DESIGNER_ARCHITECTURE.md b/packages/commerce-sdk-react/PAGE_DESIGNER_ARCHITECTURE.md
new file mode 100644
index 0000000000..b293247f41
--- /dev/null
+++ b/packages/commerce-sdk-react/PAGE_DESIGNER_ARCHITECTURE.md
@@ -0,0 +1,224 @@
+# Page Designer Concepts
+
+This document explains the key concepts behind the Page Designer integration for PWA Kit.
+
+## How It Works
+
+```
+Business Manager Page Designer
+ ↓ (creates JSON)
+ Page Data (API)
+ ↓ (fetched by)
+ PWA Kit App
+ ↓ (renders via)
+ Page → Region → Component
+ ↓ (resolves from)
+ Component Registry
+```
+
+### Runtime vs Design Mode
+
+The system operates in two modes:
+
+1. **Runtime Mode** (normal browsing)
+ - Components render directly from page data
+ - No visual editing overhead
+ - Optimized for performance
+
+2. **Design Mode** (in Page Designer iframe)
+ - Components are decorated for visual editing
+ - Click-to-select, drag-and-drop enabled
+ - Communicates with Business Manager via postMessage
+
+## Component Hierarchy
+
+### Page
+
+The top-level container that:
+- Receives page data from the ShopperExperience API
+- Sets up SEO metadata (title, description, keywords)
+- Renders top-level regions
+
+### Region
+
+A container for components that:
+- Can exist at page level or nested inside layout components
+- Finds its components by `regionId`
+- Supports fallback and error elements
+
+**Two modes of use:**
+```jsx
+// Page-level region
+
+
+// Nested region (inside a layout component)
+
+```
+
+### Component
+
+Resolves and renders individual Page Designer components:
+- Looks up the React component from the registry by `typeId`
+- Passes component data as props
+- Handles lazy loading via Suspense
+
+## Component Registry
+
+The registry is a central place to map Page Designer type IDs to React components.
+
+### Why a Registry?
+
+- **Lazy Loading** - Components load only when needed
+- **Code Splitting** - Each component is a separate chunk
+- **Decoupling** - Page data doesn't need to know about React components
+
+### How It Works
+
+```
+Page Data: { typeId: "commerce_assets.banner", data: {...} }
+ ↓
+Registry: "commerce_assets.banner" → () => import('./banner')
+ ↓
+React Component:
+```
+
+## Visual Editing
+
+When your app runs inside Page Designer's iframe, it enables visual editing.
+
+### PageDesignerProvider
+
+Wraps your app to enable design mode features:
+
+```jsx
+
+ {children}
+
+```
+
+### What It Enables
+
+- **Component Selection** - Click components to select them
+- **Visual Indicators** - Borders and overlays show component boundaries
+- **Live Updates** - Changes in Page Designer reflect immediately
+- **Communication** - postMessage bridge to Business Manager
+
+### Mode Detection
+
+Detect if you're in design mode:
+
+```jsx
+import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'
+
+function MyComponent() {
+ const {isDesignMode, isPreviewMode} = usePageDesignerMode()
+ // ...
+}
+```
+
+Or use utility functions:
+
+```jsx
+import {isDesignModeActive, isPreviewModeActive} from '@salesforce/commerce-sdk-react/components'
+```
+
+## Data Flow
+
+### Page Data Structure
+
+```typescript
+Page
+├── id: string
+├── pageTitle, pageDescription, pageKeywords
+└── regions: Region[]
+ └── Region
+ ├── id: string
+ └── components: Component[]
+ └── Component
+ ├── id: string
+ ├── typeId: string (maps to registry)
+ ├── data: {...} (your component props)
+ └── regions?: Region[] (for layouts)
+```
+
+### Props Your Components Receive
+
+```jsx
+function MyComponent({
+ // Your custom attributes from Page Designer
+ title,
+ image,
+ link,
+
+ // Automatic props
+ designMetadata, // { id, name, isVisible, isLocalized, isFragment }
+ component, // Full component object
+ regionId, // Parent region's ID
+ regions // Child regions (for layout components)
+}) {
+ // ...
+}
+```
+
+## Layout Components
+
+Layout components contain regions that hold other components.
+
+### Example Structure
+
+```
+TwoColumnLayout (component)
+├── regions.left (region)
+│ └── Banner (component)
+└── regions.right (region)
+ └── ImageTile (component)
+```
+
+### Implementing a Layout
+
+```jsx
+function TwoColumnLayout({component}) {
+ return (
+
+
+
+
+ )
+}
+```
+
+## Performance
+
+### Zero Overhead in Runtime
+
+When not in design mode:
+- No design decorators applied
+- No postMessage listeners
+- Components render directly
+
+### Lazy Loading
+
+Components load on demand:
+- Initial bundle stays small
+- Each component is a separate chunk
+- Suspense handles loading states
+
+### Fallbacks
+
+Provide loading states for better UX:
+
+```jsx
+registry.registerImporter(
+ 'commerce_assets.banner',
+ () => import('./banner'),
+ () => import('./banner-skeleton') // Optional fallback
+)
+```
+
+## Related
+
+- [Migration Guide](./PAGE_DESIGNER.md) - Step-by-step migration instructions
+- [Page Designer API](https://developer.salesforce.com/docs/commerce/commerce-api/guide/page-designer.html)
diff --git a/packages/commerce-sdk-react/jest.config.js b/packages/commerce-sdk-react/jest.config.js
index f836ca23d2..fe5627a9e6 100644
--- a/packages/commerce-sdk-react/jest.config.js
+++ b/packages/commerce-sdk-react/jest.config.js
@@ -11,6 +11,19 @@ module.exports = {
...base,
setupFilesAfterEnv: ['./setup-jest.js'],
transformIgnorePatterns: [],
+ moduleNameMapper: {
+ ...base.moduleNameMapper,
+ '^@salesforce/storefront-next-runtime/design/react/core$':
+ '@salesforce/storefront-next-runtime/dist/design-react-core.js',
+ '^@salesforce/storefront-next-runtime/design/react$':
+ '@salesforce/storefront-next-runtime/dist/design-react.js',
+ '^@salesforce/storefront-next-runtime/design$':
+ '@salesforce/storefront-next-runtime/dist/design.js',
+ '^@salesforce/storefront-next-runtime/design/mode$':
+ '@salesforce/storefront-next-runtime/dist/design-mode.js',
+ '^@salesforce/storefront-next-runtime/scapi$':
+ '@salesforce/storefront-next-runtime/dist/scapi.js'
+ },
coverageThreshold: {
global: {
branches: 0,
diff --git a/packages/commerce-sdk-react/package-lock.json b/packages/commerce-sdk-react/package-lock.json
index 6224885922..6080ac01b5 100644
--- a/packages/commerce-sdk-react/package-lock.json
+++ b/packages/commerce-sdk-react/package-lock.json
@@ -9,6 +9,7 @@
"version": "5.1.0-dev",
"license": "See license in LICENSE",
"dependencies": {
+ "@salesforce/storefront-next-runtime": "0.1.1",
"commerce-sdk-isomorphic": "5.1.0",
"js-cookie": "^3.0.1",
"jwt-decode": "^4.0.0"
@@ -230,6 +231,22 @@
"node": ">= 8"
}
},
+ "node_modules/@salesforce/storefront-next-runtime": {
+ "version": "0.1.1",
+ "resolved": "https://registry.npmjs.org/@salesforce/storefront-next-runtime/-/storefront-next-runtime-0.1.1.tgz",
+ "integrity": "sha512-j8TrIMppOdO2T+IcGfaENei3hcE3yrq3fuWj2o8yfIDB555FU9Td9DFA/UuxOSnsMqQrFw2+X3GG1rsTBoZHGA==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "openapi-fetch": "0.15.0"
+ },
+ "engines": {
+ "node": ">=24.0.0"
+ },
+ "peerDependencies": {
+ "react": ">=19.0.0",
+ "react-dom": ">=19.0.0"
+ }
+ },
"node_modules/@sinclair/typebox": {
"version": "0.34.45",
"resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.45.tgz",
@@ -2675,6 +2692,21 @@
"wrappy": "1"
}
},
+ "node_modules/openapi-fetch": {
+ "version": "0.15.0",
+ "resolved": "https://registry.npmjs.org/openapi-fetch/-/openapi-fetch-0.15.0.tgz",
+ "integrity": "sha512-OjQUdi61WO4HYhr9+byCPMj0+bgste/LtSBEcV6FzDdONTs7x0fWn8/ndoYwzqCsKWIxEZwo4FN/TG1c1rI8IQ==",
+ "license": "MIT",
+ "dependencies": {
+ "openapi-typescript-helpers": "^0.0.15"
+ }
+ },
+ "node_modules/openapi-typescript-helpers": {
+ "version": "0.0.15",
+ "resolved": "https://registry.npmjs.org/openapi-typescript-helpers/-/openapi-typescript-helpers-0.0.15.tgz",
+ "integrity": "sha512-opyTPaunsklCBpTK8JGef6mfPhLSnyy5a0IN9vKtx3+4aExf+KxEqYwIy3hqkedXIB97u357uLMJsOnm3GVjsw==",
+ "license": "MIT"
+ },
"node_modules/p-finally": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/p-finally/-/p-finally-1.0.0.tgz",
diff --git a/packages/commerce-sdk-react/package.json b/packages/commerce-sdk-react/package.json
index 4e1b57aa72..a7a464b0d4 100644
--- a/packages/commerce-sdk-react/package.json
+++ b/packages/commerce-sdk-react/package.json
@@ -17,7 +17,7 @@
"files": [
"CHANGELOG.md",
"LICENSE",
- "+(auth|components|hooks|scripts)/**/!(*.test*).{ts,js}",
+ "+(auth|components|hooks|scripts|page-designer)/**/!(*.test*).{ts,js}",
"*.{js,d.ts}",
"!*.test*.{js,d.ts}",
"!test*.*",
@@ -41,6 +41,7 @@
},
"dependencies": {
"commerce-sdk-isomorphic": "5.1.0",
+ "@salesforce/storefront-next-runtime": "0.1.1",
"js-cookie": "^3.0.1",
"jwt-decode": "^4.0.0"
},
@@ -87,6 +88,12 @@
"node": "^18.0.0 || ^20.0.0 || ^22.0.0 || ^24.0.0",
"npm": "^9.0.0 || ^10.0.0 || ^11.0.0"
},
+ "overrides": {
+ "@salesforce/storefront-next-runtime": {
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
+ }
+ },
"publishConfig": {
"directory": "dist"
}
diff --git a/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Component/index.test.tsx b/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Component/index.test.tsx
new file mode 100644
index 0000000000..794d341264
--- /dev/null
+++ b/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Component/index.test.tsx
@@ -0,0 +1,131 @@
+/*
+ * Copyright (c) 2023, 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 {render, screen} from '@testing-library/react'
+import {Component, ComponentProps} from './index'
+import {registry} from '../registry'
+
+// Mock the registry
+jest.mock('../registry', () => ({
+ registry: {
+ getComponent: jest.fn(),
+ getFallback: jest.fn(),
+ preload: jest.fn()
+ }
+}))
+
+// Type the mock registry with flexible return types for testing
+const mockRegistry = registry as unknown as {
+ getComponent: jest.Mock
+ getFallback: jest.Mock
+ preload: jest.Mock
+}
+
+describe('Component', () => {
+ // Create mock component data - cast to ComponentProps['component'] for test flexibility
+ const mockComponent = {
+ id: 'test-component-id',
+ typeId: 'commerce_assets.banner',
+ data: {
+ title: 'Test Banner',
+ imageUrl: '/test-image.jpg'
+ },
+ visible: true,
+ localized: false,
+ designMetadata: {
+ name: 'Test Component'
+ },
+ regions: []
+ } as unknown as ComponentProps['component']
+
+ beforeEach(() => {
+ jest.clearAllMocks()
+ // Suppress console.log during tests
+ jest.spyOn(console, 'log').mockImplementation(() => {})
+ })
+
+ afterEach(() => {
+ jest.restoreAllMocks()
+ })
+
+ test('renders component when DynamicComponent is available', () => {
+ const MockDynamicComponent = ({title}: {title: string}) => (
+ {title}
+ )
+ mockRegistry.getComponent.mockReturnValue(MockDynamicComponent)
+ mockRegistry.getFallback.mockReturnValue(null)
+
+ render()
+
+ expect(screen.getByTestId('dynamic-component')).toBeInTheDocument()
+ expect(screen.getByText('Test Banner')).toBeInTheDocument()
+ })
+
+ test('calls preload when DynamicComponent is not available', () => {
+ const preloadPromise = Promise.resolve()
+ mockRegistry.getComponent.mockReturnValue(undefined)
+ mockRegistry.getFallback.mockReturnValue(null)
+ mockRegistry.preload.mockReturnValue(preloadPromise)
+
+ // Component throws the preload promise for Suspense to catch
+ // We can't test the throw directly because React catches it internally
+ // Instead we verify preload is called with the correct typeId
+ try {
+ render()
+ } catch (e) {
+ // Expected - Suspense boundary catches this
+ }
+
+ expect(mockRegistry.preload).toHaveBeenCalledWith('commerce_assets.banner')
+ })
+
+ test('passes correct props to DynamicComponent', () => {
+ const receivedProps: Record = {}
+ const MockDynamicComponent = (props: Record) => {
+ Object.assign(receivedProps, props)
+ return Test
+ }
+ mockRegistry.getComponent.mockReturnValue(MockDynamicComponent)
+ mockRegistry.getFallback.mockReturnValue(null)
+
+ render(
+
+ )
+
+ expect(receivedProps.title).toBe('Test Banner')
+ expect(receivedProps.imageUrl).toBe('/test-image.jpg')
+ expect(receivedProps.className).toBe('custom-class')
+ expect(receivedProps.regionId).toBe('test-region')
+ expect(receivedProps.component).toBe(mockComponent)
+ expect(receivedProps.regions).toEqual([])
+ expect(receivedProps.designMetadata).toEqual({
+ name: 'Test Component',
+ isFragment: false,
+ isVisible: true,
+ isLocalized: false,
+ id: 'test-component-id'
+ })
+ })
+
+ test('handles component without designMetadata', () => {
+ const componentWithoutDesignMetadata = {
+ ...mockComponent,
+ designMetadata: undefined
+ } as unknown as ComponentProps['component']
+ const receivedProps: Record = {}
+ const MockDynamicComponent = (props: Record) => {
+ Object.assign(receivedProps, props)
+ return Test
+ }
+ mockRegistry.getComponent.mockReturnValue(MockDynamicComponent)
+ mockRegistry.getFallback.mockReturnValue(null)
+
+ render()
+
+ expect((receivedProps.designMetadata as {name: string | undefined}).name).toBeUndefined()
+ })
+})
diff --git a/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Component/index.tsx b/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Component/index.tsx
new file mode 100644
index 0000000000..e953eb6941
--- /dev/null
+++ b/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Component/index.tsx
@@ -0,0 +1,91 @@
+/*
+ * 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, {
+ type ReactElement,
+ memo,
+ Suspense,
+ type ComponentType as ReactComponentType
+} from 'react'
+import {registry} from '../registry'
+import type {ComponentDesignMetadata} from '@salesforce/storefront-next-runtime/design/react'
+import type {ComponentType} from '../types'
+
+export interface ComponentProps {
+ component: ComponentType
+ className?: string
+ regionId: string
+}
+
+/**
+ * Props that are passed to dynamic components loaded from the registry.
+ * This includes design metadata, component data, and region information.
+ */
+interface DynamicComponentProps extends Record {
+ designMetadata: ComponentDesignMetadata
+ component: ComponentType
+ regions?: ComponentType['regions']
+ className?: string
+ regionId: string
+}
+
+export const Component = memo(function Component({
+ component,
+ className,
+ regionId
+}: ComponentProps): ReactElement {
+ // Get this component's data promise from context by its ID
+ const FallbackComponent = registry.getFallback(component.typeId)
+ const DynamicComponent = registry.getComponent(component.typeId)
+
+ if (!DynamicComponent) {
+ throw registry.preload(component.typeId)
+ }
+
+ // visible and localized are runtime properties not in the API schema
+ const componentWithRuntimeProps = component as ComponentType & {
+ visible?: boolean
+ localized?: boolean
+ }
+ const designMetadata: ComponentDesignMetadata = {
+ name: component.designMetadata?.name,
+ isFragment: false,
+ isVisible: Boolean(componentWithRuntimeProps.visible),
+ isLocalized: Boolean(componentWithRuntimeProps.localized),
+ id: component.id
+ }
+
+ // Cast DynamicComponent to accept our props since registry returns unknown type
+ const ComponentToRender = DynamicComponent as ReactComponentType
+
+ const componentElement = (
+
+ )
+
+ // Only use Suspense on the client side since during SSR it will respond with the whole page loaded
+ const isClient = typeof window !== 'undefined'
+
+ if (!isClient) {
+ return {componentElement}
+ }
+
+ return (
+ :
+ }
+ >
+ {componentElement}
+
+ )
+})
diff --git a/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Page/index.test.tsx b/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Page/index.test.tsx
new file mode 100644
index 0000000000..0558ce7143
--- /dev/null
+++ b/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Page/index.test.tsx
@@ -0,0 +1,152 @@
+/*
+ * Copyright (c) 2023, 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 {render} from '@testing-library/react'
+import Page from './index'
+import {Helmet} from 'react-helmet'
+import type {PageWithDesignMetadata} from '../types'
+
+// Mock the Component to avoid registry dependency
+jest.mock('../Component', () => ({
+ Component: ({component}: {component: {id: string; typeId: string}}) => (
+
+ {component.typeId}
+
+ )
+}))
+
+// Mock the RegionWrapper
+jest.mock('../Region/region-wrapper', () => ({
+ RegionWrapper: ({children, className}: {children: React.ReactNode; className?: string}) => (
+ {children}
+ )
+}))
+
+const SAMPLE_PAGE = {
+ id: 'samplepage',
+ typeId: 'storePage',
+ aspectTypeId: 'pdpAspect',
+ name: 'Sample Page',
+ description: 'Sample page of the storefront.',
+ pageTitle: 'title',
+ pageDescription: 'description',
+ pageKeywords: 'keywords',
+ regions: [
+ {
+ id: 'regionA',
+ components: [
+ {
+ id: 'iofwj38fhw3f',
+ typeId: 'commerce_assets.banner',
+ data: {
+ title: 'Products On Sale',
+ bannerImage: 'sale/topsellerPromo.jpg'
+ }
+ }
+ ]
+ },
+ {
+ id: 'regionB',
+ components: [
+ {
+ id: 'rfdvj4ojtltljw3',
+ typeId: 'commerce_assets.carousel',
+ data: {
+ title: 'Topseller',
+ category: 'topseller'
+ },
+ regions: [
+ {
+ id: 'regionB1',
+ components: [
+ {
+ id: 'rfdvj4ojtltljw3',
+ typeId: 'commerce_assets.carousel',
+ data: {
+ title: 'Topseller',
+ category: 'topseller'
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ id: 'regionC',
+ components: []
+ }
+ ]
+} as unknown as PageWithDesignMetadata
+
+beforeEach(() => {
+ // Suppress console.log during tests
+ jest.spyOn(console, 'log').mockImplementation(() => {})
+})
+
+afterEach(() => {
+ jest.restoreAllMocks()
+})
+
+test('Page renders without errors', () => {
+ const {container} = render()
+
+ // Page is in document.
+ expect(container.querySelector('[id=samplepage]')).toBeInTheDocument()
+
+ // Meta data and title are set
+ const helmet = Helmet.peek()
+ expect(helmet.title).toBe('title')
+ expect(
+ helmet.metaTags.find(
+ ({name, content}) => name === 'description' && content === 'description'
+ )
+ ).toBeTruthy()
+ expect(
+ helmet.metaTags.find(({name, content}) => name === 'keywords' && content === 'keywords')
+ ).toBeTruthy()
+
+ // Regions are in document.
+ expect(container.querySelectorAll('.region')?.length).toBe(3)
+
+ // Components are in document. (Note: Sub-regions/components aren't rendered because that is
+ // the responsibility of the component definition.)
+ expect(container.querySelectorAll('.component')?.length).toBe(2)
+})
+
+test('Page renders with empty page data', () => {
+ const emptyPage = {
+ id: 'emptypage',
+ regions: []
+ } as unknown as PageWithDesignMetadata
+ const {container} = render()
+
+ expect(container.querySelector('[id=emptypage]')).toBeInTheDocument()
+ expect(container.querySelectorAll('.region')?.length).toBe(0)
+})
+
+test('Page renders without meta tags when not provided', () => {
+ const pageWithoutMeta = {
+ id: 'nometa',
+ regions: []
+ } as unknown as PageWithDesignMetadata
+ render()
+
+ const helmet = Helmet.peek()
+ expect(helmet.title).toBeUndefined()
+})
+
+test('Page applies custom className', () => {
+ const simplePage = {
+ id: 'simplepage',
+ regions: []
+ } as unknown as PageWithDesignMetadata
+ const {container} = render()
+
+ expect(container.querySelector('.page.custom-page-class')).toBeInTheDocument()
+})
diff --git a/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Page/index.tsx b/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Page/index.tsx
new file mode 100644
index 0000000000..3a071093a3
--- /dev/null
+++ b/packages/commerce-sdk-react/src/components/ShopperExperienceV2/Page/index.tsx
@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2023, 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 {Helmet} from 'react-helmet'
+import type {Component as ComponentType, PageWithDesignMetadata} from '../types'
+import {Region} from '../Region'
+
+type ComponentMap = {
+ [typeId: string]: React.ComponentType
+}
+
+interface PageProps extends React.ComponentProps<'div'> {
+ page: PageWithDesignMetadata
+ components?: ComponentMap
+}
+
+type PageContextValue = {
+ components: ComponentMap
+}
+
+// This context will hold the component map as well as any other future context.
+export const PageContext = React.createContext(undefined)
+
+/**
+ * This component will render a page designer page given its serialized data object.
+ * It wraps the page with PageDesignerProvider to enable design mode capabilities.
+ *
+ * @param {PageProps} props
+ * @param {Page} props.page - The page designer page data representation.
+ * @param {ComponentMap} props.components - A mapping of typeId's to react components representing the type.
+ * @param {Object} props.pageDesigner - Optional Page Designer configuration for design mode.
+ * @returns {React.ReactElement} - Page component.
+ */
+export const Page = (props: PageProps) => {
+ const {page, className = '', ...rest} = props
+ const {id, regions, pageDescription, pageKeywords, pageTitle} = page || {}
+
+ return (
+
+
+ {pageTitle && {pageTitle}}
+ {pageDescription && }
+ {pageKeywords && }
+
+
+
+ {regions?.map((region) => (
+
+ ))}
+
+
+
+ {component.typeId}
+
+ )
+}))
+
+// Mock the RegionWrapper
+jest.mock('./region-wrapper', () => ({
+ RegionWrapper: ({children, className}: {children: React.ReactNode; className?: string}) => (
+
+ {children}
+
+ )
+}))
+
+describe('Region', () => {
+ beforeEach(() => {
+ jest.clearAllMocks()
+ })
+
+ describe('Page Mode', () => {
+ const mockPage = {
+ id: 'test-page',
+ regions: [
+ {
+ id: 'main-region',
+ components: [
+ {id: 'comp-1', typeId: 'commerce_assets.banner', data: {}},
+ {id: 'comp-2', typeId: 'commerce_assets.carousel', data: {}}
+ ]
+ },
+ {
+ id: 'sidebar-region',
+ components: [{id: 'comp-3', typeId: 'commerce_assets.promo', data: {}}]
+ },
+ {
+ id: 'empty-region',
+ components: []
+ }
+ ],
+ designMetadata: {
+ id: 'test-page-metadata',
+ name: 'Test Page',
+ regionDefinitions: [
+ {
+ id: 'main-region',
+ componentTypeExclusions: ['excluded-type'],
+ componentTypeInclusions: ['included-type']
+ }
+ ]
+ }
+ } as unknown as PageWithDesignMetadata
+
+ test('renders page region with components', () => {
+ render()
+
+ expect(screen.getByTestId('region-wrapper')).toBeInTheDocument()
+ expect(screen.getByTestId('component-comp-1')).toBeInTheDocument()
+ expect(screen.getByTestId('component-comp-2')).toBeInTheDocument()
+ })
+
+ test('renders empty region without components', () => {
+ render()
+
+ expect(screen.getByTestId('region-wrapper')).toBeInTheDocument()
+ expect(screen.queryByTestId(/^component-/)).not.toBeInTheDocument()
+ })
+
+ test('returns null when region is not found and no errorElement', () => {
+ const {container} = render()
+
+ expect(container.firstChild).toBeNull()
+ })
+
+ test('renders errorElement when region is not found', () => {
+ render(
+ Region not found
