@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

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

@@ -1,181 +1,202 @@
 ---
 name: sfnext-page-designer
-description: Integrate Page Designer with Storefront Next using React decorators, component registry, and Region rendering. Use when creating merchant-editable pages, adding Page Designer components with @Component/@AttributeDefinition decorators, using fetchPageFromLoader, or rendering Regions. This is for the React/Storefront Next implementation — for classic ISML Page Designer, see b2c:b2c-page-designer.
+description: >-
+  Build merchant-editable Page Designer content in a Storefront Next project: components decorated with @Component/@AttributeDefinition/@RegionDefinition, page routes decorated with @PageType, <Region> rendering, fetchPageWithComponentData, component loaders and fallbacks, the generated static registry, and the pnpm cartridge:generate / cartridge:validate / cartridge:deploy workflow. Use when adding or editing a Page Designer component, exposing a region on a route (home, PDP, PLP, search), fetching a page by pageId or aspectType, marking a Region critical, debugging a component that does not appear in the Business Manager palette or renders empty, or reviewing Page Designer code. Do not use for classic ISML/SFRA Page Designer (use `b2c:b2c-page-designer`), for turning a Figma frame into blocks (use `figma-to-sfnext-pagedesigner:figma-to-sfnext-pagedesigner`), or for plain React components that merchants never edit (use `storefront-next:sfnext-components`).
 ---
 
-# Page Designer Skill
+# Page Designer in Storefront Next
 
-This skill covers Page Designer integration in Storefront Next — building merchant-editable pages with React components, decorators, and the Shopper Experience API.
+In Storefront Next your React components are the Page Designer components. You annotate them with decorators, the build generates Business Manager metadata (JSON) from those decorators, and at runtime a route loader fetches the page structure from the Shopper Experience API and `<Region>` renders it.
 
-## Overview
+The in-project guide is `docs/README-PAGE-DESIGNER.md` and the rules in `AGENTS.md` apply; this skill is the task-oriented path through them. Where the guide and the source disagree, trust the source.
 
-Page Designer is Commerce Cloud's visual editor for merchants. In Storefront Next, page structure (regions, components, attributes) is fetched from the Shopper Experience API and rendered via a component registry and `<Region>` component.
+## Pieces and where they live
 
-| Concept | Role |
-|---------|------|
-| **Page** | Fetched in route loaders via `fetchPageFromLoader(args, { pageId })` |
-| **Region** | Named area rendered with `<Region page={...} regionId="..." />` |
-| **Component** | Content block with a `typeId` and attributes; registered in `@/lib/registry` |
-| **Registry** | Static registry auto-generated by Vite plugin — do not edit by hand |
+| Piece | Location in your project |
+|-------|--------------------------|
+| Decorators (`Component`, `AttributeDefinition`, `RegionDefinition`, `PageType`) | `@/lib/decorators` (`src/lib/decorators/`) |
+| Page fetch with per-component loader promises | `fetchPageWithComponentData` in `@/lib/page-designer/page-loader.server` |
+| Single-component fetch (preview, embedded) | `fetchComponentWithComponentData` in `@/lib/page-designer/component-loader.server` |
+| Region renderer | `Region` from `@/components/region` |
+| Generated registry (do not hand-edit) | `src/lib/page-designer/static-registry.ts` |
+| Runtime hooks (`usePageDesignerMode`) | `@salesforce/storefront-next-runtime/design/react/core` |
+| Design/preview mode detection in loaders | `isDesignModeActive` / `isPreviewModeActive` from `@salesforce/storefront-next-runtime/design/mode` |
+| Generated Business Manager metadata | `cartridges/app_storefrontnext_base/cartridge/experience/{components,pages,aspects}` |
 
-## Which Pages Use Page Designer
+The runtime package's `/design` entry exports only the registry. Decorators come from your project, not from `@salesforce/storefront-next-runtime`.
 
-| Uses Page Designer | Does Not |
-|--------------------|----------|
-| Home (`homepage`), Category/PLP, Search, Product/PDP | Cart, Checkout, Account, Auth |
+## Workflow
 
