@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/content/guidance/storefront-next/sfnext-page-designer/references/DECORATOR-PATTERNS.md

@@ -1,180 +1,168 @@
-# Decorator Patterns Reference
+# Decorator Patterns
 
-## @Component Decorator
-
-Marks a class as a Page Designer component:
+All four decorators are imported from your project, not from the runtime package:
 
 ```typescript
-@Component('typeId', {
-    name: 'Display Name',
-    description: 'Component description for merchants'
-})
-class MyComponentMeta {
-    // attribute definitions...
-}
+import { AttributeDefinition, Component, PageType, RegionDefinition } from '@/lib/decorators';
 ```
 
-- `typeId` — Unique identifier (lowercase, hyphens); used in registry and Business Manager
-- `name` — Display name in Page Designer sidebar
-- `description` — Merchant-facing description
+Deep imports (`@/lib/decorators/component`, `.../attribute-definition`, `.../page-type`, `.../region-definition`) also work and are used by some shipped files.
 
-## @AttributeDefinition Decorator
+Decorators only attach metadata. They are stripped of behavior at runtime and read at build time by `pnpm cartridge:generate` (and by the registry plugin for `@Component`). Mistakes therefore show up as a missing or broken editor in Business Manager, not as a runtime error.
 
-Defines a merchant-editable attribute:
+## `@Component(typeId, options)`
 
 ```typescript
-@AttributeDefinition()              // Default: string type
-headline: string;
-
-@AttributeDefinition({ type: 'image' })
-heroImage: string;
+@Component('productCarousel', {
+    name: 'Product Carousel',
+    description: 'Scrollable row of product cards. Pick a category or add product tiles.',
+    group: 'Layout',
+})
+```
 
-@AttributeDefinition({ type: 'url' })
-ctaLink: string;
+| Option | Meaning |
+|--------|---------|
+| `typeId` (first arg) | String literal, camelCase by convention (`hero`, `heroCarousel`, `megaMenu`). The registry plugin rejects non-literals. |
+| `name`, `description` | Shown to merchants in the palette. Be specific about which attributes drive which behavior. |
+| `group` | Palette folder. Default `storefrontnext_base`. Shipped components use `Content` and `Layout`. |
+| `embedded`, `component_id` | Marks a singleton content block that is referenced rather than dropped into regions. The component preview route and `fetchComponentWithComponentData` use this path. |
 
-@AttributeDefinition({ type: 'boolean' })
-showBadge: boolean;
+The stored, fully-qualified id is `<group>.<typeId>` (`Layout.productCarousel`). That is the id that appears in SCAPI responses, in the registry, and in region include/exclude lists.
 
-@AttributeDefinition({ type: 'enum', values: ['left', 'center', 'right'] })
-alignment: string;
+## `@AttributeDefinition(config)`
 
-@AttributeDefinition({ type: 'product' })
-featuredProduct: string;
+Put it on a field of the exported metadata class. The field name is the prop name your component receives.
 
-@AttributeDefinition({ type: 'category' })
-category: string;
+```typescript
+@AttributeDefinition({
+    id: 'limit',
+    name: 'Product Limit',
+    description: 'Maximum number of products to show.',
+    type: 'integer',
+    required: false,
+    defaultValue: 12,
+})
+limit?: number;
+```
 
-@AttributeDefinition({ type: 'markup' })
-richText: string;
+| Option | Notes |
+|--------|-------|
+| `id` | Attribute id written to metadata. Keep it identical to the field name; a mismatch means merchant values never reach the prop. |
+| `name`, `description` | Merchant-facing label and help text. Without them Business Manager shows the raw id. |
+| `type` | One of the types below. Default is a string attribute. An unknown string (such as `'number'`) is not type-checked and produces a broken editor. |
+| `required` | Match the component: `required: true` only if it cannot render without a value. |
+| `defaultValue` | Prefilled in the editor. Keep it equal to the component's destructuring default so editor and runtime agree. For `enum` it must be one of `values`. |
+| `values` | Required for `enum`: the option list. |
+| `editorDefinition` | For `type: 'custom'`: `{ type, configuration? }` selecting a custom editor. |
+| `searching` | `{ searchable, refinable, boostFactor?, sortable? }`. Makes the attribute searchable in Business Manager. Both booleans are required. |
+| `dynamicLookup` | `{ aspectAttributeAlias }`. Sources the value from an aspect attribute at render time instead of a stored value. Allowed on all types. |
 
