@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

package/content/guidance/storefront-next/sfnext-security/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: sfnext-security
+description: >-
+  Configure Storefront Next security response headers, Content Security Policy (CSP), CSP contributors, Cloudflare Turnstile bot protection, and the shared cookie domain. Use for "Refused to load the script/connect/image" CSP violations, adding a third-party origin, app.security.headers, defaultCspDirectives, csp reportOnly rollout, writing a CSP contributor under src/middlewares/csp-contributors, HSTS or Permissions-Policy, Turnstile widget or enforceTurnstile, TURNSTILE_SECRET_KEYS, log-only rollout, or app.cookies.domain across subdomains. Do not use for auth tokens, cookie names or login flows (use `storefront-next:sfnext-authentication`), SFRA proxy routing (use `storefront-next:sfnext-hybrid-storefronts`), or consent banners and tracking (use `storefront-next:sfnext-analytics-consent`).
+---
+
+# Storefront Next Security
+
+Security is configured under `app.security` in `config.server.ts`: `security.headers` for response headers and CSP, `security.turnstile` for bot protection. Cookie sharing is `app.cookies.domain`. Your project ships deeper docs: `docs/README-SECURITY-HEADERS.md`, `docs/README-TURNSTILE.md`, `docs/README-COOKIE-DOMAIN.md`. Read them for details; this skill is the task guide.
+
+## Default headers
+
+Every storefront gets these with no opt-in, from `@salesforce/storefront-next-runtime/security` via the `securityHeadersMiddleware` in `src/middlewares/security-headers.server.ts`:
+
+| Header | Default |
+|---|---|
+| `Content-Security-Policy` | Strict, nonce-based (no `'unsafe-inline'` scripts, no `'unsafe-eval'`) |
+| `Strict-Transport-Security` | Sent on Managed Runtime only, suppressed locally |
+| `X-Frame-Options` | `SAMEORIGIN` |
+| `X-Content-Type-Options` | `nosniff` |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` |
+
+The CSP directive table (which origins `script-src`, `connect-src`, `img-src`, and `frame-src` allow by default) is in `docs/README-SECURITY-HEADERS.md`. The per-request nonce is read in `root.tsx` and must be forwarded to any inline `<script>` you render (for example the JSON-LD component takes a `nonce` prop).
+
+## Allow a new third-party origin
+
+The violation message names the directive to extend ("Refused to connect to ..." means `connect-src`). Spread the defaults, because **each directive you set fully replaces the default**:
+
+```ts
+// config.server.ts
+import { defaultCspDirectives } from '@salesforce/storefront-next-runtime/security';
+
+security: {
+    headers: {
+        csp: {
+            directives: {
+                ...defaultCspDirectives,
+                'script-src': [...defaultCspDirectives['script-src']!, 'https://cdn.example.com'],
+                'connect-src': [...defaultCspDirectives['connect-src']!, 'https://api.example.com'],
+            },
+        },
+    },
+},
+```
+
+Use exact origins, not wildcards. Do not load third-party scripts synchronously in the document head; load them after interaction or idle (see `storefront-next:sfnext-performance`).
+
+Env-var override is awkward for directives (names contain hyphens, and a JSON override replaces the whole map). Use `config.server.ts` for directives and env vars for toggles:
+
+```bash
+PUBLIC__app__security__headers__csp__reportOnly=true
+PUBLIC__app__security__headers__hsts=false
+```
+
+## Roll out or relax safely
+
+- Migrating or adding many origins: set `csp: { reportOnly: true }`, watch DevTools violations, extend the directives, then remove `reportOnly`. A startup warning is logged while it is on.
+- Disable one header with `hsts: false` or `permissionsPolicy: false`. `headers: { enabled: false }` disables everything; use it for debugging only. A startup warning is logged whenever any header is disabled.
+
+## CSP contributors
+
+A contributor lets a feature add its own exact origins to the CSP at boot instead of hand-editing directives. Shipped examples in `src/middlewares/csp-contributors/`: `cimulate.ts` (Shopper Agent widget, active when enabled in config), `data360.ts` (`connect-src` for the tenant ingestion host), and `openstreetmap.ts` (a deliberate no-op; replace it to permit map tiles).
+
+Shape (see `data360.ts` for the smallest real one):
+
+```ts
+import type { CspContributor, CspContribution } from '@salesforce/storefront-next-runtime/security';
+import { toCspOrigin } from './to-csp-origin.js';
+
+export function createMyFeatureCspContributor(cfg: { enabled?: boolean; apiUrl?: string } | undefined): CspContributor {
+    const origin = cfg?.apiUrl ? toCspOrigin(cfg.apiUrl) : null;
+    return {
+        id: 'my-feature',
+        isActive: () => cfg?.enabled === true && origin !== null,
+        contribute: (): CspContribution => (origin ? { 'connect-src': [origin] } : {}),
+    };
+}
+```
+
+Then add it to the `contributors` array in `src/middlewares/security-headers.server.ts`. Rules:
+
+- Derive origins from config you already have; `toCspOrigin` returns `null` for unsafe values.
+- The runtime validates contributors at boot: https only, no wildcards, no credentials, no whitespace.
+- Contribute only while the feature is active, so disabled features never widen the policy.
+- Add a colocated `*.test.ts` like the shipped ones.
+
+Use a contributor for a feature toggled by config; use the `defaultCspDirectives` spread for one-off origins.
+
+## Turnstile bot protection
+
+Cloudflare Turnstile guards passwordless email, checkout registration, and order lookup. It is **fail-open** on Cloudflare outages (so a Turnstile incident never blocks checkout) and fail-closed on real bot signals (forged, replayed, or missing tokens).
+
+Config (`config.server.ts`, overridable with `PUBLIC__` env vars): `security.turnstile.enabled`, `mode` (`managed`, `non-interactive`, `invisible`), `sites` (per-site site keys), and `verification.mode` (`enforce`, `log-only`, `disabled`).
+
+| Variable | Purpose |
+|---|---|
+| `TURNSTILE_SECRET_KEYS` | JSON map of site key to secret key. Server-only. Required for `enforce` and `log-only` |
+| `PUBLIC__app__security__turnstile__enabled` | Master switch; when false the widget never renders |
+| `PUBLIC__app__security__turnstile__sites` | JSON per-site keys |
+| `PUBLIC__app__security__turnstile__verification__mode` | `enforce`, `log-only`, `disabled` |
+
+Rollout: deploy with `verification.mode` set to `log-only`, read the logs for `would_block`, then switch to `enforce`. Shoppers start without a `cc-tv_<siteId>` attestation cookie after the switch, which is expected.
+
+Add protection to a new server action by rendering `TurnstileWidget` (`src/components/security/turnstile-widget.tsx`) in the form and calling `enforceTurnstile` (`src/lib/turnstile/enforce.server.ts`) in the action before doing work. Pass `request`, `config`, `turnstileToken`, `logger`, `actionName`, `email`, and `turnstileCookieName`; set the `cc-tv` cookie from the returned `cookieValue` when it is non-null. Copy an existing caller such as `src/routes/action.authorize-passwordless-email.ts`. Cloudflare test keys and a manual test matrix: [references/TURNSTILE.md](references/TURNSTILE.md).
+
+## Cookie domain
+
+Cookies are host-only by default. To share them across subdomains or with SFRA, set `app.cookies.domain` (or `commerce.sites[].cookies.domain` per site; env `PUBLIC__app__cookies__domain=.example.com`) **and** match Business Manager: Site Preferences, Hybrid Auth Settings, cookie-domain level `0` for host-only, `2` for the first-level parent domain. Level `1` is rejected. A mismatch silently breaks sessions. Full checklist: [references/COOKIE-DOMAIN.md](references/COOKIE-DOMAIN.md).
+
+## Pitfalls
+
+| Symptom | Cause / fix |
+|---|---|
+| Added origin to `script-src` and other scripts broke | You replaced the directive. Spread `defaultCspDirectives['script-src']` first |
+| Inline script blocked | Missing `nonce`. Read it from root loader data and pass it on |
+| CSS/JS fail on local Safari after enabling your own `upgrade-insecure-requests` | The default suppresses it locally for a reason; keep the default |
+| Login does not stick after setting `cookies.domain` | Domain is not a parent of the serving host, or Business Manager level mismatches |
+| Turnstile widget never appears | Expected when Cloudflare says no challenge is needed (`interaction-only`); check network tab and `cc-tv_<siteId>` |
+| Everything blocked in Turnstile tests | Secret keys missing in `TURNSTILE_SECRET_KEYS` for the configured site key |
+
+## Related Skills
+
+- `storefront-next:sfnext-authentication` - cookies, sessions, login flows that Turnstile protects
+- `storefront-next:sfnext-hybrid-storefronts` - SFRA proxy and `dwsid` session bridge
+- `storefront-next:sfnext-configuration` - `config.server.ts` and `PUBLIC__` overrides
+- `storefront-next:sfnext-performance` - loading third-party scripts safely
+- `storefront-next:sfnext-analytics-consent` - tracking consent and analytics adapters
+- `storefront-next:sfnext-deployment` - Managed Runtime environment variables

package/content/guidance/storefront-next/sfnext-security/references/COOKIE-DOMAIN.md

@@ -0,0 +1,39 @@
+# Cookie domain reference
+
+Full guide: `docs/README-COOKIE-DOMAIN.md` in your project.
+
+## Resolution order
+
+1. `commerce.sites[].cookies.domain` (per site)
+2. `app.cookies.domain` (global; env `PUBLIC__app__cookies__domain`)
+3. Unset: host-only cookies
+
+The domain is applied to every cookie the storefront writes (auth, session, site, locale, currency). It must be a parent of the serving host or the browser silently drops the cookies. A leading dot is optional.
+
+## Business Manager match
+
+Business Manager, Merchant Tools, Site Preferences, Hybrid Auth Settings:
+
+| Storefront `cookies.domain` | BM level | Result |
+|---|---|---|
+| unset | 0 | OK, host-only everywhere |
+| `.example.com` | 2 | OK, shared across subdomains |
+| `.example.com` | 0 | Broken cross-subdomain session |
+| unset | 2 | Duplicate host-only vs domain-scoped cookies |
+
+Level 1 is rejected. Salesforce-managed sites need a request to the team managing Business Manager.
+
+## Verify
+
+```bash
+curl -sI https://www.example.com/ | grep -i '^set-cookie:'
+```
+
+- Every cookie carries the same `Domain=`.
+- No same-name duplicates (one host-only, one domain-scoped).
+- A session persists between `www.` and `account.` hosts; in hybrid mode `dwsid` is shared with SFRA pages.
+- Logout clears the domain-scoped cookies.
+
+## Rollout
+
+Changing the domain on a live site leaves old cookies next to new ones until they expire, and a host-only cookie shadows a domain-scoped one of the same name. Expect transient session glitches; roll out in a low-traffic window. A per-site empty string inherits the global domain; it cannot force host-only.

package/content/guidance/storefront-next/sfnext-security/references/TURNSTILE.md

@@ -0,0 +1,43 @@
+# Turnstile reference
+
+Deep design lives in `docs/README-TURNSTILE.md` in your project. Quick facts:
+
+## Modules
+
+- `src/components/security/turnstile-widget.tsx` - client widget (`siteKey`, `onSuccess`, `onError`, `onExpire`, `onTimeout`, `onBypass`). Mounts with `appearance: 'interaction-only'`, so it is hidden unless Cloudflare needs shopper input.
+- `src/lib/turnstile/enforce.server.ts` - `enforceTurnstile` and `resolveVerificationMode`.
+- `src/lib/turnstile/constants.ts` - cookie base name `cc-tv` (written as `cc-tv_<siteId>`, 30 minute TTL).
+
+## Enforcement points
+
+`action.authorize-passwordless-email`, `action.initiate-checkout-registration`, the order-lookup request-code action, and the passwordless submit and OTP resend on the login route. The OTP verification actions rely on the earlier challenge plus the code itself.
+
+## Fail-open vs fail-closed
+
+Open (request allowed, logged at warn): siteverify network failure or 5xx, `internal-error`, sustained elevated failure rate, CDN probe failure, client script timeout. Closed: `invalid-input-response`, `timeout-or-duplicate`, missing token while Cloudflare looks healthy, origin mismatch, misconfigured site key.
+
+## Verification mode
+
+| Value | Behavior |
+|---|---|
+| `enforce` | Blocks failures |
+| `log-only` | Runs full verification, only logs `would_block`; no shopper blocked, no `cc-tv` cookie issued |
+| `disabled` | Skips verification |
+
+`TURNSTILE_VERIFICATION_ENABLED` is deprecated; use `PUBLIC__app__security__turnstile__verification__mode`. `TURNSTILE_CDN_PROBE_URL` overrides the health probe URL for tests.
+
+## Cloudflare test keys (local development)
+
+| Site key | Secret key | Behavior |
+|---|---|---|
+| `1x00000000000000000000AA` | `1x0000000000000000000000000000000AA` | Always passes, silent |
+| `2x00000000000000000000AB` | `2x0000000000000000000000000000000AA` | Always blocks, silent |
+| `3x00000000000000000000FF` | `1x0000000000000000000000000000000AA` | Forces an interactive challenge (only visible widget) |
+
+Set the site key in `security.turnstile.sites` and `TURNSTILE_SECRET_KEYS` to a JSON map of site key to secret key. The passwordless login form only renders when the `emailVerificationEnabled` site preference is on (Business Manager, Storefront Login Preferences); see `docs/README-TURNSTILE.md` for seeding it locally.
+
+## Manual checks
+
+- Interactive key `3x...FF` with a passing secret: widget appears, then the OTP modal opens.
+- Always-block key: no widget, a generic "We couldn't verify your information" alert, no OTP modal.
+- Block `challenges.cloudflare.com` locally: no widget, flow continues (graceful degradation).

package/content/guidance/storefront-next/sfnext-seo/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: sfnext-seo
+description: >-
+  Storefront Next SEO and AEO/GEO: the SeoMeta component (title, description, noIndex, Open Graph, X cards), JsonLd structured data, canonical URLs and the query-parameter allowlist, hreflang, configurable product/category URLs via url.seoRoutes, semantic URL builders (createProductUrl, createCategoryUrl, useSeoUrlContext), redirectToCanonicalPath, crawler rendering and pagination, and how multi-domain and base path affect generated URLs. Use when adding meta tags or JSON-LD to a route, enabling or changing seoRoutes, fixing duplicate or wrong canonical or og:url URLs, or when a build fails for a missing site in seoRoutes. Do not use for route file naming (use `storefront-next:sfnext-routing`), site/locale config in general (use `storefront-next:sfnext-configuration`), or translations (use `storefront-next:sfnext-i18n`).
+---
+
+# Storefront Next SEO
+
+In-project references: `docs/README-SEO.md`, `docs/README-AEO-GEO.md`, `docs/README-MULTI-SITE.md` (URL Config), `docs/README-MULTI-DOMAIN.md`, `docs/README-BASE-PATH.md`, `docs/migrations/seo-url-rules/README.md`. Read them for depth; this skill is the task map.
+
+## Page metadata: SeoMeta
+
+```tsx
+import { SeoMeta } from '@/components/seo-meta';
+
+<SeoMeta title={t('meta.title', { defaultValue: 'My Page' })} description={t('meta.description', { defaultValue: '...' })} />
+<SeoMeta title="Checkout" noIndex />            {/* private/transactional pages */}
+<SeoMeta rawTitle title="Store Name" />         {/* no " | Site Name" suffix */}
+<SeoMeta title={name} openGraph={{ type: 'product', url: pageUrl, image }} />
+```
+
+Props (verified in `src/components/seo-meta/index.tsx`): `title`, `rawTitle`, `description`, `noIndex`, `siteName`, `twitter`, `openGraph`. Open Graph input auto-derives X card tags unless `twitter` is set. Use `noIndex` for cart, checkout, account, and other non-public pages. Root-level canonical and hreflang descriptors come from `src/utils/seo.ts` and `src/utils/canonical-url.ts`; routes do not add them.
+
+## Structured data: JsonLd
+
+```tsx
+import { JsonLd } from '@/components/json-ld';
+
+<JsonLd data={productSchema} id="product-schema" nonce={nonce} />
+```
+
+Pass the CSP nonce so the inline script is allowed. Builders live in `src/utils/product-schema.ts`, `category-schema.ts`, `schema-url.ts`. PDP emits `Product`; PLP emits `CollectionPage` + `ItemList` (see `docs/README-AEO-GEO.md`).
+
+## One URL everywhere
+
+Canonical `<link>`, `og:url` and JSON-LD `url` must agree. In loaders:
+
+```ts
+import { buildSeoPageUrl } from '@/lib/seo/page-url.server';
+import { redirectToCanonicalPath } from '@/lib/seo/canonical-redirect.server';
+
+redirectToCanonicalPath(requestUrl);                 // 301 for trailing slash
+const pageUrl = buildSeoPageUrl(context, requestUrl); // origin + canonical path/query
+```
+
+Only allowlisted query params survive in canonicals (`CONTENT_PARAMS` in `src/utils/canonical-url.ts`: `q`, `offset`, `sort`, `refine`, `pid` by default). Add a param only if it changes main page content, and add a test next to `canonical-url.test.ts`.
+
+## Configurable URLs: url.seoRoutes
+
+```ts
+// config.server.ts
+url: {
+  prefix: '/:siteId/:localeId',
+  seoRoutes: {
+    RefArchGlobal: { product: { prefix: 'p' }, category: { prefix: 'c', mode: 'id-suffix' } },
+  },
+}
+```
+
+Key rules (full playbook in [references/SEO-ROUTES.md](references/SEO-ROUTES.md)):
+
+- Build-time: changing `seoRoutes` requires a rebuild and redeploy (restart the dev server locally).
+- Every active site needs an entry, or URL generation throws / the build fails.
+- Business Manager URL settings are the source of truth; `seoRoutes` is a manual copy that must be kept in sync.
+- Do not rename route files. Routes are already generic; the config maps prefixes.
+- Build links with the semantic builders, never hardcoded `/product/...` strings:
+
+```tsx
+import { createProductUrl, createCategoryUrl } from '@/route-paths';
+import { useSeoUrlContext } from '@/hooks/use-seo-url-context';
+
+const ctx = useSeoUrlContext();
+<Link to={createProductUrl({ productId, slug }, ctx)} />
+```
+
+`seoFallback.sites` in config supplies per-site fallback behavior when a SEO URL cannot be resolved; see `docs/README-MULTI-SITE.md`.
+
+## Multi-domain and base path
+
+- Origin for canonicals comes from `getAppOrigin` (honors forwarded host, falls back to `EXTERNAL_DOMAIN_NAME`). Each custom domain must be attached to the Managed Runtime environment. See [references/MULTI-DOMAIN-BASE-PATH.md](references/MULTI-DOMAIN-BASE-PATH.md).
+- Mapping domains to sites uses an `X-Site-Id` header set by your CDN.
+- A base path (`MRT_ENV_BASE_PATH`, set from the push config) prefixes asset and route URLs; use `getBasePath()` rather than hardcoding.
+
+## Crawlers
+
+Crawlers receive full HTML rendering; category pages stay crawlable through a `?page=N` parameter with rel prev/next links, while the canonical stays the base category URL. Verify with `curl` and a crawler user agent. Check `docs/README-SEO.md` "Crawler Rendering and Pagination" before changing streaming behavior.
+
+## Related Skills
+
+- `storefront-next:sfnext-routing` - route modules and URL patterns
+- `storefront-next:sfnext-configuration` - config.server.ts and env overrides
+- `storefront-next:sfnext-i18n` - locales, hreflang inputs
+- `storefront-next:sfnext-hybrid-storefronts` - URLs owned by another storefront
+- `storefront-next:sfnext-security` - CSP nonce for JSON-LD
+- `storefront-next:sfnext-performance` - streaming vs crawler rendering

package/content/guidance/storefront-next/sfnext-seo/references/MULTI-DOMAIN-BASE-PATH.md

@@ -0,0 +1,17 @@
+# Multi-domain and base path effects on URLs
+
+In-project docs: `docs/README-MULTI-DOMAIN.md`, `docs/README-BASE-PATH.md`, `docs/README-MULTI-SITE.md`.
+
+## Multiple domains, one environment
+
+- Attach every domain to the Managed Runtime environment (custom domains in the MRT project; see `b2c-cli:b2c-mrt`).
+- The request host is read from the forwarded host header; `getAppOrigin` uses it for canonical, hreflang, and og URLs. `EXTERNAL_DOMAIN_NAME` is a fallback only.
+- To choose the Commerce site per domain, have the CDN send an `X-Site-Id` header (for example `site-a.shop.com` -> `RefArch`).
+- Only trust forwarded host behind your CDN; the doc has a section on trusting the forwarded host.
+- Images on custom domains need `realmHostMappings`; cookies are host-only by default (see `docs/README-COOKIE-DOMAIN.md`).
+
+## Base path
+
+- `MRT_ENV_BASE_PATH` is set by Managed Runtime from the push configuration (`ssrParameters.envBasePath`).
+- Server code reads `process.env.MRT_ENV_BASE_PATH`; client code derives it from the bundle path. Use `getBasePath()` (defined in your project's `src/lib/utils.ts`) when building URLs by hand.
+- Canonical URLs must include the base path; use `buildSeoPageUrl` instead of concatenating strings.

package/content/guidance/storefront-next/sfnext-seo/references/SEO-ROUTES.md

@@ -0,0 +1,31 @@
+# Adopting url.seoRoutes
+
+Source: `docs/migrations/seo-url-rules/README.md` and `docs/README-MULTI-SITE.md` (URL Config) in your project. Trust the code if they differ; verify `apply-seo-url-config` behavior in `@salesforce/storefront-next-dev`.
+
+## What it changes
+
+Without `seoRoutes` the storefront serves the built-in `/product/{id}` and `/category/{id}` grammar. With it, each site gets its own product and category prefix (for example `/p/{slug}/{id}`), matching Business Manager URL settings.
+
+## Checklist before enabling
+
+1. Runtime and dev packages are on a release that supports `seoRoutes` (see `docs/COMPATIBILITY.md`).
+2. Every active site has an entry in `url.seoRoutes`; a missing site fails.
+3. Decide the category mode per site: `id-suffix` (slug plus trailing category id) or slug-path (pure slug hierarchy).
+4. Protect routes that must not be captured by a product/category prefix with `protectedPaths` (build-time option described in the URL Config section).
+5. Leaf routes vs segments: check how the build validates overlapping prefixes.
+6. Keep Business Manager URL settings identical; there is no automatic sync.
+
+## Avoid breaking indexed URLs
+
+- Keep old URL shapes redirecting to the new canonical ones; `redirectToCanonicalPath` only normalizes trailing slashes, so test old `/product/{id}` URLs explicitly.
+- Audit hardcoded links; replace them with `createProductUrl` / `createCategoryUrl` and `useSeoUrlContext()`.
+- Legacy category paths can be converted with `createCategoryUrlFromLegacyPath` in `@/route-paths`.
+- Deploy, then crawl canonical, hreflang, and JSON-LD URLs for consistency.
+
+## Hybrid deployments
+
+If part of the catalog is served by another storefront, the storefront only owns the URLs routed to it; see `storefront-next:sfnext-hybrid-storefronts` and `docs/README-HYBRID-PROXY.md`.
+
+## Verifying
+
+Run `pnpm typecheck && pnpm test`, then request a product and category URL for each site and check the canonical `<link>`.

package/content/guidance/storefront-next/sfnext-state-management/SKILL.md

@@ -1,123 +1,114 @@
 ---
 name: sfnext-state-management
-description: Manage client-side state in Storefront Next using React context providers and feature-level Zustand stores. Use when handling basket/auth UI state, creating extension stores (for example store locator), or syncing client-visible state after server mutations. NOT for server-side data loading — see sfnext-data-fetching for loader patterns.
+description: >-
+  Choose the right state mechanism in a Storefront Next project: loader and action data, useRouteLoaderData, URL state with useSearchParams, cookies and sessions, optimistic UI (fetcher.formData, useNavigation, useOptimistic), React context providers (BasketProvider, AuthProvider, wishlist, product-context), and small useSyncExternalStore stores such as the mini-cart store. Use for "where should this state live", "useBasket", "useAuth", "share state between components", "optimistic add to cart", "global client state", "hydration mismatch from a store", or "do I need Zustand". Do not use for fetching or mutating data (use `storefront-next:sfnext-data-fetching`), controlling loader re-runs (use `storefront-next:sfnext-revalidation`), or login flows and sessions (use `storefront-next:sfnext-authentication`).
 ---
 
-# State Management Skill
+# Storefront Next State Management
 
-This skill covers client-side state management in Storefront Next with server-first data loading.
+Server state lives in loaders and actions. Client state is small and local. There is no global client store library in the template (Zustand was removed): use the tools below in this order. `docs/README-STATE.md` and `docs/README-DATA.md` in your project cover each in depth.
 
-## Overview
+## Decision table
 
-Storefront Next keeps business data on the server (`loader`/`action`) and uses client state for UX continuity. In practice, app-wide state is commonly exposed through providers (for example auth/basket), while complex extension-specific state can use Zustand.
+| State | Use |
+|---|---|
+| Data from SCAPI | `loader` + `loaderData`; `action` for writes |
+| Another route's loader data | `useRouteLoaderData('routes/_app')` (route id = file path without extension) |
+| Filters, sort, pagination, tab | URL: `useSearchParams` / `useParams` (shareable, SSR-friendly) |
+| Must survive requests, read by server | cookies (`createCookie` from `@/lib/cookie-utils.server`) or session helpers |
+| Pending or optimistic result | `fetcher.formData`, `useNavigation`, `useOptimistic` |
+| Form fields, toggles, open/close in one component | `useState` / `useReducer` |
+| Shared by a subtree | React context with a provider at the owning layout |
+| Shared app-wide and read outside React, or high-frequency | module-level `useSyncExternalStore` store |
+| Request-scoped server values (site, auth, basket) | router `context` (middleware), read with `context.get(...)` |
 
-| State Type            | Mechanism                      | Example                                                |
-| --------------------- | ------------------------------ | ------------------------------------------------------ |
-| Server data           | React Router `loader`          | Product details, category listings                     |
-| App-wide client state | React context providers        | Session display state, basket snapshot/hydration state |
-| Feature client state  | Zustand store                  | Store locator modal/search state                       |
-| Mutations             | React Router `action` (server) | Add to cart, update profile                            |
+Prefer the earliest row that works. Never copy loader data into `useState` to "cache" it.
 
-## Zustand Store Pattern (Feature-Level)
+## Existing providers and stores
 
-```typescript
-// src/extensions/store-locator/stores/store-locator-store.ts
-import {createStore} from 'zustand/vanilla';
+| Need | API |
+|---|---|
+| Basket | `BasketProvider` in `src/providers/basket.tsx`: `useBasket({ autoLoad })`, `useBasketSnapshot`, `useBasketHydrated`, `useBasketError`, `useBasketUpdater`, `useBasketReset`, `useBasketLoader`, `useBasketReconcile`; `BasketCookieReconciler` syncs the cookie |
+| Session info | `useAuth()` from `@/providers/auth` |
+| Product / variant selection | `@/providers/product-context`, `@/providers/product-view` |
+| Image widths | `DynamicImageProvider` (`@/providers/dynamic-image`) |
+| Wishlist | `src/providers/wishlist.ts` (module-level store) |
+| Mini-cart open state | `useMiniCartStore`, `setMiniCartOpen` in `src/hooks/mini-cart-store.ts` |
+| Cart toast | `src/hooks/cart-mutation-toast-store.ts` |
+| Shopper context | `useShopperContext` (`@/hooks/use-shopper-context`) |
 
