@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0-mvp.2

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

@@ -1,6 +1,6 @@
 ---
 name: sf-view-gen
-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.
+description: Add or remove a Thor Commerce storefront view, compose and reorder a view's executable sections, or customize a view's user-owned files. Use when the user asks to add or remove a view (home, category, product, cart, account, static), add/remove/reorder a section (faq, cta, products), change a variant, or change a view's content, props, or data. Delegates every structural write to the `storefront` CLI.
 ---
 
 # sf-view-gen
@@ -10,51 +10,49 @@ Choose a view's composition **by meaning**, delegate the structural write to the
 manifest (`storefront.config.json`) is the structural authority; the CLI is the
 only writer of derived files.
 
-## Read the registry through the CLI (never from memory)
+## Read the curated view set through the CLI (never from memory)
 
 Run from the storefront project root. The CLI resolves the project from the
 current directory; do not pass a directory.
 
 ```bash
-npx @thorprovider/storefront views --json      # views, routes, supported intents/variants, installed
+npx @thorprovider/storefront views --json      # views, routes, intents/variants, installed
 npx @thorprovider/storefront recipes --json    # whole curated registry (views + features)
 npx @thorprovider/storefront features --json   # feature bundles and what they own
 ```
 
 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.)
+advertise a selection the reconciler will not honour. There is **no fixed view
+list in this skill**: `views --json` reports the authoritative curated set
+(currently `home`, `product`, `cart`, `category`, `checkout`, `account`, and
+`static`) annotated with `installed` and `supported`, so a view added to or
+removed from the registry is reflected without editing this text.
+
+`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.
 
 ## Add a view
 
-1. Read `views --json`. If the view is held or feature-owned, stop and explain
-   the correct path.
+1. Read `views --json`. If the view is held (`supported: false`) or is
+   feature-owned, stop and explain the correct path (a direct `view add` of a
+   feature-owned view is rejected — route it through the owning feature's
+   `feature add`; see the `sf-feature` skill).
 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.
+   `supportedIntents` (for example a "dense grid" description → the matching
+   intent). If the description is silent, use the default. Use
+   `--variant slot=Name` only 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]
    ```
 
-   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.
+   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.
 
 ## Remove a view
@@ -75,11 +73,15 @@ 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.
+   top-level `sectionTypes` list for which types are `executable`. Never treat the
+   `sections --json` installed-instance list as the set of available types.
+2. Only `executable` types may be composed; a `held` type is refused with the
+   `reason` the registry reports — relay that reason, never invent one. A
+   `dataBound` `products` instance is configured separately by the developer in
+   `views/<view>/data.ts` → `sectionSources[id]` (a canonical query — not a sales
+   ranking); its variant only changes presentation, and until the selection is set
+   the instance renders a truthful "needs configuration" state that `doctor`
+   reports by file and instance id.
 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:
