@decocms/start 0.19.0

package/.cursor/skills/deco-apps-architecture/vtex-deep-structure.md

@@ -0,0 +1,253 @@
+# VTEX App — Deep Structure Reference
+
+The VTEX app is the largest integration in deco-cx/apps (141 files). This document maps every subdirectory and key file.
+
+## `mod.ts` — App Factory
+
+Creates 7 typed HTTP/GraphQL clients:
+
+| Client | Base URL | Purpose |
+|--------|----------|---------|
+| `sp` | `https://sp.vtex.com` | Spark (analytics events) |
+| `my` | `https://{account}.myvtex.com` | My Account APIs |
+| `vcsDeprecated` | `{publicUrl}` | VTEXCommerceStable (checkout, catalog, auth) |
+| `io` | `{publicUrl}/api/io/_v/private/graphql/v1` | IO GraphQL (wishlist, reviews) |
+| `vcs` | `{publicUrl}` | VCS OpenAPI (typed) |
+| `api` | `https://api.vtex.com/{account}` | VTEX API |
+| `vpay` | `https://{account}.vtexpayments.com.br` | Payments |
+| `sub` | `https://{account}.vtexcommercestable.com.br` | Subscriptions |
+
+### Props
+```typescript
+interface Props {
+  account: string;          // VTEX account name
+  publicUrl: string;        // Public store URL (e.g., secure.mystore.com.br)
+  appKey?: Secret;          // For admin API operations
+  appToken?: Secret;
+  salesChannel?: string;    // Default: "1"
+  defaultSegment?: SegmentCulture;
+  setRefreshToken?: boolean;
+  usePortalSitemap?: boolean;
+  platform: "vtex";
+  advancedConfigs?: { doNotFetchVariantsForRelatedProducts?: boolean };
+  cachedSearchTerms?: { terms?: Suggestion; extraTerms?: string[] };
+}
+```
+
+## Actions (43 files, 11 subdirectories)
+
+### `actions/cart/` (16 files)
+| File | Endpoint | Method |
+|------|----------|--------|
+| `addItems.ts` | `/api/checkout/pub/orderForm/:id/items` | POST |
+| `updateItems.ts` | `/api/checkout/pub/orderForm/:id/items/update` | POST |
+| `removeItems.ts` | `/api/checkout/pub/orderForm/:id/items/removeAll` | POST |
+| `updateCoupons.ts` | `/api/checkout/pub/orderForm/:id/coupons` | POST |
+| `updateAttachment.ts` | `/api/checkout/pub/orderForm/:id/attachments/:att` | POST |
+| `updateItemAttachment.ts` | `/api/checkout/pub/orderForm/:id/items/:idx/attachments/:att` | POST |
+| `removeItemAttachment.ts` | `/api/checkout/pub/orderForm/:id/items/:idx/attachments/:att` | DELETE |
+| `updateItemPrice.ts` | `/api/checkout/pub/orderForm/:id/items/:idx/price` | PUT |
+| `updateProfile.ts` | `/api/checkout/pub/orderForm/:id/profile` | PATCH |
+| `updateUser.ts` | `/api/checkout/changeToAnonymousUser/:id` | GET |
+| `addOfferings.ts` | `/api/checkout/pub/orderForm/:id/items/:idx/offerings` | POST |
+| `removeOffering.ts` | `/api/checkout/pub/orderForm/:id/items/:idx/offerings/:off/remove` | POST |
+| `getInstallment.ts` | `/api/checkout/pub/orderForm/:id/installments` | GET |
+| `updateGifts.ts` | `/api/checkout/pub/orderForm/:id/selectable-gifts/:giftId` | POST |
+| `clearOrderformMessages.ts` | `/api/checkout/pub/orderForm/:id/messages/clear` | POST |
+| `simulation.ts` | `/api/checkout/pub/orderForms/simulation` | POST |
+
+All cart actions:
+- Receive `orderFormId` from cookie parsing
+- Pass `sc` (salesChannel) from segment
+- Use `expectedOrderFormSections` in body
+- Proxy `Set-Cookie` headers back
+- Return `OrderForm`
+
+### `actions/authentication/` (8 files)
+| File | Purpose |
+|------|---------|
+| `startAuthentication.ts` | Get auth token from VTEX ID |
+| `classicSignIn.ts` | Email + password login |
+| `accessKeySignIn.ts` | Magic link validation |
+| `sendEmailVerification.ts` | Send magic link email |
+| `recoveryPassword.ts` | Request password reset |
+| `resetPassword.ts` | Set new password |
+| `refreshToken.ts` | Refresh auth cookie |
+| `logout.ts` | Clear auth cookies |
+
+### `actions/session/` (3 files)
+| File | Endpoint |
+|------|----------|
+| `createSession.ts` | IO GraphQL — `newSession` mutation |
+| `editSession.ts` | IO GraphQL — `updateSession` mutation |
+| `deleteSession.ts` | IO GraphQL — `deleteSession` mutation |
+
+### Other Actions
+| Directory | Files | Purpose |
+|-----------|-------|---------|
+| `address/` | 3 | CRUD user addresses (IO GraphQL) |
+| `newsletter/` | 2 | Subscribe + update opt-in |
+| `wishlist/` | 2 | Add/remove items (IO GraphQL) |
+| `masterdata/` | 2 | Create/update documents |
+| `orders/` | 1 | Cancel order |
+| `payment/` | 1 | Delete payment token |
+| `profile/` | 1 | Update user profile |
+| `review/` | 1 | Submit product review |
+| `analytics/` | 1 | Send SP event |
+| `notifyme.ts` | 1 | Notify me when available |
+| `trigger.ts` | 1 | Workflow trigger |
+
+## Loaders (50+ files, 15 subdirectories)
+
+### `loaders/intelligentSearch/` (6 files) — Primary search
+| File | Returns | API |
+|------|---------|-----|
+| `productDetailsPage.ts` | `ProductDetailsPage` | IS product_search + facets |
+| `productListingPage.ts` | `ProductListingPage` | IS product_search + facets |
+| `productList.ts` | `Product[]` | IS product_search |
+| `suggestions.ts` | `Suggestion` | IS search_suggestions |
+| `topsearches.ts` | `Suggestion` | IS top_searches |
+| `productSearchValidator.ts` | Validates search args | — |
+
+### `loaders/legacy/` (7 files) — Legacy Catalog API
+| File | Returns | API |
+|------|---------|-----|
+| `productDetailsPage.ts` | `ProductDetailsPage` | `/products/search/:slug/p` |
+| `productListingPage.ts` | `ProductListingPage` | `/products/search` + `/facets/search` |
+| `productList.ts` | `Product[]` | `/products/search` |
+| `suggestions.ts` | `Suggestion` | `/buscaautocomplete` |
+| `relatedProductsLoader.ts` | `Product[]` | `/crossselling/:type/:id` |
+| `brands.ts` | `Brand[]` | `/brand/list` |
+| `pageType.ts` | `PageType` | `/portal/pagetype/:term` |
+
+### `loaders/logistics/` (5 files)
+| File | Purpose |
+|------|---------|
+| `getSalesChannelById.ts` | Get sales channel details |
+| `listSalesChannelById.ts` | List sales channels |
+| `listPickupPoints.ts` | List pickup points |
+| `listPickupPointsByLocation.ts` | Pickup points near location |
+| `listStockByStore.ts` | Stock availability by store |
+
+### Other Loaders
+| Directory | Files | Purpose |
+|-----------|-------|---------|
+| `cart.ts` | 1 | Get/create OrderForm |
+| `user.ts` | 1 | Get current user (Person) |
+| `wishlist.ts` | 1 | Get user wishlist |
+| `navbar.ts` | 1 | Category tree for navigation |
+| `proxy.ts` | 1 | VTEX checkout/API proxy handler |
+| `config.ts` | 1 | Expose app config |
+| `address/` | 2 | Get addresses, postal code lookup |
+| `categories/` | 1 | Category tree |
+| `collections/` | 1 | List collections |
+| `orders/` | 3 | Get by ID, list, orderplaced |
+| `payment/` | 2 | Payment systems, user payments |
+| `profile/` | 2 | Get current profile, get by email |
+| `session/` | 2 | Get session, get user sessions |
+| `paths/` | 2 | PDP/PLP default path patterns |
+| `product/` | 3 | Extend product, extensions, wishlist enrichment |
+| `product/extensions/` | 4 | Enrich PDP, list, PLP, suggestions |
+| `masterdata/` | 1 | Search documents |
+| `options/` | 1 | Product ID by search term |
+| `promotion/` | 1 | Get promotion by ID |
+| `workflow/` | 2 | Product/products for workflow |
+
+## Utils (31 files)
+
+### Core Transform & Types
+| File | Lines | Purpose |
+|------|-------|---------|
+| `transform.ts` | ~600 | THE canonical VTEX → schema.org mapping |
+| `types.ts` | 1320 | All VTEX API types (OrderForm, Product, etc.) |
+| `client.ts` | 317 | `VTEXCommerceStable` + `SP` typed interfaces |
+
+### Fetch & HTTP
+| File | Purpose |
+|------|---------|
+| `fetchVTEX.ts` | VTEX-specific `fetchSafe`/`fetchAPI` with URL sanitization |
+
+### Cookies & Auth
+| File | Purpose |
+|------|---------|
+| `cookies.ts` | `stringify`, `proxySetCookie`, cookie constants |
+| `vtexId.ts` | `parseCookie` — extracts auth cookie + JWT decode |
+| `orderForm.ts` | `parseCookie` — extracts checkout cookie + orderFormId |
+
+### Segment & Search
+| File | Purpose |
+|------|---------|
+| `segment.ts` | Segment bag management, cookie serialization, `isAnonymous` |
+| `intelligentSearch.ts` | IS cookie management, search params building |
+
+### Other Utils
+| File | Purpose |
+|------|---------|
+| `legacy.ts` | Legacy API helpers |
+| `similars.ts` | Similar products enrichment |
+| `batch.ts` | Batch API calls |
+| `cacheBySegment.ts` | Cache key generation per segment |
+| `slugify.ts` | URL slug generation |
+| `resourceRange.ts` | Range header parsing for pagination |
+| `pickAndOmit.ts` | Object property picking/omitting |
+| `login/getLoginCookies.ts` | Extract login-related cookies |
+| `login/setLoginCookies.ts` | Set login cookies in response |
+| `extensions/simulation.ts` | Price simulation enrichment |
+
+### OpenAPI Generated Types (12 files)
+```
+openapi/
+├── api.openapi.json + api.openapi.gen.ts       # VTEX API
+├── my.openapi.json + my.openapi.gen.ts         # My Account
+├── orders.openapi.json + orders.openapi.gen.ts # Orders
+├── payments.openapi.json + payments.openapi.gen.ts
+├── subscriptions.openapi.json + subscriptions.openapi.gen.ts
+└── vcs.openapi.json + vcs.openapi.gen.ts       # VTEXCommerceStable
+```
+
+## Hooks (5 files)
+
+| File | Framework | Purpose |
+|------|-----------|---------|
+| `context.ts` | Preact signals | Central state (cart, user, wishlist) + enqueue |
+| `useCart.ts` | Preact signals | Cart operations via invoke proxy |
+| `useUser.ts` | Preact signals | User state from context |
+| `useWishlist.ts` | Preact signals | Wishlist CRUD via invoke proxy |
+| `useAutocomplete.ts` | Preact signals | Search autocomplete |
+
+## Other
+
+| Directory | Purpose |
+|-----------|---------|
+| `middleware.ts` | Sets segment + IS cookies in ctx.bag |
+| `handlers/sitemap.ts` | VTEX sitemap proxy |
+| `sections/Analytics/Vtex.tsx` | VTEX analytics pixel section |
+| `components/VTEXPortalDataLayerCompatibility.tsx` | DataLayer compat |
+| `workflows/events.ts` | Workflow event definitions |
+| `workflows/product/index.ts` | Product sync workflow |
+| `preview/Preview.tsx` | Admin preview component |
+
+## Key Data Flow
+
+```
+Request → middleware.ts (parse cookies, set segment/IS in bag)
+        → loader/action (use ctx.bag for segment, cookies)
+          → client.ts (typed HTTP call to VTEX API)
+          → transform.ts (API response → schema.org)
+        ← Response (proxySetCookie back to client)
+```
+
+## `utils/client.ts` — Endpoint Map
+
+The `VTEXCommerceStable` interface (317 lines) defines every endpoint:
+
+| Category | Endpoints |
+|----------|-----------|
+| Auth | startAuthentication, classicValidate, accessKeyValidate, setPassword, sendAccessKey, refreshToken |
+| Checkout | orderForm, items, update, removeAll, coupons, attachments, offerings, simulation, installments, profile, messages, gifts |
+| Catalog (Legacy) | products/search, crossselling, facets/search, pagetype, brand/list, category/tree, buscaautocomplete |
+| Catalog (IS) | product_search, facets, search_suggestions, top_searches |
+| Orders | user/orders, cancel, order-group |
+| Masterdata | documents (create) |
+| Newsletter | Newsletter.aspx, AviseMe.aspx |
+| IO GraphQL | Private graphql endpoint (sessions, wishlist, addresses, reviews) |