-type StoreLocatorState = {
-  isOpen: boolean;
-  mode: 'input' | 'device';
-  selectedStoreInfo: SelectedStoreInfo | null;
-};
+The basket is loaded through `useScapiFetcher('shopperBasketsV2', 'getBasket')` and is updated from action results via `updateBasketResource` (server side, `@/middlewares/basket.server`), so after a basket action components simply re-render from `useBasket()`. The `__sfdc_basket` cookie carries the basket id; `__sfdc_usertype` is the user-type hint. Do not read these directly in components; use the hooks. Server reads: `getBasket`, `getBasketSnapshot`, `ensureBasketId`, `destroyBasket`, and `getAuth`, `updateAuth`, `destroyAuth` from `@/middlewares/auth.server`.
 
-type StoreLocatorActions = {
-  open: () => void;
-  close: () => void;
-  setSelectedStoreInfo: (info: SelectedStoreInfo) => void;
-};
+## Optimistic UI
 
-type StoreLocatorStore = StoreLocatorState & StoreLocatorActions;
-
-export const createStoreLocatorStore = (init?: Partial<StoreLocatorState>) => {
-  return createStore<StoreLocatorStore>()((set) => ({
-    isOpen: false,
-    mode: 'input',
-    selectedStoreInfo: init?.selectedStoreInfo ?? null,
-    open: () => set({isOpen: true}),
-    close: () => set({isOpen: false}),
-    setSelectedStoreInfo: (selectedStoreInfo) => set({selectedStoreInfo}),
-  }));
-};
+```tsx
+const fetcher = useFetcher<typeof action>();
+const removing = fetcher.formData?.get('itemId') === item.itemId;
+return <li hidden={removing}>...</li>;
 ```
 
