feat(apps-vtex): Cart v2 — modular, granular, framework-agnostic cart

[JonasJesus42]

Summary

Introduces a two-dimension cart fragmentation system for @decocms/apps-vtex: sections (controls what VTEX computes via expectedOrderFormSections) and projection (none / summary / summary+items / minicart / raw, controls what the server sends to the browser). The result: no OrderForm created until the first add-to-cart, add-to-cart sends 3 sections instead of 15, and the browser receives ~1 KB instead of ~40 KB by default. Optimistic badge bump + server reconciliation live in the hook — the storefront never reimplements them. The agnostic contract lives in @decocms/apps-commerce (Shopify/Wake can reuse the same types). Includes a TanStack Query adapter (6 hooks, useShipping keyed by {postalCode,items} for client-side cache), 281 passing tests, and a skill with usage guide, projection decision table, and gradual v1→v2 migration guide.

New surface

• @decocms/apps-commerce/types/cart — CartSection, CartProjection, CartSummary, CartItemSlim, SECTIONS_MINIMAL/DRAWER/FULL
• vtex/loaders/cart/{summary,full,shipping,gifts,attachments} — granular read-path loaders, each requesting only the sections it needs
• createCart({ invoke }) — factory: useCart, useCartSummary, useAddToCart, useShipping, useGifts, useAttachments, resetCart; add() returns the projected payload for toasts without a second fetch
• createCartQuery({ invoke }) — optional TanStack Query adapter with full parity
• actions/checkout.ts: addItemsToCartV2, updateCartItemsV2, addCouponToCartV2, getOrCreateCartV2
• .agents/skills/vtex-cart-v2/SKILL.md — full usage, projection decision guide, gradual migration guide

Test plan

• vitest run packages/apps-vtex packages/apps-commerce — 281 tests passing (26 files)
• tsc --noEmit on apps-vtex and apps-commerce — 0 errors
• biome check — 0 errors on all touched files
• E2E smoke: home load with no add → 0 calls to /api/checkout/pub/orderForm; add-to-cart → body contains SECTIONS_MINIMAL, response is slim summary+items; open drawer → cart/full called with 9 sections

🤖 Generated with Claude Code

---

Summary by cubic

Cart v2 for @decocms/apps-vtex adds two-way cart fragmentation (sections and projection) to cut VTEX compute and shrink client payloads. No cart is created until the first add; add-to-cart requests only minimal sections and returns a slim response with optimistic badge updates.

• New Features

  • Platform-agnostic cart types in @decocms/apps-commerce/types/cart with SECTIONS_MINIMAL, SECTIONS_DRAWER, and SECTIONS_FULL.
  • Granular loaders: vtex/loaders/cart/{summary,full,shipping,gifts,attachments}.
  • createCart({ invoke }) hooks: useCart, useCartSummary, useAddToCart, useShipping, useGifts, useAttachments, resetCart (optimistic bump + server reconciliation; add() returns the projected payload).
  • Optional TanStack Query adapter createCartQuery({ invoke }); @tanstack/react-query is an optional peer.
  • V2 checkout actions: getOrCreateCartV2, addItemsToCartV2, updateCartItemsV2, addCouponToCartV2 with server-side projectOrderForm to enforce projections.

• Migration

  • Stop creating a cart on mount; use useCartSummary + vtex/loaders/cart/summary for the badge.
  • Load the drawer on demand via vtex/loaders/cart/full.
  • Keep v1 running while migrating; components can switch to the new hooks one by one.
  • If your app uses react-query, swap to createCartQuery; otherwise use createCart.

^{Written for commit aed1d8c. Summary will update on new commits.}