@salesforce/b2c-cli 2.3.0 → 2.4.0

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

@@ -0,0 +1,202 @@
+---
+name: sfnext-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 in Storefront Next
+
+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.
+
+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.
+
+## Pieces and where they live
+
+| 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}` |
+
+The runtime package's `/design` entry exports only the registry. Decorators come from your project, not from `@salesforce/storefront-next-runtime`.
+
+## Workflow
+
+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).
+
+## A component
+
+```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';
+
+@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;
+
+    @AttributeDefinition({ id: 'image', name: 'Image', type: 'image' })
+    image?: Image;
+
+    @AttributeDefinition({ id: 'align', name: 'Alignment', type: 'enum', values: ['left', 'center'], defaultValue: 'left' })
+    align?: 'left' | 'center';
+}
+
+interface PromoBannerProps {
+    headline?: string;
+    image?: Image;
+    align?: 'left' | 'center';
+    className?: string;
+}
+
+// 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 (
+        <section className={cn('relative', align === 'center' && 'text-center', className)}>
+            {image?.url && <DynamicImage src={image.url} alt="" />}
+            <h2>{headline}</h2>
+        </section>
+    );
+}
+
+// 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" />;
+}
+```
+
+Rules that matter:
+
+- 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).
+
+## A loader
+
+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`.
+
+```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';
+
+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(','));
+};
+```
+
+```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 }) { /* ... */ }
+```
+
+- 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.
+
+More on the registry shape, group-qualified ids, preload manifest and entry wiring: [Registry and Loading](references/COMPONENT-REGISTRY.md).
+
+## A page route
+
+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.
+
+```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' }) };
+}
+
+export default function Landing({ loaderData }: Route.ComponentProps) {
+    return (
+        <>
+            <Region page={loaderData.page} regionId="banner" />
+            <Region page={loaderData.page} regionId="main" />
+        </>
+    );
+}
+```
+
+- 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`.
+
+## Design and preview 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.
+
+## Verify before you finish
+
+- [ ] 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)
+
+## Reference Documentation
+
+- [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-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

@@ -0,0 +1,111 @@
+# Registry and Loading
+
+## The static registry
+
+`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.
+
+Shape of the generated code (your file lists your project's components):
+
+```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',
+    });
+}
+```
+
+- 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.
+
+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)
+
+`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.
+
+`vite-plugins/storefront-next.ts` enables the plugin with:
+
+```typescript
+staticRegistry: {
+    componentPath: 'src/components',
+    registryPath: 'src/lib/page-designer/static-registry.ts',
+    preloadManifest: true,
+}
+```
+
+`preloadManifest: true` builds the resource-hint manifest that `critical` regions and per-component preload hints depend on. Keep it on.
+
+## How a page renders
+
+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
+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`.
+
+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 Home({ loaderData }: Route.ComponentProps) {
+    return <Region page={loaderData.page} regionId="headerbanner" critical />;
+}
+```
+
+- `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.
+
+See "Critical Page Regions" in `docs/README-PAGE-DESIGNER.md` for the full behavior.
+
+## Error handling
+
+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.

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

@@ -0,0 +1,168 @@
+# Decorator Patterns
+
+All four decorators are imported from your project, not from the runtime package:
+
+```typescript
+import { AttributeDefinition, Component, PageType, RegionDefinition } from '@/lib/decorators';
+```
+
+Deep imports (`@/lib/decorators/component`, `.../attribute-definition`, `.../page-type`, `.../region-definition`) also work and are used by some shipped files.
+
+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.
+
+## `@Component(typeId, options)`
+
+```typescript
+@Component('productCarousel', {
+    name: 'Product Carousel',
+    description: 'Scrollable row of product cards. Pick a category or add product tiles.',
+    group: 'Layout',
+})
+```
+
+| 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. |
+
+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(config)`
+
+Put it on a field of the exported metadata class. The field name is the prop name your component receives.
+
+```typescript
+@AttributeDefinition({
+    id: 'limit',
+    name: 'Product Limit',
+    description: 'Maximum number of products to show.',
+    type: 'integer',
+    required: false,
+    defaultValue: 12,
+})
+limit?: number;
+```
+
+| 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. |
+
+### Attribute types
+
+`string`, `text`, `markup`, `integer`, `boolean`, `product`, `category`, `file`, `page`, `image`, `url`, `enum`, `custom`, `cms_record`.
+
+| 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 |
+
+### `searching` combinations
+
+Generation fails (and `cartridge:validate` reports it) when the combination is invalid:
+
+- `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(regions)`
+
+Declares the slots a component (or a page route) exposes to merchants.
+
+```typescript
+@RegionDefinition([
+    {
+        id: 'products',
+        name: 'Products',
+        description: 'Add Product Tile components to populate this carousel.',
+        maxComponents: 12,
+        componentTypeInclusions: ['Content.productTile'],
+    },
+])
+```
+
+| 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.
+
+## `@PageType(config)`
+
+```typescript
+@PageType({
+    name: 'Product Detail Page',
+    description: 'Product detail page with promotional and engagement regions',
+    supportedAspectTypes: ['pdp'],
+})
+@RegionDefinition([{ id: 'pdpPromo', name: 'Promo Content Region', maxComponents: 1 }])
+export class ProductPageMetadata {}
+```
+
+| 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. |
+
+The class must be exported and empty. Never put `@AttributeDefinition` on a page type.
+
+`sfnext generate-cartridge` parses decorators statically, so decorator arguments must be literals, not imported constants.
+
+## Nested regions in a container
+
+```tsx
+import { Region } from '@/components/region';
+
+@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 TwoColumn({ component }: { component: ComponentType }) {
+    return (
+        <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.