@fayz-ai/storefront 0.2.0

package/src/pages/ProductDetailPage.tsx

@@ -0,0 +1,184 @@
+import React, { useEffect, useState } from 'react'
+import { ChevronLeft, RefreshCcw, ShieldCheck, Truck } from 'lucide-react'
+import { useProduct } from '../hooks/useProduct'
+import { useCartStore } from '../stores/cart.store'
+import { useStorefrontConfig } from '../config'
+import { useStorefrontHead } from '../hooks/useStorefrontHead'
+import { Link } from '../router'
+import { Price } from '../components/Price'
+import { QuantityInput } from '../components/QuantityInput'
+import { ProductOptionSelector } from '../components/ProductOptionSelector'
+import { ProductSpecs } from '../components/ProductSpecs'
+import { RelatedProducts } from '../components/RelatedProducts'
+import { getProductOptionGroups, type ProductOptionSelection } from '../product-options'
+import { TID } from '../testids'
+
+export function ProductDetailPage({ slug }: { slug: string }) {
+  const config = useStorefrontConfig()
+  const { product, loading } = useProduct(slug)
+  const addItem = useCartStore((s) => s.addItem)
+  const [qty, setQty] = useState(1)
+  const [selectedOptions, setSelectedOptions] = useState<ProductOptionSelection>({})
+
+  const optionGroups = product ? getProductOptionGroups(product) : []
+  useStorefrontHead({
+    title: product ? `${product.name} — ${config.name}` : config.name,
+    description: product?.description,
+  })
+
+  useEffect(() => {
+    if (!product) return
+    const defaults = Object.fromEntries(
+      getProductOptionGroups(product).map((group) => [group.label, group.values[0] ?? '']),
+    )
+    setSelectedOptions(defaults)
+  }, [product?.id])
+
+  if (loading) {
+    return (
+      <main className="mx-auto max-w-5xl px-4 py-8 sm:px-6">
+        <div className="grid animate-pulse gap-10 md:grid-cols-2">
+          <div className="aspect-square rounded-2xl bg-muted" />
+          <div className="space-y-4 py-4">
+            <div className="h-8 w-3/4 rounded bg-muted" />
+            <div className="h-6 w-1/3 rounded bg-muted" />
+            <div className="h-24 rounded bg-muted" />
+          </div>
+        </div>
+      </main>
+    )
+  }
+
+  if (!product) {
+    return (
+      <main className="mx-auto max-w-5xl px-4 py-20 text-center sm:px-6">
+        <p className="text-lg text-muted-foreground">Produto não encontrado.</p>
+        <Link to="/" className="mt-4 inline-block text-primary underline">Voltar à loja</Link>
+      </main>
+    )
+  }
+
+  const soldOut = product.inventoryCount <= 0
+  const lowStock = !soldOut && product.inventoryCount <= 5
+  const image = product.images.find((i) => i.isPrimary) ?? product.images[0]
+  const discountPct =
+    product.compareAtPrice && product.compareAtPrice > product.price
+      ? Math.round((1 - product.price / product.compareAtPrice) * 100)
+      : 0
+
+  return (
+    <main className="mx-auto max-w-5xl px-4 py-8 sm:px-6">
+      <Link to="/" className="mb-6 inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground">
+        <ChevronLeft className="h-4 w-4" /> Continuar comprando
+      </Link>
+
+      <div className="grid animate-fade-up gap-10 md:grid-cols-2">
+        <div className="group overflow-hidden border bg-muted" style={{ borderRadius: 'var(--sf-radius-card)' }}>
+          {image && (
+            <img
+              src={image.url}
+              alt={image.altText ?? product.name}
+              className="aspect-square w-full object-cover transition-transform duration-700 ease-out group-hover:scale-105"
+            />
+          )}
+        </div>
+
+        <div className="flex flex-col py-2 lg:sticky lg:top-24 lg:self-start">
+          <nav className="mb-3 flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground">
+            <Link to="/" className="transition-colors hover:text-foreground">Início</Link>
+            {product.categoryName && (
+              <>
+                <span aria-hidden>/</span>
+                <span>{product.categoryName}</span>
+              </>
+            )}
+            <span aria-hidden>/</span>
+            <span className="text-foreground">{product.name}</span>
+          </nav>
+
+          <h1 data-testid={TID.pdpName} className="sf-heading text-3xl font-bold tracking-tight">
+            {product.name}
+          </h1>
+
+          <div className="mt-3 flex items-center gap-3">
+            <div className="text-xl">
+              <Price
+                value={product.price}
+                compareAt={product.compareAtPrice}
+                testId={TID.pdpPrice}
+                compareTestId={TID.pdpComparePrice}
+              />
+            </div>
+            {discountPct > 0 && (
+              <span className="rounded-full bg-primary/10 px-2.5 py-1 text-xs font-bold text-primary">
+                −{discountPct}%
+              </span>
+            )}
+          </div>
+
+          <p data-testid={TID.pdpDescription} className="mt-5 leading-relaxed text-muted-foreground">
+            {product.description}
+          </p>
+
+          <div className="mt-4 flex flex-wrap items-center gap-x-3 gap-y-1 text-sm">
+            {soldOut ? (
+              <span className="inline-flex items-center gap-2 font-medium text-muted-foreground">
+                <span className="h-2 w-2 rounded-full bg-muted-foreground" /> Sem estoque
+              </span>
+            ) : lowStock ? (
+              <span className="inline-flex items-center gap-2 font-semibold text-amber-600">
+                <span className="h-2 w-2 animate-pulse rounded-full bg-amber-500" />
+                Últimas unidades — só {product.inventoryCount} restantes
+              </span>
+            ) : (
+              <span className="inline-flex items-center gap-2 font-medium text-emerald-600">
+                <span className="h-2 w-2 rounded-full bg-emerald-500" /> Em estoque
+              </span>
+            )}
+            {product.sku && <span className="text-muted-foreground">SKU: {product.sku}</span>}
+          </div>
+
+          <ProductOptionSelector
+            groups={optionGroups}
+            value={selectedOptions}
+            onChange={setSelectedOptions}
+          />
+
+          <div className="mt-8 flex items-center gap-4">
+            <QuantityInput
+              value={qty}
+              onChange={setQty}
+              max={soldOut ? 1 : product.inventoryCount}
+              testId={TID.pdpQtyInput}
+            />
+            <button
+              type="button"
+              data-testid={TID.pdpAddToCart}
+              disabled={soldOut}
+              onClick={() => addItem(product, qty, selectedOptions)}
+              className="sf-cta flex-1 bg-primary py-3.5 font-semibold text-primary-foreground shadow-md transition-all hover:-translate-y-0.5 hover:shadow-lg disabled:cursor-not-allowed disabled:opacity-40 disabled:shadow-none disabled:hover:translate-y-0"
+              style={{ borderRadius: 'var(--sf-radius-button)' }}
+            >
+              {soldOut ? 'Esgotado' : 'Adicionar ao carrinho'}
+            </button>
+          </div>
+
+          <div className="mt-6 grid grid-cols-3 gap-3 border-t pt-6 text-center">
+            <div className="flex flex-col items-center gap-1.5 text-[11px] font-medium text-muted-foreground">
+              <Truck className="h-5 w-5 text-primary" /> Envio rápido
+            </div>
+            <div className="flex flex-col items-center gap-1.5 text-[11px] font-medium text-muted-foreground">
+              <RefreshCcw className="h-5 w-5 text-primary" /> Troca fácil
+            </div>
+            <div className="flex flex-col items-center gap-1.5 text-[11px] font-medium text-muted-foreground">
+              <ShieldCheck className="h-5 w-5 text-primary" /> Pagamento seguro
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <ProductSpecs product={product} />
+      <RelatedProducts product={product} />
+    </main>
+  )
+}

