@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/skills/sf-view-gen/SKILL.md

@@ -1,116 +1,146 @@
 ---
 name: sf-view-gen
-description: Add a new view or modify an existing view in a Thor Commerce storefront, selecting block variants and optional sections from this package's recipes
+description: Add or remove a Thor Commerce storefront view, compose a view's faq/cta sections, or customize a view's user-owned files. Use when the user runs /sf-add-view or /sf-view, or asks to add/remove a view, add/remove/reorder a section, or change a view's content, props, or data. Delegates every structural write to the `storefront` CLI.
 ---
 
 # sf-view-gen
 
-Generate or modify a single view, driven by the **recipe registry inside this skill's own directory**, so storefronts are not identical.
+Choose a view's composition **by meaning**, delegate the structural write to the
+`storefront` CLI, and edit only the user-owned files it leaves behind. The
+manifest (`storefront.config.json`) is the structural authority; the CLI is the
+only writer of derived files.
 
-## Source of truth
+## Read the registry through the CLI (never from memory)
 
-The workflow uses only the assets in this skill directory. There is no external project to consult and no package to locate: the recipes and templates it reads live under `assets/`, and the validator under `scripts/`. When a required choice is not determined by those files, ask the user.
+Run from the storefront project root. The CLI resolves the project from the
+current directory; do not pass a directory.
 
-## Inputs (the only target-project facts this skill reads)
-
-- the existence of the target project's `package.json`
-- the existence of `lib/<name>/`
-- the existence of the project's `.opencode/`
-- the values returned by the wizard (view name, description of what the view should contain or emphasize)
-
-## Outputs (what this skill produces)
+```bash
+npx @thorprovider/storefront views --json      # views, routes, supported intents/variants, installed
+npx @thorprovider/storefront recipes --json    # whole curated registry (views + features)
+npx @thorprovider/storefront features --json   # feature bundles and what they own
+```
 
-- generated files: the view module under `lib/<name>/views/<view>/` and one barrel entry in `lib/<name>/views/index.ts`
-- declared setup commands: the typecheck command it reports
-- a summary listing every file created and every command run
+The `--json` output is the same registry the CLI validates against, so it cannot
+advertise a selection the reconciler will not honour. `views --json` and
+`recipes --json` also report, per view, `registeredSlots` (the non-removable core
+slots), `allowedSections` (the section types the view may host), and
+`maxSections` (the editorial-instance bound), plus a top-level `sectionTypes`
+list marking each type `executable` or `held` with a reason. Do not read the JSON
+files directly; they are an implementation detail.
+
+## Curated MVP set
+
+- **Standalone views:** `home`, `category`, `product` — add with `view add`.
+- **Feature-owned view:** `checkout` is owned by the `checkout` feature. A direct
+  `view add checkout` is rejected; run `feature add checkout` instead (see the
+  `sf-feature` skill).
+- **Held post-MVP:** `user-panel` and recommendations are rejected before any
+  write. Do not try to install them. (Sections are composable — see below.)
+
+## Add a view
+
+1. Read `views --json`. If the view is held or feature-owned, stop and explain
+   the correct path.
+2. Choose an **intent by meaning** for each slot from the view's
+   `supportedIntents` (e.g. a "dense grid" description → the matching intent).
+   If the description is silent, use the default. Only use
+   `--variant slot=Name` when the user names an exact supported variant.
+3. Delegate the write:
+
+   ```bash
+   npx @thorprovider/storefront view add <name> [--intent slot=intent] [--variant slot=Variant]
+   ```
 
-## Assets (inside this skill)
+   The CLI validates, updates the manifest, and reconciles the derived files.
+   If it exits non-zero, show its message and the supported options; do not
+   hand-edit derived files to work around it.
+4. Report the created view and its route.
 