-## Route Setup
+1. Create or edit the component (metadata class, props, default export, `fallback`, optional `loader`) under `src/components/<name>/index.tsx`.
+2. Run `pnpm dev` (or `pnpm build`). The Vite plugin scans `src/components` for `@Component` and rewrites the registry between the `STATIC_REGISTRY_START/END` markers.
+3. `pnpm cartridge:generate` writes the metadata JSON (`pnpm build` runs it for you).
+4. `pnpm cartridge:validate` checks the generated JSON against the schemas. Generation also fails on an invalid attribute config (for example a bad `searching` combination).
+5. `pnpm cartridge:deploy` uploads the cartridge to the B2C instance (`pnpm cartridge:deploy -- --delete` removes old cartridge files first). The optional MCP tool `cartridge_deploy` does the same. See `b2c-cli:b2c-code` for credentials and code-version handling.
+6. In Business Manager, merchants build pages from the new palette entries. See [Business Manager](references/BUSINESS-MANAGER.md).
 
-### In the Loader
+## A component
 
-```typescript
-import { fetchPageFromLoader, collectComponentDataPromises } from '@/lib/page-designer';
+```tsx
+// src/components/promo-banner/index.tsx
+import { AttributeDefinition, Component, RegionDefinition } from '@/lib/decorators';
+import { DynamicImage } from '@/components/dynamic-image';
+import { type Image } from '@/types';
+import { cn } from '@/lib/utils';
 