-## Context Integration
+Use `useOptimistic` for values the server will confirm, and `useNavigation` for URL-driven pending states. Roll back by reading the confirmed `loaderData`/basket value; never hand-maintain a parallel copy.
 
-Expose app-level state to components via providers/hooks:
+## A small external store
 
-```typescript
-import { useBasket, useBasketSnapshot } from '@/providers/basket';
+Use when state is global, changes often, or must be set outside React. Follow `src/hooks/mini-cart-store.ts`:
 
-// In components
-function CartIcon() {
-    const basket = useBasket();
-    const snapshot = useBasketSnapshot();
+```ts
+import { useSyncExternalStore } from 'react';
 
-    const itemCount =
-        basket?.productItems?.length ??
-        snapshot?.uniqueProductCount ??
-        0;
+interface State { open: boolean }
+let state: State = { open: false };
+const SERVER_STATE: State = Object.freeze({ open: false });
+const listeners = new Set<() => void>();
 
-    return <Badge count={itemCount} />;
+const subscribe = (l: () => void) => { listeners.add(l); return () => void listeners.delete(l); };
+export const setOpen = (open: boolean) => {
+    if (open === state.open) return;         // skip no-op writes
+    state = { ...state, open };
+    listeners.forEach((l) => l());
+};
+export function useDrawerStore<T>(select: (s: State) => T): T {
+    return useSyncExternalStore(subscribe, () => select(state), () => select(SERVER_STATE));
 }
 ```
 
-## Post-Mutation Sync Pattern
-
-Keep mutations on the server and update request-context resources there:
+Rules:
 
-```typescript
-import {data} from 'react-router';
-import {getBasket, updateBasketResource} from '@/middlewares/basket.server';
+- `getSnapshot` must return a referentially stable value when nothing changed. Select primitives; a selector that allocates per call loops forever.
+- Provide a server snapshot and mutate only from events or effects so SSR and the first client render match (no hydration warnings).
+- Split stores by independent writers so each consumer subscribes to a slice.
+- For an instance-based store (one per widget), create it in a factory and provide it by context, as `createStoreLocatorStore` does in the store-locator extension.
 
