@fayz-ai/storefront 0.6.0 → 0.7.0

package/src/components/sections/MediaCarousel.tsx

@@ -0,0 +1,141 @@
+import React, { useEffect, useRef, useState } from 'react'
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import { Link } from '../../router'
+import { TID } from '../../testids'
+import { prefersReducedMotion } from '../../motion'
+import type { MediaCarouselItem } from '../../sections'
+import { useStorefrontConfig } from '../../config'
+
+export interface MediaCarouselProps {
+  items: MediaCarouselItem[]
+  height?: 'medium' | 'tall' | 'screen'
+  autoplayMs?: number
+  overlay?: 'dark' | 'soft' | 'none'
+  className?: string
+}
+
+const heightClass = {
+  medium: 'h-[58vh] min-h-[420px]',
+  tall: 'h-[74vh] min-h-[520px]',
+  screen: 'min-h-[calc(100vh-64px)]',
+}
+
+const alignClass = {
+  start: 'items-start text-left',
+  center: 'items-center text-center',
+  end: 'items-end text-right',
+}
+
+export function MediaCarousel({
+  items,
+  height = 'tall',
+  autoplayMs = 7000,
+  overlay = 'dark',
+  className = '',
+}: MediaCarouselProps) {
+  const [index, setIndex] = useState(0)
+  const [loadedItems, setLoadedItems] = useState<Record<number, boolean>>({})
+  const config = useStorefrontConfig()
+  const interacted = useRef(false)
+  const revealImages = config.imageLoading.mode !== 'none'
+  const revealStyle = (loaded: boolean): React.CSSProperties | undefined =>
+    revealImages
+      ? {
+          filter: config.imageLoading.blur && !loaded ? 'blur(10px)' : 'blur(0px)',
+          transition: `opacity 700ms ease, filter ${config.imageLoading.durationMs}ms ${config.imageLoading.easing}`,
+        }
+      : undefined
+
+  useEffect(() => {
+    if (items.length < 2 || autoplayMs <= 0 || prefersReducedMotion()) return
+    const timer = setInterval(() => {
+      if (!interacted.current) setIndex((i) => (i + 1) % items.length)
+    }, autoplayMs)
+    return () => clearInterval(timer)
+  }, [autoplayMs, items.length])
+
+  if (items.length === 0) return null
+
+  const active = items[Math.min(index, items.length - 1)]!
+  const goTo = (next: number) => {
+    interacted.current = true
+    setIndex((next + items.length) % items.length)
+  }
+  const overlayClass =
+    overlay === 'dark'
+      ? 'bg-gradient-to-r from-black/70 via-black/25 to-black/25'
+      : overlay === 'soft'
+        ? 'bg-gradient-to-t from-black/45 via-black/10 to-transparent'
+        : ''
+
+  return (
+    <section data-testid={TID.mediaCarousel} className={`relative isolate overflow-hidden ${heightClass[height]} ${className}`}>
+      {items.map((item, i) => (
+        <img
+          key={`${item.title}-${i}`}
+          src={item.image}
+          alt={item.imageAlt ?? item.title}
+          aria-hidden={i !== index}
+          loading={i === 0 ? 'eager' : 'lazy'}
+          decoding="async"
+          onLoad={() => setLoadedItems((current) => ({ ...current, [i]: true }))}
+          style={revealStyle(Boolean(loadedItems[i]))}
+          className={`absolute inset-0 -z-10 h-full w-full object-cover transition-opacity duration-700 ${
+            i === index && (!revealImages || loadedItems[i]) ? 'opacity-100' : 'opacity-0'
+          }`}
+        />
+      ))}
+      <div className={`absolute inset-0 -z-10 ${overlayClass}`} />
+      <div className={`flex h-full px-5 py-16 sm:px-10 lg:px-16 ${alignClass[active.align ?? 'start']}`}>
+        <div className="my-auto max-w-2xl text-white drop-shadow-md">
+          {active.eyebrow && (
+            <p className="mb-4 text-xs font-semibold uppercase tracking-[0.24em] text-white/80">{active.eyebrow}</p>
+          )}
+          <h1 className="sf-heading text-5xl font-normal leading-[0.95] sm:text-7xl lg:text-8xl">{active.title}</h1>
+          {active.subtitle && <p className="mt-5 max-w-xl text-base leading-8 text-white/88 sm:text-lg">{active.subtitle}</p>}
+          {active.cta && (
+            <Link
+              to={active.href ?? '/catalog'}
+              className="mt-8 inline-flex border border-white/75 px-6 py-3 text-xs font-semibold uppercase tracking-[0.18em] text-white transition hover:bg-white hover:text-black"
+            >
+              {active.cta}
+            </Link>
+          )}
+        </div>
+      </div>
+      {items.length > 1 && (
+        <>
+          <button
+            type="button"
+            aria-label="Previous slide"
+            data-testid={TID.mediaCarouselPrev}
+            onClick={() => goTo(index - 1)}
+            className="absolute left-4 top-1/2 inline-flex h-10 w-10 -translate-y-1/2 items-center justify-center border border-white/60 bg-black/20 text-white backdrop-blur transition hover:bg-white hover:text-black"
+          >
+            <ChevronLeft className="h-5 w-5" />
+          </button>
+          <button
+            type="button"
+            aria-label="Next slide"
+            data-testid={TID.mediaCarouselNext}
+            onClick={() => goTo(index + 1)}
+            className="absolute right-4 top-1/2 inline-flex h-10 w-10 -translate-y-1/2 items-center justify-center border border-white/60 bg-black/20 text-white backdrop-blur transition hover:bg-white hover:text-black"
+          >
+            <ChevronRight className="h-5 w-5" />
+          </button>
+          <div className="absolute bottom-5 left-1/2 flex -translate-x-1/2 gap-2">
+            {items.map((item, i) => (
+              <button
+                key={`${item.title}-dot-${i}`}
+                type="button"
+                aria-label={`Go to slide ${i + 1}`}
+                onClick={() => goTo(i)}
+                className={`h-2 rounded-full transition-all ${i === index ? 'w-8 bg-white' : 'w-2 bg-white/55 hover:bg-white'}`}
+              />
+            ))}
+          </div>
+        </>
+      )}
+    </section>
+  )
+}