package/src/presets.ts

@@ -0,0 +1,258 @@
+import type { StorefrontTheme } from './theme'
+import type { HomeConfig } from './sections'
+
+// ---------------------------------------------------------------------------
+// Template presets — recreations of the four Nuvemshop patterns selected in
+// docs/storefront-templates-research.md. Each is { theme, home() } so an app
+// (or the Fayz agent) starts from a complete professional store and overrides
+// copy, colors, hero images and sections — the saas-core theming workflow.
+// ---------------------------------------------------------------------------
+
+/** Real imagery for a template home — resolved at build time (e.g. via
+ *  scripts/fetch-unsplash.mjs); falls back to gradient placeholders when omitted. */
+export interface TemplateImages {
+  hero?: Array<string | undefined>
+  banners?: Array<string | undefined>
+}
+
+export interface StorefrontTemplate {
+  id: string
+  /** The Nuvemshop pattern this recreates */
+  inspiration: string
+  theme: StorefrontTheme
+  /** Default home blueprint — pass the store name for copy interpolation */
+  home: (storeName: string, images?: TemplateImages) => HomeConfig
+  announcement?: string
+}
+
+/** maré — elegant fashion (Rio): airy warm paper, olive ink, sand CTA, centered logo. */
+export const mareTemplate: StorefrontTemplate = {
+  id: 'mare',
+  inspiration: 'Nuvemshop Rio',
+  announcement: 'FRETE GRÁTIS EM COMPRAS ACIMA DE R$ 300',
+  theme: {
+    name: 'mare',
+    colors: {
+      background: '40 14% 93%',
+      foreground: '90 8% 38%',
+      primary: '42 32% 61%',
+      primaryForeground: '40 30% 12%',
+      card: '40 20% 97%',
+      cardForeground: '90 10% 25%',
+      muted: '40 12% 88%',
+      mutedForeground: '90 6% 50%',
+      border: '40 10% 82%',
+      announcementBackground: '90 10% 30%',
+      announcementForeground: '40 20% 95%',
+    },
+    font: { heading: 'Plus Jakarta Sans', body: 'Plus Jakarta Sans' },
+    radius: 'soft',
+    header: { variant: 'centered' },
+    productCard: { style: 'editorial', imageAspect: 'portrait' },
+  },
+  home: (storeName, images) => ({
+    sections: [
+      {
+        type: 'hero',
+        variant: 'banner',
+        height: 'tall',
+        slides: [
+          { title: 'Feito para durar', subtitle: `A nova coleção ${storeName} chegou — peças atemporais em materiais honestos.`, cta: 'Ver coleção', hue: 75, image: images?.hero?.[0] },
+        ],
+      },
+      { type: 'categories', style: 'bubbles' },
+      { type: 'products', title: 'Destaques', filter: 'all', limit: 4 },
+      { type: 'banner', title: 'Até 30% off', eyebrow: 'por tempo limitado', subtitle: 'Peças selecionadas da estação', cta: 'Aproveitar', hue: 40, image: images?.banners?.[0] },
+      { type: 'products', title: 'Promoções', filter: 'sale', limit: 4 },
+      { type: 'products', title: 'Lançamentos', filter: 'new', limit: 4 },
+      { type: 'newsletter', title: 'Assine nossa newsletter', subtitle: 'Novidades e ofertas exclusivas, sem spam.' },
+    ],
+  }),
+}
+
+/** sertão — editorial organic (Uyuni): cream paper, coffee serif ink, boxed hero, manifesto. */
+export const sertaoTemplate: StorefrontTemplate = {
+  id: 'sertao',
+  inspiration: 'Nuvemshop Uyuni',
+  theme: {
+    name: 'sertao',
+    colors: {
+      background: '30 100% 98%',
+      foreground: '28 42% 32%',
+      primary: '28 42% 32%',
+      primaryForeground: '30 100% 97%',
+      card: '32 60% 96%',
+      cardForeground: '28 40% 26%',
+      muted: '32 40% 92%',
+      mutedForeground: '28 22% 48%',
+      border: '28 30% 80%',
+    },
+    font: { heading: 'Marcellus', body: 'Marcellus', fallback: 'serif' },
+    radius: 'none',
+    header: { variant: 'minimal', uppercaseNav: true },
+    productCard: { style: 'editorial', imageAspect: 'portrait' },
+    uppercaseButtons: true,
+  },
+  home: (storeName, images) => ({
+    sections: [
+      {
+        type: 'hero',
+        variant: 'banner',
+        height: 'tall',
+        slides: [
+          { title: 'Essenciais naturais', subtitle: 'Conheça nossa coleção', cta: 'Ver mais', hue: 28, boxed: true, image: images?.hero?.[0] },
+        ],
+      },
+      {
+        type: 'manifesto',
+        text: `Num mundo de pressa e excesso, ${storeName} escolhe o caminho lento: ingredientes honestos, produção pequena e cuidado em cada detalhe.`,
+      },
+      { type: 'categories', style: 'tiles' },
+      { type: 'products', title: 'ESSENCIAIS', filter: 'all', limit: 4 },
+      {
+        type: 'testimonials',
+        title: 'Nossos clientes',
+        items: [
+          { quote: 'Qualidade impecável e um cheiro que abraça.', author: 'Helena M.' },
+          { quote: 'Compro há dois anos e nunca me decepcionou.', author: 'Rafael T.' },
+          { quote: 'Entrega rápida e embalagem linda, dá gosto de presentear.', author: 'Cláudia P.' },
+        ],
+      },
+      { type: 'products', title: 'NOVIDADES', filter: 'new', limit: 4 },
+      {
+        type: 'benefits',
+        items: [
+          { icon: 'Truck', title: 'Frete para todo o Brasil', text: 'Envio em até 48h' },
+          { icon: 'Leaf', title: '100% vegano', text: 'Sem testes em animais' },
+          { icon: 'RotateCcw', title: 'Troca fácil', text: '30 dias para trocar' },
+        ],
+      },
+      { type: 'newsletter', title: 'NEWSLETTER', subtitle: 'Histórias, lançamentos e cuidado — direto no seu e-mail.' },
+    ],
+  }),
+}
+
+/** volt — bold tech (Brasília): white canvas, near-black ink, vivid CTA, dark search-first header, split hero. */
+export const voltTemplate: StorefrontTemplate = {
+  id: 'volt',
+  inspiration: 'Nuvemshop Brasília',
+  announcement: 'CUPOM BEMVINDO10 — 10% DE DESCONTO NA PRIMEIRA COMPRA',
+  theme: {
+    name: 'volt',
+    colors: {
+      background: '0 0% 100%',
+      foreground: '0 0% 7%',
+      primary: '341 100% 45%',
+      primaryForeground: '0 0% 100%',
+      card: '0 0% 98%',
+      cardForeground: '0 0% 10%',
+      muted: '0 0% 94%',
+      mutedForeground: '0 0% 40%',
+      border: '0 0% 88%',
+      headerBackground: '0 0% 6%',
+      headerForeground: '0 0% 98%',
+      announcementBackground: '341 100% 45%',
+      announcementForeground: '0 0% 100%',
+    },
+    font: { heading: 'Chakra Petch', body: 'Rubik' },
+    radius: 'soft',
+    header: { variant: 'search', uppercaseNav: true },
+    productCard: { style: 'card', imageAspect: 'square' },
+  },
+  home: (storeName, images) => ({
+    sections: [
+      {
+        type: 'hero',
+        variant: 'split',
+        slides: [
+          { title: 'Tecnologia', subtitle: 'O melhor do hardware e dos acessórios', hue: 250, image: images?.hero?.[0] },
+          { title: 'Ofertas', subtitle: `Descontos semanais ${storeName}`, hue: 341, href: '/catalog', image: images?.hero?.[1] },
+        ],
+      },
+      {
+        type: 'benefits',
+        items: [
+          { icon: 'CreditCard', title: '3x sem juros', text: 'Em todo o site' },
+          { icon: 'Truck', title: 'Envio em 24h', text: 'Para todo o Brasil' },
+          { icon: 'ShieldCheck', title: 'Compra segura', text: 'Seus dados protegidos' },
+        ],
+      },
+      { type: 'products', title: 'NOVIDADES', filter: 'new', limit: 4 },
+      { type: 'banner', title: 'DESCONTOS SEMANAIS', eyebrow: 'toda sexta', subtitle: 'Ofertas novas, estoque limitado', cta: 'Conferir', hue: 341, image: images?.banners?.[0] },
+      { type: 'products', title: 'PROMOÇÕES', filter: 'sale', limit: 4 },
+      { type: 'newsletter', title: 'Entre para o clube', subtitle: 'Cupons e lançamentos antes de todo mundo.' },
+    ],
+  }),
+}
+
+/** atelier — classic premium retail (Flex): white, near-black, gold accent, slider hero, trust badges. */
+export const atelierTemplate: StorefrontTemplate = {
+  id: 'atelier',
+  inspiration: 'Nuvemshop Flex',
+  theme: {
+    name: 'atelier',
+    colors: {
+      background: '0 0% 100%',
+      foreground: '0 0% 9%',
+      primary: '40 45% 48%',
+      primaryForeground: '0 0% 100%',
+      card: '0 0% 99%',
+      cardForeground: '0 0% 9%',
+      muted: '40 10% 95%',
+      mutedForeground: '0 0% 42%',
+      border: '0 0% 88%',
+      announcementBackground: '0 0% 9%',
+      announcementForeground: '0 0% 98%',
+    },
+    font: { heading: 'Outfit', body: 'Outfit' },
+    radius: 'none',
+    header: { variant: 'centered', uppercaseNav: true },
+    productCard: { style: 'card', imageAspect: 'square' },
+    uppercaseButtons: true,
+  },
+  announcement: 'PARCELE EM ATÉ 10X · 5% OFF NO PIX',
+  home: (storeName, images) => ({
+    sections: [
+      {
+        type: 'hero',
+        variant: 'slider',
+        height: 'medium',
+        slides: [
+          { title: 'Feito para quem valoriza detalhes', subtitle: `Coleção exclusiva ${storeName}`, cta: 'APROVEITE', hue: 40, image: images?.hero?.[0] },
+          { title: 'Clássicos que não saem de moda', subtitle: 'Peças autorais, produção limitada', cta: 'VER COLEÇÃO', hue: 210, image: images?.hero?.[1] },
+        ],
+      },
+      {
+        type: 'benefits',
+        items: [
+          { icon: 'CreditCard', title: 'Parcele em até 10x', text: 'Ou 5% off no PIX' },
+          { icon: 'Lock', title: 'Site 100% seguro', text: 'Seus dados protegidos' },
+          { icon: 'Award', title: 'Peças exclusivas', text: 'Produtos 100% autorais' },
+        ],
+      },
+      { type: 'categories', style: 'tiles' },
+      { type: 'products', title: 'Novidades', filter: 'new', limit: 4 },
+      { type: 'banner', title: 'Promoções', eyebrow: 'seleção especial', subtitle: 'Selecionados com até 25% off', cta: 'Ver ofertas', hue: 40, image: images?.banners?.[0] },
+      { type: 'products', title: 'Promoções', filter: 'sale', limit: 4 },
+      {
+        type: 'testimonials',
+        title: 'O que dizem sobre nós',
+        items: [
+          { quote: 'Acabamento perfeito, superou a expectativa.', author: 'Mariana C.' },
+          { quote: 'Atendimento impecável do pedido à entrega.', author: 'Jorge L.' },
+          { quote: 'Virou minha loja favorita para presentes.', author: 'Paula R.' },
+        ],
+      },
+      { type: 'newsletter' },
+    ],
+  }),
+}
+
+export const storefrontTemplates = {
+  mare: mareTemplate,
+  sertao: sertaoTemplate,
+  volt: voltTemplate,
+  atelier: atelierTemplate,
+} as const
+
+export type StorefrontTemplateId = keyof typeof storefrontTemplates

