@decocms/start 0.19.0

package/.cursor/skills/deco-apps-vtex-porting/structure-map.md

@@ -0,0 +1,234 @@
+# Structure Map: deco-cx/apps → apps-start
+
+File-by-file mapping showing what exists, what's missing, and what needs improvement.
+
+## Legend
+
+- ✅ Ported and verified
+- ⚠️ Ported but needs review/improvements
+- ❌ Missing — needs to be created
+- 🔀 Consolidated into another file
+- ➖ Not needed in TanStack (platform-specific)
+
+---
+
+## Root Files
+
+| Original (apps/vtex/) | apps-start (vtex/) | Status |
+|----------------------|-------------------|--------|
+| `mod.ts` | `index.ts` + `client.ts` (configureVtex) | ⚠️ mod.ts creates 7 typed clients; apps-start has vtexFetch only |
+| `manifest.gen.ts` | `package.json` exports | ✅ Different approach, OK |
+| `runtime.ts` | Not needed | ➖ No invoke proxy in TanStack |
+| `middleware.ts` | `middleware.ts` | ⚠️ Simplified version, missing full segment bag |
+| `README.md` | `README.md` | ✅ |
+
+## Actions
+
+### Cart (Original: 16 files → apps-start: 1 file `checkout.ts`)
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `actions/cart/addItems.ts` | `actions/checkout.ts` → `addItems()` | ✅ |
+| `actions/cart/updateItems.ts` | `actions/checkout.ts` → `updateItems()` | ✅ |
+| `actions/cart/removeItems.ts` | `actions/checkout.ts` → `removeAllItems()` | ✅ |
+| `actions/cart/updateCoupons.ts` | `actions/checkout.ts` → `updateCoupons()` | ✅ |
+| `actions/cart/updateAttachment.ts` | `actions/checkout.ts` → `sendAttachment()` | ✅ |
+| `actions/cart/updateItemAttachment.ts` | `actions/checkout.ts` → `updateItemAttachment()` | ✅ |
+| `actions/cart/removeItemAttachment.ts` | `actions/checkout.ts` → `removeItemAttachment()` | ✅ |
+| `actions/cart/updateItemPrice.ts` | `actions/checkout.ts` → `changePrice()` | ✅ |
+| `actions/cart/updateProfile.ts` | `actions/checkout.ts` → `ignoreProfileData()` | ✅ |
+| `actions/cart/updateUser.ts` | `actions/checkout.ts` → `removeAllPersonalData()` | ✅ |
+| `actions/cart/addOfferings.ts` | `actions/checkout.ts` → `addOfferings()` | ⚠️ Verify logic matches |
+| `actions/cart/removeOffering.ts` | `actions/checkout.ts` → `removeOffering()` | ⚠️ Verify logic matches |
+| `actions/cart/getInstallment.ts` | `actions/checkout.ts` → `getInstallments()` | ⚠️ Verify logic matches |
+| `actions/cart/updateGifts.ts` | `actions/checkout.ts` → `updateGifts()` | ⚠️ Verify logic matches |
+| `actions/cart/clearOrderformMessages.ts` | `actions/checkout.ts` → `clearMessages()` | ✅ |
+| `actions/cart/simulation.ts` | `actions/checkout.ts` → `simulation()` | ⚠️ Verify |
+
+### Authentication (Original: 8 files → apps-start: 1 file `auth.ts`)
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `actions/authentication/startAuthentication.ts` | `actions/auth.ts` → `startAuthentication()` | ✅ |
+| `actions/authentication/classicSignIn.ts` | `actions/auth.ts` → `classicSignIn()` | ✅ |
+| `actions/authentication/accessKeySignIn.ts` | `actions/auth.ts` → `accessKeySignIn()` | ✅ |
+| `actions/authentication/sendEmailVerification.ts` | `actions/auth.ts` → `sendEmailVerification()` | ✅ |
+| `actions/authentication/recoveryPassword.ts` | `actions/auth.ts` → `recoveryPassword()` | ✅ |
+| `actions/authentication/resetPassword.ts` | `actions/auth.ts` → `resetPassword()` | ✅ |
+| `actions/authentication/refreshToken.ts` | `actions/auth.ts` → `refreshToken()` | ⚠️ Verify |
+| `actions/authentication/logout.ts` | `actions/auth.ts` → `logout()` | ✅ |
+
+### Other Actions (Original: 13 files → apps-start: 9 files)
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `actions/session/createSession.ts` | `actions/session.ts` | ✅ |
+| `actions/session/editSession.ts` | `actions/session.ts` | ✅ |
+| `actions/session/deleteSession.ts` | `actions/session.ts` | ✅ |
+| `actions/address/create.ts` | `actions/address.ts` | ✅ |
+| `actions/address/update.ts` | `actions/address.ts` | ✅ |
+| `actions/address/delete.ts` | `actions/address.ts` | ✅ |
+| `actions/newsletter/subscribe.ts` | `actions/newsletter.ts` | ✅ |
+| `actions/newsletter/updateNewsletterOptIn.ts` | `actions/newsletter.ts` | ✅ |
+| `actions/wishlist/addItem.ts` | `actions/wishlist.ts` | ✅ |
+| `actions/wishlist/removeItem.ts` | `actions/wishlist.ts` | ✅ |
+| `actions/orders/cancel.ts` | `actions/orders.ts` | ✅ |
+| `actions/profile/updateProfile.ts` | `actions/profile.ts` | ✅ |
+| `actions/review/submit.ts` | `actions/misc.ts` → `submitReview()` | ✅ |
+| `actions/payment/deletePaymentToken.ts` | `actions/misc.ts` → `deletePaymentToken()` | ✅ |
+| `actions/notifyme.ts` | `actions/misc.ts` → `notifyMe()` | ✅ |
+| `actions/trigger.ts` | `actions/trigger.ts` | ✅ |
+| `actions/masterdata/createDocument.ts` | `actions/masterData.ts` | ⚠️ Verify completeness |
+| `actions/masterdata/updateDocument.ts` | `actions/masterData.ts` | ⚠️ Verify completeness |
+| `actions/analytics/sendEvent.ts` | `actions/misc.ts` → `sendEvent()` | ✅ |
+
+## Loaders
+
+### Intelligent Search (Original: 6 files → apps-start: `search.ts` + inline-loaders)
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `loaders/intelligentSearch/productDetailsPage.ts` | `inline-loaders/productDetailsPage.ts` | ✅ |
+| `loaders/intelligentSearch/productListingPage.ts` | `inline-loaders/productListingPage.ts` | ✅ |
+| `loaders/intelligentSearch/productList.ts` | `inline-loaders/productList.ts` | ✅ |
+| `loaders/intelligentSearch/suggestions.ts` | `inline-loaders/suggestions.ts` | ✅ |
+| `loaders/intelligentSearch/topsearches.ts` | `loaders/search.ts` → `getTopSearches()` | ✅ |
+| `loaders/intelligentSearch/productSearchValidator.ts` | ❌ Missing | ❌ |
+
+### Legacy Catalog (Original: 7 files → apps-start: `legacy.ts` + `catalog.ts`)
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `loaders/legacy/productDetailsPage.ts` | `loaders/legacy.ts` | ✅ |
+| `loaders/legacy/productListingPage.ts` | `loaders/legacy.ts` | ✅ |
+| `loaders/legacy/productList.ts` | `loaders/legacy.ts` | ✅ |
+| `loaders/legacy/suggestions.ts` | `loaders/legacy.ts` → `legacySuggestions()` | ✅ |
+| `loaders/legacy/relatedProductsLoader.ts` | `inline-loaders/relatedProducts.ts` + `loaders/catalog.ts` | ✅ |
+| `loaders/legacy/brands.ts` | `loaders/brands.ts` | ✅ |
+| `loaders/legacy/pageType.ts` | `loaders/pageType.ts` | ✅ |
+
+### Other Loaders
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `loaders/cart.ts` | `loaders/cart.ts` | ✅ |
+| `loaders/user.ts` | `loaders/user.ts` | ✅ |
+| `loaders/wishlist.ts` | `loaders/wishlist.ts` | ✅ |
+| `loaders/navbar.ts` | `loaders/navbar.ts` | ✅ |
+| `loaders/proxy.ts` | `utils/proxy.ts` | ⚠️ Different location |
+| `loaders/config.ts` | `client.ts` (getVtexConfig) | 🔀 |
+| `loaders/categories/tree.ts` | `loaders/catalog.ts` → `getCategoryTree()` | ✅ |
+| `loaders/collections/list.ts` | `loaders/collections.ts` | ✅ |
+| `loaders/logistics/getSalesChannelById.ts` | `loaders/logistics.ts` | ⚠️ Verify |
+| `loaders/logistics/listPickupPoints.ts` | `loaders/logistics.ts` | ⚠️ Verify |
+| `loaders/logistics/listPickupPointsByLocation.ts` | `loaders/logistics.ts` | ⚠️ Verify |
+| `loaders/logistics/listSalesChannelById.ts` | `loaders/logistics.ts` | ⚠️ Verify |
+| `loaders/logistics/listStockByStore.ts` | `loaders/logistics.ts` | ⚠️ Verify |
+| `loaders/orders/getById.ts` | `loaders/orders.ts` | ⚠️ Verify |
+| `loaders/orders/list.ts` | `loaders/orders.ts` | ⚠️ Verify |
+| `loaders/orders/orderplaced.ts` | `loaders/orders.ts` | ⚠️ Verify |
+| `loaders/payment/paymentSystems.ts` | `loaders/payment.ts` | ⚠️ Verify |
+| `loaders/payment/userPayments.ts` | `loaders/payment.ts` | ⚠️ Verify |
+| `loaders/profile/getCurrentProfile.ts` | `loaders/profile.ts` | ⚠️ Verify |
+| `loaders/profile/getProfileByEmail.ts` | `loaders/profile.ts` | ⚠️ Verify |
+| `loaders/session/getSession.ts` | `loaders/session.ts` | ⚠️ Verify |
+| `loaders/session/getUserSessions.ts` | `loaders/session.ts` | ⚠️ Verify |
+| `loaders/address/getAddressByPostalCode.ts` | `loaders/address.ts` | ⚠️ Verify |
+| `loaders/address/getUserAddresses.ts` | `loaders/address.ts` | ⚠️ Verify |
+| `loaders/masterdata/searchDocuments.ts` | ❌ Missing | ❌ |
+| `loaders/options/productIdByTerm.ts` | ❌ Missing | ❌ |
+| `loaders/promotion/getPromotionById.ts` | `loaders/promotion.ts` | ⚠️ Verify |
+| `loaders/workflow/product.ts` | `loaders/workflow.ts` | ✅ |
+| `loaders/workflow/products.ts` | `loaders/workflow.ts` | ✅ |
+| `loaders/paths/PDPDefaultPath.ts` | ❌ Missing (storefront handles routing) | ➖ |
+| `loaders/paths/PLPDefaultPath.ts` | ❌ Missing (storefront handles routing) | ➖ |
+| `loaders/product/extend.ts` | ❌ Missing | ❌ |
+| `loaders/product/extensions/*` (4 files) | ❌ Missing (extensions are framework-specific) | ➖ |
+| `loaders/product/wishlist.ts` | ❌ Missing | ❌ |
+
+## Utils
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `utils/transform.ts` | `utils/transform.ts` | ✅ Ported and verified |
+| `utils/types.ts` | `utils/types.ts` | ✅ |
+| `utils/client.ts` | `client.ts` (vtexFetch, etc.) | ⚠️ Different approach — no typed Proxy |
+| `utils/fetchVTEX.ts` | Part of `client.ts` | 🔀 URL sanitization may be missing |
+| `utils/cookies.ts` | `utils/cookies.ts` | ✅ |
+| `utils/vtexId.ts` | `utils/vtexId.ts` | ✅ |
+| `utils/orderForm.ts` | Part of `loaders/cart.ts` + `hooks/useCart.ts` | ⚠️ Split across files |
+| `utils/segment.ts` | `utils/segment.ts` | ⚠️ Simplified, missing full serialization |
+| `utils/intelligentSearch.ts` | `utils/intelligentSearch.ts` | ✅ |
+| `utils/legacy.ts` | `utils/legacy.ts` | ⚠️ Verify completeness |
+| `utils/similars.ts` | `utils/similars.ts` | ✅ |
+| `utils/batch.ts` | `utils/batch.ts` | ⚠️ Verify |
+| `utils/cacheBySegment.ts` | ❌ Missing (caching handled differently) | ➖ |
+| `utils/resourceRange.ts` | ❌ Missing | ❌ |
+| `utils/slugify.ts` | `utils/slugify.ts` | ✅ |
+| `utils/pickAndOmit.ts` | `utils/pickAndOmit.ts` | ✅ |
+| `utils/extensions/simulation.ts` | `utils/enrichment.ts` | 🔀 |
+| `utils/login/getLoginCookies.ts` | Part of `actions/auth.ts` | 🔀 |
+| `utils/login/setLoginCookies.ts` | Part of `actions/auth.ts` | 🔀 |
+| `utils/openapi/*.gen.ts` (12 files) | Not needed (no OpenAPI codegen) | ➖ |
+
+## Hooks
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `hooks/context.ts` | Not needed (react-query manages state) | ➖ |
+| `hooks/useCart.ts` | `hooks/useCart.ts` | ✅ React Query version |
+| `hooks/useUser.ts` | `hooks/useUser.ts` | ✅ |
+| `hooks/useWishlist.ts` | `hooks/useWishlist.ts` | ✅ |
+| `hooks/useAutocomplete.ts` | ❌ Missing | ❌ Should add |
+
+## Other
+
+| Original | apps-start | Status |
+|----------|-----------|--------|
+| `handlers/sitemap.ts` | `utils/sitemap.ts` | ⚠️ Different location |
+| `sections/Analytics/Vtex.tsx` | ❌ Missing (storefront handles analytics) | ➖ |
+| `components/VTEXPortalDataLayerCompatibility.tsx` | ❌ Not needed | ➖ |
+| `workflows/events.ts` | Not applicable | ➖ |
+| `workflows/product/index.ts` | Not applicable | ➖ |
+| `preview/Preview.tsx` | Not applicable | ➖ |
+
+## Commerce Module
+
+| Original (apps/commerce/) | apps-start (commerce/) | Status |
+|--------------------------|----------------------|--------|
+| `types.ts` (786 lines) | `types/commerce.ts` | ✅ Same types |
+| `mod.ts` | Not applicable | ➖ |
+| `utils/canonical.ts` | `utils/canonical.ts` | ✅ |
+| `utils/constants.ts` | `utils/constants.ts` | ✅ |
+| `utils/filters.ts` | `utils/filters.ts` | ✅ |
+| `utils/productToAnalyticsItem.ts` | `utils/productToAnalyticsItem.ts` | ✅ |
+| `utils/stateByZip.ts` | `utils/stateByZip.ts` | ✅ |
+| `loaders/extensions/*` | ❌ Missing (framework-specific) | ➖ |
+| `sections/Seo/*` | ❌ Not needed (storefront handles SEO) | ➖ |
+| **SDK (NEW in apps-start)** | | |
+| N/A (was in site sdk/) | `sdk/useOffer.ts` | ✅ |
+| N/A | `sdk/useVariantPossibilities.ts` | ✅ |
+| N/A | `sdk/formatPrice.ts` | ✅ |
+| N/A | `sdk/url.ts` (relative) | ✅ |
+| N/A | `sdk/analytics.ts` | ✅ |
+| N/A | `components/Image.tsx` | ✅ |
+| N/A | `components/JsonLd.tsx` | ✅ |
+
+## Shared Utils
+
+| Original (apps/utils/) | apps-start | Status |
+|------------------------|-----------|--------|
+| `http.ts` (createHttpClient) | Not needed (vtexFetch replaces it) | ➖ |
+| `graphql.ts` (createGraphqlClient) | `client.ts` → vtexIOGraphQL | 🔀 |
+| `fetch.ts` (fetchSafe, retry) | `client.ts` → vtexFetch (no retry) | ⚠️ Missing retry logic |
+| `cookie.ts` (proxySetCookie) | `client.ts` → vtexFetchWithCookies | 🔀 Different approach |
+| `normalize.ts` (removeDirtyCookies) | ❌ Missing | ⚠️ Should add URL sanitization |
+
+## Priority Missing Items
+
+1. **`utils/fetchVTEX.ts` URL sanitization** — original sanitizes UTM params, `ft` param. apps-start doesn't
+2. **Retry logic** — original uses cockatiel ExponentialBackoff. apps-start has no retry
+3. **`hooks/useAutocomplete.ts`** — client-side autocomplete hook
+4. **`loaders/masterdata/searchDocuments.ts`** — MasterData search
+5. **`loaders/product/extend.ts`** — Product enrichment loader
+6. **Segment cookie serialization** — original has stable serialization for cache hits