-- `assets/recipes/recipes.json` — per view: `route`, `loader`, `requiredDataKeys`, `defaultVariants`, `allowedVariants`, `optionalSections`
-- `assets/recipes/sections.json` — optional sections → `elementType`, `variants`, `defaultVariant`, `propsHint`
-- `assets/recipes/archetypes.json` — the **archetype (intent) layer**: per slot (`<view>.<slot>`) a set of named **intents**, each with a `variant` and a `when` usage hint, plus the slot `default` intent
-- `assets/templates/views/<view>/` — the view modules it copies
-- `assets/templates/views/sections/` — the optional-section fragments
-- `scripts/validate.mjs` — the validator
-- `references/views.md` — the view composition contract
-- `../json-render-core/` — vendored catalog/schema/spec reference
-- `../json-render-react/` — vendored registry/action reference
+## Remove a view
 
-Paths are relative to this `SKILL.md`. Run the validator from here:
 ```bash
-node scripts/validate.mjs list
-node scripts/validate.mjs show <view>
-node scripts/validate.mjs archetypes
-node scripts/validate.mjs resolve <view> <slot> <intent>
-node scripts/validate.mjs validate '<composition-json>'
+npx @thorprovider/storefront view remove <name>
 ```
 
-## Allowed views
-`home`, `product`, `category`, `checkout`, `user-panel`
+The CLI removes the derived wrapper and wiring. If it prints a preserved
+user-owned file, relay that path to the user.
+
+## Compose sections (the agent selects, the CLI writes)
+
+A view's ordered composition mixes its **registered slots** (core presentation
+slots, mandatory and non-removable) with **editorial section instances**. The
+agent selects the options and runs the CLI; the user describes the change in
+natural language and never types a command.
+
+1. Read `views --json`. For the target view use `registeredSlots` (the core
+   slots), `allowedSections` (the host allowlist), and `maxSections`; read the
+   top-level `sectionTypes` list for which types are available.
+2. Only `faq` and `cta` are `executable`. Held types (`testimonials`,
+   `statistics`, `logoCloud`, `pricing`) are refused with a bounded reason. Never
+   present a held type as available, and never invent a reason — relay the
+   `reason` the registry reports.
+3. Compose through the CLI's section operations, carried in the operations
+   envelope `{ "formatVersion": 1, "operations": [ ... ] }`. Write the envelope
+   to a file, plan it, then apply the plan:
+
+   ```bash
+   npx @thorprovider/storefront plan --operations operations.json --out plan.json
+   npx @thorprovider/storefront apply --plan plan.json
+   ```
 
-Reject any other name with the full allowed list.
+   - `{ "op": "section.add", "view": "home", "type": "faq" }` — optional `id`,
+     `variant`, and `at` (0-based insertion index, default append). Omit `id` to
+     auto-mint one; a `variant` must be declared by the section type.
+   - `{ "op": "section.remove", "view": "home", "id": "home-faq-1" }` — removes an
+     editorial instance. A registered slot (`slot:<slot>`) cannot be removed.
+   - `{ "op": "section.reorder", "view": "home", "order": ["slot:hero", "home-faq-1", "slot:benefits", "slot:categories"] }` —
+     `order` must be a permutation of the view's current entry ids: every current
+     id exactly once, and every registered slot present.
+
+4. `plan` is read-only and validates the whole intended state; `apply --plan` is
+   the only writer. On success the CLI updates the manifest and reconciles derived
+   files. If either exits non-zero, relay its diagnostic (it names the offending
+   field) and the supported options; do not hand-edit the manifest or derived
+   files to work around it.
+5. A removed instance's content is preserved in the view's user-owned
+   `content.ts`; re-adding the same `id` rebinds it, while an auto-minted id never
+   rebinds preserved content.
+
+## Customize a view (the `/sf-view` workflow)
+
+Only **user-owned** files may be edited by hand. They are consumed by thin
+derived wrappers, so `sync` regenerates the wrappers around your edits.
+
+User-owned (edit these): `lib/<name>/views/<view>/content.ts`, `props.ts`,
+`data.ts`, `schema.ts`, and `lib/<name>/mappers.ts`.
+
+Derived (never edit; the CLI regenerates them): `index.tsx`, `registry.tsx`,
+`lib/<name>/views/index.ts`, `lib/<name>/views/registry.ts`, `catalog.ts`,
+`runtime.ts`, `spec/index.ts`, `state.ts`, `handlers.ts`.
+
+1. Read the current user-owned files for the view.
+2. Apply the requested change there. Preserve exported names, element ids, and
+   the event/prop contracts the derived wrapper imports.
+3. Regenerate the wrappers: `npx @thorprovider/storefront sync`.
+4. If the change needs a different block variant or a new view, use the CLI
+   (`view add`/`remove`); never edit the derived `index.tsx` to swap a variant.
 