package/src/product-options.ts

@@ -0,0 +1,63 @@
+import type { Product } from '@fayz-ai/shop/types'
+
+export interface ProductOptionGroup {
+  id: string
+  label: string
+  values: string[]
+}
+
+export type ProductOptionSelection = Record<string, string>
+
+function cleanValues(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return Array.from(new Set(value.filter((item): item is string => typeof item === 'string' && item.trim().length > 0)))
+}
+
+function cleanOptionGroup(value: unknown): ProductOptionGroup | null {
+  if (!value || typeof value !== 'object') return null
+  const record = value as Record<string, unknown>
+  const id = typeof record.id === 'string' ? record.id : typeof record.name === 'string' ? record.name : null
+  const label = typeof record.label === 'string' ? record.label : typeof record.name === 'string' ? record.name : id
+  const values = cleanValues(record.values)
+  if (!id || !label || values.length === 0) return null
+  return { id, label, values }
+}
+
+export function getProductOptionGroups(product: Product): ProductOptionGroup[] {
+  const options = product.metadata.options
+  const explicit = Array.isArray(options)
+    ? options.map(cleanOptionGroup).filter((group): group is ProductOptionGroup => Boolean(group))
+    : []
+
+  if (explicit.length > 0) return explicit
+
+  const groups: ProductOptionGroup[] = []
+  const sizes = cleanValues(product.metadata.sizes)
+  const colors = cleanValues(product.metadata.colors)
+
+  if (sizes.length > 0) groups.push({ id: 'Tamanho', label: 'Tamanho', values: sizes })
+  if (colors.length > 0) groups.push({ id: 'Cor', label: 'Cor', values: colors })
+
+  return groups
+}
+
+export function normalizeProductOptionSelection(selection?: ProductOptionSelection | null): ProductOptionSelection {
+  if (!selection) return {}
+  return Object.fromEntries(
+    Object.entries(selection)
+      .filter((entry): entry is [string, string] => entry[0].trim().length > 0 && entry[1].trim().length > 0)
+      .sort(([a], [b]) => a.localeCompare(b)),
+  )
+}
+
+export function formatProductOptionSelection(selection?: ProductOptionSelection | null): string {
+  return Object.entries(normalizeProductOptionSelection(selection))
+    .map(([label, value]) => `${label}: ${value}`)
+    .join(' · ')
+}
+
+export function productOptionSelectionKey(selection?: ProductOptionSelection | null): string {
+  const normalized = normalizeProductOptionSelection(selection)
+  const entries = Object.entries(normalized)
+  return entries.length > 0 ? JSON.stringify(entries) : ''
+}

