@thorprovider/blocks 2.0.0 → 3.0.1

package/src/lib/contracts.ts

@@ -1,857 +0,0 @@
-import { z } from 'zod'
-import type { Money, PaymentMethod, ProductPreview } from '@thorprovider/types'
-
-/**
- * Serialization contracts for spec-driven storefronts.
- *
- * These Zod schemas are the *serializable subset* of what a spec may write for
- * a block. The component keeps its rich React interface; the catalog/registry
- * is the adapter that maps these props to real component props and binds
- * callbacks (see storefronts-on-blocks design D3). `z.infer` is the typed
- * boundary between spec and catalog — a prop outside the schema is a compile
- * error, not a runtime surprise.
- *
- * Data shapes are projections of the @thorprovider/types canon so that
- * @thorprovider/adapters output validates without conflict:
- * - Prices are plain numbers here while the canon `Money` is a decimal string
- *   ({ amount: "45.00", currencyCode }). The projection happens at the
- *   loader boundary.
- * - Blocks use `title` while the canon `ProductPreview` uses `name`. Reconcile
- *   via the canonical aliases below or the catalog/loader adapter.
- */
-export type CanonMoney = Money
-export type CanonProduct = ProductPreview
-
-/**
- * Fallback data-URI for required image fields when the data source has no
- * image. Image fields are non-optional `z.string()` in these contracts, so the
- * boundary must never emit `""` (React warns about `src=""`); it must emit a
- * real, renderable value. Hosts may override with their own branded fallback
- * (e.g. electrostore's `CATEGORY_IMAGE_FALLBACK`), but blocks ship a neutral
- * one so direct consumers are safe by default.
- */
-export const PRODUCT_IMAGE_FALLBACK =
-  'data:image/svg+xml;charset=utf-8,' +
-  encodeURIComponent(
-    `<svg xmlns='http://www.w3.org/2000/svg' width='600' height='600'><rect width='100%' height='100%' fill='#e2e8f0'/><g fill='none' stroke='#94a3b8' stroke-width='12' stroke-linecap='round'><path d='M150 300h300M300 150v300'/><path d='M220 230h50M220 300h50M220 370h50'/><path d='M330 230h50M330 300h50M330 370h50'/></g></svg>`,
-  )
-
-// ---------------------------------------------------------------------------
-// Data contracts
-// ---------------------------------------------------------------------------
-
-/**
- * Canonical `Money` (`@thorprovider/types`): a decimal string in major units
- * (`"69.99"`), never cents. A missing price is represented by omitting the
- * field (or `null` on a nullable field), not by an empty string.
- *
- * The amount stays a permissive `z.string()` on purpose: an unresolved backend
- * price may arrive as the canonical sentinel `""`, and tightening the schema
- * would reject the whole view instead of letting the presentation layer render
- * an unavailable state. Validity is enforced at render time by
- * `isAvailableMoney`/`formatMoney` (a `""`/malformed amount never becomes `$0`).
- */
-export const moneySchema: z.ZodType<Money> = z.object({
-  amount: z.string(),
-  currencyCode: z.string(),
-})
-
-const imageSchema = z.object({
-  id: z.string().optional(),
-  url: z.string(),
-  altText: z.string(),
-  width: z.number().optional(),
-  height: z.number().optional(),
-})
-
-const selectedOptionSchema = z.object({
-  name: z.string(),
-  value: z.string(),
-})
-
-export const productDetailVariantSchema = z.object({
-  id: z.string(),
-  title: z.string(),
-  sku: z.string().optional(),
-  availableForSale: z.boolean(),
-  selectedOptions: z.array(selectedOptionSchema),
-  /** Omit or null when the backend has no resolved price (purchase disabled). */
-  price: moneySchema.nullish(),
-  compareAtPrice: moneySchema.optional(),
-  image: imageSchema.optional(),
-})
-export type ProductDetailVariantSpec = z.infer<typeof productDetailVariantSchema>
-
-export const productDetailProductSchema = z.object({
-  id: z.string(),
-  handle: z.string().optional(),
-  title: z.string(),
-  description: z.string().optional(),
-  vendor: z.string().optional(),
-  options: z.array(z.object({ id: z.string(), name: z.string(), values: z.array(z.string()) })),
-  variants: z.array(productDetailVariantSchema),
-  images: z.array(imageSchema),
-  featuredImage: imageSchema.optional(),
-})
-export type ProductDetailProductSpec = z.infer<typeof productDetailProductSchema>
-
-/**
- * Canonical ProductOverview contract. Uses the canonical product projection and adds the
- * bounded `presentation` option plus the `rich` presentation's optional data. Callbacks are not
- * part of the schema (they are runtime props).
- */
-export const productOverviewReviewSchema = z.object({
-  id: z.number(),
-  author: z.string(),
-  rating: z.number(),
-  comment: z.string(),
-  date: z.string(),
-  helpful: z.number().optional(),
-})
-
-export const productOverviewPropsSchema = z.object({
-  product: productDetailProductSchema,
-  presentation: z.enum(['standard', 'gallery', 'rich']).optional(),
-  selectedVariantId: z.string().nullable().optional(),
-  quantity: z.number().optional(),
-  rating: z.object({ value: z.number(), count: z.number() }).optional(),
-  deliveryEstimate: z.string().optional(),
-  shipping: moneySchema.optional(),
-  specifications: z.record(z.string(), z.string()).optional(),
-  features: z.array(z.string()).optional(),
-  reviews: z.array(productOverviewReviewSchema).optional(),
-  sizesLabel: z.string().optional(),
-  variantLabel: z.string().optional(),
-  reviewsLabel: z.string().optional(),
-  addToCartLabel: z.string().optional(),
-  outOfStockLabel: z.string().optional(),
-  unavailablePriceLabel: z.string().optional(),
-  selectVariantLabel: z.string().optional(),
-  quantityLabel: z.string().optional(),
-  deliveryEstimateLabel: z.string().optional(),
-  shippingLabel: z.string().optional(),
-  badgeLabel: z.string().optional(),
-  availabilityLabel: z.string().optional(),
-  skuLabel: z.string().optional(),
-  overviewLabel: z.string().optional(),
-  specsLabel: z.string().optional(),
-  featuresLabel: z.string().optional(),
-  specificationsLabel: z.string().optional(),
-  galleryLabel: z.string().optional(),
-  photosLabel: z.string().optional(),
-  saveLabel: z.string().optional(),
-  savedLabel: z.string().optional(),
-  shareLabel: z.string().optional(),
-  basedOnReviewsLabel: z.string().optional(),
-  foundHelpfulLabel: z.string().optional(),
-  ofCounterLabel: z.string().optional(),
-  freeDeliveryLabel: z.string().optional(),
-})
-export type ProductOverviewSpecProps = z.infer<typeof productOverviewPropsSchema>
-
-export const cardProductSchema = z.object({
-  id: z.union([z.string(), z.number()]),
-  title: z.string(),
-  price: z.number(),
-  originalPrice: z.number().optional(),
-  image: z.string(),
-  badge: z.string().optional(),
-})
-export type CardProduct = z.infer<typeof cardProductSchema>
-
-export const cartItemSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  price: z.number(),
-  quantity: z.number().int().min(0),
-  /** Optional; absent images are omitted, never serialized as `""`. */
-  image: z.string().optional(),
-  variant: z.string().optional(),
-  /** Canonical backend per-unit price, preferred for display when present. */
-  unitPrice: moneySchema.optional(),
-  /** Canonical backend line total, preferred over `price * quantity`. */
-  lineTotal: moneySchema.optional(),
-})
-export type CartItem = z.infer<typeof cartItemSchema>
-
-export const cartTotalsSchema = z.object({
-  subtotal: moneySchema,
-  discount: moneySchema.optional(),
-  tax: moneySchema.optional(),
-  shipping: moneySchema.optional(),
-  total: moneySchema,
-})
-export type CartTotals = z.infer<typeof cartTotalsSchema>
-
-export const recentlyViewedItemSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  price: z.number(),
-  image: z.string(),
-})
-export type RecentlyViewedItem = z.infer<typeof recentlyViewedItemSchema>
-
-export const promotionSchema = z.object({
-  threshold: z.number(),
-  reward: z.string(),
-  icon: z.string().default('gift'),
-})
-export type Promotion = z.infer<typeof promotionSchema>
-
-const storeCategoryBase = {
-  label: z.string(),
-  href: z.string(),
-  emphasis: z.boolean().optional(),
-}
-
-export const storeCategorySchema: z.ZodType<StoreCategory> = z.lazy(() =>
-  z.object({
-    ...storeCategoryBase,
-    children: z.array(storeCategorySchema).optional(),
-  }),
-)
-export type StoreCategory = {
-  label: string
-  href: string
-  children?: StoreCategory[]
-  emphasis?: boolean
-}
-
-export const utilityLinkSchema = z.object({
-  label: z.string(),
-  href: z.string(),
-})
-export type UtilityLink = z.infer<typeof utilityLinkSchema>
-
-export const navCartItemSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  variant: z.string().optional(),
-  price: z.number(),
-  qty: z.number().int().min(0),
-  /** Optional; absent images are omitted, never serialized as `""`. */
-  image: z.string().optional(),
-})
-export type NavCartItem = z.infer<typeof navCartItemSchema>
-
-export const storeUserSchema = z.object({
-  name: z.string(),
-  email: z.string(),
-  avatar: z.string().optional(),
-  initials: z.string(),
-})
-export type StoreUser = z.infer<typeof storeUserSchema>
-
-export const accountMenuItemSchema = z.object({
-  label: z.string(),
-  href: z.string(),
-  description: z.string().optional(),
-  icon: z.enum(['orders', 'wishlist', 'addresses', 'settings']).optional(),
-})
-export type AccountMenuItem = z.infer<typeof accountMenuItemSchema>
-
-/**
- * Serialization contract for a payment method offered at checkout.
- *
- * A projection of `@thorprovider/types` `PaymentMethod` — the storefront-facing
- * shape produced by the adapters transform. Checkout blocks render the method
- * list from this data instead of hardcoding providers.
- */
-export const paymentMethodSchema: z.ZodType<PaymentMethod> = z.object({
-  id: z.string(),
-  name: z.string(),
-  type: z.enum([
-    'card',
-    'wallet',
-    'bank_transfer',
-    'buy_now_pay_later',
-    'cash_on_delivery',
-    'crypto',
-    'other',
-  ]),
-  isEnabled: z.boolean(),
-  requiresSetup: z.boolean(),
-  description: z.string().optional(),
-  metadata: z.record(z.string(), z.unknown()).optional(),
-  features: z
-    .object({
-      saveForLater: z.boolean().optional(),
-      requires3DS: z.boolean().optional(),
-      supportsRefunds: z.boolean().optional(),
-      minAmount: z.number().optional(),
-      maxAmount: z.number().optional(),
-      supportedCurrencies: z.array(z.string()).optional(),
-      requiresVerification: z.boolean().optional(),
-    })
-    .optional(),
-  logo: z.string().optional(),
-})
-
-// ---------------------------------------------------------------------------
-// Block prop schemas
-// ---------------------------------------------------------------------------
-
-export const buttonPropsSchema = z.object({
-  variant: z
-    .enum(['default', 'destructive', 'outline', 'secondary', 'ghost', 'link'])
-    .optional(),
-  size: z
-    .enum(['default', 'xs', 'sm', 'lg', 'icon', 'icon-xs', 'icon-sm', 'icon-lg'])
-    .optional(),
-  disabled: z.boolean().optional(),
-  className: z.string().optional(),
-})
-export type ButtonSpecProps = z.infer<typeof buttonPropsSchema>
-
-export const storeContainer1PropsSchema = z.object({
-  size: z.enum(['default', 'narrow', 'wide', 'full']).optional(),
-  className: z.string().optional(),
-})
-export type StoreContainer1SpecProps = z.infer<typeof storeContainer1PropsSchema>
-
-/**
- * Canonical product presentation — the serializable projection a storefront host
- * produces from a canonical `Product` for the merchandising sections. Unlike
- * `cardProductSchema` (legacy, numeric `price`), `price`/`compareAtPrice` carry
- * canonical `Money` (decimal major-unit string + currency code), so the block
- * formats in the shopper's currency and locale and renders a truthful
- * unavailable state instead of `$0`. Optional fields are omitted, never `""`.
- *
- * This contract is additive: `cardProductSchema` and its consumers are
- * unchanged, and a legacy numeric `price` still renders the legacy output.
- */
-export const productPresentationSchema = z.object({
-  id: z.union([z.string(), z.number()]),
-  title: z.string(),
-  /** Omitted (never `""`) when the backend has no image. */
-  image: z.string().optional(),
-  imageAlt: z.string().optional(),
-  /** Product destination; omitted when unknown. */
-  href: z.string().optional(),
-  price: moneySchema,
-  /** Comparison ("was") price; rendered only when valid and higher than `price`. */
-  compareAtPrice: moneySchema.optional(),
-  /** Only from real evidence; omitted otherwise (never fabricated). */
-  rating: z.number().optional(),
-  badge: z.string().optional(),
-})
-export type ProductPresentation = z.infer<typeof productPresentationSchema>
-
-/**
- * Canonical product card contract (item cell of a product listing). The cell
- * consumes one canonical `ProductPresentation` projection only — the legacy
- * numeric-price card shape is not accepted. `presentation` is the bounded
- * structure switch (`classic`/`minimal`/`rich`) and `wishlisted` is the
- * host-resolved membership state; callbacks and label strings are runtime
- * props and are excluded here. Collection concerns (heading, item cap, loading
- * and empty states) belong to `ProductGrid`.
- */
-export const productCardPropsSchema = z.object({
-  item: productPresentationSchema,
-  presentation: z.enum(['classic', 'minimal', 'rich']).optional(),
-  wishlisted: z.boolean().optional(),
-})
-export type ProductCardSpecProps = z.infer<typeof productCardPropsSchema>
-
-/**
- * Canonical product grid contract (listing). Consumes a collection of
- * canonical `ProductPresentation` items and owns the listing's heading, item
- * cap, wishlist membership, and loading/empty/ready states. `wishlistedIds` is
- * resolved per cell before rendering, so the cell receives only its own
- * boolean. Callbacks and label strings are runtime props and are excluded
- * here. Error state belongs to the host.
- */
-export const productGridPropsSchema = z.object({
-  items: z.array(productPresentationSchema),
-  presentation: z.enum(['classic', 'minimal', 'rich']).optional(),
-  heading: z.string().optional(),
-  maxItems: z.number().int().positive().optional(),
-  wishlistedIds: z.array(z.union([z.string(), z.number()])).readonly().optional(),
-  loading: z.boolean().optional(),
-  skeletonCount: z.number().int().positive().optional(),
-  emptyLabel: z.string().optional(),
-})
-export type ProductGridSpecProps = z.infer<typeof productGridPropsSchema>
-
-/**
- * Serializable contract for the combined grid-and-carousel product
- * presentation (`ProductShowcase1`). The grid pages are fixed-size, navigated
- * manually (prev/next) with a visible current-page indication; there is no
- * autoplay and no infinite loop. React-only callbacks are excluded.
- */
-export const productShowcase1PropsSchema = z.object({
-  products: z.array(productPresentationSchema),
-  heading: z.string().optional(),
-  description: z.string().optional(),
-  pageSize: z.number().int().positive().optional(),
-  prevLabel: z.string().optional(),
-  nextLabel: z.string().optional(),
-  pageLabel: z.string().optional(),
-  unavailablePriceLabel: z.string().optional(),
-  emptyLabel: z.string().optional(),
-  addToCartLabel: z.string().optional(),
-})
-export type ProductShowcase1SpecProps = z.infer<typeof productShowcase1PropsSchema>
-
-/**
- * Canonical shopping cart contract (consolidated shopping-cart family). Lines
- * are keyed by the backend cart line-item id and carry canonical `Money`
- * amounts only — the legacy numeric-price shape is not accepted: a line always
- * carries the backend-authoritative `lineTotal`, and an optional `unitPrice` is
- * carried verbatim (never used for a local `price * quantity` computation).
- * Suggestions fold the numbered carts' recommendations: optional image (omitted
- * when absent) and optional canonical `Money` price. `presentation` is the
- * bounded structure switch (`compact`/`page`); callbacks and interaction state
- * are runtime props and are excluded here.
- */
-export const shoppingCartItemSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  quantity: z.number().int().min(0),
-  /** Optional; absent images are omitted, never serialized as `""`. */
-  image: z.string().optional(),
-  variant: z.string().optional(),
-  /** Canonical backend line total; a malformed amount renders as unavailable. */
-  lineTotal: moneySchema,
-  /** Canonical backend unit price; carried verbatim, never used locally. */
-  unitPrice: moneySchema.optional(),
-})
-export type ShoppingCartItem = z.infer<typeof shoppingCartItemSchema>
-
-export const shoppingCartSuggestionSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  /** Optional; absent images are omitted, never serialized as `""`. */
-  image: z.string().optional(),
-  unitPrice: moneySchema.optional(),
-})
-export type ShoppingCartSuggestion = z.infer<typeof shoppingCartSuggestionSchema>
-
-export const shoppingCartPropsSchema = z.object({
-  items: z.array(shoppingCartItemSchema),
-  promotions: z.array(promotionSchema).default([]),
-  recentlyViewed: z.array(shoppingCartSuggestionSchema).optional(),
-  presentation: z.enum(['compact', 'page']).optional(),
-  /** Backend-authoritative totals; rendered verbatim, never computed locally. */
-  totals: cartTotalsSchema.optional(),
-  totalsState: z.enum(['idle', 'pending', 'error']).optional(),
-  totalsErrorLabel: z.string().optional(),
-  totalsUnavailableLabel: z.string().optional(),
-  amountUnavailableLabel: z.string().optional(),
-  retryLabel: z.string().optional(),
-  titleLabel: z.string().optional(),
-  subtotalLabel: z.string().optional(),
-  discountLabel: z.string().optional(),
-  taxLabel: z.string().optional(),
-  shippingLabel: z.string().optional(),
-  shippingFreeLabel: z.string().optional(),
-  totalLabel: z.string().optional(),
-  totalsPendingLabel: z.string().optional(),
-  awayFromLabel: z.string().optional(),
-  activatedLabel: z.string().optional(),
-  itemsLabel: z.string().optional(),
-  expressCheckoutLabel: z.string().optional(),
-  expressLabel: z.string().optional(),
-  standardLabel: z.string().optional(),
-  estimatedDeliveryLabel: z.string().optional(),
-  secureCheckoutLabel: z.string().optional(),
-  recentlyViewedLabel: z.string().optional(),
-  promoPromptLabel: z.string().optional(),
-  promoPlaceholderLabel: z.string().optional(),
-  promoApplyLabel: z.string().optional(),
-  collapseLabel: z.string().optional(),
-  expandLabel: z.string().optional(),
-  checkoutLabel: z.string().optional(),
-  quickCheckoutLabel: z.string().optional(),
-  checkoutNowLabel: z.string().optional(),
-  emptyLabel: z.string().optional(),
-  removeLabel: z.string().optional(),
-  decreaseLabel: z.string().optional(),
-  increaseLabel: z.string().optional(),
-})
-export type ShoppingCartSpecProps = z.infer<typeof shoppingCartPropsSchema>
-
-/**
- * Optional brand seams shared by the existing blocks. These mirror the
- * components' optional props as a serializable subset (no React): an accent
- * marks a trailing segment of the wordmark/brand name, and an editorial image
- * is a native `<img>` source. Omitting each keeps the block's current output.
- */
-export const logoAccentSchema = z.object({
-  text: z.string(),
-  className: z.string().optional(),
-})
-export type LogoAccent = z.infer<typeof logoAccentSchema>
-
-export const brandAccentSchema = z.object({
-  text: z.string(),
-  className: z.string().optional(),
-})
-export type BrandAccent = z.infer<typeof brandAccentSchema>
-
-export const heroImageSchema = z.object({
-  src: z.string(),
-  alt: z.string(),
-})
-export type HeroImage = z.infer<typeof heroImageSchema>
-
-/**
- * Serializable contract for the canonical commerce storefront shell
- * (`StorefrontNavbar`). Identity, cart, and search state stay host-owned: the
- * schema carries content and display state only, never cart arithmetic.
- */
-export const storefrontNavbarPropsSchema = z.object({
-  storeCategories: z.array(storeCategorySchema),
-  shippingNote: z.string().optional(),
-  utilityLinks: z.array(utilityLinkSchema),
-  logoText: z.string(),
-  logoHref: z.string().optional(),
-  /** Optional accent for a trailing segment of `logoText`; omitted → unchanged. */
-  logoAccent: logoAccentSchema.optional(),
-  /**
-   * Consumer-supplied classes merged onto the block's outer surface as the
-   * final argument (e.g. a semantic surface token). Omitted → unchanged.
-   */
-  className: z.string().optional(),
-  accountHref: z.string().optional(),
-  searchQuery: z.string().optional(),
-  items: z.array(navCartItemSchema).optional(),
-  /** Authoritative backend subtotal for the mini-cart. */
-  subtotal: moneySchema.optional(),
-  subtotalUnavailableLabel: z.string().optional(),
-  user: storeUserSchema.optional(),
-  accountMenuItems: z.array(accountMenuItemSchema).optional(),
-  accountPending: z.boolean().optional(),
-  accountUnavailable: z.boolean().optional(),
-})
-export type StorefrontNavbarSpecProps = z.infer<typeof storefrontNavbarPropsSchema>
-
-/**
- * Serializable contracts for the two bounded editorial sections (`faq`, `cta`).
- * These are the serializable subset of `FaqBlock1Props`/`CtaSection1Props`: the
- * React-only callbacks (`onPrimaryClick`/`onSecondaryClick`) are intentionally
- * excluded — the catalog adapter binds them (see design D3).
- */
-export const ctaSchema = z.object({
-  label: z.string(),
-  href: z.string().optional(),
-})
-export type CtaSpec = z.infer<typeof ctaSchema>
-
-/** Bounded presentations of the page-level navigation header. */
-export const navbarPresentationSchema = z.enum(['bar', 'mega', 'floating'])
-export type NavbarPresentationSpec = z.infer<typeof navbarPresentationSchema>
-
-export const navbarItemSchema = z.object({
-  label: z.string(),
-  href: z.string(),
-  description: z.string().optional(),
-  /** Key resolved through the consumer's host-bound `iconMap`. */
-  icon: z.string().optional(),
-})
-export type NavbarItemSpec = z.infer<typeof navbarItemSchema>
-
-export const navbarGroupSchema = z.object({
-  title: z.string().optional(),
-  items: z.array(navbarItemSchema),
-})
-export type NavbarGroupSpec = z.infer<typeof navbarGroupSchema>
-
-export const navbarLinkSchema = z.object({
-  label: z.string(),
-  href: z.string().optional(),
-  groups: z.array(navbarGroupSchema).optional(),
-  emphasis: z.boolean().optional(),
-})
-export type NavbarLinkSpec = z.infer<typeof navbarLinkSchema>
-
-export const navbarFeaturedSchema = z.object({
-  eyebrow: z.string(),
-  title: z.string(),
-  description: z.string().optional(),
-  href: z.string(),
-  linkLabel: z.string().optional(),
-  image: z.string().optional(),
-  imageAlt: z.string().optional(),
-})
-export type NavbarFeaturedSpec = z.infer<typeof navbarFeaturedSchema>
-
-/**
- * Serializable contract for the canonical page-level header (`Navbar`). The
- * serializable subset excludes the React-only bindings: `iconMap`, `onSignIn`,
- * and `onCtaClick` are bound by the host, exactly like the footer's icon map.
- */
-export const navbarPropsSchema = z.object({
-  presentation: navbarPresentationSchema.optional(),
-  logoText: z.string(),
-  logoHref: z.string().optional(),
-  currentPath: z.string().optional(),
-  links: z.array(navbarLinkSchema),
-  featured: navbarFeaturedSchema.optional(),
-  signIn: ctaSchema.optional(),
-  cta: ctaSchema.optional(),
-  /** Consumer-supplied classes merged onto the header surface last. */
-  className: z.string().optional(),
-})
-export type NavbarSpecProps = z.infer<typeof navbarPropsSchema>
-
-/**
- * Serializable subset of the canonical `StorefrontHero`'s props (callbacks
- * excluded). Every popularity, review, count, or countdown field is optional
- * host-supplied evidence: omitted fields render nothing (honest omission)
- * instead of fabricated defaults, and prices are formatted from the supplied
- * ISO 4217 `currency` via `Intl.NumberFormat` (never hardcoded).
- */
-export const storefrontHeroProductSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  price: z.number(),
-  originalPrice: z.number().optional(),
-  image: z.string().optional(),
-  imageAlt: z.string().optional(),
-  brand: z.string().optional(),
-  colors: z.array(z.string()).optional(),
-  rating: z.number().optional(),
-  reviewCount: z.number().optional(),
-  inStock: z.boolean().optional(),
-  isNew: z.boolean().optional(),
-  tag: z.string().optional(),
-})
-export type StorefrontHeroProduct = z.infer<typeof storefrontHeroProductSchema>
-
-export const storefrontHeroPropsSchema = z.object({
-  title: z.string(),
-  description: z.string(),
-  presentation: z.enum(['compact', 'showcase', 'editorial', 'promotional']).optional(),
-  currency: z.string().optional(),
-  products: z.array(storefrontHeroProductSchema),
-  badge: z.string().optional(),
-  titleAccent: z.string().optional(),
-  primaryCta: ctaSchema.optional(),
-  secondaryCta: ctaSchema.optional(),
-  heroImage: heroImageSchema.optional(),
-  departments: z
-    .array(
-      z.object({
-        id: z.string(),
-        name: z.string(),
-        image: z.string().optional(),
-        imageAlt: z.string().optional(),
-        count: z.string().optional(),
-        href: z.string().optional(),
-      }),
-    )
-    .optional(),
-  featuredDeals: z
-    .array(
-      z.object({
-        id: z.string(),
-        name: z.string(),
-        description: z.string().optional(),
-        image: z.string().optional(),
-        imageAlt: z.string().optional(),
-        price: z.number(),
-        originalPrice: z.number().optional(),
-        cta: ctaSchema.optional(),
-      }),
-    )
-    .optional(),
-  storeLocator: z
-    .object({
-      title: z.string(),
-      description: z.string(),
-      ctaLabel: z.string(),
-      ctaHref: z.string().optional(),
-    })
-    .optional(),
-  shippingInfo: z.string().optional(),
-  deals: z
-    .array(
-      z.object({
-        id: z.string(),
-        title: z.string(),
-        discount: z.string().optional(),
-        endTime: z.string().optional(),
-      }),
-    )
-    .optional(),
-  categories: z
-    .array(
-      z.object({
-        id: z.string(),
-        name: z.string(),
-        image: z.string().optional(),
-        imageAlt: z.string().optional(),
-        count: z.string().optional(),
-        href: z.string().optional(),
-      }),
-    )
-    .optional(),
-  rotationInterval: z.number().optional(),
-  addToCartLabel: z.string().optional(),
-  buyNowLabel: z.string().optional(),
-  newLabel: z.string().optional(),
-  outOfStockLabel: z.string().optional(),
-  colorsLabel: z.string().optional(),
-  discountSuffixLabel: z.string().optional(),
-  searchPlaceholder: z.string().optional(),
-  searchLabel: z.string().optional(),
-  featuredDescription: z.string().optional(),
-  shopNowLabel: z.string().optional(),
-  endsInLabel: z.string().optional(),
-  productsLabel: z.string().optional(),
-  viewLabel: z.string().optional(),
-})
-export type StorefrontHeroSpecProps = z.infer<typeof storefrontHeroPropsSchema>
-
-export const faqItemSchema = z.object({
-  value: z.string(),
-  question: z.string(),
-  answer: z.string(),
-})
-export type FaqItemSpec = z.infer<typeof faqItemSchema>
-
-export const faqBlock1PropsSchema = z.object({
-  items: z.array(faqItemSchema),
-  title: z.string().optional(),
-  description: z.string().optional(),
-  accordionType: z.enum(['single', 'multiple']).optional(),
-})
-export type FaqBlock1SpecProps = z.infer<typeof faqBlock1PropsSchema>
-
-export const ctaSection1PropsSchema = z.object({
-  badgeText: z.string().optional(),
-  title: z.string().optional(),
-  description: z.string().optional(),
-  primaryCta: ctaSchema.optional(),
-  secondaryCta: ctaSchema.optional(),
-})
-export type CtaSection1SpecProps = z.infer<typeof ctaSection1PropsSchema>
-
-/**
- * Serializable contract for the canonical `Feature` benefits section. The
- * item `icon` is a Lucide icon NAME (e.g. `'Zap'`) that the registry resolves
- * to a component at the seam; the React-only callbacks (`onCtaClick`,
- * `onLearnMore`) are intentionally excluded — the catalog adapter binds them.
- */
-export const featureItemSpecSchema = z.object({
-  id: z.string(),
-  title: z.string(),
-  description: z.string(),
-  icon: z.string(),
-})
-
-/**
- * `cards` branch: the card grid never owns an image. The presentation is
- * optional so an omitted value resolves to `cards`.
- */
-export const featureCardsSpecSchema = z.object({
-  items: z.array(featureItemSpecSchema),
-  presentation: z.literal('cards').optional(),
-  badge: z.string().optional(),
-  title: z.string().optional(),
-  description: z.string().optional(),
-  ctaLabel: z.string().optional(),
-  learnMoreLabel: z.string().optional(),
-  className: z.string().optional(),
-})
-export type FeatureCardsSpecProps = z.infer<typeof featureCardsSpecSchema>
-
-/**
- * `split` branch: the editorial image is mandatory and must carry a non-empty
- * `src`. `alt` stays required so the caller decides whether the image is
- * informative or decorative. `cards`-only chrome is intentionally absent.
- */
-export const featureSplitSpecSchema = z.object({
-  items: z.array(featureItemSpecSchema),
-  presentation: z.literal('split'),
-  title: z.string().optional(),
-  description: z.string().optional(),
-  image: z.object({ src: z.string().trim().min(1), alt: z.string() }),
-  className: z.string().optional(),
-})
-export type FeatureSplitSpecProps = z.infer<typeof featureSplitSpecSchema>
-
-/**
- * Serialized `Feature` union. The split branch is listed first so
- * `presentation: 'split'` resolves deterministically; an omitted presentation
- * falls through to `cards`. A split input without a non-empty image matches
- * neither branch and fails to parse.
- */
-export const featurePropsSchema = z.union([featureSplitSpecSchema, featureCardsSpecSchema])
-export type FeatureSpecProps = z.infer<typeof featurePropsSchema>
-
-/**
- * Canonical category contract for the consolidated `ProductCategory` block.
- *
- * `categories` is the canonical category projection (a `@thorprovider/types`
- * `ProductCategory` subset): ids are canonical strings, optional fields are
- * omitted rather than serialized as `""`, and there are no demo-only required
- * fields (no required subtitle, sector icon enum, or Lucide component). `icon`
- * is a plain, serializable icon-key string resolved by the block against a
- * bounded map with a neutral fallback. The `presentation` value is a bounded
- * structure switch, never a per-store fork. Callbacks are runtime props and are
- * excluded here (see the component).
- */
-export const productCategoryItemSchema = z.object({
-  id: z.string(),
-  handle: z.string().optional(),
-  name: z.string(),
-  description: z.string().optional(),
-  /** Optional real count; an unknown count is omitted, never fabricated as `0`. */
-  itemCount: z.number().optional(),
-  /** Omitted (never `""`) when the backend has no image. */
-  image: z.string().optional(),
-  trending: z.boolean().optional(),
-  /** Serializable icon key (e.g. `'shirt'`); unknown keys render a neutral fallback. */
-  icon: z.string().optional(),
-  subcategories: z.array(z.string()).optional(),
-  featured: z.boolean().optional(),
-})
-export type ProductCategoryItem = z.infer<typeof productCategoryItemSchema>
-
-export const productCategoryPropsSchema = z.object({
-  categories: z.array(productCategoryItemSchema),
-  presentation: z.enum(['grid', 'icons', 'list']).optional(),
-  title: z.string().optional(),
-  description: z.string().optional(),
-  badge: z.string().optional(),
-  cta: ctaSchema.optional(),
-  /** Controlled search value; filtering is owned by the host. */
-  query: z.string().optional(),
-  searchPlaceholder: z.string().optional(),
-  searchLabel: z.string().optional(),
-  emptyLabel: z.string().optional(),
-  noResultsLabel: z.string().optional(),
-  browseLabel: z.string().optional(),
-  viewAllLabel: z.string().optional(),
-  trendingLabel: z.string().optional(),
-  featuredLabel: z.string().optional(),
-  itemsLabel: z.string().optional(),
-  imageFallback: z.string().optional(),
-  className: z.string().optional(),
-})
-export type ProductCategorySpecProps = z.infer<typeof productCategoryPropsSchema>
-
-export const categoryCardPropsSchema = z.object({
-  category: productCategoryItemSchema,
-  presentation: z.enum(['grid', 'icons', 'list']).optional(),
-  browseLabel: z.string().optional(),
-  itemsLabel: z.string().optional(),
-  trendingLabel: z.string().optional(),
-  featuredLabel: z.string().optional(),
-  imageFallback: z.string().optional(),
-})
-export type CategoryCardSpecProps = z.infer<typeof categoryCardPropsSchema>
-
-export const categoryGridPropsSchema = productCategoryPropsSchema.extend({
-  maxItems: z.number().int().positive().optional(),
-  loading: z.boolean().optional(),
-  skeletonCount: z.number().int().positive().optional(),
-})
-export type CategoryGridSpecProps = z.infer<typeof categoryGridPropsSchema>
-
-// Pure monetary helpers, re-exported from the server-safe contracts entry so a
-// host boundary can validate/format `Money` without importing the React entry.
-export { isCompleteFiniteDecimal, isAvailableMoney, formatMoney } from './money'
-export { resolveAbsoluteQuantity } from './cart'