@decocms/start 0.20.2 → 0.21.1

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

@@ -15,6 +15,46 @@ Phase-based playbook for converting `deco-sites/*` storefronts from Fresh/Preact
 | **@decocms/apps** | `@decocms/apps` | VTEX/Shopify loaders, commerce types, commerce sdk (useOffer, formatPrice, analytics) | Passthrough HTML components, Preact/Fresh refs |
 | **Site repo** | (not published) | All UI: components, hooks, types, routes, styles | No compat/ layer, no aliases beyond `~` |
 
+### What Belongs Where
+
+```
+@decocms/start (framework)
+├── src/cms/          # Block loading, page resolution, section registry
+│   └── loader.ts     # loadBlocks, setBlocks, AsyncLocalStorage for per-request overrides
+├── src/admin/        # Admin protocol: meta, decofile, invoke, render, schema composition
+│   ├── meta.ts       # setMetaData() calls composeMeta() at startup; /deco/meta handler
+│   ├── schema.ts     # MetaResponse type, composeMeta(), framework block schemas (pages)
+│   ├── render.ts     # /live/previews/* for section + page preview (HTML shell)
+│   ├── setup.ts      # Client-safe setup (setMetaData, setInvokeLoaders, setRenderShell)
+│   ├── decofile.ts   # /.decofile read/reload
+│   ├── invoke.ts     # /deco/invoke for loader/action calls
+│   ├── cors.ts       # CORS + admin origin validation
+│   └── liveControls.ts # Admin iframe bridge postMessage script
+├── src/sdk/
+│   ├── workerEntry.ts # createDecoWorkerEntry: outermost Cloudflare Worker wrapper
+│   ├── useScript.ts, signal.ts, clx.ts, cachedLoader.ts, instrumentedFetch.ts
+│   └── ...
+├── src/hooks/        # DecoPageRenderer (uses registry, NOT hardcoded map), LiveControls
+├── src/types/        # FnContext, App, AppContext, Section, SectionProps, Resolved
+└── scripts/          # generate-blocks.ts, generate-schema.ts
+
+@decocms/apps (commerce)
+├── commerce/types/   # Product, AnalyticsItem, BreadcrumbList, Filter, etc.
+├── commerce/utils/   # mapProductToAnalyticsItem, parseRange, formatRange
+├── commerce/sdk/     # useOffer, useVariantPossibilities, formatPrice, relative, analytics
+├── vtex/             # Client, loaders (actual VTEX API calls)
+└── shopify/          # Client, loaders (actual Shopify API calls)
+
+site repo (UI + business logic)
+├── src/components/   # All UI components (Image, Picture, Seo, Theme, etc.)
+├── src/hooks/        # useCart (real VTEX implementation), useUser, useWishlist
+├── src/types/        # widgets.ts (string aliases), vtex.ts (OrderFormItem, etc.)
+├── src/sdk/          # Site-specific contexts, usePlatform, useUI, useSuggestions
+├── src/sections/     # All CMS-renderable sections
+├── src/routes/       # TanStack Router routes
+└── src/server/       # Server functions (invoke.ts — createServerFn wrappers for @decocms/apps)
+```
+
 ### Architecture Map
 
 | Old Stack | New Stack |
@@ -278,6 +318,24 @@ npm run dev
 # 8. Admin — /deco/meta returns JSON, /live/previews works
 ```
 
+## Quick Start (Full Migration)
+
+1. **Scaffold**: `npm create @tanstack/app@latest -- --template cloudflare-workers`
+2. **Copy source**: Move `src/` from deco-site
+3. **Configure Vite**: See `references/vite-config/`
+4. **Install deps**: `npm install @decocms/start @decocms/apps @tanstack/store @tanstack/react-store`
+5. **Link local libs** (if not published): `cd apps-start && npm link && cd ../deco-start && npm link && cd ../my-store && npm link @decocms/apps @decocms/start`
+6. **Rewrite imports** (parallelizable):
+   - Preact -> React: `references/imports/`
+   - Signals -> TanStack Store: `references/signals/`
+   - Deco framework -> inline: `references/deco-framework/`
+   - Commerce/widget types -> @decocms/apps + local: `references/commerce/`
+   - SDK utilities -> packages: `~/sdk/useOffer` -> `@decocms/apps/commerce/sdk/useOffer`, `~/sdk/useScript` -> `@decocms/start/sdk/useScript`, etc.
+7. **Create local UI components**: Image.tsx, Picture.tsx, Seo.tsx, Theme.tsx in `~/components/ui/`
+8. **Implement platform hooks**: `references/platform-hooks/`
+9. **Build & verify**: `npm run build`
+10. **Final audit**: Zero `from "apps/"`, `from "$store/"`, `from "preact"`, `from "@preact"`, `from "@deco/deco"`, `from "~/sdk/useOffer"`, `from "~/sdk/format"` etc. -- all sdk utilities should come from packages
+
 ## Key Principles
 
 1. **No compat layer anywhere** -- not in `@decocms/start`, not in `@decocms/apps`, not in the site repo
@@ -492,6 +550,7 @@ The conductor approach that worked (836 errors → 0 across 213 files) treated e
 | Vite configuration | `references/vite-config/` |
 | Automation commands | `references/codemod-commands.md` |
 | Admin schema composition | `src/admin/schema.ts` in `@decocms/start` |
+| Server functions (`createServerFn`) | `references/server-functions/` |
 | Common gotchas (45 items) | `references/gotchas.md` |
 | setup.ts template | `templates/setup-ts.md` |
 | vite.config.ts template | `templates/vite-config.md` |

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

@@ -126,3 +126,49 @@ grep -r '@deco/deco' src/ --include='*.ts' --include='*.tsx'
 grep -r '\$fresh/' src/ --include='*.ts' --include='*.tsx'
 # Both should return ZERO matches
 ```