package/src/router.ts

@@ -0,0 +1,49 @@
+import React, { useEffect, useState } from 'react'
+import { hashRouterAdapter } from '@fayz-ai/core'
+
+// Minimal hash router for the storefront. Deliberately not react-router:
+// an SDK package shipping a router dependency creates singleton hazards
+// under source-alias dev setups, and six routes don't justify one.
+
+const adapter = hashRouterAdapter()
+
+export function navigateTo(to: string): void {
+  adapter.navigate(to)
+}
+
+export function useHashPath(): string {
+  const [path, setPath] = useState(() => adapter.getCurrentPath() || '/')
+  useEffect(() => {
+    const unsub = adapter.onPathChange((p) => {
+      setPath(p || '/')
+      window.scrollTo(0, 0)
+    })
+    return unsub
+  }, [])
+  return path
+}
+
+/** Match '/product/:slug' against '/product/leather-backpack' → { slug: 'leather-backpack' } */
+export function matchPath(pattern: string, path: string): Record<string, string> | null {
+  const cleanPath = (path.split('?')[0] ?? '').replace(/\/+$/, '') || '/'
+  const patternParts = pattern.split('/').filter(Boolean)
+  const pathParts = cleanPath.split('/').filter(Boolean)
+  if (patternParts.length !== pathParts.length) return null
+  const params: Record<string, string> = {}
+  for (let i = 0; i < patternParts.length; i++) {
+    const pat = patternParts[i]!
+    const part = pathParts[i]!
+    if (pat.startsWith(':')) params[pat.slice(1)] = decodeURIComponent(part)
+    else if (pat !== part) return null
+  }
+  return params
+}
+
+export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  to: string
+}
+
+/** Real anchor (#/path) — middle-click/cmd-click friendly, Playwright friendly. */
+export function Link({ to, children, ...rest }: LinkProps) {
+  return React.createElement('a', { href: `#${to}`, ...rest }, children)
+}