package/.cursor/skills/deco-apps-architecture/website-app.md

@@ -0,0 +1,169 @@
+# Website App — Reference
+
+The `website/` app is the base layer that all Deco storefronts use. It handles routing, SEO, analytics, image optimization, themes, and A/B testing.
+
+## Structure
+
+```
+website/
+├── mod.ts                   # App factory (Props: routes, global sections, caching, abTesting, SEO, theme)
+├── manifest.gen.ts
+├── types.ts                 # Script type
+├── Preview.tsx              # Admin preview
+├── pages/Page.tsx           # Base page component
+├── actions/
+│   └── secrets/encrypt.ts   # Secret encryption
+├── components/
+│   ├── Analytics.tsx         # Analytics container
+│   ├── Clickhouse.tsx        # ClickHouse event collector
+│   ├── Events.tsx            # Event dispatching
+│   ├── Image.tsx             # Optimized image component
+│   ├── Video.tsx             # Video component
+│   ├── Theme.tsx             # Theme provider
+│   ├── _Controls.tsx         # Live controls
+│   └── _seo/                 # SEO meta tag components
+│       ├── Facebook.tsx
+│       ├── Google.tsx
+│       ├── LinkedIn.tsx
+│       └── Twitter.tsx
+├── flags/
+│   ├── audience.ts           # Audience-based routing
+│   ├── everyone.ts           # Match all visitors
+│   ├── flag.ts               # Feature flag
+│   └── multivariate.ts       # Multivariate testing
+├── functions/
+│   └── requestToParam.ts     # Extract request params
+├── handlers/
+│   ├── fresh.ts              # Fresh framework handler
+│   ├── proxy.ts              # Reverse proxy (VTEX checkout, etc.)
+│   ├── redirect.ts           # URL redirects
+│   ├── router.ts             # Main router (matches pages to URLs)
+│   └── sitemap.ts            # Sitemap generation
+├── loaders/
+│   ├── asset.ts              # Asset URL resolution
+│   ├── environment.ts        # Environment variables
+│   ├── fonts/                # Font loading (GoogleFonts, etc.)
+│   ├── image/                # Image optimization
+│   ├── pages.ts              # Page resolution
+│   ├── redirects.ts          # Redirect rules
+│   ├── redirectsFromCsv.ts   # Bulk redirects from CSV
+│   └── secret.ts             # Secret values (API keys, tokens)
+├── matchers/
+│   ├── always.ts             # Always match
+│   ├── cookie.ts             # Match by cookie value
+│   ├── cron.ts               # Match by cron schedule
+│   ├── date.ts               # Match by date range
+│   ├── device.ts             # Match by device type
+│   ├── host.ts               # Match by hostname
+│   ├── location.ts           # Match by geo-location
+│   ├── multi.ts              # Combine matchers
+│   ├── nthRequest.ts         # Match every Nth request
+│   ├── queryString.ts        # Match by query params
+│   ├── random.ts             # Random percentage
+│   ├── site.ts               # Match by site ID
+│   └── userAgent.ts          # Match by user agent
+├── sections/
+│   ├── Analytics/            # GA, GTM, Pixel sections
+│   ├── Rendering/            # Lazy, Deferred rendering sections
+│   └── Seo/                  # SEO meta sections
+└── utils/
+    ├── crypto.ts             # Encryption helpers
+    ├── html.ts               # HTML manipulation
+    ├── image/                # Image engine implementations
+    ├── location.ts           # IP-to-location
+    ├── multivariate.ts       # A/B test utilities
+    └── unhandledRejection.ts # Global error handler
+```
+
+## `mod.ts` Props
+
+```typescript
+interface Props {
+  routes?: Routes[];         // URL → page/handler mapping
+  global?: Section[];        // Sections included on every page (header, footer)
+  errorPage?: Page;          // Custom error page
+  caching?: Caching;         // Cache-Control directives
+  abTesting?: AbTesting;     // A/B test against another URL
+  flavor?: Fresh | HTMX;     // Framework selection
+  seo?: Seo;                 // Default SEO meta
+  theme?: Section;           // Theme section (CSS variables)
+  disableProxy?: boolean;    // Disable image/asset proxy
+  whilelistURLs?: string[];  // Allowed proxy URL patterns
+}
+```
+
+## Routing
+
+The `handlers/router.ts` matches incoming URLs against registered `routes` and `audiences`:
+
+```
+Request URL → matchers (device, cookie, location, etc.)
+            → matching audience → handler (page, proxy, redirect)
+            → global sections prepended
+            → render page
+```
+
+## A/B Testing
+
+Built into the website app:
+
+```typescript
+interface AbTesting {
+  enabled?: boolean;
+  name?: string;               // Cookie name for variant tracking
+  matcher?: Matcher;           // Who sees the variant
+  urlToRunAgainst?: string;    // Proxy target URL
+  replaces?: TextReplace[];    // String replacements in proxied HTML
+  includeScriptsToHead?: Script[];
+  includeScriptsToBody?: Script[];
+}
+```
+
+## Matchers
+
+Used for audience targeting and A/B testing:
+
+| Matcher | Criteria |
+|---------|----------|
+| `always` | Always matches |
+| `cookie` | Cookie name/value |
+| `cron` | Cron expression |
+| `date` | Date range |
+| `device` | Desktop/mobile/tablet |
+| `host` | Request hostname |
+| `location` | Country/city/region |
+| `queryString` | URL query params |
+| `random` | Random percentage |
+| `userAgent` | Browser/OS detection |
+| `multi` | AND/OR combination of matchers |
+
+## Handlers
+
+| Handler | Purpose |
+|---------|---------|
+| `router.ts` | Main router — resolves URL to page + sections |
+| `proxy.ts` | Reverse proxy with HTML rewriting, script injection |
+| `redirect.ts` | URL redirects (301/302) |
+| `fresh.ts` | Fresh framework page handler |
+| `sitemap.ts` | Dynamic sitemap.xml generation |
+
+## SEO Components
+
+Located in `components/_seo/`:
+- `Google.tsx` — Title, description, canonical, JSON-LD
+- `Facebook.tsx` — Open Graph meta tags
+- `Twitter.tsx` — Twitter card meta tags
+- `LinkedIn.tsx` — LinkedIn meta tags
+
+## Caching
+
+```typescript
+interface Caching {
+  enabled?: boolean;
+  directives?: CacheDirective[];
+}
+
+type CacheDirective = 
+  | { name: "stale-while-revalidate"; value: number }
+  | { name: "max-age"; value: number };
+```

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

