@thorprovider/blocks 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -5,10 +5,10 @@ import { ReactNode, JSX } from 'react';
 import { VariantProps } from 'class-variance-authority';
 import { Avatar as Avatar$1 } from 'radix-ui';
 import { LucideIcon } from 'lucide-react';
-import { StoreCategory } from './contracts.js';
-export { AccountMenuItem, ButtonSpecProps, CanonMoney, CanonProduct, CardProduct, CartItem, NavCartItem, Navbar4SpecProps, PRODUCT_IMAGE_FALLBACK, ProductCard1SpecProps, Promotion, ShoppingCart4SpecProps, StoreContainer1SpecProps, StoreUser, UtilityLink, accountMenuItemSchema, buttonPropsSchema, cardProductSchema, cartItemSchema, navCartItemSchema, navbar4PropsSchema, paymentMethodSchema, productCard1PropsSchema, promotionSchema, shoppingCart4PropsSchema, storeCategorySchema, storeContainer1PropsSchema, storeUserSchema, utilityLinkSchema } from './contracts.js';
+import { Money, ProductOption, SelectedOption, Image, PaymentMethod } from '@thorprovider/types';
+import { StoreCategory, ProductPresentation } from './contracts.js';
+export { AccountMenuItem, ButtonSpecProps, CanonMoney, CanonProduct, CardProduct, CartItem, CartTotals, NavCartItem, Navbar4SpecProps, PRODUCT_IMAGE_FALLBACK, ProductCard1SpecProps, ProductDetailProductSpec, ProductDetailVariantSpec, ProductOverview1SpecProps, ProductShowcase1SpecProps, Promotion, ShoppingCart4SpecProps, StoreContainer1SpecProps, StoreUser, UtilityLink, accountMenuItemSchema, buttonPropsSchema, cardProductSchema, cartItemSchema, cartTotalsSchema, formatMoney, isAvailableMoney, isCompleteFiniteDecimal, moneySchema, navCartItemSchema, navbar4PropsSchema, paymentMethodSchema, productCard1PropsSchema, productDetailProductSchema, productDetailVariantSchema, productOverview1PropsSchema, productPresentationSchema, productShowcase1PropsSchema, promotionSchema, resolveAbsoluteQuantity, shoppingCart4PropsSchema, storeCategorySchema, storeContainer1PropsSchema, storeUserSchema, utilityLinkSchema } from './contracts.js';
 import { z } from 'zod';
-import { PaymentMethod } from '@thorprovider/types';
 
 /**
  * Merge Tailwind CSS class names safely.
@@ -22,15 +22,15 @@ interface CTA {
 }
 
 declare const badgeVariants: (props?: ({
-    variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare function Badge({ className, variant, asChild, ...props }: react.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & {
     asChild?: boolean;
 }): react.JSX.Element;
 
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined;
-    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "icon" | "default" | "xs" | "sm" | "lg" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare function Button({ className, variant, size, asChild, ...props }: react.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
     asChild?: boolean;
@@ -140,7 +140,7 @@ declare function Navbar3({ navLinks, logoText, logoHref, currentPath, signIn, ct
 interface StoreUser {
     name: string;
     email: string;
-    avatar: string;
+    avatar?: string;
     initials: string;
 }
 interface AccountMenuItem {
@@ -151,40 +151,130 @@ interface AccountMenuItem {
 }
 
 interface CartItem {
+    /** Backend cart line-item id — the stable identity for update/removal. */
     id: string;
     name: string;
-    variant: string;
+    variant?: string;
     price: number;
     qty: number;
-    image: string;
+    /** Optional; an absent image is omitted rather than serialized as `""`. */
+    image?: string;
+    /**
+     * Canonical backend line amount. Required for truthful rendering in
+     * `canonical` mode; when absent/invalid the line shows the unavailable
+     * label rather than a numeric fallback.
+     */
+    lineTotal?: Money;
 }
+type CartSheetState = 'idle' | 'pending' | 'error';
 
 interface UtilityLink {
     label: string;
     href: string;
 }
 
+interface LogoAccent {
+    /** Trailing segment of `logoText` to render with the accent styling. */
+    text: string;
+    /** Consumer-supplied classes for the accent span (e.g. a brand color token). */
+    className?: string;
+}
 interface Navbar4Props {
     storeCategories: StoreCategory[];
-    shippingNote: string;
+    /**
+     * Optional note shown in the desktop utility strip. When omitted (or empty)
+     * and there are no `utilityLinks`, the strip is not rendered at all, so a
+     * block with no optional content paints no empty decorative chrome.
+     */
+    shippingNote?: string;
     utilityLinks: UtilityLink[];
     logoText: string;
     logoHref?: string;
-    /** When provided, a mobile-only "Account" link is appended to the utility links. */
+    /**
+     * Optional accent for a trailing segment of `logoText` (e.g. the "Cuba" in
+     * "ElectroCuba"). When omitted, or when `text` is not a trailing segment of
+     * `logoText`, the wordmark renders unchanged.
+     */
+    logoAccent?: LogoAccent;
+    /** Account destination for anonymous shoppers on every viewport. */
     accountHref?: string;
+    /**
+     * When `false`, no search control is rendered at all — neither the desktop
+     * input, the mobile trigger, nor the mobile panel. Defaults to `true` so
+     * legacy consumers keep the existing self-contained search. The generated
+     * storefront passes `false` while no verified global search contract exists
+     * (E2 task 5.4), so no global search is presented as working.
+     */
+    /**
+     * The storefront's current route path. When it matches a destination the link
+     * is marked as the current page (accessibly, beyond color alone).
+     */
+    currentPath?: string;
+    showSearch?: boolean;
     searchQuery?: string;
     onSearchChange?: (value: string) => void;
     items?: CartItem[];
+    /**
+     * Quantity DELTA for a backend cart line-item id. The boundary converts the
+     * delta into an absolute quantity against the authoritative current line
+     * quantity before mutating the cart.
+     */
     onQtyChange?: (id: string, delta: number) => void;
+    /** Remove the backend cart line-item id. */
     onRemove?: (id: string) => void;
+    /** Authoritative backend subtotal for the mini-cart. */
+    subtotal?: Money;
+    /** Shown when an authoritative subtotal is supplied but absent/malformed. */
+    subtotalUnavailableLabel?: string;
+    /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
+    formatMoney?: (money: Money) => string;
     user?: StoreUser;
     accountMenuItems?: AccountMenuItem[];
     onHelp?: () => void;
     onSignOut?: () => void;
+    accountPending?: boolean;
+    accountUnavailable?: boolean;
+    onAccountRetry?: () => void;
     onCheckout?: () => void;
     onViewCart?: () => void;
+    /**
+     * Controlled visibility for the cart sheet. When provided, the sheet opens
+     * and closes from this value and `onCartOpenChange` instead of internal
+     * state, so a host can share one cart surface across the navbar trigger and
+     * successful add-to-cart. Omit both to keep the legacy uncontrolled sheet.
+     */
+    cartOpen?: boolean;
+    /** Change handler paired with `cartOpen` for a controlled sheet. */
+    onCartOpenChange?: (open: boolean) => void;
+    /**
+     * Backend-authoritative cart rendering for the sheet. When `true`, line
+     * amounts use each item's canonical `lineTotal` Money and never fall back to
+     * numeric `price * qty`. Omit for the legacy numeric rendering.
+     */
+    canonicalCart?: boolean;
+    /** Cart read/mutation lifecycle for the sheet. */
+    cartState?: CartSheetState;
+    /** Message shown when `cartState` is `error`. */
+    cartErrorLabel?: string;
+    /** Recovery action label for the error state. */
+    cartRetryLabel?: string;
+    /** Recovery action invoked from the error state. */
+    onCartRetry?: () => void;
+    /** When `true`, the sheet's checkout action is suppressed (checkout not installed). */
+    checkoutUnavailable?: boolean;
+    /** When `true`, the sheet's checkout action is disabled (cart not ready). */
+    checkoutDisabled?: boolean;
+    /** When `true`, the sheet's review action is suppressed (cart view not installed). */
+    viewCartUnavailable?: boolean;
+    /**
+     * Consumer-supplied classes merged onto the outer `<header>` as the final
+     * argument, so a semantic surface such as `bg-brand-nav
+     * text-brand-nav-foreground` overrides the default `bg-background`. Purely
+     * presentational: no layout, structure, or behavior changes.
+     */
+    className?: string;
 }