package/.cursor/skills/deco-apps-vtex-porting/transform-mapping.md

@@ -0,0 +1,99 @@
+# transform.ts — VTEX → schema.org Mapping Reference
+
+Complete field-by-field mapping from VTEX API types to schema.org commerce types.
+
+## toProduct() — VTEX → schema.org Product
+
+| VTEX Field | schema.org Field | Notes |
+|-----------|-----------------|-------|
+| `sku.itemId` | `productID`, `sku` | SKU identifier |
+| `sku.name` | `name` | SKU name |
+| `sku.complementName` | `alternateName` | |
+| `product.description` | `description` | |
+| `product.brand` | `brand.name` | Wrapped in Brand object |
+| `product.brandId` | `brand.@id` | |
+| `product.brandImageUrl` | `brand.logo` | |
+| `sku.ean` | `gtin` | |
+| `product.releaseDate` | `releaseDate` | |
+| `product.categories[0]` | `category` | Split by `/`, joined with `>` |
+| `product.productId` | `inProductGroupWithID` | |
+| `product.productReference` | `isVariantOf.model` | |
+
+## buildOffer() — VTEX Seller → schema.org Offer
+
+| VTEX Field | schema.org Field | Notes |
+|-----------|-----------------|-------|
+| `sellerId` | `seller` | **MUST be ID, not name** |
+| `sellerName` | `sellerName` | Display name |
+| `sellerDefault` | `identifier: "default"` | Only when true |
+| `commertialOffer.spotPrice ?? Price` | `price` | Spot price preferred |
+| `commertialOffer.PriceValidUntil` | `priceValidUntil` | |
+| `commertialOffer.AvailableQuantity` | `inventoryLevel.value` | |
+| `commertialOffer.AvailableQuantity > 0` | `availability` | InStock / OutOfStock |
+| `commertialOffer.GiftSkuIds` | `giftSkuIds` | |
+| `commertialOffer.teasers` | `teasers` | |
+
+## priceSpecification — Prices and Installments
+
+| VTEX Field | priceType | Notes |
+|-----------|-----------|-------|
+| `ListPrice` | `https://schema.org/ListPrice` | Original price |
+| `Price` | `https://schema.org/SalePrice` | Sale price |
+| `PriceWithoutDiscount` | `https://schema.org/SRP` | Suggested retail |
+| `Installments[]` | `https://schema.org/Installment` | Each installment option |
+
+### Installment Mapping
+
+| VTEX Installment | UnitPriceSpecification |
+|-----------------|----------------------|
+| `PaymentSystemName` | `name` |
+| `Name` | `description` |
+| `NumberOfInstallments` | `billingDuration` |
+| `Value` | `billingIncrement` |
+| `TotalValuePlusInterestRate` | `price` |
+
+## Images
+
+| VTEX Field | schema.org ImageObject |
+|-----------|----------------------|
+| `imageUrl` | `url` |
+| `imageText` or `imageLabel` | `alternateName` |
+| `imageLabel` | `name` |
+| (fixed) | `encodingFormat: "image"` |
+
+## isVariantOf — ProductGroup
+
+| VTEX Field | schema.org ProductGroup |
+|-----------|----------------------|
+| `product.productId` | `productGroupID` |
+| `product.items` → each via `toProduct(level=1)` | `hasVariant` |
+| `/{linkText}/p` | `url` |
+| `product.productName` | `name` |
+| `product.productReference` | `model` |
+
+`level` prevents infinite recursion: `level=0` includes `isVariantOf`, `level=1` sets it to `undefined`.
+
+## Breadcrumbs
+
+| Source | ListItem |
+|--------|----------|
+| `categories[0]` split by `/` | Each segment → `name`, `position`, `item` (URL) |
+| `productName` | Last item → URL = `/{linkText}/p` |
+
+## isLegacyProduct Detection
+
+```typescript
+product.origin !== "intelligent-search" → Legacy (uses toOfferLegacy)
+product.origin === "intelligent-search" → IS (uses toOffer)
+```
+
+Both `toOffer` and `toOfferLegacy` call `buildOffer()` internally, ensuring `seller: sellerId`.
+
+## additionalProperty Sources
+
+- SKU variations (SPECIFICATION)
+- Product categories (CATEGORY)
+- Product clusters (CLUSTER)
+- Reference IDs (ReferenceID)
+- Estimated date arrival
+- Modal type