-export async function action({request, context}: ActionFunctionArgs) {
-  const formData = await request.formData();
-  const productId = formData.get('productId') as string;
+## Context providers
 
-  const basketResource = await getBasket(context);
-  const clients = createApiClients(context);
+- Put the provider at the lowest layout that contains all consumers.
+- Memoize the `value` (`useMemo`, `useCallback`) and split read-only state from updaters into separate contexts so updater-only consumers do not re-render.
+- Use a selector pattern for large contexts (see README-STATE "Context Selector Pattern").
+- Values used only inside callbacks belong in `useRef`, not context state.
+- Compose providers with `src/providers/compose-providers.tsx`.
 
-  const {data: updatedBasket} = await clients.basket.addItemToBasket({
-    params: {path: {basketId: basketResource.current?.basketId ?? ''}},
-    body: {productId, quantity: 1},
-  });
-
-  // Sync basket resource in request context for current response/revalidation flow
-  updateBasketResource(context, updatedBasket);
-
-  return data({success: true, basket: updatedBasket});
-}
-```
+More patterns and anti-patterns in [PATTERNS.md](references/PATTERNS.md).
 
-## Best Practices
+## Common mistakes
 
-1. **Server-first data** — Load/mutate commerce data with `loader`/`action`
-2. **Provider-first app state** — Use providers for shared basket/auth UI state
-3. **Scoped Zustand usage** — Use Zustand for feature-local complexity (typically extensions)
-4. **Sync in server actions** — Update server basket/auth resources inside `action` handlers
-5. **Keep state minimal** — Store only what cannot be derived cheaply
+| Mistake | Instead |
+|---|---|
+| `useEffect` that fetches on mount and stores in state | loader (or streamed promise) |
+| Copying `loaderData` or basket into `useState` | read directly; derive with plain expressions |
+| Filters in `useState` | `useSearchParams` |
+| Reading cookies in components | loader returns the value, or use the provider hook |
+| New context for one component's state | `useState` in that component |
+| Adding Zustand or Redux | the mechanisms above; check `storefront-next:sfnext-overview` for conventions |
 
-## When to Use Each Mechanism
+## Finding more
 
-| Scenario                      | Use                                                      |
-| ----------------------------- | -------------------------------------------------------- |
-| Product data on page load     | `loader`                                                 |
-| Shopping cart badge count     | Basket provider hooks (`useBasket`, `useBasketSnapshot`) |
-| Complex extension UI workflow | Zustand store                                            |
-| Search results                | `loader`                                                 |
-| Add to cart                   | Server `action` + resource update                        |
+`AGENTS.md` ("Key Documentation"), `docs/README-STATE.md`, `docs/README-DATA.md`. `b2c docs search "storefront next state"` or the `docs_search` MCP tool.
 
 ## Related Skills
 
-- `storefront-next:sfnext-data-fetching` - Server-side data loading with loaders (NOT client state)
-- `storefront-next:sfnext-authentication` - Auth state management
-- `storefront-next:sfnext-components` - Using store data in components
+- `storefront-next:sfnext-data-fetching` - loaders, actions, fetchers
+- `storefront-next:sfnext-revalidation` - when providers make a re-run unnecessary
+- `storefront-next:sfnext-performance` - hydration stability and render scope
+- `storefront-next:sfnext-authentication` - `useAuth` and session lifecycle
+- `storefront-next:sfnext-commerce-features` - cart, wishlist, checkout features
+- `storefront-next:sfnext-components` - component conventions

package/content/guidance/storefront-next/sfnext-state-management/references/PATTERNS.md

@@ -0,0 +1,45 @@
+# State patterns and anti-patterns
+
+## Render scope should not exceed data-change scope
+
+If a value changes often but only event handlers read it, do not store it in state or Context. Keep it in a `useRef` or read it at call time (for example `window.matchMedia(...).matches` inside the handler). Every state change re-renders the component and all consumers of a Context value.
+
+Hidden subscribers: a component that subscribes to a store but renders nothing visible (an invisible drawer) still re-renders. Return `null` early or move the subscription to the component that renders the content.
+
+## Provider value stability
+
+```tsx
+const value = useMemo(() => ({ items, isOpen }), [items, isOpen]);
+const actions = useMemo(() => ({ open, close }), [open, close]); // useCallback inside
+return (
+    <StateContext.Provider value={value}>
+        <ActionsContext.Provider value={actions}>{children}</ActionsContext.Provider>
+    </StateContext.Provider>
+);
+```
+
+Check each field read during render: if a consumer uses only `isOpen`, it still re-renders when `items` changes with one combined context. Split or use a selector.
+
+## Manager components
+
+A component that only subscribes to data to perform a side effect (for example syncing the basket cookie, like `BasketCookieReconciler`) should render `null` and live as a leaf so the parent is not re-rendered.
+
+## Server versus client snapshots
+
+For `useSyncExternalStore`, `getServerSnapshot` must equal what the first client render will read, or React warns and re-renders. Read browser-only data (storage, matchMedia) after mount in an effect and then write it into the store.
+
+## URL state
+
+Prefer URL state for anything a shopper might share or reload. Changing search params triggers navigation and loader re-run; see `storefront-next:sfnext-revalidation` to skip re-runs for client-only params. Use `setSearchParams(next, { replace: true, preventScrollReset: true })` for high-frequency updates such as typing.
+
+## Cookies
+
+Cookies written by the server are set from `action` or middleware responses. Use the helpers in `src/lib/cookie-utils.server.ts` (site-scoped names, domain resolution, `createCookie`). Do not store personal data or tokens in cookies readable by scripts. Consent state is covered by `storefront-next:sfnext-analytics-consent`.
+
+## Derived state
+
+Compute derived values during render. `useMemo` is for expensive pure computations of UI-derived values; it does not fix transforming loader data in render (do that in the loader) and must not wrap promises.
+
+## Testing state
+
+Render with the real provider in tests, or mock the hook module (`vi.mock('@/providers/basket')`). For stores, call the exported setters inside `act` and reset module state between tests. See `storefront-next:sfnext-testing`.