@decocms/start 1.6.2 → 1.7.0

package/.cursor/skills/deco-to-tanstack-migration/SKILL.md

@@ -5,7 +5,51 @@ description: Migrate Deco.cx storefronts from Fresh/Preact to TanStack Start/Rea
 
 # Deco-to-TanStack-Start Migration Playbook
 
-Phase-based playbook for converting `deco-sites/*` storefronts from Fresh/Preact/Deno to TanStack Start/React/Cloudflare Workers. Battle-tested on espacosmart-storefront (100+ sections, VTEX, async rendering).
+Phase-based playbook for converting `deco-sites/*` storefronts from Fresh/Preact/Deno to TanStack Start/React/Cloudflare Workers. Battle-tested on espacosmart-storefront (VTEX, 100+ sections) and storefront-tanstack (Shopify).
+
+**Framework minimum**: `@decocms/start >= 1.6.2` (deferred sections with `:slug` route params require the `routeParams` propagation fix — see gotcha #47).
+
+## One-Prompt Migration (copy/paste to an AI agent)
+
+Paste the prompt below verbatim into a code-writing AI (Claude Code, Cursor, etc.) pointed at a fresh TanStack Start scaffold that already has the source `deco-sites/*` project copied to `.context/` for reference. The agent will execute phases 0–10 sequentially, gating on exit criteria, and stop to confirm when a phase needs a human judgment call.
+
+```
+You are migrating a Deco/Fresh/Preact storefront to TanStack Start/React/Cloudflare Workers.
+
+Source site reference: .context/<SITE_NAME>/ (read-only)
+Target repo: this working directory
+Framework docs: .cursor/skills/deco-to-tanstack-migration/SKILL.md + references/ + templates/
+
+Execute the migration in phase order. For each phase:
+  1. Read the phase section in SKILL.md and the linked references/templates
+  2. Run the automation commands from references/codemod-commands.md where the phase is bulk-safe
+  3. Verify the phase's exit criteria before moving on
+  4. If a verification fails, fix root causes — do not skip
+
+Critical invariants (violate none of these):
+  - Never add compat/ layers or Vite aliases beyond `~` → `src/`
+  - Copy components faithfully from source — do NOT rewrite JSX, class names, or grid/flex structure. Only apply mechanical migrations (class→className, for→htmlFor, preact→react imports). AI-rewritten components are the #1 regression source.
+  - `@decocms/start >= 1.6.2` in package.json (deferred-section routeParams fix)
+  - `import "./setup"` is the FIRST line in server.ts and worker-entry.ts
+  - Use `createSiteSetup()` + `applySectionConventions()` + `autoconfigApps(blocks, APP_REGISTRY)` — do NOT hand-wire section loaders, alwaysEager lists, or commerce loaders for apps the registry already covers (Phase 7 reference has the shape)
+  - Section metadata is declared in the section file (`export const eager = true`, `export const cache = "listing"`, etc.) — `generate-sections.ts` extracts it. Do not maintain duplicate arrays in setup.ts.
+  - After every phase, run: `npm run build && npm run typecheck`. Both must be green before proceeding.
+
+Stop and ask the human when:
+  - A component's layout output differs visibly from the source reference
+  - A gotcha listed in references/gotchas.md applies but the fix is non-mechanical
+  - Phase 5 (commerce/platform hooks): cart/user/wishlist flows are platform-specific and require real credentials — confirm the hook implementation before writing
+  - Phase 8 (routes): SEO sections, SSR/SPA decisions, and device detection need human confirmation
+
+Start at Phase 0. Report phase completion with a one-line summary + the verification command output.
+```
+
+The prompt assumes:
+- The target repo has TanStack Start scaffolded (`npm create @tanstack/app@latest -- --template cloudflare-workers`)
+- `@decocms/start` and `@decocms/apps` are published and installable (or locally linked)
+- The source `src/` has been copied and `.deco/blocks/` is present
+
+If either is missing, the agent will stop at Phase 0 and ask.
 
 ## Architecture Boundaries
 
@@ -227,21 +271,50 @@ See: skill `deco-islands-migration`
 **Entry**: Phase 6 complete
 
 **Actions** (critical — build `src/setup.ts`):
-1. Register all sections via `registerSections()` with dynamic imports
-2. Register critical sections (Header, Footer) via `registerSectionsSync()` + `setResolvedComponent()`
-3. Register section loaders via `registerSectionLoaders()` for sections with `export const loader`
-4. Register layout sections via `registerLayoutSections()`
-5. Register commerce loaders via `registerCommerceLoaders()` with SWR caching
-6. Wire `onBeforeResolve()` → `initVtexFromBlocks()` for VTEX config
-7. Configure `setAsyncRenderingConfig()` with `alwaysEager` for critical sections
-8. Configure admin: `setMetaData()`, `setRenderShell()`, `setInvokeLoaders()`
-9. **Register SEO sections via `registerSeoSections()`** — identify sections that produce title/description/canonical (typically SEOPDP, SEOPLP). Register their loaders in `registerSectionLoaders` too.
+
+Modern site setup uses three framework composers + convention-driven section metadata. The old manual registration arrays (`registerSectionsSync`, `setResolvedComponent`, `registerSectionLoaders`, `registerLayoutSections`, `registerSeoSections`, `setAsyncRenderingConfig({ alwaysEager })`) are replaced by codegen reading `export const X = true` declarations from each section file.
+
+1. **`createSiteSetup(options)`** from `@decocms/start/setup` — one-call framework bootstrap (sections glob, blocks, meta, CSS, fonts, production origins, preview wrapper, platform init).
+
+2. **`applySectionConventions({ meta, syncComponents, loadingFallbacks, sectionGlob })`** from `@decocms/start/cms` — reads `src/server/cms/sections.gen.ts` (produced by `generate-sections.ts`) and registers:
+   - `eager` → `registerEagerSections`
+   - `layout` → `registerLayoutSections`
+   - `seo` → `registerSeoSections`
+   - `cache` → `registerCacheableSections`
+   - `sync` → `registerSectionsSync` + bundled sync import
+   - `hasLoadingFallback` → `registerSection` with fallback
+   - `clientOnly` → `registerSection` with `clientOnly: true`
+
+3. **`autoconfigApps(blocks, APP_REGISTRY)`** from `@decocms/start/apps` — dual-registers every app's loaders + actions into the CMS resolve path AND the admin `/deco/invoke` path from a single source. `APP_REGISTRY` from `@decocms/apps/registry` maintains the list — adding a new app is one entry there, no site code change.
+
+4. **`registerCommerceLoaders({ ... })`** — ONLY for site-local loaders that don't belong to an app (e.g., `site/loaders/minicart.ts`, `site/loaders/user.ts`). Do NOT register Shopify/VTEX loaders manually — autoconfig handles those.
+
+5. **Section metadata lives in section files**, not in setup.ts:
+   ```typescript
+   // src/sections/Header/Header.tsx
+   export default function Header(props) { /* ... */ }
+   export const eager = true;   // include in alwaysEager
+   export const sync = true;    // bundle sync (no Suspense boundary)
+   export const layout = true;  // render even when CMS page wraps it in Lazy
+   ```
+   Then `npm run generate:sections` emits `sections.gen.ts` with the extracted arrays.
 
 **Template**: `templates/setup-ts.md`
 
-**Exit**: `setup.ts` compiles, all sections registered
+**Build pipeline** (add to `package.json` scripts):
+```
+"generate:blocks":   "tsx node_modules/@decocms/start/scripts/generate-blocks.ts",
+"generate:schema":   "tsx node_modules/@decocms/start/scripts/generate-schema.ts --site <SITE>",
+"generate:sections": "tsx node_modules/@decocms/start/scripts/generate-sections.ts",
+"generate:loaders":  "tsx node_modules/@decocms/start/scripts/generate-loaders.ts",
+"generate:invoke":   "tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
+"generate:routes":   "tsr generate",
+"build": "npm run generate:blocks && npm run generate:schema && npm run generate:sections && npm run generate:loaders && tsr generate && vite build"
+```
 
-See: skill `deco-async-rendering-site-guide`
+**Exit**: `setup.ts` compiles; `npm run build` green; every section declared in decofile resolves on SSR.
+
+See: skill `deco-async-rendering-site-guide`, reference `templates/setup-ts.md`
 
 ---
 

package/.cursor/skills/deco-to-tanstack-migration/references/gotchas.md

@@ -718,6 +718,104 @@ Or in project `.npmrc` with an env var (for CI):
 
 **Tradeoff with `github:` syntax**: No semver resolution — `npm update` is meaningless. Pin to a tag for stability: `github:decocms/deco-start#v0.14.2`. Without a tag, you get HEAD of the default branch.
 
+## 47. Deferred Sections Lose routeParams on PDP (`@decocms/start < 1.6.2`)
+
+**Severity**: CRITICAL — every deferred PDP section loads with `page: null`, product content never renders.
+
+`resolveDeferredSection` (called by the client `_serverFn` that streams `LazySection` contents) builds its own `ResolveContext` without populating `routeParams`. When a PDP loader chain uses `website/functions/requestToParam.ts` to read `:slug` from the route, the resolver returns `null` because `routeParams` is empty. Shopify/VTEX `productDetailsPage` then receives `slug: null` and returns `null`.
+
+**Symptom**: PDP HTTP returns 200, initial HTML renders the `<LazySection>` placeholder, but the deferred `_serverFn` POST returns `{ page: null }` (or a seroval null sentinel `{t:2,s:0}`). Product details section stays empty forever.
+
+**Fix**: upgrade to `@decocms/start >= 1.6.2`. The fix:
+
+```typescript
+// src/cms/resolve.ts — resolveDeferredSection
+const match = findPageByPath(pagePath);
+const rctx: ResolveContext = {
+  routeParams: match?.params,   // ← recovered from page match
+  matcherCtx: ctx,
+  memo: new Map(),
+  depth: 0,
+};
+```
+
+**Verification**: POST directly to the _serverFn endpoint for the deferred section with a real PDP path — response body should contain `"@type":"ProductDetailsPage"`. If it contains `{t:2,s:0}` (seroval null), you're on the broken version.
+
+**Detection grep**: search your site's node_modules for the fix marker:
+```bash
+grep -n "findPageByPath(pagePath)" node_modules/@decocms/start/src/cms/resolve.ts
+```
+No match → upgrade.
+
+## 48. Section Metadata Must Live in the Section File (Convention-Driven)
+
+**Severity**: MEDIUM — duplicate registration arrays drift out of sync; sections silently miss eager/layout flags.
+
+Pre-1.6 migrations hand-maintained arrays in `setup.ts`: `alwaysEager: ["site/sections/Header/Header.tsx", ...]`, `layoutSections: [...]`, `seoSections: [...]`, `cacheableSections: {...}`. Every new section meant editing setup.ts. These lists drifted — renamed/deleted sections left dangling entries; new eager sections were forgotten.
+
+The current pattern: declare behavior in the section file, `generate-sections.ts` extracts it into `sections.gen.ts`, `applySectionConventions()` registers it.
+
+```typescript
+// src/sections/Header/Header.tsx
+export default function Header(props) { /* ... */ }
+export const eager = true;   // alwaysEager
+export const sync = true;    // bundle sync (first paint)
+export const layout = true;  // layout section (never deferred)
+```
+
+```typescript
+// src/sections/Product/SearchResult.tsx
+export const cache = "listing";   // SWR cache profile
+export function LoadingFallback() { /* ... */ }
+```
+
+```typescript
+// src/sections/SEO/SeoPDP.tsx
+export const seo = true;
+```
+
+**Fix during migration**: delete hand-maintained arrays from setup.ts. Add the right `export const` flags on each section. Run `npm run generate:sections`. The `applySectionConventions({ meta: sectionMeta, ... })` call wires everything.
+
+**Regen cadence**: `generate:sections` runs automatically as part of `npm run build`. In dev, rerun it manually after changing a section's metadata exports.
+
+## 49. `window.STOREFRONT` Stub for Phase 6 (Cart/User/Wishlist)
+
+**Severity**: MEDIUM — pages crash during Phase 6 development without the stub; the stub itself is a placeholder, not a solution.
+
+The legacy Deco cart pattern injects `window.STOREFRONT.CART.{getCart, addToCart, setQuantity, subscribe}` + matching `USER` and `WISHLIST` channels. Header badges, minicart, AddToCart button, and wishlist buttons all read from this global. Until Phase 6 (commerce wiring) ships a real TanStack Store-backed implementation, pages crash on every render where any of these are read.
+
+**Interim stub** in `src/routes/__root.tsx` `head.scripts`:
+
+```javascript
+(function(){
+  if (window.STOREFRONT) return;
+  var noop = function(){};
+  var mkChan = function(emptyValue) {
+    return {
+      getCart: function(){ return emptyValue; },
+      getUser: function(){ return emptyValue; },
+      getWishlist: function(){ return emptyValue; },
+      getQuantity: function(){ return 0; },
+      inWishlist: function(){ return false; },
+      addToCart: noop, setQuantity: noop, dispatch: noop, toggle: noop,
+      subscribe: function(cb){ try { cb(this); } catch(e){} }
+    };
+  };
+  window.STOREFRONT = { CART: mkChan(null), USER: mkChan(null), WISHLIST: mkChan(null) };
+})();
+```
+
+**Real Phase 6 replacement** (remove the stub, wire the real thing):
+
+1. Create `src/sdk/cart.ts` with a `@tanstack/store` `Store<ShopifyCart>` (or VTEX `OrderForm`).
+2. Create `src/hooks/useCart.ts` that returns `{ cart, addItem, updateItem, clear }`, backed by the store. Mutations call the app's invoke handler (`/deco/invoke/shopify/actions/cart/addItems`).
+3. Replace `AddToCartButton.tsx` inline-script / HTMX pattern with a real React component using `onClick={() => addItem(...)}`. Delete `hx-on:click` + `useScript(onClick)`.
+4. Replace `ProductVariantSelector.tsx` `hx-get` + `useSection()` with TanStack Router `<Link to={relativeLink}>` for client-side navigation.
+5. Wire the minicart loader (`src/loaders/minicart.ts`) to call `invoke.shopify.loaders.cart` server-side for SSR hydration.
+6. Either delete the STOREFRONT stub entirely, or keep a thin `STOREFRONT` bridge that delegates to the store (for any inline scripts still in Header/Minicart templates you haven't migrated).
+
+**Gotcha within the gotcha**: the HTMX-era `AddToCartButton` uses an `<input type="checkbox" className="hidden peer">` + `peer-checked:hidden` CSS to swap between the "Add to Cart" button and a QuantitySelector once the item is in the cart. The real Phase 6 implementation should drive that swap from cart state (`const inCart = useCart().items.some(i => i.id === productID)`) and render one or the other. Don't carry the checkbox trick into the TanStack world.
+
 ## 46. `export type { X } from "..."` Does Not Scope `X` for Parameter Annotations
 
 Re-exporting a type makes it available to importers but does NOT bring it into scope in the same file:

package/.cursor/skills/deco-to-tanstack-migration/templates/package-json.md

@@ -1,55 +1,75 @@
 # package.json Template
 
+Current as of `@decocms/start@1.6.2` and `@decocms/apps@1.4.1+`.
+
 ```json
 {
   "name": "my-tanstack-store",
   "version": "0.1.0",
   "type": "module",
+  "description": "storefront powered by TanStack Start",
   "scripts": {
-    "dev": "npm run generate && vite dev",
-    "build": "npm run generate && vite build",
-    "generate": "npm run generate:blocks && npm run generate:invoke && npm run generate:schema",
-    "generate:blocks": "tsx node_modules/@decocms/start/scripts/generate-blocks.ts",
-    "generate:invoke": "tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
-    "generate:schema": "tsx node_modules/@decocms/start/scripts/generate-schema.ts --site storefront",
-    "deploy": "wrangler deploy"
+    "dev": "vite dev",
+    "dev:clean": "rm -rf node_modules/.vite .wrangler/state .tanstack && vite dev",
+    "generate:blocks":   "tsx node_modules/@decocms/start/scripts/generate-blocks.ts",
+    "generate:routes":   "tsr generate",
+    "generate:schema":   "tsx node_modules/@decocms/start/scripts/generate-schema.ts --site <SITE>",
+    "generate:invoke":   "tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
+    "generate:sections": "tsx node_modules/@decocms/start/scripts/generate-sections.ts",
+    "generate:loaders":  "tsx node_modules/@decocms/start/scripts/generate-loaders.ts --exclude shopify/loaders,shopify/actions",
+    "build": "npm run generate:blocks && npm run generate:schema && npm run generate:sections && npm run generate:loaders && tsr generate && vite build",
+    "preview": "vite preview",
+    "deploy": "npm run build && wrangler deploy",
+    "types": "wrangler types",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "knip": "knip",
+    "tailwind:lint": "tsx scripts/tailwind-lint.ts",
+    "tailwind:fix": "tsx scripts/tailwind-lint.ts --fix"
   },
   "dependencies": {
-    "@decocms/apps": "^0.20.1",
-    "@decocms/start": "^0.16.4",
-    "@tanstack/react-query": "^5.90.21",
-    "@tanstack/react-router": "^1.166.2",
-    "@tanstack/react-router-devtools": "^1.166.2",
-    "@tanstack/react-start": "^1.166.2",
-    "@tanstack/react-store": "^0.9.1",
+    "@decocms/apps": "^1.4.1",
+    "@decocms/start": "^1.6.2",
+    "@tanstack/react-query": "5.90.21",
+    "@tanstack/react-router": "1.166.7",
+    "@tanstack/react-start": "1.166.8",
+    "@tanstack/react-store": "0.9.2",
+    "@tanstack/store": "0.9.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.26.1",
+    "@cloudflare/vite-plugin": "^1.27.0",
     "@tailwindcss/vite": "^4.2.1",
-    "@tanstack/router-generator": "^1.166.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
+    "@tanstack/router-cli": "1.166.7",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.4",
     "babel-plugin-react-compiler": "^1.0.0",
     "daisyui": "^5.5.19",
+    "knip": "^5.61.2",
+    "prettier": "^3.5.3",
     "tailwindcss": "^4.2.1",
-    "tsx": "^4.19.2",
+    "ts-morph": "^27.0.2",
+    "tsx": "^4.19.4",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
-    "wrangler": "^4.14.1",
-    "@vitejs/plugin-react": "^4.5.2"
+    "wrangler": "^4.72.0"
   }
 }
 ```
 
 ## Notes
 
-- `@decocms/start` and `@decocms/apps` come from GitHub Packages — needs `.npmrc`:
+- **Minimum `@decocms/start` version is `1.6.2`** — earlier versions have a bug where deferred sections (`Lazy`-wrapped) lose `routeParams`, causing PDP loaders with `:slug` to return null. See gotcha #47.
+- **`generate` scripts** run as part of `build`. In dev, Vite HMR picks up changes without re-running them — you only need to re-run `generate:blocks` / `generate:sections` after editing `.deco/blocks/` or a section's metadata exports.
+- **`generate:loaders --exclude shopify/loaders,shopify/actions`** — the Shopify app ships its own loaders/actions, registered by `autoconfigApps`. Exclude to avoid double-registering site-local invoke entries for them.
+- **`tsr generate`** produces `src/routeTree.gen.ts` from file-based routes.
+- **GitHub Packages**: add an `.npmrc` in the repo root (git-ignore is optional):
   ```
   @decocms:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
   ```
-- Set `NODE_AUTH_TOKEN` in `.env` (add `.env` to `.gitignore`)
-- `generate` scripts run before dev and build to produce `blocks.gen.ts`, `invoke.gen.ts`, `meta.gen.json`
-- `tsx` is needed for the generate scripts (TypeScript execution)
+  Then set `NODE_AUTH_TOKEN` in `.env` for local installs and as a CI secret. Alternatively, pin by Git tag via `github:` URL syntax — see gotcha #45.
+- **React Compiler** is enabled via `babel-plugin-react-compiler` in `vite.config.ts`. Most sections benefit without annotation.

package/.cursor/skills/deco-to-tanstack-migration/templates/root-route.md

@@ -1,5 +1,41 @@
 # __root.tsx Template
 
+Two options — pick the one that matches the site's needs.
+
+## Option A — Minimal (recommended default)
+
+`DecoRootLayout` from `@decocms/start/hooks` wraps the `<html>` shell with all the pieces the framework expects (DaisyUI theme, LiveControls, HeadContent, Scripts, analytics bootstrap). Use this for every new site unless you need custom providers at the root.
+
+```typescript
+import { createRootRoute } from "@tanstack/react-router";
+import { DecoRootLayout } from "@decocms/start/hooks";
+// @ts-ignore Vite ?url import
+import appCss from "../styles/app.css?url";
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: "My Store" },
+    ],
+    links: [
+      { rel: "stylesheet", href: appCss },
+      { rel: "icon", href: "/favicon.ico" },
+    ],
+  }),
+  component: RootLayout,
+});
+
+function RootLayout() {
+  return <DecoRootLayout lang="pt-BR" siteName="my-store" />;
+}
+```
+
+## Option B — Custom providers (cart/React Query at root)
+
+Only reach for this when you need providers wrapping the CMS outlet — a root-mounted cart store that must hydrate before any section, global React Query client, etc. Everything else stays in sections.
+
 ```typescript
 import { useState } from "react";
 import {
@@ -12,27 +48,12 @@ import {
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { LiveControls } from "@decocms/start/hooks";
 import { ANALYTICS_SCRIPT } from "@decocms/start/sdk/analytics";
+// @ts-ignore Vite ?url import
 import appCss from "../styles/app.css?url";
 
-// Deco analytics event dispatcher — must be in <head> before any section renders
-const DECO_EVENTS_BOOTSTRAP = `
-window.DECO = window.DECO || {};
-window.DECO.events = window.DECO.events || {
-  _q: [],
-  dispatch: function(e) {
-    if (window.dataLayer) { window.dataLayer.push({ event: e.name, ecommerce: e.params }); }
-    this._q.push(e);
-  }
-};
-window.dataLayer = window.dataLayer || [];
-`;
-
-// Navigation progress bar CSS
 const PROGRESS_CSS = `
 @keyframes decoProgress{0%{width:0}30%{width:50%}60%{width:80%}100%{width:98%}}
 .deco-nav-progress{position:fixed;top:0;left:0;height:3px;background:var(--color-primary,#e53e3e);z-index:9999;animation:decoProgress 4s cubic-bezier(.4,0,.2,1) forwards;pointer-events:none;box-shadow:0 0 8px var(--color-primary,#e53e3e)}
-@keyframes decoFadeIn{from{opacity:0}to{opacity:1}}
-.deco-nav-overlay{position:fixed;inset:0;z-index:9998;pointer-events:none;background:rgba(255,255,255,0.15);animation:decoFadeIn .2s ease-out}
 `;
 
 function NavigationProgress() {
@@ -42,7 +63,6 @@ function NavigationProgress() {
     <>
       <style dangerouslySetInnerHTML={{ __html: PROGRESS_CSS }} />
       <div className="deco-nav-progress" />
-      <div className="deco-nav-overlay" />
     </>
   );
 }
@@ -55,10 +75,6 @@ export const Route = createRootRoute({
       { title: "My Store" },
     ],
     links: [
-      { rel: "preconnect", href: "https://fonts.googleapis.com" },
-      { rel: "preconnect", href: "https://fonts.gstatic.com", crossOrigin: "anonymous" },
-      // Add your font stylesheet here:
-      // { rel: "stylesheet", href: "https://fonts.googleapis.com/css2?family=..." },
       { rel: "stylesheet", href: appCss },
       { rel: "icon", href: "/favicon.ico" },
     ],
@@ -68,22 +84,20 @@ export const Route = createRootRoute({
 
 function RootLayout() {
   const [queryClient] = useState(
-    () =>
-      new QueryClient({
-        defaultOptions: {
-          queries: {
-            staleTime: import.meta.env.DEV ? 0 : 30_000,
-            gcTime: import.meta.env.DEV ? 0 : 5 * 60_000,
-            refetchOnWindowFocus: import.meta.env.DEV,
-          },
+    () => new QueryClient({
+      defaultOptions: {
+        queries: {
+          staleTime: import.meta.env.DEV ? 0 : 30_000,
+          gcTime: import.meta.env.DEV ? 0 : 5 * 60_000,
+          refetchOnWindowFocus: import.meta.env.DEV,
         },
-      })
+      },
+    }),
   );
 
   return (
     <html lang="pt-BR" data-theme="light" suppressHydrationWarning>
       <head>
-        <script dangerouslySetInnerHTML={{ __html: DECO_EVENTS_BOOTSTRAP }} />
         <HeadContent />
       </head>
       <body className="bg-base-100 text-base-content" suppressHydrationWarning>
@@ -91,7 +105,7 @@ function RootLayout() {
         <QueryClientProvider client={queryClient}>
           <Outlet />
         </QueryClientProvider>
-        <LiveControls site={process.env.DECO_SITE_NAME} />
+        <LiveControls site="my-store" />
         <script type="module" dangerouslySetInnerHTML={{ __html: ANALYTICS_SCRIPT }} />
         <Scripts />
       </body>
@@ -100,11 +114,14 @@ function RootLayout() {
 }
 ```
 
-## Key Points
+## Key points (applies to both)
+
+1. **`data-theme="light"`** on `<html>` — required for DaisyUI v4/v5 CSS variables to activate in production AND in the admin preview shell. Option A sets this for you.
+2. **`suppressHydrationWarning`** on `<html>` and `<body>` — browser extensions mutate these elements; React would warn on mismatch.
+3. **`LiveControls site={...}`** — admin iframe bridge. `site` MUST match the CMS site name used in `@decocms/apps/registry` entries and `.deco/blocks/`.
+4. **No `Device.Provider`** — do NOT hardcode `<Device.Provider value={{ isMobile: true }}>` in the root. Device detection belongs in each page route's `createServerFn` loader (see gotcha #29).
+5. **Keep the root thin** — sections own their own data. Avoid cross-section state at the root unless it's truly global (cart, theme). Every provider at the root ships to every page, even ones that don't need it.
+
+## Cart/platform state
 
-1. **QueryClientProvider** — Required even if not using React Query directly. @decocms/apps hooks may use it.
-2. **LiveControls** — Admin iframe bridge. `site` prop must match CMS site name.
-3. **DECO_EVENTS_BOOTSTRAP** — Must be in `<head>` before sections. Sections dispatch analytics events on render.
-4. **NavigationProgress** — Visual feedback during client-side navigation.
-5. **suppressHydrationWarning** — On `<html>` and `<body>` to avoid mismatches from browser extensions.
-6. **data-theme="light"** — Required for DaisyUI v4/v5 CSS variables to activate.
+If you add a cart store at the root (Option B), wire it AFTER `QueryClientProvider` so section-local hooks can use both. The cart store itself should be a module-level `@tanstack/store` `Store`, and a `useCart()` hook reads via `useStore(cartStore)`. SSR hydration: the page loader fetches the initial cart (via the minicart loader or Shopify `getCart`) and the root passes the initial state to `cartStore.setState()` before hydration.