@thorprovider/blocks 0.1.3 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,155 @@
+# @thorprovider/blocks
+
+## 2.0.0
+
+### Major Changes
+
+- dc82f71: Consolidate the category filter family into one canonical `CategoryListing` block.
+
+  - Adds `CategoryListing` (export + `CategoryListingProps` and the `CategoryListing*` option, facet, status, filter and active-filter types). It is the single controlled listing controller: products, pagination and the selected query are props; `on*Change` / `onClearFilters` / `onRepair` / `onRetry` report intent; the block never fetches, parses the URL, or keeps a private query.
+  - Two bounded presentations share one contract: `sidebar` (default; persistent desktop panel plus mobile sheet) and `toolbar` (sticky mobile toolbar, filter/sort drawers and chip rail). Presentation changes chrome only.
+  - Results render through the canonical `ProductCard` (`minimal`), so the listing owns no card markup. Facets are generic option-only groups supplied by the host; a group renders only from real metadata, a real `0` count is displayed, and an absent/invalid count is omitted. Price renders only from a real finite range, sort only from advertised options, and no result total is fabricated.
+  - `ProductCard` gains `hideAddToCart` for listing cells and renders `data-slot='product-image-placeholder'` instead of an image with an empty source.
+  - Runtime: `toFilterProduct` → `toListingProduct` (returns canonical `ProductPresentation` with `Money`), `CategoryFilterPresentation(Input)` → `CategoryListingPresentation(Input)`, `mapCatalogResultsToFilterProps` → `mapCatalogResultsToCategoryListing`, and `resolveFilterPresentationSupport` → `resolveCategoryListingSupport` plus a separate `resolveCategoryFacetSupport`. The old numbered presentation metadata is gone.
+
+  BREAKING: removes the `CategoryFilter1`, `CategoryFilter2` and `CategoryFilter4` exports, their types, and the `category-filter-4-*` helpers. Consumers must migrate to `CategoryListing`:
+
+  | Removed           | Migration                                                                                                                                                                                     |
+  | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `CategoryFilter1` | `CategoryListing` with `presentation='sidebar'`; replace counted categories/price bands with real `categories` / `priceRange` metadata.                                                       |
+  | `CategoryFilter2` | `CategoryListing` with `presentation='sidebar'` (the default). Products become canonical `ProductPresentation` items with `Money` prices; `filterPrice` string prices are no longer accepted. |
+  | `CategoryFilter4` | `CategoryListing` with `presentation='toolbar'`; replace bike-specific facets/frame/model fields with generic `facets` groups and remove its private grid/state.                              |
+
+- 28a3bd7: Consolidate the numbered checkout-form family into one canonical page-level `Checkout` block.
+
+  - Adds `Checkout` (export plus `CheckoutProps`, `CheckoutValues`, `CheckoutPresentation`, `CheckoutStepId`, `CheckoutLabels`, `CheckoutValuesFieldErrors`, `CheckoutFieldDescriptions`, `CheckoutChangeHandler`, `CheckoutOrderSummary`, `CheckoutOrderLine`, `CheckoutTotals`, `CheckoutTotalsState`, `CheckoutCountryOption`, `CheckoutShippingOption`) with a required bounded `presentation` (`single-page` | `stepper`) and an orthogonal `showReviewStep` flow option. `single-page` is the former `CheckoutForm2` structure; `stepper` is the former `CheckoutForm1` wizard; `stepper` plus the review option is the former `CheckoutForm3`. Field values are controlled (`values` + `onChange`), the step index is ephemeral block state, and `validateStep(step: CheckoutStepId)` is injected — the block contains no validation logic.
+  - Totals are canonical `Money` only and render verbatim from the host; the legacy numeric `price`/`shipping`/`tax`/`discount`/`promoDiscount` fields and their fallback summation are removed. A missing or malformed required total renders as unavailable with recovery, never as zero.
+  - Removes raw card capture: `cardNumber`, `expiryDate`, `cvv`, `cardName`, the `collectCardFields` escape hatch, the CVV visibility toggle, and `card-formatting.ts`. Payment methods remain data (`PaymentMethod[]`); card collection belongs to the host payment-provider surface.
+  - Removes the numbered exports `CheckoutForm1`, `CheckoutForm2`, `CheckoutForm3` and their `CheckoutForm1*`, `CheckoutForm2*`, `CheckoutForm3*` types.
+
+  BREAKING: consumers importing a numbered checkout must migrate to `Checkout` with the `presentation` prop (and `showReviewStep` for the review flow). Values lose the card fields and `sameAsBilling`; totals must be supplied as backend `Money`; `validateStep` now receives a `CheckoutStepId` instead of a step number.
+
+- 06333a8: Consolidate the navigation family into two canonical components and retire the numbered navbars.
+
+  - `Navbar` is the canonical page-level header with bounded `bar`, `mega`, and `floating` presentations. Content is serializable (`links`, `items`, `featured`, `signIn`, `cta`, `logoText`, `logoHref`, `currentPath`); icons resolve through a host-bound `iconMap`; `floating` uses `sticky` so it reserves its own space.
+  - `StorefrontNavbar` is the canonical commerce shell (formerly `Navbar4`) and keeps its full storefront contract: utility strip, category navigation, optional search, account states, and the controlled cart sheet with canonical `Money`.
+  - Removed identifiers: `Navbar1`, `Navbar2`, `Navbar3`, `Navbar4`, `navbar4PropsSchema`, `Navbar4SpecProps`, `Navbar4LikeButton`, `Navbar4ProductGrid`, and the `navbar-4-*` helper modules (now `storefront-navbar-cart-sheet`, `storefront-navbar-account-menu`, `storefront-navbar-search-bar`, `storefront-navbar-mobile-nav`).
+  - The page-level header no longer owns cart state: `cartCount` and `onOpenCart` are gone. Use the commerce shell for the cart affordance.
+
+- 65fac4b: Remove the numbered compatibility adapters `Testimonial1`, `Testimonial2`, `LoginPage1`, `LoginPage2`, `FooterSection1`, `FooterSection3`, and `FooterSection4`, including their deep module paths and legacy prop types. Migrate testimonials to `TestimonialSection` with `carousel` or `bento`, login pages to `LoginPage` with `card` or `social`, and footers to `FooterSection` with `brand-columns`, `newsletter-grid`, or `contact`. Select native footer link behavior explicitly where browser navigation is intended.
+
+### Minor Changes
+
+- 5d32763: The auth blocks render into the host page instead of owning it.
+
+  `LoginPage` (both `card` and `social`), `SignUpPage1`, `ForgotPasswordPage1` and `Verify1` no longer paint a full-viewport surface. They drop the `min-h-dvh` canvas, the page landmark (the `social` presentation no longer renders a root `<main>`), the `bg-linear-to-br` backdrop with `isolate`/`overflow-hidden`, the vertical centring and the page-level padding. Each block now renders a neutral, content-sized root that keeps its width cap (`max-w-md` for login and recovery, `max-w-lg` for registration) and its card styling, including the shadow.
+
+  Why: a generated storefront mounts these blocks inside the default chrome (notice + banner + navbar + footer). A viewport-height canvas inside that chrome centres the form roughly 100 px low and, for the `social` presentation, emits a second `<main>` landmark inside the page's own `<main>`.
+
+  No prop, type or export changed, so existing call sites keep compiling. What changes is visual ownership: a host that relied on the block's canvas must now supply one (a route shell, a modal, a split screen, or a template the host owns), using the same theme tokens. `@thorprovider/storefront` does exactly that for the generated `account` view, which keeps the shopper-visible result unchanged.
+
+## 1.0.0
+
+### Major Changes
+
+- f011717: Consolidate the `home.benefits` feature family into one canonical `Feature` block.
+
+  - Adds `Feature` (export + `featurePropsSchema` / `FeatureProps` in the contracts surface) with a bounded `presentation` prop (`cards` | `split`, default `cards`). `cards` is the former header-badge card grid with per-item learn-more and an optional section CTA; `split` is the former split layout with the optional grayscale image column. `split` deliberately ignores `badge` and per-item learn-more; an absent or empty image `src` renders no image column (never a blank `src`).
+  - The storefront catalog declares the two presentations as the `home.benefits` variants with `legacyAliases` (`Feature1` → `cards`, `Feature2` → `split`), so existing manifests storing the numbered names keep regenerating to the same presentation; the benefits feature's `compact` / `detailed` configuration values are unchanged and map onto `cards` / `split`.
+
+  BREAKING: removes the `Feature1` and `Feature2` exports (components and their `Feature1Props`/`Feature1Item`/`Feature2Props`/`Feature2Item` types) that this canonical block supersedes. Consumers must migrate to `Feature` with the `presentation` prop.
+
+- f011717: Consolidate the product-card family into one canonical `ProductCard` block.
+
+  - Adds `ProductCard` (export + `productCardPropsSchema` / `ProductCardSpecProps` in the contracts surface) with a bounded `presentation` prop (`classic` | `minimal` | `rich`, default `classic`). `classic` is the former `ProductCard1` structure (badge, optional rating, compare-at, add-to-cart footer, reduced-motion-safe motion); `minimal` is the former `ProductCard2` lean look; `rich` is the former `ProductCard3` overlay actions (wishlist heart with host-owned controlled state or uncontrolled visual fallback, and view-similar rendered only when a handler is supplied). The comparison-table surface of the former `ProductCard5` is deliberately retired (a listing controller, not an item cell).
+  - Items are the canonical `ProductPresentation` contract only (identity, title, optional image with alt, canonical `Money` price, optional `compareAtPrice`/`rating`/`badge`). An unresolved price renders an unavailable state with add-to-cart disabled — never a zero. Ratings, badges and crossed-out prices render only from host-supplied data; the block invents no evidence. Prices render through the canonical `formatMoney` path (no hardcoded currency symbol) and all user-facing copy is overridable with the previous Spanish defaults.
+  - Removes the numbered exports `ProductCard1`, `ProductCard2`, `ProductCard3`, `ProductCard5`, their types `ProductCard1Product` / `ProductCard1Props`, the contracts surface `productCard1PropsSchema` / `ProductCard1SpecProps`, and the `product-card-3-reaction-toggle` / `product-card-5-reaction-toggle` / `product-card-5-checkbox-check` subcomponents.
+  - Migration: supply item data in the canonical presentation contract (canonical `Money` amounts as decimal major-unit strings plus `currencyCode`). The former numeric-price props (`price: number`, `originalPrice?: number`, mandatory demo merchandising fields) are not retained; map them to `Money` at your boundary. Consumer code importing a numbered card selects the equivalent bounded presentation (`1` → `classic`, `2` → `minimal`, `3` → `rich`); the former comparison table has no replacement in this block.
+
+- f011717: Consolidate the `home.categories` family into one canonical `ProductCategory` block.
+
+  - Adds `ProductCategory` (export + `productCategoryPropsSchema` / `ProductCategoryProps`) built on the canonical `CategoryCard` shape. It exposes a bounded `presentation` prop (`grid` | `icons` | `list`); optional per-category data (`icon` as a serializable key, `subcategories`, `featured`, `itemCount`) degrades gracefully when absent.
+  - Interaction is controlled: `onBrowse` / `onViewAll` / `onQueryChange` report from handlers with no private query state; a category count is omitted when absent or invalid and a real zero is preserved; a missing image renders a neutral placeholder, never `src=""`; no copy, currency, or demo metrics are hardcoded.
+
+  BREAKING: removes the `ProductCategory1`, `ProductCategory2`, `ProductCategory4`, and `ProductCategory5` exports (and the `product-categories/avatar-group` helper) that this canonical block supersedes. Consumers must migrate to `ProductCategory` with the `presentation` prop.
+
+- ece154d: Consolidate the `product.overview` family into one canonical `ProductOverview` block.
+
+  - Adds `ProductOverview` (export + `productOverviewPropsSchema` / `ProductOverviewProps`) built on the canonical `ProductDetailProduct` projection and canonical `Money`. It exposes a bounded `presentation` prop (`standard` | `gallery` | `rich`); `rich` accepts optional `specifications` / `features` / `reviews` props and degrades gracefully when they are absent.
+  - Selection and quantity are controlled; `onAddToCart` emits the explicitly selected backend variant id and quantity and never substitutes the first variant. Missing price renders as unavailable, never `$0`; currency is never hardcoded.
+
+  BREAKING: removes the `ProductOverview1`, `ProductOverview2`, and `ProductOverview5` exports (and the `product-overview-5-*` subcomponents) that this canonical block supersedes. Consumers must migrate to `ProductOverview` with the `presentation` prop.
+
+- b41cc50: Consolidate the numbered shopping-cart family into one canonical `ShoppingCart` block.
+
+  - Adds `ShoppingCart` (export + `shoppingCartPropsSchema` / `ShoppingCartSpecProps` in the contracts surface) with a bounded `presentation` prop (`compact` | `page`). `compact` is the former `ShoppingCart4` review card; `page` is the same contract with the page-level structure. The optional promo-entry affordance reports the entered code via `onApplyPromo(code)` and renders only authoritative promotion/discount data — it is hidden when the callback is absent, and the block never validates promotion codes itself. Host-supplied `recentlyViewed` suggestions replace the former `ShoppingCart2` recommendations, priced with canonical `Money`.
+  - Items are the canonical contract only: identity, title, quantity, optional image (omitted when absent, never `src=""`), and canonical `Money` amounts. Each line carries the backend-authoritative `lineTotal` (rendered verbatim; a malformed amount renders as unavailable — never a zero or free-shipping claim) and an optional `unitPrice` carried verbatim but never used for local arithmetic. `totals` come from the backend and are rendered verbatim; no local tax/shipping/threshold math, no fabricated merchandising, no hardcoded currency.
+  - Removes the numbered exports `ShoppingCart1`, `ShoppingCart2`, `ShoppingCart3`, `ShoppingCart4` (and their `ShoppingCart1CartItem`, `ShoppingCart2Props`/`ShoppingCart2Item`, `ShoppingCart3Props`/`ShoppingCart3CartItem`, `ShoppingCart4Props`/`ShoppingCart4Item` types), the contracts surface `shoppingCart4PropsSchema` / `ShoppingCart4SpecProps`, and the `shopping-cart-{1,2,3,4}-spinning-counter`, `shopping-cart-2-recommendations`, and `shopping-cart-2-item-row` subcomponents.
+
+  BREAKING: consumers importing a numbered cart must migrate to `ShoppingCart` with the `presentation` prop. The former numeric-price props (`price: number`, local `taxRate`/shipping-threshold arithmetic) are not retained; map item amounts to canonical `Money` (`{ amount, currencyCode }`) at your boundary and pass backend `totals` verbatim.
+
+- f011717: Consolidate the `home.hero` family into one canonical `StorefrontHero` block.
+
+  - Adds `StorefrontHero` (export + `storefrontHeroPropsSchema` / `StorefrontHeroProps` / `StorefrontHeroProduct` in the contracts surface) with a bounded `presentation` prop (`compact` | `showcase` | `editorial` | `promotional`) reusing the registry's archetype intent vocabulary. `compact` is the former `StorefrontHero1` text-forward hero with product grid and editorial image seam; `showcase` the former `StorefrontHero2` search + rotating product carousel (the search input renders only when `onSearch` is supplied); `editorial` the former `StorefrontHero5` department grid with optional featured deals and store locator; `promotional` the former `StorefrontHero6` deals bar + category grid.
+  - Truthful evidence only: ratings, review counts, category/department counts, deal descriptions, and countdowns render only from host-supplied data; discount treatments render only from a real `originalPrice > price` pair (`isOnSale` is dropped); `currency` (ISO 4217) formats all amounts via `Intl.NumberFormat` — no hardcoded `$`. Rotation respects reduced motion and is presentation-internal.
+  - The storefront catalog declares `StorefrontHero` as the single `home.hero` variant with `legacyAliases` (`StorefrontHero1`/`2`/`5`/`6` → the canonical), so existing manifests storing the numbered names keep regenerating to a working composition; `archetypes.json` intents map each intent to its matching presentation.
+
+  BREAKING: removes the `StorefrontHero1`, `StorefrontHero2`, `StorefrontHero5`, and `StorefrontHero6` exports (and the `StorefrontHero1Props` type) that this canonical block supersedes. The `FeaturedProduct` type is now exported from the canonical source and its evidence fields (`brand`, `colors`, `rating`, `reviewCount`, `originalPrice`) are optional. Consumers must migrate to `StorefrontHero` with the `presentation` prop.
+
+- dc2b11b: Split the category collection into an item cell and a listing.
+
+  - `CategoryCard` is the item cell: one `category` at a time, with the existing `grid`, `icons` and `list` presentations. It renders no section, heading, search, CTA or empty state.
+  - `CategoryGrid` is the listing: it owns the collection, `maxItems`, section copy, controlled search (list presentation), loading skeletons and the empty state, and renders `CategoryCard` for every item.
+  - BREAKING: `ProductCategory` (collection) is replaced by `CategoryGrid`; the single-item surface is `CategoryCard`. `ProductCategoryProps` is replaced by `CategoryGridProps` / `CategoryCardProps`.
+
+  Migration: replace `<ProductCategory categories={items} ... />` with `<CategoryGrid categories={items} ... />`. For a single category, render `<CategoryCard category={item} ... />`.
+
+- 3e43eb0: BREAKING: `ProductCard` is now an item cell and a new `ProductGrid` listing owns the collection.
+
+  - `ProductCard` (`packages/blocks/src/blocks/e-commerce/product-list/product-card.tsx`) now takes a single `item: ProductPresentation` (plus `presentation?` and `wishlisted?`) and renders exactly one cell — no section wrapper, no section heading, no grid, and no item cap. The `items`, `heading`, and `maxItems` props and the `wishlistedIds` collection prop are removed; `wishlisted` is now a single host-resolved boolean.
+  - The serializable contract `productCardPropsSchema` / `ProductCardSpecProps` changes accordingly (`{ item, presentation?, wishlisted? }`), still without callbacks or label strings.
+  - Adds `ProductGrid` (export + `productGridPropsSchema` / `ProductGridSpecProps`) as the canonical listing: it takes `items: ProductPresentation[]`, an optional `presentation`, `heading`, `maxItems`, `wishlistedIds`, and owns the `loading` (skeletons), `empty` (overridable copy), and ready states. It renders `ProductCard` cells (single source of cell markup) and reports actions through the same callbacks. `error` remains the host's responsibility.
+  - Migration: pass a listing's data to `ProductGrid` with `items`, `heading`, and `maxItems`; pass a single item to `ProductCard` via `item`. Resolve rich-presentation wishlist state per cell through `wishlistedIds` on the grid or `wishlisted` on the cell. The delimited showcase `ProductShowcase1` is unchanged.
+
+- b41cc50: Require an image for the `Feature` block's `split` presentation.
+
+  - `featureSplitSpecSchema` now requires `presentation: 'split'` and a non-empty, trimmed `image.src`; `featureCardsSpecSchema` keeps `image` out of its contract. `featurePropsSchema` is the union of both branches, so TypeScript narrows `image` only after checking `presentation`.
+  - The component throws a configuration error when an untyped caller renders `split` without a non-empty image, instead of silently dropping the media column. `cards` is unchanged.
+  - Editorial fallbacks belong to the consumer, not the block library. The showcase now owns `public/demo/editorial-fallback.svg`; the storefront template seeds a neutral image in user-owned `content.ts`.
+
+  Migration: pass `{ image: { src, alt } }` when using `presentation="split"`, or switch to `presentation="cards"` if the section is icon-only. Replace the storefront's neutral seed with real editorial imagery.
+
+### Minor Changes
+
+- 80d4137: Add optional, backward-compatible brand customization to existing surfaces (M5):
+
+  - `@thorprovider/blocks`: `Navbar4` and `FooterSection1` accept an optional wordmark accent `{ text, className }` (trailing segment of the brand name) and an optional surface `className`; a supplied surface `className` overrides the default surface paint (default background/backdrop not emitted) so a branded surface paints correctly. `StorefrontHero1` accepts an optional editorial `heroImage { src, alt }` rendered with a native, guarded image. `ProductCategory2` accepts an optional `itemCount`: an unknown count is omitted (no fabricated `0`), a real `0` is preserved, and non-finite/negative values render no count. All props are optional and omit to the current rendering, so existing consumers are unchanged; no new block type or variant is added, and the blocks stay framework-, backend-, and data-free.
+  - `@thorprovider/storefront`: the scaffold generates a user-owned `lib/<name>/shell/{content,props}.ts` seam (brand accents, surface classes, footer description/links, newsletter) that the derived spec composes last, so `storefront sync` regenerates only derived wiring and preserves user-owned edits. The scaffold ships no newsletter submit callback, so the newsletter is omitted by default rather than rendering a fake form; default footer copy makes no delivery/shipping promise and links only to routes the storefront serves (no assumed route). No new identity CLI command is added — `create --site-name` already covers the site name.
+
+  This changeset adds release metadata only; it does not bump versions or publish packages.
+
+- 3b3c24c: Add validated single-store commerce contracts, explicit real/mock policy, directed variant pricing, persistent guest carts, backend-authoritative totals, manual TEST checkout, and capability-authorized receipt reconciliation in generated storefronts.
+
+  Breaking migration: `@thorprovider/types` is now entirely type-only. Import `SupportedProviderType`, `PROVIDER_METADATA`, `isSupportedProviderType`, `getProviderMetadata`, and `StorefrontConfigError` from `@thorprovider/adapters` instead. The pre-1.0 curated blocks/runtime APIs also change: product detail uses canonical options/variants/Money and explicit variant selection; confirmation totals and lines use Money; `formatMoney` returns `null` for unavailable values. Real-mode failures no longer silently return mock data.
+
+  The local packed MVP candidate retains its exact current version pins until a separate release updates the compatible toolset. This changeset does not publish packages or establish public-sales readiness.
+
+- b41cc50: Deliver the global shopper account experience (M5, change `storefront-navbar-account-menu`):
+
+  - `@thorprovider/blocks`: `Navbar4` renders a session-driven account affordance from consumer props only. An authenticated `user` (optional `avatar`) with `accountMenuItems` gets an account menu (identity + configured items + consumer-supplied sign-out); no `user` with a configured `accountHref` gets a signed-out entry point on desktop and mobile; neither configured renders no account affordance or empty container. Optional `accountPending`/`accountUnavailable` drive a pending/disabled state and an accessible unavailable/retry state (`onAccountRetry`) without presenting either as anonymous, and sign-out is suppressed while pending. Absent avatar uses the initials fallback (no empty image `src`). All callbacks stay consumer bindings outside the serializable JSON prop schema; the block never authenticates.
+  - `@thorprovider/storefront`: a mounted `customer-auth` resolves the shopper server-side per request and seeds an allowlisted display identity (`id`, `email`, `firstName`, `lastName`; the auth token stays in its httpOnly cookie). One shared client lifecycle (`account-lifecycle.client.tsx`) owns identity, guarded claims, login/register/logout, and retry with no identity fetch on mount or navigation; it reconciles same-store tabs through non-secret store-scoped signals (`BroadcastChannel` with a storage-event fallback) and on foreground/resume, discards stale generations, and shows a neutral pending state instead of stale identity/orders or a fake sign-out. `/account` is the only account surface — sign-in, registration, identity, sign-out, and real paginated orders + detail (route-scoped commerce, no direct HTTP); no address book/profile/wishlist/social/recovery/cart-merge. Account wiring is delivered through derived files (`account-session*.ts`, `account-lifecycle/account-boundary/account-mutation/account-reconcile.client.*`, `account-private.core.ts`, `account-user.core.ts`, `projection-ownership*.ts`, `registry.tsx`, `schema.ts`, `spec/index.ts`); user-owned files (`views/*/{schema,content,props,data}.ts`, `mappers.ts`, `icon-map.ts`, `shell/**`) survive `sync`. `storefront feature add|remove customer-auth` toggles the `/account` route, session reads, listeners, and navbar chrome together; without the feature the generated registry carries no account-lifecycle/account-reconcile reference and reads no session.
+  - `@thorprovider/adapters`: `getCurrentCustomer()` resolves `null` only for a confirmed unauthenticated response (HTTP 401 / `"Unauthorized"`) and throws a typed `ProviderAPIError` (`GET_CURRENT_CUSTOMER_FAILED`) on operational failures (network, timeout, 5xx), so a host can distinguish an anonymous shopper from a backend outage and render the unavailable state instead of a false sign-out. `isAuthenticated()` delegates to it and can reject. Signature and framework-agnostic boundary are unchanged.
+
+  This changeset adds release metadata only; it does not bump versions or publish packages.
+
+- ece154d: Gate the `ProductOverview` wishlist affordance on a wired handler.
+
+  - `ProductOverview` renders its wishlist button only when `onToggleWishlist` is supplied; an unwired button is a dead control and is no longer rendered in any presentation (`standard`, `gallery`, `rich`).
+  - The storefront product template and the demo/electrostore registries drop their no-op `onToggleWishlist` wiring, so a storefront without wishlist backend support no longer shows a non-functional heart.
+
+### Patch Changes
+
+- ece154d: Align the `Breadcrumb` block with the page content: the trail now renders inside the shared responsive container (`mx-auto w-full max-w-7xl px-4 py-4 sm:px-6 lg:px-8`) that sibling blocks use, instead of sitting flush against the viewport edge. The container is merged with the incoming `className` via `cn`, so a custom `className` can still override it.
+- Updated dependencies [23f876f]
+- Updated dependencies [3b3c24c]
+  - @thorprovider/types@6.0.0