-@AttributeDefinition({ type: 'integer' })
-maxItems: number;
-```
+### Attribute types
 
-### Attribute Types
+`string`, `text`, `markup`, `integer`, `boolean`, `product`, `category`, `file`, `page`, `image`, `url`, `enum`, `custom`, `cms_record`.
 
-| Type | Input in Business Manager | Returns |
-|------|--------------------------|---------|
-| `string` | Text input | String |
-| `text` | Multi-line text | String |
-| `markup` | Rich text editor | Markup string |
-| `boolean` | Checkbox | Boolean |
-| `integer` | Number input | Integer |
-| `enum` | Dropdown select | String |
-| `image` | Image picker | Image URL |
-| `file` | File picker | File URL |
-| `url` | URL input | URL string |
-| `category` | Category selector | Category ID |
-| `product` | Product selector | Product ID |
+| Type | Value your component receives |
+|------|-------------------------------|
+| `string`, `text` | string (`text` is multi-line) |
+| `markup` | raw HTML string; render with `dangerouslySetInnerHTML` only after deciding it is trusted content |
+| `integer`, `boolean` | number, boolean |
+| `enum` | one of `values` |
+| `image` | object `{ url, focalPoint?, metaData? }` (`Image` from `@/types`) |
+| `url` | string |
+| `product`, `category` | the id (string); fetch details in a `loader` |
+| `file`, `page`, `custom`, `cms_record` | reference values; check the generated JSON and a live SCAPI payload before relying on the shape |
 
-### Type Inference by MCP Tool
+### `searching` combinations
 
-The `storefront_next_page_designer_decorator` MCP tool infers types from prop names:
+Generation fails (and `cartridge:validate` reports it) when the combination is invalid:
 
-| Prop Name Pattern | Inferred Type |
-|------------------|---------------|
-| `*Url`, `*Link`, `*Href` | `url` |
-| `*Image`, `*Img`, `*Src` | `image` |
-| `is*`, `show*`, `has*`, `enable*` | `boolean` |
-| `*Count`, `*Num`, `max*`, `min*` | `integer` |
-| Other | `string` |
+- `string`, `text`, `product`, `category`: all fields allowed.
+- `markup`: `sortable` must be omitted or `false`.
+- `custom`, `cms_record`: `refinable` must be `false`; `boostFactor` and `sortable` are not allowed.
+- `integer`, `boolean`, `file`, `page`, `image`, `url`, `enum`: searching is not allowed.
 
-## @RegionDefinition Decorator
+## `@RegionDefinition(regions)`
 
-Defines nested regions within a component (e.g., a grid with slots):
+Declares the slots a component (or a page route) exposes to merchants.
 
 ```typescript
-@Component('content-grid', { name: 'Content Grid', description: '2-column grid' })
 @RegionDefinition([
     {
-        id: 'left',
-        name: 'Left Column',
-        description: 'Left content area',
-        maxComponents: 3,
-    },
-    {
-        id: 'right',
-        name: 'Right Column',
-        description: 'Right content area',
-        maxComponents: 3,
+        id: 'products',
+        name: 'Products',
+        description: 'Add Product Tile components to populate this carousel.',
+        maxComponents: 12,
+        componentTypeInclusions: ['Content.productTile'],
     },
 ])
-class ContentGridMeta {
-    @AttributeDefinition({ type: 'boolean' })
-    equalWidth: boolean;
-}
 ```
 
-## @PageType Decorator
+| Field | Notes |
+|-------|-------|
+| `id`, `name` | Required. The `id` must match the `regionId` passed to `<Region>`. |
+| `description` | Shown to merchants. |
+| `maxComponents` | Set only when the layout structurally limits children. |
+| `componentTypeInclusions`, `componentTypeExclusions` | Allow-list / deny-list of component types. Unqualified ids are prefixed with the host component's group; refer to another group with the full id (`'Content.productTile'` from a `Layout.*` host). |
+| `defaultComponentConstructors` | `[{ id, typeId, data }]` components created when a merchant adds the region to a new page. `typeId` follows the same qualification rule. |
+
+Leaf components may use `@RegionDefinition([])` or omit the decorator. A declared region that the implementation never renders is invisible to shoppers even when merchants fill it.
 
-Used on route modules to define page types in Business Manager:
+## `@PageType(config)`
 
 ```typescript
 @PageType({
-    name: 'Home Page',
-    description: 'Main landing page',
-    supportedAspectTypes: ['default']
+    name: 'Product Detail Page',
+    description: 'Product detail page with promotional and engagement regions',
+    supportedAspectTypes: ['pdp'],
 })
