@decocms/start 1.6.2 → 1.7.0

package/scripts/migrate/transforms/imports.ts

@@ -34,17 +34,25 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"apps\/website\/components\/Picture\.tsx"$/, `"~/components/ui/Picture"`],
   [/^"apps\/website\/components\/Video\.tsx"$/, `"~/components/ui/Video"`],
   [/^"apps\/website\/components\/Theme\.tsx"$/, `"~/components/ui/Theme"`],
+  [/^"apps\/website\/components\/_seo\/[^"]+?"$/, null], // SEO preview — framework-only, remove
   [/^"apps\/website\/components\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/ui/$1"`],
   [/^"apps\/commerce\/types\.ts"$/, `"@decocms/apps/commerce/types"`],
   [/^"apps\/commerce\/mod\.ts"$/, `"~/types/commerce-app"`],
   [/^"apps\/commerce\/types"$/, `"@decocms/apps/commerce/types"`],
 
-  // Apps — VTEX (hooks, utils, actions, loaders, types)
+  // Apps — VTEX hooks: useUser/useCart/useWishlist → local hooks (react-query based @decocms/apps hooks crash Workers SSR)
+  [/^"apps\/vtex\/hooks\/useUser(?:\.ts)?"$/, `"~/hooks/useUser"`],
+  [/^"apps\/vtex\/hooks\/useCart(?:\.ts)?"$/, `"~/hooks/useCart"`],
+  [/^"apps\/vtex\/hooks\/useWishlist(?:\.ts)?"$/, `"~/hooks/useWishlist"`],
   [/^"apps\/vtex\/hooks\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/hooks/$1"`],