+
+## Deferred Sections and CLS Prevention
+
+When a CMS page wraps a section in `website/sections/Rendering/Lazy.tsx`, it becomes a `DeferredSection`. The `DeferredSectionWrapper` renders a skeleton via `getSectionOptions(key).loadingFallback`.
+
+**Problem**: `getSectionOptions` returns `undefined` if the section module hasn't loaded yet. The module is loaded async in a `useEffect` (`preloadSectionModule`), so on first paint `skeleton = null` — the space is blank and the footer jumps down as sections load (CLS).
+
+**Fix**: Use `registerSection` with `loadingFallback` pre-populated in `setup.ts` instead of including the section in the bulk `registerSections` call:
+
+```typescript
+import { registerSection, registerSections } from "@decocms/start/cms";
+import PDPSkeleton from "./components/product/PDPSkeleton";
+
+registerSections({
+  // ... all other sections (NOT the lazy-wrapped one)
+});
+
+// Pre-populate sectionOptions synchronously so DeferredSectionWrapper
+// has loadingFallback on the very first render — no null flash.
+registerSection(
+  "site/sections/Product/NotFoundChallenge.tsx",
+  () => import("./sections/Product/NotFoundChallenge") as any,
+  { loadingFallback: PDPSkeleton },
+);
+```
+
+**Why `as any`**: `registerSection` expects `Promise<SectionModule>` but the actual module export is wider (includes `LoadingFallback`, `loader`, etc.). The cast is safe.
+
+**Composite skeleton**: Create a `PDPSkeleton` that combines all `LoadingFallback` exports from the section's sub-components:
+
+```tsx
+// src/components/product/PDPSkeleton.tsx
+import { LoadingFallback as MountedPDPSkeleton } from "~/components/product/MountedPDP";
+import { LoadingFallback as ProductDescriptionSkeleton } from "~/components/product/MountedPDP/ProductDescription";
+import { LoadingFallback as ProductFAQSkeleton } from "~/components/product/MountedPDP/ProductFAQ";
+
+export default function PDPSkeleton() {
+  return (
+    <div>
+      <MountedPDPSkeleton />
+      <ProductDescriptionSkeleton />
+      <ProductFAQSkeleton />
+    </div>
+  );
+}
+```

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

@@ -1,6 +1,6 @@
 # Migration Gotchas
 
-45 pitfalls discovered during real migrations (espacosmart-storefront, osklen).
+46 pitfalls discovered during real migrations (espacosmart-storefront, osklen).
 
 ## 1. Section Loaders Don't Execute
 
@@ -717,3 +717,20 @@ 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.
+
+## 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:
+
+```typescript
+// BROKEN — Props is not in scope
+export type { Props } from "~/components/ui/Foo";
+export default function Foo({ bar }: Props) { } // Error: Cannot find name 'Props'
+
+// CORRECT — import separately, then re-export
+import type { Props } from "~/components/ui/Foo";
+export type { Props };
+export default function Foo({ bar }: Props) { }
+```
+
+This is a common pattern in section wrapper files (e.g. `src/sections/CountDownApp/CountDownApp.tsx`).

package/.cursor/skills/deco-to-tanstack-migration/references/platform-hooks/README.md

@@ -18,60 +18,27 @@ The storefront domain (e.g., `my-store.deco.site`) differs from the VTEX checkou
 
 Use TanStack Start `createServerFn` to create server-side proxy functions that the client hook calls transparently.
 
-### Server Functions (~/lib/vtex-cart-server.ts)
+> See `references/server-functions/README.md` for the full pattern and all TypeScript pitfalls.
 
-```typescript
-import { createServerFn } from "@tanstack/react-start";
+### Server Functions (`src/server/invoke.ts`)
 
-const ACCOUNT = "myaccount";
-const API_KEY = process.env.VTEX_APP_KEY!;
-const API_TOKEN = process.env.VTEX_APP_TOKEN!;
-
-export const getOrCreateCart = createServerFn({ method: "GET" })
-  .validator((orderFormId: string) => orderFormId)
-  .handler(async ({ data: orderFormId }) => {
-    const url = orderFormId
-      ? `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${orderFormId}`
-      : `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm`;
-    const res = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-VTEX-API-AppKey": API_KEY,
-        "X-VTEX-API-AppToken": API_TOKEN,
-      },
-      body: JSON.stringify({ expectedOrderFormSections: ["items", "totalizers", "shippingData", "clientPreferencesData", "storePreferencesData", "marketingData"] }),
-    });
-    return res.json();
-  });
+Wrap `@decocms/apps` VTEX actions in `createServerFn`. Always use `.inputValidator()` (not `.validator()`) and return `Promise<any>` to bypass `ValidateSerializable`:
 
-export const addItemsToCart = createServerFn({ method: "POST" })
-  .validator((data: { orderFormId: string; items: any[] }) => data)
-  .handler(async ({ data }) => {
-    const res = await fetch(
-      `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${data.orderFormId}/items`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
-        body: JSON.stringify({ orderItems: data.items }),
-      },
-    );
-    return res.json();
+```typescript
+import { createServerFn } from "@tanstack/react-start";
+import { getOrCreateCart } from "@decocms/apps/vtex/actions/checkout";
+
+// Preferred: wrap @decocms/apps actions (handles auth + API details internally)
+const _getOrCreateCart = createServerFn({ method: "POST" })
+  .inputValidator((data: { orderFormId?: string }) => data)
+  .handler(async ({ data }): Promise<any> => {
+    const result = await getOrCreateCart(data.orderFormId);
+    return (result as any).data;
   });
 