-@RegionDefinition([
-    { id: 'hero', name: 'Hero Section', maxComponents: 1 },
-    { id: 'content', name: 'Main Content' },
-])
+@RegionDefinition([{ id: 'pdpPromo', name: 'Promo Content Region', maxComponents: 1 }])
+export class ProductPageMetadata {}
 ```
 
-## Complete Component Example
+| Field | Notes |
+|-------|-------|
+| `name`, `description` | Human-readable. `name` is the template label merchants pick. |
+| `supportedAspectTypes` | `['pdp']`, `['plp']`, or `[]` for routes not bound to an aspect (home, about-us, component preview). Must agree with the `aspectType` the route loader fetches. |
+| `preview` | Only `'default'` is valid. Used by the component preview route. |
 
-```typescript
-import { Component, AttributeDefinition, RegionDefinition } from '@salesforce/storefront-next-runtime/design';
-
-@Component('promo-banner', {
-    name: 'Promotional Banner',
-    description: 'Banner with background image, text overlay, and CTA'
-})
-class PromoBannerMeta {
-    @AttributeDefinition({ type: 'image' })
-    backgroundImage: string;
-
-    @AttributeDefinition()
-    headline: string;
+The class must be exported and empty. Never put `@AttributeDefinition` on a page type.
 
-    @AttributeDefinition({ type: 'text' })
-    subheadline: string;
+`sfnext generate-cartridge` parses decorators statically, so decorator arguments must be literals, not imported constants.
 
-    @AttributeDefinition({ type: 'url' })
-    ctaUrl: string;
+## Nested regions in a container
 
-    @AttributeDefinition()
-    ctaLabel: string;
+```tsx
+import { Region } from '@/components/region';
 
-    @AttributeDefinition({ type: 'enum', values: ['light', 'dark'] })
-    theme: string;
-
-    @AttributeDefinition({ type: 'boolean' })
-    fullWidth: boolean;
-}
+@Component('twoColumn', { name: 'Two Column', description: 'Two side-by-side regions.', group: 'Layout' })
+@RegionDefinition([
+    { id: 'left', name: 'Left' },
+    { id: 'right', name: 'Right' },
+])
+export class TwoColumnMetadata {}
 
-export default function PromoBanner({
-    backgroundImage,
-    headline,
-    subheadline,
-    ctaUrl,
-    ctaLabel,
-    theme = 'light',
-    fullWidth,
-}: PromoBannerProps) {
+export default function TwoColumn({ component }: { component: ComponentType }) {
     return (
-        <div className={cn(
-            'relative overflow-hidden',
-            fullWidth ? 'w-full' : 'max-w-7xl mx-auto',
-            theme === 'dark' ? 'text-white' : 'text-gray-900'
-        )}>
-            <DynamicImage src={backgroundImage} alt="" className="absolute inset-0" />
-            <div className="relative z-10 p-8">
-                <h2 className="text-3xl font-bold">{headline}</h2>
-                {subheadline && <p className="mt-2">{subheadline}</p>}
-                {ctaUrl && <a href={ctaUrl} className="mt-4 inline-block">{ctaLabel}</a>}
-            </div>
+        <div className="grid grid-cols-2 gap-4">
+            <Region component={component} regionId="left" />
+            <Region component={component} regionId="right" />
         </div>
     );
 }
 ```
+
+`ComponentType` is exported from `@/components/region`. Use `className` on `<Region>` for layout; the design-mode wrapper uses `display: contents`, so children stay direct grid/flex items. `src/components/grid/index.tsx` is the reference implementation.
+
+## Images
+
+```tsx
+import { DynamicImage } from '@/components/dynamic-image';
+
+<DynamicImage src={image.url} alt="" />
+```
+
+Always provide `alt` (empty for decorative images). Set `priority="high"` only on the LCP image, never on every image.
+
+## Text that is not merchant content
+
+Button labels and fallback messages that developers (not merchants) own should use `useTranslation()`. Text in attributes is edited and localized by merchants in Business Manager, so leave it raw.

package/content/guidance/storefront-next/sfnext-page-designer/references/REVIEW-CHECKLIST.md

@@ -0,0 +1,83 @@
+# Review Checklist
+
+Use when reviewing or self-checking a Page Designer component (`@Component`) or page route (`@PageType`). Read-only: report findings with `file:line`, say why each matters, and group them as Bugs (break at runtime or in Business Manager), Conventions (drift from the rest of your project) and Polish.
+
+A file is in scope if it uses `@Component` or `@PageType`, or is listed in `src/lib/page-designer/static-registry.ts`. Components use sections 1-4; page routes use sections 1 (page type part), 3 (region rendering) and 5.
+
+## 1. Metadata
+
+**`@Component`**
+- `typeId` is a literal that matches the registry suffix (`Content.hero` -> `'hero'`). A mismatch means the component never resolves.
+- `name` is human-readable and differs from `typeId`; `description` says which attributes drive which behavior.
+- `group` is set (`Content` or `Layout`) rather than defaulting to `storefrontnext_base`.
+- The metadata class is `export`ed.
+
+**`@AttributeDefinition`** (every merchant-configurable prop needs one)
+- `type` is one of the valid types (`integer`, not `number`). An invalid string is not caught by TypeScript.
+- `enum` has `values`, and its `defaultValue` is one of them.
+- `image` props are typed as the `Image` object (`image.url`), not `string`.
+- `id` equals the field name; a mismatch means merchant values never reach the prop.
+- `required` matches the component: a prop with a destructuring default should be `required: false`; a prop that crashes on `undefined` should be `true`.
+- `defaultValue` equals the component's destructuring default (otherwise the editor pre-fills one value and runtime falls back to another).
+- `name` and `description` present.
+
+**`@RegionDefinition`**
+- Every declared region id is rendered by a matching `<Region regionId>`, and every rendered id is declared.
+- `componentTypeInclusions`/`Exclusions` are fully qualified when they cross groups (`'Content.productTile'` from a `Layout.*` host); unqualified ids take the host's group.
+- `maxComponents` only where the layout limits children.
+- `@RegionDefinition([])` or no decorator on a leaf is fine.
+
+**`@PageType`** (routes)
+- Exported, empty class with `name`, `description`, `supportedAspectTypes`. `[]` is valid for fixed-page routes.
+- `supportedAspectTypes` agrees with the loader's `aspectType`. Flag a loader aspect not in the list, a listed aspect the loader never fetches, and aspect ids that do not fit the aspect (for example `productId` with a category aspect). This is the most valuable cross-file check: Business Manager shows the wrong template with no error.
+- No `@AttributeDefinition` on page types.
+
+## 2. Module contract (components)
+
+- Default export is the component.
+- Named `fallback` export exists, is light (no `useState`/`useEffect`, no fetching, nothing that suspends), uses the same attribute props, and reserves dimensions.
+- Skeletons live in `fallback`, not in the main component.
+- A `loader` export is a function with the `{ componentData, context, request }` signature; the registry has `{ loader: 'loader' }` (regenerate if not); attributes are read from `componentData.data`; `null` is returned for "nothing configured"; independent fetches use `Promise.all`; errors are not swallowed.
+- Server-only imports (`*.server.ts`) appear only in loader files, never in the component body.
+
+## 3. Rendering
+
+- Injected props (`component`, `data`, `designMetadata`, `regionId`, and rarely `componentData`) are destructured out before any `...rest` spread onto a DOM element. Unused ones are prefixed with `_`.
+- Nested regions use component mode: `<Region component={component} regionId="x" />`, with no `page` prop, no `fallbackElement`, no Suspense wrapper, no promises.
+- Route regions use page mode: `<Region page={loaderData.page} regionId="x" />`. `critical` only on above-the-fold regions with an awaited page and no local `fallbackElement`.
+- Instance-specific `<style>` output is scoped (for example with `useId()`); unscoped CSS collides when two instances share a page.
+- Images: `Image` object, `DynamicImage` for responsive widths, `alt` always present (empty for decorative), `priority="high"` only on LCP candidates.
+- No `'use client'` directives; this is React Router, not React Server Components.
+- Developer-owned strings go through `useTranslation()`; merchant attribute text stays raw.
+- `memo` only on components with stable props.
+
+## 4. Anti-patterns
+
+1. `errorElement` on a `<Region>` used to render hard-coded content for an unconfigured page.
+2. A loader fetching data that only an `errorElement` uses.
+3. Skeleton markup inside the main component.
+4. `fetchPriority="high"` on every image.
+5. An `@Component` that is not in `static-registry.ts` (registry not regenerated, or file outside `src/components`).
+
+## 5. Do not flag
+
+- `@PageType` with `supportedAspectTypes: []` on fixed-page routes.
+- `@RegionDefinition([])` on leaves, or an omitted decorator on a leaf.
+- Missing comments that justify valid choices.
+- Formatting and import-order nits the linter already enforces.
+
+## Report format
+
+```
+## Bugs
+1. `src/components/foo/index.tsx:42` - Page Designer props leak to the DOM.
+   `designMetadata` and `component` are not destructured before `...rest` reaches a <div>; React warns in dev and emits `designmetadata="[object Object]"` in production.
+
+## Conventions
+2. `src/components/foo/index.tsx:18` - `@Component` has no `group`; peers use 'Content' or 'Layout'.
+
+## Polish
+3. `src/components/foo/index.tsx:25` - Description is generic.
+```
+
+End with a one-line count per severity. A clean review should say so explicitly.

package/content/guidance/storefront-next/sfnext-page-designer/references/TROUBLESHOOTING.md

@@ -0,0 +1,35 @@
+# Troubleshooting Page Designer
+
+Start with the command loop: `pnpm cartridge:generate`, `pnpm cartridge:validate`, `pnpm cartridge:deploy`, then hard-refresh Business Manager. Most "it does not show up" problems are one of these not having run against the right instance and code version.
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Component absent from the Business Manager palette | Cartridge not regenerated or not deployed; deployed to a code version the site does not use; cartridge not on the site's path; metadata class not `export`ed | Export the class, run generate, validate and deploy, confirm the active code version, hard-refresh |
+| `cartridge:generate` or `validate` fails | Invalid `searching` combination; unknown attribute `type`; non-literal decorator argument; `enum` without `values` | Fix the decorator; generation parses decorators statically, so use literals |
+| Component is in the palette but renders nothing | `typeId` or `group` differs from the registry entry (`Content.hero` vs `Layout.hero`); registry stale; missing default export | Compare the decorator with `src/lib/page-designer/static-registry.ts`; restart `pnpm dev` or `pnpm build` |
+| Component not in `static-registry.ts` | File outside `src/components`, or `@Component` typeId is not a string literal | Move it or make it a literal; restart the dev server |
+| Page is empty on the storefront | No published page for that `pageId` or aspect assignment; wrong `pageId` in the loader; loader fetched a different aspect than the template | Check the page in Business Manager; `fetchPageWithComponentData` returns `null` on 404/API error |
+| Wrong template offered for products or categories | `supportedAspectTypes` disagrees with the loader's `aspectType` | Make them agree (`['pdp']`/`'pdp'`, `['plp']`/`'plp'`) |
+| Region shows nothing though merchants filled it | `<Region regionId>` not matching the `@RegionDefinition` id; region declared but never rendered | Cross-check ids in both directions |
+| `data` prop is `undefined` | Exported `loader` is an object (`{ server }`) not a function; registry lacks `{ loader: 'loader' }`; loader reads attributes from the wrong place | `export const loader = loaders.server`; read `componentData.data.<attr>`; regenerate the registry |
+| Loader data for an attribute is `undefined` | Attribute `id` differs from the field name; attribute not declared on the metadata class | Align `id` and field name |
+| Image attribute crashes or shows nothing | Treated as a string | It is an object: use `image.url` and `image.focalPoint` |
+| `markup` attribute shows literal tags | Rendered as text | Render as HTML only if the content is trusted |
+| Blank space then content pops in (layout shift) | `fallback` missing or height-less | Export a `fallback` that reserves the final height |
+| Suspense never resolves / whole region blank | `fallback` suspends (hooks, fetching); `critical` region given an unresolved page | Keep `fallback` synchronous; `await` the page for critical regions |
+| React warns about `designMetadata`/`component` props on a DOM element | Spreading `...rest` onto a DOM element | Destructure the injected props (`component`, `data`, `designMetadata`, `regionId`) out before spreading |
+| TypeScript error on `<Region>` | Mixed `page` and `component` props, or `fallbackElement` on a component-mode region | Use page mode at route level and component mode for nested regions, never both |
+| Nested region empty | Page mode used inside a component, or `component` prop missing | `<Region component={component} regionId="..." />` |
+| Design mode links navigate away | `PageDesignerInit` removed from `root.tsx` | Restore it |
+| Edits in Business Manager not reflected on the storefront | Editing a different instance than the storefront reads; cached page | Check the environment and site; see `storefront-next:sfnext-revalidation` for caching |
+
+## Debugging tips
+
+```bash
+pnpm cartridge:generate          # regenerate metadata; errors name the offending decorator
+pnpm cartridge:validate          # schema-check the generated JSON
+grep -n "Content.hero" src/lib/page-designer/static-registry.ts   # is the component registered?
+ls cartridges/app_storefrontnext_base/cartridge/experience/components   # is the metadata there?
+```
+
+Deploy problems (auth, WebDAV, code version) are not Page Designer problems; use `b2c-cli:b2c-code` and `b2c-cli:b2c-webdav`, and rerun with `--log-level trace`.

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

@@ -1,132 +1,102 @@
 ---
 name: sfnext-performance
-description: Optimize Storefront Next performance with bundle size limits, DynamicImage component, Lighthouse audits, and progressive streaming. Use when checking bundle sizes, optimizing images, improving page load speed, or configuring performance metrics. Covers parallel data fetching, image optimization, and performance monitoring.
+description: >-
+  Keep a Storefront Next storefront fast and self-review changes for performance: LCP, CLS and TBT, Suspense placement and granularity, stable promise identity, lazy-loaded modals and drawers with useDeferredUnmount, useDeferredRender, Region critical, DynamicImage and image priority, font loading, resource hints (links.preconnect), bundle size checks (pnpm bundlesize, BUNDLES_SIZE_ANALYZE), Lighthouse CI, and the performance.metrics / Server-Timing flags. Use for "page is slow", "LCP regression", "skeleton flashes", "bundle too big", "review my diff for performance", "hydration mismatch or extra re-renders", "waterfall of fetches", or before merging feature work that adds loaders, fetchers, modals and drawers or images. Do not use for loader/action mechanics (use `storefront-next:sfnext-data-fetching`), revalidation policy (use `storefront-next:sfnext-revalidation`), or accessibility (use `storefront-next:sfnext-accessibility`).
 ---
 
-# Performance Skill
-
-This skill covers performance optimization techniques for Storefront Next storefronts.
-
-## Bundle Size Limits
-
-The application enforces strict bundle size limits in `package.json` under the `bundlesize` configuration.
-
-```bash
-pnpm bundlesize:test      # Verify bundle stays within limits
-pnpm bundlesize:analyze   # Analyze bundle composition
-```
-
-## Built-in Metrics
-
-Enable performance tracking in `config.server.ts`:
-
-```typescript
-{
-    performance: {
-        metrics: {
-            serverPerformanceMetricsEnabled: true,
-            clientPerformanceMetricsEnabled: true,
-            serverTimingHeaderEnabled: false  // Enable for debugging only
-        }
-    }
+# Storefront Next Performance
+
+Performance rules are part of `AGENTS.md` ("Performance & Data Rules") and detailed in `docs/README-PERFORMANCE.md`, `docs/README-SUSPENSE.md`, `docs/README-IMAGES.md` and `docs/README-PERFORMANCE-METRICS.md` in your project. This skill is the working summary plus a checklist to run on your own diff: [PERFORMANCE-REVIEW-CHECKLIST.md](references/PERFORMANCE-REVIEW-CHECKLIST.md).
+
+## Core rules
+
+1. Server-load data. Await only what SEO, LCP, layout or the HTTP status needs; return promises for the rest (see `storefront-next:sfnext-data-fetching`).
+2. One `<Suspense>` per async operation, with a skeleton that reserves the final size. No `fallback={null}` above the fold unless space is reserved.
+3. Promise identity must be stable across renders: compose in the loader, read from `loaderData`/props, never `Promise.all`/`.then`/`new Promise` in render, never `useMemo` around a promise. Escape hatches: `useState(() => ...)` pinning or `useRef` re-pinning.
+4. Every `use()`/`<Await>` consumer needs a `<Suspense>` ancestor; otherwise it blocks the first byte of the streamed shell.
+5. Heavy or hidden UI (modals, drawers, dialogs, rich editors) is `React.lazy` and mounted only while needed.
+6. Shape data in the loader, not in render.
+7. Hints and third-party scripts cost: preconnect only to origins used on every page; load scripts `async`/`defer`.
+
+## Lazy modals and drawers
+
+```tsx
+import { lazy, Suspense, useState } from 'react';
+import { useDeferredUnmount } from '@/hooks/use-deferred-unmount';
+
+const SizeGuide = lazy(() => import('@/components/size-guide').then((m) => ({ default: m.SizeGuide })));
+
+export function SizeGuideButton() {
+    const [open, setOpen] = useState(false);
+    const mounted = useDeferredUnmount(open); // stays mounted briefly after close for the exit animation
+    return (
+        <>
+            <button onClick={() => setOpen(true)}>Size guide</button>
+            {mounted && (
+                <Suspense fallback={null}>
+                    <SizeGuide open={open} onOpenChange={setOpen} />
+                </Suspense>
+            )}
+        </>
+    );
 }
 ```
 
-Tracks:
-- SSR operations and rendering time
-- SCAPI API calls with parallelization visibility
-- Authentication operations
-- Client-side navigation timing
-
-## Parallel Data Fetching
-
-Return all promises simultaneously in loaders — avoid sequential `await`:
-
-```typescript
-// GOOD — Parallel (all requests start at once)
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),
-        reviews: clients.shopperProducts.getReviews({...}),
-        recommendations: clients.shopperProducts.getRecommendations({...}),
-    };
-}
+Avoid a sticky "loaded" latch (a state that flips true on first open and never resets): fetchers inside the modal stay registered and re-run on every later revalidation. See `src/components/product-tile/quick-add-button.tsx`.
 