@@ -89,14 +91,14 @@ natural language and never types a command.
    npx @thorprovider/storefront apply --plan plan.json
    ```
 
-   - `{ "op": "section.add", "view": "home", "type": "faq" }` — optional `id`,
+   - `{ "op": "section.add", "view": "<view>", "type": "<type>" }` — 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
+   - `{ "op": "section.remove", "view": "<view>", "id": "<id>" }` — 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.
+   - `{ "op": "section.reorder", "view": "<view>", "order": [ ... ] }` — `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
@@ -107,7 +109,15 @@ natural language and never types a command.
    `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)
+## Variants
+
+A slot's variant is a presentation choice carried by the manifest. Change it
+through the CLI (`view add`/`remove` with `--variant`, or a `section.add` /
+`section.reorder` operation for editorial sections); never hand-edit a derived
+`index.tsx` or registry to swap an import identifier. Variant changes go through
+the CLI plan/apply path so the manifest and the derived files stay in sync.
+
+## Customize a view
 
 Only **user-owned** files may be edited by hand. They are consumed by thin
 derived wrappers, so `sync` regenerates the wrappers around your edits.
@@ -124,7 +134,18 @@ Derived (never edit; the CLI regenerates them): `index.tsx`, `registry.tsx`,
    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.
+   (`view add`/`remove` or the section operations); never edit a derived file to
+   swap a variant.
+
+## References
+
+Relative to this `SKILL.md`:
+
+- `references/views.md` — view module shape, registering, and data contracts.
+- `references/json-render-core.md` — catalog zod props and spec shape.
+- `references/json-render-react.md` — registry mapping, providers, and actions.
+- `references/json-render-next.md` — the Next rendering shape.
+- `references/json-render-shadcn.md` — standard component definitions.
 
 ## Stack constraints
 
@@ -132,11 +153,13 @@ Derived (never edit; the CLI regenerates them): `index.tsx`, `registry.tsx`,
 - Data only through `@thorprovider/adapters` + `@thorprovider/runtime/commerce`.
 - Never `@thorprovider/medusa-extended`.
 - No custom blocks without explicit user authorization.
+- A missing capability is a gap to report, not a reason to install another UI
+  framework or hand-edit a derived file.
 
 ## Workflow model
 
-Read `../storefront-workflow/SKILL.md` for the four phases (bootstrap → compose
-→ customize → verify), the ownership classes, and the CLI/agent authority.
+Read `../storefront-workflow/SKILL.md` for the four phases and the CLI/agent
+authority.
 
 ## Completion criteria
 

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

@@ -88,6 +88,15 @@
         }
       }
     },
+    "cart.view": {
+      "default": "review",
+      "intents": {
+        "review": {
+          "variant": "ShoppingCart4",
+          "when": "A standalone cart review page: line editing plus backend-authoritative totals before checkout."
+        }
+      }
+    },
     "category.filter": {
       "default": "sidebar",
       "intents": {
@@ -148,28 +157,6 @@
           "when": "A signed-in shopper's order history with per-order totals and detail on demand."
         }
       }
-    },
-    "user-panel.shell": {
-      "default": "standard",
-      "intents": {
-        "standard": {
-          "variant": "AppShell1",
-          "when": "A standard account shell with side navigation and content area."
-        }
-      }
-    },
-    "user-panel.orderHistory": {
-      "default": "compact",
-      "intents": {
-        "compact": {
-          "variant": "OrderHistory1",
-          "when": "A concise list of past orders with status and totals."
-        },
-        "detailed": {
-          "variant": "OrderHistory2",
-          "when": "Order history with line-item detail, tracking, and reorder actions."
-        }
-      }
     }
   }
 }

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

@@ -1,7 +1,7 @@
 {
   "$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.",
+  "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). 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",
@@ -157,6 +157,32 @@
         }
       }
     },
+    "product.breadcrumb": {
+      "default": "Breadcrumb",
+      "variants": {
+        "Breadcrumb": {
+          "status": "executable",
+          "block": "Breadcrumb",
+          "dataShape": "BreadcrumbItemData[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["productBreadcrumb"]
+        }
+      }
+    },
+    "cart.view": {
+      "default": "ShoppingCart4",
+      "variants": {
+        "ShoppingCart4": {
+          "status": "executable",
+          "block": "ShoppingCart4",
+          "dataShape": "CartLineState[] & CartTotalsState",
+          "events": ["refreshCart", "updateQuantity", "removeFromCart", "checkout", "continueShopping"],
+          "state": "controlled",
+          "requirements": ["cart", "cartTotals"]
+        }
+      }
+    },
     "category.filter": {
       "default": "CategoryFilter2",
       "variants": {
@@ -339,6 +365,19 @@
           "requirements": ["accountCustomer", "accountAuthenticated"]
         }
       }
+    },
+    "category.breadcrumb": {
+      "default": "Breadcrumb",
+      "variants": {
+        "Breadcrumb": {
+          "status": "executable",
+          "block": "Breadcrumb",
+          "dataShape": "BreadcrumbItemData[]",
+          "events": [],
+          "state": "uncontrolled",
+          "requirements": ["categoryBreadcrumb"]
+        }
+      }
     }
   },
   "capabilities": {

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

@@ -30,7 +30,7 @@
       "name": "customer-auth",
       "mvp": true,
       "description": "Customer authentication: registration, login, logout, and a minimal signed-in state. Owns the account view.",
-      "route": "/cuenta",
+      "route": "/account",
       "views": ["account"],
       "state": [
         "accountCustomer",
@@ -48,7 +48,7 @@
       "name": "static-pages",
       "mvp": true,
       "description": "Content-driven static pages (contact, legal, about) served with per-page metadata. Owns the static view.",
-      "route": "/contacto",
+      "route": "/contact",
       "views": ["static"],
       "state": [],
       "handlers": [],
@@ -122,6 +122,29 @@
       "mounts": [{ "id": "category-filters", "host": "category", "slot": "filters" }],
       "surfaces": []
     },
+    {
+      "name": "navigability",
+      "mvp": true,
+      "description": "Cross-cutting navigability feature: entity-derived breadcrumbs with BreadcrumbList structured data on the product and category surfaces, plus skip-to-content, current-page indication, back-to-top, and a mobile bottom navigation in the shared shell.",
+      "views": [],
+      "state": [],
+      "handlers": [],
+      "adapter": { "needs": [] },
+      "config": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "presentation": { "type": "string", "enum": ["default"], "default": "default" },
+          "showBackToTop": { "type": "boolean", "default": true }
+        }
+      },
+      "presentations": { "default": "Breadcrumb" },
+      "mounts": [
+        { "id": "category-breadcrumb", "host": "category", "slot": "breadcrumb" },
+        { "id": "product-breadcrumb", "host": "product", "slot": "breadcrumb" }
+      ],
+      "surfaces": []
+    },
     {
       "name": "recommendations",
       "mvp": false,

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

@@ -22,47 +22,69 @@
       },
       "optionalSections": ["testimonials", "faq", "statistics", "logoCloud", "pricing"],
       "registeredSlots": ["hero", "benefits", "categories"],
-      "allowedSections": ["faq", "cta"],
+      "allowedSections": ["faq", "cta", "products"],
       "maxSections": 4
     },
     {
       "name": "product",
       "mvp": true,
       "description": "Single product detail page with overview, gallery, and reviews",
-      "route": "/productos/[id]",
+      "route": "/products/[id]",
       "loader": "product",
       "requiredDataKeys": ["selectedProduct"],
       "defaultVariants": {
         "overview": "ProductOverview1",
-        "reviews": "ReviewRating1"
+        "reviews": "ReviewRating1",
+        "breadcrumb": "Breadcrumb"
       },
       "allowedVariants": {
         "overview": ["ProductOverview1", "ProductOverview2", "ProductOverview5"],
         "reviews": ["ReviewRating1", "ReviewRating2"],
+        "breadcrumb": ["Breadcrumb"],
         "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"]
       },
       "optionalSections": ["testimonials", "faq", "statistics"],
-      "registeredSlots": ["overview", "reviews"],
+      "registeredSlots": ["overview", "reviews", "breadcrumb"],
       "allowedSections": [],
       "maxSections": 4
     },
+    {
+      "name": "cart",
+      "mvp": true,
+      "description": "Standalone cart review page with authoritative totals and quantity editing",
+      "route": "/cart",
+      "loader": "cart",
+      "requiredDataKeys": ["cart"],
+      "defaultVariants": {
+        "view": "ShoppingCart4"
+      },
+      "allowedVariants": {
+        "view": ["ShoppingCart4"]
+      },
+      "optionalSections": [],
+      "registeredSlots": ["view"],
+      "allowedSections": [],
+      "maxSections": 0
+    },
     {
       "name": "category",
       "mvp": true,
       "description": "Product listing filtered by category with filters and sorting",
-      "route": "/categorias/[[...slug]]",
+      "route": "/categories/[[...slug]]",
       "loader": "category",
       "requiredDataKeys": ["categoryProducts", "storeCategories"],
       "defaultVariants": {
         "filter": "CategoryFilter2",
-        "productCard": "ProductCard1"
+        "productCard": "ProductCard1",
+        "breadcrumb": "Breadcrumb"
       },
       "allowedVariants": {
         "filter": ["CategoryFilter1", "CategoryFilter2", "CategoryFilter4"],
-        "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"]
+        "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"],
+        "breadcrumb": ["Breadcrumb"]
       },
       "optionalSections": ["logoCloud", "testimonials"],
-      "registeredSlots": ["filter", "productCard"],
+      "registeredSlots": ["breadcrumb", "filter", "productCard"],
       "allowedSections": ["faq", "cta"],
       "maxSections": 4
     },
@@ -90,7 +112,7 @@
       "name": "account",
       "mvp": true,
       "description": "Customer account area with sign-in, registration, and a minimal signed-in state",
-      "route": "/cuenta",
+      "route": "/account",
       "loader": "account",
       "requiredDataKeys": ["accountCustomer"],
       "defaultVariants": {
@@ -111,7 +133,7 @@
       "name": "static",
       "mvp": true,
       "description": "Content-driven static pages (contact, legal, about) with per-page metadata",
-      "route": "/contacto",
+      "route": "/contact",
       "loader": "static",
       "requiredDataKeys": [],
       "defaultVariants": {},
@@ -120,26 +142,6 @@
       "registeredSlots": [],
       "allowedSections": [],
       "maxSections": 0
-    },
-    {
-      "name": "user-panel",
-      "mvp": false,
-      "description": "Customer account area with order history and account navigation",
-      "route": "/cuenta",
-      "loader": "userPanel",
-      "requiredDataKeys": ["lastOrder", "lastOrderLines", "orderPlaced"],
-      "defaultVariants": {
-        "shell": "AppShell1",
-        "orderHistory": "OrderHistory1"
-      },
-      "allowedVariants": {
-        "shell": ["AppShell1"],
-        "orderHistory": ["OrderHistory1", "OrderHistory2"]
-      },
-      "optionalSections": [],
-      "registeredSlots": ["shell", "orderHistory"],
-      "allowedSections": [],
-      "maxSections": 4
     }
   ]
 }

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

@@ -31,6 +31,16 @@
       "propsHint": "badgeText, title, description, primaryCta/secondaryCta (label, href)",
       "status": "executable"
     },
+    {
+      "name": "products",
+      "description": "Data-bound product presentation (grid or combined grid-and-carousel) whose selection is configured independently per instance",
+      "elementType": "Products",
+      "variants": ["ProductCard1", "ProductShowcase1"],
+      "defaultVariant": "ProductCard1",
+      "dataBound": true,
+      "propsHint": "per-instance selection configured in views/<view>/data.ts sectionSources[id] (canonical category/collection/search/ordering query); heading, description, objective, ctaLabel/ctaHref are editorial content",
+      "status": "executable"
+    },
     {
       "name": "statistics",
       "description": "Key metrics or trust statistics",

package/skills/sf-view-gen/assets/templates/views/sections/products.client.tsx

@@ -0,0 +1,100 @@
+'use client'
+
+// Optional section fragment: products (mirrors recipes/sections.json) — client registry.
+// The matching server-side catalog lives in products.tsx. A data-bound section
+// renders one of two verified presentations (ProductCard1 grid, or the combined
+// grid-and-carousel ProductShowcase1) chosen by the resolved `variant`. The
+// selection and resolved products arrive through the view state; this boundary
+// only validates them and wires navigation/purchase callbacks.
+
+import {
+  ProductCard1 as ProductCard1Block,
+  ProductShowcase1 as ProductShowcase1Block,
+  type ProductCard1Product,
+} from '@thorprovider/blocks'
+import { useStateStore } from '@json-render/react'
+import { useSectionObservation } from '../../section-observation'
+import { productsPropsSchema, type ProductsStatus } from './schema.products'
+import type { ViewRegistry } from '../types'
+
+// Truthful, actionable messages for the non-`ready` states. A failed or
+// unconfigured section never fabricates products.
+function sectionStatusMessage(status: ProductsStatus): string {
+  switch (status) {
+    case 'unconfigured':
+      return 'Esta sección de productos aún no tiene una selección configurada.'
+    case 'empty':
+      return 'Esta selección no tiene productos disponibles por ahora.'
+    case 'invalid-query':
+      return 'La selección de productos de esta sección no es válida.'
+    case 'unsupported-query':
+      return 'Esta selección usa criterios que el catálogo no admite.'
+    case 'unmounted-capability':
+      return 'Esta selección requiere una capacidad que este catálogo no tiene montada.'
+    case 'data-error':
+      return 'No se pudieron cargar los productos de esta sección.'
+    default:
+      return ''
+  }
+}
+
+export const productsRegistry: ViewRegistry = {
+  Products: ({ props, emit }) => {
+    const { set } = useStateStore()
+    const parsed = productsPropsSchema.parse(props)
+    const { containerRef, noteProductClick } = useSectionObservation({
+      sectionId: parsed.sectionId ?? '',
+      sectionType: parsed.sectionType ?? 'products',
+      ...(parsed.variant ? { sectionVariant: parsed.variant } : {}),
+      ...(parsed.objective ? { objective: parsed.objective } : {}),
+    })
+
+    if (parsed.status !== 'ready') {
+      return (
+        <section
+          aria-label={parsed.heading ?? 'Productos'}
+          className="mx-auto w-full max-w-7xl px-4 py-12"
+        >
+          {parsed.heading ? (
+            <h2 className="mb-2 text-2xl font-semibold tracking-tight">{parsed.heading}</h2>
+          ) : null}
+          <p className="text-sm text-muted-foreground">{sectionStatusMessage(parsed.status)}</p>
+        </section>
+      )
+    }
+
+    // The detail affordance opens the product so a variant is chosen explicitly.
+    // It is also the section's observation origin (disabled by default).
+    const openProduct = (product: ProductCard1Product) => {
+      noteProductClick(product)
+      set('/lastClicked', product)
+      emit('openProduct')
+    }
+
+    // Product-card shortcut: the add affordance adds the product's first
+    // purchasable variant (resolved server-side from the product id), then opens
+    // the mini-cart. It is not the section's observation origin.
+    const addToCart = (product: ProductCard1Product) => {
+      set('/lastClicked', product)
+      emit('addClickedToCart')
+    }
+
+    const shared = {
+      products: parsed.products,
+      heading: parsed.heading,
+      description: parsed.description,
+      onAddToCart: addToCart,
+      onProductClick: openProduct,
+    }
+
+    return (
+      <div ref={containerRef}>
+        {parsed.variant === 'ProductShowcase1' ? (
+          <ProductShowcase1Block {...shared} />
+        ) : (
+          <ProductCard1Block {...shared} />
+        )}
+      </div>
+    )
+  },
+}

package/skills/sf-view-gen/assets/templates/views/sections/products.tsx

@@ -0,0 +1,19 @@
+// Optional section fragment: products (mirrors recipes/sections.json)
+// Server-side part: element type + zod catalog entry. The component mappings
+// live in products.client.tsx ('use client'). Unlike the stateless editorial
+// fragments (faq/cta), the products section is data-bound: its per-instance
+// selection is resolved by the host loader and delivered through the view state,
+// so this catalog entry describes the *resolved* props shape.
+
+import { productsPropsSchema } from './schema.products'
+
+export const productsSection = {
+  elementType: 'Products',
+  catalog: {
+    Products: {
+      props: productsPropsSchema,
+      description: 'Data-bound product presentation (grid or combined grid-and-carousel).',
+    },
+  },
+  registryModule: './products.client',
+}

package/skills/sf-view-gen/assets/templates/views/sections/schema.products.ts

@@ -0,0 +1,39 @@
+// Optional section fragment: products (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the resolved Products section props, shared by the server catalog
+// (products.tsx) and the client registry (products.client.tsx). The product list
+// reuses the canonical presentation contract owned by @thorprovider/blocks so the
+// section renders exactly what the host mapped from the catalog result.
+
+import { z } from 'zod'
+import { productPresentationSchema } from '@thorprovider/blocks'
+
+// The per-instance resolution status the host loader computes for a data-bound
+// section. `ready`/`empty` carry resolved products; the remaining states carry no
+// products and render an actionable, truthful message instead.
+export const productsStatusSchema = z.enum([
+  'unconfigured',
+  'ready',
+  'empty',
+  'invalid-query',
+  'unsupported-query',
+  'unmounted-capability',
+  'data-error',
+])
+
+export const productsPropsSchema = z.object({
+  sectionId: z.string().min(1).optional(),
+  sectionType: z.string().min(1).optional(),
+  variant: z.string().optional(),
+  // Defensive defaults: a missing resolved state (e.g. the view loader could not
+  // run) degrades to a truthful error instead of crashing the render.
+  status: productsStatusSchema.default('data-error'),
+  products: z.array(productPresentationSchema).default([]),
+  heading: z.string().optional(),
+  description: z.string().optional(),
+  objective: z.string().optional(),
+  ctaLabel: z.string().optional(),
+  ctaHref: z.string().optional(),
+})
+
+export type ProductsProps = z.infer<typeof productsPropsSchema>
+export type ProductsStatus = z.infer<typeof productsStatusSchema>