@faststore/core 4.5.0-dev.1 → 4.5.0-dev.3

package/.turbo/turbo-generate.log

@@ -1,9 +1,9 @@
 
-> @faststore/core@4.5.0-dev.0 generate /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@4.5.0-dev.2 generate /home/runner/work/faststore/faststore/packages/core
 > pnpm run gen-types && pnpm run cache-graphql 
 
 
-> @faststore/core@4.5.0-dev.0 gen-types /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@4.5.0-dev.2 gen-types /home/runner/work/faststore/faststore/packages/core
 > node ../cli/bin/run generate-types .
 
 [STARTED] Parse Configuration
@@ -19,7 +19,7 @@
 [COMPLETED] Generate to /home/runner/work/faststore/faststore/packages/core/@generated/
 [COMPLETED] Generate outputs
 
-> @faststore/core@4.5.0-dev.0 cache-graphql /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@4.5.0-dev.2 cache-graphql /home/runner/work/faststore/faststore/packages/core
 > node ../cli/bin/run cache-graphql --config=./discovery.config.default.js --queries=./@generated/persisted-documents.json
 
 [Info] - Config file location: /home/runner/work/faststore/faststore/packages/core/discovery.config.default.js

package/.turbo/turbo-test.log

@@ -1,11 +1,11 @@
 
-> @faststore/core@4.5.0-dev.0 test /home/runner/work/faststore/faststore/packages/core
+> @faststore/core@4.5.0-dev.2 test /home/runner/work/faststore/faststore/packages/core
 > vitest run
 
 
  RUN  v4.0.7 /home/runner/work/faststore/faststore/packages/core
 
- ✓  browser  test/sdk/session/reconcileSessionLocale.browser.test.ts (5 tests) 44ms
+ ✓  browser  test/sdk/session/reconcileSessionLocale.browser.test.ts (5 tests) 42ms
 stderr | test/components/RecommendationShelf/RecommendationShelf.browser.test.tsx
 Error in optimistic validation: TypeError: Failed to parse URL from /api/graphql?operationName=ValidateCartMutation&operationHash=32c15f8888ca34f223def7972b7f19090808435a
     at node:internal/deps/undici/undici:16416:13
@@ -32,13 +32,12 @@
   }
 }
 
+ ✓  browser  test/components/account/ContractSwitcher.browser.test.tsx (13 tests) 2028ms
+     ✓ shows an error state when the list fails to load  610ms
 stderr | test/components/RecommendationShelf/RecommendationShelf.browser.test.tsx > RecommendationShelf > renders nothing when there is an error
 Error fetching recommendations undefined boom for campaign vrn:recommendations:acc:rec-top-items-v2:campaign-1
 
- ✓  browser  test/components/RecommendationShelf/RecommendationShelf.browser.test.tsx (8 tests) 254ms
- ✓  browser  test/components/account/ContractSwitcher.browser.test.tsx (13 tests) 2294ms
-     ✓ shows an error state when the list fails to load  682ms
-     ✓ requires selecting a contract before Confirm is enabled, then switches (REQ-03)  325ms
+ ✓  browser  test/components/RecommendationShelf/RecommendationShelf.browser.test.tsx (8 tests) 282ms
 stderr | test/pages/password-protection.browser.test.tsx > PasswordProtectionLogin > posts the password and redirects to the requested return path
 Warning: An update to PasswordProtectionLogin inside a test was not wrapped in act(...).
 