-// BAD — Sequential (each waits for previous)
-export async function loader({ context }: LoaderFunctionArgs) {
-    const product = await clients.shopperProducts.getProduct({...});
-    const reviews = await clients.shopperProducts.getReviews({...});
-    return { product, reviews };
-}
-```
+## Deferred rendering
 
-## Image Optimization
+`useDeferredRender(enabled, options)` (`@/hooks/use-deferred-render`) delays mounting a Suspense boundary until an idle frame; use it for large below-the-fold grids. `DeferredProductGrid` (`@/components/product-grid/deferred`) is the reference. `useDeferredRenderSequence(n)` fans out work one step per idle frame.
 
-Use the `DynamicImage` component with WebP format:
+## Page Designer
 
-```typescript
-import { DynamicImage } from '@/components/dynamic-image';
+Mark a region `<Region critical>` only when it is required for the initial HTML or is an LCP candidate, and `await` that page in the loader (omit a region fallback). Below-the-fold regions stay streamed. See `storefront-next:sfnext-page-designer`.
 
-<DynamicImage
-    src={product.image.link}
-    alt={product.image.alt}
-    width={400}
-    height={400}
-    format="webp"
-/>
-```
+## Images, fonts, hints
 
-### Image Best Practices
+- Images: use `DynamicImage` (`@/components/dynamic-image`). Props: `src`, `alt`, `widths`, `heights`, `imageProps`, `as`, `className`, `loading`, `priority`, `objectFit`. Give the LCP image `priority="high"` (React 19 preload) and never lazy-load it. Provide `widths` matching the layout, or wrap a group in `DynamicImageProvider` (`@/providers/dynamic-image`, `value={{ widths }}`). URL helpers are in `docs/README-IMAGES.md`.
+- Fonts: the template self-hosts `public/fonts/sen-variable.woff2`, preloads it in `src/root.tsx` `links`, and declares `@font-face` with `font-display: swap` in `src/theme/base.css`. Keep fonts same-origin, preload only the one above-the-fold face, and consider system fonts for secondary text.
+- Resource hints: configure `app.links.preconnect`, `prefetchDns`, `prefetch` in `config.server.ts` or via `PUBLIC__app__links__preconnect='["https://cdn.example.com"]'`. Default preconnects to the image host only.
 
-- Use WebP format by default (smaller file sizes)
-- Set explicit `width` and `height` to prevent layout shifts
-- Lazy load below-the-fold images
-- Use SCAPI image alt text as the primary alt source
+## Measure
 
-## Progressive Streaming
+| Task | Command |
+|---|---|
+| Check bundle size limits (block CI) | `pnpm bundlesize` |
+| Interactive treemaps (`build/client-bundle-size.html`, `build/ssr-bundle-size.html`) | `cross-env BUNDLES_SIZE_ANALYZE=true pnpm build` |
+| Compare size runs | `pnpm bundlesize:compare` |
+| Lighthouse | `pnpm lighthouse:ci` |
+| Request timings | `performance.metrics` flags in `config.server.ts` |
 
-Use synchronous loaders returning promises to stream data progressively:
+The limits live in the `bundlesize` block of `package.json`. If a legitimate change exceeds a limit, state the reason and raise it deliberately; do not use `manualChunks` to bucket components.
 
-```typescript
-// Streams data as each promise resolves
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),    // Streams independently
-        reviews: clients.shopperProducts.getReviews({...}),    // Streams independently
-    };
-}
-```
+`performance.metrics` (`serverPerformanceMetricsEnabled`, `serverTimingHeaderEnabled`, `clientPerformanceMetricsEnabled`) are all `false` in the shipped `config.server.ts`; `docs/README-PERFORMANCE-METRICS.md` lists two of them as defaulting to `true`, but the shipped config wins. Enable them only while debugging, because `serverTimingHeaderEnabled` adds a `Server-Timing` header and costs response time. Override via `PUBLIC__app__...` environment variables (`storefront-next:sfnext-configuration`).
 
-Combine with granular Suspense boundaries for progressive page rendering.
+## Review workflow
 
-## Lighthouse Optimization
+1. Run the checklist on your diff (fetch topology, Suspense, promise stability, hydration, revalidation scope, client transforms).
+2. `pnpm typecheck`, `pnpm lint`, `pnpm test`.
+3. `pnpm bundlesize` when you add dependencies or routes.
+4. Load the page with network throttling and CPU slowdown; confirm no layout shift when streamed sections resolve and that server HTML contains the LCP element.
 
-Monitor and improve performance metrics:
+Impact rule of thumb: traffic of the page x number of instances on it x cost per instance. A fetch in a product tile is multiplied by every tile.
 
-```bash
-pnpm lighthouse:ci   # Run Lighthouse CI
-```
+## References
 
-**Key areas:**
-- Preload critical CSS
-- Use WebP images by default
-- Lazy load below-the-fold content
-- Optimize font loading
-- Minimize JavaScript bundle size
+- [PERFORMANCE-REVIEW-CHECKLIST.md](references/PERFORMANCE-REVIEW-CHECKLIST.md) - self-review checklist with rules, bad/good forms and exceptions
+- [SUSPENSE-AND-STREAMING.md](references/SUSPENSE-AND-STREAMING.md) - placement, granularity, promise stability recipes
 
-## Troubleshooting
+## Finding more
 
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Large bundle size | Unused imports or heavy dependencies | Run `bundlesize:analyze`; tree-shake or lazy load |
-| Slow page transitions | Async loaders blocking | Use synchronous loaders returning promises |
-| Layout shifts | Missing image dimensions | Set `width` and `height` on images |
-| Slow SCAPI responses | Sequential API calls | Use parallel data fetching |
+`AGENTS.md` "Key Documentation" and `docs/README-PERFORMANCE.md`. `b2c docs search "storefront next performance"` or `docs_search` MCP tool.
 
 ## Related Skills
 
-- `storefront-next:sfnext-data-fetching` - Parallel loader patterns for performance
-- `storefront-next:sfnext-components` - Suspense boundaries for progressive rendering
-- `storefront-next:sfnext-deployment` - Production build optimization
+- `storefront-next:sfnext-data-fetching` - loaders, streaming
+- `storefront-next:sfnext-revalidation` - cutting wasted loader re-runs
+- `storefront-next:sfnext-state-management` - render scope and stores
+- `storefront-next:sfnext-components` - component conventions
+- `storefront-next:sfnext-page-designer` - critical regions
+- `storefront-next:sfnext-quality-gates` - lint, typecheck, tests before merge
+- `storefront-next:sfnext-deployment` - bundle and MRT limits
+- `b2c-cli:b2c-mrt` - Managed Runtime logs and deploys