@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/node_modules/@salesforce/b2c-agent-plugins/figma-to-sfnext-pagedesigner/skills/figma-to-sfnext-pagedesigner/SKILL.md

@@ -0,0 +1,444 @@
+---
+name: figma-to-sfnext-pagedesigner
+description: Convert a Figma frame into one or more live Storefront Next Page Designer blocks in one shot. Use whenever the user provides a Figma URL and wants the design to become merchant-authorable Page Designer components in a Storefront Next project. Requires the Figma MCP server (and a browser MCP for visual validation).
+---
+
+# Skill: figma-to-sfnext-pagedesigner
+
+Convert a Figma frame into one or more live Storefront Next Page Designer blocks in one shot.
+
+**One block per section.** Inspect the top-level frame and identify distinct visual sections (hero, feature strip, product row, footer band, etc.). Each section becomes its own PD component with its own file, typeId, and decorator. Run Phases 1–4 once per section before moving to the next.
+
+## Prerequisites
+
+- **Figma MCP server** configured in your AI tool — the skill reads design context through it. Without it, the skill can only act as a manual checklist.
+- **Browser MCP** (Playwright or similar) — for the Phase 5 visual validation. Optional but recommended.
+- A **Storefront Next** project in a git repo, with the `sfnext` CLI available (`pnpm sfnext …`).
+- `gh` CLI authenticated (`gh auth status`) if you want the skill to clone/push for you.
+- A Figma frame URL that includes a `node-id`.
+
+## When to use
+
+Invoke this skill (`/figma-to-sfnext-pagedesigner`) whenever the user provides a Figma URL and wants the design to become a merchant-authorable Page Designer component in a Storefront Next project.
+
+Do NOT invoke this when:
+- The user only wants React/Tailwind code (no PD integration needed) — use the `figma-design-to-code` skill directly.
+- The target project is SFRA/ISML, not Storefront Next.
+
+---
+
+## Required inputs (ask if missing)
+
+| Input | Example |
+|---|---|
+| Figma node URL (must include `node-id`) | `https://www.figma.com/design/abc123/...?node-id=1-2` |
+| Git repo URL (or a local path to the project) | `https://github.com/org/my-storefront` |
+| PD group (palette folder) | `Content` |
+| Target branch | `main` or a feature branch name |
+
+Do not ask the user for typeIds, display names, or descriptions upfront — derive these from the section names discovered in the frame and confirm them in the approval gate (Phase 1, step 4).
+
+If the Figma URL has no `node-id` query param, stop and ask the user to select the frame in Figma and copy the link — never guess a node ID.
+
+### Repo setup
+
+If the repo is not already cloned locally, run:
+```bash
+gh repo clone <github-url>
+cd <repo-name>
+pnpm install
+```
+
+Check out the target branch (or create a feature branch if pushing directly to main is not appropriate):
+```bash
+git checkout -b feat/pd-blocks-from-figma
+```
+
+All file writes in Phases 1–3 operate on this local clone.
+
+---
+
+## Pre-flight reads (do these before writing any code)
+
+1. Read `references/PAGE-DESIGNER-SFN.md` (bundled alongside this skill) — mental model for PD + Storefront Next.
+2. Read the `figma-design-to-code` skill (from the official Figma plugin, if installed) — it governs correct `get_design_context` usage. If it isn't available, fall back to `get_design_context` + a screenshot and treat the design tokens as reference only.
+3. Read `src/theme/tokens/brand.css` — know which design tokens exist AND their current values, so you can spot where the Figma design diverges and needs a token update (Phase 1b.1), not just which classes are available.
+4. Scan `src/components/` — identify shared atoms to reuse rather than rebuild.
+
+---
+
+## Phase 1 — Section plan + authorable field approval (STOP FOR USER SIGN-OFF)
+
+**Goal:** before writing any code, show the user exactly what blocks will be created and what merchants will be able to edit in each one. Do not proceed to Phase 2 until the user approves.
+
+### 1a — Identify sections
+
+Call `get_design_context` on the top-level frame. Scan the returned structure and screenshot to identify distinct visual sections (e.g. hero, feature strip, product row, testimonial, footer band). Each becomes one PD block.
+
+List them:
+
+```
+Sections detected:
+  1. Hero Banner        → typeId: heroBanner        file: hero-banner
+  2. Feature Strip      → typeId: featureStrip       file: feature-strip
+  3. Product Row        → typeId: productRow         file: product-row
+```
+
+Propose typeId and file name for each. The user can rename before approving.
+
+### 1b — For each section, list proposed authorable fields with default values
+
+Show a table per block. Include a **Default value** column populated from the actual content visible in the Figma design — this is what merchants will see pre-filled when they first drag the block onto a page:
+
+```
+── Hero Banner (heroBanner) ──────────────────────────────────
+  Field label       Prop name        PD type  Req?  Default value
+  ---------------------------------------------------------------
+  Headline          headline         string   yes   "Fresh Drops This Week"
+  Subheading        subheading       string   no    "New styles just landed"
+  Background Image  backgroundImage  image    yes   (empty — library asset needed)
+  CTA Label         ctaLabel         string   no    "Shop Now"
+  CTA URL           ctaUrl           url      no    (empty — real URL needed)
+  Dark text?        isDarkText       boolean  no    false
+
+── Feature Strip (featureStrip) ──────────────────────────────
+  ...
+```
+
+**Default value rules:**
+- String and markup fields: copy the literal text visible in the Figma frame.
+- Boolean fields: infer from the design state shown (dark overlay visible → `true`).
+- `image`, `url`, `product`, `category` types: leave empty — these require live assets the Figma mock cannot supply. Note them as "(empty — needs real asset)" so the merchant knows to fill them.
+
+For each field, apply type inference:
+- `*Url`, `*Link`, `*Href` → `url`
+- `*Image`, `*Img`, `*Src`, `*Photo` → `image`
+- `is*`, `show*`, `has*`, `enable*` → `boolean`
+- `*Count`, `*Num`, `max*`, `min*` → `integer`
+- Long body copy / rich text → `markup`
+- Product reference → `product`; category reference → `category`
+- Anything else → `string`
+
+Mark layout-only props (padding, rotation, shadow) as **hardcoded** — do not list them as fields.
+
+**Product detection:** if the section shows product cards, product names, prices, star ratings, or imagery that looks like it comes from a catalog (not a static hero image), flag it as `needs_server_loader = true` and list one `product` type field per slot (e.g. `Product 1`, `Product 2`). Do not try to carry product IDs as default values — those fields must be filled by the merchant in PD.
+
+### 1b.1 — Reconcile brand tokens against the design
+
+Walking a Figma design into the codebase is **not just adding new components — it also means updating the base design tokens the whole storefront already uses** wherever the design diverges from them. This is easy to miss: you build the new block correctly against existing tokens, but the design actually specifies a *different* primary color / radius / font, and the existing token is now wrong. The block looks right; the rest of the storefront (buttons, links, focus rings) is now off-brand.
+
+For each section, before finalizing fields, compare the Figma design's core visual values against what's in `src/theme/tokens/brand.css` (and any shadcn/tailwind theme vars — `--primary`, `--accent`, `--background`, `--foreground`, `--radius`, font families):
+
+- **Primary / accent / brand colors** — if the Figma design's buttons, links, or highlights use a color that differs from the current `--primary` / `--accent` token value, that's a **token update**, not a per-component override. Do NOT hardcode the new hex in the block; update the token so every existing component (buttons, badges, focus states) inherits it.
+- **Typography** — heading/body font family, weights, and scale. If the design uses a different type family than the token defines, flag the font token for update.
+- **Radius, spacing scale, shadows** — if consistently different across the design, treat as token updates.
+
+Produce a **token diff table** for the approval gate:
+
+```
+── Token reconciliation ──────────────────────────────────────
+  Token             Current (brand.css)   Figma design    Action
+  --------------------------------------------------------------
+  --primary         #1f2a44               #E11D48         UPDATE (primary buttons are pink in design)
+  --radius          0.5rem                0.75rem         UPDATE
+  --font-heading    "Inter"               "Playfair"      UPDATE
+  --accent          #f5a623               #f5a623         keep (matches)
+```
+
+**Rules:**
+- Prefer a token update over a per-component hardcoded value whenever the changed value is something shared components already consume (button color, link color, radius, font). A one-off color used only in this one block stays local to the block.
+- Never silently hardcode a hex that contradicts an existing token — that leaves the storefront half-rebranded.
+- If unsure whether a divergence is intentional (design drift vs. a deliberate one-off), list it in the table and ask in the approval gate rather than guessing.
+
+### 1c — STOP. Present to user and wait for approval.
+
+Output the section plan, all field tables, **and the token reconciliation table (1b.1)**, then explicitly ask:
+
+> "Does this look right? You can add fields, remove fields, change types, rename labels, merge/split sections, or adjust which token updates to apply before I start writing code."
+
+**Do not write any files until the user confirms.** Accept freeform corrections — e.g. "make headline required", "add a body copy field to Hero as markup", "merge sections 2 and 3 into one block", "drop the boolean, that's always dark".
+
+Update the tables to reflect corrections, then confirm once more if changes were substantial. When the user says go, lock the field plan and proceed to Phase 2.
+
+### 1d — Apply approved token updates, then write the React component (after approval)
+
+**First, apply any token updates approved in 1b.1.** Edit `src/theme/tokens/brand.css` (and any theme var file) to the new values *before* writing components, so the new block and all existing components render against the corrected tokens. This is a real edit to the base design — commit it alongside the new component in Phase 4.
+
+Then, for each section, write `src/components/<name>/index.tsx`:
+- Props typed as a plain TypeScript interface — all approved authorable fields plus any layout-only props needed for rendering.
+- No decorator imports yet.
+- Use brand tokens from `brand.css` as Tailwind utilities or CSS variables — no hardcoded hex. If the design needed a shared value changed (primary color, radius, font), that lives in the updated token, not in the component.
+- Reuse existing shared components where they match design intent.
+
+---
+
+## Phase 2 — PD decorator metadata class (decorator mode only)
+
+**Goal:** add the metadata class that tells Page Designer what attributes exist. Do not touch the React JSX.
+
+Using the approved field plan from Phase 1, edit `src/components/<name>/index.tsx`:
+
+### 2a — Imports (add at top)
+
+```tsx
+import { Component } from '@/lib/decorators/component';
+import { AttributeDefinition } from '@/lib/decorators/attribute-definition';
+import { RegionDefinition } from '@/lib/decorators';
+```
+
+### 2b — Metadata class (insert above the default export)
+
+```tsx
+/* v8 ignore start */
+@Component('typeId', { name: 'Display Name', description: 'Description', group: 'Content' })
+@RegionDefinition([])
+export class <Name>Metadata {
+    @AttributeDefinition({ id: 'headline', name: 'Headline', type: 'string', required: true, defaultValue: 'Fresh Drops This Week' })
+    headline?: string;
+
+    @AttributeDefinition({ id: 'ctaLabel', name: 'CTA Label', type: 'string', required: false, defaultValue: 'Shop Now' })
+    ctaLabel?: string;
+
+    @AttributeDefinition({ id: 'backgroundImage', name: 'Background Image', type: 'image', required: true })
+    backgroundImage?: string;
+}
+/* v8 ignore end */
+```
+
+Rules:
+- Set `defaultValue` for every `string`, `markup`, and `boolean` field using the value from the approved field plan.
+- Do **not** set `defaultValue` on `image`, `url`, `product`, or `category` fields — these require real assets the Figma mock cannot provide.
+- Only include props marked authorable in the plan. Layout props are not attributes.
+
+### 2c — Attribute type inference
+
+Apply these rules to each authorable prop name:
+
+| Prop name pattern | PD attribute type |
+|---|---|
+| `*Url`, `*Link`, `*Href` | `url` |
+| `*Image`, `*Img`, `*Src`, `*Photo` | `image` |
+| `is*`, `show*`, `has*`, `enable*` | `boolean` |
+| `*Count`, `*Num`, `max*`, `min*` | `integer` |
+| Long body copy / rich text | `markup` |
+| Anything else | `string` |
+
+For product reference props → `product`. For category reference props → `category`.
+
+### 2d — Regions (if has_regions = true)
+
+Replace `@RegionDefinition([])` with named slot configs:
+
+```tsx
+@RegionDefinition([
+    { id: 'main', name: 'Main Content', description: 'Primary content area', maxComponents: 10 },
+])
+```
+
+### 2e — Product data (if the Figma section shows product cards, product names, prices, or imagery sourced from a catalog)
+
+When a Figma section contains product data, the merchant should supply a product ID in PD and the component fetches live catalog data at render time.
+
+**Decorator:** add a `product` type attribute for each product slot:
+
+```tsx
+@AttributeDefinition({ id: 'productId', name: 'Product', type: 'product', required: true })
+productId?: string;
+```
+
+For multi-product blocks (e.g. a 3-up product row), use indexed slots:
+
+```tsx
+@AttributeDefinition({ id: 'product1Id', name: 'Product 1', type: 'product', required: true })
+product1Id?: string;
+
+@AttributeDefinition({ id: 'product2Id', name: 'Product 2', type: 'product', required: false })
+product2Id?: string;
+```
+
+**Loader** — the thing the registry imports as `loader` MUST be a callable function. A top-level async function is the simplest correct shape:
+
+```tsx
+export async function loader({ componentData, context }: { componentData: any; context: any }) {
+    const productId: string = componentData.data?.productId
+    if (!productId) return null
+
+    const product = await context.shopperProducts.getProduct({
+        parameters: { id: productId, allImages: true },
+    })
+    return { product }
+}
+```
+
+**⚠️ The #1 silent failure: exporting a non-callable as `loader`.** If the export named `loader` is anything other than a function, the registry gets a non-callable, the loader never runs, `data` is `undefined`, and the component's `return null` fallback hides the block entirely — with **no error**. You just see an empty space where the block should be.
+
+Two ways this bites:
+1. **The `{ server: fn }` object shape.** Some loaders are authored as `export const loader = { server: dataLoader }`. That object is not callable.
+2. **Re-exporting the raw object.** `export { loader } from './loaders'` in `index.tsx` re-exports whatever `loaders.ts` called `loader` — if that was the `{ server: fn }` object, you've just re-exported a non-callable. This is the trap: it *looks* wired up.
+
+**Correct convention:** the file the registry imports must ultimately export a callable `loader`. Either author it as a plain function (above), or unwrap the object at the export boundary:
+
+```tsx
+// in loaders.ts — export the callable directly, not the wrapper object
+export const loader = dataLoader
+
+// OR, if a { server: fn } object already exists, unwrap it where you export:
+// index.tsx
+import * as loaders from './loaders'
+export const loader = loaders.server   // ✅ callable — NOT `export { loader } from './loaders'`
+```
+
+**Before committing a product block, verify the export is callable** — e.g. `import { loader } from './index'; typeof loader === 'function'`. If it's `'object'`, it's the wrapper bug.
+
+For multi-product blocks, fetch in parallel:
+
+```tsx
+export async function loader({ componentData, context }: { componentData: any; context: any }) {
+    const ids = ['product1Id', 'product2Id', 'product3Id']
+        .map((k) => componentData.data?.[k] as string)
+        .filter(Boolean)
+
+    const products = await Promise.all(
+        ids.map((id) =>
+            context.shopperProducts.getProduct({
+                parameters: { id, allImages: true },
+            })
+        )
+    )
+    return { products }
+}
+```
+
+**React component** receives `data` (loader return) alongside the PD attributes. Destructure both from props:
+
+```tsx
+export default function ProductRow({ product1Id, data }: ProductRowProps & { data?: { products: Product[] } }) {
+    const products = data?.products ?? []
+    // render product cards from products array
+}
+```
+
+**Flag `needs_server_loader = true`** in the prop triage and add `{ loader: 'loader' }` to the registry entry (Phase 3).
+
+**Fallback skeleton:** for product blocks, export a skeleton so the Suspense boundary shows something while the loader runs:
+
+```tsx
+export function fallback() {
+    return <div className="animate-pulse bg-muted h-64 w-full rounded" />
+}
+```
+
+Register it: `{ loader: 'loader', fallback: 'fallback' }`
+
+---
+
+## Phase 3 — Registry
+
+Add one import line to `src/lib/page-designer/static-registry.ts`.
+
+Find the block where `registerImporter` calls are grouped (they are alphabetical by group then typeId in practice) and insert:
+
+```ts
+targetRegistry.registerImporter(
+    'Group.typeId',
+    () => import('../../components/<name>/index')
+);
+```
+
+If the component has a loader, add the second argument:
+
+```ts
+targetRegistry.registerImporter(
+    'Group.typeId',
+    () => import('../../components/<name>/index'),
+    { loader: 'loader' }
+);
+```
+
+---
+
+## Phase 4 — Commit and deploy
+
+### 4a — Generate cartridge JSON locally (pre-commit validation)
+
+```bash
+pnpm cartridge:generate
+```
+
+Confirm the expected JSON files were written under `cartridges/`. If this fails, fix before committing — a broken decorator parse blocks the deploy too.
+
+### 4b — Commit
+
+Commit the new component file(s), the registry edit, the generated cartridge JSON, **and any token updates from Phase 1d**. If the token changes were substantial, keep them in a separate commit (e.g. `chore: align brand tokens with Figma design`) so the rebrand is reviewable on its own.
+
+### 4c — Deploy
+
+Two commands make the block live — run them directly against the target instance/environment:
+
+1. **Cartridge deploy** (`pnpm cartridge:deploy` / `sfnext deploy-cartridge`) — uploads the cartridge JSON to B2C. The new component types appear in the Page Designer palette after this.
+
+2. **MRT deploy** (`pnpm push` / `sfnext push`) — deploys the storefront bundle to MRT so the new React components render. If the project sets `GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH = true`, the cartridge deploy runs automatically as part of `pnpm push`.
+
+Then tell the user: open Business Manager → Page Designer → the target page, and the new blocks appear in the component palette ready to author — text fields pre-filled with the copy from the Figma design; they just swap in real images, URLs, and product IDs.
+
+If a deploy command fails, re-run it with `--log-level trace` for full diagnostics, and consult the `b2c` and `b2c-cli` skills (if installed) — they cover auth, WebDAV, and deploy troubleshooting in depth.
+
+---
+
+## Phase 5 — Verify
+
+### 5a — Cartridge and palette check
+
+1. Confirm the cartridge JSON was written:
+   ```
+   cartridges/app_storefrontnext_base/cartridge/experience/components/<Group>/<typeId>.json
+   ```
+2. If browser MCP is available: open Business Manager → Merchant Tools → Content → Experience Manager → Page Designer, confirm each component appears in the component palette under its group.
+
+### 5b — Visual design match (Chrome)
+
+This step is **required** when a browser MCP is available. Do a side-by-side design fidelity check:
+
+1. Start `pnpm dev` and navigate to the route that includes the new blocks.
+2. Take a screenshot of the rendered page in Chrome.
+3. Take a screenshot of the original Figma frame (via `get_screenshot` or the design context screenshot captured in Phase 1).
+4. Compare them. For each block, check:
+   - Typography (weight, size, colour, line-height)
+   - Spacing and layout proportions
+   - Image/media placement
+   - Brand token colours (no regressions to wrong colour values) — **including shared elements the design also restyles: primary/secondary buttons, links, badges, focus rings. If a button in the design is a different colour than the storefront currently renders, that's a token miss from Phase 1b.1, not a per-block fix.**
+   - Product blocks: confirm the block actually rendered with data (not an empty/hidden fallback — the loader-callable bug in Phase 2e produces a silent blank).
+   - Mobile breakpoint if the Figma includes a mobile frame
+5. **Report the diff to the user.** List any visible discrepancies with the prop, token, or CSS class responsible. If a fix belongs in a token rather than the component, say so.
+6. Fix discrepancies in the React component, then re-screenshot until the match is acceptable. Do not mark the skill complete with known visual gaps.
+
+If `pnpm dev` is not running or browser MCP is unavailable, explicitly tell the user that visual validation was skipped and they should do it manually before authoring in Production Page Designer.
+
+---
+
+## Failure modes and recovery
+
+| Symptom | Fix |
+|---|---|
+| `get_design_context` returns no Code Connect hints | Project has no `.figma.ts` files yet — use raw design tokens and screenshot as reference only. |
+| `cartridge:generate` exits with decorator parse error | The metadata class must be a `class` (not interface) and decorators must be on class fields, not function params. |
+| Component not appearing in PD palette after deploy | Check BM → Administration → Site Development → Development Setup for cartridge assignment; the storefront cartridge must be in the cartridge path. |
+| `cartridge:deploy` / `push` fails (auth, WebDAV, or connection error) | Re-run the command with `--log-level trace` for full diagnostics, and consult the `b2c` / `b2c-cli` skills (if installed) — they cover auth and deploy troubleshooting. |
+| `markup` type attribute renders as escaped HTML | Use `dangerouslySetInnerHTML={{ __html: props.bodyText }}` for markup-typed attributes — they send raw HTML. |
+| Registry entry causes a Vite HMR error | Ensure the import path resolves — run `pnpm build` to get a full error trace. |
+| Product block renders as a blank/empty space, no error | The export named `loader` is not callable (a `{ server: fn }` object, or `export { loader } from './loaders'` re-exporting that object). The loader never runs, `data` is `undefined`, and `return null` hides the block. Fix: export a callable — `export const loader = loaders.server` or a plain `export async function loader(...)`. Verify with `typeof loader === 'function'`. See Phase 2e. |
+| New block looks right but the rest of the storefront is off-brand (wrong button colour, radius, font) | A shared value in the Figma design diverged from an existing token and was missed. Update the token in `src/theme/tokens/brand.css` (Phase 1b.1 / 1d), don't hardcode it in the block. |
+
+---
+
+## Canonical example (structure of a finished block)
+
+A completed block's `src/components/<name>/index.tsx` contains, in order:
+
+1. Imports — React/Tailwind, shared components, and the PD decorators (`Component`, `AttributeDefinition`, `RegionDefinition`).
+2. A `/* v8 ignore start */ … /* v8 ignore end */`-wrapped `@Component`-decorated metadata class declaring each authorable attribute with its `type`, `required`, and (for string/markup/boolean) `defaultValue`.
+3. A plain TypeScript props interface.
+4. For product blocks: a callable `export async function loader(...)` and an optional `export function fallback()` skeleton.
+5. The default-exported React component, destructuring both the PD attributes and `data` (the loader return).
+
+Brand values come from `brand.css` tokens as Tailwind utilities/CSS variables — never hardcoded hex.

