@decocms/start 0.22.0 → 0.22.2

package/package.json

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

package/src/cms/resolve.ts

@@ -356,11 +356,16 @@ async function internalResolve(value: unknown, rctx: ResolveContext): Promise<un
   // "resolved" short-circuit
   if (resolveType === "resolved") return obj.data ?? null;
 
-  // Lazy section wrapper
+  // Lazy section wrapper — unwrap single inner section
   if (resolveType === "website/sections/Rendering/Lazy.tsx") {
     return obj.section ? internalResolve(obj.section, childCtx) : null;
   }
 
+  // Deferred section wrapper (legacy Fresh/HTMX) — unwrap inner sections array
+  if (resolveType === "website/sections/Rendering/Deferred.tsx") {
+    return obj.sections ? internalResolve(obj.sections, childCtx) : null;
+  }
+
   // Request param extraction
   if (resolveType === "website/functions/requestToParam.ts") {
     const paramName = (obj as any).param as string;
@@ -609,7 +614,7 @@ function isRawSectionLayout(section: unknown): string | null {
 
 /**
  * Resolve the final section component key by walking block references,
- * unwrapping Lazy wrappers, and evaluating multivariate flags.
+ * unwrapping Lazy/Deferred wrappers, and evaluating multivariate flags.
  * Returns null if not determinable.
  */
 function resolveFinalSectionKey(
@@ -625,6 +630,7 @@ function resolveFinalSectionKey(
     const rt = current.__resolveType as string | undefined;
     if (!rt) return null;
 
+    // Lazy wrapper — unwrap single inner section
     if (rt === "website/sections/Rendering/Lazy.tsx") {
       const inner = current.section;
       if (!inner || typeof inner !== "object") return null;
@@ -632,6 +638,22 @@ function resolveFinalSectionKey(
       continue;
     }
 
+    // Deferred wrapper (legacy) — unwrap first inner section if deterministic
+    if (rt === "website/sections/Rendering/Deferred.tsx") {
+      const inner = current.sections;
+      if (!inner || typeof inner !== "object") return null;
+      if (Array.isArray(inner)) {
+        if (inner.length === 1 && inner[0] && typeof inner[0] === "object") {
+          current = inner[0] as Record<string, unknown>;
+          continue;
+        }
+        return null;
+      }
+      // sections is an object (e.g. a flag) — follow it
+      current = inner as Record<string, unknown>;
+      continue;
+    }
+
     if (
       rt === "website/flags/multivariate.ts" ||
       rt === "website/flags/multivariate/section.ts"
@@ -670,20 +692,61 @@ function resolveFinalSectionKey(
 }
 
 /**
- * Check if a raw CMS section is directly wrapped in `Lazy.tsx`.
- * Checks both the section itself and one level of block reference.
+ * Walk the full wrapper chain (block refs, multivariate flags, Lazy, Deferred)
+ * and return true if a deferral wrapper (Lazy.tsx or Deferred.tsx) is found
+ * at any level. This is used by shouldDeferSection to determine if the CMS
+ * editor intended this section to be deferred.
  */
-function isCmsLazyWrapped(section: unknown): boolean {
+function isCmsDeferralWrapped(section: unknown, matcherCtx?: MatcherContext): boolean {
   if (!section || typeof section !== "object") return false;
-  const obj = section as Record<string, unknown>;
-  const rt = obj.__resolveType as string | undefined;
-  if (!rt) return false;
-
-  if (rt === "website/sections/Rendering/Lazy.tsx") return true;
 
   const blocks = loadBlocks();
-  const block = blocks[rt] as Record<string, unknown> | undefined;
-  if (block && block.__resolveType === "website/sections/Rendering/Lazy.tsx") return true;
+  let current = section as Record<string, unknown>;
+
+  for (let depth = 0; depth < 10; depth++) {
+    const rt = current.__resolveType as string | undefined;
+    if (!rt) return false;
+
+    if (
+      rt === "website/sections/Rendering/Lazy.tsx" ||
+      rt === "website/sections/Rendering/Deferred.tsx"
+    ) {
+      return true;
+    }
+
+    // Walk through multivariate flags to check the matched variant
+    if (
+      rt === "website/flags/multivariate.ts" ||
+      rt === "website/flags/multivariate/section.ts"
+    ) {
+      const variants = current.variants as
+        | Array<{ value: unknown; rule?: unknown }>
+        | undefined;
+      if (!variants?.length) return false;
+
+      let matched: unknown = null;
+      for (const variant of variants) {
+        const rule = variant.rule as Record<string, unknown> | undefined;
+        if (evaluateMatcher(rule, matcherCtx ?? {})) {
+          matched = variant.value;
+          break;
+        }
+      }
+      if (!matched || typeof matched !== "object") return false;
+      current = matched as Record<string, unknown>;
+      continue;
+    }
+
+    // Named block reference — follow the chain
+    const block = blocks[rt] as Record<string, unknown> | undefined;
+    if (block) {
+      const { __resolveType: _, ...overrides } = current;
+      current = { ...block, ...overrides, __resolveType: block.__resolveType as string };
+      continue;
+    }
+
+    return false;
+  }
 
   return false;
 }
@@ -702,19 +765,15 @@ function shouldDeferSection(
   const rt = obj.__resolveType as string | undefined;
   if (!rt) return false;
 
-  // Top-level flags (not wrapped in Lazy) — keep eager for safety
-  if (rt === "website/flags/multivariate.ts" || rt === "website/flags/multivariate/section.ts") {
-    return false;
-  }
-
   const finalKey = resolveFinalSectionKey(section, matcherCtx);
   if (!finalKey) return false;
 
   if (cfg.alwaysEager.has(finalKey)) return false;
   if (isLayoutSection(finalKey)) return false;
 
-  // Primary: respect CMS Lazy wrapper as source of truth
-  if (cfg.respectCmsLazy && isCmsLazyWrapped(section)) return true;
+  // Walk the full wrapper chain (including multivariate flags) to detect
+  // Lazy.tsx or Deferred.tsx wrappers at any nesting level.
+  if (cfg.respectCmsLazy && isCmsDeferralWrapped(section, matcherCtx)) return true;
 
   // Fallback: threshold-based deferral for non-Lazy sections
   if (flatIndex >= cfg.foldThreshold) return true;
@@ -725,7 +784,10 @@ function shouldDeferSection(
 /**
  * Follow the block reference chain to find the final section component
  * and collect the CMS props WITHOUT running commerce loaders.
- * Resolves named block references, lazy wrappers, and multivariate flags.
+ * Resolves named block references, Lazy/Deferred wrappers, and multivariate flags.
+ *
+ * For Deferred.tsx with a single inner section, the inner section is returned.
+ * For Deferred.tsx with multiple inner sections, returns null (falls back to eager).
  */
 function resolveSectionShallow(
   section: unknown,
@@ -751,6 +813,23 @@ function resolveSectionShallow(
       continue;
     }
 
+    // Deferred wrapper (legacy) — unwrap if it contains a single section
+    if (rt === "website/sections/Rendering/Deferred.tsx") {
+      const inner = current.sections;
+      if (!inner || typeof inner !== "object") return null;
+      if (Array.isArray(inner)) {
+        if (inner.length === 1 && inner[0] && typeof inner[0] === "object") {
+          current = inner[0] as Record<string, unknown>;
+          continue;
+        }
+        // Multiple inner sections can't be represented as a single DeferredSection
+        return null;
+      }
+      // sections is an object (e.g. a flag) — follow it
+      current = inner as Record<string, unknown>;
+      continue;
+    }
+
     // Multivariate flags — evaluate matchers and continue with matched variant
     if (
       rt === "website/flags/multivariate.ts" ||

package/src/hooks/DecoPageRenderer.tsx

@@ -265,7 +265,7 @@ function DeferredSectionWrapper({
   const skeleton = !optionsReady
     ? null
     : hasCustomFallback
-      ? createElement(loadedOptions!.loadingFallback!)
+      ? createElement(loadedOptions!.loadingFallback!, deferred.rawProps)
       : (loadingFallback ??
         (isDev ? (
           <DevMissingFallbackWarning component={deferred.component} />

package/src/matchers/builtins.ts

@@ -17,6 +17,7 @@
 
 import type { MatcherContext } from "../cms/resolve";
 import { evaluateMatcher, registerMatcher } from "../cms/resolve";
+import { resolveCountryCode } from "./countryNames";
 
 // -------------------------------------------------------------------------
 // Cookie matcher
@@ -168,106 +169,90 @@ 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;
 }
 
+interface GeoData {
+  country: string;
+  regionCode: string;
+  regionName: string;
+  city: string;
+}
+
+/**
+ * Extract geo data from the request context.
+ * Priority: request.cf (Cloudflare Workers) > geo cookies > geo headers.
+ */
+function getGeoData(ctx: MatcherContext): GeoData {
+  // 1. Cloudflare Workers: request.cf has authoritative geo data
+  const req = ctx.request;
+  if (req) {
+    const cf = (req as any).cf as Record<string, unknown> | undefined;
+    if (cf?.country) {
+      return {
+        country: (cf.country as string) ?? "",
+        regionCode: (cf.regionCode as string) ?? (cf.region as string) ?? "",
+        regionName: (cf.region as string) ?? "",
+        city: (cf.city as string) ?? "",
+      };
+    }
+  }
+
+  // 2. Geo cookies (set by Cloudflare middleware on Fresh/Deno sites)
+  const cookies = ctx.cookies ?? {};
+  const cookieCountry = cookies.__cf_geo_country ? decodeURIComponent(cookies.__cf_geo_country) : "";
+  if (cookieCountry) {
+    return {
+      country: cookieCountry,
+      regionCode: cookies.__cf_geo_region_code ? decodeURIComponent(cookies.__cf_geo_region_code) : "",
+      regionName: cookies.__cf_geo_region ? decodeURIComponent(cookies.__cf_geo_region) : "",
+      city: cookies.__cf_geo_city ? decodeURIComponent(cookies.__cf_geo_city) : "",
+    };
+  }
+
+  // 3. Fallback: standard geo headers (Vercel, etc.)
+  const headers = ctx.headers ?? {};
+  return {
+    country: headers["cf-ipcountry"] ?? headers["x-vercel-ip-country"] ?? "",
+    regionCode: headers["cf-region"] ?? headers["x-vercel-ip-country-region"] ?? "",
+    regionName: "",
+    city: "",
+  };
+}
+
 function matchesLocationRule(
   loc: LocationRule,
-  regionName: string,
-  regionCode: string,
-  country: string,
-  city: string,
+  geo: GeoData,
 ): boolean {
   if (loc.country) {
-    const code = COUNTRY_NAME_TO_CODE[loc.country] ?? loc.country;
-    if (code.toUpperCase() !== country.toUpperCase()) return false;
+    const code = resolveCountryCode(loc.country);
+    if (code.toUpperCase() !== geo.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 (geo.regionCode.toLowerCase() !== ruleVal && geo.regionName.toLowerCase() !== ruleVal) return false;
   }
-  if (loc.city && loc.city.toLowerCase() !== city.toLowerCase()) return false;
+  if (loc.city && loc.city.toLowerCase() !== geo.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 geo = getGeoData(ctx);
+  if (!geo.country) return !((rule.includeLocations as unknown[] | undefined)?.length);
 
   const includeLocations = rule.includeLocations as LocationRule[] | undefined;
   const excludeLocations = rule.excludeLocations as LocationRule[] | undefined;
 
-  if (excludeLocations?.some((loc) => matchesLocationRule(loc, regionName, regionCode, country, city))) {
+  if (excludeLocations?.some((loc) => matchesLocationRule(loc, geo))) {
     return false;
   }
   if (includeLocations?.length) {
-    return includeLocations.some((loc) => matchesLocationRule(loc, regionName, regionCode, country, city));
+    return includeLocations.some((loc) => matchesLocationRule(loc, geo));
   }
   return true;
 }

package/src/matchers/countryNames.ts

@@ -0,0 +1,89 @@
+/**
+ * CMS country name → ISO 3166-1 alpha-2 code mapping.
+ *
+ * The CMS stores countries as full names ("Brasil", "United States").
+ * Cloudflare and other geo providers return ISO codes ("BR", "US").
+ * Keys are case-sensitive as authored in the CMS — callers should
+ * try both the raw value and a case-normalized lookup.
+ */
+export const COUNTRY_NAME_TO_CODE: Record<string, string> = {
+  // Latin America
+  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",
+  "Costa Rica": "CR",
+  Panama: "PA", "Panamá": "PA",
+  "Dominican Republic": "DO",
+  Guatemala: "GT",
+  Honduras: "HN",
+  "El Salvador": "SV",
+  Nicaragua: "NI",
+  Cuba: "CU",
+  "Puerto Rico": "PR",
+
+  // North America
+  "United States": "US", USA: "US", "Estados Unidos": "US",
+  Canada: "CA", "Canadá": "CA",
+
+  // Europe
+  Spain: "ES", "España": "ES",
+  Portugal: "PT",
+  Germany: "DE", Alemania: "DE", Deutschland: "DE",
+  France: "FR", Francia: "FR",
+  Italy: "IT", Italia: "IT",
+  "United Kingdom": "GB", UK: "GB",
+  Netherlands: "NL",
+  Switzerland: "CH",
+  Sweden: "SE",
+  Norway: "NO",
+  Denmark: "DK",
+  Finland: "FI",
+  Belgium: "BE",
+  Austria: "AT",
+  Ireland: "IE",
+  Turkey: "TR", "Türkiye": "TR",
+  Poland: "PL",
+  "Czech Republic": "CZ", Czechia: "CZ",
+  Romania: "RO",
+  Hungary: "HU",
+  Greece: "GR",
+  Croatia: "HR",
+
+  // Asia & Oceania
+  Japan: "JP", "Japón": "JP",
+  China: "CN",
+  "South Korea": "KR",
+  India: "IN",
+  Australia: "AU",
+  "New Zealand": "NZ",
+
+  // Middle East & Africa
+  Israel: "IL",
+  "Saudi Arabia": "SA",
+  "United Arab Emirates": "AE",
+  "South Africa": "ZA",
+};
+
+/**
+ * Resolve a country name (as stored in CMS) to its ISO code.
+ * Tries exact match first, then case-insensitive lookup.
+ */
+export function resolveCountryCode(name: string): string {
+  if (COUNTRY_NAME_TO_CODE[name]) return COUNTRY_NAME_TO_CODE[name];
+
+  const lower = name.toLowerCase();
+  for (const [key, code] of Object.entries(COUNTRY_NAME_TO_CODE)) {
+    if (key.toLowerCase() === lower) return code;
+  }
+
+  // Assume it's already an ISO code
+  return name.toUpperCase();
+}

package/src/routes/cmsRoute.ts

@@ -64,17 +64,19 @@ async function loadCmsPageInternal(fullPath: string) {
         ? new URL(fullPath, serverUrl.origin).toString()
         : serverUrl.toString();
 
+  const originRequest = getRequest();
   const matcherCtx: MatcherContext = {
     userAgent: getRequestHeader("user-agent") ?? "",
     url: urlWithSearch,
     path: basePath,
     cookies: getCookies(),
+    request: originRequest,
   };
   const page = await resolveDecoPage(basePath, matcherCtx);
   if (!page) return null;
 
   const request = new Request(urlWithSearch, {
-    headers: getRequest().headers,
+    headers: originRequest.headers,
   });
   const enrichedSections = await runSectionLoaders(page.resolvedSections, request);
 
@@ -113,16 +115,16 @@ export const loadCmsPage = createServerFn({ method: "GET" })
  * Avoids passing data through the server function for the homepage.
  */
 export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async () => {
+  const request = getRequest();
   const matcherCtx: MatcherContext = {
     userAgent: getRequestHeader("user-agent") ?? "",
     url: getRequestUrl().toString(),
     path: "/",
     cookies: getCookies(),
+    request,
   };
   const page = await resolveDecoPage("/", matcherCtx);
   if (!page) return null;
-
-  const request = getRequest();
   const enrichedSections = await runSectionLoaders(page.resolvedSections, request);
 
   const eagerKeys = enrichedSections.map((s) => s.component);
@@ -147,19 +149,21 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
   .handler(async (ctx) => {
     const { component, rawProps, pagePath, pageUrl } = ctx.data;
 
+    const originRequest = getRequest();
     const serverUrl = getRequestUrl().toString();
     const matcherCtx: MatcherContext = {
       userAgent: getRequestHeader("user-agent") ?? "",
       url: pageUrl || serverUrl,
       path: pagePath,
       cookies: getCookies(),
+      request: originRequest,
     };
 
     const section = await resolveDeferredSection(component, rawProps, pagePath, matcherCtx);
     if (!section) return null;
 
     const request = new Request(pageUrl || serverUrl, {
-      headers: getRequest().headers,
+      headers: originRequest.headers,
     });
     const enriched = await runSingleSectionLoader(section, request);
     return normalizeUrlsInObject(enriched);