@decocms/start 0.21.0 → 0.22.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -31,6 +31,7 @@
     "./sdk/wrapCaughtErrors": "./src/sdk/wrapCaughtErrors.ts",
     "./sdk/csp": "./src/sdk/csp.ts",
     "./sdk/urlUtils": "./src/sdk/urlUtils.ts",
+    "./sdk/normalizeUrls": "./src/sdk/normalizeUrls.ts",
     "./sdk/mergeCacheControl": "./src/sdk/mergeCacheControl.ts",
     "./sdk/requestContext": "./src/sdk/requestContext.ts",
     "./sdk/createInvoke": "./src/sdk/createInvoke.ts",

package/src/cms/registry.ts

@@ -160,7 +160,24 @@ export type SyncSectionEntry =
  */
 export function registerSectionsSync(sections: Record<string, SyncSectionEntry>): void {
   for (const [key, entry] of Object.entries(sections)) {
-    const component = typeof entry === "function" ? entry : entry.default;
+    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;
 

package/src/hooks/DecoPageRenderer.tsx

@@ -209,18 +209,21 @@ export function SectionList({ sections }: { sections: Section[] | null | undefin
 interface DeferredSectionWrapperProps {
   deferred: DeferredSection;
   pagePath: string;
+  pageUrl?: string;
   loadingFallback?: ReactNode;
   errorFallback?: ReactNode;
   loadFn: (data: {
     component: string;
     rawProps: Record<string, unknown>;
     pagePath: string;
+    pageUrl?: string;
   }) => Promise<ResolvedSection | null>;
 }
 
 function DeferredSectionWrapper({
   deferred,
   pagePath,
+  pageUrl,
   loadingFallback,
   errorFallback,
   loadFn,
@@ -283,6 +286,7 @@ function DeferredSectionWrapper({
         component: deferred.component,
         rawProps: deferred.rawProps,
         pagePath,
+        pageUrl,
       })
         .then((result) => {
           if (result) deferredSectionCache.set(key0, { section: result, ts: Date.now() });
@@ -302,6 +306,7 @@ function DeferredSectionWrapper({
             component: deferred.component,
             rawProps: deferred.rawProps,
             pagePath,
+            pageUrl,
           })
             .then((result) => {
               if (result) deferredSectionCache.set(key1, { section: result, ts: Date.now() });
@@ -315,7 +320,7 @@ function DeferredSectionWrapper({
 
     observer.observe(el);
     return () => observer.disconnect();
-  }, [deferred.component, deferred.rawProps, pagePath, section, loadFn]);
+  }, [deferred.component, deferred.rawProps, pagePath, pageUrl, section, loadFn]);
 
   if (error) {
     const errFallback = loadedOptions?.errorFallback
@@ -403,12 +408,15 @@ interface Props {
   sections: ResolvedSection[];
   deferredSections?: DeferredSection[];
   pagePath?: string;
+  /** Original page URL (with query params) — forwarded to deferred section loaders. */
+  pageUrl?: string;
   loadingFallback?: ReactNode;
   errorFallback?: ReactNode;
   loadDeferredSectionFn?: (data: {
     component: string;
     rawProps: Record<string, unknown>;
     pagePath: string;
+    pageUrl?: string;
   }) => Promise<ResolvedSection | null>;
 }
 
@@ -416,6 +424,7 @@ export function DecoPageRenderer({
   sections,
   deferredSections,
   pagePath = "/",
+  pageUrl,
   loadingFallback,
   errorFallback,
   loadDeferredSectionFn,
@@ -436,6 +445,7 @@ export function DecoPageRenderer({
               key={`deferred-${pagePath}-${item.deferred.key}-${item.deferred.index}`}
               deferred={item.deferred}
               pagePath={pagePath}
+              pageUrl={pageUrl}
               loadingFallback={loadingFallback}
               errorFallback={errorFallback}
               loadFn={loadDeferredSectionFn}

package/src/routes/cmsRoute.ts

@@ -39,6 +39,7 @@ import {
   detectCacheProfile,
   routeCacheDefaults,
 } from "../sdk/cacheHeaders";
+import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 
 const isServer = typeof document === "undefined";
 
@@ -86,9 +87,10 @@ async function loadCmsPageInternal(fullPath: string) {
   const cacheProfile = detectCacheProfile(basePath);
   return {
     ...page,
-    resolvedSections: enrichedSections,
-    deferredSections: page.deferredSections,
+    resolvedSections: normalizeUrlsInObject(enrichedSections),
+    deferredSections: normalizeUrlsInObject(page.deferredSections),
     cacheProfile,
+    pageUrl: urlWithSearch,
   };
 }
 
@@ -128,8 +130,8 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
 
   return {
     ...page,
-    resolvedSections: enrichedSections,
-    deferredSections: page.deferredSections,
+    resolvedSections: normalizeUrlsInObject(enrichedSections),
+    deferredSections: normalizeUrlsInObject(page.deferredSections),
   };
 });
 
@@ -140,14 +142,15 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
 export const loadDeferredSection = createServerFn({ method: "POST" })
   .inputValidator(
     (data: unknown) =>
-      data as { component: string; rawProps: Record<string, any>; pagePath: string },
+      data as { component: string; rawProps: Record<string, any>; pagePath: string; pageUrl?: string },
   )
   .handler(async (ctx) => {
-    const { component, rawProps, pagePath } = ctx.data;
+    const { component, rawProps, pagePath, pageUrl } = ctx.data;
 
+    const serverUrl = getRequestUrl().toString();
     const matcherCtx: MatcherContext = {
       userAgent: getRequestHeader("user-agent") ?? "",
-      url: getRequestUrl().toString(),
+      url: pageUrl || serverUrl,
       path: pagePath,
       cookies: getCookies(),
     };
@@ -155,11 +158,11 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
     const section = await resolveDeferredSection(component, rawProps, pagePath, matcherCtx);
     if (!section) return null;
 
-    const request = new Request(getRequestUrl().toString(), {
+    const request = new Request(pageUrl || serverUrl, {
       headers: getRequest().headers,
     });
     const enriched = await runSingleSectionLoader(section, request);
-    return enriched;
+    return normalizeUrlsInObject(enriched);
   });
 
 // ---------------------------------------------------------------------------

package/src/sdk/index.ts

@@ -27,6 +27,11 @@ export {
 } from "./instrumentedFetch";
 export { batchInvoke, createInvokeProxy, type InvokeProxy, invokeQueryOptions } from "./invoke";
 export { createCacheControlCollector, mergeCacheControl } from "./mergeCacheControl";
+export {
+  getProductionOrigins,
+  normalizeUrlsInObject,
+  registerProductionOrigins,
+} from "./normalizeUrls";
 export {
   addRedirects,
   loadRedirects,

package/src/sdk/normalizeUrls.ts

@@ -0,0 +1,91 @@
+/**
+ * URL normalization for CMS-resolved props.
+ *
+ * Strips registered production origins from absolute URLs, converting them to
+ * relative paths. This allows staging/preview deployments to work without
+ * every CMS-authored link sending users to the production domain.
+ *
+ * Only affects strings that START with a registered origin + "/" — image CDN
+ * URLs, API endpoints on different domains, and non-URL strings are untouched.
+ *
+ * @example
+ * ```ts
+ * // In site's setup.ts:
+ * import { registerProductionOrigins } from "@decocms/start/sdk/normalizeUrls";
+ * registerProductionOrigins([
+ *   "https://www.casaevideo.com.br",
+ *   "https://casaevideo.com.br",
+ * ]);
+ * ```
+ */
+
+let origins: string[] = [];
+
+/**
+ * Register production origins that should be stripped from CMS-resolved URLs.
+ * Call once in your site's setup.ts before any page loads.
+ */
+export function registerProductionOrigins(productionOrigins: string[]) {
+  origins = productionOrigins.map((o) => o.replace(/\/+$/, ""));
+}
+
+export function getProductionOrigins(): readonly string[] {
+  return origins;
+}
+
+function normalizeString(str: string): string {
+  for (const origin of origins) {
+    if (str.startsWith(origin + "/")) {
+      return str.slice(origin.length);
+    }
+    if (str === origin) {
+      return "/";
+    }
+  }
+  return str;
+}
+
+/**
+ * Deep-walk an object tree and rewrite any string value that starts with a
+ * registered production origin to a relative path. Returns the same reference
+ * if nothing was changed (structural sharing).
+ */
+export function normalizeUrlsInObject<T>(obj: T): T {
+  if (!origins.length) return obj;
+  return deepNormalize(obj) as T;
+}
+
+function deepNormalize(val: unknown): unknown {
+  if (val == null) return val;
+
+  if (typeof val === "string") {
+    return normalizeString(val);
+  }
+
+  if (Array.isArray(val)) {
+    let changed = false;
+    const result = val.map((item) => {
+      const normalized = deepNormalize(item);
+      if (normalized !== item) changed = true;
+      return normalized;
+    });
+    return changed ? result : val;
+  }
+
+  if (typeof val === "object") {
+    // Skip React elements, Dates, RegExps, and other non-plain objects
+    const proto = Object.getPrototypeOf(val);
+    if (proto !== Object.prototype && proto !== null) return val;
+
+    let changed = false;
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(val as Record<string, unknown>)) {
+      const normalized = deepNormalize(value);
+      result[key] = normalized;
+      if (normalized !== value) changed = true;
+    }
+    return changed ? result : val;
+  }
+
+  return val;
+}