-export const updateCartItems = createServerFn({ method: "POST" })
-  .validator((data: { orderFormId: string; items: any[] }) => data)
-  .handler(async ({ data }) => {
-    const res = await fetch(
-      `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${data.orderFormId}/items/update`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
-        body: JSON.stringify({ orderItems: data.items }),
-      },
-    );
-    return res.json();
-  });
+export const invoke = {
+  vtex: { actions: { getOrCreateCart: _getOrCreateCart } },
+} as const;
 ```
 
 ### Hook (~/hooks/useCart.ts)

package/.cursor/skills/deco-to-tanstack-migration/references/server-functions/README.md

@@ -0,0 +1,120 @@
+# Server Functions (`createServerFn`)
+
+All VTEX API calls that need credentials (cart, MasterData, session, newsletter, shipping simulation) must run on the Worker — not on the client — to avoid CORS errors and keep secrets server-side.
+
+## Pattern: `src/server/invoke.ts`
+
+Create a single file that wraps `@decocms/apps` invoke functions in `createServerFn`. This keeps VTEX credentials inside the Worker and gives type-safe RPC from the browser.
+
+```typescript
+import { createServerFn } from "@tanstack/react-start";
+import {
+  getOrCreateCart,
+  addItemsToCart,
+  updateCartItems,
+  addCouponToCart,
+  updateOrderFormAttachment,
+  simulateCart,
+} from "@decocms/apps/vtex/actions/checkout";
+
+// CRITICAL: always chain .inputValidator() before .handler()
+// Without it, ctx.data is typed as `undefined` and every access fails.
+const _getOrCreateCart = createServerFn({ method: "POST" })
+  .inputValidator((data: { orderFormId?: string }) => data)
+  .handler(async ({ data }): Promise<any> => {
+    // Promise<any> bypasses ValidateSerializable on OrderForm.storeId: unknown
+    const result = await getOrCreateCart(data.orderFormId);
+    return (result as any).data;
+  });
+
+const _addItemsToCart = createServerFn({ method: "POST" })
+  .inputValidator((data: {
+    orderFormId: string;
+    orderItems: Array<{ id: string; seller: string; quantity: number }>;
+  }) => data)
+  .handler(async ({ data }): Promise<any> => {
+    const result = await addItemsToCart(data.orderFormId, data.orderItems);
+    return (result as any).data;
+  });
+
+// ... repeat for updateCartItems, addCouponToCart, simulateCart, etc.
+
+export const invoke = {
+  vtex: {
+    actions: {
+      getOrCreateCart: _getOrCreateCart,
+      addItemsToCart: _addItemsToCart,
+      // ...
+    },
+  },
+} as const;
+```
+
+## Required: `.inputValidator()`
+
+Without `.inputValidator()`, TanStack Start types `ctx.data` as `undefined`:
+
+```typescript
+// BROKEN — ctx.data is typed as undefined
+createServerFn({ method: "POST" })
+  .handler(async (ctx) => {
+    ctx.data.orderFormId; // TS Error: ctx.data is undefined
+  });
+
+// CORRECT
+createServerFn({ method: "POST" })
+  .inputValidator((data: { orderFormId: string }) => data)
+  .handler(async ({ data }) => {
+    data.orderFormId; // typed correctly
+  });
+```
+
+## Required: `Promise<any>` Return Type
+
+TanStack Start validates that return types are serializable via `ValidateSerializable`. Types with `unknown` fields (e.g. `OrderForm.storeId: unknown`) fail this check at compile time:
+
+```
+Type 'OrderForm' does not satisfy the constraint 'Serializable'.
+  Types of property 'storeId' are incompatible.
+    Type 'unknown' is not assignable to type 'Serializable'
+```
+
+**Fix**: Annotate the handler return as `Promise<any>`:
+
+```typescript
+.handler(async ({ data }): Promise<any> => {
+  return await doSomething(data);
+});
+```
+
+## Stripping Non-Serializable Properties
+
+Loader results that include function properties must have those functions removed before being returned — Seroval (TanStack's hydration serializer) cannot serialize functions.
+
+```typescript
+.handler(async ({ data }): Promise<any> => {
+  const result = await productReviewsLoader(data);
+  // Strip functions before serialization
+  const { getProductReview: _r, reviewLikeAction: _l, ...serializable } = result as any;
+  return serializable;
+});
+```
+
+## Invoke from `useCart`
+
+```typescript
+// ~/hooks/useCart.ts
+import { invoke } from "~/server/invoke";
+
+const updated = await invoke.vtex.actions.addItemsToCart({
+  data: { orderFormId, orderItems },
+});
+```
+
+## Verification
+
+```bash
+# No direct VTEX API calls from client components
+rg 'vtexcommercestable\.com\.br' src/ --include='*.tsx'
+# Should return ZERO (all calls go through invoke)
+```

package/README.md

@@ -0,0 +1,84 @@
+# @decocms/start
+
+[![npm version](https://img.shields.io/npm/v/@decocms/start.svg)](https://www.npmjs.com/package/@decocms/start)
+[![license](https://img.shields.io/npm/l/@decocms/start.svg)](https://github.com/decocms/deco-start/blob/main/LICENSE)
+
+Framework layer for [Deco](https://deco.cx) storefronts built on **TanStack Start + React 19 + Cloudflare Workers**.
+
+Provides CMS block resolution, admin protocol handlers, section rendering, schema generation, edge caching, and SDK utilities. This is **not** a storefront — it's the npm package that storefronts depend on.
+
+## Install
+
+```bash
+npm install @decocms/start
+```
+
+## Architecture
+
+```
+@decocms/start        ← Framework (this package)
+  └─ @decocms/apps    ← Commerce integrations (VTEX, Shopify)
+       └─ site repo   ← UI components, routes, styles
+```
+
+### Package Exports
+
+| Import | Purpose |
+|--------|---------|
+| `@decocms/start` | Barrel export |
+| `@decocms/start/cms` | Block loading, page resolution, section registry |
+| `@decocms/start/admin` | Admin protocol (meta, decofile, invoke, render, schema) |
+| `@decocms/start/hooks` | DecoPageRenderer, LiveControls, LazySection |
+| `@decocms/start/routes` | CMS route config, admin routes |
+| `@decocms/start/middleware` | Observability, deco state, liveness probe |
+| `@decocms/start/sdk/workerEntry` | Cloudflare Worker entry with edge caching |
+| `@decocms/start/sdk/cacheHeaders` | URL-to-profile cache detection |
+| `@decocms/start/sdk/cachedLoader` | In-flight dedup for loaders |
+| `@decocms/start/sdk/useScript` | Inline `<script>` with minification |
+| `@decocms/start/sdk/useDevice` | SSR-safe device detection |
+| `@decocms/start/sdk/analytics` | Analytics event types |
+| `@decocms/start/matchers/*` | Feature flag matchers (PostHog, built-ins) |
+| `@decocms/start/types` | Section, App, FnContext type definitions |
+| `@decocms/start/scripts/*` | Code generation (blocks, schema, invoke) |
+
+### Worker Entry Request Flow
+
+```
+Request → createDecoWorkerEntry()
+ ├─ Admin routes (/live/_meta, /.decofile, /deco/render, /deco/invoke)
+ ├─ Cache purge check
+ ├─ Static asset bypass (/assets/*, favicon)
+ ├─ Cloudflare edge cache (profile-based TTLs)
+ └─ TanStack Start server entry
+```
+
+### Edge Cache Profiles
+
+| URL Pattern | Profile | Edge TTL |
+|-------------|---------|----------|
+| `/` | static | 1 day |
+| `*/p` | product | 5 min |
+| `/s`, `?q=` | search | 60s |
+| `/cart`, `/checkout` | private | none |
+| Everything else | listing | 2 min |
+
+## Peer Dependencies
+
+- `@tanstack/react-start` >= 1.0.0
+- `@tanstack/store` >= 0.7.0
+- `react` ^19.0.0
+- `react-dom` ^19.0.0
+
+## Development
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm run lint        # biome check
+npm run check       # typecheck + lint + unused exports
+```
+
+This is a library — no dev server. Consumer sites run their own `vite dev`.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.20.2",
+  "version": "0.21.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/admin/schema.ts