+  // Specific VTEX utils that moved to different paths in @decocms/apps
+  [/^"apps\/vtex\/utils\/fetchVTEX(?:\.ts)?"$/, `"@decocms/apps/vtex/client"`],
+  [/^"apps\/vtex\/utils\/client(?:\.ts)?"$/, `"@decocms/apps/vtex/client"`],
   [/^"apps\/vtex\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/utils/$1"`],
   [/^"apps\/vtex\/actions\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/actions/$1"`],
   [/^"apps\/vtex\/loaders\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/loaders/$1"`],
   [/^"apps\/vtex\/types(?:\.ts)?"$/, `"@decocms/apps/vtex/types"`],
+  [/^"apps\/vtex\/mod(?:\.ts)?"$/, `"~/types/vtex-app"`],
   // Apps — Shopify (hooks, utils, actions, loaders)
   [/^"apps\/shopify\/hooks\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/shopify/hooks/$1"`],
   [/^"apps\/shopify\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/shopify/utils/$1"`],
@@ -54,48 +62,72 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"apps\/commerce\/sdk\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/commerce/sdk/$1"`],
   [/^"apps\/commerce\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/commerce/utils/$1"`],
 
+  // Apps — shared utils (STALE, fetchSafe, createHttpClient, etc.)
+  [/^"apps\/utils\/fetch(?:\.ts)?"$/, `"~/lib/fetch-utils"`],
+  [/^"apps\/utils\/http(?:\.ts)?"$/, `"~/lib/http-utils"`],
+  [/^"apps\/utils\/graphql(?:\.ts)?"$/, `"~/lib/graphql-utils"`],
+
   // Apps — catch-all (things like apps/website/mod.ts, apps/analytics/mod.ts, etc.)
   [/^"apps\/([^"]+)"$/, null], // Remove — site.ts is rewritten
 
   // Deco old CDN imports
   [/^"deco\/([^"]+)"$/, null],
 
+  // Remote URL imports (esm.sh, cdn.esm.sh, skypack, etc.) — remove
+  [/^"https?:\/\/esm\.sh\/[^"]*"$/, null],
+  [/^"https?:\/\/cdn\.esm\.sh\/[^"]*"$/, null],
+  [/^"https?:\/\/cdn\.skypack\.dev\/[^"]*"$/, null],
+  [/^"https?:\/\/deno\.land\/[^"]*"$/, null],
+
   // Std lib — redirect useful utils, remove the rest
   [/^"std\/async\/debounce(?:\.ts)?"$/, `"~/sdk/debounce"`],
   [/^"std\/([^"]+)"$/, null],
   [/^"@std\/crypto"$/, null], // Use globalThis.crypto instead
 
   // site/sdk/* → framework equivalents (before the catch-all site/ → ~/ rule)
-  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"~/sdk/clx"`],
+  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
   [/^"site\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
-  [/^"site\/sdk\/useOffer(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useOffer"`],
-  [/^"site\/sdk\/useVariantPossiblities(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useVariantPossibilities"`],
+  // useOffer and useVariantPossiblities kept as site files (~/sdk/)
   [/^"site\/sdk\/usePlatform(?:\.tsx?)?.*"$/, null],
 
-  // $store/account.json → ~/account.json (JSON import with assertion)
-  [/^"\$store\/account\.json"$/, `"~/account.json"`],
-  [/^"site\/account\.json"$/, `"~/account.json"`],
+  // account.json → constants/account (JSON file replaced with TS module in cleanup)
+  [/^"\$store\/account\.json"$/, `"~/constants/account"`],
+  [/^"site\/account\.json"$/, `"~/constants/account"`],
+  [/^"~\/account\.json"$/, `"~/constants/account"`],
 
   // $store/ → ~/ (common Deno import map alias for project root)
-  [/^"\$store\/sdk\/clx(?:\.tsx?)?.*"$/, `"~/sdk/clx"`],
+  [/^"\$store\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
   [/^"\$store\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
-  [/^"\$store\/sdk\/useOffer(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useOffer"`],
+  // useOffer and useVariantPossiblities kept as site files (~/sdk/)
   [/^"\$store\/sdk\/format(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/formatPrice"`],
-  [/^"\$store\/sdk\/useVariantPossiblities(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useVariantPossibilities"`],
   [/^"\$store\/sdk\/usePlatform(?:\.tsx?)?.*"$/, null],
+  // islands → components (must be before $store catch-all)
+  [/^"\$store\/islands\/ui\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/ui/$1"`],
+  [/^"\$store\/islands\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/$1"`],
   [/^"\$store\/(.+)"$/, `"~/$1"`],
 
   // $home/ → ~/ (another common alias)
   [/^"\$home\/(.+)"$/, `"~/$1"`],
 
   // site/ → ~/
-  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"~/sdk/clx"`],
+  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
   [/^"site\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
-  [/^"site\/sdk\/useOffer(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useOffer"`],
+  // useOffer and useVariantPossiblities kept as site files (~/sdk/)
   [/^"site\/sdk\/format(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/formatPrice"`],
-  [/^"site\/sdk\/useVariantPossiblities(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useVariantPossibilities"`],
   [/^"site\/sdk\/usePlatform(?:\.tsx?)?.*"$/, null],
+  // islands → components (must be before site/ catch-all)
+  [/^"site\/islands\/ui\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/ui/$1"`],
+  [/^"site\/islands\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/$1"`],
   [/^"site\/(.+)"$/, `"~/$1"`],
+
+  // ~/islands/* → ~/components/* (catch any that slipped through)
+  [/^"~\/islands\/ui\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/ui/$1"`],
+  [/^"~\/islands\/([^"]+?)(?:\.tsx?)?"$/, `"~/components/$1"`],
+
+  // @decocms/apps hooks → local hooks (react-query hooks crash Workers SSR at module eval)
+  [/^"@decocms\/apps\/vtex\/hooks\/useUser"$/, `"~/hooks/useUser"`],
+  [/^"@decocms\/apps\/vtex\/hooks\/useCart"$/, `"~/hooks/useCart"`],
+  [/^"@decocms\/apps\/vtex\/hooks\/useWishlist"$/, `"~/hooks/useWishlist"`],
 ];
 
 /**
@@ -104,20 +136,21 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
  * The key is the ending of the import path, the value is the replacement specifier.
  */
 const RELATIVE_SDK_REWRITES: Array<[RegExp, string]> = [
-  // sdk/clx → ~/sdk/clx (scaffolded locally with default export)
-  [/(?:\.\.\/)*sdk\/clx(?:\.tsx?)?$/, "~/sdk/clx"],
+  // sdk/clx → @decocms/start/sdk/clx (framework utility)
+  [/(?:\.\.\/)*sdk\/clx(?:\.tsx?)?$/, "@decocms/start/sdk/clx"],
   // sdk/useId → react (useId is built-in in React 19)
   [/(?:\.\.\/)*sdk\/useId(?:\.tsx?)?$/, "react"],
-  // sdk/useOffer → @decocms/apps/commerce/sdk/useOffer
-  [/(?:\.\.\/)*sdk\/useOffer(?:\.tsx?)?$/, "@decocms/apps/commerce/sdk/useOffer"],
+  // sdk/useOffer — kept as-is (sites customize offer logic)
+  // sdk/useVariantPossiblities — kept as-is (sites customize variant logic)
   // sdk/format → @decocms/apps/commerce/sdk/formatPrice
   [/(?:\.\.\/)*sdk\/format(?:\.tsx?)?$/, "@decocms/apps/commerce/sdk/formatPrice"],
-  // sdk/useVariantPossiblities → @decocms/apps/commerce/sdk/useVariantPossibilities
-  [/(?:\.\.\/)*sdk\/useVariantPossiblities(?:\.tsx?)?$/, "@decocms/apps/commerce/sdk/useVariantPossibilities"],
   // sdk/usePlatform → remove entirely
   [/(?:\.\.\/)*sdk\/usePlatform(?:\.tsx?)?$/, ""],
   // static/adminIcons → deleted (icon loaders need rewriting)
   [/(?:\.\.\/)*static\/adminIcons(?:\.ts)?$/, ""],
+  // islands/ui/* → components/ui/* (islands are merged into components)
+  [/(?:\.\.\/)*islands\/ui\/([^"]+?)(?:\.tsx?)?$/, "~/components/ui/$1"],
+  [/(?:\.\.\/)*islands\/([^"]+?)(?:\.tsx?)?$/, "~/components/$1"],
 ];
 
 /**
@@ -132,10 +165,27 @@ const RELATIVE_SDK_REWRITES: Array<[RegExp, string]> = [
  *
  * When a rule maps to null, the entire import line is removed.
  */
-export function transformImports(content: string): TransformResult {
+export function transformImports(
+  content: string,
+  islandWrapperTargets?: Map<string, string>,
+): TransformResult {
   const notes: string[] = [];
   let changed = false;
 
+  // Build dynamic rules from island wrapper targets (wrapper island → actual component)
+  const dynamicRules: Array<[RegExp, string]> = [];
+  if (islandWrapperTargets) {
+    for (const [islandPath, targetImport] of islandWrapperTargets) {
+      const componentPath = islandPath.replace("islands/", "components/").replace(/\.tsx?$/, "");
+      // Match ~/components/X and rewrite to the wrapper's actual target
+      const escaped = componentPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      dynamicRules.push([
+        new RegExp(`^"~/${escaped}"$`),
+        `"${targetImport}"`,
+      ]);
+    }
+  }
+
   // Strip BOM that prevents ^ matching on the first line
   if (content.charCodeAt(0) === 0xfeff) {
     content = content.slice(1);
@@ -180,6 +230,13 @@ export function transformImports(content: string): TransformResult {
     );
   }
 
+  function applyDynamicRules(result: string): string {
+    for (const [dynPattern, dynReplacement] of dynamicRules) {
+      if (dynPattern.test(result)) return dynReplacement;
+    }
+    return result;
+  }
+
   function rewriteSpecifier(specifier: string): string | null {
     // Remove quotes for matching
     const inner = specifier.slice(1, -1);
@@ -187,17 +244,16 @@ export function transformImports(content: string): TransformResult {
     for (const [pattern, replacement] of IMPORT_RULES) {
       if (pattern.test(`"${inner}"`)) {
         if (replacement === null) return null;
-        // Apply regex replacement
         let result = `"${inner}"`.replace(pattern, replacement);
-        // Strip .ts/.tsx extensions from the rewritten path if it's a relative/alias import
-        const resultInner = result.slice(1, -1);
+        let resultInner = result.slice(1, -1);
         if (
           (resultInner.startsWith("~/") || resultInner.startsWith("./") || resultInner.startsWith("../")) &&
           (resultInner.endsWith(".ts") || resultInner.endsWith(".tsx"))
         ) {
-          result = `"${resultInner.replace(/\.tsx?$/, "")}"`;
+          resultInner = resultInner.replace(/\.tsx?$/, "");
+          result = `"${resultInner}"`;
         }
-        return result;
+        return applyDynamicRules(result);
       }
     }
 
@@ -205,8 +261,9 @@ export function transformImports(content: string): TransformResult {
     if (inner.startsWith("./") || inner.startsWith("../")) {
       for (const [pattern, replacement] of RELATIVE_SDK_REWRITES) {
         if (pattern.test(inner)) {
-          if (replacement === "") return null; // remove the import
-          return `"${replacement}"`;
+          if (replacement === "") return null;
+          const resolved = inner.replace(pattern, replacement);
+          return applyDynamicRules(`"${resolved}"`);
         }
       }
     }
@@ -215,7 +272,7 @@ export function transformImports(content: string): TransformResult {
     if (inner.startsWith("npm:")) {
       const cleaned = inner
         .slice(4)
-        .replace(/@[\d^~>=<.*]+$/, ""); // strip version
+        .replace(/@[\d^~>=<.*]+$/, "");
       return `"${cleaned}"`;
     }
 
@@ -226,7 +283,7 @@ export function transformImports(content: string): TransformResult {
       (inner.endsWith(".ts") || inner.endsWith(".tsx"))
     ) {
       const stripped = inner.replace(/\.tsx?$/, "");
-      return `"${stripped}"`;
+      return applyDynamicRules(`"${stripped}"`);
     }
 
     return specifier;
@@ -247,7 +304,13 @@ export function transformImports(content: string): TransformResult {
     if (newSpec !== specifier) {
       changed = true;
       notes.push(`Rewrote: ${specifier} → ${newSpec}`);
-      return `${prefix}${newSpec}${suffix}`;
+      // Strip import assertions (with/assert { type: "json" }) when the
+      // specifier no longer points to a JSON file (e.g. account.json → constants/account)
+      let cleanSuffix = suffix;
+      if (specifier.includes(".json") && !newSpec.includes(".json")) {
+        cleanSuffix = cleanSuffix.replace(/\s*(?:with|assert)\s*\{[^}]*\}\s*/, "");
+      }
+      return `${prefix}${newSpec}${cleanSuffix}`;
     }
     return `${prefix}${specifier}${suffix}`;
   }

package/scripts/migrate/transforms/jsx.ts

@@ -1,5 +1,17 @@
 import type { TransformResult } from "../types.ts";
 
+/**
+ * Convert JSX attribute syntax to object literal entries.
+ * e.g. `page={page}` → `page`, `foo={bar.baz}` → `foo: bar.baz`, `label="hi"` → `label: "hi"`
+ */
+function jsxAttrsToObjectEntries(jsxAttrs: string): string {
+  return jsxAttrs
+    .replace(/(\w+)=\{(\1)\}/g, "$1") // shorthand: name={name} → name
+    .replace(/(\w+)=\{([^}]+)\}/g, "$1: $2") // name={expr} → name: expr
+    .replace(/(\w+)="([^"]*)"/g, '$1: "$2"') // name="str" → name: "str"
+    .replace(/(\w+)='([^']*)'/g, "$1: '$2'"); // name='str' → name: 'str'
+}
+
 /**
  * Transforms Preact JSX patterns to React JSX patterns.
  *
@@ -32,11 +44,23 @@ export function transformJsx(content: string): TransformResult {
     changed = true;
   }
 
-  // onInput= → onChange=
+  // onInput= → onChange= (React onChange fires on every keystroke, like Preact onInput)
   if (result.includes("onInput=")) {
-    result = result.replace(/onInput=/g, "onChange=");
-    changed = true;
-    notes.push("Replaced onInput= with onChange=");
+    if (result.includes("onChange=") && result.includes("onInput=")) {
+      // Both exist — remove onInput blocks to avoid duplicate JSX attributes.
+      // onInput is redundant in React since onChange already fires on every keystroke.
+      // Match onInput={...handler...} including multi-line arrow functions
+      result = result.replace(
+        /\s*onInput=\{[^{}]*(?:\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}[^{}]*)*\}/g,
+        ""
+      );
+      changed = true;
+      notes.push("Removed onInput= (redundant with existing onChange= in React)");
+    } else {
+      result = result.replace(/onInput=/g, "onChange=");
+      changed = true;
+      notes.push("Replaced onInput= with onChange=");
+    }
   }
 
   // for= → htmlFor= in JSX (label elements)
@@ -229,6 +253,57 @@ export function transformJsx(content: string): TransformResult {
     notes.push("Removed data-fresh-disable-lock attribute (Fresh-specific)");
   }
 
+  // Replace <x.Component {...x.props} /> with <SectionRenderer section={x} />
+  // In TanStack Start, nested sections have Component as a string key, not a function.
+  // SectionRenderer from @decocms/start/hooks handles the lazy registry lookup.
+  //
+  // Gate on ANY variant of the .Component/.props pattern (simple, extra props, or multi-line).
+  const sectionPatternGate = /\.\s*Component[\s\n]+\{\.\.\.(\w+)\.props\}/;
+  if (sectionPatternGate.test(result)) {
+    // 1. Simple: <x.Component {...x.props} />
+    result = result.replace(
+      /<(\w+)\.Component\s+\{\.\.\.(\w+)\.props\}\s*\/>/g,
+      (_, v1) => `<SectionRenderer section={${v1}} />`,
+    );
+
+    // 2. Extra props: <x.Component {...x.props} page={page} />
+    //    Convert JSX attrs to object entries: name={expr} → name: expr
+    result = result.replace(
+      /<(\w+)\.Component\s+\{\.\.\.(\w+)\.props\}\s+([^/]+?)\s*\/>/g,
+      (_, varName, _v2, extraJsx) => {
+        const objEntries = jsxAttrsToObjectEntries(extraJsx.trim());
+        return `<SectionRenderer section={{ ...${varName}, props: { ...${varName}.props, ${objEntries} } }} />`;
+      },
+    );
+
+    // 3. Multi-line: <x.Component\n  {...x.props}\n/>
+    result = result.replace(
+      /<(\w+)\.Component\s*\n\s*\{\.\.\.(\w+)\.props\}\s*\n\s*\/>/g,
+      (_, v1) => `<SectionRenderer section={${v1}} />`,
+    );
+
+    // 4. Multi-line with extra props: <x.Component\n {...x.props}\n extra={val}\n/>
+    result = result.replace(
+      /<(\w+)\.Component\s*\n\s*\{\.\.\.(\w+)\.props\}\s*\n\s*([^/]+?)\s*\n\s*\/>/g,
+      (_, varName, _v2, extraJsx) => {
+        const objEntries = jsxAttrsToObjectEntries(extraJsx.trim());
+        return `<SectionRenderer section={{ ...${varName}, props: { ...${varName}.props, ${objEntries} } }} />`;
+      },
+    );
+
+    if (!result.match(/^import\s.*SectionRenderer/m)) {
+      const hooksImportRe = /^import\s+\{([^}]*)\}\s+from\s+["']@decocms\/start\/hooks["'];?$/m;
+      const hooksMatch = result.match(hooksImportRe);
+      if (hooksMatch) {
+        result = result.replace(hooksImportRe, `import { ${hooksMatch[1].trim()}, SectionRenderer } from "@decocms/start/hooks";`);
+      } else {
+        result = `import { SectionRenderer } from "@decocms/start/hooks";\n${result}`;
+      }
+    }
+    changed = true;
+    notes.push("Replaced .Component/.props section pattern with SectionRenderer");
+  }
+
   // Ensure React import exists if we introduced React.* references
   if (
     (result.includes("React.") || result.includes("React,")) &&

package/scripts/migrate/transforms/section-conventions.ts

@@ -7,6 +7,46 @@ import type { TransformResult, SectionMeta } from "../types.ts";
  * These exports are read by generate-sections.ts in @decocms/start
  * to build the sections.gen.ts registry.
  */
+
+const EAGER_SYNC_SECTIONS = new Set([
+  "UtilLinks",
+  "DepartamentList",
+  "ImageGallery",
+  "BannersGrid",
+  "Carousel",
+  "Tipbar",
+  "Live",
+]);
+
+const SYNC_SECTIONS = new Set([
+  "ProductShelf",
+  "ProductShelfTabbed",
+  "ProductShelfGroup",
+  "ProductShelfTopSort",
+  "CouponList",
+  "NotFoundChallenge",
+  "MountedPDP",
+  "BackgroundWrapper",
+  "SearchResult",
+  "LpCartao",
+]);
+
+const LISTING_CACHE_SECTIONS = new Set([
+  "ProductShelf",
+  "ProductShelfTabbed",
+  "ProductShelfGroup",
+  "ProductShelfTimedOffers",
+]);
+
+const STATIC_CACHE_SECTIONS = new Set([
+  "InstagramPosts",
+  "Faq",
+]);
+
+function getSectionBasename(filePath: string): string {
+  return filePath.split("/").pop()?.replace(/\.\w+$/, "") || "";
+}
+
 export function transformSectionConventions(
   content: string,
   sectionMeta: SectionMeta | undefined,
@@ -18,6 +58,7 @@ export function transformSectionConventions(
   const notes: string[] = [];
   let result = content;
   let changed = false;
+  const basename = getSectionBasename(sectionMeta.path);
 
   // Header, footer, theme → eager + sync + layout
   if (sectionMeta.isHeader || sectionMeta.isFooter || sectionMeta.isTheme) {
@@ -31,14 +72,50 @@ export function transformSectionConventions(
       notes.push("Added: export const sync = true");
       changed = true;
     }
-    if (!result.includes("export const layout")) {
+    // Header in golden does NOT have layout=true; only footer+theme do
+    if ((sectionMeta.isFooter || sectionMeta.isTheme) && !result.includes("export const layout")) {
       result += "export const layout = true;\n";
       notes.push("Added: export const layout = true");
       changed = true;
     }
   }
 
-  // Listing sections → cache = "listing"
+  // Known eager+sync sections (non-layout)
+  if (EAGER_SYNC_SECTIONS.has(basename)) {
+    if (!result.includes("export const eager")) {
+      result += "\nexport const eager = true;\n";
+      notes.push(`Added: export const eager = true (${basename})`);
+      changed = true;
+    }
+    if (!result.includes("export const sync")) {
+      result += "export const sync = true;\n";
+      notes.push(`Added: export const sync = true (${basename})`);
+      changed = true;
+    }
+  }
+
+  // Known sync-only sections
+  if (SYNC_SECTIONS.has(basename) && !result.includes("export const sync")) {
+    result += "\nexport const sync = true;\n";
+    notes.push(`Added: export const sync = true (${basename})`);
+    changed = true;
+  }
+
+  // Listing cache sections
+  if (LISTING_CACHE_SECTIONS.has(basename) && !result.includes("export const cache")) {
+    result += '\nexport const cache = "listing";\n';
+    notes.push(`Added: export const cache = "listing" (${basename})`);
+    changed = true;
+  }
+
+  // Static cache sections
+  if (STATIC_CACHE_SECTIONS.has(basename) && !result.includes("export const cache")) {
+    result += '\nexport const cache = "static";\n';
+    notes.push(`Added: export const cache = "static" (${basename})`);
+    changed = true;
+  }
+
+  // Generic: listing sections not already matched above
   if (sectionMeta.isListing && !result.includes("export const cache")) {
     result += '\nexport const cache = "listing";\n';
     notes.push('Added: export const cache = "listing"');
@@ -52,9 +129,34 @@ export function transformSectionConventions(
     changed = true;
   }
 
+  // Sections that render nested Section children need sync so they're in
+  // the syncComponents registry (SectionRenderer resolves the string key).
+  const hasNestedSections =
+    /children:\s*Section\b/.test(result) || /fallback:\s*Section\b/.test(result);
+  if (hasNestedSections && !result.includes("export const sync")) {
+    result += "\nexport const sync = true;\n";
+    notes.push("Added: export const sync = true (renders nested Section children)");
+    changed = true;
+  }
+
+  // Re-export sections that wrap PDP/nested content need sync too.
+  // Detect: file is a re-export AND the target component renders nested Sections
+  const isReExport = /^export\s+\{[^}]*default[^}]*\}\s+from\s+/.test(result.trim());
+  if (isReExport && (basename === "MountedPDP" || basename === "NotFoundChallenge")) {
+    if (!result.includes("export const sync")) {
+      result += "\nexport const sync = true;\n";
+      notes.push(`Added: export const sync = true (re-export: ${basename})`);
+      changed = true;
+    }
+  }
+
+  // Don't add LoadingFallback re-exports to thin section files —
+  // we can't guarantee the target component exports it.
+  // Instead, if it's a listing section, a generic skeleton will be added below.
+
   // Generate a basic LoadingFallback if the section doesn't have one
   // and it's a listing section (visible skeleton improvement)
-  if (sectionMeta.isListing && !sectionMeta.hasLoadingFallback) {
+  if (sectionMeta.isListing && !sectionMeta.hasLoadingFallback && !result.includes("LoadingFallback")) {
     result += `
 export function LoadingFallback() {
   return (

package/scripts/migrate/types.ts

@@ -61,7 +61,9 @@ export type DetectedPattern =
   | "asset-function"
   | "head-component"
   | "define-app"
-  | "invoke-proxy";
+  | "invoke-proxy"
+  | "use-component"
+  | "sections-component-loader";
 
 /** Metadata extracted from a section file during analysis */
 export interface SectionMeta {
@@ -131,6 +133,8 @@ export interface MigrationContext {
   sourceDir: string;
   siteName: string;
   platform: Platform;
+  /** VTEX account name (e.g. "casaevideonewio") — extracted from source code */
+  vtexAccount: string | null;
   gtmId: string | null;
 
   /** deno.json import map entries */
@@ -151,6 +155,8 @@ export interface MigrationContext {
   sectionMetas: SectionMeta[];
   /** Island classifications */
   islandClassifications: IslandClassification[];
+  /** Map from island path → wrapped component import path (for wrapper islands) */
+  islandWrapperTargets: Map<string, string>;
   /** Loader inventory */
   loaderInventory: LoaderInfo[];
 
@@ -191,6 +197,7 @@ export function createContext(
     sourceDir,
     siteName: "",
     platform: "custom",
+    vtexAccount: null,
     gtmId: null,
     importMap: {},
     discoveredNpmDeps: {},
@@ -199,6 +206,7 @@ export function createContext(
     files: [],
     sectionMetas: [],
     islandClassifications: [],
+    islandWrapperTargets: new Map(),
     loaderInventory: [],
     scaffoldedFiles: [],
     transformedFiles: [],

package/src/cms/resolve.ts

@@ -228,7 +228,18 @@ function isBot(userAgent?: string): boolean {
   return botPatterns.some((re) => re.test(userAgent));
 }
 
-export type CommerceLoader = (props: any) => Promise<any>;
+/**
+ * A loader registered against a `__resolveType` key. The runtime invokes it
+ * through two paths:
+ *
+ * 1. CMS resolution (`commerceLoader(resolvedProps)`) — 1-arg call.
+ * 2. `/deco/invoke/...` endpoint — `(props, request)` 2-arg call.
+ *
+ * Loaders that need the `Request` (cookies, geo, headers) declare the second
+ * parameter; pure loaders ignore it. This shape lets a single registry serve
+ * both invocation paths without `as any` casts at every wrapper.
+ */
+export type CommerceLoader = (props: any, request?: Request) => Promise<any>;
 
 /**
  * Context passed through the resolution pipeline.

package/src/sdk/useScript.ts

@@ -137,13 +137,34 @@ export function inlineScript(js: string) {
 }
 
 /**
- * Stub -- Deco partial sections don't apply in TanStack Start.
- * Returns the provided props as-is.
+ * @deprecated Removed in TanStack Start.
+ *
+ * The Fresh/Deno HTMX-based partial-section pattern (`useSection` /
+ * `usePartialSection` + `sections/Component.tsx`) does not apply on
+ * Cloudflare Workers and React. Replace call-sites with one of:
+ *
+ *   1. Local React state (`useState` + event handlers) for client-side toggles.
+ *   2. `createServerFn` + `useMutation` for server actions.
+ *   3. Direct `invoke` calls (`~/server/invoke`) for ad-hoc loaders.
+ *
+ * See: deco-to-tanstack-migration skill, "useComponent / partial sections"
+ * section, for the per-pattern recipes.
+ *
+ * Both stubs throw at runtime (and at import time, if you call them at
+ * module top level) so legacy code surfaces a clear error instead of a
+ * silent no-op.
  */
-export function usePartialSection(props?: Record<string, unknown>) {
-  return props || {};
+const DEPRECATION_MESSAGE =
+  "[@decocms/start] useSection / usePartialSection were removed. " +
+  "The Fresh/Deno HTMX partial-section pattern does not apply on " +
+  "TanStack Start / Cloudflare Workers. Replace call-sites with " +
+  "createServerFn + useMutation, or local React state. See the " +
+  "deco-to-tanstack-migration skill for per-pattern recipes.";
+
+export function usePartialSection(_props?: Record<string, unknown>): never {
+  throw new Error(DEPRECATION_MESSAGE);
 }
 
-export function useSection(_props?: Record<string, unknown>) {
-  return "";
+export function useSection(_props?: Record<string, unknown>): never {
+  throw new Error(DEPRECATION_MESSAGE);
 }

package/src/sdk/workerEntry.ts

@@ -34,7 +34,7 @@ import {
 } from "./cacheHeaders";
 import { buildHtmlShell } from "./htmlShell";
 import { cleanPathForCacheKey } from "./urlUtils";
-import { isMobileUA } from "./useDevice";
+import { type Device, isMobileUA } from "./useDevice";
 import { getRenderShellConfig } from "../admin/setup";
 import { RequestContext } from "./requestContext";
 import { getAppMiddleware } from "./setupApps";
@@ -88,7 +88,16 @@ interface ServerEntry {
  * cache entry; different segments get different cached responses.
  */
 export interface SegmentKey {
-  device: "mobile" | "desktop";
+  /**
+   * Device class derived from the request User-Agent.
+   *
+   * Accepts the full `Device` union (`"mobile" | "desktop" | "tablet"`) so
+   * that callers can pass `detectDevice(...)` directly without manual
+   * narrowing. Sites that want to share cache entries between mobile and
+   * tablet can collapse the value at the call site (e.g.
+   * `device === "tablet" ? "mobile" : device`).
+   */
+  device: Device;
   /** Whether the user is logged in (e.g., has a valid auth cookie). */
   loggedIn?: boolean;
   /** Commerce sales channel / price list. */

package/src/setup.ts

@@ -96,7 +96,7 @@ export interface SiteSetupOptions {
 	 * { getCommerceLoaders: () => COMMERCE_LOADERS }
 	 * ```
 	 */
-	getCommerceLoaders?: () => Record<string, (props: any) => Promise<any>>;
+	getCommerceLoaders?: () => Record<string, (props: any, request?: Request) => Promise<any>>;
 }
 
 /**