@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/README.md

@@ -1,6 +1,6 @@
 # storefront-next
 
-Agent skills for building Salesforce B2C Storefront Next projects — React 19 storefronts with routing, data fetching, Page Designer, authentication, i18n, extensions, and deployment to Managed Runtime.
+Agent skills for building Salesforce B2C Storefront Next projects — React 19 storefronts with routing, data fetching, SCAPI, authentication, theming, Page Designer, extensions, SEO, security, testing, and deployment to Managed Runtime.
 
 Part of the [B2C Developer Tooling](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling) marketplace.
 
@@ -24,32 +24,53 @@ For file-copy install to any supported IDE, use `b2c setup skills storefront-nex
 
 ## What's included
 
-Skills covering the full Storefront Next development lifecycle:
-
-- **`sfnext-project-setup`** — project creation, environment configuration, project structure
-- **`sfnext-routing`** — React Router 7 file-based routing with flat-routes conventions
-- **`sfnext-data-fetching`** — server-side loaders, actions, useScapiFetcher
-- **`sfnext-components`** — UI components, createPage HOC, shadcn/ui, Tailwind CSS v4
-- **`sfnext-create-component`** — design-system component authoring: layer model, CVA variants, data-slot, accessibility, Storybook coverage
-- **`sfnext-create-vertical`** — create a new brand theme / storefront variant via the brand token layer, typography, dark mode, and fixtures
-- **`sfnext-configuration`** — config.server.ts, environment variables, multi-site setup
-- **`sfnext-page-designer`** — Page Designer integration with React decorators and component registry
-- **`sfnext-extensions`** — extension system, target points, extension routes, and the base-audit decision gate (extend vs token/variant override)
-- **`sfnext-authentication`** — split-cookie SLAS architecture, auth middleware, session management
-- **`sfnext-i18n`** — internationalization with i18next, dual-instance server/client, namespaces
-- **`sfnext-state-management`** — React context, Zustand stores, basket provider
-- **`sfnext-testing`** — Vitest unit tests, Storybook stories, interaction and accessibility testing
-- **`sfnext-performance`** — bundle size limits, DynamicImage, parallel fetching, Lighthouse optimization
-- **`sfnext-scapi-management`** — manage typed SCAPI clients, discover API schemas before coding
-- **`sfnext-custom-apis`** — end-to-end custom API implementation and consumption
-- **`sfnext-deployment`** — build and deploy to Managed Runtime (MRT), cartridge deployment
-- **`sfnext-hybrid-storefronts`** — hybrid setup with SFRA/SiteGenesis, gradual migration, session bridging
+Skills covering the full Storefront Next development lifecycle. Start with **`sfnext-overview`**, which routes a task to the right skill and to the guidance that ships inside your project (`AGENTS.md`, `docs/`).
+
+**Project and delivery**
+
+- **`sfnext-overview`** — start here: task-to-skill map, in-project guidance, CLI and MCP cheat sheet
+- **`sfnext-project-setup`** — create a storefront with `sfnext create-storefront`, prerequisites, project layout, scripts
+- **`sfnext-configuration`** — `config.server.ts`, `PUBLIC__` environment variables, multi-site, URLs, domains, base path
+- **`sfnext-deployment`** — build and push to Managed Runtime, Page Designer cartridge deployment, pre-launch checks
+- **`sfnext-quality-gates`** — lint, format, typecheck, bundle-size and Lighthouse budgets, pre-PR checklist
+
+**Application architecture**
+
+- **`sfnext-routing`** — flat-routes file conventions, layouts, site-aware links and navigation
+- **`sfnext-data-fetching`** — loaders, actions, API clients, `useScapiFetcher`, streaming
+- **`sfnext-revalidation`** — `shouldRevalidate` policies and keeping data fresh after mutations
+- **`sfnext-state-management`** — basket and auth providers, external stores, URL state, optimistic UI
+- **`sfnext-performance`** — Suspense, bundle budgets, images, metrics, performance review checklist
+
+**Commerce APIs and identity**
+
+- **`sfnext-scapi`** — typed SCAPI clients, custom attributes, and calling custom APIs from your storefront
+- **`sfnext-authentication`** — SLAS session cookies, auth middleware, login flows (passwordless, social, passkeys)
+- **`sfnext-hybrid-storefronts`** — run alongside SFRA/SiteGenesis with the hybrid proxy and shared sessions
+- **`sfnext-security`** — security headers, Content Security Policy contributors, Turnstile, cookie domain
+
+**UI and content**
+
+- **`sfnext-components`** — UI primitives, composite components, variants, Storybook coverage
+- **`sfnext-theming`** — rebrand your storefront: design tokens, palette, shape, typography, assets
+- **`sfnext-page-designer`** — Page Designer decorators, component registry, regions, cartridge metadata
+- **`sfnext-extensions`** — extension targets, installing and creating extensions, the extend-vs-edit decision
+- **`sfnext-i18n`** — translations, locales, currency
+- **`sfnext-accessibility`** — accessible components, a11y lint, Storybook and end-to-end accessibility checks
+- **`sfnext-testing`** — Vitest unit and route tests, Storybook tests, end-to-end tests
+
+**Features and integrations**
+
+- **`sfnext-commerce-features`** — which flags, Business Manager preferences, cartridges, or extensions each storefront feature needs
+- **`sfnext-analytics-consent`** — analytics adapters (Einstein, Active Data, Data 360) and tracking consent
+- **`sfnext-seo`** — SEO metadata, structured data, SEO URL rules, AI answer-engine readiness
 
 See [`skills/`](./skills/) for the full list.
 
 ## Related plugins
 
-- **[`storefront-next-figma`](../storefront-next-figma)** — design-kit companion: duplicate the Figma kit for a vertical and sync brand tokens. Pairs with `sfnext-create-vertical`. Requires the Figma MCP server.
+- **[`storefront-next-figma`](../storefront-next-figma)** — design-kit companion: duplicate the Storefront Next Figma kit and keep its brand variables in sync with your theme tokens. Pairs with `sfnext-theming`. Requires the Figma MCP server.
+- **[`figma-to-sfnext-pagedesigner`](../figma-to-sfnext-pagedesigner)** — turn Figma frames into Storefront Next Page Designer components. Requires the Figma MCP server.
 
 ## License
 

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "storefront-next",
-  "version": "1.10.3",
+  "version": "1.12.0",
   "description": "Storefront Next development skills for building React 19 storefronts on Salesforce B2C Commerce.",
   "author": {
     "name": "Salesforce"
@@ -14,14 +14,17 @@
     "storefront-next",
     "react",
     "b2c-commerce",
-    "commerce-cloud"
+    "commerce-cloud",
+    "react-router",
+    "page-designer",
+    "scapi"
   ],
   "extensions": {
     "com.openai": {
       "interface": {
         "displayName": "Storefront Next",
         "shortDescription": "Build Salesforce B2C Storefront Next projects with AI assistance.",
-        "longDescription": "Skills for developing React 19 storefronts on Salesforce B2C Commerce — routing, data fetching, components, Page Designer, authentication, i18n, extensions, testing, and deployment to Managed Runtime.",
+        "longDescription": "Skills for developing React 19 storefronts on Salesforce B2C Commerce — project setup, configuration, routing, data fetching and revalidation, SCAPI clients, authentication, security, theming, components, Page Designer, extensions, i18n, SEO, analytics and consent, accessibility, testing, quality gates, and deployment to Managed Runtime.",
         "developerName": "Salesforce",
         "category": "Productivity",
         "capabilities": [
@@ -32,9 +35,9 @@
         "brandColor": "#0D9DDA",
         "websiteURL": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/",
         "defaultPrompt": [
-          "Set up a new Storefront Next project",
-          "Add a new route with data fetching to my storefront",
-          "Deploy my storefront to Managed Runtime",
+          "Create a new Storefront Next storefront",
+          "Add a route with data fetching to my storefront",
+          "Rebrand my storefront's colors and fonts",
           "Add Page Designer support to my storefront component"
         ]
       }

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-accessibility/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: sfnext-accessibility
+description: >-
+  Build and fix accessible UI in a Storefront Next storefront (WCAG 2.1 AA): jsx-a11y lint findings, missing accessible names and labels, form error association, dialog focus management, aria-live status messages, keyboard behavior, color contrast, and verifying fixes with Storybook a11y/play() tests and the e2e axe scan with its baseline. Use for "accessibility", "a11y", "WCAG", "screen reader", "aria-label", "focus trap", "axe violation", pnpm lint:a11y, pnpm a11y, a11y-baseline.json, skip-a11y, STORYBOOK_A11Y_TEST_MODE, or an accessibility audit finding to fix. Do not use for general lint/typecheck gates (use `storefront-next:sfnext-quality-gates`), writing non-accessibility tests (use `storefront-next:sfnext-testing`), or color/token design (use `storefront-next:sfnext-theming`).
+---
+
+# Storefront Next Accessibility
+
+Target: WCAG 2.1 AA. Accessibility is checked at three levels, cheapest first:
+
+| Level | Tool | Catches |
+|-------|------|---------|
+| Lint | OxLint `jsx-a11y` (`pnpm lint`, `pnpm lint:a11y`) | Missing alt/labels, invalid ARIA, non-interactive handlers, ambiguous link text |
+| Component | Storybook a11y addon (axe) and `play()` assertions | Contrast and name/role issues in a rendered state; focus, live regions, dialog behavior |
+| Page | e2e axe scan (`pnpm a11y`) against `e2e/a11y-baseline.json` | Page composition, layout, mobile vs desktop |
+
+Some things no scanner finds: focus order, meaning carried by color alone, 200%/400% zoom reflow, and what a screen reader actually announces. Those need keyboard testing, a story `play()` assertion of the DOM facts behind them, or a human with assistive technology.
+
+## Author accessibly by default
+
+1. Use the project's building blocks; they are already accessible in the general case:
+   - Radix-based primitives in `src/components/ui/` (dialog, dropdown-menu, sheet, tooltip, ...).
+   - `FormLabel`/`FormControl`/`FormMessage` from `@/components/ui/form` and the wrappers in `src/components/form-fields/` (they wire `aria-describedby` and invalid state from form context).
+   - `src/components/product-image` and `src/components/dynamic-image` (alt text), `src/components/radio-card` (grouped options), `src/components/skip-link.tsx` (first focusable element, targets `#main-content`), `src/components/announcement-banner`.
+2. Icon-only controls need a translated accessible name: `<Button aria-label={t('close')}>`. Decorative icons get `aria-hidden="true"` and must not be focusable.
+3. Every input needs a real label; errors must be programmatically associated and announced (form-field wrappers do this).
+4. Use semantic elements first (`button`, `a`, `ul`, `h1..h6`); add ARIA only to fill gaps. Keep one `h1` per page and do not skip levels.
+5. Status changes that happen without navigation (cart updates, promo applied, errors) need an `aria-live` region (`role="status"` or `role="alert"`); the message must be rendered into an existing live region or the region must exist before content changes.
+6. Dialogs and drawers: focus moves in on open, is trapped, returns to the trigger on close, `Escape` closes. Use the Radix dialog primitives rather than hand-rolling.
+7. Respect `prefers-reduced-motion` (see `src/components/fade-through-image` and `product-zoom-modal` for the pattern).
+8. Keep visible focus styles; do not remove outlines without a replacement from the theme tokens.
+9. Do not "fix" `role="list"` on a `ul`: it is deliberate (Tailwind's `list-style: none` removes list semantics in Safari + VoiceOver), and the lint config allows it.
+
+## Fix the right layer
+
+Before editing a shared primitive, check the call site.
+
+- Call-site fix (most common): the primitive is correct but the caller passed no `aria-label`, a meaningless `alt`, or bypassed `FormLabel`. Fix the caller.
+- Primitive fix: the shared component itself emits inaccessible markup. One change cascades to every usage, so keep it small and re-run the component's stories and snapshots.
+- Many findings citing one primitive usually means one call-site pattern to correct, not a broken primitive.
+
+## Reproduce, fix, confirm
+
+Do not call something fixed from reading code. Capture a failing signal first, then the same check passing afterwards.
+
+1. Name the state: default, form-error, modal-open, out-of-stock, focus-after-action, zoomed. Many violations only exist after interaction, which is why default-page scans come back clean.
+2. Reproduce:
+   - Lint rule: `pnpm lint:a11y`.
+   - Rendered axe rule: run the story with `STORYBOOK_A11Y_TEST_MODE=error` via `pnpm storybook:test --type=a11y`, or add the scenario to the e2e a11y specs.
+   - Focus/label/live-region issues: write a `play()` assertion (next section) and watch it fail.
+3. Fix at the right layer.
+4. Re-run the same check; also run the component's snapshot (`pnpm storybook:test --type=snapshot`, `--update` only after reviewing the diff) and `pnpm lint`.
+5. Never add a suppression (disabled axe rule, `oxlint-disable`, `aria-hidden`) just to turn a check green. A suppression is acceptable only when it targets a node you do not control and the reason is written next to it.
+
+## Storybook: a11y addon and play() assertions
+
+- Default addon mode is `todo` (violations are shown, not failing). `pnpm storybook:test --type=a11y` runs in error mode, so violations fail. `STORYBOOK_DISABLE_A11Y=true` turns it off.
+- Opt one story file into strict mode: spread `{ a11y: { test: 'error' } }` into `parameters` (see `src/components/checkout/storybook/checkout-strict-a11y-parameters.ts`).
+- Tag `skip-a11y` excludes a story from a11y runs. Use it rarely and comment why.
+- Assert accessible outcomes, not CSS classes:
+
+```tsx
+play: async ({ canvasElement }) => {
+    await waitForStorybookReady(canvasElement);
+    const body = within(canvasElement.ownerDocument.body); // Radix portals render into <body>
+    const dialog = body.getByRole('dialog');
+    await expect(dialog).toBeInTheDocument();
+    await expect(body.getAllByRole('textbox')[0]).toHaveFocus();
+    await expect(body.getByRole('textbox', { name: /email/i })).toBeInTheDocument(); // label association
+    await expect(body.getByRole('status')).toHaveTextContent(/saved/i);               // live region populated
+},
+```
+
+A working reference is `src/components/login/stories/otp-modal.stories.tsx`. Imports: `expect, within, userEvent` from `storybook/test`; `waitForStorybookReady` from `@storybook/test-utils`. Tag the story `interaction` so it runs under `--type=interaction`.
+
+## e2e axe scan and baseline
+
+`pnpm a11y` runs axe (WCAG 2.1 A/AA tags) over key pages at desktop and mobile viewports and compares with `e2e/a11y-baseline.json`. CI fails when critical or serious violations increase or a new critical/serious rule appears; moderate and minor regressions are logged but do not block.
+
+```bash
+pnpm a11y                   # scan and compare with baseline
+pnpm --dir e2e a11y:report  # or from e2e/: markdown + HTML report of violations
+pnpm --dir e2e a11y:update-baseline   # after fixing: ratchet the baseline down, review the diff, commit
+pnpm a11y:scan-coverage     # checks that every page route is scanned or explicitly allowlisted
+```
+
+- Never hand-edit the baseline; regenerate it.
+- New pages: add a `Scenario` in `e2e/src/specs/core/a11y/` (public, account or orders spec), then run `a11y:update-baseline`. Details: `e2e/docs/a11y.md`.
+- The dev server must be running (`pnpm dev`) or use `--mode=local` as described in `storefront-next:sfnext-testing`.
+
+## Translated text
+
+`jsx-a11y/anchor-ambiguous-text` only sees literal JSX text. A link whose text comes from `t('...')` is never checked, so review link and label copy in `src/locales/*/translations.json` for "click here"/"read more" style text, in every locale you ship. See `storefront-next:sfnext-i18n`.
+
+More checklists (states, keyboard, pages to spot check): [references/checklist.md](references/checklist.md).
+
+## Related Skills
+
+- `storefront-next:sfnext-quality-gates` - lint config and pre-PR checklist
+- `storefront-next:sfnext-testing` - story, unit and e2e test mechanics
+- `storefront-next:sfnext-components` - component and form-field conventions
+- `storefront-next:sfnext-theming` - color tokens and contrast
+- `storefront-next:sfnext-i18n` - translated labels and link text

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-accessibility/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "Focus doesn't move into the OTP dialog when it opens and screen readers don't announce the error, how do I fix and test this?", "should_trigger": true},
+  {"query": "pnpm a11y fails with a new serious color-contrast violation on the PDP in the baseline comparison, what do I do?", "should_trigger": true},
+  {"query": "Change the brand primary color token and regenerate the theme CSS", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-accessibility/references/checklist.md

@@ -0,0 +1,64 @@
+# Accessibility checklists
+
+## Classify a finding
+
+| Question | If yes |
+|----------|--------|
+| Is there a DOM fact a scanner or assertion can check (missing name, unlabeled input, empty live region, `aria-hidden` on focusable, duplicate id, empty heading, contrast)? | Automatable. Reproduce with axe (story a11y run or e2e scan) and fix. |
+| Is it about focus landing in the right place, roving arrow keys, trap/return, live region populated? | Has a DOM correlate. Assert it in a story `play()`. |
+| Is it reading order, meaning conveyed by color alone, zoom/reflow at 200% to 400%, or exactly what VoiceOver/NVDA speaks? | Manual. Test with the keyboard, browser zoom and a screen reader; record the result. Do not close it as "cannot reproduce" because a scanner is clean. |
+
+For "status message is not announced": if a live region should exist in the DOM, it is assertable; if the claim is purely about speech output, test with assistive technology.
+
+## States to exercise
+
+Scan or assert in each relevant state, not only the settled default:
+
+- default
+- form-error (submit empty or invalid)
+- modal, drawer or menu open
+- out-of-stock / unavailable variant
+- after an action (focus after add-to-cart, after closing a dialog)
+- zoomed to 400% / narrow viewport
+- mobile and desktop viewports
+- reduced motion enabled
+
+Prefer states that do not depend on live catalog data for repeatable checks; data-dependent states (out-of-stock, specific content) can differ between local and CI backends.
+
+## Keyboard pass (per page or component)
+
+- Tab order follows the visual order; nothing focusable is hidden; a visible focus indicator is always present.
+- All controls operable with Enter/Space; menus, tabs, carousels and swatch groups support arrow keys as expected.
+- `Escape` closes dialogs and popovers; focus returns to the trigger.
+- No keyboard trap outside intentional modal containment.
+- The skip link is the first Tab stop and moves focus to `#main-content`.
+
+## Forms
+
+- Each field has a visible label associated through `FormLabel` or `htmlFor`.
+- Error text is associated (`aria-describedby`) and the field is `aria-invalid`; on a failed submit, move focus to the first invalid field or an error summary (verify the behavior of the form you are editing).
+- Required state is conveyed in text, not color alone.
+- Autocomplete attributes are set for address, email and payment fields.
+
+## Images and media
+
+- Product and content images use `ProductImage`/`DynamicImage` with meaningful alt text; decorative images use empty alt.
+- Icon-only buttons have translated accessible names.
+- Carousels: labelled region, pause/controls reachable by keyboard, reduced motion respected.
+
+## Content and structure
+
+- One `h1` per page; headings in order.
+- Landmarks (`header`, `nav`, `main`, `footer`) present once each with labels where repeated.
+- Link text makes sense out of context, in every locale.
+- Lists use list markup; keep `role="list"` on styled `ul` (Safari + VoiceOver).
+
+## Where to run what
+
+| Goal | Command |
+|------|---------|
+| Lint-level a11y only | `pnpm lint:a11y` |
+| Rendered component violations | `pnpm storybook:test --type=a11y` |
+| Focus/aria behavior | `pnpm storybook:test --type=interaction` |
+| Full-page scan vs baseline | `pnpm a11y` |
+| Report with HTML snippets for tickets | `pnpm --dir e2e a11y:report` |

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-analytics-consent/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: sfnext-analytics-consent
+description: >-
+  Storefront Next analytics: engagement adapters (Einstein, Active Data, Data 360), adding a custom adapter, tracking consent gating, PageViewTracker, useAnalytics events, and first-touch attribution (dw_attribution). Use when configuring engagement.adapters in config.server.ts, writing an adapter with hasConsent, registering it in initializeEngagementAdapters, wiring the consent banner (trackingConsent, consentCategories, dw_dnt), firing trackViewProduct/trackCartItemAdd events, debugging why no analytics events are sent, or passing campaign attribution to orders. Do not use for general config loading or env vars (use `storefront-next:sfnext-configuration`), CSP/script allowlisting of third-party tags (use `storefront-next:sfnext-security`), or SEO meta/JSON-LD (use `storefront-next:sfnext-seo`).
+---
+
+# Storefront Next Analytics and Consent
+
+Events flow: component -> `useAnalytics()` -> event mediator (`@salesforce/storefront-next-runtime/events`) -> each registered engagement adapter. Every adapter checks shopper consent before sending. Read `docs/README-ADAPTER-PATTERN-GUIDE.md` and `docs/README-CONSENT-TRACKING.md` in your project for the full guides; where they disagree with the code, trust the code (paths below were verified).
+
+## Where things live
+
+| Concern | Location |
+|---|---|
+| Adapter config | `engagement.adapters.*` in `config.server.ts` |
+| Adapter types, store, `hasConsent`, `buildConsentPreferences` | `@/lib/adapters` (`src/lib/adapters/engagement/`) |
+| Registration of built-in adapters | `src/lib/adapters/engagement/register.ts` (`initializeEngagementAdapters`) |
+| Built-in adapters | `einstein.ts`, `active-data.ts`, `data360.ts` in the same folder |
+| Page view tracking | `src/analytics/page-view-tracker.tsx` (`PageViewTracker`, mounted in `src/root.tsx`) |
+| Event hooks | `@/hooks/use-analytics`, `@/hooks/use-tracking-consent` |
+| Attribution | `src/lib/attribution.ts`, `@/hooks/use-attribution`, `src/middlewares/attribution-forwarding.server.ts` |
+
+## Configure built-in adapters
+
+```ts
+// config.server.ts
+engagement: {
+  adapters: {
+    einstein: { enabled: true, consentCategory: 'analytics', host, einsteinId, realm, siteId, isProduction: false,
+                eventToggles: { view_page: true, view_product: true /* ... */ } },
+    data360:  { enabled: true, consentCategory: 'analytics', appSourceId, tenantId, siteId, webStoreId: 'sfnext', eventToggles: { /* ... */ } },
+    activeData: { enabled: true, /* see config.server.ts */ },
+  },
+  analytics: {
+    trackingConsent: { enabled: true, defaultTrackingConsent: TrackingConsent.Declined,
+                       consentCategories: ['necessary', 'analytics', 'marketing', 'personalization'] },
+    pageViewsBlocklist: [/* paths that must not emit view_page */],
+  },
+}
+```
+
+- The shipped IDs (einsteinId, realm, tenantId, ...) are sample values. Replace them with your own before go-live, or set `enabled: false`.
+- An adapter with `consentCategory: 'analytics'` sends nothing unless `'analytics'` is in `trackingConsent.consentCategories`.
+- `eventToggles` turns individual event types on or off per adapter. Data 360 ships only view/impression events enabled.
+- The `einstein` and `data360` adapter blocks, and `activeData.enabled` / `activeData.eventToggles`, are protected config paths and cannot be overridden with `PUBLIC__` env vars; edit `config.server.ts` and rebuild. Other keys follow the `PUBLIC__app__engagement__...` pattern (see `storefront-next:sfnext-configuration`).
+
+## Fire events
+
+```tsx
+import { useAnalytics } from '@/hooks/use-analytics';
+
+const { trackViewProduct, trackCartItemAdd } = useAnalytics();
+```
+
+`useAnalytics` returns `trackViewPage`, `trackViewProduct`, `trackCartItemAdd`, `trackCheckoutStart`, `trackCheckoutStep`, `trackViewSearch`, `trackViewCategory`, `trackClickProductIn{Category,Search,Recommender}`, `trackViewRecommender`, search-suggestion and wishlist trackers. On the server these are no-ops, so call them from effects or event handlers. Check the hook source for exact argument shapes before calling.
+
+## Consent
+
+Consent is read from the auth session (`dw_dnt` cookie) by `useTrackingConsent()`, converted to a `ConsentPreferences` array by `buildConsentPreferences(trackingConsent, consentCategories, isTrackingConsentEnabled)`, and passed to every adapter. While consent is undetermined or declined, no events are sent.
+
+```tsx
+import { useTrackingConsent } from '@/hooks/use-tracking-consent';
+import { TrackingConsent } from '@/types/tracking-consent';
+
+const { shouldShowBanner, setTrackingConsent } = useTrackingConsent();
+setTrackingConsent(TrackingConsent.Accepted);
+```
+
+Granular per-category consent (for example from a CMP) means replacing the binary banner logic that feeds `buildConsentPreferences`; adapters already gate per `consentCategory`.
+
+## Add a custom adapter
+
+See [references/CUSTOM-ADAPTER.md](references/CUSTOM-ADAPTER.md). In short: implement `createMyAdapter(config): EngagementAdapter` using `hasConsent`, register it with `addAdapter('my-adapter', ...)` inside `initializeEngagementAdapters`, and add `engagement.adapters.myAdapter` config (the config type allows extra keys).
+
+## Attribution
+
+A first-touch `dw_attribution` cookie captures allow-listed landing/referrer params (see `LANDING_PARAM_ALLOWLIST` in `src/lib/attribution.ts`). `attributionForwardingMiddleware` forwards it on order creation. Add a parameter by extending the allowlist; cookie size is capped (`MAX_ATTRIBUTION_COOKIE_VALUE_LENGTH`).
+
+## Troubleshooting
+
+- No events at all: consent not accepted, `'analytics'` missing from `consentCategories`, adapter `enabled: false`, or the path is in `pageViewsBlocklist`. Startup logs a warning when consent categories are empty.
+- Custom adapter never fires: it was not registered in `initializeEngagementAdapters`, or `eventToggles[eventType]` is falsy.
+- Third-party script or beacon blocked: CSP, see `storefront-next:sfnext-security`.
+
+## Related Skills
+
+- `storefront-next:sfnext-configuration` - config.server.ts, env overrides
+- `storefront-next:sfnext-security` - CSP for analytics endpoints
+- `storefront-next:sfnext-authentication` - session/cookies behind `dw_dnt`
+- `storefront-next:sfnext-testing` - testing adapters and hooks
+- `storefront-next:sfnext-seo` - page metadata and structured data

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-analytics-consent/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "Add a custom analytics adapter that sends view_product events to our own endpoint, but only when the shopper accepted marketing consent", "should_trigger": true},
+  {"query": "Einstein events are not firing after I enabled the consent banner - how do I debug engagement.adapters and consentCategories?", "should_trigger": true},
+  {"query": "Add a Content-Security-Policy nonce so my third-party analytics script is allowed to load", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-analytics-consent/references/CUSTOM-ADAPTER.md

@@ -0,0 +1,49 @@
+# Writing a custom engagement adapter
+
+Verify the types in `src/lib/adapters/engagement/types.ts` in your project first.
+
+## 1. Implement
+
+```ts
+// src/lib/adapters/engagement/my-adapter.ts
+import { hasConsent, type EngagementAdapter, type EngagementAdapterConfig } from '@/lib/adapters';
+import type { AnalyticsEvent, ConsentPreferences, EventSiteInfo } from '@salesforce/storefront-next-runtime/events';
+
+export function createMyAdapter(config: EngagementAdapterConfig): EngagementAdapter {
+  return {
+    name: 'my-adapter',
+    sendEvent: async (event: AnalyticsEvent, siteInfo?: EventSiteInfo, consentPreferences?: ConsentPreferences) => {
+      if (!hasConsent(config.consentCategory, consentPreferences)) return;
+      if (!config.eventToggles[event.eventType]) return;
+      navigator.sendBeacon('https://example.com/collect', JSON.stringify({ event, siteInfo }));
+    },
+  };
+}
+```
+
+`hasConsent(category, prefs)` is in `src/lib/adapters/engagement/utils.ts`; read it for the behavior when `category` is undefined.
+
+## 2. Register
+
+In `src/lib/adapters/engagement/register.ts`, inside `initializeEngagementAdapters(appConfig)`:
+
+```ts
+const mine = appConfig?.engagement?.adapters?.myAdapter;
+if (mine?.enabled) {
+  addAdapter('my-adapter', createMyAdapter({ consentCategory: mine.consentCategory, eventToggles: mine.eventToggles || {}, ...mine }));
+}
+```
+
+Follow the try/catch and logger pattern used for the built-in adapters.
+
+## 3. Configure
+
+Add `engagement.adapters.myAdapter: { enabled: true, consentCategory: 'marketing', eventToggles: { view_page: true } }` in `config.server.ts`. Add `'marketing'` (or your category) to `trackingConsent.consentCategories`.
+
+## 4. Allow the endpoint in CSP
+
+Beacons to a new host need `connect-src` (and script hosts need `script-src`). See `storefront-next:sfnext-security`.
+
+## 5. Test
+
+Unit-test the adapter with and without consent (see the `*.test.ts` files beside the built-in adapters for the pattern).