-export function loader(args: LoaderFunctionArgs) {
-    const pagePromise = fetchPageFromLoader(args, { pageId: 'homepage' });
-    const componentData = collectComponentDataPromises(args, pagePromise);
+@Component('promoBanner', {
+    name: 'Promo Banner',
+    description: 'Headline and optional image. Headline text and alignment are editable.',
+    group: 'Content',
+})
+@RegionDefinition([])
+export class PromoBannerMetadata {
+    @AttributeDefinition({ id: 'headline', name: 'Headline', type: 'string', required: true, defaultValue: 'Spring sale' })
+    headline?: string;
 
-    return {
-        page: pagePromise,
-        componentData,
-    };
-}
-```
+    @AttributeDefinition({ id: 'image', name: 'Image', type: 'image' })
+    image?: Image;
 
-### In the Layout
+    @AttributeDefinition({ id: 'align', name: 'Alignment', type: 'enum', values: ['left', 'center'], defaultValue: 'left' })
+    align?: 'left' | 'center';
+}
 
-```typescript
-import { Region } from '@/components/region';
+interface PromoBannerProps {
+    headline?: string;
+    image?: Image;
+    align?: 'left' | 'center';
+    className?: string;
+}
 
-export default function HomePage({ loaderData: { page, componentData } }) {
+// Page Designer also injects component, data, designMetadata and regionId.
+// Never spread them onto a DOM element; destructure them out first if you forward ...rest.
+export default function PromoBanner({ headline = 'Spring sale', image, align = 'left', className }: PromoBannerProps) {
     return (
-        <div>
-            <Region page={page} regionId="hero" componentData={componentData}
-                fallbackElement={<HeroSkeleton />}
-                errorElement={<RegionError />} />
-
-            <Region page={page} regionId="content" componentData={componentData}
-                fallbackElement={<ContentSkeleton />} />
-        </div>
+        <section className={cn('relative', align === 'center' && 'text-center', className)}>
+            {image?.url && <DynamicImage src={image.url} alt="" />}
+            <h2>{headline}</h2>
+        </section>
     );
 }
-```
 
-## Component Setup
-
-### Metadata Class with Decorators
+// REQUIRED. Rendered in a Suspense boundary; receives the same attribute props. Keep it light.
+export function fallback() {
+    return <div className="h-48 animate-pulse bg-muted" />;
+}
+```
 
-```typescript
-import { Component, AttributeDefinition, RegionDefinition } from '@salesforce/storefront-next-runtime/design';
+Rules that matter:
 
-@Component('hero-banner', {
-    name: 'Hero Banner',
-    description: 'Full-width banner with image and CTA'
-})
-class HeroBannerMeta {
-    @AttributeDefinition({ type: 'image' })
-    image: string;
+- Attribute values arrive as props named after the class field, so the field name and `id` must agree.
+- The metadata class must be `export`ed; the generator only sees exported classes.
+- The `typeId` must be a string literal. It is stored as `<group>.<typeId>` (default group `storefrontnext_base`), for example `Content.promoBanner`. Use the `group` option (`Content`, `Layout`, ...) so related components sit together in the palette.
+- An `image` attribute delivers an object (`{ url, focalPoint?, metaData? }`), typed `Image` from `@/types`, not a string. Check `src/components/hero/index.tsx` for the pattern.
+- `name` and `description` are what merchants read in Business Manager; omitted ones fall back to the raw id.
+- Full option tables, attribute types, enums, nested regions and cross-group refs: [Decorator Patterns](references/DECORATOR-PATTERNS.md).
 
-    @AttributeDefinition()
-    headline: string;
+## A loader
 
-    @AttributeDefinition({ type: 'url' })
-    ctaUrl: string;
+Export a callable named `loader` when the component needs data (products, categories, your own API). It receives `{ componentData, context, request }`; `componentData` is the whole SCAPI component object, so merchant-set attributes live at `componentData.data`.
 
-    @AttributeDefinition()
-    ctaText: string;
+```tsx
+// src/components/promo-products/loaders.ts
+import type { LoaderFunctionArgs } from 'react-router';
+import type { ShopperExperience } from '@/scapi';
+import { fetchProductsByIds } from '@/lib/api/products.server';
 
-    @AttributeDefinition({ type: 'boolean' })
-    fullWidth: boolean;
-}
+export const loader = async (args: { componentData: unknown; context: LoaderFunctionArgs['context'] }) => {
+    const comp = args.componentData as ShopperExperience.schemas['Component'];
+    const { productIds } = (comp.data ?? {}) as { productIds?: string };
+    if (!productIds) return null;
+    return fetchProductsByIds(args.context, productIds.split(','));
+};
 ```
 
-### React Component
-
-```typescript
-export default function HeroBanner({ image, headline, ctaUrl, ctaText, fullWidth }) {
-    return (
-        <div className={cn('relative', fullWidth && 'w-full')}>
-            <DynamicImage src={image} alt={headline} />
-            <h1>{headline}</h1>
-            {ctaUrl && <a href={ctaUrl}>{ctaText}</a>}
-        </div>
-    );
-}
+```tsx
+// src/components/promo-products/index.tsx
+export { loader } from './loaders';
+export function fallback() { /* skeleton with reserved height */ }
+export default function PromoProducts({ data }: { data?: Product[] | null }) { /* ... */ }
 ```
 
-See [Decorator Patterns Reference](references/DECORATOR-PATTERNS.md) for all decorator options.
+- The exported `loader` must be a function. An object such as `{ server: fn }` is silently ignored and `data` stays undefined; unwrap it (`export const loader = loaders.server`), as `product-tile/index.tsx` does.
+- The loader runs on the server only (stripped from the client bundle), so it may import `*.server` modules; the component file must not. An optional `clientLoader` export is client-only.
+- Return `null` when nothing is configured, fetch in parallel with `Promise.all`, and let errors propagate so only that component is hidden.
+- The registry records `{ loader: 'loader' }` and `{ fallback: 'fallback' }` capability flags for you on regeneration.
 
-### Components with Server Data
+More on the registry shape, group-qualified ids, preload manifest and entry wiring: [Registry and Loading](references/COMPONENT-REGISTRY.md).
 
-If a component needs server data (e.g., product carousel):
+## A page route
 
-```typescript
-// Export a loader for the component
-export function loader({ componentData, context }) {
-    const clients = createApiClients(context);
-    return clients.shopperProducts.getProducts({
-        params: { query: { ids: componentData.productIds } }
-    }).then(({ data }) => data);
-}
+Routes bind a URL to a Page Designer page template and render its regions. Routes with `@PageType` today: home (`_app._index.tsx`), PLP (`_app.c.$.tsx`), PDP (`_app.p.$.tsx`), search (`_app.search.tsx`), about-us (`_app.about-us.tsx`), and the component preview route. Cart, checkout, account and auth do not use Page Designer.
 
-// Optional fallback during loading
-export function fallback() {
-    return <CarouselSkeleton />;
+```tsx
+import { Region } from '@/components/region';
+import { PageType } from '@/lib/decorators/page-type';
+import { RegionDefinition } from '@/lib/decorators/region-definition';
+import { fetchPageWithComponentData } from '@/lib/page-designer/page-loader.server';
+
+@PageType({
+    name: 'Landing Page',
+    description: 'Campaign landing page with a banner and a main content area',
+    supportedAspectTypes: [],
+})
+@RegionDefinition([
+    { id: 'banner', name: 'Banner Region', maxComponents: 1 },
+    { id: 'main', name: 'Main Region' },
+])
+export class LandingPageMetadata {}
+
+export function loader(args: Route.LoaderArgs) {
+    return { page: fetchPageWithComponentData(args, { pageId: 'landing' }) };
 }
 
-// Component receives data as prop
-export default function ProductCarousel({ data, ...props }) {
-    return <Carousel products={data.products} />;
+export default function Landing({ loaderData }: Route.ComponentProps) {
+    return (
+        <>
+            <Region page={loaderData.page} regionId="banner" />
+            <Region page={loaderData.page} regionId="main" />
+        </>
+    );
 }
 ```
 
-See [Component Registry Reference](references/COMPONENT-REGISTRY.md) for registry details.
-
-## Design Mode
+- Fetch by `{ pageId }` for a fixed page, or by aspect: `{ aspectType: 'pdp', productId, categoryId? }` and `{ aspectType: 'plp', categoryId }`. The `aspectType` passed to the fetch must agree with `@PageType.supportedAspectTypes` (`['pdp']`, `['plp']`, or `[]` for fixed-page routes such as home); a mismatch shows the wrong template in Business Manager with no error.
+- `fetchPageWithComponentData` attaches the per-component loader promises to the page (`page.componentData`). `<Region>` reads them itself; it takes no `componentData` prop, and the loader returns just `{ page }`. It resolves to `null` when the page is missing (404) or SCAPI errors, so empty regions are the normal unconfigured state.
+- `<Region page={...}>` accepts a promise and renders in Suspense. Add `fallbackElement` only for a visible skeleton.
+- Add `critical` to a page-level region only for above-the-fold or LCP content, and only with an awaited page (`page: await fetchPageWithComponentData(...)`), as `_app._index.tsx` does. Never on below-the-fold or catch-all regions. Details in [Registry and Loading](references/COMPONENT-REGISTRY.md).
+- Nested regions inside a component use component mode, synchronously: `<Region component={component} regionId="content" />`. No Suspense wrapper, no `fallbackElement`, no promises. See `src/components/grid/index.tsx`.
+- Do not use `errorElement` to render hard-coded content for an unconfigured page: it defeats merchant control and forces loaders to fetch data only for the fallback. The home route still contains such an `errorElement`; do not copy it. Use `fallbackElement` for loading and render nothing for empty.
+- Metadata classes on routes are empty, exported, and never carry `@AttributeDefinition`.
 
-Detect when running inside Page Designer:
+## Design and preview mode
 
-```typescript
-import { isDesignModeActive, isPreviewModeActive } from '@salesforce/storefront-next-runtime/design/mode';
+Business Manager loads your storefront in an iframe. In loaders use `isDesignModeActive(request)` / `isPreviewModeActive(request)` (the page loader already does and switches to the `pageId`/`pdToken` passed by Business Manager). In components use `usePageDesignerMode()` from `@salesforce/storefront-next-runtime/design/react/core`. `PageDesignerInit` (`src/page-designer-init.tsx`, rendered by `root.tsx`) blocks link navigation while editing and loads design-mode styles; do not remove it.
 
-// In loaders
-const isDesignMode = isDesignModeActive(request);
-const isPreview = isPreviewModeActive(request);
-
-// Root layout exposes pageDesignerMode in loader data
-// 'EDIT' | 'PREVIEW' | undefined
-```
+## Verify before you finish
 
-## MCP Tools
+- [ ] Metadata class exported; `typeId` literal; `group` set; every attribute has `name`, `description`, correct `type`
+- [ ] Default export is the component; `fallback` exported and lightweight; `loader` (if any) is a function
+- [ ] Every `<Region regionId>` matches a `@RegionDefinition` id, and vice versa
+- [ ] `pnpm cartridge:generate && pnpm cartridge:validate` pass; the component is in `static-registry.ts`
+- [ ] Review against [Review Checklist](references/REVIEW-CHECKLIST.md); symptoms in [Troubleshooting](references/TROUBLESHOOTING.md)
 
-Use the B2C DX MCP server tools for Page Designer development:
-
-1. **`storefront_next_page_designer_decorator`** — Adds decorators to components (auto mode or interactive)
-2. **`storefront_next_generate_page_designer_metadata`** — Generates metadata JSON for Business Manager
-3. **`cartridge_deploy`** — Deploys cartridge to Commerce Cloud
-
-### Typical Workflow
-
-1. Add decorators to component (use `storefront_next_page_designer_decorator` with autoMode)
-2. Generate metadata JSON (`storefront_next_generate_page_designer_metadata`)
-3. Deploy cartridge (`cartridge_deploy`)
-
-## Best Practices
+## Reference Documentation
 
-1. **Keep loaders synchronous** — Return promises for streaming
-2. **Use registry** — Register components with proper `typeId`
-3. **Handle design mode** — Adapt UI when `pageDesignerMode` is `'EDIT'` or `'PREVIEW'`
-4. **Rebuild after changes** — Static registry regenerates at build time
-5. **Use MCP tools** — Faster than hand-writing decorators and metadata
+- [Decorator Patterns](references/DECORATOR-PATTERNS.md) - options, attribute types, regions, page types
+- [Registry and Loading](references/COMPONENT-REGISTRY.md) - static registry, loaders, critical regions, entry wiring
+- [Business Manager](references/BUSINESS-MANAGER.md) - `route` and `aspectTypeIds`, page setup, palette
+- [Review Checklist](references/REVIEW-CHECKLIST.md) - what to check in a component or page route
+- [Troubleshooting](references/TROUBLESHOOTING.md) - component missing, empty, or wrong data
 
 ## Related Skills
 
-- `storefront-next:sfnext-data-fetching` - Loader patterns for Page Designer routes
-- `storefront-next:sfnext-components` - Component development patterns
-- `b2c:b2c-page-designer` - Classic ISML Page Designer (NOT Storefront Next)
-
-## Reference Documentation
-
-- [Decorator Patterns Reference](references/DECORATOR-PATTERNS.md) - All decorator types and options
-- [Component Registry Reference](references/COMPONENT-REGISTRY.md) - Registry setup and component loaders
+- `storefront-next:sfnext-components` - component conventions, shadcn primitives, Storybook
+- `storefront-next:sfnext-data-fetching` - loaders, `createApiClients`, streaming with Suspense/Await
+- `storefront-next:sfnext-scapi` - calling SCAPI from loaders and actions
+- `storefront-next:sfnext-performance` - LCP, preload, critical data
+- `storefront-next:sfnext-theming` - tokens and brand styling for new components
+- `storefront-next:sfnext-testing` - component and story tests
+- `storefront-next:sfnext-deployment` - shipping the storefront bundle
+- `figma-to-sfnext-pagedesigner:figma-to-sfnext-pagedesigner` - Figma frame to Page Designer blocks
+- `b2c:b2c-page-designer` - classic (ISML/SFRA) Page Designer
+- `b2c-cli:b2c-code` - deploying cartridges and code versions

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

@@ -0,0 +1,46 @@
+# Business Manager Integration
+
+How code becomes something merchants can use. The long-form version is the "Business Manager Integration" section of `docs/README-PAGE-DESIGNER.md`.
+
+## What gets generated
+
+`pnpm cartridge:generate` (also part of `pnpm build`) scans your decorators and writes JSON under `cartridges/app_storefrontnext_base/cartridge/experience/`:
+
+| Folder | Source | Content |
+|--------|--------|---------|
+| `components/<group>/<typeId>.json` | `@Component` + `@AttributeDefinition` + `@RegionDefinition` | Palette entries and their attribute editors |
+| `pages/<name>.json` | `@PageType` + `@RegionDefinition` on a route | Page templates, with `route` and `aspectTypeIds` |
+| `aspects/*.json` | aspect types (`pdp`, `plp`) | Aspect definitions for product and category pages |
+
+Never hand-edit these files; regenerate. `pnpm cartridge:validate` checks them against the schemas. `pnpm cartridge:deploy` uploads the cartridge; `pnpm cartridge:deploy -- --delete` clears old cartridge files first.
+
+The first time you set up an instance, `sfnext setup-base-cartridge --slas-client-id <id>` registers what the base cartridge needs on your SLAS client (see `docs/README-EMAIL-CARTRIDGE.md` in your project and `b2c-cli:b2c-slas`).
+
+## `route` and `aspectTypeIds`
+
+The generated page JSON carries two fields that tie a route to Business Manager:
+
+- `route`: the URL pattern Business Manager loads in its preview iframe, with `:param` placeholders replaced by the product, category or search term the merchant selected (for example `/:siteId/:localeId/product/:productId`, `/:siteId/:localeId/category/:categoryId`, `/:siteId/:localeId`). It comes from the route file, so a renamed route file changes it on the next generate.
+- `aspectTypeIds`: from `@PageType.supportedAspectTypes`. It decides which page templates are offered when a merchant creates a page for a product (`pdp`) or category (`plp`). An empty array means the template is for a fixed page.
+
+The route's loader must fetch with the same aspect the decorator advertises (`fetchPageWithComponentData(args, { aspectType: 'pdp', productId })` with `supportedAspectTypes: ['pdp']`). This cross-file agreement is the most common page-level bug and produces no error, only the wrong template in Business Manager.
+
+## Merchant setup checklist
+
+After deploying the cartridge:
+
+1. Make sure the cartridge is on the cartridge path of the site and the active code version holds the upload.
+2. If the storefront was created outside Business Manager, connect it to Business Manager so Page Designer and Storefront Preview can see it (Administration > Sites > Storefronts > Connect Existing; needs an administrator role; confirm current steps in the Salesforce Storefront Next documentation).
+3. Merchant Tools > Content > Page Designer: create a page, choose the template (page type) that matches the route, add components to its regions.
+4. For aspect pages, assign the page to the product or category; for fixed pages, use the `pageId` your loader requests (for example `homepage`, `aboutus`).
+5. Publish, then check the storefront. A `null` page (missing or unpublished) renders empty regions rather than an error.
+
+## Design vs preview mode
+
+Business Manager opens your storefront with `mode` and `pdToken` query parameters. `fetchPageFromLoader` switches to the page Business Manager specifies while in these modes, and `PageDesignerInit` blocks link navigation in edit mode. Keep both; neither needs changes when you add components.
+
+## Where to look next
+
+- Component missing or empty: [Troubleshooting](TROUBLESHOOTING.md)
+- Deploy credentials and code versions: `b2c-cli:b2c-code`, `b2c-cli:b2c-webdav`
+- Pushing the storefront bundle itself: `storefront-next:sfnext-deployment`

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

@@ -1,78 +1,111 @@
-# Component Registry Reference
+# Registry and Loading
 
-## Overview
+## The static registry
 
-The component registry maps Page Designer `typeId` values to React components. The registry is **auto-generated** at build time by the staticRegistry Vite plugin.
+`src/lib/page-designer/static-registry.ts` maps fully-qualified component ids to lazy importers. The `staticRegistry` Vite plugin generates it from every `@Component` under `src/components` when `pnpm dev` or `pnpm build` starts, and again on hot updates. Everything between `// STATIC_REGISTRY_START` and `// STATIC_REGISTRY_END` is overwritten; do not edit it by hand and do not add entries manually.
 
-## Static Registry
+Shape of the generated code (your file lists your project's components):
 
-The file `src/lib/static-registry.ts` is generated automatically. **Do not edit it by hand.** The Vite plugin scans for components with `@Component` decorators and builds the registry.
+```typescript
+const staticRegistryImporters = [
+    () => import('../../components/hero/index'),
+    () => import('../../components/product-carousel/index'),
+    // ...
+] as const;
+
+export function initializeRegistry(targetRegistry = registry): void {
+    targetRegistry.registerImporter('Content.hero', staticRegistryImporters[0]);
+    targetRegistry.registerImporter('Layout.productCarousel', staticRegistryImporters[1], {
+        loader: 'loader',
+        fallback: 'fallback',
+    });
+}
+```
 
-After adding or modifying decorators, rebuild the app to regenerate the registry:
+- Ids are `<group>.<typeId>`, so the `typeId` in `@Component('hero', ...)` plus `group: 'Content'` becomes `Content.hero`. These ids must match what Business Manager sends.
+- The third argument records which named exports the module has: `loader` (server data) and `fallback` (Suspense skeleton). The plugin derives them from your exports.
+- To see which components your project registers, read the generated file rather than relying on a fixed list.
 
-```bash
-pnpm build
-# or during development
-pnpm dev   # Hot reload regenerates automatically
-```
+If a new component is missing from the registry, the usual cause is that it is outside `src/components`, the `@Component` first argument is not a string literal, or the dev server was not running when the file changed. Restart `pnpm dev` or run `pnpm build`.
+
+## Entry wiring (do not break)
 
-## Component Registration
+`initializeRegistry()` is called once at module top level in `src/entry.server.tsx` and synchronously in `src/entry.client.tsx`, before any component markers are scanned. Keep it there; moving it into a React render function breaks registration ordering.
 
-Components are registered by their `@Component` decorator `typeId`:
+`vite-plugins/storefront-next.ts` enables the plugin with:
 
 ```typescript
-// The registry maps typeId -> component module
-// Example auto-generated entry:
-{
-    'hero-banner': () => import('@/components/hero-banner'),
-    'product-carousel': () => import('@/components/product-carousel'),
-    'content-card': () => import('@/components/content-card'),
+staticRegistry: {
+    componentPath: 'src/components',
+    registryPath: 'src/lib/page-designer/static-registry.ts',
+    preloadManifest: true,
 }
 ```
 
-## Component Loaders
+`preloadManifest: true` builds the resource-hint manifest that `critical` regions and per-component preload hints depend on. Keep it on.
+
+## How a page renders
 
-Components that need server data export a `loader` function. The registry calls these loaders during `collectComponentDataPromises()` in the route loader:
+1. The route loader calls `fetchPageWithComponentData(args, params)`.
+2. It fetches the page (SCAPI Shopper Experience, resolved from the Data Store when that middleware is active), walks every region and nested region, and for each component whose registry entry has a `loader` calls it with `{ componentData, context, request }`. The resulting promises are stored as `page.componentData[component.id]`.
+3. `<Region page={page} regionId="..." />` resolves each component's module from the registry, wraps it in Suspense (using the module's `fallback`), awaits that component's promise, and renders the default export with the attribute props plus `data`, `component`, `designMetadata` and `regionId`.
+
+Because data is attached to the page, there is no separate `componentData` return key and no `componentData` prop on `<Region>`.
+
+## Fetching a page
 
 ```typescript
-// In the component file:
-export function loader({ componentData, context }) {
-    const clients = createApiClients(context);
-    const productIds = componentData.productIds;
-
-    return clients.shopperProducts.getProducts({
-        params: { query: { ids: productIds.join(',') } }
-    }).then(({ data }) => data);
-}
+import { fetchPageWithComponentData } from '@/lib/page-designer/page-loader.server';
+
+// Fixed page by id
+fetchPageWithComponentData(args, { pageId: 'homepage' });
+
+// By aspect (page assigned to a product or category in Business Manager)
+fetchPageWithComponentData(args, { aspectType: 'pdp', productId, categoryId });
+fetchPageWithComponentData(args, { aspectType: 'plp', categoryId });
+```
+
+Return the promise unawaited for a non-critical page (React Router streams it), or `await` it when a `critical` region needs the page synchronously. `fetchPageFromLoader` (same module) is the lower-level call that returns the raw page without `componentData`; routes use `fetchPageWithComponentData`.
+
+Single components (for example an embedded content block or the preview route) use `fetchComponentWithComponentData` from `@/lib/page-designer/component-loader.server`.
+
+## Module contract
+
+| Export | Required | Notes |
+|--------|----------|-------|
+| default | yes | The React component. `forwardRef` components are fine. |
+| `fallback` | yes | Lightweight skeleton; gets the same attribute props; reserve dimensions to avoid layout shift. No hooks that suspend, no fetching. |
+| `loader` | optional | Must be a function `({ componentData, context, request }) => Promise`. Server only (stripped from the client bundle). Attributes are at `componentData.data`. |
+| `clientLoader` | optional | Client-only counterpart (stripped from the server bundle). |
+
+A `loader` that is an object (`{ server, client }`) is not callable; the loader never runs and `data` is undefined. Export the function: `export const loader = loaders.server`.
 
-export function fallback() {
-    return <ProductCarouselSkeleton />;
+Loader guidance: return `null` when nothing is configured, fetch independent resources with `Promise.all`, do not swallow errors (the component's error boundary hides only that component), and reuse the shared `@/lib/api/*.server` helpers rather than building SCAPI calls inline.
+
+## Critical regions
+
+By default regions stream: the shell renders, then each component swaps in. For above-the-fold content that must be in the first HTML (hero, LCP image), make the region critical.
+
+```tsx
+export async function loader(args: Route.LoaderArgs) {
+    const page = await fetchPageWithComponentData(args, { pageId: 'homepage' }); // must be resolved
+    const recommendations = fetchRecommendations(args.context);                  // stay deferred
+    return { page, recommendations };
 }
 
-export default function ProductCarousel({ data, ...props }) {
-    // data = resolved result from loader
-    return <div>{data.products.map(p => <ProductTile key={p.id} product={p} />)}</div>;
+export default function Home({ loaderData }: Route.ComponentProps) {
+    return <Region page={loaderData.page} regionId="headerbanner" critical />;
 }
 ```
 
-### Data Flow
+- `critical` is page mode only; nested component regions inherit it.
+- The page must already be resolved; omit `fallbackElement` on a critical region.
+- Each component's own `loader` data still streams inside its local Suspense boundary.
+- Use it sparingly; it delays the initial shell. Never on below-the-fold or catch-all regions.
+- Stylesheets added through a route's `links` export should use `createStorefrontStylesheetLink` from `@salesforce/storefront-next-runtime/design/react/preload` so critical component styles keep a stable cascade order.
 
-```
-Route loader
-  |-- fetchPageFromLoader(args, { pageId })     -> page promise
-  +-- collectComponentDataPromises(args, page)  -> componentData map
-        |
-  For each component with a loader:
-    component.loader({ componentData, context }) -> data promise
-        |
-  <Region> renders components with resolved data
-```
+See "Critical Page Regions" in `docs/README-PAGE-DESIGNER.md` for the full behavior.
 
-## Adding a New Page Designer Component
+## Error handling
 
-1. Create the React component with decorator metadata class
-2. Implement the component's render function
-3. (Optional) Export `loader` and `fallback` if server data is needed
-4. Rebuild to regenerate static registry
-5. Generate metadata JSON via MCP tool (`storefront_next_generate_page_designer_metadata`)
-6. Deploy cartridge via MCP tool (`cartridge_deploy`)
+Do not pass `errorElement` to show hard-coded content when a page is unconfigured. That hides setup problems, forces extra fetches in the loader, and bypasses merchant control. Use `fallbackElement` for loading states, or render nothing when a region is empty. The home route's existing `errorElement` is a legacy pattern; do not copy it to new routes.