@@ -238,6 +238,110 @@ registerMatcherSchemas([
       },
     },
   },
+  {
+    key: "website/matchers/location.ts",
+    title: "Location",
+    namespace: "website",
+    propsSchema: {
+      type: "object",
+      properties: {
+        includeLocations: {
+          type: "array",
+          title: "Include Locations",
+          items: {
+            type: "object",
+            properties: {
+              country: { type: "string", title: "Country" },
+              regionCode: { type: "string", title: "Region" },
+              city: { type: "string", title: "City" },
+            },
+          },
+        },
+        excludeLocations: {
+          type: "array",
+          title: "Exclude Locations",
+          items: {
+            type: "object",
+            properties: {
+              country: { type: "string", title: "Country" },
+              regionCode: { type: "string", title: "Region" },
+              city: { type: "string", title: "City" },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    key: "website/matchers/userAgent.ts",
+    title: "User Agent",
+    namespace: "website",
+    propsSchema: {
+      type: "object",
+      properties: {
+        includes: { type: "string", title: "Includes (substring)" },
+        match: { type: "string", title: "Match (regex)" },
+      },
+    },
+  },
+  {
+    key: "website/matchers/environment.ts",
+    title: "Environment",
+    namespace: "website",
+    propsSchema: {
+      type: "object",
+      properties: {
+        environment: {
+          type: "string",
+          title: "Environment",
+          enum: ["production", "development"],
+        },
+      },
+    },
+  },
+  {
+    key: "website/matchers/multi.ts",
+    title: "Multi (AND/OR)",
+    namespace: "website",
+    propsSchema: {
+      type: "object",
+      properties: {
+        op: {
+          type: "string",
+          title: "Operator",
+          enum: ["and", "or"],
+          default: "and",
+        },
+        matchers: {
+          type: "array",
+          title: "Matchers",
+          items: {
+            type: "object",
+            required: ["__resolveType"],
+            properties: { __resolveType: { type: "string" } },
+            additionalProperties: true,
+          },
+        },
+      },
+    },
+  },
+  {
+    key: "website/matchers/negate.ts",
+    title: "Negate (NOT)",
+    namespace: "website",
+    propsSchema: {
+      type: "object",
+      properties: {
+        matcher: {
+          type: "object",
+          title: "Matcher",
+          required: ["__resolveType"],
+          properties: { __resolveType: { type: "string" } },
+          additionalProperties: true,
+        },
+      },
+    },
+  },
 ]);
 
 function buildLoaderDefinitions() {

package/src/cms/index.ts

@@ -35,6 +35,7 @@ export type {
 } from "./resolve";
 export {
   addSkipResolveType,
+  evaluateMatcher,
   getAsyncRenderingConfig,
   onBeforeResolve,
   registerCommerceLoader,

package/src/cms/registry.ts

@@ -132,16 +132,61 @@ export async function preloadSectionComponents(keys: string[]): Promise<void> {
   );
 }
 
+/**
+ * A sync section entry: either a plain component reference or a full module
+ * object with optional LoadingFallback and ErrorFallback.
+ * Providing the full module allows DeferredSectionWrapper to show the correct
+ * skeleton immediately (optionsReady=true on first render) without waiting for
+ * the async preloadSectionModule() call.
+ */
+export type SyncSectionEntry =
+  | ComponentType<any>
+  | {
+      default: ComponentType<any>;
+      LoadingFallback?: ComponentType<any>;
+      ErrorFallback?: ComponentType<{ error: Error }>;
+    };
+
 /**
  * Register sections with their already-imported component references.
  * These are available synchronously on both server and client — no dynamic
  * import, no React.lazy, no Suspense. Use for critical above-the-fold
  * sections that must never flash during hydration.
+ *
+ * Accepts either a plain component or a full module object (with optional
+ * LoadingFallback / ErrorFallback). Providing the module object populates
+ * sectionOptions immediately, so DeferredSectionWrapper can show the correct
+ * skeleton without an extra async preloadSectionModule() round-trip.
  */
-export function registerSectionsSync(sections: Record<string, ComponentType<any>>): void {
-  for (const [key, component] of Object.entries(sections)) {
+export function registerSectionsSync(sections: Record<string, SyncSectionEntry>): void {
+  for (const [key, entry] of Object.entries(sections)) {
+    const raw = typeof entry === "function" ? entry : (entry as any).default;
+    // Accept functions and React wrapper objects (React.memo, forwardRef, lazy)
+    const REACT_WRAPPERS = [
+      Symbol.for("react.memo"),
+      Symbol.for("react.forward_ref"),
+      Symbol.for("react.lazy"),
+    ];
+    const component =
+      typeof raw === "function" ||
+      (raw != null &&
+        typeof raw === "object" &&
+        REACT_WRAPPERS.includes((raw as any).$$typeof))
+        ? raw
+        : undefined;
+    if (!component) {
+      console.warn(`[registerSectionsSync] "${key}" has no callable default export — skipping`);
+      continue;
+    }
     syncComponents[key] = component;
     resolvedComponents[key] = component;
+
+    if (typeof entry !== "function") {
+      const opts: SectionOptions = { ...sectionOptions[key] };
+      if (entry.LoadingFallback) opts.loadingFallback = entry.LoadingFallback;
+      if (entry.ErrorFallback) opts.errorFallback = entry.ErrorFallback;
+      sectionOptions[key] = opts;
+    }
   }
 }
 

package/src/cms/resolve.ts

@@ -237,7 +237,7 @@ function ensureInitialized() {
 // Matcher evaluation
 // ---------------------------------------------------------------------------
 
-function evaluateMatcher(rule: Record<string, unknown> | undefined, ctx: MatcherContext): boolean {
+export function evaluateMatcher(rule: Record<string, unknown> | undefined, ctx: MatcherContext): boolean {
   if (!rule) return true;
 
   const resolveType = rule.__resolveType as string | undefined;

package/src/hooks/DecoPageRenderer.tsx

@@ -81,6 +81,40 @@ import { isDevMode } from "../sdk/env";
 
 const isDev = isDevMode();
 
+// ---------------------------------------------------------------------------
+// Deferred section data cache — persists resolved section props across SPA
+// navigations so navigating back to a page doesn't re-fetch already-loaded
+// sections. TTL is aligned with cmsRouteConfig staleTime (5 min prod / 5s dev).
+// ---------------------------------------------------------------------------
+
+const DEFERRED_CACHE_TTL = isDev ? 5_000 : 5 * 60 * 1000;
+
+interface DeferredCacheEntry {
+  section: ResolvedSection;
+  ts: number;
+}
+
+const deferredSectionCache = new Map<string, DeferredCacheEntry>();
+
+function getCachedDeferredSection(stableKey: string): ResolvedSection | null {
+  const entry = deferredSectionCache.get(stableKey);
+  if (!entry) return null;
+  if (Date.now() - entry.ts > DEFERRED_CACHE_TTL) {
+    deferredSectionCache.delete(stableKey);
+    return null;
+  }
+  return entry.section;
+}
+
+/** Fast DJB2 hash for cache key differentiation. */
+function djb2(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+
 const DEFERRED_FADE_CSS = `@keyframes decoFadeIn{from{opacity:0}to{opacity:1}}`;
 
 function FadeInStyle() {
@@ -191,8 +225,11 @@ function DeferredSectionWrapper({
   errorFallback,
   loadFn,
 }: DeferredSectionWrapperProps) {
-  const stableKey = `${pagePath}::${deferred.component}::${deferred.index}`;
-  const [section, setSection] = useState<ResolvedSection | null>(null);
+  const propsHash = djb2(JSON.stringify(deferred.rawProps));
+  const stableKey = `${pagePath}::${deferred.component}::${deferred.index}::${propsHash}`;
+  const [section, setSection] = useState<ResolvedSection | null>(() =>
+    typeof document === "undefined" ? null : getCachedDeferredSection(stableKey),
+  );
   const [error, setError] = useState<Error | null>(null);
   const [loadedOptions, setLoadedOptions] = useState<SectionOptions | undefined>(() =>
     getSectionOptions(deferred.component),
@@ -208,7 +245,8 @@ function DeferredSectionWrapper({
   if (prevKeyRef.current !== stableKey) {
     prevKeyRef.current = stableKey;
     triggered.current = false;
-    if (section) setSection(null);
+    const cached = getCachedDeferredSection(stableKey);
+    if (section !== cached) setSection(cached);
     if (error) setError(null);
   }
 
@@ -240,12 +278,16 @@ function DeferredSectionWrapper({
 
     if (typeof IntersectionObserver === "undefined") {
       triggered.current = true;
+      const key0 = stableKey;
       loadFn({
         component: deferred.component,
         rawProps: deferred.rawProps,
         pagePath,
       })
-        .then(setSection)
+        .then((result) => {
+          if (result) deferredSectionCache.set(key0, { section: result, ts: Date.now() });
+          setSection(result);
+        })
         .catch((e) => setError(e));
       return;
     }
@@ -255,12 +297,16 @@ function DeferredSectionWrapper({
         if (entry?.isIntersecting && !triggered.current) {
           triggered.current = true;
           observer.disconnect();
+          const key1 = stableKey;
           loadFn({
             component: deferred.component,
             rawProps: deferred.rawProps,
             pagePath,
           })
-            .then(setSection)
+            .then((result) => {
+              if (result) deferredSectionCache.set(key1, { section: result, ts: Date.now() });
+              setSection(result);
+            })
             .catch((e) => setError(e));
         }
       },

package/src/matchers/builtins.ts

@@ -3,7 +3,8 @@
  *
  * These augment the matchers already handled inline in resolve.ts
  * (always, never, device, random, utm) with the additional matchers
- * that deco supported: cookie, cron, host, pathname, queryString.
+ * that deco supported: cookie, cron, host, pathname, queryString,
+ * location, userAgent, environment, multi, negate.
  *
  * Register these at startup:
  *
@@ -15,7 +16,7 @@
  */
 
 import type { MatcherContext } from "../cms/resolve";
-import { registerMatcher } from "../cms/resolve";
+import { evaluateMatcher, registerMatcher } from "../cms/resolve";
 
 // -------------------------------------------------------------------------
 // Cookie matcher
@@ -163,6 +164,175 @@ function queryStringMatcher(rule: Record<string, unknown>, ctx: MatcherContext):
   }
 }
 
+// -------------------------------------------------------------------------
+// Location matcher
+// -------------------------------------------------------------------------
+
+/**
+ * CF country codes -> CMS country name mapping.
+ * The CMS stores country as full names ("Brasil"), CF provides ISO codes ("BR").
+ */
+const COUNTRY_NAME_TO_CODE: Record<string, string> = {
+  Brasil: "BR", Brazil: "BR",
+  Argentina: "AR", Chile: "CL",
+  Colombia: "CO", Mexico: "MX", "México": "MX",
+  Peru: "PE", "Perú": "PE",
+  Uruguay: "UY", Paraguay: "PY",
+  Bolivia: "BO", Ecuador: "EC",
+  Venezuela: "VE",
+  "United States": "US", USA: "US",
+  "Estados Unidos": "US",
+  Spain: "ES", "España": "ES",
+  Portugal: "PT",
+  Canada: "CA", "Canadá": "CA",
+  Germany: "DE", Alemania: "DE", Deutschland: "DE",
+  France: "FR", Francia: "FR",
+  Italy: "IT", Italia: "IT",
+  "United Kingdom": "GB", UK: "GB",
+  Japan: "JP", "Japón": "JP",
+  China: "CN",
+  Australia: "AU",
+  "South Korea": "KR",
+  India: "IN",
+  Netherlands: "NL",
+  Switzerland: "CH",
+  Sweden: "SE",
+  Norway: "NO",
+  Denmark: "DK",
+  Finland: "FI",
+  Belgium: "BE",
+  Austria: "AT",
+  Ireland: "IE",
+  "New Zealand": "NZ",
+  "South Africa": "ZA",
+  Israel: "IL",
+  "Saudi Arabia": "SA",
+  "United Arab Emirates": "AE",
+  Turkey: "TR", "Türkiye": "TR",
+  Poland: "PL",
+  "Czech Republic": "CZ", Czechia: "CZ",
+  Romania: "RO",
+  Hungary: "HU",
+  Greece: "GR",
+  Croatia: "HR",
+  "Costa Rica": "CR",
+  Panama: "PA", "Panamá": "PA",
+  "Dominican Republic": "DO",
+  Guatemala: "GT",
+  Honduras: "HN",
+  "El Salvador": "SV",
+  Nicaragua: "NI",
+  Cuba: "CU",
+  "Puerto Rico": "PR",
+};
+
+interface LocationRule {
+  country?: string;
+  regionCode?: string;
+  city?: string;
+}
+
+function matchesLocationRule(
+  loc: LocationRule,
+  regionName: string,
+  regionCode: string,
+  country: string,
+  city: string,
+): boolean {
+  if (loc.country) {
+    const code = COUNTRY_NAME_TO_CODE[loc.country] ?? loc.country;
+    if (code.toUpperCase() !== country.toUpperCase()) return false;
+  }
+  if (loc.regionCode) {
+    // Match against both the short code ("SP") and full name ("São Paulo")
+    // so rules authored against either format continue working.
+    const ruleVal = loc.regionCode.toLowerCase();
+    if (regionCode.toLowerCase() !== ruleVal && regionName.toLowerCase() !== ruleVal) return false;
+  }
+  if (loc.city && loc.city.toLowerCase() !== city.toLowerCase()) return false;
+  return true;
+}
+
+function locationMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const cookies = ctx.cookies ?? {};
+  const regionName = cookies.__cf_geo_region ? decodeURIComponent(cookies.__cf_geo_region) : "";
+  const regionCode = cookies.__cf_geo_region_code ? decodeURIComponent(cookies.__cf_geo_region_code) : "";
+  const country = cookies.__cf_geo_country ? decodeURIComponent(cookies.__cf_geo_country) : "";
+  const city = cookies.__cf_geo_city ? decodeURIComponent(cookies.__cf_geo_city) : "";
+
+  const includeLocations = rule.includeLocations as LocationRule[] | undefined;
+  const excludeLocations = rule.excludeLocations as LocationRule[] | undefined;
+
+  if (excludeLocations?.some((loc) => matchesLocationRule(loc, regionName, regionCode, country, city))) {
+    return false;
+  }
+  if (includeLocations?.length) {
+    return includeLocations.some((loc) => matchesLocationRule(loc, regionName, regionCode, country, city));
+  }
+  return true;
+}
+
+// -------------------------------------------------------------------------
+// User Agent matcher
+// -------------------------------------------------------------------------
+
+function userAgentMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const ua = ctx.userAgent ?? "";
+  const includes = rule.includes as string | undefined;
+  const match = rule.match as string | undefined;
+
+  if (includes && !ua.includes(includes)) return false;
+  if (match) {
+    if (!isSafePattern(match)) return false;
+    try {
+      if (!new RegExp(match, "i").test(ua)) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+// -------------------------------------------------------------------------
+// Environment matcher
+// -------------------------------------------------------------------------
+
+function environmentMatcher(rule: Record<string, unknown>, _ctx: MatcherContext): boolean {
+  const environment = rule.environment as string | undefined;
+  if (!environment) return true;
+
+  const isProd =
+    typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+
+  if (environment === "production") return isProd;
+  if (environment === "development") return !isProd;
+  return false;
+}
+
+// -------------------------------------------------------------------------
+// Multi matcher (AND/OR combinator)
+// -------------------------------------------------------------------------
+
+function multiMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const op = (rule.op as string) ?? "and";
+  const matchers = rule.matchers as Array<Record<string, unknown>> | undefined;
+
+  if (!matchers?.length) return true;
+
+  const results = matchers.map((m) => evaluateMatcher(m, ctx));
+  return op === "or" ? results.some(Boolean) : results.every(Boolean);
+}
+
+// -------------------------------------------------------------------------
+// Negate matcher
+// -------------------------------------------------------------------------
+
+function negateMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const matcher = rule.matcher as Record<string, unknown> | undefined;
+  if (!matcher) return false;
+  return !evaluateMatcher(matcher, ctx);
+}
+
 // -------------------------------------------------------------------------
 // Registration
 // -------------------------------------------------------------------------
@@ -181,4 +351,9 @@ export function registerBuiltinMatchers(): void {
   registerMatcher("website/matchers/host.ts", hostMatcher);
   registerMatcher("website/matchers/pathname.ts", pathnameMatcher);
   registerMatcher("website/matchers/queryString.ts", queryStringMatcher);
+  registerMatcher("website/matchers/location.ts", locationMatcher);
+  registerMatcher("website/matchers/userAgent.ts", userAgentMatcher);
+  registerMatcher("website/matchers/environment.ts", environmentMatcher);
+  registerMatcher("website/matchers/multi.ts", multiMatcher);
+  registerMatcher("website/matchers/negate.ts", negateMatcher);
 }

package/src/sdk/workerEntry.ts

@@ -274,6 +274,48 @@ function buildPreviewShell(): string {
 </html>`;
 }
 
+// ---------------------------------------------------------------------------
+// Cloudflare geo cookie injection
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject Cloudflare geo data as cookies so matchers (location.ts) can
+ * read them from MatcherContext.cookies without relying on request.cf.
+ *
+ * Call this on the incoming request before passing it to the worker entry.
+ * Only needed in production Cloudflare Workers where `request.cf` is populated.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   async fetch(request, env, ctx) {
+ *     return handler.fetch(injectGeoCookies(request), env, ctx);
+ *   }
+ * };
+ * ```
+ */
+export function injectGeoCookies(request: Request): Request {
+  const cf = (request as unknown as { cf?: Record<string, string> }).cf;
+  if (!cf) return request;
+
+  const parts: string[] = [];
+  if (cf.region) parts.push(`__cf_geo_region=${encodeURIComponent(cf.region)}`);
+  if (cf.country) parts.push(`__cf_geo_country=${encodeURIComponent(cf.country)}`);
+  if (cf.city) parts.push(`__cf_geo_city=${encodeURIComponent(cf.city)}`);
+  if (cf.latitude) parts.push(`__cf_geo_lat=${encodeURIComponent(cf.latitude)}`);
+  if (cf.longitude) parts.push(`__cf_geo_lng=${encodeURIComponent(cf.longitude)}`);
+  if (cf.regionCode) parts.push(`__cf_geo_region_code=${encodeURIComponent(cf.regionCode)}`);
+
+  if (!parts.length) return request;
+
+  const existing = request.headers.get("cookie") ?? "";
+  const combined = existing ? `${existing}; ${parts.join("; ")}` : parts.join("; ");
+  const headers = new Headers(request.headers);
+  headers.set("cookie", combined);
+
+  return new Request(request, { headers });
+}
+
 const MOBILE_RE = /mobile|android|iphone|ipad|ipod/i;
 const ONE_YEAR = 31536000;
 
@@ -371,6 +413,19 @@ export function createDecoWorkerEntry(
       }
     }
 
+    // Include CF geo data in cache key so location matcher results don't leak
+    // across different geos. Applies to both segment and device-based keys.
+    const cf = (request as unknown as { cf?: Record<string, string> }).cf;
+    if (cf) {
+      const geoParts: string[] = [];
+      if (cf.country) geoParts.push(cf.country);
+      if (cf.region) geoParts.push(cf.region);
+      if (cf.city) geoParts.push(cf.city);
+      if (geoParts.length) {
+        url.searchParams.set("__cf_geo", geoParts.join("|"));
+      }
+    }
+
     if (buildSegment) {
       const segment = buildSegment(request);
       url.searchParams.set("__seg", hashSegment(segment));
@@ -397,7 +452,7 @@ export function createDecoWorkerEntry(
       return new Response("Unauthorized", { status: 401 });
     }
 
-    let body: { paths?: string[] };
+    let body: { paths?: string[]; countries?: string[] };
     try {
       body = await request.json();
     } catch {
@@ -409,6 +464,12 @@ export function createDecoWorkerEntry(
       return new Response('Body must include "paths": ["/", "/page"]', { status: 400 });
     }
 
+    // Geo strings to purge location-specific cache variants.
+    // Pass ["BR", "BR|São Paulo|Curitiba", ...] to purge specific geo variants.
+    // Each string must match the __cf_geo param format: "country|region|city".
+    // When omitted, only the non-geo cache entry is purged.
+    const geoVariants = body.countries ?? [];
+
     const cache =
       typeof caches !== "undefined"
         ? ((caches as unknown as { default?: Cache }).default ?? null)
@@ -432,33 +493,44 @@ export function createDecoWorkerEntry(
         ]
       : [];
 
+    // Purge both without geo (non-geo-targeted) and with each specified geo variant
+    const geoKeys: (string | null)[] = [null, ...geoVariants];
+
     for (const p of paths) {
       if (buildSegment && segments.length > 0) {
         for (const seg of segments) {
-          const url = new URL(p, baseUrl);
-          url.searchParams.set("__seg", hashSegment(seg));
-          const key = new Request(url.toString(), { method: "GET" });
-          try {
-            if (await cache.delete(key)) {
-              purged.push(`${p} (${hashSegment(seg)})`);
+          for (const cc of geoKeys) {
+            const url = new URL(p, baseUrl);
+            url.searchParams.set("__seg", hashSegment(seg));
+            if (cc) url.searchParams.set("__cf_geo", cc);
+            const key = new Request(url.toString(), { method: "GET" });
+            try {
+              if (await cache.delete(key)) {
+                const label = cc ? `${p} (${hashSegment(seg)}, ${cc})` : `${p} (${hashSegment(seg)})`;
+                purged.push(label);
+              }
+            } catch {
+              /* ignore */
             }
-          } catch {
-            /* ignore */
           }
         }
       } else {
         const devices = deviceSpecificKeys ? (["mobile", "desktop"] as const) : ([null] as const);
 
         for (const device of devices) {
-          const url = new URL(p, baseUrl);
-          if (device) url.searchParams.set("__cf_device", device);
-          const key = new Request(url.toString(), { method: "GET" });
-          try {
-            if (await cache.delete(key)) {
-              purged.push(device ? `${p} (${device})` : p);
+          for (const cc of geoKeys) {
+            const url = new URL(p, baseUrl);
+            if (device) url.searchParams.set("__cf_device", device);
+            if (cc) url.searchParams.set("__cf_geo", cc);
+            const key = new Request(url.toString(), { method: "GET" });
+            try {
+              if (await cache.delete(key)) {
+                const parts = [device, cc].filter(Boolean).join(", ");
+                purged.push(parts ? `${p} (${parts})` : p);
+              }
+            } catch {
+              /* ignore */
             }
-          } catch {
-            /* ignore */
           }
         }
       }