-## json-render references (consult when authoring element types)
+## Stack constraints
 
-When adding a view you register new element `type`s in the view module: the zod
-catalog entry in `views/<view>/index.tsx` and the component mapping in
-`views/<view>/registry.tsx` ('use client'). Consult the vendored references
-instead of working from memory:
+- UI components only from `@thorprovider/blocks`.
+- Data only through `@thorprovider/adapters` + `@thorprovider/runtime/commerce`.
+- Never `@thorprovider/medusa-extended`.
+- No custom blocks without explicit user authorization.
 
-- `../json-render-core/` — catalog/schema/spec authoring (the shape of a catalog entry and a spec element)
-- `../json-render-react/` — registry mapping and action wiring (`defineRegistry`, `Renderer`, `useStateStore`)
+## Workflow model
 
-**Selection rule:** choose an **intent by meaning** from the user's description (never a raw variant ordinal), then resolve the intent to its variant via `assets/recipes/archetypes.json`. The resolved variant must be allowed by the recipe for that slot. Choose optional sections the same way. Never invent an intent, variant, or component. If the description is silent, use the archetype slot `default`.
+Read `../storefront-workflow/SKILL.md` for the four phases (bootstrap → compose
+→ customize → verify), the ownership classes, and the CLI/agent authority.
 
-```bash
-node scripts/validate.mjs resolve home hero showcase   # -> StorefrontHero2
-```
-
-## Stack constraints
-- UI: only `@thorprovider/blocks`
-- Data: only `@thorprovider/adapters` + `@thorprovider/runtime/commerce`
-- Never `@thorprovider/medusa-extended`
-- No custom blocks without explicit user authorization
-- **Two-file view split (RSC):** `index.tsx` is a pure Server Component module (name, elements, zod catalog, route, loader) and imports `registry` from the sibling `registry.tsx` as data. `registry.tsx` is the **`'use client'`** module and is the only place that imports values from `@json-render/react` or `@thorprovider/blocks`. Never add those imports to `index.tsx` — `@json-render/react` calls `createContext` at module scope, which breaks the RSC server graph.
-- Every element `type` used in a spec MUST be registered in the view's zod catalog (`index.tsx`) AND its client registry (`registry.tsx`); the shared `catalog.ts` / `registry.tsx` compose both through the barrel and are never hand-edited
-
-## Add-view workflow
-
-1. Parse `$ARGUMENTS` → view name (+ optional description). Validate name. Confirm `lib/<name>/` exists (else run `npx @thorprovider/storefront create` to scaffold it).
-2. `node scripts/validate.mjs show <view>` — read slots, allowed variants + sections. `node scripts/validate.mjs archetypes` — read slots with their named intents.
-3. Choose an intent per slot by meaning from the description (defaults if silent), resolve each with `node scripts/validate.mjs resolve <view> <slot> <intent>`, choose optional sections the same way, then validate the full composition with `node scripts/validate.mjs validate '<json>'` **before writing anything**. On failure → stop, show the allowed options.
-4. Copy the view template: `assets/templates/views/<view>/` → `lib/<name>/views/<view>/`. Each template is the two-file split: `index.tsx` (server spec) + `registry.tsx` ('use client' component mappings).
-5. Register it in the barrel `lib/<name>/views/index.ts` — ONE import and ONE array entry:
-   ```ts
-   import { <view> } from './<view>'
-   export const views: ViewModule[] = [home, <view>]
-   ```
-6. Substitute variants: each slot's block is imported under a stable alias (e.g. `ProductOverview1 as ProductOverviewBlock`), shipping the recipe default. Replace **only the imported identifier** with the resolved variant — never the alias, never the props:
-   ```ts
-   import { ProductOverview5 as ProductOverviewBlock } from '@thorprovider/blocks'
-   ```
-7. Include any chosen optional section — fragments live at `assets/templates/views/sections/` as a two-file split:
-   - `<section>.tsx` (server): exports the section object with `elementType`, the zod `catalog` entry, and `registryModule: './<section>.client'`.
-   - `<section>.client.tsx` ('use client'): exports `registry: ViewRegistry` with the component mapping.
-   Import the section object from `<section>` into `index.tsx` and merge its elements/catalog into the view; put the component mapping from `<section>.client` into the view's `registry.tsx` (re-exporting the fragment's registry).
-8. Verify: `yarn typecheck`. Do NOT hand-edit `catalog.ts`, `registry.tsx`, `runtime.ts`, or `spec/index.ts` — they compose whatever the barrel exports.
-
-## Modify workflow (`/sf-view`)
-
-1. Parse view name + change. Validate name.
-2. Read `lib/<name>/views/<view>/index.tsx` (server spec) and `registry.tsx` (client mappings) fully.
-3. Apply ONLY the change. Preserve ids, `type`, untouched `props`, `$state`, `on` wiring, route/loader, and the barrel entry.
-4. If new blocks are needed, choose intents from `archetypes.json`, resolve to allowed variants, and validate before writing.
-5. Re-run `yarn typecheck`.
-
-## Generation headers
-Every generated/edited file gets:
-```
-// Generated by @thorprovider/storefront (sf-view-gen) from recipes/<view>
-```
+## Completion criteria
 