package/src/components/sections/MiscSections.tsx

@@ -4,6 +4,7 @@ import { bannerPlaceholder } from '../../sections'
 import { Reveal } from '../../motion'
 import { Link } from '../../router'
 import { TID } from '../../testids'
+import { SmoothImage } from '../SmoothImage'
 
 function Icon({ name, className }: { name: string; className?: string }) {
   const C = (LucideIcons as unknown as Record<string, React.ComponentType<{ className?: string }>>)[name]
@@ -49,7 +50,7 @@ export function PromoBanner({
 }) {
   return (
     <section data-testid={TID.promoBanner} className="group relative my-12 overflow-hidden">
-      <img
+      <SmoothImage
         src={image ?? bannerPlaceholder(title, hue, hue + 50, 1600, 420)}
         alt={title}
         className="h-80 w-full object-cover transition-transform duration-700 ease-out group-hover:scale-105"

package/src/components/sections/ProductRail.tsx

@@ -1,6 +1,7 @@
 import React, { useMemo } from 'react'
 import { useProducts } from '../../hooks/useProducts'
-import { useStorefrontConfig } from '../../config'
+import { getStorefrontComponents, useStorefrontConfig } from '../../config'
+import { useStorefrontActions } from '../../hooks/useStorefront'
 import { ProductCard } from '../ProductCard'
 import { Reveal } from '../../motion'
 import { Link } from '../../router'
@@ -20,7 +21,9 @@ export function ProductRail({
   limit?: number
 }) {
   const config = useStorefrontConfig()
-  const ProductCardComponent = config.slots?.ProductCard ?? ProductCard
+  const actions = useStorefrontActions()
+  const components = getStorefrontComponents(config)
+  const ProductCardComponent = components.ProductCard ?? ProductCard
   const { products, loading } = useProducts(
     filter === 'new'
       ? { status: 'active', orderBy: 'created_at', order: 'desc' }
@@ -54,7 +57,12 @@ export function ProductRail({
         <div className="grid grid-cols-2 gap-5 md:grid-cols-4">
           {visible.map((p, i) => (
             <Reveal key={p.id} delay={i * 90}>
-              <ProductCardComponent product={p} />
+              <ProductCardComponent
+                product={p}
+                config={config}
+                commerceMode={config.commerceMode}
+                actions={actions}
+              />
             </Reveal>
           ))}
         </div>

package/src/components/sections/ProductSlider.tsx

@@ -0,0 +1,119 @@
+import React, { useMemo, useRef } from 'react'
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import { getStorefrontComponents, useStorefrontConfig } from '../../config'
+import { useProducts } from '../../hooks/useProducts'
+import { useStorefrontActions } from '../../hooks/useStorefront'
+import { ProductCard } from '../ProductCard'
+import { Link } from '../../router'
+import { TID } from '../../testids'
+
+export interface ProductSliderProps {
+  title: string
+  subtitle?: string
+  eyebrow?: string
+  filter?: 'sale' | 'new' | 'all'
+  categoryName?: string
+  collection?: string
+  limit?: number
+  cta?: string
+  href?: string
+  className?: string
+}
+
+export function ProductSlider({
+  title,
+  subtitle,
+  eyebrow,
+  filter = 'all',
+  categoryName,
+  collection,
+  limit = 10,
+  cta = 'View all',
+  href,
+  className = '',
+}: ProductSliderProps) {
+  const config = useStorefrontConfig()
+  const actions = useStorefrontActions()
+  const viewportRef = useRef<HTMLDivElement>(null)
+  const components = getStorefrontComponents(config)
+  const ProductCardComponent = components.ProductCard ?? ProductCard
+  const { products, loading } = useProducts(
+    filter === 'new'
+      ? { status: 'active', orderBy: 'created_at', order: 'desc' }
+      : { status: 'active' },
+  )
+
+  const visible = useMemo(() => {
+    let list = products
+    if (filter === 'sale') list = list.filter((p) => p.compareAtPrice != null && p.compareAtPrice > p.price)
+    if (categoryName) list = list.filter((p) => p.categoryName === categoryName)
+    if (collection) list = list.filter((p) => p.metadata?.collection === collection)
+    return list.slice(0, limit)
+  }, [categoryName, collection, filter, limit, products])
+
+  const scroll = (direction: -1 | 1) => {
+    viewportRef.current?.scrollBy({ left: direction * Math.max(320, viewportRef.current.clientWidth * 0.75), behavior: 'smooth' })
+  }
+
+  if (!loading && visible.length === 0) return null
+
+  return (
+    <section data-testid={TID.productSlider} className={`mx-auto max-w-7xl px-4 py-14 sm:px-6 ${className}`}>
+      <div className="mb-8 flex flex-col gap-5 sm:flex-row sm:items-end sm:justify-between">
+        <div className="max-w-2xl">
+          {eyebrow && <p className="mb-2 text-xs font-semibold uppercase tracking-[0.2em] text-primary">{eyebrow}</p>}
+          <h2 className="sf-heading text-3xl font-normal leading-tight tracking-normal sm:text-5xl">{title}</h2>
+          {subtitle && <p className="mt-3 leading-7 text-muted-foreground">{subtitle}</p>}
+        </div>
+        <div className="flex items-center gap-2">
+          <button
+            type="button"
+            aria-label="Previous products"
+            data-testid={TID.productSliderPrev}
+            onClick={() => scroll(-1)}
+            className="inline-flex h-10 w-10 items-center justify-center border border-border bg-background transition hover:bg-foreground hover:text-background"
+          >
+            <ChevronLeft className="h-5 w-5" />
+          </button>
+          <button
+            type="button"
+            aria-label="Next products"
+            data-testid={TID.productSliderNext}
+            onClick={() => scroll(1)}
+            className="inline-flex h-10 w-10 items-center justify-center border border-border bg-background transition hover:bg-foreground hover:text-background"
+          >
+            <ChevronRight className="h-5 w-5" />
+          </button>
+        </div>
+      </div>
+      <div
+        ref={viewportRef}
+        data-testid={TID.productSliderViewport}
+        className="flex snap-x gap-5 overflow-x-auto pb-5 [scrollbar-width:thin]"
+      >
+        {loading
+          ? Array.from({ length: Math.min(limit, 6) }, (_, i) => (
+              <div key={i} className="h-[360px] min-w-[260px] snap-start animate-pulse bg-muted" />
+            ))
+          : visible.map((product) => (
+              <div key={product.id} className="min-w-[260px] max-w-[300px] flex-[0_0_72vw] snap-start sm:flex-[0_0_300px]">
+                <ProductCardComponent
+                  product={product}
+                  config={config}
+                  commerceMode={config.commerceMode}
+                  actions={actions}
+                />
+              </div>
+            ))}
+      </div>
+      {cta && (
+        <Link
+          to={href ?? config.catalogPath}
+          className="mt-4 inline-flex border border-foreground/30 px-6 py-3 text-xs font-semibold uppercase tracking-[0.16em] transition hover:bg-foreground hover:text-background"
+        >
+          {cta}
+        </Link>
+      )}
+    </section>
+  )
+}

package/src/config.ts

@@ -1,14 +1,10 @@
 import React, { createContext, useContext } from 'react'
-import type { Product } from '@fayz-ai/shop/types'
 import type { ShopProvider } from '@fayz-ai/shop/provider'
 import type { MockShopSeed } from '@fayz-ai/shop/mock'
 import type { StorefrontTheme } from './theme'
 import type { HomeConfig, NavLink, FooterConfig } from './sections'
-import type { StorefrontAuthAdapter } from './auth'
-
-export interface ProductCardSlotProps {
-  product: Product
-}
+import type { StorefrontAuthConfig } from './auth'
+import type { StorefrontComponents } from './component-contracts'
 
 export type StorefrontRouteKind =
   | 'home'
@@ -28,6 +24,15 @@ export interface StorefrontRouteComponentProps {
 }
 
 export type StorefrontRouteChrome = 'default' | 'focused'
+export type StorefrontCommerceMode = 'checkout' | 'catalog' | 'enquiry'
+export type StorefrontImageLoadingMode = 'fade' | 'none'
+
+export interface StorefrontImageLoadingConfig {
+  mode?: StorefrontImageLoadingMode
+  durationMs?: number
+  easing?: string
+  blur?: boolean
+}
 
 export interface StorefrontRouteDefinition {
   /**
@@ -54,22 +59,21 @@ export interface StorefrontRouteDefinition {
   component: React.ComponentType<StorefrontRouteComponentProps>
 }
 
-export interface StorefrontSlots {
-  /**
-   * Product card renderer used by catalog grids and product rails.
-   *
-   * Custom renderers must preserve `productCardSlotContract` selectors so
-   * checkout smoke tests, QA, and agents can still operate the storefront.
-   */
-  ProductCard?: React.ComponentType<ProductCardSlotProps>
-}
-
 export interface StorefrontDiscountConfig {
   code: string
   percent: number
   title?: string
 }
 
+export interface StorefrontEnquiryConfig {
+  label?: string
+  successMessage?: string
+  subjectPrefix?: string
+  email?: string
+  whatsappUrl?: string
+  requirePhone?: boolean
+}
+
 export interface StorefrontConfig {
   /** Store display name (header, page title) */
   name: string
@@ -81,6 +85,8 @@ export interface StorefrontConfig {
   locale?: string
   /** Visual identity: colors, fonts, radius, header/card personality */
   theme?: StorefrontTheme
+  /** Checkout-first default, catalog-only browsing, or product enquiry flow. */
+  commerceMode?: StorefrontCommerceMode
   /** Promo message above the header (e.g. 'FRETE GRÁTIS ACIMA DE R$ 300') */
   announcement?: string
   /** Home page blueprint. When set, `/` renders it and the catalog moves to /catalog. */
@@ -108,7 +114,7 @@ export interface StorefrontConfig {
    */
   legal?: { privacy?: string; terms?: string; returns?: string }
   /** Customer auth — same AuthAdapter contract as createSaasApp. Default: mock. */
-  auth?: { adapter?: StorefrontAuthAdapter }
+  auth?: StorefrontAuthConfig
   /** Shipping pricing — default { flatRate: 0 } */
   shipping?: { flatRate?: number; freeAbove?: number }
   /**
@@ -117,12 +123,16 @@ export interface StorefrontConfig {
    * a real payment webhook confirms settlement.
    */
   payments?: { mode?: 'mock' | 'pix-mercadopago' }
-  /** Feature toggles — discounts default off; accounts default on */
-  features?: { discounts?: boolean; accounts?: boolean }
-  /** Code-level customization slots. Kept out of serialized manifests. */
-  slots?: StorefrontSlots
+  /** Product enquiry behavior for catalog/enquiry stores. */
+  enquiry?: StorefrontEnquiryConfig
+  /** Feature toggles — defaults depend on commerceMode. */
+  features?: { discounts?: boolean; accounts?: boolean; cart?: boolean; checkout?: boolean }
+  /** Global storefront image reveal behavior. Default is a soft fade. */
+  imageLoading?: StorefrontImageLoadingConfig
+  /** Code-level component replacements. Kept out of serialized manifests. */
+  components?: StorefrontComponents
   /** Code-level route overrides/custom routes. Kept out of serialized manifests. */
-  routes?: StorefrontRouteDefinition[]
+  routes?: readonly StorefrontRouteDefinition[]
 }
 
 export interface ResolvedStorefrontConfig extends StorefrontConfig {
@@ -130,7 +140,11 @@ export interface ResolvedStorefrontConfig extends StorefrontConfig {
   locale: string
   shipping: { flatRate: number; freeAbove?: number }
   payments: { mode: 'mock' | 'pix-mercadopago' }
-  features: { discounts: boolean; accounts: boolean }
+  commerceMode: StorefrontCommerceMode
+  enquiry: Required<Pick<StorefrontEnquiryConfig, 'label' | 'successMessage' | 'subjectPrefix'>> &
+    Omit<StorefrontEnquiryConfig, 'label' | 'successMessage' | 'subjectPrefix'>
+  features: { discounts: boolean; accounts: boolean; cart: boolean; checkout: boolean }
+  imageLoading: Required<StorefrontImageLoadingConfig>
   /** Where the full product list lives ('/' without a home page, '/catalog' with one) */
   catalogPath: string
   nav: NavLink[]
@@ -138,12 +152,23 @@ export interface ResolvedStorefrontConfig extends StorefrontConfig {
 
 export function resolveConfig(config: StorefrontConfig): ResolvedStorefrontConfig {
   const catalogPath = config.home ? '/catalog' : '/'
+  const commerceMode = config.commerceMode ?? 'checkout'
+  const checkoutEnabled = commerceMode === 'checkout'
   return {
     ...config,
     currency: config.currency ?? 'BRL',
     locale: config.locale ?? 'pt-BR',
     shipping: { flatRate: config.shipping?.flatRate ?? 0, freeAbove: config.shipping?.freeAbove },
     payments: { mode: config.payments?.mode ?? 'mock' },
+    commerceMode,
+    enquiry: {
+      label: config.enquiry?.label ?? 'Contact me',
+      successMessage: config.enquiry?.successMessage ?? 'Thanks. We received your enquiry.',
+      subjectPrefix: config.enquiry?.subjectPrefix ?? 'Product enquiry',
+      email: config.enquiry?.email,
+      whatsappUrl: config.enquiry?.whatsappUrl,
+      requirePhone: config.enquiry?.requirePhone,
+    },
     features: {
       // Auto-enable the coupon UI when the store actually ships discount codes
       // (via config.discounts or a seeded catalog), unless explicitly overridden —
@@ -151,7 +176,15 @@ export function resolveConfig(config: StorefrontConfig): ResolvedStorefrontConfi
       discounts:
         config.features?.discounts ??
         Boolean(config.discounts?.length || config.catalog?.discounts?.length),
-      accounts: config.features?.accounts ?? true,
+      accounts: config.features?.accounts ?? checkoutEnabled,
+      cart: config.features?.cart ?? checkoutEnabled,
+      checkout: config.features?.checkout ?? checkoutEnabled,
+    },
+    imageLoading: {
+      mode: config.imageLoading?.mode ?? 'fade',
+      durationMs: config.imageLoading?.durationMs ?? 420,
+      easing: config.imageLoading?.easing ?? 'cubic-bezier(0.22, 1, 0.36, 1)',
+      blur: config.imageLoading?.blur ?? true,
     },
     catalogPath,
     nav:
@@ -174,3 +207,11 @@ export function useStorefrontConfig(): ResolvedStorefrontConfig {
   if (!ctx) throw new Error('useStorefrontConfig must be used inside createStorefrontApp')
   return ctx
 }
+
+export function useStorefrontConfigOptional(): ResolvedStorefrontConfig | null {
+  return useContext(StorefrontConfigContext)
+}
+
+export function getStorefrontComponents(config: ResolvedStorefrontConfig): StorefrontComponents {
+  return config.components ?? {}
+}

package/src/createStorefrontApp.tsx

@@ -3,9 +3,12 @@ import { setShopProvider } from '@fayz-ai/shop/runtime'
 import { createMockShopProvider } from '@fayz-ai/shop/mock'
 import type { MockShopSeed } from '@fayz-ai/shop/mock'
 import type { Discount } from '@fayz-ai/shop/types'
+import type { ShopProvider } from '@fayz-ai/shop/provider'
 import { initCustomerAuth, resolveAuthAdapter } from './auth'
-import { StorefrontConfigProvider, resolveConfig, useStorefrontConfig } from './config'
+import { getStorefrontComponents, StorefrontConfigProvider, resolveConfig, useStorefrontConfig } from './config'
 import type { StorefrontConfig, StorefrontDiscountConfig } from './config'
+import type { StorefrontComponents } from './component-contracts'
+import type { StorefrontSection } from './sections'
 import { useHashPath, matchPath } from './router'
 import { StorefrontThemeStyle } from './theme'
 import { StorefrontHeader } from './components/StorefrontHeader'
@@ -51,8 +54,8 @@ function RouteSwitch({ path }: { path: string }) {
   const order = matchPath('/order/:id', path)
   if (order?.id) return <OrderConfirmationPage orderId={order.id} />
 
-  if (matchPath('/checkout', path)) return <CheckoutPage />
-  if (matchPath('/account', path)) return <MyPurchasesPage />
+  if (matchPath('/checkout', path) && config.features.checkout) return <CheckoutPage />
+  if (matchPath('/account', path) && config.features.accounts) return <MyPurchasesPage />
   if (matchPath('/catalog', path)) return <CatalogPage />
   if (matchPath('/privacy', path)) return <PolicyPage kind="privacy" />
   if (matchPath('/terms', path)) return <PolicyPage kind="terms" />
@@ -112,7 +115,12 @@ function buildMockSeed(config: StorefrontConfig): MockShopSeed | undefined {
 }
 
 export function initStorefrontRuntime(config: StorefrontConfig): void {
-  initCustomerAuth(resolveAuthAdapter(config.auth?.adapter))
+  if (resolveConfig(config).features.accounts) {
+    initCustomerAuth(resolveAuthAdapter(config.auth, {
+      supabaseUrl: config.supabaseUrl,
+      supabaseAnonKey: config.supabaseAnonKey,
+    }))
+  }
 
   if (config.provider) {
     setShopProvider(config.provider)
@@ -133,16 +141,34 @@ export function StorefrontShell() {
   const config = useStorefrontConfig()
   const path = useHashPath()
   const focused = isFocusedRoute(config, path)
-  return (
-    <div className="min-h-screen bg-background text-foreground">
+  const components = getStorefrontComponents(config)
+  const chromeProps = { config, commerceMode: config.commerceMode }
+  const body = (
+    <>
       {config.theme && <StorefrontThemeStyle theme={config.theme} />}
-      {!focused && <StorefrontHeader />}
+      {!focused &&
+        (components.Header ? <components.Header {...chromeProps} /> : <StorefrontHeader />)}
       <StorefrontErrorBoundary key={path}>
         <RouteSwitch path={path} />
       </StorefrontErrorBoundary>
-      {!focused && <CartDrawer />}
-      {!focused && <StorefrontFooter />}
+      {!focused && config.features.cart && <CartDrawer />}
+      {!focused &&
+        (components.Footer ? <components.Footer {...chromeProps} /> : <StorefrontFooter />)}
       <Toaster />
+    </>
+  )
+
+  if (components.Shell) {
+    return (
+      <components.Shell {...chromeProps}>
+        {body}
+      </components.Shell>
+    )
+  }
+
+  return (
+    <div className="min-h-screen bg-background text-foreground">
+      {body}
     </div>
   )
 }
@@ -169,3 +195,30 @@ export function createStorefrontApp(config: StorefrontConfig): React.ComponentTy
   StorefrontApp.displayName = 'StorefrontApp'
   return StorefrontApp
 }
+
+export interface CreateStorefrontOptions {
+  config: StorefrontConfig
+  provider?: ShopProvider
+  components?: StorefrontComponents
+  routes?: StorefrontConfig['routes']
+  pages?: StorefrontConfig['routes']
+  sections?: readonly StorefrontSection[]
+}
+
+export function createStorefront(options: CreateStorefrontOptions): React.ComponentType {
+  const routes = [...(options.pages ?? []), ...(options.routes ?? [])]
+  const config: StorefrontConfig = {
+    ...options.config,
+    provider: options.provider ?? options.config.provider,
+    components: {
+      ...options.config.components,
+      ...options.components,
+    },
+    routes: routes.length > 0 ? routes : options.config.routes,
+    home: options.sections
+      ? { ...(options.config.home ?? { sections: [] }), sections: options.sections }
+      : options.config.home,
+  }
+
+  return createStorefrontApp(config)
+}

package/src/define.ts

@@ -0,0 +1,34 @@
+import type {
+  StorefrontConfig,
+  StorefrontRouteDefinition,
+} from './config'
+import type { StorefrontComponents } from './component-contracts'
+import type { StorefrontSection } from './sections'
+import type { CreateStorefrontOptions } from './createStorefrontApp'
+
+/**
+ * Identity helpers for generated/custom storefronts.
+ *
+ * They do not add runtime behavior; they make the intended client-app shape
+ * explicit and keep TypeScript inference tight across config, components, routes,
+ * sections and app creation options.
+ */
+export function defineStorefrontConfig<const T extends StorefrontConfig>(config: T): T {
+  return config
+}
+
+export function defineStorefrontComponents<const T extends StorefrontComponents>(components: T): T {
+  return components
+}
+
+export function defineStorefrontRoutes<const T extends readonly StorefrontRouteDefinition[]>(routes: T): T {
+  return routes
+}
+
+export function defineStorefrontSections<const T extends readonly StorefrontSection[]>(sections: T): T {
+  return sections
+}
+
+export function defineStorefrontApp<const T extends CreateStorefrontOptions>(options: T): T {
+  return options
+}

package/src/hooks/index.ts

@@ -1,5 +1,6 @@
 export { useProducts } from './useProducts'
 export { useProduct } from './useProduct'
 export { useCategories } from './useCategories'
+export { useStorefront, useCatalog, useCart, useEnquiry, useStorefrontActions } from './useStorefront'
 export { useMyOrders } from './useMyOrders'
 export { useDiscountValidator } from './useDiscountValidator'