package/node_modules/@salesforce/b2c-agent-plugins/figma-to-sfnext-pagedesigner/skills/figma-to-sfnext-pagedesigner/evals/trigger-evals.json

@@ -0,0 +1,12 @@
+[
+  {"query": "Here's a Figma frame for our new homepage — turn it into Page Designer blocks for my Storefront Next project so merchants can edit the copy.", "should_trigger": true},
+  {"query": "I have a Figma design with a hero and a 3-up product row. Convert it into merchant-authorable Page Designer components in my sfnext storefront.", "should_trigger": true},
+  {"query": "Take this figma.com/design/...?node-id=1-2 frame and generate Storefront Next Page Designer components with decorator metadata and default values from the design copy.", "should_trigger": true},
+  {"query": "Build Page Designer blocks from my Figma mockup and wire up the product cards to pull live catalog data via SCAPI.", "should_trigger": true},
+  {"query": "I want the sections in this Figma file to show up in the Business Manager Page Designer palette for my React storefront. How do I do that?", "should_trigger": true},
+  {"query": "Just implement this Figma design as plain React and Tailwind components — I don't need any Page Designer or Business Manager integration.", "should_trigger": false},
+  {"query": "Convert this Figma frame into ISML templates and a Page Designer component for my SFRA cartridge.", "should_trigger": false},
+  {"query": "Sync my brand.css tokens into the Figma design kit and republish the Code Connect mappings.", "should_trigger": false},
+  {"query": "How do I deploy my Storefront Next bundle to Managed Runtime?", "should_trigger": false},
+  {"query": "Add a new custom SCAPI endpoint for a loyalty points service in my cartridge.", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/figma-to-sfnext-pagedesigner/skills/figma-to-sfnext-pagedesigner/references/PAGE-DESIGNER-SFN.md

@@ -0,0 +1,120 @@
+# Page Designer + Storefront Next — mental model & gotchas
+
+> **Purpose:** background reference for the `figma-to-sfnext-pd` skill. It teaches the mental model, developer workflow, and gotchas for exposing React components to Page Designer in a Storefront Next project. The skill reads this file during its pre-flight step.
+
+---
+
+## 1. Related tooling
+
+Salesforce's official agent-skill plugins cover adjacent workflows and are worth installing alongside this skill:
+
+```bash
+claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling
+claude plugin install storefront-next   # sf.next patterns incl. Page Designer decorators
+claude plugin install b2c-cli           # deploys, jobs, WebDAV, sandboxes
+claude plugin install b2c               # backend cartridge patterns
+# optional:
+claude plugin install b2c-dx-mcp        # MCP server (SCAPI schema discovery, MRT)
+claude plugin install storefront-next-figma  # Figma design-kit sync workflows
+```
+
+When uncertain about anything below, fetch the official docs (Section 7) — this feature area is young and moving.
+
+---
+
+## 2. Mental model — how Page Designer connects to Storefront Next
+
+Page Designer (PD) is the visual editor in Business Manager where merchants build pages by dragging **component types** into **page-type regions**. Classically (SFRA), developers hand-authored JSON meta-definition files + ISML render scripts in a cartridge.
+
+**Storefront Next changes the authoring model:** your React components ARE the Page Designer components. No separate ISML versions. The bridge is **component metadata**:
+
+1. You annotate React components in `src/` with TypeScript **decorators**: `@Component`, `@PageType`, `@Aspect`.
+2. The `sfnext` CLI **scans `src/` for those decorators and generates the classic PD JSON metadata** into `cartridge/cartridge/experience/` (separate files for components, page types, aspects).
+3. That generated cartridge is deployed to the B2C instance, which is what makes your components appear in the Page Designer visual editor for merchants.
+4. At runtime, the storefront renders PD pages via **prebuilt page manifests** served from the **MRT Data Store** (not assembled per shopper request), and/or the **`shopperExperience`** SCAPI client for page/content lookups.
+
+So there are two sync loops to keep straight:
+
+- **Dev-time loop (you):** decorated components → generated metadata cartridge → deployed to B2C. Keeps the _palette of available components_ in PD current.
+- **Merchant-time loop (automatic):** merchant edits pages in PD → system job prebuilds manifests → pushed to MRT Data Store → storefront reads them. Keeps the _page content_ current.
+
+---
+
+## 3. Developer workflow
+
+### Author
+
+Create/modify a React component, annotate with the PD decorators (`@Component` for component types, `@PageType` for page layouts with regions, `@Aspect` for dynamic page types like PDP/PLP templates). The `storefront-next` plugin skill has the current decorator API — follow it rather than guessing attribute schemas.
+
+### Generate + deploy metadata
+
+```bash
+pnpm sfnext generate-cartridge   # scans src/ decorators → JSON metadata in cartridge/cartridge/experience/
+pnpm sfnext deploy-cartridge     # uploads cartridge to B2C Commerce (reads dw.json / SDK config)
+```
+
+Requires valid B2C credentials resolvable by the tooling SDK (`dw.json`, env vars, or CLI flags).
+
+### Keep metadata in sync automatically (recommended once stable)
+
+```ts
+// config.ts
+export const GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH = true; // default: false
+```
+
+With this on, every `pnpm sfnext push` (MRT deploy) first regenerates and redeploys the cartridge metadata — code on MRT and component palette in PD can't drift.
+
+### Deploy the storefront itself
+
+```bash
+pnpm sfnext push -e <mrt-environment> -w
+```
+
+---
+
+## 4. Runtime & publishing (what merchants/admins do — you'll get support questions)
+
+- Merchant authors PD content on **staging**. A system job (`sfcc-generate-and-push-page-manifests`) runs **every 5 minutes**, prebuilds each PD page, and pushes manifests to the MRT Data Store. Manifests are never authored manually.
+- **Staging → production:** admin replicates; the `sfcc-push-page-manifests` job runs automatically on production after replication. Then verify on the storefront.
+- **Edits made directly on production are NOT picked up automatically.** Fix: Business Manager → Administration → Operations → Jobs → run `sfcc-generate-and-push-page-manifests` manually, confirm success in Job History.
+- This manifest mechanism is **Storefront Next only** — it does not apply to PWA Kit, SFRA, or SiteGenesis. Don't apply old PWA Kit PD integration patterns (`page-designer.html` docs) to sf.next projects.
+
+---
+
+## 5. Prerequisites & gotchas checklist
+
+- [ ] **Storefront connected in BM.** If the storefront was created via CLI/MRT API (not through Business Manager), PD and Storefront Preview can't see it until you connect it: BM → Administration → Sites → Storefronts → **Connect Existing** (needs Business Administrator-level role). BM-created storefronts are connected already.
+- [ ] `dw.json` (or equivalent env config) present and valid for `deploy-cartridge`.
+- [ ] MRT env vars set for `push`: `SFCC_MRT_PROJECT`, `SFCC_MRT_ENVIRONMENT`, `SFCC_MRT_API_KEY` (or credentials file).
+- [ ] Component not showing in PD editor? In order: regenerate cartridge → redeploy cartridge → confirm cartridge upload succeeded on the active code version → hard-refresh PD.
+- [ ] Content edits not showing on storefront? Check which instance was edited (direct-prod trap above) and the manifest job history; remember up to ~5 min staging job latency.
+- [ ] Rendering PD content in routes: fetch via the **`shopperExperience`** client from `@salesforce/storefront-next-runtime/scapi`, in a **server loader** (never client-side useEffect — sf.next is server-load-everything).
+- [ ] Node ≥ 24.13, pnpm ≥ 10.28; `sfnext` runs as `pnpm sfnext …` from project root, never installed globally.
+
+---
+
+## 6. Vocabulary quick reference
+
+| Term                                              | Meaning                                                                                               |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Page type                                         | Layout definition with named regions merchants fill with components                                   |
+| Component type                                    | Reusable building block with merchant-editable attributes                                             |
+| Region                                            | Named slot in a page/component that accepts child components                                          |
+| Aspect / dynamic page                             | Template page driven by runtime attributes (e.g. PDP/PLP templates)                                   |
+| Decorators (`@Component`, `@PageType`, `@Aspect`) | TS annotations on React components that the CLI compiles into PD metadata                             |
+| Generated cartridge                               | `cartridge/cartridge/experience/` JSON produced by `generate-cartridge` — never hand-edit; regenerate |
+| Page manifest                                     | Prebuilt PD page description stored in the MRT Data Store, read at render time                        |
+| MRT Data Store                                    | MRT-side storage syncing site preferences + PD manifests from B2C                                     |
+| `shopperExperience`                               | SCAPI client namespace for fetching PD pages/content in loaders                                       |
+
+---
+
+## 7. Official docs (fetch when uncertain — this area changes fast)
+
+- Page Designer with Storefront Next: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-page-designer.html
+- MRT Data Store & manifest jobs: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-data-store.html
+- Connect an existing storefront: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-connect-storefront.html
+- CLI reference (generate-cartridge / deploy-cartridge / push): https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-cli.html
+- SCAPI client (shopperExperience): https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.html
+- Agentic B2C Developer Toolkit (plugins/MCP): https://salesforcecommercecloud.github.io/b2c-developer-tooling/
+- Classic PD concepts (background only — SFRA-era): https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html

package/node_modules/@salesforce/b2c-agent-plugins/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@salesforce/b2c-agent-plugins",
+  "version": "1.9.0",
+  "description": "B2C Commerce agent skills plugins for development and operations. Private — distributed via GitHub release zips.",
+  "private": true
+}

package/node_modules/@salesforce/b2c-agent-plugins/plugins.json

@@ -0,0 +1,23 @@
+{
+  "description": "Manifest of agent skill plugins packaged and uploaded on release. Each entry corresponds to a skills/<name>/ directory whose skills/ subfolder is zipped into <name>-skills.zip and attached to the b2c-agent-plugins GitHub release. Add a plugin here to have it published \u2014 the publish workflow reads this file and requires no edits.",
+  "plugins": [
+    {
+      "name": "b2c"
+    },
+    {
+      "name": "b2c-cli"
+    },
+    {
+      "name": "b2c-ops"
+    },
+    {
+      "name": "storefront-next"
+    },
+    {
+      "name": "storefront-next-figma"
+    },
+    {
+      "name": "figma-to-sfnext-pagedesigner"
+    }
+  ]
+}

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

@@ -0,0 +1,39 @@
+{
+  "name": "storefront-next",
+  "version": "1.9.0",
+  "description": "Storefront Next development skills for building React 19 storefronts on Salesforce B2C Commerce.",
+  "author": {
+    "name": "Salesforce"
+  },
+  "homepage": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/",
+  "repository": "https://github.com/SalesforceCommerceCloud/b2c-developer-tooling",
+  "license": "Apache-2.0",
+  "keywords": [
+    "salesforce",
+    "storefront-next",
+    "react",
+    "b2c-commerce",
+    "commerce-cloud"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Storefront Next",
+    "shortDescription": "Build Salesforce B2C Storefront Next projects with AI assistance.",
+    "longDescription": "Skills for developing React 19 storefronts on Salesforce B2C Commerce — routing, data fetching, components, Page Designer, authentication, i18n, extensions, testing, and deployment to Managed Runtime.",
+    "developerName": "Salesforce",
+    "category": "Productivity",
+    "capabilities": [
+      "Read"
+    ],
+    "logo": "./assets/logo.svg",
+    "composerIcon": "./assets/logo.svg",
+    "brandColor": "#0D9DDA",
+    "websiteURL": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/",
+    "defaultPrompt": [
+      "Set up a new Storefront Next project",
+      "Add a new route with data fetching to my storefront",
+      "Deploy my storefront to Managed Runtime",
+      "Add Page Designer support to my storefront component"
+    ]
+  }
+}