@@ -0,0 +1,189 @@
+---
+name: deco-apps-vtex-porting
+description: Port the VTEX commerce app from deco-cx/apps (Fresh/Deno) to @decocms/apps-start (TanStack Start/Node). The goal is to mirror the original production code that runs on thousands of stores, adapting only what is necessary for TanStack/Node. Covers full structural mapping (141 files → apps-start equivalent), adaptation patterns (Deno→Node, signals→react-query, manifest→exports, ctx.bag→configureVtex), schema.org compliance, and a file-by-file gap analysis. Use when porting VTEX code, fixing bugs in apps-start, or ensuring parity with the original.
+globs:
+  - "**/apps-start/vtex/**"
+  - "**/apps-start/commerce/**"
+  - "**/apps-start/shopify/**"
+---
+
+# Porting deco-cx/apps to @decocms/apps-start
+
+## Philosophy
+
+**The original `deco-cx/apps` is the source of truth.** It runs on thousands of stores in production. The goal of `apps-start` is NOT to reinvent — it's to mirror the same logic, adapted only where the platform forces a change (Deno→Node, Fresh→TanStack, Preact signals→React/TanStack Query).
+
+When in doubt about how something should work, look at the original first.
+
+## Sub-documents
+
+| Document | Topic |
+|----------|-------|
+| [structure-map.md](./structure-map.md) | File-by-file mapping: original → apps-start (what exists, what's missing, what's wrong) |
+| [adaptation-patterns.md](./adaptation-patterns.md) | How to convert each Deno/Fresh/Deco pattern to TanStack/Node |
+| [commerce-porting.md](./commerce-porting.md) | Porting the commerce/ module (types, utils, SDK, components) |
+| [website-porting.md](./website-porting.md) | Where website/ code goes (framework, storefront, worker entry) |
+| [transform-mapping.md](./transform-mapping.md) | Field-by-field VTEX → schema.org mapping in transform.ts |
+| [cookie-auth-patterns.md](./cookie-auth-patterns.md) | Cookie propagation, auth headers, session handling |
+
+## Architecture Comparison
+
+```
+deco-cx/apps (Original)              @decocms/apps-start (Port)
+═══════════════════════              ═════════════════════════
+Deno + Fresh + Preact                Node + TanStack Start + React
+@deco/deco framework                 No framework (pure functions)
+mod.ts (app factory)                 configureVtex() / index.ts
+manifest.gen.ts (auto-gen)           package.json exports (manual)
+runtime.ts (invoke proxy)            Direct imports
+ctx (AppContext + bag)               getVtexConfig() singleton
+signals (@preact/signals)            @tanstack/react-query mutations
+middleware.ts (ctx.bag)              middleware.ts (request-local)
+OpenAPI codegen (*.gen.ts)           Manual vtexFetch calls
+proxySetCookie (Deno std)            vtexFetchWithCookies (manual)
+```
+
+## What Changes, What Stays
+
+### STAYS THE SAME (copy/adapt minimally)
+- `utils/transform.ts` — the entire VTEX→schema.org mapping
+- `utils/types.ts` — all 1320 lines of VTEX API types
+- `utils/segment.ts` — segment parsing/serialization logic
+- `utils/intelligentSearch.ts` — IS param building
+- `utils/cookies.ts` — cookie stringify, constants
+- `utils/vtexId.ts` — auth cookie parsing
+- `utils/orderForm.ts` — OrderForm cookie parsing
+- `utils/similars.ts` — similar products enrichment
+- `utils/batch.ts` — batch API calls
+- `utils/slugify.ts` — URL slug generation
+- Business logic in actions (the VTEX API calls)
+- Business logic in loaders (the data fetching + transform)
+
+### MUST CHANGE (platform differences)
+| Original Pattern | apps-start Pattern | Why |
+|-----------------|-------------------|-----|
+| `export default function(props, req, ctx)` | `export async function myLoader(props)` | No Deco framework, no AppContext |
+| `ctx.account`, `ctx.salesChannel` | `getVtexConfig().account` | No ctx.bag |
+| `ctx.vcsDeprecated["POST /path"]({}, opts)` | `vtexFetch<T>("/path", opts)` | No OpenAPI typed client |
+| `createHttpClient<VCS>()` | `vtexFetch()` / `vtexFetchWithCookies()` | No Deno-style Proxy client |
+| `ctx.io.query<D,V>({query, variables})` | `vtexIOGraphQL<T>({query, variables})` | No createGraphqlClient |
+| `proxySetCookie(res.headers, ctx.response.headers)` | Return `{ data, setCookies }` from vtexFetchWithCookies | No ctx.response |
+| `getSegmentFromBag(ctx)` | Read from middleware context or config | No ctx.bag |
+| `signal<OrderForm\|null>(null)` | `useQuery` / `useMutation` from @tanstack/react-query | No @preact/signals |
+| `invoke({ cart: { key, props } })` | Direct fetch to API routes or useMutation | No Deco invoke proxy |
+| `import { getCookies } from "std/http/mod.ts"` | Parse cookies manually or use a cookie lib | No Deno std |
+
+## Key Concepts for Porters
+
+### 1. The Typed Client Is Gone
+
+Original uses `createHttpClient<VTEXCommerceStable>()` which creates a Proxy object where property access like `client["POST /api/checkout/pub/orderForm"]({sc: "1"}, {body: ...})` is fully typed.
+
+In apps-start, this is replaced by `vtexFetch<T>(path, init)` — a simpler wrapper:
+
+```typescript
+// Original (apps)
+const response = await ctx.vcsDeprecated["POST /api/checkout/pub/orderForm/:orderFormId/items"](
+  { orderFormId, sc, allowedOutdatedData: ["paymentData"] },
+  { body: { orderItems }, headers: { cookie } },
+);
+const orderForm = await response.json();
+
+// Port (apps-start)
+const orderForm = await vtexFetch<OrderForm>(
+  `/api/checkout/pub/orderForm/${orderFormId}/items?sc=${sc}&allowedOutdatedData=paymentData`,
+  { method: "POST", body: JSON.stringify({ orderItems }), headers: { cookie, "Content-Type": "application/json" } },
+);
+```
+
+### 2. One Loader Per File → Consolidated Loaders
+
+Original has one file per loader (e.g., `loaders/intelligentSearch/productDetailsPage.ts`). Apps-start consolidates:
+- `loaders/intelligentSearch/*.ts` (6 files) → `loaders/search.ts` + `inline-loaders/productDetailsPage.ts` etc.
+- `loaders/legacy/*.ts` (7 files) → `loaders/legacy.ts` + `loaders/catalog.ts`
+
+This is fine but makes it harder to compare. Always check the ORIGINAL file to understand intended behavior.
+
+### 3. Actions Are Consolidated Too
+
+Original: `actions/cart/addItems.ts`, `actions/cart/updateItems.ts`, etc. (16 files)
+Apps-start: `actions/checkout.ts` (all cart actions in one file)
+
+### 4. Hooks Use React Query Instead of Signals
+
+Original hooks use a serial queue pattern with `@preact/signals`:
+```typescript
+const cart = signal<OrderForm | null>(null);
+const enqueue = (key) => (props) => storeState.enqueue((signal) => invoke({ cart: { key, props } }));
+```
+
+Apps-start hooks use `@tanstack/react-query`:
+```typescript
+const { data: cart } = useQuery({ queryKey: ["cart"], queryFn: fetchCart });
+const addItems = useMutation({ mutationFn: addItemsToCart, onSuccess: () => queryClient.invalidateQueries(["cart"]) });
+```
+
+### 5. Middleware Has No ctx.bag
+
+Original middleware sets state in `ctx.bag` (per-request storage):
+```typescript
+setSegmentBag(cookies, req, ctx);    // ctx.bag.set(SEGMENT, data)
+setISCookiesBag(cookies, ctx);       // ctx.bag.set(IS_COOKIES, data)
+```
+
+Apps-start uses `configureVtex()` singleton + request-level context:
+```typescript
+const config = getVtexConfig(); // Global config
+// Per-request: pass cookies/segment through function params
+```
+
+## The sellerId vs sellerName Pitfall
+
+The #1 bug when porting. VTEX `Offer.seller` MUST be `sellerId` (e.g., `"1"`), NOT `sellerName`. If you see `ORD027: Item não encontrado ou indisponível`, this is almost certainly the cause.
+
+The original `transform.ts` `buildOffer()` handles this correctly. **Never** create manual Offer mappings in loaders — always use `toProduct()` / `toProductPage()`.
+
+## salesChannel (sc) Injection
+
+Missing `sc` = wrong prices, ORD027, or invisible products.
+
+| Endpoint Type | How to inject |
+|--------------|---------------|
+| Checkout API (`/api/checkout/pub/orderForm/*`) | `?sc={salesChannel}` query param |
+| Legacy Catalog (`/api/catalog_system/pub/products/search/*`) | `?sc={salesChannel}` query param |
+| Buscaautocomplete (`/buscaautocomplete`) | `&sc={salesChannel}` query param |
+| Intelligent Search | Handled automatically by `intelligentSearch()` in client.ts |
+| Client-side hooks | Read `VTEXSC` cookie via `document.cookie` |
+
+## Quick Reference: transform.ts Functions
+
+| Function | Input | Output |
+|----------|-------|--------|
+| `toProduct(product, sku, level, opts)` | VTEX Product/LegacyProduct | schema.org Product |
+| `toProductPage(product, sku, breadcrumbs, opts)` | VTEX Product + SKU | ProductDetailsPage |
+| `pickSku(product, skuId?)` | Product with items[] | Best SKU item |
+| `aggregateOffers(offers)` | Offer[] | AggregateOffer |
+| `buildOffer(seller, opts)` | VTEX Seller | schema.org Offer (with seller=sellerId) |
+| `forceHttpsOnAssets(orderForm)` | OrderForm | OrderForm with https URLs |
+
+## Debugging Checklist
+
+1. **ORD027** → Check `seller` value (must be sellerId, not sellerName)
+2. **Wrong prices** → Check `sc` parameter on API calls
+3. **Empty cart** → Check `expectedOrderFormSections` in POST body
+4. **Auth fails** → Check `buildAuthCookieHeader` produces both cookie variants
+5. **IS returns nothing** → Check `vtex_is_session` / `vtex_is_anonymous` cookies
+6. **User always logged out** → Check `useUser` uses server-side session check, not client cookie
+7. **Missing product data** → Check transform.ts is being used (not manual mapping)
+
+## Local Development
+
+```json
+// storefront package.json
+"@decocms/apps": "file:../apps-start"
+```
+
+After changes to apps-start:
+```bash
+rm -rf node_modules/.vite && npm run dev
+```