package/src/scaffold.tsx

@@ -0,0 +1,109 @@
+import React from 'react'
+import { registerScaffold, defineApp } from '@fayz-ai/core'
+import type { AppManifest, BackendProvider } from '@fayz-ai/core'
+import { StorefrontConfigProvider, resolveConfig } from './config'
+import type { StorefrontConfig } from './config'
+import type { StorefrontTheme } from './theme'
+import type { HomeConfig, NavLink, FooterConfig } from './sections'
+import { initStorefrontRuntime, StorefrontShell } from './createStorefrontApp'
+import './blocks' // ensure section blocks are registered
+
+type StorefrontBackendProvider = NonNullable<StorefrontConfig['backend']>['provider']
+const runtimeConfigRegistry = new Map<string, StorefrontConfig>()
+
+// ---------------------------------------------------------------------------
+// Storefront scaffold — renders a store from a pure-data AppManifest. The
+// storefront surface keeps its declarative config under surface.options, so the
+// mapping is loss-free for the serializable fields (the code escape hatches —
+// custom provider/adapter/logo — arrive via the registries instead).
+// ---------------------------------------------------------------------------
+
+function slug(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'app'
+}
+
+/** StorefrontConfig → AppManifest (the sugar-to-data direction). */
+export function defineStorefront(config: StorefrontConfig): AppManifest {
+  const id = slug(config.name)
+  runtimeConfigRegistry.set(id, config)
+  const backendProvider = (config.backend?.provider ?? (config.provider ? 'custom' : 'mock')) as BackendProvider
+
+  return defineApp({
+    id,
+    name: config.name,
+    backend: {
+      provider: backendProvider,
+      url: config.backend?.url,
+    },
+    locale: {
+      default: config.locale ?? 'pt-BR',
+      supported: [config.locale ?? 'pt-BR'],
+      currency: config.currency ?? 'BRL',
+    },
+    theme: config.theme as Record<string, unknown> | undefined,
+    surfaces: {
+      storefront: {
+        scaffold: 'storefront',
+        options: {
+          announcement: config.announcement,
+          home: config.home,
+          nav: config.nav,
+          footer: config.footer,
+          shipping: config.shipping,
+          features: config.features,
+          catalog: config.catalog,
+        },
+      },
+    },
+  })
+}
+
+/** AppManifest → StorefrontConfig (the data-to-render direction). */
+function manifestToStorefrontConfig(manifest: AppManifest, surfaceName: string): StorefrontConfig {
+  const runtimeConfig = runtimeConfigRegistry.get(manifest.id)
+  const surface = manifest.surfaces[surfaceName]
+  const o = (surface?.options ?? {}) as Record<string, unknown>
+  return {
+    ...runtimeConfig,
+    name: manifest.name,
+    currency: (manifest.locale as { currency?: string } | undefined)?.currency,
+    locale: (manifest.locale as { default?: string } | undefined)?.default,
+    theme: manifest.theme as StorefrontTheme | undefined,
+    announcement: o.announcement as string | undefined,
+    home: o.home as HomeConfig | undefined,
+    nav: o.nav as NavLink[] | undefined,
+    footer: o.footer as FooterConfig | undefined,
+    shipping: o.shipping as StorefrontConfig['shipping'],
+    features: o.features as StorefrontConfig['features'],
+    catalog: o.catalog as StorefrontConfig['catalog'],
+    backend: {
+      provider: manifest.backend?.provider as StorefrontBackendProvider,
+      url: manifest.backend?.url,
+    },
+    slots: runtimeConfig?.slots,
+    routes: runtimeConfig?.routes,
+    provider: runtimeConfig?.provider,
+    auth: runtimeConfig?.auth,
+    logo: runtimeConfig?.logo,
+  }
+}
+
+export function StorefrontScaffold({ manifest, surface }: { manifest: AppManifest; surface: string }) {
+  const config = React.useMemo(() => manifestToStorefrontConfig(manifest, surface), [manifest, surface])
+  const resolved = React.useMemo(() => resolveConfig(config), [config])
+  const inited = React.useRef(false)
+  if (!inited.current) {
+    initStorefrontRuntime(config)
+    inited.current = true
+  }
+  return (
+    <StorefrontConfigProvider value={resolved}>
+      <StorefrontShell />
+    </StorefrontConfigProvider>
+  )
+}
+StorefrontScaffold.displayName = 'StorefrontScaffold'
+
+// Self-register so `renderApp(manifest)` can resolve the 'storefront' scaffold
+// whenever this package is imported.
+registerScaffold('storefront', StorefrontScaffold, { source: 'sdk', label: 'Storefront' })