@@ -268,14 +267,12 @@ act(() => {
 This ensures that you're testing the behavior the user would see in the browser. Learn more at https://reactjs.org/link/wrap-tests-with-act
     at PasswordProtectionLogin (/home/runner/work/faststore/faststore/packages/core/src/pages/password-protection/index.tsx:19:69)
 
- ✓  browser  test/pages/password-protection.browser.test.tsx (6 tests) 1479ms
-     ✓ renders the password protection form  659ms
- ✓  browser  test/sdk/session/getInitialSession.browser.test.ts (6 tests) 19ms
- ✓  browser  test/sdk/account/changeContractToken.browser.test.ts (9 tests) 90ms
- ✓  browser  test/components/account/OrganizationDrawer.browser.test.tsx (5 tests) 2251ms
-     ✓ renders the menu view with contract details and manage footer  1053ms
-     ✓ opens the contract switcher and returns to the menu on back  529ms
-     ✓ resets to the menu when the drawer closes  349ms
+ ✓  browser  test/pages/password-protection.browser.test.tsx (6 tests) 1279ms
+     ✓ renders the password protection form  519ms
+ ✓  browser  test/sdk/session/getInitialSession.browser.test.ts (6 tests) 27ms
+ ✓  browser  test/components/account/OrganizationDrawer.browser.test.tsx (5 tests) 1699ms
+     ✓ renders the menu view with contract details and manage footer  978ms
+     ✓ opens the contract switcher and returns to the menu on back  349ms
 stderr | test/sdk/localization/store-url.browser.test.ts
 Error in optimistic validation: TypeError: Cannot read properties of undefined (reading 'read')
     at validateCart (/home/runner/work/faststore/faststore/packages/core/src/sdk/cart/index.ts:119:27)
@@ -283,9 +280,10 @@ This ensures that you're testing the behavior the user would see in the browser.
     at a (/home/runner/work/faststore/faststore/packages/sdk/dist/es/index.mjs:354:23)
     at processTicksAndRejections (node:internal/process/task_queues:103:5)
 
- ✓  browser  test/sdk/localization/store-url.browser.test.ts (3 tests) 14ms
- ✓  browser  test/sdk/account/useAvailableContracts.browser.test.ts (6 tests) 132ms
- ✓  browser  test/sdk/account/useSwitchContract.browser.test.ts (4 tests) 155ms
+ ✓  browser  test/sdk/account/changeContractToken.browser.test.ts (9 tests) 92ms
+ ✓  browser  test/sdk/localization/store-url.browser.test.ts (3 tests) 17ms
+ ✓  browser  test/sdk/account/useAvailableContracts.browser.test.ts (6 tests) 101ms
+ ✓  browser  test/sdk/account/useSwitchContract.browser.test.ts (4 tests) 145ms
 stderr | test/components/account/doLogout.browser.test.ts
 Error in optimistic validation: TypeError: Cannot read properties of undefined (reading 'read')
     at validateCart (/home/runner/work/faststore/faststore/packages/core/src/sdk/cart/index.ts:119:27)
@@ -293,7 +291,7 @@ This ensures that you're testing the behavior the user would see in the browser.
     at a (/home/runner/work/faststore/faststore/packages/sdk/dist/es/index.mjs:354:23)
     at processTicksAndRejections (node:internal/process/task_queues:103:5)
 
- ✓  browser  test/components/account/doLogout.browser.test.ts (1 test) 61ms
+ ✓  browser  test/components/account/doLogout.browser.test.ts (1 test) 87ms
 stderr | test/sdk/account/clearPersistedSessionState.browser.test.ts
 Error in optimistic validation: TypeError: Cannot read properties of undefined (reading 'read')
     at validateCart (/home/runner/work/faststore/faststore/packages/core/src/sdk/cart/index.ts:119:27)
@@ -301,10 +299,10 @@ This ensures that you're testing the behavior the user would see in the browser.
     at a (/home/runner/work/faststore/faststore/packages/sdk/dist/es/index.mjs:354:23)
     at processTicksAndRejections (node:internal/process/task_queues:103:5)
 
- ✓  browser  test/components/account/OrganizationDrawerHeader.browser.test.tsx (3 tests) 285ms
- ✓  browser  test/components/account/OrganizationDrawerFooter.browser.test.tsx (3 tests) 317ms
  ✓  browser  test/sdk/account/clearPersistedSessionState.browser.test.ts (1 test) 9ms
- ✓  browser  test/utils/isLocalHost.browser.test.ts (3 tests) 4ms
+ ✓  browser  test/components/account/OrganizationDrawerFooter.browser.test.tsx (3 tests) 286ms
+ ✓  browser  test/components/account/OrganizationDrawerHeader.browser.test.tsx (3 tests) 292ms
+ ✓  browser  test/utils/isLocalHost.browser.test.ts (3 tests) 5ms
  ✓  browser  test/sdk/session/reconcileSessionLocale.disabled.browser.test.ts (1 test) 3ms
 stderr | test/sdk/account/refreshToken.browser.test.ts
 Error in optimistic validation: TypeError: Cannot read properties of undefined (reading 'read')
@@ -313,12 +311,12 @@ This ensures that you're testing the behavior the user would see in the browser.
     at a (/home/runner/work/faststore/faststore/packages/sdk/dist/es/index.mjs:354:23)
     at processTicksAndRejections (node:internal/process/task_queues:103:5)
 
- ✓  node  test/utils/localization/bindingPaths.test.ts (71 tests) 31ms
- ✓  browser  test/sdk/account/refreshToken.browser.test.ts (1 test) 4ms
- ✓  node  test/utils/match-url.test.ts (10 tests) 8ms
- ✓  node  test/server/password-protection-service.test.ts (22 tests) 38ms
- ✓  node  test/sdk/localization/bindingSelector.test.ts (18 tests) 10ms
- ✓  node  test/pages/api/unlock.test.ts (15 tests) 175ms
+ ✓  node  test/utils/localization/bindingPaths.test.ts (71 tests) 25ms
+ ✓  browser  test/sdk/account/refreshToken.browser.test.ts (1 test) 6ms
+ ✓  node  test/server/password-protection-service.test.ts (22 tests) 27ms
+ ✓  node  test/utils/match-url.test.ts (10 tests) 7ms
+ ✓  node  test/sdk/localization/bindingSelector.test.ts (18 tests) 7ms
+ ✓  node  test/pages/api/unlock.test.ts (15 tests) 195ms
 stderr | test/components/search/SearchInputComponent.test.tsx
 Warning: forwardRef render functions accept exactly two parameters: props and ref. Did you forget to use the ref parameter?
 
@@ -382,23 +380,23 @@ Warning: React does not recognize the `providerProps` prop on a DOM element. If
     at Suspense
     at Wrapper (/home/runner/work/faststore/faststore/packages/core/test/components/search/SearchInputComponent.test.tsx:106:20)
 
- ✓  node  test/components/search/SearchInputComponent.test.tsx (6 tests) 91ms
- ✓  node  test/sdk/localization/useBindingSelector.test.tsx (12 tests) 12ms
- ✓  node  test/utils/cookieCacheBusting.test.ts (10 tests) 17ms
- ✓  node  test/sdk/search/useSearchHistory.test.ts (13 tests) 58ms
- ✓  node  test/utils/clearCookies.test.ts (20 tests) 21ms
- ✓  node  test/components/quotes/MyAccountListQuotesTable.test.tsx (12 tests) 316ms
+ ✓  node  test/components/search/SearchInputComponent.test.tsx (6 tests) 67ms
+ ✓  node  test/utils/cookieCacheBusting.test.ts (10 tests) 19ms
+ ✓  node  test/sdk/localization/useBindingSelector.test.tsx (12 tests) 10ms
+ ✓  node  test/sdk/search/useSearchHistory.test.ts (13 tests) 72ms
+ ✓  node  test/utils/clearCookies.test.ts (20 tests) 28ms
+ ✓  node  test/components/quotes/MyAccountListQuotesTable.test.tsx (12 tests) 329ms
 stderr | test/sdk/account/useSetPassword.test.ts > useSetPassword > maps wrongcredentials error responses to the existing message
 Set password request failed: Bad Request
 
- ✓  node  test/sdk/account/useSetPassword.test.ts (6 tests) 30ms
+ ✓  node  test/sdk/account/useSetPassword.test.ts (6 tests) 39ms
  ✓  node  test/components/quotes/quoteFilters.test.ts (23 tests) 24ms
- ✓  node  test/components/quotes/MyAccountListQuotes.test.tsx (9 tests) 835ms
+ ✓  node  test/components/quotes/MyAccountListQuotes.test.tsx (9 tests) 823ms
      ✓ navigates with the search term on blur  359ms
-     ✓ navigates without a label param when the search is cleared  363ms
- ✓  node  test/utils/multipleTemplates.test.ts (8 tests) 7ms
- ✓  node  test/utils/localization/localizeRedirectDestination.test.ts (11 tests) 6ms
- ✓  node  test/sdk/orderEntry/useOrderEntryOperation.test.ts (8 tests) 30ms
+     ✓ navigates without a label param when the search is cleared  359ms
+ ✓  node  test/utils/multipleTemplates.test.ts (8 tests) 6ms
+ ✓  node  test/utils/localization/localizeRedirectDestination.test.ts (11 tests) 8ms
+ ✓  node  test/sdk/orderEntry/useOrderEntryOperation.test.ts (8 tests) 38ms
 stderr | test/pages/api/graphql.test.ts > /api/graphql error status propagation > propagates the upstream 400 from a wrapped BadRequestError instead of 500
 Graphql execution returned with error:  [
   {
@@ -445,46 +443,46 @@ Warning: React does not recognize the `providerProps` prop on a DOM element. If
   { message: 'bad', status: 400, type: 'BadRequestError' }
 ]
 
- ✓  node  test/pages/api/graphql.test.ts (10 tests) 25ms
- ✓  node  test/sdk/orderEntry/useOrderEntryUpload.test.ts (8 tests) 36ms
- ✓  node  test/sdk/orderEntry/useOrderEntry.test.ts (8 tests) 50ms
- ✓  node  test/components/quotes/MyAccountQuotesFilterSlider.test.tsx (5 tests) 173ms
- ✓  node  test/proxy.localization.test.ts (5 tests) 76ms
- ✓  node  test/server/index.test.ts (7 tests) 1060ms
-       ✓ should handle options and execute  540ms
- ✓  node  test/proxy.test.ts (4 tests) 20ms
- ✓  node  test/server/webops-api.test.ts (9 tests) 18ms
- ✓  node  test/components/quotes/MyAccountQuotesSelectedTags.test.tsx (8 tests) 98ms
- ✓  node  test/sdk/orderEntry/useOrderFormItems.test.ts (7 tests) 32ms
+ ✓  node  test/pages/api/graphql.test.ts (10 tests) 17ms
+ ✓  node  test/sdk/orderEntry/useOrderEntryUpload.test.ts (8 tests) 56ms
+ ✓  node  test/sdk/analytics/useStartRecommendationSession.test.ts (6 tests) 50ms
+ ✓  node  test/components/quotes/MyAccountQuotesFilterSlider.test.tsx (5 tests) 138ms
+ ✓  node  test/proxy.localization.test.ts (5 tests) 51ms
+ ✓  node  test/server/index.test.ts (7 tests) 699ms
+ ✓  node  test/sdk/orderEntry/useOrderEntry.test.ts (8 tests) 30ms
+ ✓  node  test/proxy.test.ts (4 tests) 32ms
+ ✓  node  test/sdk/orderEntry/useOrderFormItems.test.ts (7 tests) 38ms
+ ✓  node  test/server/webops-api.test.ts (9 tests) 21ms
+ ✓  node  test/components/quotes/MyAccountQuotesSelectedTags.test.tsx (8 tests) 105ms
+ ✓  node  test/sdk/account/refreshToken.test.ts (5 tests) 9ms
  ✓  node  test/server/cms/global.test.ts (3 tests) 5ms
- ✓  node  test/sdk/account/refreshToken.test.ts (5 tests) 8ms
- ✓  node  test/sdk/account/getMyAccountRoutes.test.ts (8 tests) 14ms
- ✓  node  test/server/content/service.test.ts (5 tests) 7ms
+ ✓  node  test/sdk/account/getMyAccountRoutes.test.ts (8 tests) 5ms
+ ✓  node  test/server/content/service.test.ts (5 tests) 5ms
  ✓  node  test/sdk/localization/store-url.test.ts (1 test) 4ms
- ✓  node  test/sdk/auth/useAuth.test.ts (5 tests) 21ms
- ✓  node  test/utils/getRequestHostname.test.ts (12 tests) 5ms
- ✓  node  test/components/quotes/MyAccountQuotesStatusSelector.test.tsx (6 tests) 143ms
- ✓  node  test/pages/api/preview.test.ts (2 tests) 10ms
+ ✓  node  test/sdk/analytics/hasEnabledRecommendationShelf.test.ts (6 tests) 5ms
+ ✓  node  test/sdk/auth/useAuth.test.ts (5 tests) 20ms
+ ✓  node  test/utils/getRequestHostname.test.ts (12 tests) 7ms
+ ✓  node  test/components/quotes/MyAccountQuotesStatusSelector.test.tsx (6 tests) 142ms
+ ✓  node  test/pages/api/preview.test.ts (2 tests) 8ms
+ ✓  node  test/utils/validateSessionRefreshToken.test.ts (6 tests) 8ms
  ✓  node  test/components/search/SearchInput.test.ts (6 tests) 7ms
- ✓  node  test/utils/validateSessionRefreshToken.test.ts (6 tests) 5ms
- ✓  node  test/sdk/analytics/useStartRecommendationSession.test.ts (3 tests) 31ms
- ✓  node  test/components/RecommendationShelf/vrn.test.ts (5 tests) 6ms
- ✓  node  test/components/RecommendationShelf/useRecommendationUserId.test.ts (4 tests) 193ms
- ✓  node  test/components/account/Layout.test.tsx (4 tests) 83ms
+ ✓  node  test/components/RecommendationShelf/vrn.test.ts (5 tests) 5ms
  ✓  node  test/server/cms/index.test.ts (2 tests) 6ms
- ✓  node  test/utils/retry.test.ts (5 tests) 14ms
- ✓  node  test/utils/unlockResponse.test.ts (11 tests) 6ms
+ ✓  node  test/utils/retry.test.ts (5 tests) 13ms
+ ✓  node  test/components/account/Layout.test.tsx (4 tests) 37ms
+ ✓  node  test/components/RecommendationShelf/useRecommendationUserId.test.ts (4 tests) 190ms
+ ✓  node  test/utils/unlockResponse.test.ts (11 tests) 5ms
  ✓  node  test/components/RecommendationShelf/useRecommendations.test.ts (2 tests) 5ms
  ✓  node  test/utils/isLocalHost.test.ts (7 tests) 5ms
  ✓  node  test/utils/userOrderStatus.test.ts (3 tests) 4ms
- ✓  node  test/components/account/OrganizationDrawerBody.test.tsx (3 tests) 54ms
- ✓  node  test/components/auth/ProfileChallenge.test.tsx (3 tests) 43ms
+ ✓  node  test/components/account/OrganizationDrawerBody.test.tsx (3 tests) 37ms
  ✓  node  test/sdk/analytics/utils.test.ts (2 tests) 4ms
- ✓  node  test/sdk/account/clearPersistedSessionState.test.ts (1 test) 20ms
- ✓  node  test/components/quotes/MyAccountQuoteStatusBadge.test.tsx (2 tests) 25ms
-
- Test Files  70 passed (70)
-      Tests  539 passed (539)
-   Start at  21:43:08
-   Duration  36.60s (transform 8.50s, setup 0ms, collect 29.72s, tests 11.44s, environment 48.51s, prepare 1.27s)
+ ✓  node  test/components/auth/ProfileChallenge.test.tsx (3 tests) 30ms
+ ✓  node  test/sdk/account/clearPersistedSessionState.test.ts (1 test) 9ms
+ ✓  node  test/components/quotes/MyAccountQuoteStatusBadge.test.tsx (2 tests) 23ms
+
+ Test Files  71 passed (71)
+      Tests  548 passed (548)
+   Start at  21:46:31
+   Duration  36.11s (transform 8.70s, setup 0ms, collect 28.71s, tests 9.95s, environment 48.82s, prepare 1.22s)
 

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.5.0-dev.3](https://github.com/vtex/faststore/compare/v4.5.0-dev.2...v4.5.0-dev.3) (2026-07-22)
+
+### Features
+
+- **core:** move recommendation session start to CMS Global Section ([8589056](https://github.com/vtex/faststore/commit/8589056046b38e5dbc4f8ce6dcc669f7a15a4d85))
+
+# [4.5.0-dev.2](https://github.com/vtex/faststore/compare/v4.5.0-dev.1...v4.5.0-dev.2) (2026-07-20)
+
+**Note:** Version bump only for package @faststore/core
+
 # [4.5.0-dev.1](https://github.com/vtex/faststore/compare/v4.5.0-dev.0...v4.5.0-dev.1) (2026-07-14)
 
 ### Bug Fixes

package/cms/faststore/components/cms_component__recommendationshelf.jsonc

@@ -3,10 +3,16 @@
   "$componentKey": "RecommendationShelf",
   "$componentTitle": "Recommendation Shelf",
   "title": "Recommendation Shelf",
-  "description": "Display a carousel of personalized product recommendations from a VTEX Recommendations campaign.",
+  "description": "Display a carousel of personalized product recommendations from a VTEX Recommendations campaign. Enable the shelf with the Enable recommendations toggle (off by default).",
   "type": "object",
   "required": ["campaignVrn"],
   "properties": {
+    "enableRecommendations": {
+      "title": "Enable recommendations?",
+      "description": "When enabled, starts the VTEX Recommendations personalization session (once per browser session) and fetches personalized products for this shelf. Off by default so stores that do not use Recommendations never hit the Recommendations API.",
+      "type": "boolean",
+      "default": false
+    },
     "title": {
       "title": "Title",
       "description": "Override the shelf title. If not set, the campaign title will be used.",

package/cms/faststore/schema.json

@@ -4434,10 +4434,16 @@
       "$componentKey": "RecommendationShelf",
       "$componentTitle": "Recommendation Shelf",
       "title": "Recommendation Shelf",
-      "description": "Display a carousel of personalized product recommendations from a VTEX Recommendations campaign.",
+      "description": "Display a carousel of personalized product recommendations from a VTEX Recommendations campaign. Enable the shelf with the Enable recommendations toggle (off by default).",
       "type": "object",
       "required": ["campaignVrn"],
       "properties": {
+        "enableRecommendations": {
+          "title": "Enable recommendations?",
+          "description": "When enabled, starts the VTEX Recommendations personalization session (once per browser session) and fetches personalized products for this shelf. Off by default so stores that do not use Recommendations never hit the Recommendations API.",
+          "type": "boolean",
+          "default": false
+        },
         "title": {
           "title": "Title",
           "description": "Override the shelf title. If not set, the campaign title will be used.",

package/discovery.config.default.js

@@ -201,9 +201,6 @@ module.exports = {
     },
     refreshToken: false,
     scrollRestoration: false,
-    // Opt-in flag for VTEX Recommendations. When disabled (default), the store
-    // never starts a personalization session nor calls the Recommendations API.
-    enableRecommendations: false,
     /** Package names to transpile (e.g. ['@vtex/components']). Use a non-empty list to enable Next.js transpilation. */
     transpilePackages: [],
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "4.5.0-dev.1",
+  "version": "4.5.0-dev.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -71,11 +71,11 @@
     "style-loader": "^3.3.1",
     "swr": "^2.2.5",
     "use-sync-external-store": "^1.6.0",
-    "@faststore/api": "4.5.0-dev.1",
-    "@faststore/sdk": "4.5.0-dev.1",
-    "@faststore/diagnostics": "4.5.0-dev.1",
-    "@faststore/ui": "4.5.0-dev.1",
-    "@faststore/lighthouse": "4.5.0-dev.1"
+    "@faststore/diagnostics": "4.5.0-dev.3",
+    "@faststore/lighthouse": "4.5.0-dev.3",
+    "@faststore/sdk": "4.5.0-dev.3",
+    "@faststore/api": "4.5.0-dev.3",
+    "@faststore/ui": "4.5.0-dev.3"
   },
   "devDependencies": {
     "@cypress/code-coverage": "^3.12.1",

package/src/Layout.tsx

@@ -6,11 +6,10 @@ import { useStartRecommendationSession } from './sdk/analytics/hooks/useStartRec
 function Layout({ children }: PropsWithChildren) {
   const props = isValidElement(children) ? children.props : undefined
   usePageViewEvent(props)
-  // Implemented here because the personalization session must be initiated once
-  // per browser session on each page. Gated behind the
-  // `experimental.enableRecommendations` flag: stores that don't opt into
-  // Recommendations never start a session nor call the Recommendations API.
-  useStartRecommendationSession()
+
+  // Starts the personalization session once per browser session when the page
+  // CMS data includes a RecommendationShelf with `enableRecommendations: true`.
+  useStartRecommendationSession(props)
 
   return <>{children}</>
 }

package/src/components/sections/RecommendationShelf/README.md

@@ -0,0 +1,163 @@
+# Recommendation Shelf
+
+CMS section that renders a carousel of personalized product recommendations from a **VTEX Recommendations** campaign. It uses the same product cards (`ProductCard`) as other store shelves; items come from a recommendation campaign (cross-sell, similar items, top sellers, personalized, and related types) instead of a search query.
+
+- **Data source:** VTEX Recommendations BFF, exposed by `@faststore/api` through the `recommendations` GraphQL query.
+- **Registration:** global CMS component (`$componentKey: "RecommendationShelf"`), available on any page via CMS.
+- **Opt-in via CMS:** enable Recommendations with the **Enable recommendations?** toggle on the shelf (default `false`). No store code changes or feature flags are required.
+
+## Contents
+
+- [Prerequisites](#prerequisites)
+- [Setup](#setup)
+- [CMS configuration](#cms-configuration)
+- [Campaign types (VRN) and context](#campaign-types-vrn-and-context)
+- [Runtime behavior](#runtime-behavior)
+- [Code-level overrides](#code-level-overrides)
+- [Placement guidelines](#placement-guidelines)
+- [Privacy and cache](#privacy-and-cache)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+The shelf renders products only when the following conditions are met:
+
+1. **Enable recommendations on the shelf.** Set **Enable recommendations?** to `true` on the Recommendation Shelf in the CMS. This opts the store into the personalization session (`startRecommendationSession` mutation, owned by Layout) and allows the shelf to fetch recommendations. Without it (default `false`), no session is started and the shelf does not fetch.
+
+2. **Active VTEX Recommendations campaign.** Provide a valid campaign **VRN**. Example: `vrn:recommendations:my-account:rec-persona-v2:abc123`.
+
+3. **Activity Flow script (optional, recommended).** Used for analytics:
+   - reads PDP `product:*` meta tags to capture product view events;
+   - reads `data-af-*` attributes on the shelf to capture impression, view, and click events.
+
+## Setup
+
+### 1. Obtain the campaign VRN
+
+In the VTEX Recommendations admin, create or select a campaign and copy its **VRN**. The expected format is:
+
+```text
+vrn:recommendations:<account>:<campaign-type>:<campaign-id>
+```
+
+Supported `<campaign-type>` values are listed under [Campaign types (VRN) and context](#campaign-types-vrn-and-context).
+
+### 2. Add Recommendation Shelf via CMS
+
+Add **Recommendation Shelf** to the target page (home, PDP, PLP, cart, and so on), configure at least **Campaign VRN** (required), and turn **Enable recommendations?** on.
+
+## CMS configuration
+
+Schema: `cms/faststore/components/cms_component__recommendationshelf.jsonc`.
+
+| CMS property | Key | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| Enable recommendations? | `enableRecommendations` | boolean | No | `false` | Opt-in that starts the personalization session (via Layout) and allows this shelf to fetch recommendations. |
+| Title | `title` | string | No | — | Overrides the shelf title. Falls back to the campaign title. If both are empty, the heading is not rendered. |
+| Campaign VRN | `campaignVrn` | string | **Yes** | — | Recommendation campaign VRN. Validated by regex (see campaign types below). |
+| Items context | `itemsContext` | `PDP` \| `CART` | No | `PDP` | Source of products used as request context. Applies only to context-based campaigns. |
+| **Carousel Configuration** | `carouselConfiguration` | object | No | — | Carousel settings. |
+| › Items per page (desktop) | `itemsPerPageDesktop` | number | No | `4` | Items per page on desktop. |
+| › Items per page (mobile) | `itemsPerPageMobile` | number | No | `2` | Items per page on mobile and tablet (≤ 768px). |
+| › Carousel track variant | `variant` | `slide` \| `scroll` | No | `scroll` | Carousel navigation mode. |
+| › Infinite navigation? | `infiniteMode` | boolean | No | `false` | Infinite navigation (slide variant only). |
+| › Navigation controls | `controls` | `complete` \| `navigationArrows` \| `paginationBullets` | No | `complete` | Visible navigation controls. |
+| **Product Card Configuration** | `productCardConfiguration` | object | No | — | Product card settings. |
+| › Show discount badge? | `showDiscountBadge` | boolean | No | `true` | Shows the discount badge. |
+| › Cards should be bordered? | `bordered` | boolean | No | `true` | Renders bordered cards. |
+
+## Campaign types (VRN) and context
+
+The campaign type is derived from the `<campaign-type>` segment of the VRN:
+
+| Campaign | VRN segment | Internal type | Requires product context? |
+| --- | --- | --- | --- |
+| Cross-Sell | `rec-cross-v2` | `CROSS_SELL` | **Yes** |
+| Similar Items | `rec-similar-v2` | `SIMILAR_ITEMS` | **Yes** |
+| Visual Similarity | `rec-visual-v2` | `VISUAL_SIMILARITY` | **Yes** |
+| Next Interactions | `rec-next-v2` | `NEXT_INTERACTION` | **Yes** |
+| Personalized | `rec-persona-v2` | `PERSONALIZED` | No |
+| Top Sellers | `rec-top-items-v2` | `TOP_ITEMS` | No |
+| Last Seen | `rec-last-v2` | `LAST_SEEN` | No |
+| Search-Based | `rec-search-v2` | `SEARCH_BASED` | No |
+
+**Product context (`itemsContext`):**
+
+- `PDP` (default): uses the current product detail page product (`productGroupID`). Outside a PDP there is no product context.
+- `CART`: uses the products currently in the cart (deduplicated). Intended for cross-sell on the cart page.
+
+Context-based campaigns (cross-sell, similar items, visual similarity, next interaction) skip the request when no context products are available. Context-agnostic campaigns (top sellers, personalized, last seen, search-based) ignore `itemsContext`.
+
+## Runtime behavior
+
+All recommendation work runs client-side after hydration:
+
+1. **Session start (CMS opt-in)** — `Layout` calls `useStartRecommendationSession(pageProps)` once. The hook checks whether any `RecommendationShelf` in the CMS data has `enableRecommendations: true` and no-ops when none do. Multiple enabled shelves on the same page still start the session only once (in-memory lock + session cookie).
+2. **User id resolution** — `useRecommendationUserId()` reads the `vtex-rec-user-id` cookie, retrying until a value is available or the retry budget is exhausted.
+3. **Request arguments** — when enabled, `getRecommendationArguments()` builds `{ userId, campaignVrn, products }` or returns `null` when the VRN is invalid, the user id is missing, or a context-based campaign has no context products. When disabled, arguments stay `null`.
+4. **Fetch** — `useRecommendations()` runs `ClientRecommendationsQuery` and returns `products`, `correlationId`, and `campaign`.
+5. **Render** — shows `ProductShelfSkeleton` while loading; returns `null` on error or empty results; otherwise renders the carousel and optional heading.
+6. **Tracking** — when correlation and campaign identifiers are present, the shelf emits `data-af-*` attributes for Activity Flow. PDP product views use `product:*` meta tags from `pages/[slug]/p.tsx`.
+
+Related files:
+
+- Shelf: `src/components/sections/RecommendationShelf/`
+- Hook: `src/sdk/analytics/hooks/useStartRecommendationSession.ts`
+- Layout: `src/Layout.tsx`
+
+## Code-level overrides
+
+In addition to CMS props, the component accepts code-level overrides (not exposed in the CMS schema):
+
+```tsx
+import { RecommendationShelf } from 'src/components/sections/RecommendationShelf'
+
+<RecommendationShelf
+  enableRecommendations
+  campaignVrn="vrn:recommendations:my-account:rec-cross-v2:abc123"
+  itemsContext="PDP"
+  ProductCard={MyCustomCard}
+  mapProductToProductCard={(product, index) => ({
+    product,
+    index,
+    highlight: index === 0,
+  })}
+  carouselConfiguration={{ itemsPerPageDesktop: 5, variant: 'slide' }}
+/>
+```
+
+- **`ProductCard`**: custom card component (defaults to the core `ProductCard`).
+- **`mapProductToProductCard`**: maps each recommended product (normalized `StoreProduct`) into card props. When provided, it fully owns the card props and the default `productCardConfiguration` merge no longer applies.
+
+Campaign types and VRN validation are defined in `vrn.ts` (`VRN_TYPE_TO_RECOMMENDATION`). Updates should be made there and mirrored in the CMS schema `pattern`.
+
+## Placement guidelines
+
+As a global component, the shelf can be placed on any CMS page. Suggested placements by campaign type:
+
+- **Home / institutional pages:** context-agnostic campaigns (top sellers, personalized, last seen, search-based).
+- **PDP:** context-based campaigns with `itemsContext: PDP`.
+- **Cart:** cross-sell with `itemsContext: CART`.
+- **PLP:** context-agnostic campaigns.
+
+The personalization session runs only when at least one shelf has **Enable recommendations?** turned on.
+
+## Privacy and cache
+
+- The `recommendations` query uses `@cacheControl(scope: "private", sMaxAge: 120, staleWhileRevalidate: 3600)`.
+- Error logs omit `recommendationArgs` (which includes `userId`) and log only non-identifying context such as `campaignVrn`.
+- BFF `vtex-rec-*` cookies are forwarded to the browser through `ctx.storage.cookies`.
+
+## Troubleshooting
+
+**The shelf does not render.** Check, in order:
+
+1. Is **Enable recommendations?** set to `true` on the shelf?
+2. Is `campaignVrn` valid and is the campaign active?
+3. Is the `vtex-rec-user-id` cookie available? Without a user id, the shelf does not fetch.
+4. For context-based campaigns, is product context available (`PDP` on a product page, or a non-empty cart for `CART`)?
+5. Did the campaign return products? An empty response renders nothing by design.
+
+**Skeleton never resolves.** Inspect the console and the GraphQL `recommendations` response for pending or failing requests.
+
+**No tracking events.** Confirm that the Activity Flow script is present and that PDP `product:*` meta tags and shelf `data-af-*` attributes are rendered.

package/src/components/sections/RecommendationShelf/RecommendationShelf.tsx

@@ -4,8 +4,6 @@ import { usePDP } from '@faststore/core'
 import { ProductShelf, Carousel } from '@faststore/ui'
 import type { ProductSummary_ProductFragment } from '@generated/graphql'
 
-import storeConfig from 'discovery.config'
-
 import DefaultProductCard, {
   type ProductCardProps,
 } from 'src/components/product/ProductCard'
@@ -66,6 +64,7 @@ export function RecommendationShelf<
 >({
   title,
   campaignVrn,
+  enableRecommendations = false,
   itemsContext = 'PDP',
   ProductCard,
   mapProductToProductCard,
@@ -120,9 +119,9 @@ export function RecommendationShelf<
     return pdpProduct ? [pdpProduct] : []
   }, [itemsContext, cartItems, productDetailPage])
 
-  // Gate the whole feature behind the opt-in flag: when Recommendations is
+  // Gate the whole feature behind the CMS opt-in: when Recommendations is
   // disabled the shelf never requests recommendations (nor renders).
-  const recommendationArgs = storeConfig.experimental.enableRecommendations
+  const recommendationArgs = enableRecommendations
     ? getRecommendationArguments(campaignVrn, {
         userId,
         contextProducts,

package/src/components/sections/RecommendationShelf/RecommendationShelf.types.ts

@@ -30,6 +30,13 @@ export type RecommendationShelfProps<
 > = {
   readonly title?: string
   readonly campaignVrn: string
+  /**
+   * Opt-in for VTEX Recommendations on this shelf. When `true`, Layout starts
+   * the personalization session (`useStartRecommendationSession`) and this
+   * shelf fetches recommendations. When `false` (default), neither happens.
+   * @default false
+   */
+  readonly enableRecommendations?: boolean
   /**
    * Where to read the products used as context for the recommendation request:
    * - `'PDP'`: the current product detail page product.
@@ -45,7 +52,7 @@ export type RecommendationShelfProps<
   /**
    * Custom card component rendered for each recommended product. Defaults to the
    * core `ProductCard`. This is a code-level override and is not exposed through
-   * the CMS schema (`cms_component__RecommendationShelf.jsonc`).
+   * the CMS schema (`cms_component__recommendationshelf.jsonc`).
    */
   readonly ProductCard?: ComponentType<TCardProps>
   /**

package/src/sdk/analytics/hooks/useStartRecommendationSession.ts

@@ -1,8 +1,8 @@
-import { useEffect } from 'react'
+import { useEffect, useRef } from 'react'
 
 import { gql } from '@faststore/core/api'
 
-import storeConfig from 'discovery.config'
+import { hasEnabledRecommendationShelf } from 'src/sdk/analytics/utils/hasEnabledRecommendationShelf'
 import { useLazyQuery } from 'src/sdk/graphql/useLazyQuery'
 import { getCookie } from 'src/utils/getCookie'
 import { retry } from 'src/utils/retry'
@@ -20,12 +20,28 @@ const startRecommendationSessionMutation = gql(`
 type StartRecommendationSessionData = { startRecommendationSession: boolean }
 type StartRecommendationSessionVariables = Record<string, never>
 
+// In-memory lock so Layout re-renders (e.g. multiple RecommendationShelves
+// fetching) cannot start more than one session before the cookie lands.
+// Survives effect cleanup / Strict Mode remounts for this JS realm.
+let hasRequestedStartRecommendationSession = false
+
+/** @internal Test-only: clears the in-memory session-start lock. */
+export function resetStartRecommendationSessionLock() {
+  hasRequestedStartRecommendationSession = false
+}
+
 /**
  * Starts the anonymous recommendation/personalization session once per browser
  * session.
  *
- * Mounted globally from `Layout` so it runs on every page, regardless of
- * whether a recommendation section is present.
+ * Mounted from `Layout` with the current page props. Opt-in is controlled by
+ * the CMS boolean prop `enableRecommendations` on `RecommendationShelf`
+ * (default `false`): if no shelf on the page has it enabled, this hook is a
+ * no-op and the store never hits the Recommendations API.
+ *
+ * Multiple enabled shelves on the same page still produce a single call: the
+ * hook runs once from Layout and is gated by an in-memory lock plus the
+ * session cookie.
  *
  * The product view is no longer reported through a mutation here: the PDP now
  * exposes the product data as `<meta property="product:*">` tags, which the
@@ -33,11 +49,10 @@ type StartRecommendationSessionVariables = Record<string, never>
  *
  * All work runs client-side in effects (after hydration), so it doesn't affect
  * SSR/TTFB or Lighthouse render metrics.
- *
- * Gated behind the `experimental.enableRecommendations` flag: stores that don't
- * opt into Recommendations never start a session nor hit the Recommendations API.
  */
-export function useStartRecommendationSession() {
+export function useStartRecommendationSession(pageProps?: unknown) {
+  const enableRecommendations = hasEnabledRecommendationShelf(pageProps)
+
   const [runStartRecommendationSession] = useLazyQuery<
     StartRecommendationSessionData,
     StartRecommendationSessionVariables
@@ -49,30 +64,40 @@ export function useStartRecommendationSession() {
     }
   )
 
+  // useLazyQuery returns a new `execute` identity every render; keep a stable
+  // ref so the effect does not re-subscribe (and re-fire) on unrelated updates.
+  const runStartRecommendationSessionRef = useRef(runStartRecommendationSession)
+  runStartRecommendationSessionRef.current = runStartRecommendationSession
+
   useEffect(() => {
-    if (!storeConfig.experimental.enableRecommendations) {
+    if (!enableRecommendations) {
       return
     }
 
     const startRecommendationSessionCookie = getCookie(
       VTEX_REC_USER_START_SESSION
     )
-
     if (startRecommendationSessionCookie) {
       return
     }
 
-    const controller = new AbortController()
+    if (hasRequestedStartRecommendationSession) {
+      return
+    }
+    hasRequestedStartRecommendationSession = true
 
     // The session endpoint may not be ready on the first try, so we retry with
     // exponential backoff until it returns a defined result (or we give up).
     // Transient request/GraphQL rejections are treated as retryable: swallow
     // the error and return `undefined` so the backoff loop keeps going instead
     // of aborting on the first failure.
+    //
+    // Intentionally no AbortController: cleanup would cancel the only attempt
+    // (Strict Mode remount / Layout re-render) while the lock stays set.
     void retry(
       async () => {
         try {
-          return await runStartRecommendationSession({})
+          return await runStartRecommendationSessionRef.current({})
         } catch {
           return undefined
         }
@@ -83,14 +108,9 @@ export function useStartRecommendationSession() {
         backoff: true,
         maxDelayMs: 3000,
         until: (result) => result !== undefined,
-        signal: controller.signal,
       }
       // Guard the discarded promise so a give-up (or any unexpected rejection)
       // never surfaces as an unhandled promise rejection.
     ).catch(() => {})
-
-    return () => {
-      controller.abort()
-    }
-  }, [runStartRecommendationSession])
+  }, [enableRecommendations])
 }

package/src/sdk/analytics/utils/hasEnabledRecommendationShelf.ts

@@ -0,0 +1,49 @@
+type CmsSection = {
+  name?: string
+  $componentKey?: string
+  data?: {
+    enableRecommendations?: boolean
+  }
+}
+
+function pushSections(target: CmsSection[], value: unknown) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (item && typeof item === 'object') {
+        target.push(item as CmsSection)
+      }
+    }
+    return
+  }
+
+  if (value && typeof value === 'object') {
+    const sections = (value as { sections?: unknown }).sections
+    if (Array.isArray(sections)) {
+      pushSections(target, sections)
+    }
+  }
+}
+
+/**
+ * Returns true when the current page CMS data includes at least one
+ * `RecommendationShelf` with `enableRecommendations: true`.
+ */
+export function hasEnabledRecommendationShelf(pageProps: unknown): boolean {
+  if (!pageProps || typeof pageProps !== 'object') {
+    return false
+  }
+
+  const props = pageProps as Record<string, unknown>
+  const sections: CmsSection[] = []
+
+  pushSections(sections, props.sections)
+  pushSections(sections, props.globalSections)
+  pushSections(sections, props.page)
+
+  return sections.some(
+    (section) =>
+      (section.name === 'RecommendationShelf' ||
+        section.$componentKey === 'RecommendationShelf') &&
+      section.data?.enableRecommendations === true
+  )
+}

package/test/components/RecommendationShelf/RecommendationShelf.browser.test.tsx

@@ -47,27 +47,6 @@ vi.mock(
   })
 )
 
-// Keep the real store config (the cart SDK reads `storeConfig.cart` at module
-// init) and only override the opt-in flag, which we toggle per test.
-const recommendationsFlag = vi.hoisted(() => ({ enabled: true }))
-vi.mock('discovery.config', async (original) => {
-  const actual = (await original()) as { default?: Record<string, unknown> }
-  const base = (actual.default ?? actual) as Record<string, unknown>
-  const experimental = (base.experimental ?? {}) as Record<string, unknown>
-
-  return {
-    default: {
-      ...base,
-      experimental: {
-        ...experimental,
-        get enableRecommendations() {
-          return recommendationsFlag.enabled
-        },
-      },
-    },
-  }
-})
-
 import { RecommendationShelf } from 'src/components/sections/RecommendationShelf/RecommendationShelf'
 
 const CAMPAIGN_VRN = 'vrn:recommendations:acc:rec-top-items-v2:campaign-1'
@@ -91,7 +70,6 @@ beforeEach(() => {
     loading: false,
   })
   useRecommendationUserId.mockReturnValue('user-1')
-  recommendationsFlag.enabled = true
 })
 
 afterEach(() => {
@@ -99,7 +77,7 @@ afterEach(() => {
 })
 
 describe('RecommendationShelf', () => {
-  it('renders a product card per recommended product', async () => {
+  it('renders a product card per recommended product when enabled', async () => {
     useRecommendations.mockReturnValue({
       data: recommendationData,
       isLoading: false,
@@ -107,7 +85,7 @@ describe('RecommendationShelf', () => {
     })
 
     const { getAllByTestId, getByText } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
     )
 
     await waitFor(() => {
@@ -126,7 +104,9 @@ describe('RecommendationShelf', () => {
       error: null,
     })
 
-    render(<RecommendationShelf campaignVrn={CROSS_SELL_VRN} />)
+    render(
+      <RecommendationShelf campaignVrn={CROSS_SELL_VRN} enableRecommendations />
+    )
 
     await waitFor(() => {
       const lastArgs = useRecommendations.mock.calls.at(-1)?.[0]
@@ -146,7 +126,11 @@ describe('RecommendationShelf', () => {
     })
 
     const { getByText } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} title="Custom title" />
+      <RecommendationShelf
+        campaignVrn={CAMPAIGN_VRN}
+        enableRecommendations
+        title="Custom title"
+      />
     )
 
     await waitFor(() => {
@@ -162,6 +146,25 @@ describe('RecommendationShelf', () => {
       error: null,
     })
 
+    const { container, queryByTestId } = render(
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
+    )
+
+    await waitFor(() => {
+      const lastArgs = useRecommendations.mock.calls.at(-1)?.[0]
+      expect(lastArgs).toBeNull()
+    })
+    expect(queryByTestId('product-card')).toBeNull()
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('skips the fetch when recommendations are disabled (default)', async () => {
+    useRecommendations.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      error: null,
+    })
+
     const { container, queryByTestId } = render(
       <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
     )
@@ -182,7 +185,7 @@ describe('RecommendationShelf', () => {
     })
 
     const { container } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
     )
 
     expect(container).toBeEmptyDOMElement()
@@ -196,7 +199,7 @@ describe('RecommendationShelf', () => {
     })
 
     const { container, queryByTestId } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
     )
 
     expect(queryByTestId('product-card')).toBeNull()
@@ -211,25 +214,9 @@ describe('RecommendationShelf', () => {
     })
 
     const { getByTestId } = render(
-      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} />
+      <RecommendationShelf campaignVrn={CAMPAIGN_VRN} enableRecommendations />
     )
 
     expect(getByTestId('skeleton').getAttribute('data-loading')).toBe('true')
   })
-
-  it('skips the fetch when recommendations are disabled', async () => {
-    recommendationsFlag.enabled = false
-    useRecommendations.mockReturnValue({
-      data: undefined,
-      isLoading: false,
-      error: null,
-    })
-
-    render(<RecommendationShelf campaignVrn={CROSS_SELL_VRN} />)
-
-    await waitFor(() => {
-      const lastArgs = useRecommendations.mock.calls.at(-1)?.[0]
-      expect(lastArgs).toBeNull()
-    })
-  })
 })

package/test/sdk/analytics/hasEnabledRecommendationShelf.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+
+import { hasEnabledRecommendationShelf } from 'src/sdk/analytics/utils/hasEnabledRecommendationShelf'
+
+describe('hasEnabledRecommendationShelf', () => {
+  it('returns false for empty or unrelated page props', () => {
+    expect(hasEnabledRecommendationShelf(undefined)).toBe(false)
+    expect(hasEnabledRecommendationShelf({})).toBe(false)
+    expect(
+      hasEnabledRecommendationShelf({
+        sections: [{ name: 'ProductShelf', data: {} }],
+      })
+    ).toBe(false)
+  })
+
+  it('returns true when a page section enables recommendations', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        sections: [
+          {
+            name: 'RecommendationShelf',
+            data: { enableRecommendations: true, campaignVrn: 'vrn:x' },
+          },
+        ],
+      })
+    ).toBe(true)
+  })
+
+  it('returns true when a global section enables recommendations', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        globalSections: {
+          sections: [
+            {
+              $componentKey: 'RecommendationShelf',
+              data: { enableRecommendations: true },
+            },
+          ],
+        },
+      })
+    ).toBe(true)
+  })
+
+  it('returns true when page.sections enables recommendations', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        page: {
+          sections: [
+            {
+              name: 'RecommendationShelf',
+              data: { enableRecommendations: true },
+            },
+          ],
+        },
+      })
+    ).toBe(true)
+  })
+
+  it('returns false when the shelf is present but enableRecommendations is false', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        sections: [
+          {
+            name: 'RecommendationShelf',
+            data: { enableRecommendations: false },
+          },
+        ],
+      })
+    ).toBe(false)
+  })
+
+  it('returns true when at least one of multiple shelves enables recommendations', () => {
+    expect(
+      hasEnabledRecommendationShelf({
+        sections: [
+          {
+            name: 'RecommendationShelf',
+            data: { enableRecommendations: false },
+          },
+          {
+            name: 'RecommendationShelf',
+            data: { enableRecommendations: true },
+          },
+        ],
+      })
+    ).toBe(true)
+  })
+})

package/test/sdk/analytics/useStartRecommendationSession.test.ts

@@ -18,17 +18,50 @@ vi.mock('src/sdk/graphql/useLazyQuery', () => ({
 const getCookie = vi.hoisted(() => vi.fn())
 vi.mock('src/utils/getCookie', () => ({ getCookie }))
 
-const storeConfigMock = vi.hoisted(() => ({
-  experimental: { enableRecommendations: true },
-}))
-vi.mock('discovery.config', () => ({ default: storeConfigMock }))
-
-import { useStartRecommendationSession } from 'src/sdk/analytics/hooks/useStartRecommendationSession'
+import {
+  resetStartRecommendationSessionLock,
+  useStartRecommendationSession,
+} from 'src/sdk/analytics/hooks/useStartRecommendationSession'
+
+const enabledPageProps = {
+  sections: [
+    {
+      name: 'RecommendationShelf',
+      data: { enableRecommendations: true },
+    },
+  ],
+}
+
+const multipleEnabledShelvesPageProps = {
+  sections: [
+    {
+      name: 'RecommendationShelf',
+      data: { enableRecommendations: true, campaignVrn: 'vrn:a' },
+    },
+    {
+      name: 'RecommendationShelf',
+      data: { enableRecommendations: true, campaignVrn: 'vrn:b' },
+    },
+    {
+      name: 'ProductShelf',
+      data: {},
+    },
+  ],
+}
+
+const disabledPageProps = {
+  sections: [
+    {
+      name: 'RecommendationShelf',
+      data: { enableRecommendations: false },
+    },
+  ],
+}
 
 beforeEach(() => {
+  resetStartRecommendationSessionLock()
   useLazyQueryMock.mockReturnValue([runStartRecommendationSession, {}])
   runStartRecommendationSession.mockResolvedValue(true)
-  storeConfigMock.experimental.enableRecommendations = true
 })
 
 afterEach(() => {
@@ -36,34 +69,76 @@ afterEach(() => {
 })
 
 describe('useStartRecommendationSession', () => {
+  it('does not start a session when no RecommendationShelf is enabled in CMS', async () => {
+    getCookie.mockReturnValue(undefined)
+
+    renderHook(() => useStartRecommendationSession(disabledPageProps))
+
+    await waitFor(() => {
+      expect(runStartRecommendationSession).not.toHaveBeenCalled()
+    })
+  })
+
+  it('does not start a session when page props are missing', async () => {
+    getCookie.mockReturnValue(undefined)
+
+    renderHook(() => useStartRecommendationSession())
+
+    await waitFor(() => {
+      expect(runStartRecommendationSession).not.toHaveBeenCalled()
+    })
+  })
+
   it('does not start a session when the session cookie already exists', async () => {
     getCookie.mockReturnValue('already-started')
 
-    renderHook(() => useStartRecommendationSession())
+    renderHook(() => useStartRecommendationSession(enabledPageProps))
 
     await waitFor(() => {
       expect(runStartRecommendationSession).not.toHaveBeenCalled()
     })
   })
 
-  it('starts a session when no session cookie is present', async () => {
+  it('starts a session when CMS enableRecommendations is true and no session cookie is present', async () => {
     getCookie.mockReturnValue(undefined)
 
-    renderHook(() => useStartRecommendationSession())
+    renderHook(() => useStartRecommendationSession(enabledPageProps))
 
     await waitFor(() => {
-      expect(runStartRecommendationSession).toHaveBeenCalled()
+      expect(runStartRecommendationSession).toHaveBeenCalledTimes(1)
     })
   })
 
-  it('does not start a session when recommendations are disabled', async () => {
-    storeConfigMock.experimental.enableRecommendations = false
+  it('starts a session only once when the page has multiple enabled RecommendationShelves', async () => {
     getCookie.mockReturnValue(undefined)
 
-    renderHook(() => useStartRecommendationSession())
+    const { rerender } = renderHook(
+      ({ pageProps }) => useStartRecommendationSession(pageProps),
+      { initialProps: { pageProps: multipleEnabledShelvesPageProps } }
+    )
+
+    // Simulate Layout re-renders caused by multiple shelves updating.
+    rerender({ pageProps: multipleEnabledShelvesPageProps })
+    rerender({ pageProps: multipleEnabledShelvesPageProps })
 
     await waitFor(() => {
-      expect(runStartRecommendationSession).not.toHaveBeenCalled()
+      expect(runStartRecommendationSession).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  it('does not start a second session when the hook mounts again without a cookie', async () => {
+    getCookie.mockReturnValue(undefined)
+
+    renderHook(() => useStartRecommendationSession(enabledPageProps))
+
+    await waitFor(() => {
+      expect(runStartRecommendationSession).toHaveBeenCalledTimes(1)
+    })
+
+    renderHook(() => useStartRecommendationSession(enabledPageProps))
+
+    await waitFor(() => {
+      expect(runStartRecommendationSession).toHaveBeenCalledTimes(1)
     })
   })
 })