-## Error handling
-- Unknown view → error + allowed list, stop.
-- Missing `lib/<name>/` → run `npx @thorprovider/storefront create`, stop.
-- Undeclared variant/section → reject via `recipes/validate.mjs`, show allowed options.
-- Type errors → fix before finishing; never leave broken specs.
+- The manifest reflects the requested composition and `sync` reports no drift.
+- Only user-owned files were hand-edited; every derived file was written by the
+  CLI.
+- The CLI command's exit status was checked and reported.

package/skills/sf-view-gen/assets/recipes/archetypes.json

@@ -4,7 +4,7 @@
   "description": "Archetype (intent) layer. Maps a slot to named intents so selection is by meaning, not by variant ordinal. Each intent resolves to a variant that MUST be allowed by the recipe for that slot.",
   "slots": {
     "home.hero": {
-      "default": "showcase",
+      "default": "compact",
       "intents": {
         "compact": {
           "variant": "StorefrontHero1",
@@ -122,6 +122,33 @@
         }
       }
     },
+    "account.login": {
+      "default": "signIn",
+      "intents": {
+        "signIn": {
+          "variant": "LoginPage1",
+          "when": "A full sign-in page with email and password and a link to create an account."
+        }
+      }
+    },
+    "account.register": {
+      "default": "signUp",
+      "intents": {
+        "signUp": {
+          "variant": "SignUpPage1",
+          "when": "A full registration page with name, email, and password and a link to sign in."
+        }
+      }
+    },
+    "account.orders": {
+      "default": "viewOrders",
+      "intents": {
+        "viewOrders": {
+          "variant": "OrderHistory2",
+          "when": "A signed-in shopper's order history with per-order totals and detail on demand."
+        }
+      }
+    },
     "user-panel.shell": {
       "default": "standard",
       "intents": {

package/skills/sf-view-gen/assets/recipes/catalog.json

@@ -0,0 +1,361 @@
+{
+  "$schema": "./catalog.schema.json",
+  "catalogVersion": 1,
+  "description": "Initial semantic executable catalog (E1 tasks 1.2-1.3), classified by source-shape inspection of the @thorprovider/blocks prop contracts and the view templates. Scope: every slot the curated MVP views (home, product, category, checkout, account) render by default, covering both the selectable archetype slots declared by recipes/archetypes.json and the nested default slots that have no archetype (category.productCard, checkout.confirmation) so no legacy default support is dropped. The account view (change: storefront-customer-auth) declares the login/register slots: LoginPage1/SignUpPage1 are executable while LoginPage2 is held for its divergent callback contract. A variant is `executable` only when the slot's canonical data shape can feed its block props without a prop bridge and without inventing data; every other non-default variant is `held` with the specific reason. The one executable non-default swap is home.benefits Feature1 -> Feature2 (identical item contract, no bridge). user-panel (non-MVP view) is outside this initial catalog scope. E2 task 6.1 declares the base listing slot category.filter CategoryFilter2 as the single controlled listing (dataShape `CatalogQuery & CatalogResults`, state controlled) with the search/filter controls contributed by the logical mounts category.search / category.filters (no second block). Source-shape compatibility is not end-to-end backend behavior proof: the render is executable, but the category.search.apply / category.filter.apply actions remain held under the capability catalog (owner: storefront-catalog-search-filters, E2) until a real runtime proof. The `capabilities` map declares those operational capabilities with their requirements and verification state; E1 declares the held category.filter.apply action, E2 adds the held category.search.apply action and the held category.price.range capability that gates the category-filters showPrice option; no capability is claimed verified.",
+  "slots": {
+    "home.hero": {
+      "default": "StorefrontHero1",
+      "variants": {
+        "StorefrontHero1": {
+          "status": "executable",
+          "block": "StorefrontHero",
+          "dataShape": "FeaturedProduct[]",
+          "events": ["addToCart", "buyNow", "selectColor"],
+          "state": "uncontrolled",
+          "requirements": ["heroProducts"]
+        },
+        "StorefrontHero2": {
+          "status": "held",
+          "reason": "block requires a product with reviews/trending/tag and emits a search event; the canonical FeaturedProduct shape carries rating/reviewCount but not trending/tag, and no verified prop bridge exists",
+          "block": "StorefrontHero",
+          "dataShape": "StorefrontHero2FeaturedProduct[]",
+          "events": ["search", "productClick"],
+          "state": "uncontrolled",
+          "requirements": ["heroProducts"]
+        },
+        "StorefrontHero5": {
+          "status": "held",
+          "reason": "featuredDeals[].description is absent from the canonical product shape and Department.count would require inventing counts; no truthful prop bridge can be derived from source",
+          "block": "StorefrontHero",
+          "dataShape": "FeaturedDeal[] & Department[]",
+          "events": ["departmentClick", "shopNow", "locateStores"],
+          "state": "uncontrolled",
+          "requirements": ["featuredDeals", "departments"]
+        },
+        "StorefrontHero6": {
+          "status": "held",
+          "reason": "block requires deals with discount/endTime and categories with a required count; the canonical shape supplies neither without invention and no verified prop bridge exists",
+          "block": "StorefrontHero",
+          "dataShape": "HeroDeal[] & HeroCategory[]",
+          "events": ["shopNow", "categoryClick"],
+          "state": "uncontrolled",
+          "requirements": ["deals", "categories"]
+        }
+      }
+    },
+    "home.benefits": {
+      "default": "Feature1",
+      "variants": {
+        "Feature1": {
+          "status": "executable",
+          "block": "Feature",
+          "dataShape": "BenefitsItem[]",
+          "events": ["ctaClick", "learnMore"],
+          "state": "uncontrolled",
+          "requirements": []
+        },
+        "Feature2": {
+          "status": "executable",
+          "block": "Feature",
+          "dataShape": "BenefitsItem[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": []
+        }
+      }
+    },
+    "home.categories": {
+      "default": "ProductCategory2",
+      "variants": {
+        "ProductCategory2": {
+          "status": "executable",
+          "block": "CategoryCards",
+          "dataShape": "CategoryCard[]",
+          "events": ["browse"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory1": {
+          "status": "held",
+          "reason": "block requires categories with a subtitle and a named icon, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory1Category[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory4": {
+          "status": "held",
+          "reason": "block requires categories with title/icon/customers/products/avatarImages, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory4Category[]",
+          "events": ["categoryClick"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        },
+        "ProductCategory5": {
+          "status": "held",
+          "reason": "block requires categories with subcategories and a required itemCount plus a search control, which the canonical CategoryCard shape does not supply; no verified prop bridge exists",
+          "block": "CategoryCards",
+          "dataShape": "ProductCategory5Category[]",
+          "events": ["browse", "viewAll"],
+          "state": "uncontrolled",
+          "requirements": ["categories"]
+        }
+      }
+    },
+    "product.overview": {
+      "default": "ProductOverview1",
+      "variants": {
+        "ProductOverview1": {
+          "status": "executable",
+          "block": "ProductOverview",
+          "dataShape": "ProductDetailProduct",
+          "events": ["selectVariant", "quantityChange", "addToCart", "toggleWishlist"],
+          "state": "controlled",
+          "requirements": ["selectedProduct", "selectedVariantId"]
+        },
+        "ProductOverview2": {
+          "status": "held",
+          "reason": "block requires a product with brand/sku/sizes/colors and wishlist events, a shape the canonical ProductDetailProduct does not supply; no verified prop bridge exists",
+          "block": "ProductOverview",
+          "dataShape": "ProductOverview2Product",
+          "events": ["addToCart", "toggleWishlist"],
+          "state": "uncontrolled",
+          "requirements": ["selectedProduct"]
+        },
+        "ProductOverview5": {
+          "status": "held",
+          "reason": "block requires specifications/features/mainImages/galleryImages/userReviews, a shape the canonical ProductDetailProduct does not supply; no verified prop bridge exists",
+          "block": "ProductOverview",
+          "dataShape": "ProductOverview5Product",
+          "events": ["addToCart", "toggleWishlist"],
+          "state": "uncontrolled",
+          "requirements": ["selectedProduct"]
+        }
+      }
+    },
+    "product.reviews": {
+      "default": "ReviewRating1",
+      "variants": {
+        "ReviewRating1": {
+          "status": "executable",
+          "block": "Reviews",
+          "dataShape": "Review[]",
+          "events": ["toggleReviewLike", "submitReview"],
+          "state": "uncontrolled",
+          "requirements": ["productReviews"]
+        },
+        "ReviewRating2": {
+          "status": "held",
+          "reason": "block requires an aggregate averageRating/ratingDistribution and carousel controls the canonical Review[] shape does not supply; no verified prop bridge exists",
+          "block": "Reviews",
+          "dataShape": "Review[] & RatingSummary",
+          "events": ["like", "comment"],
+          "state": "uncontrolled",
+          "requirements": ["productReviews"]
+        }
+      }
+    },
+    "category.filter": {
+      "default": "CategoryFilter2",
+      "variants": {
+        "CategoryFilter2": {
+          "status": "executable",
+          "block": "CategoryFilter",
+          "dataShape": "CatalogQuery & CatalogResults",
+          "events": [
+            "productClick",
+            "pageChange",
+            "pageSizeChange",
+            "sortChange",
+            "filterChange",
+            "searchChange",
+            "clearFilters",
+            "repair",
+            "retry",
+            "removeFilter"
+          ],
+          "state": "controlled",
+          "requirements": ["categoryProducts", "categoryQuery", "facetSupport"]
+        },
+        "CategoryFilter1": {
+          "status": "held",
+          "reason": "block requires categories/priceRanges/sortOptions with counts the canonical CardProduct[] listing does not supply; no verified prop bridge exists",
+          "block": "CategoryFilter",
+          "dataShape": "CategoryFilter1Filters",
+          "events": ["filterChange"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "CategoryFilter4": {
+          "status": "held",
+          "reason": "block requires an advanced facets contract (modelTypes/rangeBands/frameSizes/colourways/features) the canonical listing does not supply; no verified prop bridge exists",
+          "block": "CategoryFilter",
+          "dataShape": "CategoryFilter4Facets",
+          "events": ["filterChange"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        }
+      }
+    },
+    "category.productCard": {
+      "default": "ProductCard1",
+      "variants": {
+        "ProductCard1": {
+          "status": "executable",
+          "block": "ProductCard",
+          "dataShape": "CardProduct[]",
+          "events": ["addToCart", "openProduct"],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard2": {
+          "status": "held",
+          "reason": "block requires a product with a required rating, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard2Product[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard3": {
+          "status": "held",
+          "reason": "block requires a product with subtitle/originalPrice/reviewCount/discountPercentage and a badge, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard3Product[]",
+          "events": ["toggleWishlist", "viewSimilar", "productClick"],
+          "state": "controlled",
+          "requirements": ["categoryProducts"]
+        },
+        "ProductCard5": {
+          "status": "held",
+          "reason": "block requires a product with name/category/stock/specifications/brand, a shape the canonical CardProduct listing does not supply; no verified prop bridge exists",
+          "block": "ProductCard",
+          "dataShape": "ProductCard5Product[]",
+          "events": ["toggleWishlist", "addToCart", "quickView", "compare", "export"],
+          "state": "controlled",
+          "requirements": ["categoryProducts"]
+        }
+      }
+    },
+    "checkout.checkout": {
+      "default": "CheckoutForm1",
+      "variants": {
+        "CheckoutForm1": {
+          "status": "executable",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm1FormData",
+          "events": ["retryTotals", "selectShippingOption", "applyPromo", "submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        },
+        "CheckoutForm2": {
+          "status": "held",
+          "reason": "unproven checkout variant: E1 keeps only the default CheckoutForm1, whose behavior is unchanged; no verified prop bridge exists",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm2Data",
+          "events": ["submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        },
+        "CheckoutForm3": {
+          "status": "held",
+          "reason": "unproven checkout variant: E1 keeps only the default CheckoutForm1, whose behavior is unchanged; no verified prop bridge exists",
+          "block": "Checkout",
+          "dataShape": "CheckoutForm3FormData",
+          "events": ["submit"],
+          "state": "controlled",
+          "requirements": ["checkoutCountries", "checkoutPaymentMethods"]
+        }
+      }
+    },
+    "checkout.confirmation": {
+      "default": "CheckoutConfirmation",
+      "variants": {
+        "CheckoutConfirmation": {
+          "status": "executable",
+          "block": "CheckoutConfirmation",
+          "dataShape": "Receipt",
+          "events": ["continueShopping"],
+          "state": "uncontrolled",
+          "requirements": ["lastReceipt"]
+        }
+      }
+    },
+    "account.login": {
+      "default": "LoginPage1",
+      "variants": {
+        "LoginPage1": {
+          "status": "executable",
+          "block": "LoginPage1",
+          "dataShape": "LoginPage1FormData & AccountAuthResult",
+          "events": ["submit", "createAccount"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        },
+        "LoginPage2": {
+          "status": "held",
+          "reason": "block's onSubmit takes positional (email, password) with no remember-me field and renders a 2-column social grid; no verified prop bridge from the account element contract exists",
+          "block": "LoginPage2",
+          "dataShape": "LoginPage2Credentials & AccountAuthResult",
+          "events": ["submit", "forgotPassword", "signUp"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    },
+    "account.register": {
+      "default": "SignUpPage1",
+      "variants": {
+        "SignUpPage1": {
+          "status": "executable",
+          "block": "SignUpPage1",
+          "dataShape": "SignUpPage1Data & AccountAuthResult",
+          "events": ["submit", "signIn"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    },
+    "account.orders": {
+      "default": "OrderHistory2",
+      "variants": {
+        "OrderHistory2": {
+          "status": "executable",
+          "block": "OrderHistory2",
+          "dataShape": "AccountOrderView[] & OrderHistory2Labels",
+          "events": ["viewDetails"],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        },
+        "OrderHistory1": {
+          "status": "held",
+          "reason": "block models one row per order item (an item-row list), the wrong shape for an order-level history; the canonical order list cannot feed it without inventing an aggregate row",
+          "block": "OrderHistory1",
+          "dataShape": "OrderHistory1Order[]",
+          "events": [],
+          "state": "controlled",
+          "requirements": ["accountCustomer", "accountAuthenticated"]
+        }
+      }
+    }
+  },
+  "capabilities": {
+    "category.search.apply": {
+      "requirements": ["adapter.getCatalogProducts(query).text"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    },
+    "category.filter.apply": {
+      "requirements": ["adapter.getProducts(query)"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    },
+    "category.price.range": {
+      "requirements": ["adapter.getAvailableFilters(query).priceRange"],
+      "verification": "unverified",
+      "owner": "storefront-catalog-search-filters"
+    }
+  }
+}