package/README.md

@@ -1,7 +1,7 @@
 ---
 title: "@thorprovider/blocks"
 purpose: "Reusable, framework-agnostic storefront blocks built from ShadcnStore UI, decoupled from data and backend"
-lastReviewed: "2026-09-23"
+lastReviewed: "2026-10-21"
 ---
 
 # @thorprovider/blocks
@@ -30,7 +30,7 @@ src/
     │   └── hero-sections/hero-section-1.tsx
     └── e-commerce/
         ├── product-list/product-card-1.tsx
-        └── storefront-hero/storefront-hero-1.tsx
+        └── storefront-hero/storefront-hero.tsx
 ```
 
 Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locates its own prop types unless a contract is shared by two or more blocks.
@@ -39,72 +39,159 @@ Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locat
 
 | Export | Category | Description |
 | --- | --- | --- |
-| `Navbar1` | Marketing | Simple navbar with logo, links, sign-in, CTA and cart count |
-| `Navbar2` | Marketing | Mega-menu navbar with grouped flyouts and featured card |
-| `Navbar3` | Marketing | Floating navbar that condenses into a rounded pill on scroll |
-| `Navbar4` | Marketing | Storefront navbar: utility bar, category links, search, account menu, cart sheet |
+| `Navbar` | Marketing | Page-level navigation header: `bar`, `mega` (grouped flyouts plus optional featured promo) or `floating` (self-reserving pinned pill) |
+| `StorefrontNavbar` | E-commerce | Commerce navigation shell: utility strip, category mega menu, optional search, account menu, cart sheet |
 | `Banner1` | Marketing | Announcement banner (bar or pill) with dismiss |
 | `HeroSection1` | Marketing | Hero with badge, headline, CTA, reviewer avatars, rating and image |
 | `CtaSection1` | Marketing | Full-width call-to-action with badge, headline and two CTAs |
-| `Feature1` | Marketing | Icon feature grid |
-| `Feature2` | Marketing | Split features with image |
-| `Testimonial1` | Marketing | Testimonial carousel with rating stars |
-| `Testimonial2` | Marketing | Bento testimonials grid |
+| `Feature` | Marketing | Canonical benefits section: `cards` (icon feature grid) or `split` (editorial split with a required image) presentation |
+| `TestimonialSection` | Marketing | Canonical testimonial collection section with `carousel` and `bento` presentations |
 | `FaqBlock1` | Marketing | FAQ accordion (single or multiple open) |
 | `PricingSection1` | Marketing | Pricing tiers with popular badge |
 | `Statistic1` | Marketing | Metrics grid with progress bars |
 | `LogoCloud1` | Marketing | Logo cloud with skeleton fallback |
-| `FooterSection1` | Marketing | Footer with brand, link columns and newsletter |
-| `FooterSection3` | Marketing | Newsletter + six-column footer with social links |
-| `ProductCard1` | E-commerce | Deals grid of product cards with add-to-cart |
-| `ProductCard2` | E-commerce | Clean three-up grid with ratings |
-| `ProductCard3` | E-commerce | Deals grid with badges, low-stock and wishlist |
-| `ProductCard5` | E-commerce | Table-style comparison with sorting and filtering |
+| `FooterSection` | Marketing | Canonical page-level footer with `brand-columns`, `newsletter-grid` or `contact` presentation |
+| `ProductCard` | E-commerce | Canonical product card (item cell of a listing); `presentation` `classic`/`minimal`/`rich`, canonical `ProductPresentation` items with `Money` prices, evidence-only merchandising |
 | `ProductShowcase1` | E-commerce | Combined grid-and-carousel of product cards with manual paging |
-| `ProductOverview1` | E-commerce | Product detail with gallery, variants and add-to-cart |
+| `ProductOverview` | E-commerce | Canonical product detail; bounded `presentation` `standard`/`gallery`/`rich` (rich adds optional specs/features/reviews tabs) |
 | `ProductQuickView` | E-commerce | Quick-view dialog with gallery, variants and quantity |
 | `ReviewRating1` | E-commerce | Review list with rating summary |
 | `ReviewRating2` | E-commerce | Rating summary with distribution and review carousel |
-| `ProductCategory1` | E-commerce | Category grid with view-all |
-| `ProductCategory2` | E-commerce | Image-based category cards |
-| `ProductCategory4` | E-commerce | Icon grid with customer/product counts |
-| `ProductCategory5` | E-commerce | Category list with search and subcategories |
-| `CategoryFilter1` | E-commerce | Category filter bar |
-| `CategoryFilter2` | E-commerce | Filter sidebar with mobile sheet |
-| `ShoppingCart1` | E-commerce | Detailed cart summary |
-| `ShoppingCart2` | E-commerce | Cart with promo code and shipping |
-| `ShoppingCart4` | E-commerce | Cart review with backend-authoritative totals; `presentation` `compact` (collapsible card) or `page` (full-width review) |
-| `CheckoutForm1` | E-commerce | Essential checkout fields |
-| `CheckoutForm2` | E-commerce | Single-page checkout with order summary beside |
+| `ProductCategory` | E-commerce | Canonical category block; bounded `presentation` `grid` (image cards) / `icons` (compact icon grid) / `list` (rows with subcategory chips and optional controlled search) |
+| `CategoryListing` | E-commerce | Canonical category listing (results + pagination) with a controlled query and bounded `presentation` `sidebar` (persistent desktop panel + mobile sheet) / `toolbar` (sticky mobile toolbar + drawers); generic facet groups render only from real metadata |
+| `ShoppingCart` | E-commerce | Canonical cart; backend-authoritative `Money` totals and item lines, optional promo entry and recently-viewed suggestions; `presentation` `compact` (collapsible card) or `page` (full-width review) |
+| `Checkout` | E-commerce | Canonical page-level checkout; controlled values, backend-authoritative `Money` totals, `PaymentMethod[]` data with no raw card input; `presentation` `single-page` or `stepper`, optional `showReviewStep` |
 | `CheckoutConfirmation` | E-commerce | Order confirmation with fulfilment timeline |
 | `OrderHistory1` | E-commerce | Orders list |
 | `OrderHistory2` | E-commerce | Order cards with carousel items |
-| `StorefrontHero1` | E-commerce | Storefront hero with gradient headline, CTAs and a product grid |
-| `StorefrontHero2` | E-commerce | Search field above a trending product carousel |
-| `StorefrontHero5` | E-commerce | Departments grid with featured deals |
-| `StorefrontHero6` | E-commerce | Rotating deals bar beside category cards |
+| `StorefrontHero` | E-commerce | Canonical storefront hero; `presentation` `compact` (gradient headline, CTAs, product grid), `showcase` (search + rotating product carousel), `editorial` (departments, featured deals, store locator) or `promotional` (rotating deals bar, category cards) |
 | `AppShell1` | Application | Application shell with navigation slots |
-| `LoginPage1` | Application | Login card with remember-me and social buttons |
-| `LoginPage2` | Application | Login with prominent social options |
-| `SignUpPage1` | Application | Registration card with social options |
+| `LoginPage` | Application | Canonical sign-in form with explicit `card` or `social` presentation |
+| `SignUpPage1` | Application | Registration form with social options (same profile as `LoginPage`) |
 | `ForgotPasswordPage1` | Application | Four-step password recovery wizard |
 | `Verify1` | Application | Two-factor verification (OTP or backup code) |
 
-Interactions are exposed as callbacks (e.g. `onAddToCart`, `onBuyNow`, `onSelectColor`). Elements stay in the DOM with no-op behavior when a callback is absent.
+Interactions are exposed as callbacks (e.g. `onAddToCart`, `onBuyNow`, `onSelectColor`). `StorefrontHero` and `LoginPage` render optional affordances only when their handlers are supplied; other blocks may keep elements in the DOM with no-op behavior when a callback is absent.
+
+### Category listing
+
+`CategoryListing` is the single controlled listing controller. Products, pagination, the selected query values, active-filter chips and the status are props; the block emits `on*Change`/`onClearFilters`/`onRepair`/`onRetry` and never fetches, parses the URL, or keeps a private query. `presentation` changes only the chrome: `sidebar` keeps a persistent desktop panel plus a mobile sheet, `toolbar` adds a sticky mobile toolbar with filter/sort drawers. Results render through the canonical `ProductCard`, so the listing never owns card markup. Facets are option-only groups (`{ id, label, options: [{ value, label, count? }] }`) supplied by the host; a group renders only when real metadata provides it, a real `0` count is displayed, and an absent/invalid count is omitted rather than invented.
+
+### Footer sections
+
+`FooterSection` is the canonical page-level footer. Its required `presentation`
+is `brand-columns`, `newsletter-grid`, or `contact`; provide serializable text,
+links, and social records as props. Social records use `{ label, href?, icon }`
+with an optional `ariaLabel`; callbacks and visible fallback text keep using the
+raw `label`. Bind icon IDs to `LucideIcon` components through `socialIcons`, and
+keep that map, `logo` nodes, and callbacks outside JSON fixtures.
+
+Column/legal and social links have separate `linkBehavior` and
+`socialLinkBehavior` props, both defaulting to `host`. Host mode requires the
+matching callback and renders callback-less destinations as text; `native`
+preserves browser navigation. Contact address, phone, and email hrefs are native.
+Newsletter controls stay visible but disabled without `onNewsletterSubmit`;
+the callback receives the entered email and the block performs no network request.
+
+The numbered `FooterSection1`, `FooterSection3`, and `FooterSection4` exports,
+deep module paths, and legacy prop contracts have been removed. Migrate to
+`FooterSection` by supplying an explicit presentation and canonical serializable
+content props. Select `linkBehavior="native"` or
+`socialLinkBehavior="native"` when browser navigation is intended; both default
+to host-controlled behavior. Canonical link types are exported as
+`CanonicalFooterLink` and `CanonicalFooterLinkColumn` to avoid collisions with
+other package contracts.
+
+### Login page
+
+`LoginPage` is a sign-in composition with one shared credential form and a
+required `presentation` of `card` or `social`. Both presentations submit the
+same `{ email, password, remember }` payload. `remember` starts as `false` and
+is reported to the host; the block does not decide session persistence.
+
+The block renders into the host page and does not own it: no viewport height, no
+page landmark, no page backdrop, no vertical centring. `card` caps its width at
+`max-w-md` and `social` at the same cap, and the mounting page supplies the
+canvas — a route shell, a modal, a split screen, or a template the host owns.
+Before the shell was removed, each of these blocks painted a full-viewport
+surface; a host that relied on that canvas must now provide it.
+
+Provider data stays serializable. Pass provider IDs and labels separately from
+the icon components, and provide a selection callback so provider buttons are
+only rendered when they can act. IDs must be unique within the list; an
+unmapped icon falls back to the visible provider label:
+
+```tsx
+import { AtSign } from 'lucide-react'
+import { LoginPage } from '@thorprovider/blocks'
+
+<LoginPage
+  presentation='social'
+  providers={[{ id: 'email', label: 'Email' }]}
+  providerIcons={{ email: AtSign }}
+  onProviderSelect={providerId => startProviderLogin(providerId)}
+  onSubmit={({ email, password, remember }) => signIn({ email, password, remember })}
+/>
+```
+
+The numbered `LoginPage1` and `LoginPage2` exports, deep module paths, and legacy
+prop contracts have been removed. Migrate to `LoginPage` and select `card` or
+`social` explicitly; both presentations use the canonical
+`{ email, password, remember }` host callback contract.
+
+## Testimonials
+
+`TestimonialSection` renders a collection of testimonials in one of two explicit
+presentations: `carousel` or `bento`. Each item requires a stable, collection-unique
+`id`, `name`, and `content`. `role`, `avatar`, and `rating` are optional and are
+rendered only when supplied; the block never invents attribution or ratings and
+does not emit an empty image source.
+
+```tsx
+import { TestimonialSection } from '@thorprovider/blocks'
+
+const testimonials = [
+  { id: 't-1', name: 'Rosa Díaz', role: 'Propietaria', content: 'Excelente servicio.' },
+]
+
+<TestimonialSection
+  presentation="carousel"
+  items={testimonials}
+  title="Lo que dicen nuestros clientes"
+  carouselLabels={{
+    previous: 'Testimonio anterior',
+    next: 'Testimonio siguiente',
+    slide: 'Ir al testimonio {n}',
+  }}
+/>
+```
+
+For `carousel`, `carouselLabels` is required and supplies localized previous,
+next, and slide-button labels; `{n}` is replaced with the one-based item number.
+The native buttons support keyboard activation, and the selected item is exposed
+with `aria-current`. For `bento`, omit `carouselLabels`; one-to-three items render
+without empty cards, and collections larger than four repeat the four-tile visual
+rhythm without dropping entries. An empty `items` array renders no section or
+controls. `title`, `description`, and `className` are optional for either
+presentation.
+
+The numbered `Testimonial1` and `Testimonial2` exports, deep module paths, and
+legacy prop contracts have been removed. Migrate to `TestimonialSection` with
+shared testimonial items and select `carousel` or `bento` explicitly.
 
 ## Optional brand props
 
 Three existing blocks expose an optional brand seam. Omitting the prop renders
 the block's current output unchanged; no demo content is added.
 
-- `Navbar4` — `logoAccent?: { text: string; className?: string }` accents a
+- `StorefrontNavbar` — `logoAccent?: { text: string; className?: string }` accents a
   trailing segment of `logoText`. With `logoText="ElectroCuba"` and
   `logoAccent={{ text: 'Cuba', className: 'text-brand-promo' }}`, the block
   renders `Electro` plus an accented `Cuba` span. If `text` is not a trailing
   segment of `logoText`, the wordmark renders unchanged.
-- `FooterSection1` — `brandAccent?: { text: string; className?: string }` applies
+- `FooterSection` — `brandAccent?: { text: string; className?: string }` applies
   the same trailing-segment accent to `brandName`.
-- `StorefrontHero1` — `heroImage?: { src: string; alt: string }` renders a native
+- `StorefrontHero` — `heroImage?: { src: string; alt: string }` renders a native
   `<img>` when `src` is a non-empty string, and nothing when the prop is absent
   or `src` is blank (never an empty `src`). The product grid is unaffected.
 
@@ -113,13 +200,13 @@ the library hardcodes no brand color.
 
 ## Custom surface `className`
 
-`Navbar4` (outer `<header>`) and `FooterSection1` (outer `<footer>`) accept an
+`Navbar4` (outer `<header>`) and `FooterSection` (outer `<footer>`) accept an
 optional `className`, merged with the existing `cn` helper. It is purely
 presentational: no layout, structure, or behavior prop, and no hardcoded color.
 
 - **Omitted `className`** — the block renders its default surface unchanged.
   `Navbar4` keeps `bg-background/95` **and** its
-  `supports-backdrop-filter:bg-background/80` variant; `FooterSection1` keeps
+  `supports-backdrop-filter:bg-background/80` variant; `FooterSection` keeps
   `bg-secondary`.
 - **Supplied `className`** — the consumer owns the surface. The default
   background **and its backdrop-filter variant** are not applied, so a semantic
@@ -128,31 +215,50 @@ presentational: no layout, structure, or behavior prop, and no hardcoded color.
   it). Layout, border, sticky, and `backdrop-blur-md` classes stay internal.
 
 The consumer is responsible for the text, transparency, and context tokens of a
-supplied surface. `Navbar4` adapts its primary nav links: they inherit the
+supplied surface. `StorefrontNavbar` adapts its primary nav links: they inherit the
 surface text color and add `hover:text-foreground` so `hover:bg-muted` never
 paints white-on-light. No magic colors are introduced by the block.
 
+## StorefrontNavbar account affordance
+
+`StorefrontNavbar` renders a **session-driven** account affordance exclusively from
+consumer-supplied props — it never resolves a session or authenticates itself.
+Given a `user` (`StoreUser`; `avatar` is optional) and `accountMenuItems`, it
+renders an authenticated account menu with the identity, the configured items,
+and the consumer's sign-out action on desktop and mobile. Given no `user` but a
+configured `accountHref`, it renders a signed-out account entry point on both
+viewports; with neither configured it renders no account affordance and no empty
+container. An absent `avatar` uses the initials fallback and emits no empty image
+`src`. Optional `accountPending` and `accountUnavailable` props drive a
+pending/disabled state and an accessible unavailable/retry state (via
+`onAccountRetry`) without presenting either as an anonymous session, and sign-out
+is suppressed while pending. All callbacks (`onSignOut`, `onAccountRetry`,
+`onHelp`) are consumer bindings kept outside the serializable JSON prop schema;
+the sign-out action is supplied by the consumer, so the block never performs
+authentication.
+
 ## Footer newsletter
 
-`FooterSection1` renders the interactive newsletter form (input + submit button)
-**only** when `newsletter.onSubmit` is supplied. A `newsletter` object without
-`onSubmit` renders no form, input, or button — never a fake form. Omit
-`newsletter` entirely to hide the newsletter block.
+`FooterSection` renders the newsletter form disabled when
+`onNewsletterSubmit` is absent. When supplied, the callback receives the entered
+email; the block performs no network request. Omit `newsletter` to hide the
+newsletter block.
 
 ## Cart presentation (controlled)
 
 The cart is presented in two shapes that share one data contract, so a change in
 either is visible in the other.
 
-- `ShoppingCart4` is the cart block. Its optional `presentation` prop selects
+- `ShoppingCart` is the cart block. Its optional `presentation` prop selects
   `'compact'` (default: a collapsible `max-w-md` card with an internal scroller —
   the navbar lateral) or `'page'` (always expanded, full-width `max-w-3xl`, no
   collapse control, ordinary page scrolling — the `/cart` review route).
   Omitting `presentation` renders the compact card byte-identically to before.
-- Line amounts prefer the canonical `lineTotal?: Money` and fall back to the
-  legacy numeric `price * quantity` only when `lineTotal` is absent. A missing or
-  malformed `Money` renders the `amountUnavailableLabel` (never a fabricated
-  zero or a currency fallback). `unitPrice?: Money` is carried verbatim.
+- Line amounts render the authoritative `lineTotal: Money` verbatim (backend
+  line total, never a local `unitPrice × quantity` computation); a malformed
+  amount renders the `amountUnavailableLabel` (never a fabricated zero or a
+  currency fallback). An optional `unitPrice: Money` is carried verbatim but
+  never used for any local arithmetic.
 - `totalsState` (`'idle' | 'pending' | 'error'`) plus `onRetryTotals` make the
   totals controlled: pending retains the last confirmed totals and disables
   conflicting mutations; error shows the error label and a retry.
@@ -160,28 +266,78 @@ either is visible in the other.
   by backend line id) and `onRemove(id)` removes by the same id.
   `checkoutUnavailable` hides the checkout action (e.g. no checkout installed)
   and `checkoutDisabled` disables it (e.g. pending or invalid totals).
-
-`Navbar4` owns the lateral. Pass `cartOpen` + `onCartOpenChange` to control the
+- Promo entry is an optional affordance: with `onApplyPromo(code)` it renders an
+  input that reports the entered code and shows only the authoritative applied
+  promotion/discount already present in `totals`; without the callback it is not
+  rendered, and the block never validates or resolves a code itself.
+  `onApplyPromo` never gates `recentlyViewed`, an optional host-supplied
+  suggestion list (name, optional image, optional `Money` price) rendered only
+  when supplied.
+
+`StorefrontNavbar` owns the lateral. Pass `cartOpen` + `onCartOpenChange` to control the
 sheet's visibility from host state (omit both to keep the legacy uncontrolled
 sheet); the block keeps `aria-expanded`/`data-state` in sync. Its cart sheet
-(`Navbar4CartSheet`) takes an optional `canonical` mode where each line shows the
+(`StorefrontNavbarCartSheet`) takes an optional `canonical` mode where each line shows the
 canonical `lineTotal` (never the placeholder numeric price), plus
 `checkoutUnavailable`/`viewCartUnavailable` to hide actions the store cannot
 serve, and a `state` (`'idle' | 'pending' | 'error'`) with retry for read/mutation
 feedback.
 
-## Checkout blocks (controlled)
+## Product card (canonical)
+
+`ProductCard` is the item cell of a product listing and the canonical member of
+the product-card family. Its items are `ProductPresentation` only (canonical
+`Money`): a missing price renders the `unavailablePriceLabel` with add-to-cart
+disabled — never a zero amount — and optional image, rating, badge, and
+compare-at price are omitted when absent (no empty `src`, no empty stars, no
+empty chip). A compare-at price renders only when it is valid and strictly
+higher than the selling price.
+
+The bounded `presentation` option selects the structure — `classic` (boxed card
+with an add-to-cart footer), `minimal` (lean image-forward tile with an
+icon-only cart action), `rich` (overlay actions: wishlist heart and
+view-similar) — while the data and action contract stays identical. Ratings,
+badges, and scarcity copy render only from host-supplied data (the `badge`
+copy and `compareAtPrice` are the evidence channels); the block never invents
+stars, chips, or urgency.
+
+The wishlist heart is host-owned: pass `wishlistedIds` to control it, and
+`onToggleWishlist(item, nextState)` receives every toggle from the click
+handler (never from an effect). Without host state the heart keeps an
+uncontrolled visual fallback and still reports. `onViewSimilar` renders its
+affordance only when supplied. Prices render through the canonical
+`formatMoney` path (no hardcoded currency), and every label is overridable
+with Spanish defaults (`Agregar al carrito`, `Precio no disponible`, …).
+
+## Checkout block (page-level, controlled)
+
+`Checkout` is the single public checkout surface; it replaces the numbered `CheckoutForm1`, `CheckoutForm2`, and `CheckoutForm3` blocks. It is a **controlled component**: field values arrive through `values` and every edit is reported through `onChange`, so the host owns all commercial state. The block owns only the ephemeral step index of the `stepper` presentation.
+
+- `presentation: 'single-page' | 'stepper'` (required) — `single-page` renders every section visible at once (summary first in DOM order on mobile); `stepper` shows one step at a time with an accessible progress indicator. Both accept the same props and emit the same callbacks.
+- `showReviewStep?: boolean` — appends a confirmation step (`stepper`) or section (`single-page`) before submission.
+- `values: CheckoutValues` — `email`, `firstName`, `lastName`, `phone`, `address`, `city`, `state`, `zipCode`, `country`, `paymentMethod`, `saveInfo`, `newsletter`, `promoCode`. There are no card fields.
+- `onChange: (field, value) => void` — reported per edit. The block holds no private copy of the form data and applies no masking.
+- `orderSummary?: { items, totals? }` — line identity, name, quantity, optional variant/image, optional canonical `Money` `lineTotal` and `unitPrice`, plus backend `totals` (`subtotal`, optional `discount`/`tax`/`shipping`, `total`). Amounts render verbatim; required totals that are absent or malformed render as unavailable with the retry action, never as zero. No local arithmetic, tax rate, shipping cost, threshold, or hardcoded currency.
+- `totalsState?: 'idle' | 'pending' | 'error'` and `onRetryTotals?` — controlled reads; pending and failed states render status/alert copy without inventing amounts.
+- `countries?: { value, label }[]`, `shippingOptions?`, `selectedShippingOptionId?`, `onSelectShippingOption?` — host-owned options and selection. With no country list the block renders a text input; with no shipping options it renders no method section; nothing is pre-selected.
+- `paymentMethods?: PaymentMethod[]` — payment methods as data (canonical `@thorprovider/types`). One option per method, the selected method's description, an empty state for an empty list, and a non-selectable rendering for `isEnabled === false`. The block renders **no raw card fields**: card collection belongs to the host payment-provider surface.
+- `labels?: Partial<CheckoutLabels>` and `formatMoney?: (money: Money) => string` — every user-facing string is overridable (neutral English defaults) and amounts format through canonical `Money` with no hardcoded symbol.
+- `fieldErrors?` / `fieldDescriptions?` — per-field messages and helper text, rendered with `role="alert"` and `aria-invalid`/`aria-describedby` wiring.
+- `validateStep?: (step: CheckoutStepId) => boolean` and `onStepChange?` — the block consults `validateStep` before advancing and for every applicable step before submitting; `onStepChange` is a notification only, never a controlled value. Without the callback the block advances and leaves submit protection to the host.
+- `onSubmit?`, `submitting?`, `submitError?`, `onRetrySubmit?` — submission is reported, with a pending guard and a recoverable error state; the block never creates an order, clears a cart, or claims success.
+
+Validation itself is **not** implemented in the block. Declare checks in your store spec's validation configuration (built-in `required`/`email`/`pattern`/`minLength`/`maxLength`/cross-field `requiredIf`/`equalTo`/`lessThan`/`greaterThan`, plus catalog-registered custom functions) and evaluate them with the renderer; the messages live in the spec so they are per-store and per-language.
+
+The order summary is an internal projection of `Checkout`, not a separate block. Order receipt and fulfilment progress remain `CheckoutConfirmation`.
+
+### Migrating from the numbered checkout blocks
+
+| Retired | Replacement |
+| --- | --- |
+| `CheckoutForm1` | `<Checkout presentation="stepper" />` — same controlled values minus `cardNumber`/`expiryDate`/`cvv`/`cardName`/`sameAsBilling`; `validateStep` now receives a `CheckoutStepId` (`'contact' \| 'shipping' \| 'payment' \| 'review'`) instead of a number |
+| `CheckoutForm2` | `<Checkout presentation="single-page" />` — the host supplies `Money` totals; the block no longer computes tax, shipping, or free-shipping thresholds |
+| `CheckoutForm3` | `<Checkout presentation="stepper" showReviewStep />` — values become controlled; `apartment`, card fields, per-step icons, and internal `isStepComplete` state are gone |
 
-`CheckoutForm1` (3-step wizard) and `CheckoutForm2` (single page) are **controlled components**: they receive the current form values through a `values` prop and report every edit through `onChange`. They hold no internal form state, so a renderer's validation context can read field values from its own state model. `CheckoutForm3` (4-step wizard) keeps the same contract with internal step state.
-
-- `paymentMethods?: PaymentMethod[]` — available payment methods as data (canonical `@thorprovider/types` `PaymentMethod`). The blocks render a radio list from this prop, show the selected method's name + `description`, and only render the card fields (`cardNumber`, `expiryDate`, `cvv`, `cardName`) when the selected method's `type === 'card'`. No payment method is hardcoded; pass an empty list to trigger the empty state.
-- `values: CheckoutForm1FormData` / `CheckoutForm2Data` — current field values (including `cardNumber`, `expiryDate`, `cvv`, `cardName`, and `paymentMethod` for `CheckoutForm1`/`CheckoutForm3`).
-- `onChange: (field, value) => void` — reported per edit; card grouping and MM/YY masking are applied by the block before the value reaches `onChange` (presentation only, no validation logic in the block).
-- `fieldErrors?: Partial<Record<FieldKey, Array<{ message?: string }>>>` — per-field error messages rendered via `FieldError` (`role="alert"`, `aria-invalid`/`aria-describedby` wiring). The same channel carries async/server errors (e.g. payment decline, invalid promo).
-- `fieldDescriptions?: Partial<Record<FieldKey, string>>` — helper text rendered via `FieldDescription`.
-- `validateStep?: (step: number) => boolean` (wizard only) — the block calls it on "Next"; advance only happens when it returns `true`, and the final submit only fires when every step validates.
-
-Validation itself is **not** implemented in the blocks. Declare checks in your store spec's validation configuration (built-in `required`/`email`/`pattern`/`minLength`/`maxLength`/cross-field `requiredIf`/`equalTo`/`lessThan`/`greaterThan`, plus catalog-registered custom functions like `luhn`/`cvv`/`expiryDate`) and evaluate them with the renderer; the messages live in the spec so they are per-store and per-language. Without a validation provider the blocks render with no inline errors.
 
 ## Usage
 
@@ -229,11 +385,11 @@ unique by contract, not by convention. See
 rules and the review checklist.
 
 Optional numeric projections are omitted rather than fabricated: e.g.
-`ProductCategory2Category.itemCount` renders a count only when it is a supplied
+`ProductCategoryItem.itemCount` renders a count only when it is a supplied
 finite non-negative number (a real `0` is preserved); an unknown count renders
 no count text, never a fabricated `0`.
 
-Product presentations (`ProductCard1`, `ProductShowcase1`) accept either the
+Product presentations (`ProductGrid`, `ProductShowcase1`) accept either the
 legacy numeric-price props or a canonical `ProductPresentation` (`price`/
 `compareAtPrice` as `Money`, `{ amount: string, currencyCode: string }` in
 decimal major units). The canonical path formats with the store currency and
@@ -242,6 +398,10 @@ locale, renders a truthful "unavailable" state for an unresolved price (never
 valid and strictly higher. Optional rating/badge/image appear only when
 supplied; a missing image is omitted, never `src=""`.
 
+The canonical `ProductCard` accepts only the canonical `ProductPresentation`
+contract — the legacy numeric-price props of the numbered cards are retired
+(migrate item data to canonical `Money`).
+
 ## Block interaction contracts
 
 State and events between a block, its host registry, and the store must follow
@@ -251,4 +411,4 @@ callbacks (`useCallback`); a fresh object literal always notifies a reference-on
 store guard; and every registered action completes its round-trip (handler → set +
 emit → spec `on` → recompute → bind). See
 [`docs/standards/interaction-contracts.md`](docs/standards/interaction-contracts.md)
-for the rules and the review checklist.
+for the rules and the review checklist.