package/.cursor/skills/deco-apps-vtex-porting/website-porting.md

@@ -0,0 +1,194 @@
+# Website Module Porting
+
+How the `website/` app from `deco-cx/apps` maps to `@decocms/start` and the storefront.
+
+## Architecture Split
+
+The original `website/` app is a monolith handling routing, SEO, analytics, images, themes, A/B testing, matchers, and more. In TanStack, these responsibilities are split across three layers:
+
+```
+Original (apps/website/)              TanStack Split
+════════════════════════              ══════════════
+handlers/router.ts              →    TanStack Router (file-based routing)
+handlers/proxy.ts               →    @decocms/start/sdk/workerEntry (Cloudflare Worker)
+handlers/redirect.ts            →    @decocms/start/sdk/redirects
+handlers/sitemap.ts             →    @decocms/start/sdk/sitemap
+handlers/fresh.ts               →    Not needed (TanStack replaces Fresh)
+
+loaders/pages.ts                →    @decocms/start/cms/loader (loadBlocks)
+loaders/fonts/*                 →    Storefront CSS (Tailwind/Vite handles fonts)
+loaders/image/*                 →    Storefront component (Image.tsx)
+loaders/redirects.ts            →    @decocms/start/sdk/redirects
+loaders/secret.ts               →    process.env / Cloudflare secrets
+loaders/asset.ts                →    Vite handles static assets
+loaders/environment.ts          →    process.env
+
+components/Analytics.tsx         →    Storefront: ~/components/Analytics.tsx
+components/Image.tsx             →    Storefront: ~/components/ui/Image.tsx
+components/Video.tsx             →    Storefront: ~/components/ui/Video.tsx
+components/Theme.tsx             →    Storefront: ~/components/ui/Theme.tsx
+components/_seo/*               →    Storefront: ~/components/Seo.tsx
+components/Events.tsx            →    @decocms/apps/commerce/sdk/analytics
+components/Clickhouse.tsx        →    Not needed (different observability)
+
+sections/Analytics/*             →    Storefront sections
+sections/Rendering/*             →    @decocms/start/hooks/LazySection
+sections/Seo/*                   →    Storefront sections
+
+flags/audience.ts                →    @decocms/start/matchers/builtins
+matchers/*                       →    @decocms/start/matchers/*
+mod.ts                           →    @decocms/start (the framework package itself)
+types.ts                         →    @decocms/start/types
+```
+
+## What @decocms/start Provides
+
+The `deco-start` package (`@decocms/start`) IS the TanStack equivalent of `website/`:
+
+| Capability | website/ | @decocms/start |
+|-----------|----------|----------------|
+| CMS page resolution | `handlers/router.ts` | `cms/loader.ts` (loadBlocks) |
+| Section rendering | Fresh island hydration | `hooks/DecoPageRenderer.tsx` |
+| Lazy loading | Fresh partials | `hooks/LazySection.tsx` |
+| Live editing | Fresh middleware | `hooks/LiveControls.tsx` |
+| Admin protocol | N/A (Deco runtime) | `admin/` (meta, decofile, invoke, render) |
+| Schema generation | `@deco/deco/scripts/bundle` | `scripts/generate-schema.ts` |
+| Worker entry | N/A | `sdk/workerEntry.ts` (createDecoWorkerEntry) |
+| Edge caching | N/A | `sdk/cacheHeaders.ts`, `sdk/mergeCacheControl.ts` |
+| Redirects | `handlers/redirect.ts` | `sdk/redirects.ts` |
+| Sitemap | `handlers/sitemap.ts` | `sdk/sitemap.ts` |
+| Matchers | `matchers/*` | `matchers/builtins.ts`, `matchers/posthog.ts` |
+| Script injection | `@deco/deco/hooks` (useScript) | `sdk/useScript.ts` |
+| Signals | `@preact/signals` | `sdk/signal.ts` (TanStack Store wrapper) |
+| CSS class helper | N/A | `sdk/clx.ts` |
+| Cookie utilities | `../utils/cookie.ts` | `sdk/cookie.ts` |
+| Analytics | `components/Events.tsx` | `sdk/analytics.ts` |
+| ID generation | N/A | `sdk/useId.ts` |
+| CSP | N/A | `sdk/csp.ts` |
+| Server timings | N/A | `sdk/serverTimings.ts` |
+| Observability | N/A | `middleware/observability.ts` |
+
+## What the Storefront Provides
+
+Each site creates these locally (NOT in a shared package):
+
+### Routing
+```
+src/routes/
+├── __root.tsx        # Root layout (html, head, body)
+├── index.tsx         # Homepage
+├── $.tsx             # Catch-all (CMS pages, PDP, PLP)
+└── deco/             # Admin API routes
+    ├── meta.ts
+    ├── decofile.ts
+    └── render.ts
+```
+
+### Components (from website/)
+```
+src/components/
+├── ui/
+│   ├── Image.tsx     # From website/components/Image.tsx
+│   ├── Video.tsx     # From website/components/Video.tsx
+│   └── Theme.tsx     # From website/components/Theme.tsx (usually a stub)
+├── Seo.tsx           # From website/components/_seo/*
+└── Analytics.tsx     # From website/components/Analytics.tsx
+```
+
+### Setup (from website/mod.ts)
+```typescript
+// src/setup.ts — registers everything
+import { setMetaData, setInvokeLoaders, setRenderShell } from "@decocms/start/admin";
+import { setBlocks } from "@decocms/start/cms";
+import metaData from "./meta.gen.json";
+import blocks from "./.deco/blocks/index.ts";
+
+// Register CMS blocks
+setBlocks(blocks);
+
+// Register schema for admin
+setMetaData(metaData);
+
+// Register loaders for admin invoke
+setInvokeLoaders({
+  "vtex/loaders/productDetailsPage": (props) => vtexProductDetailsPage(props),
+  // ...
+});
+
+// Configure preview shell
+setRenderShell({
+  css: appCss,
+  fonts: ["https://fonts.googleapis.com/css2?family=..."],
+  theme: "light",
+  bodyClass: "bg-base-100 text-base-content",
+  lang: "pt-BR",
+});
+```
+
+## Proxy Handler → Worker Entry
+
+The original `handlers/proxy.ts` is a reverse proxy for VTEX checkout/API. In TanStack, this lives in the Cloudflare Worker entry:
+
+```typescript
+// src/worker-entry.ts
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+
+export default createDecoWorkerEntry(serverEntry, {
+  admin: { handleMeta, handleDecofileRead, handleRender, corsHeaders },
+  // VTEX proxy paths are configured here or in route handlers
+});
+```
+
+VTEX checkout proxy (`/checkout/*`, `/api/*`) can be handled:
+1. As TanStack route handlers (`src/routes/api/$.ts`)
+2. In the Worker entry before TanStack handles the request
+3. Via Cloudflare Workers routes in `wrangler.jsonc`
+
+## Matchers → Storefront + @decocms/start
+
+Original matchers (device, cookie, date, etc.) are used for audience targeting. In TanStack:
+
+```typescript
+// @decocms/start/matchers/builtins.ts provides:
+// - device detection
+// - cookie matching
+// - random percentage
+// etc.
+
+// Storefront can extend with custom matchers
+```
+
+## SEO
+
+Original: `sections/Seo/*` + `components/_seo/*` provide SEO meta tags via Deco sections.
+
+TanStack: Each route handles its own SEO via TanStack Router's `meta` or a local `<Seo>` component:
+
+```typescript
+// src/routes/$.tsx (catch-all)
+export const Route = createFileRoute("/$")({
+  component: CatchAllPage,
+  head: ({ loaderData }) => ({
+    meta: [
+      { title: loaderData?.seo?.title },
+      { name: "description", content: loaderData?.seo?.description },
+    ],
+  }),
+});
+```
+
+## Summary: What to Port Where
+
+| Original website/ file | Goes to | Layer |
+|------------------------|---------|-------|
+| `mod.ts` Props | `src/setup.ts` | Storefront |
+| `handlers/router.ts` | TanStack file routing | Storefront |
+| `handlers/proxy.ts` | Worker entry / route handlers | Storefront |
+| `handlers/sitemap.ts` | `@decocms/start/sdk/sitemap` | Framework |
+| `handlers/redirect.ts` | `@decocms/start/sdk/redirects` | Framework |
+| `loaders/pages.ts` | `@decocms/start/cms/loader` | Framework |
+| `matchers/*` | `@decocms/start/matchers/*` | Framework |
+| `components/Image.tsx` | `~/components/ui/Image.tsx` | Storefront |
+| `components/_seo/*` | `~/components/Seo.tsx` | Storefront |
+| `sections/*` | `~/sections/*` | Storefront |
+| `flags/*` | `@decocms/start/matchers/*` | Framework |