-declare function Navbar4({ storeCategories, shippingNote, utilityLinks, logoText, logoHref, accountHref, searchQuery: searchQueryProp, onSearchChange, items: itemsProp, onQtyChange: onQtyChangeProp, onRemove: onRemoveProp, user, accountMenuItems, onHelp, onSignOut, onCheckout, onViewCart, }: Navbar4Props): react.JSX.Element;
+declare function Navbar4({ storeCategories, shippingNote, utilityLinks, logoText, logoHref, logoAccent, accountHref, currentPath, showSearch, searchQuery: searchQueryProp, onSearchChange, items: itemsProp, onQtyChange: onQtyChangeProp, onRemove: onRemoveProp, subtotal, subtotalUnavailableLabel, formatMoney, user, accountMenuItems, onHelp, onSignOut, accountPending, accountUnavailable, onAccountRetry, onCheckout, onViewCart, cartOpen, onCartOpenChange, canonicalCart, cartState, cartErrorLabel, cartRetryLabel, onCartRetry, checkoutUnavailable, checkoutDisabled, viewCartUnavailable, className, }: Navbar4Props): react.JSX.Element;
 
 type Banner1Shape = 'bar' | 'pill';
 interface Banner1Props {
@@ -391,15 +481,39 @@ interface FooterLinkColumn$1 {
 interface FooterNewsletter {
     placeholder?: string;
     buttonLabel: string;
+    /**
+     * Submit handler. The interactive form (input + submit button) renders only
+     * when this is supplied. A newsletter without `onSubmit` renders no form,
+     * input, or button — never a fake form.
+     */
     onSubmit?: (email: string) => void;
 }
+interface BrandAccent {
+    /** Trailing segment of `brandName` to render with the accent styling. */
+    text: string;
+    /** Consumer-supplied classes for the accent span (e.g. a brand color token). */
+    className?: string;
+}
 interface FooterSection1Props {
     brandName: string;
+    /**
+     * Optional accent for a trailing segment of `brandName` (e.g. the "Cuba" in
+     * "ElectroCuba"). When omitted, or when `text` is not a trailing segment of
+     * `brandName`, the brand name renders unchanged.
+     */
+    brandAccent?: BrandAccent;
     brandDescription?: string;
     linkColumns: FooterLinkColumn$1[];
     newsletter?: FooterNewsletter;
+    /**
+     * Consumer-supplied classes merged onto the outer `<footer>` as the final
+     * argument, so a semantic surface such as `bg-brand-nav
+     * text-brand-nav-foreground` overrides the default `bg-secondary`. Purely
+     * presentational: no layout, structure, or behavior changes.
+     */
+    className?: string;
 }
-declare function FooterSection1({ brandName, brandDescription, linkColumns, newsletter, }: FooterSection1Props): react.JSX.Element;
+declare function FooterSection1({ brandName, brandAccent, brandDescription, linkColumns, newsletter, className, }: FooterSection1Props): react.JSX.Element;
 
 interface FooterLink {
     label: string;
@@ -502,15 +616,24 @@ interface Product {
     image: string;
     badge?: string;
 }
+/**
+ * A card entry is either the legacy numeric-price product or the canonical
+ * `Money`-price presentation. The block renders both without breaking legacy
+ * consumers: a numeric `price` keeps the legacy `$` output unchanged, while a
+ * canonical `Money` price is formatted in its own currency and locale.
+ */
+type ProductCard1Product = Product | ProductPresentation;
 interface ProductCard1Props {
-    products: Product[];
+    products: ProductCard1Product[];
     heading?: string;
     maxItems?: number;
-    onAddToCart?: (product: Product) => void;
-    onProductClick?: (product: Product) => void;
+    onAddToCart?: (product: ProductCard1Product) => void;
+    onProductClick?: (product: ProductCard1Product) => void;
     addToCartLabel?: string;
+    /** Shown when a canonical price is present but unavailable (never `$0`). */
+    unavailablePriceLabel?: string;
 }
-declare function ProductCard1({ products, heading, maxItems, onAddToCart, onProductClick, addToCartLabel, }: ProductCard1Props): react.JSX.Element;
+declare function ProductCard1({ products, heading, maxItems, onAddToCart, onProductClick, addToCartLabel, unavailablePriceLabel, }: ProductCard1Props): react.JSX.Element;
 
 interface ProductCard2Product {
     id: string | number;
@@ -573,39 +696,104 @@ interface ProductCard5Props {
 }
 declare function ProductCard5({ products, onToggleWishlist, onAddToCart, onQuickView, onCompare, onExport, }: ProductCard5Props): react.JSX.Element;
 
-interface ProductOverview1ProductImage {
-    id: number;
-    src: string;
-    alt: string;
-}
-interface ProductOverview1ProductColor {
-    name: string;
-    value: string;
+interface ProductShowcase1Props {
+    products: ProductPresentation[];
+    heading?: string;
+    description?: string;
+    pageSize?: number;
+    prevLabel?: string;
+    nextLabel?: string;
+    /** Label for the current-page status, e.g. "Página". */
+    pageLabel?: string;
+    unavailablePriceLabel?: string;
+    emptyLabel?: string;
+    addToCartLabel?: string;
+    onAddToCart?: (product: ProductPresentation) => void;
+    onProductClick?: (product: ProductPresentation) => void;
 }
-interface ProductOverview1Product {
+/**
+ * Combined grid-and-carousel product presentation: fixed-size grid pages
+ * navigated manually (prev/next) with a visible current-page indication. There
+ * is no autoplay, no auto-advance, and no infinite loop. Controls are real
+ * buttons (keyboard operable and visible at every breakpoint); touch swipe is an
+ * addition, never the only way to navigate. Below-fold images are lazy.
+ *
+ * Data access lives in the host: this block only renders the props it receives
+ * and reports interactions through callbacks (no backend/router/measurement
+ * imports).
+ */
+declare function ProductShowcase1({ products, heading, description, pageSize, prevLabel, nextLabel, pageLabel, unavailablePriceLabel, emptyLabel, addToCartLabel, onAddToCart, onProductClick, }: ProductShowcase1Props): react.JSX.Element;
+
+/**
+ * Canonical product-detail projection.
+ *
+ * The block consumes the canonical `@thorprovider/types` shapes (`Money`,
+ * `ProductOption`, `SelectedOption`, `Image`) so adapter output maps without a
+ * second, drifting product type. The only deviation is `price`: the canon marks
+ * it required, but a missing/unresolved backend price is a real, distinct state
+ * that must disable purchase — so the projection allows `price` to be absent
+ * and the block treats absence as "unavailable", never as zero.
+ */
+interface ProductDetailVariant {
     id: string;
-    brand: string;
-    name: string;
-    description: string;
-    price: number;
-    currency: string;
-    rating: number;
-    images: ProductOverview1ProductImage[];
-    sizes: number[];
-    colors: ProductOverview1ProductColor[];
+    title: string;
+    sku?: string;
+    availableForSale: boolean;
+    selectedOptions: SelectedOption[];
+    /** Canonical Money; omit/null when the backend has no resolved price. */
+    price?: Money | null;
+    compareAtPrice?: Money;
+    image?: Image;
+}
+interface ProductDetailProduct {
+    id: string;
+    handle?: string;
+    title: string;
+    description?: string;
+    vendor?: string;
+    options: ProductOption[];
+    variants: ProductDetailVariant[];
+    images: Image[];
+    featuredImage?: Image;
+}
+interface ProductOverview1Rating {
+    value: number;
+    count: number;
 }
 interface ProductOverview1Props {
-    product: ProductOverview1Product;
+    product: ProductDetailProduct;
+    /** Controlled selection: the backend variant id, or null/undefined when nothing is explicitly selected. */
+    selectedVariantId?: string | null;
+    onSelectVariant?: (variantId: string) => void;
+    /** Controlled quantity for the add-to-cart action; defaults to 1 when omitted. */
+    quantity?: number;
+    onQuantityChange?: (quantity: number) => void;
+    /** Add-to-cart identity is the selected backend variant id, with the requested quantity. */
+    onAddToCart?: (variantId: string, quantity: number) => void;
+    isWishlisted?: boolean;
+    onToggleWishlist?: (variantId: string, isWishlisted: boolean) => void;
+    /** Rendered only when the backend supplies it. */
+    rating?: ProductOverview1Rating;
+    /** Rendered only when the backend supplies it. */
+    deliveryEstimate?: string;
+    /** Rendered only when the backend supplies it. */
+    shipping?: Money;
+    formatPrice?: (money: Money) => string;
     sizesLabel?: string;
-    colorLabel?: string;
+    variantLabel?: string;
     reviewsLabel?: string;
     addToCartLabel?: string;
+    outOfStockLabel?: string;
+    unavailablePriceLabel?: string;
+    selectVariantLabel?: string;
+    quantityLabel?: string;
+    deliveryEstimateLabel?: string;
+    shippingLabel?: string;
     removeFromWishlistLabel?: string;
     addToWishlistLabel?: string;
-    onAddToCart?: (product: ProductOverview1Product) => void;
-    onToggleWishlist?: (product: ProductOverview1Product, isWishlisted: boolean) => void;
+    imageFallback?: string;
 }
-declare function ProductOverview1({ product, sizesLabel, colorLabel, reviewsLabel, addToCartLabel, removeFromWishlistLabel, addToWishlistLabel, onAddToCart, onToggleWishlist, }: ProductOverview1Props): react.JSX.Element;
+declare function ProductOverview1({ product, selectedVariantId, onSelectVariant, quantity, onQuantityChange, onAddToCart, isWishlisted, onToggleWishlist, rating, deliveryEstimate, shipping, formatPrice, sizesLabel, variantLabel, reviewsLabel, addToCartLabel, outOfStockLabel, unavailablePriceLabel, selectVariantLabel, quantityLabel, deliveryEstimateLabel, shippingLabel, removeFromWishlistLabel, addToWishlistLabel, imageFallback, }: ProductOverview1Props): react.JSX.Element;
 
 interface ProductOverview2ProductImage {
     src: string;
@@ -855,7 +1043,12 @@ interface ProductCategory2Category {
     handle?: string;
     name: string;
     description: string;
-    itemCount: number;
+    /**
+     * Number of items in the category. Optional: when omitted, or when it is not
+     * a finite non-negative number, no count is rendered — an unknown projection
+     * must not be shown as a fabricated `0`. A real `0` is preserved.
+     */
+    itemCount?: number;
     image: string;
     trending: boolean;
 }
@@ -937,17 +1130,17 @@ declare const collectionItemSchema: z.ZodObject<{
     image: z.ZodOptional<z.ZodString>;
     href: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    label: string;
     id: string;
+    label: string;
     image?: string | undefined;
-    href?: string | undefined;
     description?: string | undefined;
+    href?: string | undefined;
 }, {
-    label: string;
     id: string;
+    label: string;
     image?: string | undefined;
-    href?: string | undefined;
     description?: string | undefined;
+    href?: string | undefined;
 }>;
 type CollectionItem = z.infer<typeof collectionItemSchema>;
 
@@ -991,17 +1184,17 @@ declare const megaMenuPropsSchema: z.ZodObject<{
         image: z.ZodOptional<z.ZodString>;
         href: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        label: string;
         id: string;
+        label: string;
         image?: string | undefined;
-        href?: string | undefined;
         description?: string | undefined;
+        href?: string | undefined;
     }, {
-        label: string;
         id: string;
+        label: string;
         image?: string | undefined;
-        href?: string | undefined;
         description?: string | undefined;
+        href?: string | undefined;
     }>, "many">;
     onNavigate: z.ZodOptional<z.ZodType<() => void, z.ZodTypeDef, () => void>>;
     categoryColumnTitle: z.ZodOptional<z.ZodString>;
@@ -1021,11 +1214,11 @@ declare const megaMenuPropsSchema: z.ZodObject<{
         children?: MenuItem[];
     }[];
     collections: {
-        label: string;
         id: string;
+        label: string;
         image?: string | undefined;
-        href?: string | undefined;
         description?: string | undefined;
+        href?: string | undefined;
     }[];
     onNavigate?: (() => void) | undefined;
     categoryColumnTitle?: string | undefined;
@@ -1045,11 +1238,11 @@ declare const megaMenuPropsSchema: z.ZodObject<{
         children?: MenuItem[];
     }[];
     collections: {
-        label: string;
         id: string;
+        label: string;
         image?: string | undefined;
-        href?: string | undefined;
         description?: string | undefined;
+        href?: string | undefined;
     }[];
     onNavigate?: (() => void) | undefined;
     categoryColumnTitle?: string | undefined;
@@ -1101,17 +1294,17 @@ declare const mobileCategoryDrawerPropsSchema: z.ZodObject<{
         image: z.ZodOptional<z.ZodString>;
         href: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        label: string;
         id: string;
+        label: string;
         image?: string | undefined;
-        href?: string | undefined;
         description?: string | undefined;
+        href?: string | undefined;
     }, {
-        label: string;
         id: string;
+        label: string;
         image?: string | undefined;
-        href?: string | undefined;
         description?: string | undefined;
+        href?: string | undefined;
     }>, "many">;
     open: z.ZodBoolean;
     onClose: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodVoid>;
@@ -1135,11 +1328,11 @@ declare const mobileCategoryDrawerPropsSchema: z.ZodObject<{
         children?: MenuItem[];
     }[];
     collections: {
-        label: string;
         id: string;
+        label: string;
         image?: string | undefined;
-        href?: string | undefined;
         description?: string | undefined;
+        href?: string | undefined;
     }[];
     onClose: (...args: unknown[]) => void;
     collectionsTitle?: string | undefined;
@@ -1162,11 +1355,11 @@ declare const mobileCategoryDrawerPropsSchema: z.ZodObject<{
         children?: MenuItem[];
     }[];
     collections: {
-        label: string;
         id: string;
+        label: string;
         image?: string | undefined;
-        href?: string | undefined;
         description?: string | undefined;
+        href?: string | undefined;
     }[];
     onClose: (...args: unknown[]) => void;
     collectionsTitle?: string | undefined;
@@ -1190,11 +1383,11 @@ declare const categoryIconPropsSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodEnum<["wrench", "bolt", "tree", "refrigerator", "wind", "droplet", "zap", "hard-hat", "car", "utensils", "boxes", "sofa", "shield", "sun", "chef-hat", "tractor", "store", "home"]>>;
     className: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    className?: string | undefined;
     name?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
-}, {
     className?: string | undefined;
+}, {
     name?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
+    className?: string | undefined;
 }>;
 type CategoryIconProps = z.infer<typeof categoryIconPropsSchema>;
 /**
@@ -1207,6 +1400,187 @@ type CategoryIconProps = z.infer<typeof categoryIconPropsSchema>;
  */
 declare function CategoryIcon({ name, className }: CategoryIconProps): react.JSX.Element | null;
 
+declare const breadcrumbItemSchema: z.ZodObject<{
+    label: z.ZodString;
+    href: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    href?: string | undefined;
+}, {
+    label: string;
+    href?: string | undefined;
+}>;
+type BreadcrumbItemData = z.infer<typeof breadcrumbItemSchema>;
+declare const breadcrumbPropsSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        href: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        href?: string | undefined;
+    }, {
+        label: string;
+        href?: string | undefined;
+    }>, "many">;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    ariaLabel: z.ZodOptional<z.ZodString>;
+    backLabel: z.ZodOptional<z.ZodString>;
+    className: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        label: string;
+        href?: string | undefined;
+    }[];
+    className?: string | undefined;
+    maxItems?: number | undefined;
+    ariaLabel?: string | undefined;
+    backLabel?: string | undefined;
+}, {
+    items: {
+        label: string;
+        href?: string | undefined;
+    }[];
+    className?: string | undefined;
+    maxItems?: number | undefined;
+    ariaLabel?: string | undefined;
+    backLabel?: string | undefined;
+}>;
+type BreadcrumbProps = z.infer<typeof breadcrumbPropsSchema>;
+/**
+ * Breadcrumb trail for a real navigation path (Home → … → current).
+ *
+ * Framework-agnostic and prop-driven: plain anchors (no router) and the shared
+ * shadcn breadcrumb primitives. The last item is the current page and is never
+ * a link (`aria-current="page"`); earlier items link only when an `href` is
+ * given. Long labels truncate, and trails longer than `maxItems` collapse the
+ * intermediate levels behind an ellipsis. On mobile the full list is replaced
+ * by a single back link to the parent, so a wide trail never overflows.
+ *
+ * Renders nothing when there are no labelled items.
+ */
+declare function Breadcrumb({ items, maxItems, ariaLabel, backLabel, className, }: BreadcrumbProps): react.JSX.Element | null;
+
+declare const skipToContentPropsSchema: z.ZodObject<{
+    targetId: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    className: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    targetId: string;
+    label?: string | undefined;
+    className?: string | undefined;
+}, {
+    targetId: string;
+    label?: string | undefined;
+    className?: string | undefined;
+}>;
+type SkipToContentProps = z.infer<typeof skipToContentPropsSchema>;
+/**
+ * Skip-to-content link (WCAG 2.4.1 Bypass Blocks).
+ *
+ * Framework-agnostic and prop-driven: a plain anchor to the main content id,
+ * visually hidden until it receives focus, then pinned at the top-left with
+ * visible contrast. The target element is responsible for carrying the id (and
+ * being focusable); this block only renders the bypass affordance.
+ */
+declare function SkipToContent({ targetId, label, className, }: SkipToContentProps): react.JSX.Element;
+
+declare const backToTopPropsSchema: z.ZodObject<{
+    threshold: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+    className: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    threshold?: number | undefined;
+    label?: string | undefined;
+    className?: string | undefined;
+}, {
+    threshold?: number | undefined;
+    label?: string | undefined;
+    className?: string | undefined;
+}>;
+type BackToTopProps = z.infer<typeof backToTopPropsSchema>;
+/**
+ * Resolve the scroll behavior for a back-to-top activation. Pure so it can be
+ * unit-tested without a DOM: reduced motion yields an instant jump.
+ */
+declare function resolveScrollBehavior(prefersReducedMotion: boolean): 'auto' | 'smooth';
+/**
+ * Back-to-top control that appears once the page is scrolled past `threshold`
+ * and returns the viewport to the top. Honors `prefers-reduced-motion` (instant
+ * jump instead of a smooth scroll). Framework-agnostic; icon-only with an
+ * accessible label.
+ */
+declare function BackToTop({ threshold, label, className, }: BackToTopProps): react.JSX.Element | null;
+
+declare const mobileBottomNavItemSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    label: z.ZodString;
+    href: z.ZodString;
+    icon: z.ZodOptional<z.ZodEnum<["wrench", "bolt", "tree", "refrigerator", "wind", "droplet", "zap", "hard-hat", "car", "utensils", "boxes", "sofa", "shield", "sun", "chef-hat", "tractor", "store", "home"]>>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    href: string;
+    id?: string | undefined;
+    icon?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
+}, {
+    label: string;
+    href: string;
+    id?: string | undefined;
+    icon?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
+}>;
+type MobileBottomNavItem = z.infer<typeof mobileBottomNavItemSchema>;
+declare const mobileBottomNavPropsSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        href: z.ZodString;
+        icon: z.ZodOptional<z.ZodEnum<["wrench", "bolt", "tree", "refrigerator", "wind", "droplet", "zap", "hard-hat", "car", "utensils", "boxes", "sofa", "shield", "sun", "chef-hat", "tractor", "store", "home"]>>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        href: string;
+        id?: string | undefined;
+        icon?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
+    }, {
+        label: string;
+        href: string;
+        id?: string | undefined;
+        icon?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
+    }>, "many">;
+    currentHref: z.ZodOptional<z.ZodString>;
+    ariaLabel: z.ZodOptional<z.ZodString>;
+    className: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        label: string;
+        href: string;
+        id?: string | undefined;
+        icon?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
+    }[];
+    className?: string | undefined;
+    ariaLabel?: string | undefined;
+    currentHref?: string | undefined;
+}, {
+    items: {
+        label: string;
+        href: string;
+        id?: string | undefined;
+        icon?: "tree" | "home" | "wrench" | "bolt" | "refrigerator" | "wind" | "droplet" | "zap" | "hard-hat" | "car" | "utensils" | "boxes" | "sofa" | "shield" | "sun" | "chef-hat" | "tractor" | "store" | undefined;
+    }[];
+    className?: string | undefined;
+    ariaLabel?: string | undefined;
+    currentHref?: string | undefined;
+}>;
+type MobileBottomNavProps = z.infer<typeof mobileBottomNavPropsSchema>;
+/**
+ * Mobile-only bottom navigation offering the primary destinations.
+ *
+ * Framework-agnostic and prop-driven: plain anchors (no router). Hidden at
+ * `md` and up; offsets the iOS home indicator via `env(safe-area-inset-bottom)`;
+ * each destination meets the 44px minimum touch target. The current
+ * destination is marked with `aria-current="page"` and a non-colour cue (weight
+ * + indicator bar), never colour alone.
+ */
+declare function MobileBottomNav({ items, currentHref, ariaLabel, className, }: MobileBottomNavProps): react.JSX.Element | null;
+
 interface CategoryFilter1Category {
     id: string;
     name: string;
@@ -1242,12 +1616,24 @@ interface FilterProduct {
     id: string;
     name: string;
     price: string;
-    image: string;
+    /** Optional: an absent image is omitted so the block never renders `src=""`. */
+    image?: string;
+    /**
+     * Optional product-detail link. When present the card renders as a real
+     * `<a href>` (keyboard focus, middle-click, crawlers); when absent the block
+     * falls back to the `onProductClick` path. The href is produced by the
+     * presentation layer — the block never builds a route.
+     */
+    href?: string;
 }
 interface CategoryFilter2Category {
     id: string;
     label: string;
 }
+interface CategoryFilter2Collection {
+    id: string;
+    label: string;
+}
 interface CategoryFilter2Color {
     id: string;
     color: string;
@@ -1263,19 +1649,99 @@ interface CategoryFilter2SortOption {
 }
 interface CategoryFilter2Filters {
     categories: string[];
+    /** Collections requested by the `category-filters` feature (E2). */
+    collections?: string[];
     priceRange: number[];
     size: string | null;
     color: string | null;
 }
+/**
+ * A typed catalog-query error the listing renders for repair. It is a structural
+ * mirror of the runtime boundary error (`CatalogQueryError`/`CatalogQueryFailure`):
+ * `fields` names the exact raw parameters to remove and `feature` is present only
+ * for `unmounted-capability`. The block never builds a host URL — it emits the
+ * fields through `onRepair` (E2 task 4.5).
+ */
+interface CategoryFilter2QueryError {
+    code: 'invalid-query' | 'unsupported-query' | 'unmounted-capability';
+    /** Exact raw URL parameter names that must be removed to repair the query. */
+    fields: string[];
+    message?: string;
+    feature?: 'catalog-search' | 'category-filters';
+}
+/**
+ * The observable listing status. The host derives it from the URL boundary and
+ * the provider outcome (`mapCatalogOutcomeToStatus`) and passes it down; the
+ * block only renders it. `loading` is in flight; `ready` shows products; `empty`
+ * is a valid zero-result query; `invalid-query`/`unsupported-query`/
+ * `unmounted-capability` are typed repair states; `error` is a query/network
+ * failure with retry. Distinct states stay distinct — a valid empty result is
+ * never shown as an error and a raw failure is never swallowed as empty.
+ */
+type CategoryFilter2Status = {
+    state: 'loading';
+} | {
+    state: 'ready';
+} | {
+    state: 'empty';
+} | {
+    state: 'invalid-query';
+    error: CategoryFilter2QueryError;
+} | {
+    state: 'unsupported-query';
+    error: CategoryFilter2QueryError;
+} | {
+    state: 'unmounted-capability';
+    error: CategoryFilter2QueryError;
+} | {
+    state: 'error';
+    message?: string;
+};
+/** The kind of canonical filter an active chip represents. */
+type CategoryFilter2ActiveFilterKind = 'text' | 'category' | 'collection' | 'price' | 'attribute';
+/**
+ * A removable active-filter chip. Built only from the actual canonical query
+ * (never from claimed provider filtering): `params` are the raw URL parameter
+ * names carrying the filter and `value` is the specific list value to drop.
+ */
+interface CategoryFilter2ActiveFilter {
+    /** Stable identity for React keys and removal callbacks. */
+    id: string;
+    kind: CategoryFilter2ActiveFilterKind;
+    /** Human-readable label shown on the chip. */
+    label: string;
+    /** Raw URL parameter names that carry this filter. */
+    params: string[];
+    /** The specific list value this chip removes; absent for scalar filters. */
+    value?: string;
+}
 interface CategoryFilter2Props {
     products: FilterProduct[];
     categories?: CategoryFilter2Category[];
+    collections?: CategoryFilter2Collection[];
     sizes?: string[];
     colors?: CategoryFilter2Color[];
+    /**
+     * Real backend-provided price range only. When absent the price control is
+     * omitted; the block never falls back to a fabricated `0..1000` default
+     * (E2 design Decision 8 / spec "Price controls require real price metadata").
+     */
     priceRange?: CategoryFilter2PriceRange;
     viewOptions?: (number | string)[];
+    /** Adapter-advertised sort options only. When absent/empty no sort control is rendered. */
     sortOptions?: CategoryFilter2SortOption[];
     pagination?: (number | string)[];
+    searchValue?: string;
+    selectedCategories?: string[];
+    selectedCollections?: string[];
+    selectedPriceRange?: number[];
+    selectedSort?: string;
+    selectedPage?: number | string;
+    selectedPageSize?: number | string;
+    showSearch?: boolean;
+    showFilters?: boolean;
+    showPrice?: boolean;
+    showSort?: boolean;
     filtersTitle?: string;
     selectedText?: string;
     clearAllLabel?: string;
@@ -1283,6 +1749,7 @@ interface CategoryFilter2Props {
     minLabel?: string;
     maxLabel?: string;
     categoriesTitle?: string;
+    collectionsTitle?: string;
     sizesTitle?: string;
     colorsTitle?: string;
     viewLabel?: string;
@@ -1290,13 +1757,72 @@ interface CategoryFilter2Props {
     sortPlaceholder?: string;
     productsTitle?: string;
     currentLabel?: string;
+    searchLabel?: string;
+    searchPlaceholder?: string;
     onProductClick?: (product: FilterProduct) => void;
     onPageChange?: (page: number | string) => void;
     onViewChange?: (view: number | string) => void;
+    onPageSizeChange?: (pageSize: number | string) => void;
     onSortChange?: (sort: string) => void;
     onFilterChange?: (filters: CategoryFilter2Filters) => void;
+    onSearchChange?: (text: string) => void;
+    /** Observable listing status. Defaults to `ready` so legacy consumers are unchanged. */
+    status?: CategoryFilter2Status;
+    /** Removable active-filter chips built from the canonical query. */
+    activeFilters?: CategoryFilter2ActiveFilter[];
+    loadingLabel?: string;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    clearFiltersLabel?: string;
+    invalidQueryTitle?: string;
+    unsupportedQueryTitle?: string;
+    unmountedCapabilityTitle?: string;
+    errorTitle?: string;
+    errorDescription?: string;
+    repairLabel?: string;
+    retryLabel?: string;
+    activeFiltersTitle?: string;
+    removeFilterLabel?: string;
+    /** Empty-state clear: drops the active filters but never base scope/sort/pageSize. */
+    onClearFilters?: () => void;
+    /** Invalid/unsupported/unmounted repair: receives the exact bad fields to remove. */
+    onRepair?: (remove: string[]) => void;
+    /** Query/network failure retry: preserves the current query/input. */
+    onRetry?: () => void;
+    /** Removes a single active-filter chip. */
+    onRemoveFilter?: (filter: CategoryFilter2ActiveFilter) => void;
+}
+interface CategoryFilter2StatusViewProps {
+    status: CategoryFilter2Status;
+    activeFilters?: CategoryFilter2ActiveFilter[];
+    activeFiltersTitle?: string;
+    removeFilterLabel?: string;
+    loadingLabel?: string;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    clearFiltersLabel?: string;
+    invalidQueryTitle?: string;
+    unsupportedQueryTitle?: string;
+    unmountedCapabilityTitle?: string;
+    errorTitle?: string;
+    errorDescription?: string;
+    repairLabel?: string;
+    retryLabel?: string;
+    onClearFilters?: () => void;
+    onRepair?: (remove: string[]) => void;
+    onRetry?: () => void;
+    onRemoveFilter?: (filter: CategoryFilter2ActiveFilter) => void;
 }
-declare function CategoryFilter2({ products, categories, sizes, colors, priceRange: priceRangeConfig, viewOptions, sortOptions, pagination, filtersTitle, selectedText, clearAllLabel, priceRangeTitle, minLabel, maxLabel, categoriesTitle, sizesTitle, colorsTitle, viewLabel, viewPlaceholder, sortPlaceholder, productsTitle, currentLabel, onProductClick, onPageChange, onViewChange, onSortChange, onFilterChange, }: CategoryFilter2Props): react.JSX.Element;
+/**
+ * Hooks-free presentation of the observable listing states and the removable
+ * active-filter chips (E2 task 4.5). Kept separate from `CategoryFilter2` so the
+ * interaction contract (clear / repair / retry / chip removal) is testable by
+ * invoking the rendered handlers without a DOM (this package's tests render with
+ * `react-dom/server`). It renders no products and performs no fetch — it only
+ * emits the host callbacks. When `ready` with no chips it renders nothing.
+ */
+declare function CategoryFilter2StatusView({ status, activeFilters, activeFiltersTitle, removeFilterLabel, loadingLabel, emptyTitle, emptyDescription, clearFiltersLabel, invalidQueryTitle, unsupportedQueryTitle, unmountedCapabilityTitle, errorTitle, errorDescription, repairLabel, retryLabel, onClearFilters, onRepair, onRetry, onRemoveFilter, }: CategoryFilter2StatusViewProps): react.JSX.Element | null;
+declare function CategoryFilter2({ products, categories, collections, sizes, colors, priceRange: priceRangeConfig, viewOptions, sortOptions, pagination, searchValue, selectedCategories, selectedCollections, selectedPriceRange, selectedSort, selectedPage, selectedPageSize, showSearch, showFilters, showPrice, showSort, filtersTitle, selectedText, clearAllLabel, priceRangeTitle, minLabel, maxLabel, categoriesTitle, collectionsTitle, sizesTitle, colorsTitle, viewLabel, viewPlaceholder, sortPlaceholder, productsTitle, currentLabel, searchLabel, searchPlaceholder, onProductClick, onPageChange, onViewChange, onPageSizeChange, onSortChange, onFilterChange, onSearchChange, status, activeFilters, loadingLabel, emptyTitle, emptyDescription, clearFiltersLabel, invalidQueryTitle, unsupportedQueryTitle, unmountedCapabilityTitle, errorTitle, errorDescription, repairLabel, retryLabel, activeFiltersTitle, removeFilterLabel, onClearFilters, onRepair, onRetry, onRemoveFilter, }: CategoryFilter2Props): react.JSX.Element;
 
 interface CategoryFilter4SortOption {
     value: string;
@@ -1465,13 +1991,27 @@ interface ShoppingCart2Props {
 declare function ShoppingCart2({ items, recommendations, taxRate, shippingCost, freeShippingThreshold, validatePromo, titleLabel, itemsCountLabel, cartItemsLabel, orderSummaryLabel, subtotalLabel, savingsLabel, shippingLabel, freeShippingLabel, taxLabel, totalLabel, promoPlaceholder, applyPromoLabel, promoAppliedLabel, continueShoppingLabel, emptyCartTitleLabel, emptyCartDescriptionLabel, checkoutLabel, freeShippingNoteLabel, freeShippingThresholdNoteLabel, secureCheckoutLabel, recommendationsLabel, onQuantityChange, onRemove, onAddToWishlist, onCheckout, onContinueShopping, onRecommendationClick, }: ShoppingCart2Props): react.JSX.Element;
 
 interface ShoppingCart4Item {
+    /** Backend cart line-item id — the stable identity for update/removal. */
     id: string;
     name: string;
     price: number;
     quantity: number;
-    image: string;
+    /** Optional; an absent image is omitted rather than serialized as `""`. */
+    image?: string;
     variant?: string;
-}
+    /** Canonical backend per-unit price; preferred for display when present. */
+    unitPrice?: Money;
+    /** Canonical backend line total; preferred over `price * quantity`. */
+    lineTotal?: Money;
+}
+interface ShoppingCart4Totals {
+    subtotal: Money;
+    discount?: Money;
+    tax?: Money;
+    shipping?: Money;
+    total: Money;
+}
+type ShoppingCart4TotalsState = 'idle' | 'pending' | 'error';
 interface ShoppingCart4Promotion {
     threshold: number;
     reward: string;
@@ -1481,19 +2021,48 @@ interface ShoppingCart4RecentlyViewed {
     id: string;
     name: string;
     price: number;
-    image: string;
+    image?: string;
 }
+type ShoppingCart4Presentation = 'compact' | 'page';
 interface ShoppingCart4Props {
     items: ShoppingCart4Item[];
     promotions: ShoppingCart4Promotion[];
     recentlyViewed?: ShoppingCart4RecentlyViewed[];
+    /**
+     * Layout presentation. `compact` (default) is the collapsible quick-cart
+     * card; `page` is a wide, always-expanded review layout with a primary
+     * heading, no collapse control, and normal page scrolling. Both use the same
+     * line controls and authoritative monetary rendering.
+     */
+    presentation?: ShoppingCart4Presentation;
+    /**
+     * Backend-authoritative totals. The curated cart renders these verbatim; it
+     * never computes subtotal/tax/shipping/total locally.
+     */
+    totals?: ShoppingCart4Totals;
+    /** Controlled state of the totals fetch/mutation. */
+    totalsState?: ShoppingCart4TotalsState;
+    totalsErrorLabel?: string;
+    /** Shown when a required total amount is absent or malformed (never as zero). */
+    totalsUnavailableLabel?: string;
+    /** Shown for a line whose supplied line total is absent or malformed. */
+    amountUnavailableLabel?: string;
+    retryLabel?: string;
+    onRetryTotals?: () => void;
+    /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
+    formatMoney?: (money: Money) => string;
+    /** @deprecated legacy numeric formatter, used only when `totals` is absent. */
+    formatPrice?: (value: number) => string;
+    /** @deprecated legacy local tax rate, used only when `totals` is absent. */
     taxRate?: number;
     titleLabel?: string;
     subtotalLabel?: string;
+    discountLabel?: string;
     taxLabel?: string;
     shippingLabel?: string;
     shippingFreeLabel?: string;
     totalLabel?: string;
+    totalsPendingLabel?: string;
     awayFromLabel?: string;
     activatedLabel?: string;
     itemsLabel?: string;
@@ -1508,15 +2077,31 @@ interface ShoppingCart4Props {
     checkoutLabel?: string;
     quickCheckoutLabel?: string;
     checkoutNowLabel?: string;
+    emptyLabel?: string;
+    removeLabel?: string;
+    decreaseLabel?: string;
+    increaseLabel?: string;
+    continueShoppingLabel?: string;
+    /** Suppress the checkout action (e.g. the checkout feature is not installed). */
+    checkoutUnavailable?: boolean;
+    /** Disable checkout while the cart is not ready (pending/error/invalid totals). */
+    checkoutDisabled?: boolean;
+    /**
+     * ABSOLUTE quantity for a backend cart line-item id (distinct from the
+     * Navbar's DELTA). The boundary mutates the cart by line-item id.
+     */
     onQuantityChange?: (id: string, quantity: number) => void;
+    /** Remove the backend cart line-item id. */
     onRemove?: (id: string) => void;
     onCheckout?: () => void;
     onQuickCheckout?: () => void;
     onPayWithApple?: () => void;
     onPayWithGoogle?: () => void;
     onRecentlyViewedClick?: (id: string) => void;
+    /** Page presentation only: navigate back to browsing. */
+    onContinueShopping?: () => void;
 }
-declare function ShoppingCart4({ items, promotions, recentlyViewed, taxRate, titleLabel, subtotalLabel, taxLabel, shippingLabel, shippingFreeLabel, totalLabel, awayFromLabel, activatedLabel, itemsLabel, expressCheckoutLabel, expressLabel, standardLabel, estimatedDeliveryLabel, secureCheckoutLabel, recentlyViewedLabel, collapseLabel, expandLabel, checkoutLabel, quickCheckoutLabel, checkoutNowLabel, onQuantityChange, onRemove, onCheckout, onQuickCheckout, onPayWithApple, onPayWithGoogle, onRecentlyViewedClick, }: ShoppingCart4Props): react.JSX.Element;
+declare function ShoppingCart4({ items, promotions, recentlyViewed, presentation, totals, totalsState, totalsErrorLabel, totalsUnavailableLabel, amountUnavailableLabel, retryLabel, onRetryTotals, formatMoney: formatMoneyProp, formatPrice, titleLabel, subtotalLabel, discountLabel, taxLabel, shippingLabel, shippingFreeLabel, totalLabel, totalsPendingLabel, awayFromLabel, activatedLabel, itemsLabel, expressCheckoutLabel, expressLabel, standardLabel, estimatedDeliveryLabel, secureCheckoutLabel, recentlyViewedLabel, collapseLabel, expandLabel, checkoutLabel, quickCheckoutLabel, checkoutNowLabel, emptyLabel, removeLabel, decreaseLabel, increaseLabel, continueShoppingLabel, checkoutUnavailable, checkoutDisabled, onQuantityChange, onRemove, onCheckout, onQuickCheckout, onPayWithApple, onPayWithGoogle, onRecentlyViewedClick, onContinueShopping, }: ShoppingCart4Props): react.JSX.Element;
 
 type ShoppingCart3Tag = 'Limited Edition' | 'Best Seller' | 'New Arrival';
 interface ShoppingCart3CartItem {
@@ -1610,32 +2195,82 @@ type CheckoutForm1FieldDescriptions = Partial<Record<keyof CheckoutForm1FormData
 interface CheckoutForm1OrderSummaryItem {
     id: string | number;
     name: string;
-    variant: string;
-    price: number;
+    variant?: string;
     quantity: number;
-    image: string;
+    /** Canonical backend line total; preferred over `price * quantity`. */
+    lineTotal?: Money;
+    /** @deprecated legacy numeric price, used only when `lineTotal` is absent. */
+    price?: number;
+    /** Optional; an absent image is omitted rather than serialized as `""`. */
+    image?: string;
+}
+interface CheckoutForm1Totals {
+    subtotal: Money;
+    discount?: Money;
+    tax?: Money;
+    shipping?: Money;
+    total: Money;
 }
+type CheckoutForm1TotalsState = 'idle' | 'pending' | 'error';
 interface CheckoutForm1OrderSummary {
     items: CheckoutForm1OrderSummaryItem[];
-    shipping: number;
-    tax: number;
+    /** Backend-authoritative totals; rendered verbatim when present. */
+    totals?: CheckoutForm1Totals;
+    /** @deprecated legacy numeric amounts, used only when `totals` is absent. */
+    shipping?: number;
+    /** @deprecated */
+    tax?: number;
+    /** @deprecated */
     discount?: number;
+    /** @deprecated */
     promoDiscount?: number;
 }
 interface CheckoutForm1CountryOption {
     value: string;
     label: string;
 }
+interface CheckoutForm1ShippingOption {
+    /** Backend shipping method id — the controlled selection identity. */
+    id: string;
+    name: string;
+    price?: Money;
+    description?: string;
+    estimatedDays?: string;
+}
 type CheckoutForm1ChangeHandler = (field: keyof CheckoutForm1FormData, value: string | boolean) => void;
 interface CheckoutForm1Props {
     title?: string;
     description?: string;
     orderSummary?: CheckoutForm1OrderSummary;
+    /** Controlled state of the totals fetch/mutation. */
+    totalsState?: CheckoutForm1TotalsState;
+    totalsErrorLabel?: string;
+    retryLabel?: string;
+    onRetryTotals?: () => void;
     countries?: CheckoutForm1CountryOption[];
+    /** Eligible shipping options for the cart's region/address. */
+    shippingOptions?: CheckoutForm1ShippingOption[];
+    /** Controlled selection of a shipping option id. */
+    selectedShippingOptionId?: string;
+    onSelectShippingOption?: (id: string) => void;
     paymentMethods?: PaymentMethod[];
     noPaymentMethodsLabel?: string;
+    /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
+    formatMoney?: (money: Money) => string;
+    /**
+     * Raw card fields are legacy-only and never collected in the launch flow.
+     * Defaults to `false`: the curated surface renders no card inputs.
+     */
+    collectCardFields?: boolean;
+    onApplyPromo?: (code: string) => void;
+    promoPending?: boolean;
+    promoApplyLabel?: string;
+    promoPlaceholder?: string;
+    /** Optional trust copy; rendered only when supplied (never fabricated). */
+    trustNotes?: string[];
     backLabel?: string;
     completeOrderLabel?: string;
+    processingLabel?: string;
     continueLabel?: string;
     values: CheckoutForm1FormData;
     onChange: CheckoutForm1ChangeHandler;
@@ -1647,8 +2282,11 @@ interface CheckoutForm1Props {
     submitting?: boolean;
     /** Order-level error surfaced above the footer actions. */
     submitError?: string;
+    /** Optional recovery action for a failed submission. */
+    onRetrySubmit?: () => void;
+    submitErrorActionLabel?: string;
 }
-declare function CheckoutForm1({ title, description, orderSummary, countries, paymentMethods, noPaymentMethodsLabel, backLabel, completeOrderLabel, continueLabel, values, onChange, fieldErrors, fieldDescriptions, validateStep, onSubmit, submitting, submitError, }: CheckoutForm1Props): react.JSX.Element;
+declare function CheckoutForm1({ title, description, orderSummary, totalsState, totalsErrorLabel, retryLabel, onRetryTotals, countries, shippingOptions, selectedShippingOptionId, onSelectShippingOption, paymentMethods, noPaymentMethodsLabel, formatMoney, collectCardFields, onApplyPromo, promoPending, promoApplyLabel, promoPlaceholder, trustNotes, backLabel, completeOrderLabel, processingLabel, continueLabel, values, onChange, fieldErrors, fieldDescriptions, validateStep, onSubmit, submitting, submitError, onRetrySubmit, submitErrorActionLabel, }: CheckoutForm1Props): react.JSX.Element;
 
 interface CheckoutForm2Item {
     id: string;
@@ -1831,10 +2469,13 @@ type FulfilmentStage = 'Confirmed' | 'Packed' | 'Shipped' | 'Delivered';
 interface OrderLine {
     id: string;
     name: string;
-    variant: string;
+    variant?: string;
     quantity: number;
-    price: number;
-    image: string;
+    /** Canonical backend line total. */
+    lineTotal: Money;
+    unitPrice?: Money;
+    /** Optional; an absent image is omitted rather than serialized as `""`. */
+    image?: string;
 }
 interface FulfilmentStageDetail {
     stage: FulfilmentStage;
@@ -1852,46 +2493,55 @@ interface FulfilmentStageDetail {
 interface OrderAddress {
     name: string;
     lines: string[];
-    method: string;
+    method?: string;
 }
 interface OrderTotals {
-    subtotal: number;
-    shipping: number;
-    tax: number;
+    subtotal?: Money;
+    discount?: Money;
+    shipping?: Money;
+    tax?: Money;
+    total?: Money;
 }
 interface Order$1 {
     number: string;
     /** ISO date */
     placedAt: string;
-    email: string;
-    currentStage: FulfilmentStage;
-    /** ISO date */
-    estimatedDelivery: string;
+    email?: string;
+    /** Present only when the backend reports a fulfilment stage. */
+    currentStage?: FulfilmentStage;
+    /** ISO date. Rendered only when supplied; no delivery estimate is fabricated. */
+    estimatedDelivery?: string | null;
     trackingHref?: string;
-    shipping: OrderAddress;
-    billing: OrderAddress;
+    shipping?: OrderAddress;
+    billing?: OrderAddress;
     totals: OrderTotals;
 }
 interface CheckoutConfirmationProps {
     order: Order$1;
     orderLines: OrderLine[];
     /**
-     * Keyed by `FulfilmentStage`. The stage strip is ordered by `Object.keys`,
-     * so define the record in the canonical `Confirmed → Packed → Shipped → Delivered` order.
+     * Keyed by `FulfilmentStage`. Rendered only when supplied; the stage strip is
+     * ordered by `Object.keys`, so define the record in the canonical
+     * `Confirmed → Packed → Shipped → Delivered` order.
      */
-    fulfilmentDetails: Record<FulfilmentStage, FulfilmentStageDetail>;
-    /** Override price formatting (locale, currency). Defaults to USD. */
-    formatPrice?: (value: number) => string;
+    fulfilmentDetails?: Record<FulfilmentStage, FulfilmentStageDetail>;
+    /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
+    formatPrice?: (money: Money) => string;
     titleLabel?: string;
     /** Template with `{number}`/`{date}`/`{email}` placeholders, resolved internally. */
     orderPlacedLabel?: string;
+    /** Used when the order carries no email. */
+    orderPlacedNoEmailLabel?: string;
     itemsLabel?: string;
     quantityLabel?: string;
     subtotalLabel?: string;
+    discountLabel?: string;
     shippingLabel?: string;
     taxLabel?: string;
     totalLabel?: string;
     freeLabel?: string;
+    /** Shown for a line whose supplied line total is absent or malformed. */
+    amountUnavailableLabel?: string;
     shippingAddressLabel?: string;
     billingAddressLabel?: string;
     continueShoppingLabel?: string;
@@ -1918,7 +2568,7 @@ interface CheckoutConfirmationProps {
  * your order record. Only the progress tabs are interactive, and they carry their own
  * `'use client'` — the boundary is one child rather than the whole page.
  */
-declare function CheckoutConfirmation({ order, orderLines, fulfilmentDetails, formatPrice, titleLabel, orderPlacedLabel, itemsLabel, quantityLabel, subtotalLabel, shippingLabel, taxLabel, totalLabel, freeLabel, shippingAddressLabel, billingAddressLabel, continueShoppingLabel, contactSupportLabel, supportLabel, progressLabel, estimatedDeliveryLabel, currentStageLabel, inProgressLabel, expectedByLabel, completedLabel, statusLabel, locationLabel, trackOrderLabel, continueShoppingHref, supportHref, onContinueShopping, }: CheckoutConfirmationProps): react.JSX.Element;
+declare function CheckoutConfirmation({ order, orderLines, fulfilmentDetails, formatPrice, titleLabel, orderPlacedLabel, orderPlacedNoEmailLabel, itemsLabel, quantityLabel, subtotalLabel, discountLabel, shippingLabel, taxLabel, totalLabel, freeLabel, amountUnavailableLabel, shippingAddressLabel, billingAddressLabel, continueShoppingLabel, contactSupportLabel, supportLabel, progressLabel, estimatedDeliveryLabel, currentStageLabel, inProgressLabel, expectedByLabel, completedLabel, statusLabel, locationLabel, trackOrderLabel, continueShoppingHref, supportHref, onContinueShopping, }: CheckoutConfirmationProps): react.JSX.Element;
 
 interface OrderHistory1Order {
     name: string;
@@ -1994,6 +2644,10 @@ interface FeaturedProduct$1 {
     image: string;
     colors: string[];
 }
+interface HeroImage {
+    src: string;
+    alt: string;
+}
 interface StorefrontHero1Props {
     title: string;
     description: string;
@@ -2002,6 +2656,12 @@ interface StorefrontHero1Props {
     badge?: string;
     primaryCta?: CTA;
     secondaryCta?: CTA;
+    /**
+     * Optional editorial image. Rendered as a native `<img>` when `src` is a
+     * non-empty string; omitted entirely when absent or blank (never an empty
+     * `src`). The product grid is unaffected.
+     */
+    heroImage?: HeroImage;
     onAddToCart?: (product: FeaturedProduct$1) => void;
     onBuyNow?: (product: FeaturedProduct$1) => void;
     onSelectColor?: (product: FeaturedProduct$1, index: number, color: string) => void;
@@ -2011,7 +2671,7 @@ interface StorefrontHero1Props {
     outOfStockLabel?: string;
     colorsLabel?: string;
 }
-declare function StorefrontHero1({ title, description, products, titleAccent, badge, primaryCta, secondaryCta, onAddToCart, onBuyNow, onSelectColor, addToCartLabel, buyNowLabel, newLabel, outOfStockLabel, colorsLabel, }: StorefrontHero1Props): react.JSX.Element;
+declare function StorefrontHero1({ title, description, products, titleAccent, badge, primaryCta, secondaryCta, heroImage, onAddToCart, onBuyNow, onSelectColor, addToCartLabel, buyNowLabel, newLabel, outOfStockLabel, colorsLabel, }: StorefrontHero1Props): react.JSX.Element;
 
 interface FeaturedProduct {
     /** Unique identifier for the product. */
@@ -2405,4 +3065,4 @@ interface Verify1Props {
 }
 declare function Verify1({ verifyTitleLabel, verifyDescriptionLabel, backupCodeTitleLabel, backupCodeDescriptionLabel, backupCodeLabel, backupCodePlaceholder, otpAriaLabel, verifyLabel, resendCodeLabel, resendCooldownLabel, useBackupCodeLabel, useAuthenticatorLabel, tooManyAttemptsLabel, attemptsLeftLabel, verifiedTitleLabel, verifiedDescriptionLabel, continueLabel, demoOtpHintLabel, demoBackupHintLabel, onVerify, onVerifyBackup, onResend, onContinue, }: Verify1Props): react.JSX.Element;
 
-export { AppShell1, Avatar, AvatarFallback, AvatarImage, Badge, Banner1, Button, type CTA, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CategoryFilter1, CategoryFilter2, type CategoryFilter2Category, type CategoryFilter2Color, type CategoryFilter2Filters, type CategoryFilter2PriceRange, type CategoryFilter2Props, type CategoryFilter2SortOption, CategoryFilter4, type CategoryFilter4Facets, type CategoryFilter4Product, type CategoryFilter4Props, CategoryIcon, type CategoryIconName, type CategoryIconProps, CheckoutConfirmation, type CheckoutConfirmationProps, type CheckoutFieldError, type CheckoutFieldErrors, CheckoutForm1, type CheckoutForm1ChangeHandler, type CheckoutForm1CountryOption, type CheckoutForm1FieldDescriptions, type CheckoutForm1FieldErrors, type CheckoutForm1FormData, type CheckoutForm1OrderSummary, type CheckoutForm1OrderSummaryItem, type CheckoutForm1Props, CheckoutForm2, type CheckoutForm2Data, type CheckoutForm2FieldDescriptions, type CheckoutForm2FieldErrors, type CheckoutForm2Item, type CheckoutForm2Props, type CheckoutForm2Totals, CheckoutForm3, type CheckoutForm3CartItem, type CheckoutForm3CountryOption, type CheckoutForm3FormData, type CheckoutForm3Props, type CheckoutForm3ShippingMethod, type CollectionItem, CtaSection1, type CtaSection1Props, FaqBlock1, type FaqBlock1Props, type FaqItem, Feature1, type Feature1Item, type Feature1Props, Feature2, type Feature2Item, type Feature2Props, type FeaturedProduct$1 as FeaturedProduct, type FilterProduct, type FooterLink, type FooterLinkColumn, FooterSection1, FooterSection3, type FooterSection3Props, FooterSection4, type FooterSection4Contact, type FooterSection4Link, type FooterSection4LinkColumn, type FooterSection4Props, type FooterSection4SocialIcon, type FooterSection4SocialLink, ForgotPasswordPage1, type ForgotPasswordPage1Props, type FulfilmentStage, type FulfilmentStageDetail, HeroSection1, LoginPage1, type LoginPage1FormData, type LoginPage1Props, type LoginPage1SocialButton, LoginPage2, type LoginPage2Props, type LoginPage2SocialButton, LogoCloud1, type LogoCloud1Platform, type LogoCloud1Props, MegaMenu, type MegaMenuProps, type MenuItem, MobileCategoryDrawer, type MobileCategoryDrawerProps, Navbar1, Navbar2, Navbar3, Navbar4, type Order$1 as Order, type OrderAddress, OrderHistory1, OrderHistory2, type OrderLine, type OrderTotals, PricingSection1, type PricingSection1Props, type PricingTier, ProductCard1, ProductCard2, ProductCard3, ProductCard5, ProductCategory1, type ProductCategory1Category, type ProductCategory1CategoryIcon, type ProductCategory1Props, ProductCategory2, type ProductCategory2Category, type ProductCategory2Props, ProductCategory4, ProductCategory5, ProductOverview1, ProductOverview2, type ProductOverview2Product, type ProductOverview2Props, ProductOverview5, type ProductOverview5Product, type ProductOverview5Props, type ProductOverview5Review, ProductQuickView, ReviewRating1, type ReviewRating1Review, ReviewRating2, ShoppingCart1, ShoppingCart2, type ShoppingCart2Item, type ShoppingCart2Props, ShoppingCart3, type ShoppingCart3CartItem, type ShoppingCart3Props, ShoppingCart4, type ShoppingCart4Item, type ShoppingCart4Props, SignUpPage1, type SignUpPage1Data, type SignUpPage1Props, type SignUpPage1SocialButton, type SocialLink, Statistic1, type Statistic1Props, type StatisticItem, StoreCategory, StoreContainer1, type StoreContainer1Props, StorefrontHero1, type StorefrontHero1Props, StorefrontHero2, StorefrontHero5, StorefrontHero6, Testimonial1, type Testimonial1Item, type Testimonial1Props, Testimonial2, type Testimonial2Item, type Testimonial2Props, Verify1, type Verify1Props, badgeVariants, buttonVariants, categoryIconNameSchema, categoryIconPropsSchema, cn, collectionItemSchema, megaMenuPropsSchema, menuItemSchema, mobileCategoryDrawerPropsSchema };
+export { AppShell1, Avatar, AvatarFallback, AvatarImage, BackToTop, type BackToTopProps, Badge, Banner1, Breadcrumb, type BreadcrumbItemData, type BreadcrumbProps, Button, type CTA, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CategoryFilter1, type CategoryFilter1Category, type CategoryFilter1PriceRange, type CategoryFilter1SortOption, CategoryFilter2, type CategoryFilter2ActiveFilter, type CategoryFilter2ActiveFilterKind, type CategoryFilter2Category, type CategoryFilter2Collection, type CategoryFilter2Color, type CategoryFilter2Filters, type CategoryFilter2PriceRange, type CategoryFilter2Props, type CategoryFilter2QueryError, type CategoryFilter2SortOption, type CategoryFilter2Status, CategoryFilter2StatusView, type CategoryFilter2StatusViewProps, CategoryFilter4, type CategoryFilter4Facets, type CategoryFilter4Product, type CategoryFilter4Props, CategoryIcon, type CategoryIconName, type CategoryIconProps, CheckoutConfirmation, type CheckoutConfirmationProps, type CheckoutFieldError, type CheckoutFieldErrors, CheckoutForm1, type CheckoutForm1ChangeHandler, type CheckoutForm1CountryOption, type CheckoutForm1FieldDescriptions, type CheckoutForm1FieldErrors, type CheckoutForm1FormData, type CheckoutForm1OrderSummary, type CheckoutForm1OrderSummaryItem, type CheckoutForm1Props, type CheckoutForm1ShippingOption, type CheckoutForm1Totals, type CheckoutForm1TotalsState, CheckoutForm2, type CheckoutForm2Data, type CheckoutForm2FieldDescriptions, type CheckoutForm2FieldErrors, type CheckoutForm2Item, type CheckoutForm2Props, type CheckoutForm2Totals, CheckoutForm3, type CheckoutForm3CartItem, type CheckoutForm3CountryOption, type CheckoutForm3FormData, type CheckoutForm3Props, type CheckoutForm3ShippingMethod, type CollectionItem, CtaSection1, type CtaSection1Props, FaqBlock1, type FaqBlock1Props, type FaqItem, Feature1, type Feature1Item, type Feature1Props, Feature2, type Feature2Item, type Feature2Props, type FeaturedProduct$1 as FeaturedProduct, type FilterProduct, type FooterLink, type FooterLinkColumn, FooterSection1, FooterSection3, type FooterSection3Props, FooterSection4, type FooterSection4Contact, type FooterSection4Link, type FooterSection4LinkColumn, type FooterSection4Props, type FooterSection4SocialIcon, type FooterSection4SocialLink, ForgotPasswordPage1, type ForgotPasswordPage1Props, type FulfilmentStage, type FulfilmentStageDetail, HeroSection1, LoginPage1, type LoginPage1FormData, type LoginPage1Props, type LoginPage1SocialButton, LoginPage2, type LoginPage2Props, type LoginPage2SocialButton, LogoCloud1, type LogoCloud1Platform, type LogoCloud1Props, MegaMenu, type MegaMenuProps, type MenuItem, MobileBottomNav, type MobileBottomNavItem, type MobileBottomNavProps, MobileCategoryDrawer, type MobileCategoryDrawerProps, Navbar1, Navbar2, Navbar3, Navbar4, type Order$1 as Order, type OrderAddress, OrderHistory1, OrderHistory2, type OrderLine, type OrderTotals, PricingSection1, type PricingSection1Props, type PricingTier, ProductCard1, type ProductCard1Product, type ProductCard1Props, ProductCard2, ProductCard3, ProductCard5, ProductCategory1, type ProductCategory1Category, type ProductCategory1CategoryIcon, type ProductCategory1Props, ProductCategory2, type ProductCategory2Category, type ProductCategory2Props, ProductCategory4, ProductCategory5, type ProductDetailProduct, type ProductDetailVariant, ProductOverview1, type ProductOverview1Props, type ProductOverview1Rating, ProductOverview2, type ProductOverview2Product, type ProductOverview2Props, ProductOverview5, type ProductOverview5Product, type ProductOverview5Props, type ProductOverview5Review, ProductPresentation, ProductQuickView, ProductShowcase1, type ProductShowcase1Props, ReviewRating1, type ReviewRating1Review, ReviewRating2, ShoppingCart1, ShoppingCart2, type ShoppingCart2Item, type ShoppingCart2Props, ShoppingCart3, type ShoppingCart3CartItem, type ShoppingCart3Props, ShoppingCart4, type ShoppingCart4Item, type ShoppingCart4Props, SignUpPage1, type SignUpPage1Data, type SignUpPage1Props, type SignUpPage1SocialButton, SkipToContent, type SkipToContentProps, type SocialLink, Statistic1, type Statistic1Props, type StatisticItem, StoreCategory, StoreContainer1, type StoreContainer1Props, StorefrontHero1, type StorefrontHero1Props, StorefrontHero2, StorefrontHero5, StorefrontHero6, Testimonial1, type Testimonial1Item, type Testimonial1Props, Testimonial2, type Testimonial2Item, type Testimonial2Props, Verify1, type Verify1Props, backToTopPropsSchema, badgeVariants, breadcrumbItemSchema, breadcrumbPropsSchema, buttonVariants, categoryIconNameSchema, categoryIconPropsSchema, cn, collectionItemSchema, megaMenuPropsSchema, menuItemSchema, mobileBottomNavItemSchema, mobileBottomNavPropsSchema, mobileCategoryDrawerPropsSchema, resolveScrollBehavior, skipToContentPropsSchema };